@ttt-productions/q-core 0.1.28 → 0.1.30

package/dist/migration-console/manifest.js

@@ -1,41 +1,14 @@
-// The 2.0 cutover manifest: every step of the coordinated migration, in the order the operator runs
-// them, with what each step needs first. The console's callables enforce it — an action whose
-// dependencies are not satisfied refuses to run — and its screen renders it, so both read this one
-// declaration (RULE-STD-ARCH-101, RULE-STD-ENG-002).
-//
-// Four kinds of step:
-//   executable          a console action with its own admin callable: admin-asserted, audited,
-//                       idempotent, resumable by its operation id, and re-runnable after a partial
-//                       failure. A write action offers a dry run; a verification only reads.
-//   productControl      a product callable the operator runs from its own screen (the Fix stats
-//                       actions and the stats check). The console never runs
-//                       a second copy of it; it records the run, checking the run's own evidence.
-//   operatorCheckpoint  external work the app cannot do safely — an export, a credential
-//                       revocation, a manual re-upload. Recorded with the operator's evidence; it
-//                       never claims the console performed it.
-//   cutoverMarker       the console's own record that the product now owns every destination.
-//
-// `dependsOn` is enforced: each id must be satisfied — an executable action's last real run reached
-// its end (a verification's also passed), and a recorded step recorded — before the step runs.
-// `orderedAfter` is display order only: a sequence that is ordering, not a gate.
 import { MIGRATION_ACTION_IDS as A } from './action-ids.js';
+import { SPORT_KEYS } from '../types/sports.js';
+import { MAX_MIGRATION_PAGE_SIZE, MIGRATION_COMMIT_WRITE_LIMIT } from './run-state.js';
 export const MIGRATION_STEP_KIND_KEYS = [
     'executable',
     'productControl',
     'operatorCheckpoint',
     'cutoverMarker',
 ];
-/** What an executable action's pages return: documents written, or records compared. */
 export const MIGRATION_RESULT_KIND_KEYS = ['write', 'verification'];
-/** Where a product control's completion is proven from. */
-export const MIGRATION_CONTROL_EVIDENCE_KEYS = [
-    // The control's `statsOperations` document: a real run, complete, over the whole scope, that
-    // left no game out.
-    'statsOperation',
-    // The validation's report: complete, over everything, with no finding.
-    'statsValidationReport',
-];
-/** The step folder under the migration plan that owns a step's correctness. */
+export const MIGRATION_CONTROL_EVIDENCE_KEYS = ['statsOperation', 'statsValidationReport'];
 export const MIGRATION_OWNING_STEP_KEYS = [
     'auth',
     'q-core',
@@ -46,15 +19,10 @@ export const MIGRATION_OWNING_STEP_KEYS = [
     'secret-management',
     'migration-console',
 ];
-/** The callable that records a product control's run, checking its evidence. */
 export const RECORD_MIGRATION_CONTROL_RUN_CALLABLE = 'adminRecordMigrationControlRun';
-/** The callable that records an operator checkpoint with its evidence. */
 export const RECORD_MIGRATION_CHECKPOINT_CALLABLE = 'adminRecordMigrationCheckpoint';
-/** The callable that records the cutover. */
 export const RECORD_MIGRATION_CUTOVER_CALLABLE = 'adminRecordMigrationCutover';
-/** The callable that reads the console: the cutover marker, the lock, and every step's state. */
 export const GET_MIGRATION_CONSOLE_CALLABLE = 'adminGetMigrationConsole';
-/** The console's callable name for an executable action: `admin` + its verb and its object. */
 export function migrationActionCallableName(id) {
     const [verb = '', object = ''] = id.split('.');
     const capitalize = (word) => word.charAt(0).toUpperCase() + word.slice(1);
@@ -68,6 +36,7 @@ const SINGLE_DOCUMENT = 'One source document; it is never paged.';
 const COPY_RECOVERY = 'Fix the transform and run the copy again; it refuses a live destination.';
 const VERIFY_RECOVERY = 'Repair what it reports, through its copy or its resolution, and verify again.';
 const DELETE_RECOVERY = 'Forward repair only: the retained V1 Firestore export holds what was deleted.';
+const V1_CHECK_RECOVERY = 'Fix what it reports in V1, then run the check again.';
 function copyStep(id, options) {
     return {
         kind: 'executable',
@@ -77,10 +46,12 @@ function copyStep(id, options) {
         destructive: false,
         paged: true,
         defaultPageSize: options.defaultPageSize ?? 100,
+        maxPageSize: options.maxPageSize ?? MAX_MIGRATION_PAGE_SIZE,
         informational: false,
         idempotency: COPY_IDEMPOTENCY,
         resumeKey: options.resumeKey ?? BY_DOCUMENT_ID,
         recovery: COPY_RECOVERY,
+        consumes: [],
         title: options.title,
         summary: options.summary,
         owningStep: options.owningStep,
@@ -97,10 +68,12 @@ function verifyStep(id, options) {
         destructive: false,
         paged: true,
         defaultPageSize: options.defaultPageSize ?? 100,
+        maxPageSize: options.maxPageSize ?? MAX_MIGRATION_PAGE_SIZE,
         informational: options.informational ?? false,
         idempotency: VERIFY_IDEMPOTENCY,
         resumeKey: options.resumeKey ?? BY_DOCUMENT_ID,
-        recovery: VERIFY_RECOVERY,
+        recovery: options.recovery ?? VERIFY_RECOVERY,
+        consumes: [],
         title: options.title,
         summary: options.summary,
         owningStep: options.owningStep,
@@ -108,6 +81,13 @@ function verifyStep(id, options) {
         orderedAfter: options.orderedAfter ?? [],
     };
 }
+function v1CheckStep(id, options) {
+    return verifyStep(id, {
+        dependsOn: [A.checkpointV1FirestoreExport],
+        ...options,
+        recovery: V1_CHECK_RECOVERY,
+    });
+}
 function deleteStep(id, options) {
     return {
         kind: 'executable',
@@ -117,10 +97,12 @@ function deleteStep(id, options) {
         destructive: true,
         paged: true,
         defaultPageSize: options.defaultPageSize ?? 100,
+        maxPageSize: options.maxPageSize ?? MAX_MIGRATION_PAGE_SIZE,
         informational: false,
         idempotency: DELETE_IDEMPOTENCY,
         resumeKey: options.resumeKey ?? BY_DOCUMENT_ID,
         recovery: DELETE_RECOVERY,
+        consumes: options.consumes,
         title: options.title,
         summary: options.summary,
         owningStep: options.owningStep,
@@ -128,7 +110,6 @@ function deleteStep(id, options) {
         orderedAfter: options.orderedAfter ?? [],
     };
 }
-/** The copies whose verifications must pass before the rebuild reads the games they copied. */
 const SOURCE_VERIFICATIONS_FOR_REBUILD = [
     A.verifySportLeagues,
     A.verifyLeagueTeams,
@@ -137,10 +118,6 @@ const SOURCE_VERIFICATIONS_FOR_REBUILD = [
     A.verifySportGames,
     A.verifyGameStats,
 ];
-/**
- * Every copy's verification. Each must pass before the cutover is recorded: a failed or skipped
- * record keeps the migration from being declared complete.
- */
 const COPY_VERIFICATIONS = [
     A.verifyAdminList,
     A.verifyAppConfig,
@@ -167,7 +144,6 @@ const COPY_VERIFICATIONS = [
     A.verifyV1Pictures,
 ];
 export const MIGRATION_CUTOVER_MANIFEST = [
-    // ── Before anything is read ────────────────────────────────────────────────────────────────────
     {
         kind: 'operatorCheckpoint',
         id: A.checkpointV1FirestoreExport,
@@ -180,7 +156,27 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         evidence: 'The export operation name and the bucket path it wrote to.',
         noReturnBoundary: null,
     },
-    // ── Global roles ───────────────────────────────────────────────────────────────────────────────
+    v1CheckStep(A.verifyV1DisplayNamesUnique, {
+        title: 'Check no two V1 display names collide',
+        summary: 'Lists every group of V1 accounts whose display names normalize to one reservation key. The profiles are copied only once it finds none.',
+        owningStep: 'migration-console',
+    }),
+    v1CheckStep(A.verifyV1TextFitsLimits, {
+        title: 'Check every V1 text fits its V2 field',
+        summary: 'Lists every V1 text a copy carries into a capped V2 field that is over the field’s limit or that its schema would change. The copies it covers run only once it finds none.',
+        owningStep: 'migration-console',
+    }),
+    v1CheckStep(A.verifyV1LeagueCapacity, {
+        title: 'Check no V1 league is over capacity',
+        summary: 'Lists every V1 league holding more games or teams than a league may. The leagues, teams, and games are copied only once it finds none.',
+        owningStep: 'migration-console',
+    }),
+    v1CheckStep(A.verifyV1HardwareContractIdsUnique, {
+        title: 'Check no hardware contract id is in both V1 collections',
+        summary: 'Lists every contract id found in both V1 hardware collections. The contracts are copied only once it finds none.',
+        owningStep: 'migration-console',
+        resumeKey: 'The V1 collections in turn, each by document id; the resume key is `{collection}/{id}`.',
+    }),
     copyStep(A.copyAdminList, {
         title: 'Copy the admin and referee rosters',
         summary: 'The `landing/admin` role maps become `_systemData/adminList`, the roster every role check reads.',
@@ -194,17 +190,18 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.copyAdminList],
         resumeKey: SINGLE_DOCUMENT,
     }),
-    // ── App configuration ──────────────────────────────────────────────────────────────────────────
     copyStep(A.copyAppConfig, {
         title: 'Copy the app configuration',
         summary: 'The version and the banner from `landing/base` become `_appConfig/app`, its switches at their open defaults.',
         owningStep: 'q-core',
+        dependsOn: [A.verifyV1TextFitsLimits],
         resumeKey: SINGLE_DOCUMENT,
     }),
     copyStep(A.copyLandingPageConfig, {
         title: 'Copy the landing page copy',
         summary: 'The hero title and the about text become `_appConfig/landingPage`; its picture arrives with the picture carry.',
         owningStep: 'q-core',
+        dependsOn: [A.verifyV1TextFitsLimits],
         resumeKey: SINGLE_DOCUMENT,
     }),
     copyStep(A.copyStatsBeacon, {
@@ -234,11 +231,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.copyStatsBeacon],
         resumeKey: SINGLE_DOCUMENT,
     }),
-    // ── Setup's catalogs ───────────────────────────────────────────────────────────────────────────
     copyStep(A.copyWaiverTemplates, {
         title: 'Copy the waiver templates',
         summary: 'Each template under its id, its wording as version 1.',
         owningStep: 'high-risk-callables',
+        dependsOn: [A.verifyV1TextFitsLimits],
+        maxPageSize: 200,
     }),
     verifyStep(A.verifyWaiverTemplates, {
         title: 'Verify the waiver templates',
@@ -250,6 +248,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Copy the game locations',
         summary: 'Each venue on `landing/admin` becomes a `gameLocations` document under its id; its picture arrives with the picture carry.',
         owningStep: 'q-core',
+        dependsOn: [A.verifyV1TextFitsLimits],
         resumeKey: 'The venues in array order; the resume key is the last venue id.',
     }),
     verifyStep(A.verifyGameLocations, {
@@ -259,11 +258,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.copyGameLocations],
         resumeKey: 'The venues in array order; the resume key is the last venue id.',
     }),
-    // ── Accounts and identity ──────────────────────────────────────────────────────────────────────
     copyStep(A.copyUserProfiles, {
         title: 'Copy the profiles',
         summary: 'Each `users` document becomes its profile and its owner-only private document, every account active.',
         owningStep: 'auth',
+        dependsOn: [A.verifyV1DisplayNamesUnique, A.verifyV1TextFitsLimits],
+        maxPageSize: Math.floor(MIGRATION_COMMIT_WRITE_LIMIT / 2),
     }),
     verifyStep(A.verifyUserProfiles, {
         title: 'Verify the profiles',
@@ -288,6 +288,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'Each pre-Q-Sports career total becomes its sport’s `historicalStats` document.',
         owningStep: 'stat-data-model',
         dependsOn: [A.copyUserProfiles],
+        maxPageSize: Math.floor(MIGRATION_COMMIT_WRITE_LIMIT / SPORT_KEYS.length),
     }),
     verifyStep(A.verifyHistoricalStats, {
         title: 'Verify the historical baselines',
@@ -297,9 +298,10 @@ export const MIGRATION_CUTOVER_MANIFEST = [
     }),
     copyStep(A.deriveReservedDisplayNames, {
         title: 'Reserve the display names',
-        summary: 'One reservation per copied profile; two names that collide are reported for an admin rename.',
+        summary: 'One reservation per copied profile.',
         owningStep: 'auth',
-        dependsOn: [A.copyUserProfiles],
+        dependsOn: [A.copyUserProfiles, A.verifyV1DisplayNamesUnique],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyReservedDisplayNames, {
         title: 'Verify the display-name reservations',
@@ -311,6 +313,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Migrate the public identities in place',
         summary: 'Each `publicUsers` document is rewritten where it sits: epoch timestamps, the recomputed lowercase name, the ghost flag.',
         owningStep: 'q-core',
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyPublicUsers, {
         title: 'Verify the public identities',
@@ -322,7 +325,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Copy the award catalog',
         summary: 'Each award on `landing/admin` becomes an `awardDefinitions` document with its holder count; its badge arrives with the picture carry.',
         owningStep: 'uploads-and-media',
-        dependsOn: [A.copyUserProfiles],
+        dependsOn: [A.copyUserProfiles, A.verifyV1TextFitsLimits],
         resumeKey: 'The awards in array order; the resume key is the last award id.',
     }),
     verifyStep(A.verifyAwardDefinitions, {
@@ -332,11 +335,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.copyAwardDefinitions, A.migratePublicUsers],
         resumeKey: SINGLE_DOCUMENT,
     }),
-    // ── Leagues and teams ──────────────────────────────────────────────────────────────────────────
     copyStep(A.copySportLeagues, {
         title: 'Copy the leagues',
         summary: 'Each league under its id — closed leagues included; its pictures arrive with the picture carry.',
         owningStep: 'q-core',
+        dependsOn: [A.verifyV1LeagueCapacity, A.verifyV1TextFitsLimits],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifySportLeagues, {
         title: 'Verify the leagues',
@@ -348,6 +352,8 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Copy the teams',
         summary: 'Each team under its id, its season lines in its sport’s shape.',
         owningStep: 'q-core',
+        dependsOn: [A.verifyV1LeagueCapacity, A.verifyV1TextFitsLimits],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyLeagueTeams, {
         title: 'Verify the teams',
@@ -360,6 +366,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'Each membership under its compound id, `member` becoming `player`; one whose team was not copied into its league is left behind and reported.',
         owningStep: 'q-core',
         dependsOn: [A.copyLeagueTeams],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyTeamMemberships, {
         title: 'Verify the memberships',
@@ -372,6 +379,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'Each invitation by id; a pending one whose invitee is already on the team is written approved, and a pending one whose team was not copied into its league is left behind and reported.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.copyLeagueTeams, A.copyTeamMemberships],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyTeamInvitations, {
         title: 'Verify the invitations',
@@ -384,6 +392,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'Each request by id; a pending one whose requester is already on the team is written approved, and a pending one whose team was not copied into its league is left behind and reported.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.copyLeagueTeams, A.copyTeamMemberships],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyTeamJoinRequests, {
         title: 'Verify the join requests',
@@ -396,6 +405,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'Each signup under its built id; a signup whose player already joined a team in the league is left behind and reported.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.copyTeamMemberships],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyLeagueFreeAgents, {
         title: 'Verify the free-agent signups',
@@ -403,12 +413,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'high-risk-callables',
         dependsOn: [A.copyLeagueFreeAgents],
     }),
-    // ── Signed waivers and hardware contracts ──────────────────────────────────────────────────────
     copyStep(A.copySignedWaivers, {
         title: 'Copy the signed waivers',
         summary: 'Every signed waiver, a ghost’s included, under its id; its signature file stays where it is.',
         owningStep: 'uploads-and-media',
         dependsOn: [A.copyWaiverTemplates],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifySignedWaivers, {
         title: 'Verify the signed waivers',
@@ -420,7 +430,9 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Copy the hardware loan contracts',
         summary: 'Each contract from both V1 collections under its id; its signature file stays where it is.',
         owningStep: 'high-risk-callables',
+        dependsOn: [A.verifyV1HardwareContractIdsUnique],
         resumeKey: 'The V1 collections in turn, each by document id; the resume key is `{collection}/{id}`.',
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
     }),
     verifyStep(A.verifyHardwareLoanContracts, {
         title: 'Verify the hardware loan contracts',
@@ -436,13 +448,13 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.verifySignedWaivers, A.verifyHardwareLoanContracts],
         resumeKey: 'The signed waivers by id, then the contracts; the resume key is the record path.',
     }),
-    // ── Games ──────────────────────────────────────────────────────────────────────────────────────
     copyStep(A.copyGameRosterPlayers, {
         title: 'Copy the game rosters',
         summary: 'One entry per team per person in each game, from each V1 roster document’s own team and user.',
         owningStep: 'high-risk-callables',
         resumeKey: 'The V1 games by document id; the resume key is the last game id.',
         defaultPageSize: 50,
+        maxPageSize: 50,
     }),
     {
         kind: 'executable',
@@ -452,10 +464,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         destructive: false,
         paged: false,
         defaultPageSize: 1,
+        maxPageSize: MAX_MIGRATION_PAGE_SIZE,
         informational: false,
         idempotency: 'A second resolution of the same line is acknowledged and writes nothing.',
         resumeKey: 'One game, one line; it is never paged.',
         recovery: 'Resolve the line again with the right team, then copy the game again.',
+        consumes: [],
         title: 'Resolve a stat line no roster places',
         summary: 'For a line the game copy stops on, the admin names its team: the missing roster entry is written with its reason, and the game copied again.',
         owningStep: 'stat-data-model',
@@ -466,10 +480,11 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         title: 'Copy the games',
         summary: 'Each V1 game with its stats: the event documents, the rollup, the participation lists by roster entry, and a completed game’s finalized record.',
         owningStep: 'stat-data-model',
-        dependsOn: [A.copyGameRosterPlayers],
+        dependsOn: [A.copyGameRosterPlayers, A.verifyV1LeagueCapacity],
         orderedAfter: [A.resolveUnrosteredStatLine],
         resumeKey: 'The V1 games by document id; a game’s documents commit before its id becomes the resume key.',
         defaultPageSize: 20,
+        maxPageSize: 25,
     }),
     verifyStep(A.verifySportGames, {
         title: 'Verify the game schedules',
@@ -483,6 +498,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'stat-data-model',
         dependsOn: [A.copySportGames],
         defaultPageSize: 20,
+        maxPageSize: 25,
     }),
     {
         kind: 'executable',
@@ -492,10 +508,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         destructive: false,
         paged: true,
         defaultPageSize: 20,
+        maxPageSize: 25,
         informational: false,
         idempotency: 'Each open game is reconciled through the roster core against the copied memberships; a reconciled game changes nothing on a re-run.',
         resumeKey: 'The open games by document id; the resume key is the last game id.',
         recovery: 'Run it again: a game held by another operation is reported and reconciled on the next run.',
+        consumes: [],
         title: 'Reconcile the open games’ rosters',
         summary: 'Each game open at the cutover: stale stat-free entries removed, missing members added.',
         owningStep: 'high-risk-callables',
@@ -509,7 +527,6 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.copyGameRosterPlayers, A.reconcileOpenGameRosters],
         resumeKey: 'The V1 games by document id; the resume key is the last game id.',
     }),
-    // ── Pictures ───────────────────────────────────────────────────────────────────────────────────
     copyStep(A.carryV1Pictures, {
         title: 'Carry the V1 pictures onto the pipeline',
         summary: 'Each league, landing, venue, and award image is staged and accepted through the upload pipeline, which processes and publishes it. A rehearsal reports every source unavailable.',
@@ -529,7 +546,6 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.carryV1Pictures],
         resumeKey: 'By owner kind, then owner id; the resume key is `{ownerKind}:{ownerId}`.',
     }),
-    // ── The ghost names V1 left behind ─────────────────────────────────────────────────────────────
     {
         kind: 'executable',
         id: A.cleanupOrphanGhostPublicUsers,
@@ -538,10 +554,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         destructive: true,
         paged: true,
         defaultPageSize: 100,
+        maxPageSize: 100,
         informational: false,
         idempotency: 'A ghost document is deleted only when nothing references it; a re-run finds nothing further.',
         resumeKey: BY_DOCUMENT_ID,
         recovery: DELETE_RECOVERY,
+        consumes: [],
         title: 'Remove the ghost names nothing references',
         summary: 'Each ghost `publicUsers` document no membership, roster entry, or unvoided stat event names, reported by disposition first. No signed waiver is touched.',
         owningStep: 'high-risk-callables',
@@ -553,7 +571,6 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         ],
         orderedAfter: [],
     },
-    // ── The derived statistics ─────────────────────────────────────────────────────────────────────
     {
         kind: 'productControl',
         id: A.rebuildLeagueStats,
@@ -619,7 +636,6 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'stat-data-model',
         dependsOn: [A.rebuildSportHallOfFame],
     }),
-    // ── The cutover ────────────────────────────────────────────────────────────────────────────────
     {
         kind: 'cutoverMarker',
         id: A.recordCutoverLive,
@@ -631,13 +647,13 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         orderedAfter: [A.verifySportHallOfFame, A.verifySignatureFilesResolvable],
         noReturnBoundary: 'Recording the cutover. It is never undone: every copy refuses a live destination after it.',
     },
-    // ── Cleanup: each delete gated on the verifications its core asserts ───────────────────────────
     deleteStep(A.deleteV1AdminRoles, {
         title: 'Remove the V1 role maps',
         summary: 'The `isAdmin` and `referees` fields on `landing/admin`; the document goes with its last carried row.',
         owningStep: 'auth',
         dependsOn: [A.verifyAdminList],
         resumeKey: SINGLE_DOCUMENT,
+        consumes: [A.copyAdminList, A.verifyAdminList],
     }),
     deleteStep(A.deleteV1LandingBase, {
         title: 'Delete `landing/base`',
@@ -650,12 +666,25 @@ export const MIGRATION_CUTOVER_MANIFEST = [
             A.verifyV1Pictures,
         ],
         resumeKey: SINGLE_DOCUMENT,
+        consumes: [
+            A.copyAppConfig,
+            A.copyLandingPageConfig,
+            A.copyStatsBeacon,
+            A.verifyAppConfig,
+            A.verifyLandingPageConfig,
+            A.verifyStatsBeacon,
+            A.carryV1Pictures,
+            A.verifyV1Pictures,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     deleteStep(A.deleteV1Waivers, {
         title: 'Delete the V1 waiver templates',
         summary: 'The `waivers` collection.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyWaiverTemplates],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copyWaiverTemplates, A.verifyWaiverTemplates, A.verifyV1TextFitsLimits],
     }),
     deleteStep(A.deleteV1GameLocations, {
         title: 'Remove the V1 venues',
@@ -663,6 +692,13 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'q-core',
         dependsOn: [A.verifyGameLocations, A.verifyV1Pictures],
         resumeKey: SINGLE_DOCUMENT,
+        consumes: [
+            A.copyGameLocations,
+            A.verifyGameLocations,
+            A.carryV1Pictures,
+            A.verifyV1Pictures,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     deleteStep(A.deleteV1AwardCatalog, {
         title: 'Remove the V1 award catalog',
@@ -675,42 +711,75 @@ export const MIGRATION_CUTOVER_MANIFEST = [
             A.verifyV1Pictures,
         ],
         resumeKey: SINGLE_DOCUMENT,
+        consumes: [
+            A.copyAwardDefinitions,
+            A.verifyAwardDefinitions,
+            A.carryV1Pictures,
+            A.verifyV1Pictures,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     deleteStep(A.deleteV1Users, {
         title: 'Delete the V1 user documents',
         summary: 'Each `users` document with its historical baselines.',
         owningStep: 'auth',
         dependsOn: [A.verifyUserProfiles, A.verifyHistoricalStats, A.verifyReservedDisplayNames],
+        maxPageSize: 200,
+        consumes: [
+            A.copyUserProfiles,
+            A.verifyUserProfiles,
+            A.copyHistoricalStats,
+            A.verifyHistoricalStats,
+            A.migratePublicUsers,
+            A.verifyPublicUsers,
+            A.verifyV1DisplayNamesUnique,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     deleteStep(A.deleteV1TeamInvites, {
         title: 'Delete the V1 invitations',
         summary: 'The `teamInvites` collection.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyTeamInvitations],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copyTeamInvitations, A.verifyTeamInvitations],
     }),
     deleteStep(A.deleteV1JoinRequests, {
         title: 'Delete the V1 join requests',
         summary: 'The `joinRequests` collection.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyTeamJoinRequests],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copyTeamJoinRequests, A.verifyTeamJoinRequests],
     }),
     deleteStep(A.deleteV1FreeAgentSignups, {
         title: 'Delete the V1 free-agent signups',
         summary: 'The `freeAgentSignups` collection, left-behind signups included.',
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyLeagueFreeAgents],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copyLeagueFreeAgents, A.verifyLeagueFreeAgents],
     }),
     deleteStep(A.deleteV1TeamMembers, {
         title: 'Delete the V1 memberships',
         summary: 'The `teamMembers` collection.',
         owningStep: 'q-core',
         dependsOn: [A.verifyTeamMemberships],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copyTeamMemberships, A.verifyTeamMemberships],
     }),
     deleteStep(A.deleteV1Teams, {
         title: 'Delete the V1 teams',
         summary: 'The `teams` collection; a team still holding a subcollection is reported and kept.',
         owningStep: 'q-core',
         dependsOn: [A.verifyLeagueTeams],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [
+            A.copyLeagueTeams,
+            A.verifyLeagueTeams,
+            A.verifyV1LeagueCapacity,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     {
         kind: 'executable',
@@ -720,10 +789,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         destructive: true,
         paged: true,
         defaultPageSize: 100,
+        maxPageSize: 200,
         informational: false,
         idempotency: 'Removes a kept file’s download token; a file holding none is skipped. No file is moved or deleted.',
         resumeKey: 'The signed waivers by id, then the contracts; the resume key is the record path.',
         recovery: 'Run it again; a file whose token went is skipped.',
+        consumes: [],
         title: 'Revoke the V1 signature download links',
         summary: 'Each kept signature file loses the download token V1’s stored links carry, so those links stop resolving.',
         owningStep: 'uploads-and-media',
@@ -739,6 +810,8 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         summary: 'The `waiverSignatures` records; the files stay, named by the copied records.',
         owningStep: 'uploads-and-media',
         dependsOn: [A.verifySignedWaivers],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.copySignedWaivers, A.verifySignedWaivers],
     }),
     deleteStep(A.deleteV1HardwareContracts, {
         title: 'Delete the V1 hardware contracts',
@@ -746,6 +819,12 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyHardwareLoanContracts],
         resumeKey: 'The V1 collections in turn, each by document id; the resume key is `{collection}/{id}`.',
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [
+            A.copyHardwareLoanContracts,
+            A.verifyHardwareLoanContracts,
+            A.verifyV1HardwareContractIdsUnique,
+        ],
     }),
     deleteStep(A.deleteV1GameRosters, {
         title: 'Delete the V1 game rosters',
@@ -754,6 +833,14 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.verifyGameRosterPlayers, A.validateStats],
         resumeKey: 'The V1 games by document id; the resume key is the last game id.',
         defaultPageSize: 50,
+        maxPageSize: 50,
+        consumes: [
+            A.copyGameRosterPlayers,
+            A.verifyGameRosterPlayers,
+            A.copySportGames,
+            A.verifySportGames,
+            A.verifyGameStats,
+        ],
     }),
     deleteStep(A.deleteV1LeagueGames, {
         title: 'Delete the V1 games',
@@ -766,6 +853,15 @@ export const MIGRATION_CUTOVER_MANIFEST = [
             A.validateStats,
             A.deleteV1GameRosters,
         ],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [
+            A.copySportGames,
+            A.verifySportGames,
+            A.verifyGameStats,
+            A.copyGameRosterPlayers,
+            A.verifyGameRosterPlayers,
+            A.verifyV1LeagueCapacity,
+        ],
     }),
     deleteStep(A.deleteV1LeagueChats, {
         title: 'Delete the V1 league chats',
@@ -774,6 +870,8 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         dependsOn: [A.checkpointV1FirestoreExport],
         resumeKey: 'The V1 leagues by document id; the resume key is the last league id, or `{leagueId}/unfinished` while a league holds more chats than one page deletes.',
         defaultPageSize: 50,
+        maxPageSize: 50,
+        consumes: [],
     }),
     deleteStep(A.deleteV1Leagues, {
         title: 'Delete the V1 leagues',
@@ -781,12 +879,24 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'q-core',
         dependsOn: [A.verifySportLeagues, A.verifyV1Pictures],
         orderedAfter: [A.verifyLeaguePlayerStats, A.deleteV1LeagueChats],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [
+            A.copySportLeagues,
+            A.verifySportLeagues,
+            A.verifyLeaguePlayerStats,
+            A.carryV1Pictures,
+            A.verifyV1Pictures,
+            A.verifyV1LeagueCapacity,
+            A.verifyV1TextFitsLimits,
+        ],
     }),
     deleteStep(A.deleteV1HallOfFame, {
         title: 'Delete the V1 hall of fame',
         summary: 'The `hallOfFame` collection, once every sport that keeps a hall of fame has its rebuilt document.',
         owningStep: 'stat-data-model',
         dependsOn: [A.verifySportHallOfFame],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.verifySportHallOfFame],
     }),
     deleteStep(A.deleteV1ValidationReports, {
         title: 'Delete the V1 validation reports',
@@ -794,12 +904,16 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'stat-data-model',
         dependsOn: [A.checkpointV1FirestoreExport],
         orderedAfter: [A.validateStats],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [],
     }),
     deleteStep(A.deleteV1AdminStats, {
         title: 'Delete the V1 dashboard counts',
         summary: 'The `adminStats` collection. Nothing is copied: the dashboard counts are counted live.',
         owningStep: 'q-core',
         dependsOn: [A.checkpointV1FirestoreExport],
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [],
     }),
     verifyStep(A.verifyV1CommerceDiscardable, {
         title: 'Check the V1 store holds no purchase',
@@ -814,8 +928,9 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         owningStep: 'high-risk-callables',
         dependsOn: [A.verifyV1CommerceDiscardable],
         resumeKey: 'The six store collections in turn, each by document id.',
+        maxPageSize: MIGRATION_COMMIT_WRITE_LIMIT,
+        consumes: [A.verifyV1CommerceDiscardable],
     }),
-    // ── After the cutover ──────────────────────────────────────────────────────────────────────────
     {
         kind: 'operatorCheckpoint',
         id: A.checkpointUnattachedPicturesReuploaded,
@@ -853,9 +968,7 @@ export const MIGRATION_CUTOVER_MANIFEST = [
         noReturnBoundary: 'The key revocation.',
     },
 ];
-/** Every step by its id. */
 export const MIGRATION_STEP_BY_ID = new Map(MIGRATION_CUTOVER_MANIFEST.map((step) => [step.id, step]));
-/** The steps of one kind, in cutover order. */
 export function migrationStepsOfKind(kind) {
     return MIGRATION_CUTOVER_MANIFEST.filter((step) => step.kind === kind);
 }