@gmickel/gno 1.27.1 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.27.1",
+  "version": "1.29.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -220,7 +220,7 @@
     "playwright": "1.58.2",
     "pptxgenjs": "4.0.1",
     "ultracite": "7.1.5",
-    "vitest": "4.0.18",
+    "vitest": "4.1.0",
     "web-tree-sitter": "0.26.8"
   },
   "peerDependencies": {

package/spec/cli.md

@@ -73,8 +73,8 @@ equivalent files fail closed as ambiguous.
 | collection list    | yes    | no      | no    | yes  | no    | terminal |
 | collection remove  | no     | no      | no    | no   | no    | terminal |
 | collection rename  | no     | no      | no    | no   | no    | terminal |
-| update             | no     | no      | no    | no   | no    | terminal |
-| index              | no     | no      | no    | no   | no    | terminal |
+| update             | yes    | no      | no    | no   | no    | terminal |
+| index              | yes    | no      | no    | no   | no    | terminal |
 | embed              | no     | no      | no    | no   | no    | terminal |
 | search             | yes    | yes     | yes   | yes  | yes   | terminal |
 | vsearch            | yes    | yes     | yes   | yes  | yes   | terminal |
@@ -672,6 +672,44 @@ gno collection clear-embeddings <name> [--all] [--json]
 
 ---
 
+### gno collection policy
+
+Inspect, change, or explain one collection-owned egress boundary.
+
+```bash
+gno collection policy get <name>
+gno collection policy set <name> <local_only|lan|remote> [--confirm-relaxation <current-revision>]
+gno collection policy check --action <action> --destination <zone> --content-class <class> [-c <name>...] [--authenticated] [--authorized] [--partial] [--explain-egress]
+```
+
+`get` returns the configured value, effective value, provenance source, and a
+durable monotonic revision plus a diagnostic version fingerprint. Tightening is
+immediate. Relaxation requires `--confirm-relaxation` with the exact current
+numeric revision returned by `get`; stale, replayed, cross-collection, and
+cross-target confirmation fails without changing config or the index
+projection.
+`check` and `--explain-egress` perform no action. They return the same
+content-free decision, lineage, partial disclosure, audit metadata, and
+remediation contract.
+
+### gno egress-audit
+
+Manage local content-free policy decision receipts:
+
+```bash
+gno egress-audit list [--limit <n>] [--cursor <cursor>]
+gno egress-audit show <audit-id>
+gno egress-audit status
+gno egress-audit delete <audit-id>
+gno egress-audit purge
+```
+
+Pages are newest-first. Delete/purge report truthful SQLite physical cleanup
+status. These local inspection and deletion commands never require a relaxed
+collection policy.
+
+---
+
 ### gno embed
 
 Generate embeddings for indexed chunks.
@@ -772,13 +810,14 @@ Sync files from disk into the index (ingestion without embedding).
 **Synopsis:**
 
 ```bash
-gno update [--git-pull]
+gno update [--git-pull] [--json]
 ```
 
 **Options:**
 | Option | Type | Description |
 |--------|------|-------------|
 | `--git-pull` | boolean | Run `git pull` in git repositories before scanning |
+| `--json` | boolean | Emit the complete deterministic sync result on stdout |
 
 **Behavior:**
 
@@ -789,6 +828,13 @@ gno update [--git-pull]
 5. Update FTS index
 6. Mark missing files as inactive
 
+**JSON output:** The top-level value is the complete sync result. Each entry in
+`collections[].files[]` may contain a `recordImport` receipt conforming to
+[`record-import@1.0`](./output-schemas/record-import.schema.json). Receipt items
+are sorted deterministically and capped at 1,000; `itemsTruncated` reports
+omitted actions. Partial snapshots expose `warnings[]` even when no individual
+record failure was reported. Human progress and diagnostics remain on stderr.
+
 **Exit Codes:**
 
 - 0: Success (conversion warnings do not affect exit code)
@@ -803,7 +849,7 @@ Build or update the index end-to-end (update + embed).
 **Synopsis:**
 
 ```bash
-gno index [--collection <name>] [--no-embed] [--models-pull] [--git-pull] [--yes]
+gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes]
 ```
 
 **Options:**
@@ -813,6 +859,7 @@ gno index [--collection <name>] [--no-embed] [--models-pull] [--git-pull] [--yes
 | `--no-embed` | boolean | Run ingestion only, skip embedding |
 | `--models-pull` | boolean | Download models if missing (prompts unless `--yes`) |
 | `--git-pull` | boolean | Run `git pull` in git repositories |
+| `--json` | boolean | Emit the complete deterministic sync and embedding result on stdout |
 | `--yes` | boolean | Accept defaults, no prompts |
 
 **Behavior:**
@@ -820,6 +867,13 @@ gno index [--collection <name>] [--no-embed] [--models-pull] [--git-pull] [--yes
 - Runs `update` then `embed` by default
 - With `--no-embed`, runs `update` only
 
+**JSON output:** Emits `{ syncResult, embedSkipped, embedResult? }`.
+`syncResult.collections[].files[].recordImport`, when present, conforms to
+[`record-import@1.0`](./output-schemas/record-import.schema.json) with the same
+deterministic ordering, bounds, truncation disclosure, and partial-snapshot
+warnings as `gno update --json`. Human progress and diagnostics remain on
+stderr.
+
 **Exit Codes:**
 
 - 0: Success
@@ -1034,6 +1088,27 @@ broad-to-specific path-prefix order. The field is absent when no scope matches;
 `uri` and `docid` remain the exact source identity. The same contract applies to
 `vsearch`, `query`, and the `results` array returned by `ask`.
 
+Logical documents created from file/export adapters additionally include a
+bounded `record` object with their opaque record key, exact export locator,
+people/dates, thread/event/session identity, attachment inventory, and anchors.
+`source.relPath` names the real export container; `uri` and `docid` address the
+individual virtual document. The closed `record.adapter` identity contains the
+adapter ID, version, and configuration fingerprint. `get` and `multi-get`
+preserve the same fields.
+
+File/export adapter iteration has a 60-second deadline in addition to the byte,
+record, metadata, and total-character caps. A partial import that retains valid
+siblings exits successfully but is never silent: terminal output includes the
+file, bounded warning count, and snapshot state; `--verbose` adds stable failure
+codes, bounded source locators, retryability, and redacted messages.
+`gno update --json`, `gno index --json`, and internal and SDK-facing sync
+results include a `recordImport` receipt conforming to
+[`record-import@1.0`](./output-schemas/record-import.schema.json), with adapter
+identity, configuration fingerprint, snapshot authority, cap state, bytes read,
+per-action identity/provenance/attachment receipts, truncation disclosure,
+warnings, and bounded failures. `.gno/records/` is a reserved virtual
+namespace and is never walked as physical collection content.
+
 **Exit Codes:**
 
 - 0: Success (including zero results)
@@ -3236,7 +3311,9 @@ is blocked.
 - Starts a headless `/mcp` Streamable HTTP listener; it does not serve the Web UI
 - Exposes the same safe REST lifecycle snapshot at `/api/resident/status`;
   resident-aware app status at `/api/status` is loopback-only because it
-  includes local index and configuration details
+  includes local index and configuration details. Non-loopback resident status
+  intersects exact Host/Origin and bearer authentication with the current
+  peer zone and all participating collection policies before returning metadata
 - On `--detach`: forks a detached child with stdio redirected to `--log-file`, writes pid-file JSON including the MCP gateway `port`, prints `{pid}` on stdout, exits 0
 - On `--status`: output matches the [process-status schema](./output-schemas/process-status.schema.json), including the MCP gateway port and a best-effort copy of the live redacted resident snapshot
 - On `--stop`: SIGTERM → 10s poll → SIGKILL → 2s poll; the daemon's own signal handler unlinks the pid-file, `--stop` unlinks as fallback

package/spec/db/schema.sql

@@ -49,6 +49,25 @@ CREATE TABLE IF NOT EXISTS collections (
   exclude TEXT,              -- JSON array of patterns
   update_cmd TEXT,
   language_hint TEXT,        -- BCP-47 or NULL
+  -- Migration 023 backfills existing rows as local_only/legacy_default.
+  -- Config sync without an explicit value remains local_only/config_default;
+  -- only explicit config may persist lan or remote.
+  egress_policy TEXT NOT NULL DEFAULT 'local_only'
+    CHECK (egress_policy IN ('local_only', 'lan', 'remote')),
+  egress_policy_source TEXT NOT NULL DEFAULT 'legacy_default'
+    CHECK (
+      egress_policy_source IN (
+        'explicit',
+        'config_default',
+        'legacy_default'
+      )
+    )
+    CHECK (
+      egress_policy_source = 'explicit'
+      OR egress_policy = 'local_only'
+    ),
+  egress_policy_revision INTEGER NOT NULL DEFAULT 0
+    CHECK (egress_policy_revision >= 0),
   synced_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
@@ -92,6 +111,12 @@ CREATE TABLE IF NOT EXISTS documents (
   converter_version TEXT,
   language_hint TEXT,               -- BCP-47 or NULL
   content_type_source TEXT,         -- frontmatter | rules | default | extension | null
+  record_key TEXT,                  -- opaque stable logical-record identity
+  record_source_path TEXT,          -- collection-relative export/container path
+  record_source_locator TEXT,       -- bounded exact record/cue/message/event locator
+  record_metadata TEXT,             -- bounded canonical JSON record metadata
+  record_anchors TEXT,              -- bounded canonical JSON exact anchors
+  record_adapter_fingerprint TEXT,  -- config-bound adapter identity for re-import invalidation
 
   -- Status
   active INTEGER NOT NULL DEFAULT 1,
@@ -116,6 +141,12 @@ CREATE INDEX IF NOT EXISTS idx_documents_active ON documents(active);
 CREATE INDEX IF NOT EXISTS idx_documents_mirror_hash ON documents(mirror_hash);
 CREATE INDEX IF NOT EXISTS idx_documents_docid ON documents(docid);
 CREATE INDEX IF NOT EXISTS idx_documents_uri ON documents(uri);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_documents_record_key
+  ON documents(collection, record_source_path, record_key)
+  WHERE record_source_path IS NOT NULL AND record_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_documents_record_source_path
+  ON documents(collection, record_source_path)
+  WHERE record_source_path IS NOT NULL;
 
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Content (content-addressed markdown mirrors)

package/spec/mcp.md

@@ -98,6 +98,26 @@ HTTP MCP remains read-only unless `gateway.enableWrite: true` or
 authorize mutation. Unauthorized calls to write tools fail with HTTP 403 before
 SDK dispatch.
 
+Every `tools/call`, `resources/list`, `resources/templates/list`, and
+`resources/read` request is also checked against the current socket peer zone
+and the effective policy of every referenced collection before SDK dispatch.
+The check is per request, including batch members and requests that reuse an
+existing session; a session's original peer zone is never reused as authority.
+Non-loopback access therefore requires both a valid bearer token and a
+compatible collection policy. Policy denial returns HTTP 403 with stable
+`EGRESS_DENIED` data and a redacted evaluator audit. Write authorization remains
+an independent additional requirement.
+
+The MCP tool and resource registry is paired with a callsite-level
+network-boundary inventory. A TypeScript AST scan covers shipped TS, TSX, JS,
+and JSX and recognizes direct, qualified, bracketed, imported, and aliased
+fetch, EventSource, WebSocket, Bun listener/DNS/socket, HTTP inference, and
+external-process primitives. Every detected invocation has its own stable
+inventory key, so adding a second call in an already-listed file still fails
+the contract test. Browser same-origin calls are classified as client
+transport and name the server route that performs the actual egress check; the
+client scan itself is not treated as content authorization.
+
 Boundary failures use the closed
 [`mcp-http-error`](./output-schemas/mcp-http-error.schema.json) body with stable,
 redacted statuses: 401 (authentication), 403 (peer/Host/Origin/write), 413
@@ -697,6 +717,11 @@ Search result items include `contentType` when available and always include
 human-oriented; structured clients should read `structuredContent.results`.
 Structured result items also preserve optional `context` guidance in
 global-to-specific order without changing the result `uri` or `docid`.
+File/export records also include bounded `record` provenance in structured
+search/get/multi-get/Ask output. Their `source.relPath` is the real local export
+container while the unique `uri` remains the required exact retrieval ref. The
+closed `record.adapter` object identifies the adapter ID, version, and
+configuration fingerprint used to produce the logical record.
 When `explain: true`, `structuredContent.meta.explain` includes deterministic
 stage lines and per-result score receipts. Non-neutral configured content-type
 rules add `contentTypeBoost` with base/raw scores, factor, capped contribution,
@@ -2341,6 +2366,52 @@ MCP Server Status
 
 ---
 
+## Collection Egress Policy and Audit Tools
+
+Read tools:
+
+- `gno_egress_policy_get { collection }` returns configured/effective policy,
+  provenance source, current monotonic revision, and diagnostic version.
+- `gno_egress_check` accepts exact collection scope, action, destination zone,
+  caller authentication/authorization, content class, and partial mode. It
+  performs no action and returns the canonical decision/explanation contract.
+  An explicit scope is a non-empty, duplicate-free list of at most 64 canonical
+  collection names; omitted scope means all configured collections.
+- `gno_egress_audit_list`, `gno_egress_audit_show`, and
+  `gno_egress_audit_status` expose only content-free local receipts.
+
+Write-enabled tools:
+
+- `gno_egress_policy_set` requires confirmation
+  `{ collection, currentPolicy, currentRevision, targetPolicy, acknowledged: true }`
+  for relaxation. The revision is durable and one-use; replayed, stale,
+  cross-collection, and cross-target confirmations fail closed.
+- `gno_egress_audit_delete` deletes exactly one receipt.
+- `gno_egress_audit_purge { confirm: true }` deletes only audit receipts.
+
+Policy does not replace transport authentication or `enableWrite`. Local audit
+inspection remains available when outbound content is denied. Retrieval-trace
+export resolves exact trace lineage and checks policy before creating or
+reusing an export receipt; missing traces return `NOT_FOUND` before policy
+evaluation.
+
+All collection-policy and audit tool inputs are closed objects. Unknown
+top-level fields are rejected by MCP input validation before any handler,
+mutation, invalidation, or audit operation runs.
+
+Active resident requests retain their admission authorization epoch. A policy
+mutation may advance its own request to the new epoch, but older REST and MCP
+responses are replaced by a content-free `EGRESS_POLICY_CHANGED` retry
+response/event before protected bytes are emitted, including streaming
+responses. `/api/events` binds each SSE subscriber to its admission epoch and
+rechecks it before every document event and heartbeat; a stale subscriber
+receives only the retry event and is then unsubscribed.
+
+Schemas: `collection-egress-policy.schema.json`,
+`collection-egress-policy-set.schema.json`,
+`collection-egress-check.schema.json`, and
+`egress-audit-management.schema.json`.
+
 ## See Also
 
 - [CLI Specification](./cli.md)

package/spec/output-schemas/ask.schema.json

@@ -95,6 +95,35 @@
     }
   ],
   "$defs": {
+    "egressLineage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["effectivePolicy", "digest", "sources"],
+      "properties": {
+        "effectivePolicy": { "enum": ["local_only", "lan", "remote"] },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 128,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["collection", "policy", "source"],
+            "properties": {
+              "collection": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+              },
+              "policy": { "enum": ["local_only", "lan", "remote"] },
+              "source": {
+                "enum": ["explicit", "config_default", "legacy_default"]
+              }
+            }
+          }
+        }
+      }
+    },
     "searchResult": {
       "type": "object",
       "required": ["docid", "score", "uri", "snippet", "source"],
@@ -127,10 +156,136 @@
           "type": "string",
           "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
         },
+        "egressLineage": { "$ref": "#/$defs/egressLineage" },
         "snippet": {
           "type": "string",
           "description": "Matching text snippet from document mirror"
         },
+        "record": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Bounded logical-record provenance for a file/export source",
+          "required": ["recordKey", "sourceLocator", "anchors", "adapter"],
+          "properties": {
+            "recordKey": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+            "sourceLocator": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "anchors": {
+              "type": "array",
+              "maxItems": 256,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["kind", "value"],
+                "properties": {
+                  "kind": {
+                    "enum": [
+                      "line",
+                      "cue",
+                      "timestamp",
+                      "message",
+                      "event",
+                      "record"
+                    ]
+                  },
+                  "value": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512
+                  },
+                  "endValue": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512
+                  }
+                }
+              }
+            },
+            "adapter": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "version", "fingerprint"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+                "version": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 64
+                },
+                "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+              }
+            },
+            "author": { "type": "string", "maxLength": 2048 },
+            "participants": {
+              "type": "array",
+              "maxItems": 256,
+              "items": { "type": "string", "minLength": 1, "maxLength": 2048 }
+            },
+            "categories": {
+              "type": "array",
+              "maxItems": 256,
+              "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+            },
+            "dateFields": {
+              "type": "object",
+              "maxProperties": 256,
+              "propertyNames": { "type": "string", "maxLength": 128 },
+              "additionalProperties": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 256
+              }
+            },
+            "messageId": { "type": "string", "maxLength": 2048 },
+            "inReplyTo": { "type": "string", "maxLength": 2048 },
+            "references": {
+              "type": "array",
+              "maxItems": 256,
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 2048
+              }
+            },
+            "threadId": { "type": "string", "maxLength": 2048 },
+            "eventId": { "type": "string", "maxLength": 2048 },
+            "sessionId": { "type": "string", "maxLength": 2048 },
+            "attachments": {
+              "type": "array",
+              "maxItems": 256,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["name"],
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 512
+                  },
+                  "mime": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 256
+                  },
+                  "bytes": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  "disposition": { "enum": ["inline", "attachment"] },
+                  "sha256": {
+                    "type": "string",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
+                }
+              }
+            }
+          }
+        },
         "snippetRange": {
           "type": "object",
           "description": "Line range of snippet in mirror content",
@@ -306,7 +461,7 @@
         "schemaVersion": { "const": "1.0" },
         "mode": { "const": "closed_capsule" },
         "capsule": {
-          "$ref": "gno://schemas/context-capsule-v1@1.0"
+          "$ref": "gno://schemas/context-capsule-v1@1.1"
         },
         "freshness": {
           "$ref": "gno://schemas/context-capsule-verification@1.0"

package/spec/output-schemas/browser-clip-preview.schema.json

@@ -18,6 +18,7 @@
         "destination": {
           "$ref": "gno://schemas/browser-clip@1.0#/properties/destination"
         },
+        "egressLineage": { "$ref": "#/definitions/egressLineage" },
         "tags": {
           "type": "array",
           "items": { "type": "string" }
@@ -48,6 +49,35 @@
     }
   },
   "definitions": {
+    "egressLineage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["effectivePolicy", "digest", "sources"],
+      "properties": {
+        "effectivePolicy": { "enum": ["local_only", "lan", "remote"] },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "sources": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["collection", "policy", "source"],
+            "properties": {
+              "collection": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+              },
+              "policy": { "enum": ["local_only", "lan", "remote"] },
+              "source": {
+                "enum": ["explicit", "config_default", "legacy_default"]
+              }
+            }
+          }
+        }
+      }
+    },
     "source": {
       "type": "object",
       "additionalProperties": false,

package/spec/output-schemas/collection-egress-check.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://gno.sh/schemas/collection-egress-check.schema.json",
+  "title": "Collection egress check and explanation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "mode",
+    "allowedCollections",
+    "omittedCollections",
+    "disclosure",
+    "lineage",
+    "decision",
+    "remediation"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "mode": { "enum": ["complete", "partial", "denied"] },
+    "allowedCollections": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    },
+    "omittedCollections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["collection", "reason"],
+        "properties": {
+          "collection": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "disclosure": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "omittedCount", "omittedCollections"],
+          "properties": {
+            "code": { "const": "EGRESS_PARTIAL_RESULT" },
+            "omittedCount": { "type": "integer", "minimum": 1 },
+            "omittedCollections": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          }
+        }
+      ]
+    },
+    "lineage": {
+      "type": "object",
+      "required": ["effectivePolicy", "digest", "sources"],
+      "properties": {
+        "effectivePolicy": { "enum": ["local_only", "lan", "remote"] },
+        "digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "sources": { "type": "array", "minItems": 1 }
+      }
+    },
+    "decision": {
+      "type": "object",
+      "required": ["allowed", "code", "reason", "audit"],
+      "properties": {
+        "allowed": { "type": "boolean" },
+        "code": { "enum": ["EGRESS_ALLOWED", "EGRESS_DENIED"] },
+        "reason": { "type": "string" },
+        "audit": { "type": "object" }
+      }
+    },
+    "remediation": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    }
+  }
+}