@tangle-network/agent-runtime 0.91.0 → 0.92.1

package/dist/chunk-PH65PR4F.js

@@ -0,0 +1,860 @@
+import {
+  CLAIM_FORMAT_VERSION,
+  PENDING_FORMAT_VERSION,
+  PHASE_FORMAT_VERSION,
+  RecoveryAgentCandidateTraceStore,
+  TERMINAL_FORMAT_VERSION,
+  assertExactObjectKeys,
+  assertPreparedCandidateIntegrity,
+  assertRecoveryMatchesStaged,
+  assertTerminalAllowedInPhase,
+  assertTerminalMatchesClaim,
+  assertTerminalMatchesStaged,
+  beginPreparedCandidateDisposal,
+  candidateClaimFileInternals,
+  candidateCleanupDeadline,
+  candidateCleanupTimeout,
+  canonicalCandidateBytes,
+  canonicalCandidateDigest,
+  consumePreparedCandidateExecution,
+  immutableCandidateValue,
+  persistCandidateModelSettlementEvidence,
+  recoveredTerminalRecord,
+  rejectedFinish,
+  rejectedStage,
+  requireStagedTerminal,
+  sealAgentCandidateExecutorFinalCapture,
+  sealAgentCandidateModelSettlement,
+  sealTerminalDigest,
+  terminalRecord,
+  usdToNanos,
+  withinCandidateCleanupDeadline
+} from "./chunk-A62TP7SK.js";
+
+// src/candidate-execution/claim-file-store.ts
+import { randomUUID } from "crypto";
+import { linkSync } from "fs";
+import { mkdir, open, unlink } from "fs/promises";
+import { join } from "path";
+var {
+  assertExpiredLease,
+  assertLease,
+  assertSameSlot,
+  assertUnexpiredLease,
+  attemptRecord,
+  claimSlot,
+  leaseDigest,
+  newLease,
+  readClaim,
+  readClaimIfPresent,
+  readTerminal,
+  readTerminalIfPresent,
+  readTransitionIfPresent,
+  rejectedExistingClaim,
+  rejectedRetry,
+  retryRejection,
+  sealAttemptRef,
+  sealClaim,
+  sealLease
+} = candidateClaimFileInternals;
+var FileAgentCandidateExecutionClaimStore = class {
+  directory;
+  now;
+  constructor(options) {
+    if (options.directory.length === 0) {
+      throw new Error("candidate execution claim directory must not be empty");
+    }
+    this.directory = options.directory;
+    this.now = options.now ?? Date.now;
+  }
+  async tryClaim(requested) {
+    const claim = sealClaim(requested);
+    await mkdir(this.directory, { recursive: true });
+    const claimPath = this.claimPath(claim);
+    const existing = await readClaimIfPresent(claimPath);
+    if (existing) {
+      assertSameSlot(existing.claim, claim, claimPath);
+      return rejectedExistingClaim(existing.claim, claim);
+    }
+    assertUnexpiredLease(claim.leaseExpiresAtMs, this.now());
+    const retryFailure = await this.retryFailure(claim);
+    if (retryFailure) return rejectedRetry(claim, retryFailure);
+    const lease = newLease(claim);
+    const acquired = await writeRecordIfAbsent(this.directory, claimPath, {
+      version: CLAIM_FORMAT_VERSION,
+      ...claim,
+      phase: "claimed",
+      leaseDigest: leaseDigest(lease)
+    });
+    if (acquired) return Object.freeze({ acquired: true, claim, lease });
+    const winner = await readClaim(claimPath);
+    assertSameSlot(winner.claim, claim, claimPath);
+    return rejectedExistingClaim(winner.claim, claim);
+  }
+  async getAttempt(requestedAttempt) {
+    return await this.storedAttempt(sealAttemptRef(requestedAttempt));
+  }
+  async markCandidateMayRun(requestedLease) {
+    const lease = sealLease(requestedLease);
+    const claimPath = this.claimPath(lease);
+    const stored = await readClaim(claimPath);
+    assertSameSlot(stored.claim, lease, claimPath);
+    assertLease(stored.leaseDigest, stored.claim.leaseExpiresAtMs, lease);
+    const state = await this.transitionState(stored.claim);
+    if (state.phase === "candidate-may-run") {
+      return Object.freeze({ marked: false, phase: "candidate-may-run" });
+    }
+    if (state.staged) {
+      throw new Error("candidate execution terminal was staged before candidate-may-run phase");
+    }
+    assertUnexpiredLease(stored.claim.leaseExpiresAtMs, this.now());
+    const marked = await writeRecordIfAbsent(
+      this.directory,
+      this.transitionPath(stored.claim, 1),
+      {
+        version: PHASE_FORMAT_VERSION,
+        kind: "candidate-execution-phase",
+        executionId: stored.claim.executionId,
+        attempt: stored.claim.attempt,
+        executionPlanDigest: stored.claim.executionPlanDigest,
+        phase: "candidate-may-run"
+      },
+      this.ownerPublication(stored.claim)
+    );
+    if (marked) return Object.freeze({ marked: true, phase: "candidate-may-run" });
+    const winner = await this.transitionState(stored.claim);
+    if (winner.phase === "candidate-may-run") {
+      return Object.freeze({ marked: false, phase: "candidate-may-run" });
+    }
+    throw new Error("candidate execution terminal was staged before candidate-may-run phase");
+  }
+  async stageTerminal(requestedLease, result) {
+    const lease = sealLease(requestedLease);
+    const claimPath = this.claimPath(lease);
+    const stored = await readClaim(claimPath);
+    assertSameSlot(stored.claim, lease, claimPath);
+    assertLease(stored.leaseDigest, stored.claim.leaseExpiresAtMs, lease);
+    const terminal = terminalRecord(stored.claim, result);
+    const state = await this.transitionState(stored.claim);
+    if (state.staged) return rejectedStage(state.staged, terminal);
+    assertTerminalAllowedInPhase(state.phase, terminal);
+    assertUnexpiredLease(stored.claim.leaseExpiresAtMs, this.now());
+    const transition = state.phase === "claimed" ? 1 : 2;
+    const staged = await writeRecordIfAbsent(
+      this.directory,
+      this.transitionPath(stored.claim, transition),
+      {
+        version: PENDING_FORMAT_VERSION,
+        kind: "candidate-execution-pending-terminal",
+        terminal
+      },
+      this.ownerPublication(stored.claim)
+    );
+    if (staged) return Object.freeze({ staged: true, terminal });
+    const winner = await this.transitionState(stored.claim);
+    if (!winner.staged) {
+      throw new Error("candidate execution phase transition won while staging terminal");
+    }
+    return rejectedStage(winner.staged, terminal);
+  }
+  async finish(requestedLease, requestedTerminalDigest) {
+    const lease = sealLease(requestedLease);
+    const terminalDigest = sealTerminalDigest(requestedTerminalDigest);
+    const claimPath = this.claimPath(lease);
+    const stored = await readClaim(claimPath);
+    assertSameSlot(stored.claim, lease, claimPath);
+    assertLease(stored.leaseDigest, stored.claim.leaseExpiresAtMs, lease);
+    const state = await this.transitionState(stored.claim);
+    const staged = requireStagedTerminal(state.staged, terminalDigest);
+    const terminalPath = this.terminalPath(lease);
+    const existing = await readTerminalIfPresent(terminalPath);
+    if (existing) {
+      assertTerminalMatchesClaim(existing, stored.claim, terminalPath);
+      assertTerminalMatchesStaged(existing, staged, terminalPath);
+      return rejectedFinish(existing, terminalDigest);
+    }
+    assertUnexpiredLease(stored.claim.leaseExpiresAtMs, this.now());
+    const finished = await writeRecordIfAbsent(
+      this.directory,
+      terminalPath,
+      {
+        version: TERMINAL_FORMAT_VERSION,
+        terminal: staged
+      },
+      this.ownerPublication(stored.claim)
+    );
+    if (finished) return Object.freeze({ finished: true, terminal: staged });
+    const winner = await readTerminal(terminalPath);
+    assertSameSlot(winner, lease, terminalPath);
+    assertTerminalMatchesClaim(winner, stored.claim, terminalPath);
+    assertTerminalMatchesStaged(winner, staged, terminalPath);
+    return rejectedFinish(winner, terminalDigest);
+  }
+  async recoverExpired(requestedAttempt, evidence) {
+    const attempt = sealAttemptRef(requestedAttempt);
+    const record2 = await this.storedAttempt(attempt);
+    if (!record2) throw new Error("candidate execution recovery does not name an acquired attempt");
+    const recovered = recoveredTerminalRecord(record2.claim, record2.phase, evidence);
+    if (record2.staged) assertRecoveryMatchesStaged(record2.staged, recovered);
+    const requestedDigest = record2.staged?.terminalDigest ?? recovered.terminalDigest;
+    if (record2.terminal) return rejectedFinish(record2.terminal, requestedDigest);
+    assertExpiredLease(record2.claim.leaseExpiresAtMs, this.now());
+    let staged = record2.staged;
+    if (!staged) {
+      const transition = record2.phase === "claimed" ? 1 : 2;
+      const didStage = await writeRecordIfAbsent(
+        this.directory,
+        this.transitionPath(record2.claim, transition),
+        {
+          version: PENDING_FORMAT_VERSION,
+          kind: "candidate-execution-pending-terminal",
+          terminal: recovered
+        }
+      );
+      if (didStage) {
+        staged = recovered;
+      } else {
+        const winner2 = await this.transitionState(record2.claim);
+        if (!winner2.staged) {
+          throw new Error(
+            "candidate execution recovery lost terminal staging to a phase transition"
+          );
+        }
+        assertRecoveryMatchesStaged(winner2.staged, recovered);
+        staged = winner2.staged;
+      }
+    }
+    const terminalPath = this.terminalPath(attempt);
+    const didFinish = await writeRecordIfAbsent(this.directory, terminalPath, {
+      version: TERMINAL_FORMAT_VERSION,
+      terminal: staged
+    });
+    if (didFinish) return Object.freeze({ finished: true, terminal: staged });
+    const winner = await readTerminal(terminalPath);
+    assertSameSlot(winner, attempt, terminalPath);
+    assertTerminalMatchesClaim(winner, record2.claim, terminalPath);
+    assertTerminalMatchesStaged(winner, staged, terminalPath);
+    return rejectedFinish(winner, staged.terminalDigest);
+  }
+  async storedAttempt(claim) {
+    const claimPath = this.claimPath(claim);
+    const stored = await readClaimIfPresent(claimPath);
+    if (!stored) return void 0;
+    assertSameSlot(stored.claim, claim, claimPath);
+    const state = await this.transitionState(stored.claim);
+    const terminalPath = this.terminalPath(claim);
+    const terminal = await readTerminalIfPresent(terminalPath);
+    if (terminal) {
+      assertTerminalMatchesClaim(terminal, stored.claim, terminalPath);
+      if (!state.staged) {
+        throw new Error(
+          `candidate execution terminal record at ${terminalPath} has no staged outbox`
+        );
+      }
+      assertTerminalMatchesStaged(terminal, state.staged, terminalPath);
+    }
+    return attemptRecord(stored.claim, state.phase, state.staged, terminal);
+  }
+  async transitionState(claim) {
+    const firstPath = this.transitionPath(claim, 1);
+    const first = await readTransitionIfPresent(firstPath, claim);
+    if (!first) return { phase: "claimed" };
+    if (first.kind === "pending") return { phase: "claimed", staged: first.terminal };
+    const secondPath = this.transitionPath(claim, 2);
+    const second = await readTransitionIfPresent(secondPath, claim);
+    if (!second) return { phase: "candidate-may-run" };
+    if (second.kind !== "pending") {
+      throw new Error(`candidate execution transition at ${secondPath} repeats the phase marker`);
+    }
+    return { phase: "candidate-may-run", staged: second.terminal };
+  }
+  async retryFailure(claim) {
+    if (claim.attempt === 1) return void 0;
+    return retryRejection(
+      claim,
+      await this.storedAttempt({
+        executionId: claim.executionId,
+        attempt: claim.attempt - 1
+      })
+    );
+  }
+  ownerPublication(claim) {
+    return {
+      authorizePublish: () => {
+        assertUnexpiredLease(claim.leaseExpiresAtMs, this.now());
+        return true;
+      }
+    };
+  }
+  claimPath(claim) {
+    return join(this.directory, `${claimSlot(claim)}.claim.json`);
+  }
+  terminalPath(claim) {
+    return join(this.directory, `${claimSlot(claim)}.terminal.json`);
+  }
+  transitionPath(claim, ordinal) {
+    return join(this.directory, `${claimSlot(claim)}.transition-${ordinal}.json`);
+  }
+};
+async function writeRecordIfAbsent(directory, destination, record2, options = {}) {
+  const temporaryPath = join(directory, `.candidate-execution-${process.pid}-${randomUUID()}.tmp`);
+  const handle = await open(temporaryPath, "wx", 384);
+  try {
+    await handle.writeFile(
+      Buffer.concat([Buffer.from(canonicalCandidateBytes(record2)), Buffer.from("\n")])
+    );
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  let written = false;
+  try {
+    if (options.authorizePublish && options.authorizePublish() !== true) {
+      throw new Error("candidate execution record publication was not authorized");
+    }
+    linkSync(temporaryPath, destination);
+    written = true;
+    await syncDirectory(directory);
+  } catch (error) {
+    if (!isNodeError(error, "EEXIST")) throw error;
+  } finally {
+    await unlink(temporaryPath).catch((error) => {
+      if (!isNodeError(error, "ENOENT")) throw error;
+    });
+  }
+  return written;
+}
+async function syncDirectory(directory) {
+  const handle = await open(directory, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+function isNodeError(error, code) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === code;
+}
+
+// src/candidate-execution/dispose.ts
+async function disposePreparedAgentCandidateExecution(prepared, options = {}) {
+  const initialState = assertPreparedCandidateIntegrity(prepared);
+  const cleanupTimeoutMs = options.cleanupTimeoutMs ?? initialState.cleanupTimeoutMs;
+  if (cleanupTimeoutMs > initialState.cleanupTimeoutMs) {
+    throw new Error("disposal cleanup timeout exceeds the frozen preparation bound");
+  }
+  const cleanupDeadlineAtMs = candidateCleanupDeadline(cleanupTimeoutMs);
+  const state = beginPreparedCandidateDisposal(prepared);
+  const cleanup = [];
+  if (state.memory.mode === "isolated") {
+    const reservation = state.memoryReservation;
+    if (!reservation) throw new Error("isolated memory reservation is missing");
+    cleanup.push(
+      withinCandidateCleanupDeadline(
+        async () => {
+          const closed = await state.ports.memory.close({
+            executionId: state.executionId,
+            preparationId: reservation.preparationId,
+            accessDigest: reservation.accessDigest,
+            effectiveNamespace: reservation.effectiveNamespace,
+            reason: "abandoned"
+          });
+          if (closed.closed !== true || Object.keys(closed).some((key) => key !== "closed")) {
+            throw new Error("abandoned isolated memory access did not acknowledge closure");
+          }
+        },
+        cleanupDeadlineAtMs,
+        "isolated memory disposal"
+      )
+    );
+  }
+  cleanup.push(
+    withinCandidateCleanupDeadline(
+      async () => {
+        const settlement = sealAgentCandidateModelSettlement(
+          await state.ports.models.settleGrant({
+            executionId: state.executionId,
+            preparationId: state.preparationId,
+            grantDigest: state.modelReservation.digest,
+            resolved: state.resolvedModel,
+            reason: "abandoned"
+          }),
+          {
+            preparationId: state.preparationId,
+            grantDigest: state.modelReservation.digest,
+            model: state.resolvedModel.model
+          }
+        );
+        if (settlement.usage.modelCalls !== 0) {
+          throw new Error("unexecuted model reservation unexpectedly contains calls");
+        }
+      },
+      cleanupDeadlineAtMs,
+      "model reservation disposal"
+    )
+  );
+  const results = await Promise.allSettled(cleanup);
+  const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason);
+  if (failures.length > 0) {
+    consumePreparedCandidateExecution(prepared, "disposal-failed");
+    throw new AggregateError(failures, "candidate preparation disposal failed");
+  }
+  consumePreparedCandidateExecution(prepared, "disposed");
+  return Object.freeze({ disposed: true });
+}
+
+// src/candidate-execution/protected-model-port.ts
+var MAX_RECENT_SETTLEMENTS = 4096;
+var RECOVERED_SETTLEMENT_RETENTION_MS = 15 * 60 * 1e3;
+function createProtectedAgentCandidateModelPort(options) {
+  const gatewayDomain = assertGatewayDomain(options.gatewayDomain);
+  const activationEnvNames = exactEnvironmentNames(options.activationEnvNames);
+  const reservations = /* @__PURE__ */ new Map();
+  const recentSettlements = /* @__PURE__ */ new Map();
+  return {
+    resolve: async (input) => {
+      const request = immutableCandidateValue(input);
+      const resolved = validateResolvedModel(await options.resolveModel(request), request);
+      return immutableCandidateValue(resolved);
+    },
+    reserveGrant: async (input) => {
+      pruneExpiredState(reservations, recentSettlements, Date.now());
+      const request = immutableCandidateValue(input);
+      validateReserveInput(request);
+      const requestDigest = canonicalCandidateDigest(request);
+      const key = reservationKey(request.executionId, request.preparationId);
+      if (recentSettlements.has(key)) {
+        throw new Error("protected model reservation is already settled");
+      }
+      const previous = reservations.get(key);
+      if (previous && previous.requestDigest !== requestDigest) {
+        throw new Error("protected model reservation retry changed immutable input");
+      }
+      const reservation = validateReservation(
+        await options.client.reserve(request),
+        request,
+        gatewayDomain
+      );
+      const responseDigest = canonicalCandidateDigest(reservation);
+      if (recentSettlements.has(key)) {
+        throw new Error("protected model reservation completed after the grant was settled");
+      }
+      const recorded = previous ?? reservations.get(key);
+      if (recorded && recorded.requestDigest !== requestDigest) {
+        throw new Error("protected model reservation retry changed immutable input");
+      }
+      if (recorded && recorded.responseDigest !== responseDigest) {
+        throw new Error("protected model reservation retry returned different evidence");
+      }
+      if (!recorded) {
+        reservations.set(key, {
+          requestDigest,
+          responseDigest,
+          executionId: request.executionId,
+          preparationId: request.preparationId,
+          grantDigest: reservation.digest,
+          expiresAtMs: request.expiresAtMs,
+          resolved: immutableCandidateValue(request.resolved),
+          limits: immutableCandidateValue(request.limits),
+          maxCostUsdNanos: usdToNanos(request.limits.maxCostUsd, "reserved maxCostUsd"),
+          activation: "reserved"
+        });
+      }
+      return reservation;
+    },
+    activateGrant: async (input) => {
+      pruneExpiredState(reservations, recentSettlements, Date.now());
+      const request = immutableCandidateValue(input);
+      const key = reservationKey(request.executionId, request.preparationId);
+      if (recentSettlements.has(key)) throw new Error("protected model grant is already settled");
+      const state = reservations.get(key);
+      if (!state) throw new Error("protected model grant was not reserved by this port");
+      assertGrantIdentity(state, request);
+      if (state.settlementDigest) throw new Error("protected model grant is already settled");
+      if (state.activation !== "reserved") {
+        throw new Error("protected model grant activation is single-use");
+      }
+      if (!Number.isSafeInteger(request.deadlineAtMs) || request.deadlineAtMs <= 0) {
+        throw new Error("protected model activation deadline must be a positive safe integer");
+      }
+      if (request.deadlineAtMs <= Date.now()) {
+        throw new Error("protected model activation deadline must be in the future");
+      }
+      if (request.deadlineAtMs > state.expiresAtMs) {
+        throw new Error("protected model activation deadline exceeds the reserved expiry");
+      }
+      state.activation = "activating";
+      try {
+        const activation = validateActivation(
+          await options.client.activate(request),
+          state.limits.maxModelCalls === 0 ? [] : activationEnvNames
+        );
+        if (recentSettlements.has(key) || reservations.get(key) !== state) {
+          throw new Error("protected model grant settled while activation was in flight");
+        }
+        state.activation = "activated";
+        return activation;
+      } catch (error) {
+        state.activation = "reserved";
+        throw error;
+      }
+    },
+    settleGrant: async (input) => {
+      const now = Date.now();
+      pruneExpiredState(reservations, recentSettlements, now);
+      const request = immutableCandidateValue(input);
+      const key = reservationKey(request.executionId, request.preparationId);
+      const state = reservations.get(key);
+      if (state) assertGrantIdentity(state, request);
+      const remembered = state ?? recentSettlements.get(key);
+      if (remembered?.settlementReason && remembered.settlementReason !== request.reason) {
+        throw new Error("protected model settlement retry changed the termination reason");
+      }
+      const sealed = sealAgentCandidateModelSettlement(await options.client.settle(request), {
+        preparationId: request.preparationId,
+        grantDigest: request.grantDigest,
+        model: request.resolved.model
+      });
+      if (state) assertWithinReservedLimits(sealed.fixedUsage, state);
+      const settlementDigest = canonicalCandidateDigest(sealed.value);
+      if (remembered?.settlementDigest && remembered.settlementDigest !== settlementDigest) {
+        throw new Error("protected model settlement retry returned a different final ledger");
+      }
+      if (remembered?.settlementReason && remembered.settlementReason !== request.reason) {
+        throw new Error("protected model settlement retry changed the termination reason");
+      }
+      const expiresAtMs = state?.expiresAtMs ?? now + RECOVERED_SETTLEMENT_RETENTION_MS;
+      if (state) {
+        state.settlementDigest = settlementDigest;
+        state.settlementReason = request.reason;
+      }
+      reservations.delete(key);
+      rememberSettlement(recentSettlements, key, {
+        settlementDigest,
+        settlementReason: request.reason,
+        expiresAtMs
+      });
+      return sealed.value;
+    }
+  };
+}
+function validateReserveInput(input) {
+  if (!Number.isSafeInteger(input.expiresAtMs) || input.expiresAtMs <= 0) {
+    throw new Error("protected model reservation expiry must be a positive safe integer");
+  }
+  if (input.expiresAtMs <= Date.now()) {
+    throw new Error("protected model reservation expiry must be in the future");
+  }
+  for (const [name, value] of [
+    ["maxModelCalls", input.limits.maxModelCalls],
+    ["maxInputTokens", input.limits.maxInputTokens],
+    ["maxOutputTokens", input.limits.maxOutputTokens]
+  ]) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(`protected model reservation ${name} must be a nonnegative safe integer`);
+    }
+  }
+  usdToNanos(input.limits.maxCostUsd, "reserved maxCostUsd");
+}
+function validateReservation(value, expected, gatewayDomain) {
+  const source = exactRecord(
+    value,
+    ["preparationId", "digest", "expiresAtMs", "enforcedLimits", "network"],
+    "protected model reservation response"
+  );
+  if (source.preparationId !== expected.preparationId) {
+    throw new Error("protected model reservation response changed preparation identity");
+  }
+  if (!isSha256Digest(source.digest)) {
+    throw new Error("protected model reservation response has an invalid digest");
+  }
+  if (source.expiresAtMs !== expected.expiresAtMs) {
+    throw new Error("protected model reservation response changed expiry");
+  }
+  exactRecord(
+    source.enforcedLimits,
+    ["maxModelCalls", "maxInputTokens", "maxOutputTokens", "maxCostUsd"],
+    "protected model reservation enforced limits"
+  );
+  if (canonicalCandidateDigest(source.enforcedLimits) !== canonicalCandidateDigest(expected.limits)) {
+    throw new Error("protected model reservation response changed enforced limits");
+  }
+  const network = validateReservationNetwork(
+    source.network,
+    expected.limits.maxModelCalls,
+    gatewayDomain
+  );
+  return immutableCandidateValue({
+    preparationId: source.preparationId,
+    digest: source.digest,
+    expiresAtMs: source.expiresAtMs,
+    enforcedLimits: source.enforcedLimits,
+    network
+  });
+}
+function validateReservationNetwork(value, maxModelCalls, gatewayDomain) {
+  if (maxModelCalls === 0) {
+    const source2 = exactRecord(value, ["mode"], "protected model reservation network");
+    if (source2.mode !== "disabled") {
+      throw new Error("zero-call protected model reservation must disable gateway access");
+    }
+    return { mode: "disabled" };
+  }
+  const source = exactRecord(value, ["mode", "domains"], "protected model reservation network");
+  if (source.mode !== "gateway-only") {
+    throw new Error("protected model reservation must allow only its model gateway");
+  }
+  if (!Array.isArray(source.domains) || source.domains.length !== 1 || source.domains[0] !== gatewayDomain) {
+    throw new Error("protected model reservation returned an unexpected gateway domain");
+  }
+  return { mode: "gateway-only", domains: [gatewayDomain] };
+}
+function validateActivation(value, expectedNames) {
+  const source = exactRecord(value, ["env"], "protected model activation response");
+  const env = record(source.env, "protected model activation environment");
+  const actualNames = Object.keys(env).sort();
+  if (actualNames.length !== expectedNames.length || actualNames.some((name, index) => name !== expectedNames[index])) {
+    throw new Error("protected model activation returned unexpected environment names");
+  }
+  const detached = /* @__PURE__ */ Object.create(null);
+  for (const name of expectedNames) {
+    const value2 = env[name];
+    if (typeof value2 !== "string" || value2.length < 8 || value2.length > 65536) {
+      throw new Error(`protected model activation ${name} must be a non-empty protected value`);
+    }
+    detached[name] = value2;
+  }
+  return Object.freeze({ env: Object.freeze(detached) });
+}
+function validateResolvedModel(value, expected) {
+  const source = exactRecord(
+    value,
+    ["requested", "provider", "model", "snapshot", "reasoningEffort"],
+    "resolved candidate model"
+  );
+  if (source.requested !== expected.requested) {
+    throw new Error("model resolver changed the evaluator-owned request");
+  }
+  if (source.reasoningEffort !== expected.reasoningEffort) {
+    throw new Error("model resolver changed the evaluator-owned reasoning effort");
+  }
+  for (const name of ["requested", "provider", "model", "snapshot"]) {
+    if (typeof source[name] !== "string" || source[name].length === 0) {
+      throw new Error(`resolved candidate model ${name} must be non-empty`);
+    }
+  }
+  return source;
+}
+function assertGrantIdentity(expected, actual) {
+  if (actual.executionId !== expected.executionId || actual.preparationId !== expected.preparationId || actual.grantDigest !== expected.grantDigest || canonicalCandidateDigest(actual.resolved) !== canonicalCandidateDigest(expected.resolved)) {
+    throw new Error("protected model grant input does not match its immutable reservation");
+  }
+}
+function assertWithinReservedLimits(usage, reservation) {
+  for (const [name, actual, limit] of [
+    ["model calls", usage.modelCalls, reservation.limits.maxModelCalls],
+    ["input tokens", usage.inputTokens, reservation.limits.maxInputTokens],
+    ["output tokens", usage.outputTokens, reservation.limits.maxOutputTokens],
+    ["cost USD nanos", usage.costUsdNanos, reservation.maxCostUsdNanos]
+  ]) {
+    if (actual > limit) {
+      throw new Error(`protected model settlement ${name} ${actual} exceeds reserved ${limit}`);
+    }
+  }
+}
+function exactEnvironmentNames(values) {
+  if (values.length === 0) {
+    throw new Error("protected model activation environment names must not be empty");
+  }
+  const names = [...values].sort();
+  if (new Set(names).size !== names.length) {
+    throw new Error("protected model activation environment names must be unique");
+  }
+  for (const name of names) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || ["__proto__", "constructor", "prototype"].includes(name)) {
+      throw new Error(`protected model activation environment name is invalid: ${name}`);
+    }
+  }
+  return Object.freeze(names);
+}
+function assertGatewayDomain(value) {
+  if (value.length > 253 || value !== value.toLowerCase() || value.endsWith(".") || value.includes(":") || value === "localhost" || value.endsWith(".localhost") || value === "metadata.google" || value === "metadata.google.internal") {
+    throw new Error("protected model gateway must be an exact lowercase public DNS name");
+  }
+  const labels = value.split(".");
+  if (labels.length < 2 || !labels.every(
+    (label) => label.length >= 1 && label.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)
+  ) || !/[a-z]/.test(labels.at(-1) ?? "")) {
+    throw new Error("protected model gateway must be an exact lowercase public DNS name");
+  }
+  return value;
+}
+function reservationKey(executionId, preparationId) {
+  return canonicalCandidateDigest({ executionId, preparationId });
+}
+function pruneExpiredState(reservations, settlements, now) {
+  for (const [key, value] of reservations) {
+    if (value.expiresAtMs <= now) reservations.delete(key);
+  }
+  for (const [key, value] of settlements) {
+    if (value.expiresAtMs <= now) settlements.delete(key);
+  }
+}
+function rememberSettlement(settlements, key, value) {
+  settlements.delete(key);
+  settlements.set(key, value);
+  while (settlements.size > MAX_RECENT_SETTLEMENTS) {
+    const oldest = settlements.keys().next().value;
+    if (oldest === void 0) return;
+    settlements.delete(oldest);
+  }
+}
+function isSha256Digest(value) {
+  return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+function exactRecord(value, keys, label) {
+  const source = record(value, label);
+  assertExactObjectKeys(source, keys, label);
+  return source;
+}
+function record(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new Error(`${label} must be a plain object`);
+  }
+  return value;
+}
+
+// src/candidate-execution/recover.ts
+async function recoverExpiredAgentCandidateExecution(options) {
+  const record2 = await options.claimStore.getAttempt(options.attempt);
+  if (!record2) throw new Error("candidate execution recovery attempt is missing");
+  if (record2.terminal) {
+    return Object.freeze({ finished: false, terminal: record2.terminal, exactReplay: true });
+  }
+  const cleanupTimeoutMs = candidateCleanupTimeout(
+    options.cleanupTimeoutMs ?? record2.claim.cleanup.cleanupTimeoutMs
+  );
+  if (cleanupTimeoutMs > record2.claim.cleanup.cleanupTimeoutMs) {
+    throw new Error("recovery cleanup timeout exceeds the frozen preparation bound");
+  }
+  const now = options.now ?? Date.now;
+  if (now() < record2.claim.leaseExpiresAtMs) {
+    throw new Error("candidate execution lease has not expired");
+  }
+  const cleanupDeadlineAtMs = candidateCleanupDeadline(cleanupTimeoutMs);
+  const controller = new AbortController();
+  controller.abort(new Error("recovering an expired candidate execution"));
+  const recoveryTraceStore = new RecoveryAgentCandidateTraceStore(options.traceStore);
+  const processClosure = withinCandidateCleanupDeadline(
+    async () => {
+      const stopped = await options.executor.stopAndCapture(
+        {
+          executionId: record2.claim.executionId,
+          executionPlanDigest: record2.claim.executionPlanDigest
+        },
+        {
+          traceStore: recoveryTraceStore,
+          reason: "failed",
+          signal: controller.signal,
+          deadlineAtMs: record2.claim.leaseExpiresAtMs
+        }
+      );
+      sealAgentCandidateExecutorFinalCapture(stopped);
+      return { stopped: true };
+    },
+    cleanupDeadlineAtMs,
+    "expired candidate process termination"
+  );
+  const modelClosure = withinCandidateCleanupDeadline(
+    async () => sealAgentCandidateModelSettlement(
+      await options.ports.models.settleGrant({
+        executionId: record2.claim.executionId,
+        preparationId: record2.claim.cleanup.preparationId,
+        grantDigest: record2.claim.cleanup.modelGrantDigest,
+        resolved: record2.claim.cleanup.resolvedModel,
+        reason: "failed"
+      }),
+      {
+        preparationId: record2.claim.cleanup.preparationId,
+        grantDigest: record2.claim.cleanup.modelGrantDigest,
+        model: record2.claim.cleanup.resolvedModel.model
+      }
+    ),
+    cleanupDeadlineAtMs,
+    "expired candidate model settlement"
+  );
+  const memoryClosure = record2.claim.cleanup.memory ? withinCandidateCleanupDeadline(
+    async () => {
+      const memory2 = record2.claim.cleanup.memory;
+      if (!memory2) throw new Error("expired candidate memory handle is missing");
+      const closed = await options.ports.memory.close({
+        executionId: record2.claim.executionId,
+        preparationId: record2.claim.cleanup.preparationId,
+        accessDigest: memory2.accessDigest,
+        effectiveNamespace: memory2.effectiveNamespace,
+        reason: "failed"
+      });
+      if (closed.closed !== true || Object.keys(closed).some((key) => key !== "closed")) {
+        throw new Error("expired candidate memory did not acknowledge closure");
+      }
+      return { closed: true };
+    },
+    cleanupDeadlineAtMs,
+    "expired candidate memory closure"
+  ) : void 0;
+  const operations = [processClosure, modelClosure, ...memoryClosure ? [memoryClosure] : []];
+  const outcomes = await Promise.allSettled(operations);
+  const failures = outcomes.filter((outcome) => outcome.status === "rejected").map((outcome) => outcome.reason);
+  if (failures.length > 0) {
+    throw new AggregateError(failures, "expired candidate cleanup could not be proven");
+  }
+  const model = await modelClosure;
+  const modelSettlement = await withinCandidateCleanupDeadline(
+    () => persistCandidateModelSettlementEvidence(
+      {
+        executionId: record2.claim.executionId,
+        executionPlanDigest: record2.claim.executionPlanDigest,
+        resolvedModel: record2.claim.cleanup.resolvedModel
+      },
+      model,
+      options.outputArtifacts
+    ),
+    cleanupDeadlineAtMs,
+    "expired candidate model-settlement persistence"
+  );
+  const memory = record2.claim.cleanup.memory;
+  return await options.claimStore.recoverExpired(options.attempt, {
+    failureClass: record2.phase === "claimed" && model.fixedUsage.modelCalls === 0 ? "pre-model-infrastructure" : "unknown",
+    usage: model.fixedUsage,
+    modelSettlement: modelSettlement.artifact,
+    process: {
+      stopped: true,
+      executionPlanDigest: record2.claim.executionPlanDigest
+    },
+    model: {
+      closed: true,
+      preparationId: record2.claim.cleanup.preparationId,
+      grantDigest: record2.claim.cleanup.modelGrantDigest
+    },
+    ...memory ? {
+      memory: {
+        closed: true,
+        preparationId: record2.claim.cleanup.preparationId,
+        accessDigest: memory.accessDigest,
+        effectiveNamespace: memory.effectiveNamespace
+      }
+    } : {}
+  });
+}
+
+export {
+  FileAgentCandidateExecutionClaimStore,
+  disposePreparedAgentCandidateExecution,
+  createProtectedAgentCandidateModelPort,
+  recoverExpiredAgentCandidateExecution
+};
+//# sourceMappingURL=chunk-PH65PR4F.js.map