Module json_wire 

Typed JSON wire DTOs for agent-facing stdout/stderr contracts.

Policy (Rules Rust — JSON / NDJSON)

• Format: classic single-root JSON (object or array), RFC 8259. Not NDJSON.
• Encoding: UTF-8, no BOM on emit; BOM stripped on import parse.
• Shape: one complete document per CLI invocation on the data stream (stdout success or stderr error envelope), terminated by a single LF.
• Pretty-print: forbidden on the agent wire — compact serde_json::to_string only (machine interop; matches error envelope historical compact form).
• Types: known payloads use Serialize/Deserialize structs here; Value is reserved for genuinely dynamic trees (meta command-tree) and the flexible success-envelope field map at the emission boundary.
• Must-Ignore: import deserializers ignore unknown fields (default serde).
• I-JSON: integers are u16/u32/u64/i32 within safe practical ranges (ports, exit codes, ms timeouts, byte counts); no NaN/Infinity floats.
• Schemas: hand-versioned under docs/schemas/*.schema.json (not generated at runtime). Agents validate offline; product does not embed a schema engine.
• Config on disk: TOML, not JSON5. JSON is only for CLI machine contracts and optional vps export --json / import of that envelope.

Structs

ErrorEnvelope

Stderr failure envelope when JSON errors mode is active.

ExecBatchJson

Multi-host exec batch envelope.

ExecHostJson

One entry in multi-host exec --all --json.

ExecTarget

Identity of the host a single-host execution actually ran against.

ExecutionJson

exec / sudo-exec / su-exec JSON stdout.

ExportHostJson

One host entry inside vps export --json (redacted or with secrets).

HealthBatchJson

health-check --all --json batch envelope.

HealthCheckJson

health-check --json stdout (single host).

HealthHostJson

One entry in health-check --all --json.

ImportDefaults

Default field values applied when import JSON omits them.

ImportEnvelope

Top-level import document: vps-export envelope or bare { "hosts": … }.

ImportHostEntry

One host object under hosts for JSON import.

MaskedVpsJson

Masked VPS record for vps list|show --json (secrets never raw).

ScpBatchJson

Multi-host SCP batch envelope.

ScpHostJson

One entry in multi-host scp --all --json.

ScpTransferJson

scp upload|download --json success stdout.

SftpBatchJson

Multi-host SFTP batch (reuses scp-host shape).

SftpFsOpJson

sftp mkdir|rmdir|rm|rename|stat --json (stat uses size/mode fields).

SftpListEntryJson

One entry in sftp ls --json.

SftpListJson

sftp ls --json success stdout.

SftpTransferJson

sftp upload|download --json success stdout (G-SFTP-09).

SuccessEnvelope

Agent-first success envelope: { "ok": true, "event": …, …fields }.

TargetEcho

The resolved target, echoed under both the canonical and the legacy names.

TunnelClosedJson

tunnel --json shutdown event.

TunnelListeningJson

tunnel --json post-bind event.

VpsExportJson

vps export --json envelope.

Enums

TargetSource

Where the executing host came from, reported by ExecutionJson::host_source.

TunnelCloseReason

Reason a tunnel stopped serving, reported by TunnelClosedJson.

Constants

UTF8_BOM

UTF-8 BOM character; stripped before parsing external JSON.

Functions

print_json_line

Compact JSON + LF on stdout (agent success / data path).

print_json_line_stderr

Compact JSON + LF on stderr; BrokenPipe is ignored (downstream closed).

resolved_target

Returns the host resolved by this process, if any.

set_resolved_target

Records the host this process resolved, so failures can name it.

strip_utf8_bom

Strips a leading UTF-8 BOM if present (Rules: remove BOM before parse).

write_json_line

Serializes value as compact JSON + trailing LF on the given writer.