@abloatai/ablo 0.6.0 → 0.7.0

package/dist/errors.js

@@ -18,6 +18,7 @@
  *
  * Both work on every subclass.
  */
+export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
 export class AbloError extends Error {
@@ -25,14 +26,32 @@ export class AbloError extends Error {
      *  switch on `e.type` without `instanceof` checks across package
      *  boundaries (matches Stripe's `err.type` pattern). */
     type = 'AbloError';
-    /** Stable short identifier for logs + metrics.
-     *  E.g. `'apikey_invalid'`, `'capability_scope_denied'`. */
+    /** Stable short identifier for logs + metrics, drawn from the closed
+     *  {@link ErrorCode} registry — e.g. `'apikey_invalid'`,
+     *  `'capability_scope_denied'`. Stored as a plain `string` (not
+     *  `ErrorCode`) so an older SDK still surfaces a newer server's code it
+     *  doesn't recognise yet; producers are constrained at the constructor
+     *  param instead. */
     code;
     /** HTTP status code when the error originated from an HTTP response. */
     httpStatus;
     /** Correlation id for ops — present when the server sent one on
      *  `x-request-id`. Include in support tickets. */
     requestId;
+    /** Which input caused the error — a model/field path like
+     *  `'dataroomMember.grants.subject'`. Mirrors Stripe's `error.param`;
+     *  lets tooling point at the exact offending declaration. */
+    param;
+    /** Link to the docs for this `code`. Mirrors Stripe's `error.doc_url`.
+     *  Defaults from `code` via {@link docUrlForCode} when omitted. */
+    docUrl;
+    /** Domain-specific structured payload merged into the wire envelope —
+     *  e.g. a schema push's `{ warnings, unexecutable }`, a stale write's
+     *  conflicting rows. Mirrors how Stripe attaches type-specific fields
+     *  (`decline_code`, `payment_intent`) alongside the standard ones, so a
+     *  structured error keeps its detail through `toJSON` instead of being
+     *  flattened to a bare message. */
+    details;
     constructor(message, options) {
         super(message);
         this.name = this.constructor.name;
@@ -42,10 +61,41 @@ export class AbloError extends Error {
             this.httpStatus = options.httpStatus;
         if (options?.requestId !== undefined)
             this.requestId = options.requestId;
+        if (options?.param !== undefined)
+            this.param = options.param;
+        if (options?.details !== undefined)
+            this.details = options.details;
+        const docUrl = options?.docUrl ?? (options?.code ? docUrlForCode(options.code) : undefined);
+        if (docUrl !== undefined)
+            this.docUrl = docUrl;
         if (options?.cause !== undefined) {
             Object.defineProperty(this, 'cause', { value: options.cause, enumerable: false });
         }
     }
+    /**
+     * Serialize to Stripe's error-object shape: `{ type, code, param, message,
+     * doc_url, request_id }`. One JSON shape across HTTP bodies, WS frames, and
+     * logs — so consumers parse Ablo errors the way they already parse Stripe's.
+     */
+    toJSON() {
+        return {
+            type: this.type,
+            ...(this.code !== undefined ? { code: this.code } : {}),
+            ...(this.param !== undefined ? { param: this.param } : {}),
+            message: this.message,
+            ...(this.docUrl !== undefined ? { doc_url: this.docUrl } : {}),
+            ...(this.requestId !== undefined ? { request_id: this.requestId } : {}),
+            ...(this.details ?? {}),
+        };
+    }
+}
+/**
+ * Map a stable error `code` to its docs URL — the one place the convention
+ * lives, so every error carrying a code gets a `doc_url` for free (Stripe
+ * ships a link on every error).
+ */
+export function docUrlForCode(code) {
+    return `https://docs.abloatai.com/errors#${code}`;
 }
 /** 401 — invalid/missing/expired credentials. */
 export class AbloAuthenticationError extends AbloError {
@@ -224,7 +274,10 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    const publicCode = code === 'intent_conflict' ? 'claim_conflict' : code;
+    // Wire boundary: an incoming code is an arbitrary string (a newer server
+    // may send a code this SDK predates). Cast to ErrorCode here — the one
+    // sanctioned crossing — so internal producers stay statically checked.
+    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
     const baseOpts = { code: publicCode, httpStatus: status, requestId };
     if (status === 401)
         return new AbloAuthenticationError(message, baseOpts);

package/dist/index.d.ts

@@ -48,9 +48,10 @@ export { session, agent } from './principal.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
-export { defaultPolicy } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, } from './errors.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
+export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errors.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';

package/dist/index.js

@@ -74,11 +74,11 @@ export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest,
 // (reject-on-stale) is already applied server-side, so you only import it
 // to COMPOSE a custom policy. Leave it alone and stale writes are rejected
 // safely by default. Type counterparts live under `Ablo.Conflict.*`.
-export { defaultPolicy } from './policy/index.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/policy/index.d.ts

@@ -16,4 +16,4 @@
  * ```
  */
 export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, IntentHeldConflict, } from './types.js';
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/index.js

@@ -15,4 +15,4 @@
  * };
  * ```
  */
-export { defaultPolicy } from './types.js';
+export { defaultPolicy, capabilityPreemptPolicy } from './types.js';

package/dist/policy/types.d.ts

@@ -48,6 +48,14 @@ export interface IntentHeldConflict extends ConflictBase {
     readonly entityId: string;
     /** Holder's intent expiry (ms since epoch). */
     readonly expiresAt: number;
+    /**
+     * The committer's granted capability operations (the key's allowlist). A
+     * policy is a pure function of the conflict value, so it can only authorize
+     * on what's carried here — this is what lets a policy express "preempt iff
+     * the committer holds `intent.preempt`" (see `capabilityPreemptPolicy`).
+     * Empty for a human session with no allowlist.
+     */
+    readonly committerOperations: readonly string[];
 }
 /**
  * The discriminated union the policy receives. Switch on `.kind` to
@@ -61,6 +69,20 @@ export type ConflictDecision = {
 } | {
     readonly action: 'allow';
     readonly note?: string;
+}
+/**
+ * Evict the current holder and grant the target to the committer. Only
+ * meaningful for an `intent_held` conflict at claim time (`intent_begin`):
+ * the holder receives an `intent_lost` (reason `'preempted'`) and the
+ * preemptor takes the lease, jumping ahead of any FIFO waiters. This is the
+ * authorization seam for preemption — a policy returns `preempt` only for a
+ * committer it deems higher-priority (e.g. a supervisor over its sub-agents,
+ * or an identity holding a preempt capability). At commit time there is no
+ * holder to evict, so a `preempt` decision there is treated as `allow`.
+ */
+ | {
+    readonly action: 'preempt';
+    readonly reason?: string;
 };
 /**
  * Pluggable decision function. Sync or async.
@@ -81,4 +103,13 @@ export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<
  * intent-conflicting write through.
  */
 export declare const defaultPolicy: ConflictPolicy;
+/**
+ * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
+ * committer holds the `intent.preempt` operation in its capability allowlist
+ * (the holder is evicted, the committer takes the lease); everything else falls
+ * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
+ * global to let a privileged identity jump a held entity without a bespoke
+ * policy. The authorization is the capability, not an identity string.
+ */
+export declare const capabilityPreemptPolicy: ConflictPolicy;
 export {};

package/dist/policy/types.js

@@ -15,3 +15,18 @@ export const defaultPolicy = (conflict) => ({
     action: 'reject',
     reason: conflict.kind === 'stale_context' ? 'stale_context' : 'intent_conflict',
 });
+/**
+ * Capability-gated preemption. An `intent_held` conflict is PREEMPTED when the
+ * committer holds the `intent.preempt` operation in its capability allowlist
+ * (the holder is evicted, the committer takes the lease); everything else falls
+ * back to `defaultPolicy` (reject). Opt-in — wire it as a `conflictPolicies`
+ * global to let a privileged identity jump a held entity without a bespoke
+ * policy. The authorization is the capability, not an identity string.
+ */
+export const capabilityPreemptPolicy = (conflict) => {
+    if (conflict.kind === 'intent_held' &&
+        conflict.committerOperations.includes('intent.preempt')) {
+        return { action: 'preempt', reason: 'capability:intent.preempt' };
+    }
+    return defaultPolicy(conflict);
+};

package/dist/react/AbloProvider.d.ts

@@ -114,7 +114,19 @@ export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     sessionErrorDetector?: SessionErrorDetector;
     onlineStatus?: OnlineStatusProvider;
     configOverrides?: SyncEngineConfig;
+    /**
+     * Raw sync-group strings for the initial connection. Prefer {@link scope} —
+     * the model form (`{ decks: deckId }`) that the engine resolves through the
+     * schema's `scope`, so you never hand-write a `deck:<id>` string. Both merge.
+     */
     syncGroups?: string[];
+    /**
+     * Model-form connection scope: `{ decks: deckId, documents: documentId }` or
+     * entity refs. Resolved through the schema's per-model `scope` into group
+     * strings (so typename `SlideDeck` → `deck:<id>`), unioned with {@link syncGroups}.
+     * Memoize the object if it's derived, to avoid rotating the engine each render.
+     */
+    scope?: ParticipantScope;
     bootstrapBaseUrl?: string;
     maxPoolSize?: number;
     /**

package/dist/react/AbloProvider.js

@@ -32,7 +32,7 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
     // Account scope is no longer accepted from props. The engine learns
     // it from auth (capability token) at bootstrap and we read it back
     // out of `_store.orgId` once `engine.ready()` resolves.
@@ -86,7 +86,11 @@ export function AbloProvider(props) {
             mutationExecutor,
             mutationDispatcher,
             configOverrides,
-            syncGroups,
+            // Union raw strings with model-form `scope` resolved through the schema,
+            // so `scope={{ decks: id }}` becomes `deck:<id>` via the model's `scope`.
+            syncGroups: scope
+                ? [...(syncGroups ?? []), ...resolveParticipantSyncGroups(scope, schema)]
+                : syncGroups,
             bootstrapBaseUrl,
             maxPoolSize,
             persistence,
@@ -251,7 +255,11 @@ export function useParticipant(opts) {
     const ctx = useContext(AbloInternalContext);
     const engine = ctx?.engine ?? null;
     const { paused = false } = opts;
-    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(opts.scope).sort());
+    // Resolve the model-form scope ({ decks: id } / refs) THROUGH the schema, so a
+    // model's declared `scope` kind is honored (typename `SlideDeck` → `deck:<id>`,
+    // not the `type:id` string fallback). Schema appears once the engine is ready;
+    // until then refs resolve by convention, then re-resolve when it arrives.
+    const scopeKey = JSON.stringify(resolveParticipantSyncGroups(opts.scope, engine?.schema).sort());
     const scopedSyncGroups = useMemo(() => JSON.parse(scopeKey), [scopeKey]);
     const [claimError, setClaimError] = useState(null);
     const [claimConnected, setClaimConnected] = useState(false);

package/dist/schema/ddl.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Schema → Postgres DDL — the one pure SQL emitter shared by every consumer.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ *  - `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).
+ */
+import type { SchemaJSON, ModelJSON } from './serialize.js';
+import type { MigrationStep, BackfillValue } from './diff.js';
+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. */
+    readonly statements: readonly string[];
+}
+export interface MigrationPlan {
+    /** The app Postgres schema the DDL targets (`app_<id>` or `public`). */
+    readonly appSchema: string;
+    /** Ordered DDL statements (expand → contract). */
+    readonly statements: readonly string[];
+}
+/** Per-app schema name for an app (organization) id. */
+export declare function appSchemaName(organizationId: string): string;
+export declare function camelToSnake(identifier: string): string;
+/** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
+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.
+ *
+ * `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).
+ */
+export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string): ProvisionPlan;
+/**
+ * Lower an ordered migration step list to DDL. `next` is the schema being pushed
+ * (the target column shapes are read from it), `prev` the active one (used to
+ * resolve the *old* table name on a model rename).
+ */
+export declare function generateMigrationPlan(steps: readonly MigrationStep[], opts: {
+    readonly prev: SchemaJSON | null;
+    readonly next: SchemaJSON;
+    readonly targetSchema: string;
+    /** 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[];
+}): MigrationPlan;

package/dist/schema/ddl.js

@@ -0,0 +1,317 @@
+/**
+ * Schema → Postgres DDL — the one pure SQL emitter shared by every consumer.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ *  - `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).
+ */
+import { resolveTenancy, tenancyColumn } from './tenancy.js';
+// ── Identifier safety ────────────────────────────────────────────────────────
+/** Postgres unquoted-identifier-safe slug: lowercase `[a-z0-9_]`, ≤50 chars. */
+function slug(raw) {
+    const s = raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return s.slice(0, 50) || 'x';
+}
+/** Per-app schema name for an app (organization) id. */
+export function appSchemaName(organizationId) {
+    return `app_${slug(organizationId)}`;
+}
+export function camelToSnake(identifier) {
+    return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+/** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
+export function q(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+// ── Field type mapping ───────────────────────────────────────────────────────
+export function sqlType(fieldType) {
+    switch (fieldType) {
+        case 'string':
+        case 'enum':
+            return 'TEXT';
+        case 'number':
+            // DOUBLE PRECISION, not INTEGER — a Zod `number` may be fractional and
+            // truncating to INTEGER is silent data loss.
+            return 'DOUBLE PRECISION';
+        case 'boolean':
+            return 'BOOLEAN';
+        case 'date':
+            return 'TIMESTAMPTZ';
+        case 'json':
+        default:
+            return 'JSONB';
+    }
+}
+const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+// ── Provisioning (additive, idempotent) ─────────────────────────────────────
+/**
+ * Build the additive, idempotent provisioning plan for an app. Pure — no DB
+ * access.
+ *
+ * `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).
+ */
+export function generateProvisionPlan(schema, targetSchema) {
+    const appSchema = targetSchema;
+    const qs = q(appSchema);
+    const statements = appSchema === 'public' ? [] : [`CREATE SCHEMA IF NOT EXISTS ${qs};`];
+    for (const [key, model] of Object.entries(schema.models)) {
+        // Default the physical table to the model key when `tableName` is omitted —
+        // same fallback the migration path uses (`tableOfModel: m.tableName ?? key`).
+        // Without this, a schema that doesn't set `tableName` (e.g. the `ablo init`
+        // starter) provisions zero tables.
+        const table = model.tableName ?? key;
+        const qt = `${qs}.${q(table)}`;
+        // Base columns are schema-driven, not blanket. `organization_id` (and its
+        // index + tenant-isolation RLS below) is emitted only for org-scoped models.
+        // A model that declares `orgScoped: false` (users, organizations, and other
+        // tables scoped via a FK / app layer) genuinely has no `organization_id`
+        // column — forcing one would add a NOT NULL column that fails on existing
+        // rows and contradicts the model's own declaration.
+        // Tenancy column: present only for column-scoped models, with the
+        // configured name (default `organization_id`). `parent`/`none` tenancy emit
+        // no tenancy column — they're scoped via a parent FK or not at all.
+        const orgCol = tenancyColumn(resolveTenancy(model));
+        const baseColumns = [
+            `  ${q('id')} TEXT PRIMARY KEY,`,
+            ...(orgCol ? [`  ${q(orgCol)} TEXT NOT NULL,`] : []),
+            `  ${q('created_by')} TEXT,`,
+            `  ${q('created_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW(),`,
+            `  ${q('updated_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW()`,
+        ];
+        statements.push(`CREATE TABLE IF NOT EXISTS ${qt} (\n${baseColumns.join('\n')}\n);`);
+        for (const [fieldName, meta] of Object.entries(model.fields)) {
+            const col = meta.column ?? camelToSnake(fieldName);
+            if (BASE_COLUMNS.has(col) || col === orgCol)
+                continue;
+            statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(meta.type)};`);
+            if (meta.type === 'enum' && meta.enumValues && meta.enumValues.length > 0) {
+                const cname = `${table}_${col}_enum`;
+                const allowed = meta.enumValues.map((v) => `'${v.replace(/'/g, "''")}'`).join(', ');
+                statements.push(`DO $$ BEGIN\n` +
+                    `  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = '${cname}') THEN\n` +
+                    `    ALTER TABLE ${qt} ADD CONSTRAINT ${q(cname)} CHECK (${q(col)} IN (${allowed}));\n` +
+                    `  END IF;\n` +
+                    `END $$;`);
+            }
+        }
+        // Org index + tenant-isolation RLS only where there's an `organization_id`
+        // to isolate on. Non-org-scoped tables rely on FK/app-layer scoping.
+        if (orgCol) {
+            statements.push(`CREATE INDEX IF NOT EXISTS ${q(`${table}_${orgCol}_idx`)} ON ${qt} (${q(orgCol)});`);
+            statements.push(`ALTER TABLE ${qt} ENABLE ROW LEVEL SECURITY;`);
+            statements.push(`ALTER TABLE ${qt} FORCE ROW LEVEL SECURITY;`);
+            const policy = `${table}_tenant_isolation`;
+            const predicate = `${q(orgCol)} = current_setting('app.current_org_id', true)`;
+            statements.push(`DROP POLICY IF EXISTS ${q(policy)} ON ${qt};`);
+            statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
+        }
+    }
+    return { appSchema, statements };
+}
+// ── Migration (destructive-aware, diff-driven) ──────────────────────────────
+function enumCheckStatements(table, col, qt, values) {
+    const cname = `${table}_${col}_enum`;
+    const stmts = [`ALTER TABLE ${qt} DROP CONSTRAINT IF EXISTS ${q(cname)};`];
+    if (values.length > 0) {
+        const allowed = values.map((v) => `'${v.replace(/'/g, "''")}'`).join(', ');
+        stmts.push(`ALTER TABLE ${qt} ADD CONSTRAINT ${q(cname)} CHECK (${q(col)} IN (${allowed}));`);
+    }
+    return stmts;
+}
+function indexName(table, col) {
+    return `${table}_${col}_idx`;
+}
+function columnNameOf(fieldName, meta) {
+    return meta?.column ?? camelToSnake(fieldName);
+}
+/**
+ * Encode a constant backfill value as a typed SQL literal. Inputs are operator-
+ * supplied (via the authed push), but we still encode by the field's declared
+ * type and escape strings rather than interpolate raw — defense-in-depth.
+ */
+function sqlLiteral(value, fieldType) {
+    switch (fieldType) {
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error(`backfill for a number field must be a finite number, got ${JSON.stringify(value)}`);
+            }
+            return String(value);
+        case 'boolean':
+            return value ? 'TRUE' : 'FALSE';
+        case 'date':
+            return `'${String(value).replace(/'/g, "''")}'::timestamptz`;
+        case 'json':
+            return `'${JSON.stringify(value).replace(/'/g, "''")}'::jsonb`;
+        case 'string':
+        case 'enum':
+        default:
+            return `'${String(value).replace(/'/g, "''")}'`;
+    }
+}
+/**
+ * Lower an ordered migration step list to DDL. `next` is the schema being pushed
+ * (the target column shapes are read from it), `prev` the active one (used to
+ * resolve the *old* table name on a model rename).
+ */
+export function generateMigrationPlan(steps, opts) {
+    const { prev, next, targetSchema, backfills = [] } = opts;
+    const qs = q(targetSchema);
+    const statements = [];
+    const qtFor = (table) => `${qs}.${q(table)}`;
+    const tableOfModel = (schema, key) => {
+        const m = schema?.models[key];
+        if (!m)
+            return null;
+        return m.tableName ?? key;
+    };
+    const backfillFor = (model, field) => backfills.find((b) => b.model === model && b.field === field);
+    for (const step of steps) {
+        switch (step.kind) {
+            case 'create_model': {
+                // Reuse the provisioner for the full table (base cols + fields + enum
+                // checks + RLS), minus its `CREATE SCHEMA` (the schema already exists
+                // mid-migration).
+                const def = next.models[step.model];
+                if (!def)
+                    break;
+                const sub = { v: next.v, models: { [step.model]: def }, identityRoles: next.identityRoles };
+                for (const s of generateProvisionPlan(sub, targetSchema).statements) {
+                    if (!s.startsWith('CREATE SCHEMA'))
+                        statements.push(s);
+                }
+                break;
+            }
+            case 'drop_model':
+                statements.push(`DROP TABLE IF EXISTS ${qtFor(step.tableName)};`);
+                break;
+            case 'rename_model': {
+                const fromTable = tableOfModel(prev, step.from);
+                const toTable = tableOfModel(next, step.to);
+                // A logical model rename only needs SQL when the physical table name
+                // actually changes; if tableName is unchanged the rename is metadata.
+                if (fromTable && toTable && fromTable !== toTable) {
+                    statements.push(`ALTER TABLE ${qtFor(fromTable)} RENAME TO ${q(toTable)};`);
+                }
+                break;
+            }
+            case 'add_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const qt = qtFor(table);
+                const col = columnNameOf(step.field, step.meta);
+                // Added nullable first (the column is born NULL on every existing row).
+                statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${sqlType(step.meta.type)};`);
+                if (step.meta.type === 'enum' && step.meta.enumValues?.length) {
+                    statements.push(...enumCheckStatements(table, col, qt, step.meta.enumValues));
+                }
+                // Backfill + enforce NOT NULL only with a supplied seed value. Without
+                // one, a required field stays nullable (gated `unexecutable` upstream).
+                const addBf = backfillFor(step.model, step.field);
+                if (addBf !== undefined) {
+                    statements.push(`UPDATE ${qt} SET ${q(col)} = ${sqlLiteral(addBf.value, step.meta.type)} WHERE ${q(col)} IS NULL;`);
+                    if (!step.meta.isOptional) {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} SET NOT NULL;`);
+                    }
+                }
+                if (step.meta.isIndexed) {
+                    statements.push(`CREATE INDEX IF NOT EXISTS ${q(indexName(table, col))} ON ${qt} (${q(col)});`);
+                }
+                break;
+            }
+            case 'drop_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const prevMeta = prev?.models[step.model]?.fields[step.field];
+                statements.push(`ALTER TABLE ${qtFor(table)} DROP COLUMN IF EXISTS ${q(columnNameOf(step.field, prevMeta))};`);
+                break;
+            }
+            case 'rename_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const prevMeta = prev?.models[step.model]?.fields[step.from];
+                const nextMeta = next.models[step.model]?.fields[step.to];
+                const fromCol = columnNameOf(step.from, prevMeta);
+                const toCol = columnNameOf(step.to, nextMeta);
+                if (fromCol === toCol)
+                    break;
+                statements.push(`ALTER TABLE ${qtFor(table)} RENAME COLUMN ${q(fromCol)} TO ${q(toCol)};`);
+                break;
+            }
+            case 'alter_field': {
+                const table = tableOfModel(next, step.model);
+                if (!table)
+                    break;
+                const qt = qtFor(table);
+                const nextMeta = next.models[step.model]?.fields[step.field];
+                let col = columnNameOf(step.field, nextMeta);
+                const ch = step.changes;
+                // 0. Physical column rename. Subsequent alterations must address
+                // the new name.
+                if (ch.column) {
+                    statements.push(`ALTER TABLE ${qt} RENAME COLUMN ${q(ch.column.from)} TO ${q(ch.column.to)};`);
+                    col = ch.column.to;
+                }
+                // 1. Type — in-place cast or lossy drop-and-recreate.
+                if (ch.type) {
+                    const target = sqlType(ch.type.to);
+                    if (ch.type.cast === 'notCastable') {
+                        statements.push(`ALTER TABLE ${qt} DROP COLUMN IF EXISTS ${q(col)};`);
+                        statements.push(`ALTER TABLE ${qt} ADD COLUMN IF NOT EXISTS ${q(col)} ${target};`);
+                    }
+                    else {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} TYPE ${target} USING ${q(col)}::${target};`);
+                    }
+                }
+                // 2. Enum CHECK — drop when leaving enum; (re)build when arriving at or
+                //    re-valuing an enum. Reads the full target value set from `next`.
+                if (ch.type?.from === 'enum' && nextMeta?.type !== 'enum') {
+                    statements.push(`ALTER TABLE ${qt} DROP CONSTRAINT IF EXISTS ${q(`${table}_${col}_enum`)};`);
+                }
+                else if (nextMeta?.type === 'enum' && (ch.enumValues || ch.type)) {
+                    statements.push(...enumCheckStatements(table, col, qt, nextMeta.enumValues ?? []));
+                }
+                // 3. Nullability. DROP NOT NULL is always safe. SET NOT NULL is gated
+                //    upstream (unexecutable on a table with NULLs); a supplied backfill
+                //    seeds the existing NULLs first so the constraint can take.
+                if (ch.nullability) {
+                    if (ch.nullability.toOptional) {
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} DROP NOT NULL;`);
+                    }
+                    else {
+                        const bf = backfillFor(step.model, step.field);
+                        if (bf !== undefined && nextMeta) {
+                            statements.push(`UPDATE ${qt} SET ${q(col)} = ${sqlLiteral(bf.value, nextMeta.type)} WHERE ${q(col)} IS NULL;`);
+                        }
+                        statements.push(`ALTER TABLE ${qt} ALTER COLUMN ${q(col)} SET NOT NULL;`);
+                    }
+                }
+                // 4. Index.
+                if (ch.indexed) {
+                    statements.push(ch.indexed.to
+                        ? `CREATE INDEX IF NOT EXISTS ${q(indexName(table, col))} ON ${qt} (${q(col)});`
+                        : `DROP INDEX IF EXISTS ${qs}.${q(indexName(table, col))};`);
+                }
+                break;
+            }
+        }
+    }
+    return { appSchema: targetSchema, statements };
+}