@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/benchmark/benchmark-resume-recovery.js

@@ -0,0 +1,262 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { hardenPrivateRetentionRoot, retainedWorkspaceMarker, writeBenchmarkRunManifest, writePrivateAtomic } from "./benchmark-forensics.js";
+import { appendBenchmarkLedger, assertBenchmarkLedgerBinding, validateBenchmarkLedgerPrefix } from "./benchmark-ledger.js";
+import { expectedBenchmarkRecord, pairedBenchmarkVariantMatched } from "./benchmark-record-validation.js";
+
+function fail(message) {
+  const error = new Error(message);
+  error.exitCode = 1;
+  throw error;
+}
+
+function readJson(file, label) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) { fail(`Cannot read ${label} ${file}: ${error.message}`); }
+}
+
+function key(value) {
+  return `${value.scenarioId ?? value.scenario?.id}\0${value.surface}\0${value.repeat}`;
+}
+
+function exactUsage(usage, usageStatus) {
+  const nonnegative = (value) => Number.isFinite(value) && value >= 0;
+  return usageStatus !== "unknown-after-provider-start"
+    && Number.isInteger(usage?.sessions) && usage.sessions > 0
+    && ["fresh", "input", "output", "cacheRead", "cacheWrite", "reasoning", "total"].every((field) => nonnegative(usage?.[field]))
+    && usage.fresh === usage.input + usage.output
+    && usage.total === usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+
+export function persistUnacceptedBenchmarkAttempt({ runRoot, manifest, record, reason, forceTokenUnavailable = false }) {
+  const attempt = {
+    schemaVersion: 1,
+    runId: manifest.runId,
+    attemptId: record.attemptId,
+    orderIndex: record.orderIndex,
+    scenarioId: record.scenarioId,
+    surface: record.surface,
+    repeat: record.repeat,
+    attempt: record.infrastructureAttempt,
+    failure: reason ?? record.infrastructureFailure ?? record.failure ?? "unaccepted-provider-attempt",
+    class: record.infrastructureClass ?? "infrastructure",
+    usage: record.usage,
+    usageStatus: record.usageStatus ?? "unknown-after-provider-start",
+    durationSeconds: record.durationSeconds ?? 0,
+    recoveredFromInFlight: false
+  };
+  const attemptKey = `${key(attempt)}\0${attempt.attempt}`;
+  manifest.recoveredProviderAttempts = [
+    ...(manifest.recoveredProviderAttempts ?? []).filter((value) => `${key(value)}\0${value.attempt}` !== attemptKey),
+    attempt
+  ];
+  if (forceTokenUnavailable || !exactUsage(attempt.usage, attempt.usageStatus)) {
+    manifest.tokenClaimsUnavailableReason ??= reason ?? "one-or-more-provider-attempts-have-unaccepted-or-unknown-usage";
+  }
+  writeBenchmarkRunManifest(runRoot, manifest);
+  return attempt;
+}
+
+export function clearRecoveredBenchmarkAttempts(manifest, record) {
+  manifest.recoveredProviderAttempts = (manifest.recoveredProviderAttempts ?? []).filter((attempt) => key(attempt) !== key(record));
+}
+
+export function stageMeasuredBenchmarkRecord({ runRoot, manifest, ledgerBinding, record, infrastructureFailures, index, expected, runId, suite, configurationDigest, runs }) {
+  record.infrastructureAttempts = record.infrastructureAttempt ?? 1;
+  record.infrastructureRetries = Math.max(0, record.infrastructureAttempts - 1);
+  record.infrastructureFailures = infrastructureFailures;
+  if (!expectedBenchmarkRecord(record, index, expected, runId, suite, configurationDigest) || !pairedBenchmarkVariantMatched(record, runs)) {
+    persistUnacceptedBenchmarkAttempt({ runRoot, manifest, record, reason: "measured-record-identity-or-paired-fixture-mismatch", forceTokenUnavailable: true });
+    fail(`Runner produced an incomplete, identity-mismatched, or unpaired-fixture record for ${record.scenarioId}/${record.surface}/r${record.repeat}`);
+  }
+  writePrivateAtomic(path.join(runRoot, "measured-record-ready.json"), `${JSON.stringify({ schemaVersion: 1, previousLedger: ledgerBinding, record }, null, 2)}\n`);
+  return record;
+}
+
+export function promoteMeasuredBenchmarkRecord({ runRoot, ledgerBinding, record, postSessionGuard }) {
+  const file = path.join(runRoot, "measured-record-ready.json");
+  const measured = readJson(file, "measured benchmark record");
+  if (measured?.schemaVersion !== 1 || !measured.previousLedger || !measured.record) fail("Measured benchmark record WAL is malformed");
+  assertBenchmarkLedgerBinding(measured.previousLedger, ledgerBinding, "measured-record previous ledger");
+  if (JSON.stringify(measured.record) !== JSON.stringify(record)) fail("Measured benchmark record WAL differs from the in-memory outcome");
+  if (postSessionGuard?.matched !== true || !String(postSessionGuard.stage ?? "").startsWith("after-session:")) {
+    fail("Measured benchmark record cannot be promoted without a matched post-session execution guard");
+  }
+  writePrivateAtomic(path.join(runRoot, "pending-record.json"), `${JSON.stringify({ schemaVersion: 2, previousLedger: ledgerBinding, record, postSessionGuard }, null, 2)}\n`);
+  fs.rmSync(file, { force: true });
+  return record;
+}
+
+export function recoverPendingBenchmarkRecord({ runRoot, manifest, ledgerBinding, completedRuns, pending, measuredReady, fullOrder, suite }) {
+  let binding = ledgerBinding;
+  const runs = completedRuns;
+  if (pending) {
+    if (pending.schemaVersion !== 2 || !pending.previousLedger || !pending.record || pending.postSessionGuard?.matched !== true
+      || !String(pending.postSessionGuard.stage ?? "").startsWith("after-session:")) fail("Benchmark pending record is missing its post-session execution guard receipt");
+    const expectedIndex = pending.record.orderIndex - 1;
+    if (!expectedBenchmarkRecord(pending.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest)) {
+      fail("Benchmark pending record does not match the frozen execution order");
+    }
+    if (binding.records === pending.previousLedger.records) {
+      assertBenchmarkLedgerBinding(pending.previousLedger, binding, "pending-record previous ledger");
+      binding = appendBenchmarkLedger(path.join(runRoot, "runs.jsonl"), pending.record, binding);
+      runs.push(pending.record);
+    } else if (binding.records === pending.previousLedger.records + 1) {
+      if (manifest.ledger.records === pending.previousLedger.records) {
+        assertBenchmarkLedgerBinding(pending.previousLedger, manifest.ledger, "pending-record manifest checkpoint");
+      } else {
+        assertBenchmarkLedgerBinding(manifest.ledger, binding, "pending-record committed ledger");
+      }
+      if (JSON.stringify(runs.at(-1)) !== JSON.stringify(pending.record)) fail("Benchmark pending record differs from the durable ledger suffix");
+    } else fail("Benchmark pending record is not adjacent to the manifest ledger checkpoint");
+    manifest.ledger = binding;
+    manifest.recoveredProviderAttempts = (manifest.recoveredProviderAttempts ?? [])
+      .filter((attempt) => key(attempt) !== key(pending.record));
+    writeBenchmarkRunManifest(runRoot, manifest);
+    fs.rmSync(path.join(runRoot, "pending-record.json"), { force: true });
+  }
+  if (measuredReady) {
+    if (measuredReady.schemaVersion !== 1 || !measuredReady.previousLedger || !measuredReady.record) fail("Measured benchmark record WAL is malformed");
+    const expectedIndex = measuredReady.record.orderIndex - 1;
+    if (!expectedBenchmarkRecord(measuredReady.record, expectedIndex, fullOrder[expectedIndex], manifest.runId, suite, manifest.configurationDigest)) {
+      fail("Measured benchmark record WAL does not match the frozen execution order");
+    }
+    if (pending) {
+      assertBenchmarkLedgerBinding(measuredReady.previousLedger, pending.previousLedger, "measured/pending previous ledger");
+      if (JSON.stringify(measuredReady.record) !== JSON.stringify(pending.record)) fail("Measured and post-guard pending records differ");
+    } else {
+      assertBenchmarkLedgerBinding(measuredReady.previousLedger, binding, "unpromoted measured-record ledger");
+      persistUnacceptedBenchmarkAttempt({
+        runRoot, manifest, record: measuredReady.record,
+        reason: "measured-record-ready-without-post-session-guard-receipt"
+      });
+    }
+    fs.rmSync(path.join(runRoot, "measured-record-ready.json"), { force: true });
+  }
+  const completedKeys = validateBenchmarkLedgerPrefix(
+    runs,
+    fullOrder,
+    (record, index, expected) => expectedBenchmarkRecord(record, index, expected, manifest.runId, suite, manifest.configurationDigest)
+  );
+  return { ledgerBinding: binding, completedRuns: runs, completedKeys, recoveredPending: Boolean(pending) };
+}
+
+function retainedMarker(workspaceRoot, attempt) {
+  hardenPrivateRetentionRoot(workspaceRoot);
+  writePrivateAtomic(retainedWorkspaceMarker(workspaceRoot), `${JSON.stringify({
+    schemaVersion: 1,
+    retainedAt: new Date().toISOString(),
+    reason: "orphaned-provider-attempt-recovered-after-process-exit",
+    scenarioId: attempt.scenarioId,
+    surface: attempt.surface,
+    repeat: attempt.repeat,
+    infrastructureAttempt: attempt.infrastructureAttempt
+  }, null, 2)}\n`);
+}
+
+export function recoverOrphanedBenchmarkAttempts({ runRoot, manifest, fullOrder, completedKeys }) {
+  const workspaces = path.join(runRoot, "workspaces");
+  const attemptsByKey = new Map();
+  const persisted = Array.isArray(manifest.recoveredProviderAttempts) ? manifest.recoveredProviderAttempts : [];
+  const seenAttempts = new Map();
+  for (const attempt of persisted) {
+    const expected = fullOrder[Number(attempt?.orderIndex) - 1];
+    const valid = typeof attempt?.attemptId === "string" && attempt.attemptId.length > 0
+      && Number.isInteger(attempt?.attempt) && attempt.attempt > 0
+      && attempt.scenarioId === expected?.scenario?.id
+      && attempt.surface === expected?.surface
+      && attempt.repeat === expected?.repeat;
+    if (!valid) fail("Persisted recovered provider attempt is malformed or foreign");
+    const runKey = key(attempt);
+    if (completedKeys.has(runKey)) continue;
+    const attemptKey = `${runKey}\0${attempt.attempt}`;
+    if (seenAttempts.has(attemptKey)) fail("Manifest contains duplicate recovered provider attempts");
+    seenAttempts.set(attemptKey, attempt);
+  }
+  if (!fs.existsSync(workspaces)) {
+    for (const attempt of seenAttempts.values()) {
+      const values = attemptsByKey.get(key(attempt)) ?? [];
+      values.push(attempt);
+      attemptsByKey.set(key(attempt), values);
+    }
+    return attemptsByKey;
+  }
+  const newlyRecovered = [];
+  const completedInflight = [];
+  for (const name of fs.readdirSync(workspaces).sort()) {
+    const workspaceRoot = path.join(workspaces, name);
+    const inflightPath = path.join(workspaceRoot, "inflight.json");
+    if (!fs.existsSync(inflightPath)) continue;
+    const attempt = readJson(inflightPath, "orphaned benchmark attempt");
+    const expected = fullOrder[Number(attempt?.orderIndex) - 1];
+    const valid = attempt?.schemaVersion === 1
+      && attempt.runId === manifest.runId
+      && typeof attempt.attemptId === "string" && attempt.attemptId.length > 0
+      && Number.isInteger(attempt.orderIndex) && attempt.orderIndex > 0
+      && Number.isInteger(attempt.infrastructureAttempt) && attempt.infrastructureAttempt > 0
+      && ["provider-may-start", "provider-returned"].includes(attempt.stage)
+      && attempt.scenarioId === expected?.scenario?.id
+      && attempt.surface === expected?.surface
+      && attempt.repeat === expected?.repeat;
+    if (!valid) fail(`Orphaned benchmark attempt is malformed or foreign: ${inflightPath}`);
+    const runKey = key(attempt);
+    const attemptKey = `${runKey}\0${attempt.infrastructureAttempt}`;
+    if (completedKeys.has(runKey)) {
+      completedInflight.push(inflightPath);
+      continue;
+    }
+    const recovered = {
+      schemaVersion: 1,
+      runId: manifest.runId,
+      attemptId: attempt.attemptId,
+      orderIndex: attempt.orderIndex,
+      scenarioId: attempt.scenarioId,
+      surface: attempt.surface,
+      repeat: attempt.repeat,
+      attempt: attempt.infrastructureAttempt,
+      failure: "orphaned-provider-attempt-after-process-exit",
+      class: "infrastructure",
+      usage: attempt.stage === "provider-returned" ? attempt.usage : undefined,
+      usageStatus: attempt.stage === "provider-returned" && exactUsage(attempt.usage, "measured-but-unaccepted") ? "measured-but-unaccepted" : "unknown-after-provider-start",
+      durationSeconds: 0,
+      recoveredFromInFlight: true
+    };
+    const prior = seenAttempts.get(attemptKey);
+    if (prior?.attemptId && prior.attemptId !== recovered.attemptId) fail(`Recovered provider attempt conflicts with its persisted manifest entry: ${name}`);
+    if (!prior) {
+      seenAttempts.set(attemptKey, recovered);
+      newlyRecovered.push({ recovered, workspaceRoot, inflightPath, attempt });
+    } else {
+      const merged = {
+        ...prior,
+        ...(exactUsage(recovered.usage, recovered.usageStatus) && !exactUsage(prior.usage, prior.usageStatus)
+          ? { usage: recovered.usage, usageStatus: recovered.usageStatus }
+          : {}),
+        attemptId: recovered.attemptId
+      };
+      seenAttempts.set(attemptKey, merged);
+      newlyRecovered.push({ recovered: merged, workspaceRoot, inflightPath, attempt });
+    }
+  }
+  const retainedAttempts = [...seenAttempts.values()];
+  if (retainedAttempts.length > 0) {
+    if (retainedAttempts.some((attempt) => !exactUsage(attempt.usage, attempt.usageStatus))) {
+      manifest.tokenClaimsUnavailableReason ??= "one-or-more-provider-attempts-were-recovered-after-process-exit";
+    }
+    manifest.recoveredProviderAttempts = retainedAttempts;
+    manifest.recoveredInFlightAttempts = retainedAttempts.length;
+    writeBenchmarkRunManifest(runRoot, manifest);
+  }
+  for (const { workspaceRoot, inflightPath, attempt } of newlyRecovered) {
+    retainedMarker(workspaceRoot, attempt);
+    fs.rmSync(inflightPath, { force: true });
+  }
+  for (const inflightPath of completedInflight) fs.rmSync(inflightPath, { force: true });
+  for (const attempt of retainedAttempts) {
+    const values = attemptsByKey.get(key(attempt)) ?? [];
+    values.push(attempt);
+    attemptsByKey.set(key(attempt), values);
+  }
+  return attemptsByKey;
+}

package/packages/piagent-core/benchmark/benchmark-run-lock.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function fail(message) {
+  const error = new Error(message);
+  error.code = "BENCHMARK_RUN_LOCKED";
+  error.exitCode = 1;
+  throw error;
+}
+
+function recoveryClaim(file) {
+  const claim = `${file}.recovery`;
+  let descriptor;
+  for (let attempt = 0; attempt < 4 && descriptor === undefined; attempt += 1) {
+    try {
+      descriptor = fs.openSync(claim, "wx", 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify({ schemaVersion: 1, pid: process.pid, hostname: os.hostname() })}\n`);
+      fs.fsyncSync(descriptor);
+    } catch (error) {
+      if (descriptor !== undefined) try { fs.closeSync(descriptor); } catch { /* Best effort. */ }
+      descriptor = undefined;
+      if (error?.code !== "EEXIST") throw error;
+      let owner;
+      let acquired;
+      try {
+        const current = fs.openSync(claim, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        try { acquired = fs.fstatSync(current); owner = JSON.parse(fs.readFileSync(current, "utf8")); }
+        finally { fs.closeSync(current); }
+      } catch { fail(`Benchmark recovery claim is malformed or was replaced: ${claim}`); }
+      if (owner?.schemaVersion !== 1 || owner.hostname !== os.hostname() || !Number.isInteger(owner.pid) || owner.pid < 1) {
+        fail(`Benchmark recovery claim has no provably local owner: ${claim}`);
+      }
+      try { process.kill(owner.pid, 0); fail(`Benchmark lock recovery is already in progress: ${claim}`); }
+      catch (cause) { if (cause?.code !== "ESRCH") throw cause; }
+      const current = fs.lstatSync(claim);
+      if (current.dev !== acquired.dev || current.ino !== acquired.ino) fail(`Benchmark recovery claim changed during stale-owner recovery: ${claim}`);
+      const stale = `${claim}.stale-${owner.pid}-${Date.now()}-${process.pid}`;
+      fs.renameSync(claim, stale);
+      const moved = fs.lstatSync(stale);
+      if (moved.dev !== acquired.dev || moved.ino !== acquired.ino) fail(`Benchmark recovery claim replacement race detected: ${claim}`);
+    }
+  }
+  if (descriptor === undefined) fail(`Cannot acquire benchmark recovery claim: ${claim}`);
+  const acquired = fs.fstatSync(descriptor);
+  const assertOwned = () => {
+    const current = fs.lstatSync(claim);
+    if (current.dev !== acquired.dev || current.ino !== acquired.ino) fail(`Benchmark recovery claim changed while held: ${claim}`);
+  };
+  const release = () => {
+    try { fs.closeSync(descriptor); } catch { /* Best effort. */ }
+    try {
+      const current = fs.lstatSync(claim);
+      if (current.dev === acquired.dev && current.ino === acquired.ino) fs.unlinkSync(claim);
+    } catch { /* Preserve a replaced recovery claim. */ }
+  };
+  return { assertOwned, release };
+}
+
+export function acquireBenchmarkRunLock(runRoot, runId) {
+  const file = path.join(runRoot, ".benchmark-run.lock");
+  let descriptor;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      descriptor = fs.openSync(file, "wx", 0o600);
+      fs.writeFileSync(descriptor, `${JSON.stringify({ schemaVersion: 1, runId, pid: process.pid, hostname: os.hostname(), acquiredAt: new Date().toISOString() })}\n`);
+      fs.fsyncSync(descriptor);
+      break;
+    } catch (error) {
+      if (descriptor !== undefined) try { fs.closeSync(descriptor); } catch { /* Best effort. */ }
+      descriptor = undefined;
+      if (error?.code !== "EEXIST") throw error;
+      const recovery = recoveryClaim(file);
+      try {
+        let owner;
+        const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+        const current = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        let acquired;
+        try {
+          acquired = fs.fstatSync(current);
+          owner = JSON.parse(fs.readFileSync(current, "utf8"));
+        } finally { fs.closeSync(current); }
+        let active = true;
+        if ((owner.hostname === undefined || owner.hostname === os.hostname()) && Number.isInteger(owner.pid) && owner.pid > 0) {
+          try { process.kill(owner.pid, 0); }
+          catch (cause) { if (cause?.code === "ESRCH") active = false; }
+        }
+        if (active || attempt > 0) fail(`Benchmark run is locked by another process: ${file}`);
+        const pathStat = fs.lstatSync(file);
+        if (pathStat.dev !== acquired.dev || pathStat.ino !== acquired.ino) fail(`Benchmark run lock changed during stale-owner recovery: ${file}`);
+        recovery.assertOwned();
+        fs.renameSync(file, `${file}.stale-${owner.pid}-${Date.now()}`);
+        recovery.assertOwned();
+      } catch (cause) {
+        if (cause?.code !== "ENOENT") {
+          if (cause?.exitCode) throw cause;
+          fail(`Benchmark run lock is malformed or was replaced: ${file}`);
+        }
+      } finally { recovery.release(); }
+    }
+  }
+  if (descriptor === undefined) fail(`Cannot acquire benchmark run lock: ${file}`);
+  const acquired = fs.fstatSync(descriptor);
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    process.off("exit", release);
+    try { fs.closeSync(descriptor); } catch { /* Best effort. */ }
+    try {
+      const current = fs.lstatSync(file);
+      if (current.dev === acquired.dev && current.ino === acquired.ino) fs.unlinkSync(file);
+    } catch { /* Preserve a replaced lock or tolerate prior cleanup. */ }
+  };
+  process.once("exit", release);
+  return release;
+}

package/packages/piagent-core/benchmark/benchmark-runtime-identity.js

@@ -0,0 +1,122 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  assertBenchmarkTreeIdentity,
+  assertBenchmarkTreeStatIdentity,
+  benchmarkTreeIdentity,
+  benchmarkTreeStatIdentity
+} from "./benchmark-tree-identity.js";
+
+function fail(message) {
+  const error = new Error(message);
+  error.code = "BENCHMARK_RUNTIME_IDENTITY_INVALID";
+  error.exitCode = 1;
+  throw error;
+}
+
+function executableCandidate(requested, cwd, env) {
+  if (requested.includes(path.sep) || (path.sep === "\\" && requested.includes("/"))) {
+    return path.resolve(cwd, requested);
+  }
+  for (const directory of String(env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(directory, requested);
+    try { fs.accessSync(candidate, fs.constants.X_OK); return candidate; } catch { /* Try the next PATH entry. */ }
+  }
+  fail(`Required benchmark command is unavailable: ${requested}`);
+}
+
+function commandPackageRoot(resolvedPath) {
+  let current = path.dirname(resolvedPath);
+  while (current !== path.dirname(current)) {
+    const manifest = path.join(current, "package.json");
+    if (fs.existsSync(manifest) && fs.statSync(manifest).isFile()) {
+      try {
+        const value = JSON.parse(fs.readFileSync(manifest, "utf8"));
+        if (typeof value.name === "string" && typeof value.version === "string") {
+          return { root: current, name: value.name, version: value.version };
+        }
+      } catch (error) {
+        fail(`Cannot inspect benchmark command package ${manifest}: ${error.message}`);
+      }
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function stableExecutable(file, label) {
+  const descriptor = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+  try {
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (!before.isFile()) fail(`Benchmark command is not a regular file: ${label}`);
+    const bytes = fs.readFileSync(descriptor);
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    const stable = ["dev", "ino", "mode", "size", "mtimeNs", "ctimeNs"].every((field) => before[field] === after[field]);
+    if (!stable || BigInt(bytes.length) !== after.size) fail(`Benchmark command changed while it was read: ${label}`);
+    return { bytes, stat: after };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+export function benchmarkCommandIdentity(requested, { cwd = process.cwd(), env = process.env, fullPackageClosure = true } = {}) {
+  const selectedPath = executableCandidate(requested, cwd, env);
+  let resolvedPath;
+  let observed;
+  try {
+    resolvedPath = fs.realpathSync(selectedPath);
+    observed = stableExecutable(resolvedPath, requested);
+  } catch (error) {
+    fail(`Cannot inspect benchmark command ${requested}: ${error.message}`);
+  }
+  const { bytes, stat } = observed;
+  const packageInfo = commandPackageRoot(resolvedPath);
+  return {
+    schemaVersion: 1,
+    requested,
+    selectedPath: path.resolve(selectedPath),
+    resolvedPath,
+    kind: "regular",
+    executable: (stat.mode & 0o111n) !== 0n,
+    size: bytes.length,
+    contentDigest: crypto.createHash("sha256").update(bytes).digest("hex"),
+    packageClosure: packageInfo ? {
+      root: packageInfo.root,
+      name: packageInfo.name,
+      version: packageInfo.version,
+      stat: benchmarkTreeStatIdentity(packageInfo.root, { rejectEscapingSymlinks: true }),
+      tree: fullPackageClosure ? benchmarkTreeIdentity(packageInfo.root, { rejectEscapingSymlinks: true }) : null
+    } : null
+  };
+}
+
+export function assertBenchmarkCommandIdentity(expected, observed, label, { fullPackageClosure = true } = {}) {
+  const valid = (value) => value?.schemaVersion === 1
+    && value.kind === "regular"
+    && typeof value.resolvedPath === "string"
+    && /^[a-f0-9]{64}$/.test(String(value.contentDigest ?? ""))
+    && Number.isInteger(value.size)
+    && typeof value.executable === "boolean";
+  if (!valid(expected) || !valid(observed)) fail(`${label} command identity is missing or unsupported`);
+  const fields = ["resolvedPath", "kind", "executable", "size", "contentDigest"];
+  const mismatches = fields.filter((field) => expected[field] !== observed[field]);
+  if (mismatches.length > 0) fail(`${label} command changed: ${mismatches.join(", ")}`);
+  if (JSON.stringify(expected.packageClosure?.root ?? null) !== JSON.stringify(observed.packageClosure?.root ?? null)) {
+    fail(`${label} command package root changed`);
+  }
+  if (expected.packageClosure) {
+    if (expected.packageClosure.name !== observed.packageClosure?.name || expected.packageClosure.version !== observed.packageClosure?.version) {
+      fail(`${label} command package identity changed`);
+    }
+    assertBenchmarkTreeStatIdentity(expected.packageClosure.stat, observed.packageClosure?.stat, `${label} command package closure`);
+    if (fullPackageClosure) assertBenchmarkTreeIdentity(expected.packageClosure.tree, observed.packageClosure?.tree, `${label} command package closure`);
+  }
+  return observed;
+}
+
+export function verifyBenchmarkCommandIdentity(identity, label, options = {}) {
+  const observed = benchmarkCommandIdentity(identity.resolvedPath, { fullPackageClosure: options.fullPackageClosure === true });
+  return assertBenchmarkCommandIdentity(identity, observed, label, options);
+}