@atscript/db 0.1.127 → 0.1.128

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { G as TDbStorageType, I as TDbFieldMeta, J as TExistingTableOption, L as TDbForeignKey, P as TDbDefaultValue, T as TColumnDiff, _t as TGenericLogger, at as TTableOptionDiff, q as TExistingColumn, t as AtscriptDbReadable } from "./db-readable-C0nDKX8A.cjs";
-import { i as AtscriptDbView, t as DbSpace } from "./db-space-CSntT6yS.cjs";
+import { B as TDbForeignKey, K as TDbObjectKind, L as TDbDefaultValue, Nt as TGenericLogger, O as TColumnDiff, Z as TDbStorageType, at as TExistingForeignKey, ht as TReferencingForeignKey, it as TExistingColumn, mt as TPrimaryKeyChange, ot as TExistingTableOption, rt as TEnsureTableOptions, t as AtscriptDbReadable, yt as TTableOptionDiff, z as TDbFieldMeta } from "./db-readable-CkbZn_z-.cjs";
+import { c as AtscriptQueryFieldRef$1, i as AtscriptDbView, l as AtscriptQueryNode$1, t as DbSpace } from "./db-space-BevOyVrC.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts
@@ -13,6 +13,13 @@ interface TSyncColors {
   underline(s: string): string;
 }
 type TSyncEntryStatus = "create" | "alter" | "drop" | "in-sync" | "error";
+/**
+ * Desired work safe mode did not apply (since 0.1.128): the primary-key
+ * rebuild, the `@db.sync.method 'drop'` recreate of a type change, the
+ * 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";
 interface TSyncEntryInit {
   name: string;
   /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
@@ -59,6 +66,47 @@ interface TSyncEntryInit {
   recreated?: boolean;
   errors?: string[];
   renamedFrom?: string;
+  /**
+   * The table's primary-key field set changes. `rebuild: true` when sync
+   * rebuilds the key (empty table); `false` when the rebuild is skipped
+   * (safe mode). A populated table is refused instead (see `refused`).
+   * @since 0.1.128
+   */
+  pkChange?: {
+    from: string[];
+    to: string[];
+    rebuild: boolean;
+  };
+  /**
+   * The work safe mode skipped on this table: `"pk-rebuild"` (`pkChange`
+   * kept with `rebuild: false`), `"recreate"` (`typeChanges` kept),
+   * `"table-options"` (`optionChanges` kept) and `"nullable-defaults"`
+   * (`nullableChanges` / `defaultChanges` kept). Each is pending: the
+   * table's snapshot and the schema hash are withheld, and the next run
+   * without `safe` applies it. Printed as `… — skipped (safe mode)`.
+   * Identical in the plan and in the run.
+   * @since 0.1.128
+   */
+  skipped?: ReadonlyArray<TSyncSkippedWork>;
+  /**
+   * Names of the tables this entry's DDL waits for (FK parents for tables,
+   * entry/join tables for views, referencing children for drops).
+   * Informational — schema sync already executes in that order.
+   * @since 0.1.128
+   */
+  dependsOn?: string[];
+  /**
+   * Present when the table is dropped together with the other members of a
+   * foreign-key cycle (one group operation).
+   * @since 0.1.128
+   */
+  dropGroup?: string[];
+  /**
+   * `true` when this `error` entry is a pre-flight refusal: schema sync
+   * detected a change it cannot apply safely and issued no DDL at all.
+   * @since 0.1.128
+   */
+  refused?: boolean;
 }
 declare class SyncEntry {
   readonly name: string;
@@ -106,8 +154,37 @@ declare class SyncEntry {
   readonly recreated: boolean;
   readonly errors: string[];
   readonly renamedFrom?: string;
+  /** @since 0.1.128 — see {@link TSyncEntryInit.pkChange}. */
+  readonly pkChange?: {
+    from: string[];
+    to: string[];
+    rebuild: boolean;
+  };
+  /** @since 0.1.128 — see {@link TSyncEntryInit.skipped}. */
+  readonly skipped: ReadonlyArray<TSyncSkippedWork>;
+  /** @since 0.1.128 — see {@link TSyncEntryInit.dependsOn}. */
+  readonly dependsOn: string[];
+  /** @since 0.1.128 — see {@link TSyncEntryInit.dropGroup}. */
+  readonly dropGroup?: string[];
+  /** @since 0.1.128 — see {@link TSyncEntryInit.refused}. */
+  readonly refused: boolean;
   constructor(init: TSyncEntryInit);
-  /** Whether this entry involves destructive operations */
+  /**
+   * The init object this entry was built from — lets callers derive a
+   * modified copy (`new SyncEntry({ ...entry.toInit(), status: "error" })`).
+   * @since 0.1.128
+   */
+  toInit(): TSyncEntryInit;
+  /**
+   * Whether desired work is still pending after this entry — DDL that was
+   * not issued because the entry errored or safe mode skipped it (see
+   * `skipped`). A pending entry withholds its snapshot and the schema hash,
+   * so the next run retries / applies it. External views are advisory and
+   * never pending.
+   * @since 0.1.128
+   */
+  get pending(): boolean;
+  /** Whether this entry involves destructive operations (pending work safe mode skipped is not) */
   get destructive(): boolean;
   /** Whether this entry represents any change (not in-sync) */
   get hasChanges(): boolean;
@@ -117,6 +194,24 @@ declare class SyncEntry {
   print(mode: "plan" | "result", colors?: TSyncColors): string[];
   private labelAndPrefix;
   private printError;
+  /** `! PK (id) → (code) — rebuild (table is empty)` / `— skipped (safe mode)` */
+  private printPkChange;
+  /**
+   * `! col: t1 → t2 — drop` (plan), or `! type col (t1 → t2) — skipped (safe
+   * mode)` in plan and result when the `'drop'` recreate was skipped.
+   */
+  private printTypeChanges;
+  /** `~ col — nullable` / `~ col — default a → b`, `— skipped (safe mode)` when pending. */
+  private printNullableDefaults;
+  /**
+   * Plan: `~ option k: a → b`, or `! option k: a → b — requires recreation`
+   * for a destructive change. Result: `~ option k: a → b` for an applied
+   * change. Both: `! option k: a → b — skipped (safe mode)` when pending.
+   */
+  private printOptionChanges;
+  /** `· after: a, b` (plan only — the executor already runs in this order). */
+  private printDependsOn;
+  private printDropGroup;
   private printPlan;
   private printResult;
   private printInSync;
@@ -158,12 +253,30 @@ interface TTableSnapshot {
   /** 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;
+  /** Reserved for optional joins; absent today so it does not perturb the hash. */
+  kind?: "inner" | "left";
+}
 interface TViewSnapshot {
   tableName: string;
   viewType: "V" | "M" | "E";
   entryTable?: string;
-  joinTables?: string[];
+  /**
+   * Joins in declaration order. The key keeps its historical name so a
+   * join-less view (`[]`) serializes byte-identically to older snapshots.
+   */
+  joinTables?: TViewJoinSnapshot[];
   filterHash?: string;
+  /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
+  havingHash?: string;
   materialized?: boolean;
   fields: TFieldSnapshot[];
 }
@@ -183,6 +296,30 @@ declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?:
  * 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.
@@ -233,7 +370,13 @@ interface TSyncOptions {
   pollIntervalMs?: number;
   /** Force sync even if hash matches. Default: false. */
   force?: boolean;
-  /** Safe mode — skip destructive operations (column drops, table drops). Default: false. */
+  /**
+   * Safe mode — skip destructive operations (column/table drops, `'drop'`
+   * recreates, destructive table-option recreates, key rebuilds, nullable /
+   * default DDL). Skipped work is pending (`entry.skipped`): the table's
+   * snapshot and the hash are withheld until a run without `safe` applies
+   * it. Default: false.
+   */
   safe?: boolean;
   /**
    * Logger for sync progress and failures (index/FK DDL errors are logged,
@@ -242,7 +385,7 @@ interface TSyncOptions {
   logger?: TGenericLogger;
   /**
    * What to do when the run finishes with errored entries (failed index/FK
-   * DDL, external-view checks, …):
+   * DDL, external-view checks, pre-flight refusals, …):
    * - `"warn"` (default) — emit a one-line summary plus per-entry error lines
    *   via the configured logger, **falling back to `console` when no logger
    *   is set** (errors are never silently swallowed by the NoopLogger default);
@@ -252,7 +395,16 @@ interface TSyncOptions {
   onError?: "throw" | "warn" | "silent";
 }
 interface TSyncResult {
-  status: "up-to-date" | "synced" | "synced-by-peer";
+  /**
+   * - `"up-to-date"` — stored hash matches, nothing ran;
+   * - `"synced"` — the run executed (inspect `entries` for per-table status);
+   * - `"synced-by-peer"` — another pod synced while this one waited for the lock;
+   * - `"refused"` (since 0.1.128) — pre-flight found a change that cannot be
+   *   applied safely: NO DDL ran, tracking/snapshots/hash are untouched, the
+   *   lock is released. `entries` is the full plan with the refused entries
+   *   as `error` entries (`refused: true`).
+   */
+  status: "up-to-date" | "synced" | "synced-by-peer" | "refused";
   schemaHash: string;
   entries: SyncEntry[];
 }
@@ -272,8 +424,8 @@ declare class SchemaSync {
    */
   private checkExternalView;
   /**
-   * Detects tables/views present in the previous sync but absent from the current schema.
-   * Returns SyncEntry instances with status 'drop'.
+   * Detects tables/views present in the previous sync but absent from the
+   * current schema (external views excluded — sync owns no DDL for them).
    */
   private detectRemoved;
   /**
@@ -285,9 +437,55 @@ declare class SchemaSync {
   /** Throws if the heartbeat detected a stolen/missing lock. */
   private assertLockHeld;
   /**
-   * Runs schema synchronization with distributed locking.
+   * Runs schema synchronization with distributed locking, in three phases:
+   *
+   * 1. **Discover** (read-only, under the lock): introspect every table once,
+   *    diff columns/FKs, read tracking, build the dependency graph.
+   * 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.
    */
   run(types: readonly TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+  private discover;
+  /** Whether an object named `name` exists, or `undefined` when the adapter cannot tell. */
+  private objectPresent;
+  /**
+   * Introspects one desired table and computes its plan entry.
+   * `probeRecreateInbound` — whether a drop-and-recreate's live inbound FKs
+   * are worth probing (a removed table exists that could block it).
+   */
+  private discoverTable;
+  /**
+   * Pure validation over the discovery facts. Every refusal is a change that
+   * no order of DDL can apply safely; the messages are user-facing.
+   */
+  private preflight;
+  /**
+   * The one ordering walk `plan()` and `run()` share: tables parents-first,
+   * each preceded by the removed tables that block its drop/rebuild; the
+   * deferred FK pass; managed views; external-view checks; removed views;
+   * the remaining removed tables children-first.
+   */
+  private orderedSteps;
+  /** The plan entries in execution order, refusals folded in as `error` entries. */
+  private buildPlanEntries;
+  private execute;
+  /**
+   * Drops one removed-table group (a table, or a foreign-key cycle as one
+   * operation) and returns its entries. A live inbound FK from outside the
+   * removed set blocks the group — error entries, kept tracked — instead of
+   * leaving a dangling constraint or cascading. The probe runs at execution
+   * time, so an inventory child whose FK to the group was dropped earlier in
+   * this run does not block it. Called from the walk for early groups (right
+   * before the table they block) and late groups (after the views) alike.
+   */
+  private dropRemovedGroup;
   /**
    * Surfaces the run outcome per the `onError` policy. Reporting must never be
    * silently lost to the NoopLogger default — when no real logger is
@@ -296,22 +494,25 @@ declare class SchemaSync {
    */
   private reportOutcome;
   /**
-   * Computes a dry-run plan showing what `run()` would do, without executing any DDL.
+   * Computes a dry-run plan showing what `run()` would do, without executing
+   * 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>;
   /** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
   private resolveTypeMapper;
-  private planTable;
   /**
    * Populates plan init from a column diff (shared by Path A and Path B).
    */
   private populatePlanFromDiff;
   /**
    * Computes table option diff using DB-first introspection with snapshot fallback.
-   * Returns null if the adapter has no table options.
+   * Returns null if the adapter has no table options. `tableName` is the name
+   * the table has in the database right now — the OLD name of a pending
+   * `@db.table.renamed` (the adapter's bound name is the new one, which does
+   * not exist yet); omitted for a table that is not being renamed.
    */
   private diffTableOptions;
-  private planView;
   private buildExecutorDeps;
 }
 //#endregion
@@ -365,6 +566,24 @@ declare function computeForeignKeyDiff(desired: ReadonlyMap<string, TDbForeignKe
 /** Whether the FK diff contains any changes. */
 declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
 //#endregion
+//#region src/schema/dependency-order.d.ts
+/** A directed edge `from → to`: `from` depends on `to` (child → parent). */
+type TDependencyEdge = readonly [from: string, to: string];
+/**
+ * Orders `nodes` so that dependencies come first. Returns the strongly-
+ * connected components in dependency order: every group appears AFTER each
+ * group it depends on (parents first). Singleton groups are ordinary tables;
+ * groups of size > 1 are cycles. Members are name-sorted.
+ *
+ * - Edges referencing a name outside `nodes` are ignored (external tables
+ *   impose no ordering).
+ * - Self-loops are ignored (a self-referential FK is legal inline everywhere).
+ * - Deterministic: nodes and adjacency lists are sorted by name before the
+ *   traversal, so two processes with different inventory orders compute the
+ *   same plan.
+ */
+declare function topoOrder(nodes: Iterable<string>, edges: Iterable<TDependencyEdge>): string[][];
+//#endregion
 //#region src/sync.d.ts
 /**
  * Synchronizes database schema with distributed locking.
@@ -412,4 +631,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 TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };
+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 TViewJoinSnapshot, type TViewSnapshot, canonicalizeQueryNode, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, planSchema, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema, topoOrder };