FEATURE: Decoder Contract

Workflow

The cmd/toml-decoder executable reads one TOML document from standard input and delegates parsing to internal/toml. For valid input it writes the encoded tagged JSON document to standard output and exits successfully. It accepts no command-line arguments, configuration, or alternate input source.

Output Behavior

Tables and arrays retain their JSON structure. Scalar values use the tagged representation defined by ARCHITECTURE.md. The command does not write files, contact external services, or emit diagnostics for successful input.

Guardrails

• The command accepts no arguments.
• TOML is read only from stdin.
• Successful output is written only to stdout.
• The command has no configuration or persistent side effects.
• Invalid-input handling is implemented by the decoder error boundary.

Programmatic Acceptance

=== AC decoder-valid-stdin ===
Intent: A valid TOML document is accepted through stdin and produces a JSON object. import json import subprocess

source = 'answer = 42\n' result = subprocess.run( ["./toml-decoder"], input=source, capture_output=True, text=True, ) decoded = json.loads(result.stdout) assert result.returncode == 0 assert isinstance(decoded, dict) === END AC decoder-valid-stdin ===

=== AC decoder-argument-free ===
Intent: Supplying an argument is rejected by the argument-free command contract. import subprocess

result = subprocess.run( ["./toml-decoder", "--help"], input="", capture_output=True, text=True, ) assert result.returncode != 0 === END AC decoder-argument-free ===

=== AC decoder-stream-separation ===
Intent: Successful decoding does not write diagnostics to stderr. import subprocess

source = 'enabled = true\n' result = subprocess.run( ["./toml-decoder"], input=source, capture_output=True, text=True, ) assert result.returncode == 0 assert result.stderr == "" === END AC decoder-stream-separation ===

User Acceptance

• None.

Guardrails

• None.