stabilize architecture docs: address review findings and advance to stable
Critical fixes: - Restructure pointers.md: move setNode prop-key writes section under its own heading (was incorrectly nested under selectNode) - Add Context/Density/Direction/RenderContext documentation section to host-config.md (was only a brief constraint bullet) - Advance all 5 ADRs from Status: Proposed → Accepted and frontmatter from status: draft → status: stable (decisions are driving implementation) - Add error handling philosophy section to README Warning/suggestion fixes: - Add isUElement null check (node !== null) to schema.md discriminator table - Add UjsxEnvelope convenience type documentation to events.md - Add Direction Unicode arrow naming note to transforms.md - Standardize all cross-references from absolute docs/research/ paths to relative ../research/ paths across all architecture docs - Fix schema.md ADR references to use relative paths - Reduce redundancy between transforms.md and host-config.md Direction notes - Update all architecture doc frontmatter from draft → stable Deferred: - Performance model section (reconciler not yet built) - Concepts/glossary document (low ROI at current scale) - Line counts in source references (would date quickly)
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
---
|
||||
status: draft
|
||||
status: stable
|
||||
last_updated: 2026-05-18
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@ Uses UJSX as a direct dependency. Workflow templates are `UNode` trees. Renders
|
||||
- **graphology DAG** — structural analysis, cycle detection, topological sort via a `HostConfig`
|
||||
- **Reactive execution engine** — runtime workflow execution with signal-based status propagation
|
||||
|
||||
See `docs/research/reconciler/05-flowgraph-host-configs.md` for the planned integration.
|
||||
See `../research/reconciler/05-flowgraph-host-configs.md` for the planned integration.
|
||||
|
||||
### Desktop UI (Spoke HUD)
|
||||
|
||||
@@ -118,11 +118,23 @@ last_updated: YYYY-MM-DD
|
||||
|
||||
ADR documents use a separate `Status` field in their body: `Proposed`, `Accepted`, `Deprecated`, or `Superseded`. ADRs never revert from `Accepted`. Note that ADR frontmatter (`status: draft`) refers to the **document's editorial status** (is the writing complete?), while the body `Status` refers to the **decision's status** (is this decision finalized?). A `Proposed` decision can have a `draft` document; an `Accepted` decision has a `stable` document.
|
||||
|
||||
## Error Handling Philosophy
|
||||
|
||||
UJSX follows a tiered approach to errors:
|
||||
|
||||
- **Programmer errors throw**. Invalid arguments (`h()` called without a type), missing required parameters, or `transform()` failing to find a matching rule — these are bugs that should surface immediately with a stack trace. Failing silently makes debugging harder.
|
||||
|
||||
- **Operational conditions are no-ops with defined behavior**. `selectNode` returning `undefined` for invalid paths, `setNode` returning the node unchanged for unresolvable paths, `Fragment` with no children producing an empty array — these are not errors, they are well-defined boundary conditions. The caller is responsible for checking the result.
|
||||
|
||||
- **Host errors propagate**. If `HostConfig.createInstance` throws, the error bubbles up through `mountNode` with no host involvement. UJSX does not catch or suppress host errors. The current implementation has no `handleError` hook on `HostConfig` — whether to add one is an open question (see [host-config.md](host-config.md) Open Question 4).
|
||||
|
||||
- **Recovery is the caller's responsibility**. `ReactiveRoot.subscribe()` returns a dispose function; if the caller discards it, the effect leaks. `unmount()` is a stub. There is no automatic retry, circuit breaking, or error event emission for operational failures. These concerns belong to the host or consumer, not to the core library.
|
||||
|
||||
## References
|
||||
|
||||
- UJSX research index: `docs/research/README.md`
|
||||
- Reconciler research: `docs/research/reconciler/`
|
||||
- SDD process: `docs/sdd_process.md`
|
||||
- UJSX research index: `../research/README.md`
|
||||
- Reconciler research: `../research/reconciler/`
|
||||
- SDD process: `../sdd_process.md`
|
||||
- Preact signals-core: `@preact/signals-core`
|
||||
- TypeBox: `@alkdev/typebox`
|
||||
- Taskgraph_ts architecture pattern: `/workspace/@alkdev/taskgraph_ts/docs/architecture/`
|
||||
Reference in New Issue
Block a user