@mpgd/cli 0.61.1 → 0.63.0

package/dist/pnpm-build-approvals.js

@@ -0,0 +1,157 @@
+/**
+ * pnpm build-script decisions for the dependencies a notifications game adds.
+ *
+ * pnpm 11 replaced `onlyBuiltDependencies` with `allowBuilds` and fails an
+ * install (`ERR_PNPM_IGNORED_BUILDS`) while a dependency's build script is
+ * neither allowed (`true`) nor denied (`false`), because `strictDepBuilds`
+ * defaults to `true` (https://pnpm.io/settings/build). The notifications
+ * starter adds `firebase`, whose tree has two such scripts:
+ *
+ * - `@firebase/util` `postinstall.js` only matters for Firebase App Hosting:
+ *   it reads `FIREBASE_WEBAPP_CONFIG`, may fetch the web app config from
+ *   firebase.googleapis.com, and bakes it into `dist/postinstall.*` for
+ *   `initializeApp()` without options. The published `dist` already ships the
+ *   placeholder that returns `undefined`, and the kit never initializes the web
+ *   SDK (it is there so the messaging plugin's web fallback resolves), so the
+ *   script is denied: the install stays offline and reproducible.
+ * - `protobufjs` `scripts/postinstall.js` only prints a warning when the parent
+ *   package declares protobufjs with another semver operator. The game
+ *   template already allows it for the Apps in Toss toolchain, so the same
+ *   decision is kept here.
+ *
+ * `packages/cli/test/pnpm-build-approvals.test.ts` records every package with
+ * an install script in the starter's Firebase tree and fails when the starter's
+ * firebase version moves without that list (and a decision here) being redone.
+ */
+export const notificationsBuildApprovals = Object.freeze({
+    '@firebase/util': false,
+    protobufjs: true,
+});
+const allowBuildsLine = /^allowBuilds:[ \t]*(?:#.*)?$/mu;
+// Any top-level spelling of the key, quoted or not, so an unparsed form is
+// reported instead of getting a second, duplicate mapping appended.
+const allowBuildsKey = /^(?:allowBuilds|'allowBuilds'|"allowBuilds")[ \t]*:/mu;
+const entryKey = /^([ \t]+)(?:'((?:[^']|'')*)'|"((?:[^"\\]|\\.)*)"|([^\s#'"-][^:#]*?))[ \t]*:[ \t]*[^\s#]/u;
+/** The package a matcher names: `name`, `name@range`, `@scope/name@range`, or `name@git-url`. */
+export function allowBuildsPackageName(matcher) {
+    const trimmed = matcher.trim();
+    const versionAt = trimmed.indexOf('@', trimmed.startsWith('@') ? 1 : 0);
+    return versionAt === -1 ? trimmed : trimmed.slice(0, versionAt);
+}
+function quoteKey(name) {
+    return /^[a-z0-9][a-z0-9._-]*$/u.test(name) ? name : `'${name.replaceAll("'", "''")}'`;
+}
+/**
+ * Adds an explicit decision for each package in `approvals` that the
+ * `pnpm-workspace.yaml` content does not list yet, keeping every existing
+ * entry (a game's own decision wins). Only the block-mapping form the game
+ * template writes is edited; another form is reported as unsupported so the
+ * caller can print the entries instead of rewriting YAML it cannot parse.
+ */
+export function addAllowBuilds(content, approvals) {
+    if (/^dangerouslyAllowAllBuilds:[ \t]*true\b/mu.test(content)
+        || /^strictDepBuilds:[ \t]*false\b/mu.test(content)) {
+        return { kind: 'covered' };
+    }
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/u);
+    const header = lines.findIndex((line) => allowBuildsLine.test(line));
+    // A bare name reviews every version; a qualified matcher (`name@1.2.3`,
+    // `name@git+…`) reviews only what it names, which may not be what the
+    // starter's firebase brings.
+    const listed = new Set();
+    const qualified = new Set();
+    let indent = '  ';
+    if (header !== -1) {
+        let indentSeen = false;
+        for (let index = header + 1; index < lines.length; index += 1) {
+            const line = lines[index] ?? '';
+            if (line.trim() === '' || /^[ \t]*#/u.test(line)) {
+                continue;
+            }
+            if (!/^[ \t]/u.test(line)) {
+                break;
+            }
+            // Only one-line `key: value` entries at one indentation are read; a
+            // sequence item, a value on the next line, or a nested key would make
+            // the scan miss an entry and the edit add a duplicate key.
+            const match = entryKey.exec(line);
+            if (match === null || (indentSeen && match[1] !== indent)) {
+                return { kind: 'unsupported', missing: Object.keys(approvals) };
+            }
+            // A merge key (`<<: *decisions`), an anchor, an alias or a tag brings
+            // entries the line scan cannot see, so an inserted entry could override
+            // an inherited decision.
+            if (/^(?:<<|[&*!])/u.test(match[4] ?? '') || /[&*!]$/u.test(match[0])) {
+                return { kind: 'unsupported', missing: Object.keys(approvals) };
+            }
+            if (!indentSeen) {
+                indent = match[1] ?? indent;
+                indentSeen = true;
+            }
+            const key = match[2]?.replaceAll("''", "'") ?? match[3] ?? match[4] ?? '';
+            const name = allowBuildsPackageName(key);
+            (name === key.trim() ? listed : qualified).add(name);
+        }
+    }
+    else if (allowBuildsKey.test(content)) {
+        return { kind: 'unsupported', missing: Object.keys(approvals) };
+    }
+    const missing = Object.keys(approvals).filter((name) => !listed.has(name)).sort();
+    if (missing.length === 0) {
+        return { kind: 'covered' };
+    }
+    if (missing.some((name) => qualified.has(name))) {
+        // A bare entry would override the game's version-specific decision.
+        return { kind: 'unsupported', missing };
+    }
+    const entries = missing.map((name) => `${indent}${quoteKey(name)}: ${String(approvals[name])}`);
+    if (header !== -1) {
+        lines.splice(header + 1, 0, ...entries);
+    }
+    else {
+        while (lines.length > 0 && lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        lines.push('allowBuilds:', ...entries, '');
+    }
+    const edited = lines.join(newline);
+    return {
+        kind: 'edited',
+        content: edited.endsWith(newline) ? edited : `${edited}${newline}`,
+        added: missing,
+    };
+}
+/** The `allowBuilds` block to print when the caller cannot edit the file itself. */
+export function allowBuildsSnippet(approvals) {
+    return [
+        'allowBuilds:',
+        ...Object.keys(approvals).sort().map((name) => `  ${quoteKey(name)}: ${String(approvals[name])}`),
+    ].join('\n');
+}
+/**
+ * The `pnpm-workspace.yaml` edit a notifications game needs before its
+ * install adds `firebase`: the new content when the file can be edited, or a
+ * warning with the entries to add when it cannot (no file at the game root,
+ * where a parent workspace may govern the install, or a form this edit does
+ * not parse).
+ */
+export function planNotificationsBuildApprovals(workspace) {
+    const instruction = 'pnpm 11 stops installing firebase until the pnpm-workspace.yaml that '
+        + `installs the game lists its build scripts:\n${allowBuildsSnippet(notificationsBuildApprovals)}`;
+    if (workspace === undefined) {
+        return { warning: `The game has no pnpm-workspace.yaml; ${instruction}` };
+    }
+    const edit = addAllowBuilds(workspace, notificationsBuildApprovals);
+    if (edit.kind === 'edited') {
+        return { content: edit.content };
+    }
+    if (edit.kind === 'unsupported') {
+        return {
+            warning: 'pnpm-workspace.yaml writes allowBuilds in a form the initializer does not edit '
+                + '(a quoted key, a flow mapping, or a version-specific entry for one of these packages); '
+                + instruction,
+        };
+    }
+    return {};
+}

package/dist/release-state.d.ts

@@ -1,4 +1,5 @@
 import { type PlatformVersionLedger, type PlatformVersionReleasePlan, type PlatformVersionTargetRequest } from '@mpgd/target-config';
+import { type NativeDsymIdentity } from './native-build-symbols.js';
 export interface NativeReleaseReservationInput {
   readonly gameRoot: string;
   readonly releaseKey: string;
@@ -40,6 +41,44 @@ export interface ImmutableNativeBuildRecord {
   readonly inspectedAppId: string;
   readonly inspectedSignerSha256?: string | undefined;
   readonly inspectedTeamId?: string | undefined;
+  /** Android: the R8 `mapping.txt` of this bundle, when the build was minified. */
+  readonly r8Mapping?: RecordedSymbolFile;
+  /** iOS with Firebase Crashlytics: the archive's dSYMs and what uploads them. */
+  readonly crashlyticsSymbols?: RecordedCrashlyticsSymbols;
+}
+/** A game-relative file kept next to the recorded artifact, with its SHA-256. */
+export interface RecordedSymbolFile {
+  readonly location: string;
+  readonly sha256: string;
+}
+export interface RecordedCrashlyticsSymbols {
+  /** Zip of the archive's `dSYMs` folder. */
+  readonly dsymArchive: RecordedSymbolFile;
+  /** Each dSYM bundle and its Mach-O UUIDs. */
+  readonly dsyms: readonly NativeDsymIdentity[];
+  /** Firebase's `upload-symbols` from the build's package checkout. */
+  readonly uploadTool: RecordedSymbolFile;
+  /** The `GoogleService-Info.plist` the archived app bundles. */
+  readonly googleServiceInfo: RecordedSymbolFile;
+}
+/** A symbol file to copy into the record: its bytes and its game-relative location. */
+export interface RecordSymbolFileInput {
+  readonly file: string;
+  readonly location: string;
+}
+/**
+* The Crashlytics dSYM upload of one recorded iOS build. It is mutable state
+* next to the immutable build record: `failed` can be retried, `uploaded` is final.
+*/
+export interface CrashSymbolUploadRecord {
+  readonly releaseKey: string;
+  readonly target: 'ios';
+  readonly buildRunId: string;
+  readonly dsymArchiveSha256: string;
+  readonly status: 'uploaded' | 'failed';
+  readonly updatedAt: string;
+  /** Short reason of the last failed attempt. */
+  readonly failure?: string;
 }
 export type NativeSubmissionStatus = 'started' | 'edit-open' | 'upload-committed' | 'uploaded' | 'processing' | 'testflight-ready' | 'action-required' | 'failed' | 'unknown' | 'committed';
 export declare function isNativeSubmissionSettled(status: NativeSubmissionStatus): boolean;
@@ -65,6 +104,8 @@ export interface NativeReleaseStatus {
   readonly plan: PlatformVersionReleasePlan;
   readonly builds: Partial<Record<'android' | 'ios', ImmutableNativeBuildRecord>>;
   readonly submissions: Partial<Record<'android' | 'ios', NativeSubmissionCheckpoint>>;
+  /** Crashlytics dSYM uploads of recorded iOS builds. */
+  readonly symbolUploads?: Partial<Record<'ios', CrashSymbolUploadRecord>>;
   readonly stateCommit: string;
 }
 export interface RecordNativeBuildInput {
@@ -87,6 +128,15 @@ export interface RecordNativeBuildInput {
   readonly inspectedAppId: string;
   readonly inspectedSignerSha256?: string | undefined;
   readonly inspectedTeamId?: string | undefined;
+  /** Android: the R8 mapping file the build wrote, already copied next to the artifact. */
+  readonly r8Mapping?: RecordSymbolFileInput;
+  /** iOS with Firebase Crashlytics, already copied next to the artifact. */
+  readonly crashlyticsSymbols?: {
+    readonly dsymArchive: RecordSymbolFileInput;
+    readonly dsyms: readonly NativeDsymIdentity[];
+    readonly uploadTool: RecordSymbolFileInput;
+    readonly googleServiceInfo: RecordSymbolFileInput;
+  };
   readonly environment?: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
 }
@@ -142,7 +192,26 @@ export declare function releaseNativeSubmissionLease(input: {
   readonly environment?: NodeJS.ProcessEnv;
   readonly signal?: AbortSignal;
 }): Promise<NativeSubmissionCheckpoint>;
+/**
+* Record the outcome of a Crashlytics dSYM upload for one recorded iOS build.
+* A failure can be recorded again and retried; once `uploaded`, it stays so.
+*/
+export declare function recordCrashSymbolUpload(input: {
+  readonly gameRoot: string;
+  readonly gameId: string;
+  readonly releaseKey: string;
+  readonly buildRunId: string;
+  readonly dsymArchiveSha256: string;
+  readonly status: CrashSymbolUploadRecord['status'];
+  readonly failure?: string;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly signal?: AbortSignal;
+}): Promise<CrashSymbolUploadRecord>;
 /** Exported for tests: the checkpoint status moves a store submission may make. */
 export declare function allowedSubmissionTransition(from: NativeSubmissionStatus, to: NativeSubmissionStatus): boolean;
 /** Validate persisted checkpoint shape before any remote mutation or recovery. */
 export declare function assertNativeSubmissionCheckpoint(value: unknown): asserts value is NativeSubmissionCheckpoint;
+/** A game-relative location without `..` segments. */
+export declare function isRecordedLocation(location: unknown): location is string;
+/** Streamed SHA-256 of a file, hex. */
+export declare function sha256File(file: string): Promise<string>;

package/dist/release-state.js

@@ -6,6 +6,7 @@ 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 { isDsymIdentityList } from './native-build-symbols.js';
 import { inspectAndroidBundleSigner } from './android-bundle-signer.js';
 export function isNativeSubmissionSettled(status) {
     return status === 'committed' || status === 'testflight-ready';
@@ -195,6 +196,7 @@ export async function reserveNativeRelease(input) {
             reservations: { ...(game?.reservations ?? {}), [input.releaseKey]: allocation.plan },
             builds: game?.builds ?? {},
             ...(game?.submissions === undefined ? {} : { submissions: game.submissions }),
+            ...(game?.symbolUploads === undefined ? {} : { symbolUploads: game.symbolUploads }),
         };
         const next = {
             schemaVersion: 1,
@@ -238,7 +240,26 @@ export async function recordNativeReleaseBuild(input) {
         || !statSync(input.releaseManifestFile).isFile()) {
         throw new Error('Native build record requires file artifacts.');
     }
-    const artifactSha256 = await sha256(input.artifactFile);
+    if ((input.r8Mapping !== undefined && input.target !== 'android')
+        || (input.crashlyticsSymbols !== undefined && (input.target !== 'ios'
+            || !isDsymIdentityList(input.crashlyticsSymbols.dsyms)))) {
+        throw new Error('Native build symbols do not match the build target.');
+    }
+    const r8Mapping = input.r8Mapping === undefined
+        ? undefined
+        : await recordSymbolFile(input.r8Mapping);
+    const crashlyticsSymbols = input.crashlyticsSymbols === undefined
+        ? undefined
+        : {
+            dsymArchive: await recordSymbolFile(input.crashlyticsSymbols.dsymArchive),
+            dsyms: input.crashlyticsSymbols.dsyms.map((entry) => ({
+                bundle: entry.bundle,
+                uuids: [...entry.uuids],
+            })),
+            uploadTool: await recordSymbolFile(input.crashlyticsSymbols.uploadTool),
+            googleServiceInfo: await recordSymbolFile(input.crashlyticsSymbols.googleServiceInfo),
+        };
+    const artifactSha256 = await sha256File(input.artifactFile);
     const manifestBytes = readFileSync(input.releaseManifestFile);
     const releaseManifestSha256 = createHash('sha256').update(manifestBytes).digest('hex');
     if (artifactSha256 !== input.expectedArtifactSha256
@@ -331,6 +352,8 @@ export async function recordNativeReleaseBuild(input) {
             ...(input.target === 'android'
                 ? { inspectedSignerSha256: signer }
                 : { inspectedTeamId: input.inspectedTeamId ?? '' }),
+            ...(r8Mapping === undefined ? {} : { r8Mapping }),
+            ...(crashlyticsSymbols === undefined ? {} : { crashlyticsSymbols }),
         };
         const key = `${input.releaseKey}/${input.target}`;
         const previous = ownValue(game.builds, key);
@@ -377,6 +400,8 @@ export async function readNativeReleaseStatus(input) {
                 ...(game.submissions?.[iosKey] === undefined
                     ? {} : { ios: game.submissions[iosKey] }),
             },
+            symbolUploads: game.symbolUploads?.[iosKey] === undefined
+                ? {} : { ios: game.symbolUploads[iosKey] },
             stateCommit: session.previousCommit,
         };
     });
@@ -529,6 +554,57 @@ export async function releaseNativeSubmissionLease(input) {
         return checkpoint;
     });
 }
+/**
+ * Record the outcome of a Crashlytics dSYM upload for one recorded iOS build.
+ * A failure can be recorded again and retried; once `uploaded`, it stays so.
+ */
+export async function recordCrashSymbolUpload(input) {
+    assertReleaseKey(input.releaseKey);
+    const upload = {
+        releaseKey: input.releaseKey,
+        target: 'ios',
+        buildRunId: input.buildRunId,
+        dsymArchiveSha256: input.dsymArchiveSha256,
+        status: input.status,
+        updatedAt: new Date().toISOString(),
+        ...(input.status === 'failed' && input.failure !== undefined
+            ? { failure: boundedFailure(input.failure) } : {}),
+    };
+    assertCrashSymbolUploadRecord(upload);
+    return withStateSession(input, async (session) => {
+        const game = ownValue(session.state.games, input.gameId);
+        const key = `${input.releaseKey}/ios`;
+        const build = game === undefined ? undefined : ownValue(game.builds, key);
+        if (game === undefined || build === undefined
+            || build.buildRunId !== input.buildRunId
+            || build.crashlyticsSymbols?.dsymArchive.sha256 !== input.dsymArchiveSha256) {
+            throw new Error('A dSYM upload must reference the immutable iOS build record.');
+        }
+        const previous = ownValue(game.symbolUploads ?? {}, key);
+        if (previous?.status === 'uploaded') {
+            if (input.status === 'uploaded') {
+                return previous;
+            }
+            throw new Error('The dSYMs of this build were already uploaded.');
+        }
+        const next = {
+            schemaVersion: 1,
+            games: {
+                ...session.state.games,
+                [input.gameId]: {
+                    ...game,
+                    symbolUploads: { ...(game.symbolUploads ?? {}), [key]: upload },
+                },
+            },
+        };
+        await commitState(session, next, `Symbols ${input.gameId}/${key} ${input.status}`);
+        return upload;
+    });
+}
+function boundedFailure(text) {
+    const line = text.replace(/[\u0000-\u001f\u007f]+/gu, ' ').trim();
+    return line.length > 300 ? `${line.slice(0, 297)}...` : (line === '' ? 'failed' : line);
+}
 /** Exported for tests: the checkpoint status moves a store submission may make. */
 export function allowedSubmissionTransition(from, to) {
     if (from === to) {
@@ -719,13 +795,14 @@ function parseReleaseState(json) {
         }
         const game = rawGame;
         if (Object.keys(game).some((key) => ![
-            'initialLedger', 'ledger', 'reservations', 'builds', 'submissions',
+            'initialLedger', 'ledger', 'reservations', 'builds', 'submissions', 'symbolUploads',
         ].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))) {
+            || (game.submissions !== undefined && !isRecord(game.submissions))
+            || (game.symbolUploads !== undefined && !isRecord(game.symbolUploads))) {
             throw new Error(`Release state game ${gameId} has invalid entries.`);
         }
         const initialLedger = assertPlatformVersionLedger(game.initialLedger);
@@ -789,6 +866,20 @@ function parseReleaseState(json) {
                 throw new Error(`Release state game ${gameId} has an invalid submission ${key}.`);
             }
         }
+        for (const [key, rawUpload] of Object.entries(game.symbolUploads ?? {})) {
+            const build = game.builds[key];
+            try {
+                assertCrashSymbolUploadRecord(rawUpload);
+            }
+            catch {
+                throw new Error(`Release state game ${gameId} has an invalid dSYM upload ${key}.`);
+            }
+            if (key !== `${rawUpload.releaseKey}/ios` || build === undefined
+                || rawUpload.buildRunId !== build.buildRunId
+                || rawUpload.dsymArchiveSha256 !== build.crashlyticsSymbols?.dsymArchive.sha256) {
+                throw new Error(`Release state game ${gameId} has an invalid dSYM upload ${key}.`);
+            }
+        }
     }
     return value;
 }
@@ -813,6 +904,8 @@ const buildRecordFields = [
     'inspectedAppId',
     'inspectedSignerSha256',
     'inspectedTeamId',
+    'r8Mapping',
+    'crashlyticsSymbols',
 ];
 function assertStoredBuildRecord(gameId, buildKey, value, reservations) {
     const malformed = () => {
@@ -853,7 +946,11 @@ function assertStoredBuildRecord(gameId, buildKey, value, reservations) {
             || !sha256Pattern.test(String(record.inspectedSignerSha256))))
         || (record.target === 'ios' && (record.inspectedSignerSha256 !== undefined
             || !teamIdPattern.test(String(record.inspectedTeamId))))
-        || !isRecord(record.platformVersion)) {
+        || !isRecord(record.platformVersion)
+        || (record.r8Mapping !== undefined
+            && (record.target !== 'android' || !isRecordedSymbolFile(record.r8Mapping)))
+        || (record.crashlyticsSymbols !== undefined
+            && (record.target !== 'ios' || !isRecordedCrashlyticsSymbols(record.crashlyticsSymbols)))) {
         malformed();
     }
     const plan = ownValue(reservations, record.releaseKey);
@@ -930,6 +1027,53 @@ export function assertNativeSubmissionCheckpoint(value) {
         throw new Error('Native submission checkpoint is malformed.');
     }
 }
+const recordedLocationPattern = /^[A-Za-z0-9._-][A-Za-z0-9._ +-]*(?:\/[A-Za-z0-9._-][A-Za-z0-9._ +-]*)*$/u;
+/** A game-relative location without `..` segments. */
+export function isRecordedLocation(location) {
+    return typeof location === 'string' && location.length <= 512
+        && recordedLocationPattern.test(location)
+        && !location.split('/').some((segment) => segment === '.' || segment === '..');
+}
+function isRecordedSymbolFile(value) {
+    return isRecord(value) && Object.keys(value).every((key) => key === 'location' || key === 'sha256')
+        && isRecordedLocation(value.location) && sha256Pattern.test(String(value.sha256));
+}
+function isRecordedCrashlyticsSymbols(value) {
+    return isRecord(value)
+        && Object.keys(value).every((key) => ['dsymArchive', 'dsyms', 'uploadTool', 'googleServiceInfo'].includes(key))
+        && isRecordedSymbolFile(value.dsymArchive) && isRecordedSymbolFile(value.uploadTool)
+        && isRecordedSymbolFile(value.googleServiceInfo) && isDsymIdentityList(value.dsyms);
+}
+const symbolUploadFields = [
+    'releaseKey',
+    'target',
+    'buildRunId',
+    'dsymArchiveSha256',
+    'status',
+    'updatedAt',
+    'failure',
+];
+function assertCrashSymbolUploadRecord(value) {
+    if (!isRecord(value)
+        || Object.keys(value).some((key) => !symbolUploadFields.includes(key))
+        || typeof value.releaseKey !== 'string' || !releaseKeyPattern.test(value.releaseKey)
+        || value.target !== 'ios'
+        || typeof value.buildRunId !== 'string' || value.buildRunId.trim() === ''
+        || !sha256Pattern.test(String(value.dsymArchiveSha256))
+        || (value.status !== 'uploaded' && value.status !== 'failed')
+        || typeof value.updatedAt !== 'string' || !Number.isFinite(Date.parse(value.updatedAt))
+        || (value.failure !== undefined && (value.status !== 'failed'
+            || typeof value.failure !== 'string' || value.failure.length > 300))) {
+        throw new Error('Crashlytics dSYM upload record is malformed.');
+    }
+}
+async function recordSymbolFile(input) {
+    if (!isRecordedLocation(input.location) || !existsSync(input.file)
+        || !statSync(input.file).isFile() || statSync(input.file).size === 0) {
+        throw new Error('Native build symbol file is missing or has an invalid location.');
+    }
+    return { location: input.location, sha256: await sha256File(input.file) };
+}
 function assertReservationHistory(gameId, initialLedger, ledger, plans) {
     if (plans.length === 0) {
         throw new Error(`Release state game ${gameId} has no reservation history.`);
@@ -993,7 +1137,8 @@ function assertReleaseKey(key) {
         throw new Error('Release key must be a lowercase, path-safe identifier.');
     }
 }
-async function sha256(file) {
+/** Streamed SHA-256 of a file, hex. */
+export async function sha256File(file) {
     const hash = createHash('sha256');
     for await (const chunk of createReadStream(file)) {
         hash.update(chunk);

package/dist/release-workspace.d.ts

@@ -1,4 +1,5 @@
 import { type NativeDeploymentPlan } from './deploy-planning.js';
+import { type NativeBuildSymbols } from './native-build-symbols.js';
 export interface PinnedReleaseInput {
   readonly gameRoot: string;
   readonly deploymentProfile: string;
@@ -21,6 +22,8 @@ export interface PinnedNativeBuildResult {
   readonly artifact: string;
   readonly releaseManifest: string;
   readonly runId: string;
+  /** Crash symbols of this build, as absolute paths inside the pinned game. */
+  readonly symbols?: NativeBuildSymbols;
 }
 /** Freeze a read-only deployment plan into the exact inputs used by a release run. */
 export declare function pinNativeDeploymentPlan(plan: NativeDeploymentPlan, kit: {

package/dist/release-workspace.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { planNativeDeployment } from './deploy-planning.js';
+import { assertNativeBuildSymbols, isNativeOutputPath, } from './native-build-symbols.js';
 import { runReleaseProcess, } from './deploy-process.js';
 const gitShaPattern = /^[0-9a-f]{40}$/u;
 const sha256Pattern = /^[0-9a-f]{64}$/u;
@@ -287,7 +288,49 @@ export async function runPinnedNativeBuild(workspace, input) {
         || manifest.kitGitSha !== workspace.input.kitGitSha) {
         throw new Error('Pinned native build manifest provenance does not match its inputs.');
     }
-    return { artifact, releaseManifest, runId: status.runId };
+    const symbols = status.symbols === undefined
+        ? undefined
+        : resolvePinnedBuildSymbols(workspace.gameRoot, input.target, status.symbols);
+    return {
+        artifact,
+        releaseManifest,
+        runId: status.runId,
+        ...(symbols === undefined ? {} : { symbols }),
+    };
+}
+/** Resolve the status file's symbol paths to regular files inside the pinned game. */
+function resolvePinnedBuildSymbols(gameRoot, target, value) {
+    assertNativeBuildSymbols(value, (file) => isNativeOutputPath(file, target));
+    const canonicalGameRoot = realpathSync(gameRoot);
+    const resolve = (file) => {
+        const absolute = assertInsideWorkspace(gameRoot, file);
+        if (!existsSync(absolute) || !lstatSync(absolute).isFile()) {
+            throw new Error(`Pinned native build symbol file is missing: ${file}`);
+        }
+        const relative = path.relative(canonicalGameRoot, realpathSync(absolute));
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new Error('Pinned native build symbol file resolves outside its workspace.');
+        }
+        return absolute;
+    };
+    if (value.r8Mapping !== undefined) {
+        if (target !== 'android') {
+            throw new Error('Only an Android build records an R8 mapping file.');
+        }
+        return { r8Mapping: resolve(value.r8Mapping) };
+    }
+    const crashlytics = value.crashlytics;
+    if (crashlytics === undefined || target !== 'ios') {
+        throw new Error('Only an iOS build records Crashlytics dSYMs.');
+    }
+    return {
+        crashlytics: {
+            dsymArchive: resolve(crashlytics.dsymArchive),
+            dsyms: crashlytics.dsyms,
+            uploadTool: resolve(crashlytics.uploadTool),
+            googleServiceInfo: resolve(crashlytics.googleServiceInfo),
+        },
+    };
 }
 function assertPinnedInput(input) {
     if (!gitShaPattern.test(input.gameGitSha) || !gitShaPattern.test(input.kitGitSha)