@git.zone/tsrust 1.7.0 → 1.9.0

package/ts/mod_artifact/classes.artifactassembler.ts

@@ -0,0 +1,1028 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { ITsrustBuildInfo } from '../mod_elf/index.js';
+import {
+  captureGitSnapshot,
+  getHostIdentity,
+  isLocalProcessRunning,
+  PROVENANCE_SIDECAR_SUFFIX,
+  ProvenanceStore,
+} from '../mod_provenance/index.js';
+
+const TRANSACTION_FORMAT = 'tsrust.artifact-assembly.v1';
+const LOCK_FORMAT = 'tsrust.artifact-assembly-lock.v1';
+const RECOVERY_CLAIM_FORMAT = 'tsrust.artifact-assembly-recovery.v1';
+const TRANSACTION_DIRECTORY = 'tsrust-assembly';
+const activeOwnerTokens = new Set<string>();
+const processOwnerTokens = new Set<string>();
+
+type TAssemblyPhase =
+  | 'preparing'
+  | 'prepared'
+  | 'movingOld'
+  | 'oldMoved'
+  | 'publishing'
+  | 'published'
+  | 'committing'
+  | 'committed';
+
+export interface IArtifactTarget {
+  triple: string;
+  friendly: string;
+}
+
+export interface IArtifactAssemblerOptions {
+  workspace: string;
+  sourceDirectories: string[];
+  expectedTargets: IArtifactTarget[];
+  expectedBinaries: string[];
+  expectedProjectName: string;
+  expectedProjectVersion: string;
+  expectedGitCommit: string;
+  expectedTsrustVersion: string;
+}
+
+export interface IArtifactAssemblyResult {
+  outputDirectory: string;
+  artifactCount: number;
+  binaries: string[];
+  targets: string[];
+  cleanupPending: boolean;
+}
+
+interface IArtifactCandidate {
+  binaryPath: string;
+  sidecarPath: string;
+  destinationName: string;
+  buildInfo: ITsrustBuildInfo;
+}
+
+interface IAssemblyPaths {
+  workspace: string;
+  outputDirectory: string;
+  transactionParent: string;
+  transactionDirectory: string;
+  lockPath: string;
+  lockSourcePath: string;
+  recoveryClaimPath: string;
+  statePath: string;
+  stateTemporaryPath: string;
+  stagingDirectory: string;
+  backupDirectory: string;
+  failedDirectory: string;
+}
+
+interface IAssemblyTransactionState {
+  format: typeof TRANSACTION_FORMAT;
+  pid: number;
+  hostname: string;
+  hostIdentity: string;
+  ownerToken: string;
+  startedAt: string;
+  phase: TAssemblyPhase;
+  hadExistingOutput: boolean;
+}
+
+interface IAssemblyOwnerIdentity {
+  pid: number;
+  hostname: string;
+  hostIdentity: string;
+  ownerToken: string;
+  startedAt: string;
+}
+
+interface IAssemblyLockOwner extends IAssemblyOwnerIdentity {
+  format: typeof LOCK_FORMAT;
+}
+
+interface IAssemblyRecoveryClaim extends IAssemblyOwnerIdentity {
+  format: typeof RECOVERY_CLAIM_FORMAT;
+  targetOwnerToken: string;
+}
+
+function isSameOrWithin(parentArg: string, candidateArg: string): boolean {
+  const relative = path.relative(parentArg, candidateArg);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+async function lstatOptional(filePathArg: string): Promise<fs.Stats | undefined> {
+  try {
+    return await fs.promises.lstat(filePathArg);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+async function syncFile(filePathArg: string): Promise<void> {
+  const handle = await fs.promises.open(filePathArg, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function syncDirectory(directoryPathArg: string): Promise<void> {
+  const handle = await fs.promises.open(directoryPathArg, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+function assertArtifactName(nameArg: string, labelArg: string): void {
+  if (!nameArg || nameArg.length > 255 || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(nameArg)) {
+    throw new Error(`Invalid ${labelArg}: ${JSON.stringify(nameArg)}`);
+  }
+}
+
+function isProvenanceTemporaryFile(nameArg: string): boolean {
+  return /\.tsrust-build\.json\.[a-f0-9]{64}\.\d+\.[a-f0-9-]{36}\.tmp$/.test(nameArg);
+}
+
+function isTransactionState(valueArg: unknown): valueArg is IAssemblyTransactionState {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const value = valueArg as Record<string, unknown>;
+  return (
+    value.format === TRANSACTION_FORMAT &&
+    typeof value.pid === 'number' &&
+    typeof value.hostname === 'string' &&
+    typeof value.hostIdentity === 'string' &&
+    /^[a-f0-9]{64}$/.test(value.hostIdentity) &&
+    typeof value.ownerToken === 'string' &&
+    /^[a-f0-9-]{36}$/.test(value.ownerToken) &&
+    typeof value.startedAt === 'string' &&
+    [
+      'preparing',
+      'prepared',
+      'movingOld',
+      'oldMoved',
+      'publishing',
+      'published',
+      'committing',
+      'committed',
+    ].includes(String(value.phase)) &&
+    typeof value.hadExistingOutput === 'boolean'
+  );
+}
+
+function isLockOwner(valueArg: unknown): valueArg is IAssemblyLockOwner {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const value = valueArg as Record<string, unknown>;
+  return (
+    value.format === LOCK_FORMAT &&
+    typeof value.pid === 'number' &&
+    typeof value.hostname === 'string' &&
+    typeof value.hostIdentity === 'string' &&
+    /^[a-f0-9]{64}$/.test(value.hostIdentity) &&
+    typeof value.ownerToken === 'string' &&
+    /^[a-f0-9-]{36}$/.test(value.ownerToken) &&
+    typeof value.startedAt === 'string'
+  );
+}
+
+function isRecoveryClaim(valueArg: unknown): valueArg is IAssemblyRecoveryClaim {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
+  const value = valueArg as Record<string, unknown>;
+  return (
+    value.format === RECOVERY_CLAIM_FORMAT &&
+    typeof value.pid === 'number' &&
+    typeof value.hostname === 'string' &&
+    typeof value.hostIdentity === 'string' &&
+    /^[a-f0-9]{64}$/.test(value.hostIdentity) &&
+    typeof value.ownerToken === 'string' &&
+    /^[a-f0-9-]{36}$/.test(value.ownerToken) &&
+    typeof value.startedAt === 'string' &&
+    typeof value.targetOwnerToken === 'string' &&
+    /^[a-f0-9-]{36}$/.test(value.targetOwnerToken)
+  );
+}
+
+export class ArtifactAssembler {
+  private options: IArtifactAssemblerOptions;
+
+  constructor(optionsArg: IArtifactAssemblerOptions) {
+    this.options = optionsArg;
+  }
+
+  public async assemble(): Promise<IArtifactAssemblyResult> {
+    const ownerToken = crypto.randomUUID();
+    const paths = this.createPaths(ownerToken);
+    const sourceDirectories = this.options.sourceDirectories.map((sourceDirectory) =>
+      path.resolve(paths.workspace, sourceDirectory),
+    );
+    this.validateOptions(paths, sourceDirectories);
+
+    let state: IAssemblyTransactionState = {
+      format: TRANSACTION_FORMAT,
+      pid: process.pid,
+      hostname: os.hostname(),
+      hostIdentity: getHostIdentity(),
+      ownerToken,
+      startedAt: new Date().toISOString(),
+      phase: 'preparing',
+      hadExistingOutput: false,
+    };
+    await this.ensureTransactionParent(paths);
+    processOwnerTokens.add(ownerToken);
+    try {
+      await this.acquireTransaction(paths, state);
+    } catch (error) {
+      try {
+        const lockOwner = await this.readLock(paths);
+        if (lockOwner?.ownerToken !== ownerToken) processOwnerTokens.delete(ownerToken);
+      } catch {
+        // Retain the token only when lock ownership cannot be determined safely.
+      }
+      throw error;
+    }
+    let commitReached = false;
+    let retainOwnerToken = false;
+    activeOwnerTokens.add(ownerToken);
+    try {
+      const output = await lstatOptional(paths.outputDirectory);
+      if (output && (!output.isDirectory() || output.isSymbolicLink())) {
+        throw new Error(`Assembly output is not a regular directory: ${paths.outputDirectory}`);
+      }
+      state.hadExistingOutput = !!output;
+      await this.writeState(paths, state);
+
+      const candidates = await this.collectCandidates(sourceDirectories);
+      await fs.promises.mkdir(paths.stagingDirectory, { mode: 0o700 });
+      for (const candidate of candidates) {
+        const destinationBinary = path.join(
+          paths.stagingDirectory,
+          candidate.destinationName,
+        );
+        const destinationSidecar = ProvenanceStore.sidecarPath(destinationBinary);
+        await fs.promises.copyFile(
+          candidate.binaryPath,
+          destinationBinary,
+          fs.constants.COPYFILE_EXCL,
+        );
+        await fs.promises.copyFile(
+          candidate.sidecarPath,
+          destinationSidecar,
+          fs.constants.COPYFILE_EXCL,
+        );
+        await syncFile(destinationBinary);
+        await syncFile(destinationSidecar);
+        const copiedBuildInfo = await ProvenanceStore.readSidecar(destinationBinary);
+        if (JSON.stringify(copiedBuildInfo) !== JSON.stringify(candidate.buildInfo)) {
+          throw new Error(`Artifact provenance changed while copying ${candidate.binaryPath}`);
+        }
+      }
+      await fs.promises.chmod(paths.stagingDirectory, 0o755);
+      await syncDirectory(paths.stagingDirectory);
+      state = { ...state, phase: 'prepared' };
+      await this.writeState(paths, state);
+      await this.assertAssemblySourceUnchanged(paths.workspace);
+
+      if (state.hadExistingOutput) {
+        state = { ...state, phase: 'movingOld' };
+        await this.writeState(paths, state);
+        await fs.promises.rename(paths.outputDirectory, paths.backupDirectory);
+        await syncDirectory(paths.workspace);
+        state = { ...state, phase: 'oldMoved' };
+        await this.writeState(paths, state);
+      }
+
+      state = { ...state, phase: 'publishing' };
+      await this.writeState(paths, state);
+      state = { ...state, phase: 'committing' };
+      try {
+        await this.writeState(paths, state);
+        commitReached = true;
+      } catch (error) {
+        let persistedState: IAssemblyTransactionState | undefined;
+        try {
+          persistedState = await this.readState(paths);
+        } catch (stateError) {
+          commitReached = true;
+          throw new AggregateError(
+            [error, stateError],
+            `Artifact commit state is unreadable in ${paths.transactionDirectory}`,
+          );
+        }
+        if (
+          persistedState?.ownerToken === ownerToken &&
+          persistedState.phase === 'publishing'
+        ) {
+          state = persistedState;
+        } else {
+          // Recovery follows whichever commit phase reached state.json; do not
+          // make a second, potentially contradictory decision here.
+          commitReached = true;
+        }
+        throw new Error(
+          commitReached
+            ? `Artifact commit intent is pending in ${paths.transactionDirectory}`
+            : 'Failed to persist artifact commit intent',
+          { cause: error },
+        );
+      }
+      const cleanupPending = await this.completeCommittedTransaction(paths, state);
+      retainOwnerToken = cleanupPending;
+      return {
+        outputDirectory: paths.outputDirectory,
+        artifactCount: candidates.length,
+        binaries: [...this.options.expectedBinaries].sort(),
+        targets: this.options.expectedTargets.map((target) => target.friendly).sort(),
+        cleanupPending,
+      };
+    } catch (error) {
+      if (!commitReached) {
+        try {
+          await this.rollbackTransaction(paths, state);
+        } catch (rollbackError) {
+          retainOwnerToken = true;
+          throw new AggregateError(
+            [error, rollbackError],
+            `Artifact assembly failed and rollback is pending in ${paths.transactionDirectory}`,
+          );
+        }
+      } else {
+        retainOwnerToken = true;
+      }
+      throw error;
+    } finally {
+      activeOwnerTokens.delete(ownerToken);
+      if (!retainOwnerToken) {
+        processOwnerTokens.delete(ownerToken);
+      } else {
+        try {
+          if (!(await lstatOptional(paths.lockPath))) {
+            processOwnerTokens.delete(ownerToken);
+          }
+        } catch {
+          // Keep the token so a same-process retry can recover the transaction.
+        }
+      }
+    }
+  }
+
+  private createPaths(ownerTokenArg: string): IAssemblyPaths {
+    const workspace = path.resolve(this.options.workspace);
+    const transactionParent = path.join(workspace, '.nogit');
+    const transactionDirectory = path.join(transactionParent, TRANSACTION_DIRECTORY);
+    return {
+      workspace,
+      outputDirectory: path.join(workspace, 'dist_rust'),
+      transactionParent,
+      transactionDirectory,
+      lockPath: path.join(transactionParent, 'tsrust-assembly.lock'),
+      lockSourcePath: path.join(
+        transactionParent,
+        `.tsrust-assembly-owner.${ownerTokenArg}.tmp`,
+      ),
+      recoveryClaimPath: path.join(transactionParent, 'tsrust-assembly.recovery.lock'),
+      statePath: path.join(transactionDirectory, 'state.json'),
+      stateTemporaryPath: path.join(transactionDirectory, 'state.json.tmp'),
+      stagingDirectory: path.join(transactionDirectory, 'staging'),
+      backupDirectory: path.join(transactionDirectory, 'backup'),
+      failedDirectory: path.join(transactionDirectory, 'failed'),
+    };
+  }
+
+  private validateOptions(pathsArg: IAssemblyPaths, sourceDirectoriesArg: string[]): void {
+    if (sourceDirectoriesArg.length === 0) {
+      throw new Error('Artifact assembly requires at least one source directory');
+    }
+    if (new Set(sourceDirectoriesArg).size !== sourceDirectoriesArg.length) {
+      throw new Error('Artifact assembly source directories must be unique');
+    }
+    if (this.options.expectedTargets.length === 0) {
+      throw new Error('Artifact assembly requires at least one expected target');
+    }
+    if (this.options.expectedBinaries.length === 0) {
+      throw new Error('Artifact assembly requires at least one expected binary');
+    }
+    for (const binary of this.options.expectedBinaries) {
+      assertArtifactName(binary, 'binary name');
+    }
+    if (new Set(this.options.expectedBinaries).size !== this.options.expectedBinaries.length) {
+      throw new Error('Expected artifact binary names must be unique');
+    }
+    const targetNames = this.options.expectedTargets.map((target) => target.friendly);
+    const targetTriples = this.options.expectedTargets.map((target) => target.triple);
+    if (
+      new Set(targetNames).size !== targetNames.length ||
+      new Set(targetTriples).size !== targetTriples.length
+    ) {
+      throw new Error('Expected artifact targets must be unique');
+    }
+    if (!/^[a-f0-9]{40}([a-f0-9]{24})?$/.test(this.options.expectedGitCommit)) {
+      throw new Error('Artifact assembly requires an exact Git commit');
+    }
+    for (const target of this.options.expectedTargets) {
+      assertArtifactName(target.friendly, 'target name');
+      assertArtifactName(target.triple, 'target triple');
+    }
+    for (const sourceDirectory of sourceDirectoriesArg) {
+      if (
+        isSameOrWithin(sourceDirectory, pathsArg.outputDirectory) ||
+        isSameOrWithin(pathsArg.outputDirectory, sourceDirectory) ||
+        isSameOrWithin(sourceDirectory, pathsArg.transactionDirectory) ||
+        isSameOrWithin(pathsArg.transactionDirectory, sourceDirectory)
+      ) {
+        throw new Error(`Artifact source overlaps tsrust-owned output: ${sourceDirectory}`);
+      }
+    }
+  }
+
+  private async ensureTransactionParent(pathsArg: IAssemblyPaths): Promise<void> {
+    const existing = await lstatOptional(pathsArg.transactionParent);
+    if (existing) {
+      if (!existing.isDirectory() || existing.isSymbolicLink()) {
+        throw new Error(`tsrust state path is not a regular directory: ${pathsArg.transactionParent}`);
+      }
+    } else {
+      await fs.promises.mkdir(pathsArg.transactionParent, { mode: 0o700 });
+    }
+    const workspace = await fs.promises.stat(pathsArg.workspace);
+    const transactionParent = await fs.promises.stat(pathsArg.transactionParent);
+    if (workspace.dev !== transactionParent.dev) {
+      throw new Error('tsrust assembly state and dist_rust must be on the same filesystem');
+    }
+  }
+
+  private async acquireTransaction(
+    pathsArg: IAssemblyPaths,
+    stateArg: IAssemblyTransactionState,
+  ): Promise<void> {
+    await this.cleanupAbandonedLockSources(pathsArg);
+    if (
+      (await lstatOptional(pathsArg.transactionDirectory)) &&
+      !(await lstatOptional(pathsArg.lockPath))
+    ) {
+      throw new Error(`Assembly data exists without its owner lock: ${pathsArg.transactionDirectory}`);
+    }
+    const owner = this.lockOwnerFromState(stateArg);
+    await this.writeLockSource(pathsArg, owner);
+    let ownsLock = false;
+    let transactionCreated = false;
+    try {
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        await this.clearAbandonedRecoveryClaim(pathsArg);
+        try {
+          await fs.promises.link(pathsArg.lockSourcePath, pathsArg.lockPath);
+          ownsLock = true;
+          await syncDirectory(pathsArg.transactionParent);
+          break;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+          if (attempt > 0) {
+            throw new Error(`Unable to clear stale assembly lock: ${pathsArg.lockPath}`);
+          }
+          await this.recoverExistingTransaction(pathsArg);
+        }
+      }
+      await fs.promises.unlink(pathsArg.lockSourcePath);
+      await fs.promises.mkdir(pathsArg.transactionDirectory, { mode: 0o700 });
+      transactionCreated = true;
+      await syncDirectory(pathsArg.transactionParent);
+      await this.writeState(pathsArg, stateArg);
+    } catch (error) {
+      if (transactionCreated) {
+        await fs.promises.rm(pathsArg.transactionDirectory, { recursive: true, force: true });
+      }
+      if (ownsLock) {
+        await this.releaseLock(pathsArg, owner.ownerToken);
+      }
+      throw error;
+    } finally {
+      await Promise.allSettled([fs.promises.rm(pathsArg.lockSourcePath, { force: true })]);
+    }
+  }
+
+  private lockOwnerFromState(stateArg: IAssemblyTransactionState): IAssemblyLockOwner {
+    return {
+      format: LOCK_FORMAT,
+      pid: stateArg.pid,
+      hostname: stateArg.hostname,
+      hostIdentity: stateArg.hostIdentity,
+      ownerToken: stateArg.ownerToken,
+      startedAt: stateArg.startedAt,
+    };
+  }
+
+  private async writeLockSource(
+    pathsArg: IAssemblyPaths,
+    ownerArg: IAssemblyLockOwner,
+  ): Promise<void> {
+    const lockSource = await fs.promises.open(pathsArg.lockSourcePath, 'wx', 0o600);
+    try {
+      await lockSource.writeFile(`${JSON.stringify(ownerArg, null, 2)}\n`, 'utf8');
+      await lockSource.sync();
+    } finally {
+      await lockSource.close();
+    }
+  }
+
+  private async cleanupAbandonedLockSources(pathsArg: IAssemblyPaths): Promise<void> {
+    const entries = await fs.promises.readdir(pathsArg.transactionParent, {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      if (
+        !entry.isFile() ||
+        (!entry.name.startsWith('.tsrust-assembly-owner.') &&
+          !entry.name.startsWith('.tsrust-assembly-recovery.')) ||
+        !entry.name.endsWith('.tmp')
+      ) {
+        continue;
+      }
+      const filePath = path.join(pathsArg.transactionParent, entry.name);
+      let owner: IAssemblyOwnerIdentity;
+      try {
+        const parsed = JSON.parse(await fs.promises.readFile(filePath, 'utf8'));
+        if (isLockOwner(parsed) || isRecoveryClaim(parsed)) {
+          owner = parsed;
+        } else {
+          continue;
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        continue;
+      }
+      if (
+        activeOwnerTokens.has(owner.ownerToken) ||
+        processOwnerTokens.has(owner.ownerToken) ||
+        owner.hostIdentity !== getHostIdentity() ||
+        isLocalProcessRunning(owner.pid)
+      ) {
+        continue;
+      }
+      await fs.promises.rm(filePath, { force: true });
+    }
+  }
+
+  private async readLock(pathsArg: IAssemblyPaths): Promise<IAssemblyLockOwner | undefined> {
+    const lock = await lstatOptional(pathsArg.lockPath);
+    if (!lock) return undefined;
+    if (!lock.isFile() || lock.isSymbolicLink()) {
+      throw new Error(`Assembly lock is not a regular file: ${pathsArg.lockPath}`);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(pathsArg.lockPath, 'utf8'));
+      if (!isLockOwner(parsed)) {
+        throw new Error(`Assembly lock has an invalid shape: ${pathsArg.lockPath}`);
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Assembly lock is invalid JSON: ${pathsArg.lockPath}`);
+      }
+      throw error;
+    }
+  }
+
+  private async readRecoveryClaim(
+    pathsArg: IAssemblyPaths,
+  ): Promise<IAssemblyRecoveryClaim | undefined> {
+    const claim = await lstatOptional(pathsArg.recoveryClaimPath);
+    if (!claim) return undefined;
+    if (!claim.isFile() || claim.isSymbolicLink()) {
+      throw new Error(`Assembly recovery claim is not a regular file: ${pathsArg.recoveryClaimPath}`);
+    }
+    try {
+      const parsed = JSON.parse(
+        await fs.promises.readFile(pathsArg.recoveryClaimPath, 'utf8'),
+      );
+      if (!isRecoveryClaim(parsed)) {
+        throw new Error(`Assembly recovery claim has an invalid shape: ${pathsArg.recoveryClaimPath}`);
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Assembly recovery claim is invalid JSON: ${pathsArg.recoveryClaimPath}`);
+      }
+      throw error;
+    }
+  }
+
+  private async clearAbandonedRecoveryClaim(pathsArg: IAssemblyPaths): Promise<void> {
+    const claim = await this.readRecoveryClaim(pathsArg);
+    if (!claim) return;
+    const targetOwner = await this.readLock(pathsArg);
+    if (targetOwner?.ownerToken === claim.targetOwnerToken) {
+      this.assertOwnerCanRecover(claim);
+    }
+    await this.releaseRecoveryClaim(pathsArg, claim.ownerToken);
+    processOwnerTokens.delete(claim.ownerToken);
+  }
+
+  private async acquireRecoveryClaim(
+    pathsArg: IAssemblyPaths,
+    targetOwnerArg: IAssemblyLockOwner,
+  ): Promise<IAssemblyRecoveryClaim> {
+    const claim: IAssemblyRecoveryClaim = {
+      format: RECOVERY_CLAIM_FORMAT,
+      pid: process.pid,
+      hostname: os.hostname(),
+      hostIdentity: getHostIdentity(),
+      ownerToken: crypto.randomUUID(),
+      startedAt: new Date().toISOString(),
+      targetOwnerToken: targetOwnerArg.ownerToken,
+    };
+    const sourcePath = path.join(
+      pathsArg.transactionParent,
+      `.tsrust-assembly-recovery.${claim.ownerToken}.tmp`,
+    );
+    let source: fs.promises.FileHandle | undefined;
+    let claimAcquired = false;
+    try {
+      source = await fs.promises.open(sourcePath, 'wx', 0o600);
+      await source.writeFile(`${JSON.stringify(claim, null, 2)}\n`, 'utf8');
+      await source.sync();
+      await source.close();
+      source = undefined;
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+          await fs.promises.link(sourcePath, pathsArg.recoveryClaimPath);
+          claimAcquired = true;
+          processOwnerTokens.add(claim.ownerToken);
+          activeOwnerTokens.add(claim.ownerToken);
+          await syncDirectory(pathsArg.transactionParent);
+          break;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+          if (attempt > 0) {
+            throw new Error(`Unable to acquire assembly recovery claim: ${pathsArg.recoveryClaimPath}`);
+          }
+          await this.clearAbandonedRecoveryClaim(pathsArg);
+        }
+      }
+      const currentOwner = await this.readLock(pathsArg);
+      if (currentOwner?.ownerToken !== targetOwnerArg.ownerToken) {
+        await this.releaseRecoveryClaim(pathsArg, claim.ownerToken);
+        claimAcquired = false;
+        activeOwnerTokens.delete(claim.ownerToken);
+        processOwnerTokens.delete(claim.ownerToken);
+        throw new Error('Assembly owner changed while recovery was being claimed');
+      }
+      return claim;
+    } catch (error) {
+      if (claimAcquired) {
+        try {
+          await this.releaseRecoveryClaim(pathsArg, claim.ownerToken);
+        } finally {
+          activeOwnerTokens.delete(claim.ownerToken);
+          if (!(await lstatOptional(pathsArg.recoveryClaimPath))) {
+            processOwnerTokens.delete(claim.ownerToken);
+          }
+        }
+      }
+      throw error;
+    } finally {
+      await Promise.allSettled([
+        source?.close() || Promise.resolve(),
+        fs.promises.rm(sourcePath, { force: true }),
+      ]);
+    }
+  }
+
+  private async releaseRecoveryClaim(
+    pathsArg: IAssemblyPaths,
+    ownerTokenArg: string,
+  ): Promise<void> {
+    const claim = await this.readRecoveryClaim(pathsArg);
+    if (!claim) return;
+    if (claim.ownerToken !== ownerTokenArg) {
+      throw new Error('Assembly recovery claim ownership changed before release');
+    }
+    await fs.promises.unlink(pathsArg.recoveryClaimPath);
+    await syncDirectory(pathsArg.transactionParent);
+  }
+
+  private assertOwnerCanRecover(ownerArg: IAssemblyOwnerIdentity): void {
+    if (activeOwnerTokens.has(ownerArg.ownerToken)) {
+      throw new Error(
+        `Artifact assembly is already active on ${ownerArg.hostname} with pid ${ownerArg.pid}`,
+      );
+    }
+    if (processOwnerTokens.has(ownerArg.ownerToken)) return;
+    if (ownerArg.hostIdentity !== getHostIdentity()) {
+      throw new Error(
+        `Assembly transaction belongs to another host (${ownerArg.hostname}); refusing automatic recovery`,
+      );
+    }
+    if (isLocalProcessRunning(ownerArg.pid)) {
+      throw new Error(
+        `Artifact assembly owner is still running on ${ownerArg.hostname} with pid ${ownerArg.pid}`,
+      );
+    }
+  }
+
+  private async recoverExistingTransaction(pathsArg: IAssemblyPaths): Promise<void> {
+    const owner = await this.readLock(pathsArg);
+    if (!owner) return;
+    this.assertOwnerCanRecover(owner);
+    const claim = await this.acquireRecoveryClaim(pathsArg, owner);
+    try {
+      const currentOwner = await this.readLock(pathsArg);
+      if (currentOwner?.ownerToken !== owner.ownerToken) {
+        throw new Error('Assembly owner changed after recovery was claimed');
+      }
+      const transaction = await lstatOptional(pathsArg.transactionDirectory);
+      if (!transaction) {
+        await this.releaseLock(pathsArg, owner.ownerToken);
+        processOwnerTokens.delete(owner.ownerToken);
+        return;
+      }
+      if (!transaction.isDirectory() || transaction.isSymbolicLink()) {
+        throw new Error(`Assembly transaction path is not a regular directory: ${pathsArg.transactionDirectory}`);
+      }
+      const state = await this.readState(pathsArg);
+      if (!state) {
+        await fs.promises.rm(pathsArg.transactionDirectory, { recursive: true });
+        await this.releaseLock(pathsArg, owner.ownerToken);
+        processOwnerTokens.delete(owner.ownerToken);
+        return;
+      }
+      if (
+        state.ownerToken !== owner.ownerToken ||
+        state.hostIdentity !== owner.hostIdentity ||
+        state.pid !== owner.pid
+      ) {
+        throw new Error('Assembly lock and transaction state have different owners');
+      }
+
+      if (
+        state.phase === 'committing' ||
+        state.phase === 'published' ||
+        state.phase === 'committed'
+      ) {
+        const cleanupPending = await this.completeCommittedTransaction(pathsArg, state);
+        if (cleanupPending) {
+          throw new Error(`Unable to clean committed assembly state: ${pathsArg.transactionDirectory}`);
+        }
+        processOwnerTokens.delete(state.ownerToken);
+        return;
+      }
+      await this.rollbackTransaction(pathsArg, state);
+      processOwnerTokens.delete(state.ownerToken);
+    } finally {
+      activeOwnerTokens.delete(claim.ownerToken);
+      try {
+        await this.releaseRecoveryClaim(pathsArg, claim.ownerToken);
+      } finally {
+        if (!(await lstatOptional(pathsArg.recoveryClaimPath))) {
+          processOwnerTokens.delete(claim.ownerToken);
+        }
+      }
+    }
+  }
+
+  private async releaseLock(pathsArg: IAssemblyPaths, ownerTokenArg: string): Promise<void> {
+    const owner = await this.readLock(pathsArg);
+    if (!owner) return;
+    if (owner.ownerToken !== ownerTokenArg) {
+      throw new Error('Assembly lock ownership changed before release');
+    }
+    await fs.promises.unlink(pathsArg.lockPath);
+    await syncDirectory(pathsArg.transactionParent);
+  }
+
+  private async readState(
+    pathsArg: IAssemblyPaths,
+  ): Promise<IAssemblyTransactionState | undefined> {
+    const state = await lstatOptional(pathsArg.statePath);
+    if (!state) return undefined;
+    if (!state.isFile() || state.isSymbolicLink()) {
+      throw new Error(`Assembly state is not a regular file: ${pathsArg.statePath}`);
+    }
+    try {
+      const parsed = JSON.parse(await fs.promises.readFile(pathsArg.statePath, 'utf8'));
+      if (!isTransactionState(parsed)) {
+        throw new Error(`Assembly state has an invalid shape: ${pathsArg.statePath}`);
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Assembly state is invalid JSON: ${pathsArg.statePath}`);
+      }
+      throw error;
+    }
+  }
+
+  private async writeState(
+    pathsArg: IAssemblyPaths,
+    stateArg: IAssemblyTransactionState,
+  ): Promise<void> {
+    const temporary = await fs.promises.open(pathsArg.stateTemporaryPath, 'w', 0o600);
+    try {
+      await temporary.writeFile(`${JSON.stringify(stateArg, null, 2)}\n`, 'utf8');
+      await temporary.sync();
+    } finally {
+      await temporary.close();
+    }
+    await fs.promises.rename(pathsArg.stateTemporaryPath, pathsArg.statePath);
+    await syncDirectory(pathsArg.transactionDirectory);
+  }
+
+  private async assertAssemblySourceUnchanged(workspaceArg: string): Promise<void> {
+    const snapshot = await captureGitSnapshot(workspaceArg);
+    if (
+      !snapshot.available ||
+      snapshot.commit !== this.options.expectedGitCommit ||
+      snapshot.status.length > 0
+    ) {
+      throw new Error('Git source state changed before artifact publication');
+    }
+    let projectName = 'unknown';
+    let projectVersion = 'unknown';
+    try {
+      const packageJson = JSON.parse(
+        await fs.promises.readFile(path.join(workspaceArg, 'package.json'), 'utf8'),
+      );
+      projectName = packageJson.name || projectName;
+      projectVersion = packageJson.version || projectVersion;
+    } catch {
+      // package.json is optional for pure Rust workspaces.
+    }
+    if (
+      projectName !== this.options.expectedProjectName ||
+      projectVersion !== this.options.expectedProjectVersion
+    ) {
+      throw new Error('Project package identity changed before artifact publication');
+    }
+  }
+
+  private async rollbackTransaction(
+    pathsArg: IAssemblyPaths,
+    stateArg: IAssemblyTransactionState,
+  ): Promise<void> {
+    const backup = await lstatOptional(pathsArg.backupDirectory);
+    if (backup) {
+      if (!backup.isDirectory() || backup.isSymbolicLink()) {
+        throw new Error(`Assembly backup is not a regular directory: ${pathsArg.backupDirectory}`);
+      }
+      const output = await lstatOptional(pathsArg.outputDirectory);
+      if (output) {
+        await fs.promises.rm(pathsArg.failedDirectory, { recursive: true, force: true });
+        await fs.promises.rename(pathsArg.outputDirectory, pathsArg.failedDirectory);
+      }
+      await fs.promises.rename(pathsArg.backupDirectory, pathsArg.outputDirectory);
+      await syncDirectory(pathsArg.workspace);
+      await fs.promises.rm(pathsArg.failedDirectory, { recursive: true, force: true });
+    } else if (
+      !stateArg.hadExistingOutput &&
+      (stateArg.phase === 'publishing' ||
+        stateArg.phase === 'published' ||
+        stateArg.phase === 'committing')
+    ) {
+      await fs.promises.rm(pathsArg.outputDirectory, { recursive: true, force: true });
+      await syncDirectory(pathsArg.workspace);
+    }
+    await fs.promises.rm(pathsArg.stagingDirectory, { recursive: true, force: true });
+    await fs.promises.rm(pathsArg.stateTemporaryPath, { force: true });
+    await fs.promises.rm(pathsArg.transactionDirectory, { recursive: true });
+    await this.releaseLock(pathsArg, stateArg.ownerToken);
+  }
+
+  private async completeCommittedTransaction(
+    pathsArg: IAssemblyPaths,
+    stateArg: IAssemblyTransactionState,
+  ): Promise<boolean> {
+    const output = await lstatOptional(pathsArg.outputDirectory);
+    const staging = await lstatOptional(pathsArg.stagingDirectory);
+    if (!output) {
+      if (!staging || !staging.isDirectory() || staging.isSymbolicLink()) {
+        throw new Error(`Committed artifact publication is incomplete: ${pathsArg.transactionDirectory}`);
+      }
+      await fs.promises.rename(pathsArg.stagingDirectory, pathsArg.outputDirectory);
+      await syncDirectory(pathsArg.workspace);
+    } else {
+      if (!output.isDirectory() || output.isSymbolicLink()) {
+        throw new Error(`Committed assembly output is not a regular directory: ${pathsArg.outputDirectory}`);
+      }
+      if (staging) {
+        throw new Error(`Committed assembly has both staging and output directories: ${pathsArg.transactionDirectory}`);
+      }
+    }
+    return this.cleanupCommittedTransaction(pathsArg, { ...stateArg, phase: 'published' });
+  }
+
+  private async cleanupCommittedTransaction(
+    pathsArg: IAssemblyPaths,
+    stateArg: IAssemblyTransactionState,
+  ): Promise<boolean> {
+    try {
+      const output = await fs.promises.lstat(pathsArg.outputDirectory);
+      if (!output.isDirectory() || output.isSymbolicLink()) {
+        throw new Error(`Committed assembly output is not a regular directory: ${pathsArg.outputDirectory}`);
+      }
+      await fs.promises.rm(pathsArg.backupDirectory, { recursive: true, force: true });
+      await fs.promises.rm(pathsArg.stagingDirectory, { recursive: true, force: true });
+      await fs.promises.rm(pathsArg.failedDirectory, { recursive: true, force: true });
+      await this.writeState(pathsArg, { ...stateArg, phase: 'committed' });
+      await fs.promises.rm(pathsArg.transactionDirectory, { recursive: true });
+      await this.releaseLock(pathsArg, stateArg.ownerToken);
+      return false;
+    } catch {
+      return true;
+    }
+  }
+
+  private async collectCandidates(sourceDirectoriesArg: string[]): Promise<IArtifactCandidate[]> {
+    const expectedTargets = new Map(
+      this.options.expectedTargets.map((target) => [target.friendly, target]),
+    );
+    const expectedBinaries = new Set(this.options.expectedBinaries);
+    const candidates = new Map<string, IArtifactCandidate>();
+
+    for (const sourceDirectory of sourceDirectoriesArg) {
+      const source = await fs.promises.lstat(sourceDirectory);
+      if (!source.isDirectory() || source.isSymbolicLink()) {
+        throw new Error(`Artifact source is not a regular directory: ${sourceDirectory}`);
+      }
+      const entries = await fs.promises.readdir(sourceDirectory, { withFileTypes: true });
+      const entryNames = new Set(entries.map((entry) => entry.name));
+      const usedSidecars = new Set<string>();
+
+      for (const entry of entries) {
+        const entryPath = path.join(sourceDirectory, entry.name);
+        if (entry.isSymbolicLink() || !entry.isFile()) {
+          throw new Error(`Artifact source contains a non-regular entry: ${entryPath}`);
+        }
+        if (isProvenanceTemporaryFile(entry.name)) continue;
+        if (entry.name.endsWith(PROVENANCE_SIDECAR_SUFFIX)) continue;
+
+        const sidecarName = `${entry.name}${PROVENANCE_SIDECAR_SUFFIX}`;
+        if (!entryNames.has(sidecarName)) {
+          throw new Error(`Artifact is missing its provenance sidecar: ${entryPath}`);
+        }
+        const binary = await fs.promises.lstat(entryPath);
+        if ((binary.mode & 0o111) === 0) {
+          throw new Error(`Artifact is not executable: ${entryPath}`);
+        }
+
+        const buildInfo = await ProvenanceStore.readSidecar(entryPath);
+        assertArtifactName(buildInfo.binary, 'provenance binary name');
+        assertArtifactName(buildInfo.target, 'provenance target name');
+        if (buildInfo.gitDirty !== false) {
+          throw new Error(`Artifact was not built from a clean Git worktree: ${entryPath}`);
+        }
+        if (
+          buildInfo.projectName !== this.options.expectedProjectName ||
+          buildInfo.projectVersion !== this.options.expectedProjectVersion ||
+          buildInfo.gitCommit !== this.options.expectedGitCommit
+        ) {
+          throw new Error(`Artifact provenance does not match the assembly source: ${entryPath}`);
+        }
+        if (buildInfo.tsrustVersion !== this.options.expectedTsrustVersion) {
+          throw new Error(`Artifact was built with a different tsrust version: ${entryPath}`);
+        }
+
+        const target = expectedTargets.get(buildInfo.target);
+        if (!target) {
+          throw new Error(`Artifact has an unexpected target ${buildInfo.target}: ${entryPath}`);
+        }
+        if (!expectedBinaries.has(buildInfo.binary)) {
+          throw new Error(`Artifact has an unexpected binary ${buildInfo.binary}: ${entryPath}`);
+        }
+        const destinationName = `${buildInfo.binary}_${target.friendly}`;
+        if (entry.name !== destinationName) {
+          throw new Error(
+            `Artifact filename ${entry.name} does not match provenance name ${destinationName}`,
+          );
+        }
+        const key = `${buildInfo.binary}\u0000${target.friendly}`;
+        if (candidates.has(key)) {
+          throw new Error(`Artifact inputs contain a duplicate ${destinationName}`);
+        }
+        const sidecarPath = path.join(sourceDirectory, sidecarName);
+        candidates.set(key, {
+          binaryPath: entryPath,
+          sidecarPath,
+          destinationName,
+          buildInfo,
+        });
+        usedSidecars.add(sidecarName);
+      }
+
+      for (const entry of entries) {
+        if (entry.name.endsWith(PROVENANCE_SIDECAR_SUFFIX) && !usedSidecars.has(entry.name)) {
+          throw new Error(`Artifact source contains an orphan provenance sidecar: ${entry.name}`);
+        }
+      }
+    }
+
+    for (const binary of expectedBinaries) {
+      for (const target of expectedTargets.keys()) {
+        const key = `${binary}\u0000${target}`;
+        if (!candidates.has(key)) {
+          throw new Error(`Artifact assembly is missing ${binary}_${target}`);
+        }
+      }
+    }
+    return [...candidates.values()].sort((a, b) =>
+      a.destinationName.localeCompare(b.destinationName),
+    );
+  }
+}