@prisma-next/family-sql 0.14.0-dev.49 → 0.14.0-dev.50

package/src/core/control-instance.ts

@@ -1,10 +1,8 @@
 import type {
   Contract,
   ContractMarkerRecord,
-  ControlPolicy,
   LedgerEntryRecord,
 } from '@prisma-next/contract/types';
-import { effectiveControlPolicy } from '@prisma-next/contract/types';
 import type {
   TargetBoundComponentDescriptor,
   TargetDescriptor,
@@ -13,6 +11,7 @@ import type {
   ControlFamilyInstance,
   ControlStack,
   CoreSchemaView,
+  DiffSubjectGranularity,
   MigrationPlanOperation,
   OperationPreview,
   OperationPreviewCapable,
@@ -25,7 +24,6 @@ import type {
 } from '@prisma-next/framework-components/control';
 import {
   APP_SPACE_ID,
-  dispositionForCategory,
   SchemaTreeNode,
   VERIFY_CODE_HASH_MISMATCH,
   VERIFY_CODE_MARKER_MISSING,
@@ -52,8 +50,13 @@ import type {
   SqlControlTargetDescriptor,
   SqlDescribedContractSpace,
 } from './control-target-descriptor';
+import {
+  classifyDiffEntityKind,
+  classifyDiffSubjectGranularity,
+  verifySqlSchemaByDiff,
+} from './diff/schema-verify';
 import { SqlContractSerializer } from './ir/sql-contract-serializer';
-import type { DiffDatabaseSchemaInput } from './migrations/schema-differ';
+import type { SqlSchemaDiffFn } from './migrations/schema-differ';
 import type {
   SqlControlAdapterDescriptor,
   SqlControlExtensionDescriptor,
@@ -234,6 +237,26 @@ export interface SqlControlFamilyInstance
     readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
   }): VerifyDatabaseSchemaResult;
 
+  /**
+   * Classifies a diff issue's subject granularity on demand, resolved from
+   * its node's `nodeKind` via the target's classifier. Satisfies the
+   * {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable}
+   * capability that framework consumers spanning contract spaces (the
+   * migration aggregate's unclaimed-elements sweep) detect via
+   * `hasSchemaSubjectClassifier` and call instead of reading family/target
+   * node vocabulary. Nothing is stamped on the issue or the node.
+   */
+  classifySubjectGranularity(issue: SchemaDiffIssue): DiffSubjectGranularity | undefined;
+
+  /**
+   * Classifies a diff issue's subject storage `entityKind` on demand,
+   * resolved from its node's `nodeKind` via the target's classifier —
+   * sibling of `classifySubjectGranularity` above, part of the same
+   * {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable}
+   * capability. Nothing is stamped on the issue or the node.
+   */
+  classifyEntityKind(issue: SchemaDiffIssue): string | undefined;
+
   sign(options: {
     readonly driver: SqlControlDriverInstance<string>;
     readonly contract: unknown;
@@ -542,6 +565,29 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     SqlControlTargetDescriptor<TTargetId, unknown>,
     'reading the optional target-descriptor inferPslContract hook'
   >(target).inferPslContract;
+  // The full-tree node diff the verify VERDICT derives from. Read lazily so
+  // construction-only stub descriptors (schema-view tests) keep working; the
+  // throw happens at verify time.
+  const diffSchema = blindCast<
+    { readonly diffSchema?: SqlSchemaDiffFn },
+    'reading the target-descriptor diffSchema hook'
+  >(target).diffSchema;
+  // The target's nodeKind → granularity classifier, resolved on demand by the
+  // verdict and by the instance's `classifySubjectGranularity` method below —
+  // never stamped onto an issue. Read lazily for the same
+  // construction-only-stub reason as `diffSchema`; the throw happens at call
+  // time.
+  const targetGranularityOf = blindCast<
+    { readonly classifySubjectGranularity?: (nodeKind: string) => DiffSubjectGranularity },
+    'reading the target-descriptor classifySubjectGranularity hook'
+  >(target).classifySubjectGranularity;
+  // The target's nodeKind → storage entityKind classifier — sibling of
+  // `targetGranularityOf` above, read the same lazy way for the same
+  // construction-only-stub reason.
+  const targetEntityKindOf = blindCast<
+    { readonly classifyEntityKind?: (nodeKind: string) => string | undefined },
+    'reading the target-descriptor classifyEntityKind hook'
+  >(target).classifyEntityKind;
   // `contract infer` needs each extension pack's already-assembled contract,
   // carried as-is (no merging — that is the contract-spaces machinery's
   // concern), paired with the `spaceId` its descriptor was registered under
@@ -554,24 +600,6 @@ export function createSqlFamilyInstance<TTargetId extends string>(
         ? [{ spaceId: extension.id, contract: extension.contractSpace.contractJson }]
         : [],
   );
-  // The combined database-schema verify is a required target-descriptor
-  // operation: every SQL target provides it, wrapping the same comparison
-  // `diffDatabaseSchema` runs in the verify envelope plus the pass/warn/fail
-  // tree the CLI renders. Read it off the descriptor like the other
-  // target-owned hooks.
-  const verifyDatabaseSchema = blindCast<
-    {
-      readonly verifyDatabaseSchema?: (
-        input: DiffDatabaseSchemaInput,
-      ) => VerifyDatabaseSchemaResult;
-    },
-    'reading the required target-descriptor verifyDatabaseSchema hook'
-  >(target).verifyDatabaseSchema;
-  if (!verifyDatabaseSchema) {
-    throw new Error(
-      `SQL target "${target.targetId}" is missing the required verifyDatabaseSchema descriptor operation`,
-    );
-  }
   const deserializeWithTargetSerializer = (contractOrJson: unknown): Contract<SqlStorage> => {
     const serializer = targetSerializer ?? new SqlContractSerializer();
     const json =
@@ -729,42 +757,61 @@ export function createSqlFamilyInstance<TTargetId extends string>(
       readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
     }): VerifyDatabaseSchemaResult {
       const contract = deserializeWithTargetSerializer(options.contract) as Contract<SqlStorage>;
-      // Verify is a thin consumer of the target's black-box comparison: it
-      // introspects the actual schema (already in `options.schema`), calls the
-      // target's required `verifyDatabaseSchema`, and rejects when a surviving
-      // issue is a failure. It composes no diffing itself and is blind to how
-      // the comparison works.
-      const sqlResult = verifyDatabaseSchema({
+      if (!diffSchema) {
+        throw new Error(
+          `SQL target "${target.targetId}" is missing the required diffSchema descriptor operation`,
+        );
+      }
+      if (!targetGranularityOf) {
+        throw new Error(
+          `SQL target "${target.targetId}" is missing the required classifySubjectGranularity descriptor operation`,
+        );
+      }
+      // THE VERDICT: the target's full-tree node diff, graded by the
+      // family's post-diff filters (strict gating + control-policy
+      // disposition), plus the codec verifyType hook findings. The result
+      // is issue-based — `ok` holds exactly when both issue lists are empty.
+      return verifySqlSchemaByDiff({
         contract,
         schema: options.schema,
         strict: options.strict,
-        typeMetadataRegistry,
         frameworkComponents: options.frameworkComponents,
+        diffSchema,
+        granularityOf: targetGranularityOf,
       });
-      // Control-policy suppression of the structural (e.g. RLS policy) diff
-      // issues is a verify-side post-step — the combined diff returns them
-      // ownership-filtered, and a suppressed control policy drops them here.
-      const schemaDiffIssues = filterSchemaDiffIssues(
-        sqlResult.schema.schemaDiffIssues,
-        contract.defaultControlPolicy,
-      );
-      const relationalFails = sqlResult.schema.counts.fail;
-      if (schemaDiffIssues.length === 0) {
-        if (schemaDiffIssues === sqlResult.schema.schemaDiffIssues) return sqlResult;
-        return { ...sqlResult, schema: { ...sqlResult.schema, schemaDiffIssues } };
+    },
+
+    /**
+     * Classifies a diff issue's subject granularity on demand, by resolving
+     * its node's `nodeKind` through the target's classifier — the
+     * {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable}
+     * capability. Framework consumers spanning contract spaces (the
+     * migration aggregate's unclaimed-elements sweep) detect and call this
+     * instead of reaching into the concrete schema-IR node, which they
+     * cannot read; nothing is stamped on the issue or the node.
+     */
+    classifySubjectGranularity(issue: SchemaDiffIssue): DiffSubjectGranularity | undefined {
+      if (!targetGranularityOf) {
+        throw new Error(
+          `SQL target "${target.targetId}" is missing the required classifySubjectGranularity descriptor operation`,
+        );
       }
-      const totalFails = relationalFails + schemaDiffIssues.length;
-      return {
-        ...sqlResult,
-        ok: false,
-        code: sqlResult.code ?? 'PN-RUN-3010',
-        summary: `Database schema does not satisfy contract (${totalFails} failure${totalFails === 1 ? '' : 's'})`,
-        schema: {
-          ...sqlResult.schema,
-          schemaDiffIssues,
-          counts: { ...sqlResult.schema.counts, fail: totalFails },
-        },
-      };
+      return classifyDiffSubjectGranularity(issue, targetGranularityOf);
+    },
+    /**
+     * Classifies a diff issue's subject storage `entityKind` on demand, by
+     * resolving its node's `nodeKind` through the target's classifier —
+     * the sibling of `classifySubjectGranularity` above, and part of the
+     * same {@link import('@prisma-next/framework-components/control').SchemaSubjectClassifierCapable}
+     * capability.
+     */
+    classifyEntityKind(issue: SchemaDiffIssue): string | undefined {
+      if (!targetEntityKindOf) {
+        throw new Error(
+          `SQL target "${target.targetId}" is missing the required classifyEntityKind descriptor operation`,
+        );
+      }
+      return classifyDiffEntityKind(issue, targetEntityKindOf);
     },
     async sign(options: {
       readonly driver: SqlControlDriverInstance<string>;
@@ -1115,31 +1162,3 @@ export function createSqlFamilyInstance<TTargetId extends string>(
     },
   };
 }
-
-/**
- * Filters the structural schema-diff issues (from `diffDatabaseSchema`) through
- * the contract's `defaultControlPolicy`. Issues whose outcome maps to a suppressed
- * category under the effective policy are removed. This mirrors the control-policy
- * filtering applied by `verifySqlSchema` for table/column-level findings.
- *
- * Outcome → category mapping:
- * - `'extra'`    → `'extraAuxiliary'`    (an extra auxiliary entity, e.g. an RLS policy)
- * - `'missing'`  → `'declaredMissing'`
- * - `'mismatch'` → `'declaredIncompatible'`
- */
-export function filterSchemaDiffIssues(
-  issues: readonly SchemaDiffIssue[],
-  defaultControlPolicy: ControlPolicy | undefined,
-): readonly SchemaDiffIssue[] {
-  if (issues.length === 0) return issues;
-  const policy = effectiveControlPolicy(undefined, defaultControlPolicy);
-  return issues.filter((issue) => {
-    const category =
-      issue.outcome === 'extra'
-        ? ('extraAuxiliary' as const)
-        : issue.outcome === 'missing'
-          ? ('declaredMissing' as const)
-          : ('declaredIncompatible' as const);
-    return dispositionForCategory(policy, category) !== 'suppress';
-  });
-}

package/src/core/control-target-descriptor.ts

@@ -1,6 +1,7 @@
 import type { Contract } from '@prisma-next/contract/types';
 import type {
   ContractSerializer,
+  DiffSubjectGranularity,
   MigratableTargetDescriptor,
   SchemaVerifier,
 } from '@prisma-next/framework-components/control';
@@ -10,7 +11,7 @@ import type { SqlOperationDescriptors } from '@prisma-next/sql-operations';
 import type { SqlSchemaIR, SqlSchemaIRNode } from '@prisma-next/sql-schema-ir/types';
 import type { SqlControlAdapter } from './control-adapter';
 import type { SqlControlFamilyInstance } from './control-instance';
-import type { SqlDiffDatabaseSchema, SqlVerifyDatabaseSchema } from './migrations/schema-differ';
+import type { SqlSchemaDiffFn } from './migrations/schema-differ';
 import type { SqlMigrationPlanner, SqlMigrationRunner } from './migrations/types';
 
 /**
@@ -62,22 +63,36 @@ export interface SqlControlTargetDescriptor<
     describedContracts?: readonly SqlDescribedContractSpace[],
   ) => PslDocumentAst;
   /**
-   * The single combined database-schema diff of two derived representations —
-   * the target's black-box comparison. Every SQL target provides it (Postgres
-   * returns relational + policy issues; SQLite returns relational only). It is
-   * schema logic on the target, not database I/O, so it lives here rather than
-   * on the control adapter. How it computes the two issue sets is private.
-   * See {@link SqlDiffDatabaseSchema} / {@link SqlVerifyDatabaseSchema}.
+   * The full-tree node diff the family verify verdict derives from —
+   * expected-tree derivation, pre-diff normalization, the generic differ,
+   * and ownership scoping, all target-side. The family applies strict
+   * gating + control-policy disposition over the returned issues; verify
+   * rejects when a surviving issue is a failure.
    */
-  readonly diffDatabaseSchema: SqlDiffDatabaseSchema;
+  readonly diffSchema: SqlSchemaDiffFn;
   /**
-   * The same combined comparison as {@link diffDatabaseSchema}, wrapped in the
-   * verify envelope (`ok`/`summary`/`code`/`target`/`timings`) plus the
-   * pass/warn/fail tree the CLI renders. Verify calls this instead of
-   * `diffDatabaseSchema` so the relational walk that produces the tree runs
-   * once per verify, not once for the diff and again for the tree.
+   * Classifies a diff-tree node's `nodeKind` into its framework-neutral
+   * {@link DiffSubjectGranularity} — the target owns the full node vocabulary
+   * that appears in its diff tree (its own kinds plus the relational kinds it
+   * delegates to), so it is the one place that can resolve this. The family
+   * verdict calls it inline per issue (never stamping the result); the
+   * framework aggregate's unclaimed-elements sweep reaches the same
+   * classifier via the family instance's `classifySubjectGranularity`
+   * capability.
    */
-  readonly verifyDatabaseSchema: SqlVerifyDatabaseSchema;
+  readonly classifySubjectGranularity: (nodeKind: string) => DiffSubjectGranularity;
+  /**
+   * Classifies a diff-tree node's `nodeKind` into its storage `entityKind` —
+   * the same vocabulary the contract storage's `entries` dictionary keys use
+   * (e.g. `'table'`). Sibling of `classifySubjectGranularity`, resolved the
+   * same way: the target owns the full node vocabulary, so it is the one
+   * place that can resolve this. `undefined` for a node kind with no
+   * storage entity of its own (a column, an index, …). The framework
+   * aggregate's unclaimed-elements sweep reaches this via the family
+   * instance's `classifyEntityKind` capability, so it never hardcodes a
+   * family entity kind.
+   */
+  readonly classifyEntityKind: (nodeKind: string) => string | undefined;
   createPlanner(adapter: SqlControlAdapter<TTargetId>): SqlMigrationPlanner<TTargetDetails>;
   createRunner(family: SqlControlFamilyInstance): SqlMigrationRunner<TTargetDetails>;
 }

package/src/core/diff/diff-tree-normalization.ts

@@ -0,0 +1,211 @@
+/**
+ * ⚠️ ACCEPTED-UNDER-PROTEST DEBT — DELETE IN SLICE 2.6 (`unify-unique-and-index-nodes`).
+ *
+ * A unique constraint IS a unique index. This slice modeled uniques and indexes
+ * as two separate node kinds (`SqlUniqueIR` vs `SqlIndexIR` — even though
+ * `SqlIndexIR` already carries `unique: boolean`), so the strict-by-kind differ
+ * cannot pair a contract unique with a live unique index. This whole file
+ * exists only to reconcile those two representations after the fact — it
+ * should not exist.
+ *
+ * The fix — delete `SqlUniqueIR`, model unique enforcement as
+ * `SqlIndexIR { unique: true }` on both derivation and introspection, and
+ * delete `diff-tree-normalization.ts` — is specified in
+ * `projects/postgres-rls/slices/unify-unique-and-index-nodes/spec.md` and
+ * scheduled as the very next slice. Do NOT extend this.
+ */
+
+/**
+ * Pre-diff tree normalization: adjustments to the actual/expected trees the
+ * generic differ (`diffSchemas`) runs over, so legacy semantic-equivalence
+ * rules (a unique constraint satisfied by a unique index, an FK schema
+ * segment that differs only in spelling) surface as same-kind node pairs
+ * instead of spurious drift.
+ */
+
+import {
+  SqlForeignKeyIR,
+  SqlIndexIR,
+  SqlSchemaIR,
+  SqlTableIR,
+  SqlUniqueIR,
+} from '@prisma-next/sql-schema-ir/types';
+
+// ============================================================================
+// Semantic satisfaction — derivation-side normalization of the actual tree
+// ============================================================================
+
+export interface SemanticSatisfactionInput {
+  readonly expectedUniques: readonly SqlUniqueIR[];
+  readonly expectedIndexes: readonly SqlIndexIR[];
+  readonly actualUniques: readonly SqlUniqueIR[];
+  readonly actualIndexes: readonly SqlIndexIR[];
+}
+
+export interface SemanticSatisfactionResult {
+  readonly actualUniques: readonly SqlUniqueIR[];
+  readonly actualIndexes: readonly SqlIndexIR[];
+}
+
+function sameColumns(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((c, i) => c === b[i]);
+}
+
+/**
+ * Adjusts a table pair's ACTUAL unique/index child lists so the legacy
+ * walk's cross-kind semantic satisfaction materializes as same-kind node
+ * pairs for the differ (the differ pairs strictly by id, so a `unique:`
+ * node can never pair with an `index:` node). Three legacy rules, ported
+ * from `isUniqueConstraintSatisfied` / `isIndexSatisfied` and the
+ * strict-extras loops of the retired relational walk:
+ *
+ * 1. A contract unique satisfied by a live unique INDEX: the actual index
+ *    node is reclassified as a unique node (it pairs with the expected
+ *    unique and stops being a candidate extra).
+ * 2. A contract index (with no type/options demands) satisfied by a live
+ *    unique CONSTRAINT: a same-kind actual index node is synthesized so
+ *    the expected index pairs — the unique constraint itself stays (the
+ *    legacy strict-extras loop still reports it as an undeclared unique).
+ * 3. Live unique indexes are never extras in the legacy walk (its
+ *    strict-extras loop skips `unique: true` rows), so any remaining
+ *    actual unique-index node with no expected index counterpart is
+ *    dropped rather than surfacing as `not-expected`.
+ */
+export function resolveSemanticSatisfaction(
+  input: SemanticSatisfactionInput,
+): SemanticSatisfactionResult {
+  let actualIndexes = [...input.actualIndexes];
+  const actualUniques = [...input.actualUniques];
+
+  // Rule 1: reclassify a satisfying unique index as the unique constraint
+  // the contract declared.
+  for (const expectedUnique of input.expectedUniques) {
+    const alreadyPaired = actualUniques.some((u) => sameColumns(u.columns, expectedUnique.columns));
+    if (alreadyPaired) continue;
+    const satisfyingIndex = actualIndexes.find(
+      (idx) => idx.unique && sameColumns(idx.columns, expectedUnique.columns),
+    );
+    if (satisfyingIndex) {
+      actualIndexes = actualIndexes.filter((idx) => idx !== satisfyingIndex);
+      actualUniques.push(
+        new SqlUniqueIR({
+          columns: satisfyingIndex.columns,
+          ...(satisfyingIndex.name !== undefined ? { name: satisfyingIndex.name } : {}),
+        }),
+      );
+    }
+  }
+
+  // Rule 2: synthesize an index node from a satisfying unique constraint.
+  for (const expectedIndex of input.expectedIndexes) {
+    if (expectedIndex.type !== undefined || expectedIndex.options !== undefined) continue;
+    const alreadyPaired = actualIndexes.some((idx) =>
+      sameColumns(idx.columns, expectedIndex.columns),
+    );
+    if (alreadyPaired) continue;
+    const satisfyingUnique = actualUniques.find((u) =>
+      sameColumns(u.columns, expectedIndex.columns),
+    );
+    if (satisfyingUnique) {
+      actualIndexes.push(new SqlIndexIR({ columns: satisfyingUnique.columns, unique: false }));
+    }
+  }
+
+  // Rule 3: remaining unique indexes with no expected counterpart are
+  // invisible to the legacy extras loop — drop them.
+  actualIndexes = actualIndexes.filter(
+    (idx) =>
+      !idx.unique || input.expectedIndexes.some((exp) => sameColumns(exp.columns, idx.columns)),
+  );
+
+  return { actualUniques, actualIndexes };
+}
+
+// ============================================================================
+// Flat-tree helpers (single-schema targets)
+// ============================================================================
+
+/**
+ * Applies {@link resolveSemanticSatisfaction} across a flat table pair set:
+ * every actual table with an expected counterpart gets its unique/index
+ * child lists adjusted; unpaired tables pass through untouched.
+ */
+export function normalizeFlatActualForDiff(
+  expected: SqlSchemaIR,
+  actual: SqlSchemaIR,
+): SqlSchemaIR {
+  const tables: Record<string, SqlTableIR> = {};
+  for (const [name, actualTable] of Object.entries(actual.tables)) {
+    const expectedTable = expected.tables[name];
+    if (expectedTable === undefined) {
+      tables[name] = actualTable;
+      continue;
+    }
+    const adjusted = resolveSemanticSatisfaction({
+      expectedUniques: expectedTable.uniques,
+      expectedIndexes: expectedTable.indexes,
+      actualUniques: actualTable.uniques,
+      actualIndexes: actualTable.indexes,
+    });
+    tables[name] = new SqlTableIR({
+      name: actualTable.name,
+      columns: actualTable.columns,
+      foreignKeys: actualTable.foreignKeys,
+      uniques: adjusted.actualUniques,
+      indexes: adjusted.actualIndexes,
+      ...(actualTable.primaryKey !== undefined ? { primaryKey: actualTable.primaryKey } : {}),
+      ...(actualTable.annotations !== undefined ? { annotations: actualTable.annotations } : {}),
+      ...(actualTable.checks !== undefined ? { checks: actualTable.checks } : {}),
+    });
+  }
+  return new SqlSchemaIR({
+    tables,
+    ...(actual.annotations !== undefined ? { annotations: actual.annotations } : {}),
+  });
+}
+
+/**
+ * Neutralizes the FK schema segment on a flat expected tree so its FK diff
+ * nodes pair with introspected FKs on single-schema targets: the family
+ * converter stamps `referencedSchema` with the contract namespace id
+ * verbatim (the unbound sentinel on non-namespaced targets), while a
+ * single-schema introspection stamps none — resolving both sides to the
+ * empty segment makes the ids meet.
+ */
+export function neutralizeFlatExpectedFkSchemas(expected: SqlSchemaIR): SqlSchemaIR {
+  const tables: Record<string, SqlTableIR> = {};
+  for (const [name, table] of Object.entries(expected.tables)) {
+    if (table.foreignKeys.length === 0) {
+      tables[name] = table;
+      continue;
+    }
+    const foreignKeys = table.foreignKeys.map(
+      (fk) =>
+        new SqlForeignKeyIR({
+          columns: fk.columns,
+          referencedTable: fk.referencedTable,
+          referencedColumns: fk.referencedColumns,
+          ...(fk.referencedSchema !== undefined ? { referencedSchema: fk.referencedSchema } : {}),
+          ...(fk.name !== undefined ? { name: fk.name } : {}),
+          ...(fk.onDelete !== undefined ? { onDelete: fk.onDelete } : {}),
+          ...(fk.onUpdate !== undefined ? { onUpdate: fk.onUpdate } : {}),
+          ...(fk.annotations !== undefined ? { annotations: fk.annotations } : {}),
+          resolvedReferencedNamespace: '',
+        }),
+    );
+    tables[name] = new SqlTableIR({
+      name: table.name,
+      columns: table.columns,
+      foreignKeys,
+      uniques: table.uniques,
+      indexes: table.indexes,
+      ...(table.primaryKey !== undefined ? { primaryKey: table.primaryKey } : {}),
+      ...(table.annotations !== undefined ? { annotations: table.annotations } : {}),
+      ...(table.checks !== undefined ? { checks: table.checks } : {}),
+    });
+  }
+  return new SqlSchemaIR({
+    tables,
+    ...(expected.annotations !== undefined ? { annotations: expected.annotations } : {}),
+  });
+}