@atscript/db 0.1.163 → 0.1.165

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { Ct as TEnsureTableOptions, Et as TExistingTableOption, G as TDbFieldMeta, Pt as TIndexChange, Tt as TExistingForeignKey, Vt as TReferencingForeignKey, at as TDbObjectKind, cr as TGenericLogger, gn as DbSpace, qt as TTableOptionDiff, xt as TDerivedChangeReason, zt as TPrimaryKeyChange } from "./buckets-B8UOod-v.cjs";
-import { S as snapshotToExistingTableOptions, _ as computeSchemaHash, a as hasForeignKeyChanges, b as computeViewSnapshot, d as TForeignKeySnapshot, f as TTableSnapshot, g as canonicalizeQueryNode, h as TViewSnapshot, i as fkKey, l as sameDefaultValue, m as TViewJoinSnapshot, n as computeForeignKeyDiff, o as TColumnDiffOptions, p as TViewColumnSnapshot, s as computeColumnDiff, t as TForeignKeyDiff, u as TFieldSnapshot, v as computeTableHash, x as snapshotToExistingColumns, y as computeTableSnapshot } from "./fk-diff-BNGawZi9.cjs";
+import { Bt as TPrimaryKeyChange, Ct as TEnsureTableOptions, Et as TExistingTableOption, G as TDbFieldMeta, Ht as TReferencingForeignKey, Jt as TTableOptionDiff, Pt as TIndexChange, Tt as TExistingForeignKey, at as TDbObjectKind, fr as TGenericLogger, xt as TDerivedChangeReason, yn as DbSpace } from "./buckets-BDxKfCNo.cjs";
+import { S as snapshotToExistingTableOptions, _ as computeSchemaHash, a as hasForeignKeyChanges, b as computeViewSnapshot, d as TForeignKeySnapshot, f as TTableSnapshot, g as canonicalizeQueryNode, h as TViewSnapshot, i as fkKey, l as sameDefaultValue, m as TViewJoinSnapshot, n as computeForeignKeyDiff, o as TColumnDiffOptions, p as TViewColumnSnapshot, s as computeColumnDiff, t as TForeignKeyDiff, u as TFieldSnapshot, v as computeTableHash, x as snapshotToExistingColumns, y as computeTableSnapshot } from "./fk-diff-DSM7O7hs.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -329,6 +329,27 @@ interface TSyncPlan {
   status: "up-to-date" | "changes-needed";
   schemaHash: string;
   entries: SyncEntry[];
+  /**
+   * Ids of the `dataSteps` passed to `planSchema` that have not run yet
+   * (since 0.1.165); a pending step makes the plan `"changes-needed"`.
+   * Absent when no steps were passed.
+   */
+  pendingDataSteps?: string[];
+}
+/**
+ * A one-time data step of {@link TSyncOptions.dataSteps} (since 0.1.165) —
+ * a backfill or data fix that must run exactly once per database, after the
+ * schema change it needs.
+ */
+interface TDataStep {
+  /** Stable, unique id — the step is recorded under it (`data_step:<id>` in `__atscript_control`). */
+  id: string;
+  /**
+   * The step's work. Runs in its own transaction (on adapters with
+   * transactions), the record of the step committed in the same one: a step
+   * that throws is rolled back, not recorded, and runs again on the next sync.
+   */
+  run(space: DbSpace): Promise<void> | void;
 }
 interface TSyncOptions {
   /** Pod/instance identifier for distributed locking. Default: random UUID. */
@@ -365,6 +386,15 @@ interface TSyncOptions {
    * - `"silent"` — legacy behavior: outcome is only observable on the result.
    */
   onError?: "throw" | "warn" | "silent";
+  /**
+   * One-time data steps (since 0.1.165), run in order after the schema DDL,
+   * under the sync lock — also when the schema itself is up to date. Each
+   * step runs once per database: once it committed, its id is recorded and
+   * later syncs skip it. A step that throws stops the run (the error is
+   * rethrown after the lock is released); the steps after it stay pending.
+   * Steps do not run when the sync is refused or an entry errored.
+   */
+  dataSteps?: readonly TDataStep[];
 }
 interface TSyncResult {
   /**
@@ -379,6 +409,15 @@ interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer" | "refused";
   schemaHash: string;
   entries: SyncEntry[];
+  /**
+   * The {@link TSyncOptions.dataSteps} this call ran, and those still pending
+   * (a refused or errored run leaves them all pending). Absent when no steps
+   * were passed. @since 0.1.165
+   */
+  dataSteps?: {
+    ran: string[];
+    pending: string[];
+  };
 }
 declare class SchemaSync {
   private readonly space;
@@ -413,7 +452,8 @@ declare class SchemaSync {
   /**
    * Acquires the sync lock, waiting for a peer that holds it. Resolves
    * `"acquired"`, or `"synced-by-peer"` when a non-forced run finds, after a
-   * wait, that the peer stored this schema's hash. A forced run never
+   * wait, that the peer stored this schema's hash (and `peerDone` agrees —
+   * no data step left pending). A forced run never
    * short-circuits — it waits its turn and runs. Losing the race for a freed
    * lock to another waiter just waits again, within the same `waitTimeoutMs`.
    */
@@ -425,6 +465,13 @@ declare class SchemaSync {
    * logged (the row expires after `lockTtlMs`, blocking peers until then).
    */
   private releaseLock;
+  /** Ids of the steps not recorded yet, in order. */
+  private pendingDataSteps;
+  /**
+   * Runs the pending steps in order, each with its record in one transaction.
+   * A throwing step propagates (rolled back, not recorded). Returns the ids run.
+   */
+  private runDataSteps;
   /**
    * Runs schema synchronization with distributed locking, in three phases:
    *
@@ -498,7 +545,7 @@ declare class SchemaSync {
    * any DDL. Entries come back in execution order; pre-flight refusals appear
    * as `error` entries (`refused: true`) exactly as `run()` would report them.
    */
-  plan(types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
+  plan(types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe" | "dataSteps">): Promise<TSyncPlan>;
   /** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
   private resolveTypeMapper;
   /**
@@ -600,6 +647,6 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  * Note: reading the stored baseline still requires a live DB connection (the
  * snapshot lives in the `__atscript_control` table).
  */
-declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
+declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe" | "dataSteps">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TColumnDiffOptions, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncDerivedChange, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, sameDefaultValue, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, type TColumnDiffOptions, type TDataStep, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncDerivedChange, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, sameDefaultValue, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { Ct as TEnsureTableOptions, Et as TExistingTableOption, G as TDbFieldMeta, Pt as TIndexChange, Tt as TExistingForeignKey, Vt as TReferencingForeignKey, at as TDbObjectKind, cr as TGenericLogger, gn as DbSpace, qt as TTableOptionDiff, xt as TDerivedChangeReason, zt as TPrimaryKeyChange } from "./buckets-CHyspjYP.mjs";
-import { S as snapshotToExistingTableOptions, _ as computeSchemaHash, a as hasForeignKeyChanges, b as computeViewSnapshot, d as TForeignKeySnapshot, f as TTableSnapshot, g as canonicalizeQueryNode, h as TViewSnapshot, i as fkKey, l as sameDefaultValue, m as TViewJoinSnapshot, n as computeForeignKeyDiff, o as TColumnDiffOptions, p as TViewColumnSnapshot, s as computeColumnDiff, t as TForeignKeyDiff, u as TFieldSnapshot, v as computeTableHash, x as snapshotToExistingColumns, y as computeTableSnapshot } from "./fk-diff-rj9N2QLw.mjs";
+import { Bt as TPrimaryKeyChange, Ct as TEnsureTableOptions, Et as TExistingTableOption, G as TDbFieldMeta, Ht as TReferencingForeignKey, Jt as TTableOptionDiff, Pt as TIndexChange, Tt as TExistingForeignKey, at as TDbObjectKind, fr as TGenericLogger, xt as TDerivedChangeReason, yn as DbSpace } from "./buckets-CHUgky8T.mjs";
+import { S as snapshotToExistingTableOptions, _ as computeSchemaHash, a as hasForeignKeyChanges, b as computeViewSnapshot, d as TForeignKeySnapshot, f as TTableSnapshot, g as canonicalizeQueryNode, h as TViewSnapshot, i as fkKey, l as sameDefaultValue, m as TViewJoinSnapshot, n as computeForeignKeyDiff, o as TColumnDiffOptions, p as TViewColumnSnapshot, s as computeColumnDiff, t as TForeignKeyDiff, u as TFieldSnapshot, v as computeTableHash, x as snapshotToExistingColumns, y as computeTableSnapshot } from "./fk-diff-Dapr5Dk-.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -329,6 +329,27 @@ interface TSyncPlan {
   status: "up-to-date" | "changes-needed";
   schemaHash: string;
   entries: SyncEntry[];
+  /**
+   * Ids of the `dataSteps` passed to `planSchema` that have not run yet
+   * (since 0.1.165); a pending step makes the plan `"changes-needed"`.
+   * Absent when no steps were passed.
+   */
+  pendingDataSteps?: string[];
+}
+/**
+ * A one-time data step of {@link TSyncOptions.dataSteps} (since 0.1.165) —
+ * a backfill or data fix that must run exactly once per database, after the
+ * schema change it needs.
+ */
+interface TDataStep {
+  /** Stable, unique id — the step is recorded under it (`data_step:<id>` in `__atscript_control`). */
+  id: string;
+  /**
+   * The step's work. Runs in its own transaction (on adapters with
+   * transactions), the record of the step committed in the same one: a step
+   * that throws is rolled back, not recorded, and runs again on the next sync.
+   */
+  run(space: DbSpace): Promise<void> | void;
 }
 interface TSyncOptions {
   /** Pod/instance identifier for distributed locking. Default: random UUID. */
@@ -365,6 +386,15 @@ interface TSyncOptions {
    * - `"silent"` — legacy behavior: outcome is only observable on the result.
    */
   onError?: "throw" | "warn" | "silent";
+  /**
+   * One-time data steps (since 0.1.165), run in order after the schema DDL,
+   * under the sync lock — also when the schema itself is up to date. Each
+   * step runs once per database: once it committed, its id is recorded and
+   * later syncs skip it. A step that throws stops the run (the error is
+   * rethrown after the lock is released); the steps after it stay pending.
+   * Steps do not run when the sync is refused or an entry errored.
+   */
+  dataSteps?: readonly TDataStep[];
 }
 interface TSyncResult {
   /**
@@ -379,6 +409,15 @@ interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer" | "refused";
   schemaHash: string;
   entries: SyncEntry[];
+  /**
+   * The {@link TSyncOptions.dataSteps} this call ran, and those still pending
+   * (a refused or errored run leaves them all pending). Absent when no steps
+   * were passed. @since 0.1.165
+   */
+  dataSteps?: {
+    ran: string[];
+    pending: string[];
+  };
 }
 declare class SchemaSync {
   private readonly space;
@@ -413,7 +452,8 @@ declare class SchemaSync {
   /**
    * Acquires the sync lock, waiting for a peer that holds it. Resolves
    * `"acquired"`, or `"synced-by-peer"` when a non-forced run finds, after a
-   * wait, that the peer stored this schema's hash. A forced run never
+   * wait, that the peer stored this schema's hash (and `peerDone` agrees —
+   * no data step left pending). A forced run never
    * short-circuits — it waits its turn and runs. Losing the race for a freed
    * lock to another waiter just waits again, within the same `waitTimeoutMs`.
    */
@@ -425,6 +465,13 @@ declare class SchemaSync {
    * logged (the row expires after `lockTtlMs`, blocking peers until then).
    */
   private releaseLock;
+  /** Ids of the steps not recorded yet, in order. */
+  private pendingDataSteps;
+  /**
+   * Runs the pending steps in order, each with its record in one transaction.
+   * A throwing step propagates (rolled back, not recorded). Returns the ids run.
+   */
+  private runDataSteps;
   /**
    * Runs schema synchronization with distributed locking, in three phases:
    *
@@ -498,7 +545,7 @@ declare class SchemaSync {
    * any DDL. Entries come back in execution order; pre-flight refusals appear
    * as `error` entries (`refused: true`) exactly as `run()` would report them.
    */
-  plan(types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
+  plan(types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe" | "dataSteps">): Promise<TSyncPlan>;
   /** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
   private resolveTypeMapper;
   /**
@@ -600,6 +647,6 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  * Note: reading the stored baseline still requires a live DB connection (the
  * snapshot lives in the `__atscript_control` table).
  */
-declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
+declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe" | "dataSteps">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TColumnDiffOptions, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncDerivedChange, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, sameDefaultValue, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, type TColumnDiffOptions, type TDataStep, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, type TSyncDerivedChange, type TSyncEntryInit, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TSyncSkippedWork, type TTableSnapshot, type TViewColumnSnapshot, type TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, sameDefaultValue, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/sync.mjs

@@ -1,6 +1,6 @@
-import { r as DbError } from "./db-error-hraC12B9.mjs";
-import { A as hasForeignKeyChanges, D as computeForeignKeyDiff, O as fkColumns, P as resolveDesignType, St as NoopLogger, a as computeSchemaHash, c as computeViewSnapshot, d as snapshotToExistingTableOptions, f as viewSnapshotSources, gt as aliasTargetOf, ht as relationalColumnName, i as canonicalizeQueryNode, k as fkKey, l as serializeDefaultValue, o as computeTableHash, r as sameDefaultValue, s as computeTableSnapshot, t as computeColumnDiff, u as snapshotToExistingColumns } from "./column-diff-BfNIlMwX.mjs";
-import { f as unionValueMembers } from "./validator-DuDWsIdQ.mjs";
+import { A as fkKey, F as resolveDesignType, O as computeForeignKeyDiff, _t as relationalColumnName, a as computeSchemaHash, c as computeViewSnapshot, d as snapshotToExistingTableOptions, f as viewSnapshotSources, i as canonicalizeQueryNode, j as hasForeignKeyChanges, k as fkColumns, l as serializeDefaultValue, o as computeTableHash, r as sameDefaultValue, s as computeTableSnapshot, t as computeColumnDiff, u as snapshotToExistingColumns, vt as aliasTargetOf, wt as NoopLogger } from "./column-diff-9pF0d8JP.mjs";
+import { r as DbError } from "./db-error-BMy4-OWq.mjs";
+import { f as unionValueMembers } from "./validator-UpgPhwvH.mjs";
 //#region src/schema/json-column-copy.ts
 const NONE = {
 	copies: [],
@@ -322,11 +322,28 @@ var SyncStore = class {
 	}
 	async ensureControlTable() {
 		if (!this.controlTable) {
-			const { AtscriptControl } = await import("./control-D5cQmzFj.mjs");
+			const { AtscriptControl } = await import("./control-CevYIJC4.mjs");
 			this.controlTable = this.space.getTable(AtscriptControl);
 		}
 		await this.controlTable.ensureTable();
 	}
+	/**
+	* Runs `fn` in a transaction of the control table's adapter family — the
+	* space's tables on the same driver join it (since 0.1.165, data steps).
+	*/
+	async inTransaction(fn) {
+		const { AtscriptControl } = await import("./control-CevYIJC4.mjs");
+		return this.space.getAdapter(AtscriptControl).withTransaction(fn);
+	}
+	/** Which of `ids` have a control row — one query (since 0.1.165, data steps). */
+	async presentControlIds(ids) {
+		if (ids.length === 0) return /* @__PURE__ */ new Set();
+		const rows = await this.controlTable.findMany({
+			filter: { _id: { $in: [...ids] } },
+			controls: { $select: ["_id"] }
+		});
+		return new Set(rows.map((r) => r._id));
+	}
 	async readControlValue(_id) {
 		return (await this.controlTable.findOne({
 			filter: { _id: { $eq: _id } },
@@ -494,7 +511,7 @@ function isExpired(lock, now) {
 	return expiresAt > 0 && expiresAt < now;
 }
 async function readStoredSnapshot(space, tableName, _asView) {
-	const { AtscriptControl } = await import("./control-D5cQmzFj.mjs");
+	const { AtscriptControl } = await import("./control-CevYIJC4.mjs");
 	const table = space.getTable(AtscriptControl);
 	await table.ensureTable();
 	const value = (await table.findOne({
@@ -1570,6 +1587,33 @@ function removedBlockers(t, removedTables, removedTableSet, dropEdges) {
 	} else for (const r of removedTables) if (r.snapshot && "foreignKeys" in r.snapshot && r.snapshot.foreignKeys.some((fk) => fk.targetTable === t.dbName)) direct.push(r.name);
 	return reachable(direct, dropEdges);
 }
+/** The `__atscript_control` key a data step is recorded under. */
+function dataStepKey(id) {
+	return `data_step:${id}`;
+}
+/** The steps as given, after checking their ids are non-empty and unique. */
+function checkDataSteps(steps) {
+	if (!steps?.length) return [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const step of steps) {
+		if (typeof step.id !== "string" || step.id === "") throw new Error("syncSchema: every data step needs a non-empty id");
+		if (seen.has(step.id)) throw new Error(`syncSchema: duplicate data step id "${step.id}"`);
+		seen.add(step.id);
+	}
+	return steps;
+}
+/** `result` with its `dataSteps` report — unchanged when no steps were passed. */
+function withSteps(result, steps, ran) {
+	if (steps.length === 0) return result;
+	const done = new Set(ran);
+	return {
+		...result,
+		dataSteps: {
+			ran: [...ran],
+			pending: steps.map((s) => s.id).filter((id) => !done.has(id))
+		}
+	};
+}
 var SchemaSync = class {
 	space;
 	store;
@@ -1587,7 +1631,7 @@ var SchemaSync = class {
 		const tables = [];
 		const views = [];
 		const externalViews = [];
-		for (const type of types) {
+		for (const type of new Set(types)) {
 			if (aliasTargetOf(type)) continue;
 			const readable = this.space.get(type);
 			if (readable.isView) {
@@ -1715,7 +1759,8 @@ var SchemaSync = class {
 	/**
 	* Acquires the sync lock, waiting for a peer that holds it. Resolves
 	* `"acquired"`, or `"synced-by-peer"` when a non-forced run finds, after a
-	* wait, that the peer stored this schema's hash. A forced run never
+	* wait, that the peer stored this schema's hash (and `peerDone` agrees —
+	* no data step left pending). A forced run never
 	* short-circuits — it waits its turn and runs. Losing the race for a freed
 	* lock to another waiter just waits again, within the same `waitTimeoutMs`.
 	*/
@@ -1723,7 +1768,7 @@ var SchemaSync = class {
 		const deadline = Date.now() + opts.waitTimeoutMs;
 		while (!await this.store.tryAcquireLock(podId, opts.lockTtlMs)) {
 			if (!await this.store.waitForLock(deadline - Date.now(), opts.pollIntervalMs)) throw new Error(`Schema sync lock wait timed out after ${opts.waitTimeoutMs}ms`);
-			if (!opts.force && await this.store.readHash() === hash) return "synced-by-peer";
+			if (!opts.force && await this.store.readHash() === hash && (!opts.peerDone || await opts.peerDone())) return "synced-by-peer";
 		}
 		return "acquired";
 	}
@@ -1743,6 +1788,30 @@ var SchemaSync = class {
 			this.logger.warn("[schema-sync] Failed to release the sync lock — peers wait until it expires:", error instanceof Error ? error.message : error);
 		}
 	}
+	/** Ids of the steps not recorded yet, in order. */
+	async pendingDataSteps(steps) {
+		const done = await this.store.presentControlIds(steps.map((step) => dataStepKey(step.id)));
+		return steps.filter((step) => !done.has(dataStepKey(step.id))).map((step) => step.id);
+	}
+	/**
+	* Runs the pending steps in order, each with its record in one transaction.
+	* A throwing step propagates (rolled back, not recorded). Returns the ids run.
+	*/
+	async runDataSteps(steps, getAbortReason) {
+		const ran = [];
+		const pending = new Set(await this.pendingDataSteps(steps));
+		for (const step of steps) {
+			if (!pending.has(step.id)) continue;
+			this.assertLockHeld(getAbortReason);
+			await this.store.inTransaction(async () => {
+				await step.run(this.space);
+				await this.store.writeControlValue(dataStepKey(step.id), JSON.stringify({ ranAt: Date.now() }));
+			});
+			this.logger.info?.(`[schema-sync] data step "${step.id}" applied`);
+			ran.push(step.id);
+		}
+		return ran;
+	}
 	/**
 	* Runs schema synchronization with distributed locking, in three phases:
 	*
@@ -1767,21 +1836,25 @@ var SchemaSync = class {
 		const force = opts?.force ?? false;
 		const safe = opts?.safe ?? false;
 		const onError = opts?.onError ?? "warn";
+		const steps = checkDataSteps(opts?.dataSteps);
 		const resolved = await this.resolveAndHash(types);
 		const { hash } = resolved;
 		await this.store.ensureControlTable();
 		if (!force) {
-			if (await this.store.readHash() === hash) return {
-				status: "up-to-date",
-				schemaHash: hash,
-				entries: []
-			};
+			if (await this.store.readHash() === hash) {
+				if ((await this.pendingDataSteps(steps)).length === 0) return withSteps({
+					status: "up-to-date",
+					schemaHash: hash,
+					entries: []
+				}, steps, []);
+			}
 		}
 		if (await this.acquireLock(podId, hash, {
 			lockTtlMs,
 			waitTimeoutMs,
 			pollIntervalMs,
-			force
+			force,
+			peerDone: async () => (await this.pendingDataSteps(steps)).length === 0
 		}) === "synced-by-peer") return {
 			status: "synced-by-peer",
 			schemaHash: hash,
@@ -1790,11 +1863,14 @@ var SchemaSync = class {
 		const heartbeat = this.startHeartbeat(podId, lockTtlMs);
 		try {
 			if (!force) {
-				if (await this.store.readHash() === hash) return {
-					status: "synced-by-peer",
-					schemaHash: hash,
-					entries: []
-				};
+				if (await this.store.readHash() === hash) {
+					const ran = await this.runDataSteps(steps, heartbeat.getAbortReason);
+					return withSteps({
+						status: ran.length > 0 ? "synced" : "synced-by-peer",
+						schemaHash: hash,
+						entries: []
+					}, steps, ran);
+				}
 			}
 			const d = await this.discover(resolved, safe);
 			this.assertLockHeld(heartbeat.getAbortReason);
@@ -1807,11 +1883,11 @@ var SchemaSync = class {
 					entries: this.buildPlanEntries(d, safe, refusals)
 				};
 				this.reportOutcome(result, onError);
-				return result;
+				return withSteps(result, steps, []);
 			}
 			const result = await this.execute(d, safe, heartbeat.getAbortReason);
 			this.reportOutcome(result, onError);
-			return result;
+			return withSteps(result, steps, result.entries.some((e) => e.status === "error") ? [] : await this.runDataSteps(steps, heartbeat.getAbortReason));
 		} finally {
 			await heartbeat.stop();
 			await this.releaseLock(podId);
@@ -2436,6 +2512,7 @@ var SchemaSync = class {
 	* as `error` entries (`refused: true`) exactly as `run()` would report them.
 	*/
 	async plan(types, opts) {
+		const steps = checkDataSteps(opts?.dataSteps);
 		const force = opts?.force ?? false;
 		const safe = opts?.safe ?? false;
 		const resolved = await this.resolveAndHash(types);
@@ -2445,18 +2522,23 @@ var SchemaSync = class {
 		const refusals = this.preflight(d, safe);
 		await this.planLiveWork(d, safe);
 		const entries = this.buildPlanEntries(d, safe, refusals);
+		const pending = steps.length > 0 ? await this.pendingDataSteps(steps) : void 0;
+		const withPending = (plan) => pending ? {
+			...plan,
+			pendingDataSteps: pending
+		} : plan;
 		if (!force) {
-			if (await this.store.readHash() === hash) return {
+			if (await this.store.readHash() === hash && !pending?.length) return withPending({
 				status: "up-to-date",
 				schemaHash: hash,
 				entries
-			};
+			});
 		}
-		return {
+		return withPending({
 			status: "changes-needed",
 			schemaHash: hash,
 			entries
-		};
+		});
 	}
 	/** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
 	resolveTypeMapper(adapter) {

package/dist/{validator-DK9Ijpo7.cjs → validator-D7E7T0Oy.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DmF1_xrz.cjs");
+const require_db_error = require("./db-error-G3sgvL87.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/shared/union-shape.ts

package/dist/{validator-DuDWsIdQ.mjs → validator-UpgPhwvH.mjs}

@@ -1,4 +1,4 @@
-import { i as DepthLimitExceededError } from "./db-error-hraC12B9.mjs";
+import { i as DepthLimitExceededError } from "./db-error-BMy4-OWq.mjs";
 import { getDbFieldOp } from "./ops.mjs";
 import { createAnnotatedTypeNode, flattenAnnotatedType } from "@atscript/typescript/utils";
 //#region src/shared/union-shape.ts

package/dist/validator.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DmF1_xrz.cjs");
-const require_validator = require("./validator-DK9Ijpo7.cjs");
+const require_db_error = require("./db-error-G3sgvL87.cjs");
+const require_validator = require("./validator-D7E7T0Oy.cjs");
 const require_server_stamped = require("./server-stamped-B6XbUQ4p.cjs");
 const require_object = require("./object-GjsuPNqo.cjs");
 const require_ops = require("./ops.cjs");

package/dist/validator.d.cts

@@ -1,4 +1,4 @@
-import { r as DbError } from "./db-error-B_DRL1E9.cjs";
+import { r as DbError } from "./db-error-DQUw2cED.cjs";
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
 import { a as isPlainObject, i as isEmptyObject } from "./object-Czia_qD4.cjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.cjs";

package/dist/validator.d.mts

@@ -1,4 +1,4 @@
-import { r as DbError } from "./db-error-B_DRL1E9.mjs";
+import { r as DbError } from "./db-error-DQUw2cED.mjs";
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
 import { a as isPlainObject, i as isEmptyObject } from "./object-Czia_qD4.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.mjs";

package/dist/validator.mjs

@@ -1,5 +1,5 @@
-import { r as DbError } from "./db-error-hraC12B9.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-DuDWsIdQ.mjs";
+import { r as DbError } from "./db-error-BMy4-OWq.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-UpgPhwvH.mjs";
 import { n as isServerStampedOnUpdate, t as SERVER_STAMPED_ON_UPDATE_KEYS } from "./server-stamped-BoP56K9M.mjs";
 import { a as isPlainObject, i as isEmptyObject } from "./object-PQ1J8jri.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, isDbFieldOp, reconcileCas, separateCas } from "./ops.mjs";

package/dist/{view-validation-BiDLCYMw.cjs → view-validation-C0UVLx_H.cjs}

@@ -1,4 +1,4 @@
-const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CNtrSxGH.cjs");
 const require_search_fields = require("./search-fields-B49-RCWd.cjs");
 let _atscript_core = require("@atscript/core");
 //#region src/shared/annotation-utils.ts
@@ -62,17 +62,21 @@ function primitiveBaseType(def) {
 	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
 }
 /**
+* `null` in a type expression: the `null` reference or the `null` primitive
+* (whose `config.type` is `"null"`).
+*/
+function isNullMember(node) {
+	return (0, _atscript_core.isRef)(node) && !node.hasChain && node.id === "null" || primitiveBaseType(node) === "null";
+}
+/**
 * Whether a definition is a union with a `null` member — `T | null`, or a
 * ref to an alias of one (compile-time mirror of the runtime nullable union,
 * since 0.1.155).
 */
 function isNullableUnion(def, doc, depth = 0) {
 	if (!def || depth > 8) return false;
-	if ((0, _atscript_core.isRef)(def)) {
-		if (def.id === "null") return true;
-		return isNullableUnion(doc.unwindType(def.id, def.chain)?.def, doc, depth + 1);
-	}
-	if (primitiveBaseType(def) === "null") return true;
+	if (isNullMember(def)) return true;
+	if ((0, _atscript_core.isRef)(def)) return isNullableUnion(doc.unwindType(def.id, def.chain)?.def, doc, depth + 1);
 	const group = def;
 	if (!group.isGroup || group.op !== "|" || (0, _atscript_core.isStructure)(def)) return false;
 	return group.unwrap().some((member) => isNullableUnion(member, doc, depth + 1));
@@ -369,6 +373,20 @@ function findViewCycle(owner, doc) {
 	return walk(owner, doc, [start]);
 }
 /**
+* The chain reference (`User.id`) an `@db.rel.FK` field's type names, else
+* `undefined`. `User.id | null` names it too (since 0.1.165) — the same
+* optional foreign key as `field?: User.id`; any other union does not.
+*/
+function fkChainRef(def) {
+	if (def && (0, _atscript_core.isRef)(def)) return def.hasChain ? def : void 0;
+	if (!def || !(0, _atscript_core.isGroup)(def) || def.op !== "|") return void 0;
+	const members = def.unwrap();
+	const values = members.filter((m) => !isNullMember(m));
+	if (values.length !== 1 || values.length === members.length) return void 0;
+	const [only] = values;
+	return only && (0, _atscript_core.isRef)(only) && only.hasChain ? only : void 0;
+}
+/**
 * Find all `@db.rel.FK` fields on a type that reference `targetTypeName`.
 * Resolves `extends` to include inherited fields.
 */
@@ -383,10 +401,8 @@ function findFKFieldsPointingTo(doc, iface, targetTypeName, alias) {
 	if (!struct) return results;
 	for (const [name, prop] of struct.props) {
 		if (prop.countAnnotations("db.rel.FK") === 0) continue;
-		const def = prop.getDefinition();
-		if (!def || !(0, _atscript_core.isRef)(def)) continue;
-		const ref = def;
-		if (!ref.hasChain) continue;
+		const ref = fkChainRef(prop.getDefinition());
+		if (!ref) continue;
 		const refTypeName = ref.id;
 		const refField = ref.chain.map((c) => c.text).join(".");
 		if (refTypeName !== targetTypeName) continue;
@@ -866,6 +882,12 @@ Object.defineProperty(exports, "findViewCycle", {
 		return findViewCycle;
 	}
 });
+Object.defineProperty(exports, "fkChainRef", {
+	enumerable: true,
+	get: function() {
+		return fkChainRef;
+	}
+});
 Object.defineProperty(exports, "forEachFieldRef", {
 	enumerable: true,
 	get: function() {
@@ -932,6 +954,12 @@ Object.defineProperty(exports, "isNavProp", {
 		return isNavProp;
 	}
 });
+Object.defineProperty(exports, "isNullMember", {
+	enumerable: true,
+	get: function() {
+		return isNullMember;
+	}
+});
 Object.defineProperty(exports, "isNullableUnion", {
 	enumerable: true,
 	get: function() {