@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/guarded-execution-C-3hnP6A.d.cts

@@ -0,0 +1,207 @@
+import { Node, Actor, PolicyRuleData } from '@graphrefly/pure-ts/core';
+import { Graph, GraphDescribeOutput, GraphOptions, GraphDescribeOptions } from '@graphrefly/pure-ts/graph';
+import { P as PolicyGateGraph, e as PolicyViolation } from './audit-C_bPfkqS.cjs';
+import { TopicGraph } from './utils/messaging/index.cjs';
+
+/**
+ * Composable safety layer (roadmap §9.0b — Tier 5.1 Wave-B rebuild).
+ *
+ * {@link guardedExecution} wraps any {@link Graph} with:
+ *
+ * - {@link policyGate} — reactive ABAC (Tier 2.3 rename of `policyEnforcer`),
+ *   policies stored as a `Node` so LLMs / humans can update them at runtime.
+ *   Full transitive dynamic coverage via `watchTopologyTree`.
+ * - Reactive {@link GuardedExecutionGraph.scopedDescribeNode} — a thin
+ *   delegate over `target.describe({ reactive: true, actor })` that re-derives
+ *   on every settle (topology change, error transition, actor swap).
+ * - The enforcer's `violations` topic is republished as `violations` on
+ *   the wrapper, composable with {@link graphLens}'s `health`.
+ * - The wrapper-level `lints` topic surfaces non-policy diagnostic warnings
+ *   (`empty-policies` / `audit-no-effect` / `no-actor`) so misconfigurations
+ *   are caught reactively rather than via thrown errors at scattered call sites.
+ * - The `scope` derived publishes the current configuration tuple
+ *   (`{actor, mode, policiesCount}`) for dashboards.
+ *
+ * V1 scope: policies + actor + reactive scoped describe + lints + scope.
+ * Budget-as-option is NOT in V1 — it requires a cost-tracking design that
+ * hasn't landed yet. Callers who need a budget limit today append a
+ * budget-aware {@link PolicyRuleData} to the policies list (check current
+ * cost and `deny` when exhausted).
+ *
+ * @module
+ */
+
+/** Diagnostic warning published on {@link GuardedExecutionGraph.lints}. */
+interface GuardedExecutionLint {
+    /**
+     * - `"empty-policies"` — `policies` Node emitted an empty array in
+     *   `mode: "enforce"`. Static empty arrays throw at construction; this
+     *   covers the reactive case.
+     * - `"audit-no-effect"` — `mode: "audit"` plus the target has no per-node
+     *   guards, so `scopedDescribeNode` filters by per-node guards only and
+     *   policies will never gate visibility (they still populate `violations`
+     *   on writes).
+     * - `"no-actor"` — neither a wrapper-configured nor per-call actor was
+     *   supplied. `scopedDescribeNode` falls back to "describe everything"
+     *   for the corresponding subscription.
+     */
+    kind: "empty-policies" | "audit-no-effect" | "no-actor";
+    message: string;
+    timestamp_ns: number;
+}
+/** Configuration tuple published on {@link GuardedExecutionGraph.scope}. */
+interface GuardedScope {
+    /** The wrapper-configured default actor, or `null` when none configured. */
+    actor: Actor | null;
+    mode: "audit" | "enforce";
+    /** Current policy count (reactive — re-emits on `policies` Node updates). */
+    policiesCount: number;
+}
+/** Options for {@link guardedExecution}. */
+interface GuardedExecutionOptions {
+    /**
+     * Policies enforced against every guarded write. Static list or a live
+     * `Node<readonly PolicyRuleData[]>` (LLM-updatable).
+     *
+     * **Empty-policies handling:**
+     * - Static empty array + `mode: "enforce"` throws `RangeError` at
+     *   construction (deny-by-default is almost certainly a misconfiguration).
+     * - Node-supplied empty array + `mode: "enforce"` emits a one-time
+     *   `"empty-policies"` lint on first such emission (the wrapper can't
+     *   throw mid-run — surface the warning reactively).
+     * - `mode: "audit"` tolerates empty policies (no guards stacked; policies
+     *   only feed the `violations` channel on writes).
+     */
+    policies: readonly PolicyRuleData[] | Node<readonly PolicyRuleData[]>;
+    /**
+     * Default actor used when the caller invokes
+     * {@link GuardedExecutionGraph.scopedDescribeNode} without an override.
+     * Accepts a static {@link Actor} or a `Node<Actor>` — when a Node is
+     * supplied, the reactive describe re-derives on every actor emission so
+     * harnesses binding a per-turn actor get a single live describe Node
+     * instead of re-creating one per turn.
+     *
+     * Omit to scope per-call only. A `"no-actor"` lint fires once per instance
+     * if neither a configured nor per-call actor is ever supplied (the
+     * resulting describe is unscoped — full visibility).
+     */
+    actor?: Actor | Node<Actor>;
+    /**
+     * `"enforce"` (default) — push guards onto target nodes so disallowed
+     * writes throw {@link GuardDenied}.
+     * `"audit"` — record would-be denials to the `violations` topic without
+     * blocking writes.
+     */
+    mode?: "audit" | "enforce";
+    /** Ring-buffer cap for the `violations` topic. Default 1000 (inherited from policyGate). */
+    violationsLimit?: number;
+    /** Ring-buffer cap for the `lints` topic. Default 64 — each lint kind fires at most once per instance. */
+    lintsLimit?: number;
+    /** Wrapper graph name. Default `${target.name}_guarded`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Wrapper over a target {@link Graph} providing reactive ABAC + reactive
+ * scoped describe + diagnostic lints. Mounts a {@link PolicyGateGraph} under
+ * `enforcer`, a {@link TopicGraph} of {@link GuardedExecutionLint} under
+ * `lints`, and a `scope` derived publishing `{actor, mode, policiesCount}`.
+ *
+ * @category patterns
+ */
+declare class GuardedExecutionGraph extends Graph {
+    readonly enforcer: PolicyGateGraph;
+    readonly violations: TopicGraph<PolicyViolation>;
+    readonly lints: TopicGraph<GuardedExecutionLint>;
+    readonly scope: Node<GuardedScope>;
+    /**
+     * Canonical reactive describe scoped to the wrapper's configured `actor`.
+     * Subscribes ONCE at construction; lifecycle owned by the wrapper (disposed
+     * on `wrapper.destroy()`). Use this property for the common case
+     * (long-lived consumer wanting "describe scoped to my actor"); use
+     * {@link scopedDescribeNode} only when a per-call actor override or
+     * different `detail`/`fields` is required.
+     *
+     * Re-derives on every settle of the target graph: structural changes,
+     * status transitions (errors flip nodes into `"errored"`), and actor
+     * emissions (when a `Node<Actor>` is bound, including the SENTINEL bridge
+     * applied internally — see qa G1B).
+     */
+    readonly scopedDescribe: Node<GraphDescribeOutput>;
+    private readonly _target;
+    private readonly _actorNode;
+    private readonly _mode;
+    private readonly _firedLintKinds;
+    constructor(target: Graph, opts: GuardedExecutionOptions);
+    private _fireLint;
+    /**
+     * **Per-call escape hatch.** Prefer {@link scopedDescribe} (the mounted
+     * property) for the common case of "describe scoped to my actor." Use
+     * this method ONLY when you need a per-call actor override or different
+     * `detail`/`fields`/`filter`.
+     *
+     * Returns a live `Node<GraphDescribeOutput>` scoped to the supplied (or
+     * configured) actor, plus an explicit `dispose` for caller-controlled
+     * lifecycle. Re-derives on every settle of the target graph: structural
+     * changes, status transitions, and actor emissions (when a `Node<Actor>`
+     * is bound).
+     *
+     * **Lifecycle (qa G1A — EC1 fix).** Each call instantiates a fresh
+     * `target.describe({reactive: true})` handle (with its own version state,
+     * observe handle, transitive topology subscriptions, derived + keepalive).
+     * The caller MUST invoke the returned `dispose()` when finished to release
+     * these resources. Disposers ARE also tracked on the wrapper graph so
+     * `wrapper.destroy()` cleans up any handles the caller forgot — but a
+     * long-lived wrapper with heavy per-call usage will leak until destroy
+     * unless `dispose()` is called explicitly.
+     *
+     * @param actorOverride - Optional per-call override. Static {@link Actor}
+     *   or `Node<Actor>`. Omit to use the wrapper-configured default.
+     * @param opts - Standard {@link GraphDescribeOptions} fields (`detail`,
+     *   `fields`, `filter`). `actor` / `reactive` / `reactiveName` are
+     *   controlled by the wrapper.
+     * @returns `{node, dispose}` — `node` is the live describe Node; `dispose`
+     *   tears down the underlying reactive describe subscription idempotently.
+     */
+    scopedDescribeNode(actorOverride?: Actor | Node<Actor>, opts?: Omit<GraphDescribeOptions, "actor" | "reactive" | "reactiveName">): {
+        node: Node<GraphDescribeOutput>;
+        dispose: () => void;
+    };
+    /** The wrapped graph (escape hatch for tooling). */
+    get target(): Graph;
+}
+/**
+ * Wrap a {@link Graph} with {@link policyGate} plus a reactive scoped describe
+ * lens. Returns a {@link GuardedExecutionGraph} that can be mounted, diffed,
+ * or composed with {@link graphLens}.
+ *
+ * @param target - The graph to guard.
+ * @param opts - See {@link GuardedExecutionOptions}.
+ *
+ * @example
+ * ```ts
+ * const guarded = guardedExecution(app, {
+ *   actor: node<Actor>([], { initial: { type: "human", id: "alice" } }), // reactive — re-derive on swap
+ *   policies: [
+ *     { effect: "allow", action: "read", actorType: "human" },
+ *     { effect: "deny", action: "write", pathPattern: "system::*" },
+ *   ],
+ *   mode: "enforce",
+ * });
+ *
+ * // Canonical: subscribe to the mounted reactive describe (no per-call leak).
+ * guarded.scopedDescribe.subscribe((msgs) => { /* live describe per actor / topology change *\/ });
+ * // Per-call escape hatch (different actor / detail) — caller manages dispose.
+ * const detailed = guarded.scopedDescribeNode(undefined, { detail: "standard" });
+ * try { detailed.node.subscribe(/* … *\/); } finally { detailed.dispose(); }
+ * guarded.violations.events.subscribe(msgs => console.log("violations:", msgs));
+ * guarded.lints.events.subscribe(msgs => console.warn("lints:", msgs));
+ * guarded.scope.subscribe(msgs => console.log("scope:", msgs));
+ * ```
+ *
+ * @category patterns
+ */
+declare function guardedExecution(target: Graph, opts: GuardedExecutionOptions): GuardedExecutionGraph;
+
+export { GuardedExecutionGraph as G, type GuardedExecutionLint as a, type GuardedExecutionOptions as b, type GuardedScope as c, guardedExecution as g };

package/dist/{index-CBGUK09R.d.ts → index-5SU_O78r.d.cts}

@@ -1,10 +1,10 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-DWjNfLvC.js';
+import { T as ToObservableOptions, t as toObservable } from './observable-BXQoW1P-.cjs';
+import { Graph, GraphPersistSnapshot } from '@graphrefly/pure-ts/graph';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { G as Graph, r as GraphPersistSnapshot } from './graph-D9LFnda9.js';
-import { A as Actor } from './node-kK3CvTrR.js';
-import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-CeFiHtAg.js';
-import { AppendLogStorageTier } from './extra/storage-tiers.js';
+import { Actor } from '@graphrefly/pure-ts/core';
+import { CqrsOptions, CqrsGraph, CqrsEvent } from './utils/cqrs/index.cjs';
+import { AppendLogStorageTier } from '@graphrefly/pure-ts/extra';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
 type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;

package/dist/{index-BmZXHqkE.d.ts → index-B6pxYJzO.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.js';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /** Solid accessor function — returns current value when called. */
 type Accessor<T> = () => T;

package/dist/{index-hcDJ8PSI.d.cts → index-B6pxYJzO.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /** Solid accessor function — returns current value when called. */
 type Accessor<T> = () => T;

package/dist/{index-C5stwKcw.d.cts → index-BFsng6v1.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /**
  * Subscribe to a read-only `Node<T>` as a React value. Re-renders on node value settlement.

package/dist/{index-CdAlHFEt.d.ts → index-BFsng6v1.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.js';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /**
  * Subscribe to a read-only `Node<T>` as a React value. Re-renders on node value settlement.

package/dist/{index-_6ODbuOu.d.cts → index-Bg-LwEt-.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /** Svelte store contract — implements the minimal `subscribe` method. */
 interface SvelteReadable<T> {

package/dist/{index-CviRnE4K.d.ts → index-Bg-LwEt-.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.js';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /** Svelte store contract — implements the minimal `subscribe` method. */
 interface SvelteReadable<T> {

package/dist/{index-CBBLl_rc.d.ts → index-Brp888t0.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.js';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /**
  * A Nanostores-compatible atom.

package/dist/{index-BQSKmbuG.d.cts → index-Brp888t0.d.ts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-kK3CvTrR.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
 
 /**
  * A Nanostores-compatible atom.

package/dist/{index-sqkqlb1p.d.ts → index-CDfk6jHN.d.cts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-D9LFnda9.js';
+import { Graph } from '@graphrefly/pure-ts/graph';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-ZVQhLa2i.d.cts → index-CDfk6jHN.d.ts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-CWvEUQAq.cjs';
+import { Graph } from '@graphrefly/pure-ts/graph';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-Climxqsu.d.cts → index-CEXCtYYJ.d.ts}

@@ -1,10 +1,10 @@
-import { T as ToObservableOptions, t as toObservable } from './observable-e3eiPPFy.cjs';
+import { T as ToObservableOptions, t as toObservable } from './observable-BXQoW1P-.js';
+import { Graph, GraphPersistSnapshot } from '@graphrefly/pure-ts/graph';
 import { OnModuleInit, OnModuleDestroy, ExecutionContext, CanActivate, DynamicModule } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
-import { G as Graph, r as GraphPersistSnapshot } from './graph-CWvEUQAq.cjs';
-import { A as Actor } from './node-kK3CvTrR.cjs';
-import { c as CqrsOptions, b as CqrsGraph, a as CqrsEvent } from './index-B-_tFaqV.cjs';
-import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
+import { Actor } from '@graphrefly/pure-ts/core';
+import { CqrsOptions, CqrsGraph, CqrsEvent } from './utils/cqrs/index.js';
+import { AppendLogStorageTier } from '@graphrefly/pure-ts/extra';
 
 /** Class constructor key for decorator registries and Nest `ModuleRef.get()`. */
 type DecoratorHostConstructor = abstract new (...args: unknown[]) => unknown;

package/dist/index-DLAxYaN5.d.cts

@@ -0,0 +1,169 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * DS-14.6.A U-A — tagged context substrate (Phase 14.5).
+ *
+ * Per-view tagged context (SESSION-DS-14.6-A L3–L6 + SESSION-DS-14.6-A-9Q
+ * implementation walk). Pool stores immutable tier-0 originals on an
+ * **append-only `reactiveLog`** (D-A4 — structural tier-0 immutability, free
+ * `LogChange` mutations, side-steps the DS14R1 TTL/LRU prune-fidelity bug).
+ * Each consumer holds a `ContextView` that materialises its own filtered +
+ * compressed slice (`Node<readonly RenderedEntry[]>`). Routing is mechanical
+ * tag comparison (zero LLM); only `llm-summary` rules cross to an injected
+ * `llmCompress` (D-A3). Compression cache is one shared `(id, tier)` map in
+ * the pool bundle, bounded LRU (D-A5). Schema is pure data, presentation
+ * layer (D-A1) — no `@graphrefly/pure-ts` consumer.
+ *
+ * @module
+ */
+
+type Tag = string;
+/** Compression tier. 0 = original; higher = more compressed. */
+type Tier = 0 | 1 | 2 | 3;
+interface ContextEntry<T> {
+    /** Stable id — cache key component `(id, tier)`. Auto-assigned if omitted. */
+    readonly id: string;
+    readonly payload: T;
+    readonly tags: readonly Tag[];
+    /** 0..1. Budget/GC ordering. */
+    readonly importance: number;
+    readonly compressible: boolean;
+    readonly topic: string;
+    /** Wall-clock at add (ns) — used by `poolGC({ olderThanNs })`. */
+    readonly t_ns: number;
+}
+interface RuleMatch {
+    readonly topic?: string | RegExp;
+    readonly tagsAny?: readonly Tag[];
+    readonly importanceMin?: number;
+    readonly importanceMax?: number;
+    readonly compressible?: boolean;
+}
+type CompressionRule = {
+    readonly match: RuleMatch;
+    readonly action: "evict";
+} | {
+    readonly match: RuleMatch;
+    readonly action: "truncate";
+    readonly maxChars: number;
+} | {
+    readonly match: RuleMatch;
+    readonly action: "reference";
+} | {
+    readonly match: RuleMatch;
+    readonly action: "llm-summary";
+    readonly toTier: Tier;
+};
+interface RenderedEntry<T> {
+    readonly id: string;
+    readonly topic: string;
+    readonly tags: readonly Tag[];
+    readonly tier: Tier;
+    /** Original payload at tier 0; compressed `string` otherwise. */
+    readonly payload: T | string;
+    readonly compressed: boolean;
+}
+interface ContextView<T> {
+    readonly filter: (e: ContextEntry<T>) => boolean;
+    /** 0..1. A rule fires when `pressure > 0` and the entry matches. */
+    readonly pressure: Node<number>;
+    readonly budgetTokens: number;
+    readonly rules: readonly CompressionRule[];
+    /** Default `s => Math.ceil(s.length / 4)`. */
+    readonly tokenizer?: (s: string) => number;
+}
+interface PoolGCPolicy {
+    /** Drop entries with `t_ns < (now - olderThanNs)`. */
+    readonly olderThanNs?: number;
+    /** Drop entries with `importance < importanceBelow`. */
+    readonly importanceBelow?: number;
+    /**
+     * **Scope**, not a match-to-evict rule: when set, GC only considers
+     * entries whose `topic === this`; entries of other topics always survive.
+     * `olderThanNs` / `importanceBelow` are ANDed *within* this scope.
+     */
+    readonly topic?: string;
+    /** Keep at most this many most-recent entries. */
+    readonly max?: number;
+}
+/** `(entry, toTier) => compressedText`. Injected; required iff a view uses `llm-summary`. */
+type LlmCompress<T> = (entry: ContextEntry<T>, toTier: Tier) => string;
+interface TaggedContextPoolOptions<T> {
+    readonly topic: string;
+    /** Forwarded to the backing append-only `reactiveLog` (poolGC ceiling). */
+    readonly maxEntries?: number;
+    /** Required iff any rendered view uses an `llm-summary` rule (D-A3). */
+    readonly llmCompress?: LlmCompress<T>;
+    /** Shared `(id, tier)` compression cache cap (D-A5). Default 512. */
+    readonly cacheMax?: number;
+    readonly name?: string;
+}
+interface TaggedContextPoolBundle<T> {
+    /**
+     * Append an entry (immutable tier-0). Returns its id (auto-assigned
+     * `ctx-N` per-pool if omitted).
+     *
+     * **Caller-supplied ids must be unique within the pool.** The log is
+     * append-only and does NOT dedupe; the compression cache is keyed by
+     * `(id, tier)`, so appending two different entries with the same explicit
+     * `id` makes the second render the first's cached summary (QA P11).
+     */
+    add(entry: Omit<ContextEntry<T>, "id" | "t_ns"> & {
+        id?: string;
+    }): string;
+    /** All live tier-0 entries. */
+    readonly entries: Node<readonly ContextEntry<T>[]>;
+    /** Entries carrying `tag`. */
+    byTag(tag: Tag): Node<readonly ContextEntry<T>[]>;
+    /** Pool-global retention (L6 — distinct from per-view filtering). Returns removed count. */
+    poolGC(policy: PoolGCPolicy): number;
+    readonly graph: Graph;
+    /** Internal — shared compression cache (one per pool, D-A5). */
+    readonly _cache: CompressionCache;
+    readonly _opts: TaggedContextPoolOptions<T>;
+    dispose(): void;
+}
+/**
+ * Bounded LRU cache keyed by `(id, tier)`. Uses a nested `Map<id, Map<tier,
+ * value>>` (NOT a `${id}::${tier}` string key) so a caller-supplied `id`
+ * containing the separator cannot collide (QA P5). LRU is tracked at the
+ * (id,tier) leaf via a flat insertion-order key list.
+ */
+declare class CompressionCache {
+    private readonly _max;
+    private readonly _m;
+    /** Insertion-order list of `id` keys for LRU eviction at the id granularity. */
+    private readonly _order;
+    constructor(_max: number);
+    get(id: string, tier: Tier): string | undefined;
+    set(id: string, tier: Tier, value: string): void;
+}
+/**
+ * Append-only tagged context pool (D-A4). The pool is a `reactiveLog` of
+ * immutable tier-0 entries plus a derived `entries` node; `byTag` derives a
+ * filtered view; `poolGC` is the explicit pool-global retention (L6).
+ */
+declare function taggedContextPool<T>(parent: Graph, opts: TaggedContextPoolOptions<T>): TaggedContextPoolBundle<T>;
+/**
+ * Apply the first matching rule to one entry under `pressure`. Non-LLM
+ * strategies (truncate / evict / reference) are pure data; `llm-summary`
+ * calls the injected `llmCompress`, caching by `(id, toTier)` (D-A5).
+ * Returns `undefined` for evicted / pressure-filtered entries.
+ */
+declare function tierCompress<T>(e: ContextEntry<T>, rules: readonly CompressionRule[], pressure: number, cache: CompressionCache, llmCompress?: LlmCompress<T>): RenderedEntry<T> | undefined;
+/**
+ * Per-consumer reactive rendering (D-A2). Materialises a
+ * `Node<readonly RenderedEntry[]>` over the pool: filter → per-entry rule
+ * application under `pressure` → token-budget trim (lowest-importance first).
+ *
+ * Recomputes the slice per `(entries | pressure)` wave (O(n) — behaviourally
+ * identical to the incremental closure-mirror; incremental is a perf
+ * follow-up, not a correctness gap).
+ *
+ * @throws if any rule is `llm-summary` and the pool has no `llmCompress`
+ *   (D-A3 construction guard).
+ */
+declare function renderContextView<T>(pool: TaggedContextPoolBundle<T>, view: ContextView<T>): Node<readonly RenderedEntry<T>[]>;
+
+export { CompressionCache as C, type LlmCompress as L, type PoolGCPolicy as P, type RenderedEntry as R, type Tag as T, type CompressionRule as a, type ContextEntry as b, type ContextView as c, type RuleMatch as d, type TaggedContextPoolBundle as e, type TaggedContextPoolOptions as f, type Tier as g, tierCompress as h, renderContextView as r, taggedContextPool as t };

package/dist/index-DLAxYaN5.d.ts

@@ -0,0 +1,169 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * DS-14.6.A U-A — tagged context substrate (Phase 14.5).
+ *
+ * Per-view tagged context (SESSION-DS-14.6-A L3–L6 + SESSION-DS-14.6-A-9Q
+ * implementation walk). Pool stores immutable tier-0 originals on an
+ * **append-only `reactiveLog`** (D-A4 — structural tier-0 immutability, free
+ * `LogChange` mutations, side-steps the DS14R1 TTL/LRU prune-fidelity bug).
+ * Each consumer holds a `ContextView` that materialises its own filtered +
+ * compressed slice (`Node<readonly RenderedEntry[]>`). Routing is mechanical
+ * tag comparison (zero LLM); only `llm-summary` rules cross to an injected
+ * `llmCompress` (D-A3). Compression cache is one shared `(id, tier)` map in
+ * the pool bundle, bounded LRU (D-A5). Schema is pure data, presentation
+ * layer (D-A1) — no `@graphrefly/pure-ts` consumer.
+ *
+ * @module
+ */
+
+type Tag = string;
+/** Compression tier. 0 = original; higher = more compressed. */
+type Tier = 0 | 1 | 2 | 3;
+interface ContextEntry<T> {
+    /** Stable id — cache key component `(id, tier)`. Auto-assigned if omitted. */
+    readonly id: string;
+    readonly payload: T;
+    readonly tags: readonly Tag[];
+    /** 0..1. Budget/GC ordering. */
+    readonly importance: number;
+    readonly compressible: boolean;
+    readonly topic: string;
+    /** Wall-clock at add (ns) — used by `poolGC({ olderThanNs })`. */
+    readonly t_ns: number;
+}
+interface RuleMatch {
+    readonly topic?: string | RegExp;
+    readonly tagsAny?: readonly Tag[];
+    readonly importanceMin?: number;
+    readonly importanceMax?: number;
+    readonly compressible?: boolean;
+}
+type CompressionRule = {
+    readonly match: RuleMatch;
+    readonly action: "evict";
+} | {
+    readonly match: RuleMatch;
+    readonly action: "truncate";
+    readonly maxChars: number;
+} | {
+    readonly match: RuleMatch;
+    readonly action: "reference";
+} | {
+    readonly match: RuleMatch;
+    readonly action: "llm-summary";
+    readonly toTier: Tier;
+};
+interface RenderedEntry<T> {
+    readonly id: string;
+    readonly topic: string;
+    readonly tags: readonly Tag[];
+    readonly tier: Tier;
+    /** Original payload at tier 0; compressed `string` otherwise. */
+    readonly payload: T | string;
+    readonly compressed: boolean;
+}
+interface ContextView<T> {
+    readonly filter: (e: ContextEntry<T>) => boolean;
+    /** 0..1. A rule fires when `pressure > 0` and the entry matches. */
+    readonly pressure: Node<number>;
+    readonly budgetTokens: number;
+    readonly rules: readonly CompressionRule[];
+    /** Default `s => Math.ceil(s.length / 4)`. */
+    readonly tokenizer?: (s: string) => number;
+}
+interface PoolGCPolicy {
+    /** Drop entries with `t_ns < (now - olderThanNs)`. */
+    readonly olderThanNs?: number;
+    /** Drop entries with `importance < importanceBelow`. */
+    readonly importanceBelow?: number;
+    /**
+     * **Scope**, not a match-to-evict rule: when set, GC only considers
+     * entries whose `topic === this`; entries of other topics always survive.
+     * `olderThanNs` / `importanceBelow` are ANDed *within* this scope.
+     */
+    readonly topic?: string;
+    /** Keep at most this many most-recent entries. */
+    readonly max?: number;
+}
+/** `(entry, toTier) => compressedText`. Injected; required iff a view uses `llm-summary`. */
+type LlmCompress<T> = (entry: ContextEntry<T>, toTier: Tier) => string;
+interface TaggedContextPoolOptions<T> {
+    readonly topic: string;
+    /** Forwarded to the backing append-only `reactiveLog` (poolGC ceiling). */
+    readonly maxEntries?: number;
+    /** Required iff any rendered view uses an `llm-summary` rule (D-A3). */
+    readonly llmCompress?: LlmCompress<T>;
+    /** Shared `(id, tier)` compression cache cap (D-A5). Default 512. */
+    readonly cacheMax?: number;
+    readonly name?: string;
+}
+interface TaggedContextPoolBundle<T> {
+    /**
+     * Append an entry (immutable tier-0). Returns its id (auto-assigned
+     * `ctx-N` per-pool if omitted).
+     *
+     * **Caller-supplied ids must be unique within the pool.** The log is
+     * append-only and does NOT dedupe; the compression cache is keyed by
+     * `(id, tier)`, so appending two different entries with the same explicit
+     * `id` makes the second render the first's cached summary (QA P11).
+     */
+    add(entry: Omit<ContextEntry<T>, "id" | "t_ns"> & {
+        id?: string;
+    }): string;
+    /** All live tier-0 entries. */
+    readonly entries: Node<readonly ContextEntry<T>[]>;
+    /** Entries carrying `tag`. */
+    byTag(tag: Tag): Node<readonly ContextEntry<T>[]>;
+    /** Pool-global retention (L6 — distinct from per-view filtering). Returns removed count. */
+    poolGC(policy: PoolGCPolicy): number;
+    readonly graph: Graph;
+    /** Internal — shared compression cache (one per pool, D-A5). */
+    readonly _cache: CompressionCache;
+    readonly _opts: TaggedContextPoolOptions<T>;
+    dispose(): void;
+}
+/**
+ * Bounded LRU cache keyed by `(id, tier)`. Uses a nested `Map<id, Map<tier,
+ * value>>` (NOT a `${id}::${tier}` string key) so a caller-supplied `id`
+ * containing the separator cannot collide (QA P5). LRU is tracked at the
+ * (id,tier) leaf via a flat insertion-order key list.
+ */
+declare class CompressionCache {
+    private readonly _max;
+    private readonly _m;
+    /** Insertion-order list of `id` keys for LRU eviction at the id granularity. */
+    private readonly _order;
+    constructor(_max: number);
+    get(id: string, tier: Tier): string | undefined;
+    set(id: string, tier: Tier, value: string): void;
+}
+/**
+ * Append-only tagged context pool (D-A4). The pool is a `reactiveLog` of
+ * immutable tier-0 entries plus a derived `entries` node; `byTag` derives a
+ * filtered view; `poolGC` is the explicit pool-global retention (L6).
+ */
+declare function taggedContextPool<T>(parent: Graph, opts: TaggedContextPoolOptions<T>): TaggedContextPoolBundle<T>;
+/**
+ * Apply the first matching rule to one entry under `pressure`. Non-LLM
+ * strategies (truncate / evict / reference) are pure data; `llm-summary`
+ * calls the injected `llmCompress`, caching by `(id, toTier)` (D-A5).
+ * Returns `undefined` for evicted / pressure-filtered entries.
+ */
+declare function tierCompress<T>(e: ContextEntry<T>, rules: readonly CompressionRule[], pressure: number, cache: CompressionCache, llmCompress?: LlmCompress<T>): RenderedEntry<T> | undefined;
+/**
+ * Per-consumer reactive rendering (D-A2). Materialises a
+ * `Node<readonly RenderedEntry[]>` over the pool: filter → per-entry rule
+ * application under `pressure` → token-budget trim (lowest-importance first).
+ *
+ * Recomputes the slice per `(entries | pressure)` wave (O(n) — behaviourally
+ * identical to the incremental closure-mirror; incremental is a perf
+ * follow-up, not a correctness gap).
+ *
+ * @throws if any rule is `llm-summary` and the pool has no `llmCompress`
+ *   (D-A3 construction guard).
+ */
+declare function renderContextView<T>(pool: TaggedContextPoolBundle<T>, view: ContextView<T>): Node<readonly RenderedEntry<T>[]>;
+
+export { CompressionCache as C, type LlmCompress as L, type PoolGCPolicy as P, type RenderedEntry as R, type Tag as T, type CompressionRule as a, type ContextEntry as b, type ContextView as c, type RuleMatch as d, type TaggedContextPoolBundle as e, type TaggedContextPoolOptions as f, type Tier as g, tierCompress as h, renderContextView as r, taggedContextPool as t };

package/dist/{index-CK29LV56.d.cts → index-DeWbQzMe.d.cts}

@@ -1,5 +1,5 @@
+import { Node } from '@graphrefly/pure-ts/core';
 import { Ref, WatchSource } from 'vue';
-import { N as Node } from './node-kK3CvTrR.cjs';
 
 /**
  * Subscribe to a read-only `Node<T>` as a Vue `Ref<T>`. Auto-unsubscribes on scope disposal.