@gmickel/gno 2.4.0 → 2.6.0

package/spec/compiled-context.md

@@ -0,0 +1,68 @@
+# Compiled project context
+
+Compiled context is a deterministic, extractive Markdown artifact derived from
+a verified Capsule. Source text remains fenced untrusted evidence. It does not
+install or overwrite agent instructions.
+
+## Shared contract
+
+- Preview input: {capsule: object, budgetTokens: positive integer, budgetBytes?: positive integer}.
+- Check input: {capsule: object, markdown: string}. The artifact's own bounded
+  metadata records rendering settings; no filesystem paths are accepted remotely.
+- Preview result: {schemaVersion:"1.0", rendererVersion:"1", capsuleId,
+  markdown, digest, verificationDigest, lineageDigest, budget:
+  {requestedTokens,requestedBytes,usedTokens,usedBytes,estimator,tokenizerFingerprint},
+  coverage:{complete,coveredFacets,unresolvedFacets}, evidenceIds,
+  omissions:[{evidenceId,reason}]}.
+- Check result: {schemaVersion:"1.0",status:"current"|"stale"|"conflict"|"unverifiable",
+  reasons:string[],digest:string|null,capsuleId:string|null}. It never returns
+  artifact/evidence bytes on drift or authorization failure.
+- Whole output (metadata, framing, citations and evidence) fits both budgets.
+  Bounds: 4 MiB input artifact/Capsule, 1,000,000 tokens, 4 MiB output bytes.
+- Use the Capsule's recorded estimator. A matching active-tokenizer authority
+  is mandatory when recorded; there is no silent estimator fallback.
+- Capsules1.1/1.2 contain required normalized retrieval/egress provenance.
+  Older Capsules must be rebuilt for compilation.
+- Markdown begins with an owned gno:compiled-context metadata comment, recording
+  format/renderer versions, Capsule/verification/lineage identities, payload
+  digest and settings. The response digest hashes all output bytes.
+- Compile/preview reject stale or unauthorized evidence. Check is read-only.
+  Current scope/config/model/index/tokenizer/policy identity must remain valid.
+- Check and preview enforce current configured collections and egress for every
+  scope/evidence/lineage source, including same-index inline requests.
+- Missing/invalid inputs are errors, never empty successful context.
+
+## Local files
+
+CLI: gno context compiled preview --capsule FILE --budget N [--bytes N]
+CLI: gno context compiled compile --capsule FILE --budget N --output NAME.gno-context.md
+CLI: gno context compiled check NAME.gno-context.md [--capsule FILE]
+CLI: gno context compiled refresh NAME.gno-context.md --capsule-output FILE.gno-context.capsule.json
+
+Compile requires a new output. The private adjacent sidecar records the explicit
+Capsule path, output digest, renderer settings and format. Refresh checks the
+owned output digest, rebuilds via the existing Capsule request, then rechecks
+source/policy before atomic replacement. Unexpected manual edits conflict.
+A no-change refresh is a verified no-op. Missing companions are unverifiable.
+File output forbids symlink traversal and refuses unowned destinations.
+Refresh must preflight the explicitly selected Capsule destination before
+publishing; failure preserves the prior complete artifact bytes.
+
+Check exit codes: 0 current, 3 stale, 4 conflict, 2 unverifiable.
+Other invalid command input uses existing validation exit1.
+Existing gno context check retains its unrelated configuration contract.
+
+## Remote and browser
+
+MCP: gno_context_compiled_preview and gno_context_compiled_check, read-only,
+inline inputs only. REST: POST /api/context/compiled/preview and
+POST /api/context/compiled/check with the same inputs. No remote file writes.
+Local SDK exposes preview/check plus compile/check-file/refresh-file helpers.
+
+Web UI previews verified bytes, exact cost, citations and omitted facets,
+checks supplied artifact bytes, and downloads the server-produced Markdown.
+Local file refresh is a CLI recipe, never a server path submission.
+
+Generated _.gno-context._ paths and recognized compiled artifact/sidecar content
+are excluded from ingestion, including renamed copies. Intentional indexing of
+compiled context is not supported in this version.

package/spec/mcp.md

@@ -153,7 +153,7 @@ the resident gateway applies one profile to every connected client.
 
 | Profile          | Without `--enable-write`                                                                              | With `--enable-write`                                   |
 | ---------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| `full` (default) | Every read tool below (34)                                                                            | Every read tool plus every write tool (53)              |
+| `full` (default) | Every read tool below (37)                                                                            | Every read tool plus every write tool (59)              |
 | `core`           | `gno_query`, `gno_search`, `gno_get`, `gno_multi_get`, `gno_context`, `gno_changes`, `gno_recall` (7) | The 7 read tools plus `gno_capture`, `gno_remember` (9) |
 
 Both lists are exact: `core` advertises nothing else, and `full` is byte-for-byte
@@ -232,6 +232,10 @@ the core memory service acquires the same `.mcp-write.lock` lease for every
 memory write, so an MCP remember and a CLI writer serialise on one lease. A
 lease that stays busy past the wait window returns `MEMORY_WRITE_LEASE_BUSY`.
 
+With a `requestId`, `gno_capture` and `gno_remember` admit the request under
+this same lease; there is no second lock. A request whose earlier attempt
+still holds the lease past the wait window returns `REQUEST_PENDING`.
+
 ### Resident Streamable HTTP boundary
 
 `gno serve` and `gno daemon` mount the same stateful MCP surface at `/mcp`.
@@ -1531,6 +1535,10 @@ Create a new document in a collection (write-enabled).
         "capturedAt": { "type": "string", "format": "date-time" },
         "externalId": { "type": "string" }
       }
+    },
+    "requestId": {
+      "type": "string",
+      "description": "Optional caller request ID (1-128 of A-Z a-z 0-9 . _ : -). Reuse the same ID when retrying the same write after a lost response; a new intent needs a new ID"
     }
   },
   "required": ["collection"]
@@ -1585,6 +1593,13 @@ Create a new document in a collection (write-enabled).
   writing
 - Writes run under the MCP write lock and are only registered when the server
   starts with `--enable-write` or `GNO_MCP_ENABLE_WRITE=1`
+- `requestId` (optional) makes a retry of the same call safe; look it up with
+  [`gno_request_status`](#gno_request_status). Semantics:
+  `docs/guides/retries-and-request-ids.md`
+- With a `requestId`, the result adds
+  `request: { requestId, status: "committed", replayed, committedAt }` and the
+  text output adds `Request: <id> committed` (`(replayed)` on a replay). The
+  field is absent when no `requestId` was sent
 
 **Output Schema:** `gno://schemas/mcp-capture-result@1.0`, compatible with the
 shared `gno://schemas/capture-receipt@1.0` contract.
@@ -1651,6 +1666,10 @@ file edits update existing notes, `gno_remember` upserts a fact.
     "source": {
       "type": "string",
       "description": "Free-text evidence for the fact"
+    },
+    "requestId": {
+      "type": "string",
+      "description": "Optional caller request ID (1-128 of A-Z a-z 0-9 . _ : -). Reuse the same ID when retrying the same write after a lost response; a new intent needs a new ID"
     }
   },
   "required": ["text", "collection", "scopes"]
@@ -1668,6 +1687,9 @@ file edits update existing notes, `gno_remember` upserts a fact.
   searchable)
 - `matching` — `mode` (`semantic` | `lexical`), `threshold`, and
   `semanticUnavailable` when lexical matching was used
+- `request` — present on `existing`, `added`, and `superseded` results when a
+  `requestId` was sent: `{ requestId, status: "committed", replayed,
+committedAt }`
 
 **Notes:**
 
@@ -1682,6 +1704,10 @@ file edits update existing notes, `gno_remember` upserts a fact.
 - The core service holds the shared write lease for the write and lexical
   sync; the MCP adapter takes no lock of its own
 - Identity mapping is the same as `gno_recall`
+- `requestId` requires `decision` (`add` or `supersede`); a candidates-only
+  call with a `requestId` returns `REQUEST_ID_INVALID`. `caller`, `session`,
+  and the MCP session are not part of the request identity. Semantics:
+  `docs/guides/retries-and-request-ids.md`
 - Annotations: `readOnlyHint: false`, `destructiveHint: false`,
   `idempotentHint: false`
 
@@ -1693,10 +1719,178 @@ file edits update existing notes, `gno_remember` upserts a fact.
 `MEMORY_PREDECESSOR_NOT_FOUND`, `MEMORY_PREDECESSOR_HASH_MISMATCH`,
 `MEMORY_SUPERSEDE_CONFLICT`, `MEMORY_FENCED_REPLAY`, `MEMORY_FENCED_DERIVED`,
 `MEMORY_WRITE_LEASE_BUSY`, `MEMORY_SYNC_FAILED`,
-`MEMORY_SUPERSEDE_PROJECTION_FAILED`, `MEMORY_QUERY_FAILED`.
+`MEMORY_SUPERSEDE_PROJECTION_FAILED`, `MEMORY_QUERY_FAILED`, and the
+`REQUEST_*` codes listed under [`gno_request_status`](#gno_request_status).
+
+---
+
+### gno_request_status
+
+Look up a `requestId` sent with `gno_capture` or `gno_remember` before retrying
+the write (write-enabled server).
+
+The tool is read-only but registered only when the server starts with
+`--enable-write` (or `GNO_MCP_ENABLE_WRITE=1`), and only on the `full` tool
+profile; `core` does not advertise it.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "requestId": {
+      "type": "string",
+      "description": "Request ID previously sent with gno_capture or gno_remember"
+    }
+  },
+  "required": ["requestId"]
+}
+```
+
+**Response (`structuredContent`):** `gno://schemas/request-status@1.0`
+
+```json
+{
+  "requestId": "0f8e5c1a-3c1e-4d0b-9a57-2f4f3b8f2c11",
+  "status": "committed",
+  "operation": "capture",
+  "createdAt": "2026-09-24T08:00:00.000Z",
+  "updatedAt": "2026-09-24T08:00:00.120Z",
+  "result": {
+    "uri": "gno://notes/inbox/2026-09-24/capture-3f9c.md",
+    "docid": "#a1b2c3",
+    "contentHash": "<sha256>"
+  }
+}
+```
+
+- `status`: `pending` | `committed` | `expired` | `not_found`.
+- `operation`: `capture` | `remember` | `document.update`. `result` appears
+  only for `committed` and carries `uri`, `docid`, and `contentHash` (or
+  `sourceHash` for a document update). Never note or fact content. A
+  `not_found` result has only `requestId` and `status`.
+- Text output: `Request:`, `Status:`, and, when present, `Operation:`,
+  `Updated:`, `URI:` lines.
+
+**Namespaces:** stdio uses the local-owner namespace shared with the CLI, SDK,
+and `gno serve` REST; resident Streamable HTTP uses the authorized identity
+(loopback, or the configured bearer token), not the MCP session. Visibility
+and token-rotation rules: `docs/guides/retries-and-request-ids.md`.
+
+**Annotations:** `readOnlyHint: true`, `destructiveHint: false`,
+`idempotentHint: true`, `openWorldHint: false`.
+
+**Request error codes** (on `gno_capture`, `gno_remember`, and this tool; tool
+error text `CODE: message`, `structuredContent.error` = `CODE`):
+`REQUEST_ID_INVALID`, `REQUEST_ID_CONFLICT`, `REQUEST_EXPIRED`,
+`REQUEST_PENDING`, `REQUEST_RECOVERY_CONFLICT`, `REQUEST_CAPACITY_EXHAUSTED`,
+`REQUEST_LEDGER_UNAVAILABLE`. Meanings:
+`docs/guides/retries-and-request-ids.md#errors`.
 
 ---
 
+### gno_sessions_status
+
+Read-only status of a session-archive server (a server started with the
+dedicated archive `--config` and `--index`). Registered with the `full`
+profile only; not part of `core`.
+
+**Input Schema:** `{}` (no arguments).
+
+**Output:** the shared `sessions-status` schema
+(`spec/output-schemas/sessions-status.schema.json`): archive collections with
+thread counts and, per owner-registered source, its ID, harness, destination
+collection, availability, unit counts (complete, incomplete, failed,
+pending), `sourceUnavailable`, `staleParser` and last import time, and the
+`automation` block (daemon state, per-profile state, hook and schedule
+switches, pending and running work, last run, last success, next due time,
+recovery action). The result contains no host paths.
+
+**Errors:** `SESSIONS_NOT_CONFIGURED` when the server's config has no
+`sessions` block.
+
+### gno_sessions_import
+
+Manually import one owner-registered session source into the archive and sync
+the changed archive files (write-enabled; `full` profile only). There is no
+MCP discovery tool: remote clients never learn host directories.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceId"],
+  "properties": {
+    "sourceId": {
+      "type": "string",
+      "description": "ID of an owner-registered session source (see gno_sessions_status)"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "description": "Parse and report without writing archive or index state"
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100000,
+      "description": "Maximum changed units processed this call; the rest are deferred"
+    }
+  }
+}
+```
+
+Unknown keys (for example `paths`) are rejected: MCP imports name a
+registered source ID only.
+
+**Output:** the shared `sessions-import-receipt` schema. Partial imports
+(`status: "partial"`) stay visible and are retried by the next call; the
+receipt carries no host paths or session content.
+
+Registered only with `--enable-write` (like `gno_capture` and
+`gno_remember`); without it the tool is not advertised. A dispatch while
+writes are disabled returns `WRITE_DISABLED`.
+
+### gno_sessions_automation_run
+
+Run one owner-configured automation profile now through the manual importer
+and record the outcome in automation status (write-enabled; `full` profile
+only). It cannot enable hooks or schedules, add sources, or change
+destinations; those stay local-owner operations.
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["profileId"],
+  "properties": {
+    "profileId": {
+      "type": "string",
+      "description": "ID of an owner-configured automation profile (see gno_sessions_status)"
+    }
+  }
+}
+```
+
+**Output:** the shared `sessions-automation-run` schema
+(`spec/output-schemas/sessions-automation-run.schema.json`): `ran`,
+`outcome` (`complete`, `up_to_date`, `partial`, `failed`, or `not_started`),
+`reason`, `pending`, and one `sessions-import-receipt` per source. No host
+paths or session content.
+
+**Errors:** `SESSIONS_UNKNOWN_PROFILE`, `SESSIONS_NOT_CONFIGURED`,
+`WRITE_DISABLED`; unknown keys are rejected.
+
+**Errors:** `SESSIONS_UNKNOWN_SOURCE`, `SESSIONS_SOURCE_UNAVAILABLE`,
+`SESSIONS_UNKNOWN_COLLECTION`, `SESSIONS_INVALID_INPUT`,
+`SESSIONS_NOT_CONFIGURED`; `SESSIONS_BUSY` when another import holds the
+archive lock; `SESSIONS_RUNTIME_FAILURE` (fixed, path-free message) for filesystem or
+index failures.
+
 ### gno_list_tags
 
 List all tags with document counts.
@@ -2793,6 +2987,8 @@ Resource errors use standard MCP error responses.
 - `MEMORY_*` — Memory contract errors from `gno_recall` / `gno_remember`;
   the stable code set is `MemoryErrorCode` in `src/core/memory.ts` and each
   tool section above lists the codes it returns
+- `REQUEST_*` — Request ID errors from `gno_capture`, `gno_remember`, and
+  `gno_request_status`; see [`gno_request_status`](#gno_request_status)
 
 ---
 
@@ -3066,3 +3262,28 @@ intersect caller scope before candidate limits and never expand authority.
 [metadata-predicate.schema.json](output-schemas/metadata-predicate.schema.json).
 See [Typed metadata filters](../docs/TYPED-METADATA.md) for exact membership,
 missing-field, invalid-document, and bounded-input semantics.
+
+### Retrieval coverage in text responses
+
+Search, vector search and query retain retrieval warnings in both text content
+and structured metadata, including zero-result responses. Incomplete or unknown
+metadata coverage does not establish absence. Preserve requested filters and
+scope; diagnose with the same filter when an expected target is known. Otherwise
+inspect the scoped coverage warning before claiming completeness.
+
+All typed-filter input descriptions carry this guidance. Verified Ask text
+also exposes the Capsule's metadata coverage warning. The compact agent
+protocol block and retrieval ladder remain unchanged.
+
+Coverage counts describe the scoped corpus, not the existence or metadata state of a particular matching document. With no known target, report the coverage limit instead of inventing a target or broadening the requested search.
+
+### Compiled context tools
+
+`gno_context_compiled_preview` accepts an inline Capsule, `budgetTokens` and
+optional `budgetBytes`; returns verified Markdown, digest, whole-output cost,
+coverage and omissions. `gno_context_compiled_check` accepts an inline Capsule
+and `markdown`; returns current/stale/conflict/unverifiable with bounded reasons.
+Both are read-only full-profile tools. Inputs are strict: no host paths, output
+destinations, or caller authorization fields. Current runtime scope and transport
+egress policy apply even to caller-supplied Capsules. See
+[compiled context](compiled-context.md) for exact shared schemas and bounds.

package/spec/output-schemas/capture-receipt.schema.json

@@ -129,6 +129,9 @@
         "overwritten",
         "conflict"
       ]
+    },
+    "request": {
+      "$ref": "gno://schemas/request-status@1.0#/$defs/requestReceipt"
     }
   },
   "definitions": {

package/spec/output-schemas/compiled-context-check.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["current", "stale", "conflict", "unverifiable"]
+    },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "digest": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "capsuleId": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": ["schemaVersion", "status", "reasons", "digest", "capsuleId"],
+  "additionalProperties": false
+}

package/spec/output-schemas/compiled-context-file.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["written", "unchanged"]
+    },
+    "outputPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "capsulePath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "sidecarPath": {
+      "type": "string",
+      "minLength": 1
+    },
+    "preview": {
+      "type": "object",
+      "properties": {
+        "schemaVersion": {
+          "type": "string",
+          "const": "1.0"
+        },
+        "rendererVersion": {
+          "type": "string",
+          "const": "1"
+        },
+        "capsuleId": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "markdown": {
+          "type": "string"
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "verificationDigest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "lineageDigest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "budget": {
+          "type": "object",
+          "properties": {
+            "requestedTokens": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 1000000
+            },
+            "requestedBytes": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 4194304
+            },
+            "usedTokens": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "usedBytes": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            },
+            "estimator": {
+              "type": "string",
+              "enum": ["unicode_conservative", "active_tokenizer"]
+            },
+            "tokenizerFingerprint": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          },
+          "required": [
+            "requestedTokens",
+            "requestedBytes",
+            "usedTokens",
+            "usedBytes",
+            "estimator",
+            "tokenizerFingerprint"
+          ],
+          "additionalProperties": false
+        },
+        "coverage": {
+          "type": "object",
+          "properties": {
+            "complete": {
+              "type": "boolean"
+            },
+            "coveredFacets": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "unresolvedFacets": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": ["complete", "coveredFacets", "unresolvedFacets"],
+          "additionalProperties": false
+        },
+        "evidenceIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "omissions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "evidenceId": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$"
+              },
+              "reason": {
+                "type": "string"
+              }
+            },
+            "required": ["evidenceId", "reason"],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "schemaVersion",
+        "rendererVersion",
+        "capsuleId",
+        "markdown",
+        "digest",
+        "verificationDigest",
+        "lineageDigest",
+        "budget",
+        "coverage",
+        "evidenceIds",
+        "omissions"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": ["status", "outputPath", "capsulePath", "sidecarPath", "preview"],
+  "additionalProperties": false
+}