scip-query 0.20.0 → 0.21.0

package/docs/CLI_JSON_OUTPUT.md

@@ -13,16 +13,54 @@ Public commands that support structured output share the same three options:
 --compact      With --json, minify the selected JSON form for a program.
 ```
 
-Use plain `--json` for an integration that depends on producer, schema,
+Three global controls select where that JSON is allowed to go:
+
+```text
+--agent-output        With --json, emit the bounded command-owned agent projection through cursor transport.
+--json-output <path>  With --json, atomically write the complete result and print only an integrity receipt.
+--raw-json            With --json, explicitly retain the legacy unpaged stdout stream.
+```
+
+Use plain `--json` for an existing integration that depends on producer, schema,
 coverage, evidence, arguments, or invocation options. Use `--json
 --result-only` for a program that needs just the result. Agents should run the
-ordinary command instead; pretty JSON remains structurally noisier than the
-human renderer. Both modifiers are rejected without `--json`.
-
-For example, `scip-query code <symbol>` prints source directly. Its result-only
-form contains only `file`, resolved `symbol`, `language`, a one-based `range`,
-and ordered `{ line, text }` rows. Resolution alternatives are added only when
-the requested symbol is ambiguous.
+ordinary command when possible; pretty JSON remains structurally noisier than
+the human renderer. When an agent genuinely needs JSON, it must add
+`--agent-output`. A program that needs the complete machine payload without
+placing it in model context should add `--json-output <path>`. The JSON
+modifiers are rejected without `--json`, and mutually exclusive transport
+controls are rejected instead of silently choosing one.
+
+An agent projection is the command-owned summary intended for model-facing
+clients. Its real-world units are the bounded `result` objects emitted after a
+caller selects `--agent-output`; it differs from the full command payload by
+retaining the identities, counts, coverage, recovery hints, and other facts
+the command declares material while omitting exhaustive machine-only rows.
+When a command has no specialized projection, scip-query keeps its ordinary
+result but applies the same hard transport fuse. A normal envelope marks the
+projected shape with `"resultProjection": "agent"`; absence of that additive
+field retains the full-result meaning. Result-only output carries no common
+envelope, so the explicit invocation flag identifies its projection.
+
+A JSON export receipt is a small record identifying one complete JSON file.
+Its real-world units are the `scip-query-json-export` objects printed after an
+atomic file replacement; it differs from the exported result by containing
+only the absolute path, byte count, and SHA-256 digest needed to locate and
+verify those bytes. Exported files use mode `0600`, become visible old-or-new
+rather than partially written, and are limited to a 4,096-byte resolved path,
+32 million characters, and 64 MiB.
+
+For example, one exact `scip-query code <selector>` prints source directly. Its
+single-result result-only form contains only `file`, resolved `symbol`,
+`language`, a one-based `range`, and ordered `{ line, text }` rows. With several
+selectors, an exact-file export surface, or ambiguity, result-only reports each
+selector's status, sources, range or file coverage, omitted-definition ledger,
+candidates, and literal values. A line-range selector includes the exact
+requested lines plus statically attributed same-file callable definitions and
+states the dynamic-call limit. An exact-file export surface contains exported
+definitions—or top-level definitions when no explicit export surface
+exists—and their same-file referenced definitions; `--members all` is the
+explicit whole-file form. Ambiguity never silently selects one candidate.
 
 ## Stable JSON envelope
 
@@ -39,10 +77,63 @@ The current envelope is schema version 1:
 {
   "kind": "scip-query-result",
   "schemaVersion": 1,
-  "producer": { "name": "scip-query", "version": "0.20.0" },
+  "producer": { "name": "scip-query", "version": "0.21.0" },
   "command": "refs",
+  "operationRole": "repository-observation",
   "resultSchemaVersion": 1,
   "evidence": "graph-fact",
+  "evidenceContext": {
+    "schemaVersion": 1,
+    "operationRole": "repository-observation",
+    "receipt": {
+      "schemaVersion": 2,
+      "observedAt": "2026-07-30T12:00:00.000Z",
+      "facts": {
+        "collaborationDomain": {
+          "schemaVersion": 1,
+          "canonicalizationVersion": 1,
+          "hashAlgorithm": "sha256",
+          "projection": { "name": "scip-query:collaboration-domain", "version": 1 },
+          "digest": "<64 lowercase hex characters>"
+        },
+        "index": {
+          "generation": {
+            "schemaVersion": 1,
+            "canonicalizationVersion": 1,
+            "hashAlgorithm": "sha256",
+            "projection": { "name": "scip-query:index-generation", "version": 1 },
+            "digest": "<64 lowercase hex characters>"
+          },
+          "source": "immutable"
+        }
+      },
+      "observedSources": [{ "kind": "index-generation" }],
+      "stabilityProofs": [{ "source": "index-generation", "kind": "immutable" }]
+    },
+    "analysisManifest": {
+      "schemaVersion": 1,
+      "evidence": "graph-fact",
+      "coverage": {},
+      "claimQualification": {
+        "schemaVersion": 1,
+        "origin": "compiler-graph",
+        "coverage": { "state": "complete", "returned": 1, "totalKnown": true, "total": 1, "omitted": 0 },
+        "producerValidation": { "status": "not-evaluated" },
+        "stateAuthority": {
+          "policyVersion": 1,
+          "authority": "advisory",
+          "requiredRelationships": ["collaborationDomain", "wholeContent", "observationStability"],
+          "reasons": ["wholeContent:unknown"]
+        },
+        "repositoryPolicy": {
+          "policyId": "scip-query:unresolved-repository-policy",
+          "policyVersion": 1,
+          "permission": "not-established",
+          "reasons": ["No repository action policy was supplied for this claim."]
+        }
+      }
+    }
+  },
   "args": ["login"],
   "options": { "json": true },
   "result": {},
@@ -56,6 +147,79 @@ the transport version. `producer.version` is the installed package version
 that emitted the record. `kind` prevents a consumer from mistaking another
 JSON protocol for a CLI result.
 
+`operationRole` names the effect of the parsed invocation, independently from
+how its result was derived. The closed roles distinguish repository
+observation, repository preview, mutation, combined mutation/observation,
+environment observation, and tool information. A command with several modes
+selects its role from parsed arguments and options before its handler runs.
+
+Repository observations, previews, and composite operations attach
+`evidenceContext` automatically at the shared renderer when they hold an open
+database. Pure mutations and environment/tool-information results do not
+inherit repository-observation authority merely because they emit JSON. The
+context repeats the selected operation role so it remains self-contained; the
+decoder rejects conflicting top-level and nested roles.
+
+The context's version-2 `receipt` records independent facts about the
+collaboration domain, workspace instance, whole repository content, relevant
+inputs, index inputs, immutable generation, observed sources, and the
+mechanism—if any—that kept each source fixed. Every content-derived identity
+names its projection and projection version, canonicalization version, and
+hash algorithm. A missing fact means unknown; it is never inferred from a
+neighboring identity.
+
+The example identifies the immutable index generation the query actually
+held, but it does not contain a fixed repository snapshot or an index-input
+alignment proof. Product policy therefore keeps it advisory for completion
+even though the index source itself is immutable. `analysisManifest`
+separately records how the result was produced and how much was examined.
+
+`claimQualification` keeps five questions independent. `origin` identifies
+the method that produced support for the result. `coverage` identifies how
+much of the relevant answer the invocation enumerated. `producerValidation`
+reports performance against a named versioned corpus when such certification
+exists. `stateAuthority` is product policy derived from the receipt rather
+than a producer-authored strength label. `repositoryPolicy.permission` states
+what response the repository permits. A strong value in one field never
+upgrades another.
+
+For a command whose aggregate origin is `mixed`, `families` binds a stable
+result selector either to one fixed origin or to an existing per-row
+provenance field. This retains the actual origins of findings and result
+families instead of forcing a consumer to treat every row as generically
+mixed. The legacy top-level and manifest `evidence` values remain during the
+additive compatibility window.
+
+When a producer actually reads repository bytes through the fixed-snapshot
+boundary, its receipt may additionally contain:
+
+- `facts.wholeContent`, derived from the immutable Git tree plus captured
+  dirty, untracked, declared-ignored, deletion, symlink, and executable-mode
+  overlays;
+- one `facts.relevantInputs` entry for `scip-query:index-inputs`;
+- `facts.index.inputs`, derived from the versioned project-input fingerprint
+  already persisted with the held generation; and
+- a `repository-snapshot` observed source with a `fixed-snapshot` stability
+  proof.
+
+Equal `scip-query:index-inputs` projections establish exact alignment between
+that snapshot and the immutable generation. A capture race, unsupported input,
+or producer that never read repository bytes leaves the snapshot facts absent;
+absence remains `unknown`. A producer does not gain whole-content authority
+merely because another command could have taken a snapshot.
+
+Version-1 receipts remain readable as legacy provenance. Their path-derived
+project identity and mixed worktree hash are not relabeled as collaboration,
+workspace, or content identities. Only a legacy index-generation identity can
+be compared as the same legacy fact; unproved v2 relationships remain
+`unknown`.
+
+The existing top-level `evidence`, `analysisBudget`, and `coverage` fields
+remain during the additive migration so older tolerant consumers continue to
+work. New consumers may read the nested context. `--result-only` deliberately
+omits the common envelope, including this context, and therefore cannot stand
+alone as completion evidence.
+
 The machine-readable schema is
 [`schemas/cli-json-envelope.schema.json`](schemas/cli-json-envelope.schema.json).
 The public `scip-query/runtime` export provides
@@ -80,44 +244,45 @@ Every command accepts these global options:
 ```
 
 Run commands normally without choosing a page size. Human output larger than
-12,000 characters is paged automatically as ordinary multiline text, not as a
+6,500 characters is paged automatically as ordinary multiline text, not as a
 JSON object. Each incomplete page prints one exact continuation command after
 its content. Agents must run that command unchanged until the output-complete
-marker. Supplying `--output-page-size` changes the character budget; it does
-not select JSON. The value counts rendered JavaScript string characters, not
-rows, results, model tokens, or bytes. If the complete result fits, scip-query
-returns it unchanged and removes the temporary snapshot; a page wrapper exists
-only when more content remains. Partial human pages end at the last complete
-line within that budget whenever one exists, so the next page begins with its
-own heading or source line number; a single line longer than the budget is the
-only case that requires a character-boundary split. Do not pipe scip-query
-through `head`, `tail`, or a line-range `sed`; those programs discard output
-without creating a resumable position.
+marker. Supplying `--output-page-size` changes the maximum character budget; it
+does not select JSON. A page may be smaller so its UTF-8 content plus the actual
+continuation wrapper stays within the 8,000-byte client-safe budget. The option
+does not count rows, results, or model tokens. If the complete result fits,
+scip-query returns it unchanged and removes the temporary snapshot; a page
+wrapper exists only when more content remains. Partial human pages end at the
+last complete line within both budgets whenever one exists, so the next page
+begins with its own heading or source line number; a single line longer than a
+budget is the only case that requires a character-boundary split. Do not pipe
+scip-query through `head`, `tail`, or a line-range `sed`; those programs discard
+output without creating a resumable position.
 
 Default `--json` output remains the ordinary, additively extensible
 `scip-query-result` envelope. When that envelope exceeds
-12,000 characters, scip-query writes an early stderr warning containing the
+8,000 UTF-8 bytes, scip-query writes an early stderr warning containing the
 exact command that opts into output pages. The paged command returns:
 
 ```json
 {
   "kind": "scip-query-output-page",
   "schemaVersion": 1,
-  "producer": { "name": "scip-query", "version": "0.20.0" },
+  "producer": { "name": "scip-query", "version": "0.21.0" },
   "command": "architecture",
   "contentType": "application/json",
   "agentInstruction": "INCOMPLETE EVIDENCE: do not draw conclusions or report completion from this partial page. Run page.continuation.command exactly, then repeat until page.complete is true.",
   "page": {
     "offset": 0,
-    "returnedCharacters": 12000,
+    "returnedCharacters": 3500,
     "totalCharacters": 48152,
-    "omittedCharacters": 36152,
-    "remainingCharacters": 36152,
+    "omittedCharacters": 44652,
+    "remainingCharacters": 44652,
     "complete": false,
     "outputHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "continuation": {
       "cursor": "<opaque cursor>",
-      "command": "scip-query architecture --json --output-page-size 12000 --output-cursor <opaque cursor>"
+      "command": "scip-query architecture --json --output-page-size 6500 --output-cursor <opaque cursor>"
     }
   },
   "content": "{\n  \"kind\": \"scip-query-result\",\n  ..."
@@ -138,7 +303,17 @@ A genuinely partial JSON page must carry `content` as a string because an
 arbitrary character boundary is not necessarily valid nested JSON. Run the
 emitted continuation exactly until completion. Normal agent work should use
 human output, where partial pages remain multiline text rather than a JSON
-string.
+string. Model-facing JSON must use `--agent-output`; that mode selects the
+command's bounded projection and automatically enables cursor transport even
+when the caller did not provide `--output-page-size`.
+
+Agent output is capped at 16 JSON content pages, currently 56,000 rendered
+characters. Exceeding that cap fails before any partial result reaches stdout
+and directs the caller to narrow the query or use `--json-output <path>`.
+This fuse prevents a technically resumable result from consuming an
+unbounded number of model turns. It does not weaken query coverage: the
+projection must still report its own returned, total, omitted, and recovery
+facts.
 
 One snapshot is bounded to 32 million characters, 64 MiB, and 32,768 pages.
 The per-user pool is bounded to 32 snapshots and 256 MiB under atomic
@@ -179,12 +354,15 @@ cursor is rejected after the index generation changes.
 
 The machine-readable page schema is
 [`schemas/cli-output-page.schema.json`](schemas/cli-output-page.schema.json).
+The bounded export-receipt schema is
+[`schemas/cli-json-export-receipt.schema.json`](schemas/cli-json-export-receipt.schema.json).
 Page sizes range from 256 through 100,000 characters and cursors are limited
 to 4,096 characters. The first paged invocation streams the complete output
 to a mode-`0600` snapshot beneath a current-user mode-`0700` temporary
 directory while retaining only the requested page in memory. Snapshots expire
-after one hour and are removed after the final page. Pagination imposes no
-arbitrary total-output ceiling and does not silently discard later pages;
+after one hour and are removed after the final page. Ordinary explicit
+pagination keeps the existing 32-million-character snapshot ceiling and does
+not silently discard later pages. Agent output adds the smaller 16-page fuse;
 command-level result budgets still apply and report their own completeness.
 
 ## Compatibility policy