@tangleai/context 0.21.1

package/src/storage/memory.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The in-memory storage adapter: the ledger's default, and the reason
+ * `createLedger()` works with no arguments at all.
+ *
+ * A host that wants durability injects its own adapter over
+ * `@jarenjs/db` (OPFS, survives the tab), `localStorage`, a file, or a
+ * server. `@tangleai/context` gains no dependency either way — the whole
+ * posture of this package is that it loads in a static page with two
+ * dependencies, and a store is the largest thing it could have been made
+ * to import.
+ *
+ * The base adapter contract:
+ *
+ *   get(key)      -> Promise<any | undefined>   a JSON value, or undefined
+ *   set(key, val) -> Promise<void>              val is a JSON value
+ *   delete(key)   -> Promise<void>              absent key is not an error
+ *   keys(prefix)  -> Promise<string[]>          every key starting with prefix, sorted
+ *
+ * Four methods, all async, all JSON. `keys()` answers in lexicographic
+ * order, and the ledger depends on it: listings, the goal archive and a
+ * snapshot's entries are read in key order, and its zero-padded
+ * sequences exist so that order is chronological. Async even here,
+ * where nothing needs to be: an adapter over IndexedDB or OPFS is
+ * unavoidably async, and a synchronous default would let a caller write
+ * code that silently breaks the moment real storage is wired in.
+ *
+ * Optional `mutate(scope, fn)` reads and replaces a detached record map in one
+ * indivisible step. Scopes select prefixes and/or exact keys; omitting the next
+ * map is read-only. The ledger uses it for staged, atomic publication.
+ *
+ * Another optional capability, for an adapter that can rank vectors where
+ * they live instead of handing every record over:
+ *
+ *   rank({ prefix, vector, model, dims, limit, minScore })
+ *     -> Promise<{ hits: { key, score }[], skipped, identities,
+ *                  ranking?: { algorithm, exhaustive, candidateCount } }>
+ *
+ * `hits` are the best `limit` records under `prefix` whose
+ * `embeddedBy` is `{ model, dims }`, best first; `skipped` is how many
+ * records under the prefix carry no embedding at all; `identities` is
+ * every DISTINCT `embeddedBy` the prefix holds, which is what lets the
+ * ledger refuse a mixture in its own words rather than each adapter
+ * inventing them. The ledger re-scores what comes back with its own
+ * kernels and applies `minScore` and `limit` itself, so `score` selects
+ * candidates and never decides the answer; an adapter free to rank
+ * approximately identifies its algorithm with `exhaustive: false`. Legacy
+ * adapters without metadata normalize to `legacy-exact`, exhaustive. The
+ * candidate count equals the returned hit count before ledger filtering.
+ * Returned keys must be unique and under the requested prefix; every fetched
+ * record is checked for identity and valid vector shape before re-scoring.
+ * The identity report must still cover omitted records: the ledger cannot
+ * independently prove an adapter's completeness without doing its own scan.
+ *
+ * This is the `compileQuery` seam's shape, one layer down: a capability
+ * that is present or absent, never half-implemented. An adapter without
+ * it loses nothing — `recall({ near })` reads and ranks, and reports
+ * `via: 'sweep'` — which is why the in-memory adapter below does not
+ * grow it.
+ */
+/**
+ * Create an in-memory adapter with JSON-value semantics: every value is
+ * serialized on the way in and parsed on the way out, so what survives
+ * is exactly what `JSON.stringify` preserves — a typed array comes back
+ * as a plain object of its indices, `NaN` and `Infinity` as `null`, and
+ * `undefined` members vanish. That is the contract, not a shortcut: real
+ * storage serializes, and a default that kept more (a structured clone
+ * would keep a `Float32Array`) would let the test path behave
+ * differently from the durable one, which is the kind of difference
+ * that surfaces in production and nowhere else. The round-trip also
+ * copies: a caller that mutates what it stored — or what it read —
+ * cannot reach inside the ledger.
+ *
+ * @param {Map<string, string>} [backing] - an existing map to adopt
+ * @returns {{ get: (key: string) => Promise<any>,
+ *   set: (key: string, value: any) => Promise<void>,
+ *   delete: (key: string) => Promise<void>,
+ *   keys: (prefix?: string) => Promise<string[]>,
+ *   mutate: import('./transaction.js').StorageMutation }}
+ */
+export function createMemoryStorage(backing?: Map<string, string>): {
+    get: (key: string) => Promise<any>;
+    set: (key: string, value: any) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    keys: (prefix?: string) => Promise<string[]>;
+    mutate: import("./transaction.js").StorageMutation;
+};

package/src/storage/memory.js

@@ -0,0 +1,118 @@
+//@ts-check
+/**
+ * The in-memory storage adapter: the ledger's default, and the reason
+ * `createLedger()` works with no arguments at all.
+ *
+ * A host that wants durability injects its own adapter over
+ * `@jarenjs/db` (OPFS, survives the tab), `localStorage`, a file, or a
+ * server. `@tangleai/context` gains no dependency either way — the whole
+ * posture of this package is that it loads in a static page with two
+ * dependencies, and a store is the largest thing it could have been made
+ * to import.
+ *
+ * The base adapter contract:
+ *
+ *   get(key)      -> Promise<any | undefined>   a JSON value, or undefined
+ *   set(key, val) -> Promise<void>              val is a JSON value
+ *   delete(key)   -> Promise<void>              absent key is not an error
+ *   keys(prefix)  -> Promise<string[]>          every key starting with prefix, sorted
+ *
+ * Four methods, all async, all JSON. `keys()` answers in lexicographic
+ * order, and the ledger depends on it: listings, the goal archive and a
+ * snapshot's entries are read in key order, and its zero-padded
+ * sequences exist so that order is chronological. Async even here,
+ * where nothing needs to be: an adapter over IndexedDB or OPFS is
+ * unavoidably async, and a synchronous default would let a caller write
+ * code that silently breaks the moment real storage is wired in.
+ *
+ * Optional `mutate(scope, fn)` reads and replaces a detached record map in one
+ * indivisible step. Scopes select prefixes and/or exact keys; omitting the next
+ * map is read-only. The ledger uses it for staged, atomic publication.
+ *
+ * Another optional capability, for an adapter that can rank vectors where
+ * they live instead of handing every record over:
+ *
+ *   rank({ prefix, vector, model, dims, limit, minScore })
+ *     -> Promise<{ hits: { key, score }[], skipped, identities,
+ *                  ranking?: { algorithm, exhaustive, candidateCount } }>
+ *
+ * `hits` are the best `limit` records under `prefix` whose
+ * `embeddedBy` is `{ model, dims }`, best first; `skipped` is how many
+ * records under the prefix carry no embedding at all; `identities` is
+ * every DISTINCT `embeddedBy` the prefix holds, which is what lets the
+ * ledger refuse a mixture in its own words rather than each adapter
+ * inventing them. The ledger re-scores what comes back with its own
+ * kernels and applies `minScore` and `limit` itself, so `score` selects
+ * candidates and never decides the answer; an adapter free to rank
+ * approximately identifies its algorithm with `exhaustive: false`. Legacy
+ * adapters without metadata normalize to `legacy-exact`, exhaustive. The
+ * candidate count equals the returned hit count before ledger filtering.
+ * Returned keys must be unique and under the requested prefix; every fetched
+ * record is checked for identity and valid vector shape before re-scoring.
+ * The identity report must still cover omitted records: the ledger cannot
+ * independently prove an adapter's completeness without doing its own scan.
+ *
+ * This is the `compileQuery` seam's shape, one layer down: a capability
+ * that is present or absent, never half-implemented. An adapter without
+ * it loses nothing — `recall({ near })` reads and ranks, and reports
+ * `via: 'sweep'` — which is why the in-memory adapter below does not
+ * grow it.
+ */
+
+/**
+ * Create an in-memory adapter with JSON-value semantics: every value is
+ * serialized on the way in and parsed on the way out, so what survives
+ * is exactly what `JSON.stringify` preserves — a typed array comes back
+ * as a plain object of its indices, `NaN` and `Infinity` as `null`, and
+ * `undefined` members vanish. That is the contract, not a shortcut: real
+ * storage serializes, and a default that kept more (a structured clone
+ * would keep a `Float32Array`) would let the test path behave
+ * differently from the durable one, which is the kind of difference
+ * that surfaces in production and nowhere else. The round-trip also
+ * copies: a caller that mutates what it stored — or what it read —
+ * cannot reach inside the ledger.
+ *
+ * @param {Map<string, string>} [backing] - an existing map to adopt
+ * @returns {{ get: (key: string) => Promise<any>,
+ *   set: (key: string, value: any) => Promise<void>,
+ *   delete: (key: string) => Promise<void>,
+ *   keys: (prefix?: string) => Promise<string[]>,
+ *   mutate: import('./transaction.js').StorageMutation }}
+ */
+export function createMemoryStorage(backing = new Map()) {
+  return {
+    mutate: async (prefix, transform) => {
+      const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
+        : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
+      // No await between read and publication: even separate adapters sharing
+      // this map observe one complete mutation. Serialize every value first.
+      const current = Object.fromEntries([...backing].filter(([key]) => matches(key))
+        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+        .map(([key, raw]) => [key, JSON.parse(raw)]));
+      const outcome = transform(current);
+      if (!outcome || typeof outcome.then === 'function') throw new TypeError('mutate callback must be synchronous');
+      if (outcome.next !== undefined) {
+        const entries = Object.entries(outcome.next).map(([key, value]) => {
+          if (!matches(key)) throw new TypeError('mutation escaped its namespace');
+          return [key, JSON.stringify(value)];
+        });
+        for (const key of backing.keys()) if (matches(key)) backing.delete(key);
+        for (const [key, raw] of entries) backing.set(key, raw);
+      }
+      return outcome.result;
+    },
+    get: async (key) => {
+      const raw = backing.get(key);
+      return raw === undefined ? undefined : JSON.parse(raw);
+    },
+    set: async (key, value) => {
+      backing.set(key, JSON.stringify(value));
+    },
+    delete: async (key) => {
+      backing.delete(key);
+    },
+    keys: async (prefix = '') => [...backing.keys()]
+      .filter((key) => key.startsWith(prefix))
+      .sort(),
+  };
+}

package/src/storage/slot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JSON slots must report failed writes by throwing or returning false. A legacy
+ * slot that swallows errors cannot promise durability; status says unverified.
+ * Web Locks serialize tabs using the same slot name. Without them the adapter
+ * explicitly exposes only the four-method, single-writer contract.
+ * @param {{ read: () => any, write: (data: any) => any, key?: string, reliable?: boolean }} slot
+ * @param {{ locks?: any, name?: string, singleWriter?: boolean }} [options]
+ */
+export function createSlotLedgerStorage(slot: {
+    read: () => any;
+    write: (data: any) => any;
+    key?: string;
+    reliable?: boolean;
+}, options?: {
+    locks?: any;
+    name?: string;
+    singleWriter?: boolean;
+}): {
+    status: () => {
+        concurrency: string;
+        durability: string;
+        error: any;
+    };
+    close: () => Promise<void>;
+    get: (key: any) => Promise<any>;
+    set: (key: any, value: any) => Promise<any>;
+    delete: (key: any) => Promise<any>;
+    keys: (prefix?: string) => Promise<string[]>;
+    mutate?: (prefix: any, transform: any) => Promise<any>;
+};

package/src/storage/slot.js

@@ -0,0 +1,107 @@
+//@ts-check
+/** A whole-slot ledger adapter. Reload under the shared Web Lock before writes. */
+const copy = (value) => value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+
+/**
+ * JSON slots must report failed writes by throwing or returning false. A legacy
+ * slot that swallows errors cannot promise durability; status says unverified.
+ * Web Locks serialize tabs using the same slot name. Without them the adapter
+ * explicitly exposes only the four-method, single-writer contract.
+ * @param {{ read: () => any, write: (data: any) => any, key?: string, reliable?: boolean }} slot
+ * @param {{ locks?: any, name?: string, singleWriter?: boolean }} [options]
+ */
+export function createSlotLedgerStorage(slot, options = {}) {
+  const locks = options.locks;
+  const name = options.name ?? slot.key ?? 'jaren-ai-ledger';
+  let closed = false;
+  const active = () => { if (closed) throw new Error('The ledger storage adapter is closed.'); };
+  let cache = {};
+  let error = null;
+  let durable = slot.reliable === true ? 'durable' : 'unverified';
+  const load = () => {
+    active();
+    const raw = slot.read();
+    if (raw !== null && raw !== undefined && (typeof raw !== 'object' || Array.isArray(raw)))
+      throw new TypeError('invalid ledger slot: expected a record map');
+    cache = copy(raw ?? {});
+    return cache;
+  };
+  const publish = (next) => {
+    active();
+    try {
+      if (slot.write(next) === false) throw new Error('ledger storage write failed');
+      cache = copy(next);
+      error = null;
+      durable = slot.reliable === true ? 'durable' : 'unverified';
+    }
+    catch (cause) {
+      error = cause instanceof Error ? cause.message : String(cause);
+      durable = 'failed';
+      throw cause;
+    }
+  };
+  const atomic = typeof locks?.request === 'function';
+  // WebKit's process-local storage snapshots can remain stale even across a
+  // locked task boundary. Elect one owner there instead of claiming coherence.
+  const singleWriter = options.singleWriter ?? false;
+  let ownership;
+  let releaseOwner;
+  let ownerRequest;
+  const own = () => {
+    active();
+    if (!atomic || !singleWriter) return Promise.resolve();
+    ownership ??= new Promise((resolve, reject) => {
+      const held = new Promise((release) => { releaseOwner = release; });
+      ownerRequest = locks.request(`ledger-owner:${name}`, { ifAvailable: true }, (lock) => {
+        if (!lock) {
+          reject(new Error('single-writer ledger: another tab owns this storage; close that tab before writing here'));
+          return;
+        }
+        resolve();
+        return held;
+      });
+      ownerRequest.catch(reject);
+    });
+    ownership.catch(() => { ownership = undefined; });
+    return ownership;
+  };
+  // Firefox publishes localStorage snapshots at task boundaries. Keep the
+  // lock until that publication completes, and enter a fresh task before read.
+  const taskBoundary = () => new Promise((resolve) => setTimeout(resolve, 0));
+  const locked = (fn) => atomic ? locks.request(`ledger:${name}`, async () => {
+    await taskBoundary();
+    try { return fn(); }
+    finally { await taskBoundary(); }
+  }) : Promise.resolve().then(fn);
+  const mutate = async (prefix, transform) => {
+    await own();
+    return locked(() => {
+    const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
+      : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
+    const current = load();
+    const scoped = Object.fromEntries(Object.keys(current).sort()
+      .filter((key) => matches(key)).map((key) => [key, copy(current[key])]));
+    const outcome = transform(scoped);
+    if (!outcome || typeof outcome.then === 'function') throw new TypeError('mutate callback must be synchronous');
+    if (outcome.next !== undefined) {
+      const next = copy(outcome.next);
+      if (Object.keys(next).some((key) => !matches(key))) throw new TypeError('mutation escaped its namespace');
+      for (const key of Object.keys(current)) if (matches(key)) delete current[key];
+      publish({ ...current, ...next });
+    }
+    return outcome.result;
+    });
+  };
+  return {
+    ...(atomic ? { mutate } : {}),
+    status: () => ({ concurrency: atomic && !singleWriter ? 'atomic' : 'single-writer', durability: durable, error }),
+    close: async () => { closed = true; releaseOwner?.(); await ownerRequest; ownership = undefined; },
+    get: async (key) => { await own(); return copy(load()[key]); },
+    set: (key, value) => mutate('', (current) => ({ next: { ...current, [key]: copy(value) } })),
+    delete: (key) => mutate('', (current) => {
+      delete current[key];
+      return { next: current };
+    }),
+    keys: async (prefix = '') => { await own(); return Object.keys(load()).filter((key) => key.startsWith(prefix)).sort(); },
+  };
+}

package/src/storage/transaction.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stage async ledger work off-store, then publish through one synchronous CAS.
+ * Readers never observe the staged adapter. Competing commits retry against a
+ * fresh record map; external I/O belongs outside the transform callback.
+ * Four-method adapters retain their explicit single-writer behavior.
+ * @template T
+ * @param {any} storage
+ * @param {StorageScope} prefix
+ * @param {(view: any) => Promise<T>} task
+ * @returns {Promise<T>}
+ */
+export function atomicTask<T>(storage: any, prefix: StorageScope, task: (view: any) => Promise<T>): Promise<T>;
+export function isAtomicView(view: any): boolean;
+/**
+ * Atomically transform the JSON record map under a namespace. The synchronous
+ * callback receives a detached current map and returns {next, result}; omitting
+ * next is a read-only decision. Failure publishes nothing. Keys cannot escape
+ * the namespace. Adapters serialize the callback with every other write.
+ */
+export type StorageScope = string | {
+    prefixes?: string[];
+    keys?: string[];
+};
+/**
+ * Atomically transform the JSON record map under a namespace. The synchronous
+ * callback receives a detached current map and returns {next, result}; omitting
+ * next is a read-only decision. Failure publishes nothing. Keys cannot escape
+ * the namespace. Adapters serialize the callback with every other write.
+ */
+export type StorageMutation = (prefix: StorageScope, transform: (current: Record<string, any>) => {
+    next?: Record<string, any>;
+    result?: any;
+}) => Promise<any>;

package/src/storage/transaction.js

@@ -0,0 +1,49 @@
+//@ts-check
+import { createMemoryStorage } from './memory.js';
+
+/**
+ * Atomically transform the JSON record map under a namespace. The synchronous
+ * callback receives a detached current map and returns {next, result}; omitting
+ * next is a read-only decision. Failure publishes nothing. Keys cannot escape
+ * the namespace. Adapters serialize the callback with every other write.
+ * @typedef {string | { prefixes?: string[], keys?: string[] }} StorageScope
+ * @typedef {(prefix: StorageScope, transform: (current: Record<string, any>) =>
+ *   { next?: Record<string, any>, result?: any }) => Promise<any>} StorageMutation
+ */
+
+const staged = new WeakSet();
+/** Whether a private view is already enclosed by an atomic publication. */
+export const isAtomicView = (view) => staged.has(view);
+
+const signature = (map) => JSON.stringify(Object.keys(map).sort().map((key) => [key, map[key]]));
+
+/**
+ * Stage async ledger work off-store, then publish through one synchronous CAS.
+ * Readers never observe the staged adapter. Competing commits retry against a
+ * fresh record map; external I/O belongs outside the transform callback.
+ * Four-method adapters retain their explicit single-writer behavior.
+ * @template T
+ * @param {any} storage
+ * @param {StorageScope} prefix
+ * @param {(view: any) => Promise<T>} task
+ * @returns {Promise<T>}
+ */
+export async function atomicTask(storage, prefix, task) {
+  if (typeof storage.mutate !== 'function') return task(storage);
+  for (let attempt = 0; attempt < 128; attempt++) {
+    const before = await storage.mutate(prefix, (current) => ({ result: current }));
+    const expected = signature(before);
+    const backing = new Map(Object.entries(before).map(([key, value]) => [key, JSON.stringify(value)]));
+    const view = createMemoryStorage(backing);
+    // Staging already owns its isolated map; nested transactions need no CAS.
+    const { mutate: _mutate, ...plain } = view;
+    staged.add(plain);
+    const result = await task(plain);
+    const next = Object.fromEntries([...backing].map(([key, raw]) => [key, JSON.parse(raw)]));
+    const changed = signature(next) !== expected;
+    const committed = await storage.mutate(prefix, (current) => signature(current) !== expected
+      ? { result: false } : { ...(changed ? { next } : {}), result: true });
+    if (committed) return result;
+  }
+  throw Object.assign(new Error('ledger transaction conflict; retry the operation'), { code: 'LEDGER_CONFLICT' });
+}