@deeeed/metamask-harness 0.38.1 → 0.40.0

package/library/actions/extension/perps/mutation-receipt.mjs

@@ -0,0 +1,781 @@
+import { createHash } from 'node:crypto';
+import {
+  chmod,
+  link,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+
+const SHA256 = /^[a-f0-9]{64}$/u;
+const EXECUTION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const NODE_ID = /^(?=.{1,256}$)[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?:\/[A-Za-z0-9][A-Za-z0-9._-]{0,63})*$/u;
+const BASE_UNITS = /^[1-9][0-9]{0,29}$/u;
+const ORIGIN = /^chrome-extension:\/\/[a-p]{32}$/u;
+
+function canonical(value) {
+  return `${JSON.stringify(value)}\n`;
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function recoveryError(receipt, detail) {
+  return new Error(
+    `External mutation outcome is unknown (${receipt.sha256}): ${detail}. ` +
+      'Next: do not rerun this mutation; inspect the visible position/order and activity first.',
+  );
+}
+
+class ExternalMutationNotDispatchedError extends Error {}
+
+export function externalMutationNotDispatched(message) {
+  return new ExternalMutationNotDispatchedError(message);
+}
+
+export async function withExternalMutationRecovery(receipt, callback) {
+  try {
+    return await callback();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/External mutation outcome is unknown[\s\S]*Next: do not rerun this mutation;/u.test(message)) {
+      throw error;
+    }
+    throw recoveryError(receipt, message);
+  }
+}
+
+async function requireDirectory(directory, label) {
+  const entry = await lstat(directory);
+  if (!entry.isDirectory() || entry.isSymbolicLink()) {
+    throw new Error(`${label} must be a regular directory.`);
+  }
+  if (await realpath(directory) !== path.resolve(directory)) {
+    throw new Error(`${label} must not contain symbolic-link path components.`);
+  }
+}
+
+async function receiptDestination(input, io = {}) {
+  const configuredRoot = input.context?.artifactsDir;
+  const nodeId = String(input.context?.nodeId ?? '');
+  if (typeof configuredRoot !== 'string' || configuredRoot.trim() === '' || !path.isAbsolute(configuredRoot)) {
+    throw new Error('External mutation receipt requires a nonempty absolute trusted artifacts directory.');
+  }
+  const artifactsRoot = path.resolve(configuredRoot);
+  if (artifactsRoot !== configuredRoot || !NODE_ID.test(nodeId)) {
+    throw new Error('External mutation receipt requires a trusted artifacts directory and bounded node ID.');
+  }
+  await requireDirectory(artifactsRoot, 'External mutation artifacts root');
+  const directory = path.join(artifactsRoot, 'mutation-receipts');
+  let created = false;
+  try {
+    await mkdir(directory, { mode: 0o700 });
+    created = true;
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  await requireDirectory(directory, 'External mutation receipt directory');
+  await chmod(directory, 0o700);
+  if (created) await durableDirectorySync(artifactsRoot, io);
+  return {
+    absolute: path.join(directory, `${digest(nodeId)}.json`),
+    directory,
+    relative: `mutation-receipts/${digest(nodeId)}.json`,
+  };
+}
+
+async function executionMarkerDestination(input, identity) {
+  const configuredRoot = input.context?.trustedMutation?.executionLedgerRoot;
+  const executionClaimSha256 = String(input.context?.trustedMutation?.executionClaimSha256 ?? '');
+  if (typeof configuredRoot !== 'string' || !path.isAbsolute(configuredRoot)
+    || path.resolve(configuredRoot) !== configuredRoot || !SHA256.test(executionClaimSha256)) {
+    throw new Error('External mutation requires a trusted validator-owned execution ledger.');
+  }
+  await requireDirectory(configuredRoot, 'External mutation execution ledger');
+  return {
+    absolute: path.join(configuredRoot, `${digest(identity.executionId)}.json`),
+    directory: configuredRoot,
+    relative: `funding-execution-starts/${digest(identity.executionId)}.json`,
+    executionClaimSha256,
+  };
+}
+
+function executionMarkerRecord(identity, receipt, executionClaimSha256) {
+  const initialReceipt = {
+    schemaVersion: 1,
+    kind: 'external-mutation-receipt',
+    state: 'outcome-unknown',
+    identity,
+    facts: receipt.record?.facts ?? {},
+  };
+  return {
+    schemaVersion: 1,
+    kind: 'external-mutation-start',
+    executionClaimSha256,
+    identity,
+    receipt: { path: receipt.relativePath, sha256: digest(canonical(initialReceipt)) },
+  };
+}
+
+function assertMatchingExecutionMarker(marker, expected) {
+  if (canonical(marker.record) !== canonical(expected)) {
+    throw new Error(
+      'External mutation execution marker does not match its receipt and trusted claim. ' +
+        'Next: do not dispatch; create a fresh consent request, claim, and artifact root.',
+    );
+  }
+}
+
+async function publishExecutionMarker(destination, record, receipt, io = {}) {
+  const staged = await stagedRecord(destination.directory, record);
+  let published = null;
+  let failure = null;
+  try {
+    try {
+      await (io.markerLink ?? link)(staged.stagedPath, destination.absolute);
+      published = await readPublished(destination);
+      if (!published) throw new Error('the execution marker could not be reread');
+      assertMatchingExecutionMarker(published, record);
+      await (io.markerSyncDirectory ?? syncDirectory)(destination.directory);
+    } catch (error) {
+      if (error?.code === 'EEXIST') {
+        published = await readPublished(destination);
+        if (!published) failure = error;
+        else assertMatchingExecutionMarker(published, record);
+      } else {
+        failure = error;
+      }
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await (io.markerRm ?? rm)(staged.stagingDirectory, { recursive: true, force: true });
+  } catch (error) {
+    failure ??= error;
+  }
+  if (failure) {
+    throw recoveryError(receipt, `the validator-owned execution marker was not durably published (${failure instanceof Error ? failure.message : String(failure)})`);
+  }
+  return published;
+}
+
+function decimalBaseUnits(value, decimals = 6) {
+  const match = /^(0|[1-9][0-9]*)(?:\.([0-9]{1,6}))?$/u.exec(String(value ?? ''));
+  if (!match) throw new Error('External mutation amount must be a positive decimal with at most six places.');
+  const result = `${match[1]}${String(match[2] ?? '').padEnd(decimals, '0')}`.replace(/^0+(?=\d)/u, '');
+  if (!BASE_UNITS.test(result)) throw new Error('External mutation amount must be positive.');
+  return result;
+}
+
+function trustedString(value, label, pattern) {
+  const text = String(value ?? '');
+  if (!pattern.test(text)) throw new Error(`Trusted mutation ${label} is invalid.`);
+  return text;
+}
+
+export function trustedExternalMutationIdentity(input, page, operation) {
+  const trusted = input.context?.trustedMutation;
+  if (!trusted || typeof trusted !== 'object' || Array.isArray(trusted)) {
+    throw new Error('External mutation requires the runner-verified trustedMutation context.');
+  }
+  const runtime = page?.runtimeIdentity;
+  if (!runtime || typeof runtime !== 'object' || Array.isArray(runtime)) {
+    throw new Error('External mutation requires the current verified Extension runtime identity.');
+  }
+  if (runtime.runtimeSessionId !== trusted.runtimeSessionId
+    || runtime.cdpPort !== trusted.cdpPort
+    || runtime.cdpTargetId !== trusted.cdpTargetId
+    || runtime.extensionOrigin !== trusted.extensionOrigin) {
+    throw new Error('External mutation current runtime does not match the independently validated funding evidence.');
+  }
+  const operationName = String(operation.operation ?? '');
+  const amount = String(operation.amount ?? '');
+  const amountBaseUnits = decimalBaseUnits(amount);
+  const authorizationCount = Number(operation.authorizationCount ?? 1);
+  if (!Number.isInteger(authorizationCount) || authorizationCount < 1 || authorizationCount > 2) {
+    throw new Error('External mutation authorization count is invalid.');
+  }
+  const authorized = Array.isArray(trusted.operations)
+    ? trusted.operations.filter((entry) => entry?.operation === operationName
+      && entry?.unit === 'usdc-base-units'
+      && entry?.amountBaseUnits === amountBaseUnits)
+    : [];
+  if (authorized.length !== 1 || authorized[0]?.count !== authorizationCount) {
+    throw new Error('External mutation operation is not uniquely authorized by the trusted funding request.');
+  }
+  const nodeId = trustedString(input.context?.nodeId, 'nodeId', NODE_ID);
+  const runId = trustedString(trusted.runId, 'runId', SHA256);
+  const value = {
+    action: trustedString(input.action, 'action', /^metamask\.perps\.[a-z_]+$/u),
+    nodeId,
+    executionId: digest(`${runId}\0${nodeId}`),
+    runId,
+    rootRecipeSha256: trustedString(trusted.rootRecipeSha256, 'rootRecipeSha256', SHA256),
+    executionPlanSha256: trustedString(trusted.executionPlanSha256, 'executionPlanSha256', SHA256),
+    artifactsIdentitySha256: trustedString(trusted.artifactsIdentitySha256, 'artifactsIdentitySha256', SHA256),
+    activeRecipeSha256: trustedString(trusted.recipeSha256, 'recipeSha256', SHA256),
+    fundingRequestSha256: trustedString(trusted.requestSha256, 'requestSha256', SHA256),
+    fundingPreflightSha256: trustedString(trusted.preflightSha256, 'preflightSha256', SHA256),
+    fundingReleaseProofSha256: trustedString(trusted.releaseProofSha256, 'releaseProofSha256', SHA256),
+    fundingBalanceProofSha256: trustedString(trusted.balanceProofSha256, 'balanceProofSha256', SHA256),
+    fundingRequirementsSha256: trustedString(trusted.fundingRequirementsSha256, 'fundingRequirementsSha256', SHA256),
+    runtimeArtifactSha256: trustedString(trusted.runtimeArtifactSha256, 'runtimeArtifactSha256', SHA256),
+    runtimeTreeSha256: trustedString(trusted.runtimeTreeSha256, 'runtimeTreeSha256', SHA256),
+    selectedIdentitySha256: trustedString(trusted.selectedIdentitySha256, 'selectedIdentitySha256', SHA256),
+    cdpPort: Number(runtime.cdpPort),
+    cdpTargetId: trustedString(runtime.cdpTargetId, 'cdpTargetId', EXECUTION_ID),
+    runtimeSessionId: trustedString(runtime.runtimeSessionId, 'runtimeSessionId', EXECUTION_ID),
+    extensionOrigin: trustedString(runtime.extensionOrigin, 'extensionOrigin', ORIGIN),
+    operation: operationName,
+    ...(operation.provider == null ? {} : { provider: String(operation.provider).toLowerCase() }),
+    ...(operation.network == null ? {} : { network: String(operation.network).toLowerCase() }),
+    market: String(operation.market ?? '').toUpperCase(),
+    side: String(operation.side ?? '').toLowerCase(),
+    amount,
+    amountBaseUnits,
+    leverage: Number(operation.leverage),
+    orderType: String(operation.orderType ?? ''),
+    positionMode: String(operation.positionMode ?? ''),
+    limitPrice: operation.limitPrice == null ? null : String(operation.limitPrice),
+    offsetPct: operation.offsetPct == null ? null : String(operation.offsetPct),
+    partialCloseAmount: operation.partialCloseAmount == null ? null : String(operation.partialCloseAmount),
+    visibleOrderId: operation.visibleOrderId == null ? null : String(operation.visibleOrderId),
+    externalOrderId: operation.externalOrderId == null ? null : String(operation.externalOrderId),
+    roundingToleranceBaseUnits: String(operation.roundingToleranceBaseUnits ?? '0'),
+    ...(operation.positionAmountBaseUnits == null ? {} : {
+      positionAmountBaseUnits: String(operation.positionAmountBaseUnits),
+    }),
+    ...(operation.marginAction == null ? {} : { marginAction: String(operation.marginAction) }),
+    ...(operation.takeProfitPrice == null ? {} : { takeProfitPrice: String(operation.takeProfitPrice) }),
+    ...(operation.stopLossPrice == null ? {} : { stopLossPrice: String(operation.stopLossPrice) }),
+    ...(operation.positionSize == null ? {} : { positionSize: String(operation.positionSize) }),
+    ...(operation.cleanupOnly == null ? {} : { cleanupOnly: operation.cleanupOnly === true }),
+  };
+  if (!Number.isInteger(value.cdpPort) || value.cdpPort < 1 || value.cdpPort > 65535) {
+    throw new Error('Trusted mutation cdpPort is invalid.');
+  }
+  return validateIdentity(input, value);
+}
+
+export function assertTrustedExternalMutationTarget(input, page, identity) {
+  const trustedTargetId = trustedString(
+    input.context?.trustedMutation?.cdpTargetId,
+    'cdpTargetId',
+    EXECUTION_ID,
+  );
+  const currentTargetId = trustedString(page?.runtimeIdentity?.cdpTargetId, 'cdpTargetId', EXECUTION_ID);
+  if (currentTargetId !== trustedTargetId || currentTargetId !== identity?.cdpTargetId) {
+    throw new Error('External mutation current CDP target does not match its trusted wallet proof.');
+  }
+}
+
+export function trustedExternalMutationBudget(input, operation) {
+  const trusted = input.context?.trustedMutation;
+  const matches = Array.isArray(trusted?.budgets)
+    ? trusted.budgets.filter((entry) => entry?.operation === operation
+      && entry?.unit === 'usdc-base-units')
+    : [];
+  if (matches.length !== 1 || !BASE_UNITS.test(String(matches[0]?.maxBaseUnits ?? ''))) {
+    throw new Error('External mutation requires one runner-verified operation budget.');
+  }
+  return {
+    maxBaseUnits: String(matches[0].maxBaseUnits),
+    maxCount: Number(matches[0].maxCount),
+  };
+}
+
+export function trustedExternalMutationFundingRequirement(input) {
+  const trusted = input.context?.trustedMutation;
+  const requirements = Array.isArray(trusted?.requirements) ? trusted.requirements : [];
+  if (requirements.length !== 1) {
+    throw new Error('External mutation requires one runner-verified visible funding requirement.');
+  }
+  const requirement = requirements[0];
+  if (requirement?.kind !== 'metric' || requirement?.id !== 'perps-available-margin-usdc'
+    || !BASE_UNITS.test(String(requirement?.minBaseUnits ?? ''))
+    || !BASE_UNITS.test(String(requirement?.actualBaseUnits ?? ''))
+    || !SHA256.test(String(requirement?.evidenceSha256 ?? ''))
+    || BigInt(requirement.actualBaseUnits) < BigInt(requirement.minBaseUnits)
+    || digest(canonical(requirements)) !== trusted.fundingRequirementsSha256) {
+    throw new Error('External mutation visible funding requirement is invalid.');
+  }
+  return { ...requirement };
+}
+
+export function trustedExternalMutationPlanIsExact(input, operation, count = 1) {
+  const operations = input.context?.trustedMutation?.operations;
+  return Array.isArray(operations)
+    && operations.length === 1
+    && operations[0]?.operation === operation
+    && operations[0]?.unit === 'usdc-base-units'
+    && operations[0]?.count === count;
+}
+
+async function stagedRecord(directory, record) {
+  const stagingDirectory = await mkdtemp(path.join(directory, '.mutation-receipt-'));
+  await chmod(stagingDirectory, 0o700);
+  const stagedPath = path.join(stagingDirectory, 'receipt.json');
+  const bytes = canonical(record);
+  const handle = await open(stagedPath, 'wx', 0o600);
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return { bytes, stagedPath, stagingDirectory };
+}
+
+async function syncDirectory(directory) {
+  const handle = await open(directory, 'r');
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function durableDirectorySync(directory, io) {
+  return (io?.syncDirectory ?? syncDirectory)(directory);
+}
+
+function unreadableReceiptError(detail) {
+  return recoveryError({ sha256: 'unreadable-receipt' }, detail);
+}
+
+async function readPublished(destination) {
+  let entry;
+  try {
+    entry = await lstat(destination.absolute);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw unreadableReceiptError('the persisted receipt could not be inspected');
+  }
+  if (!entry.isFile() || entry.isSymbolicLink()) {
+    throw unreadableReceiptError('the persisted receipt is unsafe');
+  }
+  let bytes;
+  try {
+    bytes = await readFile(destination.absolute, 'utf8');
+  } catch {
+    throw unreadableReceiptError('the persisted receipt could not be read');
+  }
+  let record;
+  try {
+    record = JSON.parse(bytes);
+  } catch {
+    throw unreadableReceiptError(`the persisted receipt JSON is invalid (${digest(bytes)})`);
+  }
+  return {
+    record,
+    relativePath: destination.relative,
+    sha256: digest(bytes),
+  };
+}
+
+function validateIdentity(input, identity) {
+  const nodeId = String(input.context?.nodeId ?? '');
+  const value = {
+    action: String(input.action ?? ''),
+    nodeId,
+    executionId: String(identity.executionId ?? ''),
+    fundingRequestSha256: String(identity.fundingRequestSha256 ?? '').toLowerCase(),
+    fundingPreflightSha256: String(identity.fundingPreflightSha256 ?? '').toLowerCase(),
+    fundingReleaseProofSha256: String(identity.fundingReleaseProofSha256 ?? '').toLowerCase(),
+    fundingBalanceProofSha256: String(identity.fundingBalanceProofSha256 ?? '').toLowerCase(),
+    fundingRequirementsSha256: String(identity.fundingRequirementsSha256 ?? '').toLowerCase(),
+    runtimeArtifactSha256: String(identity.runtimeArtifactSha256 ?? '').toLowerCase(),
+    runtimeTreeSha256: String(identity.runtimeTreeSha256 ?? '').toLowerCase(),
+    runId: String(identity.runId ?? '').toLowerCase(),
+    rootRecipeSha256: String(identity.rootRecipeSha256 ?? '').toLowerCase(),
+    executionPlanSha256: String(identity.executionPlanSha256 ?? '').toLowerCase(),
+    artifactsIdentitySha256: String(identity.artifactsIdentitySha256 ?? '').toLowerCase(),
+    activeRecipeSha256: String(identity.activeRecipeSha256 ?? '').toLowerCase(),
+    selectedIdentitySha256: String(identity.selectedIdentitySha256 ?? '').toLowerCase(),
+    cdpPort: Number(identity.cdpPort),
+    cdpTargetId: String(identity.cdpTargetId ?? ''),
+    runtimeSessionId: String(identity.runtimeSessionId ?? ''),
+    extensionOrigin: String(identity.extensionOrigin ?? ''),
+    operation: String(identity.operation ?? ''),
+    ...(identity.provider == null ? {} : { provider: String(identity.provider).toLowerCase() }),
+    ...(identity.network == null ? {} : { network: String(identity.network).toLowerCase() }),
+    market: String(identity.market ?? '').toUpperCase(),
+    side: String(identity.side ?? '').toLowerCase(),
+    amount: String(identity.amount ?? ''),
+    amountBaseUnits: String(identity.amountBaseUnits ?? ''),
+    leverage: Number(identity.leverage),
+    orderType: String(identity.orderType ?? ''),
+    positionMode: String(identity.positionMode ?? ''),
+    limitPrice: identity.limitPrice == null ? null : String(identity.limitPrice),
+    offsetPct: identity.offsetPct == null ? null : String(identity.offsetPct),
+    partialCloseAmount: identity.partialCloseAmount == null ? null : String(identity.partialCloseAmount),
+    visibleOrderId: identity.visibleOrderId == null ? null : String(identity.visibleOrderId),
+    externalOrderId: identity.externalOrderId == null ? null : String(identity.externalOrderId),
+    roundingToleranceBaseUnits: String(identity.roundingToleranceBaseUnits ?? ''),
+    ...(identity.positionAmountBaseUnits == null ? {} : {
+      positionAmountBaseUnits: String(identity.positionAmountBaseUnits),
+    }),
+    ...(identity.marginAction == null ? {} : { marginAction: String(identity.marginAction) }),
+    ...(identity.takeProfitPrice == null ? {} : { takeProfitPrice: String(identity.takeProfitPrice) }),
+    ...(identity.stopLossPrice == null ? {} : { stopLossPrice: String(identity.stopLossPrice) }),
+    ...(identity.positionSize == null ? {} : { positionSize: String(identity.positionSize) }),
+    ...(identity.cleanupOnly == null ? {} : { cleanupOnly: identity.cleanupOnly === true }),
+  };
+  if (!NODE_ID.test(value.nodeId) || !EXECUTION_ID.test(value.executionId)) {
+    throw new Error('External mutation receipt requires bounded node and execution IDs.');
+  }
+  if (![value.fundingRequestSha256, value.fundingPreflightSha256,
+    value.fundingReleaseProofSha256, value.fundingBalanceProofSha256,
+    value.fundingRequirementsSha256, value.runtimeArtifactSha256, value.runtimeTreeSha256, value.runId,
+    value.rootRecipeSha256, value.executionPlanSha256, value.artifactsIdentitySha256,
+    value.activeRecipeSha256, value.selectedIdentitySha256]
+    .every((entry) => SHA256.test(entry)) || !BASE_UNITS.test(value.amountBaseUnits)) {
+    throw new Error('External mutation receipt requires trusted funding, recipe, run, wallet, and amount identities.');
+  }
+  if (!/^metamask\.perps\.[a-z_]+$/u.test(value.action)
+    || !/^perps-[a-z-]+$/u.test(value.operation)
+    || !/^[A-Z0-9:_-]{2,20}$/u.test(value.market)
+    || !/^(?:long|short)$/u.test(value.side)
+    || !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(value.amount)
+    || !Number.isInteger(value.cdpPort) || value.cdpPort < 1 || value.cdpPort > 65535
+    || !EXECUTION_ID.test(value.cdpTargetId) || !EXECUTION_ID.test(value.runtimeSessionId)
+    || !ORIGIN.test(value.extensionOrigin)) {
+    throw new Error('External mutation receipt identity is invalid.');
+  }
+  if (!Number.isInteger(value.leverage) || value.leverage < 1 || value.leverage > 100
+    || !/^[a-z][a-z0-9_-]{0,31}$/u.test(value.provider)
+    || !/^(?:mainnet|testnet)$/u.test(value.network)
+    || !/^(?:market|limit|close|margin|tpsl)$/u.test(value.orderType)
+    || !/^(?:new|modify|close)$/u.test(value.positionMode)
+    || !/^(?:0|[1-9][0-9]{0,29})$/u.test(value.roundingToleranceBaseUnits)
+    || (value.limitPrice !== null && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(value.limitPrice))
+    || (value.offsetPct !== null && !/^-?[0-9]+(?:\.[0-9]{1,6})?$/u.test(value.offsetPct))
+    || (value.partialCloseAmount !== null && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(value.partialCloseAmount))) {
+    throw new Error('External mutation receipt operation parameters are invalid.');
+  }
+  if ((value.positionAmountBaseUnits != null && !BASE_UNITS.test(value.positionAmountBaseUnits))
+    || (value.marginAction != null && !/^(?:add|remove)$/u.test(value.marginAction))
+    || (value.takeProfitPrice != null && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(value.takeProfitPrice))
+    || (value.stopLossPrice != null && !/^[1-9][0-9]*(?:\.[0-9]{1,6})?$/u.test(value.stopLossPrice))) {
+    throw new Error('External mutation receipt position parameters are invalid.');
+  }
+  if ((value.positionSize != null
+    && (!/^[0-9]+(?:\.[0-9]+)? [A-Z0-9:_-]{2,20}$/u.test(value.positionSize)
+      || Number.parseFloat(value.positionSize) <= 0))
+    || (value.cleanupOnly != null && value.cleanupOnly !== true)) {
+    throw new Error('External mutation receipt cleanup position identity is invalid.');
+  }
+  if (value.visibleOrderId !== null && !/^order-card-[A-Za-z0-9._:-]{1,180}$/u.test(value.visibleOrderId)) {
+    throw new Error('External mutation receipt visible order identity is invalid.');
+  }
+  if (value.externalOrderId !== null && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,180}$/u.test(value.externalOrderId)) {
+    throw new Error('External mutation receipt external order identity is invalid.');
+  }
+  return value;
+}
+
+function assertMatchingIdentity(receipt, identity) {
+  if (canonical(receipt.record.identity) !== canonical(identity)) {
+    throw new Error(
+      `External mutation receipt identity mismatch (${receipt.sha256}). ` +
+        'Next: do not submit; inspect the existing receipt and visible position/order.',
+    );
+  }
+}
+
+export async function readExternalMutationReceipt(input, rawIdentity) {
+  const identity = validateIdentity(input, rawIdentity);
+  const destination = await receiptDestination(input);
+  const receipt = await readPublished(destination);
+  if (!receipt) return null;
+  assertMatchingIdentity(receipt, identity);
+  return receipt;
+}
+
+export async function readPriorMutationReceipt(input, currentIdentity, action, identityFields = {}) {
+  const destination = await receiptDestination(input);
+  const names = (await readdir(destination.directory)).filter((name) => /^[a-f0-9]{64}\.json$/u.test(name));
+  if (names.length > 100) throw new Error('External mutation receipt directory exceeds its bounded file count.');
+  const matches = [];
+  for (const name of names) {
+    const absolute = path.join(destination.directory, name);
+    const receipt = await readPublished({ absolute, directory: destination.directory, relative: `mutation-receipts/${name}` });
+    if (!receipt?.record?.identity || receipt.record.identity.action !== action
+      || !Object.entries(identityFields).every(([field, value]) => receipt.record.identity[field] === value)) continue;
+    const prior = validateIdentity({
+      ...input,
+      action,
+      context: { ...input.context, nodeId: receipt.record.identity.nodeId },
+    }, receipt.record.identity);
+    const stableFields = [
+      'runId', 'rootRecipeSha256', 'fundingRequestSha256', 'fundingPreflightSha256',
+      'fundingReleaseProofSha256', 'fundingBalanceProofSha256',
+      'fundingRequirementsSha256', 'runtimeArtifactSha256', 'runtimeTreeSha256',
+      'executionPlanSha256', 'artifactsIdentitySha256',
+      'selectedIdentitySha256', 'cdpPort', 'cdpTargetId', 'runtimeSessionId', 'extensionOrigin', 'market', 'side',
+      'provider', 'network',
+    ];
+    if (stableFields.every((field) => prior[field] === currentIdentity[field])) matches.push(receipt);
+  }
+  if (matches.length !== 1) {
+    throw new Error(`Expected exactly one prior ${action} receipt in this trusted run, found ${matches.length}.`);
+  }
+  return matches[0];
+}
+
+export async function beginExternalMutation(input, rawIdentity, io = {}, facts = {}) {
+  const identity = validateIdentity(input, rawIdentity);
+  const factsBytes = canonical(facts);
+  if (!facts || typeof facts !== 'object' || Array.isArray(facts) || factsBytes.length > 4096
+    || /secret|password|srp|mnemonic|private.?key/iu.test(factsBytes)) {
+    throw new Error('External mutation receipt facts must be a small secret-free object.');
+  }
+  const destination = await receiptDestination(input, io);
+  const markerDestination = await executionMarkerDestination(input, identity);
+  const existingMarker = await readPublished(markerDestination);
+  const existing = await readPublished(destination);
+  if (existingMarker && !existing) {
+    throw new Error(
+      'External mutation was previously started but its receipt is missing. ' +
+        'Next: do not dispatch; create a fresh consent request, claim, and artifact root.',
+    );
+  }
+  if (existing) {
+    assertMatchingIdentity(existing, identity);
+    const expectedMarker = executionMarkerRecord(identity, existing, markerDestination.executionClaimSha256);
+    if (existingMarker) assertMatchingExecutionMarker(existingMarker, expectedMarker);
+    else await publishExecutionMarker(markerDestination, expectedMarker, existing, io);
+    if (existing.record?.state === 'not-dispatched') {
+      throw new Error(
+        'External mutation is terminally known not dispatched. Next: create a fresh consent request, claim, and artifact root.',
+      );
+    }
+    return { ...existing, resumed: true };
+  }
+  const record = {
+    schemaVersion: 1,
+    kind: 'external-mutation-receipt',
+    state: 'outcome-unknown',
+    identity,
+    facts,
+  };
+  const staged = await stagedRecord(destination.directory, record);
+  let published = null;
+  let failure = null;
+  try {
+    try {
+      await (io.link ?? link)(staged.stagedPath, destination.absolute);
+      published = {
+        record,
+        relativePath: destination.relative,
+        sha256: digest(staged.bytes),
+        resumed: false,
+      };
+      await durableDirectorySync(destination.directory, io);
+    } catch (error) {
+      if (published) {
+        failure = recoveryError(published, `the outcome-unknown receipt was published but not durably synced (${error instanceof Error ? error.message : String(error)})`);
+      } else if (error?.code === 'EEXIST') {
+        const raced = await readPublished(destination);
+        if (!raced) failure = error;
+        else {
+          assertMatchingIdentity(raced, identity);
+          published = { ...raced, resumed: true };
+        }
+      } else {
+        failure = error;
+      }
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await (io.rm ?? rm)(staged.stagingDirectory, { recursive: true, force: true });
+  } catch (error) {
+    if (published) {
+      failure = recoveryError(published, `receipt staging cleanup failed (${error instanceof Error ? error.message : String(error)})`);
+    } else if (!failure) {
+      failure = error;
+    }
+  }
+  if (failure) throw failure;
+  const marker = executionMarkerRecord(identity, published, markerDestination.executionClaimSha256);
+  await publishExecutionMarker(markerDestination, marker, published, io);
+  return published;
+}
+
+async function markExternalMutationNotDispatched(input, receipt, reason, io = {}) {
+  const destination = await receiptDestination(input, io);
+  const current = await readPublished(destination);
+  if (!current || current.sha256 !== receipt.sha256 || current.record?.state !== 'outcome-unknown') {
+    throw recoveryError(receipt, 'the receipt changed before the known-not-dispatched state was recorded');
+  }
+  const reasonText = reason instanceof Error ? reason.message : String(reason);
+  if (!reasonText || reasonText.length > 1024 || /secret|password|srp|mnemonic|private.?key/iu.test(reasonText)) {
+    throw recoveryError(receipt, 'the known-not-dispatched reason is unsafe');
+  }
+  const record = {
+    ...current.record,
+    state: 'not-dispatched',
+    notDispatchedReasonSha256: digest(reasonText),
+  };
+  const staged = await stagedRecord(destination.directory, record);
+  try {
+    await (io.rename ?? rename)(staged.stagedPath, destination.absolute);
+    await durableDirectorySync(destination.directory, io);
+  } finally {
+    await (io.rm ?? rm)(staged.stagingDirectory, { recursive: true, force: true });
+  }
+  const published = await readPublished(destination);
+  if (!published || published.record?.state !== 'not-dispatched') {
+    throw recoveryError(receipt, 'the known-not-dispatched receipt could not be reread');
+  }
+  return published;
+}
+
+async function completeExternalMutation(input, receipt, observation, io = {}) {
+  return withExternalMutationRecovery(receipt, async () => {
+    const destination = await receiptDestination(input);
+    const current = await readPublished(destination);
+    if (!current || current.sha256 !== receipt.sha256) {
+      throw new Error('the persisted receipt changed before completion');
+    }
+    const record = {
+      ...current.record,
+      state: 'succeeded',
+      observationSha256: digest(canonical(observation)),
+      observation,
+    };
+    if (canonical(observation).length > 8192
+      || /secret|password|srp|mnemonic|private.?key/iu.test(canonical(observation))) {
+      throw new Error('External mutation observation must be small and secret-free.');
+    }
+    const staged = await stagedRecord(destination.directory, record);
+    let renamed = false;
+    let failure = null;
+    try {
+      const entry = await lstat(destination.absolute);
+      if (!entry.isFile() || entry.isSymbolicLink()) {
+        throw new Error('the receipt destination became unsafe');
+      }
+      await (io.rename ?? rename)(staged.stagedPath, destination.absolute);
+      renamed = true;
+      await durableDirectorySync(destination.directory, io);
+    } catch (error) {
+      failure = error;
+    }
+    try {
+      await (io.rm ?? rm)(staged.stagingDirectory, { recursive: true, force: true });
+    } catch (error) {
+      failure ??= error;
+    }
+    if (failure) throw failure;
+    if (!renamed) throw new Error('the completed receipt was not published');
+    const published = io.readPublished
+      ? await io.readPublished(destination, readPublished)
+      : await readPublished(destination);
+    if (!published || published.record?.state !== 'succeeded') {
+      throw new Error('the completed receipt could not be reread');
+    }
+    return published;
+  });
+}
+
+export async function recordExternalMutationCleanupCandidate(input, receipt, candidate, io = {}) {
+  return withExternalMutationRecovery(receipt, async () => {
+    const destination = await receiptDestination(input);
+    const current = await readPublished(destination);
+    if (!current || current.sha256 !== receipt.sha256 || current.record?.state !== 'outcome-unknown') {
+      throw new Error('the outcome-unknown receipt changed before cleanup classification');
+    }
+    if (!Array.isArray(current.record?.facts?.baselineOrderIds)
+      || current.record.facts.baselineOrderIds.length !== 0
+      || !candidate || typeof candidate !== 'object' || Array.isArray(candidate)
+      || !/^order-card-[A-Za-z0-9._:-]{1,180}$/u.test(String(candidate.orderId ?? ''))
+      || ![candidate.observedNotionalBaseUnits, candidate.requestedNotionalBaseUnits, candidate.overageBaseUnits]
+        .every((value) => BASE_UNITS.test(String(value)))) {
+      throw new Error('the cleanup candidate is not bound to one new visible order and bounded notional facts');
+    }
+    if (BigInt(candidate.observedNotionalBaseUnits) <= BigInt(candidate.requestedNotionalBaseUnits)
+      || BigInt(candidate.overageBaseUnits)
+        !== BigInt(candidate.observedNotionalBaseUnits) - BigInt(candidate.requestedNotionalBaseUnits)) {
+      throw new Error('the cleanup candidate does not prove a positive policy overage');
+    }
+    const record = {
+      ...current.record,
+      state: 'observed-policy-violation',
+      cleanupCandidate: candidate,
+    };
+    const bytes = canonical(record);
+    if (bytes.length > 12_288 || /secret|password|srp|mnemonic|private.?key/iu.test(bytes)) {
+      throw new Error('the cleanup candidate receipt is unsafe');
+    }
+    const staged = await stagedRecord(destination.directory, record);
+    try {
+      await (io.rename ?? rename)(staged.stagedPath, destination.absolute);
+      await durableDirectorySync(destination.directory, io);
+    } finally {
+      await (io.rm ?? rm)(staged.stagingDirectory, { recursive: true, force: true });
+    }
+    const published = await readPublished(destination);
+    if (!published || published.record?.state !== 'observed-policy-violation') {
+      throw new Error('the cleanup candidate receipt could not be reread');
+    }
+    return published;
+  });
+}
+
+export async function runGuardedExternalMutation({ input, identity, dispatch, observe, publicationFacts, receiptIo }) {
+  const receipt = await beginExternalMutation(input, identity, receiptIo, publicationFacts);
+  if (receipt.record?.state === 'observed-policy-violation') {
+    throw new Error('External mutation receipt records an observed policy violation and is cleanup-only.');
+  }
+  if (receipt.record?.state !== 'outcome-unknown' && receipt.record?.state !== 'succeeded') {
+    throw new Error('External mutation receipt state is unsafe.');
+  }
+  if (!receipt.resumed) {
+    try {
+      await dispatch();
+    } catch (error) {
+      if (error instanceof ExternalMutationNotDispatchedError) {
+        await markExternalMutationNotDispatched(input, receipt, error, receiptIo);
+        throw new Error(
+          `External mutation was safely not dispatched (${error.message}). ` +
+          'Next: correct the observed state and create a fresh consent request, claim, and artifact root.',
+        );
+      }
+      throw recoveryError(receipt, `pointer dispatch may have occurred (${error instanceof Error ? error.message : String(error)})`);
+    }
+  }
+  let observation;
+  try {
+    observation = await observe({ resumed: receipt.resumed, receipt: receipt.record });
+  } catch (error) {
+    throw recoveryError(receipt, error instanceof Error ? error.message : String(error));
+  }
+  if (!observation || observation.success !== true) {
+    throw recoveryError(receipt, 'the matching visible postcondition was not proven');
+  }
+  const completed = receipt.record.state === 'succeeded'
+    ? receipt
+    : await completeExternalMutation(input, receipt, observation, receiptIo);
+  return {
+    receipt: {
+      path: completed.relativePath,
+      sha256: completed.sha256,
+      state: completed.record.state,
+    },
+    resumed: receipt.resumed,
+    recovery: null,
+    observation,
+  };
+}