Files

glm-5.1 3b63d92976 docs: delete metagraph.md, migrate data model into metagraph-module.md

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.

2026-05-29 05:27:08 +00:00

5.3 KiB

Raw Blame History

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

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.
No comments in code: Per project convention across @alkdev packages.
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.
Injectable clients: createSqliteDatabase(client) takes a client, not env vars. Module-level side effects are forbidden.
Dependencies: @alkdev/typebox and @alkdev/drizzlebox are npm deps (not yet on JSR). This works fine — JSR handles npm dependencies natively.

Commands

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)

5.3 KiB Raw Blame History