@abloatai/ablo 0.24.0 → 0.26.0

package/dist/react/context.d.ts

@@ -1,123 +1,7 @@
 import { type ReactNode } from 'react';
-import type { Model } from '../Model.js';
-import type { ModelScope } from '../types/index.js';
-import type { QueryView, QueryViewOptions } from '../core/QueryView.js';
-import type { ViewRegistry } from '../core/ViewRegistry.js';
 import type { Schema } from '../schema/schema.js';
-import type { SyncStatus } from '../BaseSyncedStore.js';
-import type { ParticipantScope } from '../sync/participants.js';
-/**
- * A single LOCAL mutation as observed off the commit stream — the substrate
- * the undo system records from. One is emitted per local create/update/
- * delete/archive (remote/collaborator deltas never appear here: they apply
- * through a separate pool path that doesn't queue mutations). `previousData`
- * holds the pre-edit field values (captured from the model's
- * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
- * derivable from the event alone — no separate snapshot pass.
- *
- * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
- * doc and Liveblocks' `room.history` records room ops: undo listens to the
- * one place all local writes converge, rather than wrapping the write call.
- */
-export interface LocalMutation {
-    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
-    modelName: string;
-    modelId: string;
-    /** New field values (create/update). */
-    data?: Record<string, unknown> | null;
-    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
-    previousData?: Record<string, unknown> | null;
-}
-/**
- * Minimal store interface that the SDK hooks need.
- * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
- */
-export interface SyncStoreContract {
-    /**
-     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
-     * recording. Optional so minimal test doubles can omit it — when absent,
-     * undo scopes simply record nothing. The concrete store
-     * (`BaseSyncedStore`) wires this to the TransactionQueue's
-     * `transaction:created` event. Returns an unsubscribe function.
-     */
-    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
-    retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
-    queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
-        predicate?: (model: Model) => boolean;
-        scope?: ModelScope;
-        orderBy?: keyof Model;
-        order?: 'asc' | 'desc';
-        limit?: number;
-        offset?: number;
-    }): {
-        data: Model[];
-    };
-    /**
-     * Save (create or update) one entity. Calling `save` in a tight loop
-     * produces a single wire commit with one `batchIndex`: the SyncClient
-     * debounces IDB persistence and the server push to one microtask, and
-     * TransactionQueue coalesces every transaction staged in the tick into
-     * one batch. There is intentionally no `saveMany` — Zero, Replicache,
-     * and the rest of the local-first lineage all expose one-row writes
-     * and rely on the implicit tick boundary.
-     *
-     * `skipValidation` exists for trusted bulk paths (AI sandbox layer
-     * generation, PPTX import, hydration) where the producer has already
-     * type-checked and per-row Zod is a measurable cost.
-     */
-    save(model: Model, options?: {
-        skipValidation?: boolean;
-    }): Promise<void>;
-    delete(model: Model): Promise<void>;
-    archive(model: Model): Promise<void>;
-    unarchive(model: Model): Promise<void>;
-    /** The ObjectPool — for entity/collection lookups by ID or typename. */
-    pool: {
-        get(id: string): Model | undefined;
-        getByTypeName(typename: string, scope?: ModelScope): Model[];
-        getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
-        createFromData(data: Record<string, unknown>): Model | null;
-        hasForeignKeyIndex(typename: string, fieldName: string): boolean;
-        createView<T extends Record<string, unknown>>(typename: string, options?: QueryViewOptions<T>): QueryView<T>;
-        viewRegistry: ViewRegistry;
-    };
-    /**
-     * Reactive sync-status getters. Powered by MobX `computed` inside
-     * `BaseSyncedStore`, so they're safe to read in `observer` components
-     * and inside `reaction(() => store.isReady, ...)`. Consumers that
-     * don't want to touch MobX should prefer the `useSyncStatus()` hook.
-     */
-    readonly isReady: boolean;
-    readonly isSyncing: boolean;
-    readonly isOffline: boolean;
-    readonly isReconnecting: boolean;
-    readonly isError: boolean;
-    readonly hasUnsyncedChanges: boolean;
-    /**
-     * Area-of-interest (dynamic read subscription). `enterScope`/`leaveScope`
-     * move the connection's read interest as the user navigates (open/close a
-     * deck, sheet, doc); `pinScope`/`unpinScope` express prominence (an active
-     * claim keeps a group subscribed). Each resolves the scope through the same
-     * resolver the claim path uses, so read interest and write claims agree on
-     * the sync-group string. Optional so minimal test doubles can omit them;
-     * no-ops before the socket exists. The concrete store (`BaseSyncedStore`)
-     * forwards to its `AreaOfInterestManager`.
-     */
-    enterScope?(scope: ParticipantScope, opts?: {
-        hydrate?: boolean;
-    }): Promise<void>;
-    leaveScope?(scope: ParticipantScope): Promise<void>;
-    pinScope?(scope: ParticipantScope): Promise<void>;
-    unpinScope?(scope: ParticipantScope): Promise<void>;
-    /**
-     * Raw MobX-observable `SyncStatus` record. `useSyncStatus()` reads
-     * `state`, `progress`, `pendingChanges`, `isSessionError`, `error`
-     * from this to build its tagged union. Exposed on the contract so
-     * consumer-facing hooks and test doubles can manipulate it directly.
-     */
-    readonly syncStatus: SyncStatus;
-}
+import type { SyncStoreContract } from '../core/storeContract.js';
+export type { SyncStoreContract, LocalMutation } from '../core/storeContract.js';
 export interface SyncReactContext {
     store: SyncStoreContract;
     /** Current organization ID for default entity context */

package/dist/react/useAblo.js

@@ -58,7 +58,7 @@ export function useAblo(modelOrSelect, id, options) {
     useEffect(() => {
         if (!engine || id === undefined)
             return;
-        return engine.claims.onChange(() => setClaimVersion((version) => version + 1));
+        return engine.claims.onChange(() => { setClaimVersion((version) => version + 1); });
     }, [engine, id]);
     const selected = useReactive(() => {
         if (!engine || !isSelectorOnly || typeof modelOrSelect !== 'function') {

package/dist/react/useErrorListener.js

@@ -34,6 +34,6 @@ export function useErrorListener(listener) {
     const ref = useRef(listener);
     ref.current = listener;
     useEffect(() => {
-        return ctx.subscribeError((err) => ref.current(err));
+        return ctx.subscribeError((err) => { ref.current(err); });
     }, [ctx]);
 }

package/dist/react/useMutationFailureListener.js

@@ -33,6 +33,6 @@ export function useMutationFailureListener(listener) {
         const engine = ctx.engine;
         if (!engine)
             return;
-        return engine.onMutationFailure((payload) => ref.current(payload));
+        return engine.onMutationFailure((payload) => { ref.current(payload); });
     }, [ctx, ctx.engine]);
 }

package/dist/react/useMutators.js

@@ -30,7 +30,13 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                 continue;
             const invokers = {};
             for (const mutatorName of Object.keys(group)) {
-                const fn = group[mutatorName];
+                const maybeFn = group[mutatorName];
+                if (!maybeFn)
+                    continue;
+                // Bind the narrowed value: `noUncheckedIndexedAccess` types the indexed
+                // read as `Fn | undefined`, and that narrowing doesn't survive into the
+                // deferred invoker closures below — a non-optional local does.
+                const fn = maybeFn;
                 const label = `${String(modelKey)}.${mutatorName}`;
                 invokers[mutatorName] = async (args) => {
                     // Recording path: wrap the transaction so each write snapshots its

package/dist/react/useReactive.js

@@ -98,7 +98,6 @@ export function useReactive(compute, equals = defaultEquals) {
                 onChange();
             }
         });
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [subscribeVersion]);
     const getSnapshot = useCallback(() => snapshotRef.current.value, []);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);

package/dist/react/useUndoScope.js

@@ -30,7 +30,7 @@ function getManager(key, factory) {
 export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     const { store, organizationId, schema: ctxSchema } = useSyncContext();
     const isExplicit = typeof schemaOrName !== 'string';
-    const schema = isExplicit ? schemaOrName : ctxSchema;
+    const schema = isExplicit ? (schemaOrName) : ctxSchema;
     const name = isExplicit ? nameOrOptions : schemaOrName;
     const options = (isExplicit ? maybeOptions : nameOrOptions);
     if (!schema) {
@@ -58,7 +58,7 @@ export function useUndoScope(schemaOrName, nameOrOptions, maybeOptions) {
     // `canUndo`/`canRedo` go stale in every consumer that didn't itself call
     // undo/redo (e.g. a keyboard handler whose Cmd+Z gate then never fires).
     useEffect(() => {
-        return scope.onChange(() => setTick((t) => t + 1));
+        return scope.onChange(() => { setTick((t) => t + 1); });
     }, [scope]);
     const size = scope.size();
     return {

package/dist/schema/ddlLock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Safe-DDL LOCKING knobs — the ONE reader for how a schema change acquires
+ * (and retries for) table locks, shared by BOTH executors of the provision
+ * plan:
+ *
+ *   - `ablo migrate` (cli/migrate.ts) — the customer runs the DDL themselves
+ *   - the hosted executor (`apps/sync-server/src/schema/ddlExec.ts`)
+ *
+ * The two used to carry copy-pasted constants and had already drifted: the
+ * server honored `ABLO_SCHEMA_LOCK_ATTEMPTS` while the CLI hardcoded 5, so an
+ * operator tuning the knob got it applied by hosted push but silently ignored
+ * by `ablo migrate`. Both now resolve through here.
+ *
+ * The settings themselves are the battle-tested ones every mature migration
+ * tool uses (GitLab `with_lock_retries`, Strong Migrations, Doctolib
+ * `safe-pg-migrations`): a LOW `lock_timeout` so a blocked ALTER aborts fast
+ * instead of parking an ACCESS EXCLUSIVE request at the head of the lock
+ * queue (which would freeze every query on that table behind it), plus a
+ * bounded retry-with-backoff on the `55P03` abort.
+ *
+ * Env knobs (read at CALL time, not import time, so tests and long-lived
+ * processes see updates): `ABLO_SCHEMA_LOCK_TIMEOUT` / `ABLO_SCHEMA_LOCK_ATTEMPTS`
+ * — the older `ABLO_DDL_*` names are still honored so existing setups don't
+ * break.
+ */
+/** Postgres SQLSTATE `lock_not_available` — a `lock_timeout` abort. The ONE
+ *  retryable DDL failure; everything else is a real error. */
+export declare const PG_LOCK_NOT_AVAILABLE = "55P03";
+/** The env subset the resolvers read — injectable for tests. */
+export type DdlLockEnv = Readonly<Record<string, string | undefined>>;
+/** `lock_timeout` for the DDL transaction (a Postgres duration string). */
+export declare function resolveDdlLockTimeout(env?: DdlLockEnv): string;
+/** How many times the whole DDL transaction is attempted on `55P03` lock
+ *  contention. Always ≥ 1; a malformed value falls back to the default
+ *  instead of silently disabling retries. */
+export declare function resolveDdlMaxLockAttempts(env?: DdlLockEnv): number;
+/** Backoff before retry N (1-based): capped exponential + a little jitter so
+ *  two contending migrators don't re-collide in lockstep. */
+export declare function ddlLockRetryBackoffMs(attempt: number): number;

package/dist/schema/ddlLock.js

@@ -0,0 +1,51 @@
+/**
+ * Safe-DDL LOCKING knobs — the ONE reader for how a schema change acquires
+ * (and retries for) table locks, shared by BOTH executors of the provision
+ * plan:
+ *
+ *   - `ablo migrate` (cli/migrate.ts) — the customer runs the DDL themselves
+ *   - the hosted executor (`apps/sync-server/src/schema/ddlExec.ts`)
+ *
+ * The two used to carry copy-pasted constants and had already drifted: the
+ * server honored `ABLO_SCHEMA_LOCK_ATTEMPTS` while the CLI hardcoded 5, so an
+ * operator tuning the knob got it applied by hosted push but silently ignored
+ * by `ablo migrate`. Both now resolve through here.
+ *
+ * The settings themselves are the battle-tested ones every mature migration
+ * tool uses (GitLab `with_lock_retries`, Strong Migrations, Doctolib
+ * `safe-pg-migrations`): a LOW `lock_timeout` so a blocked ALTER aborts fast
+ * instead of parking an ACCESS EXCLUSIVE request at the head of the lock
+ * queue (which would freeze every query on that table behind it), plus a
+ * bounded retry-with-backoff on the `55P03` abort.
+ *
+ * Env knobs (read at CALL time, not import time, so tests and long-lived
+ * processes see updates): `ABLO_SCHEMA_LOCK_TIMEOUT` / `ABLO_SCHEMA_LOCK_ATTEMPTS`
+ * — the older `ABLO_DDL_*` names are still honored so existing setups don't
+ * break.
+ */
+/** Postgres SQLSTATE `lock_not_available` — a `lock_timeout` abort. The ONE
+ *  retryable DDL failure; everything else is a real error. */
+export const PG_LOCK_NOT_AVAILABLE = '55P03';
+const DEFAULT_LOCK_TIMEOUT = '5s';
+const DEFAULT_MAX_LOCK_ATTEMPTS = 5;
+/** `lock_timeout` for the DDL transaction (a Postgres duration string). */
+export function resolveDdlLockTimeout(env = process.env) {
+    return env.ABLO_SCHEMA_LOCK_TIMEOUT ?? env.ABLO_DDL_LOCK_TIMEOUT ?? DEFAULT_LOCK_TIMEOUT;
+}
+/** How many times the whole DDL transaction is attempted on `55P03` lock
+ *  contention. Always ≥ 1; a malformed value falls back to the default
+ *  instead of silently disabling retries. */
+export function resolveDdlMaxLockAttempts(env = process.env) {
+    const raw = env.ABLO_SCHEMA_LOCK_ATTEMPTS ?? env.ABLO_DDL_LOCK_ATTEMPTS;
+    if (raw === undefined)
+        return DEFAULT_MAX_LOCK_ATTEMPTS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_MAX_LOCK_ATTEMPTS;
+    return Math.max(1, Math.floor(parsed));
+}
+/** Backoff before retry N (1-based): capped exponential + a little jitter so
+ *  two contending migrators don't re-collide in lockstep. */
+export function ddlLockRetryBackoffMs(attempt) {
+    return Math.min(60_000, 10 * 2 ** attempt) + Math.floor(Math.random() * 50);
+}

package/dist/schema/field.js

@@ -42,7 +42,7 @@ function encodeMeta(meta) {
     return META_PREFIX + JSON.stringify(meta);
 }
 function decodeMeta(description) {
-    if (!description || !description.startsWith(META_PREFIX))
+    if (!description?.startsWith(META_PREFIX))
         return null;
     try {
         return JSON.parse(description.slice(META_PREFIX.length));

package/dist/schema/index.d.ts

@@ -24,16 +24,17 @@ 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, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type PolicyInput, } 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 { residencySchema, DEFAULT_RESIDENCY, type ModelResidency, planeSchema, DEFAULT_PLANE, type SchemaPlane, } from './residency.js';
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, 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, type ConflictAxis, } from './model.js';
 export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwrite, agentsReject, agentsNotify, systemOverwrite, systemReject, systemNotify, type ConflictRule, } from './coordination.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, 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, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type Model, 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, intersectRequestedWithAllowed, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
 export { selectModels } from './select.js';
 export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, snakeToCamel, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { PG_LOCK_NOT_AVAILABLE, resolveDdlLockTimeout, resolveDdlMaxLockAttempts, ddlLockRetryBackoffMs, type DdlLockEnv, } from './ddlLock.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

@@ -28,13 +28,19 @@ 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, policyInputSchema, resolvePolicy, 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';
+// Model residency — which DB a model's rows live in (`tenant` portable to a
+// customer's own DB, `control` = Ablo's own). Sibling axis to `tenancy`.
+// (Renamed from "plane" — that word is the server's tenancy scope.)
+export { residencySchema, DEFAULT_RESIDENCY, 
+// Deliberate back-compat re-export of the deprecated aliases:
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+planeSchema, 
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+DEFAULT_PLANE, } from './residency.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';
+export { syncDeltaCoreSchema, deltaAttributionSchema, deltaProvenanceSchema, syncDeltaRowSchema, participantKindSchema, confirmationStateSchema, backfillProvenanceSchema, DELTA_RESIDENCY, } 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.
@@ -49,13 +55,17 @@ export { coordination, humansOverwrite, humansReject, humansNotify, agentsOverwr
 // 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, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // 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, snakeToCamel, q, sqlType, } from './ddl.js';
+// Safe-DDL locking knobs (lock_timeout + bounded 55P03 retry) — the ONE
+// reader shared by `ablo migrate` and the hosted executor (ddlExec.ts), so an
+// operator tuning ABLO_SCHEMA_LOCK_* gets the same behavior on both paths.
+export { PG_LOCK_NOT_AVAILABLE, resolveDdlLockTimeout, resolveDdlMaxLockAttempts, ddlLockRetryBackoffMs, } from './ddlLock.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)

package/dist/schema/model.d.ts

@@ -22,7 +22,7 @@ import type { EntityRole, GroupsInput } from './roles.js';
 import { type FieldMeta } from './field.js';
 import { type Tenancy, type PolicyInput } from './tenancy.js';
 export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
-import { type SchemaPlane } from './plane.js';
+import { type ModelResidency } from './residency.js';
 import type { ConflictAxis } from '../policy/types.js';
 export type { ConflictAxis } from '../policy/types.js';
 /**
@@ -124,7 +124,7 @@ export interface ModelOptions {
      * provisioning. `control` = Ablo's control plane (sync log, attribution,
      * audit) — never emitted into a customer DB. See `./plane.ts`.
      */
-    plane?: SchemaPlane;
+    plane?: ModelResidency;
     /**
      * **Axis 2 — sync-group routing.** Decides which delta *channels* a row fans
      * into. Orthogonal to {@link policy} (read access). One namespaced object
@@ -318,7 +318,7 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     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;
+    readonly plane?: ModelResidency;
     /** 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

@@ -24,7 +24,7 @@ import { getFieldMeta, inferFieldMetaFromZod } from './field.js';
 // Postgres/Supabase RLS), normalized to the canonical `Tenancy` by
 // `resolvePolicy` at build time.
 import { resolvePolicy } from './tenancy.js';
-import { DEFAULT_PLANE } from './plane.js';
+import { DEFAULT_RESIDENCY } from './residency.js';
 /** Normalize the `entityRoles` option (single | array | undefined) to an array. */
 function normalizeEntityRoles(input) {
     if (!input)
@@ -93,7 +93,7 @@ export function model(shape, relations, options) {
         // Axis 1 — normalize the `policy` authoring option into the one canonical
         // tenancy descriptor (defaults to a row-local org column).
         tenancy: resolvePolicy(options?.policy),
-        plane: options?.plane ?? DEFAULT_PLANE,
+        plane: options?.plane ?? DEFAULT_RESIDENCY,
         // Axis 2 — unpack the `groups` routing namespace into the wire fields the
         // server reads (`scope`/`grants`/`entityRoles` on ModelDef/ModelJSON).
         scope: options?.groups?.root,

package/dist/schema/openapi.js

@@ -1,3 +1,7 @@
+// Dependency-free leaf (NOT client/auth.ts — that would pull the error
+// registry + credential policy into the schema subpath and close a
+// schema → client → errors → coordination → schema cycle).
+import { ABLO_HOSTED_HTTP_BASE_URL } from '../client/hostedEndpoints.js';
 function fieldSchema(f) {
     switch (f.type) {
         case 'number':
@@ -105,7 +109,7 @@ export function schemaToOpenApi(schema, options = {}) {
             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' }],
+        servers: [{ url: options.serverUrl ?? `${ABLO_HOSTED_HTTP_BASE_URL}/api` }],
         security: [{ bearerAuth: [] }],
         components: {
             securitySchemes: {

package/dist/schema/queries.d.ts

@@ -158,7 +158,7 @@ export type InferQueryInput<Q extends QueryDef> = z.infer<Q['input']>;
  * // Array<SlideLayer>
  * ```
  */
-export type InferQueryResult<S extends Schema, Q extends QueryDef> = Q extends QueryDef<z.ZodType, infer R> ? R extends InferModelNames<S> ? Array<InferModel<S, R>> : never : never;
+export type InferQueryResult<S extends Schema, Q extends QueryDef> = Q extends QueryDef<z.ZodType, infer R> ? R extends InferModelNames<S> ? InferModel<S, R>[] : never : never;
 /**
  * Define a typed query set against a schema.
  *

package/dist/schema/queries.js

@@ -56,6 +56,7 @@
  *    and lets the generic loader hydrate via a single
  *    `schema.models[queryDef.returns]` lookup.
  */
+import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 // ── query() factory ───────────────────────────────────────────────────────
 /**

package/dist/schema/residency.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Model RESIDENCY — 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 customer-connected database
+ *                 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.
+ *
+ * Named `residency` (not `plane`) because "plane" is the server's tenancy
+ * scope — (org, environment[, project, sandbox]) — the dominant meaning in the
+ * engine. The serialized model option is still the `plane` KEY (wire format,
+ * frozen until the next wire-version bump); only the TS vocabulary moved.
+ *
+ * P1 of the sync-delta decomposition (`docs/plans/sync-delta-zod-decomposition.md`):
+ * declaring the boundary lets provisioning *derive* "what a customer DB gets"
+ * (`residency === 'tenant'`) instead of hand-coding it. Defaults to `tenant`.
+ */
+import { z } from 'zod';
+export declare const residencySchema: z.ZodEnum<{
+    tenant: "tenant";
+    control: "control";
+}>;
+export type ModelResidency = z.infer<typeof residencySchema>;
+/** Default residency for a model that doesn't declare one — the tenant data plane. */
+export declare const DEFAULT_RESIDENCY: ModelResidency;
+/** @deprecated Use `residencySchema`. */
+export declare const planeSchema: z.ZodEnum<{
+    tenant: "tenant";
+    control: "control";
+}>;
+/** @deprecated Use `ModelResidency`. */
+export type SchemaPlane = ModelResidency;
+/** @deprecated Use `DEFAULT_RESIDENCY`. */
+export declare const DEFAULT_PLANE: "tenant";

package/dist/schema/residency.js

@@ -0,0 +1,27 @@
+/**
+ * Model RESIDENCY — 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 customer-connected database
+ *                 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.
+ *
+ * Named `residency` (not `plane`) because "plane" is the server's tenancy
+ * scope — (org, environment[, project, sandbox]) — the dominant meaning in the
+ * engine. The serialized model option is still the `plane` KEY (wire format,
+ * frozen until the next wire-version bump); only the TS vocabulary moved.
+ *
+ * P1 of the sync-delta decomposition (`docs/plans/sync-delta-zod-decomposition.md`):
+ * declaring the boundary lets provisioning *derive* "what a customer DB gets"
+ * (`residency === 'tenant'`) instead of hand-coding it. Defaults to `tenant`.
+ */
+import { z } from 'zod';
+export const residencySchema = z.enum(['tenant', 'control']);
+/** Default residency for a model that doesn't declare one — the tenant data plane. */
+export const DEFAULT_RESIDENCY = 'tenant';
+// ── Deprecated aliases (published schema subpath) ───────────────────────────
+/** @deprecated Use `residencySchema`. */
+export const planeSchema = residencySchema;
+/** @deprecated Use `DEFAULT_RESIDENCY`. */
+export const DEFAULT_PLANE = DEFAULT_RESIDENCY;

package/dist/schema/roles.d.ts

@@ -229,3 +229,28 @@ export declare function composeIdentitySyncGroups(identity: IdentityContext, sch
 export declare function composeEntitySyncGroups(record: EntityContext, def: {
     readonly entityRoles?: readonly EntityRole[];
 }): readonly SyncGroup[];
+/**
+ * Apply capability-style intersection to a client-requested sync-group
+ * set. Mirrors the cap-bearer path where Biscuit caveats narrow the
+ * client's requested set to what's actually authorized. Fully generic —
+ * it never inspects the group strings — so it lives here beside the
+ * composition helpers rather than in any product schema package
+ * (`@ablo/schema` re-exports it for compat).
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-
+ *     derived set (the default subscription scope for this participant).
+ *   - If the client requested a non-empty subset, intersect against the
+ *     identity-derived allowed set — drop any group the participant is
+ *     not authorized to subscribe to. Logs the dropped groups via the
+ *     optional `logDropped` callback for observability.
+ *   - If the intersection is empty after filtering, fall back to the
+ *     full allowed set rather than emit `[]` (which would degenerate to
+ *     the server-side `['default']` fallback and produce silent zero-
+ *     delta delivery).
+ */
+export declare function intersectRequestedWithAllowed(args: {
+    readonly requested: readonly string[];
+    readonly allowed: readonly string[];
+    readonly logDropped?: (dropped: readonly string[]) => void;
+}): readonly string[];

package/dist/schema/roles.js

@@ -197,3 +197,40 @@ export function composeEntitySyncGroups(record, def) {
     }
     return Array.from(out);
 }
+/**
+ * Apply capability-style intersection to a client-requested sync-group
+ * set. Mirrors the cap-bearer path where Biscuit caveats narrow the
+ * client's requested set to what's actually authorized. Fully generic —
+ * it never inspects the group strings — so it lives here beside the
+ * composition helpers rather than in any product schema package
+ * (`@ablo/schema` re-exports it for compat).
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-
+ *     derived set (the default subscription scope for this participant).
+ *   - If the client requested a non-empty subset, intersect against the
+ *     identity-derived allowed set — drop any group the participant is
+ *     not authorized to subscribe to. Logs the dropped groups via the
+ *     optional `logDropped` callback for observability.
+ *   - If the intersection is empty after filtering, fall back to the
+ *     full allowed set rather than emit `[]` (which would degenerate to
+ *     the server-side `['default']` fallback and produce silent zero-
+ *     delta delivery).
+ */
+export function intersectRequestedWithAllowed(args) {
+    const { requested, allowed, logDropped } = args;
+    if (requested.length === 0)
+        return allowed;
+    const allowedSet = new Set(allowed);
+    const accepted = [];
+    const dropped = [];
+    for (const g of requested) {
+        if (allowedSet.has(g))
+            accepted.push(g);
+        else
+            dropped.push(g);
+    }
+    if (dropped.length > 0 && logDropped)
+        logDropped(dropped);
+    return accepted.length > 0 ? accepted : allowed;
+}

package/dist/schema/schema.d.ts

@@ -23,7 +23,7 @@ import { z } from 'zod';
 import type { ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import type { IdentityRole } from './roles.js';
-export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
+export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
 /** The set of built-in casing conventions supported by `defineSchema`. */
 export type CasingConvention = 'snake_case' | 'camelCase';
 /** Plug point for custom conventions (e.g. mixed legacy databases). */
@@ -228,7 +228,7 @@ export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> =
  *
  * Matches Zero's `DeleteID<TableSchema>` from `zql/src/mutate/crud.ts`.
  */
-export type DeleteId<S extends Schema, ModelName extends keyof S['models']> = {
+export interface DeleteId<S extends Schema, ModelName extends keyof S['models']> {
     id: string;
-};
+}
 export declare function defineSchema<const S extends SchemaRecord>(models: S, options?: DefineSchemaOptions): Schema<S>;