Stack 2/5: Graph & contracts — reflection API, windowed limits, cross-field rules (rounds 5-7)

[codenamev]

Second slice (rounds 5-7), stacked on #1.

Framework

• PlanOrchestrator#graph: frozen topology snapshot — order (Kahn's, cycles appended), labeled edges from needs:, stats (per-task depth, max_depth, max_fan_in)
• RateLimit: windowed quota mode (per:), composition via #and (quota + connection pool at once)
• Contract constraints beyond type/presence: enum:, min:/max:, non_empty:; cross-field rules: (all violations reported at once, structured rules with fields:/rule_violations); ValidationError#expectations
• CapabilitySpecification#to_json_schema (draft-07 export)
• Retry: backoff_jitter default with :full variant, injectable rng: for deterministic tests
• Journal durations keyed by description (perf baselines)

Examples & docs

• Rounds 5-7 persona builds: critical path, plan diagram, freight rules, 422 renderer, jitter shootout, plan round-trip with isomorphism proof, incident report, capability evals, and the referee pattern (exit-code-gated honesty tools)

Stacked on #1; stacked under the operations slice. Review focus: lib/plan_orchestrator.rb (graph), lib/rate_limit.rb, lib/capability_validator.rb.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FeZLdZ3M4q4cho4DZPfSkF

---

Generated by Claude Code

[codenamev]

Persona review panel: Samuel Williams, Jeremy Evans, Xavier Noria. Verified locally: 562 examples, 0 failures at this cut.

---

Samuel Williams (ioquatix) — The limiter grows the right two shapes: a windowed mode (per:) for quota physics and #and composition for the real-world case of two laws at once (billed quota + connection pool). Composition acquiring outermost-first and the Composite flattening nested composites: correct, and the acquire-order comment ("own share first, then the door") matters — the reverse order is deadlock-shaped. One boundary to state plainly: at this cut the windowed stamp bookkeeping is check-then-act without a mutex — fine under a single reactor, coasting on the GVL under threads. I see slice 4 pays that debt properly; approving this slice with the caveat on the record rather than demanding churn here.

Jeremy Evans — Validation does the two things I insist on: it collects every violation instead of failing on the first (a bad payload should cost one round trip, not five), and ValidationError#expectations carries the declared contract for each violated key, so callers can render what would have been legal without side-channel knowledge. Cross-field rules: running only after per-key validation passes is the right sequencing — rules can assume typed values. enum/min/max/non_empty mapping onto dry-schema predicates rather than hand-rolled checks: good, use the library you already load. The injectable retry rng: earns its keyword — deterministic jitter tests instead of sleepy flaky ones. Approve.

Xavier Noria (fxn) — #graph is a reflection API done with care: everything in the snapshot is duped and frozen (a reflection API that hands out live internals is a mutation API with plausible deniability), order is Kahn's with cycle members appended rather than silently dropped — the difference between a tool that degrades and one that lies — and edge labels derive from needs: so the two representations of naming can't drift apart at birth. The stats block (depth/max_depth/max_fan_in) computed once here saves every downstream tool a hand-rolled walk; later slices prove that bet pays. Approve.

---

Panel verdict: approve (as comment; self-approval disallowed). No new action items — the windowed-mutex caveat is already fixed in slice #4.

---

Generated by Claude Code