What the checksum actually covers

A Kit migration is a small object with a version, a name, an optional declarative ops list, and an imperative up() callback that does the work:

await migrate(db, schema, [
  {
    version: 5,
    name: 'tighten_products',
    ops: [{ kind: 'addUnique', table: 'products', constraint: 'products_sku_uq' }],
    async up({ kit }) {
      await addUnique(kit, 'products', unique(['sku'], { name: 'products_sku_uq' }));
    },
  },
]);

The checksum is a SHA-256 over one canonical serialization of the version, the name, and the ordered op list, with the key order fixed and standard JSON string escaping, so there is exactly one byte string that represents a given logical migration:

sha256('{"version":<n>,"name":<json>,"ops":[<op>,...]}')

The canonical form matters more than the hash algorithm, because the same logical migration has to produce the identical checksum in TypeScript, in Rust, and in Python, and any serialization that leaves wiggle room, a space here, a reordered key there, breaks that property the moment two languages disagree about whitespace. There is a small two-layer wrinkle worth naming, since the discriminator in your TypeScript ops is kind while the canonical serialization calls it op, a renaming step in the canonicalizer (kind: 'addUnique' serializes as {"op":"add_unique",...}) that maps camelCase input onto the snake_case wire vocabulary every language shares, so the object you write and the bytes that get hashed are deliberately not identical. The conformance tests pin two known vectors so a drift in any language’s canonicalizer fails a build instead of failing a deploy: {"version":1,"name":"init","ops":[{"op":"create_table","name":"users"}]} hashes to fe2f521793591207bd4d8645c2631e4b7ce43e30fe7ea5691a2846c74ea71cc3, and the empty form {"version":1,"name":"init","ops":[]} hashes to 6408373a4372a2c49859db2a4548ea43308e5ba7dd3609998ca376606cf09757, and both are asserted byte-for-byte on both sides of the language boundary. When ops is omitted, as it often is in TypeScript where the list is metadata rather than an execution plan, the checksum covers the version and name against an empty op list, so even the smallest possible migration is content-addressed.

When the checksum gets verified

The runner records each applied migration in the internal __kit_schema_migrations table, one row carrying the version, the name, the checksum, the applied timestamp, the kit version that ran it, and a status, and that record is written in the same transaction discipline as everything else the kit does. The part that earns the word “content-addressed” is what happens on every subsequent run: before computing the pending set, the runner recomputes the checksum of every supplied migration that claims to correspond to an already-applied record and compares it, and the name, against what is stored, and any mismatch, or any applied version that has vanished from the supplied list entirely, raises a KitSchemaDriftError and stops the run:

migration 5 (tighten_products) checksum mismatch: stored a1b2..., expected c3d4...

That ordering is the whole point, because drift detection happens before any new migration is applied, so a tampered history aborts the deploy while the database is still untouched rather than halfway through a run of new DDL on top of a history nobody trusts. The pending set itself is computed from a high-water mark, meaning only versions above the maximum already applied are eligible to run, which is what makes re-running the runner a no-op and what makes the classic renumbering attack, slipping a new file in as 003b and hoping it replays, a non-event: a renumbered migration either sits below the high-water mark and never runs, or it collides with an applied record whose checksum it cannot reproduce, and either way the runner says so. Records left in failed status are deliberately skipped by the drift check, and the high-water mark counts only versions that reached applied, which means a failed migration sits below the watermark and blocks itself and everything after it until you repair or remove the record; that is the intended posture, because a failed run leaves the history genuinely ambiguous and the runner refuses to guess its way forward.

The honest tradeoff

The cost of this design is that the checksum is only as faithful as the ops you declare, and this is the seam I would point at before recommending it to anyone: in the TypeScript runner the ops array never drives the work, your up() does, so if you list an addUnique op and then quietly do something extra inside the callback, the checksum certifies the list and not the deed, and the discipline the system actually demands is that you keep the two in sync so the audited description stays content-aware. I consider that a fair price, and the comparison that settles it for me is the old PHP habit of a migrations folder full of numbered SQL files that everyone knew better than to edit but everyone edited anyway, where the only enforcement was social and the social contract lost to the first hotfix under deadline; the modern equivalent of doing it right is a checksum computed from a canonical form, stored next to the version, and re-verified on every run before anything else is allowed to happen, so the boring discipline that used to live in a code-review comment now lives in the runner, and the runner does not get tired on Fridays.

The DSL does not emit SQL

The natural assumption, the one I made before reading the source, is that a declaration like this gets compiled down into CREATE TABLE text and that the query builder assembles SELECT strings under the hood:

export const orders = table('orders', {
  columns: [
    int('id', { primaryKey: true, default: sequenceDefault('orders_id_seq') }),
    int('customer_id', { nullable: false }),
    text('status', {
      enumValues: ['pending', 'paid', 'shipped', 'cancelled'],
      default: staticDefault('pending'),
    }),
    timestamp('placed_at', { default: nowDefault() }),
  ],
  primaryKey: 'id',
  indexes: [index(['customer_id'])],
  foreignKeys: [
    foreignKey(['customer_id'], { table: 'customers', columns: ['id'] }, { onDelete: 'cascade' }),
  ],
});

That assumption is wrong, and it is wrong in an interesting way. The table() call builds a TableSpec, a typed descriptor that Kit validates at construction time (duplicate column names, a primary key referencing a column that does not exist, an index over nothing), persists into the engine’s schema catalog with stable table and column ids, and then uses directly: reads and writes through selectFrom / insertInto push the predicates they can down into the storage engine’s native indexes and compute the rest, joins and grouping and ordering overflow, in memory, with no SQL text produced at any point. Even at the wire boundary the two surfaces stay separate; the remote client speaks typed endpoints, POST /kit/query for a native typed query and POST /kit/txn for an atomic write batch, while SQL statements go to POST /sql, so “the DSL compiles to the same wire format as raw SQL” is not the architecture, it is the thing we deliberately did not build. The payoff for skipping the SQL round trip is that one set of declarations drives type inference, validation, constraint enforcement, and migrations all at once, so renaming a column is a compile error in your TypeScript rather than a runtime surprise three deploys later, and the int('id') up there coming back as a bigint, with the compiler refusing row.id === 1, is the kind of pedantry that has saved me real money.

Where raw SQL is the right door

The DSL is honest about its ceiling, and the ceiling is exactly where the SQL frontend starts. Recursive CTEs, window functions, CREATE TABLE AS SELECT, materialized views, and multi-statement execution live on the raw surface, and the embedded TypeScript API is two calls wide:

const result = await db.sql('SELECT count(*) AS n FROM users');
const rows = await db.sqlRows('SELECT id, email FROM users ORDER BY id');

db.sql(...) hands back an Apache Arrow table and db.sqlRows(...) decodes it to plain objects, while the remote client exposes the same names synchronously because the native binding performs the HTTP call internally, so the shape of your code does not change when you move from embedded to daemon. On top of that surface Kit ships small expression helpers for the extended function catalog, things like percentileCont(events.latency_ms, 0.95) and jsonExtract(events.payload, '$.city'), each returning a { sql: string } fragment you splice into a statement yourself, plus mongreldbFtsRank(text, query) for BM25-style relevance ordering, and virtual tables follow the same pattern, with virtualTable(...) describing a module-backed table that generates its own CREATE VIRTUAL TABLE ... USING ... statement. The rule of thumb I use is that the builder owns the hot paths, the typed CRUD and the filtered scans that run a thousand times a minute, and SQL owns the analytical long tail, the reports and one-off probes where nobody wants type inference anyway; the builder is not an ORM trying to swallow SQL, it is a typed fast lane with a clearly marked exit.

Mixing both inside one migration

The place the two surfaces genuinely meet is the migration runner, and this is where the “one system, two doors” claim either holds or falls apart. A TypeScript migration’s up(ctx) is imperative, and the context object carries both doors: helpers like ctx.ensureTable(table) and ctx.addColumn(...) work from the typed TableSpec, and ctx.sql(sql) runs raw SQL inside the same migration transaction, so a single versioned change can create a table from its spec and then install a view over it without leaving the runner:

await migrate(db, schema, [
  {
    version: 7,
    name: 'orders_reporting_view',
    async up(ctx) {
      await ctx.ensureTable(orders);
      await ctx.sql(`
        CREATE VIEW paid_orders AS
        SELECT id, customer_id, placed_at FROM orders WHERE status = 'paid'
      `);
    },
  },
]);

There are two catches worth knowing before you reach for this, and both are load-bearing rather than incidental. First, ctx.sql() is available in async migrations only and throws in migrateSync, because the sync runner has no suspension point for the SQL frontend, so the moment a migration needs raw SQL you commit to the async migrate(db, schema, migrations) helper for the whole run. Second, the optional ops array on a migration is metadata in TypeScript, not an execution plan; the runner folds it into the content-addressed checksum so that an after-the-fact edit to an applied migration is caught as drift, but your up() is what actually does the work, which is exactly the split you want, since the thing that runs and the thing that is audited are allowed to be expressed differently. Either way both doors land in the same __kit_schema_migrations history under the same advisory lock, which is the entire point: there is no shadow schema state that only the SQL side knows about.

The tradeoff you actually sign

The seam I watch in production is the remote-mode authority boundary, because it is the one place the two doors are not symmetric. The daemon enforces engine-level constraints, unique, foreign-key actions, checks, atomically and server-side for both surfaces, but the Kit-specific field validations, defaults, enums, min/max bounds, regex patterns, live in the client, so a remote caller who bypasses the typed layer and hand-writes INSERT statements against /sql is opting out of that richer validation and accepting the engine’s floor as the whole contract, and that is a deliberate boundary, not an accident we plan to paper over. I will take that trade every time, and the comparison I keep reaching for is the old LAMP habit of treating the query builder as a toy and raw SQL as the real thing, which gave you one honest surface and one decorative one; the modern equivalent of doing it right is two surfaces that share a catalog, a transaction, and a migration history, where choosing between them is a per-query judgment about types and ergonomics rather than a per-project bet about which subsystem will still be maintained in three years.

One core, three thin surfaces

The first decision was to refuse to reimplement anything per language. The Rust crate mongreldb-kit is the actual implementation: schema catalog, query builder, migrations, constraint enforcement, all of it. The Python package is a PyO3 binding built with maturin over that same crate, and the TypeScript package talks to the same compiled Rust core through native Node bindings, so the three “SDKs” are really three grammars over one semantics. A filter you build in TypeScript compiles to the same internal plan as the identical filter in Python, because there is only one compiler, and the schema catalog lives in the database itself with stable table and column ids, so all three languages are reading and writing the same descriptors rather than their own interpretation of them.

That architecture is what makes the interesting question askable at all, because once the semantics live in one place, “do all three SDKs behave the same” stops being a philosophy and becomes a diffable output.

The conformance suite is the contract

The answer to that question lives in tests/conformance/, which is a set of language-neutral JSON fixtures plus three small runners, one per SDK, that execute the same scenarios and compare against the same expected output. The fixtures are deliberately boring to read, which is the point; here is a slice of queries.json:

[
  { "name": "query_all_users", "table": "users", "order": "+id" },
  { "name": "query_users_by_role", "table": "users",
    "filter": { "role": "admin" } },
  { "name": "query_posts_by_user", "table": "posts",
    "filter": { "user_id": { "eq": 1 } } },
  { "name": "query_users_limit_offset", "table": "users",
    "order": "+id", "limit": 1, "offset": 0 }
]

Every scenario is named, and for every name there is an expected result under fixtures/expected/, so a runner’s job is just: load the fixture, apply it through the public SDK surface, serialize what came back, compare. The Rust side is a workspace member called conformance-runner that you can also run as a standalone binary, the TypeScript side is a vitest file that picks the suite up automatically in npm test, and the Python side is a pytest module that loads the same JSON files from the same directory. Nobody wrote the same test three times, which matters, because the moment you write the same test three times you have written three different tests and you are back to drift with extra steps.

The fixtures test the failures, not just the happy path

The part I care most about is that the corpus spends as much energy on what must not work as on what must. schema.json defines users, posts, and comments with unique constraints, check constraints, and foreign-key actions across cascade, set-null, and restrict, and then inserts.json and deletes.json include rows that are supposed to fail, with the expected error recorded by code rather than by message text. The Python runner, for instance, maps its exception types onto the shared vocabulary and asserts DUPLICATE where the Rust runner asserts DuplicateError; what is being tested is that all three languages reject the same row for the same reason, not that they phrase it identically. There are fixtures for aggregates, CTEs, joins, learned-range indexes, migration failure handling, byte-prefix filters, and encrypted tables, and each one lands in all three runners at once, so a new engine behavior is not “supported in the SDKs” until the fixture exists and all three suites pass it in the same CI run.

That is the real product feature hiding under the word “conformance”: when a team mixes the TypeScript service, a Python analytics job, and a Rust batch worker against the same database, the behavioral differences between those processes are held at zero by the suite rather than by hope; the bindings still own their own serialization and error mapping, which is exactly what the fixtures exist to police, and when a bug report says “the Python client let this through,” the first thing CI tells you is whether that is even possible.

What this does not buy you

Honesty about the seam: conformance proves the SDKs agree with each other and with the fixture corpus, and it does not prove the corpus is complete, so the failure mode moves from “the SDKs drifted” to “the fixtures have a blind spot,” which is a better failure mode because it has exactly one place to fix. It also costs something; every new engine feature owes three green runners before it ships, which slows the merge queue compared to a single-language library, and the error-code normalization layer (mapping Python exception types onto the shared vocabulary) is the kind of unglamorous plumbing that has to be maintained forever. I still think it is the right trade, and the comparison I keep coming back to is the old LAMP-era habit of testing only the primary driver and treating the other bindings as community goodwill: that worked until it didn’t, usually on a Friday, and the modern equivalent of doing it right is not more discipline in three repos, it is one corpus that all three repos are forced to agree with.