@nhtio/adk/batteries/orchestration/validation

Submit-time validation and the lifecycle machine.

Remarks

This module owns the freeze gate: it folds a plan's op log into a RawPlanView, runs every submit check over that folded graph, and — only on a clean pass — commits the editable → reviewable transition. It is the "the battery validates, the store commits" split made concrete: every check here is battery policy a bring-your-own store has no business reimplementing, and the store's transition is the only boundary that can atomically move the lifecycle state.

The two exported functions are the whole surface:

• collectIssues — the pure-ish validator. Given a folded view and the injected FreezeInputs (the tier-C allowlist and the wired predicate cells), it returns every PlanIssue the graph raises. It never throws on a well-typed-but-invalid plan; a malformed definition surfaces as an issue, not a crash.
• freezePlan — the lifecycle entry point. It folds the log, runs collectIssues, and only when no issue is blocking calls store.transition(editable → reviewable, {expectedDigest}). The digest is what makes the commit safe rather than racy: content is validated at digest D and the store commits only if the plan is still at D, so a concurrent edit invalidates the transition instead of slipping past an already-passed check.

Every refusal is a PlanIssue with a stable code, a model-addressed message naming the fix, the nodeId/edgeId where applicable, and a severity. Blocking issues refuse the freeze; advisory issues are surfaced for the author but do not stop the transition.

The checks are grouped into three families, each documented at its call site: topology (entry, reachability, acyclicity, the diamond-join rule, id and handle rules), references and dataflow (dangling refs, undeclared fields, join-crossing selections, ambiguous references, taint), and per-node shape (call, transform, branch/select, encodability, scaffold placeholders, unreachable calls).

Functions

Function	Description
collectIssues	Run every submit check over a folded plan view.
freezePlan	Freeze a plan: fold the log, validate, and commit the editable → reviewable transition.