@tangleai/context 0.21.1 → 0.25.0

package/src/schemas/ledger.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The ledger's four record schemas, as plain JSON Schema documents
  * compiled by `JarenValidator` when a ledger is constructed. A malformed
@@ -17,9 +16,7 @@
  * memory or skill may be proposed by a model (and must therefore carry
  * evidence), a slot is written by the harness and never proposed.
  */
-
-import { CLAIM_EVIDENCE_SCHEMA } from './evidence.js';
-
+import { CLAIM_EVIDENCE_SCHEMA } from "./evidence.js";
 /**
  * A timestamp property: RFC 3339, the suite's only date representation.
  *
@@ -38,14 +35,12 @@ import { CLAIM_EVIDENCE_SCHEMA } from './evidence.js';
  * offset rather than banning it.
  */
 const AT = {
-  type: 'string',
-  format: 'date-time',
-  pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$',
+    type: 'string',
+    format: 'date-time',
+    pattern: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$',
 };
-
 /** A non-empty identifier. */
 const ID = { type: 'string', minLength: 1 };
-
 /**
  * A stored embedding: a plain array of numbers, never a typed array. A
  * `Float32Array` does not survive the storage boundary — JSON serializes
@@ -55,7 +50,6 @@ const ID = { type: 'string', minLength: 1 };
  * `@jarenjs/core/vector` in the same gate.
  */
 const EMBEDDING = { type: 'array', items: { type: 'number' }, minItems: 1 };
-
 /**
  * A vector's identity: which model produced it, at what width. Vectors
  * from two models are pairwise meaningless and compare into plausible
@@ -63,15 +57,14 @@ const EMBEDDING = { type: 'array', items: { type: 'number' }, minItems: 1 };
  * refuses to mix two.
  */
 const EMBEDDED_BY = {
-  type: 'object',
-  properties: {
-    model: { type: 'string', minLength: 1 },
-    dims: { type: 'integer', minimum: 1 },
-  },
-  required: ['model', 'dims'],
-  additionalProperties: false,
+    type: 'object',
+    properties: {
+        model: { type: 'string', minLength: 1 },
+        dims: { type: 'integer', minimum: 1 },
+    },
+    required: ['model', 'dims'],
+    additionalProperties: false,
 };
-
 /**
  * `embedding` and `embeddedBy` are both-or-neither, and nothing requires
  * them: an un-embedded record is exactly as valid as it ever was. The
@@ -81,7 +74,6 @@ const EMBEDDED_BY = {
  * 2019-09 and later says the same thing).
  */
 const EMBEDDING_PAIR = { embedding: ['embeddedBy'], embeddedBy: ['embedding'] };
-
 /**
  * One active objective. Singular by construction: a second `setGoal`
  * supersedes this one and archives it, so "what am I doing" has exactly
@@ -92,49 +84,58 @@ const EMBEDDING_PAIR = { embedding: ['embeddedBy'], embeddedBy: ['embedding'] };
  * progress entry or decides when a goal is done.
  */
 export const GOAL_SCHEMA = {
-  $id: 'https://jarenjs.github.io/schemas/ai/ledger-goal.json',
-  type: 'object',
-  properties: {
-    objective: { type: 'string', minLength: 1 },
-    createdAt: AT,
-    status: { enum: ['active', 'done', 'abandoned', 'superseded'] },
-    progress: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          at: AT,
-          id: ID,
-          note: { type: 'string', minLength: 1 },
-          // an unevidenced progress note is a claim, not a record
-          evidence: { type: 'string', minLength: 1 },
+    $id: 'https://jarenjs.github.io/schemas/ai/ledger-goal.json',
+    type: 'object',
+    properties: {
+        objective: { type: 'string', minLength: 1 },
+        createdAt: AT,
+        status: { enum: ['active', 'done', 'abandoned', 'superseded'] },
+        progress: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    at: AT,
+                    id: ID,
+                    note: { type: 'string', minLength: 1 },
+                    // an unevidenced progress note is a claim, not a record
+                    evidence: { type: 'string', minLength: 1 },
+                },
+                required: ['at', 'note', 'evidence'],
+                additionalProperties: false,
+            },
+        },
+        checkpoint: {
+            type: 'object',
+            properties: {
+                version: { const: 1 },
+                records: {
+                    type: 'array', items: {
+                        type: 'object', properties: {
+                            note: ID, evidence: ID,
+                        }, required: ['note', 'evidence'], additionalProperties: false
+                    }
+                },
+                sources: {
+                    type: 'array', items: {
+                        type: 'object', properties: {
+                            id: ID, at: AT, record: { type: 'integer', minimum: 0 },
+                        }, required: ['id', 'at', 'record'], additionalProperties: false
+                    }
+                },
+            },
+            required: ['version', 'records', 'sources'], additionalProperties: false,
+        },
+        retention: {
+            type: 'object', properties: {
+                version: { const: 1 }, reason: { const: 'goal-budget' },
+                retired: { type: 'array', items: ID, uniqueItems: true },
+            }, required: ['version', 'reason', 'retired'], additionalProperties: false
         },
-        required: ['at', 'note', 'evidence'],
-        additionalProperties: false,
-      },
-    },
-    checkpoint: {
-      type: 'object',
-      properties: {
-        version: { const: 1 },
-        records: { type: 'array', items: { type: 'object', properties: {
-          note: ID, evidence: ID,
-        }, required: ['note', 'evidence'], additionalProperties: false } },
-        sources: { type: 'array', items: { type: 'object', properties: {
-          id: ID, at: AT, record: { type: 'integer', minimum: 0 },
-        }, required: ['id', 'at', 'record'], additionalProperties: false } },
-      },
-      required: ['version', 'records', 'sources'], additionalProperties: false,
     },
-    retention: { type: 'object', properties: {
-      version: { const: 1 }, reason: { const: 'goal-budget' },
-      retired: { type: 'array', items: ID, uniqueItems: true },
-    }, required: ['version', 'reason', 'retired'], additionalProperties: false },
-  },
-  required: ['objective', 'createdAt', 'status', 'progress'],
-  additionalProperties: false,
+    required: ['objective', 'createdAt', 'status', 'progress'],
+    additionalProperties: false,
 };
-
 /**
  * A fact worth carrying past this context window.
  *
@@ -150,66 +151,63 @@ export const GOAL_SCHEMA = {
  * before, and ranked recall reports it as skipped rather than scoring it.
  */
 export const MEMORY_SCHEMA = {
-  $id: 'https://jarenjs.github.io/schemas/ai/ledger-memory.json',
-  type: 'object',
-  properties: {
-    id: ID,
-    text: { type: 'string', minLength: 1 },
-    evidence: { anyOf: [{ type: 'string', minLength: 1 }, CLAIM_EVIDENCE_SCHEMA] },
-    tags: { type: 'array', items: { type: 'string', minLength: 1 } },
-    at: AT,
-    // OPTIONAL, as a pair: the vector `recall({ near })` ranks by, and
-    // the identity that makes it comparable
-    embedding: EMBEDDING,
-    embeddedBy: EMBEDDED_BY,
-  },
-  required: ['id', 'text', 'evidence', 'tags', 'at'],
-  dependencies: EMBEDDING_PAIR,
-  additionalProperties: false,
+    $id: 'https://jarenjs.github.io/schemas/ai/ledger-memory.json',
+    type: 'object',
+    properties: {
+        id: ID,
+        text: { type: 'string', minLength: 1 },
+        evidence: { anyOf: [{ type: 'string', minLength: 1 }, CLAIM_EVIDENCE_SCHEMA] },
+        tags: { type: 'array', items: { type: 'string', minLength: 1 } },
+        at: AT,
+        // OPTIONAL, as a pair: the vector `recall({ near })` ranks by, and
+        // the identity that makes it comparable
+        embedding: EMBEDDING,
+        embeddedBy: EMBEDDED_BY,
+    },
+    required: ['id', 'text', 'evidence', 'tags', 'at'],
+    dependencies: EMBEDDING_PAIR,
+    additionalProperties: false,
 };
-
 /**
  * A reusable recipe: when it applies, what to do, and which tools it
  * needs. Retrieved like a memory and composed into a system prompt by
  * whatever drives the agent — the ledger stores it and nothing more.
  */
 export const PROGRAM_SKILL_SCHEMA = {
-  type: 'object',
-  properties: {
-    version: { const: 1 },
-    question: { type: 'string', minLength: 1 },
-    fingerprint: { type: 'string', pattern: '^[a-f0-9]{64}$' },
-    environmentId: { type: 'string', minLength: 1 },
-    schemaVersion: { type: 'string', minLength: 1 },
-    document: { type: 'object' },
-    evidence: { type: 'string', minLength: 1 },
-    checked: { const: true },
-  },
-  required: ['version', 'question', 'fingerprint', 'environmentId', 'schemaVersion', 'document', 'evidence', 'checked'],
-  additionalProperties: false,
+    type: 'object',
+    properties: {
+        version: { const: 1 },
+        question: { type: 'string', minLength: 1 },
+        fingerprint: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+        environmentId: { type: 'string', minLength: 1 },
+        schemaVersion: { type: 'string', minLength: 1 },
+        document: { type: 'object' },
+        evidence: { type: 'string', minLength: 1 },
+        checked: { const: true },
+    },
+    required: ['version', 'question', 'fingerprint', 'environmentId', 'schemaVersion', 'document', 'evidence', 'checked'],
+    additionalProperties: false,
 };
-
 export const SKILL_SCHEMA = {
-  $id: 'https://jarenjs.github.io/schemas/ai/ledger-skill.json',
-  type: 'object',
-  properties: {
-    id: ID,
-    name: { type: 'string', minLength: 1 },
-    when: { type: 'string', minLength: 1 },
-    instructions: { type: 'string', minLength: 1 },
-    program: PROGRAM_SKILL_SCHEMA,
-    tools: { type: 'array', items: { type: 'string', minLength: 1 } },
-    at: AT,
-    // the same optional pair as a memory; the text a skill is embedded
-    // from is its name, when and instructions together
-    embedding: EMBEDDING,
-    embeddedBy: EMBEDDED_BY,
-  },
-  required: ['id', 'name', 'when', 'instructions', 'tools', 'at'],
-  dependencies: EMBEDDING_PAIR,
-  additionalProperties: false,
+    $id: 'https://jarenjs.github.io/schemas/ai/ledger-skill.json',
+    type: 'object',
+    properties: {
+        id: ID,
+        name: { type: 'string', minLength: 1 },
+        when: { type: 'string', minLength: 1 },
+        instructions: { type: 'string', minLength: 1 },
+        program: PROGRAM_SKILL_SCHEMA,
+        tools: { type: 'array', items: { type: 'string', minLength: 1 } },
+        at: AT,
+        // the same optional pair as a memory; the text a skill is embedded
+        // from is its name, when and instructions together
+        embedding: EMBEDDING,
+        embeddedBy: EMBEDDED_BY,
+    },
+    required: ['id', 'name', 'when', 'instructions', 'tools', 'at'],
+    dependencies: EMBEDDING_PAIR,
+    additionalProperties: false,
 };
-
 /**
  * An addressable blob's METADATA. The content lives under a separate
  * storage key and never travels with the metadata — that separation is
@@ -217,141 +215,30 @@ export const SKILL_SCHEMA = {
  * for a hundred slots without carrying one slot's content.
  */
 export const SLOT_SCHEMA = {
-  $id: 'https://jarenjs.github.io/schemas/ai/ledger-slot.json',
-  type: 'object',
-  properties: {
-    name: ID,
-    kind: { type: 'string', minLength: 1 },
-    size: { type: 'integer', minimum: 0 },
-    excerpt: { type: 'string' },
-    at: AT,
-    // OPTIONAL, and optional on purpose: `size` is what a slot costs and
-    // is always known, while `count` is what it CONTAINS — lines,
-    // records, pieces — which only the writer knows and only sometimes.
-    // A root view listing a hundred slots is far more useful with "1 240
-    // lines" beside a size, and a slot whose writer could not say is
-    // better off saying nothing than guessing.
-    count: { type: 'integer', minimum: 0 },
-    pinned: { type: 'boolean' },
-  },
-  required: ['name', 'kind', 'size', 'excerpt', 'at'],
-  additionalProperties: false,
+    $id: 'https://jarenjs.github.io/schemas/ai/ledger-slot.json',
+    type: 'object',
+    properties: {
+        name: ID,
+        kind: { type: 'string', minLength: 1 },
+        size: { type: 'integer', minimum: 0 },
+        excerpt: { type: 'string' },
+        at: AT,
+        // OPTIONAL, and optional on purpose: `size` is what a slot costs and
+        // is always known, while `count` is what it CONTAINS — lines,
+        // records, pieces — which only the writer knows and only sometimes.
+        // A root view listing a hundred slots is far more useful with "1 240
+        // lines" beside a size, and a slot whose writer could not say is
+        // better off saying nothing than guessing.
+        count: { type: 'integer', minimum: 0 },
+        pinned: { type: 'boolean' },
+    },
+    required: ['name', 'kind', 'size', 'excerpt', 'at'],
+    additionalProperties: false,
 };
-
 /** Every ledger schema by kind — what `createLedger` compiles at construction. */
 export const LEDGER_SCHEMAS = {
-  goal: GOAL_SCHEMA,
-  memory: MEMORY_SCHEMA,
-  skill: SKILL_SCHEMA,
-  slot: SLOT_SCHEMA,
+    goal: GOAL_SCHEMA,
+    memory: MEMORY_SCHEMA,
+    skill: SKILL_SCHEMA,
+    slot: SLOT_SCHEMA,
 };
-
-/*
- * The record shapes, as named types beside the schemas that enforce them.
- *
- * These exist because a strictly-typed consumer (the first one was the
- * tangleai rebuild, 2026-08-24) otherwise hand-writes its own copy of
- * "what addMemory returns" and the copy drifts. The schema stays the
- * runtime contract; the typedef is the same statement made to the
- * compiler, and the two live in one file so a change to one is a diff
- * touching the other's neighbourhood.
- */
-
-/**
- * One evidenced progress entry on the active goal.
- * @typedef {object} LedgerProgressEntry
- * @property {string} [id]
- * @property {string} at RFC 3339
- * @property {string} note
- * @property {string} evidence
- */
-
-/**
- * The active (or archived) objective — see {@link GOAL_SCHEMA}.
- * @typedef {object} LedgerGoal
- * @property {string} objective
- * @property {string} createdAt RFC 3339
- * @property {'active'|'done'|'abandoned'|'superseded'} status
- * @property {LedgerProgressEntry[]} progress
- * @property {{ version: 1, records: { note: string, evidence: string }[], sources: { id: string, at: string, record: number }[] }} [checkpoint]
- * @property {{ version: 1, reason: 'goal-budget', retired: string[] }} [retention]
- */
-
-/**
- * A vector's identity — see {@link EMBEDDED_BY}. What `recall({ near })`
- * compares against the query embedder's `{ model, dims }` before any
- * arithmetic happens.
- * @typedef {object} LedgerEmbeddedBy
- * @property {string} model
- * @property {number} dims
- */
-
-/**
- * The vector pair, both-or-neither — the schemas' `dependencies` rule
- * (see {@link EMBEDDING_PAIR}) stated in the type: a record either
- * carries `embedding` AND `embeddedBy`, or neither. `embedding` is the
- * vector `recall({ near })` ranks by — plain numbers, never a typed
- * array — and `embeddedBy` its identity. Narrow on either member and
- * the other follows: `if (record.embedding) record.embeddedBy.dims`.
- * An orphan vector does not type, just as the ledger refuses it.
- * @typedef {{ embedding?: undefined, embeddedBy?: undefined }
- *   | { embedding: number[], embeddedBy: LedgerEmbeddedBy }} LedgerEmbeddingPair
- */
-
-/**
- * A stored memory's own members — see {@link MEMORY_SCHEMA}; the
- * record is these plus {@link LedgerEmbeddingPair}.
- * @typedef {object} LedgerMemoryFields
- * @property {string} id
- * @property {string} text
- * @property {string | import('./evidence.js').ClaimEvidenceEnvelope} evidence
- * @property {string[]} tags
- * @property {string} at RFC 3339
- */
-
-/**
- * A stored memory — see {@link MEMORY_SCHEMA}.
- * @typedef {LedgerMemoryFields & LedgerEmbeddingPair} LedgerMemory
- */
-
-/**
- * A stored skill's own members — see {@link SKILL_SCHEMA}; the record
- * is these plus {@link LedgerEmbeddingPair}.
- * @typedef {object} LedgerSkillFields
- * @property {string} id
- * @property {string} name
- * @property {string} when
- * @property {string} instructions
- * @property {string[]} tools
- * @property {string} at RFC 3339
- * @property {{ version: 1, question: string, fingerprint: string, environmentId: string,
- *   schemaVersion: string, document: any, evidence: string, checked: true }} [program]
- */
-
-/**
- * A stored skill — see {@link SKILL_SCHEMA}.
- * @typedef {LedgerSkillFields & LedgerEmbeddingPair} LedgerSkill
- */
-
-/**
- * A slot's metadata — see {@link SLOT_SCHEMA}. Never the content.
- * @typedef {object} LedgerSlot
- * @property {string} name
- * @property {string} kind
- * @property {number} size
- * @property {string} excerpt
- * @property {string} at RFC 3339
- * @property {number} [count]
- * @property {boolean} [pinned]
- */
-
-/**
- * The one rejection shape every schema-guarded write answers with —
- * produced by `invalidInput` in `check.js`, named here because this is
- * where a consumer of the ledger's API goes looking for "what comes
- * back when a write is refused".
- * @typedef {object} LedgerRejection
- * @property {string} error
- * @property {any[]} errors
- * @property {any} inputSchema
- */