Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (36 loc) · 3.63 KB

AGENTS.md

File metadata and controls

44 lines (36 loc) · 3.63 KB
Raw

Agent orientation — jq state engine (Phase 6 prep)

Audience: zero-context agent. Goal: boot into the jq-like state engine, know current constraints/status, and execute Phase 6 work without surprises.

Engine snapshot

  • Python jq-like filter engine mutating a ref-sharded JSON state with deterministic writes.
  • Core files: python/chatter/state.py (store/ref graph/runtime), python/chatter/state_filter.py (parser/AST), python/chatter/cli.py + python/chatter/report.py (entry points), tests under python/tests/.
  • Refs/routing: ref file://... mounts shards; ref state://... aliases other paths (/, ~/, relative). Keys follow verbiage rules; writes routed to owners and validated atomically.
  • Commit policy: assignments (incl. slices) require exactly one RHS output; |= deletes on empty; multi-output RHS errors. No jq commit-compat flag.
  • Stream mode: --stream [--stream-input <path>|-] feeds JSON/NDJSON events; mutations blocked; commit policy still applies elsewhere.

Current status (through Phase 5)

  • Language: jq-like parser/control flow (foreach/reduce/while/until/limit/label/break), iterators .[]/.[]?, variables/defs/as/try, streaming selectors first/last/nth, kind-aware paths.
  • Path semantics: optional hops skip missing/non-indexable only; slices assign [start:end]; paths(predicate|kind), path(expr), leaf_paths emit concrete key/index paths; tolerant getpath/setpath/delpaths plus strict getpath_strict/setpath_strict that error on missing/non-indexable.
  • Runtime ops: truthiness matches jq; binary ops lift; + merges objects with null identity; - removes keys/array elems; * deep-merge/str repeat; / splits strings; % numeric.
  • Streaming helpers: tostream, fromstream, state_chunks (size>0) available; stream mode read-only.
  • Evidence: latest full-suite pass logged in phase5/VALIDATION-LOG.md (60 tests); rerun after changes.

Constraints and reminders

  • Preserve commit policy, ref routing/validation, and stream read-only behavior; keep optional-path semantics intact.
  • ASCII edits only unless justified; avoid reverting user changes; no destructive git resets.
  • Follow docs/brainstorm.md and docs/planning.md when planning; use docs/refresh.md for future AGENTS refreshes.

Phase 6 focus (planned, not implemented yet)

  • String/regex/encoders: explode/implode, ascii_upcase/downcase, indices, bsearch, regex flags and capture, format/printf subset, encoders @csv/@tsv/@json/@sh.
  • Encoding/time: base64encode/decode, uri_encode/decode, now, todate, fromdate.
  • Inputs: input/inputs/slurp parity with deterministic source (do not assume stdin; consult Phase 6 plan for gating).
  • Object/array helpers: multi-path del, array has, group, scalar min/max, inside, enhanced range, transpose error parity.
  • Scope: honor jq parity unless extensions conflict; maintain commit/ref/stream constraints.

How to run/validate

  • Full suite: PYTHONPATH=python python3 -m pytest python/tests.
  • Evidence: see phase5/VALIDATION-LOG.md; update logs when you rerun tests.
  • Use repo docs/tests as oracle; add targeted tests for new builtins.

Where to read next

  • JQ-STATE-OVERVIEW.md — engine semantics and constraints.
  • JQ-STATE-PARITY-PHASE-6.md — Phase 6 scope and semantics expectations.
  • JQ-STATE-PARITY-PHASE-5.md — path semantics delivered in prior phase.
  • docs/refresh.md — how to refresh this page next time.

Work ahead

  • Implement and test Phase 6 builtins per plan; keep input helpers deterministic and gated; preserve existing semantics.
  • Run full pytest before declaring done; log results in VALIDATION-LOG.md (and phase-specific logs if used).