quixos-protocol/src/execution-world/candidate.ts

import { open, lstat } from "node:fs/promises";
import { constants } from "node:fs";
import { join } from "node:path";
import { hexDigest, ExecutionPlanError, type ExecutionPlan } from "./plan.js";
import { loadExecutionInstallation, type PackageInstallationSelection } from "./installation.js";
const rootPattern = /^\/nix\/store\/[a-z0-9]{32}-[^/\s]+$/;
async function readJson(root: string, file: string): Promise<any> {
  const handle = await open(join(root, file), constants.O_RDONLY | constants.O_NOFOLLOW);
  try {
    const metadata = await handle.stat();
    if (!metadata.isFile() || metadata.size > 32 * 1024 * 1024) throw Error(`Invalid checked candidate file: ${file}`);
    return JSON.parse(await handle.readFile("utf8"));
  } finally {
    await handle.close();
  }
}
/** Load the checked Nix output, preserving its original compilation and provenance.
 * The selected toolchain validates generated code during the build. This loader
 * checks stored identities and artifact/runtime contracts, never recompiles the
 * historical candidate with whichever compiler happens to run the host. */
export async function loadCheckedInstallationCandidate(
  root: string,
  selections: Readonly<Record<string, PackageInstallationSelection>> = {},
) {
  if (!rootPattern.test(root) || !(await lstat(root)).isDirectory())
    throw Error("Candidate must be an immutable Nix output directory");
  const [candidate, plan, artifacts, source, entryRequest, kernel, queries] = await Promise.all([
    readJson(root, "candidate.json"),
    readJson(root, "execution-plan.json"),
    readJson(root, "execution-artifacts.json"),
    readJson(root, "source.json"),
    readJson(root, "entry.json"),
    readJson(root, "kernel.json"),
    readJson(root, "queries.json"),
  ]);
  const { executionContracts: _legacyContracts, ...workspace } = candidate;
  if (
    plan?.definition?.codec !== "camino-execution-plan-v1" ||
    hexDigest(plan.definition) !== plan.digest ||
    hexDigest(workspace) !== hexDigest(plan.definition.workspace)
  )
    throw new ExecutionPlanError(
      "CANDIDATE_PLAN_MISMATCH",
      root,
      "Stored plan must match its digest and exact workspace source contract",
    );
  if (
    source.kind !== "workspace" ||
    source.commit !== plan.definition.workspace.sourceRootCommit ||
    typeof source.repository !== "string"
  )
    throw new ExecutionPlanError("CANDIDATE_SOURCE_MISMATCH", root, "Expected exact workspace source provenance");
  const repository = new URL(source.repository);
  if (
    !["https:", "ssh:"].includes(repository.protocol) ||
    repository.username ||
    repository.password ||
    repository.hash ||
    repository.search
  )
    throw new ExecutionPlanError("CANDIDATE_SOURCE_INVALID", root, "Expected a source URL without credentials");
  if (
    artifacts.codec !== "camino-checked-execution-v2" ||
    typeof artifacts.generator !== "string" ||
    !/^[0-9a-f]{64}$/.test(artifacts.generator) ||
    !artifacts.roots ||
    typeof artifacts.roots !== "object" ||
    Array.isArray(artifacts.roots)
  )
    throw new ExecutionPlanError("CANDIDATE_ARTIFACTS_INVALID", root, "Expected checked package roots");
  for (const entry of Object.values(artifacts.roots))
    if (typeof entry !== "string" || !rootPattern.test(entry))
      throw new ExecutionPlanError(
        "CANDIDATE_ARTIFACTS_INVALID",
        root,
        "Package artifacts must be immutable Nix roots",
      );
  const installation = await loadExecutionInstallation(plan, artifacts.roots, selections);
  const entry = compileWorkspaceEntry(plan, entryRequest);
  for (const [name, program, codec] of [
    ["kernel", kernel, "camino-kernel-program-v1"],
    ["queries", queries, "camino-query-program-v1"],
  ] as const)
    if (program?.codec !== codec || program.plan !== plan.digest || hexDigest(program) !== artifacts.programs?.[name])
      throw new ExecutionPlanError(
        "CANDIDATE_PROGRAM_MISMATCH",
        name,
        "Stored interpreter input must match the checked build and plan",
      );
  const provenance = {
    workspaceRevision: workspace.id as string,
    source: { repository: source.repository as string, commit: source.commit as string },
    generator: artifacts.generator as string,
    packages: (plan as ExecutionPlan).definition.packages.map((pkg) => ({
      revision: pkg.revision,
      source: pkg.source,
    })),
  };
  const reference = {
    root,
    digest: hexDigest({
      plan: plan.digest,
      world: installation.world,
      provenance,
      roots: artifacts.roots,
      entry,
      programs: artifacts.programs,
    }),
  };
  return {
    reference,
    workspace: plan.definition.workspace.workspaceId,
    world: installation.world,
    plan: plan.digest,
    provenance,
    entry,
    kernel,
    queries,
    installation,
    executionPlan: plan as ExecutionPlan,
  };
}

export function compileWorkspaceEntry(plan: ExecutionPlan, entryRequest: unknown): { operation: string } | null {
  let entry: { operation: string } | null = null;
  if (entryRequest !== null) {
    if (
      typeof entryRequest !== "object" ||
      Array.isArray(entryRequest) ||
      Object.keys(entryRequest).sort().join(",") !== "atom,interface,operation"
    )
      throw new ExecutionPlanError(
        "INVALID_ENTRY_FACTORY",
        "entry",
        "Entry declaration must name atom, interface and operation identities",
      );
    const operation = plan.definition.operations.find(
      (op) =>
        op.atomId === (entryRequest as Record<string, unknown>).atom &&
        op.interfaceRevisionId === (entryRequest as Record<string, unknown>).interface &&
        op.operationId === (entryRequest as Record<string, unknown>).operation,
    );
    if (
      !operation ||
      operation.scope !== "class" ||
      operation.execution.kind !== "transaction" ||
      operation.input.kind !== "builtin" ||
      operation.input.name !== "unit" ||
      operation.output.kind !== "object-ref"
    )
      throw new ExecutionPlanError(
        "INVALID_ENTRY_FACTORY",
        "entry",
        "Entry must be a checked unit-input class transaction returning one object reference",
      );
    entry = { operation: operation.key };
  }
  return entry;
}