chainlesschain 0.165.2 → 0.165.4

package/src/lib/execution-location-result-apply.js

@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { WORKSPACE_TRANSACTION_COVERAGE } from "./process-execution-broker/workspace-transaction.js";
+import { canonicalJson } from "./scheduler-kernel/contract.js";
+
+const MAX_GIT_OUTPUT_BYTES = 16 * 1024;
+const MAX_APPLY_OUTPUT_BYTES = 1024 * 1024;
+const PROCESS_TREE_BOUNDARY = "process-tree";
+
+function digest(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(domain, "utf8")
+    .update(canonicalJson(value, "executionLocationResultApply"), "utf8")
+    .digest("hex")}`;
+}
+
+function bytesLength(value) {
+  if (value == null) return 0;
+  return Buffer.isBuffer(value)
+    ? value.byteLength
+    : Buffer.byteLength(String(value), "utf8");
+}
+
+function runGit(broker, args, options = {}) {
+  if (!broker || typeof broker.spawnSync !== "function") {
+    throw new TypeError("result apply requires ProcessExecutionBroker");
+  }
+  const result = broker.spawnSync("git", args, {
+    cwd: options.cwd,
+    shell: false,
+    detached: false,
+    policy: "allow",
+    origin: options.origin || "session:result-apply",
+    scope: "session",
+    encoding: "buffer",
+    maxBuffer: options.maxBuffer || MAX_APPLY_OUTPUT_BYTES,
+    ...(options.input ? { input: options.input } : {}),
+    ...(options.requiredBoundaries
+      ? { requiredBoundaries: options.requiredBoundaries }
+      : {}),
+  });
+  return Object.freeze({
+    exitCode: Number.isInteger(result?.status) ? result.status : null,
+    signal: typeof result?.signal === "string" ? result.signal : null,
+    stdoutBytes: bytesLength(result?.stdout),
+    stderrBytes: bytesLength(result?.stderr),
+    errorCode: result?.error?.code ? String(result.error.code) : null,
+    stdout: result?.stdout,
+  });
+}
+
+function strictGitText(result, label, maxBytes) {
+  if (result.exitCode !== 0 || result.errorCode !== null) {
+    throw new Error(`${label} failed`);
+  }
+  const bytes = Buffer.isBuffer(result.stdout)
+    ? result.stdout
+    : Buffer.from(result.stdout || "");
+  if (bytes.byteLength <= 0 || bytes.byteLength > maxBytes) {
+    throw new Error(`${label} output is invalid`);
+  }
+  return bytes.toString("utf8").trim();
+}
+
+function canonicalDirectory(value) {
+  const requested = path.resolve(value);
+  const resolved = (fs.realpathSync.native || fs.realpathSync)(requested);
+  const entry = fs.lstatSync(resolved);
+  if (entry.isSymbolicLink() || !entry.isDirectory()) {
+    throw new Error("result apply workspace root is invalid");
+  }
+  return path.resolve(resolved);
+}
+
+function samePath(left, right, platform = process.platform) {
+  const normalizedLeft = path.resolve(left);
+  const normalizedRight = path.resolve(right);
+  return platform === "win32"
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight;
+}
+
+export function verifyExecutionLocationResultApplySourceGit(
+  sessionAuthority,
+  options = {},
+) {
+  const broker = options.broker;
+  const expectedRoot = sessionAuthority?.binding?.source?.git?.root;
+  const expectedCommit = String(
+    sessionAuthority?.binding?.source?.git?.commit || "",
+  ).toLowerCase();
+  if (
+    typeof expectedRoot !== "string" ||
+    expectedRoot.length === 0 ||
+    !/^[a-f0-9]{40,64}$/u.test(expectedCommit)
+  ) {
+    throw new Error(
+      "session has no exact source Git identity for result apply",
+    );
+  }
+  const requestedRoot = canonicalDirectory(
+    options.workspaceRoot || expectedRoot,
+  );
+  const liveRootText = strictGitText(
+    runGit(broker, ["rev-parse", "--show-toplevel"], {
+      cwd: requestedRoot,
+      origin: "session:result-apply-git-root",
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+    }),
+    "result apply Git root readback",
+    MAX_GIT_OUTPUT_BYTES,
+  );
+  const liveRoot = canonicalDirectory(liveRootText);
+  const canonicalExpectedRoot = canonicalDirectory(expectedRoot);
+  const liveCommit = strictGitText(
+    runGit(broker, ["rev-parse", "--verify", "HEAD"], {
+      cwd: liveRoot,
+      origin: "session:result-apply-git-head",
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+    }),
+    "result apply Git HEAD readback",
+    128,
+  ).toLowerCase();
+  if (
+    !samePath(requestedRoot, liveRoot, options.platform) ||
+    !samePath(canonicalExpectedRoot, liveRoot, options.platform) ||
+    liveCommit !== expectedCommit
+  ) {
+    throw new Error("live source Git identity changed before result apply");
+  }
+  return Object.freeze({
+    workspaceRoot: liveRoot,
+    sourceGit: Object.freeze({
+      rootDigest: digest(
+        "chainlesschain.execution-location.result-apply-git-root.v1\0",
+        { canonicalRoot: liveRoot },
+      ),
+      commit: liveCommit,
+    }),
+  });
+}
+
+function transactionId(sessionId, applyId) {
+  return `result-apply-${createHash("sha256")
+    .update(String(sessionId), "utf8")
+    .update("\0", "utf8")
+    .update(String(applyId), "utf8")
+    .digest("hex")
+    .slice(0, 32)}`;
+}
+
+function preparedTransaction(transaction) {
+  const state = transaction.snapshot();
+  return Object.freeze({
+    id: transaction.id,
+    checkpointId: transaction.checkpointId,
+    checkpointDigest: state.checkpoint?.digest,
+    coverage: state.requestedCoverage || WORKSPACE_TRANSACTION_COVERAGE.PARTIAL,
+    externalSideEffects: false,
+  });
+}
+
+export function terminalExecutionLocationResultApplyTransaction(stateInput) {
+  const state = stateInput?.snapshot ? stateInput.snapshot() : stateInput;
+  const evidence = state?.evidence;
+  if (
+    !state ||
+    !evidence ||
+    !["committed", "rolled_back"].includes(state.state) ||
+    !["committed", "rolled_back"].includes(evidence.outcome)
+  ) {
+    throw new Error("result apply workspace transaction is not terminal");
+  }
+  return Object.freeze({
+    id: state.id,
+    checkpointId: state.checkpointId,
+    checkpointDigest: evidence.checkpointDigest,
+    evidenceDigest: evidence.evidenceDigest,
+    writeManifestDigest: evidence.writeManifestDigest,
+    coverage: evidence.coverage,
+    fileCoverage: evidence.fileCoverage,
+    externalSideEffects: evidence.externalSideEffects,
+    uncoveredPaths: Object.freeze(
+      [...(evidence.uncoveredPaths || [])].sort((left, right) =>
+        left.localeCompare(right),
+      ),
+    ),
+  });
+}
+
+function rollbackResult(
+  transaction,
+  stage,
+  processResult,
+  reason,
+  error = null,
+) {
+  const evidence = transaction.rollback({ reason });
+  return Object.freeze({
+    ok: false,
+    outcome: "rolled_back",
+    stage,
+    transaction: terminalExecutionLocationResultApplyTransaction({
+      ...transaction.snapshot(),
+      evidence,
+    }),
+    process: processResult
+      ? Object.freeze({
+          exitCode: processResult.exitCode,
+          signal: processResult.signal,
+          stdoutBytes: processResult.stdoutBytes,
+          stderrBytes: processResult.stderrBytes,
+          errorCode: processResult.errorCode,
+        })
+      : null,
+    error,
+  });
+}
+
+export function executeControlledExecutionLocationResultApply(input = {}) {
+  const broker = input.broker;
+  if (
+    !broker ||
+    typeof broker.beginWorkspaceTransaction !== "function" ||
+    typeof broker.spawnSync !== "function"
+  ) {
+    throw new TypeError("result apply requires ProcessExecutionBroker");
+  }
+  const diffBytes = Buffer.isBuffer(input.diffBytes)
+    ? Buffer.from(input.diffBytes)
+    : Buffer.from(input.diffBytes || "");
+  const transaction = broker.beginWorkspaceTransaction({
+    id: transactionId(input.sessionId, input.applyId),
+    workspaceRoot: input.workspaceRoot,
+    runId: `session-result-apply-${input.applyId}`,
+    taskKey: `result-apply:${input.applyId}`,
+    coverageTarget: WORKSPACE_TRANSACTION_COVERAGE.PARTIAL,
+    externalSideEffects: false,
+    writerIsolation: "exclusive-workspace",
+    exclusions: [".git"],
+    ...(input.stateDir ? { stateDir: path.resolve(input.stateDir) } : {}),
+  });
+  const prepared = preparedTransaction(transaction);
+  try {
+    input.onPrepared?.(prepared);
+  } catch (error) {
+    return rollbackResult(
+      transaction,
+      "reservation",
+      null,
+      "result apply reservation failed before process execution",
+      error,
+    );
+  }
+
+  let checked;
+  try {
+    checked = runGit(
+      broker,
+      ["apply", "--check", "--whitespace=error-all", "-"],
+      {
+        cwd: input.workspaceRoot,
+        input: diffBytes,
+        requiredBoundaries: [PROCESS_TREE_BOUNDARY],
+      },
+    );
+  } catch (error) {
+    return rollbackResult(
+      transaction,
+      "check",
+      null,
+      "git apply check could not complete",
+      error,
+    );
+  }
+  if (checked.exitCode !== 0 || checked.errorCode !== null) {
+    return rollbackResult(
+      transaction,
+      "check",
+      checked,
+      "git apply check rejected the reviewed diff",
+    );
+  }
+
+  let applied;
+  try {
+    applied = runGit(broker, ["apply", "--whitespace=error-all", "-"], {
+      cwd: input.workspaceRoot,
+      input: diffBytes,
+      requiredBoundaries: [PROCESS_TREE_BOUNDARY],
+    });
+  } catch (error) {
+    return rollbackResult(
+      transaction,
+      "apply",
+      null,
+      "git apply could not complete",
+      error,
+    );
+  }
+  if (applied.exitCode !== 0 || applied.errorCode !== null) {
+    return rollbackResult(
+      transaction,
+      "apply",
+      applied,
+      "git apply rejected the reviewed diff",
+    );
+  }
+
+  try {
+    const evidence = transaction.accept();
+    return Object.freeze({
+      ok: true,
+      outcome: "applied",
+      stage: "complete",
+      transaction: terminalExecutionLocationResultApplyTransaction({
+        ...transaction.snapshot(),
+        evidence,
+      }),
+      process: Object.freeze({
+        exitCode: applied.exitCode,
+        signal: applied.signal,
+        stdoutBytes: checked.stdoutBytes + applied.stdoutBytes,
+        stderrBytes: checked.stderrBytes + applied.stderrBytes,
+        errorCode: null,
+      }),
+      error: null,
+    });
+  } catch (error) {
+    return rollbackResult(
+      transaction,
+      "commit",
+      applied,
+      "result apply transaction commit failed",
+      error,
+    );
+  }
+}

package/src/lib/execution-location-result-artifact.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { ArtifactStore, publicArtifactMetadata } from "./artifact-store.js";
+import { canonicalJson } from "./scheduler-kernel/contract.js";
+
+export const EXECUTION_LOCATION_RESULT_ARTIFACT_IMPORT_SCHEMA =
+  "cc-execution-location-result-artifact-import/v1";
+export const EXECUTION_LOCATION_RESULT_ARTIFACT_LINEAGE_SCHEMA =
+  "cc-execution-location-result-artifact-lineage/v1";
+
+const SHA256_RE = /^sha256:[a-f0-9]{64}$/u;
+const AUTHORITY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,255}$/u;
+
+function digest(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(domain, "utf8")
+    .update(canonicalJson(value, "executionLocationResultArtifact"), "utf8")
+    .digest("hex")}`;
+}
+
+function bytesDigest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function exactObject(value, fields, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  const actual = Object.keys(value).sort();
+  const expected = [...fields].sort();
+  if (
+    actual.length !== expected.length ||
+    actual.some((field, index) => field !== expected[index])
+  ) {
+    throw new TypeError(`${label} has an invalid schema`);
+  }
+  return value;
+}
+
+function normalizeLineage(input) {
+  const value = exactObject(
+    input,
+    [
+      "schema",
+      "sessionId",
+      "requestId",
+      "reviewDigest",
+      "item",
+      "kind",
+      "mediaType",
+      "byteLength",
+      "sourceDigest",
+    ],
+    "execution-location result artifact lineage",
+  );
+  const sessionId = String(value.sessionId || "");
+  const requestId = String(value.requestId || "");
+  const reviewDigest = String(value.reviewDigest || "");
+  const item = String(value.item || "");
+  const kind = String(value.kind || "");
+  const mediaType = String(value.mediaType || "");
+  const sourceDigest = String(value.sourceDigest || "");
+  const byteLength = Number(value.byteLength);
+  const selectorMatches =
+    (kind === "summary" && item === "summary") ||
+    (kind === "diff" && item === "diff") ||
+    ((kind === "artifact" || kind === "evidence") &&
+      item === `${kind}:${sourceDigest}`);
+  if (
+    value.schema !== EXECUTION_LOCATION_RESULT_ARTIFACT_LINEAGE_SCHEMA ||
+    !AUTHORITY_ID_RE.test(sessionId) ||
+    !AUTHORITY_ID_RE.test(requestId) ||
+    !SHA256_RE.test(reviewDigest) ||
+    !SHA256_RE.test(sourceDigest) ||
+    !selectorMatches ||
+    mediaType.length < 1 ||
+    mediaType.length > 256 ||
+    Array.from(mediaType).some((character) => {
+      const codePoint = character.codePointAt(0);
+      return codePoint <= 0x1f || codePoint === 0x7f;
+    }) ||
+    !Number.isSafeInteger(byteLength) ||
+    byteLength < 0
+  ) {
+    throw new TypeError(
+      "execution-location result artifact lineage is invalid",
+    );
+  }
+  return Object.freeze({
+    schema: value.schema,
+    sessionId,
+    requestId,
+    reviewDigest,
+    item,
+    kind,
+    mediaType,
+    byteLength,
+    sourceDigest,
+  });
+}
+
+function artifactKind(kind) {
+  if (kind === "summary") return "report";
+  if (kind === "diff") return "patch";
+  if (kind === "evidence") return "data";
+  return "other";
+}
+
+function extensionFor(lineage) {
+  if (lineage.kind === "diff") return ".patch";
+  const exact = {
+    "application/json": ".json",
+    "image/gif": ".gif",
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "text/csv": ".csv",
+    "text/html": ".html",
+    "text/markdown": ".md",
+    "text/plain": ".txt",
+  };
+  return exact[lineage.mediaType.toLowerCase()] || ".bin";
+}
+
+function expectedArtifactMetadata(lineage, importDigest) {
+  const suffix = importDigest.slice("sha256:".length, "sha256:".length + 16);
+  return Object.freeze({
+    title: `Returned ${lineage.kind} ${suffix}`,
+    kind: artifactKind(lineage.kind),
+    mime: lineage.mediaType,
+    size: lineage.byteLength,
+    sha256: lineage.sourceDigest.slice("sha256:".length),
+    sessionId: lineage.sessionId,
+    immutable: true,
+    recordDigest: importDigest,
+    fileName: `execution-result-${lineage.kind}-${suffix}${extensionFor(lineage)}`,
+  });
+}
+
+function createReceipt(entry, lineage, importDigest) {
+  const metadata = publicArtifactMetadata(entry);
+  const artifact = { ...metadata };
+  delete artifact.lineage;
+  const material = {
+    schema: EXECUTION_LOCATION_RESULT_ARTIFACT_IMPORT_SCHEMA,
+    importDigest,
+    source: lineage,
+    artifact,
+    retention: "artifact-store-ttl-explicit-delete-not-worm",
+  };
+  return Object.freeze({
+    ...material,
+    receiptDigest: digest(
+      "chainlesschain.execution-location.result-artifact-import-receipt.v1\0",
+      material,
+    ),
+  });
+}
+
+export function readExecutionLocationResultArtifactImport(
+  importDigestInput,
+  options = {},
+) {
+  const importDigest = String(importDigestInput || "");
+  if (!SHA256_RE.test(importDigest)) {
+    throw new TypeError(
+      "execution-location result artifact import digest is invalid",
+    );
+  }
+  const store = options.artifactStore || new ArtifactStore();
+  const matches = store
+    .list()
+    .filter((entry) => entry.recordDigest === importDigest);
+  if (matches.length !== 1) {
+    throw new Error(
+      matches.length === 0
+        ? "execution-location result artifact import was not found"
+        : "execution-location result artifact import is ambiguous",
+    );
+  }
+  const entry = matches[0];
+  const lineage = normalizeLineage(entry.lineage);
+  const expectedImportDigest = digest(
+    "chainlesschain.execution-location.result-artifact-import.v1\0",
+    lineage,
+  );
+  const expected = expectedArtifactMetadata(lineage, expectedImportDigest);
+  const integrity = store.verifyIntegrity(entry);
+  if (
+    expectedImportDigest !== importDigest ||
+    entry.title !== expected.title ||
+    entry.kind !== expected.kind ||
+    entry.mime !== expected.mime ||
+    entry.size !== expected.size ||
+    entry.sha256 !== expected.sha256 ||
+    entry.sessionId !== expected.sessionId ||
+    entry.immutable !== true ||
+    entry.recordDigest !== expected.recordDigest ||
+    integrity.ok !== true ||
+    integrity.actualSha256 !== expected.sha256
+  ) {
+    throw new Error(
+      "execution-location result ArtifactStore readback does not match import authority",
+    );
+  }
+  return Object.freeze({
+    receipt: createReceipt(entry, lineage, importDigest),
+    entry,
+    integrity: Object.freeze({ ...integrity }),
+  });
+}
+
+export function importExecutionLocationResultArtifact(preview, options = {}) {
+  const bytes = Buffer.isBuffer(preview?.bytes)
+    ? Buffer.from(preview.bytes)
+    : null;
+  const lineage = normalizeLineage({
+    schema: EXECUTION_LOCATION_RESULT_ARTIFACT_LINEAGE_SCHEMA,
+    sessionId: preview?.sessionId,
+    requestId: preview?.requestId,
+    reviewDigest: preview?.reviewDigest,
+    item: preview?.item,
+    kind: preview?.kind,
+    mediaType: preview?.mediaType,
+    byteLength: preview?.byteLength,
+    sourceDigest: preview?.digest,
+  });
+  if (
+    bytes === null ||
+    bytes.byteLength !== lineage.byteLength ||
+    bytesDigest(bytes) !== lineage.sourceDigest
+  ) {
+    throw new Error(
+      "execution-location result content does not match import authority",
+    );
+  }
+  const importDigest = digest(
+    "chainlesschain.execution-location.result-artifact-import.v1\0",
+    lineage,
+  );
+  const expected = expectedArtifactMetadata(lineage, importDigest);
+  const store = options.artifactStore || new ArtifactStore();
+  if (typeof store.publishDataOnce !== "function") {
+    throw new Error("ArtifactStore idempotent import is unavailable");
+  }
+  const publication = store.publishDataOnce({
+    data: bytes,
+    fileName: expected.fileName,
+    title: expected.title,
+    kind: expected.kind,
+    mime: expected.mime,
+    sessionId: expected.sessionId,
+    immutable: true,
+    recordDigest: importDigest,
+    lineage,
+  });
+  const readback = readExecutionLocationResultArtifactImport(importDigest, {
+    artifactStore: store,
+  });
+  if (
+    canonicalJson(readback.entry.lineage, "resultArtifactStoredLineage") !==
+    canonicalJson(lineage, "resultArtifactExpectedLineage")
+  ) {
+    throw new Error(
+      "execution-location result ArtifactStore lineage does not match reviewed item",
+    );
+  }
+  return Object.freeze({
+    ...readback.receipt,
+    imported: publication.published === true,
+  });
+}