nordisk/facett

facett error codes — Phase 2: consumer REACTIONS + the reaction test matrix

Status: Phase 2 COMPLETE — all 30 (code × mount) rows have a production consumer call site (see §8 for the bar, and for the correction of an earlier over-claim of 35). Phase 1 (the facet-<component>-<n> scheme) is merged; see facett-error-codes-design.md.

The ask (Rickard): "then implement in the test matrix robot UI tests … this would mean like 150 robot UI tests that MUST react if an error is raised."

1. The analysis — what consumers do TODAY

Before this phase, no consumer reacted to a facett UI failure at all. A facett pane that had no data or failed to load simply rendered nothing: the host showed a blank pane, or at best a generic string that no code could branch on. korp already had a good typed-error story for its OWN backend errors (korp::diag::DiagCode — a closed, gRPC-mapped enum in $KORP_STATE.diagnostics), but a facett UI error never entered it: the two worlds did not meet.

That is the gap Phase 2 closes.

2. The reaction vocabulary (facett owns it)

facett_core::errcode::Reaction — the shared vocabulary every consumer agrees on, so a failure means the same thing everywhere:

facett declares the canonical reaction per code in errcode::REGISTRY, so the contract is shared rather than re-litigated in each app. errcode::reaction_for(code) resolves a bare (facet-map-2) or mounted (korp/cases:facet-map-2) code — the reaction is a property of the code; the mount only says where it happened.

3. Mount namespacing — how facett codes and APP codes compose

A component can be mounted many times in one app, so the consumer prefixes the facett code with its own mount:

korp/cases:facet-map-2      korp/infra:facet-map-2      nornir/viz:facet-graph3d-1
└── consumer mount ──┘└ base facett code ┘

• the base facett code never changes — it is facett's, frozen and append-only;
• the mount prefix is the consumer's, applied via FacetError::with_consumer_prefix;
• an app's OWN backend errors keep the app's own codes (korp-<subsystem>-<n>, nornir-…, dwarves-…, holger-…) — the two vocabularies compose, they never collide. In korp both land in ONE ring and are distinguished by whether the entry carries a facet_code.

4. The consumer mounts (measured, not assumed)

This yields 30 (code × mount) pairs — the reaction matrix. See the generated LIST (facett-error-codes-registry.md) for every row. (It was 35 until §8's audit: korp was credited with graphview + syschart mounts it does not have — no dependency on either crate — and those five rows were removed.)

5. korp's implementation (the reference consumer)

korp::facet_diag is korp's half of the contract:

• Mount — korp/cases · korp/analysis · korp/infra, tied to korp::mode::Mode.
• record(mount, &FacetError) -> Reaction — the ONE front door. It namespaces the code, records the mounted code into korp's EXISTING typed diagnostics ring ($KORP_STATE.diagnostics, not a twin), and returns the canonical reaction.
• diag_code_for(reaction) — maps a reaction onto korp's typed DiagCode, so a facett UI error is classified beside every other korp error: empty_state → NotFound (an absence, not a crash), retry/reconnect → Unavailable, fallback → FailedPrecondition (degrade, don't alarm), diagnose → Internal.
• korp::diag::DiagEntry gained an additive facet_code: Option<String>.
• matrix() / state_json() — korp's rows of the shared table, published as data.

6. The test matrix — TABLE-DRIVEN, not 150 copies

korp/tests/facet_reaction_matrix.rs generates the suite from ONE data table (errcode::reaction_matrix() filtered to korp mounts). Adding a facett code — or a mount — adds rows automatically; nobody hand-writes near-identical tests, and nobody can add a code that silently has no reaction.

Every row runs the full check set:

1. resolvable — the mounted code resolves to a canonical reaction;
2. mount-independent — the same base code at every other mount reacts identically;
3. round-trip — base code + mount recoverable from the mounted code;
4. korp reacts — record returns exactly the canonical reaction;
5. recorded — the MOUNTED code lands in $KORP_STATE.diagnostics;
6. classified — with korp's typed DiagCode, and the human message survives;
7. behaviour class — an empty state is never a hard fault, a GPU-absent code never alarms, a dead backend is always surfaced as unavailable.

Plus whole-matrix gates: a coverage report, every_code_is_accounted_for (the registry consumer column and korp's implemented matrix must AGREE — no silent gaps either way), the published state_json surface, and "an unregistered code is diagnosed, never ignored".

Tests assert the REACTION and the MOUNTED CODE — never a matched string.

7. Both demos, in lockstep (LAW #2)

The reaction matrix is a slide in both demos, from ONE source of truth:

• facett-demo (Errors tab) reads the compiled REGISTRY directly and renders the catalog slide (+ status + reaction + who-reacts columns) and the reaction-matrix slide.
• facett-demo-python (🩷 Errors tab, panes/errcode_pane.py) reads py/facett_demo_python/errcodes.json, generated from the same registry by cargo run -p facett-core --bin errcode_registry_json.
• facett-core/tests/registry_md_fresh.rs fails if EITHER export drifts, so the two demos can never show different catalogs.

8. Status — all 30 (code × mount) rows consumer-wired

Correction of record (2026-07-31). An earlier revision claimed "all 35 rows are consumer-wired". Measured against a real bar that was wrong in all four apps: each had a reaction MODULE and a table-driven suite, but the reaction function had no caller outside its own tests. A registration with no caller is not a wiring — the claim reproduced, one level up, the fiction this phase set out to kill.

The bar used below is: a production (non-test) call site on a path the app really runs, plus a test that drives that path with a component in a real failure state.

The matrix is 30 rows, not 35: five were fiction (below).

One shape, four hosts

Read the code the pane published (state_json.error_code — the seam the whole scheme exists for), resolve mount ownership from errcode::mounts_for (so a mount cannot be fiction in either direction), record the MOUNTED code, act on the canonical reaction, publish the result as data in the app's own state. The hot path is gated on the pane's structural Severity, so a healthy pane never pays for the state_json build.

Three real gaps this uncovered — and closed

1. Silent raise sites. A code was published by one type of a component family while the type hosts actually mount stayed silent, so the consumer had nothing to react to. Fixed in facett, in the same crate as the frozen code:

   • facett_graphview::DecoratedGraphView now raises facet-graphview-1 on an empty scene (only MetroView did) — this is what unblocked dwarves/funnel;
   • facett_map::layer::MapFacet now raises facet-map-2 when the view draws no features (only MapView did) — this unblocked korp's six facet-map-* rows. Both also gained the matching severity() override (the Robot-UI gate signal AND the consumer's cheap per-frame gate).

2. Five FICTIONAL rows, removed. The registry claimed korp/infra mounted syschart and graphview; korp has no dependency on facett-syschart or facett-graphview at all — not in Cargo.toml, not in src/. Those five rows are gone from the consumer column (35 → 30). They belong back only when korp really mounts those components.

3. korp had no anti-fiction guard. Its mounts are a bare Mount enum with no site anchor, so the check the other three carry never applied — which is exactly how (2) survived. every_component_korps_matrix_claims_is_really_a_korp_dependency is korp's equivalent: every claimed component must be a real dependency AND be referenced in korp's sources. And each app's site guard now also asserts the declared file calls the seam, not merely that it names the component — the check that would have caught the original over-claim.

Reserved codes

11 of the 30 rows carry codes the registry still marks reserved (GPU-fallback, non-convergence, source-load paths that have no explicit failure branch yet). Their mount is wired the same way — the seam is registry-driven, so it reacts to them the moment a pane publishes one — and each is proven through the production seam by the per-app every_*_matrix_row_is_handled_by_the_production_seam test. What is not yet proven end-to-end is the raise, and that is the facett-side work those rows wait on.

Two implementation shapes, one contract

• korp integrates facett errors into the typed DiagCode diagnostics ring it already had — no twin surface.
• nornir / dwarves / holger use the shared facett_core::errcode::FacetRecorder, so "how a consumer reacts" is implemented ONCE rather than three times. Each app supplies only its mounts and folds state_json into its own observable state.

The ANTI-FICTION guard (the dwarves lesson)

A registry that is 62% fiction is worse than none. Every ConsumerMount declares the site file that really mounts the component, and each app's suite fails if that file does not reference facett_<component> — so a DECLARED mount can never be fiction. Paired with the registry↔matrix agreement test in each app (the consumer column and the implemented matrix must agree in BOTH directions), the facett side cannot drift the way dwarves' registry did.

Composition with app-level codes

Every consumer now also owns its own frozen app registry (nornir-<subsystem>-<n>, holger-<subsystem>-<n>, dwarves-<subsystem>-<n>, korp's DiagCode). The two vocabularies compose, never collide, and each app has a test proving neither registry shadows the other:

• a facett UI failure → facett's frozen code + the consumer's mount prefix (nornir/viz:facet-graph3d-1);
• the app's own failure → the app's code.