andy
3de6e53ab0
Foundation for the persistent, inspectable cognitive runtime: README, implementation plan with phases and risk register, architecture, security model, threat model, contributing guide, eight ADRs covering the global workspace, event immutability, memory representation, LLM abstraction, capability system, authentication, frontend and storage. Includes Makefile, env example, compose stack (pgvector) and Dockerfile skeleton, plus a record of the development environment assumptions.
1008 B
1008 B
ADR-0008: PostgreSQL with explicit SQL and embedded migrations
Date: 2026-09-14
Status: Accepted
Context
Requirement: PostgreSQL, proper migrations, no ORM auto-mutation, optional pgvector.
Decision
pgx v5 with pgxpool; repository types per domain with hand-written SQL; numbered NNNN_name.up.sql / .down.sql files embedded from migrations/ and applied by a small runner (advisory lock, schema_migrations table with checksum). The embeddings migration uses a PL/pgSQL block that creates vector objects only if the extension is available; the runtime detects availability at start.
Consequences
- No hidden schema changes; migration state visible in the System page and
noemactl migrate status. - Tests needing the database use a per-run schema and skip when no URL is configured.
Alternatives considered
- golang-migrate/goose: fine tools, but a 150-line runner avoids a dependency and matches our exact needs.
- sqlc: attractive later; deferred to keep the toolchain minimal.