@mpgd/cli 0.35.0 → 0.36.0

package/dist/release-state.js

@@ -0,0 +1,1046 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { createReadStream, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { allocatePlatformVersions, assertPlatformVersionLedger, createMpgdReleaseIdentity, formatMpgdReleaseId, } from '@mpgd/target-config';
+import { runReleaseProcess } from './deploy-process.js';
+import { inspectAndroidBundleSigner } from './android-bundle-signer.js';
+export function isNativeSubmissionSettled(status) {
+    return status === 'committed' || status === 'testflight-ready';
+}
+const stateBranch = 'release-state';
+const stateFileName = 'mpgd-release-state.json';
+const releaseKeyPattern = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+const gitShaPattern = /^[0-9a-f]{40}$/u;
+const sha256Pattern = /^[0-9a-f]{64}$/u;
+const androidFingerprintPattern = /^(?:[0-9a-fA-F]{2}:){31}[0-9a-fA-F]{2}$|^[0-9a-fA-F]{64}$/u;
+const teamIdPattern = /^[A-Z0-9]{10}$/u;
+const remoteIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const attemptIdPattern = /^[0-9a-f]{32}$/u;
+const submissionLeaseMs = 25 * 60_000;
+/** Leave one minute of clock-skew headroom below the checkpoint lease cap. */
+export function freshSubmissionLeaseExpiresAt() {
+    return new Date(Date.now() + submissionLeaseMs - 60_000).toISOString();
+}
+function normalizeAndroidFingerprint(value) {
+    return value.replaceAll(':', '').toLowerCase();
+}
+/** Match the private manifest package's complete schema without a runtime workspace dependency. */
+function assertCompleteReleaseManifest(value) {
+    if (!isRecord(value) || !isRecord(value.targets)) {
+        throw new Error('Native release manifest must include target records.');
+    }
+    assertStringFields(value, [
+        'releaseId',
+        'gitSha',
+        'kitGitSha',
+        'gameVersion',
+        'buildId',
+        'targetConfigVersion',
+        'catalogVersion',
+        'adPlacementVersion',
+    ], 'release manifest');
+    if (value.releaseIdentity !== undefined) {
+        if (!isRecord(value.releaseIdentity)) {
+            throw new Error('Native release manifest identity is malformed.');
+        }
+        assertStringFields(value.releaseIdentity, ['gameVersion', 'label'], 'release identity');
+        if (value.releaseIdentity.releaseRevision !== undefined
+            && typeof value.releaseIdentity.releaseRevision !== 'number') {
+            throw new Error('Native release manifest revision is malformed.');
+        }
+    }
+    for (const [name, rawEntry] of Object.entries(value.targets)) {
+        if (!isRecord(rawEntry) || !isRecord(rawEntry.effectiveConfig)
+            || !isRecord(rawEntry.iconManifest)) {
+            throw new Error(`Native release manifest target ${name} is malformed.`);
+        }
+        assertStringFields(rawEntry, ['artifact'], `target ${name}`);
+        assertStringFields(rawEntry.effectiveConfig, ['path', 'version', 'digest'], `effective config ${name}`);
+        assertStringFields(rawEntry.iconManifest, [
+            'path',
+            'digest',
+            'sourceSha256',
+            'sharedConfigSha256',
+            'renderConfigSha256',
+            'generatorVersion',
+            'targetProfile',
+            'targetProfileVersion',
+        ], `icon manifest ${name}`);
+        for (const field of ['profile', 'versionName', 'marketingVersion', 'buildNumber', 'appName']) {
+            if (rawEntry[field] !== undefined && typeof rawEntry[field] !== 'string') {
+                throw new Error(`Native release manifest target ${name}.${field} is malformed.`);
+            }
+        }
+        for (const field of ['versionCode', 'sdkMajor']) {
+            if (rawEntry[field] !== undefined && typeof rawEntry[field] !== 'number') {
+                throw new Error(`Native release manifest target ${name}.${field} is malformed.`);
+            }
+        }
+        if (rawEntry.nativeDelivery !== undefined) {
+            if (!isRecord(rawEntry.nativeDelivery)
+                || !['android', 'ios'].includes(String(rawEntry.nativeDelivery.platform))
+                || !['sync', 'debug', 'simulator', 'unsigned-archive', 'signed-archive', 'store-export']
+                    .includes(String(rawEntry.nativeDelivery.mode))
+                || typeof rawEntry.nativeDelivery.signed !== 'boolean'
+                || typeof rawEntry.nativeDelivery.submissionCandidate !== 'boolean') {
+                throw new Error(`Native release manifest target ${name} delivery is malformed.`);
+            }
+        }
+    }
+    const manifest = value;
+    if (!gitShaPattern.test(manifest.kitGitSha)) {
+        throw new Error('Native release manifest Kit revision is invalid.');
+    }
+    for (const [target, entry] of Object.entries(manifest.targets)) {
+        const delivery = entry.nativeDelivery;
+        if (delivery === undefined) {
+            continue;
+        }
+        const expectedSigned = delivery.mode === 'signed-archive' || delivery.mode === 'store-export';
+        const validMode = delivery.platform === 'android'
+            ? ['debug', 'unsigned-archive', 'signed-archive'].includes(delivery.mode)
+            : ['sync', 'simulator', 'unsigned-archive', 'signed-archive', 'store-export']
+                .includes(delivery.mode);
+        const expectedCandidate = entry.profile === 'production' && (delivery.platform === 'android'
+            ? delivery.mode === 'signed-archive' : delivery.mode === 'store-export');
+        if (!validMode || delivery.signed !== expectedSigned
+            || delivery.submissionCandidate !== expectedCandidate
+            || (entry.profile === 'production' && !delivery.signed)) {
+            throw new Error(`Native release manifest delivery is invalid: ${target}.`);
+        }
+    }
+    if (manifest.releaseIdentity !== undefined) {
+        const identity = createMpgdReleaseIdentity({
+            gameVersion: manifest.releaseIdentity.gameVersion,
+            ...(manifest.releaseIdentity.releaseRevision === undefined
+                ? {} : { releaseRevision: manifest.releaseIdentity.releaseRevision }),
+            expectedLabel: manifest.releaseIdentity.label,
+        });
+        if (manifest.releaseIdentity.label !== identity.label
+            || manifest.releaseIdentity.gameVersion !== identity.gameVersion
+            || manifest.gameVersion !== identity.gameVersion
+            || manifest.releaseId !== formatMpgdReleaseId(identity.label, manifest.buildId)) {
+            throw new Error('Native release manifest identity is invalid.');
+        }
+    }
+    return manifest;
+}
+function assertStringFields(value, fields, label) {
+    for (const field of fields) {
+        if (typeof value[field] !== 'string') {
+            throw new Error(`Native ${label} is missing ${field}.`);
+        }
+    }
+}
+/** Reserve version numbers by committing the ledger and plan atomically. */
+export async function reserveNativeRelease(input) {
+    assertReleaseKey(input.releaseKey);
+    if (input.targets.length === 0
+        || input.targets.some((request) => request.target !== 'android' && request.target !== 'ios')) {
+        throw new Error('Native release reservations require Android or iOS targets.');
+    }
+    if (!gitShaPattern.test(input.sourceGitSha)) {
+        throw new Error('Native release source revision must be a full Git SHA.');
+    }
+    const source = await runReleaseProcess({
+        command: 'git',
+        args: ['-C', input.gameRoot, 'cat-file', '-t', input.sourceGitSha],
+        cwd: input.gameRoot,
+        environment: isolatedGitEnvironment(input.environment ?? process.env),
+        timeoutMs: 10_000,
+        signal: input.signal,
+        captureMachineStdout: true,
+    });
+    if (source.truncated || source.machineStdout?.trim() !== 'commit') {
+        throw new Error('Native release source revision is not a game Git commit.');
+    }
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        if (game === undefined && input.initialLedger === undefined) {
+            throw new Error('First release requires an explicit initial platform version ledger.');
+        }
+        const ledger = game?.ledger ?? assertPlatformVersionLedger(input.initialLedger);
+        const existingPlan = game === undefined
+            ? undefined
+            : ownValue(game.reservations, input.releaseKey);
+        if (existingPlan !== undefined) {
+            const requested = input.targets.map((item) => item.target).sort();
+            const reserved = Object.keys(existingPlan.targets).sort();
+            if (JSON.stringify(requested) !== JSON.stringify(reserved)) {
+                throw new Error('An existing release reservation cannot change its target set.');
+            }
+        }
+        const allocation = allocatePlatformVersions({
+            gameId: input.gameId,
+            gameVersion: input.gameVersion,
+            sourceGitSha: input.sourceGitSha,
+            kitGitSha: input.kitGitSha,
+            targetConfigDigest: input.targetConfigDigest,
+            targets: input.targets,
+            ledger,
+            ...(existingPlan === undefined ? {} : { existingPlan }),
+        });
+        if (existingPlan !== undefined) {
+            if (session.previousCommit === undefined) {
+                throw new Error('Existing reservation has no state commit.');
+            }
+            return { plan: existingPlan, stateCommit: session.previousCommit, reused: true };
+        }
+        const nextGame = {
+            initialLedger: game?.initialLedger ?? ledger,
+            ledger: allocation.ledger,
+            reservations: { ...(game?.reservations ?? {}), [input.releaseKey]: allocation.plan },
+            builds: game?.builds ?? {},
+            ...(game?.submissions === undefined ? {} : { submissions: game.submissions }),
+        };
+        const next = {
+            schemaVersion: 1,
+            games: { ...session.state.games, [input.gameId]: nextGame },
+        };
+        const stateCommit = await commitState(session, next, `Reserve ${input.gameId}/${input.releaseKey}`);
+        return { plan: allocation.plan, stateCommit, reused: false };
+    });
+}
+/** Attach one immutable, content-hashed native artifact to a reserved release. */
+export async function recordNativeReleaseBuild(input) {
+    assertReleaseKey(input.releaseKey);
+    if ((input.deployConfigSha256 === undefined) !== (input.deploymentProfile === undefined)
+        || (input.deployConfigSha256 === undefined) !== (input.deploymentDestination === undefined)
+        || (input.deployConfigSha256 !== undefined
+            && !sha256Pattern.test(input.deployConfigSha256))
+        || (input.deploymentProfile !== undefined
+            && !/^[a-z][a-z0-9-]*$/u.test(input.deploymentProfile))
+        || (input.deploymentDestination !== undefined
+            && input.deploymentDestination !== (input.target === 'android'
+                ? 'play-internal' : 'testflight'))
+        || (input.internalTestGroupId !== undefined && input.deployConfigSha256 === undefined)
+        || (input.target === 'android' && input.internalTestGroupId !== undefined)
+        || (input.target === 'ios' && input.deployConfigSha256 !== undefined
+            && (input.internalTestGroupId === undefined
+                || !/^[A-Za-z0-9][A-Za-z0-9-]*$/u.test(input.internalTestGroupId)))) {
+        throw new Error('Native build deployment profile identity is malformed.');
+    }
+    if (input.buildRunId.trim() === '' || input.artifactLocation.trim() === ''
+        || input.kitPackageVersion.trim() === ''
+        || input.inspectedAppId.trim() === ''
+        || (input.target === 'android' && (input.inspectedTeamId !== undefined
+            || !androidFingerprintPattern.test(input.inspectedSignerSha256 ?? '')))
+        || (input.target === 'ios' && (input.inspectedSignerSha256 !== undefined
+            || !teamIdPattern.test(input.inspectedTeamId ?? '')))
+        || !sha256Pattern.test(input.buildConfigDigest)) {
+        throw new Error('Native build record is missing a run ID, artifact location, or inspection.');
+    }
+    if (!existsSync(input.artifactFile) || !existsSync(input.releaseManifestFile)
+        || !statSync(input.artifactFile).isFile()
+        || !statSync(input.releaseManifestFile).isFile()) {
+        throw new Error('Native build record requires file artifacts.');
+    }
+    const artifactSha256 = await sha256(input.artifactFile);
+    const manifestBytes = readFileSync(input.releaseManifestFile);
+    const releaseManifestSha256 = createHash('sha256').update(manifestBytes).digest('hex');
+    if (artifactSha256 !== input.expectedArtifactSha256
+        || releaseManifestSha256 !== input.expectedReleaseManifestSha256) {
+        throw new Error('Copied native artifact or release manifest differs from the verified build.');
+    }
+    const signer = input.target === 'android'
+        ? await inspectAndroidBundleSigner(input.artifactFile)
+        : undefined;
+    if (signer !== undefined
+        && signer !== normalizeAndroidFingerprint(input.inspectedSignerSha256 ?? '')) {
+        throw new Error('Recorded Android signer does not match the signed AAB bytes.');
+    }
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        const plan = game === undefined ? undefined : ownValue(game.reservations, input.releaseKey);
+        if (game === undefined || plan === undefined || plan.targets[input.target] === undefined) {
+            throw new Error('Native build record has no matching reserved target.');
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(manifestBytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('Native release manifest is not valid JSON.');
+        }
+        const validatedManifest = assertCompleteReleaseManifest(manifest);
+        if (validatedManifest.gitSha !== plan.sourceGitSha
+            || validatedManifest.kitGitSha !== plan.kitGitSha
+            || validatedManifest.buildId !== plan.buildId
+            || validatedManifest.gameVersion !== plan.gameVersion) {
+            throw new Error('Native build manifest does not match its reserved provenance.');
+        }
+        const manifestRecord = validatedManifest;
+        const releaseIdentity = manifestRecord.releaseIdentity;
+        if (typeof releaseIdentity !== 'object' || releaseIdentity === null
+            || Array.isArray(releaseIdentity)
+            || releaseIdentity.releaseRevision !== plan.releaseRevision
+            || releaseIdentity.label !== plan.releaseLabel) {
+            throw new Error('Native build manifest release revision does not match its reservation.');
+        }
+        const manifestTargets = manifestRecord.targets;
+        if (typeof manifestTargets !== 'object' || manifestTargets === null
+            || Array.isArray(manifestTargets)) {
+            throw new Error('Native build manifest is missing target evidence.');
+        }
+        const targetManifest = manifestTargets[input.target];
+        const plannedTarget = plan.targets[input.target];
+        if (typeof targetManifest !== 'object' || targetManifest === null
+            || Array.isArray(targetManifest) || plannedTarget === undefined) {
+            throw new Error('Native build manifest is missing its reserved target.');
+        }
+        const target = targetManifest;
+        const delivery = target.nativeDelivery;
+        if (typeof delivery !== 'object' || delivery === null || Array.isArray(delivery)
+            || delivery.platform !== input.target
+            || delivery.signed !== true
+            || delivery.submissionCandidate !== true
+            || delivery.mode !== (input.target === 'android'
+                ? 'signed-archive' : 'store-export')
+            || target.profile !== 'production'
+            || (input.target === 'android' && target.versionCode !== plannedTarget.versionCode)
+            || (input.target === 'android' && target.versionName !== plannedTarget.versionName)
+            || (input.target === 'ios' && target.buildNumber !== String(plannedTarget.buildNumber))
+            || (input.target === 'ios' && target.marketingVersion !== plannedTarget.marketingVersion)) {
+            throw new Error('Native build manifest does not match reserved signed delivery.');
+        }
+        const record = {
+            releaseKey: input.releaseKey,
+            target: input.target,
+            buildRunId: input.buildRunId,
+            gameVersion: plan.gameVersion,
+            sourceGitSha: plan.sourceGitSha,
+            kitGitSha: plan.kitGitSha,
+            kitPackageVersion: input.kitPackageVersion,
+            buildConfigDigest: input.buildConfigDigest,
+            targetConfigDigest: plan.targetConfigDigest,
+            ...(input.deployConfigSha256 === undefined ? {} : {
+                deployConfigSha256: input.deployConfigSha256,
+                deploymentProfile: input.deploymentProfile,
+                deploymentDestination: input.deploymentDestination,
+                ...(input.internalTestGroupId === undefined
+                    ? {} : { internalTestGroupId: input.internalTestGroupId }),
+            }),
+            platformVersion: plannedTarget,
+            artifactLocation: input.artifactLocation,
+            artifactSha256,
+            releaseManifestSha256,
+            inspectedAppId: input.inspectedAppId,
+            ...(input.target === 'android'
+                ? { inspectedSignerSha256: signer }
+                : { inspectedTeamId: input.inspectedTeamId ?? '' }),
+        };
+        const key = `${input.releaseKey}/${input.target}`;
+        const previous = ownValue(game.builds, key);
+        if (previous !== undefined) {
+            if (!isDeepStrictEqual(previous, record)) {
+                throw new Error('An immutable native build record cannot be replaced.');
+            }
+            if (session.previousCommit === undefined) {
+                throw new Error('Existing build record has no state commit.');
+            }
+            return { record: previous, stateCommit: session.previousCommit };
+        }
+        const next = {
+            schemaVersion: 1,
+            games: {
+                ...session.state.games,
+                [input.gameId]: { ...game, builds: { ...game.builds, [key]: record } },
+            },
+        };
+        const stateCommit = await commitState(session, next, `Record ${input.gameId}/${key}`);
+        return { record, stateCommit };
+    });
+}
+/** Read one explicitly named release from the authoritative game-owned state branch. */
+export async function readNativeReleaseStatus(input) {
+    assertReleaseKey(input.releaseKey);
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        const plan = game === undefined ? undefined : ownValue(game.reservations, input.releaseKey);
+        if (game === undefined || plan === undefined || session.previousCommit === undefined) {
+            throw new Error('The requested native release has not been reserved.');
+        }
+        const androidKey = `${input.releaseKey}/android`;
+        const iosKey = `${input.releaseKey}/ios`;
+        return {
+            plan,
+            builds: {
+                ...(game.builds[androidKey] === undefined ? {} : { android: game.builds[androidKey] }),
+                ...(game.builds[iosKey] === undefined ? {} : { ios: game.builds[iosKey] }),
+            },
+            submissions: {
+                ...(game.submissions?.[androidKey] === undefined
+                    ? {} : { android: game.submissions[androidKey] }),
+                ...(game.submissions?.[iosKey] === undefined
+                    ? {} : { ios: game.submissions[iosKey] }),
+            },
+            stateCommit: session.previousCommit,
+        };
+    });
+}
+/** Persist a resumable store checkpoint with the build record in one Git state. */
+export async function checkpointNativeSubmission(input) {
+    assertNativeSubmissionCheckpoint(input.checkpoint);
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        const key = `${input.checkpoint.releaseKey}/${input.checkpoint.target}`;
+        const build = game === undefined ? undefined : ownValue(game.builds, key);
+        if (game === undefined || build === undefined
+            || build.buildRunId !== input.checkpoint.buildRunId
+            || build.artifactSha256 !== input.checkpoint.artifactSha256) {
+            throw new Error('Store checkpoint must reference the immutable native build record.');
+        }
+        const previous = ownValue(game.submissions ?? {}, key);
+        if (previous !== undefined) {
+            if (previous.attemptId !== input.checkpoint.attemptId) {
+                throw new Error('Store submission has another active or unreconciled attempt owner.');
+            }
+            if (Date.parse(previous.leaseExpiresAt) <= Date.now()
+                && !isNativeSubmissionSettled(previous.status)) {
+                throw new Error('Store submission lease expired; reconcile remote state before takeover.');
+            }
+            if (isDeepStrictEqual(previous, input.checkpoint)) {
+                if (session.previousCommit === undefined) {
+                    throw new Error('Existing store checkpoint has no state commit.');
+                }
+                return { checkpoint: previous, stateCommit: session.previousCommit };
+            }
+            if (isNativeSubmissionSettled(previous.status)
+                || previous.status === 'failed'
+                || previous.remoteEditId !== undefined
+                    && previous.remoteEditId !== input.checkpoint.remoteEditId
+                    && !(previous.target === 'android'
+                        && (previous.status === 'unknown' || previous.status === 'edit-open')
+                        && input.checkpoint.status === 'edit-open'
+                        && input.checkpoint.remoteEditId !== undefined)
+                || previous.remoteUploadId !== undefined
+                    && previous.remoteUploadId !== input.checkpoint.remoteUploadId
+                || previous.remoteBuildId !== undefined
+                    && previous.remoteBuildId !== input.checkpoint.remoteBuildId) {
+                throw new Error('A completed submission or remote checkpoint ID cannot be replaced.');
+            }
+            if (!allowedSubmissionTransition(previous.status, input.checkpoint.status)) {
+                throw new Error('Store submission status cannot move backward.');
+            }
+        }
+        else if (input.checkpoint.status !== 'started') {
+            throw new Error('A new store submission must checkpoint started before remote mutation.');
+        }
+        if (Date.parse(input.checkpoint.leaseExpiresAt) <= Date.now()
+            || Date.parse(input.checkpoint.leaseExpiresAt) > Date.now() + submissionLeaseMs) {
+            throw new Error('Store submission lease must be active and no longer than 25 minutes.');
+        }
+        const next = {
+            schemaVersion: 1,
+            games: {
+                ...session.state.games,
+                [input.gameId]: {
+                    ...game,
+                    submissions: { ...(game.submissions ?? {}), [key]: input.checkpoint },
+                },
+            },
+        };
+        const stateCommit = await commitState(session, next, `Submit ${input.gameId}/${key}`);
+        return { checkpoint: input.checkpoint, stateCommit };
+    });
+}
+/** Claim an expired attempt without discarding its remote IDs or changing its status. */
+export async function reclaimNativeSubmission(input) {
+    assertReleaseKey(input.releaseKey);
+    if (!gitShaPattern.test(input.expectedStateCommit)
+        || !attemptIdPattern.test(input.attemptId)) {
+        throw new Error('Submission reclaim needs an explicit state commit and new attempt ID.');
+    }
+    return withStateSession(input, async (session) => {
+        if (session.previousCommit !== input.expectedStateCommit) {
+            throw new Error('Submission state changed; read its latest remote checkpoint first.');
+        }
+        const game = ownValue(session.state.games, input.gameId);
+        const key = `${input.releaseKey}/${input.target}`;
+        const previous = game === undefined ? undefined : ownValue(game.submissions ?? {}, key);
+        if (game === undefined || previous === undefined) {
+            throw new Error('No store submission exists to reclaim.');
+        }
+        if (Date.parse(previous.leaseExpiresAt) > Date.now()) {
+            throw new Error('Store submission lease is still active.');
+        }
+        if (isNativeSubmissionSettled(previous.status)
+            || previous.status === 'failed'
+            || (previous.status === 'action-required'
+                && previous.remoteUploadId === undefined && previous.remoteBuildId === undefined)
+            || (previous.status === 'unknown'
+                && previous.remoteEditId === undefined && previous.remoteUploadId === undefined
+                && previous.remoteBuildId === undefined)) {
+            throw new Error('Store submission needs operator reconciliation before reclaim.');
+        }
+        const checkpoint = {
+            ...previous,
+            attemptId: input.attemptId,
+            leaseExpiresAt: new Date(Date.now() + submissionLeaseMs).toISOString(),
+        };
+        const next = {
+            schemaVersion: 1,
+            games: {
+                ...session.state.games,
+                [input.gameId]: {
+                    ...game,
+                    submissions: { ...(game.submissions ?? {}), [key]: checkpoint },
+                },
+            },
+        };
+        const stateCommit = await commitState(session, next, `Reclaim ${input.gameId}/${key}`);
+        return { checkpoint, stateCommit };
+    });
+}
+/** Relinquish a completed command's lease so an immediate status poll can resume. */
+export async function releaseNativeSubmissionLease(input) {
+    assertReleaseKey(input.releaseKey);
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        const key = `${input.releaseKey}/${input.target}`;
+        const previous = game === undefined ? undefined : ownValue(game.submissions ?? {}, key);
+        if (game === undefined || previous === undefined
+            || previous.attemptId !== input.attemptId) {
+            throw new Error('Cannot release another submission attempt lease.');
+        }
+        if (Date.parse(previous.leaseExpiresAt) <= Date.now()) {
+            return previous;
+        }
+        const checkpoint = { ...previous, leaseExpiresAt: new Date(0).toISOString() };
+        const next = {
+            schemaVersion: 1,
+            games: {
+                ...session.state.games,
+                [input.gameId]: {
+                    ...game,
+                    submissions: { ...(game.submissions ?? {}), [key]: checkpoint },
+                },
+            },
+        };
+        await commitState(session, next, `Release ${input.gameId}/${key} submission lease`);
+        return checkpoint;
+    });
+}
+function allowedSubmissionTransition(from, to) {
+    if (from === to) {
+        return true;
+    }
+    const allowed = {
+        started: ['edit-open', 'upload-committed', 'unknown', 'failed', 'action-required'],
+        'edit-open': ['committed', 'unknown', 'failed', 'action-required'],
+        'upload-committed': [
+            'uploaded',
+            'processing',
+            'testflight-ready',
+            'unknown',
+            'failed',
+            'action-required',
+        ],
+        uploaded: ['processing', 'testflight-ready', 'unknown', 'failed', 'action-required'],
+        processing: ['testflight-ready', 'unknown', 'failed', 'action-required'],
+        unknown: [
+            'edit-open',
+            'uploaded',
+            'processing',
+            'testflight-ready',
+            'committed',
+            'failed',
+            'action-required',
+        ],
+        'action-required': ['processing', 'testflight-ready', 'unknown'],
+    };
+    return allowed[from]?.includes(to) ?? false;
+}
+async function withStateSession(input, action) {
+    const environment = isolatedGitEnvironment(input.environment ?? process.env);
+    // Read the authoritative write destination, not a possibly stale fetch mirror.
+    // Keep the URL in memory: the redacted runner must never modify embedded auth.
+    let remoteUrl;
+    let repositoryRoot;
+    try {
+        repositoryRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: input.gameRoot,
+            env: environment,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+            maxBuffer: 64 * 1024,
+        }).trim();
+        remoteUrl = execFileSync('git', ['remote', 'get-url', '--push', 'origin'], {
+            cwd: input.gameRoot,
+            env: environment,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+            maxBuffer: 64 * 1024,
+        }).trim();
+    }
+    catch {
+        throw new Error('Could not read the game repository origin remote.');
+    }
+    if (remoteUrl === '' || repositoryRoot === '') {
+        throw new Error('Game repository origin remote is missing.');
+    }
+    remoteUrl = resolveRemoteUrl(repositoryRoot, remoteUrl);
+    const directory = mkdtempSync(path.join(tmpdir(), 'mpgd-release-state-'));
+    try {
+        const session = {
+            directory,
+            previousCommit: undefined,
+            remoteUrl,
+            environment,
+            signal: input.signal,
+            state: { schemaVersion: 1, games: {} },
+        };
+        await git(session, ['init', '--object-format=sha1', '-q', directory]);
+        await git(session, ['remote', 'add', 'origin', remoteUrl]);
+        const remoteHead = await git(session, [
+            'ls-remote',
+            '--heads',
+            'origin',
+            `refs/heads/${stateBranch}`,
+        ]);
+        const previousCommit = remoteHead.output.trim().split(/\s+/u)[0];
+        if (previousCommit !== undefined && gitShaPattern.test(previousCommit)) {
+            await git(session, ['fetch', 'origin', `refs/heads/${stateBranch}`]);
+            await git(session, ['checkout', '-q', '-B', stateBranch, 'FETCH_HEAD']);
+            const fetchedCommit = (await git(session, ['rev-parse', 'HEAD'])).output.trim();
+            if (!gitShaPattern.test(fetchedCommit)) {
+                throw new Error('Fetched release-state revision is invalid.');
+            }
+            const statePath = path.join(directory, stateFileName);
+            if (!existsSync(statePath)) {
+                throw new Error('Existing release-state branch has no state file.');
+            }
+            return await action({
+                ...session,
+                previousCommit: fetchedCommit,
+                state: parseReleaseState(readFileSync(statePath, 'utf8')),
+            });
+        }
+        if (remoteHead.output.trim() !== '') {
+            throw new Error('Release-state remote returned an invalid branch reference.');
+        }
+        await git(session, ['checkout', '-q', '--orphan', stateBranch]);
+        return await action(session);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+}
+function resolveRemoteUrl(repositoryRoot, remoteUrl) {
+    if (!path.isAbsolute(remoteUrl)
+        && !/^(?:[a-z][a-z0-9+.-]*:\/\/|(?:[^/@:\s]+@)?[^/@:\s]+:)/iu.test(remoteUrl)) {
+        return path.resolve(repositoryRoot, remoteUrl);
+    }
+    return remoteUrl;
+}
+async function commitState(session, state, subject) {
+    const statePath = path.join(session.directory, stateFileName);
+    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    await git(session, ['add', '--', stateFileName]);
+    await git(session, [
+        '-c',
+        'user.name=mpgd-release',
+        '-c',
+        'user.email=mpgd-release@example.invalid',
+        'commit',
+        '--no-gpg-sign',
+        '-qm',
+        subject,
+    ]);
+    const commit = (await git(session, ['rev-parse', 'HEAD'])).output.trim();
+    if (!gitShaPattern.test(commit)) {
+        throw new Error('Release-state commit is not a full Git SHA.');
+    }
+    const expected = session.previousCommit ?? '';
+    try {
+        await git(session, [
+            'push',
+            `--force-with-lease=refs/heads/${stateBranch}:${expected}`,
+            'origin',
+            `HEAD:refs/heads/${stateBranch}`,
+        ]);
+    }
+    catch (error) {
+        let remoteCommit;
+        let verificationFailure;
+        try {
+            const remoteHead = await git(session, [
+                'ls-remote',
+                '--heads',
+                'origin',
+                `refs/heads/${stateBranch}`,
+            ]);
+            remoteCommit = remoteHead.output.trim().split(/\s+/u)[0];
+        }
+        catch (verificationError) {
+            verificationFailure = verificationError;
+        }
+        if (remoteCommit !== commit) {
+            const cause = verificationFailure === undefined
+                ? error
+                : new AggregateError([error, verificationFailure], 'Push and verification both failed.');
+            throw new Error('Release-state update conflicted or has an uncertain result; retry with the same release key.', { cause });
+        }
+    }
+    return commit;
+}
+function parseReleaseState(json) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        throw new Error('Release-state file on the remote branch is not valid JSON.');
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('Release state must be a JSON object.');
+    }
+    const record = value;
+    if (record.schemaVersion !== 1 || typeof record.games !== 'object'
+        || record.games === null || Array.isArray(record.games)
+        || Object.keys(record).some((key) => key !== 'schemaVersion' && key !== 'games')) {
+        throw new Error('Release state has an unsupported schema.');
+    }
+    for (const [gameId, rawGame] of Object.entries(record.games)) {
+        if (typeof rawGame !== 'object' || rawGame === null || Array.isArray(rawGame)) {
+            throw new Error(`Release state game ${gameId} is malformed.`);
+        }
+        const game = rawGame;
+        if (Object.keys(game).some((key) => ![
+            'initialLedger', 'ledger', 'reservations', 'builds', 'submissions',
+        ].includes(key))
+            || typeof game.reservations !== 'object' || game.reservations === null
+            || Array.isArray(game.reservations)
+            || typeof game.builds !== 'object' || game.builds === null
+            || Array.isArray(game.builds)
+            || (game.submissions !== undefined && !isRecord(game.submissions))) {
+            throw new Error(`Release state game ${gameId} has invalid entries.`);
+        }
+        const initialLedger = assertPlatformVersionLedger(game.initialLedger);
+        const ledger = assertPlatformVersionLedger(game.ledger);
+        const plans = [];
+        for (const [releaseKey, rawPlan] of Object.entries(game.reservations)) {
+            let targetNames = [];
+            if (isRecord(rawPlan) && isRecord(rawPlan.targets)) {
+                targetNames = Object.keys(rawPlan.targets);
+            }
+            if (!releaseKeyPattern.test(releaseKey) || !isRecord(rawPlan)
+                || rawPlan.schemaVersion !== 2 || !isRecord(rawPlan.targets)
+                || typeof rawPlan.gameId !== 'string' || rawPlan.gameId !== gameId
+                || typeof rawPlan.gameVersion !== 'string'
+                || !Number.isSafeInteger(rawPlan.releaseRevision)
+                || Number(rawPlan.releaseRevision) < 1
+                || typeof rawPlan.releaseLabel !== 'string'
+                || typeof rawPlan.buildId !== 'string'
+                || !gitShaPattern.test(String(rawPlan.sourceGitSha))
+                || !gitShaPattern.test(String(rawPlan.kitGitSha))
+                || !sha256Pattern.test(String(rawPlan.targetConfigDigest))
+                || targetNames.length === 0
+                || targetNames.some((target) => target !== 'android' && target !== 'ios')
+                || Object.values(rawPlan.targets).some((target) => !isRecord(target))) {
+                throw new Error(`Release state game ${gameId} has an invalid reservation ${releaseKey}.`);
+            }
+            const plan = rawPlan;
+            try {
+                const checked = allocatePlatformVersions({
+                    gameId,
+                    gameVersion: plan.gameVersion,
+                    sourceGitSha: plan.sourceGitSha,
+                    kitGitSha: plan.kitGitSha,
+                    targetConfigDigest: plan.targetConfigDigest,
+                    targets: targetNames.map((target) => ({
+                        target: target,
+                    })),
+                    ledger,
+                    existingPlan: plan,
+                });
+                if (!isDeepStrictEqual(checked.plan, plan)) {
+                    throw new Error('Stored release plan differs from its validated allocation.');
+                }
+            }
+            catch {
+                throw new Error(`Release state game ${gameId} has an invalid reservation ${releaseKey}.`);
+            }
+            plans.push(plan);
+        }
+        assertReservationHistory(gameId, initialLedger, ledger, plans);
+        for (const [buildKey, rawBuild] of Object.entries(game.builds)) {
+            assertStoredBuildRecord(gameId, buildKey, rawBuild, game.reservations);
+        }
+        for (const [key, rawCheckpoint] of Object.entries(game.submissions ?? {})) {
+            assertNativeSubmissionCheckpoint(rawCheckpoint);
+            const checkpoint = rawCheckpoint;
+            const build = game.builds[key];
+            if (key !== `${checkpoint.releaseKey}/${checkpoint.target}` || build === undefined
+                || checkpoint.buildRunId !== build.buildRunId
+                || checkpoint.artifactSha256 !== build.artifactSha256) {
+                throw new Error(`Release state game ${gameId} has an invalid submission ${key}.`);
+            }
+        }
+    }
+    return value;
+}
+const buildRecordFields = [
+    'releaseKey',
+    'target',
+    'buildRunId',
+    'gameVersion',
+    'sourceGitSha',
+    'kitGitSha',
+    'kitPackageVersion',
+    'buildConfigDigest',
+    'targetConfigDigest',
+    'deployConfigSha256',
+    'deploymentProfile',
+    'deploymentDestination',
+    'internalTestGroupId',
+    'platformVersion',
+    'artifactLocation',
+    'artifactSha256',
+    'releaseManifestSha256',
+    'inspectedAppId',
+    'inspectedSignerSha256',
+    'inspectedTeamId',
+];
+function assertStoredBuildRecord(gameId, buildKey, value, reservations) {
+    const malformed = () => {
+        throw new Error(`Release state game ${gameId} has an invalid build record ${buildKey}.`);
+    };
+    if (!isRecord(value)) {
+        malformed();
+    }
+    const record = value;
+    if (typeof record.releaseKey !== 'string'
+        || !releaseKeyPattern.test(record.releaseKey)
+        || (record.target !== 'android' && record.target !== 'ios')
+        || buildKey !== `${record.releaseKey}/${record.target}`
+        || Object.keys(record).some((key) => !buildRecordFields.includes(key))
+        || typeof record.buildRunId !== 'string' || record.buildRunId.trim() === ''
+        || typeof record.kitPackageVersion !== 'string' || record.kitPackageVersion.trim() === ''
+        || typeof record.artifactLocation !== 'string' || record.artifactLocation.trim() === ''
+        || typeof record.inspectedAppId !== 'string' || record.inspectedAppId.trim() === ''
+        || !sha256Pattern.test(String(record.buildConfigDigest))
+        || (record.deployConfigSha256 !== undefined
+            && !sha256Pattern.test(String(record.deployConfigSha256)))
+        || (record.deploymentProfile !== undefined
+            && (typeof record.deploymentProfile !== 'string'
+                || !/^[a-z][a-z0-9-]*$/u.test(record.deploymentProfile)))
+        || (record.deployConfigSha256 === undefined) !== (record.deploymentProfile === undefined)
+        || (record.deployConfigSha256 === undefined) !== (record.deploymentDestination === undefined)
+        || (record.deploymentDestination !== undefined
+            && record.deploymentDestination !== (record.target === 'android'
+                ? 'play-internal' : 'testflight'))
+        || (record.internalTestGroupId !== undefined && record.deployConfigSha256 === undefined)
+        || (record.target === 'android' && record.internalTestGroupId !== undefined)
+        || (record.target === 'ios' && record.deployConfigSha256 !== undefined
+            && (typeof record.internalTestGroupId !== 'string'
+                || !/^[A-Za-z0-9][A-Za-z0-9-]*$/u.test(record.internalTestGroupId)))
+        || !sha256Pattern.test(String(record.artifactSha256))
+        || !sha256Pattern.test(String(record.releaseManifestSha256))
+        || (record.target === 'android' && (record.inspectedTeamId !== undefined
+            || !sha256Pattern.test(String(record.inspectedSignerSha256))))
+        || (record.target === 'ios' && (record.inspectedSignerSha256 !== undefined
+            || !teamIdPattern.test(String(record.inspectedTeamId))))
+        || !isRecord(record.platformVersion)) {
+        malformed();
+    }
+    const plan = ownValue(reservations, record.releaseKey);
+    if (!isRecord(plan) || !isRecord(plan.targets)
+        || !isDeepStrictEqual(record.platformVersion, plan.targets[record.target])
+        || record.gameVersion !== plan.gameVersion
+        || record.sourceGitSha !== plan.sourceGitSha
+        || record.kitGitSha !== plan.kitGitSha
+        || record.targetConfigDigest !== plan.targetConfigDigest) {
+        malformed();
+    }
+}
+const checkpointFields = [
+    'releaseKey',
+    'target',
+    'buildRunId',
+    'artifactSha256',
+    'attemptId',
+    'leaseExpiresAt',
+    'status',
+    'remoteEditId',
+    'remoteUploadId',
+    'remoteBuildId',
+];
+/** Validate persisted checkpoint shape before any remote mutation or recovery. */
+export function assertNativeSubmissionCheckpoint(value) {
+    if (!isRecord(value)) {
+        throw new Error('Native submission checkpoint is not an object.');
+    }
+    const id = (name) => value[name] === undefined || typeof value[name] === 'string'
+        && remoteIdPattern.test(value[name]);
+    const androidStatuses = [
+        'started',
+        'edit-open',
+        'committed',
+        'failed',
+        'action-required',
+        'unknown',
+    ];
+    const iosStatuses = [
+        'started',
+        'upload-committed',
+        'uploaded',
+        'processing',
+        'testflight-ready',
+        'failed',
+        'action-required',
+        'unknown',
+    ];
+    if (typeof value.releaseKey !== 'string' || !releaseKeyPattern.test(value.releaseKey)
+        || (value.target !== 'android' && value.target !== 'ios')
+        || typeof value.buildRunId !== 'string' || value.buildRunId.trim() === ''
+        || !sha256Pattern.test(String(value.artifactSha256))
+        || typeof value.attemptId !== 'string' || !attemptIdPattern.test(value.attemptId)
+        || typeof value.leaseExpiresAt !== 'string'
+        || !Number.isFinite(Date.parse(value.leaseExpiresAt))
+        || Object.keys(value).some((key) => !checkpointFields.includes(key))
+        || !id('remoteEditId') || !id('remoteUploadId') || !id('remoteBuildId')
+        || (value.target === 'android' && (!androidStatuses.includes(value.status)
+            || value.remoteUploadId !== undefined || value.remoteBuildId !== undefined
+            || (['edit-open', 'committed'].includes(String(value.status))
+                && value.remoteEditId === undefined)))
+        || (value.target === 'ios' && (!iosStatuses.includes(value.status)
+            || value.remoteEditId !== undefined
+            || (['upload-committed', 'uploaded', 'processing', 'testflight-ready']
+                .includes(String(value.status)) && value.remoteUploadId === undefined
+                && (value.status === 'upload-committed' || value.remoteBuildId === undefined))))
+        || (value.status === 'started'
+            && (value.remoteEditId !== undefined || value.remoteUploadId !== undefined
+                || value.remoteBuildId !== undefined))) {
+        throw new Error('Native submission checkpoint is malformed.');
+    }
+}
+function assertReservationHistory(gameId, initialLedger, ledger, plans) {
+    if (plans.length === 0) {
+        throw new Error(`Release state game ${gameId} has no reservation history.`);
+    }
+    const ordered = [...plans].sort((left, right) => left.releaseRevision - right.releaseRevision);
+    if (ordered[0]?.releaseRevision !== initialLedger.releaseRevision.lastAllocated + 1) {
+        throw new Error(`Release state game ${gameId} has a truncated reservation history.`);
+    }
+    for (let index = 1; index < ordered.length; index += 1) {
+        if (ordered[index]?.releaseRevision !== Number(ordered[index - 1]?.releaseRevision) + 1) {
+            throw new Error(`Release state game ${gameId} has nonconsecutive release revisions.`);
+        }
+    }
+    if (ordered.at(-1)?.releaseRevision !== ledger.releaseRevision.lastAllocated) {
+        throw new Error(`Release state game ${gameId} ledger revision differs from reservations.`);
+    }
+    for (const target of ['android', 'ios']) {
+        const key = target === 'android' ? 'versionCode' : 'buildNumber';
+        const versions = ordered.flatMap((plan) => {
+            const entry = plan.targets[target];
+            return entry === undefined ? [] : [Number(entry[key])];
+        });
+        const initialVersion = target === 'android'
+            ? initialLedger.platforms.android?.versionCode
+            : initialLedger.platforms.ios?.buildNumber;
+        if (versions.length > 0 && (initialVersion === undefined
+            || versions[0] !== initialVersion + 1)) {
+            throw new Error(`Release state game ${gameId} has a truncated ${target} history.`);
+        }
+        for (let index = 1; index < versions.length; index += 1) {
+            if (versions[index] !== Number(versions[index - 1]) + 1) {
+                throw new Error(`Release state game ${gameId} has nonconsecutive ${target} numbers.`);
+            }
+        }
+        let ledgerVersion;
+        if (target === 'android') {
+            ledgerVersion = ledger.platforms.android?.versionCode;
+        }
+        else {
+            ledgerVersion = ledger.platforms.ios?.buildNumber;
+        }
+        if (versions.length > 0 && versions.at(-1) !== ledgerVersion) {
+            throw new Error(`Release state game ${gameId} ${target} ledger differs from reservations.`);
+        }
+        if (versions.length === 0 && ledgerVersion !== initialVersion) {
+            throw new Error(`Release state game ${gameId} ${target} ledger differs from its baseline.`);
+        }
+    }
+    if (!isDeepStrictEqual(ledger.platforms['microsoft-store'], initialLedger.platforms['microsoft-store'])) {
+        throw new Error(`Release state game ${gameId} Microsoft Store ledger differs from its baseline.`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ownValue(items, key) {
+    return Object.hasOwn(items, key) ? items[key] : undefined;
+}
+function assertReleaseKey(key) {
+    if (!releaseKeyPattern.test(key)) {
+        throw new Error('Release key must be a lowercase, path-safe identifier.');
+    }
+}
+async function sha256(file) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file)) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+function isolatedGitEnvironment(source) {
+    const environment = { ...source };
+    for (const name of [
+        'GIT_DIR',
+        'GIT_WORK_TREE',
+        'GIT_INDEX_FILE',
+        'GIT_COMMON_DIR',
+        'GIT_OBJECT_DIRECTORY',
+        'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+        'GIT_NAMESPACE',
+    ]) {
+        delete environment[name];
+    }
+    return environment;
+}
+async function git(session, args) {
+    const secrets = [session.remoteUrl];
+    for (const remote of [session.remoteUrl]) {
+        try {
+            const url = new URL(remote);
+            for (const component of [url.username, url.password]) {
+                if (component !== '') {
+                    secrets.push(component);
+                    try {
+                        secrets.push(decodeURIComponent(component));
+                    }
+                    catch {
+                        // Retain the raw component if it is not valid percent encoding.
+                    }
+                }
+            }
+        }
+        catch {
+            // Local paths and scp-style Git remotes are not URL instances.
+        }
+    }
+    const input = {
+        command: 'git',
+        // Apply before checkout too: a relative inherited hooksPath could execute
+        // post-checkout from the fetched, untrusted release-state branch.
+        args: ['-c', `core.hooksPath=${path.join(session.directory, '.git', '.mpgd-no-hooks')}`, ...args],
+        cwd: session.directory,
+        environment: session.environment,
+        timeoutMs: 60_000,
+        signal: session.signal,
+        secretValues: secrets,
+        captureMachineStdout: true,
+    };
+    const result = await runReleaseProcess(input);
+    if (result.truncated || result.machineStdout === undefined) {
+        throw new Error('Release-state Git machine output was truncated or unavailable.');
+    }
+    return { output: result.machineStdout };
+}