FEATURE: Decoder Contract

Workflow

The executable reads the complete TOML document from standard input and delegates parsing to internal/toml. On success it writes exactly one tagged JSON document to standard output and exits zero. On invalid TOML it writes a diagnostic to standard error, writes no successful result to standard output, and exits non-zero. The executable accepts no required arguments and has no runtime configuration.

Output Contract

• Tables are JSON objects.
• Arrays are JSON arrays.
• Every scalar is encoded as {"type": "<TOML_TYPE>", "value": "<TOML_VALUE>"}.
• Scalar value fields are always JSON strings.
• Integer values must remain lossless across the signed 64-bit range.
• Offset and local date/time values use the required TOML type tags and formatting.

Programmatic Acceptance

=== AC decoder-valid-contract ===
Intent: A valid TOML document produces the required tagged JSON on stdout with no stderr diagnostic.

import json import subprocess

source = "answer = 42\n" expected = {"answer": {"type": "integer", "value": "42"}} result = subprocess.run( ["./toml-decoder"], input=source, capture_output=True, text=True, ) print(result.stdout) print(result.stderr) assert result.returncode == 0 assert result.stderr == "" assert json.loads(result.stdout) == expected === END AC decoder-valid-contract ===

=== AC decoder-invalid-contract ===
Intent: Invalid TOML produces a non-zero exit, no successful stdout result, and a stderr diagnostic.

import subprocess

source = "answer = [\n" result = subprocess.run( ["./toml-decoder"], input=source, capture_output=True, text=True, ) print(result.stdout) print(result.stderr) assert result.returncode != 0 assert result.stdout == "" assert result.stderr != "" === END AC decoder-invalid-contract ===

=== AC decoder-stage-contract ===
Intent: The supplied decoder contract gate passes in full.

import subprocess

result = subprocess.run( ["sh", "sources/stage_contract.sh", "decoder"], capture_output=True, text=True, ) print(result.stdout) print(result.stderr) assert result.returncode == 0 === END AC decoder-stage-contract ===

User Acceptance

• None.

Guardrails

• Successful JSON is written only to stdout.
• Diagnostics are written only to stderr.
• Invalid input must never exit successfully.
• The executable must not read configuration files or produce runtime side effects.