storage/AGENTS.md

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/              # Schema types + SchemaBuilder (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 → graphs types + SchemaBuilder (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 a known technical debt item — 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

deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts  # Type check
deno lint                                               # Lint (slow-types excluded)
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)
• client.ts refactored to be injectable
• Module-level db and client exports removed

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)

What's Not Done Yet

• src/pg/ — PostgreSQL host (same table shapes, pgTable + jsonb + timestamp + pgEnum)
• 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)