@graphrefly/graphrefly 0.47.1 → 0.48.0

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

@@ -170,9 +170,19 @@ interface ReviewRequest {
     readonly threshold: number;
 }
 interface FactStoreAuditRecord extends BaseAuditRecord {
-    readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "overflow";
+    readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "decay" | "overflow";
     readonly id?: FactId;
     readonly reason?: CascadeReason;
+    /**
+     * Number of facts whose state actually changed in a batch action
+     * (post-filter — excludes no-op / non-finite / resurrection-guard
+     * skips; equals the length of the emitted `decay_processor` value
+     * array). Populated for `"decay"` (a per-tick batch over many facts
+     * with no single `id` — the bare `{action,t_ns,seq}` record was opaque
+     * to audit-log forensics). Absent for single-fact actions (`id`
+     * carries those).
+     */
+    readonly count?: number;
 }
 interface ReactiveFactStoreConfig<T> {
     readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
@@ -181,11 +191,59 @@ interface ReactiveFactStoreConfig<T> {
     /** Shard count for the default hash-mod sharder. Default 4 (§3.2). */
     readonly shardCount?: number;
     readonly scoring?: Node<ScoringPolicy<T>>;
+    /**
+     * Forgetting-curve policy `(confidence, ageNs) => confidence'` (MEME L1
+     * time-drift / Hassabis forgetting curve, DS-14.7 PART 4.1 face ②). `ageNs`
+     * is the fact's monotonic age (`monotonicNs() - t_ns`, a `bigint`
+     * nanosecond duration — `Number()` it for float math; precision degrades
+     * for ages beyond `Number.MAX_SAFE_INTEGER` ns ≈ 104 days of process
+     * uptime). Reactive: the policy itself can evolve (e.g.
+     * `derived([outcome], …)` for continual learning — spec §1.4
+     * push-on-update).
+     *
+     * **Activation contract.** The decay processor exists only when
+     * {@link decayTrigger} is *configured*. Once it is, **both** a
+     * `decayTrigger` tick **and** a `decay` policy emit drive a full pass
+     * (push-on-update — the `outcomeProcessor`+`scoring` precedent). A policy
+     * Node's *initial* value therefore runs a pass on first resolution: if you
+     * build `decay` via `derived(...)`, expect a store-wide pass when it first
+     * settles. With no `decayTrigger` configured the face is fully inert
+     * (mirrors {@link consolidate}/{@link consolidateTrigger}).
+     *
+     * Each pass applies the current policy to every *live* fact (`validTo`
+     * unset), clamps to `[0, 1]`, and writes back only facts whose confidence
+     * actually changed (a fact obsoleted earlier in the same tick is never
+     * resurrected). A drop below {@link reviewThreshold} surfaces via the
+     * `review` topic; decay never sets `validTo`, so it cannot itself drive the
+     * cascade.
+     *
+     * **Quiescence is the policy's responsibility.** The only no-op guard is
+     * exact-equality (`next === confidence`). A policy with no reachable
+     * fixpoint (e.g. plain geometric `c => c * 0.5`) therefore re-decays and
+     * re-emits **every** live fact on **every** tick forever (silent CPU/GC +
+     * audit-log churn — never an error). Bound it in the policy: clamp to a
+     * floor and return `confidence` unchanged once at/below it (so the
+     * exact-equality guard quiesces the store). The {@link decayExponential}
+     * recipe is the ergonomic alternative that owns its own `fromTimer` +
+     * `floor`/`epsilon` and writes through the `ingest` face (no
+     * `decay`/`decayTrigger` wiring). Use this face when you want the store to
+     * own decay as a reactive, swappable policy and you are providing the floor.
+     */
     readonly decay?: Node<DecayPolicy>;
     readonly admissionFilter?: Node<AdmissionFilter<T>>;
     readonly ingest: Node<MemoryFragment<T>>;
     readonly outcome?: Node<OutcomeSignal>;
     readonly query?: Node<MemoryQuery>;
+    /**
+     * Decay trigger — a reactive timer/cron Node (e.g. `fromTimer(...)` /
+     * `fromCron(...)`). Configuring it creates the decay processor; each tick
+     * then re-applies the current {@link decay} policy to every live fact (a
+     * `decay` policy emit also drives a pass — see {@link decay}'s "Activation
+     * contract"). A tick before any `decay` policy has emitted is a no-op.
+     * Without this field the `decay` face is fully inert (mirrors
+     * {@link consolidateTrigger}/{@link consolidate}).
+     */
+    readonly decayTrigger?: Node<unknown>;
     /**
      * Consolidator trigger — a reactive timer/cron Node (e.g. `fromCron(...)`).
      * When supplied, the `consolidated` node maps each tick to summarized
@@ -258,29 +316,6 @@ interface ReactiveFactStoreConfig<T> {
      */
     readonly recordIngest?: boolean;
 }
-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>;
-    /**
-     * Payload-carrying, replayable log of every committed fragment. Present iff
-     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
-     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
-     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
-     * replayable projection source (see `recordIngest` docs for the recipe).
-     */
-    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
-    /** 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).
  *
@@ -314,6 +349,38 @@ interface ReactiveFactStoreGraph<T> extends Graph {
  *
  * @category memory
  */
+declare class 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>;
+    /**
+     * Payload-carrying, replayable log of every committed fragment. Present iff
+     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
+     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
+     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
+     * replayable projection source (see `recordIngest` docs for the recipe).
+     */
+    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
+    constructor(config: ReactiveFactStoreConfig<T>);
+    /** 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).
+ *
+ * Thin factory over {@link ReactiveFactStoreGraph} — see that class for the
+ * full topology / locked-decision docs and the `instanceof`-narrowable type.
+ *
+ * @category memory
+ */
 declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
 /**
@@ -620,14 +687,15 @@ declare function consolidationRem<T>(opts: ConsolidationRemOptions<T>): Consolid
  * 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.
+ * > **Recipe vs the `decay` face.** `ReactiveFactStoreConfig.decay:
+ * > Node<DecayPolicy>` (DS-14.7 PART 4.1 face ②) **is wired** in the factory —
+ * > pair it with `decayTrigger` and the store owns decay as a reactive,
+ * > swappable policy. This recipe is the **ergonomic alternative**: it owns its
+ * > own `fromTimer` and writes through the already-wired `ingest` face, so the
+ * > caller wires no `decay`/`decayTrigger` and the recipe composes whether or
+ * > not the face is also used. Both deliver the §5.8 "`fromTimer` for periodic
+ * > confidence drift" behavior; pick the face for a caller-controlled policy
+ * > Node, this recipe for a self-contained drop-in forgetting curve.
  *
  * **Convergence (conditional — read this).** Per-id decay is computed against
  * the elapsed time since this fact was last decayed (recipe-owned closure
@@ -905,6 +973,166 @@ interface ShardByTenantConfig<T> {
  */
 declare function shardByTenant<T>(tenantOf: (f: MemoryFragment<T>) => string, opts?: ShardByTenantOptions): ShardByTenantConfig<T>;
 
+/**
+ * `simpleFactStore()` — the 80%-case ergonomic wrapper over
+ * {@link reactiveFactStore} / {@link persistentReactiveFactStore}
+ * (DS-14.7 follow-up #2; design LOCKED 2026-05-17 `/dev-dispatch` Q-walk,
+ * Q1–Q6 + sub-decisions resolved).
+ *
+ * Closes the gap where a consumer wanting durable agent memory had to
+ * hand-compose: an `ingest` source + `extractDependencies` + (optionally) a
+ * `StorageBackend` + decay/consolidation recipes + the
+ * `BigInt(monotonicNs())` fragment boilerplate. `simpleFactStore` owns all
+ * of that and exposes a single ergonomic `remember(id, payload, opts?)`.
+ *
+ * **Q-walk locks (canonical: `docs/optimizations.md` DS-14.7 follow-up #2):**
+ * - **Q1** — `extractDependencies` defaults to `() => []` (flat store;
+ *   cascade inert by default — dependency-tracking is opt-in).
+ * - **Q2** — single factory, **optional `storage`**: present → wraps
+ *   {@link persistentReactiveFactStore} (durable, event-sourced); absent →
+ *   in-memory {@link reactiveFactStore}.
+ * - **Q3** — the wrapper **owns** the internal `ingest` source and exposes
+ *   {@link SimpleFactStoreGraph.remember}. `remember` `.emit`s into the
+ *   owned leaf source — this is the *sanctioned* external push that the
+ *   `reactiveFactStore` ingest contract documents (same shape as the
+ *   `decay`/replay recipes' `.emit`-into-source), **not** a spec-§5.9
+ *   imperative trigger: it feeds DATA into a source node, it does not
+ *   bypass topology for control flow. Reactive reads (`answer` / `review` /
+ *   `events`) stay the canonical observation surface.
+ * - **Q4** — auto-wire **default recipes** with internal `fromTimer`
+ *   cadences (batteries-included; user-blessed 2026-05-17). `decay` is
+ *   generically meaningful (confidence forgetting needs no domain
+ *   knowledge) → **ON by default** with conservative defaults
+ *   ({@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}),
+ *   tunable or `false` to disable. `consolidate` is **domain-bound** —
+ *   {@link consolidationRem} *requires* a `summarize` (there is no generic
+ *   default; an arbitrary `T` cannot be summarized blindly), so it is wired
+ *   **iff** the caller supplies `opts.consolidate`. This consolidation
+ *   asymmetry is dictated by the recipe's own required contract, not an
+ *   autonomous downgrade of the Q4 lock.
+ * - **Q5** — minimal input: `remember(id, payload, { tags? })` auto-fills
+ *   `t_ns = BigInt(monotonicNs())` (per the {@link MemoryFragment.t_ns}
+ *   contract + the clock-return-type rule — `monotonicNs()` is `number`,
+ *   the `BigInt(...)` wrap is load-bearing) and `confidence = 1`.
+ * - **Q6** — **wraps** the existing factories (not a parallel impl).
+ *
+ * Presentation-only (`@graphrefly/graphrefly`, `utils/memory` barrel),
+ * universal tier (`fromTimer` only, no `node:*`/DOM — the optional
+ * `StorageBackend` impl's tier is the *caller's* concern, forwarded
+ * verbatim, exactly as {@link persistentReactiveFactStore} does).
+ *
+ * @module
+ */
+
+/**
+ * Default exponential-decay half-life: **7 days** in nanoseconds. Confidence
+ * halves once per week of fact age — gentle forgetting suitable for the
+ * 80%-case agent memory. Override via `opts.decay.halfLifeNs`.
+ */
+declare const DEFAULT_DECAY_HALF_LIFE_NS = 604800000000000n;
+/**
+ * Default decay tick cadence: **1 hour** (ms). How often the forgetting pass
+ * runs. Override via `opts.decay.periodMs`.
+ */
+declare const DEFAULT_DECAY_PERIOD_MS = 3600000;
+/** Per-fact override fields accepted by {@link SimpleFactStoreGraph.remember}. */
+interface RememberOptions {
+    /** Tags. Default `[]`. */
+    readonly tags?: readonly string[];
+    /** Dependency edges (fact IDs this fact derives from). Default `[]`. */
+    readonly sources?: readonly FactId[];
+    /** Confidence 0..1. Default `1`. */
+    readonly confidence?: number;
+    /** Valid-time end — set to obsolete a fact (MEME L3 lever). */
+    readonly validTo?: bigint;
+    /** Valid-time start — `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Free-form provenance string. */
+    readonly provenance?: string;
+}
+interface SimpleFactStoreOptions<T> {
+    /**
+     * Durable backing. Present → delegates to
+     * {@link persistentReactiveFactStore} (event-sourced, replay-on-start,
+     * substrate-owned cursor). Absent → in-memory {@link reactiveFactStore}.
+     * The backend's runtime tier (node / browser) is the caller's concern —
+     * forwarded verbatim.
+     */
+    readonly storage?: StorageBackend;
+    /**
+     * Cascade dependency extractor. **Default `() => []`** — flat store, no
+     * cascade. Supply to opt into MEME L2 cascade invalidation.
+     */
+    readonly extractDependencies?: (f: MemoryFragment<T>) => readonly FactId[];
+    /**
+     * Exponential-decay forgetting. **Default: ON** with
+     * {@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}.
+     * Pass a partial to tune; pass `false` to disable. Wires an internal
+     * `fromTimer` (the user-blessed batteries-included cadence).
+     */
+    readonly decay?: false | Partial<DecayExponentialOptions>;
+    /**
+     * REM-replay consolidation. **Domain-bound** — requires a `summarize`
+     * (no generic default exists). Supply the full
+     * {@link ConsolidationRemOptions} to enable; omit to disable. Wires an
+     * internal `fromTimer` at `consolidate.periodMs`.
+     */
+    readonly consolidate?: ConsolidationRemOptions<T>;
+    /** Persistent-only: durable bucket name. Default `fact_store_ingest`. */
+    readonly persistName?: string;
+    /** Persistent-only: durable codec. Default `bigintJsonCodecFor`. */
+    readonly codec?: Codec<readonly MemoryFragment<T>[]>;
+}
+/**
+ * The ergonomic write added to every `simpleFactStore` graph. Normalizes to a
+ * {@link MemoryFragment} (auto `t_ns = BigInt(monotonicNs())`,
+ * `confidence = 1`, `tags`/`sources` = `[]`) and `.emit`s it into the owned
+ * `ingest` source. Re-`remember`ing an existing `id` is the MEME L1
+ * direct-replace lever; set `opts.validTo` to obsolete (MEME L3).
+ */
+type SimpleFactStoreRemember<T> = (id: FactId, payload: T, opts?: RememberOptions) => void;
+/**
+ * In-memory `simpleFactStore` graph (no `storage`) augmented with
+ * {@link SimpleFactStoreRemember}.
+ */
+interface SimpleFactStoreGraph<T> extends ReactiveFactStoreGraph<T> {
+    remember: SimpleFactStoreRemember<T>;
+}
+/**
+ * Durable (`storage`-backed) `simpleFactStore` graph — the **type-honest**
+ * persistent surface. EC-LOW-1 (`/qa` 2026-05-17): the `storage` overload
+ * returns this so `position` / `replayedCount` / `flush` / `tier` are typed
+ * without a hand-cast (the durable path is the headline 80%-case).
+ */
+type PersistentSimpleFactStoreGraph<T> = PersistentReactiveFactStoreGraph<T> & {
+    remember: SimpleFactStoreRemember<T>;
+};
+/**
+ * Build a fact store with sensible defaults and a one-call `remember`.
+ *
+ * @example
+ * ```ts
+ * import { simpleFactStore } from "@graphrefly/graphrefly/utils/memory";
+ * import { memoryBackend } from "@graphrefly/graphrefly/extra";
+ *
+ * const mem = simpleFactStore<string>(); // in-memory, decay ON
+ * mem.remember("user:lang", "TypeScript", { tags: ["pref"] });
+ * mem.answer.subscribe((a) => console.log(a)); // reactive read
+ *
+ * // Durable: the `storage` overload returns the typed persistent surface
+ * // (no hand-cast needed for `position` / `flush`).
+ * const durable = simpleFactStore<string>({ storage: memoryBackend() });
+ * durable.remember("k", "v");
+ * await durable.flush();
+ * ```
+ *
+ * @category memory
+ */
+declare function simpleFactStore<T>(opts: SimpleFactStoreOptions<T> & {
+    storage: StorageBackend;
+}): PersistentSimpleFactStoreGraph<T>;
+declare function simpleFactStore<T>(opts?: SimpleFactStoreOptions<T>): SimpleFactStoreGraph<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).
@@ -1246,4 +1474,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 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 };
+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, DEFAULT_DECAY_HALF_LIFE_NS, DEFAULT_DECAY_PERIOD_MS, 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, ReactiveFactStoreGraph, type RememberOptions, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type SimpleFactStoreGraph, type SimpleFactStoreOptions, 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, simpleFactStore, vectorIndex };

package/dist/utils/memory/index.js

@@ -1,4 +1,7 @@
 import {
+  DEFAULT_DECAY_HALF_LIFE_NS,
+  DEFAULT_DECAY_PERIOD_MS,
+  ReactiveFactStoreGraph,
   admissionLlmJudge,
   bitemporalQuery,
   collection,
@@ -12,13 +15,17 @@ import {
   reactiveFactStore,
   scoringByOutcome,
   shardByTenant,
+  simpleFactStore,
   vectorIndex
-} from "../../chunk-U225SKB4.js";
+} from "../../chunk-K4ZYJ4EM.js";
 import "../../chunk-QMBYUVRL.js";
 import "../../chunk-FMPF42Q4.js";
-import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-C5QD5DQX.js";
 import "../../chunk-AZDQPQ3V.js";
 export {
+  DEFAULT_DECAY_HALF_LIFE_NS,
+  DEFAULT_DECAY_PERIOD_MS,
+  ReactiveFactStoreGraph,
   admissionLlmJudge,
   bitemporalQuery,
   collection,
@@ -32,6 +39,7 @@ export {
   reactiveFactStore,
   scoringByOutcome,
   shardByTenant,
+  simpleFactStore,
   vectorIndex
 };
 //# sourceMappingURL=index.js.map