Project: release a receipt-quality and risk-model cascade

Last updated: 6 Oct 20265 min read

project

Pin two model artifacts and a routing policy, test every branch and stage a reversible cascade release.

Freeze the pair

The first model checks whether a receipt image is readable; uncertain images go to a specialist risk model. Pin quality-model digest, specialist digest, preprocessing revisions, interstage schema, cutoff, deadline, fallback policy and prior complete manifest. A new quality model emits a confidence field under a different name, so a happy-path test that bypasses the specialist does not catch the mismatch. The cascade manifest blocks an unqualified pair.

Replay all branches

Run a frozen set with clear scans, borderline scans, corrupted inputs and high-value blurry receipts. Compare final route, branch exposure, score and latency to the approved cascade. Inject a first-stage timeout, specialist failure and missing confidence field. The schema mismatch must hold promotion rather than defaulting the specialist input to zero. Branch gates include a manual fallback under the full-request deadline.

Stage under real load

Correct the schema contract and preload both artifacts on the target host classes. Stage a small sticky cohort, then compare branch share, fast-branch misses, specialist capacity, p99 and manual review load. A shift in scan quality can suddenly send more traffic to the specialist, so test a burst before expanding. Shared capacity admission protects other models on the same nodes. Audit coverage checks released receipts that routine review never sees.

Finish with a reversible release packet

Record the approved pair, route-policy revision, replay evidence, host matrix, canary exposure and prior full manifest. Promote one cascade pointer only after all components are ready. In rollback, restore the old pair and cutoff together; do not leave a new quality model feeding the old specialist. Track branch-level outcomes until they mature. If the specialist fails later, a documented fallback route and owner must be available before the first customer-facing failure.

Implementation

def cascade_manifest_ready(manifest, available_artifacts, schema_pairs):
    pair = (manifest["quality_digest"], manifest["risk_digest"])
    if not set(pair).issubset(available_artifacts):
        return "hold:artifact"
    if pair not in schema_pairs:
        return "hold:interstage-schema"
    if manifest["fallback"] not in {"manual-review", "prior-cascade"}:
        return "hold:fallback"
    return "stage:complete-manifest"

manifest = {"quality_digest": "quality-r8", "risk_digest": "risk-r31",
            "fallback": "manual-review"}
assert cascade_manifest_ready(manifest, {"quality-r8", "risk-r31"},
                              {("quality-r8", "risk-r31")}) ==        "stage:complete-manifest"
assert cascade_manifest_ready(manifest, {"quality-r8", "risk-r31"},
                              set()) == "hold:interstage-schema"

Performance and operating cost

The compatibility gate is O(1) expected time and space for indexed artifact and schema sets. End-to-end replay costs two model executions on routed cases, and warm specialist capacity may remain idle during ordinary traffic. That cost should be compared with avoided manual review and missed-risk cost, never used alone to waive branch quality.

Common Mistakes

Testing only clear scans that skip the specialist.
Defaulting a missing interstage field to a safe-looking score.
Canarying a pair without burst capacity for the specialist.
Rolling back one component while retaining the new cutoff and schema.