slhx agent
78aff362ff
Document optional PWA/offline support as an adapter boundary: cached shell, domain-command queues, server-canonical replay, conflict/fingerprint behavior, and sync-crate shape without adding a client state graph or service worker to core. req: canonical_authoring/008 req: runtime/003 req: runtime/004 req: auth/002 req: auth/004 req: failure/004 req: failure/005 req: sync/001 req: sync/007
186 lines
6.7 KiB
Markdown
186 lines
6.7 KiB
Markdown
# 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.
|