@graphrefly/graphrefly 0.47.1 → 0.47.2

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

@@ -170,7 +170,7 @@ 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;
 }
@@ -181,11 +181,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
@@ -620,14 +668,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

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

@@ -170,7 +170,7 @@ 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;
 }
@@ -181,11 +181,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
@@ -620,14 +668,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

package/dist/utils/memory/index.js

@@ -13,7 +13,7 @@ import {
   scoringByOutcome,
   shardByTenant,
   vectorIndex
-} from "../../chunk-U225SKB4.js";
+} from "../../chunk-7AVQIGF6.js";
 import "../../chunk-QMBYUVRL.js";
 import "../../chunk-FMPF42Q4.js";
 import "../../chunk-BXGZFGZ4.js";

package/dist/utils/orchestration/index.cjs

@@ -379,9 +379,11 @@ function humanInput(opts) {
           });
         }
       });
-      return () => {
-        promptUnsub();
-        respUnsub?.();
+      return {
+        onDeactivation: () => {
+          promptUnsub();
+          respUnsub?.();
+        }
       };
     },
     {