@abloatai/ablo 0.26.0 → 0.27.0

package/dist/server/commit.d.ts

@@ -1,126 +1,122 @@
 /**
- * `@abloatai/ablo/server` — the COMMIT contract types.
+ * The commit contract types for the sync engine's server surface.
  *
- * `CommitContext` is the attribution/claim envelope the host's commit executor
- * stamps onto every delta a batch produces; `CommitResult` is the receipt. Both
- * are PURE descriptors (no `postgres`, no SQL, no functions), which is why they
- * live in the portable package while the SQL engine that consumes them
- * (`executeCommit`) stays host-side. They feed the `ChangeSet`/`DataAdapter`
- * contract.
+ * {@link CommitContext} is the attribution envelope stamped onto every delta a
+ * commit produces; {@link CommitResult} is the receipt returned when the commit
+ * finishes. Both are plain data descriptors — no database driver, no SQL, no
+ * functions — so they belong to this package's public contract, which your commit
+ * implementation reads and writes. They feed the `ChangeSet` and `DataAdapter`
+ * contracts defined alongside them.
  *
- * The attribution fields reuse the canonical `ParticipantKind` /
- * `ConfirmationState` / `ParticipantRef` so the commit-time shape and the
- * stored/broadcast delta shape share ONE source of truth (these were previously
- * a server-local interface "kept in sync by convention").
+ * The attribution fields reuse the shared {@link ParticipantKind},
+ * {@link ConfirmationState}, and {@link ParticipantRef} types, so the shape at
+ * commit time and the shape of a stored or broadcast delta share one definition
+ * rather than being kept in step by hand.
  */
-import type { ParticipantKind, ConfirmationState } from '../schema/sync-delta-row.js';
-import type { ParticipantRef } from '../schema/sync-delta-wire.js';
+import type { ParticipantKind, ConfirmationState } from '../schema/syncDeltaRow.js';
+import type { ParticipantRef } from '../wire/delta.js';
 import type { Environment } from '../environment.js';
 import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
 export interface CommitContext {
     participantId: string;
     /**
-     * Typed participant classification — required so every delta written through
-     * the commit executor carries structured attribution, not a string-prefix
-     * convention.
+     * The kind of participant making the commit. Required, so that every delta carries
+     * structured attribution rather than a string-prefix convention.
      */
     participantKind: ParticipantKind;
     organizationId: string;
     /**
-     * Product/project scope for routing source-mode storage. Omitted means the
-     * org-default project (the legacy behavior).
+     * Project scope used to route source-mode storage. When omitted, the commit
+     * targets the organization's default project.
      */
     projectId?: string;
     /** Optional external account scope forwarded to storage resolvers. */
     accountScope?: string;
     /**
-     * Canonical environment for this commit. Source-mode adapters forward this to
-     * customer handlers so sandbox and production traffic can hit distinct
+     * The environment this commit runs in. Source-mode adapters forward it to the
+     * customer's handlers so that sandbox and production traffic can reach distinct
      * customer-owned stores.
      */
     environment?: Environment;
     /**
-     * The participant's own subscribed sync groups (from the WS upgrade or
-     * capability token). Appended to every delta's `sync_groups` so writes fan
-     * out to agents scoped to entity-level groups (e.g. `deck:abc`), not only the
-     * default `org:X` / `user:Y` surface. Callers that omit this fall back to the
-     * legacy `[org, user]` broadcast behavior.
+     * The sync groups this participant subscribes to, taken from the connection
+     * upgrade or the capability token. Each is appended to every delta's `sync_groups`
+     * so that writes fan out to subscribers of entity-level groups (such as
+     * `deck:abc`), not only the default `org:X` and `user:Y` groups. When omitted, the
+     * commit fans out to just the organization and user groups.
      */
     syncGroups?: readonly string[];
     /**
-     * Sandbox keys should not stamp `org:<organizationId>` on deltas — otherwise
-     * live org subscribers would see test-environment writes.
+     * When true, the commit does not add `org:<organizationId>` to a delta's sync
+     * groups. Set this for sandbox writes, so that live organization subscribers do
+     * not receive test-environment changes.
      */
     omitOrgSyncGroup?: boolean;
     /**
-     * On-behalf-of attribution — whose authority the actor acted under. For
-     * human-direct commits, equals the actor. For agent commits, the human at the
-     * root of the capability's delegation chain. Null for `system` principals.
+     * The participant on whose authority the actor acted. For a direct human commit
+     * this equals the actor; for an agent commit it is the human at the root of the
+     * capability's delegation chain. Null for `system` principals.
      */
     onBehalfOf?: ParticipantRef | null;
     /**
-     * Scoped credential id. Non-null for agent / system commits when the
-     * authorizing credential is known; null for human-direct commits.
+     * The id of the scoped credential that authorized the commit. Non-null for agent
+     * and system commits when that credential is known; null for direct human commits.
      */
     capabilityId?: string | null;
     /**
-     * Human user id at the root of the delegated authority chain. Stored directly
-     * on `sync_deltas` so audit triggers never need to join mutable credential
-     * tables while appending the hash chain.
+     * The id of the human user at the root of the delegated-authority chain. Stored
+     * directly on `sync_deltas` so that audit triggers appending the hash chain never
+     * need to join mutable credential tables.
      */
     delegationChainRootUserId?: string | null;
     /**
-     * ApiKey row id when the caller authenticated with an API key. Used by the
-     * idempotency cache and usage attribution. Null for session / capability
+     * The id of the API key row when the caller authenticated with an API key. Used by
+     * the idempotency cache and for usage attribution. Null for session and capability
      * callers.
      */
     apiKeyId?: string | null;
     /**
-     * Whether the human explicitly approved the change. Defaults to `auto` until
-     * the chat-side previewed/approved plumbing lands.
+     * Whether a human explicitly approved the change. Defaults to `auto` when the
+     * caller does not specify an approval state.
      */
     confirmationState?: ConfirmationState;
     /**
-     * Dormant FK to the agent-task id (`agent_tasks.id`). The SDK no longer
-     * sets it (turns/tasks removed; attribution rides on the claim/claim id
-     * + server-stamped actor/capability). Still validated + written onto
-     * `caused_by_task_id` when present, but client writes leave it `null`.
+     * Optional foreign key to the task that caused the change, written to the
+     * `caused_by_task_id` column when present. Validated when set; clients typically
+     * leave it null and let attribution ride on the actor and capability instead.
      */
     causedByTaskId?: string | null;
     /**
-     * Batch-level read dependencies (the STORM read-set layer). The committer
-     * declares rows/groups it READ to form this batch; the engine validates none
-     * changed since their `readAt` and fires each entry's `onStale` disposition
-     * over the whole batch. Distinct from the per-op `readAt` guard, which only
-     * validates the rows being WRITTEN. Omit for write-target-only checking.
+     * Read dependencies for the whole batch. The committer declares the rows or groups
+     * it read to form this batch; the engine checks that none of them changed since
+     * each entry's `readAt` timestamp and applies that entry's `onStale` disposition
+     * across the batch. This differs from the per-operation `readAt` guard, which
+     * validates only the rows being written. Omit it to check the write targets alone.
      */
     reads?: ReadDependency[] | null;
 }
 /**
- * The receipt of a commit. Pins the exact `sync_deltas` id range the batch
- * produced, so a caller can broadcast just THIS batch's deltas
- * (`getDeltasInRange(firstSyncId - 1, lastSyncId, …)`) without racing concurrent
- * commits with adjacent ids. `firstSyncId` is 0 when the batch produced no
- * deltas (empty ops / all no-ops).
+ * The receipt returned when a commit finishes. It pins the exact range of
+ * `sync_deltas` ids the batch produced, so a caller can broadcast just this batch's
+ * deltas without racing concurrent commits that hold adjacent ids. `firstSyncId` is
+ * 0 when the batch produced no deltas (no operations, or all of them were no-ops).
  */
 export interface CommitResult {
     lastSyncId: number;
     firstSyncId: number;
     /**
-     * Stale-context notifications for ops the committer guarded with
-     * `onStale: 'notify'. Present (non-empty) only when a guarded write
-     * collided with a concurrent change; the committer self-heals from these
-     * rather than receiving an `AbloStaleContextError`. See
-     * `StaleNotification` in `coordination/schema.ts`.
+     * Stale-context notifications for operations the committer guarded with
+     * `onStale: 'notify'`. Non-empty only when a guarded write collided with a
+     * concurrent change; the committer heals from these instead of receiving an
+     * `AbloStaleContextError`. See {@link StaleNotification}.
      */
     notifications?: StaleNotification[];
     /**
-     * Ids of UPDATE/DELETE targets that matched ZERO rows — the row doesn't
-     * exist (or is outside the caller's org). The engine has always detected
-     * this (and logged it); surfacing it here lets the client turn a silent
-     * no-op into a loud `AbloNotFoundError`. Present (non-empty) only when at
-     * least one op missed. Ids are globally-unique uuids, so a caller can match
-     * its own target id against this set without ambiguity.
+     * Ids of update or delete targets that matched no rows — the row does not exist, or
+     * lies outside the caller's organization. Surfacing them here lets a client turn a
+     * silent no-op into an `AbloNotFoundError`. Non-empty only when at least one
+     * operation missed. The ids are globally unique, so a caller can match its own
+     * target id against this set without ambiguity.
      */
     missingIds?: string[];
 }

package/dist/server/index.d.ts

@@ -1,14 +1,13 @@
 /**
- * `@abloatai/ablo/server` — the host-side surface of the sync engine.
- *
- * Today this exposes the DataAdapter CONTRACT vocabulary (see {@link Row}).
- * It will grow to hold the transport/storage-agnostic commit orchestration and
- * the `Hub` core lifted out of `apps/sync-server` (see
- * docs/plans/sync-engine-server-extraction-plan.md). The reference Postgres
- * adapter (`executeCommit`/`selectAdapter`) and the WebSocket process lifecycle
- * stay in the host — only the portable, driver-free pieces live here.
+ * The server-side entry point of the sync engine. It re-exports the contract types
+ * you implement a storage backend against: the {@link DataAdapter} and its
+ * vocabulary ({@link Row}, {@link ReadRequest}, {@link ChangeSet}, and the rest),
+ * the {@link CommitContext} and {@link CommitResult} commit types, the
+ * {@link StorageMode} enumeration, and the per-model read configuration
+ * ({@link BootstrapModel}, {@link ColumnOverride}). These are plain, driver-free
+ * types; you supply the database code that fulfills them.
  */
 export type { Row, ReadResult, SyncCursor, DataAdapterCapabilities, ProposalResult, ReadRequest, ChangeSet, SyncResult, DataAdapter, ProposableDataAdapter, AdapterResolver, } from './adapter.js';
 export type { CommitContext, CommitResult } from './commit.js';
-export { storageModeSchema, type StorageMode } from './storage-mode.js';
-export type { ColumnOverride, BootstrapModel } from './read-config.js';
+export { storageModeSchema, type StorageMode } from './storageMode.js';
+export type { ColumnOverride, BootstrapModel } from './readConfig.js';

package/dist/server/index.js

@@ -1 +1 @@
-export { storageModeSchema } from './storage-mode.js';
+export { storageModeSchema } from './storageMode.js';

package/dist/server/readConfig.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Per-model read configuration consumed when a client bootstraps. Each
+ * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
+ * any parent scoping — plain data with no database driver. It feeds the read side of
+ * the data adapter contract; your query builder reads it to load a model's initial
+ * rows.
+ */
+/** A mapping from a declared field to a physical column, with the alias to apply after a `SELECT *`. */
+export interface ColumnOverride {
+    readonly field: string;
+    readonly column: string;
+    readonly alias: string;
+}
+/** Read configuration for one model: how to locate its rows and scope them to a tenant. */
+export interface BootstrapModel {
+    name: string;
+    /**
+     * Extra names accepted when a request looks up or filters this model. When the
+     * physical table name is canonical, `name` stays that table name and the aliases
+     * cover generated compatibility names such as `WeatherReports` or `weatherReports`.
+     */
+    aliases?: readonly string[];
+    /**
+     * The schema key used by source endpoints. `name` stays the wire and result model
+     * name (usually the typename), while source handlers are keyed by the developer's
+     * schema key, such as `files` or `slideLayers`.
+     */
+    sourceModel?: string;
+    table: string;
+    syncGroups?: string[];
+    enabled?: boolean;
+    /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
+    limit?: number;
+    /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
+    orderBy?: string;
+    /** Whether the table has organization_id. Default: true. */
+    orgScoped?: boolean;
+    /** Physical tenancy column (default `organization_id`, configurable per model). */
+    orgColumn?: string;
+    /**
+     * Parent-table scoping for rows that have no `organization_id` column, mirroring
+     * the schema's `scopedVia` option. When set, the bootstrap query adds:
+     *
+     *   WHERE <table>.<localKey> IN
+     *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
+     *
+     * This applies on top of whatever `orgScoped` dictates, so a table can carry its
+     * own `organization_id` and still narrow through a parent. The common case,
+     * though, is `orgScoped: false` together with `scopedVia` on a table that lacks the
+     * column.
+     */
+    scopedVia?: {
+        localKey: string;
+        parentTable: string;
+        parentKey?: string;
+        parentOrgColumn?: string;
+    };
+    /** Client-facing field name → physical DB column for declared fields. */
+    fieldColumns?: Record<string, string>;
+    /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
+    columnOverrides?: readonly ColumnOverride[];
+    /**
+     * Physical columns the schema declares as JSON (via `field.json()`). A JSON field
+     * stored in a text column comes back from `row_to_json` as a serialized string, so
+     * the bootstrap reparses these columns to make the wire value the canonical object
+     * regardless of the physical column type. A `jsonb` column already returns an
+     * object, so reparsing it is a no-op.
+     */
+    jsonColumns?: readonly string[];
+}

package/dist/server/readConfig.js

@@ -0,0 +1,8 @@
+/**
+ * Per-model read configuration consumed when a client bootstraps. Each
+ * {@link BootstrapModel} maps a model to its physical table, its tenancy column, and
+ * any parent scoping — plain data with no database driver. It feeds the read side of
+ * the data adapter contract; your query builder reads it to load a model's initial
+ * rows.
+ */
+export {};

package/dist/server/storageMode.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The set of storage modes a `DataAdapter` can run in. An adapter carries one of
+ * these as a label for diagnostics; it does not decide routing, which the adapter
+ * resolver handles separately. The package defines the enum so that the contract
+ * and every adapter agree on the same closed set of values:
+ *
+ *   - `hosted`     — a database this engine operates on the caller's behalf.
+ *   - `selfHosted` — the caller's own database, reached through the same execution
+ *                    path as `hosted`.
+ *   - `source`     — a caller-owned endpoint that accepts changes over HTTP without
+ *                    database credentials.
+ *
+ * These names describe where the data lives, not anything an end user sees.
+ */
+import { z } from 'zod';
+/** Runtime validator for the storage-mode values; {@link StorageMode} is its inferred type. */
+export declare const storageModeSchema: z.ZodEnum<{
+    source: "source";
+    hosted: "hosted";
+    selfHosted: "selfHosted";
+}>;
+/** The storage mode an adapter runs in — one of the values described in the module overview. */
+export type StorageMode = z.infer<typeof storageModeSchema>;

package/dist/server/storageMode.js

@@ -0,0 +1,17 @@
+/**
+ * The set of storage modes a `DataAdapter` can run in. An adapter carries one of
+ * these as a label for diagnostics; it does not decide routing, which the adapter
+ * resolver handles separately. The package defines the enum so that the contract
+ * and every adapter agree on the same closed set of values:
+ *
+ *   - `hosted`     — a database this engine operates on the caller's behalf.
+ *   - `selfHosted` — the caller's own database, reached through the same execution
+ *                    path as `hosted`.
+ *   - `source`     — a caller-owned endpoint that accepts changes over HTTP without
+ *                    database credentials.
+ *
+ * These names describe where the data lives, not anything an end user sees.
+ */
+import { z } from 'zod';
+/** Runtime validator for the storage-mode values; {@link StorageMode} is its inferred type. */
+export const storageModeSchema = z.enum(['hosted', 'source', 'selfHosted']);

package/dist/source/adapter.d.ts

@@ -1,32 +1,33 @@
 /**
- * The Data Source adapter — ONE interface every ORM backend implements, and the
- * bridge that wires it into the core `dataSource()` handler.
+ * The interface every data-source backend implements, together with the bridge
+ * that wires an implementation into the `dataSource()` HTTP handler. This package
+ * defines the contract and ships adapters for three object-relational mappers —
+ * {@link prismaDataSource}, {@link drizzleDataSource}, and {@link kyselyDataSource} —
+ * each verified by the shared conformance suite. You can also write your own.
  *
- * Pattern (Auth.js / Better Auth): one core interface, one package per ORM
- * (`prismaDataSource`, `drizzleDataSource`, `kyselyDataSource`), each provably
- * correct via the shared conformance suite. The adapter owns reading and writing
- * the database, plus the transactional outbox and idempotency, so a customer never
- * hand-writes them:
+ * An adapter reads and writes your database, and it owns the transactional outbox
+ * and idempotency bookkeeping as well, so you never write those by hand:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,
  *     ...sourceHandlersFromAdapter(prismaDataSource(prisma, schema), schema),
  *   });
  *
- * The bridge below connects the adapter to the core: it turns ONE adapter into the
- * core handler's `commit` / `events` / per-model `load`+`list` — no per-ORM
- * branching anywhere above the adapter.
+ * `sourceHandlersFromAdapter` is the bridge: it turns a single adapter into the
+ * handler's `commit`, `events`, and per-model `load` and `list` operations, so no
+ * code above the adapter needs to know which mapper you chose.
  */
 import type { SourceListQuery, SourceRequestContext } from './types.js';
 import type { AdapterCapabilities, ChangeSet, EventsPage, Migration } from './contract.js';
 /**
- * A canonical row keyed by schema FIELD name (e.g. `operatorId`) — the SDK shape,
- * NOT physical column names. Each adapter is the translation boundary: Prisma maps
- * via its `@map`, Drizzle via the schema's `camelToSnake`/`column` rule. `unknown`
- * leaf is narrowed by codegen later.
+ * A single row keyed by the schema's field names (for example `operatorId`), not
+ * by physical column names. Each adapter is the boundary that translates between
+ * the two, mapping a field name to whatever the underlying database column is
+ * called. Values are typed as `unknown`, so a caller must narrow a value before
+ * using it.
  */
 export type Row = Record<string, unknown>;
-/** A read against the canonical store — a single-row load or a filtered list. */
+/** A read request handed to an adapter: either a single-row load by id, or a filtered list. */
 export type AdapterReadRequest = {
     readonly kind: 'load';
     readonly model: string;
@@ -38,28 +39,32 @@ export type AdapterReadRequest = {
     readonly query?: SourceListQuery;
     readonly scope?: SourceRequestContext;
 };
+/** What {@link DataSourceAdapter.commit} returns: the rows as they stand after the write. */
 export interface AdapterCommitResult {
-    /** Canonical rows after the write — Ablo derives deltas from these. */
+    /** The affected rows after the write. The change log is derived from these. */
     readonly rows: readonly Row[];
 }
 /**
- * The adapter interface. An ORM adapter implements exactly these. `read`/`commit`
- * read and write the database; `events` reads the outbox; `migrations` ships the
- * `ablo_idempotency` + `ablo_outbox` table-creation SQL so the customer never writes it.
+ * The interface an adapter implements to serve one data source. `read` and
+ * `commit` read from and write to your database, `events` reads the outbox that
+ * `commit` appends to, and `migrations` supplies the SQL that creates the adapter's
+ * own two tables. `capabilities` advertises which optional features the adapter
+ * supports.
  */
 export interface DataSourceAdapter {
     readonly capabilities: AdapterCapabilities;
-    /** The table-creation SQL the adapter ships for its own tables (`ablo_idempotency` + `ablo_outbox`). */
+    /** The table-creation SQL the adapter needs for its own tables, `ablo_idempotency` and `ablo_outbox`. */
     migrations(): readonly Migration[];
-    /** Canonical rows for a load/list. */
+    /** The rows matching a load or list request. */
     read(req: AdapterReadRequest): Promise<readonly Row[]>;
     /**
-     * Apply a change set transactionally and idempotently by `clientTxId`:
-     * a duplicate `clientTxId` returns the original rows without re-applying.
-     * Writes the `ablo_outbox` rows in the SAME transaction as the app rows.
+     * Applies a change set in one transaction, keyed for idempotency by `clientTxId`.
+     * Replaying the same `clientTxId` returns the original rows without applying the
+     * change again. The matching `ablo_outbox` rows are written in the same
+     * transaction as the data rows, so the outbox can never drift from the data.
      */
     commit(change: ChangeSet): Promise<AdapterCommitResult>;
-    /** Read outbox events after `cursor` (null = from the beginning), up to `limit`. */
+    /** Reads outbox events after `cursor` (`null` starts from the beginning), up to `limit` events. */
     events(cursor: string | null, limit: number): Promise<EventsPage>;
 }
 export type { AdapterCapabilities, ChangeSet, Migration, OutboxEvent, EventsPage } from './contract.js';

package/dist/source/adapter.js

@@ -1,20 +1,20 @@
 /**
- * The Data Source adapter — ONE interface every ORM backend implements, and the
- * bridge that wires it into the core `dataSource()` handler.
+ * The interface every data-source backend implements, together with the bridge
+ * that wires an implementation into the `dataSource()` HTTP handler. This package
+ * defines the contract and ships adapters for three object-relational mappers —
+ * {@link prismaDataSource}, {@link drizzleDataSource}, and {@link kyselyDataSource} —
+ * each verified by the shared conformance suite. You can also write your own.
  *
- * Pattern (Auth.js / Better Auth): one core interface, one package per ORM
- * (`prismaDataSource`, `drizzleDataSource`, `kyselyDataSource`), each provably
- * correct via the shared conformance suite. The adapter owns reading and writing
- * the database, plus the transactional outbox and idempotency, so a customer never
- * hand-writes them:
+ * An adapter reads and writes your database, and it owns the transactional outbox
+ * and idempotency bookkeeping as well, so you never write those by hand:
  *
  *   export const POST = dataSource({
  *     schema, apiKey: process.env.ABLO_API_KEY!,
  *     ...sourceHandlersFromAdapter(prismaDataSource(prisma, schema), schema),
  *   });
  *
- * The bridge below connects the adapter to the core: it turns ONE adapter into the
- * core handler's `commit` / `events` / per-model `load`+`list` — no per-ORM
- * branching anywhere above the adapter.
+ * `sourceHandlersFromAdapter` is the bridge: it turns a single adapter into the
+ * handler's `commit`, `events`, and per-model `load` and `list` operations, so no
+ * code above the adapter needs to know which mapper you chose.
  */
 export {};

package/dist/source/adapters/drizzle.d.ts

@@ -1,32 +1,37 @@
 /**
- * Drizzle Data Source adapter. Same adapter interface + conformance as `prismaDataSource`,
- * built against Drizzle's REAL API (read from drizzle-orm's own source/docs):
- *   - `db.transaction(async (tx) => …)` — interactive transaction (commit/rollback).
- *   - `db.execute(sql`…`)` — parametrized raw SQL; `sql.identifier()` safely quotes
- *     dynamic table/column names, `sql`${value}`` parametrizes values.
+ * The Drizzle adapter for the data-source interface. It implements the same
+ * {@link DataSourceAdapter} contract as {@link prismaDataSource} and passes the
+ * same conformance suite, built against Drizzle's query API:
+ *   - `db.transaction(async (tx) => …)` runs an interactive transaction that
+ *     commits or rolls back as a unit.
+ *   - `db.execute(sql`…`)` runs parameterized raw SQL; `sql.identifier()` safely
+ *     quotes dynamic table and column names, and `sql`${value}`` parameterizes
+ *     values.
  *
- * SCHEMA-DRIVEN COLUMNS. Unlike Prisma — whose delegate applies the model's
- * `@map` for free — this adapter writes raw SQL, so it would otherwise bypass any
- * field→column translation. It therefore derives every table + column name from
- * the SAME rule the provisioner uses (`generateProvisionPlan`):
+ * Table and column names come from your schema, not from a hand-written Drizzle
+ * table. Because this adapter issues raw SQL, it would otherwise bypass any
+ * field-to-column translation, so it derives every name from the same rule the
+ * table provisioner uses:
  *   table  = `model.tableName ?? key`
- *   column = `fieldMeta.column ?? camelToSnake(field)`   (+ the model's tenancy column)
- * so `ablo migrate` (which emits `operator_id`) and this adapter (which now writes
- * `operator_id`) COMPOSE. Define the schema once, point Ablo at your Postgres —
- * no hand-written parallel Drizzle table. The adapter is the translation boundary:
- * its public surface (rows in/out, outbox `data`) is field-keyed (the SDK shape);
- * the physical columns it reads/writes are snake_case.
+ *   column = `fieldMeta.column ?? camelToSnake(field)`   (plus the tenancy column)
+ * This keeps the tables `ablo migrate` creates (for example `operator_id`) and the
+ * columns this adapter reads and writes in agreement. You define the schema once
+ * and point the engine at your Postgres database. The adapter is the translation
+ * boundary: the rows it accepts and returns, and the outbox `data` it writes, are
+ * keyed by field name, while the physical columns it touches are snake_case.
  *
- * IMPORTANT GOTCHAS (from drizzle-orm docs):
- *   1. Interactive `db.transaction` requires a driver that supports it. Neon's
- *      `neon-http` driver does NOT (single-shot only) — use `neon-serverless`
- *      (WebSocket) or `pg`. With neon-http the commit path throws at runtime.
- *   2. `db.execute` result shape is driver-specific (postgres-js returns an
- *      array-like RowList; node-postgres returns `{ rows }`). `rowsOf()`
+ * Two things to know about drivers:
+ *   1. Interactive `db.transaction` needs a driver that supports it. Neon's
+ *      `neon-http` driver is single-shot and does not, so use `neon-serverless`
+ *      (over WebSocket) or `pg`; under `neon-http` the commit path throws at
+ *      runtime.
+ *   2. The `db.execute` result shape is driver-specific — `postgres-js` returns an
+ *      array-like row list, while `node-postgres` returns `{ rows }`. `rowsOf`
  *      normalizes both.
  *
- * We use `sql` + `db.execute` for ALL writes (not the fluent builder) so the
- * adapter is one small, fully-typed unit with no per-driver builder generics.
+ * Every write goes through `sql` and `db.execute` rather than the fluent builder,
+ * which keeps the adapter one small, fully typed unit with no per-driver builder
+ * generics.
  */
 import { type SQL } from 'drizzle-orm';
 import type { DataSourceAdapter, Row } from '../adapter.js';