hemx/PLAN.md

PLAN

Current outcome: make Hemx internals easier to change without altering public behavior, generated contracts, diagnostics, or portability.

HMX-M01 — Isolate template authoring validation

Outcome: template authoring validation is privately owned without public, diagnostic, ordering, or fingerprint drift. Delta: architecture/001 assurance/001 Checks: cargo test -p hemx-build; focused contract/fingerprint/diagnostic checks; Redgate; diff check; fresh-context review. State: Done Blocked by: none

HMX-M02 — Isolate Rust source fact extraction

Outcome: hemx-build Rust/syn fact collection has one private owner independent of template validation and emission. Delta: architecture/002 assurance/001 Path: application Rust source -> syntax facts -> generated component/form/handler contract -> deterministic artifact. Build: move the whole fact model, syn traversal, and related tests together; retain the existing host-only dependency boundary. Risk: reordered facts or changed path handling alters generated contracts or fingerprints. Checks: cargo test -p hemx-build; generated-contract semantic and fingerprint fixtures; Wasm target tree gate; redgate check. Non-goals: replacing syn, changing generated vocabulary, or introducing a generic analysis framework. Residual risk: overlaps hemx-build/src/lib.rs; implement after HMX-M01 to avoid conflicting movement. State: Draft Blocked by: HMX-M01

HMX-M03 — Isolate artifact emission and diagnostics

Outcome: generated Rust, metadata, lowering tables, and contract diagnostics are emitted through one private boundary behind the public builder. Delta: architecture/003 assurance/001 Path: validated template and Rust facts -> stable IDs/metadata -> generated files -> downstream compilation diagnostics. Build: move artifact assembly and diagnostic formatting as one responsibility; keep public entry points and no-op write behavior in place. Risk: byte, ordering, fingerprint, or diagnostic drift breaks downstream builds despite compiling locally. Checks: cargo test -p hemx-build; exact generated API/diagnostic/fingerprint fixtures; no-op rewrite check; package archive checks; redgate check. Non-goals: a new IR, new serialization, public API changes, or formatting-only rewrites. Residual risk: this is the broadest movement slice and requires fresh-context review after integrated proof. State: Draft Blocked by: HMX-M02

HMX-M04 — Localize Axum interaction forms

Outcome: media-type enforcement, body limits, URL-encoded/multipart extraction, typed decoding, and rejections have one private Axum owner. Delta: architecture/004 assurance/002 Path: HTTP request -> InteractionRequest extraction -> typed Form<T> or custom multipart model -> registered handler/rejection. Build: move the complete form boundary with its tests; add compile coverage for documented Form<T> spellings and custom FromInteractionForm extraction. Risk: extraction order, limits, rejection status/body, or public adapter signatures change. Checks: cargo test -p hemx-axum; cargo test -p hemx-derive; focused URL-encoded, multipart, limit, rejection, and compile-pass/fail assertions; redgate check. Non-goals: framework-owned CSRF/auth policy, a general extractor abstraction, or changing native form semantics. Residual risk: none beyond the existing application-owned security policy boundary after focused route proof. State: Ready Blocked by: none

Closure

Run all repository-required Redgate, fmt, clippy, workspace test, license, Wasm graph, and package archive gates. Finish with a fresh-context blocker-only review against INTENT.tsv, SPEC.tsv, this plan, the actual diff, and proof outputs. Keep hemx-core, hemx-js, hemx-derive, and public package boundaries cohesive unless a later validated responsibility seam requires change.