@abelxiaoxing/cadence 1.3.0 → 1.4.0

package/src/verification-environment.ts

@@ -0,0 +1,213 @@
+import {
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import {
+  type StructuredVerificationContract,
+  VERIFICATION_CONFIGURATION_PATHS,
+} from "./contracts.ts";
+import type { IsolationMount } from "./isolation-backend.ts";
+import {
+  resolveVerificationRunner,
+  type VerificationRunnerBinding,
+  validateVerificationAdapterCapability,
+  verificationRunnerFiles,
+} from "./verification-capability.ts";
+import { runWorkspaceIo } from "./workspace-io.ts";
+
+export async function captureVerificationEnvironmentIdentity(
+  dependencyOwner: string,
+  verifications: readonly StructuredVerificationContract[],
+  signal?: AbortSignal,
+): Promise<string> {
+  const roots = [path.join(dependencyOwner, "node_modules")];
+  const node = resolveVerificationRunner("node");
+  if (node) roots.push(realpathSync(node.executablePath));
+  for (const verification of verifications) {
+    // Identity describes installed tools; admission/execution separately owns config authorization.
+    const capability = validateVerificationAdapterCapability(
+      dependencyOwner,
+      verification,
+      { executionWritePaths: VERIFICATION_CONFIGURATION_PATHS },
+    );
+    if (!capability.ok) throw new Error("verification-environment-unavailable");
+    roots.push(
+      ...verificationRunnerFiles(
+        dependencyOwner,
+        verification,
+        capability.runnerBindings,
+      ),
+    );
+    for (const binding of capability.runnerBindings)
+      if (binding.mountSource) roots.push(binding.mountSource);
+  }
+  return runWorkspaceIo<string>({
+    root: dependencyOwner,
+    artifactRoot: dependencyOwner,
+    operation: "verificationIdentity",
+    args: [roots],
+    signal,
+  });
+}
+
+const CACHES = [".vite", ".vite-temp"];
+function within(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+/** A disposable dependency view: immutable packages and independently writable caches. */
+export function prepareVerificationEnvironment(
+  root: string,
+  dependencyOwner: string,
+  runnerBindings: readonly VerificationRunnerBinding[],
+) {
+  const privateRoot = mkdtempSync(
+    path.join(path.dirname(root), ".cadence-verification-"),
+  );
+  const cleanup = () => rmSync(privateRoot, { recursive: true, force: true });
+  try {
+    const mounts: IsolationMount[] = [
+      { source: privateRoot, target: "/cadence", writable: true },
+    ];
+    for (const directory of [
+      "home",
+      "cache",
+      "tmp",
+      "reports",
+      "dependencies",
+    ]) {
+      mkdirSync(path.join(privateRoot, directory), { mode: 0o700 });
+    }
+    writeFileSync(path.join(privateRoot, "home/user.npmrc"), "");
+    writeFileSync(path.join(privateRoot, "home/global.npmrc"), "");
+    const dependencies = path.join(dependencyOwner, "node_modules");
+    const stat = lstatSync(dependencies, { throwIfNoEntry: false });
+    if (stat) {
+      const target = path.join(root, "node_modules");
+      const targetStat = lstatSync(target, { throwIfNoEntry: false });
+      if (
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        (targetStat &&
+          (!targetStat.isDirectory() || targetStat.isSymbolicLink()))
+      ) {
+        throw new Error("dependency-path-unsafe");
+      }
+      if (!targetStat) mkdirSync(target, { mode: 0o700 });
+      const view = path.join(privateRoot, "dependencies");
+      mounts.push({ source: view, target: "/workspace/node_modules" });
+      const entries = readdirSync(dependencies);
+      if (entries.length > 20_000) throw new Error("dependency-view-too-large");
+      const canonical = realpathSync(dependencies);
+      for (const name of entries) {
+        if (CACHES.includes(name)) continue;
+        const source = path.join(dependencies, name);
+        const placeholder = path.join(view, name);
+        const entry = lstatSync(source);
+        if (entry.isSymbolicLink()) {
+          const link = readlinkSync(source);
+          if (
+            path.isAbsolute(link) ||
+            !within(canonical, realpathSync(source))
+          ) {
+            throw new Error("dependency-path-unsafe");
+          }
+          symlinkSync(link, placeholder);
+        } else {
+          if (entry.isDirectory()) mkdirSync(placeholder);
+          else if (entry.isFile()) writeFileSync(placeholder, "");
+          else throw new Error("dependency-path-unsafe");
+          mounts.push({ source, target: `/workspace/node_modules/${name}` });
+        }
+      }
+      for (const cache of CACHES) {
+        mkdirSync(path.join(view, cache));
+        const source = path.join(privateRoot, "cache", cache);
+        mkdirSync(source);
+        mounts.push({
+          source,
+          target: `/workspace/node_modules/${cache}`,
+          writable: true,
+        });
+      }
+    }
+    const sources = new Map<string, string>();
+    const bindings = runnerBindings.map((binding) => {
+      if (!binding.mountSource) return { ...binding };
+      const source = path.resolve(binding.mountSource);
+      const stat = lstatSync(source);
+      const executable = realpathSync(binding.executablePath);
+      if (
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        !within(source, executable)
+      ) {
+        throw new Error("runner-mount-unavailable");
+      }
+      let target = sources.get(source);
+      if (!target) {
+        target = `/cadence-runners/${sources.size}`;
+        sources.set(source, target);
+        mounts.push({ source, target });
+      }
+      const translate = (file: string) =>
+        path.posix.join(target, ...path.relative(source, file).split(path.sep));
+      return {
+        ...binding,
+        executablePath: translate(executable),
+        ...(binding.fixedArgs
+          ? {
+              fixedArgs: binding.fixedArgs.map((arg) =>
+                path.isAbsolute(arg) && within(source, arg)
+                  ? translate(arg)
+                  : arg,
+              ),
+            }
+          : {}),
+      };
+    });
+    return {
+      privateRoot,
+      mounts,
+      bindings,
+      cleanup,
+      environment: {
+        CI: "1",
+        HOME: "/cadence/home",
+        XDG_CACHE_HOME: "/cadence/cache",
+        TMPDIR: "/cadence/tmp",
+        npm_config_cache: "/cadence/cache/npm",
+        npm_config_userconfig: "/cadence/home/user.npmrc",
+        npm_config_globalconfig: "/cadence/home/global.npmrc",
+        PATH: [
+          ...new Set(
+            // Honor explicitly resolved private runtimes before system fallbacks.
+            [
+              ...bindings.filter((binding) => binding.mountSource),
+              ...bindings.filter((binding) => !binding.mountSource),
+            ].map((binding) => path.posix.dirname(binding.executablePath)),
+          ),
+          "/usr/local/bin",
+          "/usr/bin",
+          "/bin",
+        ].join(":"),
+      },
+    };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}

package/src/verification-identity.ts

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readdirSync,
+  readlinkSync,
+  readSync,
+} from "node:fs";
+import path from "node:path";
+
+/** Content identity, including executable modes and links. Never follows dependency links. */
+export function verificationEnvironmentDigest(
+  roots: readonly string[],
+  checkCancelled: () => void = () => {},
+) {
+  const digest = createHash("sha256");
+  let entries = 0;
+  let bytes = 0;
+  const started = Date.now();
+  const buffer = Buffer.alloc(256 * 1024);
+  const visit = (file: string, relative: string, dependencyRoot: boolean) => {
+    checkCancelled();
+    if (++entries > 500_000 || Date.now() - started > 60_000)
+      throw new Error("verification-environment-limit");
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    digest.update(JSON.stringify([relative, stat ? stat.mode & 0o777 : null]));
+    if (!stat) {
+      digest.update("absent");
+      return;
+    }
+    if (stat.isSymbolicLink()) {
+      digest.update(JSON.stringify(["link", readlinkSync(file)]));
+      return;
+    }
+    if (stat.isDirectory()) {
+      digest.update("directory");
+      for (const name of readdirSync(file).sort()) {
+        if (dependencyRoot && [".vite", ".vite-temp"].includes(name)) continue;
+        visit(path.join(file, name), `${relative}/${name}`, false);
+      }
+      return;
+    }
+    if (!stat.isFile()) throw new Error("verification-environment-unsafe");
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const before = fstatSync(fd);
+      if (before.ino !== stat.ino || before.dev !== stat.dev)
+        throw new Error("verification-environment-changed");
+      const content = createHash("sha256");
+      for (;;) {
+        const count = readSync(fd, buffer, 0, buffer.length, null);
+        if (count === 0) break;
+        checkCancelled();
+        bytes += count;
+        if (bytes > 16 * 1024 ** 3 || Date.now() - started > 60_000)
+          throw new Error("verification-environment-limit");
+        content.update(buffer.subarray(0, count));
+      }
+      const after = fstatSync(fd);
+      if (
+        before.size !== after.size ||
+        before.mtimeMs !== after.mtimeMs ||
+        before.ctimeMs !== after.ctimeMs
+      )
+        throw new Error("verification-environment-changed");
+      digest.update(JSON.stringify(["file", content.digest("hex")]));
+    } finally {
+      closeSync(fd);
+    }
+  };
+  for (const root of [...new Set(roots)].sort())
+    visit(root, root, path.basename(root) === "node_modules");
+  return digest.digest("hex");
+}

package/src/worker-broker.ts

@@ -21,6 +21,8 @@ export interface RouteRequirements {
   dialects?: RouteDialect[];
   minContextWindow?: number;
   minOutputTokens?: number;
+  preferredContextWindow?: number;
+  preferredOutputTokens?: number;
 }
 
 interface RouteHealth {
@@ -56,6 +58,7 @@ export interface WorkerBrokerOptions {
 
 export interface RunWorkerAttemptInput<T> {
   runId: string;
+  taskId?: string;
   operationId: string;
   role: WorkerRole;
   requirements?: RouteRequirements;
@@ -126,7 +129,13 @@ function validRequirements(value: unknown): value is RouteRequirements {
   if (
     Object.keys(candidate).some(
       (key) =>
-        !["dialects", "minContextWindow", "minOutputTokens"].includes(key),
+        ![
+          "dialects",
+          "minContextWindow",
+          "minOutputTokens",
+          "preferredContextWindow",
+          "preferredOutputTokens",
+        ].includes(key),
     )
   ) {
     return false;
@@ -147,7 +156,12 @@ function validRequirements(value: unknown): value is RouteRequirements {
         (candidate.minContextWindow as number) > 0)) &&
     (candidate.minOutputTokens === undefined ||
       (Number.isSafeInteger(candidate.minOutputTokens) &&
-        (candidate.minOutputTokens as number) > 0))
+        (candidate.minOutputTokens as number) > 0)) &&
+    [candidate.preferredContextWindow, candidate.preferredOutputTokens].every(
+      (value) =>
+        value === undefined ||
+        (Number.isSafeInteger(value) && (value as number) > 0),
+    )
   );
 }
 
@@ -176,7 +190,6 @@ export class WorkerBroker {
   readonly #policy: RoutePolicy;
   readonly #now: () => number;
   readonly #healthStore: RouteHealthStore;
-  readonly #health = new Map<string, RouteHealth>();
 
   constructor(policy: RoutePolicy, options: WorkerBrokerOptions = {}) {
     this.#policy = structuredClone(policy);
@@ -187,7 +200,6 @@ export class WorkerBroker {
   #routeHealth(routeId: string): RouteHealth {
     const route = this.#policy.routes[routeId];
     return (
-      this.#health.get(routeId) ??
       (route ? this.#healthStore.get(route.fingerprint) : undefined) ?? {
         state: "healthy",
       }
@@ -197,7 +209,6 @@ export class WorkerBroker {
   #setRouteHealth(routeId: string, health: RouteHealth): void {
     const route = this.#policy.routes[routeId];
     if (!route) throw new Error("route-not-declared");
-    this.#health.set(routeId, structuredClone(health));
     this.#healthStore.set(route.fingerprint, health);
   }
 
@@ -229,14 +240,13 @@ export class WorkerBroker {
     });
   }
 
-  select(input: {
-    role: WorkerRole;
-    dialects?: RouteDialect[];
-    minContextWindow?: number;
-    minOutputTokens?: number;
-    exclude?: readonly string[];
-    routeId?: string;
-  }):
+  select(
+    input: RouteRequirements & {
+      role: WorkerRole;
+      exclude?: readonly string[];
+      routeId?: string;
+    },
+  ):
     | { ok: true; route: WorkerRoutePolicy; health: RouteHealthState }
     | { ok: false; code: "endpoint-unavailable" | "route-not-declared" } {
     const requirements: RouteRequirements = {
@@ -247,6 +257,12 @@ export class WorkerBroker {
       ...(input.minOutputTokens === undefined
         ? {}
         : { minOutputTokens: input.minOutputTokens }),
+      ...(input.preferredContextWindow === undefined
+        ? {}
+        : { preferredContextWindow: input.preferredContextWindow }),
+      ...(input.preferredOutputTokens === undefined
+        ? {}
+        : { preferredOutputTokens: input.preferredOutputTokens }),
     };
     if (!isRole(input.role) || !validRequirements(requirements)) {
       return { ok: false, code: "endpoint-unavailable" };
@@ -261,7 +277,22 @@ export class WorkerBroker {
       return { ok: false, code: "route-not-declared" };
     }
     const excluded = new Set(input.exclude ?? []);
-    for (const routeId of candidates) {
+    // Stable preference tiers preserve declared order within each tier. Health,
+    // hard minima and explicit pins still determine eligibility.
+    const preferred = (routeId: string) => {
+      const route = this.#policy.routes[routeId];
+      return route &&
+        route.capabilities.contextWindow >=
+          (requirements.preferredContextWindow ?? 0) &&
+        route.capabilities.maxTokens >=
+          (requirements.preferredOutputTokens ?? 0)
+        ? 1
+        : 0;
+    };
+    const ordered = [...candidates].sort(
+      (left, right) => preferred(right) - preferred(left),
+    );
+    for (const routeId of ordered) {
       if (excluded.has(routeId)) continue;
       const route = this.#policy.routes[routeId];
       if (!route || !capable(route, input.role, requirements)) continue;
@@ -606,7 +637,8 @@ export class WorkerBroker {
 }
 
 /**
- * Adds stable run/role route bindings to the stateless route-attempt broker.
+ * Adds run/role defaults and independent task bindings to route attempts.
+ * All bound brokers consult the same health store.
  * Attempt credentials and provider objects remain disposable and are never
  * retained by this facade.
  */
@@ -622,16 +654,21 @@ export class RunWorkerBroker {
 
   constructor(policy: RoutePolicy, options: WorkerBrokerOptions = {}) {
     this.#policy = structuredClone(policy);
-    this.#options = options;
-    this.#defaultBroker = new WorkerBroker(this.#policy, options);
+    this.#options = {
+      ...options,
+      healthStore: options.healthStore ?? new MemoryRouteHealthStore(),
+    };
+    this.#defaultBroker = new WorkerBroker(this.#policy, this.#options);
   }
 
-  #bindingKey(runId: string, role: WorkerRole): string {
-    return `${runId}\0${role}`;
+  #bindingKey(runId: string, role: WorkerRole, taskId?: string): string {
+    return JSON.stringify([runId, role, taskId ?? null]);
   }
 
-  #brokerFor(runId: string, role: WorkerRole): WorkerBroker {
-    const binding = this.#bindings.get(this.#bindingKey(runId, role));
+  #brokerFor(runId: string, role: WorkerRole, taskId?: string): WorkerBroker {
+    const binding =
+      this.#bindings.get(this.#bindingKey(runId, role, taskId)) ??
+      this.#bindings.get(this.#bindingKey(runId, role));
     if (!binding) return this.#defaultBroker;
     const routeId = binding.routeId;
     const key = `${role}\0${routeId}`;
@@ -657,6 +694,8 @@ export class RunWorkerBroker {
     if (
       typeof input.runId !== "string" ||
       input.runId.length === 0 ||
+      (input.taskId !== undefined &&
+        (typeof input.taskId !== "string" || input.taskId.length === 0)) ||
       typeof input.operationId !== "string" ||
       input.operationId.length === 0
     ) {
@@ -667,7 +706,11 @@ export class RunWorkerBroker {
         attempts: [],
       };
     }
-    const result = await this.#brokerFor(input.runId, input.role).run({
+    const result = await this.#brokerFor(
+      input.runId,
+      input.role,
+      input.taskId,
+    ).run({
       operationId: input.operationId,
       role: input.role,
       ...(input.requirements ? { requirements: input.requirements } : {}),
@@ -679,39 +722,54 @@ export class RunWorkerBroker {
     if (result.ok) {
       const route = this.#policy.routes[result.routeId];
       if (!route) throw new Error("broker-route-result-invalid");
-      this.#bindings.set(this.#bindingKey(input.runId, input.role), {
-        routeId: route.id,
-        fingerprint: route.fingerprint,
-      });
+      this.#bindings.set(
+        this.#bindingKey(input.runId, input.role, input.taskId),
+        {
+          routeId: route.id,
+          fingerprint: route.fingerprint,
+        },
+      );
     }
     return result;
   }
 
   rebind(input: {
     runId: string;
+    taskId?: string;
     role: WorkerRole;
     routeId: string;
     requirements?: RouteRequirements;
   }) {
-    const result = this.#defaultBroker.rebind(input);
+    const { taskId, ...routeInput } = input;
+    if (
+      taskId !== undefined &&
+      (typeof taskId !== "string" || taskId.length === 0)
+    ) {
+      return { ok: false as const, code: "approval-boundary" as const };
+    }
+    const result = this.#defaultBroker.rebind(routeInput);
     if (result.ok) {
-      this.#bindings.set(this.#bindingKey(input.runId, input.role), {
-        routeId: result.route.id,
-        fingerprint: result.route.fingerprint,
-      });
+      this.#bindings.set(
+        this.#bindingKey(input.runId, input.role, input.taskId),
+        {
+          routeId: result.route.id,
+          fingerprint: result.route.fingerprint,
+        },
+      );
     }
     return result;
   }
 
   resumeBinding(input: {
     runId: string;
+    taskId?: string;
     role: WorkerRole;
     routeId: string;
     expectedFingerprint?: string;
     requirements?: RouteRequirements;
   }) {
     const binding = this.#bindings.get(
-      this.#bindingKey(input.runId, input.role),
+      this.#bindingKey(input.runId, input.role, input.taskId),
     );
     const route = this.#policy.routes[input.routeId];
     if (!binding) {
@@ -724,6 +782,7 @@ export class RunWorkerBroker {
       }
       return this.rebind({
         runId: input.runId,
+        ...(input.taskId === undefined ? {} : { taskId: input.taskId }),
         role: input.role,
         routeId: input.routeId,
         ...(input.requirements ? { requirements: input.requirements } : {}),
@@ -751,8 +810,12 @@ export class RunWorkerBroker {
     this.#boundBrokers.clear();
   }
 
-  binding(runId: string, role: WorkerRole): string | undefined {
-    return this.#bindings.get(this.#bindingKey(runId, role))?.routeId;
+  binding(
+    runId: string,
+    role: WorkerRole,
+    taskId?: string,
+  ): string | undefined {
+    return this.#bindings.get(this.#bindingKey(runId, role, taskId))?.routeId;
   }
 
   status(): Record<string, unknown> {