# 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.