{"record":{"id":"a862a2c897540cf6","repo":"JuliusBrussee/caveman","slug":"registry-output-has-invalid-capability","errorCode":null,"errorMessage":"registry output has invalid capability","messagePattern":"registry output has invalid capability","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/agent/src/cli.ts","lineNumber":1123,"sourceCode":"    });\n    const parsed = JSON.parse(stdout) as {\n      registry_sha256?: unknown;\n      capabilities?: Array<{\n        transform_id?: unknown;\n        eligible_segment_kinds?: unknown;\n      }>;\n    };\n    if (typeof parsed.registry_sha256 !== \"string\" || !/^[0-9a-f]{64}$/.test(parsed.registry_sha256)) {\n      throw new Error(\"registry output has no valid registry_sha256\");\n    }\n    if (!Array.isArray(parsed.capabilities) || parsed.capabilities.length === 0) {\n      throw new Error(\"registry output has no capabilities\");\n    }\n    const capabilities = parsed.capabilities.map((capability): TransformCapability => {\n      if (typeof capability.transform_id !== \"string\" ||\n          !Array.isArray(capability.eligible_segment_kinds) ||\n          capability.eligible_segment_kinds.some((kind) => typeof kind !== \"string\")) {\n        throw new Error(\"registry output has invalid capability\");\n      }\n      return {\n        transformID: capability.transform_id,\n        segmentKinds: capability.eligible_segment_kinds as TransformCapability[\"segmentKinds\"],\n      };\n    });\n    return { sha256: parsed.registry_sha256, capabilities };\n  } catch (error) {\n    throw new Error(\n      `cave_transform_registry_unavailable: run caveman setup or set CAVEMAN_ENGINE_BIN (${error instanceof Error ? error.message : String(error)})`,\n    );\n  }\n}\n\nasync function engineEntitled(): Promise<boolean> {\n  const command = process.env.CAVEMAN_CLI_BIN ?? \"caveman\";\n  try {\n    const env = buildRuntimeControlEnv();","sourceCodeStart":1105,"sourceCodeEnd":1141,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/cli.ts#L1105-L1141","documentation":"Thrown per-entry while mapping the engine registry's `capabilities` array into `TransformCapability` objects. Each capability must have a string `transform_id` and an `eligible_segment_kinds` array whose every element is a string. Any entry violating that shape fails the whole registry load (and is then wrapped into `cave_transform_registry_unavailable` by the outer catch).","triggerScenarios":"An engine registry payload where a capability has a numeric or null `transform_id`, `eligible_segment_kinds` is missing/an object, or contains non-string kinds. Usually an engine/framework schema mismatch or hand-edited/corrupted registry data inside the engine's install.","commonSituations":"Engine binary from a different release train than the CLI package; registry files edited or partially written after a crash; third-party transforms installed into the engine with malformed manifests.","solutions":["Inspect the engine registry JSON and remove or fix the malformed capability entry.","Reinstall the engine (`caveman setup`) to restore a known-good registry.","Ensure the engine version matches the framework's expected registry schema; pin both together."],"exampleFix":"// before: malformed entry\n{ \"transform_id\": 42, \"eligible_segment_kinds\": [\"static\"] }\n\n// after\n{ \"transform_id\": \"caveman.engine.text.v1\", \"eligible_segment_kinds\": [\"static\"] }","handlingStrategy":"type-guard","validationCode":"function isValidCapability(v: unknown): boolean {\n  return typeof v === \"object\" && v !== null &&\n    typeof (v as { transform_id?: unknown }).transform_id === \"string\" &&\n    Array.isArray((v as { eligible_segment_kinds?: unknown }).eligible_segment_kinds) &&\n    ((v as { eligible_segment_kinds: unknown[] }).eligible_segment_kinds.every((k) => typeof k === \"string\"));\n}","typeGuard":"function isTransformCapability(v: unknown): v is { transform_id: string; eligible_segment_kinds: string[] } {\n  return typeof v === \"object\" && v !== null &&\n    typeof (v as { transform_id?: unknown }).transform_id === \"string\" &&\n    Array.isArray((v as { eligible_segment_kinds?: unknown }).eligible_segment_kinds) &&\n    (v as { eligible_segment_kinds: unknown[] }).eligible_segment_kinds.every((k) => typeof k === \"string\");\n}","tryCatchPattern":"try {\n  await build(args);\n} catch (error) {\n  if (error instanceof Error && error.message.startsWith(\"cave_transform_registry_unavailable\")) {\n    // invalid capability entry: reinstall engine registry via caveman setup\n  } else throw error;\n}","preventionTips":["Never hand-edit the engine's registry data.","Only install transforms from sources matching the engine's schema version.","Re-run `caveman setup` after any engine or transform pack update."],"tags":["engine","registry","parsing","validation"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}