{"record":{"id":"be9b2c78f36ea27e","repo":"JuliusBrussee/caveman","slug":"cave-unknown-transform","errorCode":"cave_unknown_transform","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/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/runtime.ts#L2613-L2649","documentation":"Thrown when a compaction plan's segment_routes reference a transform_id that is not in the set of known/registered transforms. The runtime validates every route's transform before evaluating routes and fails fast on unknown ids. This guards against plans naming transforms that were never registered with the engine.","triggerScenarios":"Executing a plan whose plan.segment_routes[i].transform_id is not present in the known transform registry — e.g. a hand-written plan, a plan from an older/newer runtime version, or a typo in the transform id (engine transforms must match caveman.engine.<name>.v1).","commonSituations":"Plan files produced by a different engine version whose transform set changed; hand-authoring plans with invented transform names; registering transforms conditionally so the plan's transform wasn't registered this run.","solutions":["Print the registered transform set and correct the plan's transform_id to an existing one.","Register the missing transform with the engine before executing the plan.","Regenerate the plan with the current runtime version instead of reusing a stale one.","Fix typos in the transform_id — engine ids follow the caveman.engine.<slug>.v1 pattern."],"exampleFix":"// before\nsegment_routes: [{ segment_kind: \"history\", transform_id: \"caveman.engine.summarize.v2\" }]\n// after\nsegment_routes: [{ segment_kind: \"history\", transform_id: \"caveman.engine.summarize.v1\" }]","handlingStrategy":"validation","validationCode":"const known = new Set(registeredTransforms.map(t => t.id));\nconst bad = plan.segment_routes.filter(r => !known.has(r.transform_id));\nif (bad.length) throw new Error(`unknown transforms in plan: ${bad.map(r => r.transform_id).join(\",\")}`);","typeGuard":"function isKnownTransform(id: string, known: Set<string>): boolean { return known.has(id); }","tryCatchPattern":"try {\n  await executePlan(plan, lowered);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith(\"cave_unknown_transform:\")) {\n    const id = err.message.split(\":\")[1];\n    // register the transform or regenerate the plan with valid ids\n  } else throw err;\n}","preventionTips":["Generate plans from the runtime's registered transform list, never by hand.","Regenerate stored plans after runtime/engine upgrades.","Validate plan transform ids against the registry at plan load time.","Keep engine ids in the caveman.engine.<slug>.v1 shape."],"tags":["plan","transform","registry","agent-runtime"],"backgroundTag":"invalid-identifier-format","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}