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
This commit is contained in:
@@ -29,7 +29,7 @@ ecosystem.
|
||||
@alkdev/storage/
|
||||
├── mod.ts → re-exports graphs/ (zero db deps)
|
||||
├── src/
|
||||
│ ├── graphs/ → schema types + SchemaBuilder (no db deps)
|
||||
│ ├── graphs/ → Metagraph Module, bridge functions (no db deps)
|
||||
│ ├── sqlite/ → SQLite host (drizzle-orm/libsql)
|
||||
│ │ ├── tables/ → drizzle table definitions
|
||||
│ │ ├── relations.ts → drizzle relational mappings
|
||||
@@ -85,12 +85,16 @@ type with specific node types (operation call, subcall) and edge types
|
||||
This trades some query convenience for generality. Domain-specific queries are
|
||||
built on top of the graph query layer, not baked into table schemas.
|
||||
|
||||
### D3: SchemaBuilder as the primary API surface
|
||||
### D3: Type.Module as the primary API surface
|
||||
|
||||
The `SchemaBuilder` fluent API is the intended way to construct graph type
|
||||
definitions. It validates against TypeBox schemas at build time, ensuring that
|
||||
graph/node/edge type definitions are structurally sound before they're persisted
|
||||
to the database.
|
||||
The `Type.Module()` construction API is the intended way to define graph type
|
||||
definitions. The `Metagraph` Module provides base entries (`BaseNode`,
|
||||
`BaseEdge`, `Config`); concrete graph types compose them via `Metagraph.Import()`
|
||||
and `Type.Composite()`. The `SchemaBuilder` is removed.
|
||||
|
||||
This replaces the earlier fluent builder pattern. The Module format provides
|
||||
native `Type.Ref()` for internal references, `Module.Import()` for cross-package
|
||||
references, and JSON Schema `$defs` that map directly to DB storage.
|
||||
|
||||
### D4: Injectable clients, no module-level side effects
|
||||
|
||||
@@ -147,7 +151,7 @@ consumed by the hub and spokes, not by storage itself.
|
||||
|
||||
### Implemented
|
||||
|
||||
- Graph schema types and SchemaBuilder
|
||||
- Graph schema types and Metagraph Module (replaces SchemaBuilder)
|
||||
- SQLite host: 6 metagraph tables + actors table + Drizzle relations + client
|
||||
factory
|
||||
- TypeBox select/insert schemas generated from Drizzle tables (drizzlebox)
|
||||
@@ -296,6 +300,8 @@ storage node attributes and operations call events), they should either:
|
||||
|
||||
## References
|
||||
|
||||
- Metagraph Module evolution: [metagraph-module.md](./metagraph-module.md)
|
||||
- Forward-looking connections: [forward-look.md](./forward-look.md)
|
||||
- Operations architecture: `/workspace/@alkdev/operations/docs/architecture/README.md`
|
||||
- Pubsub architecture: `/workspace/@alkdev/pubsub/docs/architecture/README.md`
|
||||
- Flowgraph architecture: `/workspace/@alkdev/flowgraph/docs/architecture/README.md`
|
||||
|
||||
Reference in New Issue
Block a user