@abloatai/ablo 0.26.0 → 0.27.0

package/dist/schema/coordination.d.ts

@@ -1,11 +1,8 @@
 /**
- * Coordination authoring helpers for the model `conflict` axis.
- *
- * Composable disposition functions + a `cn`/`cx`-style combinator, so a model
- * declares conflict behaviour the way the rest of the DSL reads
- * (`relation.belongsTo()`, `field.string()`) — and the way modern libraries
- * compose config (Better Auth's `plugins: [admin(), twoFactor()]`, shadcn's
- * `cx(a, b)`) — instead of a raw disposition map:
+ * Authoring helpers for a model's `conflict` axis — the setting that decides
+ * what happens when two writers touch the same row. Instead of writing a raw
+ * disposition map, you compose small, named functions the way the rest of the
+ * schema DSL reads (`relation.belongsTo()`, `field.string()`):
  *
  * ```ts
  * import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
@@ -14,12 +11,11 @@
  * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
  * ```
  *
- * Each helper is named for the exact disposition it applies — the same
- * `overwrite | reject | notify` vocabulary used by write guards (`onStale`) —
- * and returns a partial {@link ConflictAxis}. {@link coordination} merges them
- * (later rules win on key collisions). The result is plain, serializable data —
- * the engine interpreter and schema round-trip are unchanged; this is only a
- * nicer authoring surface.
+ * Each helper is named for the disposition it applies — drawn from the same
+ * `overwrite | reject | notify` vocabulary the write guards use (`onStale`) —
+ * and returns a partial {@link ConflictAxis}. {@link coordination} merges the
+ * pieces, with later rules winning on key collisions. The result is plain,
+ * serializable data that the engine reads at commit time.
  */
 import type { ConflictAxis } from '../policy/types.js';
 /**
@@ -27,28 +23,28 @@ import type { ConflictAxis } from '../policy/types.js';
  * disposition helper below. Compose with {@link coordination}.
  */
 export type ConflictRule = ConflictAxis;
-/** A human's conflicting write OVERWRITES — wins; never blocked (LWW among humans). */
+/** A human's conflicting write wins and overwrites the other; it is never blocked. Among humans this gives last-write-wins. */
 export declare const humansOverwrite: () => ConflictRule;
-/** A human's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+/** A human's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
 export declare const humansReject: () => ConflictRule;
-/** A human's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+/** A human's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
 export declare const humansNotify: () => ConflictRule;
-/** An agent's conflicting write OVERWRITES — wins (rarely wanted). */
+/** An agent's conflicting write wins and overwrites the other (rarely what you want). */
 export declare const agentsOverwrite: () => ConflictRule;
-/** An agent's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+/** An agent's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
 export declare const agentsReject: () => ConflictRule;
-/** An agent's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+/** An agent's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
 export declare const agentsNotify: () => ConflictRule;
-/** A system/automation conflicting write OVERWRITES. */
+/** A system or automation write wins and overwrites the other. */
 export declare const systemOverwrite: () => ConflictRule;
-/** A system/automation conflicting write is REJECTED. */
+/** A system or automation write is rejected. */
 export declare const systemReject: () => ConflictRule;
-/** A system/automation stale write NOTIFIES (re-read & re-apply). */
+/** A system or automation stale write triggers a notification: it re-reads and re-applies. */
 export declare const systemNotify: () => ConflictRule;
 /**
- * Merge coordination rules into one {@link ConflictAxis} — the `cn`/`cx` of
- * conflict policy. Later rules win on key collisions; an omitted committer kind
- * falls through to the engine default at commit time.
+ * Merges coordination rules into a single {@link ConflictAxis}. Later rules win
+ * on key collisions, and a committer kind you leave out falls through to the
+ * engine's default at commit time.
  *
  * ```ts
  * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }

package/dist/schema/coordination.js

@@ -1,11 +1,8 @@
 /**
- * Coordination authoring helpers for the model `conflict` axis.
- *
- * Composable disposition functions + a `cn`/`cx`-style combinator, so a model
- * declares conflict behaviour the way the rest of the DSL reads
- * (`relation.belongsTo()`, `field.string()`) — and the way modern libraries
- * compose config (Better Auth's `plugins: [admin(), twoFactor()]`, shadcn's
- * `cx(a, b)`) — instead of a raw disposition map:
+ * Authoring helpers for a model's `conflict` axis — the setting that decides
+ * what happens when two writers touch the same row. Instead of writing a raw
+ * disposition map, you compose small, named functions the way the rest of the
+ * schema DSL reads (`relation.belongsTo()`, `field.string()`):
  *
  * ```ts
  * import { coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
@@ -14,38 +11,37 @@
  * // → { user: 'overwrite', agent: 'reject' }  (a human's write wins, an agent's yields)
  * ```
  *
- * Each helper is named for the exact disposition it applies — the same
- * `overwrite | reject | notify` vocabulary used by write guards (`onStale`) —
- * and returns a partial {@link ConflictAxis}. {@link coordination} merges them
- * (later rules win on key collisions). The result is plain, serializable data —
- * the engine interpreter and schema round-trip are unchanged; this is only a
- * nicer authoring surface.
+ * Each helper is named for the disposition it applies — drawn from the same
+ * `overwrite | reject | notify` vocabulary the write guards use (`onStale`) —
+ * and returns a partial {@link ConflictAxis}. {@link coordination} merges the
+ * pieces, with later rules winning on key collisions. The result is plain,
+ * serializable data that the engine reads at commit time.
  */
 // ── Humans (user sessions) ──────────────────────────────────────────────
-/** A human's conflicting write OVERWRITES — wins; never blocked (LWW among humans). */
+/** A human's conflicting write wins and overwrites the other; it is never blocked. Among humans this gives last-write-wins. */
 export const humansOverwrite = () => ({ user: 'overwrite' });
-/** A human's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+/** A human's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
 export const humansReject = () => ({ user: 'reject' });
-/** A human's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+/** A human's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
 export const humansNotify = () => ({ user: 'notify' });
 // ── Agents (AI) ─────────────────────────────────────────────────────────
-/** An agent's conflicting write OVERWRITES — wins (rarely wanted). */
+/** An agent's conflicting write wins and overwrites the other (rarely what you want). */
 export const agentsOverwrite = () => ({ agent: 'overwrite' });
-/** An agent's conflicting write is REJECTED — yields to a held claim / stale snapshot. */
+/** An agent's conflicting write is rejected, yielding to a held claim or a stale snapshot. */
 export const agentsReject = () => ({ agent: 'reject' });
-/** An agent's stale write NOTIFIES — re-reads & re-applies instead of clobbering. */
+/** An agent's stale write triggers a notification: it re-reads and re-applies rather than clobbering. */
 export const agentsNotify = () => ({ agent: 'notify' });
 // ── System / automation ─────────────────────────────────────────────────
-/** A system/automation conflicting write OVERWRITES. */
+/** A system or automation write wins and overwrites the other. */
 export const systemOverwrite = () => ({ system: 'overwrite' });
-/** A system/automation conflicting write is REJECTED. */
+/** A system or automation write is rejected. */
 export const systemReject = () => ({ system: 'reject' });
-/** A system/automation stale write NOTIFIES (re-read & re-apply). */
+/** A system or automation stale write triggers a notification: it re-reads and re-applies. */
 export const systemNotify = () => ({ system: 'notify' });
 /**
- * Merge coordination rules into one {@link ConflictAxis} — the `cn`/`cx` of
- * conflict policy. Later rules win on key collisions; an omitted committer kind
- * falls through to the engine default at commit time.
+ * Merges coordination rules into a single {@link ConflictAxis}. Later rules win
+ * on key collisions, and a committer kind you leave out falls through to the
+ * engine's default at commit time.
  *
  * ```ts
  * coordination(humansOverwrite(), agentsReject())  // → { user: 'overwrite', agent: 'reject' }

package/dist/schema/ddl.d.ts

@@ -1,21 +1,25 @@
 /**
- * Schema → Postgres DDL — the one pure SQL emitter shared by every consumer.
+ * Turns a schema definition into the ordered Postgres DDL that provisions and
+ * migrates its tables. A schema built with `defineSchema(...)` and serialized to
+ * {@link SchemaJSON} is the single source of truth, and this module lowers it to
+ * ordered SQL strings.
  *
- * `defineSchema(...)` (serialized to {@link SchemaJSON}) is the single source of
- * truth; this module lowers it to ordered DDL strings. Both the hosted server
- * (which applies it to Ablo-managed Postgres on `schema push`) and the
- * `ablo migrate` CLI (which applies it to a customer's own Postgres) call these
- * generators, so the SQL — column types, RLS, enum checks — is identical no
- * matter who runs it. There is no second type map.
+ * The same generators run wherever tables are created — in a hosted server
+ * applying them to the Postgres it manages, and in the `ablo migrate` CLI
+ * applying them to a customer's own Postgres — so the SQL, from column types to
+ * row-level security to enum checks, is identical no matter who runs it.
  *
- * Everything here is pure (returns strings; no DB, no I/O); the execution side
- * (transaction + advisory lock) lives with each consumer because it's coupled
- * to that consumer's Postgres client and error type.
+ * Everything here is pure: it returns strings and touches no database. The
+ * execution side — the transaction and advisory lock that actually run the
+ * statements — lives with each caller, because it is coupled to that caller's
+ * Postgres client and error types.
  *
- *  - `generateProvisionPlan` — additive + idempotent (CREATE/ADD … IF NOT
- *    EXISTS + RLS). Never loses data. The "create my tables" primitive.
- *  - `generateMigrationPlan` — the destructive-aware counterpart driven by the
- *    {@link diffSchema} step list (drops, renames, type casts, backfills).
+ *  - {@link generateProvisionPlan} builds an additive, idempotent plan (CREATE
+ *    and ADD … IF NOT EXISTS, plus row-level security) that never loses data —
+ *    the "create my tables" primitive.
+ *  - {@link generateMigrationPlan} is its destructive-aware counterpart, driven
+ *    by a {@link diffSchema} step list: drops, renames, type casts, and
+ *    backfills.
  */
 import type { SchemaJSON, ModelJSON } from './serialize.js';
 import type { MigrationStep, BackfillValue } from './diff.js';
@@ -23,30 +27,30 @@ export interface ProvisionPlan {
     /** The Postgres schema the tables live in (`app_<id>` or `public`). */
     readonly appSchema: string;
     /** Ordered, idempotent DDL statements. Safe to run repeatedly. Executors run
-     *  these together in ONE transaction. */
+     *  these together in one transaction. */
     readonly statements: readonly string[];
-    /** Post-commit, NON-transactional DDL (`VALIDATE CONSTRAINT`, `CREATE INDEX
-     *  CONCURRENTLY`) — run AFTER {@link statements} commit, each outside any
-     *  transaction, best-effort. Keeps the lock-heavy / scan-heavy work off the
-     *  main transaction so adding a foreign key never freezes a large, live BYO
-     *  table. Optional + back-compat: absent = nothing to run. */
+    /** Post-commit, non-transactional DDL (`VALIDATE CONSTRAINT`, `CREATE INDEX
+     *  CONCURRENTLY`) — run after {@link statements} commit, each outside any
+     *  transaction, best-effort. Keeps the lock-heavy and scan-heavy work off the
+     *  main transaction so adding a foreign key never freezes a large, live table.
+     *  Optional: when absent, there is nothing to run. */
     readonly concurrent?: readonly string[];
 }
 export interface ProvisionOptions {
     /**
-     * Emit `DEFERRABLE INITIALLY DEFERRED` FOREIGN KEY constraints for every
-     * `parent: true` belongsTo relation (true ownership edges only — see
-     * {@link foreignKeyStatements}). Off by default: the soft-reference model keeps
-     * out-of-order sync robust on Ablo-managed tables. Turn on for a customer's own
-     * (BYO / dedicated) database, where a clean, navigable relational schema is
-     * wanted and the DB starts empty (nothing for the constraint to fail against).
+     * Emit `DEFERRABLE INITIALLY DEFERRED` foreign-key constraints for the
+     * belongsTo relations that opt in; see {@link foreignKeyStatements} for exactly
+     * which relations qualify. Off by default, so soft references keep out-of-order
+     * sync robust. Turn it on for a customer's own database, where a clean,
+     * navigable relational schema is wanted and the database starts empty, so a
+     * constraint has nothing to fail against.
      */
     readonly foreignKeys?: boolean;
 }
 export interface MigrationPlan {
     /** The app Postgres schema the DDL targets (`app_<id>` or `public`). */
     readonly appSchema: string;
-    /** Ordered DDL statements (expand → contract). Run in ONE transaction. */
+    /** Ordered DDL statements (expand → contract). Run in one transaction. */
     readonly statements: readonly string[];
     /** Post-commit, non-transactional DDL — see {@link ProvisionPlan.concurrent}. */
     readonly concurrent?: readonly string[];
@@ -55,10 +59,10 @@ export interface MigrationPlan {
 export declare function appSchemaName(organizationId: string): string;
 export declare function camelToSnake(identifier: string): string;
 /**
- * Pure snake_case → camelCase — the inverse of {@link camelToSnake}, matching
- * `postgres.toCamel` semantics. Read-side translation: a column read back from a
- * BYO database (e.g. via `drizzleDataSource`) maps to the same JS field the SDK
- * wrote, so `camelToSnake('operatorId') === 'operator_id'` and
+ * Converts snake_case to camelCase — the inverse of {@link camelToSnake}. This
+ * is the read-side translation: a column read back from a customer's own
+ * database maps to the same JavaScript field the SDK wrote, so
+ * `camelToSnake('operatorId') === 'operator_id'` and
  * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
  */
 export declare function snakeToCamel(identifier: string): string;
@@ -66,13 +70,13 @@ export declare function snakeToCamel(identifier: string): string;
 export declare function q(identifier: string): string;
 export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;
 /**
- * Build the additive, idempotent provisioning plan for an app. Pure — no DB
- * access.
+ * Builds the additive, idempotent provisioning plan for an app. Pure — it does
+ * not touch a database.
  *
- * `targetSchema` is where the tables live: the app's schema `app_<id>` on the
- * shared tier, or `public` on a dedicated tenant's own database (where the DB
- * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
- * skipped (it always exists).
+ * `targetSchema` is where the tables live: a per-app Postgres schema such as
+ * `app_<id>`, or `public` when the database itself is the isolation boundary
+ * (for example a customer's own database). For `public` the `CREATE SCHEMA`
+ * statement is skipped, since it always exists.
  */
 export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string, opts?: ProvisionOptions): ProvisionPlan;
 /**
@@ -87,7 +91,7 @@ export declare function generateMigrationPlan(steps: readonly MigrationStep[], o
     /** Constant seed values that let a required-field add / made-required step
      *  set NOT NULL on a non-empty table. Keyed by (model, field). */
     readonly backfills?: readonly BackfillValue[];
-    /** Emit DEFERRABLE FK constraints for `parent: true` edges of newly-created
-     *  models. Off by default — see {@link ProvisionOptions.foreignKeys}. */
+    /** Emit deferrable foreign-key constraints for the relations that opt in.
+     *  Off by default — see {@link ProvisionOptions.foreignKeys}. */
     readonly foreignKeys?: boolean;
 }): MigrationPlan;

package/dist/schema/ddl.js

@@ -1,21 +1,25 @@
 /**
- * Schema → Postgres DDL — the one pure SQL emitter shared by every consumer.
+ * Turns a schema definition into the ordered Postgres DDL that provisions and
+ * migrates its tables. A schema built with `defineSchema(...)` and serialized to
+ * {@link SchemaJSON} is the single source of truth, and this module lowers it to
+ * ordered SQL strings.
  *
- * `defineSchema(...)` (serialized to {@link SchemaJSON}) is the single source of
- * truth; this module lowers it to ordered DDL strings. Both the hosted server
- * (which applies it to Ablo-managed Postgres on `schema push`) and the
- * `ablo migrate` CLI (which applies it to a customer's own Postgres) call these
- * generators, so the SQL — column types, RLS, enum checks — is identical no
- * matter who runs it. There is no second type map.
+ * The same generators run wherever tables are created — in a hosted server
+ * applying them to the Postgres it manages, and in the `ablo migrate` CLI
+ * applying them to a customer's own Postgres — so the SQL, from column types to
+ * row-level security to enum checks, is identical no matter who runs it.
  *
- * Everything here is pure (returns strings; no DB, no I/O); the execution side
- * (transaction + advisory lock) lives with each consumer because it's coupled
- * to that consumer's Postgres client and error type.
+ * Everything here is pure: it returns strings and touches no database. The
+ * execution side — the transaction and advisory lock that actually run the
+ * statements — lives with each caller, because it is coupled to that caller's
+ * Postgres client and error types.
  *
- *  - `generateProvisionPlan` — additive + idempotent (CREATE/ADD … IF NOT
- *    EXISTS + RLS). Never loses data. The "create my tables" primitive.
- *  - `generateMigrationPlan` — the destructive-aware counterpart driven by the
- *    {@link diffSchema} step list (drops, renames, type casts, backfills).
+ *  - {@link generateProvisionPlan} builds an additive, idempotent plan (CREATE
+ *    and ADD … IF NOT EXISTS, plus row-level security) that never loses data —
+ *    the "create my tables" primitive.
+ *  - {@link generateMigrationPlan} is its destructive-aware counterpart, driven
+ *    by a {@link diffSchema} step list: drops, renames, type casts, and
+ *    backfills.
  */
 import { AbloValidationError } from '../errors.js';
 import { resolveTenancy, tenancyColumn } from './tenancy.js';
@@ -33,10 +37,10 @@ export function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
 /**
- * Pure snake_case → camelCase — the inverse of {@link camelToSnake}, matching
- * `postgres.toCamel` semantics. Read-side translation: a column read back from a
- * BYO database (e.g. via `drizzleDataSource`) maps to the same JS field the SDK
- * wrote, so `camelToSnake('operatorId') === 'operator_id'` and
+ * Converts snake_case to camelCase — the inverse of {@link camelToSnake}. This
+ * is the read-side translation: a column read back from a customer's own
+ * database maps to the same JavaScript field the SDK wrote, so
+ * `camelToSnake('operatorId') === 'operator_id'` and
  * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
  */
 export function snakeToCamel(identifier) {
@@ -70,7 +74,7 @@ const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at
 /**
  * A Postgres-identifier-safe constraint name ≤63 bytes. When the natural
  * `<table>_<col>_<suffix>` exceeds the limit, fall back to a deterministic
- * hashed form so the name stays stable AND matches what Postgres actually stores
+ * hashed form so the name stays stable and matches what Postgres actually stores
  * — a silently-truncated name would never match the DO-block existence guard,
  * breaking idempotency (re-adds every push) and risking prefix collisions.
  */
@@ -86,45 +90,47 @@ function constraintName(table, col, suffix) {
     return `${prefix}_${hash}_${suffix}`;
 }
 /**
- * Foreign-key constraints for a model's belongsTo relations marked `{ fk: true }`.
+ * Builds the foreign-key constraints for a model's belongsTo relations that opt
+ * in by setting `{ fk: true }`.
  *
- * Emission is driven by an explicit `fk` marker, DECOUPLED from `parent`
- * (`parent` = sync-group fan-out / visibility, control plane; `fk` = physical
- * referential integrity, data plane — orthogonal axes, per Drizzle's
- * relations()-vs-references() split and the Zanzibar "parent is permission-only"
- * rule). A relation sets `fk` only when its target is co-located in the same DB
- * AND written in the same commit, and is a strong / contained entity. Soft
- * references (provenance / template pointers, e.g. `sourceSlideId`, `templateId`)
- * stay plain columns — a hard FK there would reject a write pointing cross-scope
- * or at an absent row and break sync.
+ * The `fk` marker is deliberately separate from `parent`: `parent` controls
+ * sync-group fan-out and visibility, while `fk` requests physical referential
+ * integrity in the database. A relation sets `fk` only when its target lives in
+ * the same database, is written in the same commit, and is a strong, contained
+ * entity. Soft references — provenance or template pointers such as
+ * `sourceSlideId` or `templateId` — stay plain columns; a hard foreign key there
+ * would reject a write that points across scopes or at an absent row and break
+ * sync.
  *
- * LIVE / POPULATED tables: a plain ADD CONSTRAINT takes SHARE ROW EXCLUSIVE on
- * both tables and scans the whole child table — freezing writes on a customer's
- * production DB. So the constraint is added `NOT VALID` (instant, no scan, brief
- * lock) INSIDE the transaction, and the existing-row check (`VALIDATE
- * CONSTRAINT`, SHARE UPDATE EXCLUSIVE — allows writes) plus the child index
- * (`CREATE INDEX CONCURRENTLY`) are returned SEPARATELY in {@link
- * ForeignKeyDdl.concurrent}, run after commit, outside any transaction, and are
- * best-effort: if existing data violates a freshly-added FK the VALIDATE is
- * skipped (logged, never fatal), the constraint still enforces all new writes,
- * and nothing is destroyed.
+ * On a live, populated table a plain `ADD CONSTRAINT` takes a heavy lock and
+ * scans the whole child table, which would freeze writes on a customer's
+ * production database. To avoid that, the constraint is added `NOT VALID`
+ * (instant, no scan, brief lock) inside the transaction, and the existing-row
+ * check (`VALIDATE CONSTRAINT`, which allows concurrent writes) plus the child
+ * index (`CREATE INDEX CONCURRENTLY`) are returned separately in {@link
+ * ForeignKeyDdl.concurrent}, to run after commit, outside any transaction, and
+ * best-effort: if existing data violates a freshly added constraint the
+ * validation is skipped (logged, never fatal), the constraint still enforces
+ * every new write, and nothing is destroyed.
  *
- * The key is a pure `DEFERRABLE INITIALLY DEFERRED` **integrity guard** with
- * `ON DELETE NO ACTION`: it NEVER mutates a child row itself. (SET NULL / CASCADE
- * would change data server-side with NO sync_delta — invisible to other clients
- * until re-bootstrap — and would override the app-layer ModelRegistry onDelete
- * contract.) The app layer owns deletes + nullification and emits the deltas; the
- * deferred check just verifies — at COMMIT, so same-batch child-before-parent and
- * the app's own cascade both pass — that integrity holds, failing loudly only if
- * the app left a dangling reference.
+ * The constraint is a `DEFERRABLE INITIALLY DEFERRED` integrity guard with `ON
+ * DELETE NO ACTION`; it never mutates a child row itself. A `SET NULL` or
+ * `CASCADE` action would change data in the database with no matching
+ * sync_delta — invisible to other clients until they re-bootstrap — and would
+ * override the application layer's own onDelete handling. The application layer
+ * owns deletes and nullification and emits the deltas; the deferred check only
+ * verifies, at commit time (so a same-batch child-before-parent write and the
+ * application's own cascade both pass), that integrity holds, failing loudly
+ * only when a dangling reference is left behind.
  *
- * Authoritative + idempotent: a same-named constraint that isn't deferrable or
- * carries the wrong delete action (a hand-added or legacy FK) is dropped and
- * recreated; an already-correct one is left untouched (no re-validation cost).
- * Emitted in a final pass, after every referenced table exists.
+ * Emission is idempotent and authoritative: a same-named constraint that is not
+ * deferrable or carries the wrong delete action (a hand-added or older foreign
+ * key) is dropped and recreated, while an already-correct one is left untouched
+ * with no revalidation cost. It runs in a final pass, after every referenced
+ * table exists.
  *
- * The FK column is resolved the SAME way the table loop names columns
- * (`fieldMeta.column ?? camelToSnake(field)`), not from `rel.foreignKeyColumn` —
+ * The foreign-key column is resolved the same way the table loop names columns
+ * (`fieldMeta.column ?? camelToSnake(field)`), not from `rel.foreignKeyColumn`:
  * the table loop ignores relation casing, so trusting `foreignKeyColumn` would
  * mismatch the real column whenever `casing` is unset.
  */
@@ -143,7 +149,7 @@ function foreignKeyStatements(table, model, models, qs) {
     const concurrent = [];
     for (const rel of Object.values(model.relations)) {
         if (rel.type !== 'belongsTo')
-            continue; // only relations whose FK column lives on THIS table
+            continue; // only relations whose FK column lives on this table
         if (rel.options?.fk !== true)
             continue; // explicit `fk` marker — decoupled from `parent` (visibility)
         const targetModel = models[rel.target];
@@ -171,7 +177,7 @@ function foreignKeyStatements(table, model, models, qs) {
             `REFERENCES ${targetQt} (${q('id')}) ON DELETE NO ACTION DEFERRABLE INITIALLY DEFERRED NOT VALID;\n` +
             `  END IF;\nEND $$;`);
         // Post-commit, non-blocking: validate existing rows (SHARE UPDATE EXCLUSIVE,
-        // allows concurrent writes) then index the child column (Postgres does NOT
+        // allows concurrent writes) then index the child column (Postgres does not
         // auto-index the referencing column → parent deletes would seq-scan it).
         concurrent.push(`ALTER TABLE ${qt} VALIDATE CONSTRAINT ${q(cname)};`);
         concurrent.push(`CREATE INDEX CONCURRENTLY IF NOT EXISTS ${q(iname)} ON ${qt} (${q(col)});`);
@@ -180,13 +186,13 @@ function foreignKeyStatements(table, model, models, qs) {
 }
 // ── Provisioning (additive, idempotent) ─────────────────────────────────────
 /**
- * Build the additive, idempotent provisioning plan for an app. Pure — no DB
- * access.
+ * Builds the additive, idempotent provisioning plan for an app. Pure — it does
+ * not touch a database.
  *
- * `targetSchema` is where the tables live: the app's schema `app_<id>` on the
- * shared tier, or `public` on a dedicated tenant's own database (where the DB
- * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
- * skipped (it always exists).
+ * `targetSchema` is where the tables live: a per-app Postgres schema such as
+ * `app_<id>`, or `public` when the database itself is the isolation boundary
+ * (for example a customer's own database). For `public` the `CREATE SCHEMA`
+ * statement is skipped, since it always exists.
  */
 export function generateProvisionPlan(schema, targetSchema, opts = {}) {
     const appSchema = targetSchema;
@@ -194,10 +200,11 @@ export function generateProvisionPlan(schema, targetSchema, opts = {}) {
     const statements = appSchema === 'public' ? [] : [`CREATE SCHEMA IF NOT EXISTS ${qs};`];
     const concurrent = [];
     for (const [key, model] of Object.entries(schema.models)) {
-        // Control-plane models (Ablo's own sync log / attribution / audit) are never
-        // emitted into a tenant database — only `tenant`-plane models are. Absent
-        // plane = `tenant` (back-compat). This declared boundary is what makes "what
-        // a BYO customer DB gets" derivable instead of hand-coded.
+        // Control-plane models (the engine's own sync log, attribution, and audit
+        // tables) are never emitted into a tenant database — only `tenant`-plane
+        // models are. A model with no declared plane defaults to `tenant`. This
+        // declared boundary is what makes the set of tables a customer's own
+        // database receives derivable instead of hand-coded.
         if ((model.plane ?? 'tenant') === 'control')
             continue;
         // Default the physical table to the model key when `tableName` is omitted —
@@ -316,7 +323,7 @@ export function generateMigrationPlan(steps, opts) {
     const statements = [];
     const concurrent = [];
     // The app schema must exist before any statement targets it. On a fresh
-    // org's FIRST push (`prev = null`) the migration plan IS the provisioning —
+    // org's first push (`prev = null`) the migration plan is the provisioning —
     // `app_<orgId>` has never been created, and skipping this line made every
     // first push die with `3F000 invalid_schema_name` at statement 0. Idempotent
     // (`IF NOT EXISTS`), so emitting it on every later migration is free.
@@ -464,8 +471,8 @@ export function generateMigrationPlan(steps, opts) {
             }
         }
     }
-    // Foreign keys (opt-in). Reconcile against the FULL `next` schema, not just
-    // create_model steps: a parent edge ADDED to an existing model surfaces only as
+    // Foreign keys (opt-in). Reconcile against the full `next` schema, not just
+    // create_model steps: a parent edge added to an existing model surfaces only as
     // an add_field (relation changes aren't diffed), so a create_model-only pass
     // would never materialize its FK. The DO-block is authoritative + idempotent
     // (a no-op when the constraint is already correct), so emitting the full set

package/dist/schema/ddlLock.d.ts

@@ -1,32 +1,28 @@
 /**
- * Safe-DDL LOCKING knobs — the ONE reader for how a schema change acquires
- * (and retries for) table locks, shared by BOTH executors of the provision
- * plan:
+ * Lock settings for schema-change (DDL) statements. When a schema push alters a
+ * table, these values control how quickly the change gives up on a contended
+ * lock and how many times it retries. The command-line `ablo migrate` and the
+ * host that applies a schema push both resolve their lock behavior through this
+ * module, so tuning the environment variables below changes both paths the same
+ * way.
  *
- *   - `ablo migrate` (cli/migrate.ts) — the customer runs the DDL themselves
- *   - the hosted executor (`apps/sync-server/src/schema/ddlExec.ts`)
+ * The defaults follow the standard safe-migration recipe: a short `lock_timeout`
+ * so a blocked `ALTER` aborts quickly instead of parking an `ACCESS EXCLUSIVE`
+ * lock request at the head of the queue — which would freeze every other query
+ * on that table behind it — paired with a bounded retry-and-backoff on the
+ * resulting timeout.
  *
- * The two used to carry copy-pasted constants and had already drifted: the
- * server honored `ABLO_SCHEMA_LOCK_ATTEMPTS` while the CLI hardcoded 5, so an
- * operator tuning the knob got it applied by hosted push but silently ignored
- * by `ablo migrate`. Both now resolve through here.
- *
- * The settings themselves are the battle-tested ones every mature migration
- * tool uses (GitLab `with_lock_retries`, Strong Migrations, Doctolib
- * `safe-pg-migrations`): a LOW `lock_timeout` so a blocked ALTER aborts fast
- * instead of parking an ACCESS EXCLUSIVE request at the head of the lock
- * queue (which would freeze every query on that table behind it), plus a
- * bounded retry-with-backoff on the `55P03` abort.
- *
- * Env knobs (read at CALL time, not import time, so tests and long-lived
- * processes see updates): `ABLO_SCHEMA_LOCK_TIMEOUT` / `ABLO_SCHEMA_LOCK_ATTEMPTS`
- * — the older `ABLO_DDL_*` names are still honored so existing setups don't
- * break.
+ * The environment variables are read each time a resolver is called, not once
+ * at import, so a long-running process or a test that changes them sees the
+ * update: `ABLO_SCHEMA_LOCK_TIMEOUT` and `ABLO_SCHEMA_LOCK_ATTEMPTS`. The older
+ * `ABLO_DDL_*` names are also accepted.
  */
-/** Postgres SQLSTATE `lock_not_available` — a `lock_timeout` abort. The ONE
- *  retryable DDL failure; everything else is a real error. */
+/** The Postgres SQLSTATE `55P03` (`lock_not_available`), raised when a statement
+ *  gives up waiting for a lock after `lock_timeout`. This is the one DDL failure
+ *  worth retrying; any other error is a genuine problem. */
 export declare const PG_LOCK_NOT_AVAILABLE = "55P03";
-/** The env subset the resolvers read — injectable for tests. */
+/** The subset of environment variables the resolvers in this module read. It is
+ *  passed in explicitly so tests can supply their own values. */
 export type DdlLockEnv = Readonly<Record<string, string | undefined>>;
 /** `lock_timeout` for the DDL transaction (a Postgres duration string). */
 export declare function resolveDdlLockTimeout(env?: DdlLockEnv): string;