docs(requirements): tighten wire rows

Add explicit northstar ring fields to wire requirements, split root-boundary metadata, and shorten runtime metadata wording without changing behavior.

req: wire/001

req: wire/002

req: wire/003

req: wire/004

req: wire/005

req: wire/006
This commit is contained in:
slhx agent
2026-06-25 15:27:05 +02:00
parent 9a4971eee8
commit 3a1512994d
2 changed files with 9 additions and 6 deletions
+1 -1
View File
@@ -55,7 +55,7 @@ Keep it stable. Prefer pointers to canonical sources over copied structure, file
- Example behavior tests should prefer `hemx_test` generated-resource assertions over raw slot constants or raw effect/payload matching. req: test/008 - Example behavior tests should prefer `hemx_test` generated-resource assertions over raw slot constants or raw effect/payload matching. req: test/008
- Run the workout product exemplar with `cargo run -p hemx-xtask -- workout dev` and open `http://127.0.0.1:3028`; set `HEMX_WORKOUT_ADDR=127.0.0.1:3030` if the default port is busy. Its durable visual direction and recovery expectations live in `examples/workout/DESIGN.md`. req: examples/008 - Run the workout product exemplar with `cargo run -p hemx-xtask -- workout dev` and open `http://127.0.0.1:3028`; set `HEMX_WORKOUT_ADDR=127.0.0.1:3030` if the default port is busy. Its durable visual direction and recovery expectations live in `examples/workout/DESIGN.md`. req: examples/008
- Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets. req: examples/006 req: examples/011 - Use the same Workout command surface for tests, production build, and mobile release: `cargo run -p hemx-xtask -- workout test`, `cargo run -p hemx-xtask -- workout build`, `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-release`, and `HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout mobile-verify`; Android/iOS SDKs, store submission targets, and signing remain external blockers, not repo-owned secrets. req: examples/006 req: examples/011
- hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. req: laws/001 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 - hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus the closed EffectBatch op set, and treat DOM details as runtime lowering. Public identifiers should flow through typed wrappers over internal `ResourceId`/`ResourceRef`, not special-case opcodes. Wire output lowers symbolic authoring names to compact metadata and postcard/form-encoded envelopes, not JSON. req: laws/001 req: typed_id/001 req: typed_id/003 req: effect_algebra/001 req: effect_algebra/006 req: wire/001 req: wire/002 req: wire/003 req: wire/004 req: wire/005 req: wire/006
- Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates. - Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates.
- Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, render/page helpers, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: public_api/001 req: public_api/002 req: public_api/003 req: public_api/005 req: public_api/006 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003 - Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, render/page helpers, and `IntoEffect`, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, `$OUT_DIR` includes, raw render/lower calls, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: public_api/001 req: public_api/002 req: public_api/003 req: public_api/005 req: public_api/006 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
- Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. Preserve keyed/optional scope identity for addressable loop nodes and prefer generated keyed-slot helpers over low-level keyed calls. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: scope/001 req: list/001 req: list/002 req: list/003 req: list/004 req: list/005 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003 - Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. Preserve keyed/optional scope identity for addressable loop nodes and prefer generated keyed-slot helpers over low-level keyed calls. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: scope/001 req: list/001 req: list/002 req: list/003 req: list/004 req: list/005 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003
+8 -5
View File
@@ -485,19 +485,22 @@ what a valid business email is. [north_star]
## wire ## wire
### req: wire/001 ### req: wire/001
001 Authoring HTML uses symbolic `data-hemx-*` attributes. Rendered runtime HTML lowers these to compact numeric metadata: `data-hid`, `data-sid`, optional `data-key`, optional atom ids, optional form/control ids, and `data-hemx-st` for state bootstrap. The browser never sees handler or slot names. `data-hemx-root` marks a scoped root boundary. 0 001 Authoring HTML uses symbolic `data-hemx-*` attributes. Runtime HTML lowers them to compact metadata: `data-hid`, `data-sid`, optional `data-key`, atom ids, form/control ids, and `data-hemx-st`. The browser never sees handler or slot names. [north_star]
### req: wire/006
0 006 `data-hemx-root` marks a scoped root boundary. [north_star]
### req: wire/002 ### req: wire/002
002 POST bodies carry `application/x-www-form-urlencoded` with distinguished field `__h` (handle id). Server routes by numeric id, not by URL path. 0 002 POST bodies carry `application/x-www-form-urlencoded` with distinguished field `__h` (handle id). Server routes by numeric id, not by URL path. [north_star]
### req: wire/003 ### req: wire/003
003 HTTP interaction responses may be `text/html` fragments containing `<template data-hemx>...`. Push streams use `application/hemx` or transport-specific event frames carrying serialized `EffectBatch`. 0 003 HTTP interaction responses may be `text/html` fragments containing `<template data-hemx>...`. Push streams use `application/hemx` or transport-specific event frames carrying serialized `EffectBatch`. [north_star]
### req: wire/004 ### req: wire/004
004 Server push is orthogonal: integration crates stream postcard `EffectBatch` over SSE or WebSocket connections. hemx core owns the effect bytes; transport and connection management are integration concerns. 0 004 Server push is orthogonal: integration crates stream postcard `EffectBatch` over SSE or WebSocket connections. hemx core owns the effect bytes; transport and connection management are integration concerns. [north_star]
### req: wire/005 ### req: wire/005
005 No JSON anywhere in hemx-internal artifacts. Public request/response envelopes use `application/x-www-form-urlencoded`; effects and symbols use postcard. `application/json` is acceptable only at integration boundaries. 0 005 No JSON anywhere in hemx-internal artifacts. Public request/response envelopes use `application/x-www-form-urlencoded`; effects and symbols use postcard. `application/json` is acceptable only at integration boundaries. [north_star]
--- ---