slhx agent
e9ced4e0c1
Elect one canonical EffectBatch codec, remove the parallel postcard API, and strengthen fail-closed host, form, sync, WASM, macro, generated-contract, and test-harness proofs with mutation-driven coverage. req: wire/008 req: wire/009 req: wire/010 req: push/008 req: client_local/015 req: client_local/016 req: client_local/017 req: client_local/018 req: client_local/019 req: sync/024 req: sync/025 req: sync/026 req: sync/027 req: sync/028 req: sync/029 req: test/020 req: test/021
190 lines
7.2 KiB
Markdown
190 lines
7.2 KiB
Markdown
# v1 readiness audit
|
|
|
|
This audit records the proven server-first/page-enhanced baseline. It is not a
|
|
marketing release announcement and no longer claims the full v1 north star is
|
|
closed. The product evidence in `docs/v1-product-evidence.md` and current
|
|
requirements add client-local WASM, durable offline/sync, accessibility,
|
|
security, operations, performance, compatibility, and production-reference
|
|
closure. Their implementation order lives in `PLAN.md`. req: examples/001 req: public_api/001 req: v1_release/001
|
|
|
|
## Current status
|
|
|
|
- Server-first and page-enhanced baseline: proven by the evidence below.
|
|
- Client-local WASM: real generated-resource browser/WASM execution proven.
|
|
- Durable offline/sync and multiplayer milestone: framework-owned replay,
|
|
acknowledgement, convergence, presence, recovery, and accessibility proven.
|
|
- Production reference: authenticated mutation, origin/CSRF denial, atomic
|
|
rollback-safe persistence, restart recovery, health/readiness, diagnostics,
|
|
metrics, CSP, and mixed-build fail-closed recovery proven.
|
|
- V1 closure matrix: not closed. The recorded local workspace, browser,
|
|
performance, docs, and example gates pass, and warning-denied vulnerability
|
|
and source audits are clean. Strict license closure still awaits a repository
|
|
license allowlist, and the mutation-testing release gate is only partially
|
|
classified. These open gates block a feature-complete or production-ready
|
|
claim. req: test/020 req: test/021 req: v1_release/006
|
|
- Publishing and deployment: explicitly unauthorized.
|
|
|
|
## Baseline evidence
|
|
|
|
### Canonical tutorial app
|
|
|
|
Status: satisfied.
|
|
|
|
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, full-page route fallback for settings, enhanced page-panel swap,
|
|
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.
|
|
|
|
### Beginner API stability
|
|
|
|
Status: satisfied for the current v1 goal.
|
|
|
|
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.
|
|
|
|
### Advanced APIs isolated
|
|
|
|
Status: satisfied.
|
|
|
|
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.
|
|
- Forbidden-normal-path scans only hit explicit route/static asset serving,
|
|
deploy/versioning text, or the `examples/saas` metrics island.
|
|
|
|
### Docs explain the model in one sitting
|
|
|
|
Status: 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,
|
|
deploy/versioning, and optional PWA/offline.
|
|
- `docs/diagnostics.md` and `docs/versioning.md` cover failure and release
|
|
policy.
|
|
|
|
### Diagnostics
|
|
|
|
Status: satisfied for the current v1 goal.
|
|
|
|
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, result-handler mapping, and example
|
|
contract checks.
|
|
- Final diagnostics gates include `cargo test -p hemx-build`,
|
|
`cargo test -p hemx-derive --test compile_fail`, `cargo test -p hemx-js`, and
|
|
`cargo test -p hemx-test --test examples_contract`.
|
|
|
|
### Production recipes
|
|
|
|
Status: satisfied.
|
|
|
|
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`
|
|
- mobile release: `docs/recipes/mobile-release.md`
|
|
- optional PWA/offline: `docs/recipes/pwa-offline.md`
|
|
|
|
### Public examples
|
|
|
|
Status: satisfied.
|
|
|
|
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.
|
|
|
|
### Runtime remains tiny and selectorless
|
|
|
|
Status: satisfied.
|
|
|
|
Evidence:
|
|
|
|
- `README.md`, `docs/versioning.md`, `docs/recipes/deploy-versioning.md`,
|
|
`docs/recipes/observability-flags.md`, and `docs/recipes/pwa-offline.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.
|
|
- `cargo test -p hemx-js` covers runtime root/fingerprint behavior.
|
|
|
|
### Versioning explicit
|
|
|
|
Status: satisfied.
|
|
|
|
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.
|
|
|
|
## Final closure gates
|
|
|
|
The following baseline commands remain required. They are insufficient for full
|
|
v1 closure until the browser/WASM/offline/multiplayer, accessibility, security,
|
|
performance, compatibility, and production-reference proofs in `v1_release/*`
|
|
also pass. Run them only as local validation; none publishes or deploys.
|
|
|
|
Run these on the final tree before GOAL_DONE:
|
|
|
|
```sh
|
|
cargo run -p hemx-xtask -- test
|
|
cargo check --workspace
|
|
cargo test -p hemx-saas-example
|
|
cargo test -p hemx-v0-examples
|
|
cargo test -p hemx-build
|
|
cargo test -p hemx-js
|
|
cargo test -p hemx-derive --test compile_fail
|
|
cargo test -p hemx-test --test examples_contract
|
|
redgate list
|
|
redgate refs
|
|
redgate health
|
|
git diff --check
|
|
```
|
|
|
|
Also run the forbidden-normal-path scan over `README.md`, `docs/`, `examples/v0`,
|
|
`examples/saas`, and the public advanced example READMEs. Expected remaining hits
|
|
are explicit route/static asset serving, deploy/versioning docs, or explicit
|
|
leaf-island JavaScript.
|