docs: propose ADR 0050, Module Database ABI v1

Core and modules exchange PostgreSQL SQL text, bound parameters, result rows with field metadata, and Core-owned transaction scopes. Never ORM objects. A module may use Drizzle, Kysely, raw SQL, or another module-side builder. Core's own ORM becomes an implementation detail. ADR 0050 decides: - an explicit correctness/compatibility boundary, not a security sandbox: no claim for SQL parsing, execution-time prefix checks, SET ROLE, or PostgreSQL roles; - opt-in through manifest version 8 `database.abi: 1`, a hard cutover like every manifest version; a version 8 module without `database` keeps the legacy ModuleDatabase facade during the deprecation window; - the executor: query({ text, values, rowMode }) returning { command, rowCount, rows, fields }, one executor per module; - a small parameter set (no Date, no implicit JSON, no identifiers); - a Core-owned decoding table that loses no precision and does not depend on time zones (int8, numeric, temporal, and JSON as text; bytea as Uint8Array); - a sanitized ModuleDatabaseError { code, sqlState? }, recognised structurally; - callback-scoped transactions and Core-named savepoints, revoked when their callback settles; - module-side adapters (Drizzle via pg-proxy, raw SQL, later Kysely); - plain schema metadata for ABI v1 modules instead of Drizzle objects; - migrations unchanged; packageFormat stays 1; ABI v1 packages omit transitional.databaseRuntime. It partly supersedes ADR 0016 and amends ADR 0007 for ABI v1 modules, and extends ADR 0049. Status Proposed. Accepted ADRs are unchanged. No runtime, SDK, manifest, packaging, migration, or Signage changes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-07 15:18:59 -05:00
parent 9ddb5e2796
commit 759872834d
3 changed files with 504 additions and 1 deletions
@@ -58,3 +58,4 @@ ADRs capture durable choices that affect more than one package or phase.
 - [0047: Every module proves itself inside Ekklesia, with one harness the platform publishes](0047-module-ci-harness.md) — Proposed
 - [0048: Ekklesia ships one generic image, and installed modules live outside it](0048-generic-image-and-installed-module-storage.md) — Accepted
 - [0049: A module release is one immutable, self-contained package: Ekklesia Module Package v1](0049-module-package-v1.md) — Accepted
+- [0050: Module Database ABI v1: modules and Core exchange SQL, never ORM objects](0050-module-database-abi-v1.md) — Proposed