docs(v1): define evidence-backed production contract
req: client_local/005\nreq: sync/009\nreq: accessibility/001\nreq: operations/001\nreq: security/001\nreq: performance/001\nreq: v1_release/001
This commit is contained in:
slhx agent
@@ -0,0 +1,166 @@
|
||||
# Hemx v1 product evidence
|
||||
|
||||
This document records external evidence used to sharpen the hemx v1 requirements.
|
||||
It is not authority over `REQUIREMENTS.md`, and precedent does not prove demand.
|
||||
The product decision remains: checked hypermedia for Rust, with server-first as the
|
||||
simple default and client-local/offline execution as explicit opt-in layers over
|
||||
the same generated-resource and effect contract.
|
||||
|
||||
Research checked on 2026-07-13.
|
||||
|
||||
## User job and alternatives
|
||||
|
||||
The target user is a Rust team building an interaction-heavy web application that
|
||||
wants server-rendered HTML and ordinary Rust domain logic without accepting a
|
||||
second selector/string contract or a component/VDOM runtime. Today that team can:
|
||||
|
||||
- use server-only hypermedia and accept round-trip latency;
|
||||
- add handwritten JavaScript and own two state/effect models;
|
||||
- adopt React/Vue or another client framework for local interaction;
|
||||
- use LiveView/Turbo-style server-driven interaction; or
|
||||
- build a local-first sync engine directly.
|
||||
|
||||
Those alternatives work. Hemx v1 is justified only if execution location can be
|
||||
an opt-in handler choice while generated resources, `EffectBatch`, failure
|
||||
semantics, and server authority stay coherent.
|
||||
|
||||
## Evidence and decisions
|
||||
|
||||
### Linear: local responsiveness requires a real sync architecture
|
||||
|
||||
Sources:
|
||||
|
||||
- [Scaling the Linear Sync Engine](https://linear.app/now/scaling-the-linear-sync-engine)
|
||||
- [Linear Method](https://linear.app/method/introduction)
|
||||
- [Linear Security](https://linear.app/security)
|
||||
- [How Linear uses Google Cloud databases](https://cloud.google.com/blog/products/databases/product-workflow-tool-linear-uses-google-cloud-databases)
|
||||
|
||||
Linear materializes fast local interaction with a client-side data model and a
|
||||
server replication/sync system rather than hiding latency behind cosmetic
|
||||
loading states. Its published architecture discusses initial synchronization,
|
||||
real-time updates, database change capture, and scaling work; its product method
|
||||
also values deliberate, opinionated workflows. Its security page treats access,
|
||||
encryption, backups, monitoring, incident handling, and independent assurance as
|
||||
operational systems rather than UI features.
|
||||
|
||||
**Use in hemx:** client-local work must be genuinely local; offline/sync must have
|
||||
durable identities, bounded queues, resumable acknowledgement, migration,
|
||||
conflict/rejection behavior, and observable recovery. Production proof must cover
|
||||
operations and failures, not only the happy-path API.
|
||||
|
||||
**Do not copy:** hemx is a framework, not Linear's product. It must not grow issue
|
||||
tracking, workspace policy, SSO/SCIM, a hosted database, or a mandatory global
|
||||
client graph. Authentication, authorization, encryption policy, backups, and
|
||||
retention remain application/platform concerns; hemx integrations must expose
|
||||
boundaries that let applications enforce and test them.
|
||||
|
||||
### Local-first: offline is a data-ownership and recovery promise
|
||||
|
||||
Source: [Local-first software: You own your data, in spite of the cloud](https://www.inkandswitch.com/essay/local-first/).
|
||||
|
||||
The local-first work identifies availability without a network, multi-device
|
||||
coordination, ownership, longevity, and collaboration as distinct properties. A
|
||||
cache or optimistic DOM patch does not establish them.
|
||||
|
||||
**Use in hemx:** persisted commands/domain events are truth; DOM effects are
|
||||
projections. Queue durability, export/deletion, schema upgrades, conflict policy,
|
||||
and recovery from corruption/quota failure must be explicit. “Offline capable”
|
||||
cannot mean only that a shell loads.
|
||||
|
||||
**Do not copy:** CRDTs are not the default. Hemx v1 keeps the server authoritative
|
||||
and requires explicit opt-in policy where collaboration semantics differ.
|
||||
|
||||
### Hypermedia and live-server systems: preserve browser and deploy semantics
|
||||
|
||||
Sources:
|
||||
|
||||
- [HTMX documentation](https://htmx.org/docs/)
|
||||
- [Phoenix LiveView deployments](https://hexdocs.pm/phoenix_live_view/deployments.html)
|
||||
- [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction)
|
||||
|
||||
These systems demonstrate progressive enhancement, history-aware navigation,
|
||||
request synchronization, server-driven DOM updates, reconnect/deployment
|
||||
concerns, and the value of preserving ordinary links and forms.
|
||||
|
||||
**Use in hemx:** real `href`/form fallback, back/forward correctness, stale-request
|
||||
suppression, deploy fingerprint refusal, reconnect behavior, and clear full-page
|
||||
recovery are release requirements.
|
||||
|
||||
**Do not copy:** selector mini-languages, implicit component lifecycles, and a
|
||||
router owned by core remain outside hemx.
|
||||
|
||||
### Platform primitives: use the browser's durable and accessible contracts
|
||||
|
||||
Sources:
|
||||
|
||||
- [IndexedDB API](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
|
||||
- [Using Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers)
|
||||
- [WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/)
|
||||
- [RAIL performance model](https://web.dev/articles/rail)
|
||||
|
||||
IndexedDB provides transactional browser storage; service workers provide an
|
||||
HTTPS-bound offline/network interception lifecycle. WCAG 2.2 makes keyboard
|
||||
operation, visible focus, status/error communication, and programmatic
|
||||
name/role/value release concerns. RAIL treats roughly 100 ms as the response
|
||||
window in which direct manipulation feels immediate.
|
||||
|
||||
**Use in hemx:** optional adapters reuse platform storage/service-worker
|
||||
primitives; storage failures and upgrades are recoverable. Generated interaction
|
||||
must preserve semantic HTML, keyboard operation, focus, status/error
|
||||
announcements, and reduced-motion preferences. Client-local interaction gets an
|
||||
observable latency/frame budget rather than a “fast” adjective.
|
||||
|
||||
**Do not copy:** hemx core does not mandate IndexedDB, a service worker, or an
|
||||
application cache policy.
|
||||
|
||||
### Security and release discipline: framework controls need testable boundaries
|
||||
|
||||
Sources:
|
||||
|
||||
- [OWASP Application Security Verification Standard 5.0](https://owasp.org/www-project-application-security-verification-standard/)
|
||||
- [Cargo SemVer compatibility](https://doc.rust-lang.org/cargo/reference/semver.html)
|
||||
- [cargo-audit](https://github.com/rust-secure-code/cargo-audit)
|
||||
|
||||
ASVS provides a test-oriented baseline for web controls such as encoding,
|
||||
injection prevention, session/access boundaries, validation, and logging. Cargo's
|
||||
SemVer guidance shows that public Rust items, traits, features, MSRV, and runtime
|
||||
behavior all carry compatibility risk. `cargo-audit` checks the committed lockfile
|
||||
against RustSec advisories.
|
||||
|
||||
**Use in hemx:** unsafe HTML stays type-gated; integrations make origin/CSRF,
|
||||
authorization, limits, and security logging testable; replay never bypasses
|
||||
current authorization. v1 has an explicit public/generated/wire/runtime
|
||||
compatibility policy, migration evidence, MSRV/browser support, and a pinned
|
||||
lockfile advisory audit before release approval.
|
||||
|
||||
**Do not copy:** hemx does not claim application-level ASVS compliance. It proves
|
||||
only controls and boundaries it owns. Publishing remains a separate explicit
|
||||
human decision.
|
||||
|
||||
## Product thesis
|
||||
|
||||
Hemx v1 should feel like boring server-rendered HTML with typed, selectorless
|
||||
partial swaps, while letting a team opt one handler into local WASM or durable
|
||||
sync without changing the resource/effect language. The smallest coherent
|
||||
mechanism is:
|
||||
|
||||
1. hemplate Surface facts and generated resources;
|
||||
2. one handler shape with explicit execution placement;
|
||||
3. one versioned `EffectBatch` application contract;
|
||||
4. server-first by default;
|
||||
5. explicit local state ownership;
|
||||
6. optional durable command-log/reconciliation adapters; and
|
||||
7. fail-closed versioning plus native-browser recovery.
|
||||
|
||||
## Kill tests
|
||||
|
||||
Reshape or drop client-local/sync work if any slice requires:
|
||||
|
||||
- a second effect protocol or selector target language;
|
||||
- hidden global state or a component lifecycle;
|
||||
- bespoke JavaScript per application handler;
|
||||
- persisted DOM/effect payloads as domain truth;
|
||||
- a mandatory browser database, service worker, CRDT, or conflict policy;
|
||||
- authorization decisions cached across replay without server revalidation; or
|
||||
- inaccessible interaction or failure states that cannot preserve native HTML
|
||||
fallback.
|
||||
+21
-4
@@ -1,10 +1,22 @@
|
||||
# v1 readiness audit
|
||||
|
||||
This audit records the current hemx v1 northstar against the active Close when.
|
||||
It is not a marketing release announcement; it is the engineering closure record
|
||||
for the current v1 product-readiness goal. req: examples/001 req: public_api/001
|
||||
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
|
||||
|
||||
## Close-when status
|
||||
## Current status
|
||||
|
||||
- Server-first and page-enhanced baseline: proven by the evidence below.
|
||||
- Client-local WASM: not implemented; first active v1 slice.
|
||||
- Durable offline/sync: contracts shaped, implementation blocked by the local
|
||||
execution boundary.
|
||||
- Full production reference and v1 closure matrix: not yet proven.
|
||||
- Publishing and deployment: explicitly unauthorized.
|
||||
|
||||
## Baseline evidence
|
||||
|
||||
### Canonical tutorial app
|
||||
|
||||
@@ -141,6 +153,11 @@ Evidence:
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user