{"record":{"id":"2db62951d34f9d3e","repo":"JuliusBrussee/caveman","slug":"cave-unknown-transform-route-transform-id","errorCode":null,"errorMessage":"cave_unknown_transform:${route.transform_id}","messagePattern":"cave_unknown_transform:(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/runtime.ts","lineNumber":2631,"sourceCode":"      failures: [],\n      recoveryResolved: true,\n      recoveryHandles: new Set(),\n      trace: [],\n    };\n  }\n  const known = new Set([\n    \"a11y\", \"code\", \"config\", \"diff\", \"html\", \"json\", \"log\", \"repetition\",\n    \"search-result\", \"tabular\", \"terminal\", \"text\", \"toolschema\", \"toon\",\n  ].map((name) => `caveman.engine.${name}.v1`));\n  const evaluated: string[] = [];\n  const applied: string[] = [];\n  const failures: string[] = [];\n  const handles = new Set<string>();\n  const trace: MutableTransformTrace[] = [];\n  let recoveryResolved = true;\n  for (const route of plan.segment_routes) {\n    if (!known.has(route.transform_id)) {\n      throw new Error(`cave_unknown_transform:${route.transform_id}`);\n    }\n    const targets = lowered.ir.segments.filter((segment) =>\n      segment.kind === route.segment_kind &&\n      (route.segment_id === undefined || segment.id === route.segment_id));\n    if (targets.length === 0) {\n      if (route.segment_kind === \"history\" || route.segment_kind === \"tool_result\") {\n        continue;\n      }\n      throw new Error(`cave_plan_route_unmatched:${route.segment_id ?? route.segment_kind}`);\n    }\n    evaluated.push(route.transform_id);\n    let routeApplied = false;\n    for (const segment of targets) {\n      const original = lowered.bodies.get(segment.bodyHandle);\n      if (!original) throw new Error(`cave_context_body_missing:${segment.id}`);\n      if (segment.safety !== \"S4\") throw new Error(`cave_transform_safety_mismatch:${segment.id}`);\n      const startedAt = performance.now();\n      // beforeTokens/afterTokens are byte-derived (bytes/4) throughout so a","sourceCodeStart":2613,"sourceCodeEnd":2649,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/runtime.ts#L2613-L2649","documentation":"Thrown while applying a plan when a segment_route references a transform_id outside the built-in known set (caveman.engine.{a11y,code,config,diff,html,json,log,repetition,search-result,tabular,terminal,text,toolschema,toon}.v1). Unknown transform engines are rejected before touching any segment.","triggerScenarios":"plan.segment_routes contains a transform_id not in the hardcoded set — e.g. a plan produced by a newer/older caveman version with different engine names, or a hand-written plan with a typo'd id.","commonSituations":"Version skew: plan serialized by one version of caveman, executed by another whose engine set differs; custom or experimental transform ids; typos when authoring plans by hand.","solutions":["Regenerate the plan with the same caveman version that executes it","Check the transform_id in the error against the known list and fix typos/renames","Pin matching versions of plan producer and runtime"],"exampleFix":"// before\nconst plan = { segment_routes: [{ transform_id: \"caveman.engine.text.v2\", segment_kind: \"history\" }] };\n\n// after\nconst plan = { segment_routes: [{ transform_id: \"caveman.engine.text.v1\", segment_kind: \"history\" }] };","handlingStrategy":"validation","validationCode":"const KNOWN = new Set([\n  \"a11y\",\"code\",\"config\",\"diff\",\"html\",\"json\",\"log\",\"repetition\",\n  \"search-result\",\"tabular\",\"terminal\",\"text\",\"toolschema\",\"toon\",\n].map((n) => `caveman.engine.${n}.v1`));\nfunction planTransformsKnown(plan: CavePlan): boolean {\n  return plan.segment_routes.every((r) => KNOWN.has(r.transform_id));\n}","typeGuard":"function unknownTransform(e: unknown): string | null {\n  if (!(e instanceof Error)) return null;\n  const m = /^cave_unknown_transform:(.+)$/.exec(e.message);\n  return m ? m[1] : null;\n}","tryCatchPattern":"if (!planTransformsKnown(plan)) {\n  plan = await buildPlan(...); // regenerate with the current version\n}\nawait applyPlan(plan, lowered);","preventionTips":["Generate and execute plans with the same caveman version","Validate transform ids against the known set before applying cached plans","Invalidate plan caches on version upgrades"],"tags":["transforms","plan","version-skew"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}