@lazyingart/agintiflow 0.20.331 → 0.20.336-integration.2

package/src/execution-worker-jobs.js

@@ -0,0 +1,399 @@
+import { types as utilTypes } from "node:util";
+
+import {
+  ExecutionWorkerError,
+  executionJobRequestDigest,
+  validateExecutionJobRequest,
+  validateExecutionResult,
+} from "./execution-worker.js";
+import { contractDigest } from "./integration-policy.js";
+
+export const EXECUTION_JOB_MANAGER_SCHEMA_VERSION = "aginti-execution-job-manager-v1";
+export const EXECUTION_EVENT_SCHEMA_VERSION = "aginti-execution-event-v1";
+export const EXECUTION_ZERO_EVENT_HASH = "0".repeat(64);
+export const EXECUTION_MAX_RETAINED_JOBS = 128;
+
+const JOB_ID = /^job_[A-Za-z0-9_-]{24,96}$/u;
+const ARTIFACT_ID = /^art_[A-Za-z0-9_-]{32,86}$/u;
+const DIGEST = /^[a-f0-9]{64}$/u;
+const TERMINAL_STATES = new Set([
+  "succeeded",
+  "failed",
+  "timed_out",
+  "output_limited",
+  "cancelled",
+  "sandbox_error",
+  "artifact_invalid",
+  "termination_unproven",
+  "worker_error",
+]);
+
+function fail(code, message, { status = 400, details } = {}) {
+  throw new ExecutionWorkerError(code, message, { status, details });
+}
+
+function exactObject(input, allowed, required, label) {
+  if (
+    !input || typeof input !== "object" || Array.isArray(input) || utilTypes.isProxy(input) ||
+    (Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)
+  ) {
+    fail("EXECUTION_REQUEST_INVALID", `${label} must be a plain data object.`);
+  }
+  const keys = Reflect.ownKeys(input);
+  if (keys.some((key) => typeof key !== "string" || !allowed.includes(key))) {
+    fail("EXECUTION_REQUEST_INVALID", `${label} contains an unsupported field.`);
+  }
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!descriptor?.enumerable || !Object.prototype.hasOwnProperty.call(descriptor, "value")) {
+      fail("EXECUTION_REQUEST_INVALID", `${label} must contain only data fields.`);
+    }
+  }
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(input, key)) {
+      fail("EXECUTION_REQUEST_INVALID", `${label}.${key} is required.`);
+    }
+  }
+  return input;
+}
+
+function reference(input, label = "execution job reference") {
+  const value = exactObject(input, ["jobId", "attempt"], ["jobId", "attempt"], label);
+  if (typeof value.jobId !== "string" || !JOB_ID.test(value.jobId)) {
+    fail("EXECUTION_REQUEST_INVALID", `${label}.jobId is invalid.`);
+  }
+  if (!Number.isSafeInteger(value.attempt) || value.attempt < 1 || value.attempt > 1_000_000) {
+    fail("EXECUTION_REQUEST_INVALID", `${label}.attempt is invalid.`);
+  }
+  return Object.freeze({ jobId: value.jobId, attempt: value.attempt });
+}
+
+function recordKey({ jobId, attempt }) {
+  return `${jobId}:${attempt}`;
+}
+
+function timestamp(value) {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/u.test(value)) {
+    fail("EXECUTION_CLOCK_INVALID", "execution worker clock returned an invalid timestamp.", { status: 503 });
+  }
+  return value;
+}
+
+function eventData(value) {
+  return Object.freeze(value);
+}
+
+function appendEvent(record, type, data, now) {
+  const previous = record.events.at(-1);
+  const unsigned = Object.freeze({
+    schemaVersion: EXECUTION_EVENT_SCHEMA_VERSION,
+    jobId: record.jobId,
+    attempt: record.attempt,
+    seq: record.events.length + 1,
+    previousHash: previous?.eventHash || EXECUTION_ZERO_EVENT_HASH,
+    type,
+    timestamp: timestamp(now()),
+    data: eventData(data),
+  });
+  const event = Object.freeze({ ...unsigned, eventHash: contractDigest(unsigned) });
+  record.events.push(event);
+  record.updatedAt = event.timestamp;
+  return event;
+}
+
+function publicRecord(record, { reused = false } = {}) {
+  return Object.freeze({
+    schemaVersion: EXECUTION_JOB_MANAGER_SCHEMA_VERSION,
+    jobId: record.jobId,
+    attempt: record.attempt,
+    sourceSha256: record.sourceSha256,
+    state: record.state,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt,
+    reused,
+    terminal: TERMINAL_STATES.has(record.state),
+    result: record.result,
+    errorCode: record.errorCode,
+  });
+}
+
+function workerErrorCode(error) {
+  if (error instanceof ExecutionWorkerError && typeof error.code === "string") return error.code;
+  return "EXECUTION_WORKER_FAILURE";
+}
+
+export function createExecutionJobManager({
+  worker,
+  now = () => new Date().toISOString(),
+  maximumRetainedJobs = EXECUTION_MAX_RETAINED_JOBS,
+} = {}) {
+  if (!worker || typeof worker.capabilities !== "function" || typeof worker.execute !== "function") {
+    throw new TypeError("worker must provide capabilities and execute");
+  }
+  if (typeof now !== "function") throw new TypeError("now must be a function");
+  if (!Number.isSafeInteger(maximumRetainedJobs) || maximumRetainedJobs < 8 || maximumRetainedJobs > 1_024) {
+    throw new TypeError("maximumRetainedJobs is invalid");
+  }
+  const records = new Map();
+  let activeJobs = 0;
+
+  function evictTerminalRecords() {
+    if (records.size < maximumRetainedJobs) return;
+    for (const [key, record] of records) {
+      if (TERMINAL_STATES.has(record.state)) {
+        records.delete(key);
+        if (records.size < maximumRetainedJobs) return;
+      }
+    }
+    if (records.size >= maximumRetainedJobs) {
+      fail("EXECUTION_BUSY", "execution worker retention is full of active jobs.", { status: 429 });
+    }
+  }
+
+  function find(input, label) {
+    const normalized = reference(input, label);
+    const record = records.get(recordKey(normalized));
+    if (!record) fail("EXECUTION_JOB_NOT_FOUND", "execution job was not found.", { status: 404 });
+    return record;
+  }
+
+  async function capabilities() {
+    const workerCapabilities = await worker.capabilities();
+    const protocol = Object.freeze({
+      schemaVersion: EXECUTION_JOB_MANAGER_SCHEMA_VERSION,
+      durable: false,
+      tenantBlind: true,
+      retainedJobs: maximumRetainedJobs,
+      eventLedger: Object.freeze({ schemaVersion: EXECUTION_EVENT_SCHEMA_VERSION, hashChained: true, pruned: false }),
+      routes: Object.freeze([
+        "capabilities", "jobs.start", "jobs.status", "jobs.events", "jobs.cancel",
+        "artifacts.list", "artifacts.get",
+      ]),
+    });
+    const workerMaximum = workerCapabilities.admission?.maximumConcurrentJobs;
+    const maximumConcurrentJobs = Number.isSafeInteger(workerMaximum) && workerMaximum > 0
+      ? workerMaximum
+      : 0;
+    const state = workerCapabilities.ready !== true
+      ? (workerCapabilities.admission?.state || "blocked")
+      : activeJobs < maximumConcurrentJobs ? "ready" : "busy";
+    const coordinatorAdmission = Object.freeze({
+      state,
+      activeJobs,
+      maximumConcurrentJobs,
+      workerAdmission: workerCapabilities.admission,
+    });
+    const ready = state === "ready";
+    return Object.freeze({
+      ...workerCapabilities,
+      ready,
+      admission: coordinatorAdmission,
+      coordinatorProtocol: protocol,
+      coordinatorProtocolDigest: contractDigest(protocol),
+      coordinatorHealthDigest: contractDigest({ ready, admission: coordinatorAdmission }),
+    });
+  }
+
+  async function start(input) {
+    const request = validateExecutionJobRequest(input);
+    const key = recordKey(request);
+    const requestDigest = executionJobRequestDigest(request);
+    const existing = records.get(key);
+    if (existing) {
+      if (existing.requestDigest !== requestDigest) {
+        fail("EXECUTION_IDEMPOTENCY_CONFLICT", "execution job identity was reused with different input.", { status: 409 });
+      }
+      return publicRecord(existing, { reused: true });
+    }
+    const currentCapabilities = await worker.capabilities();
+    const raced = records.get(key);
+    if (raced) {
+      if (raced.requestDigest !== requestDigest) {
+        fail("EXECUTION_IDEMPOTENCY_CONFLICT", "execution job identity was reused with different input.", { status: 409 });
+      }
+      return publicRecord(raced, { reused: true });
+    }
+    if (currentCapabilities.ready !== true) {
+      const busy = currentCapabilities.admission?.state === "busy";
+      fail(
+        busy ? "EXECUTION_BUSY" : "EXECUTION_UNAVAILABLE",
+        busy ? "execution worker has no available slot." : "execution worker is not ready for admitted jobs.",
+        { status: busy ? 429 : 503 }
+      );
+    }
+    const maximumConcurrentJobs = currentCapabilities.admission?.maximumConcurrentJobs;
+    if (!Number.isSafeInteger(maximumConcurrentJobs) || maximumConcurrentJobs < 1 || maximumConcurrentJobs > 64) {
+      fail("EXECUTION_UNAVAILABLE", "execution worker admission contract is invalid.", { status: 503 });
+    }
+    if (activeJobs >= maximumConcurrentJobs) {
+      fail("EXECUTION_BUSY", "execution worker has no available slot.", { status: 429 });
+    }
+    evictTerminalRecords();
+    const createdAt = timestamp(now());
+    const record = {
+      jobId: request.jobId,
+      attempt: request.attempt,
+      sourceSha256: request.sourceSha256,
+      requestDigest,
+      request,
+      state: "running",
+      createdAt,
+      updatedAt: createdAt,
+      result: null,
+      errorCode: null,
+      controller: new AbortController(),
+      events: [],
+      completion: null,
+    };
+    activeJobs += 1;
+    try {
+      records.set(key, record);
+      appendEvent(record, "job.started", {
+        sourceSha256: request.sourceSha256,
+        timeoutMs: request.timeoutMs,
+        language: request.language,
+      }, now);
+    } catch (error) {
+      records.delete(key);
+      activeJobs -= 1;
+      throw error;
+    }
+    record.completion = Promise.resolve()
+      .then(() => worker.execute(request, { signal: record.controller.signal }))
+      .then((result) => {
+        const validatedResult = validateExecutionResult(result, {
+          jobId: record.jobId,
+          attempt: record.attempt,
+          sourceSha256: record.sourceSha256,
+        });
+        record.state = validatedResult.status;
+        record.result = validatedResult;
+        record.request = null;
+        appendEvent(record, "job.terminal", {
+          status: validatedResult.status,
+          resultDigest: validatedResult.resultDigest,
+          artifactIds: Object.freeze(validatedResult.artifacts.map(({ id }) => id)),
+        }, now);
+        return publicRecord(record);
+      })
+      .catch((error) => {
+        record.state = "worker_error";
+        record.errorCode = workerErrorCode(error);
+        record.request = null;
+        appendEvent(record, "job.terminal", {
+          status: "worker_error",
+          errorCode: record.errorCode,
+          artifactIds: Object.freeze([]),
+        }, now);
+        return publicRecord(record);
+      })
+      .finally(() => {
+        record.controller = null;
+        activeJobs -= 1;
+      });
+    return publicRecord(record);
+  }
+
+  function status(input) {
+    return publicRecord(find(input, "execution status request"));
+  }
+
+  function events(input) {
+    const request = exactObject(
+      input,
+      ["jobId", "attempt", "afterSeq", "afterHash"],
+      ["jobId", "attempt", "afterSeq", "afterHash"],
+      "execution events request"
+    );
+    const record = find({ jobId: request.jobId, attempt: request.attempt }, "execution events request");
+    if (!Number.isSafeInteger(request.afterSeq) || request.afterSeq < 0 || request.afterSeq > record.events.length) {
+      fail("EXECUTION_CURSOR_INVALID", "execution event cursor is invalid.", { status: 409 });
+    }
+    if (typeof request.afterHash !== "string" || !DIGEST.test(request.afterHash)) {
+      fail("EXECUTION_CURSOR_INVALID", "execution event cursor hash is invalid.", { status: 409 });
+    }
+    const expectedHash = request.afterSeq === 0
+      ? EXECUTION_ZERO_EVENT_HASH
+      : record.events[request.afterSeq - 1].eventHash;
+    if (request.afterHash !== expectedHash) {
+      fail("EXECUTION_CURSOR_CONFLICT", "execution event cursor does not match the retained ledger.", { status: 409 });
+    }
+    const replay = Object.freeze(record.events.slice(request.afterSeq));
+    const cursor = record.events.at(-1);
+    return Object.freeze({
+      schemaVersion: EXECUTION_JOB_MANAGER_SCHEMA_VERSION,
+      jobId: record.jobId,
+      attempt: record.attempt,
+      events: replay,
+      cursor: Object.freeze({
+        seq: cursor?.seq || 0,
+        hash: cursor?.eventHash || EXECUTION_ZERO_EVENT_HASH,
+      }),
+      terminal: TERMINAL_STATES.has(record.state),
+    });
+  }
+
+  function cancel(input) {
+    const record = find(input, "execution cancel request");
+    if (TERMINAL_STATES.has(record.state)) return publicRecord(record, { reused: true });
+    if (record.state !== "cancelling") {
+      record.state = "cancelling";
+      appendEvent(record, "job.cancel_requested", {}, now);
+      record.controller?.abort();
+    }
+    return publicRecord(record);
+  }
+
+  function listArtifacts(input) {
+    const record = find(input, "execution artifact list request");
+    const artifacts = Object.freeze(record.result?.status === "succeeded" ? [...record.result.artifacts] : []);
+    return Object.freeze({
+      schemaVersion: EXECUTION_JOB_MANAGER_SCHEMA_VERSION,
+      jobId: record.jobId,
+      attempt: record.attempt,
+      terminal: TERMINAL_STATES.has(record.state),
+      artifacts,
+    });
+  }
+
+  function getArtifact(input) {
+    const request = exactObject(
+      input,
+      ["jobId", "attempt", "artifactId"],
+      ["jobId", "attempt", "artifactId"],
+      "execution artifact get request"
+    );
+    if (typeof request.artifactId !== "string" || !ARTIFACT_ID.test(request.artifactId)) {
+      fail("EXECUTION_REQUEST_INVALID", "execution artifactId is invalid.");
+    }
+    const record = find({ jobId: request.jobId, attempt: request.attempt }, "execution artifact get request");
+    const artifact = record.result?.status === "succeeded"
+      ? record.result.artifacts.find(({ id }) => id === request.artifactId)
+      : null;
+    if (!artifact) fail("EXECUTION_ARTIFACT_NOT_FOUND", "execution artifact was not found.", { status: 404 });
+    return Object.freeze({
+      schemaVersion: EXECUTION_JOB_MANAGER_SCHEMA_VERSION,
+      jobId: record.jobId,
+      attempt: record.attempt,
+      artifact,
+    });
+  }
+
+  async function waitForTerminal(input) {
+    const record = find(input, "execution wait request");
+    await record.completion;
+    return publicRecord(record);
+  }
+
+  return Object.freeze({
+    kind: "aginti-execution-job-manager",
+    capabilities,
+    start,
+    status,
+    events,
+    cancel,
+    listArtifacts,
+    getArtifact,
+    waitForTerminal,
+  });
+}

package/src/execution-worker-server.js

@@ -0,0 +1,239 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+
+import { EXECUTION_RUNTIME_BUNDLE_PRODUCTION_ROOT } from "./execution-runtime-bundle.js";
+import {
+  createExecutionWorkerApiServer,
+  listenExecutionWorkerSystemdSocket,
+  validateExecutionWorkerBearerToken,
+} from "./execution-worker-api.js";
+import { createExecutionJobManager } from "./execution-worker-jobs.js";
+import {
+  attestExecutionWorkerActivationEnvironment,
+  attestExecutionWorkerCgroupBoundary,
+} from "./execution-worker-systemd-boundary.js";
+import { createPythonExecutionWorker } from "./execution-worker.js";
+
+export const EXECUTION_WORKER_SYSTEMD_UNIT = "aginti-execution-worker.service";
+export const EXECUTION_WORKER_CREDENTIAL_NAME = "execution-worker-token";
+export const EXECUTION_WORKER_CREDENTIALS_DIRECTORY = `/run/credentials/${EXECUTION_WORKER_SYSTEMD_UNIT}`;
+export const EXECUTION_WORKER_SERVER_SCHEMA_VERSION = "aginti-execution-worker-server-v1";
+
+const TOKEN_PATH = path.join(EXECUTION_WORKER_CREDENTIALS_DIRECTORY, EXECUTION_WORKER_CREDENTIAL_NAME);
+const DIGEST = /^[a-f0-9]{64}$/u;
+const MAX_CREDENTIAL_BYTES = 257;
+
+export class ExecutionWorkerServerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "ExecutionWorkerServerError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) {
+  throw new ExecutionWorkerServerError(code, message);
+}
+
+function insidePath(candidate, parent) {
+  const relative = path.relative(parent, candidate);
+  return relative !== "" && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
+}
+
+function sameFile(left, right) {
+  return Boolean(
+    left && right && left.dev === right.dev && left.ino === right.ino && left.uid === right.uid
+    && left.gid === right.gid && left.mode === right.mode && left.nlink === right.nlink
+    && left.size === right.size && left.ctimeMs === right.ctimeMs
+  );
+}
+
+function validateCredentialMetadata(directory, credential, { uid, gid }) {
+  const directoryMode = directory.mode & 0o7777;
+  const credentialMode = credential.mode & 0o7777;
+  const trustedUid = (value) => value === 0 || value === uid;
+  const trustedGid = (value) => value === 0 || value === gid;
+  if (!directory.isDirectory() || directory.isSymbolicLink() || !trustedUid(directory.uid) || !trustedGid(directory.gid)
+      || (directoryMode !== 0o500 && directoryMode !== 0o550)) {
+    fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential directory is not trusted.");
+  }
+  if (!credential.isFile() || credential.isSymbolicLink() || !trustedUid(credential.uid) || !trustedGid(credential.gid)
+      || (credentialMode !== 0o400 && credentialMode !== 0o440) || credential.nlink !== 1
+      || credential.size < 32 || credential.size > MAX_CREDENTIAL_BYTES) {
+    fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential file is not trusted.");
+  }
+}
+
+async function loadCredential(filesystem, processObject) {
+  let directoryBefore;
+  let credentialBefore;
+  let handle;
+  try {
+    const [directoryReal, credentialReal] = await Promise.all([
+      filesystem.realpath(EXECUTION_WORKER_CREDENTIALS_DIRECTORY),
+      filesystem.realpath(TOKEN_PATH),
+    ]);
+    if (directoryReal !== EXECUTION_WORKER_CREDENTIALS_DIRECTORY || credentialReal !== TOKEN_PATH) {
+      fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential path traverses a symbolic link.");
+    }
+    [directoryBefore, credentialBefore] = await Promise.all([
+      filesystem.lstat(EXECUTION_WORKER_CREDENTIALS_DIRECTORY),
+      filesystem.lstat(TOKEN_PATH),
+    ]);
+    const uid = processObject.geteuid?.() ?? processObject.getuid?.();
+    const gid = processObject.getegid?.() ?? processObject.getgid?.();
+    if (!Number.isSafeInteger(uid) || uid < 0 || !Number.isSafeInteger(gid) || gid < 0) {
+      fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential process identity is unavailable.");
+    }
+    validateCredentialMetadata(directoryBefore, credentialBefore, { uid, gid });
+    try {
+      await filesystem.access(TOKEN_PATH, fsConstants.W_OK);
+      fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential is writable by the service.");
+    } catch (error) {
+      if (error instanceof ExecutionWorkerServerError) throw error;
+      if (!["EACCES", "EPERM", "EROFS"].includes(error?.code)) {
+        fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential read-only state is unproven.");
+      }
+    }
+    handle = await filesystem.open(
+      TOKEN_PATH,
+      fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | (fsConstants.O_CLOEXEC || 0) | (fsConstants.O_NONBLOCK || 0)
+    );
+    const openedBefore = await handle.stat();
+    if (!sameFile(credentialBefore, openedBefore)) {
+      fail("EXECUTION_WORKER_CREDENTIAL_CHANGED", "execution worker credential changed before read.");
+    }
+    const raw = await handle.readFile("utf8");
+    const openedAfter = await handle.stat();
+    const [directoryAfter, credentialAfter, directoryRealAfter, credentialRealAfter] = await Promise.all([
+      filesystem.lstat(EXECUTION_WORKER_CREDENTIALS_DIRECTORY),
+      filesystem.lstat(TOKEN_PATH),
+      filesystem.realpath(EXECUTION_WORKER_CREDENTIALS_DIRECTORY),
+      filesystem.realpath(TOKEN_PATH),
+    ]);
+    if (!sameFile(openedBefore, openedAfter) || !sameFile(openedAfter, credentialAfter)
+        || !sameFile(directoryBefore, directoryAfter)
+        || directoryRealAfter !== EXECUTION_WORKER_CREDENTIALS_DIRECTORY || credentialRealAfter !== TOKEN_PATH
+        || Buffer.byteLength(raw, "utf8") !== openedAfter.size) {
+      fail("EXECUTION_WORKER_CREDENTIAL_CHANGED", "execution worker credential changed during read.");
+    }
+    if (raw.includes("\u0000") || raw.includes("\r")) {
+      fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential framing is invalid.");
+    }
+    const token = raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    if (!token || token.includes("\n")) {
+      fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential must contain exactly one line.");
+    }
+    return validateExecutionWorkerBearerToken(token);
+  } catch (error) {
+    if (error instanceof ExecutionWorkerServerError) throw error;
+    fail("EXECUTION_WORKER_CREDENTIAL_INVALID", "execution worker credential could not be read safely.");
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function validateEnvironment(environment) {
+  if (!environment || typeof environment !== "object") {
+    throw new TypeError("environment must be an object");
+  }
+  if (environment.CREDENTIALS_DIRECTORY !== EXECUTION_WORKER_CREDENTIALS_DIRECTORY) {
+    fail("EXECUTION_WORKER_CONFIG_INVALID", "execution worker requires its exact systemd credential directory.");
+  }
+  const runtimeBundleDirectory = environment.AGINTI_EXECUTION_RUNTIME_BUNDLE_DIRECTORY;
+  if (typeof runtimeBundleDirectory !== "string" || !path.isAbsolute(runtimeBundleDirectory)
+      || path.normalize(runtimeBundleDirectory) !== runtimeBundleDirectory
+      || !insidePath(runtimeBundleDirectory, EXECUTION_RUNTIME_BUNDLE_PRODUCTION_ROOT)) {
+    fail("EXECUTION_WORKER_CONFIG_INVALID", "execution worker runtime bundle directory is invalid.");
+  }
+  const runtimeBundleRootDigest = environment.AGINTI_EXECUTION_RUNTIME_BUNDLE_DIGEST;
+  if (typeof runtimeBundleRootDigest !== "string" || !DIGEST.test(runtimeBundleRootDigest)) {
+    fail("EXECUTION_WORKER_CONFIG_INVALID", "execution worker runtime bundle digest is invalid.");
+  }
+  if (environment.AGINTI_EXECUTION_TEST_BYPASS !== undefined) {
+    fail("EXECUTION_WORKER_CONFIG_INVALID", "execution worker test bypass must not exist in production.");
+  }
+  const workerId = `worker_${crypto.createHash("sha256")
+    .update(`${EXECUTION_WORKER_SERVER_SCHEMA_VERSION}:${runtimeBundleRootDigest}`)
+    .digest("base64url")}`;
+  return Object.freeze({ runtimeBundleDirectory, runtimeBundleRootDigest, workerId });
+}
+
+export async function loadExecutionWorkerServerConfig({
+  filesystem = fs,
+  environment = process.env,
+  processObject = process,
+} = {}) {
+  const config = validateEnvironment(environment);
+  if (!processObject || typeof processObject !== "object") throw new TypeError("processObject must be an object");
+  const bearerToken = await loadCredential(filesystem, processObject);
+  return Object.freeze({
+    schemaVersion: EXECUTION_WORKER_SERVER_SCHEMA_VERSION,
+    ...config,
+    bearerToken,
+  });
+}
+
+export async function createProductionExecutionWorkerServer({
+  config,
+  serverFactory,
+  listen = true,
+} = {}) {
+  if (!config || config.schemaVersion !== EXECUTION_WORKER_SERVER_SCHEMA_VERSION) {
+    throw new TypeError("config must be a validated execution worker server config");
+  }
+  if (typeof listen !== "boolean") throw new TypeError("listen must be a boolean");
+  if (listen && ((process.geteuid?.() ?? process.getuid?.()) === 0)) {
+    fail("EXECUTION_WORKER_PROCESS_IDENTITY_INVALID", "execution worker must run as its dedicated non-root service user.");
+  }
+  const boundary = listen
+    ? Object.freeze({
+        activation: attestExecutionWorkerActivationEnvironment(),
+        containment: await attestExecutionWorkerCgroupBoundary(),
+      })
+    : null;
+  const worker = createPythonExecutionWorker({
+    workerId: config.workerId,
+    runtimeBundleDirectory: config.runtimeBundleDirectory,
+    expectedRuntimeBundleRootDigest: config.runtimeBundleRootDigest,
+    ...(boundary
+      ? { containmentProbeImpl: async () => boundary.containment }
+      : {}),
+  });
+  const manager = createExecutionJobManager({ worker });
+  const server = createExecutionWorkerApiServer({
+    manager,
+    bearerToken: config.bearerToken,
+    ...(serverFactory === undefined ? {} : { serverFactory }),
+  });
+  const address = listen ? await listenExecutionWorkerSystemdSocket(server) : null;
+  return Object.freeze({
+    schemaVersion: EXECUTION_WORKER_SERVER_SCHEMA_VERSION,
+    worker,
+    manager,
+    server,
+    address,
+    boundary,
+  });
+}
+
+export function installExecutionWorkerShutdownHandlers(server, { processObject = process } = {}) {
+  if (!server || typeof server.close !== "function") throw new TypeError("server must provide close");
+  if (!processObject || typeof processObject.once !== "function") throw new TypeError("processObject must provide once");
+  let closing = false;
+  const shutdown = () => {
+    if (closing) return;
+    closing = true;
+    const forced = setTimeout(() => processObject.exit?.(1), 5_000);
+    forced.unref?.();
+    server.close(() => {
+      clearTimeout(forced);
+      processObject.exitCode = 0;
+    });
+  };
+  processObject.once("SIGTERM", shutdown);
+  processObject.once("SIGINT", shutdown);
+  return Object.freeze({ shutdown });
+}