@tangleai/context 0.21.1 → 0.25.0

package/src/schemas/patch.d.ts

@@ -1,12 +1,38 @@
 /**
- * Path-discriminated RFC 6902 operations. Provider decoding uses this same
- * schema in non-strict mode; local validation remains authoritative.
- * @param {{ maxOps?: number }} [options]
- * @returns {any}
+ * The refinement patch: a deliberately small subset of RFC 6902.
+ *
+ * A model that has finished a run is asked what it learned. The unsafe
+ * answer is a rewritten prompt or a restated set of memories — a
+ * rewrite is unreviewable, unbounded, and a model asked to restate what
+ * it remembers will drift it. The safe answer is a PATCH: small enough
+ * to read, addressed enough to audit, and reversible with a snapshot.
+ *
+ * Three restrictions, and each one exists because the alternative fails
+ * on the tier this package targets:
+ *
+ *  - **`path` is a pattern, not a free string.** It matches exactly the
+ *    supplemental subtree — append or replace a memory, append or
+ *    replace a skill, append one progress entry — and nothing else. The
+ *    base system prompt is not merely undocumented as a target, it is
+ *    unaddressable: it is not in the document a refinement is applied
+ *    to, and no path that could reach it matches this pattern. That is
+ *    D5 asserted rather than described.
+ *  - **`op` is three verbs.** `move`, `copy` and `test` are legal RFC
+ *    6902 and useless here; every one of them is another shape a small
+ *    model can get subtly wrong, and none of them expresses anything
+ *    `add`/`replace`/`remove` cannot.
+ *  - **The number of operations is capped.** A refinement is meant to be
+ *    a few evidence-backed updates. A patch of forty operations is a
+ *    rewrite wearing a patch's clothes, and it is also the shape that
+ *    makes a repair round useless — the model cannot tell which of forty
+ *    operations the error came from.
+ *
+ * `value` carries no `id` and no `at` on purpose. Identity and time are
+ * the ledger's to mint: a model that could choose an id could overwrite
+ * a record it never read, and a model that could choose a timestamp
+ * could put a memory in front of one that came later — the recency
+ * ordering everything downstream depends on is not the model's to set.
  */
-export function refinementPatchSchema(options?: {
-    maxOps?: number;
-}): any;
 /**
  * Where a refinement may write. Anchored, and read as: append or address
  * one memory, append or address one skill, append one progress entry.
@@ -16,20 +42,28 @@ export function refinementPatchSchema(options?: {
  * a memory is revised by replacing it whole, with fresh evidence, so
  * that every stored record was validated as a whole exactly once.
  */
-export const REFINEMENT_PATH_PATTERN: "^(/memories/(-|[0-9]+)|/skills/(-|[0-9]+)|/goal/progress/-)$";
+export declare const REFINEMENT_PATH_PATTERN = "^(/memories/(-|[0-9]+)|/skills/(-|[0-9]+)|/goal/progress/-)$";
 /** The default cap on operations per refinement. */
-export const DEFAULT_MAX_OPS: 6;
-export namespace MEMORY_PROPOSAL_SCHEMA {
-    let type: string;
-    namespace properties {
-        namespace text {
-            let type_1: string;
-            export { type_1 as type };
-            export let minLength: number;
-            export let description: string;
-        }
-        namespace evidence {
-            let anyOf: ({
+export declare const DEFAULT_MAX_OPS = 6;
+/**
+ * A proposed memory. `evidence` is required here AND by the ledger's own
+ * schema — the same requirement twice, on purpose: this copy is what
+ * constrains decoding (a model generating against it tends to write the
+ * evidence rather than be corrected into it), and the ledger's copy is
+ * what makes the rule true even for a patch that never went near a
+ * model. It is the mechanism that stops a refinement laundering a
+ * hallucination into durable state.
+ */
+export declare const MEMORY_PROPOSAL_SCHEMA: {
+    type: string;
+    properties: {
+        text: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        evidence: {
+            anyOf: ({
                 type: "object";
                 properties: Record<string, object>;
                 required: string[];
@@ -38,92 +72,72 @@ export namespace MEMORY_PROPOSAL_SCHEMA {
                 type: string;
                 minLength: number;
             })[];
-        }
-        namespace tags {
-            let type_2: string;
-            export { type_2 as type };
-            export namespace items {
-                let type_3: string;
-                export { type_3 as type };
-                let minLength_1: number;
-                export { minLength_1 as minLength };
-            }
-        }
-    }
-    let required: string[];
-    let additionalProperties: boolean;
-}
-export namespace SKILL_PROPOSAL_SCHEMA {
-    let type_4: string;
-    export { type_4 as type };
-    export namespace properties_1 {
-        namespace name {
-            let type_5: string;
-            export { type_5 as type };
-            let minLength_2: number;
-            export { minLength_2 as minLength };
-        }
-        namespace when {
-            let type_6: string;
-            export { type_6 as type };
-            let minLength_3: number;
-            export { minLength_3 as minLength };
-            let description_1: string;
-            export { description_1 as description };
-        }
-        namespace instructions {
-            let type_7: string;
-            export { type_7 as type };
-            let minLength_4: number;
-            export { minLength_4 as minLength };
-            let description_2: string;
-            export { description_2 as description };
-        }
-        namespace tools {
-            let type_8: string;
-            export { type_8 as type };
-            export namespace items_1 {
-                let type_9: string;
-                export { type_9 as type };
-                let minLength_5: number;
-                export { minLength_5 as minLength };
-            }
-            export { items_1 as items };
-        }
-    }
-    export { properties_1 as properties };
-    let required_1: string[];
-    export { required_1 as required };
-    let additionalProperties_1: boolean;
-    export { additionalProperties_1 as additionalProperties };
-}
-export namespace PROGRESS_PROPOSAL_SCHEMA {
-    let type_10: string;
-    export { type_10 as type };
-    export namespace properties_2 {
-        export namespace note {
-            let type_11: string;
-            export { type_11 as type };
-            let minLength_6: number;
-            export { minLength_6 as minLength };
-            let description_3: string;
-            export { description_3 as description };
-        }
-        export namespace evidence_1 {
-            let type_12: string;
-            export { type_12 as type };
-            let minLength_7: number;
-            export { minLength_7 as minLength };
-            let description_4: string;
-            export { description_4 as description };
-        }
-        export { evidence_1 as evidence };
-    }
-    export { properties_2 as properties };
-    let required_2: string[];
-    export { required_2 as required };
-    let additionalProperties_2: boolean;
-    export { additionalProperties_2 as additionalProperties };
-}
+        };
+        tags: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** A proposed skill: when it applies, what to do, which tools it needs. */
+export declare const SKILL_PROPOSAL_SCHEMA: {
+    type: string;
+    properties: {
+        name: {
+            type: string;
+            minLength: number;
+        };
+        when: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        instructions: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        tools: {
+            type: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** A proposed progress entry against the active goal. */
+export declare const PROGRESS_PROPOSAL_SCHEMA: {
+    type: string;
+    properties: {
+        note: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        evidence: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/**
+ * Path-discriminated RFC 6902 operations. Provider decoding uses this same
+ * schema in non-strict mode; local validation remains authoritative.
+ * @param [options]
+ */
+export declare function refinementPatchSchema(options?: {
+    maxOps?: number;
+}): any;
 /** The full schema used for handwritten and generated proposals alike. */
-export const REFINEMENT_PATCH_SCHEMA: any;
+export declare const REFINEMENT_PATCH_SCHEMA: any;

package/src/schemas/patch.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The refinement patch: a deliberately small subset of RFC 6902.
  *
@@ -34,9 +33,7 @@
  * could put a memory in front of one that came later — the recency
  * ordering everything downstream depends on is not the model's to set.
  */
-
-import { CLAIM_EVIDENCE_SCHEMA } from './evidence.js';
-
+import { CLAIM_EVIDENCE_SCHEMA } from "./evidence.js";
 /**
  * Where a refinement may write. Anchored, and read as: append or address
  * one memory, append or address one skill, append one progress entry.
@@ -46,12 +43,9 @@ import { CLAIM_EVIDENCE_SCHEMA } from './evidence.js';
  * a memory is revised by replacing it whole, with fresh evidence, so
  * that every stored record was validated as a whole exactly once.
  */
-export const REFINEMENT_PATH_PATTERN =
-  '^(/memories/(-|[0-9]+)|/skills/(-|[0-9]+)|/goal/progress/-)$';
-
+export const REFINEMENT_PATH_PATTERN = '^(/memories/(-|[0-9]+)|/skills/(-|[0-9]+)|/goal/progress/-)$';
 /** The default cap on operations per refinement. */
 export const DEFAULT_MAX_OPS = 6;
-
 /**
  * A proposed memory. `evidence` is required here AND by the ledger's own
  * schema — the same requirement twice, on purpose: this copy is what
@@ -62,74 +56,75 @@ export const DEFAULT_MAX_OPS = 6;
  * hallucination into durable state.
  */
 export const MEMORY_PROPOSAL_SCHEMA = {
-  type: 'object',
-  properties: {
-    text: { type: 'string', minLength: 1, description: 'The fact worth carrying, in one sentence.' },
-    evidence: { anyOf: [{ type: 'string', minLength: 1 }, CLAIM_EVIDENCE_SCHEMA] },
-    tags: { type: 'array', items: { type: 'string', minLength: 1 } },
-  },
-  required: ['text', 'evidence'],
-  additionalProperties: false,
+    type: 'object',
+    properties: {
+        text: { type: 'string', minLength: 1, description: 'The fact worth carrying, in one sentence.' },
+        evidence: { anyOf: [{ type: 'string', minLength: 1 }, CLAIM_EVIDENCE_SCHEMA] },
+        tags: { type: 'array', items: { type: 'string', minLength: 1 } },
+    },
+    required: ['text', 'evidence'],
+    additionalProperties: false,
 };
-
 /** A proposed skill: when it applies, what to do, which tools it needs. */
 export const SKILL_PROPOSAL_SCHEMA = {
-  type: 'object',
-  properties: {
-    name: { type: 'string', minLength: 1 },
-    when: { type: 'string', minLength: 1, description: 'The situation this recipe applies to.' },
-    instructions: { type: 'string', minLength: 1, description: 'The steps, concretely.' },
-    tools: { type: 'array', items: { type: 'string', minLength: 1 } },
-  },
-  required: ['name', 'when', 'instructions'],
-  additionalProperties: false,
+    type: 'object',
+    properties: {
+        name: { type: 'string', minLength: 1 },
+        when: { type: 'string', minLength: 1, description: 'The situation this recipe applies to.' },
+        instructions: { type: 'string', minLength: 1, description: 'The steps, concretely.' },
+        tools: { type: 'array', items: { type: 'string', minLength: 1 } },
+    },
+    required: ['name', 'when', 'instructions'],
+    additionalProperties: false,
 };
-
 /** A proposed progress entry against the active goal. */
 export const PROGRESS_PROPOSAL_SCHEMA = {
-  type: 'object',
-  properties: {
-    note: { type: 'string', minLength: 1, description: 'What was done or established.' },
-    evidence: { type: 'string', minLength: 1, description: 'What in the run establishes it.' },
-  },
-  required: ['note', 'evidence'],
-  additionalProperties: false,
+    type: 'object',
+    properties: {
+        note: { type: 'string', minLength: 1, description: 'What was done or established.' },
+        evidence: { type: 'string', minLength: 1, description: 'What in the run establishes it.' },
+    },
+    required: ['note', 'evidence'],
+    additionalProperties: false,
 };
-
 /**
  * Path-discriminated RFC 6902 operations. Provider decoding uses this same
  * schema in non-strict mode; local validation remains authoritative.
- * @param {{ maxOps?: number }} [options]
- * @returns {any}
+ * @param [options]
  */
 export function refinementPatchSchema(options = {}) {
-  const maxOps = options.maxOps ?? DEFAULT_MAX_OPS;
-  if (!Number.isSafeInteger(maxOps) || maxOps < 0)
-    throw new TypeError('maxOps must be a non-negative safe integer');
-  const branch = (op, pattern, value) => ({
-    type: 'object',
-    properties: { op: { enum: op }, path: { type: 'string', pattern },
-      ...(value ? { value } : {}) },
-    required: value ? ['op', 'path', 'value'] : ['op', 'path'],
-    additionalProperties: false,
-  });
-  const index = '(0|[1-9][0-9]*)';
-  return {
-    $id: 'https://jarenjs.github.io/schemas/ai/refinement-patch.json',
-    title: 'Refinement patch',
-    type: 'array', maxItems: maxOps,
-    $defs: { memory: MEMORY_PROPOSAL_SCHEMA, skill: SKILL_PROPOSAL_SCHEMA,
-      progress: PROGRESS_PROPOSAL_SCHEMA },
-    items: { oneOf: [
-      ...[['memories', 'memory'], ['skills', 'skill']].flatMap(([path, kind]) => [
-        branch(['add'], `^/${path}/(-|${index})$`, { $ref: `#/$defs/${kind}` }),
-        branch(['replace'], `^/${path}/${index}$`, { $ref: `#/$defs/${kind}` }),
-        branch(['remove'], `^/${path}/${index}$`, null),
-      ]),
-      branch(['add'], '^/goal/progress/-$', { $ref: '#/$defs/progress' }),
-    ] },
-  };
+    const maxOps = options.maxOps ?? DEFAULT_MAX_OPS;
+    if (!Number.isSafeInteger(maxOps) || maxOps < 0)
+        throw new TypeError('maxOps must be a non-negative safe integer');
+    const branch = (op, pattern, value) => ({
+        type: 'object',
+        properties: {
+            op: { enum: op }, path: { type: 'string', pattern },
+            ...(value ? { value } : {})
+        },
+        required: value ? ['op', 'path', 'value'] : ['op', 'path'],
+        additionalProperties: false,
+    });
+    const index = '(0|[1-9][0-9]*)';
+    return {
+        $id: 'https://jarenjs.github.io/schemas/ai/refinement-patch.json',
+        title: 'Refinement patch',
+        type: 'array', maxItems: maxOps,
+        $defs: {
+            memory: MEMORY_PROPOSAL_SCHEMA, skill: SKILL_PROPOSAL_SCHEMA,
+            progress: PROGRESS_PROPOSAL_SCHEMA
+        },
+        items: {
+            oneOf: [
+                ...[['memories', 'memory'], ['skills', 'skill']].flatMap(([path, kind]) => [
+                    branch(['add'], `^/${path}/(-|${index})$`, { $ref: `#/$defs/${kind}` }),
+                    branch(['replace'], `^/${path}/${index}$`, { $ref: `#/$defs/${kind}` }),
+                    branch(['remove'], `^/${path}/${index}$`, null),
+                ]),
+                branch(['add'], '^/goal/progress/-$', { $ref: '#/$defs/progress' }),
+            ]
+        },
+    };
 }
-
 /** The full schema used for handwritten and generated proposals alike. */
 export const REFINEMENT_PATCH_SCHEMA = refinementPatchSchema();

package/src/storage/memory.d.ts

@@ -70,17 +70,12 @@
  * copies: a caller that mutates what it stored — or what it read —
  * cannot reach inside the ledger.
  *
- * @param {Map<string, string>} [backing] - an existing map to adopt
- * @returns {{ get: (key: string) => Promise<any>,
- *   set: (key: string, value: any) => Promise<void>,
- *   delete: (key: string) => Promise<void>,
- *   keys: (prefix?: string) => Promise<string[]>,
- *   mutate: import('./transaction.js').StorageMutation }}
+ * @param [backing] - an existing map to adopt
  */
-export function createMemoryStorage(backing?: Map<string, string>): {
+export declare function createMemoryStorage(backing?: Map<string, string>): {
     get: (key: string) => Promise<any>;
     set: (key: string, value: any) => Promise<void>;
     delete: (key: string) => Promise<void>;
     keys: (prefix?: string) => Promise<string[]>;
-    mutate: import("./transaction.js").StorageMutation;
+    mutate: import('./transaction.ts').StorageMutation;
 };

package/src/storage/memory.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The in-memory storage adapter: the ledger's default, and the reason
  * `createLedger()` works with no arguments at all.
@@ -58,7 +57,6 @@
  * `via: 'sweep'` — which is why the in-memory adapter below does not
  * grow it.
  */
-
 /**
  * Create an in-memory adapter with JSON-value semantics: every value is
  * serialized on the way in and parsed on the way out, so what survives
@@ -72,47 +70,47 @@
  * copies: a caller that mutates what it stored — or what it read —
  * cannot reach inside the ledger.
  *
- * @param {Map<string, string>} [backing] - an existing map to adopt
- * @returns {{ get: (key: string) => Promise<any>,
- *   set: (key: string, value: any) => Promise<void>,
- *   delete: (key: string) => Promise<void>,
- *   keys: (prefix?: string) => Promise<string[]>,
- *   mutate: import('./transaction.js').StorageMutation }}
+ * @param [backing] - an existing map to adopt
  */
 export function createMemoryStorage(backing = new Map()) {
-  return {
-    mutate: async (prefix, transform) => {
-      const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
-        : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
-      // No await between read and publication: even separate adapters sharing
-      // this map observe one complete mutation. Serialize every value first.
-      const current = Object.fromEntries([...backing].filter(([key]) => matches(key))
-        .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
-        .map(([key, raw]) => [key, JSON.parse(raw)]));
-      const outcome = transform(current);
-      if (!outcome || typeof outcome.then === 'function') throw new TypeError('mutate callback must be synchronous');
-      if (outcome.next !== undefined) {
-        const entries = Object.entries(outcome.next).map(([key, value]) => {
-          if (!matches(key)) throw new TypeError('mutation escaped its namespace');
-          return [key, JSON.stringify(value)];
-        });
-        for (const key of backing.keys()) if (matches(key)) backing.delete(key);
-        for (const [key, raw] of entries) backing.set(key, raw);
-      }
-      return outcome.result;
-    },
-    get: async (key) => {
-      const raw = backing.get(key);
-      return raw === undefined ? undefined : JSON.parse(raw);
-    },
-    set: async (key, value) => {
-      backing.set(key, JSON.stringify(value));
-    },
-    delete: async (key) => {
-      backing.delete(key);
-    },
-    keys: async (prefix = '') => [...backing.keys()]
-      .filter((key) => key.startsWith(prefix))
-      .sort(),
-  };
+    return {
+        mutate: async (prefix, transform) => {
+            const matches = (key) => typeof prefix === 'string' ? key.startsWith(prefix)
+                : (prefix.keys ?? []).includes(key) || (prefix.prefixes ?? []).some((part) => key.startsWith(part));
+            // No await between read and publication: even separate adapters sharing
+            // this map observe one complete mutation. Serialize every value first.
+            const current = Object.fromEntries([...backing].filter(([key]) => matches(key))
+                .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+                .map(([key, raw]) => [key, JSON.parse(raw)]));
+            const outcome = transform(current);
+            if (!outcome || typeof outcome.then === 'function')
+                throw new TypeError('mutate callback must be synchronous');
+            if (outcome.next !== undefined) {
+                const entries = Object.entries(outcome.next).map(([key, value]) => {
+                    if (!matches(key))
+                        throw new TypeError('mutation escaped its namespace');
+                    return [key, JSON.stringify(value)];
+                });
+                for (const key of backing.keys())
+                    if (matches(key))
+                        backing.delete(key);
+                for (const [key, raw] of entries)
+                    backing.set(key, raw);
+            }
+            return outcome.result;
+        },
+        get: async (key) => {
+            const raw = backing.get(key);
+            return raw === undefined ? undefined : JSON.parse(raw);
+        },
+        set: async (key, value) => {
+            backing.set(key, JSON.stringify(value));
+        },
+        delete: async (key) => {
+            backing.delete(key);
+        },
+        keys: async (prefix = '') => [...backing.keys()]
+            .filter((key) => key.startsWith(prefix))
+            .sort(),
+    };
 }

package/src/storage/slot.d.ts

@@ -3,10 +3,9 @@
  * slot that swallows errors cannot promise durability; status says unverified.
  * Web Locks serialize tabs using the same slot name. Without them the adapter
  * explicitly exposes only the four-method, single-writer contract.
- * @param {{ read: () => any, write: (data: any) => any, key?: string, reliable?: boolean }} slot
- * @param {{ locks?: any, name?: string, singleWriter?: boolean }} [options]
+ * @param [options]
  */
-export function createSlotLedgerStorage(slot: {
+export declare function createSlotLedgerStorage(slot: {
     read: () => any;
     write: (data: any) => any;
     key?: string;
@@ -26,5 +25,5 @@ export function createSlotLedgerStorage(slot: {
     set: (key: any, value: any) => Promise<any>;
     delete: (key: any) => Promise<any>;
     keys: (prefix?: string) => Promise<string[]>;
-    mutate?: (prefix: any, transform: any) => Promise<any>;
+    mutate?: ((prefix: any, transform: any) => Promise<any>) | undefined;
 };