Authored by Claude Opus 4.7 (Claude Code). Session e748e6db-2785-414d-a13c-2ecbadbd221a.

FAIR-band: in-band [12/30] (canonical merged-count per gh search prs --merged --repo neomjs/neo --limit 30 --sort updated --json author 2026-05-19; pending PRs #11620 + #11621 + this PR not in count).

Resolves #11447.

Summary

Graduates Discussion #11444 with Visibility-Only V1 of the Brain-Pillar Consumer-Friction Feedback Channel. Local-model substrate consumers (e.g. Gemma 4-31b, Qwen3-8b) signal back when the substrate payload is the wrong shape — context overflow, parse failure, pre-invocation size-precheck skip, etc.

Frictions accumulate in an in-memory aggregator and surface in the next GoldenPathSynthesizer.synthesizeGoldenPath() handoff section. V1 is visibility-only: no AgentOrchestrator.parseGoldenPath() task-routing changes, no auto-mutation of caller behavior beyond the explicit pre-check skip. Symmetric to PR #11441 Review-Cost Circuit Breaker (swarm-side) but Brain-side.

Cycle history

• Cycle 0 (0a11bfb31): initial implementation with byte-only metrics + free-text suggestion. Drifted from Discussion #11444's consensus-bound graduation schema.
• Cycle 1 (84508e5ba): schema realigned to the full Round-2 + Round-3 consensus contract per @neo-gpt review PRR_kwDODSospM8AAAABAUqoyA. Added suggestionKind enum, token-based durable metrics, serviceDomain provenance, firstSeenAt/lastSeenAt/count aggregation fields, note optional context. Config renamed from contextWindowBytes → contextLimitTokens + new safeProcessingLimitTokens field. Safe-fraction corrected from 0.80 → 0.75 (Round-2 consensus).

Changes

1. ai/services/memory-core/helpers/ConsumerFrictionHelper.mjs (337 lines)

Pure functional helper following EmbeddingProviderConfig.mjs / HarnessClassifier.mjs sibling pattern.

Final V1 schema (per Discussion #11444 Round-2 + Round-3 consensus):

type ConsumerFriction = {
    // Identity tuple (aggregation key: assetRef|consumer|symptom)
    assetRef: string;
    consumer: string;            // service name (e.g. 'SemanticGraphExtractor')
    model: string;

    // Symptom + provenance
    symptom: 'context-overflow' | 'parse-failure' | 'token-budget-exceeded'
           | 'semantic-confusion' | 'timeout' | 'size-precheck-skip';
    emissionPoint: 'pre-invocation' | 'post-invocation-failure';
    serviceDomain: 'dream-pipeline' | 'memory-core' | 'concept-extraction' | 'other';

    // Enum-backed structured suggestion
    suggestionKind: 'split-document' | 'compress-payload' | 'extract-anchor'
                  | 'reduce-review-cycle' | 'schema-repair' | 'unknown';

    // Token-based durable metrics (bytes retained as evidence)
    inputBytes: number;
    inputTokensEstimate: number;          // Math.ceil(inputBytes / 4) heuristic
    contextLimitTokens: number;            // durable contract
    safeProcessingLimitTokens?: number;    // defaults to 75% of contextLimitTokens

    // Aggregation surface
    firstSeenAt: string;
    lastSeenAt: string;
    count: number;

    // Optional context
    note?: string;
};

API surface:

• invokeWithGuardrail({invocationFn, inputPayload, model, assetRef, consumer, contextLimitTokens, safeProcessingLimitTokens?, serviceDomain, suggestionKind?, note?}) — bidirectional defense wrapper. Angle 2 (upstream) pre-checks bytesToTokens(Buffer.byteLength(inputPayload)) against safeProcessingLimitTokens (defaults to 75% of contextLimitTokens); over-budget input emits size-precheck-skip and skips the invocation. Angle 1 (downstream) wraps the invocation in try/catch and categorizes failures into context-overflow / parse-failure / timeout. Returns uniform {result, friction} envelope.
• emitConsumerFriction(input) — module-singleton aggregator with enum-validated input. Deterministic symptoms (size-precheck-skip, context-overflow) surface on first occurrence; probabilistic symptoms aggregate by (assetRef, consumer, symptom) tuple and surface at PROBABILISTIC_EMIT_THRESHOLD (3) emissions.
• getAggregatedFrictions({now?}) — reader with 1-hour TTL pruning; injectable clock.
• renderConsumerFrictionSection({now?}) — pure formatter for the Markdown section.
• bytesToTokens(bytes) — exportable 4-chars/token heuristic.
• categorizeInvocationError(err) — exportable enum mapper.
• deriveSuggestionKind(symptom, assetRef?) — exportable default suggestionKind resolver.
• clearAggregatedFrictions() — test-only state reset.

Sibling pattern lifted from EmbeddingProviderConfig.mjs / HarnessClassifier.mjs (pure functional helpers with injectable deps).

2. Integration into 2 canonical emitters (AC3)

• ai/daemons/services/SemanticGraphExtractor.mjs — wraps provider.generate(messages) inside the 3-retry Tri-Vector extraction loop. Pre-check fires per attempt (repair-prompts grow byte size). Friction emitted with consumer: 'SemanticGraphExtractor', serviceDomain: 'dream-pipeline'.
• ai/services/memory-core/SessionService.mjs — wraps this.model.generateContent(summaryPrompt) in summarizeSession(). Friction emitted with consumer: 'SessionService.summarizeSession', serviceDomain: 'memory-core'. assetRef = sessionId.

3. Config substrate

ai/mcp/server/memory-core/config.template.mjs adds:

• aiConfig.openAiCompatible.contextLimitTokens (default 32768 — Gemma-4-31b / Qwen3-8B class ~32K-token context).
• aiConfig.openAiCompatible.safeProcessingLimitTokens (optional; defaults to 75% of contextLimitTokens when unset, per Discussion #11444 Round-2 consensus 25% headroom for envelope + repair + output reservation).

4. Handoff rendering integration (AC4)

ai/daemons/services/GoldenPathSynthesizer.mjs — synthesizeGoldenPath() invokes renderConsumerFrictionSection() after the capability-gap section cluster and before the Active PR Cycle State section. Section is omitted when nothing surfaces (empty-string short-circuit). Defensive try/catch.

Ticket scope mentioned synthesizeHandoff() but the actual method is synthesizeGoldenPath(). Section landed in existing method per substrate-truth.

5. Test coverage

test/playwright/unit/ai/services/memory-core/helpers/ConsumerFrictionHelper.spec.mjs — 18 tests:

• bytesToTokens 4-chars/token heuristic (incl. edge cases)
• categorizeInvocationError enum mapping
• deriveSuggestionKind symptom-to-suggestion enum mapping
• emitConsumerFriction enum validation throws (symptom / suggestionKind / serviceDomain / emissionPoint)
• Deterministic symptom emission on first occurrence (2 tests)
• Probabilistic aggregation at threshold
• Tuple aggregation by (assetRef, consumer, symptom)
• TTL pruning at injectable-clock future
• Angle 2 pre-check skip (2 tests: explicit + 75% default)
• Angle 1 success / parse-failure threshold / context-overflow immediate (3 tests)
• suggestionKind + note overrides
• renderConsumerFrictionSection empty / structured / multi-symptom output (3 tests)

Contract Ledger (per pr-review-guide §5.4)

Backfilled in PR body per @neo-gpt Cycle 0 review. The ConsumerFriction helper + the aiConfig.openAiCompatible.contextLimitTokens / safeProcessingLimitTokens config keys are public/consumed surfaces and require contract documentation.

MCP Config Template Change Guide compliance (per pull-request-workflow.md §4)

Per mcp-config-template-change-guide.md:

• Changed config keys: aiConfig.openAiCompatible.contextLimitTokens (new, default 32768) and aiConfig.openAiCompatible.safeProcessingLimitTokens (new, optional). No prior shipped keys removed; the Cycle-0 contextWindowBytes proposal was renamed before any operator could clone it.
• Local config.mjs follow-up: No shape/key migration required for existing clones. The new keys are additive with sensible defaults (32768 + 75% computed-safe). Operators running models with non-32K context windows should add contextLimitTokens: <model-token-window> to their local config.mjs to tune the pre-check threshold; otherwise the default suffices.
• Harness restart: Recommended for Memory Core / Sandman processes after local config refresh, so long-running daemons observe the new pre-check budget. Required only if operator changes the local override after first boot; new operators inherit the default at first launch without restart.
• Peer A2A notification: this PR's [pr-open] broadcast at MESSAGE:0ae7cd28-58c6-4836-ac15-c22ab5c12440 already satisfies the peer-notification clause for the substantive consumer-friction primitive landing.

Slot Rationale (per pull-request-workflow §1.1 substrate-mutation gate)

Modified substrate:

• 1 new helper module (ai/services/memory-core/helpers/ConsumerFrictionHelper.mjs)
• 1 new test spec
• 3 service integration touch-points (SemanticGraphExtractor, SessionService, GoldenPathSynthesizer)
• 1 config addition (renamed + new field on aiConfig.openAiCompatible)

Disposition deltas (per ADR 0007 taxonomy):

• ConsumerFrictionHelper.mjs — keep (visibility-only primitive; sunset trigger = V2 routing/Model-Stats integration)
• ConsumerFrictionHelper.spec.mjs — keep (canonical regression coverage)
• 3 service integrations — rewrite (wraps existing invocations; no removed logic)
• config.template.mjs — keep (additive keys with safe defaults)

3-axis rating:

• Trigger-frequency: every Brain-pillar LLM invocation across SemanticGraphExtractor + SessionService.summarizeSession — HIGH
• Failure-severity: pre-fix consumer-side payload-mismatch was silent/ephemeral; post-fix surfaces to operators/swarm via handoff — MEDIUM (visibility-only, downstream still needs to act)
• Enforceability: substrate-level guard at LLM invocation; aggregator state + handoff render are mechanical — HIGH

Decay mitigation: Visibility-only V1 contract is the floor; V2 ticket-class adds routing-side mutation (AgentOrchestrator friction-aware scheduling) or per-provider tokenization via Model-Stats registry. 1-hour TTL prevents indefinite memory growth. Pure-functional helper API + injectable clock enables future-V2 callers to mock state cleanly.

Architectural Impact

• Brain-pillar substrate: introduces the first symmetric peer to swarm-side Review-Cost Circuit Breaker (#11441).
• No production routing change: V1 visibility-only; AgentOrchestrator and downstream task-routing unchanged.
• MX-loop closure: Brain friction → handoff section → operator/swarm read → upstream emission adjustment is the V1 loop. V2 may close the loop with auto-mutation.

Edge Cases

• Pre-check fires per retry: when SemanticGraphExtractor's retry loop's repair-prompt grows the messages array, byte-size grows per iteration. Pre-check correctly fires fresh each attempt — over-budget input that started fitting may end up exceeding safeProcessingLimitTokens on attempt 3 with appended repair messages.
• Engine-error abort vs schema-fail retry: invokeWithGuardrail catches engine-level failures (network, context, timeout). Schema-validation failures (Json.extract returning null) are handled by the existing retry loop's repair-prompt logic, not by friction emission.
• Aggregator state across REM cycles: module-singleton state persists within the same daemon process. TTL pruning (1 hour) prevents indefinite growth. Daemon restart clears state — substrate-correct for visibility-only V1 (feedback-feed, not durable audit log).
• Token-estimation vs actual tokenization: V1 uses a 4-chars/token heuristic. Provider-specific tokenizers may yield slightly different counts. The inputBytes field is retained on each record as raw evidence for cross-validation. V2 may delegate to Model-Stats registry per ADR 0012.

Test Evidence

• npm run test-unit -- ConsumerFrictionHelper.spec.mjs → 18/18 PASS (598ms)
• npm run test-unit -- ConsumerFrictionHelper.spec.mjs GoldenPathSynthesizer.spec.mjs SemanticGraphExtractor.spec.mjs → 24/24 PASS (748ms)
• node ai/scripts/lint-agents.mjs --base origin/dev → OK
• node ai/scripts/check-substrate-size.mjs → PASS
• node buildScripts/util/check-whitespace.mjs → PASS
• git diff --check origin/dev...HEAD → PASS

Evidence: L2 (sandbox-ceiling — empirical Playwright unit specs covering all 7 API surfaces of the helper + regression coverage on integration surfaces). L3 (post-merge live REM cycle observing friction emission + handoff section render) is the operator verification surface; not gated here.

V1 explicitly excludes (ticket scope)

• MemorySessionIngestor, SummarizationCoordinatorService, ConceptIngestor — deterministic / scheduler-only / commentary-only mentions, not LLM invocation boundaries per Discussion #11444 Round-3 source-truth correction
• AgentOrchestrator.parseGoldenPath() task-routing mutations (V2 ticket)
• Auto-scoring of PRs based on Brain friction (Brain friction = evidence, not auto-mutation in V1)
• Per-provider tokenization (V2 — Model-Stats registry integration)
• Integration into non-LLM invocation boundaries

Cross-Family Review Mandate

Per pull-request-workflow.md §6.1. Cycle 1 re-review requested from @neo-gpt at head 84508e5ba — Gemini benched per operator-direction. V-B-A focus areas:

1. Schema match against Discussion #11444 Round-2+3 consensus: does the helper typedef + emitted records satisfy the consensus shape? suggestionKind enum / serviceDomain enum / token-based metrics / firstSeenAt/lastSeenAt/count aggregation / note optional?
2. Config rename: contextWindowBytes → contextLimitTokens + new safeProcessingLimitTokens. Right shape vs token-only?
3. Safe-fraction 0.75: Round-2 consensus value. Right vs Cycle 0's 0.80 default?
4. Service-name conventions: consumer: 'SemanticGraphExtractor' vs 'SessionService.summarizeSession'. Consistent enough for handoff readability?
5. Method-name discrepancy resolution: synthesizeGoldenPath() vs ticket's synthesizeHandoff(). Right call?

Requested action: use /pr-review on this PR.

Post-Merge Validation

• Run npm run ai:run-sandman against the local Memory Core + observe whether ### 🧠 Substrate-Consumer Friction section appears in generated sandman_handoff.md when payload-mismatch is triggered
• Verify pre-existing friction-free REM cycles don't emit empty section (empty-string short-circuit preserves prior handoff shape)
• Validate token-estimation heuristic against actual provider-specific tokenizer output on at least 1 sample payload (operator-feedback to calibrate the 4-chars/token ratio if needed)

Deltas from ticket

• ✅ V1 schema NOW delivered (Cycle 1 realignment): enum-backed suggestionKind, token-based durable metrics, serviceDomain provenance, firstSeenAt/lastSeenAt/count aggregation fields, note optional context. Cycle 0 had drifted to byte-only + free-text; Cycle 1 corrects to consensus contract.
• ✅ All 5 ACs delivered (schema / helper / 2-emitter integration / GoldenPath section / V1-exclusion-list honored)
• ✅ Discussion #11444 4× [RESOLVED_TO_AC] markers all satisfied (Route Contract, Schema, Emission Helpers, Target Emitters)
• ⚠ Method-name discrepancy: ticket says GoldenPathSynthesizer.synthesizeHandoff() but actual method is synthesizeGoldenPath(). Landed in existing method per substrate-truth.

Related

• Source ticket: Resolves #11447
• Graduation source: Discussion #11444 (consensus comments DC_kwDODSospM4BAnHU Round-2 + DC_kwDODSospM4BAnHc Round-3)
• Symmetric peer: #11441 Review-Cost Circuit Breaker (swarm-side)
• V2 tokenization anchor: ADR 0012 Model-Stats Framework (#11601 merged)
• Operator-direction: "both of you could have picked up more lanes" 2026-05-19 ~06:42Z + subsequent "nice progress" affirmation