=== BEGIN ARTIFACT FEATURE-Arithmetic-And-Structural-Operators.md ===
# FEATURE: Arithmetic and Structural Operators
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Implements jq arithmetic, structural combination, repetition, splitting, and negation operators. |
| Depends On | FEATURE-Type-And-Numeric-Primitives.md, FEATURE-Composition-And-Cartesian-Evaluation.md, FEATURE-Errors-And-Optional-Evaluation.md |
| Provides | +, -, *, /, %, unary negation, recursive object merge, string repetition and splitting |
| Consumes | jq value model, generator evaluation, comparison semantics |
## Intent
Implement jq's typed arithmetic and structural operators. Operators evaluate both operands as filters over the same input and preserve Cartesian generator behavior.
## Behavior
- Numbers use jq-compatible arithmetic.
- Arrays concatenate with `+` and subtract matching elements with `-`.
- Strings concatenate with `+`, repeat with numeric `*`, and split with `/`.
- Objects merge with `+`; `*` recursively merges nested objects.
- `null` is additive with any value.
- Division and remainder by zero raise runtime errors.
- Unary negation accepts numbers only and preserves partial output semantics.
## Programmatic Acceptance
=== AC flow-001-conformance ===
Intent: The arithmetic and structural operator implementation passes representative declared arithmetic and structural behaviors.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
addition = subprocess.run(
[jq, "-c", "1 + 2"],
capture_output=True,
text=True,
)
assert addition.returncode == 0
assert json.loads(addition.stdout) == 3
merge = subprocess.run(
[jq, "-c", '{"a":{"x":1}} * {"a":{"y":2}}'],
capture_output=True,
text=True,
)
assert merge.returncode == 0
assert json.loads(merge.stdout) == {"a": {"x": 1, "y": 2}}
=== END AC flow-001-conformance ===
## User Acceptance
- None.
## Guardrails
- Do not perform implicit cross-type conversions.
- Preserve operator precedence, generator multiplicity, and runtime errors.
- Do not shell out to another jq implementation.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Boolean-And-Alternative-Operators.md ===
# FEATURE: Boolean and Alternative Operators
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Implements jq Boolean operators, truthiness-aware alternatives, and defined-or assignment. |
| Depends On | FEATURE-Truthiness-And-Comparison.md, FEATURE-Arithmetic-And-Structural-Operators.md |
| Provides | and, or, not, //, //= |
| Consumes | jq truthiness, generator core, arithmetic operators |
## Intent
Implement strict Boolean operators and jq's value-selection alternative operators. Boolean operators produce Boolean values, while `//` selects non-null and non-false generator outputs.
## Behavior
- Only `false` and `null` are falsey.
- `and`, `or`, and `not` produce Boolean results with generator-valued operands evaluated according to jq semantics.
- `a // b` emits all non-false, non-null values from `a`; otherwise it evaluates `b`.
- `//=` updates defined-or paths using jq assignment semantics.
- Short-circuiting must prevent unnecessary error-producing branches where jq requires it.
## Programmatic Acceptance
=== AC flow-002-conformance ===
Intent: The Boolean and alternative operator implementation passes representative declared Boolean and fallback behaviors.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
boolean = subprocess.run(
[jq, "-c", "true and (1 == 1)"],
capture_output=True,
text=True,
)
assert boolean.returncode == 0
assert json.loads(boolean.stdout) is True
alternative = subprocess.run(
[jq, "-c", "null // 7"],
capture_output=True,
text=True,
)
assert alternative.returncode == 0
assert json.loads(alternative.stdout) == 7
=== END AC flow-002-conformance ===
## User Acceptance
- None.
## Guardrails
- Do not treat empty strings, arrays, or objects as falsey.
- Preserve generator multiplicity and alternative fallback semantics.
- Do not evaluate fallback branches when jq semantics select the left stream.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Collection-Transformations.md ===
# FEATURE: Collection Transformations
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Provide jq collection transformation builtins with generator-preserving behavior. |
| Depends On | FEATURE-Reductions-And-Iteration-Control.md, FEATURE-Deletion-And-Assignment.md, FEATURE-Type-And-Numeric-Primitives.md |
| Provides | map, map_values, select, add, flatten, transpose, combinations, walk |
| Consumes | generator evaluator, operators, path mutation |
## Workflow
Collection filters transform arrays and objects while preserving jq stream order and multiplicity. Implement `map`, `map_values`, `select`, `add`, `flatten`, `transpose`, `combinations`, and recursive `walk` using the established evaluator and immutable update semantics. Empty generators, nested arrays, jagged matrices, and recursive values must follow the manual and `sources/builtin.jq`.
## Programmatic Acceptance
=== AC data-001-conformance ===
Intent: The collection transformation implementation passes representative declared map and flatten behaviors.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
mapped = subprocess.run(
[jq, "-c", "map(. * 2)"],
input="[1,2,3]",
capture_output=True,
text=True,
)
assert mapped.returncode == 0
assert json.loads(mapped.stdout) == [2, 4, 6]
flattened = subprocess.run(
[jq, "-c", "flatten"],
input="[[1],[2,3]]",
capture_output=True,
text=True,
)
assert flattened.returncode == 0
assert json.loads(flattened.stdout) == [1, 2, 3]
=== END AC data-001-conformance ===
## User Acceptance
- None.
## Guardrails
- Preserve generator ordering, multiplicity, and backtracking.
- Do not mutate input values in place.
- Use only Python standard-library facilities.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Complex-Assignment-Edges.md ===
# FEATURE: Complex Assignment Edges
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Defines edge-case behavior for iterated, empty, fractional, invalid, and deep assignments. |
| Depends On | FEATURE-Deletion-And-Assignment.md, FEATURE-Path-Primitives.md |
| Provides | Iterated path assignment, empty-update deletion, array expansion, assignment depth protections |
| Consumes | Assignment operators, path primitives |
## Purpose
Complete assignment semantics for complex path expressions and adversarial boundary cases.
## Implementation Requirements
- Apply assignments across iterated and multi-path selections in generator order.
- Treat an update producing `empty` as deletion.
- Expand arrays with `null` values when setting beyond their current length.
- Handle negative, fractional, NaN, and out-of-range indexes according to jq semantics.
- Reject invalid string updates and invalid array path components with runtime errors.
- Enforce assignment path depth limits.
- Preserve partial output behavior when a later assignment fails.
## Programmatic Acceptance
=== AC complex-assignment-conformance ===
Intent: The complex assignment implementation passes representative declared path update and empty-update deletion behaviors.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
updated = subprocess.run(
[jq, "-c", ".a |= . + 1"],
input='{"a":1}',
capture_output=True,
text=True,
)
assert updated.returncode == 0
assert json.loads(updated.stdout) == {"a": 2}
deleted = subprocess.run(
[jq, "-c", "del(.a)"],
input='{"a":1,"b":2}',
capture_output=True,
text=True,
)
assert deleted.returncode == 0
assert json.loads(deleted.stdout) == {"b": 2}
=== END AC complex-assignment-conformance ===
## User Acceptance
- None.
## Guardrails
- Do not silently clamp invalid assignment indexes when jq specifies an error.
- Do not discard valid outputs produced before a later runtime failure.
- Do not exceed configured path depth limits through recursive or iterated assignments.
=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-Composition-And-Cartesian-Evaluation.md ===
# FEATURE: Composition and Cartesian Evaluation
| Field | Value |
|-------------|-------|
| Version | 20260822 V1 |
| Description | Implement jq composition, Cartesian argument evaluation, collection, object construction, and binary filter composition. |
| Depends On | FEATURE-Generator-Core.md, FEATURE-Filter-Grammar.md |
| Provides | Pipes, commas, Cartesian arguments, arrays, objects, and binary filter composition |
| Consumes | Generator core, parsed expressions, JSON value model |
## Scope
Composition shall feed every output of a left-hand filter into the right-hand filter, concatenate comma streams in order, evaluate multi-output arguments as Cartesian products, and collect all generated values for arrays and objects. Binary operators shall receive independently evaluated filter results according to jq semantics.
## Programmatic Acceptance
=== AC composition-conformance ===
Intent: The composition implementation passes representative declared pipe, comma, array, and object behaviors.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
piped = subprocess.run(
[jq, "-c", ".[] | . * 2"],
input="[1,2]",
capture_output=True,
text=True,
)
assert piped.returncode == 0
assert [json.loads(line) for line in piped.stdout.splitlines()] == [2, 4]
constructed = subprocess.run(
[jq, "-c", "[1,2]"],
capture_output=True,
text=True,
)
assert constructed.returncode == 0
assert json.loads(constructed.stdout) == [1, 2]
=== END AC composition-conformance ===
=== AC composition-cartesian-streams ===
Intent: The composition implementation preserves comma stream ordering and Cartesian products.
Suite: scoped
Requires: executable=python3; scope=test
import json
import os
import subprocess
jq = os.path.join(os.getcwd(), "jq")
streams = subprocess.run(
[jq, "-c", "1,2,3"],
capture_output=True,
text=True,
)
assert streams.returncode == 0
assert [json.loads(line) for line in streams.stdout.splitlines()] == [1, 2, 3]
cartesian = subprocess.run(
[jq, "-c", "[1,2] as $a | [3,4] as $b | [$a,$b]"],
capture_output=True,
text=True,
)
assert cartesian.returncode == 0
assert json.loads(cartesian.stdout) == [[1, 3], [1, 4], [2, 3], [2, 4]]
=== END AC composition-cartesian-streams ===
## User Acceptance
- None.
## Guardrails
- Preserve left-to-right generator ordering.
- Evaluate every multi-output argument combination required by jq.
- Array and object construction must collect generated values without dropping or duplicating outputs.
=== END ARTIFACT ===Run artifact