Commit Graph

4 Commits

Author SHA1 Message Date
ed8710a7f5 Clean up architecture specs: remove stale references, align docs with code, improve readability
- Replace stale DD references (DD3, DD6, DD9, DD10) with proper ADR links
- Fix 'Open Question 1' → OQ-01/OQ-03 cross-references
- Rewrite metagraph-module.md 'Why TypeBox Modules' to describe capabilities
  directly instead of framing as SchemaBuilder replacement
- Remove 'Transition from SchemaBuilder' section, replace with Source Structure
- Clean up implementation path: strikethrough phases → status table
- Fix data model diagram: remove non-existent nodeTypeId, fix EdgeType label
- Align EdgeConstraints examples with actual code (add default values)
- Clarify validateNode/validateEdge error behavior in docs
- Align EncryptedDataSchema code example with actual implementation
- Fix overview.md: correct dependency table, update current state, fix TypeBox URL
- Fix forward-look.md garbled text about dbtype element migration
- Fix open-questions.md: correct OQ count (4→7 open), add summary table
- Update doc statuses: schema-evolution, encrypted-data, open-questions → reviewed
- Update AGENTS.md to reflect current implementation state
2026-05-30 09:12:24 +00:00
95e02f939d docs: add schema-evolution.md — TypeBox Value.Diff/Patch/Cast for schema evolution 2026-05-28 16:31:25 +00:00
1e804b9174 docs: remove backward compatibility framing from architecture specs 2026-05-28 16:18:54 +00:00
5ce93b1357 docs: add metagraph-module and forward-look architecture specs, remove SchemaBuilder legacy support
Graph type definitions as TypeBox Modules — the core architecture evolution
for @alkdev/storage. The SchemaBuilder is removed (no existing consumers),
replaced by direct TypeModule construction with Metagraph.Import() for
base attribute composition and Type.Composite() for node/edge type
specialization.

Key additions:
- metagraph-module.md: Module pattern, edge constraints as named entries,
  SchemaBuilder equivalence, DB bridge contracts (moduleToDbSchema return
  type, validateNode/validateEdge signatures), 10 design decisions (DD1-DD10)
- forward-look.md: pointer abstraction (ujsx ValuePointer analogy, JPATH
  Module), dbtype table rendering relationship, ujsx as universal IR pipeline

Critical corrections from architecture review:
- Type.Composite uses IntersectEvaluated (intersection, not Object.assign
  override) — overlapping keys with subtype relationships resolve correctly
- Type.Ref inside Type.Composite within a Module is verified working
- BaseNode/BaseEdge use Metagraph.Import() for same-package Modules (Option B),
  not local re-declaration (no circular dep within same package)
- Edge constraints use Type.String() for node type name arrays (not Type.Ref) —
  constraints contain names, not schemas
2026-05-28 15:32:56 +00:00