=== BEGIN ARTIFACT FEATURE-Error-and-Optional-Evaluation.md ===
# FEATURE: Error and Optional Evaluation
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines jq runtime errors, optional evaluation, suppression, and try/catch behavior. |
| Depends On | FEATURE-Composition.md |
| Provides | empty, error, runtime failure, optional operator, try/catch |
| Consumes | ordered generator evaluation |
## Questions
- None.
## Workflow
Runtime errors propagate with exit status 5 after preserving values already emitted. `empty` emits no values. The optional suffix suppresses errors, while `try ... catch ...` evaluates a handler with the error value.
## Programmatic Acceptance
=== AC core-003-conformance ===
Intent: The authoritative corpus cases covering errors, optional evaluation, and try/catch execute without failures.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"try|error|\?"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC core-003-conformance ===
=== AC core-003-runtime-contract ===
Intent: Compile errors, runtime errors, and successful execution retain their distinct exit statuses.
Requires: executable=python3; scope=test
import subprocess
valid = subprocess.run(
["./jq", "-c", "."],
input="1\n",
capture_output=True,
text=True,
)
compile_error = subprocess.run(
["./jq", "-c", "["],
input="1\n",
capture_output=True,
text=True,
)
runtime_error = subprocess.run(
["./jq", "-c", "error"],
input="1\n",
capture_output=True,
text=True,
)
assert valid.returncode == 0
assert compile_error.returncode == 3
assert runtime_error.returncode == 5
=== END AC core-003-runtime-contract ===
## User Acceptance
- None.
## Guardrails
- Diagnostics are written to stderr and are not used as the behavioral oracle.
- Partial stdout emitted before a runtime error is preserved.
- Optional evaluation must not suppress compile-time errors.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Truthiness-and-Comparison.md ===
# FEATURE: Truthiness and Comparison
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines jq truthiness, equality, inequality, and total value ordering. |
| Depends On | FEATURE-Error-and-Optional-Evaluation.md |
| Provides | truthiness, equality, inequality, type ordering, comparisons |
| Consumes | ordered generator evaluation |
## Questions
- None.
## Semantics
Only `false` and `null` are falsey. Equality is type-aware, with numeric equivalence across integer and floating representations. Ordering follows jq's value ordering across nulls, booleans, numbers, strings, arrays, and objects. Comparison operators preserve generator multiplicity.
## Programmatic Acceptance
=== AC core-004-conformance ===
Intent: The authoritative corpus comparison and truthiness cases execute without failures.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"==|!=|<=|>=|<|>"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC core-004-conformance ===
=== AC core-004-json-contract ===
Intent: The runner confirms structural equality and ordering behavior over the supplied corpus.
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"==|!=|<=|>=|<|>"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
report = json.loads(result.stdout)
summary = report["summary"]
assert isinstance(summary["pass"], int)
assert summary["pass"] > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC core-004-json-contract ===
## User Acceptance
- None.
## Guardrails
- Python truthiness must not replace jq truthiness.
- Boolean values must not compare equal to numbers.
- Object key insertion order must not affect structural equality.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Value-Model.md ===
# FEATURE: Value Model
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines the internal representation and serialization of jq values, including special numbers. |
| Depends On | FEATURE-Truthiness-and-Comparison.md |
| Provides | null, booleans, numbers, strings, arrays, objects, NaN, infinities |
| Consumes | truthiness, equality, and ordering |
## Questions
- None.
## Value Contract
The interpreter represents JSON-compatible nulls, booleans, numbers, strings, arrays, and objects using standard-library facilities. Numeric handling preserves literal-aware behavior required by the corpus and supports NaN and infinities where jq exposes them. Serialization emits valid JSON-compatible output for the harness.
## Programmatic Acceptance
=== AC value-001-conformance ===
Intent: The authoritative corpus special-number and number-serialization cases execute without failures.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"nan|infinite|tojson|fromjson"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC value-001-conformance ===
=== AC value-001-special-values ===
Intent: The implementation accepts and processes the special numeric values exercised by jq.
Requires: executable=python3; scope=test
import json
import subprocess
input_value = "null\n"
result = subprocess.run(
["./jq", "-c", "infinite, nan | type"],
input=input_value,
capture_output=True,
text=True,
)
assert result.returncode == 0
actual = [json.loads(line) for line in result.stdout.splitlines()]
assert actual == ["number", "number"]
=== END AC value-001-special-values ===
## User Acceptance
- None.
## Guardrails
- No third-party numeric or jq implementation may be used.
- NaN and infinity handling must remain compatible with the supplied harness.
- Numeric formatting must not introduce non-JSON output lines.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Accessors.md ===
# FEATURE: Accessors
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines object-field access, array indexing, optional access, and negative-index behavior. |
| Depends On | FEATURE-Value-Model.md |
| Provides | object fields, array indices, optional access, negative indices |
| Consumes | jq value model |
## Questions
- None.
## Access Semantics
Object fields return the matching value or null when absent. Array indices are zero-based and support negative indices. Invalid access raises a jq runtime error unless the expression is optional, in which case the error is suppressed according to jq semantics.
## Programmatic Acceptance
=== AC value-002-conformance ===
Intent: The authoritative corpus accessor cases execute without failures.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"\.[A-Za-z]|\[[-0-9]"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC value-002-conformance ===
=== AC value-002-access-contract ===
Intent: Field access, negative indexing, and optional access produce the supplied jq behavior.
Requires: executable=python3; scope=test
import json
import subprocess
payload = '{"field":[10,20,30]}\n'
result = subprocess.run(
["./jq", "-c", ".field[-1], .missing?, .field[0]"],
input=payload,
capture_output=True,
text=True,
)
assert result.returncode == 0
actual = [json.loads(line) for line in result.stdout.splitlines()]
expected = [30, None, 10]
assert actual == expected
=== END AC value-002-access-contract ===
## User Acceptance
- None.
## Guardrails
- Missing fields yield null rather than Python exceptions.
- Negative array indices follow jq indexing rules.
- Optional access suppresses only the applicable runtime access error.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Slices-and-Iteration.md ===
# FEATURE: Slices and Iteration
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines array and string slicing plus array and object iteration semantics. |
| Depends On | FEATURE-Accessors.md |
| Provides | array/string slices, array/object iteration, fractional bounds |
| Consumes | field and index access |
## Questions
- None.
## Semantics
Array and string slices use inclusive-start and exclusive-end bounds, support omitted and negative bounds, and clamp out-of-range values. Fractional bounds are handled according to jq's numeric rules. Iteration over arrays and objects yields values in the required order, while optional iteration suppresses invalid-container errors.
## Programmatic Acceptance
=== AC value-003-conformance ===
Intent: The authoritative corpus slice cases execute without failures.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
import sys
selector = r"\[.*:|\.\[\]"
result = subprocess.run(
[sys.executable, "sources/run_conformance.py", "--select", selector, "--json"],
capture_output=True,
text=True,
env={**os.environ, "JQ": f"{os.getcwd()}/jq"},
)
print(result.stdout)
print(result.stderr, file=sys.stderr)
report = json.loads(result.stdout)
summary = report["summary"]
assert sum(summary.values()) > 0
assert summary["fail"] == 0
assert summary["error"] == 0
assert result.returncode == 0
=== END AC value-003-conformance ===
=== AC value-003-iteration-contract ===
Intent: Array iteration and slicing preserve output order and bounds.
Requires: executable=python3; scope=test
import json
import subprocess
payload = '["a","b","c","d"]\n'
result = subprocess.run(
["./jq", "-c", ".[], .[1:3]"],
input=payload,
capture_output=True,
text=True,
)
assert result.returncode == 0
actual = [json.loads(line) for line in result.stdout.splitlines()]
expected = ["a", "b", "c", "d", ["b", "c"]]
assert actual == expected
=== END AC value-003-iteration-contract ===
## User Acceptance
- None.
## Guardrails
- Iteration preserves generator order and multiplicity.
- Slices must not mutate the source value.
- Out-of-range slices return the jq-compatible empty or clamped result rather than failing unexpectedly.
=== END ARTIFACT ===Run artifact