Golden scenarios & the model drift gate

"Accurate recommendation" as an executable artifact (#1964): representative buyer situations with expected outcomes, plus structural invariants that catch silent model regressions. Implementation: src/lib/server/golden-scenarios.ts; suite fixture: data/selection-model/golden-scenarios.json.

Adding a scenario when a bad recommendation is found in the wild: add-a-golden-scenario.

Where it runs

Surface	What
npm test (CI)	golden-scenarios.spec.ts runs drift gate + every scenario against the committed authored envelope (data/selection-model/authored-model.json)
npm run model:validate -- [envelope]	Same checks against ANY envelope (default: the authored one) — validate a proposed import before promotion
npm run model:promote	Hard gate: refuses unless the suite passes and the scenario file is human-approved

The engine world (system attribute values, tier ladder) comes from the #1849 parity fixture — refresh it alongside model changes via npm run backup:remote / npm run fixture:recommendation. model:validate first resolves the envelope into that world's id space through the import planner (enum surrogate ids are instance-local; the annex label bridges), so a local export validates exactly as its promotion would behave on prod.

Scenario format

{
  "schemaVersion": 1,
  // Human review state — promotion refuses until "approved".
  "approval": { "status": "pending", "by": null, "on": null },
  "scenarios": [
    {
      "id": "coastal-hurricane-home",          // stable kebab id
      "title": "Coastal hurricane-zone home…",
      "track": "residential-homeowner",         // published track (documentation)
      "optionIds": [                            // what the flow submits, pre-seeds included
        "residential-commercial-residential",
        "geography-coastal",
        "hurricane-zone-yes"
      ],
      "expect": {
        "topOneOf": ["sl73"],                  // recommended system ∈ this set (the tolerance)
        "mustInclude": ["sl73"],               // must appear among candidates
        "mustExclude": []                       // must NOT appear
      }
    }
  ]
}

An empty optionIds is legitimate — it is the no-answers fallback scenario. topOneOf with several entries expresses tolerance; omit it (or use []) for scenarios that only constrain membership.

Drift gate invariants

Any failure is loud and fails CI + promotion:

1. Enabled unconditional fallback — a recommend rule with zero conditions exists and is enabled (the no-empty-hands guarantee; its silent disablement in prod is the founding bug of this gate).
2. Reachability — every active system is an outcome of at least one enabled rule.
3. No dangling option refs — no enabled rule's option condition references a missing factor option.
4. Live ruleset — at least one active ruleset has at least one enabled member rule.