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
+216
-1
@@ -690,6 +690,51 @@ what a valid business email is. [north_star]
|
||||
### req: sync/008
|
||||
0 008 Sync is bidirectional state reconciliation built on top of push/transport. It is not required for server-sent dashboards, notifications, or live status updates.
|
||||
|
||||
### req: sync/009
|
||||
0 009 Every queued mutation has a stable client-generated command id, actor/session scope, schema version, and causal ordering token so retries and reconnects do not create ambiguous duplicates. [north_star]
|
||||
|
||||
### req: sync/010
|
||||
0 010 The authoritative server processes command ids idempotently and returns an acknowledgement, canonical replacement, explicit rejection, or conflict result; transport success alone never clears local work. [north_star]
|
||||
|
||||
### req: sync/011
|
||||
0 011 The client durably advances its acknowledgement cursor only after the corresponding canonical result is committed locally; crash or reload between send and acknowledgement is safe to retry. [north_star]
|
||||
|
||||
### req: sync/012
|
||||
0 012 Initial sync uses a versioned snapshot plus an ordered change cursor or an equivalent bounded protocol; reconnect resumes from the last committed cursor and falls back to a fresh snapshot when history is unavailable. [north_star]
|
||||
|
||||
### req: sync/013
|
||||
0 013 Server rejection and conflict are distinct outcomes. Each produces application-visible reconciliation data, compensates or replaces optimistic projection explicitly, and never silently drops the command. [north_star]
|
||||
|
||||
### req: sync/014
|
||||
0 014 Queued command and projection schema upgrades are transactional and versioned. Incompatible data fails closed with export/reset recovery instead of partial replay. [north_star]
|
||||
|
||||
### req: sync/015
|
||||
0 015 Durable browser storage failures, corruption, eviction, and quota exhaustion are observable and recoverable; the adapter must not claim offline durability after persistence fails. [north_star]
|
||||
|
||||
### req: sync/016
|
||||
0 016 Reconnect uses bounded exponential backoff with jitter and explicit online/offline state; manual retry remains available, and reconnect storms are prevented. [north_star]
|
||||
|
||||
### req: sync/017
|
||||
0 017 Queue size, payload size, in-flight commands, retry rate, and server fan-out are bounded with backpressure and actionable overflow behavior. Unbounded buffering is forbidden. [north_star]
|
||||
|
||||
### req: sync/018
|
||||
0 018 Multiple tabs or workers coordinate one durable queue through an explicit lease/ownership protocol or safe idempotent parallel replay; they must not race destructive queue updates. [north_star]
|
||||
|
||||
### req: sync/019
|
||||
0 019 Replay revalidates the current authenticated principal, authorization, tenancy, and command preconditions on the server; cached permission from enqueue time is not authority. [north_star]
|
||||
|
||||
### req: sync/020
|
||||
0 020 Applications explicitly choose retention, encryption-at-rest, export, and deletion policy for local command data; `hemx-sync` exposes lifecycle hooks but does not invent product policy. [north_star]
|
||||
|
||||
### req: sync/021
|
||||
0 021 Sync diagnostics expose queue depth, oldest command age, connection state, retry count, cursor, acknowledgement latency, conflicts, and rejected commands without logging sensitive payloads by default. [north_star]
|
||||
|
||||
### req: sync/022
|
||||
0 022 The default reconciliation model is server-authoritative and deterministic for identical snapshot, command sequence, and server results; custom merge or CRDT policy is an explicit integration. [north_star]
|
||||
|
||||
### req: sync/023
|
||||
0 023 A durable browser test proves offline mutation, reload, reconnect replay, duplicate delivery, rejection, conflict, schema mismatch, and final convergence through public hemx APIs. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## local
|
||||
@@ -947,7 +992,37 @@ what a valid business email is. [north_star]
|
||||
0 003 High-frequency UI handlers (drag, pointermove, animation tick) must not require server round-trips or handwritten JS. [north_star]
|
||||
|
||||
### req: client_local/004
|
||||
0 004 Client-local handler opt-in syntax is an integration contract, not hemx-core v0; `hemx-wasm` owns concrete handler attributes. [north_star]
|
||||
0 004 Client-local handler opt-in syntax is an integration contract, not hemx core; `hemx-wasm` owns `#[hemx::handler(client)]` and its browser boundary. [north_star]
|
||||
|
||||
### req: client_local/005
|
||||
0 005 A client-local handler accepts generated events and explicit state and returns the same `IntoEffect`/`EffectBatch` contract as a server handler; it must not expose DOM mutation APIs. [north_star]
|
||||
|
||||
### req: client_local/006
|
||||
0 006 `hemx-wasm` exports only handlers explicitly opted into client execution and rejects parameters, captures, or return values that cannot cross its generated ABI with an actionable Rust span. [north_star]
|
||||
|
||||
### req: client_local/007
|
||||
0 007 Each hemx root owns its client-local state instance; initialization from defaults or versioned `data-hemx-st` input is explicit, and no process-global browser singleton owns application state. [north_star]
|
||||
|
||||
### req: client_local/008
|
||||
0 008 Invalid browser event payload or incompatible bootstrap state must not call the handler; the runtime emits a root-scoped diagnostic, restores pending UI, and preserves a native/server fallback where declared. [north_star]
|
||||
|
||||
### req: client_local/009
|
||||
0 009 A successfully dispatched client-local handler applies its ordinary `EffectBatch` through the same version/fingerprint checks and ordered root-scoped effect interpreter used for server responses. [north_star]
|
||||
|
||||
### req: client_local/010
|
||||
0 010 A client-local interaction performs no network request unless the handler explicitly returns an integration effect that declares remote work. [north_star]
|
||||
|
||||
### req: client_local/011
|
||||
0 011 Client-local handlers are cancellable or supersedable according to the generated handle policy, and stale asynchronous completions must not overwrite newer state or effects. [north_star]
|
||||
|
||||
### req: client_local/012
|
||||
0 012 Removing a hemx root releases its handler bindings, timers, observers, pending work, and local state; repeated mount/unmount must not leak root-owned browser resources. [north_star]
|
||||
|
||||
### req: client_local/013
|
||||
0 013 Direct-manipulation client handlers meet an evidence-backed interaction budget: ordinary input responds within 100 ms, and pointer-follow animation work fits the tested frame budget on the supported baseline browser. [north_star]
|
||||
|
||||
### req: client_local/014
|
||||
0 014 Client-local behavior has a browser-level proof using generated resources, a real WASM artifact, zero app-authored JavaScript, and network instrumentation that distinguishes local from server execution. [north_star]
|
||||
|
||||
---
|
||||
|
||||
@@ -1272,6 +1347,146 @@ async fn delete(app: State<App>, todo_id: TodoId) -> impl IntoEffect
|
||||
|
||||
---
|
||||
|
||||
## accessibility
|
||||
|
||||
### req: accessibility/001
|
||||
0 001 Server-first, page-enhanced, client-local, and sync modes preserve semantic HTML and native link/form behavior; enhancement must not remove an available keyboard or no-script path. [north_star]
|
||||
|
||||
### req: accessibility/002
|
||||
0 002 Every generated interaction is keyboard operable. Pointer-specific features such as drag/drop provide an application-declared keyboard action path with equivalent outcome. [north_star]
|
||||
|
||||
### req: accessibility/003
|
||||
0 003 Effect application preserves or deliberately moves focus. Removed focused nodes, validation failures, modal boundaries, navigation, and full-page fallback each have deterministic focus behavior. [north_star]
|
||||
|
||||
### req: accessibility/004
|
||||
0 004 Pending, success, validation, transport, offline, conflict, and recovery state is exposed programmatically through native validity, `aria-busy`, status/error regions, or generated application targets without relying on color or motion alone. [north_star]
|
||||
|
||||
### req: accessibility/005
|
||||
0 005 Generated resources preserve authored accessible names, roles, values, labels, descriptions, and table/list structure across replacement, insertion, and reconciliation. [north_star]
|
||||
|
||||
### req: accessibility/006
|
||||
0 006 Optional transitions and direct-manipulation effects honor reduced-motion preferences and do not block input, focus, or recovery when animation is disabled. [north_star]
|
||||
|
||||
### req: accessibility/007
|
||||
0 007 The supported example matrix includes automated accessibility checks plus keyboard/focus browser scenarios for forms, page navigation, client-local interaction, offline state, and error recovery. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## operations
|
||||
|
||||
### req: operations/001
|
||||
0 001 Every request, push stream, client-local dispatch, sync command, acknowledgement, and effect application has a stable correlation boundary that integrations can attach to existing tracing without hemx owning a telemetry backend. [north_star]
|
||||
|
||||
### req: operations/002
|
||||
0 002 Integration diagnostics distinguish build/version mismatch, transport failure, timeout, cancellation, decode failure, missing target, handler rejection, authorization denial, storage failure, and sync conflict. [north_star]
|
||||
|
||||
### req: operations/003
|
||||
0 003 Requests, streams, handlers, and background replay support explicit timeouts and cancellation; cancellation restores pending UI and prevents late effects from applying. [north_star]
|
||||
|
||||
### req: operations/004
|
||||
0 004 Push and sync adapters implement bounded buffering, heartbeat/liveness detection, reconnect backoff, and slow-consumer behavior instead of relying on unbounded transport queues. [north_star]
|
||||
|
||||
### req: operations/005
|
||||
0 005 Production diagnostics omit sensitive form values, auth material, local command payloads, and rendered private HTML by default; development detail is explicit and cannot silently enable in production. [north_star]
|
||||
|
||||
### req: operations/006
|
||||
0 006 Mixed deploy versions fail closed through ABI/fingerprint checks and recover by reload, full navigation, or fresh sync snapshot; rolling deployment must not apply an incompatible partial batch. [north_star]
|
||||
|
||||
### req: operations/007
|
||||
0 007 A production reference exposes health/readiness, structured errors, tracing hooks, and metrics for latency, failures, queue pressure, reconnect, and effect decode/apply without requiring a hemx-specific observability stack. [north_star]
|
||||
|
||||
### req: operations/008
|
||||
0 008 Process restart, browser reload, network interruption, duplicate delivery, and partial deployment are first-class recovery tests rather than manual release notes. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## security
|
||||
|
||||
### req: security/001
|
||||
0 001 Hemx-owned HTML and attribute sinks preserve hemplate escaping and explicit `SafeHtml` trust boundaries in every execution mode; sync, WASM, and push must not introduce a weaker payload path. [north_star]
|
||||
|
||||
### req: security/002
|
||||
0 002 Standard HTTP, navigation, asset, push, and sync connections are same-origin by default. Cross-origin use requires explicit integration configuration and cannot silently forward credentials. [north_star]
|
||||
|
||||
### req: security/003
|
||||
0 003 Mutating HTTP integrations expose testable origin/CSRF enforcement, secure session/cookie boundaries, request-size limits, and content-type validation while leaving application policy to the host framework. [north_star]
|
||||
|
||||
### req: security/004
|
||||
0 004 Every handler invocation and replayed command receives current authenticated identity and authorization context from the integration boundary; numeric generated ids are routing identifiers, never authorization. [north_star]
|
||||
|
||||
### req: security/005
|
||||
0 005 Effect, state, event, command, and sync decoders reject unknown versions, invalid kinds, oversized lengths, truncated values, and trailing incompatible data without panicking or partially applying the batch. [north_star]
|
||||
|
||||
### req: security/006
|
||||
0 006 The browser runtime and generated bootstrap are compatible with a strict Content Security Policy: no `eval`, dynamic code generation, inline application script requirement, or `javascript:` URL. [north_star]
|
||||
|
||||
### req: security/007
|
||||
0 007 Local persistence makes sensitive-data exposure explicit: applications can redact, encrypt, expire, export, and delete queued data, and examples never store credentials or session secrets in offline command records. [north_star]
|
||||
|
||||
### req: security/008
|
||||
0 008 Release evidence includes a pinned advisory audit of the committed lockfile, review of unsafe code and licenses, and documented disposition for every accepted advisory or supply-chain exception. [north_star]
|
||||
|
||||
### req: security/009
|
||||
0 009 Hemx claims only the framework controls it proves. Application compliance, identity provider, database encryption, backup, retention, and incident policy remain explicit host responsibilities. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## performance
|
||||
|
||||
### req: performance/001
|
||||
0 001 Performance requirements are measured on named supported configurations with reproducible fixtures; “fast”, “60fps”, and bundle-size claims must have commands, baselines, and regression thresholds. [north_star]
|
||||
|
||||
### req: performance/002
|
||||
0 002 Server-first and page-enhanced handlers add bounded framework overhead relative to rendering and transport, and benchmark regressions fail the repository performance gate. [north_star]
|
||||
|
||||
### req: performance/003
|
||||
0 003 Client-local direct manipulation responds within 100 ms for ordinary input and keeps pointer-follow work within the tested frame budget without network dependence. [north_star]
|
||||
|
||||
### req: performance/004
|
||||
0 004 Initial sync is proportional to the scoped snapshot, incremental sync is proportional to delivered changes, and neither path requires loading unrelated workspace state. [north_star]
|
||||
|
||||
### req: performance/005
|
||||
0 005 Effect decode/apply, generated target lookup, queue replay, and keyed reconciliation have adversarial size tests and explicit memory/operation bounds. [north_star]
|
||||
|
||||
### req: performance/006
|
||||
0 006 Optional WASM, sync, PWA, transition, and editor assets are separately loadable; server-first applications do not pay their download, initialization, or dependency cost. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## v1_release
|
||||
|
||||
### req: v1_release/001
|
||||
0 001 Hemx v1 is feature-complete only when server-first, page-enhanced, client-local WASM, and hybrid offline/sync modes share generated resources and `EffectBatch` semantics and pass their end-to-end proof scenarios. [north_star]
|
||||
|
||||
### req: v1_release/002
|
||||
0 002 The local-first multiplayer Kanban milestone proves direct manipulation, optimistic projection, offline durability, reload, ordered replay, idempotency, conflict/rejection, presence, convergence, and SSR-first fallback without React, Vue, VDOM, or app-authored JavaScript. [north_star]
|
||||
|
||||
### req: v1_release/003
|
||||
0 003 A production reference proves durable persistence, current authorization, CSRF/origin policy, transactions, restart recovery, structured failures, observability hooks, accessibility, and deploy compatibility while keeping vendor policy outside hemx core. [north_star]
|
||||
|
||||
### req: v1_release/004
|
||||
0 004 Public Rust API, generated API, Surface schema, symbol schema, wire ABI, browser runtime ABI, persisted sync schema, MSRV, and supported browser changes each have an explicit compatibility and migration policy. [north_star]
|
||||
|
||||
### req: v1_release/005
|
||||
0 005 V1 documentation teaches one progression: server-first partial swaps, page enhancement, explicit islands/client-local handlers, then durable sync; every level states ownership, failure, recovery, accessibility, security, and operational boundaries. [north_star]
|
||||
|
||||
### req: v1_release/006
|
||||
0 006 Release closure requires formatting, workspace tests, strict all-target linting, compile-fail contracts, browser/WASM/offline scenarios, performance budgets, security audit, documentation checks, examples, and clean-tree reproducibility with no unresolved P0 or P1 defect. [north_star]
|
||||
|
||||
### req: v1_release/007
|
||||
0 007 The supported matrix names Rust/MSRV, browser versions, WASM target/toolchain, operating systems needed for development, and integration crate versions; unsupported combinations fail with actionable diagnostics. [north_star]
|
||||
|
||||
### req: v1_release/008
|
||||
0 008 All canonical examples use public generated APIs and are treated as compatibility tests. No release claim depends on unpublished demo-only glue, ad hoc scripts, or test-only runtime behavior. [north_star]
|
||||
|
||||
### req: v1_release/009
|
||||
0 009 Local release-readiness validation must not publish crates, deploy services, upload artifacts, submit stores, or mutate external systems. Publishing remains a separate explicit human-authorized action. [north_star]
|
||||
|
||||
### req: v1_release/010
|
||||
0 010 Feature-complete does not mean feature-accumulative: v1 refuses a built-in router, auth system, database, mandatory client store, default CRDT, component lifecycle, VDOM, selector language, telemetry vendor, deployment platform, and application policy framework. [north_star]
|
||||
|
||||
---
|
||||
|
||||
## multipart
|
||||
|
||||
### req: multipart/001
|
||||
|
||||
Reference in New Issue
Block a user