# 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.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

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)