From 7b647add0aecb944c1a356d486cb5a8f9954036a Mon Sep 17 00:00:00 2001 From: slhx agent Date: Thu, 25 Jun 2026 14:18:27 +0200 Subject: [PATCH] docs(requirements): split offline adapter boundary Split oversized canonical_authoring/008 into offline opt-in, adapter queue, and no-core-local-runtime requirements. req: canonical_authoring/008 req: canonical_authoring/018 req: canonical_authoring/019 --- AGENTS.md | 2 +- README.md | 2 +- REQUIREMENTS.md | 8 +++++++- docs/recipes/pwa-offline.md | 2 +- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 18aa165..8902f7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,5 +67,5 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file - JS runtime changes must preserve root-scoped lookup, fail-closed request handling, root-scoped error outlets, and tiny pending/failure/trigger-timing conventions without selectors, VDOM, expressions, or per-node listeners. req: runtime/005 req: convention/001 req: convention/003 req: convention/005 req: convention/007 - Opaque island JavaScript is a leaf adapter for high-frequency local behavior only; it must not introduce a component runtime, client state graph, VDOM, or second UI model. req: canonical_authoring/017 - Host capability adapters must stay at the `hemx-host` boundary: they may call host APIs and return host events, but they must not mutate DOM or own app/domain state. req: host/002 -- Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, or stored `EffectBatch` truth without a proven reusable contract. req: local/001 req: local/002 +- Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, stored `EffectBatch` truth, or a core client state graph without a proven reusable contract. req: canonical_authoring/018 req: canonical_authoring/019 req: local/001 req: local/002 - Axum apps should serve and load the shared runtime through hemx-axum helpers such as `runtime_js_path()` and `runtime_js()`, not hard-coded `/hemx.js` URLs or app-owned cache-busting strings. diff --git a/README.md b/README.md index fa28706..34989db 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ and integrate at explicit boundaries. req: laws/002 req: auth/001 but core hemx must not gain a mandatory client state graph or local app runtime. Local truth is commands/events/projections, not stored DOM patches or stored `EffectBatch` payloads. See `docs/recipes/pwa-offline.md` and - `docs/recipes/local-command-log.md`. req: canonical_authoring/008 req: local/001 req: local/002 + `docs/recipes/local-command-log.md`. req: canonical_authoring/008 req: canonical_authoring/018 req: canonical_authoring/019 req: local/001 req: local/002 - **Host capabilities:** browser, PWA, WebView, and native-shell capabilities use `hemx-host` manifests/calls/events. Adapters return host facts to app code; UI still changes through normal hemx effects. See diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index f5f5269..0b072f9 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -98,7 +98,13 @@ client app state framework. 017 Island JavaScript owns only high-frequency local behavior and must not introduce a component runtime, client state graph, VDOM, or second UI model. [north_star] ### req: canonical/008 -008 Offline/PWA support is opt-in adapter territory. Server-first hemx may fail interactions while offline; cached shells and local-sync queues live in crates such as `hemx-pwa` or `hemx-sync`, reuse generated slots/effects, queue explicit patches, and reconcile with server-canonical effects. Core hemx must not gain a mandatory client state graph, scheduler, CRDT, or local app runtime. [north_star] +008 Offline/PWA support is opt-in adapter territory; server-first hemx may fail interactions while offline. [north_star] + +### req: canonical/018 +018 Cached shells and local-sync queues live in crates such as `hemx-pwa` or `hemx-sync`; they reuse generated slots/effects, queue explicit patches, and reconcile with server-canonical effects. [north_star] + +### req: canonical/019 +019 Core hemx must not gain a mandatory client state graph, scheduler, CRDT, or local app runtime. [north_star] --- diff --git a/docs/recipes/pwa-offline.md b/docs/recipes/pwa-offline.md index 3ac7ee9..6d351fa 100644 --- a/docs/recipes/pwa-offline.md +++ b/docs/recipes/pwa-offline.md @@ -5,7 +5,7 @@ without turning core hemx into a client app framework. Offline/PWA support is opt-in adapter territory: reuse generated targets and server-canonical effects, but keep service workers, queues, conflict policy, and local storage outside `hemx`, `hemx-core`, `hemx-build`, `hemx-derive`, `hemx-axum`, and the tiny -runtime. req: canonical_authoring/008 req: runtime/003 req: runtime/004 +runtime. req: canonical_authoring/008 req: canonical_authoring/018 req: canonical_authoring/019 req: runtime/003 req: runtime/004 Use this only after the normal server-first path works. A hemx app is allowed to fail interactions while offline and recover with a full page once the network is