@abloatai/ablo 0.6.0 → 0.8.0

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 };
+}

package/dist/schema/diff.d.ts

@@ -50,8 +50,14 @@ export interface IndexChange {
     readonly from: boolean;
     readonly to: boolean;
 }
+/** Physical column-name transition for a stable logical field. */
+export interface FieldColumnChange {
+    readonly from: string;
+    readonly to: string;
+}
 /** The facets of a single column that changed (Atlas-style bitmask, as data). */
 export interface FieldChanges {
+    readonly column?: FieldColumnChange;
     readonly type?: FieldTypeChange;
     readonly nullability?: NullabilityChange;
     readonly enumValues?: EnumValuesChange;

package/dist/schema/diff.js

@@ -65,8 +65,19 @@ function diffEnumValues(from, to) {
         return undefined;
     return { added, removed };
 }
-function diffField(prev, next) {
+function camelToSnake(identifier) {
+    return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+function columnNameOf(fieldName, meta) {
+    return meta.column ?? camelToSnake(fieldName);
+}
+function diffField(prevFieldName, nextFieldName, prev, next) {
     const changes = {};
+    const prevColumn = columnNameOf(prevFieldName, prev);
+    const nextColumn = columnNameOf(nextFieldName, next);
+    if (prevColumn !== nextColumn) {
+        changes.column = { from: prevColumn, to: nextColumn };
+    }
     if (prev.type !== next.type) {
         changes.type = { from: prev.type, to: next.type, cast: classifyCast(prev.type, next.type) };
     }
@@ -112,9 +123,16 @@ function diffModelFields(model, prev, next, fieldRenames) {
         const prevMeta = prev.fields[prevName];
         if (!prevMeta)
             continue;
-        const changes = diffField(prevMeta, nextMeta);
-        if (changes)
+        const changes = diffField(prevName, name, prevMeta, nextMeta);
+        if (changes?.column && renameByNewName.has(name)) {
+            // A hinted logical field rename already emits `rename_field`, whose
+            // lowering renames the physical column when needed. Do not emit a
+            // second `alter_field.column` for the same transition.
+            delete changes.column;
+        }
+        if (changes && Object.keys(changes).length > 0) {
             steps.push({ kind: 'alter_field', model, field: name, changes });
+        }
     }
     // Dropped (present in prev, not in next, and not renamed away).
     for (const name of Object.keys(prev.fields)) {

package/dist/schema/field.d.ts

@@ -31,6 +31,11 @@ export interface FieldMeta {
     isOptional: boolean;
     /** Whether the field was marked indexed via `.indexed()`. */
     isIndexed: boolean;
+    /**
+     * Physical database column name override. When absent, SQL layers derive
+     * the column from the field name using the active casing convention.
+     */
+    column?: string;
     /** For enums: the allowed values. */
     enumValues?: readonly string[];
 }
@@ -73,27 +78,21 @@ export declare function inferFieldMetaFromZod(schema: z.ZodType): FieldMeta;
  * `model.ts:inferMetaFromZod`.
  */
 export declare function resolveFieldMeta(schema: z.ZodType): FieldMeta;
+export type FieldBuilder<T extends z.ZodType> = T & {
+    indexed(): FieldBuilder<T>;
+    from(column: string): FieldBuilder<T>;
+};
 export declare const field: {
     /** String field */
-    readonly string: () => z.ZodString & {
-        indexed(): z.ZodString;
-    };
+    readonly string: () => FieldBuilder<z.ZodString>;
     /** Number field */
-    readonly number: () => z.ZodNumber & {
-        indexed(): z.ZodNumber;
-    };
+    readonly number: () => FieldBuilder<z.ZodNumber>;
     /** Boolean field */
-    readonly boolean: () => z.ZodBoolean & {
-        indexed(): z.ZodBoolean;
-    };
+    readonly boolean: () => FieldBuilder<z.ZodBoolean>;
     /** Date field */
-    readonly date: () => z.ZodDate & {
-        indexed(): z.ZodDate;
-    };
+    readonly date: () => FieldBuilder<z.ZodDate>;
     /** Enum field with constrained string values */
-    readonly enum: <const T extends readonly [string, ...string[]]>(values: T) => z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never> & {
-        indexed(): z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never>;
-    };
+    readonly enum: <const T extends readonly [string, ...string[]]>(values: T) => FieldBuilder<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>;
     /**
      * JSON field. Three call shapes:
      *
@@ -124,11 +123,9 @@ export declare const field: {
      * deck.metadataJson.icon  // 'presentation' (typed, with default)
      * ```
      */
-    readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> & {
-        indexed(): z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    };
+    readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => FieldBuilder<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     /** Indexed string field (shorthand for `field.string().indexed()`). */
-    readonly id: () => z.ZodString;
+    readonly id: () => FieldBuilder<z.ZodString>;
 };
 /** Mark a Zod schema as indexed for fast lookups (function form). */
 export declare function indexed<T extends z.ZodType>(schema: T): T;

package/dist/schema/field.js

@@ -142,7 +142,15 @@ export function inferFieldMetaFromZod(schema) {
         current instanceof z.ZodArray ||
         current instanceof z.ZodRecord ||
         current instanceof z.ZodUnion ||
-        current instanceof z.ZodUnknown) {
+        current instanceof z.ZodUnknown ||
+        // `z.custom<T>()` is an opaque, structurally-uninspectable blob —
+        // by construction the engine can't see its shape, which is exactly
+        // the JSON-blob pattern (ProseMirror docs, LayerData/LayerStyle maps,
+        // chart specs). Classifying it as `'string'` (the fallthrough default)
+        // gave these fields deep MobX observability instead of the intended
+        // `observable.ref` (see Ablo.ts registerProperty), producing the
+        // microtask-storm + nested-reactivity-drift bug on live updates.
+        current instanceof z.ZodCustom) {
         type = 'json';
     }
     return { type, isOptional, isIndexed: false, enumValues };
@@ -169,39 +177,44 @@ export function resolveFieldMeta(schema) {
         return attached;
     return inferFieldMetaFromZod(schema);
 }
-// ── Chainable field builders ──────────────────────────────────────────────
-//
-// Each builder returns the underlying Zod schema (so `z.object(shape)` still
-// works) with `.indexed()` added as a chainable method. `.optional()` and
-// `.nullable()` still come from Zod itself and preserve the description.
-/** Add `.indexed()` to a Zod schema without disturbing its type. */
-function withIndexed(schema, baseMeta) {
-    const described = schema.describe(encodeMeta({ ...baseMeta, isIndexed: false }));
-    described.indexed = () => {
-        return schema.describe(encodeMeta({ ...baseMeta, isIndexed: true }));
+function assertColumnName(column) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(column)) {
+        throw new Error(`field.from(): invalid column identifier ${JSON.stringify(column)}`);
+    }
+}
+/** Add sync-engine chain methods to a Zod schema without disturbing its type. */
+function withFieldMethods(schema, meta) {
+    const described = schema.describe(encodeMeta(meta));
+    described.indexed = () => withFieldMethods(schema, { ...meta, isIndexed: true });
+    described.from = (column) => {
+        assertColumnName(column);
+        return withFieldMethods(schema, { ...meta, column });
     };
     return described;
 }
+function buildField(schema, baseMeta) {
+    return withFieldMethods(schema, { ...baseMeta, isIndexed: false });
+}
 export const field = {
     /** String field */
     string() {
-        return withIndexed(z.string(), { type: 'string' });
+        return buildField(z.string(), { type: 'string' });
     },
     /** Number field */
     number() {
-        return withIndexed(z.number(), { type: 'number' });
+        return buildField(z.number(), { type: 'number' });
     },
     /** Boolean field */
     boolean() {
-        return withIndexed(z.boolean(), { type: 'boolean' });
+        return buildField(z.boolean(), { type: 'boolean' });
     },
     /** Date field */
     date() {
-        return withIndexed(z.date(), { type: 'date' });
+        return buildField(z.date(), { type: 'date' });
     },
     /** Enum field with constrained string values */
     enum(values) {
-        return withIndexed(z.enum(values), { type: 'enum', enumValues: values });
+        return buildField(z.enum(values), { type: 'enum', enumValues: values });
     },
     /**
      * JSON field. Three call shapes:
@@ -245,7 +258,7 @@ export const field = {
             // Plain object shape → wrap in z.object() for the sub-property pattern
             inner = z.object(schemaOrShape);
         }
-        return withIndexed(inner, { type: 'json' });
+        return buildField(inner, { type: 'json' });
     },
     /** Indexed string field (shorthand for `field.string().indexed()`). */
     id() {

package/dist/schema/index.d.ts

@@ -21,12 +21,15 @@
  * ```
  */
 export { z } from 'zod';
-export { field, indexed, getFieldMeta, type FieldMeta } from './field.js';
+export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
-export { model, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, } from './model.js';
+export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.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, type IdentityRole, type IdentityContext, identityRole, extractIdentityIds, type IdentityRoleSource, } from './schema.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';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
-export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, 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 { selectModels } from './select.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+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';

package/dist/schema/index.js

@@ -26,17 +26,23 @@ export { z } from 'zod';
 export { field, indexed, getFieldMeta } from './field.js';
 // Relation builders
 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';
 // Model builder
-export { model, } from './model.js';
+export { model, scopeKindOf, } from './model.js';
 // Intent-first shorthand: `mutable.lazy({...})` and friends. Read the
 // safety posture and load shape off the verb tokens; everything else
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, identityRole, extractIdentityIds, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
-// Schema diff + migration planning (pure; SQL emission is server-side)
+// Schema projection — derive an app's subset from one canonical schema.
+export { selectModels } from './select.js';
+// Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, } from './ddl.js';
+// Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)
 export { generateTypes } from './generate.js';