@tangleai/context 0.21.1

package/src/evidence.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Validate structure and references, without interpreting prose or making requests.
+ * Supplied artifacts are the host's allow-list; matching ids must retain their
+ * admitted descriptor. Without an external list, the envelope is self-contained.
+ * @param {any} envelope
+ * @param {{ artifacts?: import('./schemas/evidence.js').ArtifactRecord[] }} [options]
+ */
+export function validateClaimEvidence(envelope: any, options?: {
+    artifacts?: import("./schemas/evidence.js").ArtifactRecord[];
+}): {
+    valid: boolean;
+    errors: any[];
+};
+/**
+ * A second guarded-document consumer: replace or patch a claim envelope using
+ * host persistence and an explicit artifact admission list.
+ * @param {{ read: () => Promise<any>, apply: (document: any, proposal: any) => any,
+ *   validateProposal: (proposal: any) => any, commit: (document: any) => Promise<any>,
+ *   artifacts: import('./schemas/evidence.js').ArtifactRecord[],
+ *   snapshot?: () => Promise<any>, restore?: (token: any) => Promise<any> }} options
+ */
+export function createClaimRefiner(options: {
+    read: () => Promise<any>;
+    apply: (document: any, proposal: any) => any;
+    validateProposal: (proposal: any) => any;
+    commit: (document: any) => Promise<any>;
+    artifacts: import("./schemas/evidence.js").ArtifactRecord[];
+    snapshot?: () => Promise<any>;
+    restore?: (token: any) => Promise<any>;
+}): {
+    prepare: (document: any, proposal: any) => {
+        valid: boolean;
+        errors: any;
+        next?: undefined;
+        plan?: undefined;
+    } | {
+        valid: boolean;
+        errors: never[];
+        next: any;
+        plan: any;
+    };
+    commitPrepared: (previous: any, prepared: any) => Promise<{
+        ok: boolean;
+        stage: string;
+        errors: any;
+        cause?: undefined;
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        stage?: undefined;
+        cause?: undefined;
+        errors?: undefined;
+        ok: boolean;
+        value: any;
+        snapshot: any;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        snapshot: any;
+        restoreError?: {} | null | undefined;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        value?: undefined;
+    }>;
+    commit: (proposal: any) => Promise<{
+        ok: boolean;
+        stage: string;
+        errors: any;
+        cause?: undefined;
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        snapshot?: undefined;
+        value?: undefined;
+    } | {
+        stage?: undefined;
+        cause?: undefined;
+        errors?: undefined;
+        ok: boolean;
+        value: any;
+        snapshot: any;
+    } | {
+        ok: boolean;
+        stage: string;
+        cause: unknown;
+        snapshot: any;
+        restoreError?: {} | null | undefined;
+        errors: {
+            code: any;
+            docPath: any;
+            message: any;
+            stage: any;
+        }[];
+        value?: undefined;
+    }>;
+};

package/src/evidence.js

@@ -0,0 +1,71 @@
+//@ts-check
+import { JarenValidator } from '@jarenjs/validate';
+import { checkOutcome } from '@jarenjs/core/check';
+import { CLAIM_EVIDENCE_SCHEMA } from './schemas/evidence.js';
+import { createGuardedRefiner } from '@jarenjs/core/guarded';
+const check = new JarenValidator({ collectErrors: true, skipErrors: false }).compile(CLAIM_EVIDENCE_SCHEMA);
+
+/**
+ * Validate structure and references, without interpreting prose or making requests.
+ * Supplied artifacts are the host's allow-list; matching ids must retain their
+ * admitted descriptor. Without an external list, the envelope is self-contained.
+ * @param {any} envelope
+ * @param {{ artifacts?: import('./schemas/evidence.js').ArtifactRecord[] }} [options]
+ */
+export function validateClaimEvidence(envelope, options = {}) {
+  const shape = checkOutcome(check(envelope));
+  if (!shape.valid) return shape;
+  const errors = [];
+  const add = (code, docPath, message) => errors.push({ code, docPath, instancePath: docPath, message });
+  const sets = {};
+  for (const kind of ['artifacts', 'evidence', 'claims']) {
+    const ids = new Set();
+    envelope[kind].forEach((record, index) => {
+      if (ids.has(record.id)) add('EVIDENCE_DUPLICATE', `/${kind}/${index}/id`, `duplicate ${kind} id '${record.id}'`);
+      ids.add(record.id);
+    });
+    sets[kind] = ids;
+  }
+  if (options.artifacts) {
+    const admitted = new Map(options.artifacts.map((artifact) => [artifact.id, artifact]));
+    envelope.artifacts.forEach((artifact, i) => {
+      const held = admitted.get(artifact.id);
+      if (!held || ['kind', 'locator', 'digest'].some((field) => artifact[field] !== held[field]))
+        add('EVIDENCE_UNADMITTED', `/artifacts/${i}`, `artifact '${artifact.id}' is not admitted with this descriptor`);
+    });
+  }
+  envelope.evidence.forEach((record, i) => {
+    if (!sets.artifacts.has(record.artifact))
+      add('EVIDENCE_ARTIFACT', `/evidence/${i}/artifact`, `unknown artifact '${record.artifact}'`);
+  });
+  const visible = new Set(envelope.visibleEvidence);
+  envelope.visibleEvidence.forEach((id, i) => {
+    if (!sets.evidence.has(id)) add('EVIDENCE_REFERENCE', `/visibleEvidence/${i}`, `unknown evidence '${id}'`);
+  });
+  envelope.claims.forEach((claim, i) => {
+    if (claim.critical && (claim.status === 'unresolved' || claim.evidence.length === 0))
+      add('EVIDENCE_CRITICAL', `/claims/${i}/status`, `critical claim '${claim.id}' is unresolved`);
+    claim.evidence.forEach((id, j) => {
+      if (!sets.evidence.has(id)) add('EVIDENCE_REFERENCE', `/claims/${i}/evidence/${j}`, `unknown evidence '${id}'`);
+      else if (!visible.has(id)) add('EVIDENCE_HIDDEN', `/claims/${i}/evidence/${j}`, `evidence '${id}' is outside the visible view`);
+    });
+  });
+  errors.sort((a, b) => a.docPath < b.docPath ? -1 : a.docPath > b.docPath ? 1 : a.code.localeCompare(b.code));
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * A second guarded-document consumer: replace or patch a claim envelope using
+ * host persistence and an explicit artifact admission list.
+ * @param {{ read: () => Promise<any>, apply: (document: any, proposal: any) => any,
+ *   validateProposal: (proposal: any) => any, commit: (document: any) => Promise<any>,
+ *   artifacts: import('./schemas/evidence.js').ArtifactRecord[],
+ *   snapshot?: () => Promise<any>, restore?: (token: any) => Promise<any> }} options
+ */
+export function createClaimRefiner(options) {
+  const artifacts = JSON.parse(JSON.stringify(options.artifacts));
+  return createGuardedRefiner({ ...options,
+    validateCandidate: (next) => validateClaimEvidence(next, { artifacts }),
+    planCommit: (next) => next,
+  });
+}

package/src/index.d.ts

@@ -0,0 +1,9 @@
+export { createMemoryStorage } from "./storage/memory.js";
+export { RECALL_TOOL_NAME, createRecallTool, roundSlotName, indexSlotName, slotRef, slotAddress, slotAddressesIn } from "./recall.js";
+export { createLedger, sameIdentity, describeIdentity } from "./ledger.js";
+export { createEnvironment, environmentTools, chunkSlotName, chunkFamily, CHUNK_KIND } from "./environment.js";
+export { LEDGER_SCHEMAS, GOAL_SCHEMA, MEMORY_SCHEMA, SKILL_SCHEMA, SLOT_SCHEMA } from "./schemas/ledger.js";
+export { REFINEMENT_PATCH_SCHEMA, refinementPatchSchema, REFINEMENT_PATH_PATTERN, DEFAULT_MAX_OPS, MEMORY_PROPOSAL_SCHEMA, SKILL_PROPOSAL_SCHEMA, PROGRESS_PROPOSAL_SCHEMA } from "./schemas/patch.js";
+export { validateClaimEvidence, createClaimRefiner } from "./evidence.js";
+export { CLAIM_EVIDENCE_SCHEMA, ARTIFACT_SCHEMA, EVIDENCE_SCHEMA, CLAIM_SCHEMA } from "./schemas/evidence.js";
+export { ledgerFootprint, checkpointProgress, validateCheckpoint, goalPrompt } from "./retention.js";

package/src/index.js

@@ -0,0 +1,11 @@
+//@ts-check
+/** context: public AI mechanisms over injected Jaren foundations. */
+export { RECALL_TOOL_NAME, createRecallTool, roundSlotName, indexSlotName, slotRef, slotAddress, slotAddressesIn } from './recall.js';
+export { createLedger, sameIdentity, describeIdentity } from './ledger.js';
+export { createEnvironment, environmentTools, chunkSlotName, chunkFamily, CHUNK_KIND } from './environment.js';
+export { createMemoryStorage } from './storage/memory.js';
+export { LEDGER_SCHEMAS, GOAL_SCHEMA, MEMORY_SCHEMA, SKILL_SCHEMA, SLOT_SCHEMA } from './schemas/ledger.js';
+export { REFINEMENT_PATCH_SCHEMA, refinementPatchSchema, REFINEMENT_PATH_PATTERN, DEFAULT_MAX_OPS, MEMORY_PROPOSAL_SCHEMA, SKILL_PROPOSAL_SCHEMA, PROGRESS_PROPOSAL_SCHEMA } from './schemas/patch.js';
+export { validateClaimEvidence, createClaimRefiner } from './evidence.js';
+export { CLAIM_EVIDENCE_SCHEMA, ARTIFACT_SCHEMA, EVIDENCE_SCHEMA, CLAIM_SCHEMA } from './schemas/evidence.js';
+export { ledgerFootprint, checkpointProgress, validateCheckpoint, goalPrompt } from './retention.js';

package/src/ledger.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Whether two vector identities name the same space: the same model at
+ * the same width. The rule the ledger applies before any arithmetic
+ * happens, exported because it is not the ledger's alone — a storage
+ * adapter's optional `rank` selects the records whose `embeddedBy` is
+ * the query's, and a host keeping its own vector store beside the
+ * ledger has to refuse the same mixtures. A second implementation of a
+ * one-line predicate is a second chance to get its edges wrong, and
+ * both edges below are ones a re-derivation usually misses.
+ *
+ * Total, and false rather than a throw for anything malformed, so it
+ * can be applied straight to what a store handed back.
+ *
+ * **Two absent identities are NOT the same.** A record with no identity
+ * has no space to share; "unknown" must never rank against "unknown",
+ * or an un-embedded record would compare equal to every other one.
+ * **A width alone is not an identity either** — two models at 768 dims
+ * 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
+ * @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: LedgerEmbeddedBy | undefined | null, b: LedgerEmbeddedBy | undefined | null): boolean;
+/**
+ * An identity as a refusal names it — `"text-embedding-3-small (1536
+ * dims)"`. Exported for the same reason as {@link sameIdentity}: it is
+ * the wording the ledger's mixture refusals use, so a host reporting
+ * the same condition reports it in the same words, and it is a stable
+ * key for collecting the DISTINCT identities a `rank` adapter owes its
+ * caller.
+ *
+ * @param {LedgerEmbeddedBy} identity
+ * @returns {string}
+ */
+export function describeIdentity(identity: LedgerEmbeddedBy): string;
+/**
+ * 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]
+ *   - `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
+ *     declares an optional fifth (`rank`) and `recall({ near })` asks it
+ *     instead of reading every record.
+ *   - `compileQuery` is the retrieval seam — `compileJsonQuery` from
+ *     `@jarenjs/json/query`, or absent. With it, `recall` filters with a
+ *     real query document; without it, retrieval degrades to tag match
+ *     and recency, and a caller-supplied predicate is refused rather
+ *     than silently ignored.
+ *   - `embedder` is the meaning seam — `createEmbeddingClient(...)`,
+ *     `createHashEmbedder()`, or any host `{ embed, model, dims }` whose
+ *     `embed` returns a Promise and rejects rather than throws. With it,
+ *     `recall({ near })` ranks and `embedMissing()` sweeps; without it,
+ *     both refuse naming the seam. Every stored vector is compared
+ *     against the embedder's `{ model, dims }` before any arithmetic.
+ *   - `embedOnWrite` (default `false`) embeds a memory or skill that
+ *     arrives without a vector inside its own write. Off by default on
+ *     purpose: a write must not silently acquire a network dependency.
+ *     On, a seam failure stores the record un-embedded and reports it on
+ *     the returned record (`embedError`) — never a dropped write.
+ *   - `now` returns an RFC 3339 timestamp (injected for deterministic
+ *     tests, exactly as the rest of the suite injects its environment).
+ */
+export function createLedger(options?: {
+    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[];
+}): {
+    storageStatus: () => any;
+    concurrency: string;
+    validate: (kind: "goal" | "memory" | "skill" | "slot", record: any) => null | {
+        error: string;
+        errors: any[];
+        inputSchema: any;
+    };
+    setGoal: (input: {
+        objective: string;
+        createdAt?: string;
+        status?: string;
+        progress?: any[];
+    }) => Promise<LedgerGoal | LedgerRejection>;
+    getGoal: () => Promise<LedgerGoal | null>;
+    listArchivedGoals: () => Promise<LedgerGoal[]>;
+    recordProgress: (entry: {
+        note: string;
+        evidence: string;
+        at?: string;
+    }) => Promise<LedgerGoal | LedgerRejection | {
+        error: string;
+    }>;
+    setGoalStatus: (status: "active" | "done" | "abandoned" | "superseded") => Promise<LedgerGoal | LedgerRejection | {
+        error: string;
+    }>;
+    composeGoal: () => Promise<{
+        error: string;
+        errors: any[];
+        inputSchema: any;
+    } | {
+        text: string;
+        error?: undefined;
+        code?: undefined;
+    } | {
+        error: string;
+        code: string;
+        text?: undefined;
+    }>;
+    addMemory: (input: {
+        id?: string;
+        text: string;
+        evidence: LedgerMemory["evidence"];
+        tags?: string[];
+        at?: string;
+    } & LedgerEmbeddingPair) => Promise<(LedgerMemory & {
+        embedError?: string;
+    }) | LedgerRejection>;
+    getMemory: (id: string) => Promise<LedgerMemory | null>;
+    listMemories: () => Promise<LedgerMemory[]>;
+    deleteMemory: (id: string) => Promise<boolean>;
+    addSkill: (input: {
+        id?: string;
+        name: string;
+        when: string;
+        instructions: string;
+        tools?: string[];
+        at?: string;
+        program?: LedgerSkill["program"];
+    } & LedgerEmbeddingPair) => Promise<(LedgerSkill & {
+        embedError?: string;
+    }) | LedgerRejection>;
+    getSkill: (id: string) => Promise<LedgerSkill | null>;
+    listSkills: () => Promise<LedgerSkill[]>;
+    deleteSkill: (id: string) => Promise<boolean>;
+    recall: (query?: LedgerQuery) => Promise<LedgerMemory[] | LedgerRankedMemories | {
+        error: string;
+    }>;
+    recallSkills: (query?: LedgerQuery) => Promise<LedgerSkill[] | LedgerRankedSkills | {
+        error: string;
+    }>;
+    embedMissing: (options?: {
+        limit?: number;
+        batch?: number;
+    }) => Promise<{
+        embedded: number;
+        remaining: number;
+        error?: string;
+    }>;
+    putSlot: (name: string, content: string, meta?: {
+        kind?: string;
+        at?: string;
+        count?: number;
+        pinned?: boolean;
+    }) => Promise<LedgerSlot | LedgerRejection>;
+    getSlot: (name: string) => Promise<LedgerSlot | null>;
+    readSlot: (name: string) => Promise<string | undefined | {
+        status: "evicted";
+        name: string;
+        bytes: number;
+        reason: string;
+    }>;
+    listSlots: () => Promise<LedgerSlot[]>;
+    deleteSlot: (name: string) => Promise<boolean>;
+    putArchive: (entries: any, protection?: {}) => Promise<{
+        error: string;
+        code: string;
+        retention?: undefined;
+        next?: undefined;
+        report?: undefined;
+        footprint?: undefined;
+    } | {
+        error: string;
+        code: string;
+        retention: {
+            refused: boolean;
+            limits: any;
+            current: {
+                items: number;
+                bytes: number;
+            };
+            attempted: {
+                items: number;
+                bytes: number;
+            };
+        };
+        next?: undefined;
+        report?: undefined;
+        footprint?: undefined;
+    } | {
+        next: any;
+        report: {
+            version: number;
+            policy: string;
+            evicted: any[];
+            written: any;
+        };
+        footprint: {
+            items: number;
+            bytes: number;
+        };
+        error?: undefined;
+        code?: undefined;
+        retention?: undefined;
+    } | {
+        error: string;
+        errors: any[];
+        inputSchema: any;
+    } | {
+        ok: boolean;
+        retention: {
+            version: number;
+            policy: string;
+            evicted: any[];
+            written: any;
+        };
+        footprint: {
+            items: number;
+            bytes: number;
+        };
+    }>;
+    clearArchives: (prefix?: string) => Promise<boolean>;
+    retentionReport: () => Promise<any>;
+    snapshot: () => Promise<string>;
+    rollback: (token: string) => Promise<true | {
+        error: string;
+    }>;
+    transaction: (expected: any, work: (ledger: any) => Promise<any>) => Promise<any>;
+};
+export type LedgerGoal = import("./schemas/ledger.js").LedgerGoal;
+export type LedgerMemory = import("./schemas/ledger.js").LedgerMemory;
+export type LedgerSkill = import("./schemas/ledger.js").LedgerSkill;
+export type LedgerSlot = import("./schemas/ledger.js").LedgerSlot;
+export type LedgerRejection = import("./schemas/ledger.js").LedgerRejection;
+export type LedgerEmbeddingPair = import("./schemas/ledger.js").LedgerEmbeddingPair;
+export type LedgerEmbeddedBy = import("./schemas/ledger.js").LedgerEmbeddedBy;
+export type Embedder = import("@tangleai/models/embed").Embedder;
+/**
+ * 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.
+ */
+export type LedgerRankedMemories = {
+    memories: LedgerMemory[];
+    scores: number[];
+    skipped: number;
+    /**
+     * - which path answered: the ledger's
+     * own read-and-rank, or the adapter's `rank` capability
+     */
+    via: "sweep" | "adapter";
+    /**
+     * - candidate selection provenance, not a quality guarantee
+     */
+    ranking: LedgerRanking;
+};
+/**
+ * What `recallSkills({ near })` answers — see {@link LedgerRankedMemories}.
+ */
+export type LedgerRankedSkills = {
+    skills: LedgerSkill[];
+    scores: number[];
+    skipped: number;
+    /**
+     * - see {@link LedgerRankedMemories}
+     */
+    via: "sweep" | "adapter";
+    /**
+     * - see {@link LedgerRankedMemories}
+     */
+    ranking: LedgerRanking;
+};
+/**
+ * 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.
+ */
+export type LedgerRanking = {
+    algorithm: string;
+    exhaustive: boolean;
+    candidateCount: number;
+};
+/**
+ * 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`.
+ */
+export type LedgerQuery = {
+    tags?: string[];
+    where?: any;
+    limit?: number;
+    near?: string;
+    minScore?: number;
+};