@git.zone/tsrust 1.8.0 → 1.9.0

package/ts/mod_artifact/index.ts

@@ -0,0 +1,6 @@
+export {
+  ArtifactAssembler,
+  type IArtifactAssemblerOptions,
+  type IArtifactAssemblyResult,
+  type IArtifactTarget,
+} from './classes.artifactassembler.js';

package/ts/mod_cli/classes.tsrustcli.ts

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as plugins from '../plugins.js';
+import { ArtifactAssembler } from '../mod_artifact/index.js';
 import { CargoConfig } from '../mod_cargo/index.js';
 import { CargoRunner } from '../mod_cargo/index.js';
 import {
@@ -12,56 +13,22 @@ import {
   resolveManagedTargetDir,
   writeTargetCacheMarker,
 } from '../mod_cargo/index.js';
-import { ElfInspector, ProvenanceStamper, type ITsrustBuildInfo } from '../mod_elf/index.js';
+import { ElfInspector, type ITsrustBuildInfo } from '../mod_elf/index.js';
 import { FsHelpers } from '../mod_fs/index.js';
+import {
+  assertGitSnapshotUnchanged,
+  captureGitSnapshot,
+  ProvenanceStore,
+  type IGitSnapshot,
+} from '../mod_provenance/index.js';
 import { ToolchainManager } from '../mod_toolchain/index.js';
 import { commitinfo } from '../00_commitinfo_data.js';
-
-/** Maps friendly target names to Rust target triples */
-const targetAliasMap: Record<string, string> = {
-  linux_amd64: 'x86_64-unknown-linux-gnu',
-  linux_arm64: 'aarch64-unknown-linux-gnu',
-  linux_amd64_musl: 'x86_64-unknown-linux-musl',
-  linux_arm64_musl: 'aarch64-unknown-linux-musl',
-  macos_amd64: 'x86_64-apple-darwin',
-  macos_arm64: 'aarch64-apple-darwin',
-};
-
-/** Reverse map: Rust triple → friendly name */
-const tripleToFriendlyMap: Record<string, string> = {};
-for (const [friendly, triple] of Object.entries(targetAliasMap)) {
-  tripleToFriendlyMap[triple] = friendly;
-}
-
-/**
- * Resolves a user-provided target name to a Rust target triple.
- * Accepts both friendly names (linux_arm64) and raw triples (aarch64-unknown-linux-gnu).
- */
-function resolveTargetAlias(name: string): string {
-  return targetAliasMap[name] || name;
-}
-
-/**
- * Derives a friendly name from a Rust target triple for use in output filenames.
- * Falls back to the raw triple with dashes replaced by underscores.
- */
-function friendlyName(triple: string): string {
-  if (tripleToFriendlyMap[triple]) {
-    return tripleToFriendlyMap[triple];
-  }
-  // Derive from triple: e.g. x86_64-unknown-linux-gnu → x86_64_unknown_linux_gnu
-  return triple.replace(/-/g, '_');
-}
-
-interface ITsrustConfig {
-  targets?: string[];
-  locked?: boolean;
-  static?: boolean;
-  rustflags?: string[];
-  remapLocalPaths?: boolean;
-  targetDir?: string;
-  pruneAfterBuild?: boolean;
-}
+import {
+  configuredAssemblyTargets,
+  normalizeTargets,
+  resolveBuildTargets,
+  type ITsrustConfig,
+} from './helpers.targets.js';
 
 /** crt-static injection only applies to glibc targets; musl is static by default. */
 function wantsCrtStatic(triple: string): boolean {
@@ -89,15 +56,11 @@ export class TsRustCli {
     this.registerStandardCommand();
     this.registerCleanCommand();
     this.registerPruneCommand();
+    this.registerAssembleCommand();
     this.registerInspectCommand();
   }
 
-  /**
-   * Collects build provenance once per run: consuming project identity,
-   * git commit, and the tsrust version doing the build. Tolerant of
-   * non-git checkouts and missing package metadata.
-   */
-  private async collectBuildProvenance(): Promise<Omit<ITsrustBuildInfo, 'binary' | 'target'>> {
+  private readProjectIdentity(): { projectName: string; projectVersion: string } {
     let projectName = 'unknown';
     let projectVersion = 'unknown';
     try {
@@ -109,25 +72,40 @@ export class TsRustCli {
     } catch {
       // package.json optional for pure Rust workspaces
     }
-    let gitCommit = 'unknown';
-    try {
-      const shell = new plugins.smartshell.Smartshell({ executor: 'bash' });
-      const result = await shell.execSilent(`git -C ${JSON.stringify(this.cwd)} rev-parse HEAD`);
-      if (result.exitCode === 0) {
-        gitCommit = result.stdout.trim();
-      }
-    } catch {
-      // not a git checkout
-    }
+    return { projectName, projectVersion };
+  }
+
+  /**
+   * Collects build provenance for one Cargo invocation: consuming project identity,
+   * git commit, and the tsrust version doing the build. Tolerant of
+   * non-git checkouts and missing package metadata.
+   */
+  private collectBuildProvenance(
+    gitSnapshotArg: IGitSnapshot,
+  ): Omit<ITsrustBuildInfo, 'binary' | 'target'> {
+    const { projectName, projectVersion } = this.readProjectIdentity();
     return {
       projectName,
       projectVersion,
-      gitCommit,
+      gitCommit: gitSnapshotArg.commit,
+      gitDirty: gitSnapshotArg.available ? gitSnapshotArg.status.length > 0 : undefined,
       builtAt: new Date().toISOString(),
       tsrustVersion: commitinfo.version,
     };
   }
 
+  private assertProjectIdentityUnchanged(
+    beforeArg: Omit<ITsrustBuildInfo, 'binary' | 'target'>,
+    afterArg: Omit<ITsrustBuildInfo, 'binary' | 'target'>,
+  ): void {
+    if (
+      beforeArg.projectName !== afterArg.projectName ||
+      beforeArg.projectVersion !== afterArg.projectVersion
+    ) {
+      throw new Error('Project package identity changed while Cargo was building');
+    }
+  }
+
   /**
    * Resolves the Rust toolchain to use. Tries system cargo first,
    * then falls back to a bundled toolchain at /tmp/tsrust_toolchain/.
@@ -183,17 +161,19 @@ export class TsRustCli {
       console.log(`Binary targets: ${workspaceInfo.binTargets.join(', ')}`);
 
       const isDebug = !!(argvArg as any).debug;
-      const shouldClean = !!(argvArg as any).clean;
+      let shouldClean = !!(argvArg as any).clean;
       const distDir = path.join(this.cwd, 'dist_rust');
       const profile = isDebug ? 'debug' : 'release';
       const managedTargetDir = resolveManagedTargetDir(this.cwd, this.config.targetDir);
       await writeTargetCacheMarker(managedTargetDir);
 
-      // Parse --target flag (can appear multiple times), fall back to smartconfig.json config
+      // CLI targets override host-specific and legacy configured targets.
       const cliTargets = (argvArg as any).target;
-      const targets: string[] = cliTargets
+      const cliTargetList: string[] | undefined = cliTargets
         ? (Array.isArray(cliTargets) ? cliTargets : [cliTargets])
-        : this.config.targets || [];
+        : undefined;
+      const hostTriple = new ToolchainManager().getHostTriple();
+      const resolvedTargets = resolveBuildTargets(this.config, hostTriple, cliTargetList);
 
       const useStatic = !!(argvArg as any).static || !!this.config.static;
       if (useStatic) {
@@ -205,25 +185,24 @@ export class TsRustCli {
         console.log(`Using additional Rust flags: ${rustflags.join(' ')}`);
       }
 
-      const buildProvenance = await this.collectBuildProvenance();
-
-      if (targets.length > 0) {
+      if (resolvedTargets.length > 0) {
         // Cross-compilation mode
-        const resolvedTargets = targets.map((t: string) => ({
-          triple: resolveTargetAlias(t),
-          friendly: friendlyName(resolveTargetAlias(t)),
-        }));
-
-        console.log(`Cross-compiling for: ${resolvedTargets.map((t) => `${t.friendly} (${t.triple})`).join(', ')}`);
+        console.log(
+          `Cross-compiling for: ${resolvedTargets.map((target) => `${target.friendly} (${target.triple})`).join(', ')}`,
+        );
 
         await FsHelpers.ensureEmptyDir(distDir);
 
         for (const { triple, friendly } of resolvedTargets) {
           console.log(`\n--- Building for ${friendly} (${triple}) ---`);
           if (useStatic && !isLinuxTriple(triple)) {
-            console.log(`Note: static linking is not applicable for ${triple}; building with default linkage.`);
+            console.log(
+              `Note: static linking is not applicable for ${triple}; building with default linkage.`,
+            );
           }
           const cargoRunner = new CargoRunner(rustDir, envPrefix);
+          const gitBefore = await captureGitSnapshot(this.cwd);
+          const provenanceBefore = this.collectBuildProvenance(gitBefore);
           const buildResult = await cargoRunner.build({
             debug: isDebug,
             clean: shouldClean,
@@ -238,6 +217,10 @@ export class TsRustCli {
             console.error(`Build failed for target ${triple} with exit code ${buildResult.exitCode}`);
             process.exit(1);
           }
+          const gitAfter = await captureGitSnapshot(this.cwd);
+          assertGitSnapshotUnchanged(gitBefore, gitAfter);
+          const provenanceAfter = this.collectBuildProvenance(gitAfter);
+          this.assertProjectIdentityUnchanged(provenanceBefore, provenanceAfter);
 
           const targetDir = getCargoArtifactDir(managedTargetDir, profile, triple);
 
@@ -255,27 +238,33 @@ export class TsRustCli {
             await FsHelpers.makeExecutable(destBinary);
 
             const size = await FsHelpers.getFileSize(destBinary);
-            console.log(`Copied ${binName} (${FsHelpers.formatFileSize(size)}) -> dist_rust/${destName}`);
+            console.log(
+              `Copied ${binName} (${FsHelpers.formatFileSize(size)}) -> dist_rust/${destName}`,
+            );
 
             if (useStatic && isLinuxTriple(triple)) {
               if (!(await ElfInspector.isStaticElf(destBinary))) {
-                console.error(`Error: ${destName} is not statically linked (PT_INTERP present) although static linking was requested.`);
+                console.error(
+                  `Error: ${destName} is not statically linked (PT_INTERP present) although static linking was requested.`,
+                );
                 process.exit(1);
               }
               console.log(`Verified statically linked: dist_rust/${destName}`);
             }
 
-            await ProvenanceStamper.stamp(destBinary, {
-              ...buildProvenance,
+            await ProvenanceStore.write(destBinary, {
+              ...provenanceBefore,
               binary: binName,
               target: friendly,
             });
-            console.log(`Stamped provenance: ${buildProvenance.projectName}@${buildProvenance.projectVersion} ${buildProvenance.gitCommit.slice(0, 12)} (${friendly})`);
+            console.log(
+              `Wrote provenance: ${provenanceBefore.projectName}@${provenanceBefore.projectVersion} ${provenanceBefore.gitCommit.slice(0, 12)} (${friendly})`,
+            );
           }
 
           // Only clean on first iteration
           if (shouldClean) {
-            (argvArg as any).clean = false;
+            shouldClean = false;
           }
         }
       } else {
@@ -284,13 +273,17 @@ export class TsRustCli {
         // (proc-macros cannot build with +crt-static on linux-gnu).
         let nativeTriple: string | undefined;
         if (useStatic) {
-          nativeTriple = new ToolchainManager().getHostTriple();
+          nativeTriple = hostTriple;
           if (!isLinuxTriple(nativeTriple)) {
-            console.log(`Note: static linking is not applicable for ${nativeTriple}; building with default linkage.`);
+            console.log(
+              `Note: static linking is not applicable for ${nativeTriple}; building with default linkage.`,
+            );
           }
         }
 
         const cargoRunner = new CargoRunner(rustDir, envPrefix);
+        const gitBefore = await captureGitSnapshot(this.cwd);
+        const provenanceBefore = this.collectBuildProvenance(gitBefore);
         const buildResult = await cargoRunner.build({
           debug: isDebug,
           clean: shouldClean,
@@ -305,6 +298,10 @@ export class TsRustCli {
           console.error(`Build failed with exit code ${buildResult.exitCode}`);
           process.exit(1);
         }
+        const gitAfter = await captureGitSnapshot(this.cwd);
+        assertGitSnapshotUnchanged(gitBefore, gitAfter);
+        const provenanceAfter = this.collectBuildProvenance(gitAfter);
+        this.assertProjectIdentityUnchanged(provenanceBefore, provenanceAfter);
 
         const targetDir = getCargoArtifactDir(managedTargetDir, profile, nativeTriple);
 
@@ -323,22 +320,28 @@ export class TsRustCli {
           await FsHelpers.makeExecutable(destBinary);
 
           const size = await FsHelpers.getFileSize(destBinary);
-          console.log(`Copied ${binName} (${FsHelpers.formatFileSize(size)}) -> dist_rust/${binName}`);
+          console.log(
+            `Copied ${binName} (${FsHelpers.formatFileSize(size)}) -> dist_rust/${binName}`,
+          );
 
           if (useStatic && nativeTriple && isLinuxTriple(nativeTriple)) {
             if (!(await ElfInspector.isStaticElf(destBinary))) {
-              console.error(`Error: ${binName} is not statically linked (PT_INTERP present) although static linking was requested.`);
+              console.error(
+                `Error: ${binName} is not statically linked (PT_INTERP present) although static linking was requested.`,
+              );
               process.exit(1);
             }
             console.log(`Verified statically linked: dist_rust/${binName}`);
           }
 
-          await ProvenanceStamper.stamp(destBinary, {
-            ...buildProvenance,
+          await ProvenanceStore.write(destBinary, {
+            ...provenanceBefore,
             binary: binName,
             target: nativeTriple || 'native',
           });
-          console.log(`Stamped provenance: ${buildProvenance.projectName}@${buildProvenance.projectVersion} ${buildProvenance.gitCommit.slice(0, 12)} (${nativeTriple || 'native'})`);
+          console.log(
+            `Wrote provenance: ${provenanceBefore.projectName}@${provenanceBefore.projectVersion} ${provenanceBefore.gitCommit.slice(0, 12)} (${nativeTriple || 'native'})`,
+          );
         }
       }
 
@@ -359,7 +362,13 @@ export class TsRustCli {
 
   private shouldPruneAfterBuild(): boolean {
     const normalized = process.env.TSRUST_PRUNE_AFTER_BUILD?.toLowerCase();
-    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'y' || this.config.pruneAfterBuild === true;
+    return (
+      normalized === '1' ||
+      normalized === 'true' ||
+      normalized === 'yes' ||
+      normalized === 'y' ||
+      this.config.pruneAfterBuild === true
+    );
   }
 
   private buildRustflags(rustDir: string): string[] {
@@ -381,7 +390,7 @@ export class TsRustCli {
   }
 
   /**
-   * `tsrust inspect <binary>` — prints the embedded build provenance so any
+   * `tsrust inspect <binary>` — verifies and prints build provenance so any
    * environment can answer "what is this binary built from" definitively.
    */
   private registerInspectCommand(): void {
@@ -394,15 +403,73 @@ export class TsRustCli {
       const resolvedPath = path.isAbsolute(binaryPath)
         ? binaryPath
         : path.join(this.cwd, binaryPath);
-      const info = await ProvenanceStamper.read(resolvedPath);
+      const info = await ProvenanceStore.read(resolvedPath);
       if (!info) {
-        console.error(`No tsrust build provenance found in ${resolvedPath} (built before tsrust 1.7.0?).`);
+        console.error(`No tsrust build provenance found in ${resolvedPath}.`);
         process.exit(1);
       }
       console.log(JSON.stringify(info, null, 2));
     });
   }
 
+  private registerAssembleCommand(): void {
+    this.cli.addCommand('assemble').subscribe(async (argvArg) => {
+      const sourceDirectories = ((argvArg as any)._ as unknown[])
+        .slice(1)
+        .map((sourceDirectory) => String(sourceDirectory));
+      if (sourceDirectories.length === 0) {
+        throw new Error('Usage: tsrust assemble <artifact-directory> [...]');
+      }
+
+      const cliTargets = (argvArg as any).target;
+      const cliTargetList: string[] | undefined = cliTargets
+        ? (Array.isArray(cliTargets) ? cliTargets : [cliTargets])
+        : undefined;
+      const expectedTargets = cliTargetList
+        ? normalizeTargets(cliTargetList, '--target')
+        : configuredAssemblyTargets(this.config);
+      if (expectedTargets.length === 0) {
+        throw new Error(
+          'Artifact assembly requires configured targets or at least one --target',
+        );
+      }
+
+      const rustDir = await this.detectRustDir();
+      if (!rustDir) {
+        throw new Error('No rust/ or ts_rust/ directory found with a Cargo.toml');
+      }
+      const workspaceInfo = await new CargoConfig(rustDir).parse();
+      if (workspaceInfo.binTargets.length === 0) {
+        throw new Error('No binary targets found in Cargo.toml');
+      }
+
+      const gitSnapshot = await captureGitSnapshot(this.cwd);
+      if (!gitSnapshot.available || gitSnapshot.commit === 'unknown') {
+        throw new Error('Artifact assembly requires a Git checkout');
+      }
+      if (gitSnapshot.status.length > 0) {
+        throw new Error('Artifact assembly requires a clean Git worktree');
+      }
+      const { projectName, projectVersion } = this.readProjectIdentity();
+      const result = await new ArtifactAssembler({
+        workspace: this.cwd,
+        sourceDirectories,
+        expectedTargets,
+        expectedBinaries: workspaceInfo.binTargets,
+        expectedProjectName: projectName,
+        expectedProjectVersion: projectVersion,
+        expectedGitCommit: gitSnapshot.commit,
+        expectedTsrustVersion: commitinfo.version,
+      }).assemble();
+      console.log(
+        `Assembled ${result.artifactCount} artifacts for ${result.targets.join(', ')} into ${result.outputDirectory}`,
+      );
+      if (result.cleanupPending) {
+        console.warn('Artifact assembly committed; stale transaction cleanup will retry next run.');
+      }
+    });
+  }
+
   private registerCleanCommand(): void {
     this.cli.addCommand('clean').subscribe(async (_argvArg) => {
       // Clean cargo build

package/ts/mod_cli/helpers.targets.ts

@@ -0,0 +1,141 @@
+export const targetAliasMap: Record<string, string> = {
+  linux_amd64: 'x86_64-unknown-linux-gnu',
+  linux_arm64: 'aarch64-unknown-linux-gnu',
+  linux_amd64_musl: 'x86_64-unknown-linux-musl',
+  linux_arm64_musl: 'aarch64-unknown-linux-musl',
+  macos_amd64: 'x86_64-apple-darwin',
+  macos_arm64: 'aarch64-apple-darwin',
+};
+
+const tripleToFriendlyMap = Object.fromEntries(
+  Object.entries(targetAliasMap).map(([friendly, triple]) => [triple, friendly]),
+);
+
+const supportedHostKeys = new Set([
+  'linux',
+  'macos',
+  'linux_amd64',
+  'linux_arm64',
+  'macos_amd64',
+  'macos_arm64',
+]);
+
+export interface ITsrustConfig {
+  targets?: string[];
+  targetsByHost?: Record<string, string[]>;
+  locked?: boolean;
+  static?: boolean;
+  rustflags?: string[];
+  remapLocalPaths?: boolean;
+  targetDir?: string;
+  pruneAfterBuild?: boolean;
+}
+
+export interface INormalizedTarget {
+  triple: string;
+  friendly: string;
+}
+
+export function resolveTargetAlias(nameArg: string): string {
+  return targetAliasMap[nameArg] || nameArg;
+}
+
+export function friendlyTargetName(tripleArg: string): string {
+  return tripleToFriendlyMap[tripleArg] || tripleArg.replace(/-/g, '_');
+}
+
+function validateTargetName(nameArg: string): void {
+  if (
+    !nameArg ||
+    nameArg.length > 255 ||
+    !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(nameArg)
+  ) {
+    throw new Error(`Invalid Rust target name: ${JSON.stringify(nameArg)}`);
+  }
+}
+
+export function normalizeTargets(targetsArg: string[], labelArg: string): INormalizedTarget[] {
+  if (!Array.isArray(targetsArg)) {
+    throw new Error(`${labelArg} must be an array of Rust target names`);
+  }
+  const byTriple = new Map<string, INormalizedTarget>();
+  const tripleByFriendly = new Map<string, string>();
+  for (const target of targetsArg) {
+    if (typeof target !== 'string') {
+      throw new Error(`${labelArg} must contain only Rust target names`);
+    }
+    validateTargetName(target);
+    const triple = resolveTargetAlias(target);
+    validateTargetName(triple);
+    const friendly = friendlyTargetName(triple);
+    validateTargetName(friendly);
+    const collidingTriple = tripleByFriendly.get(friendly);
+    if (collidingTriple && collidingTriple !== triple) {
+      throw new Error(
+        `${labelArg} targets ${collidingTriple} and ${triple} share output suffix ${friendly}`,
+      );
+    }
+    tripleByFriendly.set(friendly, triple);
+    byTriple.set(triple, { triple, friendly });
+  }
+  return [...byTriple.values()];
+}
+
+function validateTargetsByHost(configArg: ITsrustConfig): void {
+  if (configArg.targets !== undefined) {
+    normalizeTargets(configArg.targets, 'targets');
+  }
+  if (configArg.targetsByHost === undefined) return;
+  if (
+    !configArg.targetsByHost ||
+    typeof configArg.targetsByHost !== 'object' ||
+    Array.isArray(configArg.targetsByHost)
+  ) {
+    throw new Error('targetsByHost must be an object keyed by supported build hosts');
+  }
+  for (const [host, targets] of Object.entries(configArg.targetsByHost)) {
+    if (!supportedHostKeys.has(host)) {
+      throw new Error(`Unsupported targetsByHost key: ${host}`);
+    }
+    if (!Array.isArray(targets) || targets.length === 0) {
+      throw new Error(`targetsByHost.${host} must be a non-empty target array`);
+    }
+    normalizeTargets(targets, `targetsByHost.${host}`);
+  }
+}
+
+function hostFamily(hostTripleArg: string): 'linux' | 'macos' {
+  if (hostTripleArg.includes('-linux-')) return 'linux';
+  if (hostTripleArg.endsWith('-apple-darwin')) return 'macos';
+  throw new Error(`Unsupported Rust host triple for targetsByHost: ${hostTripleArg}`);
+}
+
+export function resolveBuildTargets(
+  configArg: ITsrustConfig,
+  hostTripleArg: string,
+  cliTargetsArg?: string[],
+): INormalizedTarget[] {
+  validateTargetsByHost(configArg);
+  if (cliTargetsArg !== undefined) {
+    if (cliTargetsArg.length === 0) {
+      throw new Error('--target requires at least one target');
+    }
+    return normalizeTargets(cliTargetsArg, '--target');
+  }
+  const exactHost = friendlyTargetName(hostTripleArg);
+  const configured =
+    configArg.targetsByHost?.[exactHost] ||
+    configArg.targetsByHost?.[hostFamily(hostTripleArg)] ||
+    configArg.targets ||
+    [];
+  return normalizeTargets(configured, 'targets');
+}
+
+export function configuredAssemblyTargets(configArg: ITsrustConfig): INormalizedTarget[] {
+  validateTargetsByHost(configArg);
+  const configured = [
+    ...(configArg.targets || []),
+    ...Object.values(configArg.targetsByHost || {}).flat(),
+  ];
+  return normalizeTargets(configured, 'configured assembly targets');
+}

package/ts/mod_cli/index.ts

@@ -1 +1,11 @@
 export { TsRustCli, runCli } from './classes.tsrustcli.js';
+export {
+  configuredAssemblyTargets,
+  friendlyTargetName,
+  normalizeTargets,
+  resolveBuildTargets,
+  resolveTargetAlias,
+  targetAliasMap,
+  type INormalizedTarget,
+  type ITsrustConfig,
+} from './helpers.targets.js';

package/ts/mod_provenance/classes.gitstate.ts

@@ -0,0 +1,49 @@
+import * as childProcess from 'child_process';
+import * as util from 'util';
+
+const execFile = util.promisify(childProcess.execFile);
+
+export interface IGitSnapshot {
+  available: boolean;
+  commit: string;
+  status: string;
+}
+
+export async function captureGitSnapshot(cwdArg: string): Promise<IGitSnapshot> {
+  let commit: string;
+  try {
+    const result = await execFile('git', ['-C', cwdArg, 'rev-parse', 'HEAD'], {
+      encoding: 'utf8',
+    });
+    commit = result.stdout.trim();
+  } catch {
+    return { available: false, commit: 'unknown', status: '' };
+  }
+  try {
+    const status = await execFile(
+      'git',
+      ['-C', cwdArg, 'status', '--porcelain=v1', '--untracked-files=all'],
+      { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+    );
+    return {
+      available: true,
+      commit,
+      status: status.stdout,
+    };
+  } catch {
+    throw new Error('Failed to inspect Git worktree state');
+  }
+}
+
+export function assertGitSnapshotUnchanged(
+  beforeArg: IGitSnapshot,
+  afterArg: IGitSnapshot,
+): void {
+  if (
+    beforeArg.available !== afterArg.available ||
+    beforeArg.commit !== afterArg.commit ||
+    beforeArg.status !== afterArg.status
+  ) {
+    throw new Error('Git source state changed while Cargo was building');
+  }
+}