docs(v1): define evidence-backed production contract

req: client_local/005\nreq: sync/009\nreq: accessibility/001\nreq: operations/001\nreq: security/001\nreq: performance/001\nreq: v1_release/001

PLAN.md

@@ -1,19 +1,76 @@
-# hemx plan
+# Hemx v1 implementation plan
 
-This is a small work surface for explicitly delegated hemx follow-up. `REQUIREMENTS.md` remains the requirement authority; this file only records execution intent.
+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.
 
-## URL-as-state page navigation primitive
+## Product boundary
 
-User value: server-first apps can build browse/search/filter pages whose URL is the durable state, so reload, bookmarks, sharing, copy/paste, and back/forward work without app-owned client state or search frameworks.
+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.
 
-State: Done
+## Slice 1 — one real client-local handler
 
-Build:
-- Document the URL-as-state contract for enhanced GET forms and page swaps: native successful controls serialize into the URL; committed submits push history; high-frequency filter typing may replace history; normal reload/no-JS behavior remains native. req: page_swap/009
-- Convert or add one html_examples browse/search example that uses a plain GET form plus generated page/target helpers to prove query-string state round-trips through server-rendered page state. req: page_swap/009 req: htmx_equivalents/005
-- Add focused runtime/browser smoke that changes a GET query, verifies the URL, reloads or uses back/forward, and observes the same rendered state without hidden client state. req: page_swap/005 req: page_swap/009
-- Keep the primitive subtractive: refuse an omnisearch framework, router, selector include model, client state graph, or domain search API in hemx core; use generated forms, page swap, and `Navigate` only. req: page_swap/003 req: page_swap/009 req: page_swap/010 req: htmx_equivalents/003
+- [ ] **User value:** a Rust author marks one high-frequency handler local and gets immediate browser behavior without app-authored JavaScript or a request.
+- **State:** Ready.
+- **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:** real WASM/browser test visibly updates a generated target, network capture remains empty, invalid event/state restores pending UI with a diagnostic, server handlers are unchanged, and formatting/workspace tests/strict all-target Clippy/wasm-target checks pass.
 
-Blocked by: none.
+## Slice 2 — direct manipulation that survives interruption
 
-Proof: `cargo run -p hemx-xtask -- html-examples-smoke`, focused runtime/page-swap tests, `redgate lint`, and `redgate health --strict` pass with an example showing URL state survives reload/back/forward.
+- [ ] **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.