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

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))`,
+    ];
+}

package/dist/storage/store.d.ts

@@ -0,0 +1,129 @@
+import { type Chunk } from '../chunk.js';
+import type { EraseReport, Fact } from '../fact.js';
+import type { Scope } from '../scope.js';
+import { type AcceptancePolicy, type Origin } from '../trust.js';
+import type { SqlDriver } from './driver.js';
+import { TableMap } from './schema.js';
+export declare const MAX_QUERY_TERMS = 16;
+export interface StoredSource {
+    readonly source: string;
+    readonly stored: number;
+    readonly retired: number;
+}
+/**
+ * Scoped memory storage over a SqlDriver, a port of the PHP reference's
+ * PdoGraphStore. SCOPE IS PART OF EVERY QUERY: reads apply the visibility
+ * predicate in SQL, so a row outside the reader's scope is never fetched.
+ * Every write runs in driver.atomic(): all-or-nothing, including inside the
+ * caller's own transaction.
+ */
+/** A source in a listing (G-282, contract g282.1). */
+export interface ListedSource {
+    readonly sourceId: string;
+    readonly title: string;
+    readonly kind: string | null;
+    readonly createdAt: string;
+    readonly chunkCount: number;
+    readonly trust: string;
+}
+/** A chunk in a listing (G-282, contract g282.1). */
+export interface ListedChunk {
+    readonly chunkId: string;
+    readonly sourceId: string;
+    readonly text: string;
+    readonly position: number;
+    readonly provenance: {
+        readonly uri: string;
+        readonly sha256: string;
+        readonly byteStart: number;
+        readonly byteEnd: number;
+        readonly lineStart: number;
+        readonly lineEnd: number;
+        readonly headingPath: string[];
+        readonly recipe: string;
+        readonly trust: string;
+        readonly writer: string;
+        readonly recordedAt: string;
+    };
+}
+/** A page of a listing. A consumer refuses a contractVersion it does not know. */
+export interface ListingPage<T> {
+    readonly contractVersion: 'g282.1';
+    readonly items: T[];
+    readonly nextCursor: string | null;
+}
+export declare class GraphStore {
+    private readonly db;
+    private readonly tables;
+    private readonly clock;
+    constructor(db: SqlDriver, tables?: TableMap, clock?: () => string);
+    /**
+     * Store a source and its verbatim chunks at `scope`, in ONE atomic block.
+     * A source's trust is fixed when first stored: the upsert itself refuses a
+     * different trust, so there is no read-then-write window.
+     */
+    storeSource(scope: Scope, key: string, uri: string, sha256: string, metadata: Record<string, unknown>, origin: Origin, occurredAt: string | null, chunks: readonly Chunk[]): Promise<StoredSource>;
+    /** Retire every chunk of a source stored at exactly `scope`. */
+    retireSource(scope: Scope, key: string): Promise<number>;
+    /** Chunks visible from `reader`, in the order asked. */
+    getChunks(reader: Scope, ids: readonly string[]): Promise<Chunk[]>;
+    /**
+     * Sources visible from `reader`, newest first, with at least one live chunk (G-282, contract g282.1). Rows are in
+     * the agreed shape; the caller pages with `after` = [createdAt, sourceId] of the last item it returned.
+     */
+    listSources(reader: Scope, after: readonly [string, string] | null, limit: number): Promise<ListedSource[]>;
+    /** Live chunks of one source visible from `reader`, in source order. A source outside the scope yields nothing. */
+    listChunks(reader: Scope, sourceId: string, afterSeq: number | null, limit: number): Promise<Array<ListedChunk & {
+        seq: number;
+    }>>;
+    /** Full-text search over live chunks visible from `reader`, best first. */
+    textSearch(reader: Scope, query: string, limit: number): Promise<Array<{
+        chunkId: string;
+        score: number;
+    }>>;
+    assertFact(scope: Scope, fact: Fact, policy: AcceptancePolicy): Promise<Fact>;
+    /**
+     * The world changed: close `oldKey`'s valid time and record the replacement.
+     * The overwrite guard decides BEFORE any write: an accepted fact is closed
+     * only for a replacement the policy also accepts, in the same statement.
+     */
+    supersede(scope: Scope, oldKey: string, replacement: Fact, policy: AcceptancePolicy): Promise<Fact>;
+    /**
+     * We were wrong: end the fact's RECORDED time. An app decision, never a
+     * tool: it does not check the acceptance policy, so retract-then-assert can
+     * replace an accepted fact with weaker evidence; use supersede() to record
+     * that the world changed.
+     */
+    retract(scope: Scope, key: string): Promise<void>;
+    /** An app decision: a proposed fact still in force becomes accepted. */
+    accept(scope: Scope, key: string): Promise<void>;
+    facts(reader: Scope, subject: string, options?: {
+        at?: string | null;
+        knownAt?: string | null;
+        unaccepted?: boolean;
+    }): Promise<Fact[]>;
+    /** Every version of every fact about `subject` visible from `reader`, oldest first. */
+    timeline(reader: Scope, subject: string): Promise<Fact[]>;
+    /** Erase a source stored at exactly `scope`: its chunks, their evidence links, and every fact left with no evidence. */
+    eraseSource(scope: Scope, key: string): Promise<EraseReport>;
+    /** Validate a fact and decide its status, READING ONLY. */
+    private prepareFact;
+    private writeFact;
+    private retireExcept;
+    /** The visibility predicate for a reader, over a table aliased `alias` carrying the scope columns. */
+    private visible;
+    private toFact;
+    private now;
+}
+/**
+ * An FTS5 MATCH expression in which every term is a quoted string (inner quotes
+ * doubled): a literal, never an operator, column filter or prefix. ORed, so
+ * BM25 ranks partial matches instead of dropping them.
+ */
+export declare function ftsMatch(terms: readonly string[]): string;
+/**
+ * Validate a UTC ISO 8601 time and return it in ONE fixed-width form
+ * (microseconds, Z), identical to the PHP reference, so stored times compare
+ * correctly as strings whatever precision they were given in.
+ */
+export declare function normaliseTime(value: string): string;

package/dist/storage/store.js

@@ -0,0 +1,391 @@
+import { chunkId } from '../chunk.js';
+import { GraphError, InvalidArgumentError } from '../errors.js';
+import { FactStatus, isTrust, Trust } from '../trust.js';
+import { TableMap } from './schema.js';
+export const MAX_QUERY_TERMS = 16;
+const TIME = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(\.\d{1,6})?Z$/;
+const KEY = /^[\x21-\x7E]{1,191}$/;
+export class GraphStore {
+    db;
+    tables;
+    clock;
+    constructor(db, tables = new TableMap(), clock = () => new Date().toISOString()) {
+        this.db = db;
+        this.tables = tables;
+        this.clock = clock;
+    }
+    /**
+     * Store a source and its verbatim chunks at `scope`, in ONE atomic block.
+     * A source's trust is fixed when first stored: the upsert itself refuses a
+     * different trust, so there is no read-then-write window.
+     */
+    async storeSource(scope, key, uri, sha256, metadata, origin, occurredAt, chunks) {
+        assertKey(key);
+        const id = scope.qualify('source', key);
+        const occurred = occurredAt === null ? null : normaliseTime(occurredAt);
+        return this.db.atomic(async () => {
+            const written = await this.db.run(`INSERT INTO ${this.tables.sources}
+         (id, source_key, tenant_id, owner_id, agent_id, thread_id, uri, sha256, metadata, trust, writer, occurred_at, recorded_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT (id) DO UPDATE SET uri = excluded.uri, sha256 = excluded.sha256, metadata = excluded.metadata,
+            writer = excluded.writer, occurred_at = excluded.occurred_at
+         WHERE ${this.tables.sources}.trust = excluded.trust`, [id, key, ...scope.toRow(), uri, sha256, JSON.stringify(metadata), origin.trust, origin.writer, occurred, this.now()]);
+            if (written !== 1) {
+                const stored = (await this.db.all(`SELECT trust FROM ${this.tables.sources} WHERE id = ?`, [id]))[0]?.['trust'] ?? 'unknown';
+                throw new GraphError(`Source [${key}] was stored with trust [${String(stored)}]; trust cannot change. Erase it and ingest again.`);
+            }
+            let stored = 0;
+            const keep = [];
+            for (const chunk of chunks) {
+                if (chunk.sourceId !== id) {
+                    throw new GraphError('A chunk belongs to a different source than the one being stored.');
+                }
+                if (chunkId(chunk.recipe, chunk.sourceId, chunk.byteStart, chunk.byteEnd, Buffer.from(chunk.text, 'utf8')) !== chunk.id) {
+                    throw new GraphError('A chunk id does not match its content; ids are content-addressed.');
+                }
+                if (chunk.byteStart < 0 || Buffer.byteLength(chunk.text, 'utf8') !== chunk.byteEnd - chunk.byteStart) {
+                    throw new GraphError('A chunk text must be exactly the bytes of its span.');
+                }
+                stored += await this.db.run(`INSERT INTO ${this.tables.chunks} (id, source_id, text, byte_start, byte_end, line_start, line_end, heading_path, recipe)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (id) DO NOTHING`, [chunk.id, chunk.sourceId, chunk.text, chunk.byteStart, chunk.byteEnd, chunk.lineStart, chunk.lineEnd, JSON.stringify(chunk.headingPath), chunk.recipe]);
+                keep.push(chunk.id);
+            }
+            return { source: id, stored, retired: await this.retireExcept(id, keep) };
+        });
+    }
+    /** Retire every chunk of a source stored at exactly `scope`. */
+    async retireSource(scope, key) {
+        return this.db.atomic(() => this.retireExcept(scope.qualify('source', key), []));
+    }
+    /** Chunks visible from `reader`, in the order asked. */
+    async getChunks(reader, ids) {
+        const wanted = [...new Set(ids.filter((id) => typeof id === 'string'))];
+        const byId = new Map();
+        for (const batch of batches(wanted, 500)) {
+            const [visible, bindings] = this.visible('s', reader);
+            const rows = await this.db.all(`SELECT c.*, s.source_key, s.trust FROM ${this.tables.chunks} c
+         JOIN ${this.tables.sources} s ON s.id = c.source_id
+         WHERE c.id IN (${marks(batch)}) AND ${visible}`, [...batch, ...bindings]);
+            for (const row of rows) {
+                byId.set(String(row['id']), toChunk(row));
+            }
+        }
+        return wanted.map((id) => byId.get(id)).filter((c) => c !== undefined);
+    }
+    /**
+     * Sources visible from `reader`, newest first, with at least one live chunk (G-282, contract g282.1). Rows are in
+     * the agreed shape; the caller pages with `after` = [createdAt, sourceId] of the last item it returned.
+     */
+    async listSources(reader, after, limit) {
+        const [visible, bindings] = this.visible('s', reader);
+        const live = `SELECT 1 FROM ${this.tables.chunks} c WHERE c.source_id = s.id AND c.retired_at IS NULL`;
+        const page = after === null ? '' : ' AND (s.recorded_at < ? OR (s.recorded_at = ? AND s.id < ?))';
+        const rows = await this.db.all(`SELECT s.id, s.uri, s.metadata, s.trust, s.recorded_at,
+              (SELECT COUNT(*) FROM ${this.tables.chunks} c WHERE c.source_id = s.id AND c.retired_at IS NULL) AS chunk_count
+       FROM ${this.tables.sources} s
+       WHERE ${visible} AND EXISTS (${live})${page}
+       ORDER BY s.recorded_at DESC, s.id DESC
+       LIMIT ${Math.max(1, Math.min(1001, Math.trunc(limit)))}`, after === null ? bindings : [...bindings, after[0], after[0], after[1]]);
+        return rows.map((row) => {
+            let metadata;
+            try {
+                metadata = JSON.parse(String(row['metadata']));
+            }
+            catch {
+                metadata = {};
+            }
+            const meta = typeof metadata === 'object' && metadata !== null ? metadata : {};
+            const title = typeof meta['title'] === 'string' && meta['title'] !== '' ? meta['title'] : String(row['uri']);
+            const kind = typeof meta['kind'] === 'string' && meta['kind'] !== '' ? meta['kind'] : null;
+            return {
+                sourceId: String(row['id']).trim(),
+                title,
+                kind,
+                createdAt: String(row['recorded_at']).trim(),
+                chunkCount: Number(row['chunk_count']),
+                trust: String(row['trust']),
+            };
+        });
+    }
+    /** Live chunks of one source visible from `reader`, in source order. A source outside the scope yields nothing. */
+    async listChunks(reader, sourceId, afterSeq, limit) {
+        const [visible, bindings] = this.visible('s', reader);
+        const rows = await this.db.all(`SELECT * FROM (
+         SELECT c.seq, c.id, c.source_id, c.text, c.byte_start, c.byte_end, c.line_start, c.line_end,
+                c.heading_path, c.recipe, s.uri, s.sha256, s.trust, s.writer, s.recorded_at,
+                ROW_NUMBER() OVER (ORDER BY c.seq) AS position
+         FROM ${this.tables.chunks} c
+         JOIN ${this.tables.sources} s ON s.id = c.source_id
+         WHERE c.source_id = ? AND c.retired_at IS NULL AND ${visible}
+       ) listed WHERE listed.seq > ? ORDER BY listed.seq LIMIT ${Math.max(1, Math.min(1001, Math.trunc(limit)))}`, [sourceId, ...bindings, afterSeq ?? 0]);
+        return rows.map((row) => ({
+            chunkId: String(row['id']).trim(),
+            sourceId: String(row['source_id']).trim(),
+            text: String(row['text']),
+            position: Number(row['position']),
+            seq: Number(row['seq']),
+            provenance: {
+                uri: String(row['uri']),
+                sha256: String(row['sha256']).trim(),
+                byteStart: Number(row['byte_start']),
+                byteEnd: Number(row['byte_end']),
+                lineStart: Number(row['line_start']),
+                lineEnd: Number(row['line_end']),
+                headingPath: JSON.parse(String(row['heading_path'])),
+                recipe: String(row['recipe']),
+                trust: String(row['trust']),
+                writer: String(row['writer']),
+                recordedAt: String(row['recorded_at']).trim(),
+            },
+        }));
+    }
+    /** Full-text search over live chunks visible from `reader`, best first. */
+    async textSearch(reader, query, limit) {
+        const terms = [...new Set(query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((t) => t !== ''))].slice(0, MAX_QUERY_TERMS);
+        if (terms.length === 0) {
+            return [];
+        }
+        const [visible, bindings] = this.visible('s', reader);
+        const fts = this.tables.fts();
+        const bounded = Number.isFinite(limit) ? Math.max(1, Math.min(1000, Math.trunc(limit))) : 1;
+        const rows = await this.db.all(`SELECT c.id AS chunk_id, -bm25(${fts}) AS score
+       FROM ${fts} JOIN ${this.tables.chunks} c ON c.seq = ${fts}.rowid
+       JOIN ${this.tables.sources} s ON s.id = c.source_id
+       WHERE ${fts} MATCH ? AND c.retired_at IS NULL AND ${visible}
+       ORDER BY score DESC, c.id LIMIT ${bounded}`, [ftsMatch(terms), ...bindings]);
+        return rows.map((r) => ({ chunkId: String(r['chunk_id']), score: Number(r['score']) }));
+    }
+    async assertFact(scope, fact, policy) {
+        return this.db.atomic(async () => this.writeFact(scope, fact, await this.prepareFact(scope, fact, policy)));
+    }
+    /**
+     * The world changed: close `oldKey`'s valid time and record the replacement.
+     * The overwrite guard decides BEFORE any write: an accepted fact is closed
+     * only for a replacement the policy also accepts, in the same statement.
+     */
+    async supersede(scope, oldKey, replacement, policy) {
+        return this.db.atomic(async () => {
+            const prepared = await this.prepareFact(scope, replacement, policy);
+            const oldId = scope.qualify('fact', oldKey);
+            const closed = await this.db.run(`UPDATE ${this.tables.facts} SET valid_to = ?, superseded_by = ?
+         WHERE id = ? AND valid_to IS NULL AND expired_at IS NULL AND valid_from <= ?
+           AND (status <> ? OR ? = ?)`, [prepared.from, replacement.id, oldId, prepared.from, FactStatus.Accepted, prepared.status, FactStatus.Accepted]);
+            if (closed !== 1) {
+                const old = (await this.db.all(`SELECT status, valid_to, expired_at FROM ${this.tables.facts} WHERE id = ?`, [oldId]))[0];
+                if (old !== undefined && old['valid_to'] === null && old['expired_at'] === null
+                    && old['status'] === FactStatus.Accepted && prepared.status !== FactStatus.Accepted) {
+                    throw new GraphError(`An accepted fact can only be superseded by one the policy also accepts; this replacement would be a ${prepared.status}.`);
+                }
+                throw new GraphError('Only a fact still in force, valid before the replacement starts, can be superseded.');
+            }
+            return this.writeFact(scope, replacement, prepared);
+        });
+    }
+    /**
+     * We were wrong: end the fact's RECORDED time. An app decision, never a
+     * tool: it does not check the acceptance policy, so retract-then-assert can
+     * replace an accepted fact with weaker evidence; use supersede() to record
+     * that the world changed.
+     */
+    async retract(scope, key) {
+        const changed = await this.db.atomic(() => this.db.run(`UPDATE ${this.tables.facts} SET expired_at = ? WHERE id = ? AND expired_at IS NULL`, [this.now(), scope.qualify('fact', key)]));
+        if (changed !== 1) {
+            throw new GraphError(`No current fact [${key}] at this scope to retract.`);
+        }
+    }
+    /** An app decision: a proposed fact still in force becomes accepted. */
+    async accept(scope, key) {
+        const changed = await this.db.atomic(() => this.db.run(`UPDATE ${this.tables.facts} SET status = ? WHERE id = ? AND status = ? AND expired_at IS NULL AND valid_to IS NULL`, [FactStatus.Accepted, scope.qualify('fact', key), FactStatus.Proposed]));
+        if (changed !== 1) {
+            throw new GraphError(`No proposed fact [${key}] at this scope to accept.`);
+        }
+    }
+    async facts(reader, subject, options = {}) {
+        const [visible, bindings] = this.visible('f', reader);
+        const where = ['f.subject = ?', visible];
+        const values = [subject, ...bindings];
+        if (options.at == null) {
+            where.push('f.valid_to IS NULL');
+        }
+        else {
+            const at = normaliseTime(options.at);
+            where.push('f.valid_from <= ? AND (f.valid_to IS NULL OR f.valid_to > ?)');
+            values.push(at, at);
+        }
+        if (options.knownAt == null) {
+            where.push('f.expired_at IS NULL');
+        }
+        else {
+            const known = normaliseTime(options.knownAt);
+            where.push('f.recorded_at <= ? AND (f.expired_at IS NULL OR f.expired_at > ?)');
+            values.push(known, known);
+        }
+        if (options.unaccepted !== true) {
+            where.push('f.status = ?');
+            values.push(FactStatus.Accepted);
+        }
+        const rows = await this.db.all(`SELECT f.* FROM ${this.tables.facts} f WHERE ${where.join(' AND ')} ORDER BY f.valid_from, f.fact_key`, values);
+        return Promise.all(rows.map((row) => this.toFact(row)));
+    }
+    /** Every version of every fact about `subject` visible from `reader`, oldest first. */
+    async timeline(reader, subject) {
+        const [visible, bindings] = this.visible('f', reader);
+        const rows = await this.db.all(`SELECT f.* FROM ${this.tables.facts} f WHERE f.subject = ? AND ${visible} ORDER BY f.valid_from, f.recorded_at, f.fact_key`, [subject, ...bindings]);
+        return Promise.all(rows.map((row) => this.toFact(row)));
+    }
+    /** Erase a source stored at exactly `scope`: its chunks, their evidence links, and every fact left with no evidence. */
+    async eraseSource(scope, key) {
+        return this.db.atomic(async () => {
+            const sourceId = scope.qualify('source', key);
+            if ((await this.db.all(`SELECT id FROM ${this.tables.sources} WHERE id = ?`, [sourceId])).length === 0) {
+                return { sourceFound: false, chunks: 0, evidenceLinks: 0, factsErased: 0, factsKept: 0, vectors: 0, chunkIds: [] };
+            }
+            const chunkIds = (await this.db.all(`SELECT id FROM ${this.tables.chunks} WHERE source_id = ?`, [sourceId])).map((r) => String(r['id']));
+            let links = 0;
+            const affected = new Set();
+            for (const batch of batches(chunkIds, 500)) {
+                for (const row of await this.db.all(`SELECT DISTINCT fact_id FROM ${this.tables.evidence} WHERE chunk_id IN (${marks(batch)})`, batch)) {
+                    affected.add(String(row['fact_id']));
+                }
+                links += await this.db.run(`DELETE FROM ${this.tables.evidence} WHERE chunk_id IN (${marks(batch)})`, batch);
+            }
+            let erased = 0;
+            let kept = 0;
+            for (const batch of batches([...affected], 500)) {
+                const orphans = (await this.db.all(`SELECT f.id FROM ${this.tables.facts} f WHERE f.id IN (${marks(batch)})
+           AND NOT EXISTS (SELECT 1 FROM ${this.tables.evidence} e WHERE e.fact_id = f.id)`, batch)).map((r) => String(r['id']));
+                if (orphans.length > 0) {
+                    erased += await this.db.run(`DELETE FROM ${this.tables.facts} WHERE id IN (${marks(orphans)})`, orphans);
+                }
+                kept += batch.length - orphans.length;
+            }
+            const chunks = await this.db.run(`DELETE FROM ${this.tables.chunks} WHERE source_id = ?`, [sourceId]);
+            await this.db.run(`DELETE FROM ${this.tables.sources} WHERE id = ?`, [sourceId]);
+            return { sourceFound: true, chunks, evidenceLinks: links, factsErased: erased, factsKept: kept, vectors: 0, chunkIds };
+        });
+    }
+    /** Validate a fact and decide its status, READING ONLY. */
+    async prepareFact(scope, fact, policy) {
+        assertKey(fact.id);
+        const from = normaliseTime(fact.validFrom);
+        const to = fact.validTo == null ? null : normaliseTime(fact.validTo);
+        if (to !== null && to < from) {
+            throw new GraphError('A fact cannot end before it starts.');
+        }
+        if (fact.supersededBy != null || fact.status != null || fact.recordedAt != null || fact.expiredAt != null) {
+            throw new GraphError('Status, recorded times and superseded_by are set by the store, never asserted.');
+        }
+        const evidence = [...new Set(fact.evidence)];
+        if (evidence.length === 0) {
+            throw new GraphError('A fact must cite at least one chunk as evidence.');
+        }
+        // Evidence must be visible from the FACT's scope: a tenant-wide fact can
+        // never cite one person's private thread.
+        const chunks = await this.getChunks(scope, evidence);
+        if (chunks.length !== evidence.length) {
+            throw new GraphError("Every evidence id must name a stored chunk visible from the fact's scope.");
+        }
+        if (chunks.some((c) => c.retiredAt != null)) {
+            throw new GraphError('A retired chunk cannot be cited as new evidence.');
+        }
+        return { from, to, evidence, status: policy.decide(chunks.map((c) => c.trust ?? Trust.System)) };
+    }
+    async writeFact(scope, fact, prepared) {
+        const now = this.now();
+        const id = scope.qualify('fact', fact.id);
+        await this.db.run(`INSERT INTO ${this.tables.facts}
+       (id, fact_key, tenant_id, owner_id, agent_id, thread_id, subject, predicate, object, status, valid_from, valid_to, superseded_by, recorded_at, expired_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, NULL)`, [id, fact.id, ...scope.toRow(), fact.subject, fact.predicate, fact.object, prepared.status, prepared.from, prepared.to, now]);
+        for (const chunk of prepared.evidence) {
+            await this.db.run(`INSERT INTO ${this.tables.evidence} (fact_id, chunk_id) VALUES (?, ?)`, [id, chunk]);
+        }
+        return { ...fact, evidence: prepared.evidence, validFrom: prepared.from, validTo: prepared.to, supersededBy: null, status: prepared.status, recordedAt: now, expiredAt: null };
+    }
+    async retireExcept(sourceId, keep) {
+        await this.db.run(`UPDATE ${this.tables.chunks} SET retired_at = ? WHERE source_id = ? AND retired_at IS NULL`, [this.now(), sourceId]);
+        for (const batch of batches([...new Set(keep)], 500)) {
+            await this.db.run(`UPDATE ${this.tables.chunks} SET retired_at = NULL WHERE source_id = ? AND id IN (${marks(batch)})`, [sourceId, ...batch]);
+        }
+        return Number((await this.db.all(`SELECT COUNT(*) AS n FROM ${this.tables.chunks} WHERE source_id = ? AND retired_at IS NOT NULL`, [sourceId]))[0]?.['n'] ?? 0);
+    }
+    /** The visibility predicate for a reader, over a table aliased `alias` carrying the scope columns. */
+    visible(alias, reader) {
+        return [
+            `${alias}.tenant_id = ?`
+                + ` AND (${alias}.owner_id IS NULL OR ${alias}.owner_id = ?)`
+                + ` AND (${alias}.agent_id IS NULL OR ${alias}.agent_id = ?)`
+                + ` AND (${alias}.thread_id IS NULL OR ${alias}.thread_id = ?)`,
+            reader.toRow(),
+        ];
+    }
+    async toFact(row) {
+        const evidence = (await this.db.all(`SELECT chunk_id FROM ${this.tables.evidence} WHERE fact_id = ? ORDER BY chunk_id`, [String(row['id'])]))
+            .map((r) => String(r['chunk_id']));
+        const opt = (v) => (v == null ? null : String(v));
+        return {
+            id: String(row['fact_key']), subject: String(row['subject']), predicate: String(row['predicate']), object: String(row['object']),
+            evidence, validFrom: String(row['valid_from']), validTo: opt(row['valid_to']), supersededBy: opt(row['superseded_by']),
+            status: String(row['status']), recordedAt: String(row['recorded_at']), expiredAt: opt(row['expired_at']),
+        };
+    }
+    now() {
+        return normaliseTime(this.clock());
+    }
+}
+/**
+ * An FTS5 MATCH expression in which every term is a quoted string (inner quotes
+ * doubled): a literal, never an operator, column filter or prefix. ORed, so
+ * BM25 ranks partial matches instead of dropping them.
+ */
+export function ftsMatch(terms) {
+    return terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(' OR ');
+}
+/**
+ * Validate a UTC ISO 8601 time and return it in ONE fixed-width form
+ * (microseconds, Z), identical to the PHP reference, so stored times compare
+ * correctly as strings whatever precision they were given in.
+ */
+export function normaliseTime(value) {
+    const match = TIME.exec(value);
+    if (match === null) {
+        throw new InvalidArgumentError('Times must be UTC ISO 8601, e.g. 2026-11-14T00:00:00Z.');
+    }
+    const base = match[1];
+    const parsed = new Date(`${base}Z`);
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 19) !== base) {
+        throw new InvalidArgumentError('Times must name a real UTC date and time.');
+    }
+    return `${base}.${(match[2] ?? '.').slice(1).padEnd(6, '0')}Z`;
+}
+function assertKey(key) {
+    if (!KEY.test(key)) {
+        throw new InvalidArgumentError('Keys are 1-191 printable ASCII characters with no spaces.');
+    }
+}
+function marks(values) {
+    return values.map(() => '?').join(',');
+}
+function batches(values, size) {
+    const out = [];
+    for (let i = 0; i < values.length; i += size) {
+        out.push(values.slice(i, i + size));
+    }
+    return out;
+}
+function toChunk(row) {
+    const trust = row['trust'] == null ? null : String(row['trust']);
+    return {
+        id: String(row['id']),
+        sourceId: String(row['source_id']),
+        text: String(row['text']),
+        byteStart: Number(row['byte_start']),
+        byteEnd: Number(row['byte_end']),
+        lineStart: Number(row['line_start']),
+        lineEnd: Number(row['line_end']),
+        headingPath: JSON.parse(String(row['heading_path'])),
+        recipe: String(row['recipe']),
+        retiredAt: row['retired_at'] == null ? null : String(row['retired_at']),
+        sourceKey: row['source_key'] == null ? null : String(row['source_key']),
+        trust: trust !== null && isTrust(trust) ? trust : null,
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,28 @@
+import type { ScopedGraph } from './graph.js';
+/**
+ * A tool any MCP server can register: plain data plus an async call. No MCP
+ * SDK dependency, so it mounts on prism-mcp-server, the official SDK's
+ * low-level Server, or an app's own server alike.
+ */
+export interface MemoryToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    /** JSON Schema for the arguments object. */
+    readonly inputSchema: Record<string, unknown>;
+    /** Runs the tool. Always resolves to a JSON string; never rejects at the model. */
+    call(args: unknown): Promise<string>;
+}
+export declare const MAX_RESULTS = 20;
+export declare const MAX_IDS = 50;
+export declare const MAX_NOTE_BYTES = 8192;
+/**
+ * Agent tools over ONE scope of memory: search, get, facts, timeline, and note.
+ * The scope and the writer are bound here, by the app, never taken from a
+ * model's arguments. A note is stored with trust "agent": searchable, but it
+ * never becomes an accepted fact by being written. No tool asserts, accepts,
+ * supersedes or erases: those are app decisions.
+ */
+export declare function memoryTools(memory: ScopedGraph, writer: string, options?: {
+    prefix?: string;
+    withNote?: boolean;
+}): MemoryToolDefinition[];