@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/{index-CZ3r5Rxp.d.ts → utils/memory/index.d.cts}

@@ -1,7 +1,242 @@
-import { N as Node } from './node-kK3CvTrR.js';
-import { B as BaseAuditRecord } from './index-Yq60JP3s.js';
-import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
-import { G as Graph } from './graph-D9LFnda9.js';
+import { Node } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle } 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';
+
+/**
+ * DS-14.7 — Reactive Fact Store / Live Knowledge Graph (locked 2026-05-13).
+ *
+ * Static-topology agent-memory substrate that satisfies MEME L2 (cascade
+ * invalidation) and L3 (obsolescence reasoning) plus Hassabis's
+ * filter/consolidate/continual-learning frame, **without** materializing one
+ * reactive node per fact. ~12 fixed operator nodes never grow regardless of how
+ * many facts the store holds; facts live as columnar DATA inside an indexed
+ * `state<FactStore>` (optionally sharded), and cascade is implemented as
+ * bounded recursive message emission. Termination rests on a per-root
+ * semantic contract — a fact only drives the cascade when it transitions to
+ * obsolete (`validTo` set), and each obsolete root emits its cascade exactly
+ * once across all waves — plus an empty-array fixpoint short-circuit. The
+ * cascade is modeled as DATA arrays (NOT INVALIDATE messages), so spec §1.4's
+ * idempotent-within-a-wave INVALIDATE guarantee does NOT govern this loop;
+ * convergence is the per-root contract, not a spec §1.4 diamond-merge.
+ *
+ * Canonical design: `archive/docs/SESSION-DS-14.7-reactive-fact-store.md`
+ * (9Q walk complete; Q9-open items 1–9 all resolved).
+ *
+ * Locked decisions baked in here:
+ * - `cascadeMaxIterations` default **8**; overflow emits a per-batch summary
+ *   `{ droppedCount, sample, rootFactId }` to `cascadeOverflow` (Q9-open-4).
+ *   The overflow `sample` is capped at `OVERFLOW_SAMPLE_SIZE` (8),
+ *   independent of `cascadeMaxIterations`.
+ * - `shardBy` default hash-mod **4**; caller override; `dependentsIndex`
+ *   unsharded for v1 (Q9-open-1).
+ * - `MemoryFragment` adds `embedding? / parent_fragment_id? / provenance?`
+ *   (Q9-open-3).
+ * - `dependentsIndex` updates synchronous + atomic with `factStore` commit
+ *   (Q9-open-2).
+ * - Scoring contract `(fragment, storeReadHandle) => number` — read-only
+ *   handle, no mutation exposure (Q9-open-5).
+ * - Consolidator emits to a dedicated `consolidated` topic that the pattern
+ *   default-wires back to `ingest`; caller can intercept (Q9-open-6).
+ * - Query surface = structured `MemoryQuery` via the `query` topic (default);
+ *   function-shaped is caller-side `derived` over `factStore` (Q9-open-7).
+ * - Bi-temporal is pattern-layer only — no DS-14 envelope shape change
+ *   (Q9-open-9); `simpleFactStore()` deferred to v1.1 (Q9-open-8 — NOT built).
+ *
+ * **Cascade cycle visibility.** `cascadeProcessor` stays synchronous (preserves
+ * spec §1.4 batch-dedupe — LLM-driven dependency extraction lives UPSTREAM of
+ * the cascade topic, never inside the recursion). Every cascade message carries
+ * a `causalReason` field and the cycle nodes are tagged `meta.cycle:"cascade"`
+ * so `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` fn-body lookup.
+ *
+ * @module
+ */
+
+/** Stable identity for a stored fact. */
+type FactId = string;
+/** Shard partition key (string | number — any hashable scalar). */
+type ShardKey = string | number;
+/**
+ * A single stored memory fact. Pattern convention only — NOT a spec primitive
+ * and NOT a DS-14 envelope field (bi-temporal stays pattern-layer per
+ * Q9-open-9). Each field is a reactive lever (see design PART 2.3):
+ * `validTo` set → cascade fires; `confidence < θ` → review; `sources` →
+ * `dependentsIndex` edges feeding cascade.
+ */
+interface MemoryFragment<T> {
+    readonly id: FactId;
+    readonly payload: T;
+    /** Transaction time (when learned). `bigint` ns (e.g. `BigInt(monotonicNs())`). */
+    readonly t_ns: bigint;
+    /** Valid-time start. `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Valid-time end. Setting this is the MEME L3 obsolescence lever. */
+    readonly validTo?: bigint;
+    /** Confidence 0..1. Dropping below the review threshold emits a review. */
+    readonly confidence: number;
+    readonly tags: readonly string[];
+    /** Dependency edges — fact IDs this fact is derived from / depends on. */
+    readonly sources: readonly FactId[];
+    /** Optional dense embedding (recipes use it for retrieval). */
+    readonly embedding?: readonly number[];
+    /** Version-chain pointer — consolidator emits successor fragments. */
+    readonly parent_fragment_id?: FactId;
+    /** Free-form provenance string for audit. */
+    readonly provenance?: string;
+}
+/**
+ * Columnar in-memory store. Held as DATA inside a `state<FactStore<T>>` node
+ * (one per shard). `byId` is the authoritative map; the typed companions are
+ * kept for the recipe layer (`bitemporal-query`, `influence-analysis`) — v1
+ * stores fragments directly and lazily projects columns on demand.
+ */
+interface FactStore<T> {
+    readonly byId: ReadonlyMap<FactId, MemoryFragment<T>>;
+}
+/** Reverse dependency index: fact → IDs that depend on it. Unsharded (v1). */
+type DependentsIndex = ReadonlyMap<FactId, readonly FactId[]>;
+/** Read-only projection passed to scoring policies (no mutation surface). */
+interface StoreReadHandle<T> {
+    get(id: FactId): MemoryFragment<T> | undefined;
+    has(id: FactId): boolean;
+    readonly size: number;
+    values(): IterableIterator<MemoryFragment<T>>;
+}
+type ScoringPolicy<T> = (fragment: MemoryFragment<T>, store: StoreReadHandle<T>) => number;
+type DecayPolicy = (confidence: number, ageNs: bigint) => number;
+type AdmissionFilter<T> = (fragment: MemoryFragment<T>) => boolean;
+/** Outcome / RL signal — write-back lever for continual learning. */
+interface OutcomeSignal {
+    readonly factId: FactId;
+    readonly reward: number;
+}
+/** Structured query (Q9-open-7 default surface). Serializable + inspectable. */
+interface MemoryQuery {
+    /** Match any of these tags (OR). Omit for no tag filter. */
+    readonly tags?: readonly string[];
+    /** Bi-temporal "as of" — only facts valid at this instant. */
+    readonly asOf?: bigint;
+    /** Minimum confidence (inclusive). */
+    readonly minConfidence?: number;
+    /** Cap results (sorted by confidence desc, then t_ns desc). */
+    readonly limit?: number;
+}
+interface MemoryAnswer<T> {
+    readonly query: MemoryQuery;
+    readonly results: readonly MemoryFragment<T>[];
+}
+type CascadeReason = "cascade" | "obsolete" | "manual";
+/** A single cascade invalidation message flowing through the cascade cycle. */
+interface CascadeEvent {
+    readonly factId: FactId;
+    readonly rootFactId: FactId;
+    readonly reason: CascadeReason;
+    /** Cascade recursion depth (1 = first wave). Bounded by `cascadeMaxIterations`. */
+    readonly iteration: number;
+    /**
+     * Human-readable causal chain — makes the `dependentsIndex` fn-body lookup
+     * visible in `explain()` output even though it is not a topology edge
+     * (design Q3 / COMPOSITION-GUIDE §24 mitigation).
+     */
+    readonly causalReason: string;
+}
+/** Per-batch overflow summary (Q9-open-4 — never per-message). */
+interface CascadeOverflow {
+    readonly droppedCount: number;
+    readonly sample: readonly FactId[];
+    readonly rootFactId: FactId;
+}
+interface ReviewRequest {
+    readonly factId: FactId;
+    readonly confidence: number;
+    readonly threshold: number;
+}
+interface FactStoreAuditRecord extends BaseAuditRecord {
+    readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "overflow";
+    readonly id?: FactId;
+    readonly reason?: CascadeReason;
+}
+interface ReactiveFactStoreConfig<T> {
+    readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
+    /** Shard partition fn. Default: FNV-1a hash of `id` mod `shardCount`. */
+    readonly shardBy?: (f: MemoryFragment<T>) => ShardKey;
+    /** Shard count for the default hash-mod sharder. Default 4 (§3.2). */
+    readonly shardCount?: number;
+    readonly scoring?: Node<ScoringPolicy<T>>;
+    readonly decay?: Node<DecayPolicy>;
+    readonly admissionFilter?: Node<AdmissionFilter<T>>;
+    readonly ingest: Node<MemoryFragment<T>>;
+    readonly outcome?: Node<OutcomeSignal>;
+    readonly query?: Node<MemoryQuery>;
+    /**
+     * Consolidator trigger — a reactive timer/cron Node (e.g. `fromCron(...)`).
+     * When supplied, the `consolidated` node maps each tick to summarized
+     * fragments emitted on the `consolidated` topic and default-wired back to
+     * the internal ingest path.
+     */
+    readonly consolidateTrigger?: Node<unknown>;
+    /**
+     * Consolidation summarizer. Reads a store snapshot, returns successor
+     * fragments (typically with `parent_fragment_id` set). Default: no-op
+     * (emits nothing) so the cron tick is observable without forcing a policy.
+     */
+    readonly consolidate?: (store: StoreReadHandle<T>) => readonly MemoryFragment<T>[];
+    /** Cascade recursion cap (§3.1). Default 8. */
+    readonly cascadeMaxIterations?: number;
+    /** Confidence below which a {@link ReviewRequest} is emitted. Default 0.3. */
+    readonly reviewThreshold?: number;
+}
+interface ReactiveFactStoreGraph<T> extends Graph {
+    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+    readonly shards: readonly Node<FactStore<T>>[];
+    /** Unified read view across all shards (derived). */
+    readonly factStore: Node<FactStore<T>>;
+    readonly dependentsIndex: Node<DependentsIndex>;
+    readonly answer: Node<MemoryAnswer<T> | null>;
+    readonly cascade: Node<readonly CascadeEvent[]>;
+    readonly cascadeOverflow: Node<CascadeOverflow | null>;
+    readonly review: Node<ReviewRequest | null>;
+    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
+    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
+    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
+}
+/**
+ * Build a static-topology reactive fact store (DS-14.7 architecture C).
+ *
+ * Topology (~12 fixed nodes — never grows with fact count):
+ *  - `shards[0..N]` — `state<FactStore<T>>` columnar stores (default 4 shards).
+ *  - `factStore` — derived union read view across shards.
+ *  - `dependentsIndex` — `state<DependentsIndex>` reverse-dep map, unsharded,
+ *    updated synchronously + atomically with each commit (Q9-open-2).
+ *  - `extractOp` — derived: ingest → admission-filtered fragment + dep edges.
+ *  - `invalidationDetector` — derived: scans committed store for `validTo`-set
+ *    / low-confidence facts, resolves dependents via `dependentsIndex`, emits
+ *    cascade messages.
+ *  - `cascade` — topic node carrying `CascadeEvent[]`.
+ *  - `cascadeProcessor` — derived, **synchronous**, `meta.cycle:"cascade"`:
+ *    dedupes by factId, writes invalidations back to shards, recurses until
+ *    fixpoint OR `cascadeMaxIterations` → `cascadeOverflow`.
+ *  - `cascadeOverflow` — per-batch overflow summary node.
+ *  - `queryOp` / `answer` — structured `MemoryQuery` → results (SENTINEL-safe).
+ *  - `outcomeProcessor` — outcome signal → confidence write-back.
+ *  - `consolidated` — cron-tick → summarized fragments on the
+ *    `consolidated` topic,
+ *    default-wired back into the ingest path.
+ *  - `review` — low-confidence proactive-verification requests.
+ *
+ * The cascade cycle (`invalidationDetector → cascade → cascadeProcessor →
+ * shards → invalidationDetector`) is a real, bounded reactive cycle. Both
+ * `invalidationDetector` and `cascadeProcessor` are tagged
+ * `meta.cycle:"cascade"` and every cascade message carries `causalReason`, so
+ * `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` lookup (COMPOSITION-GUIDE §24).
+ *
+ * @category memory
+ */
+declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
@@ -25,7 +260,7 @@ import { G as Graph } from './graph-D9LFnda9.js';
  * `firstValueFrom(node)`.
  *
  * **Audit logs.** Every imperative mutation (`upsert / remove / clear / link /
- * unlink / rescore / reindex`) is wrapped via {@link lightMutation} and appends a
+ * unlink / rescore / reindex`) is wrapped via {@link mutate} and appends a
  * typed record to a public `events` log on the bundle / graph.
  *
  * @module
@@ -49,8 +284,7 @@ import { G as Graph } from './graph-D9LFnda9.js';
  * @category memory
  */
 declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
-/** Public alias for the `Node | value` shape accepted by reactive read factories. */
-type NodeOrValue<T> = T | Node<T>;
+
 type CollectionEntry<T> = {
     readonly id: string;
     readonly value: T;
@@ -345,30 +579,4 @@ type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
  */
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
 
-type index_CollectionAuditRecord = CollectionAuditRecord;
-type index_CollectionEntry<T> = CollectionEntry<T>;
-type index_CollectionGraph<T> = CollectionGraph<T>;
-type index_CollectionOptions<T> = CollectionOptions<T>;
-type index_CollectionScoreFn<T> = CollectionScoreFn<T>;
-type index_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
-type index_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
-type index_KnowledgeGraph<TEntity, TRelation extends string = string> = KnowledgeGraph<TEntity, TRelation>;
-type index_KnowledgeGraphAuditRecord = KnowledgeGraphAuditRecord;
-type index_KnowledgeGraphOptions = KnowledgeGraphOptions;
-type index_NodeOrValue<T> = NodeOrValue<T>;
-type index_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
-type index_VectorBackend = VectorBackend;
-type index_VectorIndexAuditRecord = VectorIndexAuditRecord;
-type index_VectorIndexGraph<TMeta> = VectorIndexGraph<TMeta>;
-type index_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
-type index_VectorRecord<TMeta> = VectorRecord<TMeta>;
-type index_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
-declare const index_collection: typeof collection;
-declare const index_cosineSimilarity: typeof cosineSimilarity;
-declare const index_knowledgeGraph: typeof knowledgeGraph;
-declare const index_vectorIndex: typeof vectorIndex;
-declare namespace index {
-  export { type index_CollectionAuditRecord as CollectionAuditRecord, type index_CollectionEntry as CollectionEntry, type index_CollectionGraph as CollectionGraph, type index_CollectionOptions as CollectionOptions, type index_CollectionScoreFn as CollectionScoreFn, type index_HnswAdapter as HnswAdapter, type index_KnowledgeEdge as KnowledgeEdge, type index_KnowledgeGraph as KnowledgeGraph, type index_KnowledgeGraphAuditRecord as KnowledgeGraphAuditRecord, type index_KnowledgeGraphOptions as KnowledgeGraphOptions, type index_NodeOrValue as NodeOrValue, type index_RankedCollectionEntry as RankedCollectionEntry, type index_VectorBackend as VectorBackend, type index_VectorIndexAuditRecord as VectorIndexAuditRecord, type index_VectorIndexGraph as VectorIndexGraph, type index_VectorIndexOptions as VectorIndexOptions, type index_VectorRecord as VectorRecord, type index_VectorSearchResult as VectorSearchResult, index_collection as collection, index_cosineSimilarity as cosineSimilarity, index_knowledgeGraph as knowledgeGraph, index_vectorIndex as vectorIndex };
-}
-
-export { type CollectionGraph as C, type HnswAdapter as H, type KnowledgeGraph as K, type NodeOrValue as N, type RankedCollectionEntry as R, type VectorSearchResult as V, type VectorIndexGraph as a, type CollectionAuditRecord as b, type CollectionEntry as c, type CollectionOptions as d, type CollectionScoreFn as e, type KnowledgeEdge as f, type KnowledgeGraphAuditRecord as g, type KnowledgeGraphOptions as h, index as i, type VectorBackend as j, type VectorIndexAuditRecord as k, type VectorIndexOptions as l, type VectorRecord as m, collection as n, cosineSimilarity as o, knowledgeGraph as p, vectorIndex as v };
+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 };

package/dist/{index-B17QddL1.d.cts → utils/memory/index.d.ts}

@@ -1,7 +1,242 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
-import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
-import { G as Graph } from './graph-CWvEUQAq.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
+import { ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { Graph } from '@graphrefly/pure-ts/graph';
+import { BaseAuditRecord } from '../../base/mutation/index.js';
+import { N as NodeOrValue } from '../../_internal-B23BagFd.js';
+
+/**
+ * DS-14.7 — Reactive Fact Store / Live Knowledge Graph (locked 2026-05-13).
+ *
+ * Static-topology agent-memory substrate that satisfies MEME L2 (cascade
+ * invalidation) and L3 (obsolescence reasoning) plus Hassabis's
+ * filter/consolidate/continual-learning frame, **without** materializing one
+ * reactive node per fact. ~12 fixed operator nodes never grow regardless of how
+ * many facts the store holds; facts live as columnar DATA inside an indexed
+ * `state<FactStore>` (optionally sharded), and cascade is implemented as
+ * bounded recursive message emission. Termination rests on a per-root
+ * semantic contract — a fact only drives the cascade when it transitions to
+ * obsolete (`validTo` set), and each obsolete root emits its cascade exactly
+ * once across all waves — plus an empty-array fixpoint short-circuit. The
+ * cascade is modeled as DATA arrays (NOT INVALIDATE messages), so spec §1.4's
+ * idempotent-within-a-wave INVALIDATE guarantee does NOT govern this loop;
+ * convergence is the per-root contract, not a spec §1.4 diamond-merge.
+ *
+ * Canonical design: `archive/docs/SESSION-DS-14.7-reactive-fact-store.md`
+ * (9Q walk complete; Q9-open items 1–9 all resolved).
+ *
+ * Locked decisions baked in here:
+ * - `cascadeMaxIterations` default **8**; overflow emits a per-batch summary
+ *   `{ droppedCount, sample, rootFactId }` to `cascadeOverflow` (Q9-open-4).
+ *   The overflow `sample` is capped at `OVERFLOW_SAMPLE_SIZE` (8),
+ *   independent of `cascadeMaxIterations`.
+ * - `shardBy` default hash-mod **4**; caller override; `dependentsIndex`
+ *   unsharded for v1 (Q9-open-1).
+ * - `MemoryFragment` adds `embedding? / parent_fragment_id? / provenance?`
+ *   (Q9-open-3).
+ * - `dependentsIndex` updates synchronous + atomic with `factStore` commit
+ *   (Q9-open-2).
+ * - Scoring contract `(fragment, storeReadHandle) => number` — read-only
+ *   handle, no mutation exposure (Q9-open-5).
+ * - Consolidator emits to a dedicated `consolidated` topic that the pattern
+ *   default-wires back to `ingest`; caller can intercept (Q9-open-6).
+ * - Query surface = structured `MemoryQuery` via the `query` topic (default);
+ *   function-shaped is caller-side `derived` over `factStore` (Q9-open-7).
+ * - Bi-temporal is pattern-layer only — no DS-14 envelope shape change
+ *   (Q9-open-9); `simpleFactStore()` deferred to v1.1 (Q9-open-8 — NOT built).
+ *
+ * **Cascade cycle visibility.** `cascadeProcessor` stays synchronous (preserves
+ * spec §1.4 batch-dedupe — LLM-driven dependency extraction lives UPSTREAM of
+ * the cascade topic, never inside the recursion). Every cascade message carries
+ * a `causalReason` field and the cycle nodes are tagged `meta.cycle:"cascade"`
+ * so `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` fn-body lookup.
+ *
+ * @module
+ */
+
+/** Stable identity for a stored fact. */
+type FactId = string;
+/** Shard partition key (string | number — any hashable scalar). */
+type ShardKey = string | number;
+/**
+ * A single stored memory fact. Pattern convention only — NOT a spec primitive
+ * and NOT a DS-14 envelope field (bi-temporal stays pattern-layer per
+ * Q9-open-9). Each field is a reactive lever (see design PART 2.3):
+ * `validTo` set → cascade fires; `confidence < θ` → review; `sources` →
+ * `dependentsIndex` edges feeding cascade.
+ */
+interface MemoryFragment<T> {
+    readonly id: FactId;
+    readonly payload: T;
+    /** Transaction time (when learned). `bigint` ns (e.g. `BigInt(monotonicNs())`). */
+    readonly t_ns: bigint;
+    /** Valid-time start. `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Valid-time end. Setting this is the MEME L3 obsolescence lever. */
+    readonly validTo?: bigint;
+    /** Confidence 0..1. Dropping below the review threshold emits a review. */
+    readonly confidence: number;
+    readonly tags: readonly string[];
+    /** Dependency edges — fact IDs this fact is derived from / depends on. */
+    readonly sources: readonly FactId[];
+    /** Optional dense embedding (recipes use it for retrieval). */
+    readonly embedding?: readonly number[];
+    /** Version-chain pointer — consolidator emits successor fragments. */
+    readonly parent_fragment_id?: FactId;
+    /** Free-form provenance string for audit. */
+    readonly provenance?: string;
+}
+/**
+ * Columnar in-memory store. Held as DATA inside a `state<FactStore<T>>` node
+ * (one per shard). `byId` is the authoritative map; the typed companions are
+ * kept for the recipe layer (`bitemporal-query`, `influence-analysis`) — v1
+ * stores fragments directly and lazily projects columns on demand.
+ */
+interface FactStore<T> {
+    readonly byId: ReadonlyMap<FactId, MemoryFragment<T>>;
+}
+/** Reverse dependency index: fact → IDs that depend on it. Unsharded (v1). */
+type DependentsIndex = ReadonlyMap<FactId, readonly FactId[]>;
+/** Read-only projection passed to scoring policies (no mutation surface). */
+interface StoreReadHandle<T> {
+    get(id: FactId): MemoryFragment<T> | undefined;
+    has(id: FactId): boolean;
+    readonly size: number;
+    values(): IterableIterator<MemoryFragment<T>>;
+}
+type ScoringPolicy<T> = (fragment: MemoryFragment<T>, store: StoreReadHandle<T>) => number;
+type DecayPolicy = (confidence: number, ageNs: bigint) => number;
+type AdmissionFilter<T> = (fragment: MemoryFragment<T>) => boolean;
+/** Outcome / RL signal — write-back lever for continual learning. */
+interface OutcomeSignal {
+    readonly factId: FactId;
+    readonly reward: number;
+}
+/** Structured query (Q9-open-7 default surface). Serializable + inspectable. */
+interface MemoryQuery {
+    /** Match any of these tags (OR). Omit for no tag filter. */
+    readonly tags?: readonly string[];
+    /** Bi-temporal "as of" — only facts valid at this instant. */
+    readonly asOf?: bigint;
+    /** Minimum confidence (inclusive). */
+    readonly minConfidence?: number;
+    /** Cap results (sorted by confidence desc, then t_ns desc). */
+    readonly limit?: number;
+}
+interface MemoryAnswer<T> {
+    readonly query: MemoryQuery;
+    readonly results: readonly MemoryFragment<T>[];
+}
+type CascadeReason = "cascade" | "obsolete" | "manual";
+/** A single cascade invalidation message flowing through the cascade cycle. */
+interface CascadeEvent {
+    readonly factId: FactId;
+    readonly rootFactId: FactId;
+    readonly reason: CascadeReason;
+    /** Cascade recursion depth (1 = first wave). Bounded by `cascadeMaxIterations`. */
+    readonly iteration: number;
+    /**
+     * Human-readable causal chain — makes the `dependentsIndex` fn-body lookup
+     * visible in `explain()` output even though it is not a topology edge
+     * (design Q3 / COMPOSITION-GUIDE §24 mitigation).
+     */
+    readonly causalReason: string;
+}
+/** Per-batch overflow summary (Q9-open-4 — never per-message). */
+interface CascadeOverflow {
+    readonly droppedCount: number;
+    readonly sample: readonly FactId[];
+    readonly rootFactId: FactId;
+}
+interface ReviewRequest {
+    readonly factId: FactId;
+    readonly confidence: number;
+    readonly threshold: number;
+}
+interface FactStoreAuditRecord extends BaseAuditRecord {
+    readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "overflow";
+    readonly id?: FactId;
+    readonly reason?: CascadeReason;
+}
+interface ReactiveFactStoreConfig<T> {
+    readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
+    /** Shard partition fn. Default: FNV-1a hash of `id` mod `shardCount`. */
+    readonly shardBy?: (f: MemoryFragment<T>) => ShardKey;
+    /** Shard count for the default hash-mod sharder. Default 4 (§3.2). */
+    readonly shardCount?: number;
+    readonly scoring?: Node<ScoringPolicy<T>>;
+    readonly decay?: Node<DecayPolicy>;
+    readonly admissionFilter?: Node<AdmissionFilter<T>>;
+    readonly ingest: Node<MemoryFragment<T>>;
+    readonly outcome?: Node<OutcomeSignal>;
+    readonly query?: Node<MemoryQuery>;
+    /**
+     * Consolidator trigger — a reactive timer/cron Node (e.g. `fromCron(...)`).
+     * When supplied, the `consolidated` node maps each tick to summarized
+     * fragments emitted on the `consolidated` topic and default-wired back to
+     * the internal ingest path.
+     */
+    readonly consolidateTrigger?: Node<unknown>;
+    /**
+     * Consolidation summarizer. Reads a store snapshot, returns successor
+     * fragments (typically with `parent_fragment_id` set). Default: no-op
+     * (emits nothing) so the cron tick is observable without forcing a policy.
+     */
+    readonly consolidate?: (store: StoreReadHandle<T>) => readonly MemoryFragment<T>[];
+    /** Cascade recursion cap (§3.1). Default 8. */
+    readonly cascadeMaxIterations?: number;
+    /** Confidence below which a {@link ReviewRequest} is emitted. Default 0.3. */
+    readonly reviewThreshold?: number;
+}
+interface ReactiveFactStoreGraph<T> extends Graph {
+    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+    readonly shards: readonly Node<FactStore<T>>[];
+    /** Unified read view across all shards (derived). */
+    readonly factStore: Node<FactStore<T>>;
+    readonly dependentsIndex: Node<DependentsIndex>;
+    readonly answer: Node<MemoryAnswer<T> | null>;
+    readonly cascade: Node<readonly CascadeEvent[]>;
+    readonly cascadeOverflow: Node<CascadeOverflow | null>;
+    readonly review: Node<ReviewRequest | null>;
+    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
+    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
+    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
+}
+/**
+ * Build a static-topology reactive fact store (DS-14.7 architecture C).
+ *
+ * Topology (~12 fixed nodes — never grows with fact count):
+ *  - `shards[0..N]` — `state<FactStore<T>>` columnar stores (default 4 shards).
+ *  - `factStore` — derived union read view across shards.
+ *  - `dependentsIndex` — `state<DependentsIndex>` reverse-dep map, unsharded,
+ *    updated synchronously + atomically with each commit (Q9-open-2).
+ *  - `extractOp` — derived: ingest → admission-filtered fragment + dep edges.
+ *  - `invalidationDetector` — derived: scans committed store for `validTo`-set
+ *    / low-confidence facts, resolves dependents via `dependentsIndex`, emits
+ *    cascade messages.
+ *  - `cascade` — topic node carrying `CascadeEvent[]`.
+ *  - `cascadeProcessor` — derived, **synchronous**, `meta.cycle:"cascade"`:
+ *    dedupes by factId, writes invalidations back to shards, recurses until
+ *    fixpoint OR `cascadeMaxIterations` → `cascadeOverflow`.
+ *  - `cascadeOverflow` — per-batch overflow summary node.
+ *  - `queryOp` / `answer` — structured `MemoryQuery` → results (SENTINEL-safe).
+ *  - `outcomeProcessor` — outcome signal → confidence write-back.
+ *  - `consolidated` — cron-tick → summarized fragments on the
+ *    `consolidated` topic,
+ *    default-wired back into the ingest path.
+ *  - `review` — low-confidence proactive-verification requests.
+ *
+ * The cascade cycle (`invalidationDetector → cascade → cascadeProcessor →
+ * shards → invalidationDetector`) is a real, bounded reactive cycle. Both
+ * `invalidationDetector` and `cascadeProcessor` are tagged
+ * `meta.cycle:"cascade"` and every cascade message carries `causalReason`, so
+ * `describe()` / `explain()` surface the otherwise-invisible
+ * `dependentsIndex` lookup (COMPOSITION-GUIDE §24).
+ *
+ * @category memory
+ */
+declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
@@ -25,7 +260,7 @@ import { G as Graph } from './graph-CWvEUQAq.cjs';
  * `firstValueFrom(node)`.
  *
  * **Audit logs.** Every imperative mutation (`upsert / remove / clear / link /
- * unlink / rescore / reindex`) is wrapped via {@link lightMutation} and appends a
+ * unlink / rescore / reindex`) is wrapped via {@link mutate} and appends a
  * typed record to a public `events` log on the bundle / graph.
  *
  * @module
@@ -49,8 +284,7 @@ import { G as Graph } from './graph-CWvEUQAq.cjs';
  * @category memory
  */
 declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
-/** Public alias for the `Node | value` shape accepted by reactive read factories. */
-type NodeOrValue<T> = T | Node<T>;
+
 type CollectionEntry<T> = {
     readonly id: string;
     readonly value: T;
@@ -345,30 +579,4 @@ type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
  */
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
 
-type index_CollectionAuditRecord = CollectionAuditRecord;
-type index_CollectionEntry<T> = CollectionEntry<T>;
-type index_CollectionGraph<T> = CollectionGraph<T>;
-type index_CollectionOptions<T> = CollectionOptions<T>;
-type index_CollectionScoreFn<T> = CollectionScoreFn<T>;
-type index_HnswAdapter<TMeta> = HnswAdapter<TMeta>;
-type index_KnowledgeEdge<TRelation extends string = string> = KnowledgeEdge<TRelation>;
-type index_KnowledgeGraph<TEntity, TRelation extends string = string> = KnowledgeGraph<TEntity, TRelation>;
-type index_KnowledgeGraphAuditRecord = KnowledgeGraphAuditRecord;
-type index_KnowledgeGraphOptions = KnowledgeGraphOptions;
-type index_NodeOrValue<T> = NodeOrValue<T>;
-type index_RankedCollectionEntry<T> = RankedCollectionEntry<T>;
-type index_VectorBackend = VectorBackend;
-type index_VectorIndexAuditRecord = VectorIndexAuditRecord;
-type index_VectorIndexGraph<TMeta> = VectorIndexGraph<TMeta>;
-type index_VectorIndexOptions<TMeta> = VectorIndexOptions<TMeta>;
-type index_VectorRecord<TMeta> = VectorRecord<TMeta>;
-type index_VectorSearchResult<TMeta> = VectorSearchResult<TMeta>;
-declare const index_collection: typeof collection;
-declare const index_cosineSimilarity: typeof cosineSimilarity;
-declare const index_knowledgeGraph: typeof knowledgeGraph;
-declare const index_vectorIndex: typeof vectorIndex;
-declare namespace index {
-  export { type index_CollectionAuditRecord as CollectionAuditRecord, type index_CollectionEntry as CollectionEntry, type index_CollectionGraph as CollectionGraph, type index_CollectionOptions as CollectionOptions, type index_CollectionScoreFn as CollectionScoreFn, type index_HnswAdapter as HnswAdapter, type index_KnowledgeEdge as KnowledgeEdge, type index_KnowledgeGraph as KnowledgeGraph, type index_KnowledgeGraphAuditRecord as KnowledgeGraphAuditRecord, type index_KnowledgeGraphOptions as KnowledgeGraphOptions, type index_NodeOrValue as NodeOrValue, type index_RankedCollectionEntry as RankedCollectionEntry, type index_VectorBackend as VectorBackend, type index_VectorIndexAuditRecord as VectorIndexAuditRecord, type index_VectorIndexGraph as VectorIndexGraph, type index_VectorIndexOptions as VectorIndexOptions, type index_VectorRecord as VectorRecord, type index_VectorSearchResult as VectorSearchResult, index_collection as collection, index_cosineSimilarity as cosineSimilarity, index_knowledgeGraph as knowledgeGraph, index_vectorIndex as vectorIndex };
-}
-
-export { type CollectionGraph as C, type HnswAdapter as H, type KnowledgeGraph as K, type NodeOrValue as N, type RankedCollectionEntry as R, type VectorSearchResult as V, type VectorIndexGraph as a, type CollectionAuditRecord as b, type CollectionEntry as c, type CollectionOptions as d, type CollectionScoreFn as e, type KnowledgeEdge as f, type KnowledgeGraphAuditRecord as g, type KnowledgeGraphOptions as h, index as i, type VectorBackend as j, type VectorIndexAuditRecord as k, type VectorIndexOptions as l, type VectorRecord as m, collection as n, cosineSimilarity as o, knowledgeGraph as p, vectorIndex as v };
+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 };

package/dist/utils/memory/index.js

@@ -0,0 +1,19 @@
+import {
+  collection,
+  cosineSimilarity,
+  knowledgeGraph,
+  reactiveFactStore,
+  vectorIndex
+} from "../../chunk-FR6RGA3B.js";
+import "../../chunk-QMBYUVRL.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  collection,
+  cosineSimilarity,
+  knowledgeGraph,
+  reactiveFactStore,
+  vectorIndex
+};
+//# sourceMappingURL=index.js.map

package/dist/utils/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}