# 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: satisfied pending final closure verification.

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

Remaining before GOAL_DONE:

- Run the final closure audit and full gates on a clean tree.

### 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 app,
  `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:

- Run the final recipe scan and confirm links from the tutorial and README remain
  complete.

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

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

Run the closure audit with the full gates from the active goal, including
`cargo run -p hemx-xtask -- test`, the full diagnostics scan, forbidden
normal-path scans, and a final critic review before any GOAL_DONE claim.