@particle-academy/prism-graph 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -54,6 +54,11 @@ await memory.ingest('entry-42', 'journal://42', text, new MarkdownChunker(), new
 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
@@ -63,6 +68,27 @@ 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
@@ -71,16 +97,27 @@ 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')) {
-  // e.g. official SDK low-level Server, prism-mcp-server, or your own dispatcher
-  register({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema },
-           async (args) => ({ content: [{ type: 'text', text: await tool.call(args) }] }));
+  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.

package/dist/graph.d.ts

@@ -1,7 +1,7 @@
 import type { Chunk, Chunker } from './chunk.js';
 import type { EraseReport, Fact, IngestReport } from './fact.js';
 import type { Scope } from './scope.js';
-import type { GraphStore } from './storage/store.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 {
@@ -21,7 +21,11 @@ export declare class Graph {
     private readonly vectors;
     private readonly embedder;
     private readonly policy;
-    constructor(store: GraphStore, vectors?: VectorStore | null, embedder?: Embedder | null, policy?: AcceptancePolicy);
+    /** 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;
 }
 /**
@@ -35,12 +39,32 @@ export declare class ScopedGraph {
     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;
-    constructor(memoryScope: Scope, store: GraphStore, vectors: VectorStore | null, embedder: Embedder | null, policy: AcceptancePolicy);
+    /** 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:

package/dist/graph.js

@@ -1,4 +1,4 @@
-import { sha256 } from './digest.js';
+import { digest, sha256 } from './digest.js';
 import { GraphError, InvalidArgumentError } from './errors.js';
 import { IndexSpec } from './index-spec.js';
 import { DefaultAcceptancePolicy } from './trust.js';
@@ -13,17 +13,24 @@ export class Graph {
     vectors;
     embedder;
     policy;
-    constructor(store, vectors = null, embedder = null, policy = new DefaultAcceptancePolicy()) {
+    listMax;
+    constructor(store, vectors = null, embedder = null, policy = new DefaultAcceptancePolicy(), 
+    /** The largest page listSources/listChunks will return (G-282). */
+    listMax = ScopedGraph.DEFAULT_LIST_MAX) {
         this.store = store;
         this.vectors = vectors;
         this.embedder = embedder;
         this.policy = policy;
+        this.listMax = listMax;
+        if (!Number.isInteger(listMax) || listMax < 1) {
+            throw new InvalidArgumentError('listMax must be a positive integer.');
+        }
         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);
+        return new ScopedGraph(scope, this.store, this.vectors, this.embedder, this.policy, this.listMax);
     }
 }
 /**
@@ -37,17 +44,100 @@ export class ScopedGraph {
     vectors;
     embedder;
     policy;
+    listMax;
     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) {
+    /** The listing contract (G-282). A consumer refuses a version it does not know. */
+    static CONTRACT_VERSION = 'g282.1';
+    static DEFAULT_LIST_LIMIT = 50;
+    static DEFAULT_LIST_MAX = 200;
+    constructor(memoryScope, store, vectors, embedder, policy, listMax = ScopedGraph.DEFAULT_LIST_MAX) {
         this.memoryScope = memoryScope;
         this.store = store;
         this.vectors = vectors;
         this.embedder = embedder;
         this.policy = policy;
+        this.listMax = listMax;
+    }
+    /** Sources this scope can see, newest first, a page at a time (G-282). */
+    async listSources(cursor = null, limit = null) {
+        const size = this.listLimit(limit);
+        let after = null;
+        if (cursor !== null) {
+            const key = this.readCursor(cursor, 'sources');
+            if (key.length !== 2 || typeof key[0] !== 'string' || typeof key[1] !== 'string') {
+                throw new InvalidArgumentError('Invalid cursor.');
+            }
+            after = [key[0], key[1]];
+        }
+        const rows = await this.store.listSources(this.memoryScope, after, size + 1);
+        const items = rows.slice(0, size);
+        const last = items.at(-1);
+        return {
+            contractVersion: ScopedGraph.CONTRACT_VERSION,
+            items,
+            nextCursor: rows.length > size && last !== undefined ? this.writeCursor('sources', [last.createdAt, last.sourceId]) : null,
+        };
+    }
+    /**
+     * 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.
+     */
+    async listChunks(sourceId, cursor = null, limit = null) {
+        const size = this.listLimit(limit);
+        let afterSeq = null;
+        if (cursor !== null) {
+            const key = this.readCursor(cursor, `chunks:${sourceId}`);
+            if (key.length !== 1 || typeof key[0] !== 'number' || !Number.isInteger(key[0]) || key[0] < 0) {
+                throw new InvalidArgumentError('Invalid cursor.');
+            }
+            afterSeq = key[0];
+        }
+        const rows = await this.store.listChunks(this.memoryScope, sourceId, afterSeq, size + 1);
+        const page = rows.slice(0, size);
+        const last = page.at(-1);
+        return {
+            contractVersion: ScopedGraph.CONTRACT_VERSION,
+            // seq is the store's paging key; the contract's order is `position`.
+            items: page.map(({ seq: _seq, ...chunk }) => chunk),
+            nextCursor: rows.length > size && last !== undefined ? this.writeCursor(`chunks:${sourceId}`, [last.seq]) : null,
+        };
+    }
+    listLimit(limit) {
+        const size = limit ?? Math.min(ScopedGraph.DEFAULT_LIST_LIMIT, this.listMax);
+        if (!Number.isInteger(size) || size < 1 || size > this.listMax) {
+            throw new InvalidArgumentError(`limit must be between 1 and ${this.listMax}.`);
+        }
+        return size;
+    }
+    /**
+     * 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.
+     */
+    writeCursor(listing, key) {
+        return Buffer.from(JSON.stringify({ k: key, b: this.cursorBinding(listing) }), 'utf8').toString('base64url');
+    }
+    readCursor(cursor, listing) {
+        let data = null;
+        if (cursor.length <= 1024 && /^[A-Za-z0-9_-]*$/.test(cursor)) {
+            try {
+                data = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+            }
+            catch {
+                data = null;
+            }
+        }
+        if (typeof data !== 'object' || data === null || !Array.isArray(data.k)
+            || data.b !== this.cursorBinding(listing)) {
+            throw new InvalidArgumentError('Invalid cursor.');
+        }
+        return data.k;
+    }
+    cursorBinding(listing) {
+        return digest('prism-graph/cursor@1', [...this.memoryScope.toRow().map((v) => v ?? ''), listing]).slice(0, 16);
     }
     scope() {
         return this.memoryScope;

package/dist/index.d.ts

@@ -10,6 +10,7 @@ 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 type { ListedChunk, ListedSource, ListingPage } 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';

package/dist/storage/store.d.ts

@@ -17,6 +17,41 @@ export interface StoredSource {
  * 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;
@@ -32,6 +67,15 @@ export declare class GraphStore {
     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;

package/dist/storage/store.js

@@ -5,13 +5,6 @@ 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}$/;
-/**
- * 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.
- */
 export class GraphStore {
     db;
     tables;
@@ -79,6 +72,73 @@ export class GraphStore {
         }
         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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-graph",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Long-term memory for AI agents, for TypeScript: scoped, trust-labelled, cited facts, hybrid search and erasure. The port of particle-academy/prism-graph.",
   "type": "module",
   "sideEffects": false,