@abloatai/ablo 0.8.0 → 0.9.0

package/dist/schema/ddl.d.ts

@@ -22,14 +22,34 @@ 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. */
+    /** Ordered, idempotent DDL statements. Safe to run repeatedly. Executors run
+     *  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. */
+    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).
+     */
+    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). */
+    /** 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[];
 }
 /** Per-app schema name for an app (organization) id. */
 export declare function appSchemaName(organizationId: string): string;
@@ -46,7 +66,7 @@ export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']):
  * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
  * skipped (it always exists).
  */
-export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string): ProvisionPlan;
+export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string, opts?: ProvisionOptions): 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
@@ -59,4 +79,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}. */
+    readonly foreignKeys?: boolean;
 }): MigrationPlan;

package/dist/schema/ddl.js

@@ -55,6 +55,118 @@ export function sqlType(fieldType) {
     }
 }
 const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+// ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
+/**
+ * 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
+ * — a silently-truncated name would never match the DO-block existence guard,
+ * breaking idempotency (re-adds every push) and risking prefix collisions.
+ */
+function constraintName(table, col, suffix) {
+    const full = `${table}_${col}_${suffix}`;
+    if (full.length <= 63)
+        return full;
+    let h = 5381;
+    for (let i = 0; i < full.length; i++)
+        h = ((h * 33) + full.charCodeAt(i)) >>> 0;
+    const hash = h.toString(36);
+    const prefix = full.slice(0, Math.max(1, 63 - suffix.length - hash.length - 2));
+    return `${prefix}_${hash}_${suffix}`;
+}
+/**
+ * Foreign-key constraints for a model's belongsTo relations marked `{ 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * The FK 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.
+ */
+function foreignKeyStatements(table, model, models, qs) {
+    const qt = `${qs}.${q(table)}`;
+    // The model's provisioned column set — guard so a relation whose FK field
+    // isn't actually declared (no column) never produces a broken ALTER.
+    const orgCol = tenancyColumn(resolveTenancy(model));
+    const columns = new Set(['id', 'created_by', 'created_at', 'updated_at']);
+    if (orgCol)
+        columns.add(orgCol);
+    for (const [fieldName, meta] of Object.entries(model.fields)) {
+        columns.add(meta.column ?? camelToSnake(fieldName));
+    }
+    const statements = [];
+    const concurrent = [];
+    for (const rel of Object.values(model.relations)) {
+        if (rel.type !== 'belongsTo')
+            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];
+        if (!targetModel)
+            continue; // target not provisioned into this DB → can't reference it
+        if ((targetModel.plane ?? 'tenant') === 'control')
+            continue; // control-plane table absent in a tenant DB
+        const col = model.fields[rel.foreignKey]?.column ?? camelToSnake(rel.foreignKey);
+        if (!columns.has(col))
+            continue; // FK field isn't a provisioned column
+        const targetTable = targetModel.tableName ?? rel.target;
+        const cname = constraintName(table, col, 'fkey');
+        const lit = cname.replace(/'/g, "''");
+        const iname = constraintName(table, col, 'idx');
+        const targetQt = `${qs}.${q(targetTable)}`;
+        // In-tx: authoritative create as NOT VALID — instant, no child-table scan,
+        // only a brief lock. confdeltype 'a' = NO ACTION; recreate only when absent /
+        // not deferrable / wrong delete action, so a correct constraint is untouched.
+        statements.push(`DO $$ BEGIN\n` +
+            `  IF EXISTS (SELECT 1 FROM pg_constraint WHERE conname = '${lit}' AND (NOT condeferrable OR confdeltype <> 'a')) THEN\n` +
+            `    ALTER TABLE ${qt} DROP CONSTRAINT ${q(cname)};\n` +
+            `  END IF;\n` +
+            `  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = '${lit}') THEN\n` +
+            `    ALTER TABLE ${qt} ADD CONSTRAINT ${q(cname)} FOREIGN KEY (${q(col)}) ` +
+            `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
+        // 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)});`);
+    }
+    return { statements, concurrent };
+}
 // ── Provisioning (additive, idempotent) ─────────────────────────────────────
 /**
  * Build the additive, idempotent provisioning plan for an app. Pure — no DB
@@ -65,11 +177,18 @@ const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at
  * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
  * skipped (it always exists).
  */
-export function generateProvisionPlan(schema, targetSchema) {
+export function generateProvisionPlan(schema, targetSchema, opts = {}) {
     const appSchema = targetSchema;
     const qs = q(appSchema);
     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.
+        if ((model.plane ?? 'tenant') === 'control')
+            continue;
         // 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`
@@ -121,7 +240,19 @@ export function generateProvisionPlan(schema, targetSchema) {
             statements.push(`CREATE POLICY ${q(policy)} ON ${qt}\n  USING (${predicate})\n  WITH CHECK (${predicate});`);
         }
     }
-    return { appSchema, statements };
+    // Foreign keys (opt-in) — a final pass so every referenced table already
+    // exists when its constraint is added.
+    if (opts.foreignKeys) {
+        for (const [key, m] of Object.entries(schema.models)) {
+            if ((m.plane ?? 'tenant') === 'control')
+                continue;
+            const t = m.tableName ?? key;
+            const fk = foreignKeyStatements(t, m, schema.models, qs);
+            statements.push(...fk.statements);
+            concurrent.push(...fk.concurrent);
+        }
+    }
+    return { appSchema, statements, concurrent };
 }
 // ── Migration (destructive-aware, diff-driven) ──────────────────────────────
 function enumCheckStatements(table, col, qt, values) {
@@ -169,9 +300,10 @@ function sqlLiteral(value, fieldType) {
  * resolve the *old* table name on a model rename).
  */
 export function generateMigrationPlan(steps, opts) {
-    const { prev, next, targetSchema, backfills = [] } = opts;
+    const { prev, next, targetSchema, backfills = [], foreignKeys = false } = opts;
     const qs = q(targetSchema);
     const statements = [];
+    const concurrent = [];
     const qtFor = (table) => `${qs}.${q(table)}`;
     const tableOfModel = (schema, key) => {
         const m = schema?.models[key];
@@ -313,5 +445,21 @@ export function generateMigrationPlan(steps, opts) {
             }
         }
     }
-    return { appSchema: targetSchema, statements };
+    // 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
+    // each push is cheap and self-healing. Appended after every table/column step.
+    if (foreignKeys) {
+        for (const [key, def] of Object.entries(next.models)) {
+            if ((def.plane ?? 'tenant') === 'control')
+                continue;
+            const table = def.tableName ?? key;
+            const fk = foreignKeyStatements(table, def, next.models, qs);
+            statements.push(...fk.statements);
+            concurrent.push(...fk.concurrent);
+        }
+    }
+    return { appSchema: targetSchema, statements, concurrent };
 }

package/dist/schema/index.d.ts

@@ -24,6 +24,9 @@ export { z } from 'zod';
 export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
 export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.js';
+export { planeSchema, DEFAULT_PLANE, type SchemaPlane } from './plane.js';
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, type SyncDeltaCore, type DeltaAttribution, type DeltaProvenance, type SyncDeltaRow, type ParticipantKind, type ConfirmationState, type BackfillProvenance, } from './sync-delta-row.js';
+export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, type SyncDeltaAction, type WireDeltaData, type ParticipantRef, type SyncDeltaWireCore, type ClientSyncDelta, type ServerSyncDelta, } from './sync-delta-wire.js';
 export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
 export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
@@ -33,3 +36,4 @@ export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSna
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';
+export { schemaToOpenApi, type SchemaToOpenApiOptions } from './openapi.js';

package/dist/schema/index.js

@@ -28,6 +28,17 @@ export { field, indexed, getFieldMeta } from './field.js';
 export { relation } from './relation.js';
 // Tenancy — the single source of truth for how a model's rows are tenant-scoped.
 export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
+// Database plane — which DB a model's rows live in (`tenant` portable to a BYO
+// customer DB, `control` = Ablo's own). Sibling axis to `tenancy`.
+export { planeSchema, DEFAULT_PLANE } from './plane.js';
+// Decomposed sync-delta storage row (P0 of the control/tenant plane split —
+// see docs/plans/sync-delta-zod-decomposition.md). Describes the existing
+// `sync_deltas` columns as Zod schemas grouped by subsystem + database plane.
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_PLANES, } from './sync-delta-row.js';
+// Canonical WIRE delta contract — the broadcast (server→client) projection of
+// the stored row. The SDK client and the sync-server both derive their
+// `SyncDelta` type from these via `z.infer` so the contract cannot drift.
+export { syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './sync-delta-wire.js';
 // Model builder
 export { model, scopeKindOf, } from './model.js';
 // Intent-first shorthand: `mutable.lazy({...})` and friends. Read the
@@ -48,3 +59,4 @@ export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlocke
 export { generateTypes } from './generate.js';
 // Query definition DSL + type inference
 export { query, defineQueries, } from './queries.js';
+export { schemaToOpenApi } from './openapi.js';

package/dist/schema/model.d.ts

@@ -22,6 +22,7 @@ import type { EntityRole } from './roles.js';
 import { type FieldMeta } from './field.js';
 import { type Tenancy, type ScopedViaRef } from './tenancy.js';
 export type { ScopedViaRef, Tenancy } from './tenancy.js';
+import { type SchemaPlane } from './plane.js';
 /**
  * Controls when model data is loaded from the server.
  *
@@ -130,6 +131,13 @@ export interface ModelOptions {
      * directly only to author the union form explicitly.
      */
     tenancy?: Tenancy;
+    /**
+     * Which database plane this model's rows live in. `tenant` (default) =
+     * the tenant data plane, emitted into a customer's BYO/dedicated DB by
+     * provisioning. `control` = Ablo's control plane (sync log, attribution,
+     * audit) — never emitted into a customer DB. See `./plane.ts`.
+     */
+    plane?: SchemaPlane;
     /**
      * Marks this model as a **scope root** — a model that forms a sync group of
      * its own. A scope-root record lives in the group `<kind>:<id>`, where `kind`
@@ -321,6 +329,9 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     /** Canonical tenancy descriptor — the single source of truth, normalized from
      *  the `orgScoped`/`scopedVia`/`orgColumn` authoring sugar at build. */
     readonly tenancy: Tenancy;
+    /** Database plane — `tenant` (default) is portable to a customer DB; `control`
+     *  is Ablo-only. See {@link ModelOptions.plane} and `./plane.ts`. */
+    readonly plane?: SchemaPlane;
     /** Scope-root marker. See {@link ModelOptions.scope}. */
     readonly scope?: boolean | string;
     /** Membership edge granting identity → scope-root access. See {@link ModelOptions.grants}. */

package/dist/schema/model.js

@@ -22,6 +22,7 @@ import { getFieldMeta, inferFieldMetaFromZod } from './field.js';
 // re-exported so existing `import { ScopedViaRef } from './model'` call sites
 // keep resolving while consumers migrate.
 import { resolveTenancy } from './tenancy.js';
+import { DEFAULT_PLANE } from './plane.js';
 /** Normalize the `entityRoles` option (single | array | undefined) to an array. */
 function normalizeEntityRoles(input) {
     if (!input)
@@ -94,6 +95,7 @@ export function model(shape, relations, options) {
             scopedVia: options?.scopedVia,
             orgColumn: options?.orgColumn,
         }),
+        plane: options?.plane ?? DEFAULT_PLANE,
         scope: options?.scope,
         grants: options?.grants,
         entityRoles: normalizeEntityRoles(options?.entityRoles),

package/dist/schema/openapi.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `schemaToOpenApi(schema)` — generate an OpenAPI 3.1 spec FROM a pushed schema,
+ * so the API Reference reflects the customer's OWN models, not Ablo's.
+ *
+ * The API surface *is* the schema: a `task` model is what makes `/v1/models/task`
+ * exist. This walks `schema.models[*].fields` (the introspectable `FieldMeta`)
+ * and emits, per model, the CRUD + coordination routes the hosted API serves:
+ *   GET/POST   /v1/models/{model}
+ *   GET/PATCH/DELETE /v1/models/{model}/{id}
+ *   POST/DELETE      /v1/models/{model}/{id}/claim
+ *   POST            /v1/models/{model}/{id}/claim/reorder
+ * plus POST /v1/commits. Auth is a single Bearer scheme (the API key).
+ *
+ * Wire it into `ablo` codegen (e.g. `ablo openapi > openapi.json`) or serve it
+ * per-org; the output is a plain JSON-able object.
+ */
+import type { Schema, SchemaRecord } from './schema.js';
+export interface SchemaToOpenApiOptions {
+    /** Spec title. Default `"Ablo API"`. */
+    readonly title?: string;
+    /** Spec version. Default `"1.0.0"`. */
+    readonly version?: string;
+    /** API base URL. Default `"https://api.abloatai.com/api"`. */
+    readonly serverUrl?: string;
+}
+type Json = Record<string, unknown>;
+export declare function schemaToOpenApi<S extends SchemaRecord>(schema: Schema<S>, options?: SchemaToOpenApiOptions): Json;
+export {};

package/dist/schema/openapi.js

@@ -0,0 +1,118 @@
+function fieldSchema(f) {
+    switch (f.type) {
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+            return { type: 'string', format: 'date-time' };
+        case 'enum':
+            return f.enumValues ? { type: 'string', enum: [...f.enumValues] } : { type: 'string' };
+        case 'json':
+            return { type: 'object', additionalProperties: true };
+        case 'string':
+        default:
+            return { type: 'string' };
+    }
+}
+const pascal = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const idParam = () => ({ name: 'id', in: 'path', required: true, schema: { type: 'string' } });
+const jsonBody = (schema) => ({
+    required: true,
+    content: { 'application/json': { schema } },
+});
+const jsonResp = (description, schema) => ({
+    description,
+    content: { 'application/json': { schema } },
+});
+const commitReceipt = () => jsonResp('Commit receipt', {
+    type: 'object',
+    properties: {
+        object: { type: 'string', enum: ['commit_receipt'] },
+        clientTxId: { type: 'string' },
+        serverTxId: { type: 'string' },
+        success: { type: 'boolean' },
+        lastSyncId: { type: 'integer' },
+    },
+});
+export function schemaToOpenApi(schema, options = {}) {
+    const models = schema.models;
+    const paths = {};
+    const schemas = {};
+    for (const [key, def] of Object.entries(models)) {
+        const ref = { $ref: `#/components/schemas/${pascal(key)}` };
+        const properties = { id: { type: 'string' } };
+        const required = ['id'];
+        const createProps = {};
+        for (const [fname, fmeta] of Object.entries(def.fields)) {
+            const fs = fieldSchema(fmeta);
+            properties[fname] = fs;
+            createProps[fname] = fs;
+            if (!fmeta.isOptional)
+                required.push(fname);
+        }
+        schemas[pascal(key)] = { type: 'object', properties, required };
+        const createBody = jsonBody({ type: 'object', properties: createProps });
+        paths[`/v1/models/${key}`] = {
+            get: {
+                tags: [key],
+                summary: `List ${key}`,
+                parameters: [
+                    { name: 'limit', in: 'query', schema: { type: 'integer' } },
+                    { name: 'order_by', in: 'query', schema: { type: 'string' } },
+                    { name: 'order', in: 'query', schema: { type: 'string', enum: ['asc', 'desc'] } },
+                ],
+                responses: {
+                    '200': jsonResp('List of rows', {
+                        type: 'object',
+                        properties: { object: { type: 'string', enum: ['list'] }, data: { type: 'array', items: ref } },
+                    }),
+                },
+            },
+            post: { tags: [key], summary: `Create a ${key}`, requestBody: createBody, responses: { '200': commitReceipt() } },
+        };
+        paths[`/v1/models/${key}/{id}`] = {
+            get: {
+                tags: [key],
+                summary: `Retrieve a ${key}`,
+                parameters: [idParam()],
+                responses: {
+                    '200': jsonResp('The row', {
+                        type: 'object',
+                        properties: { data: ref, stamp: { type: 'integer' } },
+                    }),
+                },
+            },
+            patch: { tags: [key], summary: `Update a ${key}`, parameters: [idParam()], requestBody: createBody, responses: { '200': commitReceipt() } },
+            delete: { tags: [key], summary: `Delete a ${key}`, parameters: [idParam()], responses: { '200': commitReceipt() } },
+        };
+        paths[`/v1/models/${key}/{id}/claim`] = {
+            post: { tags: [key], summary: `Claim a ${key} (acquire lease)`, parameters: [idParam()], responses: { '200': jsonResp('Claim acquired', { type: 'object' }) } },
+            delete: { tags: [key], summary: `Release a ${key} claim`, parameters: [idParam()], responses: { '200': jsonResp('Released', { type: 'object' }) } },
+        };
+        paths[`/v1/models/${key}/{id}/claim/reorder`] = {
+            post: { tags: [key], summary: `Reorder the ${key} wait-line (privileged)`, parameters: [idParam()], responses: { '200': jsonResp('Reordered', { type: 'object' }) } },
+        };
+    }
+    paths['/v1/commits'] = {
+        post: { tags: ['commits'], summary: 'Commit a batch of operations atomically', responses: { '200': commitReceipt() } },
+    };
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: options.title ?? 'Ablo API',
+            version: options.version ?? '1.0.0',
+            description: 'Generated from your pushed Ablo schema — these routes are your models. ' +
+                'Authenticate every request with your API key as a Bearer token.',
+        },
+        servers: [{ url: options.serverUrl ?? 'https://api.abloatai.com/api' }],
+        security: [{ bearerAuth: [] }],
+        components: {
+            securitySchemes: {
+                bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_… / rk_…).' },
+            },
+            schemas,
+        },
+        paths,
+    };
+}

package/dist/schema/plane.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Database PLANE — which database a model's rows live in. A sibling axis to
+ * `tenancy` (which says how rows are isolated *within* a database):
+ *
+ *   - `tenant`  — the tenant data plane. For a BYO/dedicated customer this is
+ *                 THEIR database; provisioning emits these tables there.
+ *   - `control` — Ablo's control plane (the sync log, attribution, audit, …).
+ *                 Never emitted into a customer DB; lives only in Ablo's own DB.
+ *
+ * P1 of the sync-delta decomposition (`docs/plans/sync-delta-zod-decomposition.md`):
+ * declaring the boundary lets BYO provisioning *derive* "what a customer DB gets"
+ * (`plane === 'tenant'`) instead of hand-coding it. Defaults to `tenant` —
+ * today every `defineSchema` model is the customer's own data; only Ablo's
+ * internal tables (once modeled in P2) declare `control`.
+ */
+import { z } from 'zod';
+export declare const planeSchema: z.ZodEnum<{
+    tenant: "tenant";
+    control: "control";
+}>;
+export type SchemaPlane = z.infer<typeof planeSchema>;
+/** Default plane for a model that doesn't declare one — the tenant data plane. */
+export declare const DEFAULT_PLANE: SchemaPlane;

package/dist/schema/plane.js

@@ -0,0 +1,19 @@
+/**
+ * Database PLANE — which database a model's rows live in. A sibling axis to
+ * `tenancy` (which says how rows are isolated *within* a database):
+ *
+ *   - `tenant`  — the tenant data plane. For a BYO/dedicated customer this is
+ *                 THEIR database; provisioning emits these tables there.
+ *   - `control` — Ablo's control plane (the sync log, attribution, audit, …).
+ *                 Never emitted into a customer DB; lives only in Ablo's own DB.
+ *
+ * P1 of the sync-delta decomposition (`docs/plans/sync-delta-zod-decomposition.md`):
+ * declaring the boundary lets BYO provisioning *derive* "what a customer DB gets"
+ * (`plane === 'tenant'`) instead of hand-coding it. Defaults to `tenant` —
+ * today every `defineSchema` model is the customer's own data; only Ablo's
+ * internal tables (once modeled in P2) declare `control`.
+ */
+import { z } from 'zod';
+export const planeSchema = z.enum(['tenant', 'control']);
+/** Default plane for a model that doesn't declare one — the tenant data plane. */
+export const DEFAULT_PLANE = 'tenant';

package/dist/schema/relation.d.ts

@@ -79,6 +79,26 @@ export interface BelongsToOptions {
      * "the deck is the parent."
      */
     readonly parent?: boolean;
+    /**
+     * Emit a real Postgres FOREIGN KEY for this relation when provisioning a
+     * customer-owned (BYO / dedicated) database. **Independent of `parent`:**
+     * `parent` governs sync-group fan-out / visibility (control plane); `fk`
+     * governs physical referential integrity (data plane). The two are orthogonal
+     * — a relation may set either, both, or neither (mirrors Drizzle's
+     * `relations()` vs `references()` split; Zanzibar's `parent` is permission-only
+     * and "says nothing about data ownership or lifecycle").
+     *
+     * Set `fk: true` ONLY when the target row is co-located in the SAME database
+     * AND written in the SAME commit as this row, and the reference is to a
+     * strong / contained entity. Do NOT set it on provenance / template pointers
+     * (`sourceSlideId`, `templateId`), cross-tenant refs, or anything that may be
+     * written in a different transaction than its target — a hard FK there would
+     * reject the write and break out-of-order sync. Emitted as `DEFERRABLE
+     * INITIALLY DEFERRED, ON DELETE NO ACTION` — a pure integrity guard; cascade /
+     * nullify is owned by the app-layer mutation pipeline, not the DB. See
+     * `foreignKeyStatements` in `ddl.ts`.
+     */
+    readonly fk?: boolean;
 }
 declare const __relationType: unique symbol;
 declare const __relationTarget: unique symbol;

package/dist/schema/serialize.d.ts

@@ -26,6 +26,7 @@
  */
 import type { FieldMeta } from './field.js';
 import type { Tenancy } from './tenancy.js';
+import type { SchemaPlane } from './plane.js';
 import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule } from './model.js';
 import type { RelationType } from './relation.js';
 import { type Schema, type SchemaRecord, type IdentityRole, type EntityRole } from './schema.js';
@@ -51,6 +52,9 @@ export interface ModelJSON {
     readonly typename: string;
     readonly tableName?: string;
     readonly tenancy: Tenancy;
+    /** Database plane. Optional for back-compat: absent in artifacts written before
+     *  the plane axis → read as `tenant` (the default). See `./plane.ts`. */
+    readonly plane?: SchemaPlane;
     readonly scope?: boolean | string;
     readonly grants?: GrantsRef;
     readonly entityRoles?: readonly EntityRole[];

package/dist/schema/serialize.js

@@ -57,6 +57,7 @@ function modelToJSON(def) {
         typename: def.typename ?? '',
         tableName: def.tableName,
         tenancy: def.tenancy,
+        plane: def.plane,
         scope: def.scope,
         grants: def.grants,
         entityRoles: def.entityRoles,
@@ -161,6 +162,9 @@ function modelFromJSON(json) {
         persist: json.persist,
         tableName: json.tableName,
         tenancy: json.tenancy,
+        // Absent in pre-plane-axis artifacts → default `tenant` (matches the model
+        // builder default + the provisioning fallback), so the round-trip is stable.
+        plane: json.plane ?? 'tenant',
         scope: json.scope,
         grants: json.grants,
         entityRoles: json.entityRoles,