tmk241/hemx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement closed typed effect path

Browse Source
This commit is contained in:
tmk241
2026-09-01 00:58:29 +02:00
parent 353174604e
commit 31a0f02211
58 changed files with 4247 additions and 5933 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLAN.md
+47 -25
View File
@@ -1,31 +1,53 @@
# PLAN — Cloudflare Durable Objects proof
# Current plan
Parent outcome: prove that hemx keeps its semantic `.heml` authoring, generated typed resources, compile-time target checking, canonical `EffectBatch` wire format, and tiny runtime while a Cloudflare Durable Object owns one durable collaborative room and hibernating WebSocket fan-out.
## Slice HMX-001 — Closed typed effect path
Non-goals: a generic Cloudflare framework, Cloudflare-owned auth policy, RPC/alarm/queue abstractions, global object discovery, offline reconciliation, deployment automation, or treating stored HTML/effects as business truth.
Outcome: A handler can build the complete closed effect algebra with generated resource types, encode it canonically, and have one owned browser root apply it in order with defined failure behavior.
Delta: kernel/001–016, resource/001–004, resource/006, runtime/001, runtime/005, axum/001, axum/005.
Path: generated resource API -> typed effect batch -> canonical Axum response -> root-scoped browser decoder and executor -> DOM, focus, scroll, history, or dispatch result.
Build: Reconcile `hemx-core` effect/resource types and wire format, `hemx-build`/`hemx-derive` generated capabilities, `hemx-axum` response boundary, and `hemx-js` execution semantics as one compatibility break.
Risk: Partial migration can make server and browser disagree about opcodes, targets, ordering, or failure, causing wrong-root mutation or partial application.
Checks: Focused core round-trip/rejection tests; generated capability compile-pass/fail tests; Axum byte/status tests; browser scenarios for all eight effects, ordering, created-resource reuse, move identity, and stop-on-failure; `tests/redgate_test.sh`; `redgate check` for the slice IDs.
Non-goals: Request-policy attributes, optional transport adapters, islands, or public release publication.
Residual risk: Native interaction policy and adapter lifecycle remain in later slices.
State: Done
Blocked by: none
## Slice CF-1 — Canonical WebSocket push
## Slice HMX-002 — Native interaction and recovery
Outcome: a hemx root can receive binary `EffectBatch` updates over a same-origin WebSocket with the same ABI/fingerprint and root-scoped failure behavior as HTTP/SSE.
Delta: push/001, push/003, push/005, push/009; runtime/001; failure/001.
Path: `data-hemx-ws` on generated root -> runtime WebSocket -> binary frame -> existing `applyBatch` -> generated target or root error outlet.
Build: validate the root declaration in hemx-build; add runtime bind/cleanup/error behavior and focused consumer-boundary tests.
Risk: accepting text, cross-origin, malformed, or stale-build messages could bypass the canonical compatibility boundary or mutate the wrong root.
Proof: `cargo test -p hemx-build -p hemx-js` plus `cargo check --target wasm32-unknown-unknown -p hemx`.
Non-goals: client command protocol, reconnect/replay policy beyond the browser WebSocket primitive, multiplexing, or a general transport trait.
Residual risk: a real Cloudflare hibernation journey remains for CF-2.
State: Ready.
Blocked by: none.
Outcome: Generated semantic HTML submits forms and navigation through the closed effect path while preserving accessibility and ordinary browser recovery.
Delta: html/001–007, runtime/003–004, axum/003–004.
Path: generated marker and native anchor/form -> request policy and Axum boundary -> rendered validation or navigation response -> accessible browser result or native fallback.
Build: Align generated marker vocabulary, native-event defaults, bounded request policies, form encoding, validation markup, partial navigation metadata, and full-navigation recovery.
Risk: Enhancement can suppress native input, accessibility, or fallback behavior and leave users unable to submit, navigate, or recover.
Checks: Generated-markup assertions for every marker and policy value; browser scenarios with enhancement enabled and unavailable; form encoding and body-limit integration tests; validation accessibility assertions; partial/full navigation recovery scenarios; `redgate check` for the slice IDs.
Non-goals: SSE, WebSocket, timers, reveal behavior, or island-owned local state.
Residual risk: Optional adapter and island lifecycle remains open.
State: Ready
Blocked by: none
## Slice CF-2 — Durable room exemplar
## Slice HMX-003 — Direct adapters and explicit islands
Outcome: two browser clients in one named room see a counter mutation rendered from durable Rust state without reload, and reopening the room after object restart/eviction restores the persisted count.
Delta: push/001, push/002, push/003, push/009, push/010, push/011; canonical_authoring/001; state/001; abi/004.
Path: Worker room URL -> stable Durable Object name -> `.heml` page -> WebSocket upgrade -> typed increment command -> persisted counter -> generated counter partial -> canonical `EffectBatch` -> hibernating sockets -> both roots update.
Build: add one `examples/cloudflare_do` worker-rs exemplar with build-time hemx generation, one semantic template, one Durable Object class, Wrangler migration/binding, and focused pure tests for command/state/render output.
Risk: target-toolchain incompatibility, using an in-memory socket registry, persisting UI output instead of state, or emitting noncanonical WebSocket bytes would invalidate the proof.
Proof: native tests for command/render behavior; `cargo check --target wasm32-unknown-unknown -p hemx-cloudflare-do-example`; then `wrangler dev` browser smoke when Wrangler is available.
Non-goals: production auth/CSRF/tenancy, alarms, queues, RPC wrappers, multi-object transactions, deployment, billing, or a public `hemx-cloudflare` crate.
Residual risk: hosted Cloudflare deployment, jurisdiction policy, and production credentials remain external.
State: Ready for local build; hosted runtime proof is Blocked.
Blocked by: Wrangler runtime availability and Cloudflare account credentials for hosted verification.
Outcome: Optional transports and local islands compose with the generic runtime without adding effect schemas, a plugin registry, or mirrored client application state.
Delta: runtime/006–008, boundary/001–004, axum/002.
Path: root-owned adapter or explicit island marker -> direct bind/scan/cleanup lifecycle -> unchanged effect batch or island-owned subtree -> deterministic ownership result.
Build: Keep generic runtime behavior in `hemx-js`, framework transport in `hemx-axum`, direct adapter lifecycle beside each adapter, and explicit morph boundaries around islands.
Risk: Duplicate binding, leaked cleanup, or ambiguous ownership can apply effects twice, cross roots, or overwrite island state.
Checks: Browser lifecycle scenarios for bind-once, inserted fragments, removal cleanup, wrong-root rejection, and island preservation; static/public-API checks excluding plugin registries, extra core effects, and client stores; unchanged-byte transport tests; `redgate check` for the slice IDs.
Non-goals: New transports, a general extension API, or application-specific island frameworks.
Residual risk: Adapter-specific network behavior remains owned by each optional adapter.
State: Ready
Blocked by: none
## Slice HMX-004 — Deterministic generation and portable server build
Outcome: Template inspection and macros produce stable, actionable generated contracts, and normal server-side Hemx APIs compile for wasm32 without host parser dependencies.
Delta: resource/005, build/001–003, derive/001–004, wasm/001.
Path: Hemplate template input -> build inspection and macro expansion -> generated contract artifact -> unchanged rebuild or actionable compile failure -> portable server target.
Build: Tighten semantic fingerprinting and no-op writes, source-path diagnostics, macro preservation and compile failures, and the target dependency boundary.
Risk: Nondeterministic artifacts cause rebuild churn and ABI drift; leaked host parsers make the promised server target unusable.
Checks: Existing deterministic/no-op build and compile-fail tests; source I/O diagnostic test; wasm32 check plus normal dependency-tree exclusion; `tests/redgate_test.sh`; `redgate check` for the slice IDs.
Non-goals: Changing Hemplate syntax, parser internals, or package publication.
Residual risk: None after focused checks and the repository’s required workspace gates pass.
State: Ready
Blocked by: none