hemx/docs/v1-readiness.md

v1 readiness audit

This audit records the proven server-first/page-enhanced baseline. It is not a marketing release announcement and no longer claims the full v1 north star is closed. The product evidence in docs/v1-product-evidence.md and current requirements add client-local WASM, durable offline/sync, accessibility, security, operations, performance, compatibility, and production-reference closure. Their implementation order lives in PLAN.md. req: examples/001 req: public_api/001 req: v1_release/001

Current status

• Server-first and page-enhanced baseline: proven by the evidence below.
• Client-local WASM: real generated-resource browser/WASM execution proven.
• Durable offline/sync and multiplayer milestone: framework-owned replay, acknowledgement, convergence, presence, recovery, and accessibility proven.
• Production reference: authenticated mutation, origin/CSRF denial, atomic rollback-safe persistence, restart recovery, health/readiness, diagnostics, metrics, CSP, and mixed-build fail-closed recovery proven.
• V1 closure matrix: not closed. The recorded local workspace, browser, performance, docs, and example gates pass, warning-denied vulnerability and source audits are clean, and the mutation-applicable library/proc-macro matrix has no unexplained survivors. Strict license closure still awaits an owner-chosen license for 20 currently unlicensed workspace packages and an allowlist decision for Apache-2.0, Apache-2.0 WITH LLVM-exception, BSD-3-Clause, BSL-1.0, MIT, Unicode-3.0, and Unlicense dependencies; this blocks a production-ready claim. req: test/020 req: test/021 req: v1_release/006
• Publishing and deployment: explicitly unauthorized.

Baseline evidence

Canonical tutorial app

Status: satisfied.

Evidence:

• examples/saas is a compile-tested tutorial app with typed domain values, #[hemx::form("new_project")], auth/session-shaped AppContext, CSRF-safe mutation, local persistence adapter, generated keyed row/form/summary/page/live effects, full-page route fallback for settings, enhanced page-panel swap, SSE/polling shape, plain CSS, one explicit metrics island, and tests.
• docs/tutorial-saas.md walks through the app from template to production provider handoff.
• docs/recipes/sqlx-persistence.md shows how to replace LocalProjectStore with an app-owned SQLx adapter without moving SQLx into core.

Release decision:

• The supported v1 production boundary is the compile-tested local persistence adapter plus provider-explicit recipes. SQLx/auth/observability/deploy/PWA stay app integrations rather than required workspace dependencies, so the tutorial remains runnable in CI without credentials or external services.

Beginner API stability

Status: satisfied for the current v1 goal.

Evidence:

• Normal path is documented around app, component, handler, form, page, generated helpers, tuple IntoEffect, and Result<impl IntoEffect, E> mapping.
• docs/versioning.md defines stable beginner API vs wire/runtime ABI vs advanced escape hatches.
• examples/v0 and examples/saas exercise the normal path without manual registries or raw ids in app authoring.

Advanced APIs isolated

Status: satisfied.

Evidence:

• README.md, docs/versioning.md, and docs/diagnostics.md identify raw effects, ids, render/target construction, manual registries, runtime hooks, SSE internals, and island internals as advanced.
• Public examples label v0 as beginner, examples/saas as the tutorial app, kanban as advanced/north-star, and techdemo as advanced.
• Forbidden-normal-path scans only hit explicit route/static asset serving, deploy/versioning text, or the examples/saas metrics island.

Docs explain the model in one sitting

Status: satisfied.

Evidence:

• README.md explains render → slot/key → effect → runtime, forms/errors, pages/push, CSS/islands, production boundaries, escape hatches, and deploy/version compatibility.
• docs/tutorial-saas.md provides the product walkthrough.
• Recipes cover SQLx, auth/session + CSRF, observability/flags/killswitches, deploy/versioning, and optional PWA/offline.
• docs/diagnostics.md and docs/versioning.md cover failure and release policy.

Diagnostics

Status: satisfied for the current v1 goal.

Evidence:

• docs/diagnostics.md names common mistakes and desired fixes in author language.
• Existing gates cover build diagnostics, derive compile-fail diagnostics, runtime root/fingerprint behavior, result-handler mapping, and example contract checks.
• Final diagnostics gates include cargo test -p hemx-build, cargo test -p hemx-derive --test compile_fail, cargo test -p hemx-js, and cargo test -p hemx-test --test examples_contract.

Production recipes

Status: satisfied.

Evidence:

• SQLx: docs/recipes/sqlx-persistence.md
• auth/session + CSRF: docs/recipes/auth-session-csrf.md
• observability/metrics + feature flags/killswitches: docs/recipes/observability-flags.md
• deploy/versioning: docs/recipes/deploy-versioning.md
• mobile release: docs/recipes/mobile-release.md
• optional PWA/offline: docs/recipes/pwa-offline.md

Public examples

Status: satisfied.

Evidence:

• examples/v0/README.md is the beginner entry.
• examples/saas/README.md identifies the production-shaped tutorial app.
• examples/kanban/README.md identifies Kanban as advanced/north-star.
• examples/techdemo/README.md identifies Techdemo as advanced.
• Contract tests guard against browser JavaScript and low-level resource plumbing in canonical examples.

Runtime remains tiny and selectorless

Status: satisfied.

Evidence:

• README.md, docs/versioning.md, docs/recipes/deploy-versioning.md, docs/recipes/observability-flags.md, and docs/recipes/pwa-offline.md keep runtime scope to checked effect application and reject VDOM/hydration/client store/selector-retargeting growth.
• examples/saas/templates/metrics.js uses selectors only inside an explicit leaf island, not for normal hemx targeting.
• cargo test -p hemx-js covers runtime root/fingerprint behavior.

Versioning explicit

Status: satisfied.

Evidence:

• docs/versioning.md defines semver tiers, wire/runtime ABI policy, advanced escape-hatch policy, upgrade-note template, and release checklist.
• docs/recipes/deploy-versioning.md documents release units, asset caching, rolling deploy behavior, fingerprint mismatch behavior, and rollback checks.

Final closure gates

The following baseline commands remain required. They are insufficient for full v1 closure until the browser/WASM/offline/multiplayer, accessibility, security, performance, compatibility, and production-reference proofs in v1_release/* also pass. Run them only as local validation; none publishes or deploys.

Run these on the final tree before GOAL_DONE:

cargo run -p hemx-xtask -- test
cargo run -p hemx-xtask -- mutation
cargo check --workspace
cargo test -p hemx-saas-example
cargo test -p hemx-v0-examples
cargo test -p hemx-build
cargo test -p hemx-js
cargo test -p hemx-derive --test compile_fail
cargo test -p hemx-test --test examples_contract
redgate list
redgate refs
redgate health
git diff --check

Also run the forbidden-normal-path scan over README.md, docs/, examples/v0, examples/saas, and the public advanced example READMEs. Expected remaining hits are explicit route/static asset serving, deploy/versioning docs, or explicit leaf-island JavaScript.