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
This commit is contained in:
40
AGENTS.md
40
AGENTS.md
@@ -17,6 +17,14 @@ instances) from the earlier `@ade` prototype.
|
||||
├── deno.json # JSR config, imports, tasks, lint rules
|
||||
├── src/
|
||||
│ ├── graphs/ # Metagraph Module + bridge functions (no db deps)
|
||||
│ │ ├── modules/ # TypeBox Module definitions
|
||||
│ │ │ ├── metagraph.ts # Base Metagraph Module (Config, BaseNode, BaseEdge)
|
||||
│ │ │ ├── call-graph.ts # CallGraph reference Module
|
||||
│ │ │ ├── secret-graph.ts # SecretGraph reference Module
|
||||
│ │ │ └── index.ts # Barrel re-export
|
||||
│ │ ├── bridge.ts # moduleToDbSchema, validateNode, validateEdge
|
||||
│ │ ├── crypto.ts # encrypt, decrypt, generateEncryptionKey, EncryptedDataSchema
|
||||
│ │ └── mod.ts # Re-exports all graphs exports
|
||||
│ ├── sqlite/ # SQLite host (drizzle-orm/libsql)
|
||||
│ │ ├── tables/ # Drizzle table definitions
|
||||
│ │ ├── relations.ts # Drizzle relations
|
||||
@@ -24,6 +32,7 @@ instances) from the earlier `@ade` prototype.
|
||||
│ │ └── client.ts # Injectable createSqliteDatabase()
|
||||
│ └── pg/ # PostgreSQL host (NOT YET IMPLEMENTED)
|
||||
└── test/
|
||||
└── reference-modules.test.ts # Metagraph, bridge, crypto tests
|
||||
```
|
||||
|
||||
### Subpath Exports (JSR/npm)
|
||||
@@ -67,19 +76,20 @@ deno publish --allow-slow-types --dry-run # Dry-run publish
|
||||
|
||||
The `graphs/` and `sqlite/` modules were adapted from
|
||||
`@ade/ade-v0/packages/core/graphs` and `@ade/ade-v0/packages/storage_sqlite`.
|
||||
Key changes from the originals:
|
||||
The codebase has diverged significantly from the originals:
|
||||
|
||||
- `@sinclair/typebox` → `@alkdev/typebox`
|
||||
- `drizzle-typebox` → `@alkdev/drizzlebox`
|
||||
- `@ade/core` imports → relative imports within `src/graphs/`
|
||||
- `import type { GraphConfig }` → `import { GraphConfig }` (TypeBox schemas are
|
||||
both values and types)
|
||||
- `Relation` type alias removed (JSR slow type)
|
||||
- TypeScript enums replaced with `as const` objects (`EnumGraphStatus` →
|
||||
`GRAPH_STATUS`)
|
||||
- `client.ts` refactored to be injectable
|
||||
- Module-level `db` and `client` exports removed
|
||||
- `SchemaBuilder` removed — replaced by `Type.Module()` construction
|
||||
- All schemas use `Type.Module()` construction (not `SchemaBuilder`)
|
||||
- `Metagraph`, `CallGraph`, `SecretGraph` are TypeBox Modules composing via
|
||||
`Import()` and `Type.Composite()`
|
||||
- Bridge functions (`moduleToDbSchema`, `validateNode`, `validateEdge`) project
|
||||
Modules to DB row values
|
||||
- Crypto utility ported from `@alkdev/hub/src/crypto/mod.ts` with `EncryptedDataSchema`
|
||||
as a TypeBox schema
|
||||
- `@sinclair/typebox` → `@alkdev/typebox`, `drizzle-typebox` → `@alkdev/drizzlebox`
|
||||
- TypeScript enums replaced with `as const` objects (`GRAPH_STATUS`, `ACTOR_TYPE`)
|
||||
- `Type.Unknown()` used for unvalidated fields (not `Type.Any()`)
|
||||
- Injectable client pattern (`createSqliteDatabase(client)` takes a pre-created client)
|
||||
- No module-level side effects or state
|
||||
|
||||
## File Conventions
|
||||
|
||||
@@ -105,8 +115,7 @@ See `docs/architecture/` for detailed specifications:
|
||||
- `schema-evolution.md` — How graph type schemas evolve, TypeBox Value.Diff/Patch/Cast
|
||||
for schema change detection and data migration
|
||||
- `sqlite-host.md` — SQLite tables, relations, client factory, porting notes
|
||||
- `encrypted-data.md` — Encrypted data design (planned), crypto utility, node
|
||||
type modeling
|
||||
- `encrypted-data.md` — Encrypted data design, crypto utility, node type modeling
|
||||
|
||||
These docs describe what the package is AND what it's becoming. Items marked ⚠️
|
||||
are not yet implemented.
|
||||
@@ -115,9 +124,6 @@ are not yet implemented.
|
||||
|
||||
- `src/pg/` — PostgreSQL host (same table shapes, `pgTable` + `jsonb` +
|
||||
`timestamp` + `pgEnum`)
|
||||
- `src/graphs/crypto.ts` — Crypto utility (`encrypt`, `decrypt`,
|
||||
`generateEncryptionKey`, `EncryptedDataSchema`)
|
||||
- Tests
|
||||
- Repository/CRUD layer (currently only table definitions, no typed query
|
||||
functions)
|
||||
- Hub-specific tables (sessions, messages, parts, call graphs, tasks, etc.)
|
||||
|
||||
Reference in New Issue
Block a user