FEATURE: Reductions and Iteration Controls

Field	Value
Version	20260822 V1
Description	Provides jq reductions and generator iteration-control builtins.
Depends On	ARCHITECTURE.md, FEATURE-FLOW-004.md
Provides	reduce, foreach, range, limit, skip, first, last, nth
Consumes	ordered generator evaluator, lexical labels, variable bindings

Workflow

Reduction and iteration controls consume ordered generator streams and preserve jq's state, ordering, Cartesian argument, backtracking, and short-circuit semantics.

reduce EXP as $var (INIT; UPDATE) accumulates each generated value.
foreach EXP as $var (INIT; UPDATE; EXTRACT) emits intermediate extracted values.
range supports one, two, and three argument forms.
limit, skip, first, last, and nth operate on generated streams.
Invalid negative counts for limit, skip, and nth raise runtime errors.

Programmatic Acceptance

=== AC flow-005-conformance ===
Intent: The executable passes the authoritative conformance cases exercising reductions and iteration controls.
Suite: scoped
Requires: executable=python3; scope=test

import json import os import subprocess import sys

SELECT = r"reduce|foreach|limit|skip|nth|first|last" result = subprocess.run( [sys.executable, "sources/run_conformance.py", "--select", SELECT, "--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) tally = report["summary"] assert sum(tally.values()) > 0 assert tally["fail"] == 0 and tally["error"] == 0 assert result.returncode == 0 === END AC flow-005-conformance ===

User Acceptance

Reduction and iteration filters preserve output ordering and generator multiplicity.

Guardrails

Do not replace generator evaluation with single-value evaluation.
Preserve runtime errors and partial output semantics.