{"record":{"id":"aa16bebd7e6f2c79","repo":"JuliusBrussee/caveman","slug":"invalid-plan-aa16be","errorCode":"invalid_plan","errorMessage":"invalid_plan","messagePattern":"invalid_plan","errorType":"error_code","errorClass":"MiddlewareError","httpStatus":null,"severity":"error","filePath":"packages/sdk/python/caveman_cloud/middleware/validate.py","lineNumber":104,"sourceCode":"                    or not recovery[\"available\"] or not recovery[\"persistent\"] or re.fullmatch(r\"cmw_[a-f0-9]{48}\", r[\"recovery_handle\"]) is None\n                    or not r[\"text\"].startswith(f\"[caveman: shortened; exact original via caveman_retrieve handle={r['recovery_handle']}]\\n\")):\n                raise ValueError()\n            seen.add(r[\"segment_id\"])\n            reduction += r[\"tokens_before\"] - r[\"tokens_after\"]\n            if r[\"unique_original\"]:\n                unique += r[\"tokens_before\"] - r[\"tokens_after\"]\n                credited.add(r[\"original_sha256\"])\n        for skipped in p[\"skipped\"]:\n            if skipped[\"segment_id\"] not in segments or skipped[\"segment_id\"] in seen or not token(skipped[\"reason\"]):\n                raise ValueError()\n            seen.add(skipped[\"segment_id\"])\n        if (len(seen) != len(segments) or m[\"tokens_before\"] - m[\"tokens_after\"] != reduction or m[\"unique_tokens_reduced\"] != unique\n                or (p[\"replacements\"] and (p[\"status\"] != \"optimized\" or reduction <= m[\"recovery_overhead_tokens\"]))\n                or (p[\"status\"] == \"optimized\" and not p[\"replacements\"])):\n            raise ValueError()\n        return p\n    except (KeyError, TypeError, ValueError, UnicodeError):\n        raise MiddlewareError(\"invalid_plan\") from None\n\n\ndef page(value: Any, args: dict, max_bytes: int) -> dict:\n    try:\n        p = value\n        if (type(p[\"schema_version\"]) is not int or p[\"schema_version\"] != 1 or p[\"handle\"] != args[\"handle\"] or not token(p[\"source_id\"]) or not digest(p[\"original_sha256\"])\n                or not isinstance(p[\"text\"], str) or not integer(p[\"total_bytes\"]) or not integer(p[\"offset\"]) or p[\"offset\"] != args.get(\"offset\", 0)\n                or p[\"kind\"] not in (\"original_page\", \"excerpt\") or type(p[\"complete\"]) is not bool\n                or not (p[\"next_offset\"] is None or integer(p[\"next_offset\"]))):\n            raise ValueError()\n        length = len(p[\"text\"].encode(\"utf-8\"))\n        end = p[\"offset\"] + length\n        if length > max_bytes:\n            raise ValueError()\n        if p[\"kind\"] == \"original_page\" and (end > p[\"total_bytes\"] or p[\"next_offset\"] != (end if end < p[\"total_bytes\"] else None)\n                or p[\"complete\"] != (p[\"offset\"] == 0 and length == p[\"total_bytes\"])):\n            raise ValueError()\n        if p[\"kind\"] == \"excerpt\" and (p[\"complete\"] or not args.get(\"query\") or p[\"next_offset\"] != 0):","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/sdk/python/caveman_cloud/middleware/validate.py#L86-L122","documentation":"MiddlewareError raised by plan() when the returned optimization plan is internally inconsistent: duplicate segments, token accounting that doesn't add up (tokens_before - tokens_after != reduction, unique_tokens_reduced mismatch), replacements present without status \"optimized\" or with reduction at/below recovery_overhead_tokens, or status \"optimized\" with no replacements. It also fires on any KeyError/TypeError/ValueError/UnicodeError while checking the plan's shape against the request and input digest.","triggerScenarios":"Calling the flow that validates a plan with: a plan whose request_id/input_digest don't match the original request, tampered or recomputed token counts, a plan claiming \"optimized\" with an empty replacements list, or a corrupted/deserialized plan object.","commonSituations":"A buggy or malicious middleware returning a fabricated plan; plans round-tripped through JSON edits; version skew changing field semantics; manually constructing a plan in tests with inconsistent numbers.","solutions":["Regenerate the plan: re-run the optimize request so middleware recomputes consistent token counts","Verify middleware and SDK versions match; upgrade the side that is behind","Don't hand-edit plan fields; if a test fixture is involved, recompute tokens_before/tokens_after/reduction so the arithmetic holds","Pre-check status/replacements consistency before passing the plan onward"],"exampleFix":"# before\nplan_doc[\"status\"] = \"optimized\"  # replacements left empty\n// after\nif replacements:\n    plan_doc[\"status\"] = \"optimized\"\nelse:\n    plan_doc[\"status\"] = \"skipped\"","handlingStrategy":"validation","validationCode":"def plan_arithmatic_ok(p) -> bool:\n    m = p[\"metrics\"]\n    reduction = m[\"tokens_before\"] - m[\"tokens_after\"]\n    return not (p.get(\"replacements\") and (p[\"status\"] != \"optimized\" or reduction <= m[\"recovery_overhead_tokens\"])) \\\n        and not (p[\"status\"] == \"optimized\" and not p.get(\"replacements\"))","typeGuard":"def is_consistent_plan(p) -> bool:\n    m = p.get(\"metrics\", {})\n    return m.get(\"tokens_before\", 0) - m.get(\"tokens_after\", 0) == m.get(\"reduction\", 0)","tryCatchPattern":"try:\n    checked = validate.plan(plan_doc, request, input_digest, caps)\nexcept MiddlewareError as e:\n    if e.args[0] == \"invalid_plan\":\n        plan_doc = client.optimize(request)  # regenerate\n    else:\n        raise","preventionTips":["Never hand-edit plan fields; always regenerate from the middleware","Keep plan/request_id and input_digest immutable through any serialization round-trip","Recompute fixture numbers when building tests so arithmetic invariants hold","Upgrade SDK/middleware together when plan field semantics change"],"tags":["validation","plan","integrity","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"}