@particle-academy/prism-graph 0.0.0-stage → 0.1.0

package/dist/graph.js

@@ -0,0 +1,176 @@
+import { sha256 } from './digest.js';
+import { GraphError, InvalidArgumentError } from './errors.js';
+import { IndexSpec } from './index-spec.js';
+import { DefaultAcceptancePolicy } from './trust.js';
+/**
+ * Long-term memory for agents. This object only holds the wiring (store,
+ * optional vectors and embedder, acceptance policy); it has NO read or write
+ * methods of its own. Everything goes through a scope, so an unscoped query
+ * cannot be written, by an app or by a model.
+ */
+export class Graph {
+    store;
+    vectors;
+    embedder;
+    policy;
+    constructor(store, vectors = null, embedder = null, policy = new DefaultAcceptancePolicy()) {
+        this.store = store;
+        this.vectors = vectors;
+        this.embedder = embedder;
+        this.policy = policy;
+        if ((vectors === null) !== (embedder === null)) {
+            throw new InvalidArgumentError('Configure a VectorStore and an Embedder together, or neither.');
+        }
+    }
+    scope(scope) {
+        return new ScopedGraph(scope, this.store, this.vectors, this.embedder, this.policy);
+    }
+}
+/**
+ * Memory as seen from one scope. Reads return what this scope can see (its own
+ * rows and those shared from wider scopes above it); writes land at exactly
+ * this scope. Nothing here widens a write.
+ */
+export class ScopedGraph {
+    memoryScope;
+    store;
+    vectors;
+    embedder;
+    policy;
+    static MAX_LIMIT = 200;
+    /** A query goes to the embedding provider and the full-text index, so it is bounded. */
+    static MAX_QUERY_BYTES = 4096;
+    static MAX_GET_IDS = 1000;
+    static RRF_K = 60;
+    constructor(memoryScope, store, vectors, embedder, policy) {
+        this.memoryScope = memoryScope;
+        this.store = store;
+        this.vectors = vectors;
+        this.embedder = embedder;
+        this.policy = policy;
+    }
+    scope() {
+        return this.memoryScope;
+    }
+    /**
+     * Store a source and its verbatim chunks at this scope. Idempotent per key:
+     * unchanged text stores and embeds nothing new; text the source no longer
+     * contains is retired from search. Verbatim is stored first and never waits
+     * on embedding; a failed embedding heals on the next ingest.
+     */
+    async ingest(key, uri, text, chunker, origin, options = {}) {
+        const actual = sha256(Buffer.from(text, 'utf8'));
+        if (options.sha256 !== undefined && options.sha256.toLowerCase() !== actual) {
+            throw new GraphError(`The provided sha256 for [${key}] does not match its text.`);
+        }
+        const chunks = chunker.chunk(this.memoryScope.qualify('source', key), text);
+        const { stored, retired } = await this.store.storeSource(this.memoryScope, key, uri, actual, options.metadata ?? {}, origin, options.occurredAt ?? null, chunks);
+        if (this.vectors !== null && this.embedder !== null && chunks.length > 0) {
+            const spec = this.spec();
+            await this.vectors.ensureIndex(spec);
+            const byId = new Map(chunks.map((c) => [c.id, c]));
+            const ids = [...byId.keys()];
+            for (let i = 0; i < ids.length; i += 500) {
+                const todo = await this.vectors.missing(spec, ids.slice(i, i + 500));
+                if (todo.length === 0) {
+                    continue;
+                }
+                const vectors = await this.embedder.embed(todo.map((id) => byId.get(id).text));
+                if (vectors.length !== todo.length) {
+                    throw new GraphError('The embedder returned a different number of vectors than chunks.');
+                }
+                await this.vectors.upsert(spec, new Map(todo.map((id, n) => [id, vectors[n]])));
+                // An erase that ran while the provider was embedding has already removed
+                // these chunks; erased text must not live on as an embedding.
+                const present = new Set((await this.store.getChunks(this.memoryScope, todo)).map((c) => c.id));
+                const gone = todo.filter((id) => !present.has(id));
+                if (gone.length > 0) {
+                    await this.vectors.forget(gone);
+                }
+            }
+        }
+        return { source: key, sha256: actual, recipe: chunker.recipe(), chunks: chunks.length, stored, retired };
+    }
+    /** Take a source at this scope out of search; it stays readable by id. */
+    async retireSource(key) {
+        return this.store.retireSource(this.memoryScope, key);
+    }
+    /** Erase a source stored at this scope: chunks, vectors, evidence links and orphaned facts. */
+    async erase(key) {
+        const report = await this.store.eraseSource(this.memoryScope, key);
+        if (this.vectors === null || report.chunkIds.length === 0) {
+            return report;
+        }
+        return { ...report, vectors: await this.vectors.forget(report.chunkIds) };
+    }
+    async get(chunkIds) {
+        if (chunkIds.length > ScopedGraph.MAX_GET_IDS) {
+            throw new InvalidArgumentError(`Pass at most ${ScopedGraph.MAX_GET_IDS} chunk ids.`);
+        }
+        return this.store.getChunks(this.memoryScope, chunkIds);
+    }
+    /**
+     * Hybrid search over what this scope can see: full-text (BM25) and, when
+     * configured and `vectors` is true, vectors, fused by reciprocal rank. A
+     * chunk with no vector yet still ranks through text.
+     */
+    async search(query, limit = 10, vectors = true) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > ScopedGraph.MAX_LIMIT) {
+            throw new InvalidArgumentError(`limit must be between 1 and ${ScopedGraph.MAX_LIMIT}.`);
+        }
+        if (Buffer.byteLength(query, 'utf8') > ScopedGraph.MAX_QUERY_BYTES) {
+            throw new InvalidArgumentError(`A query may be at most ${ScopedGraph.MAX_QUERY_BYTES} bytes.`);
+        }
+        if (!query.isWellFormed()) {
+            throw new InvalidArgumentError('A query must be valid UTF-8.');
+        }
+        const lists = new Map([['text', (await this.store.textSearch(this.memoryScope, query, limit * 3)).map((r) => r.chunkId)]]);
+        if (vectors && this.vectors !== null && this.embedder !== null && query.trim() !== '') {
+            const embedded = (await this.embedder.embed([query]))[0];
+            lists.set(this.vectors.method(), (await this.vectors.nearest(this.spec(), embedded, Math.min(1000, limit * 10))).map((r) => r.chunkId));
+        }
+        const fused = new Map();
+        const methods = new Map();
+        for (const [method, ids] of lists) {
+            ids.forEach((id, rank) => {
+                fused.set(id, (fused.get(id) ?? 0) + 1 / (ScopedGraph.RRF_K + rank + 1));
+                methods.set(id, [...(methods.get(id) ?? []), method]);
+            });
+        }
+        if (fused.size === 0) {
+            return [];
+        }
+        // Visibility and retirement are applied by the store, in SQL.
+        const chunks = (await this.store.getChunks(this.memoryScope, [...fused.keys()])).filter((c) => c.retiredAt == null);
+        return chunks
+            .map((chunk) => ({ chunk, score: fused.get(chunk.id), method: methods.get(chunk.id).length > 1 ? 'hybrid' : methods.get(chunk.id)[0] }))
+            .sort((a, b) => b.score - a.score || (a.chunk.id < b.chunk.id ? -1 : 1))
+            .slice(0, limit);
+    }
+    async facts(subject, options = {}) {
+        return this.store.facts(this.memoryScope, subject, options);
+    }
+    async timeline(subject) {
+        return this.store.timeline(this.memoryScope, subject);
+    }
+    /** Store a fact at this scope; its status comes from the acceptance policy. */
+    async assert(fact) {
+        return this.store.assertFact(this.memoryScope, fact, this.policy);
+    }
+    async supersede(oldKey, replacement) {
+        return this.store.supersede(this.memoryScope, oldKey, replacement, this.policy);
+    }
+    /** An app decision, never a tool. */
+    async retract(key) {
+        return this.store.retract(this.memoryScope, key);
+    }
+    /** An app decision, never a tool: a proposed fact becomes accepted. */
+    async accept(key) {
+        return this.store.accept(this.memoryScope, key);
+    }
+    /** The vector index for this tenant: another tenant's vectors can neither crowd nor appear in its results. */
+    spec() {
+        const base = this.embedder.spec();
+        return new IndexSpec(`${base.name.slice(0, 80)}.t${sha256(this.memoryScope.tenant).slice(0, 16)}`, base.provider, base.model, base.dimensions, base.recipe);
+    }
+}

package/dist/index-spec.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The embedder an index is pinned to. Vectors from a different provider,
+ * model, dimension count or recipe are refused, never mixed into the index.
+ */
+export declare class IndexSpec {
+    readonly name: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly dimensions: number;
+    readonly recipe: string;
+    constructor(name: string, provider: string, model: string, dimensions: number, recipe?: string);
+    /** Stable identity of the embedder, identical to the PHP reference's fingerprint(). */
+    fingerprint(): string;
+}

package/dist/index-spec.js

@@ -0,0 +1,31 @@
+import { digest } from './digest.js';
+import { InvalidArgumentError } from './errors.js';
+/**
+ * The embedder an index is pinned to. Vectors from a different provider,
+ * model, dimension count or recipe are refused, never mixed into the index.
+ */
+export class IndexSpec {
+    name;
+    provider;
+    model;
+    dimensions;
+    recipe;
+    constructor(name, provider, model, dimensions, recipe = 'raw@1') {
+        this.name = name;
+        this.provider = provider;
+        this.model = model;
+        this.dimensions = dimensions;
+        this.recipe = recipe;
+        if (!/^[A-Za-z0-9_.:-]{1,100}$/.test(name)) {
+            throw new InvalidArgumentError('Index names are 1-100 of A-Z a-z 0-9 _ . : -');
+        }
+        if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 65536) {
+            throw new InvalidArgumentError('Dimensions must be between 1 and 65536.');
+        }
+        Object.freeze(this);
+    }
+    /** Stable identity of the embedder, identical to the PHP reference's fingerprint(). */
+    fingerprint() {
+        return digest('prism-graph/index@1', [this.provider, this.model, this.dimensions, this.recipe]);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { type Chunk, type Chunker, chunkId } from './chunk.js';
+export { MarkdownChunker } from './chunking/markdown.js';
+export { WindowChunker } from './chunking/window.js';
+export { digest, sha256 } from './digest.js';
+export { GraphError, InvalidArgumentError } from './errors.js';
+export type { EraseReport, Fact, IngestReport } from './fact.js';
+export { Graph, ScopedGraph, type Hit } from './graph.js';
+export { IndexSpec } from './index-spec.js';
+export { Scope } from './scope.js';
+export { NodeSqliteDriver, type Row, type SqlDriver, type SqlValue } from './storage/driver.js';
+export { baseSchema, fullTextSchema, repairFullTextSchema, TableMap, vectorSchema } from './storage/schema.js';
+export { ftsMatch, GraphStore, normaliseTime } from './storage/store.js';
+export { MAX_IDS, MAX_NOTE_BYTES, MAX_RESULTS, memoryTools, type MemoryToolDefinition } from './tools.js';
+export { type AcceptancePolicy, DefaultAcceptancePolicy, FactStatus, isTrust, Origin, Trust } from './trust.js';
+export { float32, MAX_K, SqliteVectorStore, type Embedder, type VectorStore } from './vectors.js';
+export { markVisible, scrubUtf8 } from './visible.js';
+export { FactsLayer, SearchLayer, Wake, WakeReport, type WakeIncluded, type WakeItem, type WakeLayer } from './wake.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export { chunkId } from './chunk.js';
+export { MarkdownChunker } from './chunking/markdown.js';
+export { WindowChunker } from './chunking/window.js';
+export { digest, sha256 } from './digest.js';
+export { GraphError, InvalidArgumentError } from './errors.js';
+export { Graph, ScopedGraph } from './graph.js';
+export { IndexSpec } from './index-spec.js';
+export { Scope } from './scope.js';
+export { NodeSqliteDriver } from './storage/driver.js';
+export { baseSchema, fullTextSchema, repairFullTextSchema, TableMap, vectorSchema } from './storage/schema.js';
+export { ftsMatch, GraphStore, normaliseTime } from './storage/store.js';
+export { MAX_IDS, MAX_NOTE_BYTES, MAX_RESULTS, memoryTools } from './tools.js';
+export { DefaultAcceptancePolicy, FactStatus, isTrust, Origin, Trust } from './trust.js';
+export { float32, MAX_K, SqliteVectorStore } from './vectors.js';
+export { markVisible, scrubUtf8 } from './visible.js';
+export { FactsLayer, SearchLayer, Wake, WakeReport } from './wake.js';

package/dist/scope.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Where a memory lives and who can read it. Every read and write goes through
+ * one; there is no unscoped query.
+ *
+ * Levels nest: tenant > owner > agent > thread. An agent needs an owner and a
+ * thread needs an agent, so no row can be visible across owners except a
+ * tenant-wide one written deliberately at tenant level.
+ *
+ * A reader at (t, o, a, th) sees rows whose tenant is t and whose every
+ * narrower level is either unset (shared upward) or exactly its own.
+ */
+export declare class Scope {
+    readonly tenant: string;
+    readonly owner: string | null;
+    readonly agent: string | null;
+    readonly thread: string | null;
+    constructor(tenant: string, owner?: string | null, agent?: string | null, thread?: string | null);
+    static tenant(tenant: string): Scope;
+    withOwner(owner: string): Scope;
+    withAgent(agent: string): Scope;
+    withThread(thread: string): Scope;
+    level(): 'tenant' | 'owner' | 'agent' | 'thread';
+    /** Can a reader at this scope see a row stored at `row`? */
+    canSee(row: Scope): boolean;
+    /** The internal id for an app-supplied key at this scope (identical to the PHP reference). */
+    qualify(kind: string, key: string): string;
+    toRow(): [string, string | null, string | null, string | null];
+}

package/dist/scope.js

@@ -0,0 +1,70 @@
+import { digest } from './digest.js';
+import { InvalidArgumentError } from './errors.js';
+const ID = /^[A-Za-z0-9_.:@/-]{1,191}$/;
+/**
+ * Where a memory lives and who can read it. Every read and write goes through
+ * one; there is no unscoped query.
+ *
+ * Levels nest: tenant > owner > agent > thread. An agent needs an owner and a
+ * thread needs an agent, so no row can be visible across owners except a
+ * tenant-wide one written deliberately at tenant level.
+ *
+ * A reader at (t, o, a, th) sees rows whose tenant is t and whose every
+ * narrower level is either unset (shared upward) or exactly its own.
+ */
+export class Scope {
+    tenant;
+    owner;
+    agent;
+    thread;
+    constructor(tenant, owner = null, agent = null, thread = null) {
+        for (const [level, value] of [['tenant', tenant], ['owner', owner], ['agent', agent], ['thread', thread]]) {
+            if (value !== null && (typeof value !== 'string' || !ID.test(value))) {
+                throw new InvalidArgumentError(`Scope ${level} must be 1-191 of A-Z a-z 0-9 _ . : @ / -`);
+            }
+        }
+        if (agent !== null && owner === null) {
+            throw new InvalidArgumentError('An agent scope needs an owner: agent memory is always about someone.');
+        }
+        if (thread !== null && agent === null) {
+            throw new InvalidArgumentError('A thread scope needs an agent.');
+        }
+        this.tenant = tenant;
+        this.owner = owner;
+        this.agent = agent;
+        this.thread = thread;
+        Object.freeze(this);
+    }
+    static tenant(tenant) {
+        return new Scope(tenant);
+    }
+    withOwner(owner) {
+        return new Scope(this.tenant, owner);
+    }
+    withAgent(agent) {
+        if (this.owner === null) {
+            throw new InvalidArgumentError('Set the owner before the agent.');
+        }
+        return new Scope(this.tenant, this.owner, agent);
+    }
+    withThread(thread) {
+        return new Scope(this.tenant, this.owner, this.agent, thread);
+    }
+    level() {
+        return this.thread !== null ? 'thread' : this.agent !== null ? 'agent' : this.owner !== null ? 'owner' : 'tenant';
+    }
+    /** Can a reader at this scope see a row stored at `row`? */
+    canSee(row) {
+        return row.tenant === this.tenant
+            && (row.owner === null || row.owner === this.owner)
+            && (row.agent === null || row.agent === this.agent)
+            && (row.thread === null || row.thread === this.thread);
+    }
+    /** The internal id for an app-supplied key at this scope (identical to the PHP reference). */
+    qualify(kind, key) {
+        return digest(`prism-graph/${kind}@1`, [this.tenant, this.owner ?? '', this.agent ?? '', this.thread ?? '', key]);
+    }
+    toRow() {
+        return [this.tenant, this.owner, this.agent, this.thread];
+    }
+}

package/dist/storage/driver.d.ts

@@ -0,0 +1,49 @@
+import type { DatabaseSync } from 'node:sqlite';
+export type SqlValue = string | number | bigint | null | Uint8Array;
+export type Row = Record<string, unknown>;
+/**
+ * The SQL the stores need, and nothing else. Every value is a bound
+ * parameter ("?" placeholders); table names come only from a validated
+ * TableMap.
+ *
+ * `atomic()` is all-or-nothing INCLUDING inside a caller's own transaction:
+ * the work runs in a SAVEPOINT, so a refusal or failure rolls back exactly
+ * prism-graph's work and leaves the caller's transaction usable. (The PHP
+ * reference had to learn this the hard way: see its 0.2.1 notes.)
+ */
+export interface SqlDriver {
+    readonly dialect: 'sqlite';
+    run(sql: string, params?: readonly SqlValue[]): Promise<number>;
+    all(sql: string, params?: readonly SqlValue[]): Promise<Row[]>;
+    exec(sql: string): Promise<void>;
+    atomic<T>(work: () => Promise<T>): Promise<T>;
+}
+/**
+ * SQLite through Node's built-in node:sqlite (Node 22.16+): no native module,
+ * no third-party dependency. Needs SQLite with FTS5, which node:sqlite has.
+ *
+ * GIVE IT A CONNECTION OF ITS OWN, or route every write on that connection
+ * through `atomic()`. SQLite transactions belong to the connection: a write
+ * another part of the app makes while one of our blocks is open lands inside
+ * our savepoint, and is rolled back with it if our block fails.
+ *
+ * Atomic blocks are serialised on the connection. A block opened inside
+ * another (the same async call chain) queues inside its parent; a callback
+ * that outlives its block (a timer, an un-awaited promise) is treated as a
+ * new caller, never as part of a block that has already closed.
+ */
+export declare class NodeSqliteDriver implements SqlDriver {
+    private readonly db;
+    readonly dialect: "sqlite";
+    private queue;
+    /** Only ever increases: savepoint names are unique for the life of the driver. */
+    private counter;
+    private readonly inside;
+    constructor(db: DatabaseSync);
+    run(sql: string, params?: readonly SqlValue[]): Promise<number>;
+    all(sql: string, params?: readonly SqlValue[]): Promise<Row[]>;
+    exec(sql: string): Promise<void>;
+    atomic<T>(work: () => Promise<T>): Promise<T>;
+    private savepoint;
+    private rollback;
+}

package/dist/storage/driver.js

@@ -0,0 +1,100 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { GraphError } from '../errors.js';
+/**
+ * SQLite through Node's built-in node:sqlite (Node 22.16+): no native module,
+ * no third-party dependency. Needs SQLite with FTS5, which node:sqlite has.
+ *
+ * GIVE IT A CONNECTION OF ITS OWN, or route every write on that connection
+ * through `atomic()`. SQLite transactions belong to the connection: a write
+ * another part of the app makes while one of our blocks is open lands inside
+ * our savepoint, and is rolled back with it if our block fails.
+ *
+ * Atomic blocks are serialised on the connection. A block opened inside
+ * another (the same async call chain) queues inside its parent; a callback
+ * that outlives its block (a timer, an un-awaited promise) is treated as a
+ * new caller, never as part of a block that has already closed.
+ */
+export class NodeSqliteDriver {
+    db;
+    dialect = 'sqlite';
+    queue = Promise.resolve();
+    /** Only ever increases: savepoint names are unique for the life of the driver. */
+    counter = 0;
+    inside = new AsyncLocalStorage();
+    constructor(db) {
+        this.db = db;
+        if (typeof db.isTransaction !== 'boolean') {
+            // Without it, a failed commit cannot be told apart from a caller's own
+            // transaction, and a stuck connection would silently lose later writes.
+            throw new GraphError('prism-graph needs node:sqlite with DatabaseSync.isTransaction (Node 22.16+).');
+        }
+    }
+    async run(sql, params = []) {
+        return Number(this.db.prepare(sql).run(...params.map(bind)).changes);
+    }
+    async all(sql, params = []) {
+        return this.db.prepare(sql).all(...params.map(bind));
+    }
+    async exec(sql) {
+        this.db.exec(sql);
+    }
+    atomic(work) {
+        const parent = this.inside.getStore();
+        if (parent?.open === true) {
+            // Nested in an open block: run inside it, one nested block at a time.
+            const result = parent.queue.then(() => this.savepoint(work, false));
+            parent.queue = result.catch(() => undefined);
+            return result;
+        }
+        const result = this.queue.then(() => this.savepoint(work, true));
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+    async savepoint(work, outermost) {
+        // In SQLite a SAVEPOINT outside a transaction opens one, and RELEASE
+        // commits it; inside the caller's transaction it nests. One rule for both.
+        // Remember whether THIS block opened the transaction: only then may a
+        // failure close it with a full ROLLBACK.
+        const opened = outermost && !this.db.isTransaction;
+        const name = `prism_graph_sp_${++this.counter}`;
+        this.db.exec(`SAVEPOINT ${name}`);
+        const block = { queue: Promise.resolve(), open: true };
+        let result;
+        try {
+            result = await this.inside.run(block, work);
+            await block.queue; // nested blocks the work started but did not await
+        }
+        catch (error) {
+            block.open = false;
+            this.rollback(name, opened);
+            throw error;
+        }
+        block.open = false;
+        try {
+            this.db.exec(`RELEASE SAVEPOINT ${name}`);
+        }
+        catch (error) {
+            // The commit itself failed (e.g. SQLITE_BUSY on the outermost RELEASE):
+            // undo our work and never leave the connection inside a transaction,
+            // where every later write would report success and be lost.
+            this.rollback(name, opened);
+            throw error;
+        }
+        return result;
+    }
+    rollback(name, opened) {
+        try {
+            this.db.exec(`ROLLBACK TO SAVEPOINT ${name}`);
+            this.db.exec(`RELEASE SAVEPOINT ${name}`);
+        }
+        catch {
+            // Fall through: if we opened the transaction, close it below.
+        }
+        if (opened && this.db.isTransaction) {
+            this.db.exec('ROLLBACK');
+        }
+    }
+}
+function bind(value) {
+    return value === undefined ? null : value;
+}

package/dist/storage/schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which app-owned tables play each role. Apps create and extend these tables
+ * in their own migrations; the package only reads and writes the core columns
+ * it documents. Names are capped at 50 characters so derived names stay inside
+ * PostgreSQL's 63-character identifier limit.
+ */
+export declare class TableMap {
+    readonly sources: string;
+    readonly chunks: string;
+    readonly facts: string;
+    readonly evidence: string;
+    constructor(sources?: string, chunks?: string, facts?: string, evidence?: string);
+    /** The full-text index over chunks (an FTS5 table on SQLite). */
+    fts(): string;
+}
+/**
+ * The core schema, as plain SQL for SQLite, matching the PHP reference's
+ * BaseSchema. The package never creates tables at runtime: apps run these from
+ * their own migration tooling, and own them afterwards.
+ */
+export declare function baseSchema(t?: TableMap): string[];
+/** External-content FTS5 kept in step by triggers; the text lives once, in the chunks table. */
+export declare function fullTextSchema(t?: TableMap): string[];
+/**
+ * Restore the full-text index after a migration that rebuilt the chunks table
+ * (which drops its triggers), and rebuild it from the stored chunks. Safe to
+ * run at any time.
+ */
+export declare function repairFullTextSchema(t?: TableMap): string[];
+/** The optional vector tables (exact cosine search over packed float32). */
+export declare function vectorSchema(indexes?: string, vectors?: string): string[];

package/dist/storage/schema.js

@@ -0,0 +1,102 @@
+import { InvalidArgumentError } from '../errors.js';
+/**
+ * Which app-owned tables play each role. Apps create and extend these tables
+ * in their own migrations; the package only reads and writes the core columns
+ * it documents. Names are capped at 50 characters so derived names stay inside
+ * PostgreSQL's 63-character identifier limit.
+ */
+export class TableMap {
+    sources;
+    chunks;
+    facts;
+    evidence;
+    constructor(sources = 'graph_sources', chunks = 'graph_chunks', facts = 'graph_facts', evidence = 'graph_fact_evidence') {
+        this.sources = sources;
+        this.chunks = chunks;
+        this.facts = facts;
+        this.evidence = evidence;
+        for (const [role, table] of Object.entries({ sources, chunks, facts, evidence })) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]{0,49}$/.test(table)) {
+                throw new InvalidArgumentError(`Invalid table name for ${role}.`);
+            }
+        }
+        Object.freeze(this);
+    }
+    /** The full-text index over chunks (an FTS5 table on SQLite). */
+    fts() {
+        return `${this.chunks}_fts`;
+    }
+}
+/**
+ * The core schema, as plain SQL for SQLite, matching the PHP reference's
+ * BaseSchema. The package never creates tables at runtime: apps run these from
+ * their own migration tooling, and own them afterwards.
+ */
+export function baseSchema(t = new TableMap()) {
+    const scope = 'tenant_id VARCHAR(191) NOT NULL, owner_id VARCHAR(191), agent_id VARCHAR(191), thread_id VARCHAR(191)';
+    return [
+        `CREATE TABLE ${t.sources} (id CHAR(64) PRIMARY KEY, source_key VARCHAR(191) NOT NULL, ${scope},
+      uri TEXT NOT NULL, sha256 CHAR(64) NOT NULL, metadata TEXT NOT NULL,
+      trust VARCHAR(20) NOT NULL, writer VARCHAR(191) NOT NULL,
+      occurred_at CHAR(27), recorded_at CHAR(27) NOT NULL)`,
+        `CREATE INDEX ${t.sources}_scope ON ${t.sources} (tenant_id, owner_id, agent_id, thread_id)`,
+        // seq is the explicit integer key the full-text index joins on: an implicit
+        // rowid is not guaranteed stable across VACUUM.
+        `CREATE TABLE ${t.chunks} (seq INTEGER PRIMARY KEY, id CHAR(64) NOT NULL UNIQUE, source_id CHAR(64) NOT NULL REFERENCES ${t.sources} (id),
+      text TEXT NOT NULL, byte_start INTEGER NOT NULL, byte_end INTEGER NOT NULL,
+      line_start INTEGER NOT NULL, line_end INTEGER NOT NULL, heading_path TEXT NOT NULL,
+      recipe VARCHAR(191) NOT NULL, retired_at CHAR(27))`,
+        `CREATE INDEX ${t.chunks}_source ON ${t.chunks} (source_id, byte_start)`,
+        `CREATE TABLE ${t.facts} (id CHAR(64) PRIMARY KEY, fact_key VARCHAR(191) NOT NULL, ${scope},
+      subject VARCHAR(191) NOT NULL, predicate VARCHAR(191) NOT NULL, object TEXT NOT NULL,
+      status VARCHAR(20) NOT NULL, valid_from CHAR(27) NOT NULL, valid_to CHAR(27),
+      superseded_by VARCHAR(191), recorded_at CHAR(27) NOT NULL, expired_at CHAR(27))`,
+        `CREATE INDEX ${t.facts}_subject ON ${t.facts} (tenant_id, subject, valid_to)`,
+        `CREATE TABLE ${t.evidence} (fact_id CHAR(64) NOT NULL REFERENCES ${t.facts} (id),
+      chunk_id CHAR(64) NOT NULL REFERENCES ${t.chunks} (id), PRIMARY KEY (fact_id, chunk_id))`,
+        `CREATE INDEX ${t.evidence}_chunk ON ${t.evidence} (chunk_id)`,
+        ...fullTextSchema(t),
+    ];
+}
+/** External-content FTS5 kept in step by triggers; the text lives once, in the chunks table. */
+export function fullTextSchema(t = new TableMap()) {
+    const fts = t.fts();
+    return [
+        `CREATE VIRTUAL TABLE ${fts} USING fts5(text, content='${t.chunks}', content_rowid='seq', tokenize='unicode61')`,
+        `CREATE TRIGGER ${t.chunks}_ai AFTER INSERT ON ${t.chunks} BEGIN
+      INSERT INTO ${fts} (rowid, text) VALUES (new.seq, new.text); END`,
+        `CREATE TRIGGER ${t.chunks}_ad AFTER DELETE ON ${t.chunks} BEGIN
+      INSERT INTO ${fts} (${fts}, rowid, text) VALUES ('delete', old.seq, old.text); END`,
+        `CREATE TRIGGER ${t.chunks}_au AFTER UPDATE OF text ON ${t.chunks} BEGIN
+      INSERT INTO ${fts} (${fts}, rowid, text) VALUES ('delete', old.seq, old.text);
+      INSERT INTO ${fts} (rowid, text) VALUES (new.seq, new.text); END`,
+    ];
+}
+/**
+ * Restore the full-text index after a migration that rebuilt the chunks table
+ * (which drops its triggers), and rebuild it from the stored chunks. Safe to
+ * run at any time.
+ */
+export function repairFullTextSchema(t = new TableMap()) {
+    const fts = t.fts();
+    const [virtual, insert, del, update] = fullTextSchema(t);
+    return [
+        virtual.replace('CREATE VIRTUAL TABLE', 'CREATE VIRTUAL TABLE IF NOT EXISTS'),
+        `DROP TRIGGER IF EXISTS ${t.chunks}_ai`,
+        `DROP TRIGGER IF EXISTS ${t.chunks}_ad`,
+        `DROP TRIGGER IF EXISTS ${t.chunks}_au`,
+        insert,
+        del,
+        update,
+        `INSERT INTO ${fts} (${fts}) VALUES ('rebuild')`,
+    ];
+}
+/** The optional vector tables (exact cosine search over packed float32). */
+export function vectorSchema(indexes = 'graph_vector_indexes', vectors = 'graph_vectors') {
+    return [
+        `CREATE TABLE ${indexes} (name VARCHAR(100) PRIMARY KEY, fingerprint CHAR(64) NOT NULL, provider VARCHAR(100) NOT NULL,
+      model VARCHAR(191) NOT NULL, dimensions INTEGER NOT NULL, recipe VARCHAR(191) NOT NULL)`,
+        `CREATE TABLE ${vectors} (index_name VARCHAR(100) NOT NULL REFERENCES ${indexes} (name), chunk_id CHAR(64) NOT NULL,
+      vector BLOB NOT NULL, PRIMARY KEY (index_name, chunk_id))`,
+    ];
+}