@gmickel/gno 1.20.0 → 1.22.0

package/README.md

@@ -94,7 +94,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.19.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.22.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -109,6 +109,13 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
   watcher, jobs, stores, and models. The packed npm smoke proves two-client
   parity, warm reuse, redacted lifecycle status, fail-closed security, restart,
   and shutdown.
+- **Knowledge Delta**: `gno changes`, `gno diff`, and `gno impact` expose
+  bounded metadata-only history, structural change summaries, and explainable
+  dependency paths across CLI, REST, MCP, and SDK.
+- **Saved Capsule freshness**: CLI-only `gno context watch`, `watches`,
+  `reverify`, and `unwatch` register caller-owned Capsule files. The resident
+  runtime coalesces evidence changes into canonical, non-generative freshness
+  receipts and closed local metadata notifications.
 - **Second-brain capture**: `gno capture`, REST `/api/capture`, SDK
   `client.capture()`, MCP `gno_capture`, and Web UI Quick Capture write
   provenance-rich notes from text, stdin, or files, including typed presets for
@@ -553,9 +560,9 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 22 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 25 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 15 opt-in mutation tools, for 37 total.
+adds 15 opt-in mutation tools, for 40 total.
 
 | Tool                 | Description                           |
 | :------------------- | :------------------------------------ |
@@ -574,6 +581,9 @@ adds 15 opt-in mutation tools, for 37 total.
 | `gno_status`         | Index health check                    |
 | `gno_trace_list`     | List private local retrieval receipts |
 | `gno_trace_show`     | Inspect one bounded trace receipt     |
+| `gno_changes`        | Read retained metadata-only changes   |
+| `gno_diff`           | Read one structural document delta    |
+| `gno_impact`         | Trace bounded dependency impact       |
 
 **Design**: Default MCP mode is read-only: retrieval, opt-in verified synthesis,
 graph, status, and job inspection. Raw retrieval tools leave synthesis to your
@@ -700,7 +710,7 @@ GNO is local-first, but sometimes you want a URL to send someone. [**gno.sh**](h
 
 ![gno.sh publish reader](./assets/screenshots/publish-reader.jpg)
 
-The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Your private notes and metadata stay on your machine. Only what you export leaves.
+The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Private and `publish: false` notes stay on your machine. Exported artifacts omit local collection paths and source URIs.
 
 ```bash
 # Export a single note
@@ -735,6 +745,15 @@ Upload the artifact at [gno.sh/studio](https://gno.sh/studio) and pick a visibil
 
 **Reader experience**: editorial serif typography, drop caps, hanging punctuation, table of contents, keyboard shortcuts (`j/k`, `/`), scoped Pagefind-style search, and backlinks restricted to the published subset. Nothing leaks that you didn't publish.
 
+Public exports also carry a deterministic agent manifest. It lists only the
+sanitized published Markdown projection, with relative Markdown locators,
+content hashes, exact line spans, and Capsule-compatible evidence identities.
+The projection revision is stable while those published bytes and reader
+metadata are unchanged. Secret-link and invite-only exports do not receive
+agent capabilities or manifests. Encrypted exports remain ciphertext-only.
+Reader metadata drops embedded local path or GNO/file URI tokens; canonical
+and image fields accept only uncredentialed public HTTP(S) targets.
+
 Republishing a public, secret-link, or invite-only artifact updates the same URL. Encrypted shares should be replaced from a fresh local export so the server never needs your plaintext.
 
 Encrypted source-backed publish on `gno.sh` is intentionally disabled. For encrypted shares, use:
@@ -775,6 +794,9 @@ curl http://localhost:3000/api/health
 | `/api/ask`                    | POST   | AI-powered Q&A               |
 | `/api/context`                | POST   | Build evidence Capsule       |
 | `/api/context/verify`         | POST   | Verify saved Capsule         |
+| `/api/changes`                | GET    | List retained changes        |
+| `/api/diff`                   | GET    | Read structural delta        |
+| `/api/impact`                 | GET    | Trace dependency impact      |
 | `/api/docs`                   | GET    | List documents               |
 | `/api/docs`                   | POST   | Create document              |
 | `/api/docs/:id`               | PUT    | Update document content      |
@@ -850,7 +872,9 @@ graph TD
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                          |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation    |
 | **Privacy First**    | Local by default; no telemetry; network use is explicit or model provisioning  |
-| **MCP Server**       | 10 automatic client targets; 22 read-only tools, 37 with writes enabled        |
+| **MCP Server**       | 10 automatic client targets; 25 read-only tools, 40 with writes enabled        |
+| **Knowledge Delta**  | Bounded metadata history, structural diffs, and dependency impact paths        |
+| **Context Capsules** | Deterministic evidence bundles plus saved-file freshness reverification        |
 | **Collections**      | Organize sources with patterns, excludes, contexts                             |
 | **Tag Filtering**    | Frontmatter tags with hierarchical paths, filter via `--tags-any`/`--tags-all` |
 | **Note Linking**     | Wiki links, backlinks, related notes, cross-collection navigation              |

package/assets/skill/SKILL.md

@@ -63,21 +63,22 @@ Recipe rules:
 
 ## Command Overview
 
-| Category     | Commands                                                         | Description                                            |
-| ------------ | ---------------------------------------------------------------- | ------------------------------------------------------ |
-| **Search**   | `search`, `vsearch`, `query`, `ask`                              | Find documents by keywords, meaning, or get AI answers |
-| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`          | Navigate document relationships and typed connections  |
-| **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                    |
-| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                     |
-| **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                          |
-| **Context**  | `context add/list/rm/check/build/verify`                         | Configure guidance or compile/verify evidence Capsules |
-| **Traces**   | `trace list/show/label/export/replay/delete/purge`               | Manage and replay private retrieval receipts           |
-| **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                 |
-| **Serve**    | `serve`, `daemon`                                                | One resident Web/headless gateway and watcher          |
-| **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                        |
-| **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                               |
-| **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                            |
-| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`      | Maintenance and diagnostics                            |
+| Category     | Commands                                                                | Description                                                              |
+| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Search**   | `search`, `vsearch`, `query`, `ask`                                     | Find documents by keywords, meaning, or get AI answers                   |
+| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`                 | Navigate document relationships and typed connections                    |
+| **Retrieve** | `get`, `multi-get`, `ls`                                                | Fetch document content by URI or ID                                      |
+| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed`        | Set up and maintain document index                                       |
+| **Tags**     | `tags`, `tags add`, `tags rm`                                           | Organize and filter documents                                            |
+| **Context**  | `context add/list/rm/check/build/verify/watch/watches/reverify/unwatch` | Configure guidance or compile, verify, and watch saved evidence Capsules |
+| **Changes**  | `changes`, `diff`, `impact`                                             | Inspect bounded metadata history and dependency impact                   |
+| **Traces**   | `trace list/show/label/export/replay/delete/purge`                      | Manage and replay private retrieval receipts                             |
+| **Models**   | `models list/use/pull/clear/path`                                       | Manage local AI models                                                   |
+| **Serve**    | `serve`, `daemon`                                                       | One resident Web/headless gateway and watcher                            |
+| **Publish**  | `publish export`                                                        | Export gno.sh publish artifacts                                          |
+| **MCP**      | `mcp`, `mcp install/uninstall/status`                                   | AI assistant integration                                                 |
+| **Skill**    | `skill install/uninstall/show/paths`                                    | Install skill for AI agents                                              |
+| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`             | Maintenance and diagnostics                                              |
 
 ## Search Modes
 
@@ -229,6 +230,36 @@ When using GNO through MCP, prefer this retrieval order:
 6. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
 7. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
 
+For a caller-owned canonical Capsule that should stay fresh locally:
+
+```bash
+gno context watch capsule.json --question "Who owns launch?" --notify --json
+gno context watches --json
+gno context reverify <registration-id> --json
+gno context unwatch <registration-id> --json
+```
+
+These lifecycle operations are CLI-only and scoped to the Capsule's index.
+They persist bounded metadata and evidence hashes, not Capsule or passage
+bytes. Automatic resident work starts only after settled index changes,
+produces the same canonical non-generative verification receipt, and never
+rewrites the saved file or invokes answer generation. A failed operation has
+no receipt. Local notifications contain no question, label, path, URI, hashes,
+receipt, credentials, or source content.
+
+Use Knowledge Delta when the task asks what changed or what depends on a
+changed source:
+
+```bash
+gno changes --since 2026-07-20T00:00:00Z --json
+gno diff gno://notes/plan.md --json
+gno impact gno://notes/plan.md --max-depth 3 --json
+```
+
+Treat cursors and change IDs as opaque. Journal results are bounded,
+metadata-only, and retention-aware; do not infer source-body history when a
+diff reports partial, expired, or unavailable history.
+
 Use narrower tools when the request tells you to:
 
 - `gno_search`: exact phrase, filename, identifier, stack trace, error text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -83,6 +83,7 @@
     "eval:retrieval-candidates": "bun scripts/retrieval-candidate-benchmark.ts",
     "eval:retrieval-candidates:write": "bun scripts/retrieval-candidate-benchmark.ts --write",
     "eval:agentic": "bun evals/agentic/cli.ts",
+    "eval:agentic:demo": "bun evals/agentic/demos/generate-context-capsule.ts",
     "eval:watch": "bun --bun evalite watch",
     "research:finetune:bootstrap": "bun research/finetune/scripts/bootstrap-promotion-fixtures.ts",
     "research:finetune:autonomous:noop": "bun research/finetune/autonomous/scripts/noop-run.ts",

package/spec/cli.md

@@ -86,11 +86,16 @@ equivalent files fail closed as ambiguous.
 | context check      | yes    | no      | no    | yes  | no    | terminal |
 | context build      | yes    | no      | no    | yes  | no    | Markdown |
 | context verify     | yes    | no      | no    | yes  | no    | Markdown |
+| context watch      | yes    | no      | no    | no   | no    | terminal |
+| context watches    | yes    | no      | no    | no   | no    | terminal |
+| context unwatch    | yes    | no      | no    | no   | no    | terminal |
+| context reverify   | yes    | no      | no    | no   | no    | terminal |
 | context rm         | no     | no      | no    | no   | no    | terminal |
 | models list        | yes    | no      | no    | yes  | no    | terminal |
 | models pull        | no     | no      | no    | no   | no    | terminal |
 | models clear       | no     | no      | no    | no   | no    | terminal |
 | models path        | yes    | no      | no    | no   | no    | terminal |
+| publish export     | yes    | no      | no    | no   | no    | terminal |
 | cleanup            | no     | no      | no    | no   | no    | terminal |
 | doctor             | yes    | no      | no    | yes  | no    | terminal |
 | mcp                | no     | no      | no    | no   | no    | stdio    |
@@ -1364,6 +1369,58 @@ fingerprint and deterministic recount callback before any store read; CLI
 runtimes without that tokenizer fail with `tokenizer_unavailable` rather than
 trusting saved `usedTokens`.
 
+### gno context watch / watches / unwatch / reverify
+
+Register an explicit canonical JSON Capsule file for local, evidence-triggered
+reverification:
+
+```bash
+gno context watch <file> [--question <text>] [--label <text>] [--notify] [--json]
+gno context watches [--json]
+gno context unwatch <registration> [--json]
+gno context reverify <registration> [--json]
+```
+
+The registration persists only the absolute file path, exact file hash,
+Capsule/index identity, optional question and label, notification preference,
+and evidence URI/hash references. Capsule bytes and evidence passages are never
+copied into the database. The file remains caller-owned and immutable to GNO.
+The Capsule's canonical index is authoritative when `watch` is invoked without
+an explicit global `--index`; an explicit mismatch fails before journal or
+evidence reads.
+
+A resident `serve` or `daemon` runtime reverifies affected registrations after
+watcher work has settled. Raw journal changes are coalesced, one bounded
+reverification batch runs at a time, and the durable journal high-water mark
+prevents duplicate work after restart. An expired journal cursor triggers a
+conservative bounded pass over all registrations. Reverification uses the
+canonical `context verify` receipt. Operation failures are stored separately
+and never synthesized into a receipt.
+
+`--notify` enables local metadata-only `capsule-reverified` events after the
+verification record commits. Events contain registration/Capsule identity,
+operation status, affected-question state, and timestamp; they contain no
+question, file path, URI, passage, Capsule, or receipt bytes. `context
+reverify` performs the same non-generative verification immediately.
+
+`context reverify` exits `0` only when `operationStatus` is `completed`. A
+persisted `failed` operation is still rendered: terminal output includes the
+failure code and message, while `--json` writes the closed structured
+reverification object to stdout. The command then exits `2`; the structured
+failure must never be mistaken for a successful verification receipt.
+
+JSON contracts are Draft-07 and closed:
+
+- `watch`: `saved-capsule-watch.schema.json`; the initial verification is null.
+- `watches`: `saved-capsule-list.schema.json`.
+- `unwatch`: `saved-capsule-unwatch.schema.json`.
+- `reverify`: `saved-capsule-reverification.schema.json`; a completed
+  canonical receipt and a failed operation record are mutually exclusive.
+- local SSE notification data: `capsule-reverified-event.schema.json`.
+
+These registration-management surfaces are CLI-only. REST, MCP, and SDK expose
+the non-persistent `context verify` operation, not watch lifecycle mutations.
+
 ---
 
 ### gno models list
@@ -1502,6 +1559,49 @@ gno models path [--json]
 
 ---
 
+### gno publish export
+
+Build a reader-safe gno.sh artifact from one active collection or document.
+
+**Synopsis:**
+
+```bash
+gno publish export <target> \
+  [--out <path>] \
+  [--visibility public|secret-link|invite-only|encrypted] \
+  [--passphrase <value>] \
+  [--slug <slug>] \
+  [--title <title>] \
+  [--summary <summary>] \
+  [--preview] \
+  [--json]
+```
+
+Public V1 spaces MUST carry a `manifest` conforming to
+[`publish-artifact.schema.json`](./output-schemas/publish-artifact.schema.json).
+The manifest contains schema version `1.0`, a deterministic projection
+revision, generated time, closed public capabilities, sorted published
+documents, relative Markdown locators, SHA-256 content hashes, and
+Capsule-compatible evidence identities. Manifest hashes and revisions MUST be
+derived only from sanitized notes and metadata present in the published
+projection. Local collection paths, document source URIs, unpublished
+documents, and filtered metadata MUST NOT enter artifact bytes or revision
+inputs. Reader metadata values containing embedded local path or GNO/file URI
+tokens MUST be filtered. Canonical and image metadata MUST contain
+uncredentialed public HTTP(S) targets; local hostnames and literal loopback,
+private, or link-local addresses MUST be filtered.
+
+Secret-link and invite-only V1 spaces MUST NOT contain a manifest or agent
+capability field. Encrypted V2 spaces MUST contain only ciphertext parameters,
+the opaque secret token, route slug, source type, and encrypted visibility; no
+plaintext manifest or evidence may appear outside the ciphertext. V2 builders
+MUST emit a closed projection, validate payload strings as non-empty bounded
+base64, require a positive safe-integer KDF iteration count, and bound the
+non-blank opaque token. Caller-supplied extension fields MUST NOT enter the
+artifact.
+
+---
+
 ### gno cleanup
 
 Remove orphaned content, chunks, and vectors not referenced by active documents.
@@ -2607,6 +2707,50 @@ derived from frontmatter relations, content-type graph hints, and backfilled
 wiki/markdown projections (for example `mentions`, `references`, or
 `related`), not the global graph export edge-type enum above.
 
+### gno changes
+
+List retained, metadata-only document lifecycle changes.
+
+```bash
+gno changes [--since <ISO-8601|cursor>] [--collection <name>] [--limit <n>] [--json]
+```
+
+- `--since` accepts an ISO-8601 time or an opaque cursor returned by an earlier
+  call. Cursors are monotonic, stable, and must not be parsed by callers.
+- `--limit` defaults to 100 and is bounded to 1-1000.
+- JSON output uses `changes.schema.json`. It includes opaque per-change IDs,
+  old/new identity and hash snapshots, normalized structural deltas, pagination,
+  cursor-expiry, and retention-truncation disclosure.
+- The journal never returns source bodies.
+
+### gno diff
+
+Show the latest retained structural delta for one document, or select an exact
+retained journal entry by opaque ID.
+
+```bash
+gno diff <doc> [--change <id>] [--json]
+```
+
+JSON output uses `document-diff.schema.json`. `content.status` is always
+`not_retained`; GNO does not reconstruct old bodies. `history.status` is
+`partial` when `structureDelta.truncated` discloses unavailable prior
+structure. Expired/purged IDs return `status: "expired"` without inventing
+history.
+
+### gno impact
+
+Find active documents that depend on one document through inbound typed,
+wiki-link, or Markdown-link edges.
+
+```bash
+gno impact <doc> [--max-depth <n>] [--max-nodes <n>] [--max-edges <n>] [--frontier-limit <n>] [--visited-limit <n>] [--json]
+```
+
+The traversal is cycle-safe and enforces depth, node, edge, frontier, and
+visited-row caps. Every impacted document includes one deterministic
+dependency-to-root evidence path. JSON output uses `impact.schema.json`.
+
 **Exit Codes:**
 
 - 0: Success

package/spec/db/schema.sql

@@ -19,6 +19,8 @@
 --   retrieval_traces - Opt-in private retrieval trace headers
 --   retrieval_trace_runs/events/judgments - Bounded trace outcome records
 --   retrieval_trace_exports/export_traces - Export manifests and trace joins
+--   document_changes - Bounded metadata-only document lifecycle journal
+--   document_change_journal_state - Monotonic cursor/retention boundary
 
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Schema Metadata
@@ -361,6 +363,64 @@ CREATE TABLE IF NOT EXISTS retrieval_trace_export_traces (
 -- and an absolute 100,000 subordinate-record safety cap per trace. Runtime
 -- retention applies the lower configured maxRecordsPerTrace bound.
 
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Document Change Journal
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- Append-only while retained. Rows contain identity, hashes, active state, and
+-- compact structural summaries only; source and converted bodies are excluded.
+
+CREATE TABLE IF NOT EXISTS document_changes (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  document_id INTEGER NOT NULL CHECK (document_id > 0),
+  collection TEXT NOT NULL,
+  change_kind TEXT NOT NULL
+    CHECK (change_kind IN ('create', 'update', 'rename', 'inactivate', 'reactivate')),
+  old_rel_path TEXT,
+  new_rel_path TEXT,
+  old_docid TEXT,
+  new_docid TEXT,
+  old_uri TEXT,
+  new_uri TEXT,
+  old_source_hash TEXT,
+  new_source_hash TEXT,
+  old_mirror_hash TEXT,
+  new_mirror_hash TEXT,
+  old_active INTEGER CHECK (old_active IS NULL OR old_active IN (0, 1)),
+  new_active INTEGER CHECK (new_active IS NULL OR new_active IN (0, 1)),
+  heading_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+  link_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+  typed_edge_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+  date_delta_json TEXT NOT NULL
+    DEFAULT '{"added":[],"removed":[],"changed":[]}',
+  structure_truncated INTEGER NOT NULL DEFAULT 0
+    CHECK (structure_truncated IN (0, 1)),
+  observed_at_ms INTEGER NOT NULL CHECK (observed_at_ms >= 0),
+  byte_size INTEGER NOT NULL CHECK (byte_size > 0 AND byte_size <= 131072),
+  CHECK (length(CAST(heading_delta_json AS BLOB)) <= 16384),
+  CHECK (length(CAST(link_delta_json AS BLOB)) <= 16384),
+  CHECK (length(CAST(typed_edge_delta_json AS BLOB)) <= 16384),
+  CHECK (length(CAST(date_delta_json AS BLOB)) <= 16384)
+);
+
+CREATE INDEX IF NOT EXISTS idx_document_changes_collection_sequence
+  ON document_changes(collection, sequence);
+CREATE INDEX IF NOT EXISTS idx_document_changes_document_sequence
+  ON document_changes(document_id, sequence);
+CREATE INDEX IF NOT EXISTS idx_document_changes_retention
+  ON document_changes(observed_at_ms, sequence);
+
+CREATE TABLE IF NOT EXISTS document_change_journal_state (
+  singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+  last_sequence INTEGER NOT NULL DEFAULT 0 CHECK (last_sequence >= 0),
+  retention_floor INTEGER NOT NULL DEFAULT 0
+    CHECK (retention_floor >= 0 AND retention_floor <= last_sequence),
+  retained_entries INTEGER NOT NULL DEFAULT 0
+    CHECK (retained_entries >= 0),
+  retained_bytes INTEGER NOT NULL DEFAULT 0
+    CHECK (retained_bytes >= 0)
+);
+
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Document Tags
 -- ─────────────────────────────────────────────────────────────────────────────
@@ -440,3 +500,113 @@ CREATE TABLE IF NOT EXISTS doc_edges (
 
 CREATE INDEX IF NOT EXISTS idx_doc_edges_src_type ON doc_edges(src_doc_id, edge_type);
 CREATE INDEX IF NOT EXISTS idx_doc_edges_dst_type ON doc_edges(dst_doc_id, edge_type);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- Saved Context Capsules (metadata only)
+-- ─────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS saved_capsule_registrations (
+  registration_id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL UNIQUE,
+  file_hash TEXT NOT NULL,
+  capsule_id TEXT NOT NULL,
+  index_name TEXT NOT NULL,
+  question TEXT,
+  label TEXT,
+  notification_preference TEXT NOT NULL DEFAULT 'none'
+    CHECK (notification_preference IN ('none', 'local')),
+  registered_at_ms INTEGER NOT NULL CHECK (registered_at_ms >= 0),
+  updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= registered_at_ms),
+  last_attempted_sequence INTEGER NOT NULL DEFAULT 0
+    CHECK (last_attempted_sequence >= 0),
+  registration_generation INTEGER NOT NULL DEFAULT 0
+    CHECK (registration_generation >= 0),
+  CHECK (length(registration_id) BETWEEN 1 AND 128),
+  CHECK (length(CAST(file_path AS BLOB)) BETWEEN 1 AND 8192),
+  CHECK (length(file_hash) = 64 AND file_hash NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(capsule_id) = 64 AND capsule_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(CAST(index_name AS BLOB)) BETWEEN 1 AND 128),
+  CHECK (question IS NULL OR length(CAST(question AS BLOB)) <= 8192),
+  CHECK (label IS NULL OR length(CAST(label AS BLOB)) <= 512)
+);
+
+CREATE INDEX IF NOT EXISTS idx_saved_capsules_index
+  ON saved_capsule_registrations(index_name, registration_id);
+
+CREATE TABLE IF NOT EXISTS saved_capsule_evidence (
+  registration_id TEXT NOT NULL,
+  evidence_id TEXT NOT NULL,
+  canonical_uri TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  source_hash TEXT NOT NULL,
+  mirror_hash TEXT NOT NULL,
+  passage_hash TEXT NOT NULL,
+  PRIMARY KEY (registration_id, evidence_id),
+  FOREIGN KEY (registration_id)
+    REFERENCES saved_capsule_registrations(registration_id)
+    ON DELETE CASCADE,
+  CHECK (length(evidence_id) = 64 AND evidence_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(CAST(canonical_uri AS BLOB)) BETWEEN 1 AND 8192),
+  CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+  CHECK (length(source_hash) = 64 AND source_hash NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(mirror_hash) = 64 AND mirror_hash NOT GLOB '*[^0-9a-f]*'),
+  CHECK (length(passage_hash) = 64 AND passage_hash NOT GLOB '*[^0-9a-f]*')
+);
+
+CREATE INDEX IF NOT EXISTS idx_saved_capsule_evidence_uri
+  ON saved_capsule_evidence(canonical_uri, registration_id);
+CREATE INDEX IF NOT EXISTS idx_saved_capsule_evidence_source
+  ON saved_capsule_evidence(source_hash, registration_id);
+CREATE INDEX IF NOT EXISTS idx_saved_capsule_evidence_mirror
+  ON saved_capsule_evidence(mirror_hash, registration_id);
+
+CREATE TABLE IF NOT EXISTS saved_capsule_verifications (
+  registration_id TEXT PRIMARY KEY,
+  trigger_kind TEXT NOT NULL CHECK (trigger_kind IN ('manual', 'journal')),
+  from_sequence INTEGER NOT NULL CHECK (from_sequence >= 0),
+  through_sequence INTEGER NOT NULL CHECK (through_sequence >= from_sequence),
+  operation_status TEXT NOT NULL CHECK (operation_status IN ('completed', 'failed')),
+  affected_question_state TEXT NOT NULL
+    CHECK (affected_question_state IN ('unaffected', 'affected', 'unknown')),
+  affected_reasons_json TEXT NOT NULL,
+  receipt_json TEXT,
+  receipt_hash TEXT,
+  error_code TEXT,
+  error_message TEXT,
+  verified_at_ms INTEGER NOT NULL CHECK (verified_at_ms >= 0),
+  FOREIGN KEY (registration_id)
+    REFERENCES saved_capsule_registrations(registration_id)
+    ON DELETE CASCADE,
+  CHECK (length(CAST(affected_reasons_json AS BLOB)) <= 4096),
+  CHECK (receipt_json IS NULL OR length(CAST(receipt_json AS BLOB)) <= 16777216),
+  CHECK (receipt_hash IS NULL OR (
+    length(receipt_hash) = 64 AND receipt_hash NOT GLOB '*[^0-9a-f]*'
+  )),
+  CHECK (error_code IS NULL OR length(CAST(error_code AS BLOB)) <= 256),
+  CHECK (error_message IS NULL OR length(CAST(error_message AS BLOB)) <= 4096),
+  CHECK (
+    (
+      operation_status = 'completed'
+      AND receipt_json IS NOT NULL
+      AND receipt_hash IS NOT NULL
+      AND error_code IS NULL
+      AND error_message IS NULL
+    )
+    OR
+    (
+      operation_status = 'failed'
+      AND receipt_json IS NULL
+      AND receipt_hash IS NULL
+      AND error_code IS NOT NULL
+      AND error_message IS NOT NULL
+    )
+  )
+);
+
+CREATE TABLE IF NOT EXISTS saved_capsule_reverification_state (
+  singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+  last_processed_sequence INTEGER NOT NULL DEFAULT 0
+    CHECK (last_processed_sequence >= 0),
+  registration_epoch INTEGER NOT NULL DEFAULT 0
+    CHECK (registration_epoch >= 0)
+);

package/spec/evals-agentic.md

@@ -24,6 +24,7 @@ evals/agentic/
   promotion.ts
   verified-ask-outcome.ts
   verified-ask-promotion.ts
+  demos/context-capsule.ts
   registry.ts
   report.ts
   report-artifacts.ts
@@ -44,6 +45,7 @@ evals/agentic/
     final-envelope.schema.json
     trajectory-receipt.schema.json
     benchmark-report.schema.json
+    context-capsule-demo.schema.json
 
 evals/fixtures/agentic-retrieval/
   manifest.json
@@ -61,6 +63,9 @@ evals/fixtures/agentic-retrieval/
       verified-ask-promotion.json
       verified-ask-promotion.md
     optional/{qmd,local-model}/     # local opt-in evidence; not authoritative
+  demos/
+    context-capsule.json
+    context-capsule.md
 ```
 
 The first fixture version contains 24 original synthetic tasks and 34 Markdown
@@ -412,6 +417,48 @@ summary. The six files are staged and directory-renamed as one baseline set.
 The verified Ask files are a separate attributable outcome lane; they do not
 rename the Capsule retrieval promotion in `report.json`.
 
+## Reproducible Context Capsule demo
+
+`demos/context-capsule.json` is a closed, canonically fingerprinted projection
+of one frozen exact-identifier task from the authoritative fixture-agent
+report. It contains exactly three lanes in fixed order: the lexical-only
+no-GNO baseline, shipped GNO MCP query/get primitives, and the Context Capsule.
+Every lane retains its complete normalized trajectory receipt, score, exact
+evidence coordinates and hashes, final stop outcome, agent/backend call counts,
+model-visible UTF-8 bytes, token availability, and matching-lifecycle latency.
+
+All three lanes must share the task, outer agent, trial, seed, lifecycle,
+corpus, prompt, tool, model, runtime, and canonical effective-index
+fingerprints. The generator selects exactly one receipt and score per full
+identity and rejects ambiguous multi-trial input. Adapter configuration
+fingerprints may differ. The Capsule projection additionally retains its
+normalized `retrieval.request`, effective index fingerprint, capability states,
+fallback list, and complete model-visible payload. Validation parses the
+delivered evidence bundle and compares those values, then recomputes every
+displayed lane metric from the embedded receipt and score.
+
+Source provenance distinguishes each source run's clean `runGitCommit` from
+the later Git commit that contains the generated demo artifact. The artifact
+does not attempt to embed its own containing commit. Its report and Verified
+Ask fingerprints and projected fields must match the canonical linked source
+artifacts.
+
+The readable `context-capsule.md` is generated from the JSON contract. It
+states the single-trial variance limitation, reports tokens as unavailable
+without one pinned comparable tokenizer, and limits its claim to the measured
+controlled task. It discloses that the chosen task is the sole cold
+current-GNO-failure / Capsule-success case in the 24-task authoritative cohort,
+that the Capsule lane is an evaluation-only lexical prototype, and that its
+latency is not shipped-product latency. It cannot be used as a general
+product-superiority claim.
+
+The adjacent Verified Ask block is an attributable but separate
+`answer_enforcement` proof. It binds the clean-Git canonical fingerprint of the
+frozen 22-pair `raw_ask`/`verified_ask` artifact, retains the two declared
+missing-evidence exclusions, and exposes only answer-accuracy and unsupported-
+substantive-claim metrics. Those metrics are never merged into or labeled as
+retrieval metrics.
+
 ## Deterministic scoring
 
 The scorer compares typed claims and exact citations with the hidden oracle. It
@@ -551,6 +598,7 @@ Contract tests are ordinary offline tests:
 
 ```bash
 bun test test/eval/agentic
+bun run eval:agentic:demo
 ```
 
 The runner is local and opt-in:

package/spec/mcp.md

@@ -1526,6 +1526,28 @@ Use for explicit relationship questions over typed edges such as `works_at`,
 `attended`, or `mentions` after a seed ref is known. Use `gno_query` first if
 the seed document is unknown.
 
+### gno_changes
+
+Read-only metadata journal listing. Input fields: `since` (ISO-8601 time or
+opaque cursor), `collection`, and `limit` (1-1000, default 100). Structured
+content is contract-identical to CLI/REST/SDK `changes.schema.json`; it never
+contains source bodies.
+
+### gno_diff
+
+Read-only structural diff for `ref`, optionally selecting opaque `change`.
+Structured content is `document-diff.schema.json`. Expired/purged history and
+metadata-only content are explicit output states, while unavailable prior
+structure is derived from `structureDelta.truncated`.
+
+### gno_impact
+
+Read-only inbound dependency traversal for `ref`. Inputs `maxDepth`,
+`maxNodes`, `maxEdges`, `frontierLimit`, and `visitedLimit` use the same bounds
+as CLI/REST/SDK. Structured content is `impact.schema.json`; each impacted
+document includes a deterministic evidence path over typed or backlink
+projections. Truncation is explicit when any cap is reached.
+
 ---
 
 ### gno_graph_neighbors