Ekklesia/docs/architecture/decisions/0050-module-database-abi-v1.md

# 0050: Module Database ABI v1: modules and Core exchange SQL, never ORM objects

- Status: Accepted
- Date: 2026-10-07
- Supersedes (partial): [0016](0016-module-database-access.md) — for modules that declare ABI v1,
  only its definition of the module database service as `Pick<NodePgDatabase, …>`, a facade over
  Core's Drizzle instance, and its rule that every module receives the same `services` object.
  One pool, no pool or connection string for modules, no database access during `register`, the
  shutdown order, handler error sanitization, and the trust boundary remain accepted and unchanged.
  Modules that do not declare ABI v1 keep ADR 0016's facade until it is removed (see
  [Compatibility and deprecation](#compatibility-and-deprecation)).
- Amends: [0007](0007-module-owned-drizzle-schemas.md) — for modules that declare ABI v1, the
  schema definition Core inspects is plain Ekklesia-owned metadata instead of Drizzle table objects.
  Table namespacing, identifier rules, uniqueness, same-module foreign keys, atomic aggregation, and
  sanitized discovery errors remain accepted and unchanged.
- Extends: [0049](0049-module-package-v1.md) — this is the Module Database ABI that ADR 0049 deferred
  and anticipated. ABI v1 packages carry no `transitional.databaseRuntime`. `packageFormat` stays 1.
- Related: [ADR 0006](0006-versioned-capabilities-and-compiled-module-runtime.md),
  [ADR 0008](0008-module-owned-migration-contracts.md),
  [ADR 0009](0009-transactional-module-migrations.md),
  [ADR 0015](0015-static-module-http-routing-and-runtime-lifecycle.md),
  [ADR 0021](0021-modules-as-hostable-products.md),
  [ADR 0047](0047-module-ci-harness.md),
  [ADR 0048](0048-generic-image-and-installed-module-storage.md)

## Context

ADR 0016 gave module code database access through `ModuleDatabase`, which is
`Pick<NodePgDatabase, "select" | "selectDistinct" | "selectDistinctOn" | "insert" | "update" |
"delete" | "execute" | "transaction">`. Core implements it as a frozen object whose eight methods are
bound to Core's own `drizzle(pool)` instance.

ADR 0048 then took modules out of the platform image, and ADR 0049 made each module release a
self-contained package that bundles its own copy of Drizzle. The two copies now meet at run time,
and an investigation of the current code (Drizzle 0.45.2) found the coupling runs deeper than a
type:

- **Module objects cross into Core's ORM.** A module builds queries from table, column, and `SQL`
  objects made by its own Drizzle copy. Core's Drizzle instance then compiles and decodes them.
  This only works while the two copies agree on internal symbols and entity kinds, which is why ADR
  0049 records the module's Drizzle version under `transitional.databaseRuntime` and refuses a
  mismatch.
- **Core's ORM objects cross into the module.** `transaction` hands module code Core's live
  `NodePgTransaction`. At run time that object is a full Drizzle database: its session, dialect,
  relational query builder, and `rollback()` are all reachable, whatever the `Pick` type says. A
  reference kept after the callback settles still points at a connection that has returned to the
  pool.
- **Result decoding is split between two ORMs.** Core's Drizzle session overrides `pg`'s parsers
  for each query, so temporal values arrive as raw text. Then the module's column objects convert
  them. Neither half is an Ekklesia contract. `pg`'s default parsers are also process-global and
  mutable, and some lose information: `jsonb` numbers beyond double precision, and `numeric[]`
  elements, are parsed to JavaScript numbers.
- **Errors are ORM and driver shapes.** A module that needs to recognize a PostgreSQL condition
  reads it from whatever object Drizzle or `pg` throws. Drizzle 0.45 wraps driver errors in its own
  error type, whose message carries the SQL text and the parameters.
- **Schema validation needs Drizzle objects.** Module validation, Doctor, and the package verifier
  import a module's schema entrypoint and inspect it with Drizzle's `is(…, PgTable)`,
  `getTableConfig`, and `PgColumn`. That is the same cross-copy dependency, at validation time. Core
  extracts only plain facts from it: table names and foreign-key target tables.

Two findings show the dependency is unnecessary:

- **Migration execution is already independent of the ORM runtime.** Migration discovery reads SQL
  files and JSON metadata, and the runner executes SQL text. Neither imports Drizzle. Drizzle Kit
  snapshots are validated metadata; they are not needed to apply a migration.
- **The module side can compile to SQL alone.** Drizzle and Kysely both compile a query to
  PostgreSQL text with `$n` placeholders and an ordered parameter list. Drizzle 0.45.2's own
  `pg-proxy` driver, given only a callback that receives SQL text, parameters, and an array-or-object
  row mode, ran `select`, `update`, and `insert … returning`, and decoded `timestamptz` and `int8`
  text with the module's own column definitions. That driver has no transactions, which a
  module-side adapter has to supply.

Signage 0.1.2, the first production module, uses `select`, `insert`, `update`, `delete`,
`transaction`, one `returning`, and SQL expressions in `set` clauses. It uses no `execute`, joins,
row locks, isolation options, or result row counts. None of its usage needs a Core ORM object. It
recognizes a uniqueness conflict by reading SQLSTATE `23505` from the thrown error. A stable,
Ekklesia-owned place for that code is desirable regardless of which ORM either side uses. (This
paragraph is motivation, not part of the decision.)

## Decision

### The goal: the ORM is an implementation detail on both sides

Ekklesia defines a stable, Ekklesia-owned **Module Database ABI** between Core and modules.

- **The boundary is PostgreSQL itself.** Exactly these concepts cross it:
  - SQL text;
  - ordered, bound parameter values;
  - result rows and their metadata;
  - transaction scopes that Core controls.
- **Core never receives or depends on a module's ORM or query-builder object.** That includes:
  - Drizzle tables, columns, `SQL` objects, query builders, and transactions;
  - Kysely objects;
  - any other third-party ORM or runtime object.
- **Modules never receive Core's ORM objects, driver objects, or connections.**
- **Each side chooses its own tools.** A module may use Drizzle, Kysely, raw SQL, or any module-side
  query builder that produces PostgreSQL text and parameters. Core may keep Drizzle, or replace it,
  without any module noticing.

This ADR defines **Module Database ABI version 1**. The TypeScript names below are illustrative; the
concepts and the semantics are the contract.

### A correctness boundary, not a security boundary

**The Module Database ABI is a correctness and compatibility boundary. It is not a security
sandbox.** Installed modules remain trusted backend code running inside the API process with its
database role (ADR 0006, ADR 0016, ADR 0048).

Nothing in this ADR claims, and nothing built from it may claim, that the following can stop
malicious module code from reaching data that is not its own:

- the ABI itself;
- parsing or inspecting SQL;
- checking table prefixes when statements execute;
- `SET ROLE`;
- PostgreSQL roles.

A module sends arbitrary SQL by design, including SQL that changes its role back. It also runs
in-process, where it can reach the network and the environment without the ABI.

Table ownership remains what ADR 0007 made it: a static correctness check of declared tables and
foreign keys, run during validation. The ABI keeps that check honest by removing the ORM objects it
used to depend on. It adds no runtime enforcement.

### Declaring the ABI: manifest version 8

A module opts into the ABI explicitly, in its static manifest. The manifest is strict and changes by
hard cutover (ADR 0006, ADR 0014, ADR 0021, ADR 0029), so the declaration arrives with
**manifest version 8**. Conceptually:

```json
{
  "manifestVersion": 8,
  "database": { "abi": 1 }
}
```

- **`database.abi: 1`** means the module receives a Module Database ABI v1 executor. It never
  receives the legacy facade.
- **No `database` field** means the module receives ADR 0016's legacy `ModuleDatabase` facade
  during the deprecation window.
- **Any other ABI value** fails validation. A platform that does not implement a declared ABI refuses
  the module rather than guessing.
- **Version 8 is a hard cutover, like every manifest version before it.** Core parses exactly one
  manifest version; it never parses version 7 and version 8 side by side.
  - An existing source module moves to version 8, and repacks, without changing any database code.
  - A package already built with a version 7 manifest must be rebuilt.
  - Module Package v1 has only just landed, and no published ecosystem depends on version 7
    packages, so this costs a rebuild and nothing more.

In this ADR, a **legacy module** means a module with a version 8 manifest and no `database`
declaration, which therefore uses the legacy facade. It never means a module with a version 7
manifest.

Because the declaration is static, Core, the packager, and the verifier know a module's database
contract without loading its code. Because Core enforces it, an ABI v1 module cannot reach the
legacy facade, so nothing at run time can depend on Drizzle agreement.

The rest of manifest version 8 (field placement, validation messages, the template, and the
cutover itself) is an implementation detail of the change that introduces it.

### The executor

An ABI v1 module's database service is an **executor**. Conceptually:

```ts
query({ text, values, rowMode }) → { command, rowCount, rows, fields }
transaction(callback, options)   → the callback's result
```

- **`text`** is exactly one PostgreSQL statement, using `$1 … $n` placeholders. **One `query` call
  runs one statement.** This is a correctness and API rule, not a security boundary.
  - The implementation upholds it with a reliable driver or protocol mechanism where one exists,
    such as PostgreSQL's extended query protocol, which accepts a single statement per request.
  - It does not require, and must not grow, an Ekklesia SQL parser.
  - If an implementation cannot reliably uphold this rule, the implementing change stops and reports
    the conflict. It does not weaken this ADR silently.
- **`values`** is the ordered list of bound parameters (see
  [Parameters](#parameters)). Values are always bound and never interpolated into the text.
- **`rowMode`** is `"object"` or `"array"`.
  - `"object"` rows are keyed by column name.
  - `"array"` rows are positional, in `fields` order. An ORM that selects the same column name twice,
    as joins do, needs this mode.
  - Duplicate column names are invalid in object mode. Core rejects such a result rather than
    silently dropping a column.
  - With the current PostgreSQL and driver execution path, the result's shape is only known once
    the statement has run. So a mutating statement can already have had its effects when the
    result-shape error is reported.
  - This is not a security guarantee. A caller that needs atomicity runs the mutation inside an ABI
    transaction, where the error rolls the mutation back with everything else.
- **`command`** is PostgreSQL's command tag word, such as `SELECT`, `INSERT`, `UPDATE`, or `DELETE`.
- **`rowCount`** is the number of rows PostgreSQL reports as processed, or `null` when it reports
  none.
- **`rows`** are the result rows, decoded as in [Results](#results). `RETURNING` rows are ordinary
  rows.
- **`fields`** are the ordered column metadata, present even when there are no rows: at least each
  column's name and its PostgreSQL type OID.

The executor contains no ORM type, AST, query object, or schema object, and accepts none.

**One executor per module.** Each ABI v1 module receives its own executor, bound to its module id.
The module's `start` and `stop` hooks and its route handlers all receive that same object, which
keeps ADR 0016's guarantee that lifecycle code and handlers share one database service. Different
modules get different executors, so Core can attribute every statement to the module that issued it.

**Observability belongs to Core.** Core may record per-module timings, command tags, row counts, and
error codes. It never writes SQL text or parameter values to logs, diagnostics, Doctor output, or
HTTP responses.

**Session state is not part of the ABI.** Top-level `query` calls are separate autocommit statements
that may run on different pooled connections. A module must not rely on session-level state, and
must not change it. That includes:

- session `SET`;
- temporary tables;
- named prepared statements;
- `LISTEN`;
- session advisory locks.

Settings that must hold for one unit of work use `SET LOCAL` inside a transaction. Core may reset or
discard a connection that a module changed. `COPY`, cursors, streaming results, and named prepared
statements are not part of v1.

### Parameters

The ABI deliberately accepts a small set of PostgreSQL wire-safe values:

| Value | Sent as |
| --- | --- |
| `null` | SQL `NULL` |
| `boolean` | `true` / `false` |
| `number` | its JavaScript decimal text; `NaN`, `Infinity`, and `-Infinity` as PostgreSQL's `NaN`, `Infinity`, and `-Infinity` |
| `bigint` | its decimal text |
| `string` | the text, unchanged |
| `Uint8Array` | `bytea` |
| arrays of the above | a PostgreSQL array, nested for more dimensions |

Everything else is refused with a sanitized error before anything reaches PostgreSQL, rather than
being coerced. In particular:

- **`Date` is not an ABI parameter.** A JavaScript `Date` is an instant. Whether it should become a
  `timestamp` or a `timestamptz`, and in which time zone, depends on a column type the ABI cannot
  see. The module-side adapter converts it to explicit text first; for example, Drizzle's timestamp
  columns already send ISO-8601 text.
- **Plain objects are not implicit JSON.** A module or adapter encodes JSON explicitly, as a string,
  and the SQL casts it where needed.
- **Identifiers are never parameters.** Table and column names are part of the module's compiled
  SQL text. The ABI provides no identifier interpolation.

### Results

Core owns one documented decoding table for ABI v1. It does not depend on `pg`'s global parser
registry, which module code could change, or on any ORM. Values that a generic conversion could
change, or change silently by time zone, arrive in a stable raw form:

| PostgreSQL type | Arrives as |
| --- | --- |
| any `NULL` | `null` |
| `bool` | `boolean` |
| `int2`, `int4`, `oid` | `number` |
| `int8` | `string`, its exact decimal text |
| `float4`, `float8` | `number`, including `NaN` and `±Infinity` |
| `numeric` / `decimal` | `string`, its exact text (`NaN` included) |
| `text`, `varchar`, `bpchar`, `name`, `uuid` | `string` |
| `date`, `timestamp`, `timestamptz`, `time`, `timetz`, `interval` | `string`: PostgreSQL's ISO text output |
| `json`, `jsonb` | `string`: the JSON text, not parsed |
| `bytea` | `Uint8Array` |
| arrays of any of the above | JavaScript arrays (nested for more dimensions), each element decoded by the same rule, with `null` elements as `null` |
| any other type | `string`: PostgreSQL's text output |

- **Temporal text is fixed for every module.** Core fixes the session's `DateStyle` (ISO),
  `IntervalStyle` (`postgres`), and `TimeZone` (UTC) on every connection that serves the ABI. The
  same instant therefore always produces the same text, whatever the server's or the host's local
  zone.
- **`bytea` has one representation.** A value is a `Uint8Array`. A module must not rely on it being
  any particular subclass.
- **Higher-level conversion belongs to the module side.** Converting text to `Date`, `numeric` to a
  decimal type, `int8` to `bigint` or `number`, and JSON text to values is the adapter's job, or the
  module's. The Drizzle column types Signage uses already accept exactly these raw forms.

Changing how any type arrives, including decoding a type that arrives as text today, requires a new
ABI version.

### Errors

Every failure the executor reports is a Core-owned, sanitized **`ModuleDatabaseError`**.
Conceptually:

```ts
ModuleDatabaseError { code, sqlState? }
```

The two fields mean different things:

- **`code`** is always present. It is a stable, Ekklesia-owned error **category**, meant for
  programmatic handling. Its categories cover at least:
  - PostgreSQL rejected the statement;
  - a parameter value was refused;
  - a transaction option was refused;
  - the scope was closed or used incorrectly;
  - the transaction could not be completed.

  This ADR does not freeze the complete set or the exact names. Once published, a code keeps its
  meaning.
- **`sqlState`** is optional. It is the five-character SQLSTATE that PostgreSQL itself reported, such
  as `23505` (unique violation), `23503` (foreign-key violation), or `40001` (serialization failure).
  It is present only when the database supplied one, and Core never invents one.
  - Failures that the ABI detects itself have a `code` and no `sqlState`: a closed scope, an
    invalid parameter type, or an invalid transaction option.
  - Modules branch on `code` for ABI failures and on `sqlState` for PostgreSQL conditions.
- **It never carries:**
  - SQL text or parameter values;
  - the driver's message, detail, hint, constraint, table, or column names;
  - a stack, a cause, connection details, or any Core, `pg`, or Drizzle object.
- **Modules recognize it structurally** (its name and its `code`), never with `instanceof`. A module
  bundles its own copy of the SDK (ADR 0049), so class identity across the boundary is not a
  contract.

This replaces modules depending on `DrizzleQueryError`, `pg`'s `DatabaseError`, or any other driver
or ORM error shape. An uncaught `ModuleDatabaseError` in a route handler is sanitized at the
handler boundary exactly as before (ADR 0015, ADR 0016).

### Transactions

Transactions are **callback-scoped**, and Core owns the connection throughout:

```ts
transaction(async (tx) => { … }, { isolation, readOnly })
```

- **Starting.** Core takes a connection from its pool and begins a transaction with the requested
  options. It then calls the callback with `tx`, a Module Database ABI v1 executor scoped to that
  transaction alone. No `pg` client and no Core ORM transaction is ever exposed.
- **Commit and rollback.** Core commits only when the callback's promise resolves and no operation
  launched through `tx` is still outstanding. When the callback rejects, Core rolls back, and the
  transaction call rejects with the callback's error. There is no `rollback()` method: to roll back,
  the module throws.
- **All work is awaited inside the callback.** Module code must await every database operation it
  starts through `tx` before its callback returns. What happens when work is still outstanding
  depends on how the callback settled:
  - **Resolved with work outstanding.** The module forgot an `await` and has used the scope
    incorrectly. The transaction is never committed: Core rolls it back, and the transaction call
    rejects with the scope-usage `ModuleDatabaseError`. A forgotten `await` therefore fails. It never
    quietly changes what the transaction contains.
  - **Rejected with work outstanding.** The callback's own rejection stays the transaction's error.
    Core rolls back and does not replace that error, a PostgreSQL failure included, with the
    scope-usage error just because sibling work was still settling. This is what happens when one
    query in `await Promise.all([tx.query(a), tx.query(b)])` fails while the other is still running.
  - Either way, outstanding work never leads to a commit.
  - Core may let operations that already started finish, or settle, before it rolls back and releases
    the connection, so that a pooled connection is never handed on mid-operation. Waiting for them
    never turns into a commit.
- **Transaction control belongs to the callbacks.** Transaction-control SQL is forbidden through
  `query`: `BEGIN`, `START TRANSACTION`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `RELEASE SAVEPOINT`, and
  every other statement that starts, ends, or marks a transaction. Modules control a transaction's
  lifecycle only through the `transaction` and `savepoint` callbacks.
  - This is a conformance rule for trusted module code, not a sandbox or a security guarantee.
  - Core does not parse SQL to enforce it. Such a statement is valid PostgreSQL, so PostgreSQL
    executes it before Core can see its result.
  - Core detects a violation where the driver and protocol make that possible: from the statement's
    command tag, and from the connection's transaction status. It then fails safely:
    - the call rejects;
    - the transaction's scopes refuse every later statement without sending it, because it would
      otherwise run outside any transaction;
    - Core never commits the enclosing transaction itself, and that transaction rejects too;
    - the connection is destroyed rather than reused.
  - Core does not claim to undo a transaction-control statement PostgreSQL has already executed. A
    `COMMIT` sent through a transaction's `query` has already committed the work before it.
  - The commit and rollback guarantees in this section apply to conforming use of the ABI.
- **Revocation.** When the callback settles, `tx` is revoked, and it stays revoked once the scope has
  finished. Any later call on it fails with the
  closed-scope `ModuleDatabaseError` and sends nothing to PostgreSQL. A `tx` that escapes its
  callback can never run a statement on a connection that has gone back to the pool.
- **Options.** `isolation` is `read committed`, `repeatable read`, or `serializable`. `readOnly` is a
  boolean. An unknown option or value is refused, never ignored. `deferrable` is reserved for a
  later version.
- **No automatic retries.** Core never retries a transaction. A callback may have side effects
  outside the database, so retrying on `40001` is the module's decision.
- **Failed statements.** PostgreSQL semantics apply unchanged. After a failed statement the
  transaction is aborted, and later statements fail until the scope ends. A module that wants to
  continue after a failure uses a savepoint.

**Savepoints** are callback-scoped too:

```ts
tx.savepoint(async (sp) => { … })
```

- **Naming.** Core generates every savepoint identifier. Modules never provide one.
- **Release and rollback.** A resolved callback releases the savepoint. A rejected one rolls back
  to it, releases it, and rejects with the callback's error.
- **Outstanding work.** The awaiting rule for transactions applies unchanged.
  - A savepoint callback that resolves with operations still outstanding is a scope-usage error.
    The savepoint is rolled back, never released, and the call rejects with that error.
  - A savepoint callback that rejects keeps its own error. The savepoint is rolled back as for any
    rejection.
  - Either way, outstanding work never leads to a release.
- **One active scope.** Only the innermost open scope may run statements. While a savepoint is
  open, its parent executor refuses statements and new savepoints, so savepoint scopes can never
  overlap.
- **Revocation.** `sp` is revoked when its callback settles, exactly like `tx`.

Nested transactions are savepoints. No nested-transaction API exposes a driver or ORM object.

**Timeouts and cancellation stay with Core.** The existing per-statement bounds of the pool
(`statement_timeout` and `query_timeout`) apply to every ABI statement. Core may also bound how long
a transaction stays open. Modules cannot change Core's timeout policy through the ABI. `AbortSignal`
and module-initiated cancellation are not part of v1.

### Module-side adapters

The ABI is ORM-neutral. The Module SDK may ship adapters **on the module side**, bundled into each
module like the rest of the SDK (ADR 0049):

- **A Drizzle adapter.** It turns the executor into a Drizzle database the module's own tables work
  with. It may use Drizzle's `pg-proxy` driver, mapping row-array queries to `rowMode: "array"` and
  the rest to `"object"`. It supplies `transaction` by opening an ABI transaction and binding a fresh
  Drizzle instance to `tx`.
- **A raw-SQL helper.** A tagged template that turns interpolations into placeholders and values.
- **Later, a Kysely adapter.**

Adapter types and query-builder types are not part of the ABI. Core never learns, and never needs
to learn, that a module used Drizzle. A module may bundle any Drizzle version its adapter supports.

### Schema metadata

For an ABI v1 module, Core validates table ownership from **plain, Ekklesia-owned metadata**, not
from ORM objects. Conceptually:

```yaml
tables:
  - name: care_team_members
    foreignKeys:
      - table: care_team_teams
```

- **What it is.** Plain data: strings, arrays, and records, with no functions or class instances.
  Core validates its structure strictly.
- **What Core checks.** It is enough for the checks ADR 0007 already makes:
  - the module namespace and identifier rules;
  - uniqueness;
  - foreign keys that stay within the module and target its declared tables;
  - atomic, deterministic aggregation with sanitized issues.
- **What Core never does.** For ABI v1 modules, Core does not call Drizzle's `is(…, PgTable)`,
  `getTableConfig`, or `PgColumn` checks on module-provided objects, and does not import an ORM to
  understand the metadata.
- **How a module produces it.** A Drizzle helper in the Module SDK may derive it from the module's
  own Drizzle tables, on the module side. A Kysely or raw-SQL module may write it by hand or produce
  it another way.
- **What it promises.** The metadata is a declaration checked for consistency. It is exactly as
  strong a correctness check as today's, and no stronger: the database enforces columns when the
  migration runs.

Legacy modules keep the existing Drizzle-object path while legacy support exists. Where the metadata
lives (in the schema entrypoint's default export or in a static file) is decided by the change that
implements it. Either way, it must be readable without Core importing an ORM.

### Migrations are unchanged

Migration discovery, validation, and execution stay as ADR 0008, ADR 0009, and ADR 0048 define
them. The runner already executes SQL without an ORM runtime. Migrations stay forward-only and
explicit, and history is retained for absent modules.

The Drizzle Kit migration file format (journal, snapshots, and `_ekklesia.json`) remains the module
migration contract. Whether that build-tool format should become Ekklesia-owned is a separate
question, and this ADR does not change it.

### Module Package v1

ADR 0049's `packageFormat` stays **1**. For a module that declares ABI v1:

- **Drizzle is allowed in the bundle.** It is a module-side implementation detail, for example of
  the adapter.
- **The packager omits `transitional.databaseRuntime`.** Core requires no Drizzle runtime agreement.
- **The verifier checks the ABI declaration and the plain schema metadata instead.** It refuses an
  ABI v1 package that carries `transitional.databaseRuntime`. Such a package was made by a packager
  that did not know the module's database contract.

A legacy module's package keeps today's `transitional.databaseRuntime` recording and validation for
as long as the legacy facade exists.

This needs no new package format. ADR 0049 already lets a format 1 package carry no `transitional`
facts. A platform from before this change cannot misread an ABI v1 package either: it refuses the
version 8 manifest.

### Compatibility and deprecation

The deprecation window applies to the **legacy database facade**, not to manifest version 7.

1. **Phase 1.** Core serves both contracts: the legacy facade to version 8 modules without a
   `database` declaration, and an ABI v1 executor to modules that declare `abi: 1`.
2. **Phase 2.** The Module SDK and the module template use ABI v1. First-party modules move over
   independently, each in its own change.
3. **Phase 3.** After at least one documented deprecation window, ending in a breaking Module SDK
   release, the legacy facade may be removed. Its removal date, and how the manifest then expresses
   the database contract, belong to that later decision.

The legacy facade is transitional. It is not part of the permanent module contract, and it keeps
its current behaviour until it is removed.

## Consequences

- A module's ORM, and its version, no longer has to match Core's. Core can upgrade or replace its
  own Drizzle without rebuilding any ABI v1 module.
- `transitional.databaseRuntime`, recorded in ADR 0049 as an implementation constraint, disappears
  for ABI v1 packages, as ADR 0049 anticipated.
- Modules get one stable error shape with SQLSTATE, and one documented result encoding that loses
  no precision and does not depend on time zones.
- A transaction object can no longer outlive its callback or reach a pooled connection afterwards.
- Every module moves to manifest version 8. Already-built version 7 packages must be rebuilt.
  Database code changes only when a module opts into ABI v1.
- An ABI v1 module bundles an adapter. Its Drizzle code mostly stays as it is: the query builders
  are its own.
- Core takes on a documented decoding table, transaction scoping, savepoint management, and error
  mapping that Drizzle did implicitly before. Each needs live PostgreSQL test evidence.
- Core must serve two database contracts during the deprecation window.
- None of this is a sandbox. A trusted module can still do anything the API's database role can.

## Alternatives

- **An ORM AST or query-object ABI.** Rejected. Anything richer than SQL text and parameters is one
  ORM's internal representation, so it would tie the ABI to that ORM and its release cadence. The
  only part worth keeping, the row mode and field metadata, is already in the executor.
- **An Ekklesia-owned query DSL.** Rejected. It would cover less of PostgreSQL than Drizzle or
  Kysely, cost more to maintain than either, and still force every module to rewrite its queries.
- **A permanent, versioned Drizzle facade.** Rejected as the permanent contract. It would make Drizzle
  version agreement a permanent install-time constraint. Core's transaction object would keep
  reaching module code. Core could never change its ORM. It remains only as the transitional legacy
  facade.
- **Exposing the pool, a client, or a connection string.** Rejected, as in ADR 0016. Connection
  lifecycle, timeouts, and transaction cleanup belong to the platform.
- **SQL parsing or execution-time prefix checks as a security boundary.** Rejected. SQL can name
  tables in too many ways, and a trusted module can send any SQL, so a parser would be bypassable
  and a false promise. ADR 0016 rejected the same idea.
- **`SET ROLE` or per-module PostgreSQL roles as a security boundary.** Rejected. Any SQL the module
  sends can reset the role, and in-process code can reach the database without the ABI. Roles in a
  module's CI, as a test aid, would be a correctness tool, not a boundary.
- **`Date` as a direct parameter.** Rejected. Its meaning depends on the target column's type, which
  the ABI cannot see. Adapters convert it explicitly.
- **`pg`'s default parsing as the result contract.** Rejected. It is process-global and mutable, it
  loses precision for `jsonb` numbers and `numeric[]` elements, and it is not an Ekklesia contract.
- **Parsing manifest versions 7 and 8 side by side.** Rejected. Manifest versions are hard cutovers,
  and the deprecation window is about the database facade, not the manifest.

## Deferred

- The implementation: Core's executor, decoding table, transactions, savepoints, errors, and their
  tests.
- Manifest version 8's exact mechanics, and the template and fixture cutover.
- The Module SDK's Drizzle adapter and raw-SQL helper.
- A Kysely adapter.
- The legacy facade's removal date and the release that removes it.
- Redesigning the migration file format.
- SQL cancellation and `AbortSignal`.
- Stronger process or database isolation for modules.
- Moving Signage to ABI v1.