@tangleai/context 0.21.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @tangleai/context
 
+## 0.25.0
+
+### Patch Changes
+
+- @tangleai/models@0.25.0
+
+## 0.24.1
+
+### Patch Changes
+
+- @tangleai/models@0.24.1
+
+## 0.24.0
+
+### Patch Changes
+
+- @tangleai/models@0.24.0
+
+## 0.23.0
+
+### Patch Changes
+
+- @tangleai/models@0.23.0
+
+## 0.22.0
+
+### Patch Changes
+
+- Convert the migrated source, tests, benchmarks and hosts to strict TypeScript,
+  with JavaScript and declarations emitted through one release build. Move the
+  program pen from `@tangleai/jaren/program` and the Jaren integration barrel to
+  `@tangleai/linq/program`, preserving its JSON format and phantom binding types.
+  The new `@tangleai/linq` root exposes the program namespace and shared build error.
+
+  Match the embedder declarations to unknown widths before the first response,
+  retain precise ledger result variants, and enforce the refinement-pressure
+  instrument's stated 60-second deadline through the chat client's abort signal.
+- Updated dependencies
+  - @tangleai/models@0.22.0
+
 ## 0.21.1
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,8 @@
 
 Evidence-backed ledgers, bounded environments, recall, retention and storage contracts.
 
-This package keeps its JS/JSDoc implementation and deterministic tests. Inject
+The implementation and deterministic tests use strict TypeScript. Published
+packages contain ESM JavaScript and declarations emitted from that source. Inject
 fetch, storage and compiler services at the existing seams. The public source
 exports and emitted npm JavaScript share one implementation.
 
@@ -310,7 +311,7 @@ the single exception and it makes the caller state a budget, because a design wh
 is as easy as peeking is a design that ends up back in the transcript.
 
 **The root view does not grow with the corpus.** Sweeping a corpus across three orders of
-magnitude (10 kB → 10 MB, `test/context/environment-scale.test.js`), the root request stays
+magnitude (10 kB → 10 MB, `test/context/environment-scale.test.ts`), the root request stays
 inside a 3 000-character band and moves by *tens* of characters between decades — the extra
 digits in a chunk's index, and nothing else. The digest lists at most twelve slots and
 reports how many it did not list; a cap that hid the difference would let a model conclude
@@ -338,7 +339,7 @@ so the request stops growing with the conversation, and an earlier round is reac
 anything else is: `env_grep` for it, `env_read` at the offset it reports. Over forty
 gathering rounds the request stays under 3 000 characters, and a value that a
 6 000-character `historyBudget` run no longer carries comes back from a 600-character read
-(`test/agents/transcript-slot.test.js`).
+(`test/agents/transcript-slot.test.ts`).
 
 This is the alternative to `historyBudget` rather than a tuning of it: there is no budget to
 exceed when the history is addressed instead of resent. `historyBudget` keeps working
@@ -350,7 +351,7 @@ this existed — and which to reach for is the choice, not a migration.
 
 This injected adapter stores the complete ledger contract in one collection.
 
-```js
+```ts
 import { openStore } from '@jarenjs/db';
 import { nodeDriver } from '@jarenjs/db/node';
 
@@ -361,7 +362,7 @@ import { nodeDriver } from '@jarenjs/db/node';
  * untyped: the ledger stores objects, strings and arrays under the same
  * contract, and only the vector member has to be declared.
  */
-const ledgerModel = (dims) => ({
+const ledgerModel = (dims: any) => ({
   $model: '0.1',
   collections: {
     slots: {
@@ -381,7 +382,7 @@ const ledgerModel = (dims) => ({
 });
 
 /** A collection answer as a list — `execute` returns the bare item for one. */
-const many = (result) => (Array.isArray(result) ? result : result === undefined ? [] : [result]);
+const many = (result: any) => (Array.isArray(result) ? result : result === undefined ? [] : [result]);
 
 /**
  * A durable ledger storage adapter over one `@jarenjs/db` collection:
@@ -395,20 +396,20 @@ const many = (result) => (Array.isArray(result) ? result : result === undefined
  * range scan over the key column. The ledger asks for a handful of
  * distinct prefixes, so the documents are built once each and cached.
  */
-export async function createDbStorage({ path = ':memory:', dims } = {}) {
+export async function createDbStorage({ path = ':memory:', dims }: { path?: string; dims?: number; } = {}) {
   const store = await openStore(ledgerModel(dims), { driver: nodeDriver(), path });
-  const slots = store.collection('slots');
+  const slots = store.collection<{ key: string; value: any; }>('slots');
   const documents = new Map();
 
   /** Every query document one prefix needs, built once. */
-  const forPrefix = (prefix) => {
+  const forPrefix = (prefix: any) => {
     let built = documents.get(prefix);
     if (built !== undefined) return built;
     const under = { '$starts-with': ['$r.key', prefix] };
     const score = { $similarity: ['$r.value.embedding', '$q'] };
     const mine = [{ $eq: ['$r.value.embeddedBy.model', '$model'] },
-      { $eq: ['$r.value.embeddedBy.dims', '$dims'] }];
-    const counted = (where) => ({ $count: { $for: { r: '$[*]' }, $where: where, $return: '$r' } });
+    { $eq: ['$r.value.embeddedBy.dims', '$dims'] }];
+    const counted = (where: any) => ({ $count: { $for: { r: '$[*]' }, $where: where, $return: '$r' } });
     const ranked = {
       $for: { r: '$[*]' },
       $where: { $and: [under, ...mine] },
@@ -416,13 +417,13 @@ export async function createDbStorage({ path = ':memory:', dims } = {}) {
       // ordering only has to agree with its tie-break: score, then
       // newest, then the key
       $orderby: [{ $key: score, $dir: 'desc', $empty: 'least' },
-        { $key: '$r.value.at', $dir: 'desc' }, '$r.key'],
+      { $key: '$r.value.at', $dir: 'desc' }, '$r.key'],
       $return: { key: '$r.key', score },
     };
     built = {
       keys: { $for: { r: '$[*]' }, $where: under, $orderby: ['$r.key'], $return: '$r.key' },
       ranked,
-      window: (limit) => ({ $subsequence: [ranked, 0, limit] }),
+      window: (limit: any) => ({ $subsequence: [ranked, 0, limit] }),
       skipped: counted({ $and: [under, { $not: { $exists: '$r.value.embedding' } }] }),
       held: counted({ $and: [under, { $exists: '$r.value.embedding' }] }),
       ours: counted({ $and: [under, { $exists: '$r.value.embedding' }, ...mine] }),
@@ -433,12 +434,12 @@ export async function createDbStorage({ path = ':memory:', dims } = {}) {
   };
 
   return {
-    mutate: async (prefix, transform) => store.transaction((tx) => {
-      const rows = tx.sync.collection('slots');
+    mutate: async (prefix: any, transform: any) => store.transaction((tx) => {
+      const rows = tx.sync!.collection<{ key: string; value: any; }>('slots');
       const prefixes = typeof prefix === 'string' ? [prefix] : prefix.prefixes ?? [];
-      const keys = [...new Set([...(prefix.keys ?? []), ...prefixes.flatMap((part) => many(rows.execute(forPrefix(part).keys)))])].sort();
-      const matches = (key) => (prefix.keys ?? []).includes(key) || prefixes.some((part) => key.startsWith(part));
-      const current = Object.fromEntries(keys.map((key) => [key, rows.get(key)?.value]));
+      const keys = [...new Set([...(prefix.keys ?? []), ...prefixes.flatMap((part: any) => many(rows.execute(forPrefix(part).keys)))])].sort();
+      const matches = (key: any) => (prefix.keys ?? []).includes(key) || prefixes.some((part: any) => key.startsWith(part));
+      const current = Object.fromEntries(keys.map((key: any) => [key, rows.get(key)?.value]));
       for (const key of Object.keys(current)) if (current[key] === undefined) delete current[key];
       const outcome = transform(current);
       if (!outcome || typeof outcome.then === 'function') throw new TypeError('mutate callback must be synchronous');
@@ -450,9 +451,9 @@ export async function createDbStorage({ path = ':memory:', dims } = {}) {
       }
       return outcome.result;
     }, { mode: 'immediate' }),
-    get: async (key) => (await slots.get(key))?.value,
-    set: async (key, value) => { await slots.put({ key, value }); },
-    delete: async (key) => { await slots.delete(key); },
+    get: async (key: any) => (await slots.get(key))?.value,
+    set: async (key: any, value: any) => { await slots.put({ key, value }); },
+    delete: async (key: any) => { await slots.delete(key); },
     // sorted, because the ledger reads listings, the goal archive and a
     // snapshot's entries in key order and its zero-padded sequences
     // exist so that order is chronological
@@ -465,12 +466,12 @@ export async function createDbStorage({ path = ':memory:', dims } = {}) {
      * paid only when the counts prove a mixture, which is the one case
      * that is about to refuse anyway.
      */
-    rank: async ({ prefix, vector, model, dims: width, limit }) => {
+    rank: async ({ prefix, vector, model, dims: width, limit }: { prefix?: any; vector?: any; model?: any; dims?: any; limit?: any; }) => {
       const docs = forPrefix(prefix);
       const externals = { q: vector, model, dims: width };
       const hits = many(await slots.execute(
         limit === undefined ? docs.ranked : docs.window(limit), { externals }));
-      const skipped = await slots.execute(docs.skipped);
+      const skipped = await slots.execute(docs.skipped) as number;
       const held = await slots.execute(docs.held);
       const ours = await slots.execute(docs.ours, { externals });
       const identities = held === ours

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangleai/context",
-  "version": "0.21.1",
+  "version": "0.25.0",
   "description": "Evidence-backed ledgers, bounded environments, recall, retention and storage contracts.",
   "license": "MIT",
   "type": "module",
@@ -74,9 +74,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@jarenjs/core": "0.84.3",
-    "@jarenjs/validate": "0.84.3",
-    "@tangleai/models": "^0.21.1"
+    "@jarenjs/core": "0.86.0",
+    "@jarenjs/validate": "0.86.0",
+    "@tangleai/models": "^0.25.0"
   },
   "private": false,
   "files": [

package/src/archive.d.ts

@@ -1,10 +1,10 @@
 /** Exact bytes of the archive sub-map, including durable loss metadata. */
-export function archiveFootprint(records: any): {
+export declare 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?: {}): {
+export declare function retainArchives(current: Record<string, any>, added: any, limits: any, options?: Record<string, any>): {
     error: string;
     code: string;
     retention?: undefined;
@@ -30,7 +30,7 @@ export function retainArchives(current: any, added: any, limits: any, options?:
     report?: undefined;
     footprint?: undefined;
 } | {
-    next: any;
+    next: Record<string, any>;
     report: {
         version: number;
         policy: string;

package/src/archive.js

@@ -1,53 +1,58 @@
-//@ts-check
-import { jsonBytes } from './retention.js';
+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]]))) };
+    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) };
+    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

@@ -1,28 +1,60 @@
+/**
+ * The environment: a corpus the agent works ON rather than reads.
+ *
+ * Everything before this file tried to make a long context fit. The
+ * ledger stopped compaction destroying what it cut, and that moved the
+ * needle question from 2.5% to fully recoverable — but a question over
+ * *everything at once* stayed unanswerable, because the answer was never
+ * about how well the transcript was summarised. It was about the corpus
+ * being in the transcript at all.
+ *
+ * So it is not. Content lives in named slots; the root model sees a
+ * **digest** — name, kind, size, count, one line of excerpt — and works
+ * by naming slots in operations. Five of them, and they are the ones the
+ * RLM paper reports its models discovering for themselves:
+ *
+ *   peek    metadata plus a head excerpt — the default view of anything
+ *   chunk   split a slot into addressable pieces, deterministically
+ *   grep    scan for a pattern, answer with ADDRESSES and match lines
+ *   select  run a query over a structured slot, store the result
+ *   stat    counts, sizes, shape — answers that need no model at all
+ *
+ * Three rules hold without exception, and the tests assert each one:
+ *
+ *  - **No operation returns bulk content** (D2). Every result is capped
+ *    by construction — excerpts, match counts, listed slots — so a
+ *    result is the same size whether the slot holds 10 kB or 10 MB. The
+ *    one call that returns content is `read`, which requires an explicit
+ *    character budget, and it exists for a sub-call payload or a user
+ *    asking, not for the root's convenience.
+ *  - **The root view is constant-size.** The digest lists at most
+ *    `digestSlots` slots and says how many it did not list. That cap is
+ *    what makes the claim true rather than clever: a corpus three orders
+ *    of magnitude larger produces the same-size root request, and the
+ *    model narrows with `grep` and `stat` instead of with a longer list.
+ *  - **Addressing is derived, never stored.** A chunk's name is a pure
+ *    function of its parent, the strategy and its index, so chunking the
+ *    same slot twice writes the same slots instead of a second copy.
+ *
+ * Storage and the query compiler are injected (D3) — the same seams the
+ * ledger takes, because this IS the ledger's slot kind with operations
+ * over it rather than a second store.
+ */
+/** The kind a chunk slot is written under, so a digest can group them. */
+export declare const CHUNK_KIND = "chunk";
 /**
  * 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;
+export declare 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;
+export declare 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]
+ * @param [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
@@ -30,9 +62,9 @@ export function chunkFamily(parent: any, strategy: any, size: any): string;
  *   - `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?: {
+export declare function createEnvironment(options?: {
+    scope?: string;
     ledger?: any;
     storage?: {
         get: (key: string) => Promise<any>;
@@ -58,9 +90,7 @@ export function createEnvironment(options?: {
  * 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
+ * @param environment - from {@link createEnvironment}
+ * @returns 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";
+export declare function environmentTools(environment: any): any[];