@graphrefly/graphrefly 0.45.0 → 0.47.0

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-DeWbQzMe.d.cts

@@ -0,0 +1,34 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Ref, WatchSource } from 'vue';
+
+/**
+ * Subscribe to a read-only `Node<T>` as a Vue `Ref<T>`. Auto-unsubscribes on scope disposal.
+ * Subscription lifecycle is tied to Vue scope disposal (not node terminal messages).
+ */
+declare function useSubscribe<T>(node: Node<T>): Readonly<Ref<T | undefined | null>>;
+/**
+ * Bind a writable `Node<T>` as a Vue `Ref<T>`. Reads and writes are bidirectional.
+ * Value sets always dispatch `[[DIRTY], [DATA, value]]`, including `value === undefined`.
+ * Subscription lifecycle is tied to Vue scope disposal (not node terminal messages).
+ */
+declare function useStore<T>(node: Node<T>): Ref<T | undefined | null>;
+/** Maps a key to an object of nodes. Used by `useSubscribeRecord` factory. */
+type NodeFactory<K, R extends Record<string, any>> = (key: K) => {
+    [P in keyof R]: Node<R[P]>;
+};
+/**
+ * Subscribe to a dynamic set of keyed node records. When keys change,
+ * old subscriptions are torn down and new ones created automatically.
+ * Must be called during Vue `setup()`.
+ */
+declare function useSubscribeRecord<K extends string, R extends Record<string, any>>(keys: WatchSource<K[] | undefined>, factory: NodeFactory<K, R>): Readonly<Ref<Record<K, R>>>;
+
+type index_NodeFactory<K, R extends Record<string, any>> = NodeFactory<K, R>;
+declare const index_useStore: typeof useStore;
+declare const index_useSubscribe: typeof useSubscribe;
+declare const index_useSubscribeRecord: typeof useSubscribeRecord;
+declare namespace index {
+  export { type index_NodeFactory as NodeFactory, index_useStore as useStore, index_useSubscribe as useSubscribe, index_useSubscribeRecord as useSubscribeRecord };
+}
+
+export { type NodeFactory as N, useSubscribe as a, useSubscribeRecord as b, index as i, useStore as u };

package/dist/index-DeWbQzMe.d.ts

@@ -0,0 +1,34 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Ref, WatchSource } from 'vue';
+
+/**
+ * Subscribe to a read-only `Node<T>` as a Vue `Ref<T>`. Auto-unsubscribes on scope disposal.
+ * Subscription lifecycle is tied to Vue scope disposal (not node terminal messages).
+ */
+declare function useSubscribe<T>(node: Node<T>): Readonly<Ref<T | undefined | null>>;
+/**
+ * Bind a writable `Node<T>` as a Vue `Ref<T>`. Reads and writes are bidirectional.
+ * Value sets always dispatch `[[DIRTY], [DATA, value]]`, including `value === undefined`.
+ * Subscription lifecycle is tied to Vue scope disposal (not node terminal messages).
+ */
+declare function useStore<T>(node: Node<T>): Ref<T | undefined | null>;
+/** Maps a key to an object of nodes. Used by `useSubscribeRecord` factory. */
+type NodeFactory<K, R extends Record<string, any>> = (key: K) => {
+    [P in keyof R]: Node<R[P]>;
+};
+/**
+ * Subscribe to a dynamic set of keyed node records. When keys change,
+ * old subscriptions are torn down and new ones created automatically.
+ * Must be called during Vue `setup()`.
+ */
+declare function useSubscribeRecord<K extends string, R extends Record<string, any>>(keys: WatchSource<K[] | undefined>, factory: NodeFactory<K, R>): Readonly<Ref<Record<K, R>>>;
+
+type index_NodeFactory<K, R extends Record<string, any>> = NodeFactory<K, R>;
+declare const index_useStore: typeof useStore;
+declare const index_useSubscribe: typeof useSubscribe;
+declare const index_useSubscribeRecord: typeof useSubscribeRecord;
+declare namespace index {
+  export { type index_NodeFactory as NodeFactory, index_useStore as useStore, index_useSubscribe as useSubscribe, index_useSubscribeRecord as useSubscribeRecord };
+}
+
+export { type NodeFactory as N, useSubscribe as a, useSubscribeRecord as b, index as i, useStore as u };