TCG-PROTOCOL v0.1 — the oracle wire protocol, both hops

1. Framing and envelopes

05req r1

06NDJSON duplex: one JSON object per line, UTF-8, \n-terminated, both directions.

07Requests and responses correlate by caller-chosen id (number, unique per in-flight request).

08The protocol version rides every frame:

// request
{"proto": 1, "id": 7, "op": "validate", "params": { /* per-op */ }}
// success
{"proto": 1, "id": 7, "ok": true, "result": { /* per-op */ }}
// failure (op-grain, session survives)
{"proto": 1, "id": 7, "ok": false,
 "error": {"kind": "<taxonomy §4>", "detail": "…", "recipe": "…?"}}

10ORACLE_PROTOCOL = 1 is independent of ts-extract's PROTOCOL = 1 (different channel, different message set; the constants version independently).

11A proto mismatch is a protocol error; responses to unknown ids are a bridge bug and dropped with a stderr note.

12Requests MAY be pipelined; responses come in completion order (the oracle is single-threaded per op today, so in practice FIFO — callers must still match by id, not order).

2. Operations

13req r2

14Positions are {line, character}, 1-based line, 0-based character (the TypeScript convention surfaced honestly).

15Paths are project-root- relative with forward slashes.

• 16init {root, cells_dir?, seam?} → {ts_version, config_file, root_files} — builds the service (ORACLE §2–3). cells_dir/seam are policy-derived DATA the Rust layer passes down (the node side never reads conform.toml itself); they feed the scope op's cell/seam/branded context and default to none/"index". Re-init on a live oracle rebuilds config and policy; overlays are cleared.
• update {file, content | null} → {version} — set/clear an overlay (ORACLE §3).
• validate {file, content?} → {diagnostics: [{code, category, message, line, character}], facts: [/* ts-extract fact shapes */], markers: [/* §9 marker shapes */], degraded} — the fact/marker arrays reuse the ts-extract record vocabulary verbatim (ts_unsafe, import, item, file_metrics; {tag, uri, reason, symbol, line}) so one serde vocabulary serves both tools.
• scope {file, position?} → {symbols: [{name, kind, type_text}], cell, seam_file, branded: [{name, seam, heuristic}]}.
• complete {file, position, content?, prefix?, max?} → {entries: [{name, kind, type_text, unsafe}]} — prefix filters by name prefix and max caps the set (default 50) BEFORE the per-entry checker details are computed: type text and the unsafe flag are entry-grain checker work, affordable only after the cut. A caller that wants the raw thousand-entry universe passes no prefix and a large max, and pays for it knowingly.
• type {file, position, content?} → {display, documentation}.
• shutdown {} → {} then exit 0.

3. The enrichment hop (Rust adds, never reshapes)

17req r3

18typescript-ai-native-tcg serve speaks §1–§2 upward unchanged and widens two responses with policy-derived fields (policy = the project's conform.toml, read at init; ORACLE §4 keeps the node side policy-free):

• 19validate.result gains conform_findings: [{rule, message, line, baselined}] — the REAL rule set (ts-unsafe-in-domain, ts-cell-isolation, file budget) run over the returned facts via conform_core::check, each finding flagged against the project's frozen ratchet baseline — and advice: [string] (Class-F strings citing spec:// REQs).
• scope.result.branded is completed from seam files per the policy's cells_dir/seam, and advice may name the branded constructor a bare primitive at this seam should use.
• complete.result.entries[].unsafe is finalised against the policy (the node side flags candidates; policy decides).

20A consumer that talks to the oracle directly (no Rust layer) gets well-formed §2 responses with no enrichment fields — the fields are additive, and their absence means "no policy layer", not an error.

4. Error taxonomy

21req r4

22Five kinds, each actionable, each carried in the §1 error object (and mirrored as typed variants in typescript-ai-native-tcg-bridge):

24Errors are OP-GRAIN wherever possible (the session survives, ORACLE §5); only oracle-crashed is session-grain.

5. Compatibility rules

25req r5

26Additive evolution within a proto: new OPTIONAL request params, new response fields, and new advice/finding entries are non-breaking; a consumer ignores what it does not know.

27Renames, type changes, and semantic changes to existing fields bump ORACLE_PROTOCOL, and the bridge treats a mismatch as its own error class — the same cache-retirement posture the extract bridge established.

28Scripted doubles pin the INNER side in this package's tests (the no-node double, crates/typescript-ai-native-tcg-bridge/src/transport.rs:312); the fact-parity test (ORACLE §1) pins the vocabulary shared with ts-extract. The OUTER shape is not yet pinned — no recorded stream is checked into the package and no test constructs an outer frame.