Narrow contract and implementation adjustments from review. No SDK, manifest, packaging, or Signage work. Callback-error precedence: - A transaction or savepoint callback that rejects keeps its own error, even while sibling work it started is still settling (one failed half of a Promise.all). Core drains that work, rolls back, and never commits or releases. - A callback that resolves with work outstanding (a forgotten await) still fails with MODULE_DATABASE_SCOPE_WORK_OUTSTANDING and rolls back. Transaction-control SQL: - ADR 0050 forbids it through query() as a conformance rule for trusted code, not a security guarantee. Core does not parse SQL, so PostgreSQL has run the statement before Core sees it. Core detects the violation from the command tag or the transaction status, and claims nothing it cannot do: a module's own COMMIT has committed. - After a violation, the transaction's scopes refuse every later statement without sending it (it would otherwise autocommit). Core never commits the transaction itself, and the connection is destroyed rather than reused, for top-level violations too. - The commit and rollback guarantees apply to conforming use. Duplicate object-mode columns: documented as found only after execution, so a mutation can have taken effect; atomicity needs an ABI transaction. Tests prove each of these against PostgreSQL: Promise.all failures in a transaction and a savepoint keep 23505; a forgotten await still rolls back; a module COMMIT's prior work is committed while nothing after it runs; a backend PID changes after every violation; duplicate RETURNING columns persist at the top level and roll back in a transaction. ADR 0050 stays Accepted: the executor conforms to the revised text. Co-Authored-By: Claude Opus 5.5 <[email protected]>
32 KiB
0050: Module Database ABI v1: modules and Core exchange SQL, never ORM objects
- Status: Accepted
- Date: 2026-10-07
- Supersedes (partial): 0016 — 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 sameservicesobject. One pool, no pool or connection string for modules, no database access duringregister, 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). - Amends: 0007 — 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 — this is the Module Database ABI that ADR 0049 deferred
and anticipated. ABI v1 packages carry no
transitional.databaseRuntime.packageFormatstays 1. - Related: ADR 0006, ADR 0008, ADR 0009, ADR 0015, ADR 0021, ADR 0047, ADR 0048
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
SQLobjects 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 undertransitional.databaseRuntimeand refuses a mismatch. - Core's ORM objects cross into the module.
transactionhands module code Core's liveNodePgTransaction. At run time that object is a full Drizzle database: its session, dialect, relational query builder, androllback()are all reachable, whatever thePicktype 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:jsonbnumbers beyond double precision, andnumeric[]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
pgthrows. 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, andPgColumn. 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
$nplaceholders and an ordered parameter list. Drizzle 0.45.2's ownpg-proxydriver, given only a callback that receives SQL text, parameters, and an array-or-object row mode, ranselect,update, andinsert … returning, and decodedtimestamptzandint8text 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,
SQLobjects, query builders, and transactions; - Kysely objects;
- any other third-party ORM or runtime object.
- Drizzle tables, columns,
- 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:
{
"manifestVersion": 8,
"database": { "abi": 1 }
}
database.abi: 1means the module receives a Module Database ABI v1 executor. It never receives the legacy facade.- No
databasefield means the module receives ADR 0016's legacyModuleDatabasefacade 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:
query({ text, values, rowMode }) → { command, rowCount, rows, fields }
transaction(callback, options) → the callback's result
textis exactly one PostgreSQL statement, using$1 … $nplaceholders. Onequerycall 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.
valuesis the ordered list of bound parameters (see Parameters). Values are always bound and never interpolated into the text.rowModeis"object"or"array"."object"rows are keyed by column name."array"rows are positional, infieldsorder. 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.
commandis PostgreSQL's command tag word, such asSELECT,INSERT,UPDATE, orDELETE.rowCountis the number of rows PostgreSQL reports as processed, ornullwhen it reports none.rowsare the result rows, decoded as in Results.RETURNINGrows are ordinary rows.fieldsare 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:
Dateis not an ABI parameter. A JavaScriptDateis an instant. Whether it should become atimestampor atimestamptz, 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), andTimeZone(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. byteahas one representation. A value is aUint8Array. A module must not rely on it being any particular subclass.- Higher-level conversion belongs to the module side. Converting text to
Date,numericto a decimal type,int8tobigintornumber, 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:
ModuleDatabaseError { code, sqlState? }
The two fields mean different things:
-
codeis 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.
-
sqlStateis optional. It is the five-character SQLSTATE that PostgreSQL itself reported, such as23505(unique violation),23503(foreign-key violation), or40001(serialization failure). It is present only when the database supplied one, and Core never invents one.- Failures that the ABI detects itself have a
codeand nosqlState: a closed scope, an invalid parameter type, or an invalid transaction option. - Modules branch on
codefor ABI failures and onsqlStatefor PostgreSQL conditions.
- Failures that the ABI detects itself have a
-
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 withinstanceof. 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:
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. Nopgclient 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
txis still outstanding. When the callback rejects, Core rolls back, and the transaction call rejects with the callback's error. There is norollback()method: to roll back, the module throws. - All work is awaited inside the callback. Module code must await every database operation it
starts through
txbefore its callback returns. What happens when work is still outstanding depends on how the callback settled:- Resolved with work outstanding. The module forgot an
awaitand has used the scope incorrectly. The transaction is never committed: Core rolls it back, and the transaction call rejects with the scope-usageModuleDatabaseError. A forgottenawaittherefore 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.
- Resolved with work outstanding. The module forgot an
- 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 thetransactionandsavepointcallbacks.- 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
COMMITsent through a transaction'squeryhas 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,
txis revoked, and it stays revoked once the scope has finished. Any later call on it fails with the closed-scopeModuleDatabaseErrorand sends nothing to PostgreSQL. Atxthat escapes its callback can never run a statement on a connection that has gone back to the pool. - Options.
isolationisread committed,repeatable read, orserializable.readOnlyis a boolean. An unknown option or value is refused, never ignored.deferrableis 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
40001is 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:
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.
spis revoked when its callback settles, exactly liketx.
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-proxydriver, mapping row-array queries torowMode: "array"and the rest to"object". It suppliestransactionby opening an ABI transaction and binding a fresh Drizzle instance totx. - 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:
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, orPgColumnchecks 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.
- Phase 1. Core serves both contracts: the legacy facade to version 8 modules without a
databasedeclaration, and an ABI v1 executor to modules that declareabi: 1. - Phase 2. The Module SDK and the module template use ABI v1. First-party modules move over independently, each in its own change.
- 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 ROLEor 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.Dateas 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 forjsonbnumbers andnumeric[]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.