@graphrefly/graphrefly 0.47.0 → 0.47.1

package/dist/utils/memory/index.d.cts

@@ -1,5 +1,5 @@
 import { Node } from '@graphrefly/pure-ts/core';
-import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { ReactiveLogBundle, StorageBackend, Codec, AppendLogStorageTier } from '@graphrefly/pure-ts/extra';
 import { Graph } from '@graphrefly/pure-ts/graph';
 import { BaseAuditRecord } from '../../base/mutation/index.cjs';
 import { N as NodeOrValue } from '../../_internal-B23BagFd.cjs';
@@ -316,6 +316,595 @@ interface ReactiveFactStoreGraph<T> extends Graph {
  */
 declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
+/**
+ * Promotion 1 (memo:Re Story 6.4 back-derivation; DS-14.7 follow-up #2 —
+ * the persistence half of `simpleFactStore()`). Design-review-locked
+ * 2026-05-16.
+ *
+ * memo:Re hand-rolled `createPersistentMemoryStore` (217 LOC): a
+ * `reactiveLog.attach(ingest)` side-log + an `appendLogStorage` tier +
+ * paginated replay + a `persistedCount` suffix-cursor for replay-dedup +
+ * flush/dispose lifecycle. Its code-review's *only High* finding (flush
+ * partial-failure double-append) + several Meds (concurrent-flush race,
+ * `persistedCount` baseline fragility, `loadAllHistory` silent truncation)
+ * were all artifacts of the first consumer hand-rolling substrate-general
+ * orchestration. This factory owns log↔store↔replay↔dedup correctly so the
+ * whole silent-corruption bug class disappears for every future consumer.
+ *
+ * **Key design properties (locked):**
+ * - **Synchronous factory.** Returns the `Graph` immediately like every other
+ *   `utils/memory` factory — `utils/` is composed by presets/solutions and
+ *   must stay reactive (no `await` in a construction path). The inherently-IO
+ *   durable load + replay is the ONE async boundary and it lives in a single
+ *   isolated reactive source node (`fromAny` over a paginated `loadEntries`
+ *   async-iterator), per spec §5.10 — not in the factory signature.
+ * - **Substrate-owned durable cursor.** Persistence is wired AFTER the replay
+ *   source drains; `ReactiveLogBundle.attachStorage` initialises its
+ *   delivered-cursor to `ingestLog.size` at attach time, so the replayed
+ *   history is NOT re-persisted and only post-replay live fragments ship.
+ *   The cursor is entirely internal — the consumer tracks nothing (no
+ *   `persistedCount`). Observability is the read-only `position` Node.
+ * - **Flush delegated** to the already-QA-hardened `appendLogStorage.flush`
+ *   (reject-on-prior-failure + rollback-epoch + chained-drain) — the High
+ *   double-append dissolves because nothing here hand-rolls `appendEntries`
+ *   + a cursor.
+ * - **No silent partial-history loss.** Replay reads the durable history in a
+ *   single `tier.loadEntries()` call — the substrate append-log tier returns
+ *   the COMPLETE log (it does not paginate / windowed-truncate), so memo:Re's
+ *   `loadAllHistory` partial-page-truncation bug class is absent by
+ *   construction (not "detected"). Any `loadEntries` rejection propagates as
+ *   `ERROR` on the replay source (observable), not a swallowed partial load.
+ *   (Real cursor pagination for very large logs is a deferred substrate
+ *   enhancement — see `docs/optimizations.md`.)
+ *
+ * Determinism: `reactiveFactStore`'s cascade `validTo` is derived from the
+ * triggering root (not wall-clock), so replaying the persisted ingest stream
+ * rebuilds a byte-identical store — the rebuildable-projection contract
+ * documented on {@link ReactiveFactStoreConfig.recordIngest}.
+ *
+ * Only the bytes-`StorageBackend` adapter stays userland; the BigInt-safe
+ * codec is upstream (`bigintJsonCodecFor`, the default here).
+ *
+ * @module
+ */
+
+interface PersistentReactiveFactStoreConfig<T> extends Omit<ReactiveFactStoreConfig<T>, "recordIngest" | "admissionFilter"> {
+    /**
+     * Bytes backend the durable ingest log is persisted through. The ONLY
+     * userland piece — e.g. memo:Re's Drizzle/Expo-SQLite `StorageBackend`,
+     * or `memoryBackend()` for tests.
+     */
+    readonly storage: StorageBackend;
+    /** Backend key / tier name. Default `"fact_store_ingest"`. */
+    readonly persistName?: string;
+    /** Codec for the durable bucket. Default `bigintJsonCodecFor` (BigInt-safe). */
+    readonly codec?: Codec<readonly MemoryFragment<T>[]>;
+}
+interface PersistentReactiveFactStoreGraph<T> extends ReactiveFactStoreGraph<T> {
+    /**
+     * Reactive count of durably-persisted fragments. `0` until startup replay
+     * completes; thereafter the committed-fragment count (replayed history —
+     * loaded FROM the durable tier — plus live fragments shipped by the
+     * substrate-owned `attachStorage` cursor; call {@link flush} to force them
+     * physically durable). Observability only — the cursor is internal.
+     */
+    readonly position: Node<number>;
+    /**
+     * Reactive count of fragments rebuilt from durable history at startup.
+     * `0` until the first replayed fragment; final value once replay
+     * `COMPLETE`s.
+     */
+    readonly replayedCount: Node<number>;
+    /** The durable append-log tier (shared backend; e.g. for projector cursors). */
+    readonly tier: AppendLogStorageTier<MemoryFragment<T>>;
+    /**
+     * Force-drain the durable tier. Delegates to the QA-hardened
+     * `appendLogStorage.flush` (rejects if a prior in-flight write failed;
+     * honours the rollback epoch). Resolves once all shipped fragments are
+     * physically durable.
+     *
+     * **Pre-attach-live durability (QA-E):** a fragment emitted into
+     * `config.ingest` in the same synchronous tick as construction (before the
+     * async replay drains) is shipped by a one-shot, fire-and-forget
+     * reconciliation write whose rejection is NOT surfaced inline. Call
+     * `flush()` after construction settles to (a) confirm that slice is
+     * physically durable and (b) surface any write failure as a rejection. The
+     * normal pattern — observe `replayedCount`/`position` before feeding live
+     * ingest — avoids the window entirely.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Build a durable, event-sourced {@link reactiveFactStore} that owns
+ * log↔store↔replay↔dedup correctly. Synchronous factory; the only async is
+ * an isolated internal replay source. See module docstring for the locked
+ * design rationale.
+ *
+ * @example
+ * ```ts
+ * import { persistentReactiveFactStore } from "@graphrefly/graphrefly";
+ * import { memoryBackend } from "@graphrefly/pure-ts/extra";
+ *
+ * const ingest = node<MemoryFragment<Doc>>([], { initial: undefined });
+ * const mem = persistentReactiveFactStore<Doc>({
+ *   ingest,
+ *   extractDependencies: (f) => f.sources,
+ *   storage: memoryBackend(),
+ * });
+ * // Restart is automatic: the durable history is replayed through `ingest`
+ * // on construction; observe `mem.replayedCount` / `mem.position`.
+ * ingest.emit(myFragment);            // live — persisted (not re-persisted)
+ * await mem.flush();                  // force physically durable
+ * ```
+ *
+ * @category memory
+ */
+declare function persistentReactiveFactStore<T>(config: PersistentReactiveFactStoreConfig<T>): PersistentReactiveFactStoreGraph<T>;
+
+/**
+ * Recipe — **LLM gatekeeper** admission filter.
+ *
+ * `ReactiveFactStoreConfig.admissionFilter` is a **synchronous** face — it runs
+ * inside `extract_op` at ingest time, so it cannot itself `await` an LLM (spec
+ * §5.10 forbids raw async in the reactive layer; the LLM call belongs in a
+ * source / `promptNode` upstream). This recipe adapts a **precomputed verdict
+ * stream** to the sync face: the caller runs the judge upstream (a `promptNode`
+ * over the candidate fragment stream) and feeds its `Map<FactId, boolean>`
+ * verdicts in; the recipe returns a `Node<AdmissionFilter<T>>` that consults
+ * the latest verdicts synchronously.
+ *
+ * ```ts
+ * // upstream: async LLM judge produces verdicts (id → admit?)
+ * const verdicts = promptNode(adapter, [candidates], judgeFragmentsFn); // Node<Map<FactId,boolean>>
+ * const mem = reactiveFactStore<Doc>({
+ *   ingest, extractDependencies,
+ *   admissionFilter: admissionLlmJudge<Doc>(verdicts), // ② sync-face adapter
+ * });
+ * ```
+ *
+ * **Deny-by-default.** A fragment with no verdict yet is rejected
+ * (`defaultVerdict` default `false`) — the store never admits an unjudged fact.
+ * Set `defaultVerdict: true` for an allow-then-prune posture instead.
+ *
+ * **⚠️ The filter only gates admission AT ingest, synchronously.**
+ * - A fragment ingested **before** its verdict lands is rejected (with the
+ *   default `false`) and is **permanently lost** — there is no buffering or
+ *   retry; a later verdict admitting that id does NOT retroactively ingest it.
+ *   If you cannot guarantee verdict-before-fragment ordering, buffer/replay
+ *   the candidate stream upstream (e.g. gate ingest behind the verdict Node).
+ * - "Prune" in `defaultVerdict: true` is a misnomer for *post-hoc removal*: a
+ *   verdict flipping `true → false` after a fact is committed does nothing
+ *   (the fact stays). It only means "admit unjudged, reject explicitly-denied
+ *   at ingest". True pruning requires a separate obsoletion path.
+ *
+ * @module
+ */
+
+interface AdmissionLlmJudgeOptions {
+    /** Verdict for a fragment the judge hasn't ruled on yet. Default `false` (strict gate). */
+    readonly defaultVerdict?: boolean;
+    /** Node name. Default `admission_llm_judge`. */
+    readonly name?: string;
+}
+/**
+ * Adapt an upstream LLM-verdict stream to the synchronous `admissionFilter`
+ * face. `verdicts` is a Node carrying the current `factId → admit?` map (e.g.
+ * a `promptNode` accumulating judgements).
+ *
+ * @category memory
+ */
+declare function admissionLlmJudge<T>(verdicts: Node<ReadonlyMap<FactId, boolean>>, opts?: AdmissionLlmJudgeOptions): Node<AdmissionFilter<T>>;
+
+/**
+ * Recipe — **"as of t" historical view** (MEME L3 obsolescence reasoning).
+ *
+ * `reactiveFactStore`'s built-in `query`/`answer` face answers a structured
+ * `MemoryQuery` (which already supports `asOf`), but a common need is a
+ * *standing, reactive* historical projection that re-derives whenever either
+ * the store changes **or** the as-of instant moves (e.g. a scrubber in a debug
+ * UI). This recipe is that projection over face ④ + a reactive `asOf` input:
+ * `derived([asOf, mem.factStore])` → only fragments valid at `asOf`
+ * (bi-temporal `[validFrom, validTo)` test), giving Graphiti/Zep-style
+ * "what did we believe at time T" without committing anything to the spec.
+ *
+ * ```ts
+ * const asOf = node<bigint>([], { initial: undefined });
+ * const view = bitemporalQuery(mem, asOf, { tags: ["policy"] });
+ * asOf.emit(lastTuesdayNs);  // view re-derives to the policy facts valid then
+ * ```
+ *
+ * Pass `asOf` SENTINEL (no emit yet) → the view is the **currently-valid** set
+ * (live facts, `validTo` unset), so it's useful before any scrub too.
+ *
+ * @module
+ */
+
+interface BitemporalQueryOptions {
+    /** Restrict to fragments carrying any of these tags (OR). */
+    readonly tags?: readonly string[];
+    /** Minimum confidence (inclusive). */
+    readonly minConfidence?: number;
+    /** Node name. Default `bitemporal_query`. */
+    readonly name?: string;
+}
+/**
+ * Build a standing bi-temporal historical view over a {@link reactiveFactStore}.
+ * Emits the fragments valid at the latest `asOf` (sorted confidence desc, then
+ * `t_ns` desc — same order as the built-in `answer`).
+ *
+ * @category memory
+ */
+declare function bitemporalQuery<T>(mem: ReactiveFactStoreGraph<T>, asOf: Node<bigint>, opts?: BitemporalQueryOptions): Node<readonly MemoryFragment<T>[]>;
+
+/**
+ * Recipe — **REM-style replay consolidation**.
+ *
+ * Hassabis's sleep-consolidation frame: periodically replay the
+ * highest-confidence × most-recent facts and synthesize a compressed successor
+ * fragment (version-chained via `parent_fragment_id`). Builds the two config
+ * fields the `consolidate` extension face needs — a reactive `consolidateTrigger`
+ * (a `fromTimer` source, spec §5.8-compliant) and the `consolidate(store)`
+ * summarizer — so the caller just spreads them in:
+ *
+ * ```ts
+ * const mem = reactiveFactStore<Doc>({
+ *   ingest, extractDependencies,
+ *   ...consolidationRem<Doc>({
+ *     periodMs: 60_000,
+ *     topK: 8,
+ *     recentWindowNs: 3_600_000_000_000n,           // 1h
+ *     summarize: (frags) => mergeDocs(frags),       // domain-specific
+ *   }),
+ * });
+ * ```
+ *
+ * The pattern default-wires consolidator output back into ingest (Q9-open-6),
+ * so the successor fragment becomes a first-class fact; the originals are left
+ * intact (callers obsolete them via their own `validTo` policy if desired —
+ * keeping that out of the recipe preserves "the recipe never decides what to
+ * forget").
+ *
+ * **Selection order & assumptions.** `recentWindowNs` filters the *pool* first
+ * (facts within `recentWindowNs` of the newest live fact's `t_ns`); the pool
+ * is then sorted by `confidence desc, t_ns desc` and `topK`-sliced — so an
+ * old-but-in-window high-confidence fact can beat a brand-new low-confidence
+ * one (recency gates the pool, confidence picks the winners). If every fact
+ * falls outside the window the pool is empty and `summarize` is not called
+ * (the consolidator emits `[]` — indistinguishable from an empty store).
+ * `recentWindowNs` math assumes all fragments' `t_ns` come from the **same
+ * clock** (`monotonicNs` xor `wallClockNs`, not mixed) — the window is
+ * meaningless across mixed clocks.
+ *
+ * @module
+ */
+
+interface ConsolidationRemOptions<T> {
+    /** Replay period in milliseconds. */
+    readonly periodMs: number;
+    /** How many top facts to replay per pass. */
+    readonly topK: number;
+    /**
+     * Synthesize successor fragment(s) from the replayed set. Domain-specific —
+     * required (the pattern's default `consolidate` is a no-op). Set
+     * `parent_fragment_id` on the result to chain versions.
+     */
+    readonly summarize: (replayed: readonly MemoryFragment<T>[]) => readonly MemoryFragment<T>[];
+    /**
+     * Only replay facts whose `t_ns` is within this many ns of the most-recent
+     * fact's `t_ns` (recency gate). Omit to consider all live facts.
+     */
+    readonly recentWindowNs?: bigint;
+}
+interface ConsolidationRemConfig<T> {
+    readonly consolidateTrigger: Node<number>;
+    readonly consolidate: (store: StoreReadHandle<T>) => readonly MemoryFragment<T>[];
+}
+/**
+ * Build the `{ consolidateTrigger, consolidate }` pair for a REM-replay
+ * consolidation policy. Spread into {@link reactiveFactStore}'s config.
+ *
+ * @category memory
+ */
+declare function consolidationRem<T>(opts: ConsolidationRemOptions<T>): ConsolidationRemConfig<T>;
+
+/**
+ * Recipe — **standard forgetting curve** (Hassabis confidence drift).
+ *
+ * Periodically decays every live fact's `confidence` toward a floor on an
+ * exponential half-life schedule, re-ingesting the drifted fragment (MEME L1
+ * direct-replace). The periodic trigger is a reactive `fromTimer` source
+ * (spec §5.8 no-polling / §5.10 no raw `setTimeout` — `fromTimer` is the
+ * sanctioned reactive timer) and the only reactive dep, so there is no
+ * within-wave feedback loop (COMPOSITION-GUIDE-GRAPH §7): the store snapshot is
+ * read **advisory** off `mem.factStore.cache`, never as a reactive dep; the
+ * re-ingest write commits **synchronously this tick** (graphrefly push is
+ * synchronous) and the next tick decays from there.
+ *
+ * > **Why a recipe, not the `decay` face.** `ReactiveFactStoreConfig.decay:
+ * > Node<DecayPolicy>` is a *locked design face* (DS-14.7 PART 4.1) but the
+ * > shipped `reactiveFactStore()` v1 factory does **not** consume it (tracked
+ * > as a factory-gap item in `docs/optimizations.md`). This recipe delivers the
+ * > §5.8 "`decay` recipe uses `fromTimer` for periodic confidence drift"
+ * > behavior over the **wired** `ingest` face instead — fully spec-compliant
+ * > and zero-core-change. It composes regardless of whether the `decay` face is
+ * > later wired.
+ *
+ * **Convergence (conditional — read this).** Per-id decay is computed against
+ * the elapsed time since this fact was last decayed (recipe-owned closure
+ * clock — `t_ns` provenance is preserved, never overwritten; a re-ingested
+ * *new version* — fresher `t_ns` than the last tick — restarts from its own
+ * `t_ns`, not the stale prior-version tick). A fragment is skipped (no
+ * re-ingest) when it is obsolete (`validTo` set), already at/below `floor`, or
+ * the drift is below `epsilon`. Quiescence ("timer keeps ticking, recipe emits
+ * `[]`, no churn") therefore holds **only when `epsilon > 0` AND `floor` is
+ * reachable** — with `epsilon <= 0` and a finite half-life the geometric
+ * drift toward `floor` is always `> 0`, so the loop re-ingests every live fact
+ * forever (silent CPU/GC churn, never an error). `epsilon` is clamped to a
+ * tiny positive minimum to make accidental non-quiescence impossible.
+ * Obsoletion safety: the obsolete guard is re-checked against the **live**
+ * store immediately before re-ingest, so a fact obsoleted by an in-flight
+ * cascade earlier in the same tick is never resurrected by a stale snapshot
+ * read.
+ *
+ * @module
+ */
+
+interface DecayExponentialOptions {
+    /** Half-life in nanoseconds — confidence halves every `halfLifeNs` of fact age. */
+    readonly halfLifeNs: bigint;
+    /** Timer period in milliseconds (how often the forgetting pass runs). */
+    readonly periodMs: number;
+    /** Confidence floor; facts at/below it are left untouched. Default `0`. */
+    readonly floor?: number;
+    /**
+     * Minimum confidence drift to bother re-ingesting. Default `1e-4`. Clamped
+     * to a tiny positive minimum (`<= 0` would prevent quiescence — see the
+     * module "Convergence" note).
+     */
+    readonly epsilon?: number;
+    /** Node name. Default `decay_exponential`. */
+    readonly name?: string;
+}
+/**
+ * Wire an exponential-decay forgetting loop onto a {@link reactiveFactStore}.
+ * Self-adds a driver Node to the store's graph (`describe()`-visible) and
+ * returns it; each emission is the batch of fragments decayed that tick (also
+ * fed back through `ingest`).
+ *
+ * @category memory
+ */
+declare function decayExponential<T>(mem: ReactiveFactStoreGraph<T>, ingest: Node<MemoryFragment<T>>, opts: DecayExponentialOptions): Node<readonly MemoryFragment<T>[]>;
+
+/**
+ * Recipe — **write-time influence analysis** (MEME write-time `reachable`).
+ *
+ * The store's `dependents_index` is a one-hop reverse-dependency map; "if I
+ * obsolete fact X, what *transitively* gets invalidated?" is its closure. This
+ * recipe exposes that closure as a reactive projection over face ④
+ * (`mem.dependentsIndex`), so a writer can see blast-radius **before**
+ * committing an obsolescence — the same reachability the cascade loop walks,
+ * surfaced for inspection.
+ *
+ * ```ts
+ * const inf = influenceAnalysis(mem);
+ * inf.influenceOf("home").subscribe(ids => console.log("obsoleting home hits", ids));
+ * inf.ranked.subscribe(rows => rows.slice(0,5)); // most-influential facts
+ * ```
+ *
+ * Pure observer — never writes back, so it cannot perturb cascade
+ * convergence. **Single-apply per store** (it adds an `${name}_ranked` node);
+ * apply twice on the same `mem` only with a distinct `opts.name`.
+ *
+ * **Cost.** `ranked` runs a BFS closure per index key on every
+ * `dependents_index` emit — O(keys · (V+E)), NOT O(maxRanked); `maxRanked`
+ * caps only the emitted slice, not the computation. Acceptable because
+ * `dependents_index` is metadata (≪ the fact store, per DS-14.7 Q9-open-1);
+ * for a pathologically dense index prefer `influenceOf(id)` (single-root BFS)
+ * over subscribing `ranked`. In a cyclic reverse-dep graph
+ * (LLM-extracted `A→B→A`) `closureOf` still terminates (`seen` set) but every
+ * SCC member reports the same closure size — a *reachability* count, not the
+ * cascade's actual obsolete-only propagation reach (which `processedRoots`
+ * bounds further).
+ *
+ * @module
+ */
+
+interface InfluenceRow {
+    readonly factId: FactId;
+    /** Size of the transitive dependent closure (blast radius if obsoleted). */
+    readonly influence: number;
+}
+interface InfluenceAnalysisOptions {
+    /** Cap on rows emitted by `ranked` (top-N by influence). Default `64`. */
+    readonly maxRanked?: number;
+    /** Node name prefix. Default `influence`. */
+    readonly name?: string;
+}
+interface InfluenceAnalysis {
+    /** Reactive transitive dependent closure of `rootId` (excludes the root). */
+    influenceOf(rootId: FactId): Node<readonly FactId[]>;
+    /** Facts ranked by transitive-closure size (desc), capped at `maxRanked`. */
+    readonly ranked: Node<readonly InfluenceRow[]>;
+}
+/**
+ * Attach influence/blast-radius analysis to a {@link reactiveFactStore}.
+ *
+ * @category memory
+ */
+declare function influenceAnalysis<T>(mem: ReactiveFactStoreGraph<T>, opts?: InfluenceAnalysisOptions): InfluenceAnalysis;
+
+/**
+ * Recipe — **cascade-event tracer** (debugging the invisible edge).
+ *
+ * The `dependents_index` lookup that drives cascade invalidation is a fn-body
+ * map read, not a topology edge — `describe()` / `explain()` can't see *why*
+ * fact C got invalidated. This recipe is the pure-observer (face ④) companion
+ * that subscribes `mem.cascade` + `mem.cascadeOverflow` and keeps a bounded
+ * ring of human-readable trace entries (each carries the `causalReason` string
+ * the store stamps for exactly this purpose), so a developer can answer
+ * "what obsoleted this?" without instrumenting the store.
+ *
+ * ```ts
+ * const trace = invalidationTracer(mem, { limit: 256 });
+ * trace.subscribe((entries) => entries.forEach(e => log(e.causalReason)));
+ * ```
+ *
+ * Read-only: it never writes back into the store, so it cannot perturb cascade
+ * convergence.
+ *
+ * @module
+ */
+
+interface InvalidationTraceEntry {
+    readonly kind: "cascade" | "overflow";
+    readonly factId: FactId;
+    readonly rootFactId: FactId;
+    readonly reason: CascadeReason | "overflow";
+    readonly iteration?: number;
+    readonly causalReason: string;
+}
+interface InvalidationTracerOptions {
+    /** Ring-buffer size (most-recent N trace entries retained). Default `256`. */
+    readonly limit?: number;
+    /** Node name. Default `invalidation_tracer`. */
+    readonly name?: string;
+}
+/**
+ * Attach a bounded cascade-event tracer to a {@link reactiveFactStore}.
+ * Self-adds a `describe()`-visible observer Node and returns it; each emission
+ * is the current trace ring (oldest → newest).
+ *
+ * @category memory
+ */
+declare function invalidationTracer<T>(mem: ReactiveFactStoreGraph<T>, opts?: InvalidationTracerOptions): Node<readonly InvalidationTraceEntry[]>;
+
+/**
+ * Recipe — **self-evolving scoring policy** (continual learning).
+ *
+ * Closes Hassabis's continual-learning frame against the `scoring` extension
+ * face (②): an outcome / RL signal stream feeds back into the policy that
+ * `reactiveFactStore` applies on `outcome` write-back, so the agent's memory
+ * *learns* which facts proved useful.
+ *
+ * ```ts
+ * const outcomes = node<OutcomeSignal>([], { initial: undefined });
+ * const mem = reactiveFactStore<Doc>({
+ *   ingest, extractDependencies,
+ *   outcome:  outcomes,                       // ③ topic input (RL signal)
+ *   scoring:  scoringByOutcome(outcomes),     // ② policy that evolves with it
+ * });
+ * ```
+ *
+ * The returned `Node<ScoringPolicy<T>>` re-emits a fresh policy closure every
+ * time an `OutcomeSignal` arrives; the closure scores a fragment as
+ * `clamp01(base(f) + learningRate · Σ reward(f.id))`. The reward accumulator is
+ * a recipe-owned closure Map (sole-owner mutation inside the derived fn — the
+ * COMPOSITION-GUIDE-sanctioned pattern for a fold the node alone advances),
+ * keyed by `factId`, so learning is cumulative across episodes and survives
+ * policy re-emission.
+ *
+ * **Contract (load-bearing — do not "normalize"):**
+ * - The fn folds **every signal in the wave** (`for (const sig of batchData[0])`),
+ *   NOT `lastOf` last-only like the other recipes — a batched wave carrying N
+ *   `OutcomeSignal`s must accumulate all N. Replacing this with `lastOf` would
+ *   silently drop all-but-last reward in a batch.
+ * - `outcomes` MUST be a non-replaying event source (each physical signal
+ *   delivered once). The fold has no per-signal idempotency key (two identical
+ *   `{factId, reward}` are legitimately distinct events); a source that
+ *   push-on-subscribe **re-delivers** a cached signal to a re-subscribe would
+ *   double-count it. The normal wiring (single keepalive'd consumer via the
+ *   factory's `outcomeProcessor`, subscribed at construction before any emit)
+ *   is safe.
+ * - The policy node carries **no `equals`** by design: every emit is a fresh
+ *   closure identity so the factory's `outcomeProcessor` always re-fires and
+ *   re-reads the freshly-folded `acc` (the closure reads `acc` lazily at call
+ *   time). Adding an `equals` would make outcome write-back lag one signal.
+ * - `acc` retains one entry per rewarded `factId` for the store's lifetime
+ *   (same bounded-growth class as `ingestLog`; acceptable — it is metadata).
+ *
+ * @module
+ */
+
+interface ScoringByOutcomeOptions<T> {
+    /**
+     * Base score before accumulated reward. Default: the fragment's own
+     * `confidence` (so an un-rewarded fact keeps its ingested confidence).
+     */
+    readonly base?: (f: MemoryFragment<T>) => number;
+    /** Multiplier on accumulated reward. Default `1`. */
+    readonly learningRate?: number;
+    /** Node name (collision-safe if you build more than one). Default `scoring_by_outcome`. */
+    readonly name?: string;
+}
+/**
+ * Build a continual-learning {@link ScoringPolicy} Node from an
+ * {@link OutcomeSignal} stream. Pass the SAME `outcomes` Node as both
+ * `config.outcome` and (via this recipe) `config.scoring`.
+ *
+ * @category memory
+ */
+declare function scoringByOutcome<T>(outcomes: Node<OutcomeSignal>, opts?: ScoringByOutcomeOptions<T>): Node<ScoringPolicy<T>>;
+
+/**
+ * Recipe — **multi-tenant isolation** sharding.
+ *
+ * Two postures over the `shardBy` + `shardCount` faces (plain-fn face ①):
+ *
+ * - **Strict isolation** (`tenants` listed): one shard per tenant, fixed
+ *   `tenant → index` mapping. A tenant's facts never share a shard with
+ *   another's — the strongest in-process isolation the static-topology store
+ *   offers (per-shard `state<FactStore>` nodes). Unknown tenants fall to a
+ *   dedicated overflow shard (last index).
+ * - **Soft partition** (no `tenants`): hash the tenant key into `shardCount`
+ *   buckets — even load, tenants *may* co-reside (collision), but cross-tenant
+ *   reads still require an explicit query (no accidental leakage of the *index*,
+ *   just shared physical storage).
+ *
+ * **Caveats.** Soft "even load" holds only at sufficient tenant cardinality —
+ * with few tenants vs `shardCount`, FNV-1a-mod can collide several onto one
+ * shard (use **strict** mode for a guaranteed-per-tenant shard). `tenantOf`
+ * must return a defined, stable key: a `undefined`/`null` return is coerced to
+ * the string `"undefined"` by the factory's hash and silently pools all
+ * tenant-less facts together. Strict mode's overflow shard intentionally pools
+ * **all** unconfigured tenants together (isolated from configured ones, not
+ * from each other).
+ *
+ * ```ts
+ * const mem = reactiveFactStore<Doc>({
+ *   ingest, extractDependencies,
+ *   ...shardByTenant<Doc>((f) => f.payload.tenantId, {
+ *     tenants: ["acme", "globex"],   // strict: 3 shards (2 + overflow)
+ *   }),
+ * });
+ * ```
+ *
+ * @module
+ */
+
+interface ShardByTenantOptions {
+    /**
+     * Known tenants for strict 1-shard-per-tenant isolation. Omit for soft
+     * hash partitioning. The strict layout adds one trailing **overflow** shard
+     * for tenants not in this list (so an unconfigured tenant is still isolated
+     * from the configured ones, just pooled together).
+     */
+    readonly tenants?: readonly string[];
+    /** Bucket count for the soft (non-strict) posture. Default `4`. */
+    readonly shardCount?: number;
+}
+interface ShardByTenantConfig<T> {
+    readonly shardBy: (f: MemoryFragment<T>) => ShardKey;
+    readonly shardCount: number;
+}
+/**
+ * Build the `{ shardBy, shardCount }` pair for tenant-isolated sharding.
+ * `tenantOf` extracts the tenant key from a fragment. Spread into
+ * {@link reactiveFactStore}'s config.
+ *
+ * @category memory
+ */
+declare function shardByTenant<T>(tenantOf: (f: MemoryFragment<T>) => string, opts?: ShardByTenantOptions): ShardByTenantConfig<T>;
+
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
  * `archive/docs/SESSION-public-face-blocks-review.md` (Wave A, locked 2026-04-25).
@@ -657,4 +1246,4 @@ type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
  */
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
 
-export { type AdmissionFilter, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type RankedCollectionEntry, type ReactiveFactStoreConfig, type ReactiveFactStoreGraph, type ReviewRequest, type ScoringPolicy, type ShardKey, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, collection, cosineSimilarity, knowledgeGraph, reactiveFactStore, vectorIndex };
+export { type AdmissionFilter, type AdmissionLlmJudgeOptions, type BitemporalQueryOptions, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type ConsolidationRemConfig, type ConsolidationRemOptions, type DecayExponentialOptions, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type InfluenceAnalysis, type InfluenceAnalysisOptions, type InfluenceRow, type InvalidationTraceEntry, type InvalidationTracerOptions, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type PersistentReactiveFactStoreConfig, type PersistentReactiveFactStoreGraph, type RankedCollectionEntry, type ReactiveFactStoreConfig, type ReactiveFactStoreGraph, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, admissionLlmJudge, bitemporalQuery, collection, consolidationRem, cosineSimilarity, decayExponential, influenceAnalysis, invalidationTracer, knowledgeGraph, persistentReactiveFactStore, reactiveFactStore, scoringByOutcome, shardByTenant, vectorIndex };