# Gemel — Agent Protocol
Status: **Normative.** Version 1.0.0. Query surface schema: `gemel.query.v1`.
Implementation status: §5.1–§5.10 (status, why, claims, evidence, residuals, attempts,
trajectory, checkpoint, context, reconcile), §5.14–§5.18 (log, show, index, semantic,
next, policy), §6 (progressive disclosure), §8 (context bundles), §9
(handoff/checkpoint/readiness), §10 (execution boundary via the Phase 8 court runner),
and §11–§13 (session, errors, determinism) are **implemented** (Phases 1–8).
§5.11–§5.13 (multidimensional `diff`, `impact`, `context-diff`), §5.19 (`release`),
and the standalone §7 `evidence ingest` endpoint are **specified here but not yet
implemented** — do not treat them as available. They are the Phase 9 delivery contract
(SPECIFICATION.md §10); this header flips to “implemented” when Phase 9 exits.
This document defines the machine-readable query surface: response envelope, JSON
object mapping, pagination, token budgets, every query endpoint with its schema,
progressive disclosure levels, the evidence-ingestion protocol, context manifest
construction, handoff/checkpoint generation, readiness computation, and the FRF
boundary.
Every important Gemel query exists in four forms: human CLI output, machine JSON
(`gemel … --json`), library API, and (Phase 6+) a lightweight agent protocol. Agents
never scrape decorative terminal prose.
---
## 1. Principles
1. **Deterministic.** Identical (repository, query, parameters) ⇒ identical response
bytes. No wall-clock timestamps in responses unless explicitly requested; no
random ordering; defined tie-breaks.
2. **Versioned.** Every response declares `"schema": "gemel.query.v1"`.
3. **Bounded.** Every response is size-limited; expansions are explicit.
4. **Paginated.** Stable opaque cursors.
5. **Explicit omission.** Anything not returned that could be relevant is listed in
`omitted[]` with a reason.
6. **Explicit uncertainty.** Uncertainty is reported, never silently resolved.
7. **ID-first.** Responses return canonical identities; payloads are expandable on
demand (progressive disclosure, §6).
8. **Budget-aware.** Context endpoints honor token budgets.
---
## 2. Response Envelope
```json
{
"schema": "gemel.query.v1",
"request": {"command": "status", "params": {...}},
"pagination": {"has_more": false, "next_cursor": null, "count": 12},
"result": {...},
"omitted": [{"class": "evidence", "count": 812, "reason": "budget"}],
"uncertainty": [{"class": "evidence_freshness", "ids": ["evidence.ab12…"], "reason": "no evaluated-state anchor"}]
}
```
- `omitted` and `uncertainty` are mandatory arrays (possibly empty).
- Ordering convention: any array of objects is sorted by canonical identity (hex
string), unless the endpoint documents another deterministic order. Strings sort by
byte value. `null` is never emitted for absent optional fields (§3.1).
---
## 3. JSON Object Mapping
### 3.1 Canonical form
```json
{
"family": "change",
"schemever": 1,
"body": [
{"tag": 1, "name": "summary", "value": "Fix parser compatibility problem"},
{"tag": 6, "name": "producer", "value": "producer.9f3a…"}
]
}
```
- `name` is an annotation; `tag` is authoritative.
- Value encodings: UINT/SINT → decimal strings (exact, no precision loss); BOOL →
JSON boolean; BYTES → lowercase hex; STRING → JSON string; GID → textual identity;
RECORD → array of field objects (as above); ARRAY → JSON array.
- Optional absent fields are omitted; `null` is never emitted.
### 3.2 Compact form
Endpoints may return a compact form (`"form": "compact"`) with named fields for the
most useful subsets (e.g., `status` summaries). Compact forms are documented per
endpoint; the canonical form is always available via `gemel show <id> --json`.
### 3.3 Identity and reference conventions
- All identities are textual (§OBJECT_MODEL 3.1).
- A reference object: `{"id": "change.ab12…", "family": "change", "summary": "…"}`
(summary included when cheap; otherwise omitted).
---
## 4. Pagination and Budgets
### 4.1 Pagination
- Request: `{"limit": 100, "cursor": "<opaque>"}`. Default limit 100, max 1000.
- Cursor: base64url of `{"anchor": "<last id>", "offset": <n>, "order": "<asc|desc>"}`.
Cursors are stable while the repository is unchanged; they are invalidated (never
misdirected) by GC of referenced objects — the response then restarts with an
explicit `notice`.
### 4.2 Token budgets
Context endpoints accept `budget` (tokens) or `budget_bytes`. Semantics:
1. Results are computed as ID-level references first (level L0, §6).
2. Expansion proceeds in deterministic order (§6.2) until the budget is exhausted.
3. The response reports what was expanded and what was omitted with reason `budget`.
4. Budgets are enforced server-side; clients cannot request more than the policy
maximum (`config.limits`; THREAT_MODEL.md §5).
---
## 5. Query Endpoints
All endpoints: `gemel <command> [args] --json [--limit N] [--cursor C]`.
### 5.1 `status`
Human default: §50 of the brief (one screen). JSON:
```json
{
"schema": "gemel.query.v1",
"request": {"command": "status", "params": {}},
"result": {
"trajectory": {"id": "trajectory.…", "summary": "Implement DNS compression"},
"intent": {"id": "intent.…", "summary": "…"},
"state": {"id": "state.…"},
"changed": {"files": 4, "semantic_entities": 12},
"claims": {"proposed": 8, "supported": 6, "partially_supported": 0,
"contradicted": 1, "unverified": 1, "stale": 0, "superseded": 0},
"evidence": [
{"platform": "linux", "arch": "x86_64", "result": "pass"},
{"platform": "linux", "arch": "aarch64", "result": "pass"},
{"platform": "freebsd", "arch": "x86_64", "result": "not_run"},
{"oracle": "bind", "match_rate": 0.9998}
],
"residuals": [{"id": "residual.…", "summary": "pointer-loop discrepancy",
"severity": "high", "disposition": "open"}],
"previous_attempts": 2,
"readiness": {"verdict": "NOT_READY", "reasons": [
"open residual residual.… (blocking)",
"contradicted claim claim.…",
"missing verification: freebsd/x86_64" ]}
},
"omitted": [],
"uncertainty": []
}
```
`--verbose` adds per-claim status detail, evidence scopes, and the readiness algorithm
inputs (§9.3).
### 5.2 `why <subject>`
Subject = canonical path, identity, or entity name. Traverses (brief §14):
```text
current code → Change → Intent → Claim → Evidence → Residual → Decision
```
```json
{
"schema": "gemel.query.v1",
"request": {"command": "why", "params": {"subject": "src/name.rs:417"}},
"result": {
"subject": "src/name.rs:417",
"current_identity": {"path": "src/dns/name/parser.rs:82",
"lineage": "explicit|similarity|unknown", "confidence": "high"},
"introduced_by": {
"change": {"id": "change.…", "summary": "Match upstream pointer-loop behavior"},
"intent": {"id": "intent.…", "summary": "Implement pointer-loop detection matching upstream behavior"},
"claim": {"id": "claim.…", "predicate": "BIND 9.20 compatibility",
"status": "SUPPORTED"},
"evidence": [{"id": "evidence.…", "kind": "oracle_comparison", "outcome": "match"},
{"id": "evidence.…", "kind": "court_receipt", "outcome": "pass"}],
"residuals": [{"id": "residual.…", "summary": "BIND 9.11 differs",
"disposition": "acknowledged"}],
"decision": {"id": "reconciliation.…", "summary": "Target BIND 9.20 behavior"}
},
"previous_approaches": [
{"trajectory": "trajectory.…", "outcome": "rejected",
"reason": "strict RFC behavior diverged in 17 oracle cases",
"evidence": ["evidence.…"]}
]
},
"omitted": [],
"uncertainty": []
}
```
The traversal is a bounded typed query (indexes: change-by-subject, claim-by-subject,
claim→evidence edges), never a prose search.
Phase 5: when the subject resolves to a semantic entity, `why` walks the entity's
**lineage aliases** (current and ancestor file paths, module paths, names) so a moved
or renamed entity surfaces every change that touched its ancestors; the report
carries the resolved entity under `semantic` (§5.16).
### 5.3 `claims [--subject X] [--status S]`
```json
{"result": {"claims": [
{"id": "claim.…", "predicate": "parser accepts all valid RFC inputs",
"predicate_kind": "correctness", "status": "SUPPORTED",
"supporting": ["evidence.…"], "contradicting": [], "stale": [],
"scope": "parser::decode_name",
"change": "change.…", "trajectory": "trajectory.…"}
]}}
```
Status derivation per §OBJECT_MODEL 8.1, always with `basis`.
### 5.4 `evidence <id>`
Canonical object (form `canonical`) or compact with derived freshness:
```json
{"result": {"id": "evidence.…", "kind": "oracle_comparison",
"subject": "decode_name", "outcome": "mismatch",
"evaluated_state": "state.…",
"freshness": {"status": "MAY_REQUIRE_REFRESH",
"caused_by": ["change.…"]},
"reproduction": {"replayable": true, "inputs_present": true, "policy_required": false}}}
```
### 5.5 `residuals [--subject X] [--disposition open]`
```json
{"result": {"residuals": [
{"id": "residual.…", "summary": "semantic divergence", "classification":
"semantic_divergence", "severity": "high", "disposition": "open",
"persistence": {"descendant_changes": 7},
"scope": {"intent": "intent.…", "paths": ["parser::decode_name"]},
"origin_evidence": "evidence.…",
"affected_claims": ["claim.…"], "affected_changes": ["change.…"]}
]}}
```
"Where does certainty end?" = `residuals --disposition open --order severity`.
### 5.6 `attempts <subject>`
Trajectories whose changes touch the subject, plus intent-sharing trajectories:
```json
{"result": {"attempts": [
{"trajectory": "trajectory.…", "intent": "intent.…", "outcome": "rejected",
"termination_reason": "FreeBSD race reproduced",
"evidence": ["evidence.…"], "residuals": ["residual.…"]},
{"trajectory": "trajectory.…", "outcome": "incomplete", "handoff": "…"}
]}}
```
### 5.7 `trajectory <id>`
```json
{"result": {"id": "trajectory.…", "intent": "intent.…", "base_state": "state.…",
"outcome": "incomplete",
"sequence": [{"change": "change.…", "summary": "…", "state": "state.…"}, …],
"evidence": ["evidence.…"], "residuals": ["residual.…"],
"handoff": {"summary": "…", "remaining": ["FreeBSD verification"],
"open_residuals": ["residual.…"],
"recommended_objects": ["change.…", "trajectory.…"]}}}
```
The sequence is the concatenation of `added_changes` along the chain (§OBJECT_MODEL
7.3), materialized by the query layer.
### 5.8 `checkpoint` (create/read)
`gemel checkpoint --json` generates from structured state (§9.2) and returns the
checkpoint object. Read returns the checkpoint with its referenced context pre-resolved
at level L1.
### 5.9 `context <subject> --for-intent I91 --budget 32000 --include residuals,claims,attempts`
See §6 for the full algorithm. Response is a bundle (§6.4):
```json
{"result": {"subject": "parser::decode_name", "intent": "intent.…",
"budget": {"tokens": 32000, "consumed": 28144, "remaining": 3856},
"bundle": {
"objects": [{"id": "…", "family": "…", "level": 1, "summary": "…"}, …],
"deduplicated": 41,
"expanded": {"claims": 3, "residuals": 2, "attempts": 2, "evidence": 5}
},
"next": {"expand": ["evidence.ab12…", "trajectory.ef56…"], "why": "budget"}}}
```
### 5.10 `reconcile --plan --json`
Dry-run plan for reconciling trajectories (no state mutation):
```json
{"result": {"plan": {
"inputs": ["trajectory.…", "trajectory.…"],
"textual_conflicts": [{"path": "src/name.rs", "changes": ["change.…", "change.…"]}],
"semantic_interactions": [
{"kind": "dependency", "certainty": "possible",
"detail": "serialize depends on invariant changed by normalize",
"subjects": ["change.…", "change.…"]}],
"claims": {"retained": ["claim.…"], "invalidated": ["claim.…"],
"verification_required": ["claim.…"]},
"resulting_state": "state.…",
"unresolved_residuals": ["residual.…"],
"rationale": "…"
}}}
```
### 5.11 `diff <A> <B> --semantic --claims --behavior --evidence --residuals --dependencies`
*Delivery: Phase 9 (SPECIFICATION.md §10). Not yet implemented; textual and `--semantic`
deltas exist today.*
Multidimensional delta (brief §23):
```json
{"result": {
"textual": {"files": {"changed": ["src/name.rs"], "added": [], "deleted": []}},
"behavioral": [{"entity": "decode_name", "delta": "rejects pointer cycles > 16"}],
"claims": {"added": ["claim.…"], "invalidated": ["claim.…"]},
"evidence": {"gained": [{"id": "evidence.…", "count": 1922, "kind": "oracle_comparison"}],
"invalidated": ["evidence.…"]},
"residuals": {"introduced": ["residual.…"], "resolved": ["residual.…", "residual.…"]},
"semantic_interactions": [{"subject": "serializer::emit", "certainty": "possible"}]
}}
```
### 5.12 `impact <change-id>`
*Delivery: Phase 9 (SPECIFICATION.md §10). Not yet implemented.*
Conservative impact (brief §33): objects potentially affected.
```json
{"result": {
"change": "change.…",
"touches": {"paths": ["src/name.rs"], "entities": ["normalize"]},
"may_require_refresh": [
{"evidence": "evidence.…", "supports": "claim.…", "rule": "path overlap"}],
"affected_claims": ["claim.…"],
"affected_residuals": ["residual.…"],
"verification_required": ["freebsd/x86_64"]
}}
```
### 5.13 `context-diff <run-a> <run-b>`
*Delivery: Phase 9 (SPECIFICATION.md §10). Not yet implemented.*
Compares two agent runs via their context manifests (brief §19):
```json
{"result": {
"seen_by_a_only": [{"class": "residual", "id": "residual.…"}],
"seen_by_b_only": [{"class": "external_artifact", "id": "blob.…"}],
"upstream_revision": {"a": "U18", "b": "U19"},
"instruction_digests_equal": false
}}
```
### 5.14 `log`, `show`
`log` lists changes/episodes/operations at the requested resolution (brief §3);
`show <id> --json` returns the canonical form (§3.1).
### 5.15 `index [--state <id>]`
Builds (or rebuilds) the semantic index of a state (default: the head state).
Deterministic: identical state bytes produce identical entity objects and the
identical index object; unchanged entities deduplicate by content identity.
The index is disposable — canonical objects + refs are truth, and deleting or
rebuilding the index never changes query answers (brief §2).
```json
{
"schema": "gemel.query.v1",
"request": {"command": "index", "params": {"state": "state.…"}},
"result": {
"state": "state.…",
"index": "semantic-index.…",
"entities": 12,
"files": 3,
"new": 5, "modified": 4, "moved": 2, "lineage_links": 6
},
"omitted": [],
"uncertainty": []
}
```
### 5.16 `semantic [<subject>]`
With a subject: resolves an entity by name, `path::name`, `file:line`, or
`semantic-entity` identity and returns its full description, including the
**explicit lineage** (`lineage_from`, `lineage_evidence`, `lineage_certainty`
entities (bounded).
```json
{
"schema": "gemel.query.v1",
"request": {"command": "semantic", "params": {"subject": "decode_name"}},
"result": {
"id": "semantic-entity.…",
"kind": "function",
"name": "decode_name",
"module_path": "crate::parser",
"full_path": "crate::parser::decode_name",
"file_path": "src/parser.rs",
"start_line": 1, "end_line": 3,
"signature": "pub fn decode_name(data: &[u8]) -> String",
"visibility": "public",
"lineage": {"from": "semantic-entity.…",
"evidence": "similarity:same-name-kind",
"certainty": "possible"},
"state": "state.…"
},
"omitted": [],
"uncertainty": []
}
```
### 5.17 `next`
Derives the next-step plan purely from durable engineering state (brief §57;
nothing is invented): pending change → `continue`; open residuals → `resolve`;
contradicted/partially-supported claims → `verify`; required-but-missing
verification (config matrix, §8) → `verify`; unindexed head state → `index`;
relevant failed attempts → `inspect`; stale exchange context → `reconcile`.
Every recommendation carries its derived rationale and a certainty
(`observed` for graph facts, `possible` for policy derivations).
```json
{
"schema": "gemel.query.v1",
"request": {"command": "next"},
"result": {
"intent": "intent.…",
"trajectory": {"name": "T1", "id": "trajectory.…"},
"state": "state.…",
"recommendations": [
{"kind": "resolve", "subject": "FreeBSD divergence",
"refs": ["residual.…"],
"rationale": "open residual: FreeBSD divergence",
"certainty": "observed"}
]
},
"omitted": [],
"uncertainty": []
}
```
### 5.18 `policy`
Shows the active required-verification matrix (config `required_verification`,
OBJECT_MODEL.md §6.21) and the gaps: required combinations with no supporting
evidence on the head change. Missing required verification makes readiness
`NOT_READY` (OBJECT_MODEL.md §8.4).
### 5.19 `release <trajectory> [--case <id>] [--name <string>]`
*Delivery: Phase 9 (SPECIFICATION.md §10). Not yet implemented.*
A **proof-carrying release** (brief §11, §24): publishes a `release` object binding a
user-facing name to a distributable state and carries the verification evidence that
supports the readiness claim — a release is not a label, it is a claim with its proof
in scope.
```json
{"result": {
"release": "release.…",
"name": "v0.4.2",
"state": "state.…",
"trajectories": ["trajectory.…"],
"cases": ["case.…"],
"readiness": "READY",
"readiness_evidence": ["evidence.…"],
"open_residuals": ["residual.…"],
"verification_scope": [{"platform": "linux", "arch": "x86_64", "outcome": "pass"}]
}}
```
The readiness claim is derived from the same policy machinery as `status`/`next`; the
response names the evidence objects that support it, so a consumer can decide whether
the proof is sufficient without trusting the label. A release is immutable; a new
release supersedes it without rewriting it.
---
## 6. Progressive Disclosure and Context Bundles
### 6.1 Levels
| L0 | identities only (ids, families, summaries absent) |
| L1 | + summaries (default for list endpoints) |
| L2 | + structured fields (predicates, outcomes, dispositions, scopes) |
| L3 | + full canonical objects and evidence payloads (blobs/logs) |
`context` requests default to L1 for referenced objects, L2 for directly relevant
claims/residuals, and never L3 without explicit `--include-l3`.
### 6.2 Deterministic expansion order
Within a budget: phase 1 = objects directly referencing the subject (changes,
claims); phase 2 = residuals affecting the subject (open first); phase 3 = previous
attempts (trajectories sharing intent or touching subject); phase 4 = evidence for the
included claims; phase 5 = context manifests of the relevant agent runs. Within a
phase: newest first (by `created_at` metadata when present, else 0), then ascending
gid. All ties break on gid ascending. Expansion stops at the budget; the remainder is
reported in `omitted`.
### 6.3 Deduplication
Objects already included by identity are never repeated (bundle reports
`deduplicated`). Identical evidence payloads referenced by multiple claims appear once.
### 6.4 Bundles
A context bundle is the concrete output of `context`: a deduplicated, budget-bounded
set of object references with levels, plus `next` expansion pointers. Bundles are
deterministic for identical inputs and may be cached by content hash.
---
## 7. Evidence Ingestion Protocol
*Delivery: the standalone `gemel evidence ingest` endpoint is Phase 9
(SPECIFICATION.md §10). Today, evidence is published through the change workflow
(`change finish --evidence`), the Phase 8 court runner, and the semantic indexer.*
`gemel evidence ingest` accepts a stable JSON document (schema `gemel.evidence.v1`):
```json
{
"schema": "gemel.evidence.v1",
"producer": "producer.…",
"kind": "court_receipt",
"subject": "parser::decode_name",
"command": "frf court run parser-decode-name --corpus dns-2024",
"inputs": [{"id": "state.…", "role": "evaluated_state"}],
"environment": "environment.…",
"tools": [{"name": "frf-court", "version": "1.2.0"}],
"result": {"outcome": "pass", "counts": {"passed": 99421, "failed": 0,
"skipped": 0, "total": 99421}},
"reproduction": {"replayable": true, "inputs_present": true, "policy_required": false},
"outputs": [{"id": "blob.…", "role": "court_log"}]
}
```
Three concepts are kept distinct (brief §38):
1. **tool ran** — the evidence object exists;
2. **result produced** — `result.outcome` and payloads;
3. **interpreted as evidence for Claim C** — the explicit `claim → evidence` edge
created by `gemel claim link C --evidence E`, a deliberate act by a producer.
Ingestion never auto-links claims; it validates references, computes the identity, and
publishes. Execution of reproduction instructions requires explicit policy
(§10; default `never_auto_execute`).
---
## 8. Context Manifest Construction
`context-manifest` objects are built from: source/documentation objects supplied,
claims/residuals included, previous trajectories considered, external artifacts, tool
outputs, policies in force, instruction + digest. Construction is deterministic from
The input list is normalized by id, preserving order. Manifests enable `context-diff`
(§5.13, Phase 9) and re-hydration: a later agent can request the exact objects a
previous run saw.
make `AgentRun.context_manifest` a content-addressed record of what an agent saw.
---
## 9. Handoff, Checkpoint, and Readiness Generation
### 9.1 Handoff
`trajectory.handoff` is machine-generated from repository state: `remaining` from the
trajectory's open residuals + incomplete verification scope; `open_residuals` from the
current residual set; `important_evidence` from evidence supporting the trajectory's
claims; `recommended_objects` from the impact frontier (objects whose evidence is
`MAY_REQUIRE_REFRESH`). Human text is allowed but the structured fields are the
contract.
### 9.2 Checkpoint
`gemel checkpoint` assembles: current intent, trajectory, state; open claims and
residuals; important evidence; recent decisions (head changes); relevant attempts;
continuation scope (impact frontier). All fields are references resolved to L1 in the
output.
### 9.3 Readiness
Deterministic function of:
1. open residuals with severity `blocking` ⇒ `NOT_READY`;
2. contradicted claims within the queried scope ⇒ `NOT_READY`;
3. required verification matrix (config) entries unsatisfied ⇒ `NOT_READY`
(each with the missing platform/config);
4. open residuals with severity ≤ `high` but acknowledged ⇒
`READY_WITH_RESIDUALS` (each listed);
5. unverified claims in scope ⇒ `READY_WITH_RESIDUALS` (listed);
6. otherwise `READY`.
Every verdict includes `reasons[]`; no verdict is produced without them.
---
## 10. FRF Integration Boundary
- Gemel references FRF courts, fixtures, comparators, normalizers, and receipts by
immutable identity (evidence kind `court_receipt`, tool records, fixture refs).
- Gemel never executes FRF or reproduction commands during ingestion, `status`,
sync, or a protocol session. The **court runner** (Phase 8; HOSTED.md §7) is the
single execution path: `gemel court <evidence-id>` re-executes the recorded
reproduction command under `config.execution_policy` (`never_auto_execute`
default, `policy_gated` requiring `--allow`, `allowlist` against
`.gemel/court.allowlist`), publishes the fresh observation as new evidence
(`court-runner` producer, outcome/exit_code, replayable reproduction record,
`evaluated_state` = head), and never rewrites the source evidence.
- FRF logic (courts, comparators, reproducibility semantics, residual analysis) is not
duplicated in Gemel; Gemel stores FRF artifacts and derives statuses from them.
- The `reconcile --plan` endpoint may flag `verification_required` scopes; actual runs
happen under policy.
---
## 11. Agent Protocol Session (Phase 7; brief §15.4)
`gemel protocol` is a bounded, line-delimited JSON session over stdin/stdout. It is a
**session framing around the query layer** — no parallel ontology: every request
routes to the same library queries as the CLI.
Request (one JSON object per line):
```json
{"id": 1, "query": "why", "params": {"subject": "decode_name"}}
```
Response (one JSON object per line):
```json
{"id": 1, "schema": "gemel.agent.v1", "result": {…}, "omitted": [], "uncertainty": []}
```
Errors carry stable codes (`invalid_request`, `query_failed`, `limit_exceeded`,
`internal`) — agents never parse prose. Queries: `status`, `next`, `why`, `semantic`,
`claims`, `evidence`, `residuals`, `attempts`, `context`, `log`, `index`. Bounds: 64
KiB request lines, 4 MiB responses; the session is stateless per request; EOF ends it;
nothing is executed during a session.
Network transports reuse this discipline as the sync session (Phase 8; HOSTED.md
§6): `list_refs`/`reachable`/`missing`/`update_refs` plus raw-`gemlpack`
`fetch`/`push`, bounded lines, packs, and id sets.
---
## 12. Error Semantics
```json
{
"schema": "gemel.query.v1",
"error": {
"code": "NOT_FOUND",
"message": "object not present: change.ab12… (pruned; tombstone: …)",
"ids": ["change.ab12…"]
}
}
```
Codes: `NOT_FOUND`, `INVALID_ARGUMENT`, `BUDGET_EXCEEDED`, `PAGINATION_INVALID`,
`REPOSITORY_CORRUPT` (with fsck guidance), `POLICY_DENIED`, `LIMIT_EXCEEDED`,
`INTERNAL`. Errors are deterministic; `message` is for humans, `code` is the contract.
---
## 13. Determinism and Stability
- Response bytes are a pure function of (repository content, query, parameters).
- Schema evolution of the query surface follows additive rules: new endpoints and new
fields are additive within `gemel.query.v1`; breaking changes bump the schema string.
- Clients must tolerate unknown fields (forward compatibility) and must never depend on
`message` text.