Gnomon SDK specification

One specification, the same names in every language, and a conformance suite every SDK passes (conformance/*.json). Every method is one SQL function call: the database is the only place with logic. Version 1, against the SQL API gnomon.api_version() = 2.

Two loginsCopy Anchor Link

• app: the application's own login. Starts runs (a member of gnomon_runner), reads their diffs and summaries, accepts them (a member of gnomon_merger, or covered by a merge policy), reviews change requests.
• runs: one confined login shared by every agent run, holding no grant on the base tables. Named once in the database: gnomon.set('runs_role', '<login>'), after gnomon.confine('<login>').

The envelopeCopy Anchor Link

Every agent statement on a run is sent on the runs login as:

BEGIN
SELECT gnomon.begin($branch)                         -- binds this transaction to the run
SELECT gnomon.note($actor, $reason, $meta::jsonb)    -- attribution: history, blame, the log
SELECT set_config('statement_timeout', $ms, true), set_config('lock_timeout', $ms, true)
<the statement, by the extended protocol, one statement>
COMMIT

A second statement is refused (by PostgreSQL where the driver uses the extended protocol, and by the SDK's own splitter for every driver). A run cannot read or write another run's branch, even on the same login: gnomon.begin binds the transaction to one run.

MethodsCopy Anchor Link

Leaving a run's scope (await using, with) without merge, submit or discard discards it.

ErrorsCopy Anchor Link

A base GnomonError with code (the slug in the hint, [gnomon:<slug>]), sqlstate, hint and the driver's error as cause. Subclasses by what callers branch on:

run.sql retries a statement that failed with 40001, with backoff, up to three times: the envelope held nothing else. run.transaction(fn) retries by running fn again. Nothing else is retried.

ValuesCopy Anchor Link

A diff carries values as JSON. Integers beyond 2^53 are read from the JSON text, not through a float: bigint becomes BigInt (or a string, by option); a decimal whose text a float would not reproduce stays a string. Python decodes to int and Decimal.

Tools for modelsCopy Anchor Link

tools.json holds the tools every framework adapter returns, bound to one run: sql, describe, diff, dry_run, checkpoint, rewind, done, with descriptions written for models. Each SDK carries a copy; the conformance suite checks that it equals this file.

SnapshotsCopy Anchor Link

A diff normalized for a stored file. Each table's changed keys are replaced by placeholders (<accounts:1>, <accounts:2>, ...) in ascending key order (numbers numerically, text by code point, a composite key column by column): generated keys differ between runs, their order does not. A foreign-key column whose value is a placeholder's key shows the placeholder. Named columns are ignored. One line per changed field (an insert: one per column; a delete: one line), sorted by table, placeholder number, then text:

public.accounts <accounts:1> insert email = "a@x.io"
public.accounts <accounts:1> insert id = <accounts:1>
public.orders <orders:1> update total: 10 -> 12
public.orders <orders:2> delete

Values are JSON text with object keys sorted.

snapshot/*.json holds inputs and expected outputs both SDKs check.

Conformance scenariosCopy Anchor Link

conformance/*.json are scenarios as data: setup SQL run as a superuser, then steps, each a call (startRun, run.sql, app.sql, run.diff, run.summary, run.merge, run.discard) with args and an expect: error (an error class of the Errors section), rowCount, rows, length, or a dotted path into the result. "sqlOnly": true skips a step when the server loads the C module, where it behaves differently by design (a schema-qualified name is routed to the branch instead of refused). A binding is conformant when every scenario passes through every driver adapter it ships, against the SQL core and the C module.

A connection of the run's ownCopy Anchor Link

run.url(base?) and run.connection(...) hand a tool a connection pinned to one run. The shared runs login cannot do it (it binds each transaction to one run with gnomon.begin(run), so a pinned session would not carry the binding), so they call gnomon.run_login(run): a login role of the run's own, a member of the runs role, confined to the run's branch, whose sessions start on the branch through role defaults. run.url(base) puts its role and password into base (the SDK's url option or the argument; for a socket directory, as user and password query parameters, since libpq takes the user from there); run.connection(connect, base?) opens one with the caller's driver. A second call rotates the password. run_end ends the login's sessions and drops it. Behind a transaction pooler the branch still comes from the login's role defaults (pools are per user), not from session state.