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 type { WorkspaceRevision } from "../capability-model/types.js";
import { compileExecutionPlan, hexDigest, ExecutionPlanError, type ExecutionPlan } from "./plan.js";
import { loadExecutionInstallation, type PackageInstallationSelection } from "./installation.js";
import { compileKernelProgram } from "./kernel.js";
import { compileQueryProgram } from "./queries.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();
  }
}
/** Revalidate the normal checked-candidate output. This is the shared artifact
 * loader, not a second managed-only executable manifest or an activation grant. */
export async function loadCheckedInstallationCandidate(
  root: string,
  generator: 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, recordedPlan, artifacts, source, entryRequest] = 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"),
  ]);
  const { executionContracts: _legacyContracts, ...workspace } = candidate;
  const plan = compileExecutionPlan(workspace as WorkspaceRevision);
  if (hexDigest(plan) !== hexDigest(recordedPlan))
    throw new ExecutionPlanError(
      "CANDIDATE_PLAN_MISMATCH",
      root,
      "Recompiled source contract differs from the stored plan",
    );
  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-v1" ||
    !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, generator, selections);
  const entry = compileWorkspaceEntry(plan, entryRequest);
  const kernel = compileKernelProgram(plan),
    queries = compileQueryProgram(plan);
  // The isolated runner and managed host consume the same compiled programs.
  for (const [file, expected] of [
    ["kernel.json", kernel],
    ["queries.json", queries],
  ] as const)
    if (hexDigest(await readJson(root, file)) !== hexDigest(expected))
      throw new ExecutionPlanError(
        "CANDIDATE_PROGRAM_MISMATCH",
        file,
        "Stored interpreter input differs from checked compilation",
      );
  const provenance = {
    workspaceRevision: workspace.id as string,
    source: { repository: source.repository as string, commit: source.commit as string },
    generator,
    packages: plan.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 }),
  };
  return {
    reference,
    workspace: plan.definition.workspace.workspaceId,
    world: installation.world,
    plan: plan.digest,
    provenance,
    entry,
    kernel,
    queries,
    installation,
    executionPlan: plan,
  };
}

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;
}