@metaobjectsdev/migrate-ts 0.23.1 → 0.24.0

package/src/expected-schema.ts

@@ -43,6 +43,7 @@ import {
   FIELD_SUBTYPE_INET,
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_VALUES,
+  FIELD_ATTR_INT_VALUE_MAP,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_STORAGE,
   FIELD_ATTR_DB_COLUMN_TYPE,
@@ -60,6 +61,7 @@ import type {
   Dialect, SchemaSnapshot, TableDescriptor, ColumnDescriptor, IndexDescriptor, FkDescriptor,
   CheckDescriptor, ViewDescriptor,
 } from "./types.js";
+import { qualifiedDbName } from "./qualified-name.js";
 import { viewFingerprint } from "./view-fingerprint.js";
 import { resolveViewColumns, type ExpectedViewColumnInput } from "./view-column-types.js";
 import {
@@ -111,12 +113,55 @@ export interface ExpectedViewInput {
   sql?: string;
   dependsOn?: readonly string[];
   columns?: readonly ExpectedViewColumnInput[];
+  /**
+   * `resolutionKey()` of the object that declared this view — its PROVENANCE.
+   * Recorded in the provenance map and deliberately NEVER copied onto the
+   * `ViewDescriptor`: descriptors are serialized into the committed snapshot, and
+   * a descriptor that gains a field owes a `SNAPSHOT_FORMAT_VERSION` bump, which
+   * hard-fails every older reader. Optional — a caller that supplies no FQN gets a
+   * view with no provenance, which `scopeExpectedSchema` keeps (never guesses).
+   */
+  fqn?: string;
+}
+
+/**
+ * Qualified physical name (`qualifiedDbName`) → the `resolutionKey()` of the
+ * metadata object that declared it. The ONLY sound basis for a per-command scope
+ * decision: a SQL name cannot be reversed into an FQN (naming strategies, `@table`
+ * overrides and TPH folding are all lossy), and a second metadata walk would have
+ * to re-implement Pass 1's skip rules — abstract, TPH subtype, no writable source,
+ * `@unmanaged` — and would drift from them.
+ */
+export type SchemaProvenance = ReadonlyMap<string, string>;
+
+export interface ExpectedSchemaWithProvenance {
+  snapshot: SchemaSnapshot;
+  provenance: SchemaProvenance;
 }
 
+/**
+ * The expected schema as every existing caller wants it. Thin wrapper over
+ * {@link buildExpectedSchemaWithProvenance}; byte-identical output.
+ */
 export function buildExpectedSchema(
   root: MetaData,
   opts?: BuildExpectedSchemaOptions,
 ): SchemaSnapshot {
+  return buildExpectedSchemaWithProvenance(root, opts).snapshot;
+}
+
+/**
+ * The expected schema PLUS the declaring FQN of every table and view in it.
+ *
+ * Provenance is threaded out of the passes that already hold the declaring node —
+ * Pass 2 has each table's entity, Pass 4 each view's input — so there is exactly
+ * one walk and one set of skip rules. Callers that filter by scope
+ * (`scopeExpectedSchema`) consume it; callers that don't use the wrapper above.
+ */
+export function buildExpectedSchemaWithProvenance(
+  root: MetaData,
+  opts?: BuildExpectedSchemaOptions,
+): ExpectedSchemaWithProvenance {
   // D1 is SQLite at the SQL level; normalize it so downstream dialect checks
   // don't need to handle "d1" separately.
   const dialect = opts?.dialect === "d1" ? "sqlite" : opts?.dialect;
@@ -206,6 +251,12 @@ export function buildExpectedSchema(
     return byBareHit === AMBIGUOUS ? undefined : byBareHit;
   };
 
+  // Provenance: qualified physical name → declaring object's FQN. Recorded as the
+  // descriptors are built, never re-derived from a SQL name (lossy) and never by a
+  // second walk (it would have to duplicate Pass 1's skip rules and would drift from
+  // them — a TPH subtype, for one, shares its base's table and declares none of its own).
+  const provenance = new Map<string, string>();
+
   // Pass 2: build full descriptors with FK resolution.
   // Schema is resolved here (not stored in Pass 1) to avoid exactOptionalPropertyTypes
   // issues with `string | undefined` vs `schema?: string`.
@@ -213,6 +264,7 @@ export function buildExpectedSchema(
     const t = buildTable(entity, tableName, resolveTargetTable, root as MetaRoot, strategy, dialect);
     const schema = resolveTableSchema(entity);
     if (schema !== undefined) t.schema = schema;
+    provenance.set(qualifiedDbName(t), entity.resolutionKey());
     return t;
   });
 
@@ -287,13 +339,17 @@ export function buildExpectedSchema(
   //     whether a view change can use a non-destructive CREATE OR REPLACE.
   const views: ViewDescriptor[] = (opts?.views ?? []).map((v) => {
     const columns = resolveViewColumns(v.columns, tables);
-    return {
+    const descriptor: ViewDescriptor = {
       name: v.name,
       ...(v.schema !== undefined ? { schema: v.schema } : {}),
       ...(v.sql !== undefined ? { sql: v.sql, fingerprint: viewFingerprint(v.sql) } : {}),
       ...(v.dependsOn !== undefined ? { dependsOn: v.dependsOn } : {}),
       ...(columns !== undefined ? { columns } : {}),
     };
+    // The declaring FQN goes to the provenance map ONLY — never onto the descriptor,
+    // which is what the committed snapshot serializes (see ExpectedViewInput.fqn).
+    if (v.fqn !== undefined) provenance.set(qualifiedDbName(descriptor), v.fqn);
+    return descriptor;
   });
 
   // Collision guard: two DISTINCT metadata objects that resolve to the same generated
@@ -323,7 +379,7 @@ export function buildExpectedSchema(
     );
   }
 
-  return { tables, views };
+  return { snapshot: { tables, views }, provenance };
 }
 
 /**
@@ -698,12 +754,35 @@ function buildChecks(
     if (field.resolvedIsArray()) continue;
     const col = resolveColumnName(field, strategy);
     const qcol = quoteCheckCol(col);
-    // Enum membership check.
+    // Enum membership check. An INT-BACKED enum (@intValueMap, design D5) stores
+    // the mapped integers, so the CHECK lists those integers unquoted rather than
+    // the member strings — `IN (0, 5, 9)`, not `IN ('DRAFT', …)`. The members are
+    // still the SSOT: the integers are read THROUGH the map, keyed by member, so a
+    // member with no mapping cannot silently vanish from the constraint.
     if (field.subType === FIELD_SUBTYPE_ENUM) {
       const raw = field.attr(FIELD_ATTR_VALUES);
       if (Array.isArray(raw) && raw.length > 0) {
         const values = raw.map((v) => String(v));
-        const expression = `${qcol} IN (${values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ")})`;
+        const intMap = intValueMapOf(field);
+        let expression: string;
+        if (intMap !== undefined) {
+          // The loader pins key-set-equals-@values (Check 5b) in every port, so every
+          // member resolves. Guard anyway: emitting a partial IN list would silently
+          // reject rows the model considers valid.
+          const ints = values.map((v) => {
+            const n = intMap[v];
+            if (typeof n !== "number") {
+              throw new Error(
+                `field.enum '${field.name}' @intValueMap has no integer for member '${v}' — ` +
+                  `cannot build the CHECK constraint for column '${col}'.`,
+              );
+            }
+            return String(n);
+          });
+          expression = `${qcol} IN (${ints.join(", ")})`;
+        } else {
+          expression = `${qcol} IN (${values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ")})`;
+        }
         checks.push({ name: `${tableName}_${col}_chk`, expression });
       }
     }
@@ -842,11 +921,27 @@ function buildForeignKeys(
 
     // Target columns: prefer explicit multi-field dotted form, else delegate
     // to MetaReferenceIdentity.resolvedTargetPkField (single field → target's
-    // primary identity → "id" fallback).
+    // primary identity → "id" fallback). Each target FIELD name must resolve to
+    // its PHYSICAL column via the target entity's own @column override (e.g. a
+    // PK field `id` with `@column: "Id"`), exactly like fkCols above — the raw
+    // naming strategy alone would emit the logical name and phantom-diff every
+    // FK into that table (expected ["id"] vs actual ["Id"]).
+    // targetEntity may be package-qualified (FQN); findObject is keyed by bare
+    // name — same fallback as resolvedTargetPkField/resolveTargetTable.
+    const targetObj = root.findObject(targetEntity)
+      ?? (targetEntity.includes("::")
+        ? root.findObject(targetEntity.slice(targetEntity.lastIndexOf("::") + 2))
+        : undefined);
     const explicitTargetFields = refChild.targetFields;
-    const refColumns = explicitTargetFields.length > 1
-      ? explicitTargetFields.map((n) => applyColumnNamingStrategy(n, strategy))
-      : [applyColumnNamingStrategy(refChild.resolvedTargetPkField(root) ?? "id", strategy)];
+    const targetFieldNames = explicitTargetFields.length > 1
+      ? explicitTargetFields
+      : [refChild.resolvedTargetPkField(root) ?? "id"];
+    const refColumns = targetFieldNames.map((jsName) => {
+      const targetField = targetObj ? findField(targetObj, jsName) : undefined;
+      return targetField
+        ? resolveColumnName(targetField, strategy)
+        : applyColumnNamingStrategy(jsName, strategy);
+    });
 
     const { onDelete, onUpdate } = resolveReferentialActions(entity, refChild);
     // An explicit @constraintName adopts an existing FK name (e.g. a database
@@ -925,12 +1020,29 @@ function buildColumn(
   };
 
   if (typeof defaultRaw === "string") {
-    // #235: an EMPTY-string default (`@default: ""`) is a real literal default —
-    // codegen emits `.default("")` and the DB gets `DEFAULT ''`, so dropping it here
-    // (a falsy `.length > 0` check) made the column drift forever on sqlite/d1 and
-    // disagree with codegen. Keep it as a literal; only `undefined` means "no default".
-    const isExpr = defaultRaw.length > 0 && EXPR_DEFAULT_PATTERNS.some((re) => re.test(defaultRaw));
-    col.default = { kind: isExpr ? "expr" : "literal", value: defaultRaw };
+    // An INT-BACKED enum's @default names a MEMBER SYMBOL, but the column holds the
+    // mapped integer — emitting `DEFAULT 'DRAFT'` on an `integer` column is
+    // un-appliable DDL. Lower it through the map. The member is already validated
+    // against @values by the loader (FR-011 Check 5), so a miss here is unreachable;
+    // throw rather than silently emit the symbol, which would fail only at apply time.
+    const enumIntMap = field.subType === FIELD_SUBTYPE_ENUM ? intValueMapOf(field) : undefined;
+    if (enumIntMap !== undefined) {
+      const mapped = enumIntMap[defaultRaw];
+      if (typeof mapped !== "number") {
+        throw new Error(
+          `field.enum '${field.name}' @default '${defaultRaw}' has no entry in @intValueMap — ` +
+            `cannot lower the column default for '${col.name}'.`,
+        );
+      }
+      col.default = { kind: "literal", value: String(mapped) };
+    } else {
+      // #235: an EMPTY-string default (`@default: ""`) is a real literal default —
+      // codegen emits `.default("")` and the DB gets `DEFAULT ''`, so dropping it here
+      // (a falsy `.length > 0` check) made the column drift forever on sqlite/d1 and
+      // disagree with codegen. Keep it as a literal; only `undefined` means "no default".
+      const isExpr = defaultRaw.length > 0 && EXPR_DEFAULT_PATTERNS.some((re) => re.test(defaultRaw));
+      col.default = { kind: isExpr ? "expr" : "literal", value: defaultRaw };
+    }
   } else if (typeof defaultRaw === "boolean" || typeof defaultRaw === "number") {
     col.default = { kind: "literal", value: String(defaultRaw) };
   } else {
@@ -978,8 +1090,10 @@ function buildColumn(
  */
 function arrayElementSqlType(field: MetaData): SqlType | undefined {
   switch (field.subType) {
+    // enum[] stores as text[] — membership is app-level (no CHECK — see buildChecks).
+    // An INT-BACKED enum[] (@intValueMap, design D7) stores as integer[] instead.
+    case FIELD_SUBTYPE_ENUM:      return isIntBackedEnum(field) ? { kind: "integer", bits: 32 } : { kind: "text" };
     case FIELD_SUBTYPE_STRING:
-    case FIELD_SUBTYPE_ENUM:      // enum[] stores as text[]; membership is app-level (no CHECK — see buildChecks)
     case FIELD_SUBTYPE_URI:       return { kind: "text" };
     case FIELD_SUBTYPE_UUID:      return { kind: "uuid" };
     case FIELD_SUBTYPE_INT:       return { kind: "integer", bits: 32 };
@@ -1078,7 +1192,33 @@ function subtypeToSqlType(field: MetaData): SqlType {
     // stores as text (the native inet column would reject a not-strictly-valid
     // value at INSERT). ADR-0039: resolving — @lenient may be inherited via extends.
     case FIELD_SUBTYPE_INET:      return field.attr(FIELD_ATTR_LENIENT) === true ? { kind: "text" } : { kind: "inet" };
+    // A string-backed field.enum is a text column with a membership CHECK; an
+    // INT-BACKED one (@intValueMap, design D5) stores the mapped integer instead.
+    // The TS/wire type is the member string either way — only the column differs.
+    case FIELD_SUBTYPE_ENUM:      return isIntBackedEnum(field) ? { kind: "integer", bits: 32 } : { kind: "text" };
     default:                      return { kind: "text" }; // unknown → text fallback
   }
 }
 
+/**
+ * True when this `field.enum` persists as an integer — i.e. it carries an
+ * `@intValueMap` (design D5).
+ *
+ * ADR-0039: RESOLVING (`attr`, not `ownAttr`). Post-#246 a shared (root-level
+ * abstract) enum OWNS the map and consuming fields inherit it — declaring an own
+ * `@intValueMap` against a shared super is `ERR_ENUM_EXTENDS_VALUES_CONFLICT`. So
+ * the inherited case is not an edge case, it is the CANONICAL authoring shape, and
+ * an own-only read here would emit a `text` column for an integer-encoded value on
+ * every consuming field of every shared enum.
+ */
+function isIntBackedEnum(field: MetaData): boolean {
+  return intValueMapOf(field) !== undefined;
+}
+
+/** The resolved `@intValueMap` as a plain record, or undefined when absent. */
+export function intValueMapOf(field: MetaData): Record<string, number> | undefined {
+  const raw = field.attr(FIELD_ATTR_INT_VALUE_MAP);
+  if (raw === undefined || raw === null || typeof raw !== "object") return undefined;
+  return raw as Record<string, number>;
+}
+

package/src/index.ts

@@ -8,11 +8,23 @@
 // See docs/specs/2026-05-11-v0.2-sp4-migrate-ts-design.md.
 
 // Pipeline functions
-export { buildExpectedSchema } from "./expected-schema.js";
+export { buildExpectedSchema, buildExpectedSchemaWithProvenance } from "./expected-schema.js";
+export type { ExpectedSchemaWithProvenance, SchemaProvenance } from "./expected-schema.js";
 export { introspect, introspectPostgres, introspectSqlite } from "./introspect/index.js";
 export { diff } from "./diff/index.js";
 export { collectUnmanagedNames } from "./unmanaged.js";
-export { computeDrift, computeDriftFromActual, type ComputeDriftOptions } from "./drift/drift.js";
+// Per-command scope (`migrate.scope`) — see scope.ts for why the suppression is
+// two-sided and why the pattern engine stays in @metaobjectsdev/sdk.
+export {
+  scopeExpectedSchema,
+  declaredSchemasOf,
+  carryForwardOutOfScope,
+  excludeFromSnapshot,
+  scopedDiffInputs,
+} from "./scope.js";
+export type { ObjectScopePredicate, ScopedExpectedSchema, GovernedScope } from "./scope.js";
+export { qualifiedDbName } from "./qualified-name.js";
+export { computeDrift, computeDriftFromActual, type ComputeDriftOptions, type DriftResult } from "./drift/drift.js";
 export { classifyDrift, driftAgainstSnapshot } from "./drift/classify.js";
 export type { DriftClassification } from "./drift/classify.js";
 export { emit } from "./emit/index.js";
@@ -100,6 +112,10 @@ export {
 export { verifyReplay } from "./verify/replay.js";
 export type { VerifyReplayArgs, VerifyReplayResult } from "./verify/replay.js";
 
+// An empty in-process database to replay a committed chain into (#313).
+export { openReplayEngine } from "./verify/replay-engine.js";
+export type { ReplayEngine } from "./verify/replay-engine.js";
+
 // Wrangler config helpers
 export {
   findWranglerConfig,

package/src/qualified-name.ts

@@ -0,0 +1,22 @@
+// The ONE qualified-physical-name form: `<schema>.<name>`, with an absent schema
+// normalized to the Postgres default.
+//
+// Three things must key DB objects identically or the diff silently disagrees with
+// itself: `diff`'s table/view identity maps, the declared-`@unmanaged` exclusion set
+// (`collectUnmanagedNames`), and the out-of-scope exclusion set (`scopeExpectedSchema`).
+// The last two are ACT-side suppressions matched against the first, so a name built a
+// second way — a different default schema, a different separator — reads as "not
+// suppressed" and the object it names comes back as a proposed DROP. One function.
+//
+// SQLite has no schema concept, so every SQLite object normalizes to the same prefix.
+// That is harmless: it is a constant, and the un-prefixed names were already unique.
+
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+
+/** `<schema>.<name>`; an absent schema is the Postgres default (`public`). The
+ *  parameter accepts an EXPLICIT `undefined` schema (not only an omitted key) so a
+ *  caller holding a `string | undefined` can pass it straight through under
+ *  `exactOptionalPropertyTypes` — the two spell the same thing here. */
+export function qualifiedDbName(obj: { name: string; schema?: string | undefined }): string {
+  return `${obj.schema ?? DEFAULT_DB_SCHEMA_POSTGRES}.${obj.name}`;
+}

package/src/scope.ts

@@ -0,0 +1,261 @@
+// Per-command scope — narrowing a migrate/verify run to the objects it governs.
+//
+// A consumer sharing a database with another owner declares
+// `"migrate": { "scope": ["acme::platform::**"] }`. Tables and views outside that
+// scope are neither created nor dropped, which takes TWO suppressions:
+//
+//   1. drop them from the EXPECTED side, so nothing is created or altered;
+//   2. suppress the same names on the ACTUAL side (via `diff`'s `unmanagedNames`,
+//      the seam `@unmanaged` already uses), so nothing is dropped.
+//
+// Doing only (1) is strictly worse than doing nothing: every out-of-scope table that
+// EXISTS in the database becomes a proposed `DROP TABLE` — the precise hazard this
+// feature exists to remove. `scopeExpectedSchema` therefore returns both halves and
+// callers must thread `outOfScope` into the diff.
+//
+// There is a THIRD half, and it is the one that bites hardest when the scope is
+// wrong. `diff` derives its SCHEMA scope from the schemas the expected side
+// mentions, falling back to "no schema scoping at all" when expected is empty (the
+// legacy whole-DB path for a project with no model). A scope matching NOTHING
+// empties `expected`, reaches that fallback, and every actual table in every schema
+// becomes a drop candidate — another owner's included, which was never in `expected`
+// so it has no provenance and never lands in `outOfScope`. Narrowing must never
+// WIDEN. `declaredSchemas` below reports the UNSCOPED model's schemas so callers can
+// pin `diff`'s `scopeSchemas` to a property of the whole model, which `migrate.scope`
+// then cannot move in either direction.
+//
+// THE RULE THAT FOLLOWS FROM THAT, stated once because it is easy to read the other
+// way: **a scope narrows which OBJECTS the tool governs, never which SCHEMAS it is
+// allowed to see.** Pinning `scopeSchemas` to the unscoped model means a scope that
+// excludes every declared object in schema `X` leaves `X` in scope, so another
+// owner's UNDECLARED table in `X` stays a drop candidate — exactly as it would be on
+// an unscoped run of the same model. That is deliberate: a schema this model
+// declares into is a schema this model manages, and deriving the schema set from the
+// survivors instead is precisely the inversion above. Declaring a scope is not a way
+// to hand a schema over; removing the objects from the model is.
+//
+// `scopedDiffInputs` exists so no caller has to remember any of this: it returns all
+// three obligations as one object, and every scoped `diff` call goes through it.
+
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+import type { DiffArgs } from "./diff/index.js";
+import type { ExpectedSchemaWithProvenance } from "./expected-schema.js";
+import { qualifiedDbName } from "./qualified-name.js";
+import type { SchemaSnapshot } from "./types.js";
+
+/**
+ * Decides whether an object's fully-qualified name (`resolutionKey()`) is governed
+ * by this run. Supplied by the caller as a PREDICATE so migrate-ts never carries a
+ * second implementation of the scope-pattern grammar — `matchesScope` in
+ * `@metaobjectsdev/sdk` is the only one, and the CLI adapts a compiled scope to
+ * this seam.
+ */
+export type ObjectScopePredicate = (fqn: string) => boolean;
+
+export interface ScopedExpectedSchema {
+  /** The expected schema narrowed to the governed objects. */
+  snapshot: SchemaSnapshot;
+  /**
+   * Qualified physical names (`<schema>.<name>`) of the tables and views removed
+   * above. Reaches `diff`'s `unmanagedNames` (MERGED with `collectUnmanagedNames`,
+   * never replacing it) so the actual side is suppressed too — `scopedDiffInputs`
+   * does that merge; see the module header for why omitting it inverts the feature.
+   */
+  outOfScope: string[];
+  /**
+   * The database schemas the UNSCOPED model declares, for `diff`'s `scopeSchemas`.
+   * `scopedDiffInputs` threads it — see the module header: without it a scope
+   * matching nothing hands `diff` an empty expected side, which it reads as "no
+   * model, govern the whole database".
+   *
+   * `undefined` when no predicate was supplied (so `diff` derives its own set from
+   * an untouched `expected`, exactly as before — an unscoped project's arguments are
+   * unchanged) and also when the unscoped model declares no tables or views at all
+   * (nothing to derive from; `diff`'s legacy whole-DB fallback is preserved).
+   */
+  declaredSchemas?: string[];
+}
+
+/**
+ * Carry an out-of-scope object forward into the snapshot a run is about to commit.
+ *
+ * The committed snapshot is built from the metadata-expected schema, which a scoped
+ * run has already narrowed — so accepting a scoped run DELETES every out-of-scope
+ * entry the previous snapshot held. Widening or removing `migrate.scope` later then
+ * proposes `CREATE TABLE` for a table that exists, and the migration fails at apply.
+ *
+ * `prior` is the snapshot (or introspected schema) the run diffed against, and the
+ * entries taken from it are exactly the ones this run excluded — nothing else is
+ * carried, so a table the model never declared is unaffected either way. An empty
+ * `outOfScope` returns the SAME object, so an unscoped run commits a byte-identical
+ * snapshot.
+ */
+export function carryForwardOutOfScope(
+  next: SchemaSnapshot,
+  prior: SchemaSnapshot,
+  outOfScope: readonly string[],
+): SchemaSnapshot {
+  if (outOfScope.length === 0) return next;
+  const excluded = new Set(outOfScope);
+  return {
+    ...next,
+    tables: [...next.tables, ...splitOnName(prior.tables, excluded).named],
+    views: [...next.views, ...splitOnName(prior.views, excluded).named],
+  };
+}
+
+/**
+ * Drop the out-of-scope entries from a COMMITTED SNAPSHOT, producing the same
+ * three-part shape `scopeExpectedSchema` produces so the result can go straight
+ * through {@link scopedDiffInputs}.
+ *
+ * `verify`'s committed-snapshot gate (#292) needs this: `unmanagedNames` suppresses
+ * only the ACTUAL side, which is right when the expected side is the metadata (it is
+ * already scoped) and wrong here, where the expected side IS the snapshot — a
+ * snapshot written before the scope was declared still carries the other owner's
+ * tables, and leaving them in reports a phantom disagreement about an object this
+ * consumer does not manage.
+ *
+ * `governed` is the scope decision the caller's drift comparison already made — pass
+ * the `DriftResult` itself, which satisfies this shape. Taking `declaredSchemas`
+ * from there rather than re-deriving it from the snapshot is what closes the last
+ * whole-database door: a snapshot that is present but EMPTY (a never-migrated
+ * project) declares no schemas at all, so deriving from it hands `diff` nothing and
+ * reaches its "no model, govern the whole database" fallback — the very inversion
+ * this module exists to prevent, at the one call site that was still re-deriving.
+ *
+ * An empty `outOfScope` returns the SAME snapshot object with no schema pin, so an
+ * unscoped project's `diff` arguments are byte-for-byte what they always were.
+ */
+export function excludeFromSnapshot(
+  snapshot: SchemaSnapshot,
+  governed: GovernedScope,
+): ScopedExpectedSchema {
+  if (governed.outOfScope.length === 0) return { snapshot, outOfScope: [] };
+  const excluded = new Set(governed.outOfScope);
+  const declared = governed.declaredSchemas ?? declaredSchemasOf(snapshot);
+  return {
+    snapshot: {
+      ...snapshot,
+      tables: splitOnName(snapshot.tables, excluded).rest,
+      views: splitOnName(snapshot.views, excluded).rest,
+    },
+    outOfScope: [...governed.outOfScope],
+    declaredSchemas: [...declared],
+  };
+}
+
+/** The scope decision a run made, as `DriftResult` reports it. */
+export interface GovernedScope {
+  /** Qualified physical names (`<schema>.<name>`) the run does not govern. */
+  readonly outOfScope: readonly string[];
+  /** The schemas the run governs — `ScopedExpectedSchema.declaredSchemas`. */
+  readonly declaredSchemas?: readonly string[] | undefined;
+}
+
+/**
+ * Partition `objs` on whether `qualifiedDbName(o)` is in `names`.
+ *
+ * `carryForwardOutOfScope` wants the `named` half (carry the excluded entries
+ * forward) and `excludeFromSnapshot` wants the `rest` half (drop them). They are
+ * exact complements over the same key function, so they share one traversal rather
+ * than two filters that could come to key differently.
+ */
+function splitOnName<T extends { name: string; schema?: string }>(
+  objs: readonly T[],
+  names: ReadonlySet<string>,
+): { named: T[]; rest: T[] } {
+  const named: T[] = [];
+  const rest: T[] = [];
+  for (const o of objs) (names.has(qualifiedDbName(o)) ? named : rest).push(o);
+  return { named, rest };
+}
+
+/**
+ * The three `diff` arguments a scoped run owes, as ONE value.
+ *
+ * The module header lists them as three separate obligations, and five call sites
+ * re-derived them by hand — one of which had already drifted into its own guard.
+ * Every scoped `diff` call is now
+ * `diff({ ...scopedDiffInputs(scoped, collectUnmanagedNames(metadata)), actual, ... })`,
+ * so the rule is enforced by the type rather than by the comment.
+ *
+ * `unmanaged` is the `@unmanaged`-declared set (`collectUnmanagedNames`); it is
+ * MERGED with `outOfScope`, never replaced by it — both must reach `diff`.
+ * `scopeSchemas` is omitted entirely when the run narrowed nothing, so an unscoped
+ * project's arguments are unchanged.
+ */
+export function scopedDiffInputs(
+  scoped: ScopedExpectedSchema,
+  unmanaged: readonly string[],
+): Pick<DiffArgs, "expected" | "unmanagedNames" | "scopeSchemas"> {
+  return {
+    expected: scoped.snapshot,
+    unmanagedNames: [...unmanaged, ...scoped.outOfScope],
+    ...(scoped.declaredSchemas !== undefined ? { scopeSchemas: scoped.declaredSchemas } : {}),
+  };
+}
+
+/**
+ * The distinct database schemas a snapshot's tables and views sit in, absent
+ * normalized to the Postgres default — the value `diff` derives for itself when no
+ * `scopeSchemas` is supplied. The ONE definition: any caller narrowing an expected
+ * side must pin `diff`'s schema scope to the UNNARROWED snapshot's schemas, and a
+ * second encoding of "absent means public" here would silently disagree with the
+ * one inside `diff`.
+ *
+ * Empty in ⇒ empty out, which callers translate to "pass nothing", preserving
+ * `diff`'s legacy whole-database fallback for a genuinely empty model.
+ */
+export function declaredSchemasOf(snapshot: SchemaSnapshot): string[] {
+  return [
+    ...new Set(
+      [...snapshot.tables, ...snapshot.views].map(
+        (o) => o.schema ?? DEFAULT_DB_SCHEMA_POSTGRES,
+      ),
+    ),
+  ].sort();
+}
+
+/**
+ * Narrow an expected schema to the objects inside `inScope`.
+ *
+ * An undefined predicate returns the input untouched — the SAME snapshot object,
+ * not an equal copy — so a project that declares no `migrate.scope` reaches the
+ * diff, the emitter and the committed snapshot through an unchanged value.
+ *
+ * A table or view with NO recorded provenance is KEPT. Scope decides on the
+ * declaring object's FQN, and an object whose FQN is unknown was never proven to be
+ * anyone else's; dropping it would silently un-manage it (and, worse, suppressing
+ * its name on the actual side would hide real drift).
+ */
+export function scopeExpectedSchema(
+  built: ExpectedSchemaWithProvenance,
+  inScope: ObjectScopePredicate | undefined,
+): ScopedExpectedSchema {
+  if (inScope === undefined) return { snapshot: built.snapshot, outOfScope: [] };
+
+  // Computed from `built.snapshot` — the UNSCOPED side — deliberately, and before
+  // the filter below runs. Deriving it from the survivors would reproduce exactly
+  // the defect this exists to close.
+  const declared = declaredSchemasOf(built.snapshot);
+
+  const outOfScope: string[] = [];
+  const governed = <T extends { name: string; schema?: string }>(obj: T): boolean => {
+    const qualified = qualifiedDbName(obj);
+    const fqn = built.provenance.get(qualified);
+    if (fqn === undefined || inScope(fqn)) return true;
+    outOfScope.push(qualified);
+    return false;
+  };
+
+  return {
+    snapshot: {
+      ...built.snapshot,
+      tables: built.snapshot.tables.filter(governed),
+      views: built.snapshot.views.filter(governed),
+    },
+    outOfScope,
+    ...(declared.length > 0 ? { declaredSchemas: declared } : {}),
+  };
+}