=== BEGIN ARTIFACT FEATURE-FLOW-005.md ===
# 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 |

## Questions

- None.

## 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.

=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-FLOW-006.md ===
# FEATURE: Recursive Generator Primitives

| Field       | Value |
|-------------|-------|
| Version     | 20260822 V1 |
| Description | Provides jq recursive generator and recursive-descent primitives. |
| Depends On  | ARCHITECTURE.md, FEATURE-FLOW-005.md |
| Provides    | while, until, repeat, recurse, recursive descent |
| Consumes    | ordered generator evaluator, runtime error model |

## Questions

- None.

## Workflow

Recursive generators repeatedly apply filters while preserving jq stream order and termination behavior.

- `while(cond; update)` emits each qualifying value before continuing.
- `until(cond; next)` continues until its condition succeeds.
- `repeat(exp)` continues until the expression raises an error.
- `recurse` emits the current value and recursively generated descendants.
- `..` provides recursive descent equivalent to zero-argument `recurse`.

## Programmatic Acceptance

=== AC flow-006-conformance ===
Intent: The executable passes the authoritative conformance cases exercising recursive generators and recursive descent.
Suite: scoped
Requires: executable=python3; scope=test

import json
import os
import subprocess
import sys

SELECT = r"while|until|recurse|repeat"
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-006-conformance ===

## User Acceptance

- Recursive filters terminate and preserve the documented depth-first output order.

## Guardrails

- Do not introduce incorrect termination for generators that intentionally produce repeated values.
- Preserve runtime error behavior for `repeat`.

=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-FUNC-001.md ===
# FEATURE: Lexical Variable Bindings

| Field       | Value |
|-------------|-------|
| Version     | 20260822 V1 |
| Description | Provides jq lexical value bindings and variable lookup. |
| Depends On  | ARCHITECTURE.md, FEATURE-FLOW-006.md |
| Provides    | as bindings, variable lookup, lexical scope, shadowing |
| Consumes    | generator evaluator, parser AST |

## Questions

- None.

## Workflow

Bindings evaluate the left-hand filter as a generator, bind each produced value lexically, and run the remainder of the expression with the original input and the active binding environment.

- `EXP as $name | REST` supports multiple generated bindings.
- Bindings are immutable and lexically scoped.
- Nested bindings may shadow outer names without mutating them.
- Keyword identifiers may be used as binding names.
- Array and object patterns bind missing members as `null`.

## Programmatic Acceptance

=== AC func-001-conformance ===
Intent: The executable passes the authoritative conformance cases exercising lexical bindings and variable lookup.
Suite: scoped
Requires: executable=python3; scope=test

import json
import os
import subprocess
import sys

SELECT = r" as \$|\$[A-Za-z]"
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 func-001-conformance ===

## User Acceptance

- Variable values remain available only within their lexical scope and preserve generator backtracking.

## Guardrails

- Do not implement bindings as mutable global variables.
- Do not leak nested or out-of-scope bindings.

=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-FUNC-002.md ===
# FEATURE: Function Parameters

| Field       | Value |
|-------------|-------|
| Version     | 20260822 V1 |
| Description | Provides jq filter parameters, value parameters, and multi-arity calls. |
| Depends On  | ARCHITECTURE.md, FEATURE-FUNC-001.md |
| Provides    | filter parameters, value parameters, function arities, Cartesian function calls |
| Consumes    | lexical variable bindings, generator evaluator |

## Questions

- None.

## Workflow

User-defined functions accept filter parameters as reusable generators and value parameters as captured values.

- Regular identifiers in parameter lists represent filter parameters.
- `$`-prefixed parameters represent value parameters.
- Arguments preserve jq's generator and Cartesian-product semantics.
- Functions support multiple arities and repeated parameter invocation.
- Closures retain the lexical environment active at definition and call sites.

## Programmatic Acceptance

=== AC func-002-conformance ===
Intent: The executable passes the authoritative conformance cases exercising filter and value function parameters.
Suite: scoped
Requires: executable=python3; scope=test

import json
import os
import subprocess
import sys

SELECT = r"def .*\("
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 func-002-conformance ===

## User Acceptance

- Function arguments behave as filters or values according to their declaration form.

## Guardrails

- Do not eagerly collapse filter arguments to one value.
- Preserve repeated invocation and Cartesian output behavior.

=== END ARTIFACT ===
=== BEGIN ARTIFACT FEATURE-FUNC-003.md ===
# FEATURE: Function Definitions and Recursion

| Field       | Value |
|-------------|-------|
| Version     | 20260822 V1 |
| Description | Provides jq function declarations, lexical function scope, and recursion. |
| Depends On  | ARCHITECTURE.md, FEATURE-FUNC-002.md |
| Provides    | def declarations, lexical function scope, redefinition, recursion, forward/self references |
| Consumes     | function parameters, lexical variable bindings |

## Questions

- None.

## Workflow

Function definitions introduce named filters into lexical scope and support recursive evaluation.

- `def name: FILTER;` defines a zero-arity function.
- Parameterized definitions support filter and value parameters.
- Definitions are resolved lexically and may refer to themselves recursively.
- Redefinition replaces only the matching arity for subsequent references.
- Function calls preserve generator ordering, closures, and backtracking.

## Programmatic Acceptance

=== AC func-003-conformance ===
Intent: The executable passes the authoritative conformance cases exercising function definitions, scope, redefinition, and recursion.
Suite: scoped
Requires: executable=python3; scope=test

import json
import os
import subprocess
import sys

SELECT = r"def "
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 func-003-conformance ===

## User Acceptance

- Recursive and redefined functions resolve according to jq's lexical scoping rules.

## Guardrails

- Do not resolve function names through mutable global state.
- Preserve self-reference, recursion, and generator backtracking.

=== END ARTIFACT ===