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

package/LICENSE

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

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# @particle-academy/prism-graph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Long-term memory for AI agents, for TypeScript. This is the port of
+[`particle-academy/prism-graph`](https://github.com/Particle-Academy/prism-graph)
+(PHP, the reference). It is byte-compatible with the reference: chunk ids,
+scope ids, embedder fingerprints and the fenced wake block match exactly,
+checked against a golden fixture generated by the PHP package.
+
+Node 22.16+, ESM, **zero runtime dependencies**. Storage is SQLite through
+Node's built-in `node:sqlite`.
+
+## What it guarantees
+
+- **Scope is enforced in SQL, on every query.** Scopes are tenant, owner,
+  agent and thread. A reader sees its own level and the levels above it, never
+  sideways, and there is no unscoped read.
+- **Every source records its trust class and writer.** Trust is `user`,
+  `document`, `agent`, `tool`, `subagent`, `consolidator` or `system`. The
+  caller binds both, never a model. A source's trust cannot change later.
+- **Facts cite evidence, and a policy decides their status:**
+  - **accepted** when every cited chunk is user or document text;
+  - a **belief** when the evidence is only agent notes;
+  - a **proposal** otherwise.
+
+  An accepted fact can only be superseded by another accepted one, so tool
+  output cannot overwrite what the user said.
+- **Facts are bi-temporal.** There is valid time (supersede) and recorded time
+  (retract, `knownAt`).
+- **Hybrid search.** FTS5 full-text search folds case and accents. Optional
+  vectors are fused by reciprocal rank and partitioned per tenant.
+- **Erasure cascades** to chunks, vectors, full-text entries, evidence and
+  orphaned facts, and returns counts.
+- **Every write is all-or-nothing, including inside your own transaction**
+  (it runs in a savepoint). Concurrent writes on one connection are
+  serialised.
+- **Recalled text is fenced as data.** Hidden characters are shown as
+  `<U+XXXX>`, and item text is quoted line by line, so stored text cannot
+  forge a header or close the fence.
+
+## Use
+
+```ts
+import { DatabaseSync } from 'node:sqlite';
+import { baseSchema, Graph, GraphStore, MarkdownChunker, NodeSqliteDriver, Origin, Scope, Trust } from '@particle-academy/prism-graph';
+
+const db = new DatabaseSync('memory.db');
+// Once, from your own migration tooling (the package never creates tables at runtime):
+for (const sql of baseSchema()) db.exec(sql);
+
+const graph = new Graph(new GraphStore(new NodeSqliteDriver(db)));
+const memory = graph.scope(Scope.tenant('acme').withOwner('user-7').withAgent('journal'));
+
+await memory.ingest('entry-42', 'journal://42', text, new MarkdownChunker(), new Origin(Trust.User, 'user-7'));
+const hits = await memory.search('refund policy');      // verbatim chunks, with trust and source
+```
+
+`baseSchema()` is the complete schema for the default setup, and already
+includes the full-text table and its triggers. Do not run `fullTextSchema()`
+as well. Run `vectorSchema()` only if you store vectors. If a migration rebuilds
+the chunks table (which drops its triggers), run `repairFullTextSchema()`.
+
+### Give memory a connection of its own
+
+SQLite transactions belong to the connection. Suppose another part of your
+app writes on the same `DatabaseSync` while one of prism-graph's writes is in
+progress. That write lands inside prism-graph's savepoint, and is rolled back
+with it if prism-graph's write fails. So use a dedicated connection to the same
+file (WAL mode is the usual setup), or send every write on the shared
+connection through `driver.atomic()`.
+
+## Listing sources and chunks
+
+For a memory explorer, list what a scope can see, a page at a time:
+
+```ts
+const page = await memory.listSources();                // newest first, 50 per page
+const next = await memory.listSources(page.nextCursor);
+const chunks = await memory.listChunks(sourceId, null, 100);
+```
+
+Each call returns `{ contractVersion: 'g282.1', items, nextCursor }`, the same shape as the PHP package.
+- A source item has `sourceId`, `title` (`metadata.title`, else the uri), `kind` (`metadata.kind`, else null),
+  `createdAt`, `chunkCount` and `trust`.
+- A chunk item has `chunkId`, `sourceId`, `text`, `position` (its place in the source) and `provenance` (uri,
+  sha256, byte and line range, heading path, recipe, trust, writer, recordedAt).
+- **Scoped like every read.** A source outside the scope lists as empty.
+- **Cursors are opaque** and only work in the scope and listing that issued them.
+- **Page size** defaults to 50 and is capped at 200. Pass a different cap as `new Graph(store, vectors, embedder,
+  policy, listMax)`.
+- Retired sources and chunks are not listed.
+
+## MCP tools on your own server
+
+`memoryTools()` returns framework-neutral tool definitions: a name, a
+description, a JSON Schema for the input, and an async `call()` that always
+resolves to a JSON string and never rejects at the model. They can be
+registered on any MCP server, with no MCP SDK dependency. The scope and the
+writer are bound by your code, never by the model.
+
+With [`@particle-academy/prism-mcp-server`](https://github.com/Particle-Academy/prism-mcp-server-ts)
+(this is the setup the test suite runs over a real MCP exchange):
+
+```ts
+import { LoopbackHttpTransport, Server, ToolDefinition, type JsonObject } from '@particle-academy/prism-mcp-server';
+import { memoryTools } from '@particle-academy/prism-graph';
+
+const server = new Server({ server: 'journal', transport: new LoopbackHttpTransport() });
+for (const tool of memoryTools(memory, 'agent:journal')) {
+  server.register(
+    new ToolDefinition(tool.name, tool.description, tool.inputSchema as JsonObject),
+    async (args) => ({ text: await tool.call(args), isError: false }),
+  );
+}
+await server.listen();
+```
+
+`inputSchema` is plain JSON Schema, so any MCP server that takes a tool's
+JSON Schema as-is can register these tools without converting anything. No
+schema library is needed: `call()` validates its own input either way.
+
+The tools are `memory_search`, `memory_get`, `memory_facts`, `memory_timeline`
+and `memory_note`:
+- No tool asserts, accepts, supersedes or erases. Those are app decisions.
+- A note is stored as the agent's own words, so it can only ever be a belief.
+- Tool names may not contain the verbs reserved for the human: confirm,
+  approve, accept, reject, deny.
+
+## Not yet in this port
+
+- **PostgreSQL:** the driver interface is ready, but the adapter is not
+  shipped until it is tested here.
+- **Harness adapters:** this port does not include the PHP reference's
+  harness adapters (WakeContext and TurnRecorder).
+- **Entity graph:** typed entities, edges with notes and traversal are
+  planned for both languages together.
+
+## Gates
+
+```sh
+npm run typecheck && npm run build && npx vitest run
+```

package/dist/chunk.d.ts

@@ -0,0 +1,29 @@
+import type { Trust } from './trust.js';
+/**
+ * One verbatim slice of a source: the text is exactly the source's UTF-8
+ * bytes in [byteStart, byteEnd). Nothing derived ever replaces it.
+ */
+export interface Chunk {
+    readonly id: string;
+    /** The scope-qualified internal source id. */
+    readonly sourceId: string;
+    readonly text: string;
+    readonly byteStart: number;
+    readonly byteEnd: number;
+    readonly lineStart: number;
+    readonly lineEnd: number;
+    readonly headingPath: readonly string[];
+    readonly recipe: string;
+    /** Set when the source no longer contains this text: it leaves search but stays readable by id. */
+    readonly retiredAt?: string | null;
+    /** Filled on read: the app's own key for the source. */
+    readonly sourceKey?: string | null;
+    /** Filled on read: the trust class the source was written with. */
+    readonly trust?: Trust | null;
+}
+/** Content-addressed chunk id, identical to the PHP reference's Chunk::idFor(). */
+export declare function chunkId(recipe: string, sourceId: string, byteStart: number, byteEnd: number, text: string | Uint8Array): string;
+export interface Chunker {
+    recipe(): string;
+    chunk(sourceId: string, text: string): Chunk[];
+}

package/dist/chunk.js

@@ -0,0 +1,5 @@
+import { digest } from './digest.js';
+/** Content-addressed chunk id, identical to the PHP reference's Chunk::idFor(). */
+export function chunkId(recipe, sourceId, byteStart, byteEnd, text) {
+    return digest('prism-graph/chunk@1', [recipe, sourceId, byteStart, byteEnd, text]);
+}

package/dist/chunking/markdown.d.ts

@@ -0,0 +1,10 @@
+import { WindowChunker, type Section } from './window.js';
+/**
+ * Markdown-aware: windows never cross an ATX heading (# .. ######), and each
+ * chunk carries the heading path above it. Headings inside fenced code blocks
+ * are ignored. The heading line belongs to the section it opens.
+ */
+export declare class MarkdownChunker extends WindowChunker {
+    protected name(): string;
+    protected sections(bytes: Buffer): Section[];
+}

package/dist/chunking/markdown.js

@@ -0,0 +1,64 @@
+import { WindowChunker } from './window.js';
+// PORT NOTE: the PHP reference matches these WITHOUT the /u flag, so its \s is
+// ASCII whitespace only and "." matches any byte but \n. The lines are decoded
+// as latin1 here (one char per byte) so the same patterns match the same bytes;
+// JavaScript's own \s and "." are Unicode-wide and would not.
+const FENCE = /^[ \t\n\x0B\f\r]{0,3}(```|~~~)/;
+const HEADING = /^[ \t\n\x0B\f\r]{0,3}(#{1,6})[ \t]+([^\n]+?)[ \t#]*$/;
+/**
+ * Markdown-aware: windows never cross an ATX heading (# .. ######), and each
+ * chunk carries the heading path above it. Headings inside fenced code blocks
+ * are ignored. The heading line belongs to the section it opens.
+ */
+export class MarkdownChunker extends WindowChunker {
+    name() {
+        return 'markdown';
+    }
+    sections(bytes) {
+        const sections = [];
+        let stack = new Map();
+        let sectionStart = 0;
+        let sectionPath = [];
+        let offset = 0;
+        let inFence = false;
+        const length = bytes.length;
+        while (offset < length) {
+            const nl = bytes.indexOf(0x0a, offset);
+            const lineEnd = nl === -1 ? length : nl + 1;
+            const line = phpRtrim(bytes.subarray(offset, lineEnd).toString('latin1'), '\r\n');
+            const heading = FENCE.test(line) ? null : HEADING.exec(line);
+            if (FENCE.test(line)) {
+                inFence = !inFence;
+            }
+            else if (!inFence && heading !== null) {
+                if (offset > sectionStart) {
+                    sections.push([sectionStart, offset, sectionPath]);
+                }
+                // level => title; a heading closes every deeper level, even across skipped levels.
+                const level = heading[1].length;
+                stack = new Map([...stack].filter(([l]) => l < level));
+                stack.set(level, Buffer.from(phpTrim(heading[2]), 'latin1').toString('utf8'));
+                stack = new Map([...stack].sort(([a], [b]) => a - b));
+                sectionStart = offset;
+                sectionPath = [...stack.values()];
+            }
+            offset = lineEnd;
+        }
+        if (length > sectionStart) {
+            sections.push([sectionStart, length, sectionPath]);
+        }
+        return sections;
+    }
+}
+/** PHP's trim() default: " \t\n\r\0\x0B" only. */
+function phpTrim(value) {
+    return value.replace(/^[ \t\n\r\0\x0B]+|[ \t\n\r\0\x0B]+$/g, '');
+}
+/** PHP's rtrim($value, $chars) for a set of single characters. */
+function phpRtrim(value, chars) {
+    let end = value.length;
+    while (end > 0 && chars.includes(value[end - 1])) {
+        end--;
+    }
+    return value.slice(0, end);
+}

package/dist/chunking/window.d.ts

@@ -0,0 +1,23 @@
+import { type Chunk, type Chunker } from '../chunk.js';
+/** A section windows may not cross: [byteStart, byteEnd, headingPath]. */
+export type Section = [number, number, string[]];
+/**
+ * Byte windows with overlap, preferring paragraph, then sentence, then line
+ * breaks, and never splitting a UTF-8 character.
+ *
+ * PORT NOTE: this works on the UTF-8 BYTES, exactly as the PHP reference works
+ * on PHP strings, so spans, ids and boundaries are identical across languages
+ * (checked against a golden fixture generated by the reference).
+ */
+export declare class WindowChunker implements Chunker {
+    protected readonly target: number;
+    protected readonly max: number;
+    protected readonly overlap: number;
+    constructor(target?: number, max?: number, overlap?: number);
+    recipe(): string;
+    protected name(): string;
+    chunk(sourceId: string, text: string): Chunk[];
+    protected sections(bytes: Buffer): Section[];
+    private windows;
+    private breakAt;
+}

package/dist/chunking/window.js

@@ -0,0 +1,128 @@
+import { chunkId } from '../chunk.js';
+import { InvalidArgumentError } from '../errors.js';
+const MARKS = ['\n\n', '. ', '! ', '? ', '\n', ' '].map((m) => Buffer.from(m, 'latin1'));
+/**
+ * Byte windows with overlap, preferring paragraph, then sentence, then line
+ * breaks, and never splitting a UTF-8 character.
+ *
+ * PORT NOTE: this works on the UTF-8 BYTES, exactly as the PHP reference works
+ * on PHP strings, so spans, ids and boundaries are identical across languages
+ * (checked against a golden fixture generated by the reference).
+ */
+export class WindowChunker {
+    target;
+    max;
+    overlap;
+    constructor(target = 1200, max = 1500, overlap = 150) {
+        this.target = target;
+        this.max = max;
+        this.overlap = overlap;
+        // max >= 4: one UTF-8 character can be 4 bytes.
+        if (!Number.isInteger(target) || !Number.isInteger(max) || !Number.isInteger(overlap)
+            || target < 1 || max < target || max < 4 || overlap < 0 || overlap >= target) {
+            throw new InvalidArgumentError('Chunk sizes need 0 <= overlap < target <= max, and max >= 4.');
+        }
+    }
+    recipe() {
+        return `${this.name()}@1;target=${this.target};max=${this.max};overlap=${this.overlap}`;
+    }
+    name() {
+        return 'window';
+    }
+    chunk(sourceId, text) {
+        const bytes = Buffer.from(text, 'utf8');
+        if (bytes.length === 0) {
+            return [];
+        }
+        const lines = lineStarts(bytes);
+        const recipe = this.recipe();
+        const chunks = [];
+        for (const [start, end, path] of this.sections(bytes)) {
+            for (const [s, e] of this.windows(bytes, start, end)) {
+                const slice = bytes.subarray(s, e);
+                chunks.push({
+                    id: chunkId(recipe, sourceId, s, e, slice),
+                    sourceId,
+                    text: slice.toString('utf8'),
+                    byteStart: s,
+                    byteEnd: e,
+                    lineStart: lineAt(lines, s),
+                    lineEnd: lineAt(lines, e - 1),
+                    headingPath: path,
+                    recipe,
+                });
+            }
+        }
+        return chunks;
+    }
+    sections(bytes) {
+        return [[0, bytes.length, []]];
+    }
+    windows(bytes, start, end) {
+        const windows = [];
+        let pos = start;
+        while (pos < end) {
+            const stop = end - pos <= this.max ? end : this.breakAt(bytes, pos, end);
+            windows.push([pos, stop]);
+            if (stop >= end) {
+                break;
+            }
+            let next = charBoundary(bytes, Math.max(pos + 1, stop - this.overlap));
+            // Start the overlap on a word boundary, never inside a word.
+            const space = bytes.indexOf(0x20, next);
+            if (this.overlap > 0 && space !== -1 && space < stop) {
+                next = space + 1;
+            }
+            pos = next > pos ? next : stop;
+        }
+        return windows;
+    }
+    breakAt(bytes, pos, end) {
+        const limit = Math.min(pos + this.max, end);
+        const floor = pos + Math.floor(this.target / 2);
+        const window = bytes.subarray(pos, limit);
+        for (const mark of MARKS) {
+            const at = window.lastIndexOf(mark);
+            if (at !== -1 && pos + at + mark.length > floor) {
+                return pos + at + mark.length;
+            }
+        }
+        // Hard cut, on a character boundary.
+        return Math.max(pos + 1, charBoundary(bytes, limit));
+    }
+}
+/** Move back to the start of a UTF-8 character. */
+function charBoundary(bytes, at) {
+    while (at > 0 && at < bytes.length && (bytes[at] & 0xc0) === 0x80) {
+        at--;
+    }
+    return at;
+}
+function lineStarts(bytes) {
+    const starts = [0];
+    let offset = 0;
+    for (;;) {
+        const nl = bytes.indexOf(0x0a, offset);
+        if (nl === -1) {
+            break;
+        }
+        starts.push(nl + 1);
+        offset = nl + 1;
+    }
+    return starts;
+}
+/** 1-based line of a byte offset. */
+function lineAt(starts, byte) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi + 1) / 2);
+        if (starts[mid] <= byte) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return lo + 1;
+}

package/dist/digest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * sha256 of a length-prefixed tuple, byte-identical to the PHP reference's
+ * Support\Digest::of(). Lengths are UTF-8 BYTE lengths, as PHP's strlen().
+ * A separator byte would let two different tuples hash the same; a length
+ * prefix cannot be forged that way.
+ */
+export declare function digest(domain: string, fields: ReadonlyArray<string | number | Uint8Array>): string;
+export declare function sha256(data: string | Uint8Array): string;

package/dist/digest.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+/**
+ * sha256 of a length-prefixed tuple, byte-identical to the PHP reference's
+ * Support\Digest::of(). Lengths are UTF-8 BYTE lengths, as PHP's strlen().
+ * A separator byte would let two different tuples hash the same; a length
+ * prefix cannot be forged that way.
+ */
+export function digest(domain, fields) {
+    const hash = createHash('sha256');
+    const part = (field) => {
+        const bytes = typeof field === 'string' ? Buffer.from(field, 'utf8')
+            : typeof field === 'number' ? Buffer.from(String(field), 'utf8')
+                : Buffer.from(field);
+        hash.update(`${bytes.length}:`);
+        hash.update(bytes);
+    };
+    part(domain);
+    for (const field of fields) {
+        part(field);
+    }
+    return hash.digest('hex');
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/** A refusal by the graph itself: forged ids, policy violations, pinned embedders, storage refusals. */
+export declare class GraphError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A malformed argument: a programming error in the caller, kept apart from GraphError on purpose. */
+export declare class InvalidArgumentError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+/** A refusal by the graph itself: forged ids, policy violations, pinned embedders, storage refusals. */
+export class GraphError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'GraphError';
+    }
+}
+/** A malformed argument: a programming error in the caller, kept apart from GraphError on purpose. */
+export class InvalidArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArgumentError';
+    }
+}

package/dist/fact.d.ts

@@ -0,0 +1,44 @@
+import type { FactStatus } from './trust.js';
+/**
+ * A subject-predicate-object statement, bi-temporal:
+ *  - VALID time [validFrom, validTo): when it held in the world;
+ *  - RECORDED time [recordedAt, expiredAt): when the memory held it.
+ *
+ * The app supplies id, subject, predicate, object, evidence and valid times.
+ * The store fills status, recordedAt, expiredAt and supersededBy; a writer
+ * that sets any of them is refused.
+ */
+export interface Fact {
+    readonly id: string;
+    readonly subject: string;
+    readonly predicate: string;
+    readonly object: string;
+    /** Chunk ids this fact rests on. */
+    readonly evidence: readonly string[];
+    readonly validFrom: string;
+    readonly validTo?: string | null;
+    readonly supersededBy?: string | null;
+    readonly status?: FactStatus | null;
+    readonly recordedAt?: string | null;
+    readonly expiredAt?: string | null;
+}
+/** What an erasure removed, as counts that can be shown as evidence. */
+export interface EraseReport {
+    readonly sourceFound: boolean;
+    readonly chunks: number;
+    readonly evidenceLinks: number;
+    readonly factsErased: number;
+    readonly factsKept: number;
+    readonly vectors: number;
+    /** The erased chunk ids (vectors are removed by these). */
+    readonly chunkIds: readonly string[];
+}
+export interface IngestReport {
+    readonly source: string;
+    readonly sha256: string;
+    readonly recipe: string;
+    readonly chunks: number;
+    readonly stored: number;
+    /** Chunks of this source retired after the ingest: text it no longer contains. */
+    readonly retired: number;
+}

package/dist/fact.js

@@ -0,0 +1 @@
+export {};

package/dist/graph.d.ts

@@ -0,0 +1,106 @@
+import type { Chunk, Chunker } from './chunk.js';
+import type { EraseReport, Fact, IngestReport } from './fact.js';
+import type { Scope } from './scope.js';
+import type { GraphStore, ListedChunk, ListedSource, ListingPage } from './storage/store.js';
+import { type AcceptancePolicy, type Origin } from './trust.js';
+import type { Embedder, VectorStore } from './vectors.js';
+export interface Hit {
+    readonly chunk: Chunk;
+    readonly score: number;
+    /** "text", the vector store's method, or "hybrid" when both found it. */
+    readonly method: string;
+}
+/**
+ * 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 declare class Graph {
+    private readonly store;
+    private readonly vectors;
+    private readonly embedder;
+    private readonly policy;
+    /** The largest page listSources/listChunks will return (G-282). */
+    private readonly listMax;
+    constructor(store: GraphStore, vectors?: VectorStore | null, embedder?: Embedder | null, policy?: AcceptancePolicy, 
+    /** The largest page listSources/listChunks will return (G-282). */
+    listMax?: number);
+    scope(scope: Scope): ScopedGraph;
+}
+/**
+ * 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 declare class ScopedGraph {
+    private readonly memoryScope;
+    private readonly store;
+    private readonly vectors;
+    private readonly embedder;
+    private readonly policy;
+    private readonly listMax;
+    static readonly MAX_LIMIT = 200;
+    /** A query goes to the embedding provider and the full-text index, so it is bounded. */
+    static readonly MAX_QUERY_BYTES = 4096;
+    static readonly MAX_GET_IDS = 1000;
+    private static readonly RRF_K;
+    /** The listing contract (G-282). A consumer refuses a version it does not know. */
+    static readonly CONTRACT_VERSION: "g282.1";
+    static readonly DEFAULT_LIST_LIMIT = 50;
+    static readonly DEFAULT_LIST_MAX = 200;
+    constructor(memoryScope: Scope, store: GraphStore, vectors: VectorStore | null, embedder: Embedder | null, policy: AcceptancePolicy, listMax?: number);
+    /** Sources this scope can see, newest first, a page at a time (G-282). */
+    listSources(cursor?: string | null, limit?: number | null): Promise<ListingPage<ListedSource>>;
+    /**
+     * Live chunks of one source, in source order, a page at a time (G-282). A source outside this scope yields an
+     * empty page, never an error that would confirm it exists.
+     */
+    listChunks(sourceId: string, cursor?: string | null, limit?: number | null): Promise<ListingPage<ListedChunk>>;
+    private listLimit;
+    /**
+     * Opaque, and bound to this scope and listing: a cursor from another scope or listing is refused. It needs no
+     * secret, because every listing query applies the scope predicate regardless of the cursor.
+     */
+    private writeCursor;
+    private readCursor;
+    private cursorBinding;
+    scope(): Scope;
+    /**
+     * 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.
+     */
+    ingest(key: string, uri: string, text: string, chunker: Chunker, origin: Origin, options?: {
+        metadata?: Record<string, unknown>;
+        sha256?: string;
+        occurredAt?: string;
+    }): Promise<IngestReport>;
+    /** Take a source at this scope out of search; it stays readable by id. */
+    retireSource(key: string): Promise<number>;
+    /** Erase a source stored at this scope: chunks, vectors, evidence links and orphaned facts. */
+    erase(key: string): Promise<EraseReport>;
+    get(chunkIds: readonly string[]): Promise<Chunk[]>;
+    /**
+     * 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.
+     */
+    search(query: string, limit?: number, vectors?: boolean): Promise<Hit[]>;
+    facts(subject: string, options?: {
+        at?: string | null;
+        knownAt?: string | null;
+        unaccepted?: boolean;
+    }): Promise<Fact[]>;
+    timeline(subject: string): Promise<Fact[]>;
+    /** Store a fact at this scope; its status comes from the acceptance policy. */
+    assert(fact: Fact): Promise<Fact>;
+    supersede(oldKey: string, replacement: Fact): Promise<Fact>;
+    /** An app decision, never a tool. */
+    retract(key: string): Promise<void>;
+    /** An app decision, never a tool: a proposed fact becomes accepted. */
+    accept(key: string): Promise<void>;
+    /** The vector index for this tenant: another tenant's vectors can neither crowd nor appear in its results. */
+    private spec;
+}