com.blockether.vis.contract.wire — com.blockether/vis-contract 0.1.43

Canonical value and JSON codecs shared by Core, the gateway and every SDK.

This namespace is a pure deterministic boundary: it performs no transport, filesystem, process or lifecycle work. Engine EDN becomes total JSON data; in-process readers receive exactly the shape a remote JSON reader receives.

->engine clj

(->engine x)

Recursively convert decoded wire data into the engine's keyword-keyed shape — the mirror of ->wire. Only KEYS are converted (via engine-key); values are data and are never re-typed.

->wire clj

(->wire x)

Recursively convert an engine value into JSON-encodable data.

canonical clj

(canonical x)

THE canonical gateway value shape — snake_case STRING map keys, exactly what a remote client holds after parse-json ∘ json-str. In-process and remote consumers therefore read the same role-labelled messages and typed content blocks.

Invariant: (canonical x) equals (parse-json (json-str x)).

engine-key clj

(engine-key k)

Wire key -> engine keyword: THE inverse of wire-key, and the only one. is_foo -> :is-foo, foo_bar -> :foo-bar.

It is total only because the engine spells a boolean :is-foo and never :foo?: wire-key collapses BOTH spellings onto is_foo, so while a :foo? key exists no rule can tell which one a wire key came from. That ambiguity is why every inbound seam used to grow its own hand-written list of exceptions, and why forgetting one entry was silent. A FOREIGN contract that insists on ? (svar's :tool-call?) maps through its own named table at its own seam — never by convention here.

json-str clj

(json-str x)

Encode any engine value as a JSON string via ->wire.

parse-json clj

(parse-json s)

Parse a JSON string into the canonical wire shape: snake_case STRING map keys, identical to canonical. Returns nil on blank or malformed input (callers map that to 400).

wire-key clj

(wire-key k)

Keyword/symbol map key -> snake_case string. A boolean-style foo? key becomes is_foo (already-is- prefixed keys just drop the ?). String keys (fact keys, scope strings, file paths) pass VERBATIM - rewriting them could corrupt user data that legitimately contains hyphens. ANY other key (the number/boolean/nil keys a decoded JSON or Python value can carry into a tool result) is rendered to its JSON key spelling: JSON has no non-string keys, and leaving one unrendered makes the whole event unencodable - which kills the transport, not just the field.