=== BEGIN ARTIFACT ARCHITECTURE.md ===
# ARCHITECTURE: TOML 1.0.0 Parser
| Field | Value |
|-------------|-------|
| Version | 20260816 V1 |
| Description | Standard-library-only Go architecture for a TOML 1.0.0 command-line decoder. |
| Depends On | — |
| Provides | cmd/toml-decoder, internal/toml, Go module |
| Consumes | — |
## Questions
- None.
## Intent
The project is a Go command-line filter that reads a TOML 1.0.0 document from standard input and emits deterministic tagged JSON. Parsing is implemented in `internal/toml`, while `cmd/toml-decoder` owns process I/O, JSON encoding, diagnostics, and exit status.
## Modules and Boundaries
| Module | Responsibility |
|---|---|
| `cmd/toml-decoder` | Read stdin, invoke the parser, encode successful results, and report failures. |
| `internal/toml` | Parse TOML 1.0.0 syntax and semantics into tagged values and tables. |
| `go.mod` | Declare the Go module and toolchain floor without third-party dependencies. |
The command must not read configuration files, access the network, persist data, or modify supplied scoring assets. The parser must use only the Go standard library.
## Tagged Value Model
Tables map to JSON objects and arrays map to JSON arrays. Every scalar value is represented as an object containing string-valued `type` and `value` fields. Supported type tags are `string`, `integer`, `float`, `bool`, `datetime`, `datetime-local`, `date-local`, and `time-local`.
## Technology Stack
- Go 1.22 or newer, using `go.md`.
- POSIX shell for supplied acceptance scripts, using `common.md`.
## Programmatic Acceptance
=== AC architecture-build ===
Intent: The declared Go module and decoder command compile without third-party module requirements.
import subprocess
result = subprocess.run(
["sh", "sources/stage_contract.sh", "architecture"],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC architecture-build ===
=== AC architecture-module ===
Intent: The command package is buildable through the required repository path.
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-module ===
=== AC architecture-dependencies ===
Intent: The module declares no forbidden third-party dependency.
from pathlib import Path
module_text = Path("go.mod").read_text(encoding="utf-8")
require_lines = [
line for line in module_text.splitlines()
if line.lstrip().startswith("require ")
]
assert not require_lines
=== END AC architecture-dependencies ===
## User Acceptance
- None.
## Guardrails
- The parser must not import a third-party TOML library.
- The `cmd/toml-decoder` build path must remain unchanged.
- Supplied scoring scripts and harness assets must not be modified.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Decoder-Contract.md ===
# FEATURE: Decoder Contract
| Field | Value |
|-------------|-------|
| Version | 20260816 V1 |
| Description | Defines the stdin, tagged-JSON, diagnostic-stream, and exit-status contract for the TOML decoder. |
| Depends On | ARCHITECTURE.md |
| Provides | stdin TOML decoder, tagged JSON stdout, stderr diagnostics |
| Consumes | internal/toml |
## Questions
- None.
## 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.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Strings.md ===
# FEATURE: TOML Strings
| Field | Value |
|-------------|-------|
| Version | 20260816 V1 |
| Description | Defines TOML 1.0.0 basic, literal, multiline basic, and multiline literal string parsing. |
| Depends On | ARCHITECTURE.md |
| Provides | TOML string parsing |
| Consumes | internal/toml |
## Questions
- None.
## Scope
Support basic and literal strings, multiline delimiters, required escapes, Unicode scalar escapes, newline trimming, line-ending continuation, embedded quotes, preserved whitespace, and prohibited-control validation according to TOML 1.0.0.
## Programmatic Acceptance
=== AC strings-valid-suite ===
Intent: The authoritative conformance suite passes every valid string case owned by this feature.
import subprocess
result = subprocess.run(
["sh", "sources/stage_test.sh", "valid/string/**"],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC strings-valid-suite ===
=== AC strings-invalid-suite ===
Intent: The authoritative conformance suite rejects every invalid string case owned by this feature.
import subprocess
result = subprocess.run(
["sh", "sources/stage_test.sh", "invalid/string/**"],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC strings-invalid-suite ===
=== AC strings-bounded-suites ===
Intent: Both string conformance invocations complete successfully as separate executable checks.
import subprocess
patterns = ["valid/string/**", "invalid/string/**"]
for pattern in patterns:
result = subprocess.run(
["sh", "sources/stage_test.sh", pattern],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC strings-bounded-suites ===
## User Acceptance
- None.
## Guardrails
- Basic-string escapes must be decoded only when TOML 1.0.0 permits them.
- Literal strings must preserve backslashes and reject unescaped delimiters.
- Multiline strings must enforce delimiter, trimming, continuation, and control-character rules.
- Invalid UTF-8 and prohibited controls must not be accepted as string content.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Lexical-Scalars.md ===
# FEATURE: Lexical Scalars
| Field | Value |
|-------------|-------|
| Version | 20260816 V1 |
| Description | Defines TOML boolean, integer, and floating-point scalar parsing. |
| Depends On | ARCHITECTURE.md |
| Provides | TOML boolean, integer, and float parsing |
| Consumes | internal/toml |
## Questions
- None.
## Scope
Support lowercase booleans; signed decimal integers; hexadecimal, octal, and binary integers; underscores; signed 64-bit bounds; decimal fractions and exponents; signed zero; infinity; and NaN. Scalar values must be emitted with the corresponding TOML type tag and a JSON string representation.
## Programmatic Acceptance
=== AC scalars-valid-suite ===
Intent: The authoritative conformance suite passes all valid boolean, integer, and float cases.
import subprocess
result = subprocess.run(
[
"sh",
"sources/stage_test.sh",
"valid/bool/**|valid/integer/**|valid/float/**",
],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC scalars-valid-suite ===
=== AC scalars-invalid-suite ===
Intent: The authoritative conformance suite rejects all invalid boolean, integer, and float cases.
import subprocess
result = subprocess.run(
[
"sh",
"sources/stage_test.sh",
"invalid/bool/**|invalid/integer/**|invalid/float/**",
],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC scalars-invalid-suite ===
=== AC scalars-bounded-suites ===
Intent: The valid and invalid scalar conformance slices each complete successfully.
import subprocess
patterns = [
"valid/bool/**|valid/integer/**|valid/float/**",
"invalid/bool/**|invalid/integer/**|invalid/float/**",
]
for pattern in patterns:
result = subprocess.run(
["sh", "sources/stage_test.sh", pattern],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC scalars-bounded-suites ===
## User Acceptance
- None.
## Guardrails
- Integer parsing must reject values outside the signed 64-bit range.
- Integer underscores must satisfy TOML placement rules.
- Floats must reject malformed decimal points and exponents.
- Special float tokens must remain lowercase and preserve the required type semantics.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Lexical-Boundaries.md ===
# FEATURE: Lexical Boundaries
| Field | Value |
|-------------|-------|
| Version | 20260816 V1 |
| Description | Defines TOML comment, whitespace, line-ending, encoding, and control-character handling. |
| Depends On | ARCHITECTURE.md |
| Provides | TOML lexical boundary validation |
| Consumes | internal/toml |
## Questions
- None.
## Scope
Handle spaces and tabs, LF and CRLF line endings, comments outside strings, multiline lexical boundaries, valid UTF-8 documents, and rejection of prohibited control characters in comments and applicable value contexts.
## Programmatic Acceptance
=== AC lexical-comments-valid-suite ===
Intent: The authoritative conformance suite passes every valid comment and lexical-boundary case.
import subprocess
result = subprocess.run(
["sh", "sources/stage_test.sh", "valid/comment/**"],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC lexical-comments-valid-suite ===
=== AC lexical-boundaries-invalid-suite ===
Intent: The authoritative conformance suite rejects every invalid control-character and encoding case.
import subprocess
result = subprocess.run(
[
"sh",
"sources/stage_test.sh",
"invalid/control/**|invalid/encoding/**",
],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC lexical-boundaries-invalid-suite ===
=== AC lexical-boundaries-suites ===
Intent: The valid comment and invalid lexical-boundary conformance slices complete successfully.
import subprocess
patterns = [
"valid/comment/**",
"invalid/control/**|invalid/encoding/**",
]
for pattern in patterns:
result = subprocess.run(
["sh", "sources/stage_test.sh", pattern],
capture_output=True,
text=True,
)
print(result.stdout)
print(result.stderr)
assert result.returncode == 0
=== END AC lexical-boundaries-suites ===
## User Acceptance
- None.
## Guardrails
- Comments must not consume content inside strings.
- Only TOML-permitted whitespace and line endings may be accepted.
- Invalid UTF-8 must be rejected.
- Prohibited control characters must be rejected in every applicable lexical context.
=== END ARTIFACT ===Run artifact