opencode-swarm 7.105.0 → 7.107.0

package/dist/memory/config.d.ts

@@ -58,6 +58,8 @@ export interface MemoryConfig {
         };
         latencyBudgetMs: number;
     };
+    /** Q-learning-style utility tracking for memory recall/promotion/suppression. */
+    qLearning: QLearningConfig;
 }
 export interface ImportanceConfig {
     wRecency: number;
@@ -70,6 +72,45 @@ export interface ImportanceConfig {
     /** A memory is low-utility when importance < threshold. */
     threshold: number;
 }
+export interface QLearningConfig {
+    /** EMA learning rate η for q ← (1-η)·q + η·reward. */
+    learningRate: number;
+    /** Weight of the q-value term added to recall scoring. */
+    qValueBoostWeight: number;
+    /** Memories with qValue below this are suppressed from default recall. */
+    suppressionThreshold: number;
+    /** Memories with qValue above this (and enough retrievals) are promotion candidates. */
+    promotionThreshold: number;
+    /** Minimum retrieval count before a high-q memory is a promotion candidate. */
+    promotionMinRetrievals: number;
+    /** Fraction of a reward propagated to closely-related memories. */
+    propagationFraction: number;
+    /** Max related memories a single reward may propagate to. */
+    propagationFanoutCap: number;
+    /** Only propagate to memories retrieved within this window (days). */
+    propagationWindowDays: number;
+    /**
+     * Jaccard token-overlap bar for treating two same-scope+kind memories as
+     * "related" for reward propagation (B.5). Deliberately HIGH — propagation
+     * mutates OTHER memories' learned utility, so wrong bounds = blast radius;
+     * it must reach only near-duplicate memories. Strictly higher than
+     * consolidation's clustering bar (`DEFAULT_CONSOLIDATION_CONFIG.jaccardThreshold`
+     * = 0.30, a more aggressive MERGE operation): incidental template-word
+     * overlap between distinct sibling-task memories (e.g. "Recalled by task
+     * A." vs "...task B." ≈ 0.6 Jaccard) must NOT count as related, so
+     * propagation never cross-pollinates distinct tasks' memories — which
+     * coheres with the B.2 unitId attribution the reward path already
+     * enforces. Documented judgment call (task B.5 report): deviates upward
+     * from the spec's "e.g. 0.5" example toward blast-radius safety.
+     */
+    propagationRelatednessThreshold: number;
+    /** Bounded rate at which suppressed memories are surfaced for exploration. */
+    explorationRate: number;
+    /** Max bytes of the retained council-synthesis payload (truncated with a marker beyond this). */
+    verdictPayloadCapBytes: number;
+    /** Neutral starting utility for a new memory. */
+    initialQValue: number;
+}
 export interface ConsolidationConfig {
     /** Run episodic→semantic consolidation at phase_complete. Gated by `enabled` too. */
     enabled: boolean;
@@ -105,6 +146,13 @@ export interface MemoryLearningConfig {
 }
 export declare const DEFAULT_DECAY_HALF_LIFE_DAYS: Record<MemoryKind, number>;
 export declare const DEFAULT_IMPORTANCE_CONFIG: ImportanceConfig;
+export declare const DEFAULT_QLEARNING_CONFIG: QLearningConfig;
+/** Council verdict → EMA reward on the [0,1] utility scale (coherence fix; see spec FR-001). */
+export declare const COUNCIL_VERDICT_REWARDS: {
+    readonly APPROVE: 1;
+    readonly CONCERNS: 0.5;
+    readonly REJECT: 0;
+};
 export declare const DEFAULT_CONSOLIDATION_CONFIG: ConsolidationConfig;
 export declare const DEFAULT_MEMORY_LEARNING_CONFIG: MemoryLearningConfig;
 export declare const DEFAULT_EMBEDDINGS_CONFIG: {

package/dist/memory/finalize-reward-sweep.d.ts

@@ -0,0 +1,132 @@
+/**
+ * B.6 — Deterministic negative-terminal reward sweep at session finalize.
+ *
+ * This is the RELIABLE negative learning signal (resolved design decision C-6),
+ * the deterministic counterpart to A.4's positive terminal reward
+ * (APPROVE→complete→1.0). At `/swarm close`, every task left non-complete is
+ * stamped `close_reason='session_terminated'` (see `guaranteeAllPlansComplete`
+ * in `src/commands/close.ts`). The memories recalled into those non-completed
+ * tasks earn a NEGATIVE terminal reward (0.0) so their learned utility (q-value)
+ * drifts DOWN via the shared EMA mechanism and, once it crosses
+ * `qLearning.suppressionThreshold`, they are suppressed from future default
+ * recall (FR-001 negative terminal; FR-006 makes suppression functional;
+ * SC-007 end-to-end).
+ *
+ * ── Attribution / why we DISCOVER the runId rather than assume the finalize
+ *    session ──────────────────────────────────────────────────────────────
+ * `applyCouncilReward` lists recall bundles by `runId` at the provider level
+ * (`listRecallUsage({ runId })`) BEFORE narrowing them by `unitId` in memory.
+ * Recall usage is recorded with `runId = context.runId ?? context.sessionID` —
+ * i.e. the WORK session that performed the recall. Finalize, however, may run
+ * in a DIFFERENT session (plans persist across sessions via the ledger, and
+ * `/swarm close` can run in a separate process — the reason close has a
+ * cross-process `readEarliestSessionStart` fallback). So passing the finalize
+ * session id as `runId` would make the provider-level filter miss the task's
+ * bundles entirely and the sweep would be a silent no-op — unacceptable for a
+ * "reliable" signal. Passing an empty `runId` (which disables the provider
+ * filter) is also wrong: it would let UNTAGGED bundles from unrelated sessions
+ * be penalized once per swept task (blast-radius / disjointness violation).
+ *
+ * Therefore, for each closed task we FIRST discover the real run id(s) that
+ * recalled memories into it via `listRecallUsage({ unitId: taskId })` (the B.1
+ * bundle-identity join key), then invoke `applyCouncilReward` once per
+ * (task, runId) with `reward = 0.0` and `unitId = taskId`. Within each runId,
+ * `applyCouncilReward`'s unitId narrowing keeps this task's tagged bundles plus
+ * that run's untagged bundles (the documented B.2 run_id fallback) — exactly
+ * symmetric to how A.4 rewards those same bundles on completion.
+ *
+ * ── Correctness invariants ────────────────────────────────────────────────
+ * - Disjointness: only `closedTaskIds` (non-complete tasks) are swept, so a
+ *   memory recalled into a COMPLETED task is never penalized. When a completed
+ *   task and a closed task share one work session, the per-runId
+ *   `applyCouncilReward` call still lists the whole session's bundles but its
+ *   `unitId` narrowing excludes the completed task's tagged bundle (its
+ *   `unitId` differs), so the completed task's memory is untouched. A memory
+ *   recalled into BOTH a completed and a non-completed task legitimately gets
+ *   +1.0 (A.4) and 0.0 (this sweep) for the two DIFFERENT tasks — not a
+ *   double-penalty.
+ * - Cross-finalize idempotency: the sweep holds NO persistent per-task
+ *   "rewarded" flag (unlike A.4's `session.taskCouncilApproved.rewarded`). It
+ *   does not need one — a task closed on a prior finalize already has status
+ *   `'closed'`, so `guaranteeAllPlansComplete` does not re-close it and it is
+ *   NOT present in `closedTaskIds` on a subsequent finalize. (Finalize also
+ *   removes `plan.json`/`plan-ledger.jsonl`, so a re-run short-circuits with an
+ *   empty task set.) Within a single sweep we additionally dedupe `taskId`.
+ *   Two intentional multiplicity sources are accepted, both a consequence of
+ *   reusing the mandated shared reward path rather than a bug:
+ *     1. A memory recalled into the SAME closed task across MULTIPLE work
+ *        sessions receives one 0.0 EMA step PER runId (`applyCouncilReward`
+ *        dedupes within a runId, not across our per-runId calls). The
+ *        dominant one-runId-per-task case is exactly A.4-symmetric; the
+ *        multi-session case is marginally more aggressive.
+ *     2. An UNTAGGED (`unit_id == null`) bundle in a runId SHARED by N closed
+ *        tasks is penalized once PER closed task that shares that runId: each
+ *        per-task `applyCouncilReward` call re-keeps the same untagged bundle
+ *        via the documented B.2 run_id fallback (an untagged bundle is kept
+ *        regardless of which task's unitId is being narrowed for), so a
+ *        memory recalled only in that untagged bundle earns N separate 0.0
+ *        steps for N closed tasks in the same session, not one.
+ * - Persistence ordering: the caller invokes this sweep BEFORE the destructive
+ *   git alignment stage, and the memory store lives at `.swarm/memory/` (not in
+ *   finalize's clean allowlists and not touched by align's `dist`-scoped
+ *   clean), so the reward writes survive finalize.
+ * - Non-blocking: the ENTIRE sweep is wrapped in try/catch that logs and
+ *   continues. A sweep failure NEVER throws into finalize and never alters
+ *   finalize's task/archival/align behavior — it only records rewards.
+ *
+ * NOTE: `applyCouncilReward`'s `verdictLabel` option lets this sweep label its
+ * reward events with the true reason instead of the misleading default
+ * `'APPROVE'`. Sweep events are persisted as
+ * `{ verdict: 'session_terminated', reward: 0.0 }` (see the `applyCouncilReward`
+ * call below).
+ */
+import type { MemoryConfig } from '../config/schema';
+import { createConfiguredMemoryProvider } from './gateway';
+import { applyCouncilReward } from './reward-capture';
+/**
+ * Negative terminal reward for memories recalled into non-completed
+ * (`session_terminated`) tasks. On the [0,1] utility scale, 0.0 is the minimum:
+ * the EMA step `q ← (1-η)·q + η·0` strictly decreases any positive q toward 0.
+ */
+export declare const FINALIZE_NEGATIVE_TERMINAL_REWARD = 0;
+export interface FinalizeRewardSweepArgs {
+    /** Project root; the memory store lives under `<directory>/.swarm/memory/`. */
+    directory: string;
+    /**
+     * Task ids stamped `close_reason='session_terminated'` this finalize
+     * (`ctx.guaranteeResult.closedTaskIds`). Deduped defensively inside.
+     */
+    closedTaskIds: readonly string[];
+    /**
+     * Resolved `config.memory` (already parsed via `PluginConfigSchema`). When
+     * absent or `enabled !== true` the sweep is a complete no-op.
+     */
+    memoryConfig: MemoryConfig | undefined;
+    /** ISO 8601 timestamp for the reward events; defaults to now. */
+    timestamp?: string;
+}
+export interface FinalizeRewardSweepResult {
+    /** True once the sweep loop actually ran (memory enabled + tasks present). */
+    swept: boolean;
+    /** Count of closed tasks that had at least one memory rewarded. */
+    tasksSwept: number;
+    /** Total EMA steps applied (summed across tasks and their run ids). */
+    memoriesRewarded: number;
+    /** Count of (task, runId) `applyCouncilReward` invocations performed. */
+    runIdsProcessed: number;
+}
+/**
+ * Apply the deterministic negative terminal reward (0.0) to memories recalled
+ * into the given non-completed tasks. See the module header for the full
+ * attribution model and correctness invariants. Never throws.
+ */
+export declare function runFinalizeRewardSweep(args: FinalizeRewardSweepArgs): Promise<FinalizeRewardSweepResult>;
+/**
+ * DI seam (AGENTS.md invariant 7 — DI over `mock.module`). Tests override these
+ * to inject a throwing provider (non-blocking assertion) or to count/observe
+ * calls. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    createConfiguredMemoryProvider: typeof createConfiguredMemoryProvider;
+    applyCouncilReward: typeof applyCouncilReward;
+};

package/dist/memory/gateway.d.ts

@@ -24,7 +24,6 @@ export interface RecallMemoryInput {
     maxItems?: number;
     tokenBudget?: number;
     minScore?: number;
-    includeLowQ?: boolean;
     requireQuerySignal?: boolean;
     includeExpired?: boolean;
 }

package/dist/memory/index.d.ts

@@ -9,10 +9,9 @@ export { backupLegacyJsonl, getLegacyJsonlFileStatus, type JsonlBackupResult, ty
 export { LocalJsonlMemoryProvider } from './local-jsonl-provider';
 export { buildMemoryMaintenanceReport, type MemoryMaintenanceReport, type MemoryMaintenanceReportOptions, type MemoryRecallUsageByMemory, type MemoryRecallUsageByRole, type MemorySupersededChain, shouldCompactMemory, } from './maintenance';
 export { buildRecallPromptBlock } from './prompt-block';
-export type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallRewardInput, MemoryRecallRewardResult, MemoryRecallUsageEvent, MemoryRecallUsageFilter, MemoryTaskOutcome, MemoryValueLogEntry, MemoryValueLogFilter, } from './provider';
+export type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter, } from './provider';
 export { buildMemoryRecallPlan, type MemoryRecallPlan, type MemoryRecallPlannerInput, } from './recall-planner';
 export { findSecrets, redactSecrets } from './redaction';
-export { applyRecallRewardForCouncil, councilVerdictToMemoryOutcome, resolveRewardRunIds, } from './reward';
 export { MEMORY_RECALL_PROFILES, type MemoryRecallProfile, normalizeMemoryAgentRole, resolveMemoryRecallProfile, } from './role-profiles';
 export { appendMemoryRunLog, sanitizeRunId } from './run-log';
 export { computeMemoryContentHash, createBundleId, createMemoryId, createProposalId, isExpired, normalizeMemoryText, validateCuratorMemoryDecision, validateMemoryProposal, validateMemoryRecordRules, } from './schema';

package/dist/memory/injector.d.ts

@@ -6,12 +6,23 @@ export interface MemoryLifecycleHookOptions {
     directory: string;
     config?: Partial<MemoryConfig>;
     getActiveAgentName?: (sessionID: string | undefined) => string | undefined;
+    /**
+     * Resolve the task/phase unit-of-work id (e.g. plan task "1.1") for the
+     * session being processed. ADDITIVE join key threaded onto recorded recall
+     * bundles (B.1). Injectable seam (mirrors getActiveAgentName) so the injector
+     * stays swarmState-free; the production default reads the SAME session's
+     * `currentTaskId` in index.ts. MUST resolve only from the recall's OWN session
+     * — never a parent/orchestrator — because a wrong id corrupts B.2 attribution
+     * (a false join is worse than NULL). Returns undefined when unresolvable.
+     */
+    getActiveTaskId?: (sessionID: string | undefined) => string | undefined;
     createGateway?: (context: {
         directory: string;
         sessionID?: string;
         agentRole?: string;
         agentId?: string;
         runId?: string;
+        unitId?: string;
     }, options: {
         config?: Partial<MemoryConfig>;
     }) => Pick<MemoryGateway, 'isEnabled' | 'deriveAllowedScopes' | 'recall' | 'propose'> & Partial<Pick<MemoryGateway, 'applyCuratorDecision' | 'dispose'>>;

package/dist/memory/local-jsonl-provider.d.ts

@@ -1,5 +1,5 @@
 import { type MemoryConfig } from './config';
-import type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter } from './provider';
+import type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter, MemoryRewardEvent, MemoryRewardEventFilter } from './provider';
 import type { RecallScoringDiagnostics } from './scoring';
 import type { AppliedMemoryChange, MemoryListFilter, MemoryProposal, MemoryRecord, RecallRequest, RecallResultItem, ResolvedCuratorMemoryDecision } from './types';
 export declare class LocalJsonlMemoryProvider implements MemoryProvider, MemoryProposalStore {
@@ -22,6 +22,8 @@ export declare class LocalJsonlMemoryProvider implements MemoryProvider, MemoryP
     }>;
     recordRecallUsage(event: MemoryRecallUsageEvent): Promise<void>;
     listRecallUsage(filter?: MemoryRecallUsageFilter): Promise<MemoryRecallUsageEvent[]>;
+    appendRewardEvent(event: Omit<MemoryRewardEvent, 'id'>): Promise<void>;
+    listRewardEvents(filter?: MemoryRewardEventFilter): Promise<MemoryRewardEvent[]>;
     list(filter?: MemoryListFilter): Promise<MemoryRecord[]>;
     createProposal(proposal: MemoryProposal): Promise<MemoryProposal>;
     listProposals(filter?: {

package/dist/memory/maintenance.d.ts

@@ -1,4 +1,5 @@
-import type { MemoryProposalStore, MemoryProvider, MemoryValueLogEntry } from './provider';
+import { type QLearningConfig } from './config';
+import type { MemoryProposalStore, MemoryProvider } from './provider';
 import { type ImportanceWeights } from './scoring';
 import type { MemoryProposal, MemoryRecord } from './types';
 /**
@@ -40,8 +41,18 @@ export interface MemoryMaintenanceReport {
     supersededMemories: MemoryRecord[];
     supersededChains: MemorySupersededChain[];
     lowUtilityMemories: MemoryRecord[];
-    lowQValueMemories: MemoryValueLogEntry[];
-    promotionCandidates: MemoryValueLogEntry[];
+    /**
+     * Memories suppressed for low LEARNED utility (q-value < suppression
+     * threshold). Distinct from `lowUtilityMemories`, which is the orthogonal
+     * importance-based (recency/frequency/confidence) axis — see FR-006/A-1.
+     */
+    lowQValueMemories: MemoryRecord[];
+    /**
+     * Memories whose learned utility is above the promotion threshold AND that
+     * have been recalled more than the configured minimum — surfaced as
+     * candidates for promotion (not auto-promoted). FR-007.
+     */
+    promotionCandidates: MemoryRecord[];
     neverRecalledMemories: MemoryRecord[];
     mostRecalledMemories: MemoryRecallUsageByMemory[];
     recallByAgentRole: MemoryRecallUsageByRole[];
@@ -58,10 +69,11 @@ export interface MemoryMaintenanceReportOptions {
     importanceWeights?: ImportanceWeights;
     /** A memory is low-utility when importance < threshold. Defaults to DEFAULT_IMPORTANCE_THRESHOLD. */
     importanceThreshold?: number;
+    /** Learned-utility (q-value) thresholds for the low-Q / promotion surfaces. Defaults to DEFAULT_QLEARNING_CONFIG. */
+    qLearning?: QLearningConfig;
 }
 type ObservableProvider = MemoryProvider & Partial<MemoryProposalStore> & {
     listRecallUsage?: MemoryProvider['listRecallUsage'];
-    listMemoryValueLog?: MemoryProvider['listMemoryValueLog'];
 };
 export declare function buildMemoryMaintenanceReport(provider: ObservableProvider, options?: MemoryMaintenanceReportOptions): Promise<MemoryMaintenanceReport>;
 export declare function shouldCompactMemory(memory: MemoryRecord, now?: Date): 'deleted' | 'superseded' | 'expired_scratch' | null;

package/dist/memory/provider.d.ts

@@ -14,61 +14,43 @@ export interface MemoryRecallUsageEvent {
     tokenEstimate: number;
     agentRole?: string;
     runId?: string;
-    qValue?: number;
-    lastReward?: number;
-    taskOutcome?: MemoryTaskOutcome;
+    /**
+     * Task/phase unit-of-work identity (ADDITIVE — recorded alongside `runId`).
+     * Undefined when unresolvable at recording time (graceful degrade to
+     * session-scoped `runId`).
+     */
+    unitId?: string;
     timestamp: string;
 }
 export interface MemoryRecallUsageFilter {
     limit?: number;
-}
-export type MemoryTaskOutcome = 'approved' | 'rejected' | 'concerns' | 'unknown';
-export interface MemoryRecallRewardInput {
+    runId?: string;
     /**
-     * Candidate session/run identifiers whose recall-usage bundle(s) should
-     * receive this reward. Every id is matched independently (exact match
-     * only, no unscoped time-window fallback); all matched bundles are
-     * rewarded together. Callers should include every session id known to
-     * have actually recalled memory for this task (e.g. dispatched council
-     * member sessions), not just the submitting session, so sub-agent
-     * recalls are not silently skipped.
+     * Restrict to rows whose `unit_id` matches. Combined with `runId` the two
+     * predicates AND. Attribution prefers this filter and falls back to `runId`.
      */
-    runIds: string[];
-    outcome: MemoryTaskOutcome;
-    verdictPayload: unknown;
-    timestamp?: string;
-}
-export interface MemoryRecallRewardResult {
-    success: boolean;
-    /** First matched bundle id, for back-compat display. See `bundleIds` for the full set. */
-    bundleId?: string;
-    /** Every recall-usage bundle (across all matched runIds) that received this reward. */
-    bundleIds?: string[];
-    outcome: MemoryTaskOutcome;
-    memoryIds: string[];
-    updatedMemoryIds: string[];
-    propagatedMemoryIds: string[];
-    reward: number;
-    qValue?: number;
-    reason?: string;
+    unitId?: string;
+    /**
+     * Restrict recall events to those with `timestamp >= since` (ISO 8601).
+     * Used by buildRetrievalRecency to bound iteration over recent events only.
+     */
+    since?: string;
 }
-export interface MemoryValueLogEntry {
+export interface MemoryRewardEvent {
+    id: string;
     memoryId: string;
-    kind: MemoryRecord['kind'];
-    scopeKey: string;
-    textPreview: string;
-    qValue: number;
-    lastReward?: number;
-    taskOutcome?: MemoryTaskOutcome;
-    recallCount: number;
-    lastRecalledAt?: string;
-    promotionCandidate: boolean;
-    suppressionCandidate: boolean;
+    runId?: string;
+    unitId?: string;
+    verdict: string;
+    reward: number;
+    qBefore?: number;
+    qAfter?: number;
+    verdictSynthesisJson?: string;
+    timestamp: string;
 }
-export interface MemoryValueLogFilter {
+export interface MemoryRewardEventFilter {
+    memoryId?: string;
     limit?: number;
-    includePromotionCandidatesOnly?: boolean;
-    includeSuppressionCandidatesOnly?: boolean;
 }
 export interface MemoryCompactOptions {
     dryRun?: boolean;
@@ -81,6 +63,11 @@ export interface MemoryCompactResult {
     removedExpiredScratch: number;
     remaining: number;
 }
+/**
+ * Lightweight transaction marker. Concrete transaction semantics are
+ * backend-specific (SQLite serialised, local-jsonl no-op).
+ */
+export type MemoryTransaction = object;
 export interface MemoryProvider {
     readonly name: string;
     initialize?(): Promise<void>;
@@ -92,10 +79,18 @@ export interface MemoryProvider {
     recallWithDiagnostics?(request: RecallRequest): Promise<MemoryRecallResult>;
     recordRecallUsage?(event: MemoryRecallUsageEvent): Promise<void>;
     listRecallUsage?(filter?: MemoryRecallUsageFilter): Promise<MemoryRecallUsageEvent[]>;
-    applyRecallReward?(input: MemoryRecallRewardInput): Promise<MemoryRecallRewardResult>;
-    listMemoryValueLog?(filter?: MemoryValueLogFilter): Promise<MemoryValueLogEntry[]>;
+    appendRewardEvent?(event: Omit<MemoryRewardEvent, 'id'>): Promise<void>;
+    listRewardEvents?(filter?: MemoryRewardEventFilter): Promise<MemoryRewardEvent[]>;
     compactMaintenance?(options?: MemoryCompactOptions): Promise<MemoryCompactResult>;
     list(filter: MemoryListFilter): Promise<MemoryRecord[]>;
+    /**
+     * Run `fn` atomically within a transaction. When the provider does not
+     * support transactions (e.g. local-jsonl), this is a no-op that calls
+     * `fn` directly. The applyCouncilReward loop uses this to avoid a
+     * read-then-update race between concurrent council verdicts on the same
+     * memory id.
+     */
+    withTransaction?<T>(fn: (tx: MemoryTransaction) => Promise<T> | T): Promise<T>;
 }
 export interface MemoryProposalStore {
     createProposal(proposal: MemoryProposal): Promise<MemoryProposal>;

package/dist/memory/q-learning.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure q-learning-style utility math for memory reward propagation.
+ *
+ * No I/O, no provider imports — safe to import from any layer (hooks, scoring,
+ * tools) without pulling in sqlite/jsonl or council-verdict types. Callers
+ * (A.4 reward capture, A.5 scoring) own the wiring; this module only owns
+ * the math.
+ *
+ * `getQValue`/`setQValue` operate on any `MemoryRecord`-shaped object (a
+ * structural `{ metadata?: Record<string, unknown> }`), so no runtime or
+ * type import of `MemoryRecord` is required here.
+ */
+/**
+ * EMA update: q ← (1-η)·q + η·reward.
+ *
+ * A convex combination of two [0,1] inputs stays in [0,1]; the clamp guards
+ * against float drift and out-of-range callers (e.g. reward slightly outside
+ * [0,1]) rather than relying on that invariant alone.
+ *
+ * Non-finite guards (a malformed reward, learning rate, or prior must not
+ * corrupt the stored q-value): a non-finite `reward` or `eta` falls back to
+ * the clamped `qOld`; a non-finite `qOld` (for which `clamp01` would itself
+ * yield NaN) falls back to `0`. This branch is unreachable under the intended
+ * `getQValue`-first contract (which always yields a finite value in [0,1]).
+ */
+export declare function applyEmaUpdate(qOld: number, reward: number, eta: number): number;
+/**
+ * B.5 — Propagation EMA step (soft Q-propagation). Applies a fractionally
+ * REDUCED reward step to a RELATED memory, reusing the SAME EMA mechanism as a
+ * direct reward but scaling the effective learning rate by `fraction`:
+ *
+ *   applyPropagatedEmaUpdate(q, r, η, f) = applyEmaUpdate(q, r, η·f)
+ *                                        = q + η·f·(r − q)
+ *
+ * so a related memory shifts by EXACTLY `fraction` times the shift a direct
+ * reward would produce from the same `qOld` (whose shift is η·(r − q)). This is
+ * the precise, testable meaning of "the related memory shifts by the fraction"
+ * (SC-005). It is algebraically identical to the alternative framing — pulling
+ * the reward `fraction` of the way from `qOld` toward `r` and then applying η —
+ * because η·(qOld + f·(r − qOld) − qOld) = η·f·(r − qOld).
+ *
+ * `fraction` is clamped to (0, 1]: a non-finite or ≤0 fraction yields NO shift
+ * (returns the clamped `qOld`) — propagation degrades to a no-op rather than
+ * corrupting the stored value; a fraction >1 is capped at 1 so a propagated
+ * step can never exceed the direct step it derives from (blast-radius guard).
+ */
+export declare function applyPropagatedEmaUpdate(qOld: number, reward: number, eta: number, fraction: number): number;
+/**
+ * Read a memory record's stored q-value from `metadata.qValue`, falling back
+ * to `fallback` when absent, non-numeric, non-finite, or out of [0,1].
+ */
+export declare function getQValue(record: {
+    metadata?: Record<string, unknown>;
+}, fallback?: number): number;
+/**
+ * Return a NEW record-shaped object with `metadata.qValue` set to the
+ * clamped value, preserving all other metadata (immutable — does not
+ * mutate `record`).
+ */
+export declare function setQValue<T extends {
+    metadata?: Record<string, unknown>;
+}>(record: T, value: number): T;

package/dist/memory/reward-capture.d.ts

@@ -0,0 +1,119 @@
+/**
+ * A.4/B.2 — Council reward capture (positive terminal reward only).
+ *
+ * Closes the memory learning loop: when an APPROVE council verdict advances a
+ * task to `complete`, every DISTINCT memory recalled and attributable to that
+ * task earns a single EMA reward step toward the terminal reward (1.0 for
+ * APPROVE).
+ *
+ * Design constraints (resolved decision C-6, Phase A; unitId narrowing B.2):
+ *   - POSITIVE reward only. No negative/REJECT/CONCERNS/max-rounds trigger here;
+ *     that is the finalize-time sweep (B.6).
+ *   - unitId-narrowed with run_id fallback: bundles are listed by `runId`
+ *     (session), then narrowed to the verdict's `opts.unitId` so sibling
+ *     tasks' recalls in the same session are NOT rewarded for this verdict.
+ *     A bundle is kept when it is untagged (`bundle.unitId == null`, the
+ *     legacy/unattributable case), when the verdict itself has no `unitId`
+ *     (cannot narrow — degrades to full session-scoped reward, today's
+ *     behavior), or when `bundle.unitId === opts.unitId` (precise match). A
+ *     bundle is excluded only when both ids are present and differ (a
+ *     different task's tagged bundle). `unitId` is also recorded on each
+ *     reward event for audit/attribution.
+ *   - DISTINCT dedup: a memory recalled in several KEPT bundles this session
+ *     gets exactly ONE EMA step.
+ *
+ * This module owns NO error isolation beyond the optional-method (`?.`) guards
+ * on capabilities the provider may not implement. The calling HOOK owns
+ * try/catch isolation so a reward-capture failure can never affect task
+ * completion. (Exception: the B.5 soft-propagation pass below is wrapped in its
+ * OWN best-effort try/catch so that a propagation failure can never discard the
+ * direct reward that already succeeded — the direct EMA steps are persisted and
+ * counted BEFORE propagation runs at all, so they are unaffected by any
+ * propagation-time error. Propagation itself is NOT guaranteed all-or-nothing:
+ * if a mid-loop `upsert` throws (e.g. after some propagated targets already
+ * received their step), the targets updated before the throw keep their
+ * propagated step and the remaining scheduled targets are simply never
+ * reached — partial propagation is an accepted outcome, per FR-004's "better
+ * to under-propagate than over-propagate".)
+ *
+ * B.5 — soft Q-propagation (FR-004 / SC-005). After each DIRECT reward, a
+ * FRACTION of that reward is propagated ONE HOP to closely-related memories so
+ * learning generalizes to similar memories, strictly bounded to avoid runaway
+ * updates. Relatedness = same scope + same kind + high Jaccard token overlap;
+ * only memories retrieved within `propagationWindowDays` (from recall-usage
+ * timestamps) are eligible; at most `propagationFanoutCap` per source (top-by-
+ * overlap, deterministic); each related memory gets at most ONE propagated
+ * step regardless of how many sources reach it; directly-rewarded ids and the
+ * source itself are excluded; propagated updates never re-enter propagation.
+ * See the constant/helper docs below for the exact formula and thresholds.
+ */
+import type { QLearningConfig } from './config';
+import type { MemoryProvider } from './provider';
+export interface CouncilRewardOptions {
+    /** Session id — bundles are listed by this `runId`. */
+    runId: string;
+    /**
+     * taskId — narrows bundle attribution (see module header for the exact
+     * predicate) and is recorded on reward events for audit/attribution.
+     */
+    unitId?: string;
+    /** Terminal reward on the [0,1] utility scale (1.0 for APPROVE). */
+    reward: number;
+    /** EMA learning rate η (config.memory.qLearning.learningRate). */
+    eta: number;
+    /** Neutral fallback q-value for records without a stored qValue. */
+    initialQValue: number;
+    /**
+     * Full q-learning config. B.5 reads the propagation parameters
+     * (`propagationFraction`, `propagationFanoutCap`, `propagationWindowDays`)
+     * from here. Optional for back-compat with A.4 call sites; defaults to
+     * `DEFAULT_QLEARNING_CONFIG` when omitted. `eta`/`initialQValue` above are
+     * kept as explicit fields (the direct-reward contract predates this) and are
+     * NOT overridden by this config.
+     */
+    qLearning?: QLearningConfig;
+    /** Already-truncated council-synthesis payload (FR-010). */
+    verdictSynthesisJson?: string;
+    /** ISO 8601 timestamp, caller-supplied. */
+    timestamp: string;
+    /**
+     * True label persisted on the DIRECT reward event's `verdict` field (and,
+     * with the `_PROPAGATED` suffix, on any B.5 propagated event it produces).
+     * Defaults to `'APPROVE'` when omitted — byte-identical to this module's
+     * pre-existing behavior, so A.4 (delegation-gate.ts, which never passes this)
+     * is unaffected. Callers with a graded or negative-terminal reward (B.3's
+     * phase verdict, B.6's finalize sweep) should pass the reason so the
+     * value-log audit is not mislabeled `'APPROVE'` for a REJECT/CONCERNS/
+     * session-terminated reward.
+     */
+    verdictLabel?: string;
+}
+export interface CouncilRewardResult {
+    /** Count of distinct memories that received an EMA step. */
+    memoriesRewarded: number;
+}
+/**
+ * Apply the positive council reward to every distinct memory recalled during
+ * the session identified by `opts.runId` that is attributable to
+ * `opts.unitId` (with the run_id fallback described in the module header for
+ * untagged bundles and unitId-less verdicts).
+ *
+ * Uses the provider's DIRECT `upsert` (a SYSTEM-level utility update that
+ * bypasses the propose/curator flow, like maintenance/compaction). `setQValue`
+ * changes only `metadata.qValue`, leaving scope/kind/text (and therefore the
+ * record id) unchanged, so `upsert` replaces the record in place.
+ */
+export declare function applyCouncilReward(provider: MemoryProvider, opts: CouncilRewardOptions): Promise<CouncilRewardResult>;
+/**
+ * FB-003 [MEDIUM]: Truncate a plain object so its JSON representation fits
+ * within a byte cap while always producing valid JSON. The source object is
+ * truncated before stringification so the output can never be a JSON fragment.
+ *
+ * Strategy:
+ *  1. If the full JSON already fits → return unchanged.
+ *  2. If adding a `__truncated__: true` marker still fits → return with marker.
+ *  3. Last resort: return a placeholder with metadata about the original size.
+ */
+export declare function truncateObjectForJson<T extends Record<string, unknown>>(obj: T, capBytes: number): T & {
+    __truncated__?: boolean;
+};