@tangleai/context 0.21.1 → 0.25.0

package/src/ledger.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The ledger: schema-validated, durable, addressable state that outlives
  * a context window.
@@ -23,7 +22,7 @@
  *  - **Nothing enters without passing its schema**, compiled by
  *    `JarenValidator` here at construction. A rejected write answers the
  *    same `{ error, errors, inputSchema }` the toolbox answers with (one
- *    implementation, in `check.js`) and never throws: a model that wrote
+ *    implementation, in `check.ts`) and never throws: a model that wrote
  *    a bad memory can read why and fix it.
  *  - **Every mutation is reversible.** `snapshot()` before, `rollback()`
  *    after — which is what will make model-proposed refinements safe to
@@ -55,98 +54,47 @@
  * slots, refinement's patchable state, and the website assistant's
  * durable memory — all on this one implementation.
  */
-
 import { JarenValidator } from '@jarenjs/validate';
 import { excerpt } from '@jarenjs/core/chunk';
 import { isVector, cosineSimilarity } from '@jarenjs/core/vector';
-
 import { checkOutcome } from '@jarenjs/core/check';
 import { invalidInput } from '@tangleai/models/check';
-import { validateClaimEvidence } from './evidence.js';
+import { validateClaimEvidence } from "./evidence.js";
 import { AiError } from '@tangleai/models/errors';
-import { retainArchives } from './archive.js';
-import { jsonBytes, checkpointProgress, validateCheckpoint, goalPrompt } from './retention.js';
-import { atomicTask, isAtomicView } from './storage/transaction.js';
-import { createMemoryStorage } from './storage/memory.js';
-import { LEDGER_SCHEMAS } from './schemas/ledger.js';
-
-/** @typedef {import('./schemas/ledger.js').LedgerGoal} LedgerGoal */
-/** @typedef {import('./schemas/ledger.js').LedgerMemory} LedgerMemory */
-/** @typedef {import('./schemas/ledger.js').LedgerSkill} LedgerSkill */
-/** @typedef {import('./schemas/ledger.js').LedgerSlot} LedgerSlot */
-/** @typedef {import('./schemas/ledger.js').LedgerRejection} LedgerRejection */
-/** @typedef {import('./schemas/ledger.js').LedgerEmbeddingPair} LedgerEmbeddingPair */
-/** @typedef {import('./schemas/ledger.js').LedgerEmbeddedBy} LedgerEmbeddedBy */
-/** @typedef {import('@tangleai/models/embed').Embedder} Embedder */
-
-/**
- * What `recall({ near })` answers: the memories that carry a comparable
+import { retainArchives } from "./archive.js";
+import { jsonBytes, checkpointProgress, validateCheckpoint, goalPrompt } from "./retention.js";
+import { atomicTask, isAtomicView } from "./storage/transaction.js";
+import { createMemoryStorage } from "./storage/memory.js";
+import { LEDGER_SCHEMAS } from "./schemas/ledger.js";
+/** What `recall({ near })` answers: the memories that carry a comparable
  * vector, ranked by cosine similarity (descending; ties by recency, then
  * id), one score per memory in the same order, and the count of records
  * that passed the filter but carry no vector and were therefore skipped
- * — reported, never scored.
- * @typedef {object} LedgerRankedMemories
- * @property {LedgerMemory[]} memories
- * @property {number[]} scores
- * @property {number} skipped
- * @property {'sweep' | 'adapter'} via - which path answered: the ledger's
- *   own read-and-rank, or the adapter's `rank` capability
- * @property {LedgerRanking} ranking - candidate selection provenance, not a quality guarantee
- */
-
-/**
- * What `recallSkills({ near })` answers — see {@link LedgerRankedMemories}.
- * @typedef {object} LedgerRankedSkills
- * @property {LedgerSkill[]} skills
- * @property {number[]} scores
- * @property {number} skipped
- * @property {'sweep' | 'adapter'} via - see {@link LedgerRankedMemories}
- * @property {LedgerRanking} ranking - see {@link LedgerRankedMemories}
- */
-
-/**
- * Optional storage rank metadata. Legacy adapters normalize to exhaustive.
+ * — reported, never scored. */
+/** Optional storage rank metadata. Legacy adapters normalize to exhaustive.
  * Exhaustive means exact candidate selection, not that every record is returned.
- * Candidate count is the number returned before ledger filtering and capping.
- * @typedef {object} LedgerRanking
- * @property {string} algorithm
- * @property {boolean} exhaustive
- * @property {number} candidateCount
- */
-
-/**
- * The query both recalls take. `near` is the string to rank by meaning
+ * Candidate count is the number returned before ledger filtering and capping. */
+/** The query both recalls take. `near` is the string to rank by meaning
  * against, and needs the embedder seam; `minScore` filters the ranked
  * result (cosine, in [-1, 1]); `tags` and `where` narrow the candidates
- * first, exactly as they do without `near`.
- * @typedef {object} LedgerQuery
- * @property {string[]} [tags]
- * @property {any} [where]
- * @property {number} [limit]
- * @property {string} [near]
- * @property {number} [minScore]
- */
-
+ * first, exactly as they do without `near`. */
 /** The key space. State and snapshots are separate prefixes on purpose:
  * a rollback wipes state and must not take the other snapshots with it. */
 const STATE = 'ai/state/';
 const SNAP = 'ai/snap/';
 const KEYS = {
-  goal: `${STATE}goal/active`,
-  goalArchive: `${STATE}goal/archive/`,
-  memory: `${STATE}memory/`,
-  skill: `${STATE}skill/`,
-  slot: `${STATE}slot/`,
-  slotContent: `${STATE}slot-content/`,
+    goal: `${STATE}goal/active`,
+    goalArchive: `${STATE}goal/archive/`,
+    memory: `${STATE}memory/`,
+    skill: `${STATE}skill/`,
+    slot: `${STATE}slot/`,
+    slotContent: `${STATE}slot-content/`,
 };
-
 /** Slot metadata carries a short excerpt so a root request can list a
  * hundred slots without carrying one slot's content. */
 const SLOT_EXCERPT_CHARS = 120;
-
 /** A zero-padded sequence, so `keys()` sorts lexicographically into order. */
 const seq = (n) => String(n).padStart(6, '0');
-
 /**
  * The next sequence number under a prefix: one past the highest that
  * still exists, read from the trailing digits of every key. Never the
@@ -155,21 +103,20 @@ const seq = (n) => String(n).padStart(6, '0');
  * key that happens to end in digits merely advances the sequence, which
  * costs nothing: uniqueness needs only that no existing key ends in the
  * number minted.
- * @param {string[]} keys - every key under the prefix
- * @returns {number}
+ * @param keys - every key under the prefix
  */
 function nextSequence(keys) {
-  let highest = -1;
-  for (const key of keys) {
-    const match = /(\d+)$/.exec(key);
-    if (match !== null) {
-      const n = Number(match[1]);
-      if (n > highest) highest = n;
+    let highest = -1;
+    for (const key of keys) {
+        const match = /(\d+)$/.exec(key);
+        if (match !== null) {
+            const n = Number(match[1]);
+            if (n > highest)
+                highest = n;
+        }
     }
-  }
-  return highest + 1;
+    return highest + 1;
 }
-
 /**
  * A record with its `undefined` members removed.
  *
@@ -179,50 +126,42 @@ function nextSequence(keys) {
  * present, and the write validates — then `JSON.stringify` drops it on
  * the way to storage and an unevidenced memory is durable. Stripping
  * first makes what is validated exactly what would be stored.
- * @param {Record<string, any>} record
- * @returns {any} the stripped record — `any` so each write site's declared
+ * @returns the stripped record — `any` so each write site's declared
  *   return type (the record typedef) is the statement that binds, not an
  *   inference from this generic helper
  */
 function defined(record) {
-  const out = {};
-  for (const [key, value] of Object.entries(record)) {
-    if (value !== undefined) out[key] = value;
-  }
-  return out;
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
 }
-
 /**
  * Newest first, ties broken by id so two records written in the same
  * millisecond still come back in a stable order. A retrieval whose order
  * wobbled between calls would make everything downstream of it
  * unreproducible.
- * @param {any[]} records
  */
 function byRecency(records) {
-  return [...records].sort(recencyOrder);
+    return [...records].sort(recencyOrder);
 }
-
 /**
  * The comparator behind {@link byRecency}: newer first, then id — the
  * same rule ranked recall falls back to between two equal scores.
- * @param {any} a
- * @param {any} b
  */
 function recencyOrder(a, b) {
-  return a.at === b.at
-    ? String(a.id ?? a.name).localeCompare(String(b.id ?? b.name))
-    : String(b.at).localeCompare(String(a.at));
+    return a.at === b.at
+        ? String(a.id ?? a.name).localeCompare(String(b.id ?? b.name))
+        : String(b.at).localeCompare(String(a.at));
 }
-
 /**
  * The text a skill is embedded from: its name, when it applies and what
  * to do, one per line — what "near" means for a skill. A memory is
  * embedded from its `text` alone.
- * @param {{ name: string, when: string, instructions: string }} skill
  */
 const skillText = (skill) => `${skill.name}\n${skill.when}\n${skill.instructions}`;
-
 /**
  * Whether two vector identities name the same space: the same model at
  * the same width. The rule the ledger applies before any arithmetic
@@ -243,19 +182,16 @@ const skillText = (skill) => `${skill.name}\n${skill.when}\n${skill.instructions
  * produce vectors whose cosine is arithmetic without meaning, which is
  * why `dims` matching is necessary and never sufficient.
  *
- * @param {LedgerEmbeddedBy | undefined | null} a
- * @param {LedgerEmbeddedBy | undefined | null} b
- * @returns {boolean} whether both are identities naming one space
+ * @returns whether both are identities naming one space
  * @example
  * sameIdentity({ model: 'm', dims: 4 }, { model: 'm', dims: 4 });  // true
  * sameIdentity({ model: 'm', dims: 4 }, { model: 'm', dims: 8 });  // false — a re-embed, not a match
  * sameIdentity(undefined, undefined);                              // false — no space is not a shared space
  */
 export function sameIdentity(a, b) {
-  return a !== undefined && a !== null && b !== undefined && b !== null
-    && a.model === b.model && a.dims === b.dims;
+    return a !== undefined && a !== null && b !== undefined && b !== null
+        && a.model === b.model && a.dims === b.dims;
 }
-
 /**
  * An identity as a refusal names it — `"text-embedding-3-small (1536
  * dims)"`. Exported for the same reason as {@link sameIdentity}: it is
@@ -264,40 +200,18 @@ export function sameIdentity(a, b) {
  * key for collecting the DISTINCT identities a `rank` adapter owes its
  * caller.
  *
- * @param {LedgerEmbeddedBy} identity
- * @returns {string}
  */
 export function describeIdentity(identity) {
-  return `${identity.model} (${identity.dims} dims)`;
+    return `${identity.model} (${identity.dims} dims)`;
 }
-
 /** The seam refusal, shared by every entry point that needs the embedder. */
 const SEAM_REFUSAL = 'needs the embedder seam — inject createEmbeddingClient(...) or any { embed, model, dims }';
-
 /** How many texts one `embedMissing` batch hands the seam. */
 const EMBED_BATCH = 64;
-
 /**
  * Create a ledger.
  *
- * @param {{ storage?: { get: (key: string) => Promise<any>,
- *     set: (key: string, value: any) => Promise<void>,
- *     delete: (key: string) => Promise<void>,
- *     keys: (prefix?: string) => Promise<string[]>,
- *     status?: () => any,
- *     mutate?: import('./storage/transaction.js').StorageMutation,
- *     rank?: (request: { prefix: string, vector: number[], model: string, dims: number,
- *       limit?: number, minScore?: number }) => Promise<{ hits: { key: string, score: number }[],
- *       skipped: number, identities: LedgerEmbeddedBy[], ranking?: LedgerRanking }> },
- *   compileQuery?: (document: any) => (data: any) => any,
- *   embedder?: Embedder,
- *   embedOnWrite?: boolean,
- *   validator?: any,
- *   now?: () => string,
- *   archiveLimits?: { maxItems?: number, maxBytes?: number },
- *   goalLimits?: { maxEntries?: number, maxBytes?: number, maxChars?: number },
- *   checkpointReducer?: (goal: any) => any,
- *   artifacts?: import('./schemas/evidence.js').ArtifactRecord[] }} [options]
+ * @param [options]
  *   - `storage` defaults to an in-memory adapter, so a ledger works with
  *     nothing wired. Anything durable is the host's to inject. Its four
  *     methods are the contract; an adapter that can rank vectors itself
@@ -323,1075 +237,1015 @@ const EMBED_BATCH = 64;
  *     tests, exactly as the rest of the suite injects its environment).
  */
 export function createLedger(options = {}) {
-  const storage = options.storage ?? createMemoryStorage();
-  for (const [limits, names] of [[options.archiveLimits, ['maxItems', 'maxBytes']],
-    [options.goalLimits, ['maxEntries', 'maxBytes', 'maxChars']]]) {
-    for (const [name, value] of Object.entries(limits ?? {})) {
-      if (!names.includes(name)) throw new TypeError(`unknown ledger budget '${name}'`);
-      if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+    const storage = options.storage ?? createMemoryStorage();
+    for (const [limits, names] of [[options.archiveLimits, ['maxItems', 'maxBytes']],
+        [options.goalLimits, ['maxEntries', 'maxBytes', 'maxChars']]]) {
+        for (const [name, value] of Object.entries(limits ?? {})) {
+            if (!names.includes(name))
+                throw new TypeError(`unknown ledger budget '${name}'`);
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw new TypeError(`${name} must be a non-negative safe integer`);
+        }
     }
-  }
-  const admittedArtifacts = options.artifacts === undefined ? undefined : JSON.parse(JSON.stringify(options.artifacts));
-  if (admittedArtifacts !== undefined && !validateClaimEvidence({ version: 1, artifacts: admittedArtifacts,
-    evidence: [], claims: [], visibleEvidence: [] }).valid) throw new TypeError('artifacts must be unique, valid admitted records');
-  const compileQuery = typeof options.compileQuery === 'function' ? options.compileQuery : null;
-  /** @type {Embedder | null} */
-  const embedder = options.embedder ?? null;
-  if (embedder !== null) {
-    if (typeof embedder !== 'object' || typeof embedder.embed !== 'function')
-      throw new AiError('AI0001', 'embedder: expected the seam — { embed(texts) → Promise<Float32Array[]>, model, dims }');
-    if (typeof embedder.model !== 'string' || embedder.model === '')
-      throw new AiError('AI0001', 'embedder: needs a model name — it is half of every vector\'s identity');
-  }
-  const embedOnWrite = options.embedOnWrite === true;
-  if (embedOnWrite && embedder === null)
-    throw new AiError('AI0001', `embedOnWrite ${SEAM_REFUSAL}`);
-  const now = options.now ?? (() => new Date().toISOString());
-  // `unknownFormats: 'ignore'` is the library default; it is passed
-  // EXPLICITLY because this project's convention for a schema it ships is
-  // the opposite one (`'error'`, so a format nobody registered fails the
-  // build instead of checking nothing), and this is the deliberate
-  // exception. It has to be: the schemas declare `format: 'date-time'`
-  // because that is what the values ARE, but the package may not depend
-  // on `@jarenjs/formats` (D3), so no compiler for it can ever be
-  // registered here. The enforcement is the `pattern` beside the format,
-  // which needs nothing injected; a host passing its own
-  // formats-registered `validator` gets the stricter check on top.
-  const jaren = options.validator
-    ?? new JarenValidator({
-      skipErrors: false, collectErrors: true, unknownFormats: 'ignore',
-    });
-
-  /** Every kind's compiled check, built once. */
-  const checks = Object.fromEntries(Object.entries(LEDGER_SCHEMAS)
-    .map(([kind, schema]) => [kind, jaren.compile(schema)]));
-
-  /** Compiled retrieval queries, keyed by their document. Recall runs on
-   * every turn of a long conversation; compiling the same predicate each
-   * time would be the kind of waste that only shows up under load. */
-  const queryCache = new Map();
-
-  /** The tail of the write queue: the promise every mutation waits on. */
-  let queue = Promise.resolve();
-
-  /**
-   * Run one mutating operation after every one queued before it has
-   * settled. Every write is a read-modify-write — mint an id from what
-   * exists, then store; read the goal, then replace it — and two of them
-   * interleaved read the same "what exists" and collide. One queue per
-   * ledger makes a `Promise.all` of writes behave as the sequence it
-   * reads as. A rejected operation does not stall the queue: the next
-   * one runs regardless, and only its own caller sees the rejection.
-   * @template T
-   * @param {(view: any) => Promise<T>} task
-   * @param {import('./storage/transaction.js').StorageScope} [scope]
-   * @returns {Promise<T>}
-   */
-  function enqueue(task, scope = 'ai/') {
-    const result = queue.then(() => atomicTask(storage, scope, task));
-    queue = result.then(() => undefined, () => undefined);
-    return result;
-  }
-
-  /**
-   * Validate a complete record against its kind, or produce the standard
-   * rejection. The record is built by the caller (defaults already
-   * filled) so that what is validated is exactly what would be stored.
-   *
-   * Exported as well as used internally, because a caller that wants to
-   * know whether a record WOULD be storable before storing it — a
-   * model-proposed refinement, which has to reject an unevidenced memory
-   * without writing one — must ask the same question the write asks,
-   * against the same compiled schema. A second copy of these checks is
-   * how "the ledger rejects it" and "the gate rejects it" would come to
-   * mean different things.
-   * @param {'goal'|'memory'|'skill'|'slot'} kind
-   * @param {any} record
-   * @returns {null | { error: string, errors: any[], inputSchema: any }}
-   *   null when the record is storable.
-   */
-  function validate(kind, record) {
-    const outcome = checkOutcome(checks[kind](record));
-    if (!outcome.valid) return invalidInput(kind, outcome, LEDGER_SCHEMAS[kind]);
-    if (kind === 'goal') {
-      const ids = new Set();
-      const errors = [];
-      const entries = [...(record.checkpoint?.sources ?? []), ...record.progress];
-      for (const entry of entries) {
-        if (entry.id !== undefined && ids.has(entry.id)) errors.push({ keyword: 'uniqueId', instancePath: '/progress', message: 'progress source ids must be unique' });
-        if (entry.id !== undefined) ids.add(entry.id);
-      }
-      for (const source of record.checkpoint?.sources ?? []) {
-        if (source.record >= record.checkpoint.records.length)
-          errors.push({ keyword: 'reference', instancePath: '/checkpoint/sources', message: 'checkpoint source refers to a missing record' });
-      }
-      if (errors.length) return invalidInput(kind, { errors }, LEDGER_SCHEMAS[kind]);
+    const admittedArtifacts = options.artifacts === undefined ? undefined : JSON.parse(JSON.stringify(options.artifacts));
+    if (admittedArtifacts !== undefined && !validateClaimEvidence({
+        version: 1, artifacts: admittedArtifacts,
+        evidence: [], claims: [], visibleEvidence: []
+    }).valid)
+        throw new TypeError('artifacts must be unique, valid admitted records');
+    const compileQuery = typeof options.compileQuery === 'function' ? options.compileQuery : null;
+    const embedder = options.embedder ?? null;
+    if (embedder !== null) {
+        if (typeof embedder !== 'object' || typeof embedder.embed !== 'function')
+            throw new AiError('AI0001', 'embedder: expected the seam — { embed(texts) → Promise<Float32Array[]>, model, dims }');
+        if (typeof embedder.model !== 'string' || embedder.model === '')
+            throw new AiError('AI0001', 'embedder: needs a model name — it is half of every vector\'s identity');
     }
-    if (kind === 'memory' && typeof record.evidence !== 'string') {
-      const references = validateClaimEvidence(record.evidence, { artifacts: admittedArtifacts });
-      if (!references.valid) return invalidInput(kind, { errors: references.errors.map((error) => ({
-        ...error, keyword: error.code ?? error.keyword, instancePath: `/evidence${error.instancePath ?? error.docPath ?? ''}`,
-      })) }, LEDGER_SCHEMAS[kind]);
+    const embedOnWrite = options.embedOnWrite === true;
+    if (embedOnWrite && embedder === null)
+        throw new AiError('AI0001', `embedOnWrite ${SEAM_REFUSAL}`);
+    const now = options.now ?? (() => new Date().toISOString());
+    // `unknownFormats: 'ignore'` is the library default; it is passed
+    // EXPLICITLY because this project's convention for a schema it ships is
+    // the opposite one (`'error'`, so a format nobody registered fails the
+    // build instead of checking nothing), and this is the deliberate
+    // exception. It has to be: the schemas declare `format: 'date-time'`
+    // because that is what the values ARE, but the package may not depend
+    // on `@jarenjs/formats` (D3), so no compiler for it can ever be
+    // registered here. The enforcement is the `pattern` beside the format,
+    // which needs nothing injected; a host passing its own
+    // formats-registered `validator` gets the stricter check on top.
+    const jaren = options.validator
+        ?? new JarenValidator({
+            skipErrors: false, collectErrors: true, unknownFormats: 'ignore',
+        });
+    /** Every kind's compiled check, built once. */
+    const checks = Object.fromEntries(Object.entries(LEDGER_SCHEMAS)
+        .map(([kind, schema]) => [kind, jaren.compile(schema)]));
+    /** Compiled retrieval queries, keyed by their document. Recall runs on
+     * every turn of a long conversation; compiling the same predicate each
+     * time would be the kind of waste that only shows up under load. */
+    const queryCache = new Map();
+    /** The tail of the write queue: the promise every mutation waits on. */
+    let queue = Promise.resolve();
+    /**
+     * Run one mutating operation after every one queued before it has
+     * settled. Every write is a read-modify-write — mint an id from what
+     * exists, then store; read the goal, then replace it — and two of them
+     * interleaved read the same "what exists" and collide. One queue per
+     * ledger makes a `Promise.all` of writes behave as the sequence it
+     * reads as. A rejected operation does not stall the queue: the next
+     * one runs regardless, and only its own caller sees the rejection.
+     * @template T
+     * @param [scope]
+     */
+    function enqueue(task, scope = 'ai/') {
+        const result = queue.then(() => atomicTask(storage, scope, task));
+        queue = result.then(() => undefined, () => undefined);
+        return result;
     }
-    // the schema has said the pair is present together and shaped; what
-    // it cannot say is that the vector IS what its identity declares —
-    // `isVector` is the suite's one definition of that
-    if (record.embedding !== undefined && !isVector(record.embedding, record.embeddedBy.dims)) {
-      return invalidInput(kind, { errors: [{
-        instancePath: '/embedding',
-        keyword: 'embeddedBy',
-        message: `must be exactly ${record.embeddedBy.dims} finite numbers, as embeddedBy.dims declares`,
-      }] }, LEDGER_SCHEMAS[kind]);
+    /**
+     * Validate a complete record against its kind, or produce the standard
+     * rejection. The record is built by the caller (defaults already
+     * filled) so that what is validated is exactly what would be stored.
+     *
+     * Exported as well as used internally, because a caller that wants to
+     * know whether a record WOULD be storable before storing it — a
+     * model-proposed refinement, which has to reject an unevidenced memory
+     * without writing one — must ask the same question the write asks,
+     * against the same compiled schema. A second copy of these checks is
+     * how "the ledger rejects it" and "the gate rejects it" would come to
+     * mean different things.
+     * @returns
+     *   null when the record is storable.
+     */
+    function validate(kind, record) {
+        const outcome = checkOutcome(checks[kind](record));
+        if (!outcome.valid)
+            return invalidInput(kind, outcome, LEDGER_SCHEMAS[kind]);
+        if (kind === 'goal') {
+            const ids = new Set();
+            const errors = [];
+            const entries = [...(record.checkpoint?.sources ?? []), ...record.progress];
+            for (const entry of entries) {
+                if (entry.id !== undefined && ids.has(entry.id))
+                    errors.push({ keyword: 'uniqueId', instancePath: '/progress', message: 'progress source ids must be unique' });
+                if (entry.id !== undefined)
+                    ids.add(entry.id);
+            }
+            for (const source of record.checkpoint?.sources ?? []) {
+                if (source.record >= record.checkpoint.records.length)
+                    errors.push({ keyword: 'reference', instancePath: '/checkpoint/sources', message: 'checkpoint source refers to a missing record' });
+            }
+            if (errors.length)
+                return invalidInput(kind, { errors }, LEDGER_SCHEMAS[kind]);
+        }
+        if (kind === 'memory' && typeof record.evidence !== 'string') {
+            const references = validateClaimEvidence(record.evidence, { artifacts: admittedArtifacts });
+            if (!references.valid)
+                return invalidInput(kind, {
+                    errors: references.errors.map((error) => ({
+                        ...error, keyword: error.code ?? error.keyword, instancePath: `/evidence${error.instancePath ?? error.docPath ?? ''}`,
+                    }))
+                }, LEDGER_SCHEMAS[kind]);
+        }
+        // the schema has said the pair is present together and shaped; what
+        // it cannot say is that the vector IS what its identity declares —
+        // `isVector` is the suite's one definition of that
+        if (record.embedding !== undefined && !isVector(record.embedding, record.embeddedBy.dims)) {
+            return invalidInput(kind, {
+                errors: [{
+                        instancePath: '/embedding',
+                        keyword: 'embeddedBy',
+                        message: `must be exactly ${record.embeddedBy.dims} finite numbers, as embeddedBy.dims declares`,
+                    }]
+            }, LEDGER_SCHEMAS[kind]);
+        }
+        return null;
     }
-    return null;
-  }
-
-  /**
-   * Embed texts through the seam, holding a host embedder to the
-   * contract the shipped ones keep — one finite vector per input, all of
-   * one width — and answering `{ vectors, identity }` or `{ error }`,
-   * never a throw. The call sits inside the `try` so that a host `embed`
-   * that throws synchronously lands in the same catch as one that
-   * rejects. `identity.dims` is the embedder's settled width, or the
-   * width this reply settled it at.
-   * @param {string[]} texts
-   * @returns {Promise<{ vectors: Float32Array[], identity: LedgerEmbeddedBy, error?: undefined }
-   *   | { error: string, vectors?: undefined, identity?: undefined }>}
-   */
-  async function embedThrough(texts) {
-    if (embedder === null) return { error: SEAM_REFUSAL };
-    try {
-      const vectors = await embedder.embed(texts);
-      if (!Array.isArray(vectors) || vectors.length !== texts.length) {
-        return { error: `the embedder answered ${Array.isArray(vectors) ? vectors.length : 'no'}`
-          + ` vectors for ${texts.length} inputs` };
-      }
-      const dims = embedder.dims ?? vectors[0].length;
-      for (let i = 0; i < vectors.length; i++) {
-        if (!isVector(vectors[i], dims))
-          return { error: `the embedder answered something other than ${dims} finite numbers for input ${i}` };
-      }
-      return { vectors, identity: { model: embedder.model, dims } };
+    /**
+     * Embed texts through the seam, holding a host embedder to the
+     * contract the shipped ones keep — one finite vector per input, all of
+     * one width — and answering `{ vectors, identity }` or `{ error }`,
+     * never a throw. The call sits inside the `try` so that a host `embed`
+     * that throws synchronously lands in the same catch as one that
+     * rejects. `identity.dims` is the embedder's settled width, or the
+     * width this reply settled it at.
+     */
+    async function embedThrough(texts) {
+        if (embedder === null)
+            return { error: SEAM_REFUSAL };
+        try {
+            const vectors = await embedder.embed(texts);
+            if (!Array.isArray(vectors) || vectors.length !== texts.length) {
+                return {
+                    error: `the embedder answered ${Array.isArray(vectors) ? vectors.length : 'no'}`
+                        + ` vectors for ${texts.length} inputs`
+                };
+            }
+            const dims = embedder.dims ?? vectors[0].length;
+            for (let i = 0; i < vectors.length; i++) {
+                if (!isVector(vectors[i], dims))
+                    return { error: `the embedder answered something other than ${dims} finite numbers for input ${i}` };
+            }
+            return { vectors, identity: { model: embedder.model, dims } };
+        }
+        catch (err) {
+            return { error: err?.message ?? String(err) };
+        }
     }
-    catch (err) {
-      return { error: /** @type {any} */ (err)?.message ?? String(err) };
+    /**
+     * The stored form of one seam vector on a record: plain numbers, with
+     * the identity beside them.
+     * @template {object} T
+     */
+    const withEmbedding = (record, vector, identity) => ({ ...record, embedding: Array.from(vector), embeddedBy: { ...identity } });
+    /**
+     * The `embedOnWrite` step: a record arriving without a vector is
+     * embedded inside its own write. A seam failure is reported on the
+     * RESULT, not the record — the record is stored un-embedded and the
+     * write succeeds, because one bad network call must not lose a memory;
+     * `embedMissing()` closes the gap later.
+     * @template {{ embedding?: number[] }} T
+     */
+    async function embedOnWriteStep(record, text) {
+        if (!embedOnWrite || record.embedding !== undefined)
+            return { record };
+        const answer = await embedThrough([text]);
+        if (answer.error !== undefined)
+            return { record, embedError: `the embedder seam failed — ${answer.error}; stored un-embedded` };
+        return { record: withEmbedding(record, answer.vectors[0], answer.identity) };
     }
-  }
-
-  /**
-   * The stored form of one seam vector on a record: plain numbers, with
-   * the identity beside them.
-   * @template {object} T
-   * @param {T} record
-   * @param {Float32Array} vector
-   * @param {LedgerEmbeddedBy} identity
-   * @returns {T & { embedding: number[], embeddedBy: LedgerEmbeddedBy }}
-   */
-  const withEmbedding = (record, vector, identity) =>
-    ({ ...record, embedding: Array.from(vector), embeddedBy: { ...identity } });
-
-  /**
-   * The `embedOnWrite` step: a record arriving without a vector is
-   * embedded inside its own write. A seam failure is reported on the
-   * RESULT, not the record — the record is stored un-embedded and the
-   * write succeeds, because one bad network call must not lose a memory;
-   * `embedMissing()` closes the gap later.
-   * @template {{ embedding?: number[] }} T
-   * @param {T} record
-   * @param {string} text
-   * @returns {Promise<{ record: T, embedError?: string }>}
-   */
-  async function embedOnWriteStep(record, text) {
-    if (!embedOnWrite || record.embedding !== undefined) return { record };
-    const answer = await embedThrough([text]);
-    if (answer.error !== undefined)
-      return { record, embedError: `the embedder seam failed — ${answer.error}; stored un-embedded` };
-    return { record: withEmbedding(record, answer.vectors[0], answer.identity) };
-  }
-
-  /** Read every value under a prefix, in key order. */
-  async function readAll(prefix, view = storage) {
-    const keys = await view.keys(prefix);
-    return Promise.all(keys.map((key) => view.get(key)));
-  }
-
-  /**
-   * An id for a record the caller did not name. Derived from the
-   * timestamp and one past the highest sequence of that kind still
-   * stored, so it is unique within a ledger and reproducible under an
-   * injected clock. Called only from inside the write queue: the mint
-   * and the store that follows it are one step, so no second writer can
-   * read the same highest in between.
-   */
-  async function mintId(kind, prefix, view) {
-    const counter = `ai/counters/${kind}`;
-    const n = Math.max(await view.get(counter) ?? 0, nextSequence(await view.keys(prefix)));
-    if (!Number.isSafeInteger(n) || n >= Number.MAX_SAFE_INTEGER) throw new RangeError('ledger id sequence exhausted');
-    await view.set(counter, n + 1);
-    return `${kind}-${now()}-${seq(n)}`;
-  }
-
-  //#region goal
-
-  /**
-   * Set the active objective. Singular by construction: an existing goal
-   * is marked `superseded` and moved to the archive rather than
-   * overwritten, so the history of what this agent was asked to do
-   * survives the change.
-   * @param {{ objective: string, createdAt?: string, status?: string,
-   *   progress?: any[] }} input
-   * @returns {Promise<LedgerGoal | LedgerRejection>} the stored goal, or a rejection
-   */
-  function setGoal(input) {
-    return enqueue(async (storage) => {
-      let goal = defined({
-        objective: input?.objective,
-        createdAt: input?.createdAt ?? now(),
-        status: input?.status ?? 'active',
-        progress: input?.progress ?? [],
-      });
-      const rejected = validate('goal', goal);
-      if (rejected !== null) return rejected;
-
-      const bounded = await boundGoal(goal, storage);
-      if (bounded.error) return bounded;
-      goal = bounded;
-      const previous = await storage.get(KEYS.goal);
-      if (previous !== undefined) {
-        const archived = await storage.keys(KEYS.goalArchive);
-        await storage.set(`${KEYS.goalArchive}${seq(nextSequence(archived))}`,
-          { ...previous, status: 'superseded' });
-      }
-      await storage.set(KEYS.goal, goal);
-      return goal;
-    }, { prefixes: [KEYS.goalArchive], keys: [KEYS.goal, 'ai/counters/progress'] });
-  }
-
-  /**
-   * The active objective, or null.
-   * @returns {Promise<LedgerGoal | null>}
-   */
-  async function getGoal() {
-    return (await storage.get(KEYS.goal)) ?? null;
-  }
-
-  /**
-   * Every superseded goal, oldest first.
-   * @returns {Promise<LedgerGoal[]>}
-   */
-  async function listArchivedGoals() {
-    return readAll(KEYS.goalArchive);
-  }
-
-  /**
-   * Append one evidenced progress entry to the active goal. Storage
-   * only: nothing here reads a note, scores it, or decides that a goal
-   * is finished — that judgement belongs to whatever drives the agent.
-   * @param {{ note: string, evidence: string, at?: string }} entry
-   * @returns {Promise<LedgerGoal | LedgerRejection | { error: string }>}
-   *   the goal with the entry appended; the bare `{ error }` is "no
-   *   active goal", which is a state problem, not a validation one
-   */
-  function recordProgress(entry) {
-    return enqueue(async (storage) => {
-      const goal = await storage.get(KEYS.goal);
-      if (goal === undefined) return { error: 'no active goal — call setGoal first' };
-      let next = {
-        ...goal,
-        progress: [...goal.progress, defined({
-          at: entry?.at ?? now(),
-          note: entry?.note,
-          evidence: entry?.evidence,
-        })],
-      };
-      const rejected = validate('goal', next);
-      if (rejected !== null) return rejected;
-      next = await boundGoal(next, storage);
-      if (next.error) return next;
-      await storage.set(KEYS.goal, next);
-      return next;
-    }, { keys: [KEYS.goal, 'ai/counters/progress'] });
-  }
-
-  /**
-   * Change the active goal's status without superseding it — how a run
-   * records that its objective finished or was abandoned.
-   * @param {'active'|'done'|'abandoned'|'superseded'} status
-   * @returns {Promise<LedgerGoal | LedgerRejection | { error: string }>}
-   */
-  function setGoalStatus(status) {
-    return enqueue(async (storage) => {
-      const goal = await storage.get(KEYS.goal);
-      if (goal === undefined) return { error: 'no active goal — call setGoal first' };
-      const next = { ...goal, status };
-      const rejected = validate('goal', next);
-      if (rejected !== null) return rejected;
-      await storage.set(KEYS.goal, next);
-      return next;
-    }, { keys: [KEYS.goal] });
-  }
-
-  /** Bound a goal only through validated, lossless coverage, or visibly refuse. */
-  async function boundGoal(goal, view) {
-    const limits = options.goalLimits;
-    if (!limits) return goal;
-    if (typeof storage.mutate !== 'function' && !isAtomicView(storage))
-      return { error: 'goal budgets require atomic storage', code: 'ATOMIC_REQUIRED' };
-    const next = JSON.parse(JSON.stringify(goal));
-    let counter = await view.get('ai/counters/progress') ?? 0;
-    const ids = new Set([...(next.checkpoint?.sources ?? []), ...next.progress].map((entry) => entry.id));
-    for (const entry of next.progress) {
-      if (entry.id !== undefined) continue;
-      while (ids.has(`progress-${seq(counter)}`)) counter++;
-      if (!Number.isSafeInteger(counter) || counter >= Number.MAX_SAFE_INTEGER) throw new RangeError('progress sequence exhausted');
-      entry.id = `progress-${seq(counter++)}`;
-      ids.add(entry.id);
+    /** Read every value under a prefix, in key order. */
+    async function readAll(prefix, view = storage) {
+        const keys = await view.keys(prefix);
+        return Promise.all(keys.map((key) => view.get(key)));
     }
-    const fits = (candidate) => candidate.progress.length <= (limits.maxEntries ?? Infinity)
-      && jsonBytes(candidate) <= (limits.maxBytes ?? Infinity)
-      && goalPrompt(candidate).length <= (limits.maxChars ?? Infinity);
-    if (!fits(next)) {
-      let checkpoint;
-      try { checkpoint = options.checkpointReducer ? options.checkpointReducer(JSON.parse(JSON.stringify(next))) : checkpointProgress(next); }
-      catch (error) { return { error: `checkpoint reducer failed: ${error instanceof Error ? error.message : String(error)}`, code: 'GOAL_CHECKPOINT' }; }
-      const checked = validateCheckpoint(checkpoint, next);
-      if (!checked.valid) return { error: 'invalid goal checkpoint', errors: checked.errors, code: 'GOAL_CHECKPOINT' };
-      const compacted = { ...next, progress: [], checkpoint,
-        retention: { version: 1, reason: 'goal-budget', retired: next.progress.map((entry) => entry.id) } };
-      const rejected = validate('goal', compacted);
-      if (rejected) return rejected;
-      if (!fits(compacted)) return { error: 'goal budget cannot preserve the objective and evidence; host action required',
-        code: 'GOAL_BUDGET', retention: { refused: true, bytes: jsonBytes(compacted), chars: goalPrompt(compacted).length, limits } };
-      await view.set('ai/counters/progress', counter);
-      return compacted;
+    /**
+     * An id for a record the caller did not name. Derived from the
+     * timestamp and one past the highest sequence of that kind still
+     * stored, so it is unique within a ledger and reproducible under an
+     * injected clock. Called only from inside the write queue: the mint
+     * and the store that follows it are one step, so no second writer can
+     * read the same highest in between.
+     */
+    async function mintId(kind, prefix, view) {
+        const counter = `ai/counters/${kind}`;
+        const n = Math.max(await view.get(counter) ?? 0, nextSequence(await view.keys(prefix)));
+        if (!Number.isSafeInteger(n) || n >= Number.MAX_SAFE_INTEGER)
+            throw new RangeError('ledger id sequence exhausted');
+        await view.set(counter, n + 1);
+        return `${kind}-${now()}-${seq(n)}`;
     }
-    await view.set('ai/counters/progress', counter);
-    return next;
-  }
-
-  /** Render the complete goal under the host's hard character budget. */
-  async function composeGoal() {
-    const goal = await getGoal();
-    if (!goal || goal.status !== 'active') return { text: '' };
-    const rejected = validate('goal', goal);
-    if (rejected) return rejected;
-    const text = goalPrompt(goal);
-    if (text.length > (options.goalLimits?.maxChars ?? Infinity))
-      return { error: 'goal prompt exceeds its character budget; host action required', code: 'GOAL_BUDGET' };
-    return { text };
-  }
-
-  //#endregion
-
-  //#region memories and skills
-
-  /**
-   * Store a fact worth carrying. `evidence` is required by the schema,
-   * and the rejection says so: a memory without it is a guess, and a
-   * ledger of guesses is worse than an empty one.
-   *
-   * The record is EVERY member of the input plus the generated defaults,
-   * validated whole — so a member the schema does not know is refused
-   * with the same `additionalProperties` answer `validate()` gives,
-   * never silently dropped. A write that quietly stored less than it
-   * was handed would let "it was accepted" and "it is there" diverge.
-   * @param {{ id?: string, text: string, evidence: LedgerMemory['evidence'],
-   *   tags?: string[], at?: string } & LedgerEmbeddingPair} input
-   *   `embedding` + `embeddedBy` travel together (plain numbers, never a
-   *   typed array — the pair type says so, and an orphan does not
-   *   compile); the vector must be exactly `embeddedBy.dims` finite
-   *   numbers or the write is rejected
-   * @returns {Promise<(LedgerMemory & { embedError?: string }) | LedgerRejection>}
-   *   the record as stored (defaults filled, undefined members
-   *   stripped), or the rejection saying why nothing was. `embedError`
-   *   appears only under `embedOnWrite` when the seam failed: the record
-   *   is stored WITHOUT a vector and the member is not part of it
-   */
-  function addMemory(input) {
-    let embedded;
-    return enqueue(async (storage) => {
-      const memory = defined({
-        ...input,
-        id: input?.id ?? '(pending)',
-        tags: input?.tags ?? [],
-        at: input?.at ?? now(),
-      });
-      const rejected = validate('memory', memory);
-      if (rejected !== null) return rejected;
-      if (input?.id === undefined || input?.id === null) memory.id = await mintId('memory', KEYS.memory, storage);
-      embedded ??= await embedOnWriteStep(memory, memory.text);
-      const record = { ...embedded.record, id: memory.id, at: memory.at };
-      const { embedError } = embedded;
-      await storage.set(`${KEYS.memory}${record.id}`, record);
-      return embedError === undefined ? record : { ...record, embedError };
-    }, { prefixes: [KEYS.memory], keys: ['ai/counters/memory'] });
-  }
-
-  /**
-   * One memory by id, or null.
-   * @param {string} id
-   * @returns {Promise<LedgerMemory | null>}
-   */
-  async function getMemory(id) {
-    return (await storage.get(`${KEYS.memory}${id}`)) ?? null;
-  }
-
-  /**
-   * Every memory, newest first.
-   * @returns {Promise<LedgerMemory[]>}
-   */
-  async function listMemories() {
-    return byRecency(await readAll(KEYS.memory));
-  }
-
-  /**
-   * Remove a memory. Answers whether one was there.
-   * @param {string} id
-   */
-  function deleteMemory(id) {
-    return enqueue(async (storage) => {
-      const key = `${KEYS.memory}${id}`;
-      const existed = (await storage.get(key)) !== undefined;
-      await storage.delete(key);
-      return existed;
-    }, { keys: [`${KEYS.memory}${id}`] });
-  }
-
-  /**
-   * Store a reusable recipe. Built and validated exactly as a memory is:
-   * every input member, defaults filled, the whole record checked.
- * @param {{ id?: string, name: string, when: string,
-   *   instructions: string, tools?: string[], at?: string, program?: LedgerSkill['program'] }
-   *   & LedgerEmbeddingPair} input
-   * @returns {Promise<(LedgerSkill & { embedError?: string }) | LedgerRejection>}
-   *   as `addMemory`; under `embedOnWrite` the skill is embedded from its
-   *   name, when and instructions
-   */
-  function addSkill(input) {
-    let embedded;
-    return enqueue(async (storage) => {
-      const skill = defined({
-        ...input,
-        id: input?.id ?? '(pending)',
-        tools: input?.tools ?? [],
-        at: input?.at ?? now(),
-      });
-      const rejected = validate('skill', skill);
-      if (rejected !== null) return rejected;
-      if (input?.id === undefined || input?.id === null) skill.id = await mintId('skill', KEYS.skill, storage);
-      embedded ??= await embedOnWriteStep(skill, skillText(skill));
-      const record = { ...embedded.record, id: skill.id, at: skill.at };
-      const { embedError } = embedded;
-      await storage.set(`${KEYS.skill}${record.id}`, record);
-      return embedError === undefined ? record : { ...record, embedError };
-    }, { prefixes: [KEYS.skill], keys: ['ai/counters/skill'] });
-  }
-
-  /**
-   * One skill by id, or null.
-   * @param {string} id
-   * @returns {Promise<LedgerSkill | null>}
-   */
-  async function getSkill(id) {
-    return (await storage.get(`${KEYS.skill}${id}`)) ?? null;
-  }
-
-  /**
-   * Every skill, newest first.
-   * @returns {Promise<LedgerSkill[]>}
-   */
-  async function listSkills() {
-    return byRecency(await readAll(KEYS.skill));
-  }
-
-  /**
-   * Remove a skill. Answers whether one was there.
-   * @param {string} id
-   */
-  function deleteSkill(id) {
-    return enqueue(async (storage) => {
-      const key = `${KEYS.skill}${id}`;
-      const existed = (await storage.get(key)) !== undefined;
-      await storage.delete(key);
-      return existed;
-    }, { keys: [`${KEYS.skill}${id}`] });
-  }
-
-  //#endregion
-
-  //#region retrieval
-
-  /**
-   * The tag predicate as a query document. Jaren's comparison operators
-   * are existentially lifted over sequences, so `$eq` between the record's
-   * tag sequence and the requested one is exactly "the two overlap" —
-   * one operator, no loop, and the same meaning as the fallback's
-   * `some`/`includes`.
-   * @param {string[]} tags
-   */
-  const tagPredicate = (tags) => ({ $eq: ['$it.tags[*]', { $seq: tags }] });
-
-  /** Compile once per distinct query document. */
-  function compiled(document) {
-    const key = JSON.stringify(document);
-    let run = queryCache.get(key);
-    if (run === undefined) {
-      run = compileQuery(document);
-      queryCache.set(key, run);
+    //#region goal
+    /**
+     * Set the active objective. Singular by construction: an existing goal
+     * is marked `superseded` and moved to the archive rather than
+     * overwritten, so the history of what this agent was asked to do
+     * survives the change.
+     * @returns the stored goal, or a rejection
+     */
+    function setGoal(input) {
+        return enqueue(async (storage) => {
+            let goal = defined({
+                objective: input?.objective,
+                createdAt: input?.createdAt ?? now(),
+                status: input?.status ?? 'active',
+                progress: input?.progress ?? [],
+            });
+            const rejected = validate('goal', goal);
+            if (rejected !== null)
+                return rejected;
+            const bounded = await boundGoal(goal, storage);
+            if (bounded.error)
+                return bounded;
+            goal = bounded;
+            const previous = await storage.get(KEYS.goal);
+            if (previous !== undefined) {
+                const archived = await storage.keys(KEYS.goalArchive);
+                await storage.set(`${KEYS.goalArchive}${seq(nextSequence(archived))}`, { ...previous, status: 'superseded' });
+            }
+            await storage.set(KEYS.goal, goal);
+            return goal;
+        }, { prefixes: [KEYS.goalArchive], keys: [KEYS.goal, 'ai/counters/progress'] });
     }
-    return run;
-  }
-
-  /**
-   * Filter a record set. With the query seam wired this is a real jaren
-   * query — one document, which a host that also wired `@jarenjs/db`
-   * could push down to SQL unchanged. With the seam empty it is tag
-   * match, and a caller predicate is REFUSED rather than ignored:
-   * silently dropping a filter would answer the wrong question with a
-   * straight face.
-   */
-  function filter(records, tags, where) {
-    const parts = [];
-    if (tags !== undefined && tags.length > 0) parts.push(tagPredicate(tags));
-    if (where !== undefined && where !== null) parts.push(where);
-
-    if (compileQuery === null) {
-      if (where !== undefined && where !== null) {
-        return { error: 'recall: a `where` predicate needs the compileQuery seam — '
-          + 'inject compileJsonQuery from @jarenjs/json/query, or filter by tags only' };
-      }
-      if (parts.length === 0) return { value: records };
-      return { value: records.filter((record) =>
-        (record.tags ?? []).some((tag) => tags.includes(tag))) };
+    /**
+     * The active objective, or null.
+     */
+    async function getGoal() {
+        return (await storage.get(KEYS.goal)) ?? null;
     }
-
-    if (parts.length === 0) return { value: records };
-    const predicate = parts.length === 1 ? parts[0] : { $and: parts };
-    try {
-      const run = compiled([{ $for: { it: '$[*]' }, $where: predicate, $return: '$it' }]);
-      return { value: run(records) };
+    /**
+     * Every superseded goal, oldest first.
+     */
+    async function listArchivedGoals() {
+        return readAll(KEYS.goalArchive);
     }
-    catch (err) {
-      // a caller's predicate that does not compile is content, not a
-      // crash — same posture as a tool call the model got wrong
-      return { error: `recall: ${/** @type {any} */ (err)?.reason ?? /** @type {any} */ (err)?.message ?? err}` };
+    /**
+     * Append one evidenced progress entry to the active goal. Storage
+     * only: nothing here reads a note, scores it, or decides that a goal
+     * is finished — that judgement belongs to whatever drives the agent.
+     * @returns
+     *   the goal with the entry appended; the bare `{ error }` is "no
+     *   active goal", which is a state problem, not a validation one
+     */
+    function recordProgress(entry) {
+        return enqueue(async (storage) => {
+            const goal = await storage.get(KEYS.goal);
+            if (goal === undefined)
+                return { error: 'no active goal — call setGoal first' };
+            let next = {
+                ...goal,
+                progress: [...goal.progress, defined({
+                        at: entry?.at ?? now(),
+                        note: entry?.note,
+                        evidence: entry?.evidence,
+                    })],
+            };
+            const rejected = validate('goal', next);
+            if (rejected !== null)
+                return rejected;
+            next = await boundGoal(next, storage);
+            if (next.error)
+                return next;
+            await storage.set(KEYS.goal, next);
+            return next;
+        }, { keys: [KEYS.goal, 'ai/counters/progress'] });
     }
-  }
-
-  /**
-   * Retrieve by relevance: tag match, then recency, plus any predicate
-   * the seam can evaluate.
-   * @param {any[]} records
-   * @param {LedgerQuery} query
-   */
-  function retrieve(records, query = {}) {
-    const filtered = filter(records, query.tags, query.where);
-    if (filtered.error !== undefined) return filtered;
-    const ordered = byRecency(filtered.value);
-    return typeof query.limit === 'number' ? ordered.slice(0, query.limit) : ordered;
-  }
-
-  /**
-   * The mixture refusal, in one place, so the sweep and an adapter that
-   * ranks for us word it identically and in the same order.
-   * @param {string} name
-   * @param {Map<string, LedgerEmbeddedBy>} found - every identity seen, in the order seen
-   * @param {LedgerEmbeddedBy} identity - the query embedder's
-   * @returns {{ error: string } | null}
-   */
-  function refuseMixture(name, found, identity) {
-    if ([...found.values()].every((stored) => sameIdentity(stored, identity))) return null;
-    return { error: `${name}: near cannot rank across embedders — the ledger holds vectors from`
-      + ` ${[...found.keys()].join(', ')} and the query embedder is ${describeIdentity(identity)};`
-      + ' rank through the embedder that wrote them, or re-embed every record with one embedder' };
-  }
-
-  /**
-   * The last two steps both ranked paths share: the kernels score every
-   * record the path selected, `minScore` filters and `limit` caps.
-   *
-   * The score is always `cosineSimilarity` over the record as stored —
-   * never a number an adapter handed back — so the two paths cannot
-   * report different similarities for the same record. Equal scores
-   * fall back to recency, then id.
-   * @param {any[]} records
-   * @param {any} probe
-   * @param {LedgerQuery} query
-   * @param {'memories' | 'skills'} member
-   * @param {number} skipped
-   * @param {'sweep' | 'adapter'} via
-   * @param {LedgerRanking} [ranking]
-   */
-  function rankedResult(records, probe, query, member, skipped, via,
-    ranking = { algorithm: 'exact-cosine', exhaustive: true, candidateCount: records.length }) {
-    const ranked = records
-      .map((record) => ({ record, score: cosineSimilarity(probe, record.embedding) }))
-      .sort((a, b) => (b.score - a.score) || recencyOrder(a.record, b.record));
-    const kept = typeof query.minScore === 'number'
-      ? ranked.filter((entry) => entry.score >= /** @type {number} */ (query.minScore))
-      : ranked;
-    const capped = typeof query.limit === 'number' ? kept.slice(0, query.limit) : kept;
-    return {
-      [member]: capped.map((entry) => entry.record),
-      scores: capped.map((entry) => entry.score),
-      skipped,
-      via,
-      ranking,
-    };
-  }
-
-  /**
-   * Retrieve by meaning: the records that pass the tag/where filter AND
-   * carry a vector, ranked by cosine similarity to the embedded query.
-   *
-   * The refusals come before the arithmetic, in this order: `near` must
-   * be a non-empty string; the seam must be wired (the `compileQuery`
-   * precedent — an absent capability refuses, it never degrades); the
-   * filter must compile; the seam must answer; and every candidate's
-   * identity must equal the query embedder's. A mixture — two models in
-   * the ledger, or a ledger embedded by one model and queried through
-   * another — is refused naming every identity found, because ranking
-   * the matching subset would be a silent wrong answer. Records without
-   * a vector are not scored (a fabricated score poisons a ranking) and
-   * not hidden (a silent drop poisons trust): they are counted in
-   * `skipped`.
-   *
-   * TWO paths reach that answer and both report which one ran. By
-   * default the ledger reads every record under the prefix and ranks
-   * them here. An adapter that declares `rank` is asked instead — it
-   * knows how to narrow to the k best without handing over the whole
-   * ledger — and is held to exactly the same contract: it reports the
-   * distinct identities it holds so the mixture refusal is the ledger's,
-   * it reports what it skipped, and the kernels re-score what it
-   * returns. An adapter whose own ranking is approximate makes recall
-   * approximate: the ledger can re-score what it is handed, never
-   * recover a record the adapter did not return.
-   *
-   * `tags` and `where` narrow candidates the adapter knows nothing
-   * about, so a query carrying either takes the sweep.
-   *
-   * Ranking is `cosineSimilarity` from the kernels, descending; equal
-   * scores fall back to recency, then id, so the order is deterministic.
-   * `minScore` filters the ranked list; `limit` caps what survives.
-   * @param {LedgerQuery} query
-   * @param {'recall' | 'recallSkills'} name - the entry point, for the refusal text
-   * @param {'memories' | 'skills'} member - the result member the ranked records go under
-   * @param {string} prefix - the key space the records live under
-   * @returns {Promise<{ error: string }
-   *   | { [member: string]: any, scores: number[], skipped: number, via: 'sweep' | 'adapter' }>}
-   */
-  async function rankNear(query, name, member, prefix) {
-    const { near } = query;
-    if (typeof near !== 'string' || near === '')
-      return { error: `${name}: near must be a non-empty string — the text to rank by meaning against` };
-    if (embedder === null) return { error: `${name}: near ${SEAM_REFUSAL}` };
-
-    const narrowed = query.tags !== undefined || query.where !== undefined;
-    const delegated = typeof storage.rank === 'function' && !narrowed;
-    // the sweep reads first so that a `where` without the compileQuery
-    // seam still refuses before the embedder is called; the adapter path
-    // has no filter to compile
-    const filtered = delegated ? null : filter(await readAll(prefix), query.tags, query.where);
-    if (filtered !== null && filtered.error !== undefined) return filtered;
-
-    const answer = await embedThrough([near]);
-    if (answer.error !== undefined) return { error: `${name}: the embedder seam failed — ${answer.error}` };
-    const probe = answer.vectors[0];
-    const identity = answer.identity;
-
-    if (delegated) {
-      const hits = await /** @type {any} */ (storage).rank({
-        prefix, vector: Array.from(probe), model: identity.model, dims: identity.dims,
-        limit: query.limit, minScore: query.minScore,
-      });
-      if (hits === null || typeof hits !== 'object' || !Array.isArray(hits.hits)
-        || !Array.isArray(hits.identities) || !Number.isSafeInteger(hits.skipped) || hits.skipped < 0) {
-        return { error: `${name}: the storage adapter's rank answered something other than`
-          + ' { hits, skipped, identities } — a capability that cannot be trusted to report what it'
-          + ' skipped is worse than one that is absent' };
-      }
-      const ranking = hits.ranking === undefined ? { algorithm: 'legacy-exact', exhaustive: true, candidateCount: hits.hits.length } : hits.ranking;
-      if (ranking === null || typeof ranking !== 'object' || typeof ranking.algorithm !== 'string' || ranking.algorithm.trim() === ''
-        || typeof ranking.exhaustive !== 'boolean' || ranking.candidateCount !== hits.hits.length)
-        return { error: `${name}: invalid storage rank metadata` };
-      const keys = new Set();
-      for (const hit of hits.hits) {
-        if (typeof hit?.key !== 'string' || !hit.key.startsWith(prefix) || hit.key.length === prefix.length
-          || keys.has(hit.key) || typeof hit.score !== 'number' || !Number.isFinite(hit.score))
-          return { error: `${name}: invalid or duplicate storage rank candidate` };
-        keys.add(hit.key);
-      }
-      /** @type {Map<string, LedgerEmbeddedBy>} */
-      const found = new Map();
-      for (const stored of hits.identities) {
-        if (typeof stored?.model !== 'string' || stored.model === '' || !Number.isSafeInteger(stored.dims) || stored.dims < 1)
-          return { error: `${name}: invalid storage rank identity` };
-        found.set(describeIdentity(stored), stored);
-      }
-      const records = await Promise.all(hits.hits.map((/** @type {any} */ hit) => storage.get(hit.key)));
-      for (let i = 0; i < records.length; i++) {
-        const record = records[i];
-        if (record == null) continue; // Deleted between selection and read.
-        if (`${prefix}${record.id}` !== hits.hits[i].key || !sameIdentity(record.embeddedBy, identity))
-          return { error: `${name}: storage rank candidate identity mismatch` };
-        if (!isVector(record.embedding, identity.dims))
-          return { error: `${name}: invalid storage rank candidate vector` };
-        found.set(describeIdentity(record.embeddedBy), record.embeddedBy);
-      }
-      const refused = refuseMixture(name, found, identity);
-      if (refused !== null) return refused;
-      // a key the adapter ranked and a read that no longer finds it is a
-      // record deleted in between, not a record without a vector
-      return rankedResult(records.filter((record) => record?.embedding !== undefined),
-        probe, query, member, hits.skipped, 'adapter',
-        { algorithm: ranking.algorithm, exhaustive: ranking.exhaustive, candidateCount: ranking.candidateCount });
+    /**
+     * Change the active goal's status without superseding it — how a run
+     * records that its objective finished or was abandoned.
+     */
+    function setGoalStatus(status) {
+        return enqueue(async (storage) => {
+            const goal = await storage.get(KEYS.goal);
+            if (goal === undefined)
+                return { error: 'no active goal — call setGoal first' };
+            const next = { ...goal, status };
+            const rejected = validate('goal', next);
+            if (rejected !== null)
+                return rejected;
+            await storage.set(KEYS.goal, next);
+            return next;
+        }, { keys: [KEYS.goal] });
+    }
+    /** Bound a goal only through validated, lossless coverage, or visibly refuse. */
+    async function boundGoal(goal, view) {
+        const limits = options.goalLimits;
+        if (!limits)
+            return goal;
+        if (typeof storage.mutate !== 'function' && !isAtomicView(storage))
+            return { error: 'goal budgets require atomic storage', code: 'ATOMIC_REQUIRED' };
+        const next = JSON.parse(JSON.stringify(goal));
+        let counter = await view.get('ai/counters/progress') ?? 0;
+        const ids = new Set([...(next.checkpoint?.sources ?? []), ...next.progress].map((entry) => entry.id));
+        for (const entry of next.progress) {
+            if (entry.id !== undefined)
+                continue;
+            while (ids.has(`progress-${seq(counter)}`))
+                counter++;
+            if (!Number.isSafeInteger(counter) || counter >= Number.MAX_SAFE_INTEGER)
+                throw new RangeError('progress sequence exhausted');
+            entry.id = `progress-${seq(counter++)}`;
+            ids.add(entry.id);
+        }
+        const fits = (candidate) => candidate.progress.length <= (limits.maxEntries ?? Infinity)
+            && jsonBytes(candidate) <= (limits.maxBytes ?? Infinity)
+            && goalPrompt(candidate).length <= (limits.maxChars ?? Infinity);
+        if (!fits(next)) {
+            let checkpoint;
+            try {
+                checkpoint = options.checkpointReducer ? options.checkpointReducer(JSON.parse(JSON.stringify(next))) : checkpointProgress(next);
+            }
+            catch (error) {
+                return { error: `checkpoint reducer failed: ${error instanceof Error ? error.message : String(error)}`, code: 'GOAL_CHECKPOINT' };
+            }
+            const checked = validateCheckpoint(checkpoint, next);
+            if (!checked.valid)
+                return { error: 'invalid goal checkpoint', errors: checked.errors, code: 'GOAL_CHECKPOINT' };
+            const compacted = {
+                ...next, progress: [], checkpoint,
+                retention: { version: 1, reason: 'goal-budget', retired: next.progress.map((entry) => entry.id) }
+            };
+            const rejected = validate('goal', compacted);
+            if (rejected)
+                return rejected;
+            if (!fits(compacted))
+                return {
+                    error: 'goal budget cannot preserve the objective and evidence; host action required',
+                    code: 'GOAL_BUDGET', retention: { refused: true, bytes: jsonBytes(compacted), chars: goalPrompt(compacted).length, limits }
+                };
+            await view.set('ai/counters/progress', counter);
+            return compacted;
+        }
+        await view.set('ai/counters/progress', counter);
+        return next;
+    }
+    /** Render the complete goal under the host's hard character budget. */
+    async function composeGoal() {
+        const goal = await getGoal();
+        if (!goal || goal.status !== 'active')
+            return { text: '' };
+        const rejected = validate('goal', goal);
+        if (rejected)
+            return rejected;
+        const text = goalPrompt(goal);
+        if (text.length > (options.goalLimits?.maxChars ?? Infinity))
+            return { error: 'goal prompt exceeds its character budget; host action required', code: 'GOAL_BUDGET' };
+        return { text };
+    }
+    //#endregion
+    //#region memories and skills
+    /**
+     * Store a fact worth carrying. `evidence` is required by the schema,
+     * and the rejection says so: a memory without it is a guess, and a
+     * ledger of guesses is worse than an empty one.
+     *
+     * The record is EVERY member of the input plus the generated defaults,
+     * validated whole — so a member the schema does not know is refused
+     * with the same `additionalProperties` answer `validate()` gives,
+     * never silently dropped. A write that quietly stored less than it
+     * was handed would let "it was accepted" and "it is there" diverge.
+     *   `embedding` + `embeddedBy` travel together (plain numbers, never a
+     *   typed array — the pair type says so, and an orphan does not
+     *   compile); the vector must be exactly `embeddedBy.dims` finite
+     *   numbers or the write is rejected
+     * @returns
+     *   the record as stored (defaults filled, undefined members
+     *   stripped), or the rejection saying why nothing was. `embedError`
+     *   appears only under `embedOnWrite` when the seam failed: the record
+     *   is stored WITHOUT a vector and the member is not part of it
+     */
+    function addMemory(input) {
+        let embedded;
+        return enqueue(async (storage) => {
+            const memory = defined({
+                ...input,
+                id: input?.id ?? '(pending)',
+                tags: input?.tags ?? [],
+                at: input?.at ?? now(),
+            });
+            const rejected = validate('memory', memory);
+            if (rejected !== null)
+                return rejected;
+            if (input?.id === undefined || input?.id === null)
+                memory.id = await mintId('memory', KEYS.memory, storage);
+            embedded ??= await embedOnWriteStep(memory, memory.text);
+            const record = { ...embedded.record, id: memory.id, at: memory.at };
+            const { embedError } = embedded;
+            await storage.set(`${KEYS.memory}${record.id}`, record);
+            return embedError === undefined ? record : { ...record, embedError };
+        }, { prefixes: [KEYS.memory], keys: ['ai/counters/memory'] });
+    }
+    /**
+     * One memory by id, or null.
+     */
+    async function getMemory(id) {
+        return (await storage.get(`${KEYS.memory}${id}`)) ?? null;
+    }
+    /**
+     * Every memory, newest first.
+     */
+    async function listMemories() {
+        return byRecency(await readAll(KEYS.memory));
+    }
+    /**
+     * Remove a memory. Answers whether one was there.
+     */
+    function deleteMemory(id) {
+        return enqueue(async (storage) => {
+            const key = `${KEYS.memory}${id}`;
+            const existed = (await storage.get(key)) !== undefined;
+            await storage.delete(key);
+            return existed;
+        }, { keys: [`${KEYS.memory}${id}`] });
+    }
+    /**
+     * Store a reusable recipe. Built and validated exactly as a memory is:
+     * every input member, defaults filled, the whole record checked.
+     * @returns
+     *   as `addMemory`; under `embedOnWrite` the skill is embedded from its
+     *   name, when and instructions
+     */
+    function addSkill(input) {
+        let embedded;
+        return enqueue(async (storage) => {
+            const skill = defined({
+                ...input,
+                id: input?.id ?? '(pending)',
+                tools: input?.tools ?? [],
+                at: input?.at ?? now(),
+            });
+            const rejected = validate('skill', skill);
+            if (rejected !== null)
+                return rejected;
+            if (input?.id === undefined || input?.id === null)
+                skill.id = await mintId('skill', KEYS.skill, storage);
+            embedded ??= await embedOnWriteStep(skill, skillText(skill));
+            const record = { ...embedded.record, id: skill.id, at: skill.at };
+            const { embedError } = embedded;
+            await storage.set(`${KEYS.skill}${record.id}`, record);
+            return embedError === undefined ? record : { ...record, embedError };
+        }, { prefixes: [KEYS.skill], keys: ['ai/counters/skill'] });
+    }
+    /**
+     * One skill by id, or null.
+     */
+    async function getSkill(id) {
+        return (await storage.get(`${KEYS.skill}${id}`)) ?? null;
     }
-
-    // the identity check, before any math: every candidate's identity
-    // must be the query's, or nothing is ranked
-    /** @type {any[]} */
-    const candidates = [];
-    /** @type {Map<string, LedgerEmbeddedBy>} */
-    const found = new Map();
-    let skipped = 0;
-    for (const record of /** @type {any} */ (filtered).value) {
-      if (record.embedding === undefined) {
-        skipped += 1;
-        continue;
-      }
-      found.set(describeIdentity(record.embeddedBy), record.embeddedBy);
-      candidates.push(record);
+    /**
+     * Every skill, newest first.
+     */
+    async function listSkills() {
+        return byRecency(await readAll(KEYS.skill));
     }
-    const refused = refuseMixture(name, found, identity);
-    if (refused !== null) return refused;
-    return rankedResult(candidates, probe, query, member, skipped, 'sweep');
-  }
-
-  /**
-   * Memories relevant to a query. Without `near`: tag match, then
-   * recency — an array, newest first. With `near`: ranked by meaning
-   * through the embedder seam — `{ memories, scores, skipped, via }` — or
-   * the refusal that says why not.
-   * @param {LedgerQuery} [query]
-   * @returns {Promise<LedgerMemory[] | LedgerRankedMemories | { error: string }>}
-   *   the `{ error }` is a query problem — no seam for a `where` or a
-   *   `near`, a predicate that does not compile, a seam that failed, or
-   *   a mixture of vector identities — content, not a crash
-   */
-  async function recall(query = {}) {
-    return query.near === undefined
-      ? retrieve(await readAll(KEYS.memory), query)
-      : /** @type {any} */ (rankNear(query, 'recall', 'memories', KEYS.memory));
-  }
-
-  /**
-   * Skills relevant to a query — what a host composes into a system
-   * prompt. The same two paths as `recall`; a skill's meaning is its
-   * name, when and instructions together.
-   * @param {LedgerQuery} [query]
-   * @returns {Promise<LedgerSkill[] | LedgerRankedSkills | { error: string }>}
-   */
-  async function recallSkills(query = {}) {
-    return query.near === undefined
-      ? retrieve(await readAll(KEYS.skill), query)
-      : /** @type {any} */ (rankNear(query, 'recallSkills', 'skills', KEYS.skill));
-  }
-
-  /**
-   * The explicit sweep: embed every memory and skill that carries no
-   * vector, through the seam, in batches, inside the write chain — so no
-   * other write moves a record under it. Memories first, then skills,
-   * each in key order; `limit` caps how many records this run embeds,
-   * `batch` how many texts one seam call carries. Positive fractional batch sizes
-   * are floored to an integer of at least one.
-   *
-   * Honest about what it did not do. A second run over a swept ledger
-   * embeds zero and makes no seam call (the two-run check). A failing
-   * batch ends the run: the records embedded before it are written, the
-   * failed batch and everything after it stay un-embedded and are
-   * counted in `remaining`, and the error is surfaced once — never a
-   * throw that loses the batch, and never a per-record retry against a
-   * provider that just refused (the seam's own retry policy has already
-   * run). A ledger that already holds vectors under another identity is
-   * refused up front rather than turned into a mixture `recall({ near })`
-   * would then refuse.
-   * @param {{ limit?: number, batch?: number }} [options]
-   * @returns {Promise<{ embedded: number, remaining: number, error?: string }>}
-   */
-  function embedMissing(options = {}) {
-    const batches = new Map();
-    return enqueue(async (storage) => {
-      const batch = typeof options.batch === 'number' && options.batch > 0 ? Math.max(1, Math.floor(options.batch)) : EMBED_BATCH;
-      /** @type {Array<{ key: string, record: any, text: string }>} */
-      const pending = [];
-      /** @type {Map<string, LedgerEmbeddedBy>} */
-      const held = new Map();
-      for (const memory of await readAll(KEYS.memory, storage)) {
-        if (memory.embedding === undefined) pending.push({ key: `${KEYS.memory}${memory.id}`, record: memory, text: memory.text });
-        else held.set(describeIdentity(memory.embeddedBy), memory.embeddedBy);
-      }
-      for (const skill of await readAll(KEYS.skill, storage)) {
-        if (skill.embedding === undefined) pending.push({ key: `${KEYS.skill}${skill.id}`, record: skill, text: skillText(skill) });
-        else held.set(describeIdentity(skill.embeddedBy), skill.embeddedBy);
-      }
-      const total = pending.length;
-      if (embedder === null) return { embedded: 0, remaining: total, error: `embedMissing: ${SEAM_REFUSAL}` };
-
-      /** The mixture refusal, once the embedder's width is known. */
-      const mixture = (/** @type {LedgerEmbeddedBy} */ identity) => {
-        const foreign = [...held.keys()].filter((key) => !sameIdentity(held.get(key), identity));
-        return foreign.length === 0 ? null
-          : { embedded: 0, remaining: total, error: 'embedMissing: would mix vector identities — the ledger'
-            + ` already holds vectors from ${foreign.join(', ')} and the embedder is ${describeIdentity(identity)};`
-            + ' sweep with the embedder that wrote them, or re-add those records without a vector first' };
-      };
-      if (embedder.dims !== undefined) {
-        const refused = mixture({ model: embedder.model, dims: embedder.dims });
-        if (refused !== null) return refused;
-      }
-
-      const todo = typeof options.limit === 'number' ? pending.slice(0, Math.max(0, Math.floor(options.limit))) : pending;
-      let embedded = 0;
-      for (let i = 0; i < todo.length; i += batch) {
-        const slice = todo.slice(i, i + batch);
-        const texts = slice.map((entry) => entry.text), key = JSON.stringify(texts);
-        if (!batches.has(key)) batches.set(key, await embedThrough(texts));
-        const answer = batches.get(key);
+    /**
+     * Remove a skill. Answers whether one was there.
+     */
+    function deleteSkill(id) {
+        return enqueue(async (storage) => {
+            const key = `${KEYS.skill}${id}`;
+            const existed = (await storage.get(key)) !== undefined;
+            await storage.delete(key);
+            return existed;
+        }, { keys: [`${KEYS.skill}${id}`] });
+    }
+    //#endregion
+    //#region retrieval
+    /**
+     * The tag predicate as a query document. Jaren's comparison operators
+     * are existentially lifted over sequences, so `$eq` between the record's
+     * tag sequence and the requested one is exactly "the two overlap" —
+     * one operator, no loop, and the same meaning as the fallback's
+     * `some`/`includes`.
+     */
+    const tagPredicate = (tags) => ({ $eq: ['$it.tags[*]', { $seq: tags }] });
+    /** Compile once per distinct query document. */
+    function compiled(document) {
+        const key = JSON.stringify(document);
+        let run = queryCache.get(key);
+        if (run === undefined) {
+            run = compileQuery(document);
+            queryCache.set(key, run);
+        }
+        return run;
+    }
+    /**
+     * Filter a record set. With the query seam wired this is a real jaren
+     * query — one document, which a host that also wired `@jarenjs/db`
+     * could push down to SQL unchanged. With the seam empty it is tag
+     * match, and a caller predicate is REFUSED rather than ignored:
+     * silently dropping a filter would answer the wrong question with a
+     * straight face.
+     */
+    function filter(records, tags, where) {
+        const parts = [];
+        if (tags !== undefined && tags.length > 0)
+            parts.push(tagPredicate(tags));
+        if (where !== undefined && where !== null)
+            parts.push(where);
+        if (compileQuery === null) {
+            if (where !== undefined && where !== null) {
+                return {
+                    error: 'recall: a `where` predicate needs the compileQuery seam — '
+                        + 'inject compileJsonQuery from @jarenjs/json/query, or filter by tags only'
+                };
+            }
+            if (parts.length === 0)
+                return { value: records };
+            return {
+                value: records.filter((record) => (record.tags ?? []).some((tag) => tags.includes(tag)))
+            };
+        }
+        if (parts.length === 0)
+            return { value: records };
+        const predicate = parts.length === 1 ? parts[0] : { $and: parts };
+        try {
+            const run = compiled([{ $for: { it: '$[*]' }, $where: predicate, $return: '$it' }]);
+            return { value: run(records) };
+        }
+        catch (err) {
+            // a caller's predicate that does not compile is content, not a
+            // crash — same posture as a tool call the model got wrong
+            return { error: `recall: ${err?.reason ?? err?.message ?? err}` };
+        }
+    }
+    /**
+     * Retrieve by relevance: tag match, then recency, plus any predicate
+     * the seam can evaluate.
+     */
+    function retrieve(records, query = {}) {
+        const filtered = filter(records, query.tags, query.where);
+        if (filtered.error !== undefined)
+            return filtered;
+        const ordered = byRecency(filtered.value);
+        return typeof query.limit === 'number' ? ordered.slice(0, query.limit) : ordered;
+    }
+    /**
+     * The mixture refusal, in one place, so the sweep and an adapter that
+     * ranks for us word it identically and in the same order.
+     * @param found - every identity seen, in the order seen
+     * @param identity - the query embedder's
+     */
+    function refuseMixture(name, found, identity) {
+        if ([...found.values()].every((stored) => sameIdentity(stored, identity)))
+            return null;
+        return {
+            error: `${name}: near cannot rank across embedders — the ledger holds vectors from`
+                + ` ${[...found.keys()].join(', ')} and the query embedder is ${describeIdentity(identity)};`
+                + ' rank through the embedder that wrote them, or re-embed every record with one embedder'
+        };
+    }
+    /**
+     * The last two steps both ranked paths share: the kernels score every
+     * record the path selected, `minScore` filters and `limit` caps.
+     *
+     * The score is always `cosineSimilarity` over the record as stored —
+     * never a number an adapter handed back — so the two paths cannot
+     * report different similarities for the same record. Equal scores
+     * fall back to recency, then id.
+     * @param [ranking]
+     */
+    function rankedResult(records, probe, query, member, skipped, via, ranking = { algorithm: 'exact-cosine', exhaustive: true, candidateCount: records.length }) {
+        const ranked = records
+            .map((record) => ({ record, score: cosineSimilarity(probe, record.embedding) }))
+            .sort((a, b) => (b.score - a.score) || recencyOrder(a.record, b.record));
+        const kept = typeof query.minScore === 'number'
+            ? ranked.filter((entry) => entry.score >= query.minScore)
+            : ranked;
+        const capped = typeof query.limit === 'number' ? kept.slice(0, query.limit) : kept;
+        return {
+            [member]: capped.map((entry) => entry.record),
+            scores: capped.map((entry) => entry.score),
+            skipped,
+            via,
+            ranking,
+        };
+    }
+    /**
+     * Retrieve by meaning: the records that pass the tag/where filter AND
+     * carry a vector, ranked by cosine similarity to the embedded query.
+     *
+     * The refusals come before the arithmetic, in this order: `near` must
+     * be a non-empty string; the seam must be wired (the `compileQuery`
+     * precedent — an absent capability refuses, it never degrades); the
+     * filter must compile; the seam must answer; and every candidate's
+     * identity must equal the query embedder's. A mixture — two models in
+     * the ledger, or a ledger embedded by one model and queried through
+     * another — is refused naming every identity found, because ranking
+     * the matching subset would be a silent wrong answer. Records without
+     * a vector are not scored (a fabricated score poisons a ranking) and
+     * not hidden (a silent drop poisons trust): they are counted in
+     * `skipped`.
+     *
+     * TWO paths reach that answer and both report which one ran. By
+     * default the ledger reads every record under the prefix and ranks
+     * them here. An adapter that declares `rank` is asked instead — it
+     * knows how to narrow to the k best without handing over the whole
+     * ledger — and is held to exactly the same contract: it reports the
+     * distinct identities it holds so the mixture refusal is the ledger's,
+     * it reports what it skipped, and the kernels re-score what it
+     * returns. An adapter whose own ranking is approximate makes recall
+     * approximate: the ledger can re-score what it is handed, never
+     * recover a record the adapter did not return.
+     *
+     * `tags` and `where` narrow candidates the adapter knows nothing
+     * about, so a query carrying either takes the sweep.
+     *
+     * Ranking is `cosineSimilarity` from the kernels, descending; equal
+     * scores fall back to recency, then id, so the order is deterministic.
+     * `minScore` filters the ranked list; `limit` caps what survives.
+     * @param name - the entry point, for the refusal text
+     * @param member - the result member the ranked records go under
+     * @param prefix - the key space the records live under
+     */
+    async function rankNear(query, name, member, prefix) {
+        const { near } = query;
+        if (typeof near !== 'string' || near === '')
+            return { error: `${name}: near must be a non-empty string — the text to rank by meaning against` };
+        if (embedder === null)
+            return { error: `${name}: near ${SEAM_REFUSAL}` };
+        const narrowed = query.tags !== undefined || query.where !== undefined;
+        const delegated = typeof storage.rank === 'function' && !narrowed;
+        // the sweep reads first so that a `where` without the compileQuery
+        // seam still refuses before the embedder is called; the adapter path
+        // has no filter to compile
+        const filtered = delegated ? null : filter(await readAll(prefix), query.tags, query.where);
+        if (filtered !== null && filtered.error !== undefined)
+            return filtered;
+        const answer = await embedThrough([near]);
         if (answer.error !== undefined)
-          return { embedded, remaining: total - embedded, error: `embedMissing: the embedder seam failed — ${answer.error}` };
-        if (i === 0) {
-          // a wire client settles its width on its first reply; the
-          // check that could not run up front runs here, before a write
-          const refused = mixture(answer.identity);
-          if (refused !== null) return refused;
+            return { error: `${name}: the embedder seam failed — ${answer.error}` };
+        const probe = answer.vectors[0];
+        const identity = answer.identity;
+        if (delegated) {
+            const hits = await storage.rank({
+                prefix, vector: Array.from(probe), model: identity.model, dims: identity.dims,
+                limit: query.limit, minScore: query.minScore,
+            });
+            if (hits === null || typeof hits !== 'object' || !Array.isArray(hits.hits)
+                || !Array.isArray(hits.identities) || !Number.isSafeInteger(hits.skipped) || hits.skipped < 0) {
+                return {
+                    error: `${name}: the storage adapter's rank answered something other than`
+                        + ' { hits, skipped, identities } — a capability that cannot be trusted to report what it'
+                        + ' skipped is worse than one that is absent'
+                };
+            }
+            const ranking = hits.ranking === undefined ? { algorithm: 'legacy-exact', exhaustive: true, candidateCount: hits.hits.length } : hits.ranking;
+            if (ranking === null || typeof ranking !== 'object' || typeof ranking.algorithm !== 'string' || ranking.algorithm.trim() === ''
+                || typeof ranking.exhaustive !== 'boolean' || ranking.candidateCount !== hits.hits.length)
+                return { error: `${name}: invalid storage rank metadata` };
+            const keys = new Set();
+            for (const hit of hits.hits) {
+                if (typeof hit?.key !== 'string' || !hit.key.startsWith(prefix) || hit.key.length === prefix.length
+                    || keys.has(hit.key) || typeof hit.score !== 'number' || !Number.isFinite(hit.score))
+                    return { error: `${name}: invalid or duplicate storage rank candidate` };
+                keys.add(hit.key);
+            }
+            const found = new Map();
+            for (const stored of hits.identities) {
+                if (typeof stored?.model !== 'string' || stored.model === '' || !Number.isSafeInteger(stored.dims) || stored.dims < 1)
+                    return { error: `${name}: invalid storage rank identity` };
+                found.set(describeIdentity(stored), stored);
+            }
+            const records = await Promise.all(hits.hits.map((hit) => storage.get(hit.key)));
+            for (let i = 0; i < records.length; i++) {
+                const record = records[i];
+                if (record == null)
+                    continue; // Deleted between selection and read.
+                if (`${prefix}${record.id}` !== hits.hits[i].key || !sameIdentity(record.embeddedBy, identity))
+                    return { error: `${name}: storage rank candidate identity mismatch` };
+                if (!isVector(record.embedding, identity.dims))
+                    return { error: `${name}: invalid storage rank candidate vector` };
+                found.set(describeIdentity(record.embeddedBy), record.embeddedBy);
+            }
+            const refused = refuseMixture(name, found, identity);
+            if (refused !== null)
+                return refused;
+            // a key the adapter ranked and a read that no longer finds it is a
+            // record deleted in between, not a record without a vector
+            return rankedResult(records.filter((record) => record?.embedding !== undefined), probe, query, member, hits.skipped, 'adapter', { algorithm: ranking.algorithm, exhaustive: ranking.exhaustive, candidateCount: ranking.candidateCount });
         }
-        for (let j = 0; j < slice.length; j++) {
-          await storage.set(slice[j].key, withEmbedding(slice[j].record, answer.vectors[j], answer.identity));
-          embedded += 1;
+        // the identity check, before any math: every candidate's identity
+        // must be the query's, or nothing is ranked
+        const candidates = [];
+        const found = new Map();
+        let skipped = 0;
+        for (const record of filtered.value) {
+            if (record.embedding === undefined) {
+                skipped += 1;
+                continue;
+            }
+            found.set(describeIdentity(record.embeddedBy), record.embeddedBy);
+            candidates.push(record);
         }
-      }
-      return { embedded, remaining: total - embedded };
-    }, { prefixes: [KEYS.memory, KEYS.skill] });
-  }
-
-  //#endregion
-
-  //#region slots
-
-  /**
-   * Write an addressable blob. The metadata and the content go to
-   * separate keys, and only the metadata is ever handed around: that
-   * separation is the point of a slot, and it is what will let a request
-   * name a hundred of them without carrying any of their content.
-   * @param {string} name
-   * @param {string} content
-   * @param {{ kind?: string, at?: string, count?: number, pinned?: boolean }} [meta]
-   *   `count` is what the content HOLDS (lines, records, pieces) where
-   *   the writer knows it; absent where it does not, rather than guessed.
-   * @returns {Promise<LedgerSlot | LedgerRejection>}
-   */
-  function putSlot(name, content, meta = {}) {
-    return enqueue(async (storage) => {
-      const text = typeof content === 'string' ? content : JSON.stringify(content ?? null);
-      const slot = defined({
-        name,
-        kind: meta.kind ?? 'text',
-        size: text.length,
-        excerpt: excerpt(text, SLOT_EXCERPT_CHARS),
-        at: meta.at ?? now(),
-        count: meta.count,
-        pinned: meta.pinned,
-      });
-      const rejected = validate('slot', slot);
-      if (rejected !== null) return rejected;
-      if (options.archiveLimits && (slot.kind === 'agent-round' || slot.kind === 'agent-round-index')) {
-        const result = await storeArchive(storage, [{ slot, text }]);
-        return result.error ? result : slot;
-      }
-      await storage.set(`${KEYS.slotContent}${name}`, text);
-      await storage.set(`${KEYS.slot}${name}`, slot);
-      return slot;
-    }, options.archiveLimits && (meta.kind === 'agent-round' || meta.kind === 'agent-round-index') ? 'ai/state/' : { keys: [`${KEYS.slot}${name}`, `${KEYS.slotContent}${name}`, `ai/state/evicted/${name}`] });
-  }
-
-  /**
-   * A slot's metadata — never its content.
-   * @param {string} name
-   * @returns {Promise<LedgerSlot | null>}
-   */
-  async function getSlot(name) {
-    return (await storage.get(`${KEYS.slot}${name}`)) ?? null;
-  }
-
-  /**
-   * A slot's content, or undefined. The one call that returns the bytes.
-   * @param {string} name
-   * @returns {Promise<string | undefined | { status: 'evicted', name: string, bytes: number, reason: string }>}
-   */
-  async function readSlot(name) {
-    return (await storage.get(`${KEYS.slotContent}${name}`))
-      ?? (await storage.get(`ai/state/evicted/${name}`));
-  }
-
-  /**
-   * Every slot's metadata, newest first.
-   * @returns {Promise<LedgerSlot[]>}
-   */
-  async function listSlots() {
-    return byRecency(await readAll(KEYS.slot));
-  }
-
-  /**
-   * Remove a slot and its content. Answers whether one was there.
-   * @param {string} name
-   */
-  function deleteSlot(name) {
-    return enqueue(async (storage) => {
-      const key = `${KEYS.slot}${name}`;
-      const existed = (await storage.get(key)) !== undefined;
-      await storage.delete(key);
-      await storage.delete(`${KEYS.slotContent}${name}`);
-      await storage.delete(`ai/state/evicted/${name}`);
-      return existed;
-    }, { keys: [`${KEYS.slot}${name}`, `${KEYS.slotContent}${name}`, `ai/state/evicted/${name}`] });
-  }
-
-  /** Apply a complete archive plan only after retention accepts its exact bytes. */
-  async function storeArchive(view, entries, protection = {}) {
-    if (options.archiveLimits && typeof storage.mutate !== 'function' && !isAtomicView(storage))
-      return { error: 'archive budgets require atomic storage', code: 'ATOMIC_REQUIRED' };
-    const keys = await view.keys('ai/state/');
-    const current = Object.fromEntries(await Promise.all(keys.map(async (key) => [key, await view.get(key)])));
-    const planned = retainArchives(current, entries, options.archiveLimits ?? {}, protection);
-    if (planned.error) return planned;
-    for (const key of Object.keys(current)) if (!Object.hasOwn(planned.next, key)) await view.delete(key);
-    for (const [key, value] of Object.entries(planned.next))
-      if (JSON.stringify(value) !== JSON.stringify(current[key])) await view.set(key, value);
-    return { ok: true, retention: planned.report, footprint: planned.footprint };
-  }
-
-  /** Atomically store rounds and their index before removing any transcript.
-   * `protection.immutable` refuses address collisions, including within one batch;
-   * ordinary host-named archives retain their replacement behavior. */
-  function putArchive(entries, protection = {}) {
-    return enqueue(async (view) => {
-      const records = [];
-      for (const entry of entries) {
-        if ((entry.kind !== 'agent-round' && entry.kind !== 'agent-round-index') || typeof entry.text !== 'string')
-          return { error: 'archive entries require round/index kind and string content', code: 'ARCHIVE_INPUT' };
-        const held = await view.get(`${KEYS.slot}${entry.name}`);
-        const unchanged = held?.kind === entry.kind && await view.get(`${KEYS.slotContent}${entry.name}`) === entry.text;
-        records.push({ text: entry.text, slot: unchanged ? held : {
-          name: entry.name, kind: entry.kind, size: entry.text.length,
-          excerpt: excerpt(entry.text, SLOT_EXCERPT_CHARS), at: now(),
-          ...(held?.pinned === undefined ? {} : { pinned: held.pinned }),
-        } });
-      }
-      for (const entry of records) {
-        const rejected = validate('slot', entry.slot);
-        if (rejected) return rejected;
-      }
-      return storeArchive(view, records, protection);
-    });
-  }
-
-  /** Read the last durable archive decision and current host capability. */
-  async function retentionReport() {
-    return (await storage.get('ai/state/retention/archive')) ?? null;
-  }
-
-  /** Intentionally remove all conversation archives, tombstones and their report. */
-  function clearArchives(prefix = '') {
-    return enqueue(async (view) => {
-      for (const slot of await readAll(KEYS.slot, view)) {
-        if (!slot.name.startsWith(prefix) || (slot.kind !== 'agent-round' && slot.kind !== 'agent-round-index')) continue;
-        await view.delete(`${KEYS.slot}${slot.name}`);
-        await view.delete(`${KEYS.slotContent}${slot.name}`);
-      }
-      for (const key of await view.keys(`ai/state/evicted/${prefix}`)) await view.delete(key);
-      const report = await view.get('ai/state/retention/archive');
-      if (prefix === '') await view.delete('ai/state/retention/archive');
-      else if (report) await view.set('ai/state/retention/archive', { ...report,
-        evicted: report.evicted.filter((entry) => !entry.name.startsWith(prefix)),
-        written: report.written.filter((name) => !name.startsWith(prefix)) });
-      return true;
-    });
-  }
-
-  //#endregion
-
-  //#region snapshots
-
-  /**
-   * Record the whole state under a token. Cheap — a ledger is small JSON
-   * — and it is what makes an automatic write safe to accept: a bad one
-   * is undone by its token, with no human reading a diff. The token
-   * continues the sequence already in storage, exactly as an id does: a
-   * second ledger over the same adapter — the next process over a
-   * durable one — mints the next token, never the first one's again.
-   * @returns {Promise<string>} an opaque token for `rollback`
-   */
-  function snapshot() {
-    return enqueue(async (storage) => {
-      const keys = await storage.keys(STATE);
-      const entries = await Promise.all(keys.map(async (key) => [key, await storage.get(key)]));
-      const token = `snap-${seq(nextSequence(await storage.keys(SNAP)))}`;
-      await storage.set(`${SNAP}${token}`, entries);
-      return token;
-    });
-  }
-
-  /**
-   * Restore the state a token recorded. Every current state key is
-   * removed first, so a rollback is a restore and not a merge — a record
-   * created after the snapshot is gone afterwards, which is the only
-   * reading of "rollback" that can be relied on.
-   * @param {string} token
-   * @returns {Promise<true | { error: string }>}
-   */
-  function rollback(token) {
-    return enqueue(async (storage) => {
-      const entries = await storage.get(`${SNAP}${token}`);
-      if (entries === undefined) return { error: `unknown snapshot '${token}'` };
-      for (const key of await storage.keys(STATE)) await storage.delete(key);
-      for (const [key, value] of entries) await storage.set(key, value);
-      return true;
-    });
-  }
-
-  //#endregion
-
-  /**
-   * Commit guarded supplemental work against the exact document it read.
-   * Atomic adapters publish the snapshot and all writes together. A stale
-   * proposal is refused, never rebased onto different record indices.
-   * @param {any} expected
-   * @param {(ledger: any) => Promise<any>} work
-   */
-  function transaction(expected, work) {
-    return enqueue(async (view) => {
-      const scoped = createLedger({ ...options, artifacts: admittedArtifacts, storage: view });
-      const current = { goal: await scoped.getGoal(), memories: await scoped.listMemories(),
-        skills: await scoped.listSkills() };
-      if (JSON.stringify(current) !== JSON.stringify(expected))
-        return { error: 'the refinement was rejected: supplemental state changed; regenerate the proposal',
-          errors: [{ code: 'LEDGER_CONFLICT', docPath: '', message: 'supplemental state changed' }] };
-      const outcome = await work(scoped);
-      if (outcome?.error) throw Object.assign(new Error(outcome.error), { outcome });
-      return outcome;
-    });
-  }
-
-  return {
-    storageStatus: () => typeof storage.status === 'function' ? storage.status()
-      : { concurrency: typeof storage.mutate === 'function' ? 'atomic' : 'single-writer', durability: 'host-defined', error: null },
-    concurrency: typeof storage.mutate === 'function' ? 'atomic' : 'single-writer',
-    validate,
-    setGoal, getGoal, listArchivedGoals, recordProgress, setGoalStatus, composeGoal,
-    addMemory, getMemory, listMemories, deleteMemory,
-    addSkill, getSkill, listSkills, deleteSkill,
-    recall, recallSkills, embedMissing,
-    putSlot, getSlot, readSlot, listSlots, deleteSlot, putArchive, clearArchives, retentionReport,
-    snapshot, rollback, transaction,
-  };
+        const refused = refuseMixture(name, found, identity);
+        if (refused !== null)
+            return refused;
+        return rankedResult(candidates, probe, query, member, skipped, 'sweep');
+    }
+    async function recall(query = {}) {
+        return query.near === undefined
+            ? retrieve(await readAll(KEYS.memory), query)
+            : rankNear(query, 'recall', 'memories', KEYS.memory);
+    }
+    async function recallSkills(query = {}) {
+        return query.near === undefined
+            ? retrieve(await readAll(KEYS.skill), query)
+            : rankNear(query, 'recallSkills', 'skills', KEYS.skill);
+    }
+    /**
+     * The explicit sweep: embed every memory and skill that carries no
+     * vector, through the seam, in batches, inside the write chain — so no
+     * other write moves a record under it. Memories first, then skills,
+     * each in key order; `limit` caps how many records this run embeds,
+     * `batch` how many texts one seam call carries. Positive fractional batch sizes
+     * are floored to an integer of at least one.
+     *
+     * Honest about what it did not do. A second run over a swept ledger
+     * embeds zero and makes no seam call (the two-run check). A failing
+     * batch ends the run: the records embedded before it are written, the
+     * failed batch and everything after it stay un-embedded and are
+     * counted in `remaining`, and the error is surfaced once — never a
+     * throw that loses the batch, and never a per-record retry against a
+     * provider that just refused (the seam's own retry policy has already
+     * run). A ledger that already holds vectors under another identity is
+     * refused up front rather than turned into a mixture `recall({ near })`
+     * would then refuse.
+     * @param [options]
+     */
+    function embedMissing(options = {}) {
+        const batches = new Map();
+        return enqueue(async (storage) => {
+            const batch = typeof options.batch === 'number' && options.batch > 0 ? Math.max(1, Math.floor(options.batch)) : EMBED_BATCH;
+            const pending = [];
+            const held = new Map();
+            for (const memory of await readAll(KEYS.memory, storage)) {
+                if (memory.embedding === undefined)
+                    pending.push({ key: `${KEYS.memory}${memory.id}`, record: memory, text: memory.text });
+                else
+                    held.set(describeIdentity(memory.embeddedBy), memory.embeddedBy);
+            }
+            for (const skill of await readAll(KEYS.skill, storage)) {
+                if (skill.embedding === undefined)
+                    pending.push({ key: `${KEYS.skill}${skill.id}`, record: skill, text: skillText(skill) });
+                else
+                    held.set(describeIdentity(skill.embeddedBy), skill.embeddedBy);
+            }
+            const total = pending.length;
+            if (embedder === null)
+                return { embedded: 0, remaining: total, error: `embedMissing: ${SEAM_REFUSAL}` };
+            /** The mixture refusal, once the embedder's width is known. */
+            const mixture = (identity) => {
+                const foreign = [...held.keys()].filter((key) => !sameIdentity(held.get(key), identity));
+                return foreign.length === 0 ? null
+                    : {
+                        embedded: 0, remaining: total, error: 'embedMissing: would mix vector identities — the ledger'
+                            + ` already holds vectors from ${foreign.join(', ')} and the embedder is ${describeIdentity(identity)};`
+                            + ' sweep with the embedder that wrote them, or re-add those records without a vector first'
+                    };
+            };
+            if (embedder.dims !== undefined) {
+                const refused = mixture({ model: embedder.model, dims: embedder.dims });
+                if (refused !== null)
+                    return refused;
+            }
+            const todo = typeof options.limit === 'number' ? pending.slice(0, Math.max(0, Math.floor(options.limit))) : pending;
+            let embedded = 0;
+            for (let i = 0; i < todo.length; i += batch) {
+                const slice = todo.slice(i, i + batch);
+                const texts = slice.map((entry) => entry.text), key = JSON.stringify(texts);
+                if (!batches.has(key))
+                    batches.set(key, await embedThrough(texts));
+                const answer = batches.get(key);
+                if (answer.error !== undefined)
+                    return { embedded, remaining: total - embedded, error: `embedMissing: the embedder seam failed — ${answer.error}` };
+                if (i === 0) {
+                    // a wire client settles its width on its first reply; the
+                    // check that could not run up front runs here, before a write
+                    const refused = mixture(answer.identity);
+                    if (refused !== null)
+                        return refused;
+                }
+                for (let j = 0; j < slice.length; j++) {
+                    await storage.set(slice[j].key, withEmbedding(slice[j].record, answer.vectors[j], answer.identity));
+                    embedded += 1;
+                }
+            }
+            return { embedded, remaining: total - embedded };
+        }, { prefixes: [KEYS.memory, KEYS.skill] });
+    }
+    //#endregion
+    //#region slots
+    /**
+     * Write an addressable blob. The metadata and the content go to
+     * separate keys, and only the metadata is ever handed around: that
+     * separation is the point of a slot, and it is what will let a request
+     * name a hundred of them without carrying any of their content.
+     * @param [meta]
+     *   `count` is what the content HOLDS (lines, records, pieces) where
+     *   the writer knows it; absent where it does not, rather than guessed.
+     */
+    function putSlot(name, content, meta = {}) {
+        return enqueue(async (storage) => {
+            const text = typeof content === 'string' ? content : JSON.stringify(content ?? null);
+            const slot = defined({
+                name,
+                kind: meta.kind ?? 'text',
+                size: text.length,
+                excerpt: excerpt(text, SLOT_EXCERPT_CHARS),
+                at: meta.at ?? now(),
+                count: meta.count,
+                pinned: meta.pinned,
+            });
+            const rejected = validate('slot', slot);
+            if (rejected !== null)
+                return rejected;
+            if (options.archiveLimits && (slot.kind === 'agent-round' || slot.kind === 'agent-round-index')) {
+                const result = await storeArchive(storage, [{ slot, text }]);
+                return 'error' in result ? result : slot;
+            }
+            await storage.set(`${KEYS.slotContent}${name}`, text);
+            await storage.set(`${KEYS.slot}${name}`, slot);
+            return slot;
+        }, options.archiveLimits && (meta.kind === 'agent-round' || meta.kind === 'agent-round-index') ? 'ai/state/' : { keys: [`${KEYS.slot}${name}`, `${KEYS.slotContent}${name}`, `ai/state/evicted/${name}`] });
+    }
+    /**
+     * A slot's metadata — never its content.
+     */
+    async function getSlot(name) {
+        return (await storage.get(`${KEYS.slot}${name}`)) ?? null;
+    }
+    /**
+     * A slot's content, or undefined. The one call that returns the bytes.
+     */
+    async function readSlot(name) {
+        return (await storage.get(`${KEYS.slotContent}${name}`))
+            ?? (await storage.get(`ai/state/evicted/${name}`));
+    }
+    /**
+     * Every slot's metadata, newest first.
+     */
+    async function listSlots() {
+        return byRecency(await readAll(KEYS.slot));
+    }
+    /**
+     * Remove a slot and its content. Answers whether one was there.
+     */
+    function deleteSlot(name) {
+        return enqueue(async (storage) => {
+            const key = `${KEYS.slot}${name}`;
+            const existed = (await storage.get(key)) !== undefined;
+            await storage.delete(key);
+            await storage.delete(`${KEYS.slotContent}${name}`);
+            await storage.delete(`ai/state/evicted/${name}`);
+            return existed;
+        }, { keys: [`${KEYS.slot}${name}`, `${KEYS.slotContent}${name}`, `ai/state/evicted/${name}`] });
+    }
+    /** Apply a complete archive plan only after retention accepts its exact bytes. */
+    async function storeArchive(view, entries, protection = {}) {
+        if (options.archiveLimits && typeof storage.mutate !== 'function' && !isAtomicView(storage))
+            return { error: 'archive budgets require atomic storage', code: 'ATOMIC_REQUIRED' };
+        const keys = await view.keys('ai/state/');
+        const current = Object.fromEntries(await Promise.all(keys.map(async (key) => [key, await view.get(key)])));
+        const planned = retainArchives(current, entries, options.archiveLimits ?? {}, protection);
+        if ('error' in planned)
+            return planned;
+        for (const key of Object.keys(current))
+            if (!Object.hasOwn(planned.next, key))
+                await view.delete(key);
+        for (const [key, value] of Object.entries(planned.next))
+            if (JSON.stringify(value) !== JSON.stringify(current[key]))
+                await view.set(key, value);
+        return { ok: true, retention: planned.report, footprint: planned.footprint };
+    }
+    /** Atomically store rounds and their index before removing any transcript.
+     * `protection.immutable` refuses address collisions, including within one batch;
+     * ordinary host-named archives retain their replacement behavior. */
+    function putArchive(entries, protection = {}) {
+        return enqueue(async (view) => {
+            const records = [];
+            for (const entry of entries) {
+                if ((entry.kind !== 'agent-round' && entry.kind !== 'agent-round-index') || typeof entry.text !== 'string')
+                    return { error: 'archive entries require round/index kind and string content', code: 'ARCHIVE_INPUT' };
+                const held = await view.get(`${KEYS.slot}${entry.name}`);
+                const unchanged = held?.kind === entry.kind && await view.get(`${KEYS.slotContent}${entry.name}`) === entry.text;
+                records.push({
+                    text: entry.text, slot: unchanged ? held : {
+                        name: entry.name, kind: entry.kind, size: entry.text.length,
+                        excerpt: excerpt(entry.text, SLOT_EXCERPT_CHARS), at: now(),
+                        ...(held?.pinned === undefined ? {} : { pinned: held.pinned }),
+                    }
+                });
+            }
+            for (const entry of records) {
+                const rejected = validate('slot', entry.slot);
+                if (rejected)
+                    return rejected;
+            }
+            return storeArchive(view, records, protection);
+        });
+    }
+    /** Read the last durable archive decision and current host capability. */
+    async function retentionReport() {
+        return (await storage.get('ai/state/retention/archive')) ?? null;
+    }
+    /** Intentionally remove all conversation archives, tombstones and their report. */
+    function clearArchives(prefix = '') {
+        return enqueue(async (view) => {
+            for (const slot of await readAll(KEYS.slot, view)) {
+                if (!slot.name.startsWith(prefix) || (slot.kind !== 'agent-round' && slot.kind !== 'agent-round-index'))
+                    continue;
+                await view.delete(`${KEYS.slot}${slot.name}`);
+                await view.delete(`${KEYS.slotContent}${slot.name}`);
+            }
+            for (const key of await view.keys(`ai/state/evicted/${prefix}`))
+                await view.delete(key);
+            const report = await view.get('ai/state/retention/archive');
+            if (prefix === '')
+                await view.delete('ai/state/retention/archive');
+            else if (report)
+                await view.set('ai/state/retention/archive', {
+                    ...report,
+                    evicted: report.evicted.filter((entry) => !entry.name.startsWith(prefix)),
+                    written: report.written.filter((name) => !name.startsWith(prefix))
+                });
+            return true;
+        });
+    }
+    //#endregion
+    //#region snapshots
+    /**
+     * Record the whole state under a token. Cheap — a ledger is small JSON
+     * — and it is what makes an automatic write safe to accept: a bad one
+     * is undone by its token, with no human reading a diff. The token
+     * continues the sequence already in storage, exactly as an id does: a
+     * second ledger over the same adapter — the next process over a
+     * durable one — mints the next token, never the first one's again.
+     * @returns an opaque token for `rollback`
+     */
+    function snapshot() {
+        return enqueue(async (storage) => {
+            const keys = await storage.keys(STATE);
+            const entries = await Promise.all(keys.map(async (key) => [key, await storage.get(key)]));
+            const token = `snap-${seq(nextSequence(await storage.keys(SNAP)))}`;
+            await storage.set(`${SNAP}${token}`, entries);
+            return token;
+        });
+    }
+    /**
+     * Restore the state a token recorded. Every current state key is
+     * removed first, so a rollback is a restore and not a merge — a record
+     * created after the snapshot is gone afterwards, which is the only
+     * reading of "rollback" that can be relied on.
+     */
+    function rollback(token) {
+        return enqueue(async (storage) => {
+            const entries = await storage.get(`${SNAP}${token}`);
+            if (entries === undefined)
+                return { error: `unknown snapshot '${token}'` };
+            for (const key of await storage.keys(STATE))
+                await storage.delete(key);
+            for (const [key, value] of entries)
+                await storage.set(key, value);
+            return true;
+        });
+    }
+    //#endregion
+    /**
+     * Commit guarded supplemental work against the exact document it read.
+     * Atomic adapters publish the snapshot and all writes together. A stale
+     * proposal is refused, never rebased onto different record indices.
+     */
+    function transaction(expected, work) {
+        return enqueue(async (view) => {
+            const scoped = createLedger({ ...options, artifacts: admittedArtifacts, storage: view });
+            const current = {
+                goal: await scoped.getGoal(), memories: await scoped.listMemories(),
+                skills: await scoped.listSkills()
+            };
+            if (JSON.stringify(current) !== JSON.stringify(expected))
+                return {
+                    error: 'the refinement was rejected: supplemental state changed; regenerate the proposal',
+                    errors: [{ code: 'LEDGER_CONFLICT', docPath: '', message: 'supplemental state changed' }]
+                };
+            const outcome = await work(scoped);
+            if (outcome?.error)
+                throw Object.assign(new Error(outcome.error), { outcome });
+            return outcome;
+        });
+    }
+    return {
+        storageStatus: () => typeof storage.status === 'function' ? storage.status()
+            : { concurrency: typeof storage.mutate === 'function' ? 'atomic' : 'single-writer', durability: 'host-defined', error: null },
+        concurrency: typeof storage.mutate === 'function' ? 'atomic' : 'single-writer',
+        validate,
+        setGoal, getGoal, listArchivedGoals, recordProgress, setGoalStatus, composeGoal,
+        addMemory, getMemory, listMemories, deleteMemory,
+        addSkill, getSkill, listSkills, deleteSkill,
+        recall, recallSkills, embedMissing,
+        putSlot, getSlot, readSlot, listSlots, deleteSlot, putArchive, clearArchives, retentionReport,
+        snapshot, rollback, transaction,
+    };
 }