@atscript/db 0.1.140 → 0.1.142

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { $t as AtscriptDbReadable, Ft as DbSpace, G as TDbObjectKind, I as TDbDefaultValue, R as TDbFieldMeta, Rt as AtscriptDbView, Ut as AtscriptQueryFieldRef$1, Wt as AtscriptQueryNode$1, X as TDbStorageType, at as TExistingTableOption, ht as TReferencingForeignKey, it as TExistingForeignKey, mt as TPrimaryKeyChange, nt as TEnsureTableOptions, rt as TExistingColumn, sn as TGenericLogger, yt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-C-27xmtq.cjs";
-import { t as computeColumnDiff } from "./column-diff-BmqvgBWw.cjs";
+import { G as TDbObjectKind, Lt as DbSpace, R as TDbFieldMeta, _t as TReferencingForeignKey, gt as TPrimaryKeyChange, it as TEnsureTableOptions, nt as TDerivedChangeReason, ot as TExistingForeignKey, st as TExistingTableOption, un as TGenericLogger, xt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-Bv4pah66.cjs";
+import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-DiBbXyLA.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -19,7 +19,17 @@ type TSyncEntryStatus = "create" | "alter" | "drop" | "in-sync" | "error";
  * recreate a destructive table-option change needs, and nullable/default
  * changes on adapters that need DDL for them.
  */
-type TSyncSkippedWork = "pk-rebuild" | "recreate" | "table-options" | "nullable-defaults";
+type TSyncSkippedWork = "pk-rebuild" | "recreate" | "table-options" | "nullable-defaults" /** A derived column's drop + add (kind / expression / type change) — since 0.1.141. */ | "derived";
+/**
+ * One derived-column rebuild as plan and run entries report it (since 0.1.141):
+ * `reason` as the column diff classified it, `derived` whether the MODEL side
+ * is the derived one (`kind` reads `regular → derived` / `derived → regular`).
+ */
+interface TSyncDerivedChange {
+  column: string;
+  reason: TDerivedChangeReason;
+  derived: boolean;
+}
 interface TSyncEntryInit {
   name: string;
   /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
@@ -60,6 +70,13 @@ interface TSyncEntryInit {
     targetTable: string;
     details: string;
   }>;
+  /**
+   * Derived columns the run drops and re-adds (a generated column's
+   * expression cannot be altered in place) — kept on the entry when safe
+   * mode skipped the rebuild (`skipped` includes `'derived'`).
+   * @since 0.1.141
+   */
+  derivedChanges?: TSyncDerivedChange[];
   columnsAdded?: string[];
   columnsRenamed?: string[];
   columnsDropped?: string[];
@@ -107,6 +124,13 @@ interface TSyncEntryInit {
    * @since 0.1.128
    */
   refused?: boolean;
+  /**
+   * Managed views this view reads whose recreate forces this view's own
+   * drop-and-recreate (its definition is unchanged). Printed as
+   * `· upstream view "x" recreated`.
+   * @since 0.1.141
+   */
+  cascadeFrom?: string[];
 }
 declare class SyncEntry {
   readonly name: string;
@@ -148,6 +172,8 @@ declare class SyncEntry {
     targetTable: string;
     details: string;
   }>;
+  /** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
+  readonly derivedChanges: TSyncDerivedChange[];
   readonly columnsAdded: string[];
   readonly columnsRenamed: string[];
   readonly columnsDropped: string[];
@@ -168,6 +194,8 @@ declare class SyncEntry {
   readonly dropGroup?: string[];
   /** @since 0.1.128 — see {@link TSyncEntryInit.refused}. */
   readonly refused: boolean;
+  /** @since 0.1.141 — see {@link TSyncEntryInit.cascadeFrom}. */
+  readonly cascadeFrom: string[];
   constructor(init: TSyncEntryInit);
   /**
    * The init object this entry was built from — lets callers derive a
@@ -208,6 +236,11 @@ declare class SyncEntry {
    * mode)` in plan and result when the `'drop'` recreate was skipped.
    */
   private printTypeChanges;
+  /**
+   * `~ col — derived column (expression changed) — drop + add` (plan) /
+   * `— rebuilt` (result), or `! … — skipped (safe mode)` when pending.
+   */
+  private printDerivedChanges;
   /** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
   private printNullableDefaults;
   /**
@@ -218,165 +251,14 @@ declare class SyncEntry {
   private printOptionChanges;
   /** `· after: a, b` (plan only — the executor already runs in this order). */
   private printDependsOn;
+  /** `· upstream view "x" recreated` — why an unchanged view is recreated. */
+  private printCascade;
   private printDropGroup;
   private printPlan;
   private printResult;
   private printInSync;
 }
 //#endregion
-//#region src/schema/schema-hash.d.ts
-interface TFieldSnapshot {
-  physicalName: string;
-  designType: string;
-  optional: boolean;
-  isPrimaryKey: boolean;
-  storage: TDbStorageType;
-  defaultValue?: TDbDefaultValue;
-  /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
-  mappedType?: string;
-  /** `@db.encrypted` — toggling encryption changes the snapshot hash on every adapter. */
-  encrypted?: boolean;
-}
-interface TIndexSnapshot {
-  key: string;
-  type: string;
-  fields: Array<{
-    name: string;
-    sort: string;
-  }>;
-}
-interface TForeignKeySnapshot {
-  fields: string[];
-  targetTable: string;
-  targetFields: string[];
-  onDelete?: string;
-  onUpdate?: string;
-}
-interface TTableSnapshot {
-  tableName: string;
-  fields: TFieldSnapshot[];
-  indexes: TIndexSnapshot[];
-  foreignKeys: TForeignKeySnapshot[];
-  /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
-  tableOptions?: TExistingTableOption[];
-}
-/**
- * One join of a managed view as stored in its snapshot.
- * @since 0.1.128 — `joinTables` elements were bare target-table names before;
- * the ON predicate is now part of the view definition.
- */
-interface TViewJoinSnapshot {
-  targetTable: string;
-  /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
-  condition: string;
-  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
-  kind?: "inner" | "left";
-}
-/**
- * One column of a managed view as stored in its snapshot — the PHYSICAL
- * source it reads, so a source rename (`@db.column`, flattening, a moved
- * JSON leaf) or an aggregate change recreates the view.
- * @since 0.1.136
- */
-interface TViewColumnSnapshot {
-  column: string;
-  sourceTable: string;
-  sourceColumn: string;
-  /** JSON array of the path segments inside a JSON source column. */
-  jsonPath?: string;
-  jsonType?: string;
-  aggFn?: string;
-  aggField?: string;
-  /** Canonical JSON of a conditional aggregate's predicate. */
-  aggFilter?: string;
-}
-interface TViewSnapshot {
-  tableName: string;
-  viewType: "V" | "M" | "E";
-  entryTable?: string;
-  /**
-   * Joins in declaration order. The key keeps its historical name so a
-   * join-less view (`[]`) serializes byte-identically to older snapshots.
-   */
-  joinTables?: TViewJoinSnapshot[];
-  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
-  columns?: TViewColumnSnapshot[];
-  filterHash?: string;
-  /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
-  havingHash?: string;
-  materialized?: boolean;
-  /**
-   * @since 0.1.137 — the adapter's `viewRenderRevision()`, present only when
-   * the adapter defines one (managed views only).
-   */
-  renderRevision?: string;
-  fields: TFieldSnapshot[];
-}
-/**
- * Extracts a canonical, serializable snapshot from a readable's metadata.
- * Sorted deterministically so the hash is stable across runs.
- *
- * @param readable - The table/view readable.
- * @param typeMapper - Optional adapter-specific type mapper. When provided,
- *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
- *   for precise type change detection.
- */
-declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
-/**
- * Extracts a canonical, serializable snapshot from a view's metadata.
- * Captures view plan (entry table, joins, filter, materialization) for
- * detecting view definition changes.
- */
-declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
-/** Canonical (table-qualified, fixed-key-order) form of a view predicate. */
-type TCanonicalQueryNode = {
-  and: TCanonicalQueryNode[];
-} | {
-  or: TCanonicalQueryNode[];
-} | {
-  not: TCanonicalQueryNode;
-} /** `r` is `{ f: "<table>.<field>" }` for a field-to-field comparison, else the literal. */ | {
-  l: string;
-  op: string;
-  r?: unknown;
-};
-/**
- * Converts a view predicate (join condition, `@db.view.filter`,
- * `@db.view.having`) into a serializable structure whose JSON is a stable
- * function of its MEANING: field refs become `qualify(ref)` — the view's
- * `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
- * retargeted to another table with the same field name changes — operators
- * and literal values are kept as-is, `$and`/`$or` keep declaration order, and
- * no function references survive. Two identical models produce byte-identical
- * JSON.
- * @since 0.1.128
- */
-declare function canonicalizeQueryNode(node: AtscriptQueryNode$1, qualify: (ref: AtscriptQueryFieldRef$1) => string): TCanonicalQueryNode;
-/**
- * Computes a deterministic hash string from multiple table snapshots.
- * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
- */
-declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
-/**
- * Computes a hash for a single table/view snapshot.
- * Used for per-table change detection via stored snapshots.
- */
-declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
-/**
- * Converts stored snapshot fields to `TExistingColumn[]` format
- * for use with `computeColumnDiff`. Used by adapters that lack
- * native column introspection (e.g., MongoDB).
- *
- * The `type` field uses `mappedType` when available (adapter-specific),
- * falling back to `designType`.
- */
-declare function snapshotToExistingColumns(snapshot: TTableSnapshot): TExistingColumn[];
-/**
- * Extracts table options from a stored snapshot for diff comparison.
- * Used as fallback when an adapter lacks native table option introspection.
- */
-declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
-//#endregion
 //#region src/schema/sync-store.d.ts
 /**
  * Reads a stored table snapshot from the control table.
@@ -465,10 +347,27 @@ declare class SchemaSync {
    * Starts a periodic heartbeat that extends the lock's TTL while sync runs.
    * Returns a handle with `stop()` to cancel and `getAbortReason()` to check
    * whether the lock was stolen or unexpectedly removed.
+   *
+   * At most one refresh is in flight; `stop()` resolves once it has settled,
+   * so the lock is released only after the last refresh — a late refresh must
+   * never race the release (or the next holder's lock).
    */
   private startHeartbeat;
+  /**
+   * 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
+   * 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`.
+   */
+  private acquireLock;
   /** Throws if the heartbeat detected a stolen/missing lock. */
   private assertLockHeld;
+  /**
+   * Releases the lock without masking the run's outcome: a failed release is
+   * logged (the row expires after `lockTtlMs`, blocking peers until then).
+   */
+  private releaseLock;
   /**
    * Runs schema synchronization with distributed locking, in three phases:
    *
@@ -477,12 +376,12 @@ declare class SchemaSync {
    * 2. **Pre-flight** (pure): every change that no order of DDL can apply
    *    safely becomes a refusal. One refusal → `status: "refused"`, no DDL,
    *    nothing persisted, lock released.
-   * 3. **Execute** in dependency order: stale/removed views → inbound FKs of
-   *    key-changing tables → tables (parents first; a removed table that
-   *    blocks a table's drop-and-recreate or key rebuild is dropped right
-   *    before it) → deferred FKs of cycles → managed views → external-view
-   *    checks → remaining removed tables (children first) →
-   *    snapshots/tracking/hash.
+   * 3. **Execute** in dependency order: removed views, then stale views
+   *    (dependents first) → inbound FKs of key-changing tables → tables
+   *    (parents first; a removed table that blocks a table's drop-and-recreate
+   *    or key rebuild is dropped right before it) → deferred FKs of cycles →
+   *    managed views (upstream views first) → external-view checks →
+   *    remaining removed tables (children first) → snapshots/tracking/hash.
    */
   run(types: readonly TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
   private discover;
@@ -661,4 +560,4 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  */
 declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, 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, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, 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, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { $t as AtscriptDbReadable, Ft as DbSpace, G as TDbObjectKind, I as TDbDefaultValue, R as TDbFieldMeta, Rt as AtscriptDbView, Ut as AtscriptQueryFieldRef$1, Wt as AtscriptQueryNode$1, X as TDbStorageType, at as TExistingTableOption, ht as TReferencingForeignKey, it as TExistingForeignKey, mt as TPrimaryKeyChange, nt as TEnsureTableOptions, rt as TExistingColumn, sn as TGenericLogger, yt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-BFG2RYRW.mjs";
-import { t as computeColumnDiff } from "./column-diff-DPkbZIVE.mjs";
+import { G as TDbObjectKind, Lt as DbSpace, R as TDbFieldMeta, _t as TReferencingForeignKey, gt as TPrimaryKeyChange, it as TEnsureTableOptions, nt as TDerivedChangeReason, ot as TExistingForeignKey, st as TExistingTableOption, un as TGenericLogger, xt as TTableOptionDiff, z as TDbForeignKey } from "./buckets-CjL7F-hp.mjs";
+import { a as TTableSnapshot, c as TViewSnapshot, d as computeTableHash, f as computeTableSnapshot, h as snapshotToExistingTableOptions, i as TForeignKeySnapshot, l as canonicalizeQueryNode, m as snapshotToExistingColumns, o as TViewColumnSnapshot, p as computeViewSnapshot, r as TFieldSnapshot, s as TViewJoinSnapshot, t as computeColumnDiff, u as computeSchemaHash } from "./column-diff-n-k5KY0u.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -19,7 +19,17 @@ type TSyncEntryStatus = "create" | "alter" | "drop" | "in-sync" | "error";
  * recreate a destructive table-option change needs, and nullable/default
  * changes on adapters that need DDL for them.
  */
-type TSyncSkippedWork = "pk-rebuild" | "recreate" | "table-options" | "nullable-defaults";
+type TSyncSkippedWork = "pk-rebuild" | "recreate" | "table-options" | "nullable-defaults" /** A derived column's drop + add (kind / expression / type change) — since 0.1.141. */ | "derived";
+/**
+ * One derived-column rebuild as plan and run entries report it (since 0.1.141):
+ * `reason` as the column diff classified it, `derived` whether the MODEL side
+ * is the derived one (`kind` reads `regular → derived` / `derived → regular`).
+ */
+interface TSyncDerivedChange {
+  column: string;
+  reason: TDerivedChangeReason;
+  derived: boolean;
+}
 interface TSyncEntryInit {
   name: string;
   /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
@@ -60,6 +70,13 @@ interface TSyncEntryInit {
     targetTable: string;
     details: string;
   }>;
+  /**
+   * Derived columns the run drops and re-adds (a generated column's
+   * expression cannot be altered in place) — kept on the entry when safe
+   * mode skipped the rebuild (`skipped` includes `'derived'`).
+   * @since 0.1.141
+   */
+  derivedChanges?: TSyncDerivedChange[];
   columnsAdded?: string[];
   columnsRenamed?: string[];
   columnsDropped?: string[];
@@ -107,6 +124,13 @@ interface TSyncEntryInit {
    * @since 0.1.128
    */
   refused?: boolean;
+  /**
+   * Managed views this view reads whose recreate forces this view's own
+   * drop-and-recreate (its definition is unchanged). Printed as
+   * `· upstream view "x" recreated`.
+   * @since 0.1.141
+   */
+  cascadeFrom?: string[];
 }
 declare class SyncEntry {
   readonly name: string;
@@ -148,6 +172,8 @@ declare class SyncEntry {
     targetTable: string;
     details: string;
   }>;
+  /** @since 0.1.141 — see {@link TSyncEntryInit.derivedChanges}. */
+  readonly derivedChanges: TSyncDerivedChange[];
   readonly columnsAdded: string[];
   readonly columnsRenamed: string[];
   readonly columnsDropped: string[];
@@ -168,6 +194,8 @@ declare class SyncEntry {
   readonly dropGroup?: string[];
   /** @since 0.1.128 — see {@link TSyncEntryInit.refused}. */
   readonly refused: boolean;
+  /** @since 0.1.141 — see {@link TSyncEntryInit.cascadeFrom}. */
+  readonly cascadeFrom: string[];
   constructor(init: TSyncEntryInit);
   /**
    * The init object this entry was built from — lets callers derive a
@@ -208,6 +236,11 @@ declare class SyncEntry {
    * mode)` in plan and result when the `'drop'` recreate was skipped.
    */
   private printTypeChanges;
+  /**
+   * `~ col — derived column (expression changed) — drop + add` (plan) /
+   * `— rebuilt` (result), or `! … — skipped (safe mode)` when pending.
+   */
+  private printDerivedChanges;
   /** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
   private printNullableDefaults;
   /**
@@ -218,165 +251,14 @@ declare class SyncEntry {
   private printOptionChanges;
   /** `· after: a, b` (plan only — the executor already runs in this order). */
   private printDependsOn;
+  /** `· upstream view "x" recreated` — why an unchanged view is recreated. */
+  private printCascade;
   private printDropGroup;
   private printPlan;
   private printResult;
   private printInSync;
 }
 //#endregion
-//#region src/schema/schema-hash.d.ts
-interface TFieldSnapshot {
-  physicalName: string;
-  designType: string;
-  optional: boolean;
-  isPrimaryKey: boolean;
-  storage: TDbStorageType;
-  defaultValue?: TDbDefaultValue;
-  /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
-  mappedType?: string;
-  /** `@db.encrypted` — toggling encryption changes the snapshot hash on every adapter. */
-  encrypted?: boolean;
-}
-interface TIndexSnapshot {
-  key: string;
-  type: string;
-  fields: Array<{
-    name: string;
-    sort: string;
-  }>;
-}
-interface TForeignKeySnapshot {
-  fields: string[];
-  targetTable: string;
-  targetFields: string[];
-  onDelete?: string;
-  onUpdate?: string;
-}
-interface TTableSnapshot {
-  tableName: string;
-  fields: TFieldSnapshot[];
-  indexes: TIndexSnapshot[];
-  foreignKeys: TForeignKeySnapshot[];
-  /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
-  tableOptions?: TExistingTableOption[];
-}
-/**
- * One join of a managed view as stored in its snapshot.
- * @since 0.1.128 — `joinTables` elements were bare target-table names before;
- * the ON predicate is now part of the view definition.
- */
-interface TViewJoinSnapshot {
-  targetTable: string;
-  /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
-  condition: string;
-  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
-  kind?: "inner" | "left";
-}
-/**
- * One column of a managed view as stored in its snapshot — the PHYSICAL
- * source it reads, so a source rename (`@db.column`, flattening, a moved
- * JSON leaf) or an aggregate change recreates the view.
- * @since 0.1.136
- */
-interface TViewColumnSnapshot {
-  column: string;
-  sourceTable: string;
-  sourceColumn: string;
-  /** JSON array of the path segments inside a JSON source column. */
-  jsonPath?: string;
-  jsonType?: string;
-  aggFn?: string;
-  aggField?: string;
-  /** Canonical JSON of a conditional aggregate's predicate. */
-  aggFilter?: string;
-}
-interface TViewSnapshot {
-  tableName: string;
-  viewType: "V" | "M" | "E";
-  entryTable?: string;
-  /**
-   * Joins in declaration order. The key keeps its historical name so a
-   * join-less view (`[]`) serializes byte-identically to older snapshots.
-   */
-  joinTables?: TViewJoinSnapshot[];
-  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
-  columns?: TViewColumnSnapshot[];
-  filterHash?: string;
-  /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
-  havingHash?: string;
-  materialized?: boolean;
-  /**
-   * @since 0.1.137 — the adapter's `viewRenderRevision()`, present only when
-   * the adapter defines one (managed views only).
-   */
-  renderRevision?: string;
-  fields: TFieldSnapshot[];
-}
-/**
- * Extracts a canonical, serializable snapshot from a readable's metadata.
- * Sorted deterministically so the hash is stable across runs.
- *
- * @param readable - The table/view readable.
- * @param typeMapper - Optional adapter-specific type mapper. When provided,
- *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
- *   for precise type change detection.
- */
-declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
-/**
- * Extracts a canonical, serializable snapshot from a view's metadata.
- * Captures view plan (entry table, joins, filter, materialization) for
- * detecting view definition changes.
- */
-declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
-/** Canonical (table-qualified, fixed-key-order) form of a view predicate. */
-type TCanonicalQueryNode = {
-  and: TCanonicalQueryNode[];
-} | {
-  or: TCanonicalQueryNode[];
-} | {
-  not: TCanonicalQueryNode;
-} /** `r` is `{ f: "<table>.<field>" }` for a field-to-field comparison, else the literal. */ | {
-  l: string;
-  op: string;
-  r?: unknown;
-};
-/**
- * Converts a view predicate (join condition, `@db.view.filter`,
- * `@db.view.having`) into a serializable structure whose JSON is a stable
- * function of its MEANING: field refs become `qualify(ref)` — the view's
- * `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
- * retargeted to another table with the same field name changes — operators
- * and literal values are kept as-is, `$and`/`$or` keep declaration order, and
- * no function references survive. Two identical models produce byte-identical
- * JSON.
- * @since 0.1.128
- */
-declare function canonicalizeQueryNode(node: AtscriptQueryNode$1, qualify: (ref: AtscriptQueryFieldRef$1) => string): TCanonicalQueryNode;
-/**
- * Computes a deterministic hash string from multiple table snapshots.
- * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
- */
-declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
-/**
- * Computes a hash for a single table/view snapshot.
- * Used for per-table change detection via stored snapshots.
- */
-declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
-/**
- * Converts stored snapshot fields to `TExistingColumn[]` format
- * for use with `computeColumnDiff`. Used by adapters that lack
- * native column introspection (e.g., MongoDB).
- *
- * The `type` field uses `mappedType` when available (adapter-specific),
- * falling back to `designType`.
- */
-declare function snapshotToExistingColumns(snapshot: TTableSnapshot): TExistingColumn[];
-/**
- * Extracts table options from a stored snapshot for diff comparison.
- * Used as fallback when an adapter lacks native table option introspection.
- */
-declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
-//#endregion
 //#region src/schema/sync-store.d.ts
 /**
  * Reads a stored table snapshot from the control table.
@@ -465,10 +347,27 @@ declare class SchemaSync {
    * Starts a periodic heartbeat that extends the lock's TTL while sync runs.
    * Returns a handle with `stop()` to cancel and `getAbortReason()` to check
    * whether the lock was stolen or unexpectedly removed.
+   *
+   * At most one refresh is in flight; `stop()` resolves once it has settled,
+   * so the lock is released only after the last refresh — a late refresh must
+   * never race the release (or the next holder's lock).
    */
   private startHeartbeat;
+  /**
+   * 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
+   * 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`.
+   */
+  private acquireLock;
   /** Throws if the heartbeat detected a stolen/missing lock. */
   private assertLockHeld;
+  /**
+   * Releases the lock without masking the run's outcome: a failed release is
+   * logged (the row expires after `lockTtlMs`, blocking peers until then).
+   */
+  private releaseLock;
   /**
    * Runs schema synchronization with distributed locking, in three phases:
    *
@@ -477,12 +376,12 @@ declare class SchemaSync {
    * 2. **Pre-flight** (pure): every change that no order of DDL can apply
    *    safely becomes a refusal. One refusal → `status: "refused"`, no DDL,
    *    nothing persisted, lock released.
-   * 3. **Execute** in dependency order: stale/removed views → inbound FKs of
-   *    key-changing tables → tables (parents first; a removed table that
-   *    blocks a table's drop-and-recreate or key rebuild is dropped right
-   *    before it) → deferred FKs of cycles → managed views → external-view
-   *    checks → remaining removed tables (children first) →
-   *    snapshots/tracking/hash.
+   * 3. **Execute** in dependency order: removed views, then stale views
+   *    (dependents first) → inbound FKs of key-changing tables → tables
+   *    (parents first; a removed table that blocks a table's drop-and-recreate
+   *    or key rebuild is dropped right before it) → deferred FKs of cycles →
+   *    managed views (upstream views first) → external-view checks →
+   *    remaining removed tables (children first) → snapshots/tracking/hash.
    */
   run(types: readonly TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
   private discover;
@@ -661,4 +560,4 @@ declare function syncSchema(space: DbSpace, types: readonly TAtscriptAnnotatedTy
  */
 declare function planSchema(space: DbSpace, types: readonly TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
 //#endregion
-export { SchemaSync, SyncEntry, type TDbObjectKind, type TDependencyEdge, type TEnsureTableOptions, type TExistingForeignKey, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TPrimaryKeyChange, type TReferencingForeignKey, type TSyncColors, 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, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };
+export { SchemaSync, SyncEntry, 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, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };