{"record":{"id":"478ccceab04b1cc5","repo":"JuliusBrussee/caveman","slug":"unknown-capability-478ccc","errorCode":"unknown_capability","errorMessage":"unknown_capability","messagePattern":"unknown_capability","errorType":"error_code","errorClass":"MiddlewareError","httpStatus":null,"severity":"error","filePath":"packages/sdk/python/caveman_cloud/middleware/validate.py","lineNumber":47,"sourceCode":"    if not all(token(v) for v in values):\n        raise MiddlewareError(\"invalid_scope\")\n    return json.dumps(values, separators=(\",\", \":\"))\n\n\ndef capabilities(value: Any) -> dict[str, Any]:\n    try:\n        if (type(value[\"schema_version\"]) is not int or value[\"schema_version\"] != 1 or not token(value[\"policy_revision\"])\n                or not isinstance(value[\"runtime_build\"], str) or value[\"mode\"] not in (\"record\", \"compress\")\n                or not isinstance(value[\"transforms\"], list) or len(value[\"transforms\"]) > 128\n                or not all(integer(value[\"limits\"][k]) and value[\"limits\"][k] > 0 for k in (\"deadline_ms\", \"request_bytes\", \"segment_bytes\", \"page_bytes\"))\n                or not integer(value[\"retention_seconds\"]) or type(value[\"recovery\"]) is not bool\n                or type(value[\"persistent\"]) is not bool):\n            raise ValueError()\n        seen = set()\n        for t in value[\"transforms\"]:\n            if (not token(t[\"transform_id\"]) or t[\"transform_id\"] in seen or not token(t[\"implementation_version\"])\n                    or not isinstance(t[\"eligible_segment_kinds\"], list) or t[\"recovery\"] not in (\"exact_ccr\", \"none\") or t[\"deterministic\"] is not True):\n                raise MiddlewareError(\"unknown_capability\")\n            seen.add(t[\"transform_id\"])\n        return value\n    except (KeyError, TypeError, ValueError) as error:\n        raise MiddlewareError(\"unsupported_version\") from None\n\n\ndef plan(value: Any, request: dict, input_digest: str, caps: dict) -> dict:\n    try:\n        p = value\n        if (type(p[\"schema_version\"]) is not int or p[\"schema_version\"] != 1 or p[\"request_id\"] != request[\"request_id\"] or p[\"input_digest\"] != input_digest\n                or p[\"policy_revision\"] != request[\"policy\"][\"revision\"] or not digest(p[\"replacement_set_id\"])\n                or p[\"status\"] not in (\"optimized\", \"bypassed\", \"record\") or not token(p[\"reason\"])\n                or not isinstance(p[\"replacements\"], list) or not isinstance(p[\"skipped\"], list)):\n            raise ValueError()\n        m = p[\"measurement\"]\n        recovery = p[\"recovery\"]\n        if (m[\"basis\"] != \"inferred\" or m[\"scope\"] != \"segment\" or m[\"verified_saved_usd\"] != 0\n                or not isinstance(m[\"tokenizer\"], str)","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/python/caveman_cloud/middleware/validate.py#L29-L65","documentation":"MiddlewareError raised by capabilities() when a capability manifest passes schema-version checks but contains a transform entry that is structurally invalid: duplicate transform_id, bad token fields, non-list eligible_segment_kinds, recovery not in (\"exact_ccr\",\"none\"), or deterministic is not literally True. Only vetted, deterministic, recoverable transforms are accepted.","triggerScenarios":"Calling capabilities() (or any flow that validates the manifest) with a transforms array containing: a repeated transform_id, recovery set to e.g. \"best_effort\", deterministic omitted/False, or eligible_segment_kinds as a string instead of a list.","commonSituations":"Hand-editing a capability manifest and typo-ing recovery; copying a transform entry without changing transform_id; a provider shipping a new transform type the validator doesn't whitelist; schema drift between middleware versions.","solutions":["Fix the offending transform entry: make transform_id unique, recovery exactly \"exact_ccr\" or \"none\", deterministic literally true, eligible_segment_kinds a list","Remove duplicate transform entries or merge them under one id","If the transform is legitimately new, update the validator/contract rather than loosening the manifest","Pre-validate the manifest with the check below before calling"],"exampleFix":"# before\n{\"transform_id\": \"t1\", \"recovery\": \"best_effort\", \"deterministic\": false, ...}\n# after\n{\"transform_id\": \"t1\", \"recovery\": \"none\", \"deterministic\": True, \"eligible_segment_kinds\": [\"prose\"]}","handlingStrategy":"validation","validationCode":"def transform_entry_ok(t) -> bool:\n    return (isinstance(t.get(\"transform_id\"), str) and t[\"transform_id\"]\n            and t.get(\"recovery\") in (\"exact_ccr\", \"none\")\n            and t.get(\"deterministic\") is True\n            and isinstance(t.get(\"eligible_segment_kinds\"), list))\n\ndef manifest_transforms_ok(doc) -> bool:\n    ids = [t.get(\"transform_id\") for t in doc.get(\"transforms\", [])]\n    return len(ids) == len(set(ids)) and all(transform_entry_ok(t) for t in doc[\"transforms\"])","typeGuard":"def is_deterministic_transform(t) -> bool:\n    return isinstance(t, dict) and t.get(\"deterministic\") is True and t.get(\"recovery\") in (\"exact_ccr\", \"none\")","tryCatchPattern":"try:\n    caps = client.capabilities(manifest)\nexcept MiddlewareError as e:\n    if e.args[0] == \"unknown_capability\":\n        log.error(\"a transform entry violates the capability contract\")\n    raise","preventionTips":["Keep transform_id values unique; generate ids instead of copy-pasting entries","Only use whitelisted recovery values (\"exact_ccr\", \"none\") and deterministic: true","Lint capability manifests in CI before shipping them to the middleware","Coordinate new transform types with a validator update, not silent manifest changes"],"tags":["validation","schema","capability","python"],"backgroundTag":"schema-validation-failed","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"}