=== BEGIN ARTIFACT ARCHITECTURE.md ===
# ARCHITECTURE: TOML 1.0.0 Parser
| Field | Value |
|-------------|-------|
| Version | 20260814 V1 |
| Description | Defines the standard-library Go architecture for the TOML parser and decoder command. |
| Depends On | — |
| Provides | parser module boundary, decoder command boundary, tagged JSON contract |
| Consumes | — |
## Questions
- None.
## Intent
The application is a deterministic command-line filter that reads TOML 1.0.0 from standard input and emits tagged JSON on standard output. Invalid TOML produces a diagnostic on standard error and a non-zero exit status.
## Module Boundaries
| Module | Responsibility |
|---|---|
| `cmd/toml-decoder` | Reads stdin, invokes the parser, encodes successful results, and maps failures to process behavior. |
| `internal/toml` | Parses TOML 1.0.0, validates lexical and structural rules, and exposes the internal value model. |
| JSON encoder | Converts internal values to the required tagged JSON representation. |
The parser separates lexical scanning, structural parsing, semantic validation, value representation, and JSON encoding responsibilities. The internal value model uses explicit value kinds and preserves integer lexemes losslessly.
## Technology Stack
| Technology | Use |
|---|---|
| Go | Parser, command, tests, and standard-library integration. |
| Shell | Supplied conformance harness entry points. |
The Go module declares no external dependencies. Runtime behavior uses only the Go standard library.
## Process Contract
The decoder accepts no arguments or configuration. It reads the complete TOML document from stdin. Valid input produces one JSON document on stdout and exit status `0`. Invalid input produces no successful JSON result, writes diagnostics to stderr, and exits non-zero. The command has no filesystem or network side effects.
## Tagged JSON Contract
Tables are JSON objects and arrays are JSON arrays. Each scalar TOML value is represented as an object with `type` and `value` fields. The `value` field is always a JSON string. Supported scalar types are `string`, `integer`, `float`, `bool`, `datetime`, `datetime-local`, `date-local`, and `time-local`.
## Guardrails
- The implementation uses Go with no `go.mod` dependencies.
- The parser does not import a third-party TOML parser.
- The parser preserves signed 64-bit integer values without floating-point conversion.
- The decoder remains an argument-free stdin/stdout filter.
- Supplied scoring scripts remain unchanged.
## Programmatic Acceptance
=== AC architecture-module ===
Intent: The completed build contains the declared Go module and command boundary.
from pathlib import Path
module = Path("go.mod")
command = Path("cmd/toml-decoder")
parser = Path("internal/toml")
assert module.is_file()
assert command.is_dir()
assert parser.is_dir()
=== END AC architecture-module ===
=== AC architecture-dependencies ===
Intent: The Go module has no third-party dependency declarations.
from pathlib import Path
module_text = Path("go.mod").read_text(encoding="utf-8")
assert "require " not in module_text
assert "github.com/BurntSushi/toml" not in module_text
assert "github.com/pelletier/go-toml" not in module_text
=== END AC architecture-dependencies ===
=== AC architecture-command-build ===
Intent: The declared decoder command builds successfully.
import subprocess
result = subprocess.run(
["go", "build", "./cmd/toml-decoder"],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC architecture-command-build ===
## User Acceptance
- None.
## Guardrails
- None.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Decoder-Contract.md ===
# FEATURE: Decoder Contract
| Field | Value |
|-------------|-------|
| Version | 20260814 V1 |
| Description | Defines the argument-free stdin-to-tagged-JSON decoder command contract. |
| Depends On | ARCHITECTURE.md |
| Provides | cmd/toml-decoder |
| Consumes | parser module boundary, tagged JSON contract |
## Questions
- None.
## 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.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Decoder-Invalid-Input.md ===
# FEATURE: Decoder Invalid Input
| Field | Value |
|-------------|-------|
| Version | 20260814 V1 |
| Description | Defines decoder behavior for malformed TOML input. |
| Depends On | FEATURE-Decoder-Contract.md |
| Provides | invalid-input diagnostic boundary |
| Consumes | cmd/toml-decoder, parser error boundary |
## Questions
- None.
## Workflow
When `internal/toml` rejects the input, `cmd/toml-decoder` writes a diagnostic to standard error and exits non-zero. It does not emit a successful JSON document on standard output. The diagnostic wording is not part of the contract.
## Failure Contract
Malformed syntax, invalid UTF-8, prohibited control characters, duplicate definitions, structural conflicts, and unsupported values all use the same process-level failure boundary: non-zero exit status, diagnostic on stderr, and no successful result on stdout.
## Guardrails
- Invalid TOML is rejected rather than accepted permissively.
- Failure diagnostics are written to stderr.
- The command does not claim success for invalid input.
- Diagnostic wording is not used as an acceptance oracle.
## Programmatic Acceptance
=== AC invalid-exit-status ===
Intent: Malformed TOML exits non-zero.
import subprocess
source = 'broken = [\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
assert result.returncode != 0
=== END AC invalid-exit-status ===
=== AC invalid-diagnostic-stream ===
Intent: Malformed TOML produces a non-empty diagnostic on stderr.
import subprocess
source = 'broken = [\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
assert result.returncode != 0
assert result.stderr != ""
=== END AC invalid-diagnostic-stream ===
=== AC invalid-no-success-result ===
Intent: Malformed TOML does not produce a successful JSON result on stdout.
import subprocess
source = 'broken = [\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
assert result.returncode != 0
assert result.stdout == ""
=== END AC invalid-no-success-result ===
## User Acceptance
- None.
## Guardrails
- None.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Tagged-JSON.md ===
# FEATURE: Tagged JSON
| Field | Value |
|-------------|-------|
| Version | 20260814 V1 |
| Description | Defines tagged JSON encoding for TOML tables, arrays, and scalar values. |
| Depends On | FEATURE-Decoder-Contract.md |
| Provides | tagged JSON encoding |
| Consumes | parser value model, cmd/toml-decoder |
## Questions
- None.
## Encoding Rules
Tables become JSON objects and arrays become JSON arrays. Every scalar value becomes an object containing a `type` field and a string-valued `value` field. Integer, float, and boolean payloads remain strings rather than native JSON numbers or booleans.
The encoder supports the scalar type names `string`, `integer`, `float`, `bool`, `datetime`, `datetime-local`, `date-local`, and `time-local`.
## Guardrails
- Empty tables encode as `{}`.
- Empty arrays encode as `[]`.
- Nested tables and arrays retain their structure.
- Every scalar payload is a JSON string.
- Offset datetimes use RFC 3339 representation.
- Local datetimes omit an offset.
- Local dates and local times use their respective representations.
## Programmatic Acceptance
=== AC tagged-scalars ===
Intent: Scalar TOML values are emitted with type names and string payloads.
import json
import subprocess
source = 'text = "hello"\ncount = 42\nactive = true\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
decoded = json.loads(result.stdout)
assert result.returncode == 0
assert decoded["text"]["type"] == "string"
assert decoded["text"]["value"] == "hello"
assert decoded["count"]["type"] == "integer"
assert decoded["count"]["value"] == "42"
assert decoded["active"]["type"] == "bool"
assert decoded["active"]["value"] == "true"
=== END AC tagged-scalars ===
=== AC tagged-structures ===
Intent: Tables and arrays retain structural JSON forms while their scalar members remain tagged.
import json
import subprocess
source = 'items = [1, 2]\n[meta]\nname = "x"\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["items"], list)
assert isinstance(decoded["meta"], dict)
assert decoded["items"][0]["type"] == "integer"
assert decoded["meta"]["name"]["type"] == "string"
=== END AC tagged-structures ===
=== AC tagged-empty-containers ===
Intent: Empty arrays and tables encode as empty JSON containers.
import json
import subprocess
source = 'empty_array = []\n[empty_table]\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
decoded = json.loads(result.stdout)
assert result.returncode == 0
assert decoded["empty_array"] == []
assert decoded["empty_table"] == {}
=== END AC tagged-empty-containers ===
=== AC tagged-datetime-types ===
Intent: Date and time values use the distinct required tagged type names.
import json
import subprocess
source = (
'offset = 1979-05-27T07:32:00Z\n'
'local = 1979-05-27T07:32:00\n'
'date = 1979-05-27\n'
'time = 07:32:00\n'
)
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
decoded = json.loads(result.stdout)
assert result.returncode == 0
assert decoded["offset"]["type"] == "datetime"
assert decoded["local"]["type"] == "datetime-local"
assert decoded["date"]["type"] == "date-local"
assert decoded["time"]["type"] == "time-local"
=== END AC tagged-datetime-types ===
## User Acceptance
- None.
## Guardrails
- None.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Lexical-Strings.md ===
# FEATURE: Lexical Strings
| Field | Value |
|-------------|-------|
| Version | 20260814 V1 |
| Description | Defines TOML 1.0.0 basic, multiline, literal, and multiline literal string parsing. |
| Depends On | ARCHITECTURE.md |
| Provides | TOML string values |
| Consumes | parser module boundary |
## Questions
- None.
## String Forms
The parser supports basic strings, multiline basic strings, literal strings, and multiline literal strings. Basic strings implement the TOML escape sequences for control characters, quotes, backslashes, and Unicode scalar values. Literal strings preserve content without escape processing.
Multiline strings trim the first newline after the opening delimiter. Multiline basic strings support line-ending backslash continuation and valid TOML escapes. Multiline literal strings preserve content without escaping and reject prohibited control characters.
All string forms require valid UTF-8 and reject prohibited control characters. String values may be used as keys as well as values.
## Conformance Scope
The authoritative acceptance scope is the supplied `toml-test` string suite. The stage runner selects the `valid/string/*` cases and the complete invalid string cases without asserting on runner output.
## Guardrails
- Invalid escape sequences are rejected.
- Unterminated strings are rejected.
- Literal strings do not interpret backslashes as escapes.
- Prohibited control characters are rejected.
- String conformance is measured by the supplied suite.
## Programmatic Acceptance
=== AC strings-conformance ===
Intent: The implementation passes the authoritative TOML 1.0.0 string conformance slice.
Suite: scoped
import os
import subprocess
result = subprocess.run(
["sh", "sources/stage_test.sh", "valid/string/*"],
capture_output=True,
text=True,
env={**os.environ},
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC strings-conformance ===
=== AC strings-invalid-conformance ===
Intent: The implementation rejects the authoritative invalid string cases.
Suite: scoped
import os
import subprocess
result = subprocess.run(
["sh", "sources/stage_test.sh", "invalid/string/*"],
capture_output=True,
text=True,
env={**os.environ},
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC strings-invalid-conformance ===
=== AC strings-process ===
Intent: A basic string is accepted through the decoder process boundary.
import json
import subprocess
value = "line\nvalue"
source = 'text = "line\\nvalue"\n'
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
decoded = json.loads(result.stdout)
assert result.returncode == 0
assert decoded["text"]["type"] == "string"
assert decoded["text"]["value"] == value
=== END AC strings-process ===
=== AC strings-literal ===
Intent: A literal string preserves its backslashes as supplied input.
import json
import subprocess
value = r"C:\Users\nodejs"
source = f"text = '{value}'\n"
result = subprocess.run(
["./toml-decoder"],
input=source,
capture_output=True,
text=True,
)
decoded = json.loads(result.stdout)
assert result.returncode == 0
assert decoded["text"]["type"] == "string"
assert decoded["text"]["value"] == value
=== END AC strings-literal ===
## User Acceptance
- None.
## Guardrails
- None.
=== END ARTIFACT ===Run artifact