hemx/docs/v1-readiness.md

v1 readiness audit

This audit tracks the current hemx v1 northstar against the active Close when. It is a checkpoint, not the release announcement: update it before any GOAL_DONE or v1 tag. req: examples/001 req: public_api/001

Close-when status

Canonical tutorial app

Status: partially satisfied; not enough for GOAL_DONE.

Evidence:

• examples/saas is a compile-tested tutorial skeleton 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, 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.

Remaining before GOAL_DONE:

• Turn examples/saas from a skeleton into the canonical v1 close artifact: either add one checked production adapter path/profile, or make an explicit release decision that local persistence plus provider recipes is the supported v1 production boundary.
• If the release must prove a real DB provider in CI, add a feature-gated or companion SQLx-backed test instead of only a recipe.

Beginner API stability

Status: mostly satisfied; final release audit still required.

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.

Remaining before GOAL_DONE:

• Run a final API surface audit before v1 and either accept current names or make the last naming changes before declaring stability.

Advanced APIs isolated

Status: satisfied for docs/examples; final scan required.

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 skeleton, kanban as advanced/north-star, and techdemo as advanced.

Remaining before GOAL_DONE:

• Re-run the forbidden-normal-path scan over README, docs, and public examples; review any hits in explicit island/runtime/deploy sections as intentional.

Docs explain the model in one sitting

Status: mostly 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, and deploy/versioning.
• docs/diagnostics.md and docs/versioning.md cover failure and release policy.

Remaining before GOAL_DONE:

• Add a small docs index or check the root README is enough as the single entry point for all tutorial/recipe/versioning pages.

Diagnostics

Status: documented and substantially tested; coverage audit still required.

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, and example contract checks.

Remaining before GOAL_DONE:

• Run the full diagnostics gate and confirm each required mistake class has either an actual test or an explicitly accepted compiler diagnostic: missing handler/form/slot/key/param, invalid form field type, unknown hemx attribute, unsafe HTML boundary, wrong component/slot target, missing root/fingerprint, and bad result error type.

Production recipes

Status: mostly satisfied; optional PWA/offline remains unresolved.

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

Remaining before GOAL_DONE:

• Add a bounded optional PWA/offline recipe, or explicitly scope it out of v1 if optional adapters are not required for the release.
• Confirm whether SQLx/auth/observability/deploy recipes are sufficient as recipe-only production guidance or whether one provider path must be exercised by the tutorial crate before v1.

Public examples

Status: satisfied pending final scan.

Evidence:

• examples/v0/README.md is the beginner entry.
• examples/saas/README.md identifies the production-shaped tutorial skeleton.
• 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.

Remaining before GOAL_DONE:

• Re-run example contract tests and forbidden-pattern scans on a clean tree.

Runtime remains tiny and selectorless

Status: satisfied in core; final runtime gate required.

Evidence:

• README.md, docs/versioning.md, docs/recipes/deploy-versioning.md, and docs/recipes/observability-flags.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.

Remaining before GOAL_DONE:

• Run cargo test -p hemx-js and audit runtime diff before closure.

Versioning explicit

Status: satisfied pending final release check.

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.

Remaining before GOAL_DONE:

• Run final verification and confirm upgrade/versioning docs still match the current generated ABI/runtime behavior.

Recommended next waypoint

Make the production-shaped SaaS path closure decision concrete. The smallest implementation path is a bounded, checked provider slice for examples/saas (such as a feature-gated SQLx adapter test) if v1 must prove a real provider in CI; the smallest docs path is an explicit release decision that the local adapter plus provider recipes is the v1 production boundary.

After that, either add the optional PWA/offline recipe or explicitly scope it out of v1, then run the closure audit with the full gates from the active goal, including cargo run -p hemx-xtask -- test and the full diagnostics scan.