@tangleai/core 0.20.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @tangleai/core
+
+## 0.20.0
+
+### Minor Changes
+
+- Establish the coordinated 0.20.0 release with JavaScript and TypeScript declaration distributions, preserved public subpaths and JSON schemas, and verified Node and Bun consumers. Use published JarenJS 0.83.3 fixes without a consumer installation patch. Prepare versions before release commits, verify locally, push directly to main and publish CI-verified tarballs. Deploy the website independently from local Tangle workspace source with JarenJS packages from npm, verifying dependency sources and the live commit.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joham (jklarenbeek@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @tangleai/core
+
+Tangle AI core — memory record model, k-means clustering, token heuristics (vector arithmetic is @jarenjs/core/vector's)
+
+Install with `npm install @tangleai/core`. The npm distribution provides ESM JavaScript, TypeScript declarations, and the documented package subpaths for Node 24 and Bun 1.4 or newer.
+
+See the [Tangle documentation](https://github.com/jklarenbeek/tangleai#readme) for architecture, examples, and runtime requirements. All public Tangle packages use one coordinated version.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@tangleai/core",
+  "version": "0.20.0",
+  "description": "Tangle AI core — memory record model, k-means clustering, token heuristics (vector arithmetic is @jarenjs/core/vector's)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./errors": {
+      "types": "./src/errors.d.ts",
+      "import": "./src/errors.js",
+      "default": "./src/errors.js"
+    },
+    "./clustering": {
+      "types": "./src/clustering.d.ts",
+      "import": "./src/clustering.js",
+      "default": "./src/clustering.js"
+    },
+    "./tokens": {
+      "types": "./src/tokens.d.ts",
+      "import": "./src/tokens.js",
+      "default": "./src/tokens.js"
+    },
+    "./schemas/memory": {
+      "types": "./src/schemas/memory.d.ts",
+      "import": "./src/schemas/memory.js",
+      "default": "./src/schemas/memory.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@jarenjs/ai": "0.83.3"
+  },
+  "private": false,
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "schemas/**/*.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jklarenbeek/tangleai.git",
+    "directory": "packages/core"
+  }
+}

package/src/clustering.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Zero-dependency centroid k-means with k-means++ seeding. Ported from
+ * memflow `src/utils/clustering.ts` with one deliberate change: the
+ * random source is INJECTED. memflow called `Math.random()` inline,
+ * which made every clustering run unreproducible — a test could assert
+ * "it converged" but never "it converged to this". Pass a seeded
+ * generator and the whole run is a pure function of its inputs.
+ */
+export interface KMeansResult {
+    /** Final centroid positions. */
+    centroids: number[][];
+    /** Cluster assignment for each input vector (index into centroids). */
+    assignments: number[];
+    /** Iterations until convergence. */
+    iterations: number;
+}
+export interface KMeansOptions {
+    maxIterations?: number;
+    random?: () => number;
+}
+export declare function kMeans(vectors: number[][], k: number, options?: KMeansOptions): KMeansResult;

package/src/clustering.js

@@ -0,0 +1,112 @@
+/**
+ * Zero-dependency centroid k-means with k-means++ seeding. Ported from
+ * memflow `src/utils/clustering.ts` with one deliberate change: the
+ * random source is INJECTED. memflow called `Math.random()` inline,
+ * which made every clustering run unreproducible — a test could assert
+ * "it converged" but never "it converged to this". Pass a seeded
+ * generator and the whole run is a pure function of its inputs.
+ */
+/**
+ * Squared Euclidean distance, private to this module. `@jarenjs/core/vector`
+ * is the suite's one home for vector arithmetic, but it publishes
+ * SIMILARITIES (higher-is-better, `1 / (1 + distance)` for Euclidean) and
+ * k-means++ seeding needs the squared distance itself; inverting the
+ * similarity back into a distance is a round trip nobody should have to
+ * read. Mismatched lengths answer Infinity — such a point joins no
+ * cluster rather than a wrong one.
+ */
+function squaredDistance(a, b) {
+    if (a.length !== b.length)
+        return Infinity;
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const d = a[i] - b[i];
+        sum += d * d;
+    }
+    return sum;
+}
+export function kMeans(vectors, k, options = {}) {
+    const maxIterations = options.maxIterations ?? 100;
+    const random = options.random ?? Math.random;
+    if (vectors.length === 0 || k <= 0) {
+        return { centroids: [], assignments: [], iterations: 0 };
+    }
+    const n = vectors.length;
+    const dim = vectors[0].length;
+    const effectiveK = Math.min(k, n);
+    const centroids = initCentroids(vectors, effectiveK, random);
+    const assignments = new Array(n).fill(0);
+    let converged = false;
+    let iter = 0;
+    while (!converged && iter < maxIterations) {
+        iter++;
+        converged = true;
+        for (let i = 0; i < n; i++) {
+            let minDist = Infinity;
+            let minIdx = 0;
+            for (let c = 0; c < effectiveK; c++) {
+                const dist = squaredDistance(vectors[i], centroids[c]);
+                if (dist < minDist) {
+                    minDist = dist;
+                    minIdx = c;
+                }
+            }
+            if (assignments[i] !== minIdx) {
+                assignments[i] = minIdx;
+                converged = false;
+            }
+        }
+        for (let c = 0; c < effectiveK; c++) {
+            const members = [];
+            for (let i = 0; i < n; i++)
+                if (assignments[i] === c)
+                    members.push(vectors[i]);
+            if (members.length === 0)
+                continue;
+            for (let d = 0; d < dim; d++) {
+                let sum = 0;
+                for (const m of members)
+                    sum += m[d];
+                centroids[c][d] = sum / members.length;
+            }
+        }
+    }
+    return { centroids, assignments, iterations: iter };
+}
+/**
+ * k-means++ seeding: first centroid uniform, the rest proportional to
+ * squared distance from the nearest chosen centroid.
+ */
+function initCentroids(vectors, k, random) {
+    const n = vectors.length;
+    const centroids = [];
+    centroids.push([...vectors[Math.floor(random() * n)]]);
+    for (let c = 1; c < k; c++) {
+        const distances = vectors.map((v) => {
+            let minDist = Infinity;
+            for (const cent of centroids) {
+                const d = squaredDistance(v, cent);
+                if (d < minDist)
+                    minDist = d;
+            }
+            return minDist;
+        });
+        const totalDist = distances.reduce((a, b) => a + b, 0);
+        if (totalDist === 0) {
+            // remaining points coincide with existing centroids
+            centroids.push([...vectors[c % n]]);
+            continue;
+        }
+        let threshold = random() * totalDist;
+        for (let i = 0; i < n; i++) {
+            threshold -= distances[i];
+            if (threshold <= 0) {
+                centroids.push([...vectors[i]]);
+                break;
+            }
+        }
+        if (centroids.length <= c)
+            centroids.push([...vectors[c % n]]);
+    }
+    return centroids;
+}

package/src/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tangle's error type. One class, coded, mirroring the jarenjs
+ * `CodedError` convention without importing it — @tangleai/core stays
+ * dependency-free so the vector math and schemas can be lifted anywhere.
+ *
+ * Codes:
+ *   TA0001 — caller/config error (bad argument, missing seam)
+ *   TA0002 — transport error (HTTP status from a provider)
+ *   TA0003 — malformed payload (a provider answered, but not with what
+ *             the contract promises)
+ *
+ * The split matters the same way it does in @jarenjs/ai: TA0001 is a bug
+ * in the host, TA0002 is the network's fault, TA0003 is the provider's.
+ * A retry policy may retry the second, must not retry the first, and
+ * should log the third.
+ */
+export type TangleErrorCode = 'TA0001' | 'TA0002' | 'TA0003';
+export interface TangleErrorOptions {
+    status?: number;
+    cause?: unknown;
+}
+export declare class TangleError extends Error {
+    readonly code: TangleErrorCode;
+    readonly status?: number;
+    constructor(code: TangleErrorCode, message: string, options?: TangleErrorOptions);
+}
+export declare function callerError(message: string, options?: TangleErrorOptions): TangleError;
+export declare function transportError(message: string, options?: TangleErrorOptions): TangleError;
+export declare function payloadError(message: string, options?: TangleErrorOptions): TangleError;

package/src/errors.js

@@ -0,0 +1,36 @@
+/**
+ * Tangle's error type. One class, coded, mirroring the jarenjs
+ * `CodedError` convention without importing it — @tangleai/core stays
+ * dependency-free so the vector math and schemas can be lifted anywhere.
+ *
+ * Codes:
+ *   TA0001 — caller/config error (bad argument, missing seam)
+ *   TA0002 — transport error (HTTP status from a provider)
+ *   TA0003 — malformed payload (a provider answered, but not with what
+ *             the contract promises)
+ *
+ * The split matters the same way it does in @jarenjs/ai: TA0001 is a bug
+ * in the host, TA0002 is the network's fault, TA0003 is the provider's.
+ * A retry policy may retry the second, must not retry the first, and
+ * should log the third.
+ */
+export class TangleError extends Error {
+    code;
+    status;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'TangleError';
+        this.code = code;
+        if (options.status !== undefined)
+            this.status = options.status;
+    }
+}
+export function callerError(message, options) {
+    return new TangleError('TA0001', message, options);
+}
+export function transportError(message, options) {
+    return new TangleError('TA0002', message, options);
+}
+export function payloadError(message, options) {
+    return new TangleError('TA0003', message, options);
+}

package/src/index.d.ts

@@ -0,0 +1,9 @@
+/** @tangleai/core barrel. Subpath exports exist for tree-shaking hosts;
+ * this re-export exists for convenience. */
+export { TangleError, callerError, transportError, payloadError } from './errors.ts';
+export type { TangleErrorCode, TangleErrorOptions } from './errors.ts';
+export { kMeans } from './clustering.ts';
+export type { KMeansResult, KMeansOptions } from './clustering.ts';
+export { CHARS_PER_TOKEN, estimateTokens, truncateToTokens } from './tokens.ts';
+export { MEMORY_KINDS, MEMORY_UNIT_SCHEMA, MEMORY_RELATION_SCHEMA, OUTCOME_REPORT_SCHEMA, MEMORY_SCHEMAS, toLedgerMemory, } from './schemas/memory.ts';
+export type { JsonSchema, MemoryKind, MemoryRelation, EmbeddedBy, MemoryUnit, OutcomeReport, LedgerMemory, } from './schemas/memory.ts';

package/src/index.js

@@ -0,0 +1,6 @@
+/** @tangleai/core barrel. Subpath exports exist for tree-shaking hosts;
+ * this re-export exists for convenience. */
+export { TangleError, callerError, transportError, payloadError } from "./errors.js";
+export { kMeans } from "./clustering.js";
+export { CHARS_PER_TOKEN, estimateTokens, truncateToTokens } from "./tokens.js";
+export { MEMORY_KINDS, MEMORY_UNIT_SCHEMA, MEMORY_RELATION_SCHEMA, OUTCOME_REPORT_SCHEMA, MEMORY_SCHEMAS, toLedgerMemory, } from "./schemas/memory.js";

package/src/schemas/memory.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The Tangle memory record, as plain JSON Schema — memflow's `MemoryUnit`
+ * aligned with the text-evidence specialization of the @jarenjs/ai ledger memory.
+ *
+ * The alignment is the design decision that matters. A jarenjs ledger
+ * memory is `{ id, text, evidence, tags, at }` with evidence REQUIRED —
+ * a memory without evidence is a guess. memflow's MemoryUnit had
+ * `content`/`timestamp`/`metadata` and no evidence rule, which is one
+ * reason its consolidation loops could never be audited. Tangle keeps
+ * jarenjs's five fields under jarenjs's names and adds what the
+ * consolidation policies need on top:
+ *
+ *   kind        — fact | event | summary | relation (memflow's `type`)
+ *   embedding   — the vector, present once an embed pass has run, and
+ *   embeddedBy  — its identity `{ model, dims }`, the jarenjs ledger's
+ *                 own rule (a vector never travels without the model
+ *                 that made it: vectors from two models compare into
+ *                 plausible garbage). Both-or-neither, as in the ledger.
+ *   confidence  — [0,1], moved by outcome learning, never below the floor
+ *   supersededBy / supersededAt / supersededReason — contradiction
+ *                 resolution marks the loser instead of deleting it, so
+ *                 "what did we believe before" stays answerable
+ *   mergedFrom  — crystallization provenance: the ids this record absorbed
+ *   relations   — typed edges to other memories, document-shaped; a graph
+ *                 store may index these later, nothing requires one now
+ *
+ * `toLedgerMemory()` projects a Tangle record down to the jarenjs fields
+ * — the five the ledger always held plus the optional embedding pair —
+ * so any Tangle memory can be mirrored into a real ledger and recalled
+ * by an unmodified @jarenjs/ai agent, by tag AND by meaning
+ * (`recall({ near })` through the same embedder that wrote the vector).
+ * The projection is lossy by design — the ledger's strictness
+ * (`additionalProperties: false`) is a feature we align with, not a
+ * limitation we fight.
+ *
+ * The interfaces are hand-written beside the schemas rather than derived
+ * from them: the schemas are the runtime contract (what a validator
+ * enforces at the store boundary), the interfaces are the compile-time
+ * one, and the schema tests are what keep them honest with each other.
+ */
+/** A JSON Schema document as a plain map: this module has no runtime imports
+ * and does not name `@jarenjs/validate`'s `JSONSchema` type. The
+ * validator's boundary methods take `JSONSchemaLike` (`JSONSchema |
+ * Record<string, unknown>`), so a plain map crosses without a cast. */
+export type JsonSchema = Record<string, unknown>;
+export declare const MEMORY_KINDS: readonly ["fact", "event", "summary", "relation"];
+export type MemoryKind = typeof MEMORY_KINDS[number];
+export interface MemoryRelation {
+    target: string;
+    relType: string;
+    weight?: number;
+}
+/** Which model produced a vector, at what width — the same shape as
+ * `LedgerEmbeddedBy` in `@jarenjs/ai/schemas/ledger`, restated here
+ * because this package is dependency-free (the mirror test pins the
+ * two against each other). */
+export interface EmbeddedBy {
+    model: string;
+    dims: number;
+}
+export interface MemoryUnit {
+    id: string;
+    text: string;
+    evidence: string;
+    tags: string[];
+    /** RFC 3339. */
+    at: string;
+    kind: MemoryKind;
+    /** Present exactly when `embeddedBy` is. */
+    embedding?: number[];
+    /** Present exactly when `embedding` is. */
+    embeddedBy?: EmbeddedBy;
+    confidence?: number;
+    supersededBy?: string;
+    supersededAt?: string;
+    supersededReason?: string;
+    mergedFrom?: string[];
+    relations?: MemoryRelation[];
+}
+export interface OutcomeReport {
+    memoryIds: string[];
+    outcome: 'success' | 'failure' | 'partial';
+    /** RFC 3339. */
+    at: string;
+    /** What happened, in the world — the ground truth that makes the
+     * adjustment an observation rather than a self-judgment. */
+    evidence: string;
+}
+/** The vector pair, both-or-neither: the schema's `dependencies` rule
+ * (`EMBEDDING_PAIR`) stated in the type. Narrow on either member and
+ * the other follows; an orphan vector does not type. */
+export type EmbeddingPair = {
+    embedding?: undefined;
+    embeddedBy?: undefined;
+} | {
+    embedding: number[];
+    embeddedBy: EmbeddedBy;
+};
+/** A @jarenjs/ai ledger memory's own five fields. */
+export interface LedgerMemoryFields {
+    id: string;
+    text: string;
+    evidence: string;
+    tags: string[];
+    at: string;
+}
+/** What a @jarenjs/ai ledger memory holds: the five fields, plus the
+ * vector pair. Structurally identical to `LedgerMemory` in
+ * `@jarenjs/ai/schemas/ledger` — restated because this package is
+ * dependency-free; `test/memory/ledger-mirror.test.ts` pins the two
+ * against each other at compile time, in both directions. */
+export type LedgerMemory = import('@jarenjs/ai/schemas/ledger').LedgerMemory;
+export declare const MEMORY_RELATION_SCHEMA: JsonSchema;
+export declare const MEMORY_UNIT_SCHEMA: JsonSchema;
+/** The outcome report a host files after acting on recalled memories. */
+export declare const OUTCOME_REPORT_SCHEMA: JsonSchema;
+export declare const MEMORY_SCHEMAS: {
+    readonly unit: JsonSchema;
+    readonly relation: JsonSchema;
+    readonly outcome: JsonSchema;
+};
+/**
+ * Project a Tangle memory down to what a @jarenjs/ai ledger accepts:
+ * the five fields, and the embedding pair when the unit carries one —
+ * so a mirrored memory is recallable by meaning, not only by tag.
+ * Lossy on purpose; see the header.
+ */
+export declare function toLedgerMemory(unit: MemoryUnit): LedgerMemory;

package/src/schemas/memory.js

@@ -0,0 +1,141 @@
+/**
+ * The Tangle memory record, as plain JSON Schema — memflow's `MemoryUnit`
+ * aligned with the text-evidence specialization of the @jarenjs/ai ledger memory.
+ *
+ * The alignment is the design decision that matters. A jarenjs ledger
+ * memory is `{ id, text, evidence, tags, at }` with evidence REQUIRED —
+ * a memory without evidence is a guess. memflow's MemoryUnit had
+ * `content`/`timestamp`/`metadata` and no evidence rule, which is one
+ * reason its consolidation loops could never be audited. Tangle keeps
+ * jarenjs's five fields under jarenjs's names and adds what the
+ * consolidation policies need on top:
+ *
+ *   kind        — fact | event | summary | relation (memflow's `type`)
+ *   embedding   — the vector, present once an embed pass has run, and
+ *   embeddedBy  — its identity `{ model, dims }`, the jarenjs ledger's
+ *                 own rule (a vector never travels without the model
+ *                 that made it: vectors from two models compare into
+ *                 plausible garbage). Both-or-neither, as in the ledger.
+ *   confidence  — [0,1], moved by outcome learning, never below the floor
+ *   supersededBy / supersededAt / supersededReason — contradiction
+ *                 resolution marks the loser instead of deleting it, so
+ *                 "what did we believe before" stays answerable
+ *   mergedFrom  — crystallization provenance: the ids this record absorbed
+ *   relations   — typed edges to other memories, document-shaped; a graph
+ *                 store may index these later, nothing requires one now
+ *
+ * `toLedgerMemory()` projects a Tangle record down to the jarenjs fields
+ * — the five the ledger always held plus the optional embedding pair —
+ * so any Tangle memory can be mirrored into a real ledger and recalled
+ * by an unmodified @jarenjs/ai agent, by tag AND by meaning
+ * (`recall({ near })` through the same embedder that wrote the vector).
+ * The projection is lossy by design — the ledger's strictness
+ * (`additionalProperties: false`) is a feature we align with, not a
+ * limitation we fight.
+ *
+ * The interfaces are hand-written beside the schemas rather than derived
+ * from them: the schemas are the runtime contract (what a validator
+ * enforces at the store boundary), the interfaces are the compile-time
+ * one, and the schema tests are what keep them honest with each other.
+ */
+/** RFC 3339 timestamp — same shape and same reasoning as the jarenjs ledger:
+ * `format` is honest metadata, `pattern` is the zero-dependency enforcement,
+ * and recency sorts these strings lexicographically. */
+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})$',
+};
+/** A non-empty identifier. */
+const ID = { type: 'string', minLength: 1 };
+/** A stored embedding: plain numbers, never a typed array — a
+ * `Float32Array` does not survive JSON, and the store boundary is JSON.
+ * Finiteness and width are the identity's job, checked where the vector
+ * is used (`@jarenjs/core/vector` `isVector`). */
+const EMBEDDING = { type: 'array', items: { type: 'number' }, minItems: 1 };
+/** A vector's identity, byte-for-byte the jarenjs ledger's `EMBEDDED_BY`. */
+const EMBEDDED_BY = {
+    type: 'object',
+    properties: {
+        model: { type: 'string', minLength: 1 },
+        dims: { type: 'integer', minimum: 1 },
+    },
+    required: ['model', 'dims'],
+    additionalProperties: false,
+};
+/** Both-or-neither, spelled as draft-07 `dependencies` — the ledger's
+ * spelling, under the validator's draft-07 default. */
+const EMBEDDING_PAIR = { embedding: ['embeddedBy'], embeddedBy: ['embedding'] };
+export const MEMORY_KINDS = ['fact', 'event', 'summary', 'relation'];
+export const MEMORY_RELATION_SCHEMA = {
+    $id: 'https://tangleai.dev/schemas/memory-relation.json',
+    type: 'object',
+    properties: {
+        target: ID,
+        relType: { type: 'string', minLength: 1 },
+        weight: { type: 'number', minimum: 0 },
+    },
+    required: ['target', 'relType'],
+    additionalProperties: false,
+};
+export const MEMORY_UNIT_SCHEMA = {
+    $id: 'https://tangleai.dev/schemas/memory-unit.json',
+    type: 'object',
+    properties: {
+        id: ID,
+        text: { type: 'string', minLength: 1 },
+        evidence: { type: 'string', minLength: 1 },
+        tags: { type: 'array', items: { type: 'string', minLength: 1 } },
+        at: AT,
+        kind: { enum: [...MEMORY_KINDS] },
+        embedding: EMBEDDING,
+        embeddedBy: EMBEDDED_BY,
+        confidence: { type: 'number', minimum: 0, maximum: 1 },
+        supersededBy: ID,
+        supersededAt: AT,
+        supersededReason: { type: 'string', minLength: 1 },
+        mergedFrom: { type: 'array', items: ID },
+        relations: { type: 'array', items: { $ref: 'https://tangleai.dev/schemas/memory-relation.json' } },
+    },
+    required: ['id', 'text', 'evidence', 'tags', 'at', 'kind'],
+    dependencies: EMBEDDING_PAIR,
+    additionalProperties: false,
+};
+/** The outcome report a host files after acting on recalled memories. */
+export const OUTCOME_REPORT_SCHEMA = {
+    $id: 'https://tangleai.dev/schemas/outcome-report.json',
+    type: 'object',
+    properties: {
+        memoryIds: { type: 'array', items: ID, minItems: 1 },
+        outcome: { enum: ['success', 'failure', 'partial'] },
+        at: AT,
+        // what happened, in the world — the ground truth that makes the
+        // adjustment an observation rather than a self-judgment
+        evidence: { type: 'string', minLength: 1 },
+    },
+    required: ['memoryIds', 'outcome', 'at', 'evidence'],
+    additionalProperties: false,
+};
+export const MEMORY_SCHEMAS = {
+    unit: MEMORY_UNIT_SCHEMA,
+    relation: MEMORY_RELATION_SCHEMA,
+    outcome: OUTCOME_REPORT_SCHEMA,
+};
+/**
+ * Project a Tangle memory down to what a @jarenjs/ai ledger accepts:
+ * the five fields, and the embedding pair when the unit carries one —
+ * so a mirrored memory is recallable by meaning, not only by tag.
+ * Lossy on purpose; see the header.
+ */
+export function toLedgerMemory(unit) {
+    const fields = {
+        id: unit.id,
+        text: unit.text,
+        evidence: unit.evidence,
+        tags: unit.tags,
+        at: unit.at,
+    };
+    return unit.embedding !== undefined && unit.embeddedBy !== undefined
+        ? { ...fields, embedding: unit.embedding, embeddedBy: { ...unit.embeddedBy } }
+        : fields;
+}

package/src/tokens.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Token estimation. The 4-characters-per-token heuristic from memflow
+ * `src/utils/tokens.ts`, kept as a heuristic ON PURPOSE: a real
+ * tokenizer is model-specific and heavy, and every place this number is
+ * used (budgets, truncation) already treats it as a ceiling, not a
+ * measurement. When a budget decision starts to matter more than ±25%,
+ * the fix is a real count from the provider's usage field, not a better
+ * guess here.
+ */
+export declare const CHARS_PER_TOKEN = 4;
+/** Estimated token count, never negative. */
+export declare function estimateTokens(text: string): number;
+/** Truncate `text` so its estimated token count fits `maxTokens`. */
+export declare function truncateToTokens(text: string, maxTokens: number): string;

package/src/tokens.js

@@ -0,0 +1,23 @@
+/**
+ * Token estimation. The 4-characters-per-token heuristic from memflow
+ * `src/utils/tokens.ts`, kept as a heuristic ON PURPOSE: a real
+ * tokenizer is model-specific and heavy, and every place this number is
+ * used (budgets, truncation) already treats it as a ceiling, not a
+ * measurement. When a budget decision starts to matter more than ±25%,
+ * the fix is a real count from the provider's usage field, not a better
+ * guess here.
+ */
+export const CHARS_PER_TOKEN = 4;
+/** Estimated token count, never negative. */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/** Truncate `text` so its estimated token count fits `maxTokens`. */
+export function truncateToTokens(text, maxTokens) {
+    if (!text || maxTokens <= 0)
+        return '';
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    return text.length <= maxChars ? text : text.slice(0, maxChars);
+}