JuliusBrussee/caveman · error · Error

cave_harness_unknown_transform

cave_harness_unknown_transform

Error message

cave_harness_unknown_transform

What it means

`validateTransformEvidence` also rejects evidence that names transforms OUTSIDE the plan: every entry in `evaluatedTransformIDs` and `appliedTransformIDs` must be one of the plan's selected transform IDs. Unknown IDs mean the execution touched transforms the plan never authorized, so the adapter throws `cave_harness_unknown_transform` — the reverse direction of error 32, guarding against plan/execution divergence in the other direction.

Source

Thrown at packages/agent/src/adapters.ts:680

  evidence: Pick<HarnessRequest, "evaluatedTransformIDs" | "appliedTransformIDs" | "recoveryResolved">,
  plan: CavePlan,
): void {
  if (!Array.isArray(evidence.evaluatedTransformIDs) ||
      !Array.isArray(evidence.appliedTransformIDs) ||
      evidence.evaluatedTransformIDs.some((value) => typeof value !== "string" || value.length === 0) ||
      evidence.appliedTransformIDs.some((value) => typeof value !== "string" || value.length === 0) ||
      evidence.recoveryResolved !== true) {
    throw new Error("cave_harness_incomplete_evidence");
  }
  const selected = [...new Set(plan.segment_routes.map((route) => route.transform_id))].sort();
  const evaluated = [...new Set(evidence.evaluatedTransformIDs)].sort();
  const applied = [...new Set(evidence.appliedTransformIDs)].sort();
  if (selected.some((transformID) => !evaluated.includes(transformID))) {
    throw new Error("cave_harness_transform_not_evaluated");
  }
  if (evaluated.some((transformID) => !selected.includes(transformID)) ||
      applied.some((transformID) => !selected.includes(transformID))) {
    throw new Error("cave_harness_unknown_transform");
  }
}

function validateExecution(execution: HarnessExecution, plan: CavePlan): void {
  const [provider, ...modelParts] = plan.model.split("/");
  const model = modelParts.join("/");
  try {
    validateProviderUsage(execution, {
      expected: { provider: provider ?? "", model },
      reportedCostUsd: execution.costUsd,
      requirePriced: true,
    });
  } catch {
    throw new Error("cave_harness_incomplete_evidence");
  }
  if (execution.terminal !== true || typeof execution.text !== "string" ||
      execution.text.length === 0 ||
      execution.usageBasis !== "provider_reported" ||

View on GitHub (pinned to 27d5a3981a)

Solutions

  1. Ensure the execution evidence and the plan come from the same compiled build (same lock).
  2. Configure the custom harness to evaluate/apply exactly the plan's selected transform IDs — no extras.
  3. If you recompile the plan, discard and regenerate any cached execution evidence.

Example fix

// before
// plan selects ["history-text"], harness evaluated:
execution.evaluatedTransformIDs = ["history-text", "toon"]; // -> throws

// after
execution.evaluatedTransformIDs = ["history-text"]; // matches plan exactly
Defensive patterns

Strategy: validation

Validate before calling

function evidenceOnlyNamesPlanTransforms(plan: CavePlan, evidence: { evaluatedTransformIDs: string[]; appliedTransformIDs: string[] }): boolean {
  const selected = new Set(plan.segment_routes.map((r) => r.transform_id));
  return [...evidence.evaluatedTransformIDs, ...evidence.appliedTransformIDs]
    .every((id) => selected.has(id));
}
if (!evidenceOnlyNamesPlanTransforms(plan, execution)) throw new Error("stale evidence for this plan");

Try / catch

try {
  validateTransformEvidence(execution, plan);
} catch (err) {
  if (err instanceof Error && err.message === "cave_harness_unknown_transform") {
    // evidence came from a different plan build: discard and regenerate it
  }
}

Prevention

When it happens

Trigger: An execution reporting `evaluatedTransformIDs: ["history-text", "toon"]` when the plan selected only `history-text`; stale evidence from a previous plan replayed against a new one; a harness that always evaluates its full transform set regardless of plan selection.

Common situations: Mixing artifacts across builds — execution evidence recorded under plan A validated against plan B; a default transform set in a custom harness that includes IDs the compiled plan doesn't route; concurrency bug interleaving two runs' evidence.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/fef319c19a79b3f3. Report an issue: GitHub.