@tangleai/store 0.20.0

package/src/model.d.ts

@@ -0,0 +1,446 @@
+/**
+ * The Tangle database model — a `jaren-model` 0.1 document for
+ * @jarenjs/db `openStore`.
+ *
+ * The core collections, one decision each:
+ *
+ *   memories  — the MemoryUnit records. The db-level schema is
+ *               deliberately minimal: the REAL write gate is
+ *               `MEMORY_UNIT_SCHEMA`, enforced by `createDbMemoryStore`
+ *               at the MemoryStore boundary (same rule as the in-memory
+ *               store). Validating twice with two schemas invites drift.
+ *   runs      — one record per pipeline run: kind, status, summary.
+ *   events    — one record per DAG node record per run; this is the
+ *               "historical DAG state" the desktop surface renders.
+ *   chats     — the conversation transcript with citations.
+ *   documents — folder-sync state: content hash per file, so an
+ *               unchanged file is skipped on re-sync.
+ *   sources / document_versions / document_elements / document_chunks —
+ *               the independent, replaceable web-document corpus lane.
+ *   settings  — key/value host configuration (folder, provider).
+ *   config_identities — the content-addressed, credential-free run
+ *               identities runs and chats refer to by id. Stored once
+ *               per identity; a run row carries only the reference.
+ *
+ * Keys are JSON Pointers into the document (`key: '/id'`), so the id
+ * lives IN the record — a row is self-describing when exported.
+ */
+import type { JsonSchema } from '@tangleai/core/schemas/memory';
+export declare const TANGLE_DB_MODEL: {
+    readonly $model: "0.1";
+    readonly collections: {
+        readonly memories: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly runs: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "kind", "startedAt", "status"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly startedAt: {
+                        readonly type: "string";
+                    };
+                    readonly finishedAt: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly status: {
+                        readonly enum: readonly ["running", "ok", "error"];
+                    };
+                    readonly summary: {};
+                    readonly identityId: {
+                        readonly type: "string";
+                        readonly pattern: "^[0-9a-f]{64}$";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly events: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId", "seq", "node", "status", "at"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: {
+                        readonly type: "string";
+                    };
+                    readonly seq: {
+                        readonly type: "integer";
+                    };
+                    readonly node: {
+                        readonly type: "string";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                    };
+                    readonly ms: {
+                        readonly type: "number";
+                    };
+                    readonly at: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly chats: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "role", "text", "at"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly role: {
+                        readonly enum: readonly ["user", "assistant"];
+                    };
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly at: {
+                        readonly type: "string";
+                    };
+                    readonly citations: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly provider: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly identityId: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly usage: {
+                        readonly type: readonly ["object", "null"];
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly documents: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["path", "hash", "chunks", "ingestedAt"];
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly hash: {
+                        readonly type: "string";
+                    };
+                    readonly chunks: {
+                        readonly type: "integer";
+                    };
+                    readonly ingestedAt: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly key: "/path";
+        };
+        readonly sources: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "requestedUrl", "finalUrl", "canonicalUrl", "title", "mimeType", "fetchMode", "status", "fetchedAt"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly requestedUrl: {
+                        readonly type: "string";
+                    };
+                    readonly finalUrl: {
+                        readonly type: "string";
+                    };
+                    readonly canonicalUrl: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly mimeType: {
+                        readonly type: "string";
+                    };
+                    readonly fetchMode: {
+                        readonly enum: readonly ["static", "bun-webview", "remote-playwright"];
+                    };
+                    readonly status: {
+                        readonly enum: readonly ["ready", "failed", "blocked", "dynamic-unavailable"];
+                    };
+                    readonly fetchedAt: {
+                        readonly type: "string";
+                    };
+                    readonly activeVersionId: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly document_versions: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "sourceId", "contentHash", "extractionVersion", "chunkerVersion", "chunkerConfig", "embeddedBy", "status", "fetchedAt", "metrics"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly sourceId: JsonSchema;
+                    readonly contentHash: {
+                        readonly type: "string";
+                    };
+                    readonly extractionVersion: {
+                        readonly type: "string";
+                    };
+                    readonly chunkerVersion: {
+                        readonly type: "string";
+                    };
+                    readonly chunkerConfig: {
+                        readonly type: "object";
+                    };
+                    readonly embeddedBy: {
+                        readonly type: "object";
+                    };
+                    readonly status: {
+                        readonly enum: readonly ["staging", "active", "failed", "superseded"];
+                    };
+                    readonly fetchedAt: {
+                        readonly type: "string";
+                    };
+                    readonly metrics: {
+                        readonly type: "object";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly document_elements: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "sourceId", "versionId", "text", "role", "order", "headingPath"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly sourceId: JsonSchema;
+                    readonly versionId: JsonSchema;
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly role: {
+                        readonly type: "string";
+                    };
+                    readonly order: {
+                        readonly type: "integer";
+                    };
+                    readonly headingPath: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly document_chunks: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "sourceId", "versionId", "elementIds", "text", "tokenCount", "order", "headingPath", "embedding", "embeddedBy"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly sourceId: JsonSchema;
+                    readonly versionId: JsonSchema;
+                    readonly elementIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly tokenCount: {
+                        readonly type: "integer";
+                    };
+                    readonly order: {
+                        readonly type: "integer";
+                    };
+                    readonly headingPath: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly embedding: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "number";
+                        };
+                    };
+                    readonly embeddedBy: {
+                        readonly type: "object";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly settings: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["key"];
+                readonly properties: {
+                    readonly key: JsonSchema;
+                    readonly value: {};
+                };
+            };
+            readonly key: "/key";
+        };
+        readonly config_identities: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "value"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly pattern: "^[0-9a-f]{64}$";
+                    };
+                    readonly value: {
+                        readonly type: "object";
+                    };
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_workflows: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_workflow_versions: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["versionId"];
+                readonly properties: {
+                    readonly versionId: {
+                        readonly type: "string";
+                        readonly pattern: "^[0-9a-f]{64}$";
+                    };
+                };
+            };
+            readonly key: "/versionId";
+        };
+        readonly mas_templates: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_template_versions: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["versionId"];
+                readonly properties: {
+                    readonly versionId: {
+                        readonly type: "string";
+                        readonly pattern: "^[0-9a-f]{64}$";
+                    };
+                };
+            };
+            readonly key: "/versionId";
+        };
+        readonly mas_registry_snapshots: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["revision"];
+                readonly properties: {
+                    readonly revision: {
+                        readonly type: "string";
+                        readonly pattern: "^[0-9a-f]{64}$";
+                    };
+                };
+            };
+            readonly key: "/revision";
+        };
+        readonly mas_runs: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_node_attempts: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_messages: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_state_revisions: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_interactions: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+        readonly mas_trace_artifacts: {
+            readonly schema: {
+                readonly type: "object";
+                readonly required: readonly ["id", "runId"];
+                readonly properties: {
+                    readonly id: JsonSchema;
+                    readonly runId: JsonSchema;
+                };
+            };
+            readonly key: "/id";
+        };
+    };
+};

package/src/model.js

@@ -0,0 +1,242 @@
+/**
+ * The Tangle database model — a `jaren-model` 0.1 document for
+ * @jarenjs/db `openStore`.
+ *
+ * The core collections, one decision each:
+ *
+ *   memories  — the MemoryUnit records. The db-level schema is
+ *               deliberately minimal: the REAL write gate is
+ *               `MEMORY_UNIT_SCHEMA`, enforced by `createDbMemoryStore`
+ *               at the MemoryStore boundary (same rule as the in-memory
+ *               store). Validating twice with two schemas invites drift.
+ *   runs      — one record per pipeline run: kind, status, summary.
+ *   events    — one record per DAG node record per run; this is the
+ *               "historical DAG state" the desktop surface renders.
+ *   chats     — the conversation transcript with citations.
+ *   documents — folder-sync state: content hash per file, so an
+ *               unchanged file is skipped on re-sync.
+ *   sources / document_versions / document_elements / document_chunks —
+ *               the independent, replaceable web-document corpus lane.
+ *   settings  — key/value host configuration (folder, provider).
+ *   config_identities — the content-addressed, credential-free run
+ *               identities runs and chats refer to by id. Stored once
+ *               per identity; a run row carries only the reference.
+ *
+ * Keys are JSON Pointers into the document (`key: '/id'`), so the id
+ * lives IN the record — a row is self-describing when exported.
+ */
+const ID = { type: 'string', minLength: 1 };
+export const TANGLE_DB_MODEL = {
+    $model: '0.1',
+    collections: {
+        memories: {
+            schema: { type: 'object', required: ['id'], properties: { id: ID } },
+            key: '/id',
+        },
+        runs: {
+            schema: {
+                type: 'object',
+                required: ['id', 'kind', 'startedAt', 'status'],
+                properties: {
+                    id: ID,
+                    kind: { type: 'string' },
+                    startedAt: { type: 'string' },
+                    finishedAt: { type: ['string', 'null'] },
+                    status: { enum: ['running', 'ok', 'error'] },
+                    summary: {},
+                    identityId: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+                },
+            },
+            key: '/id',
+        },
+        events: {
+            schema: {
+                type: 'object',
+                required: ['id', 'runId', 'seq', 'node', 'status', 'at'],
+                properties: {
+                    id: ID,
+                    runId: { type: 'string' },
+                    seq: { type: 'integer' },
+                    node: { type: 'string' },
+                    status: { type: 'string' },
+                    ms: { type: 'number' },
+                    at: { type: 'string' },
+                },
+            },
+            key: '/id',
+        },
+        chats: {
+            schema: {
+                type: 'object',
+                required: ['id', 'role', 'text', 'at'],
+                properties: {
+                    id: ID,
+                    role: { enum: ['user', 'assistant'] },
+                    text: { type: 'string' },
+                    at: { type: 'string' },
+                    citations: { type: 'array', items: { type: 'string' } },
+                    provider: { type: ['string', 'null'] },
+                    identityId: { type: ['string', 'null'] },
+                    usage: { type: ['object', 'null'] },
+                },
+            },
+            key: '/id',
+        },
+        documents: {
+            schema: {
+                type: 'object',
+                required: ['path', 'hash', 'chunks', 'ingestedAt'],
+                properties: {
+                    path: { type: 'string', minLength: 1 },
+                    hash: { type: 'string' },
+                    chunks: { type: 'integer' },
+                    ingestedAt: { type: 'string' },
+                },
+            },
+            key: '/path',
+        },
+        sources: {
+            schema: {
+                type: 'object',
+                required: ['id', 'requestedUrl', 'finalUrl', 'canonicalUrl', 'title', 'mimeType', 'fetchMode', 'status', 'fetchedAt'],
+                properties: {
+                    id: ID,
+                    requestedUrl: { type: 'string' },
+                    finalUrl: { type: 'string' },
+                    canonicalUrl: { type: 'string' },
+                    title: { type: ['string', 'null'] },
+                    mimeType: { type: 'string' },
+                    fetchMode: { enum: ['static', 'bun-webview', 'remote-playwright'] },
+                    status: { enum: ['ready', 'failed', 'blocked', 'dynamic-unavailable'] },
+                    fetchedAt: { type: 'string' },
+                    activeVersionId: { type: 'string' },
+                },
+            },
+            key: '/id',
+        },
+        document_versions: {
+            schema: {
+                type: 'object',
+                required: ['id', 'sourceId', 'contentHash', 'extractionVersion', 'chunkerVersion', 'chunkerConfig', 'embeddedBy', 'status', 'fetchedAt', 'metrics'],
+                properties: {
+                    id: ID,
+                    sourceId: ID,
+                    contentHash: { type: 'string' },
+                    extractionVersion: { type: 'string' },
+                    chunkerVersion: { type: 'string' },
+                    chunkerConfig: { type: 'object' },
+                    embeddedBy: { type: 'object' },
+                    status: { enum: ['staging', 'active', 'failed', 'superseded'] },
+                    fetchedAt: { type: 'string' },
+                    metrics: { type: 'object' },
+                },
+            },
+            key: '/id',
+        },
+        document_elements: {
+            schema: {
+                type: 'object',
+                required: ['id', 'sourceId', 'versionId', 'text', 'role', 'order', 'headingPath'],
+                properties: {
+                    id: ID,
+                    sourceId: ID,
+                    versionId: ID,
+                    text: { type: 'string' },
+                    role: { type: 'string' },
+                    order: { type: 'integer' },
+                    headingPath: { type: 'array', items: { type: 'string' } },
+                },
+            },
+            key: '/id',
+        },
+        document_chunks: {
+            schema: {
+                type: 'object',
+                required: ['id', 'sourceId', 'versionId', 'elementIds', 'text', 'tokenCount', 'order', 'headingPath', 'embedding', 'embeddedBy'],
+                properties: {
+                    id: ID,
+                    sourceId: ID,
+                    versionId: ID,
+                    elementIds: { type: 'array', items: { type: 'string' } },
+                    text: { type: 'string' },
+                    tokenCount: { type: 'integer' },
+                    order: { type: 'integer' },
+                    headingPath: { type: 'array', items: { type: 'string' } },
+                    embedding: { type: 'array', items: { type: 'number' } },
+                    embeddedBy: { type: 'object' },
+                },
+            },
+            key: '/id',
+        },
+        settings: {
+            schema: {
+                type: 'object',
+                required: ['key'],
+                properties: { key: ID, value: {} },
+            },
+            key: '/key',
+        },
+        config_identities: {
+            schema: {
+                type: 'object',
+                required: ['id', 'value'],
+                properties: {
+                    id: { type: 'string', pattern: '^[0-9a-f]{64}$' },
+                    value: { type: 'object' },
+                },
+            },
+            key: '/id',
+        },
+        // The eleven MAS semantic collections. The db-level schemas are
+        // deliberately minimal (the same rule as `memories`): the REAL write
+        // gate is the generated mas-runtime/mas-workflow contracts, enforced by
+        // `createMasStore` at the MasStore boundary — validating twice with two
+        // schemas invites drift. There is deliberately no mas_jobs, lease,
+        // retry, dead-letter or generic checkpoint collection: durable work is
+        // the suite's own `_jaren_jobs` / `_jaren_job_checkpoints`.
+        mas_workflows: {
+            schema: { type: 'object', required: ['id'], properties: { id: ID } },
+            key: '/id',
+        },
+        mas_workflow_versions: {
+            schema: { type: 'object', required: ['versionId'], properties: { versionId: { type: 'string', pattern: '^[0-9a-f]{64}$' } } },
+            key: '/versionId',
+        },
+        mas_templates: {
+            schema: { type: 'object', required: ['id'], properties: { id: ID } },
+            key: '/id',
+        },
+        mas_template_versions: {
+            schema: { type: 'object', required: ['versionId'], properties: { versionId: { type: 'string', pattern: '^[0-9a-f]{64}$' } } },
+            key: '/versionId',
+        },
+        mas_registry_snapshots: {
+            schema: { type: 'object', required: ['revision'], properties: { revision: { type: 'string', pattern: '^[0-9a-f]{64}$' } } },
+            key: '/revision',
+        },
+        mas_runs: {
+            schema: { type: 'object', required: ['id'], properties: { id: ID } },
+            key: '/id',
+        },
+        mas_node_attempts: {
+            schema: { type: 'object', required: ['id', 'runId'], properties: { id: ID, runId: ID } },
+            key: '/id',
+        },
+        mas_messages: {
+            schema: { type: 'object', required: ['id', 'runId'], properties: { id: ID, runId: ID } },
+            key: '/id',
+        },
+        mas_state_revisions: {
+            schema: { type: 'object', required: ['id', 'runId'], properties: { id: ID, runId: ID } },
+            key: '/id',
+        },
+        mas_interactions: {
+            schema: { type: 'object', required: ['id', 'runId'], properties: { id: ID, runId: ID } },
+            key: '/id',
+        },
+        mas_trace_artifacts: {
+            schema: { type: 'object', required: ['id', 'runId'], properties: { id: ID, runId: ID } },
+            key: '/id',
+        },
+    },
+};