@tangleai/context 0.21.1

package/src/archive.d.ts

@@ -0,0 +1,47 @@
+/** Exact bytes of the archive sub-map, including durable loss metadata. */
+export function archiveFootprint(records: any): {
+    items: number;
+    bytes: number;
+};
+/** Plan deterministic oldest-unreferenced eviction, or refuse without mutation. */
+export function retainArchives(current: any, added: any, limits: any, options?: {}): {
+    error: string;
+    code: string;
+    retention?: undefined;
+    next?: undefined;
+    report?: undefined;
+    footprint?: undefined;
+} | {
+    error: string;
+    code: string;
+    retention: {
+        refused: boolean;
+        limits: any;
+        current: {
+            items: number;
+            bytes: number;
+        };
+        attempted: {
+            items: number;
+            bytes: number;
+        };
+    };
+    next?: undefined;
+    report?: undefined;
+    footprint?: undefined;
+} | {
+    next: any;
+    report: {
+        version: number;
+        policy: string;
+        evicted: any[];
+        written: any;
+    };
+    footprint: {
+        items: number;
+        bytes: number;
+    };
+    error?: undefined;
+    code?: undefined;
+    retention?: undefined;
+};

package/src/archive.js

@@ -0,0 +1,53 @@
+//@ts-check
+import { jsonBytes } from './retention.js';
+const SLOT = 'ai/state/slot/', CONTENT = 'ai/state/slot-content/';
+const EVICTED = 'ai/state/evicted/', REPORT = 'ai/state/retention/archive';
+const archived = (value) => value?.kind === 'agent-round' || value?.kind === 'agent-round-index';
+
+/** Exact bytes of the archive sub-map, including durable loss metadata. */
+export function archiveFootprint(records) {
+  const names = Object.keys(records).filter((key) => key.startsWith(SLOT) && archived(records[key]));
+  const keys = new Set(names.flatMap((key) => [key, `${CONTENT}${records[key].name}`]));
+  for (const key of Object.keys(records)) if (key.startsWith(EVICTED) || key === REPORT) keys.add(key);
+  return { items: names.length, bytes: jsonBytes(Object.fromEntries([...keys].sort().map((key) => [key, records[key]]))) };
+}
+
+/** Plan deterministic oldest-unreferenced eviction, or refuse without mutation. */
+export function retainArchives(current, added, limits, options = {}) {
+  const next = structuredClone(current);
+  const protectedNames = new Set([...(options.protectedNames ?? []), ...added.map((entry) => entry.slot.name)]);
+  const references = JSON.stringify(Object.entries(current).filter(([key]) =>
+    key.startsWith('ai/state/memory/') || key.startsWith('ai/state/goal/')))
+    + (options.referenceText ?? '');
+  for (const { slot, text } of added) {
+    if (options.immutable === true && Object.hasOwn(next, `${CONTENT}${slot.name}`)
+      && next[`${CONTENT}${slot.name}`] !== text)
+      return { error: `archive address collision at '${slot.name}'`, code: 'ARCHIVE_COLLISION' };
+    next[`${SLOT}${slot.name}`] = slot;
+    next[`${CONTENT}${slot.name}`] = text;
+    delete next[`${EVICTED}${slot.name}`];
+  }
+  const evicted = [];
+  const report = { version: 1, policy: 'oldest-unreferenced', evicted,
+    written: added.map((entry) => entry.slot.name) };
+  next[REPORT] = report;
+  const candidates = Object.entries(next).filter(([key, slot]) => key.startsWith(SLOT) && archived(slot)
+    && !slot.pinned && !protectedNames.has(slot.name) && !references.includes(slot.name))
+    .sort(([, a], [, b]) => a.at < b.at ? -1 : a.at > b.at ? 1 : a.name < b.name ? -1 : 1);
+  const fits = () => {
+    const footprint = archiveFootprint(next);
+    return footprint.items <= (limits.maxItems ?? Infinity) && footprint.bytes <= (limits.maxBytes ?? Infinity);
+  };
+  for (const [, slot] of candidates) {
+    if (fits()) break;
+    const keys = [`${SLOT}${slot.name}`, `${CONTENT}${slot.name}`];
+    const bytes = jsonBytes(Object.fromEntries(keys.map((key) => [key, next[key]])));
+    const tombstone = { version: 1, name: slot.name, status: 'evicted', bytes, reason: 'archive-budget' };
+    for (const key of keys) delete next[key];
+    next[`${EVICTED}${slot.name}`] = tombstone;
+    evicted.push(tombstone);
+  }
+  if (!fits()) return { error: 'archive budget cannot preserve protected addresses and loss metadata',
+    code: 'ARCHIVE_BUDGET', retention: { refused: true, limits, current: archiveFootprint(current), attempted: archiveFootprint(next) } };
+  return { next, report, footprint: archiveFootprint(next) };
+}

package/src/environment.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The address of one chunk: parent, strategy, size, index. Derived, so
+ * the same split always names the same slots — that is what makes
+ * re-chunking idempotent rather than duplicating, and it is why nothing
+ * here keeps a mapping from a parent to its pieces.
+ * @param {string} parent
+ * @param {string} strategy
+ * @param {number} size
+ * @param {number} index
+ * @returns {string}
+ */
+export function chunkSlotName(parent: string, strategy: string, size: number, index: number): string;
+/** The prefix every chunk of one split shares — a family, addressable as one. */
+export function chunkFamily(parent: any, strategy: any, size: any): string;
+/**
+ * Create an environment over a slot store.
+ *
+ * @param {{ ledger?: any,
+ *   storage?: { get: (key: string) => Promise<any>,
+ *     set: (key: string, value: any) => Promise<void>,
+ *     delete: (key: string) => Promise<void>,
+ *     keys: (prefix?: string) => Promise<string[]> },
+ *   compileQuery?: (document: any) => (data: any) => any,
+ *   excerptChars?: number, digestSlots?: number, matchLimit?: number,
+ *   chunkSize?: number, now?: () => string }} [options]
+ *   - `ledger` shares an existing ledger — the normal case, because the
+ *     agent's archived rounds and the corpus then live in one store and
+ *     one `recall` reaches both. Given `storage` instead, a ledger is
+ *     built over it; given neither, everything runs in memory.
+ *   - `compileQuery` is the `select` seam (`compileJsonQuery` from
+ *     `@jarenjs/json/query`). Absent, `select` declines with a stated
+ *     reason and every other operation is unaffected.
+ * @returns {any}
+ */
+export function createEnvironment(options?: {
+    ledger?: any;
+    storage?: {
+        get: (key: string) => Promise<any>;
+        set: (key: string, value: any) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        keys: (prefix?: string) => Promise<string[]>;
+    };
+    compileQuery?: (document: any) => (data: any) => any;
+    excerptChars?: number;
+    digestSlots?: number;
+    matchLimit?: number;
+    chunkSize?: number;
+    now?: () => string;
+}): any;
+/**
+ * The environment as a toolbox definition list: the five operations plus
+ * `read`, ready for `createToolbox().add(...)`.
+ *
+ * They are defined here rather than in the agent for the reason `recall`
+ * is: a tool a model calls and an operation a harness calls have to be
+ * the same thing, or the tested path and the shipped path drift.
+ *
+ * Every schema is deliberately small — one required string, optional
+ * numbers — because the tier this package targets gets a tool call right
+ * in proportion to how few decisions it has to make.
+ * @param {any} environment - from {@link createEnvironment}
+ * @returns {any[]} tool definitions
+ */
+export function environmentTools(environment: any): any[];
+/** The kind a chunk slot is written under, so a digest can group them. */
+export const CHUNK_KIND: "chunk";