glm-5.1
3b63d92976
The historical reference doc was exactly the confusing artifact we were cleaning up. Its unique content (the three-level type system overview and ASCII diagram) now lives in metagraph-module.md as an introductory section. Everything else was redundant: - Schema types → metagraph-module.md (Module entries) - SchemaBuilder → metagraph-module.md (SchemaBuilder Equivalence section) - Usage patterns → metagraph-module.md + encrypted-data.md (Module examples) - Composite identity / attributes storage → sqlite-host.md (table definitions) - Versioning → schema-evolution.md (thorough treatment) - Ecosystem context → overview.md (Ecosystem Integration section) All cross-references updated: AGENTS.md, sqlite-host.md, schema-evolution.md.
125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
# AGENTS.md — @alkdev/storage
|
|
|
|
Project-specific guidance for agents working on this package.
|
|
|
|
## Project Overview
|
|
|
|
`@alkdev/storage` is a deno-first TypeScript package providing typed graph
|
|
storage with dual database hosts (SQLite for spokes, PostgreSQL for the hub). It
|
|
uses the metagraph pattern (graphTypes → nodeTypes → edgeTypes → typed graph
|
|
instances) from the earlier `@ade` prototype.
|
|
|
|
## Architecture Snapshot
|
|
|
|
```
|
|
@alkdev/storage/
|
|
├── mod.ts # Re-exports graphs/ only (zero db deps)
|
|
├── deno.json # JSR config, imports, tasks, lint rules
|
|
├── src/
|
|
│ ├── graphs/ # Metagraph Module + bridge functions (no db deps)
|
|
│ ├── sqlite/ # SQLite host (drizzle-orm/libsql)
|
|
│ │ ├── tables/ # Drizzle table definitions
|
|
│ │ ├── relations.ts # Drizzle relations
|
|
│ │ ├── schema.ts # Re-exports
|
|
│ │ └── client.ts # Injectable createSqliteDatabase()
|
|
│ └── pg/ # PostgreSQL host (NOT YET IMPLEMENTED)
|
|
└── test/
|
|
```
|
|
|
|
### Subpath Exports (JSR/npm)
|
|
|
|
- `@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
|
|
IMPLEMENTED)
|
|
|
|
This design ensures consumers don't bundle database drivers they don't use.
|
|
|
|
## Key Decisions
|
|
|
|
1. **Deno-first, npm-second via JSR**: Package is published to JSR
|
|
(`deno publish`). npm compatibility is automatic via JSR's npm layer
|
|
(`@jsr/alkdev__storage`). No separate dnt build step.
|
|
2. **No comments in code**: Per project convention across @alkdev packages.
|
|
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics
|
|
(`sqliteTable`, `createInsertSchema`, `relations`) make explicit type
|
|
annotations impractical. We use `--allow-slow-types` on publish and
|
|
`"exclude": ["no-slow-types"]` in lint config. This is known technical debt —
|
|
can be tightened iteratively.
|
|
4. **Injectable clients**: `createSqliteDatabase(client)` takes a client, not
|
|
env vars. Module-level side effects are forbidden.
|
|
5. **Dependencies**: `@alkdev/typebox` and `@alkdev/drizzlebox` are npm deps
|
|
(not yet on JSR). This works fine — JSR handles npm dependencies natively.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts # Type check
|
|
deno lint # Lint (slow-types, verbatim-module-syntax excluded)
|
|
deno task lint:analyze # Analyze lint issues by code/file grouping
|
|
deno fmt # Format
|
|
deno test --allow-all test/ # Run tests
|
|
deno publish --allow-slow-types --dry-run # Dry-run publish
|
|
```
|
|
|
|
## Source Heritage
|
|
|
|
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:
|
|
|
|
- `@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
|
|
|
|
## File Conventions
|
|
|
|
- All source files use `.ts` extension with explicit extensions in imports (Deno
|
|
convention)
|
|
- Entry points are `mod.ts` files that re-export from subdirectories
|
|
- TypeBox schemas are named with PascalCase (`NodeType`, `GraphConfig`)
|
|
- Drizzle table objects are named with camelCase (`graphTypes`, `nodeTypes`)
|
|
- Schema objects from drizzlebox are named with PascalCase (`InsertGraph`,
|
|
`SelectGraph`)
|
|
- Enum constants use `SCREAMING_SNAKE_CASE` objects (`GRAPH_STATUS`,
|
|
`ACTOR_TYPE`)
|
|
|
|
## Architecture Docs
|
|
|
|
See `docs/architecture/` for detailed specifications:
|
|
|
|
- `overview.md` — Package purpose, exports, design decisions, open questions
|
|
- `metagraph-module.md` — Graph type definitions as TypeBox Modules, data model,
|
|
naming conventions, implementation path
|
|
- `forward-look.md` — Connections to dbtype, graph pointers, ujsx universal IR
|
|
pipeline
|
|
- `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
|
|
|
|
These docs describe what the package is AND what it's becoming. Items marked ⚠️
|
|
are not yet implemented.
|
|
|
|
## What's Not Done Yet
|
|
|
|
- `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.)
|
|
- JSR publication setup (need to create scope/package on jsr.io first)
|