hemx/PLAN.md

Hemx v1 implementation plan

Authority: REQUIREMENTS.md. Product evidence: docs/v1-product-evidence.md. This file is an execution cursor, not requirement authority or release permission. Publishing, deployment, artifact upload, and package-registry mutation are out of scope.

Product boundary

Hemx v1 keeps server-rendered HTML and ordinary Rust as the default. Generated resources and the versioned EffectBatch are the one UI contract. Client-local WASM and durable sync are optional execution layers, not a component framework. Hemplate remains the rendering/Surface foundation; application auth, persistence, encryption, retention, backup, and deployment policy remain host concerns.

Slice 1 — one real client-local handler

• User value: a Rust author marks one high-frequency handler local and gets immediate browser behavior without app-authored JavaScript or a request.
• State: In progress. Client handlers now receive versioned ClientEvent/root-owned ClientState; incompatible input is rejected before handler execution, reports an actionable hemx:client-error, restores pending UI, and invokes an explicitly declared server fallback. Real WASM still applies the ordinary generated-target EffectBatch with zero request on valid input. Generated bootstrap must replace the browser proof's manual import/registration glue before the slice is complete.
• Build: add the smallest optional hemx-wasm boundary for #[hemx::handler(client)]; export only opted-in handlers; generate typed event/state ABI glue; run one existing generated-target interaction through the ordinary EffectBatch interpreter; preserve an explicit native/server fallback.
• Refusals: no VDOM, component lifecycle, global store, sync queue, second effect protocol, or generic WASM framework.
• Requirements: client_local/001-010, security/001, security/005-006, performance/003, v1_release/001.
• Proof: cargo test -p hemx-wasm --test browser client_handler_applies_effect_batch_without_network -- --exact visibly updates a generated target through real WASM, keeps the resource count unchanged for valid input, and proves invalid state diagnostics, pending restoration, and one declared fallback request. Slice completion additionally requires generated bootstrap with no app-authored JavaScript plus unchanged server handlers and formatting/workspace tests/strict all-target Clippy/wasm-target checks.

Slice 2 — direct manipulation that survives interruption

• User value: Kanban drag/reorder follows the pointer immediately, remains keyboard operable, and cannot apply stale work after cancellation or root removal.
• State: Blocked by Slice 1.
• Build: use the client handler in the canonical Kanban path; add cancellation/supersession, root-owned state cleanup, keyboard equivalent, focus/status behavior, reduced-motion behavior, and measured response/frame budgets.
• Refusals: no persistence, collaboration, or animation framework yet.
• Requirements: client_local/011-014, accessibility/001-007, operations/002-003, performance/001, performance/003, milestone/001.
• Proof: browser tests cover pointer and keyboard reorder, cancellation, removal/remount, error recovery, focus/status, reduced motion, zero request, no leaked listeners/timers, and named latency/frame thresholds.

Slice 3 — durable offline command log

• User value: an opted-in Kanban mutation remains available after network loss and browser reload without storing DOM patches as truth.
• State: Blocked by Slice 2.
• Build: add an optional durable command-log adapter around platform transactional storage; persist versioned command ids and app payload before projection; restore projection after reload; expose queue state, export/delete/reset, quota/corruption failure, and migration refusal.
• Refusals: no server reconciliation, CRDT, mandatory IndexedDB, credential storage, or policy hidden in core.
• Requirements: local/001-004, sync/009, sync/014-015, sync/020, security/007, performance/006.
• Proof: browser scenario mutates offline, reloads, restores the projection, exports/deletes/reset data, and fails recoverably under quota, corruption, and unknown schema without claiming durability after persistence failure.

Slice 4 — authoritative reconnect and convergence

• User value: offline and concurrent work reconnects without duplicate mutation, silent loss, stale authorization, or ambiguous conflict.
• State: Blocked by Slice 3.
• Build: materialize hemx-sync over an integration transport with idempotent server command processing, snapshot/change cursor, durable acknowledgements, bounded ordered replay, current auth checks, rejection/conflict results, canonical replacement, reconnect jitter/backoff, multi-tab coordination, and redacted diagnostics.
• Refusals: no default CRDT, transport in core, cached enqueue-time permission, unbounded queue, or silent last-write-wins policy.
• Requirements: sync/001-023, operations/001-005, security/002-005, performance/004-005.
• Proof: deterministic browser/server test covers offline → reload → reconnect, duplicate and reordered delivery, authorization revocation, rejection, conflict, missing history/fresh snapshot, two tabs, backpressure, and final convergence.

Slice 5 — local-first multiplayer Kanban milestone

• User value: the complete north-star app demonstrates SSR-first startup, direct manipulation, offline durability, optimistic projection, reconciliation, and live presence as one comprehensible workflow.
• State: Blocked by Slice 4.
• Build: connect the previous slices in the canonical Kanban example; keep native server-rendered fallback; add presence and server-canonical conflict presentation; exercise deploy fingerprint recovery and accessible online/offline/conflict state.
• Refusals: no demo-only runtime, hidden app JS, proprietary service, or requirement to load collaboration code for server-first apps.
• Requirements: milestone/001, v1_release/001-002, accessibility/001-007, operations/006, performance/006.
• Proof: one browser journey covers SSR/no-script fallback, local drag, keyboard reorder, offline/reload, concurrent peer edit, reconnect/convergence, presence, conflict/rejection recovery, mixed-version reload, and optional-asset isolation.

Slice 6 — production integration reference

• User value: adopters can copy a proven boundary for durable storage, auth, transactions, security controls, observability, and restart recovery without hemx owning vendor policy.
• State: Ready after public execution/sync contracts stabilize.
• Build: evolve one existing reference app using ordinary integration adapters; add durable app storage, authenticated/authorized allowed and denied mutations, CSRF/origin checks, transaction rollback, bounded input, structured failures, health/readiness, tracing/metrics hooks, and restart/deploy recovery.
• Refusals: no built-in database/auth provider, compliance claim, telemetry vendor, deployment system, or repository framework.
• Requirements: security/001-009, operations/001-008, v1_release/003, existing adapter/*, integration/*, and diagnostics/* contracts.
• Proof: end-to-end test survives process restart and mixed deployment, proves allowed/denied/rolled-back mutations and redacted diagnostics, and maps each framework-owned ASVS-relevant control to a failing/passing case.

Slice 7 — v1 compatibility and closure

• User value: maintainers and adopters receive a reproducible, migration-aware v1 with no known material contradiction and no hidden publication side effect.
• State: Blocked by Slices 1-6 and explicit authority for any missing local audit tool installation.
• Build: freeze the supported Rust/browser/WASM/integration matrix; reconcile public/generated/Surface/symbol/wire/runtime/persisted-schema compatibility; add migration fixtures; make canonical examples compatibility tests; update the progressive tutorial path; run all local release gates and disposition every P0/P1, advisory, unsafe-code, license, performance, accessibility, and documentation finding.
• Refusals: no publish, deploy, upload, store submission, speculative feature, or weakening a gate to make it pass.
• Requirements: v1_release/001-010, versioning/*, test/*, diag/*, performance/*, security/008, and all requirements changed by the preceding slices.
• Proof: clean-tree formatting, workspace tests, strict all-target Clippy, compile-fail, browser/WASM/offline/multiplayer scenarios, benchmark budgets, approved pinned lockfile audit, requirements proof audit, docs/examples checks, and independent contradiction review all pass with no unresolved P0/P1.