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:
2026-05-28 15:32:56 +00:00
parent 33a5b0816d
commit 5ce93b1357
5 changed files with 1123 additions and 9 deletions

View File

@@ -16,7 +16,7 @@ instances) from the earlier `@ade` prototype.
├── mod.ts # Re-exports graphs/ only (zero db deps)
├── deno.json # JSR config, imports, tasks, lint rules
├── 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 relations
@@ -28,7 +28,7 @@ instances) from the earlier `@ade` prototype.
### Subpath Exports (JSR/npm)
- `@alkdev/storage` → graphs types + SchemaBuilder (zero deps)
- `@alkdev/storage`Metagraph Module, graph type definitions (zero deps)
- `@alkdev/storage/sqlite` → SQLite tables, relations, client (drizzle-orm +
libsql)
- `@alkdev/storage/pg` → PostgreSQL tables, relations, client (NOT YET
@@ -79,6 +79,7 @@ Key changes from the originals:
`GRAPH_STATUS`)
- `client.ts` refactored to be injectable
- Module-level `db` and `client` exports removed
- `SchemaBuilder` removed — replaced by `Type.Module()` construction
## File Conventions
@@ -99,6 +100,10 @@ See `docs/architecture/` for detailed specifications:
- `overview.md` — Package purpose, exports, design decisions, open questions
- `metagraph.md` — Core graph model, schema types, SchemaBuilder, attribute
storage
- `metagraph-module.md` — Graph type definitions as TypeBox Modules (evolution
of metagraph.md), naming conventions, migration path
- `forward-look.md` — Connections to dbtype, graph pointers, ujsx universal IR
pipeline
- `sqlite-host.md` — SQLite tables, relations, client factory, porting notes
- `encrypted-data.md` — Encrypted data design (planned), crypto utility, node
type modeling