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: satisfied pending final recipe scan.

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
• optional PWA/offline: docs/recipes/pwa-offline.md

Remaining before GOAL_DONE:

• Confirm whether SQLx/auth/observability/deploy/PWA 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, run the closure audit with the full gates from the active goal, including cargo run -p hemx-xtask -- test and the full diagnostics scan.