Skip to content

PHASE-AUDIT.md

Latest commit

 

History

History
29 lines (23 loc) · 3.81 KB

PHASE-AUDIT.md

File metadata and controls

29 lines (23 loc) · 3.81 KB
Raw

Phase 1–4 audit (post Phase 3 completion, pre Phase 4 stream mode)

Audience: maintainers/implementers. Purpose: capture the current state after completing Phases 1–3, assess Phase 4 alignment with our conventions and jq parity goals, and flag adjustments needed to keep the state engine powerful and coherent.

Current state (Phases 1–3 implemented)

  • Parser/runtime parity: jq-style operators, comparisons, optionals (missing/non-indexable only), [start:end] slices, iterators .[]/.[]?, as (original input), try default catch empty with early abort, binary op Cartesian lifting. Def params follow jq (filter/value) with streaming outputs.
  • Control flow/iteration: foreach, reduce, while/until, limit, label/break (control flow, acts like empty, not catchable), streaming first/last/nth implemented as generators. Loop guard present (iteration cap).
  • Commit policy (stateful extension): single-output required for mutations/slices; |= deletes on empty; multi-output RHS errors. No jq-compat flag yet for |= first-value mode. Assignments remain deterministic for ref-routed storage.
  • Refs: ref graph build/expand/routing intact; non-conflicting extension.
  • Streaming helpers in runtime: tostream(val) emits jq-style [path, leaf]/[path] events; fromstream reconstructs; state_chunks(array, size) splits arrays with validation. CLI stream mode is implemented (JSON/NDJSON input or current state) and is read-only.
  • Tests/docs: Updated through Phase 3 constructs; stream tests cover tostream/fromstream/chunking/mutation guard; full suite passing. Docs capture Phase 1–3 semantics, commit policy, and stream flag basics.

Phase 4 plan vs current trajectory

  • Plan goals: CLI stream mode (--stream/NDJSON) defaulting to read-only; path/value emission matching jq; optional inputs/slurp analogs; chunk helper; mutation guard in stream mode; docs/tests covering stream semantics and safety.
  • Alignment: Stream mode now feeds tostream-compatible events (JSON/NDJSON or current state), prints outputs as NDJSON, and blocks mutations. No inputs/slurp yet; write gating beyond the default guard is still undecided.
  • Extension safety: We must avoid new jq-conflicting syntax. Prefixed helpers (state_*) are okay for state-specific features (chunks, state_slurp if needed). Reuse jq names only when semantics match (e.g., tostream/fromstream).

Risks/adjustments needed for Phase 4

  • Inputs/slurp semantics: If added, ensure behavior matches jq; otherwise prefix and document as extensions to avoid collision/confusion.
  • Mutation policy in stream mode: Keep single-output commit rule; if writes allowed, require atomic multi-file commit; document clearly. Otherwise, fail fast on mutations in stream mode (current behavior).
  • Docs/tests gap: If new streaming helpers or write gates are added, extend docs/tests accordingly; current stream flag, event order, and mutation guard are covered.
  • Helper naming: state_chunks already prefixed; keep that pattern for any state-specific helpers; only use jq names (tostream/fromstream) when matching jq behavior.

Parity stance for Phase 4

  • Target jq parity for stream emission shape/order (tostream/--stream behavior), read-only default, and composition with existing filters. Where the state engine must diverge (commit policy, refs), keep divergences explicit and outside jq syntax.
  • Use jq differential tests (tostream/fromstream round-trips, small nested fixtures) as oracles for event ordering if more coverage is needed.

Summary

Phases 1–3 are solid and parity-aligned with an explicit, documented commit policy. Phase 4 now has CLI stream mode with mutation guard; remaining choices are scoped to inputs/slurp and any optional write gate. Avoid new jq keyword/operator collisions; prefer prefixed helpers for state-specific needs.