venue: type the venue-error surface with dedicated variants for representable conditions

[mfw78]

Follow-up from #589 and #590 (M4 CoW follow-ups). Both had to encode a representable, recurring adapter condition as venue-error.invalid-body(string) because the surface has no dedicated variant for it.

Evidence

The venue-error variant in wit/videre-types/types.wit is { unknown-venue, invalid-body(string), unsupported, denied(string), rate-limited, unavailable(string), timeout }. Recent adapter work shoved typed conditions into the string payloads:

• venue: restore the dropped empty-receipt guard on status and cancel #590 rejects an empty receipt as invalid-body("empty receipt"), an adapter-side receipt-validity condition, not a malformed body.
• cow: reconcile the accepted receipt uid against the local derivation #589 refuses an accepted receipt whose UID disagrees with the local derivation as invalid-body("orderbook uid ... disagrees with derived uid ..."), a receipt/derivation mismatch, again not a malformed body.

Both are venue-neutral, representable, recurring conditions wearing a string because the surface has no home for them. A caller cannot branch on them without parsing the message.

The design tension

The wire venue-error is deliberately coarse (see nullislabs/videre-nexum-module#11: denied is intentionally minimal, with venue-specific detail recovered venue-side via classify_denied). That coarseness is right for venue-reported errors whose taxonomy we do not control. It is wrong for adapter-detected conditions that are venue-neutral and finite: an invalid or empty receipt, a receipt-versus-derivation mismatch, an unsupported operation. Those deserve typed variants; the open-ended venue-reported cases keep a stringly escape hatch.

So this is not "make everything typed". It is: give the finite, representable, venue-neutral conditions dedicated variants, and keep invalid-body and denied string payloads only for genuinely custom or previously-unrepresentable errors.

Proposal

Audit the venue-error surface across the adapter (cow-venue) and the SDK, and:

• Add dedicated variants for the adapter-detected conditions that are venue-neutral and recurring. Candidates from the evidence: invalid-receipt (empty or structurally-invalid receipt) and a receipt/uid mismatch variant. These two are self-evidently venue-neutral (any orderbook venue can hand back an invalid receipt, or a UID that disagrees with the local derivation), so they land now; genuinely uncertain or venue-specific cases are left to sdk: prove venue-neutrality with a second venue and freeze the vocabulary videre-nexum-module#23's second-venue pass rather than guessed at here.
• Keep invalid-body(string) and denied(string) as the escape hatch for custom or unrepresentable errors; do not force a variant where the condition is open-ended or venue-specific.
• Thread the new variants through the bindgen VenueError, the owned VenueFault mirror, and the faults.rs conversions, and migrate cow: reconcile the accepted receipt uid against the local derivation #589 and venue: restore the dropped empty-receipt guard on status and cancel #590 off invalid-body onto the typed variants.

Where this belongs: M5, before the cleave

venue-error is a videre:types WIT vocabulary, so the decisive factor is the repo cut, not the second venue. Adding a variant is an additive, non-breaking WIT change either way, but the cost differs sharply on which side of the cleave it lands:

• Before the cleave (M5, still a monorepo): a single in-tree fold. Edit the WIT, the bindgen VenueError, the VenueFault mirror and faults.rs, regenerate goldens, done.
• After the cleave (M6): wit: hold the value-flow freeze until the second venue proves the abstraction videre-nexum-module#22's cross-repo ripple. Re-tag videre, re-pin in nexum-runtime, shepherd and the second-venue repo, regenerate goldens cross-repo, re-run the tip oracle per repo.

The two demonstrated cases are self-evidently venue-neutral, so waiting for the second venue to confirm them buys nothing and costs the ripple. Do them now, cheaply, in the monorepo. This must land before the carve (#407 / #549); after that it is no longer a fold.

This does not pre-empt nullislabs/videre-nexum-module#23: the second-venue vocabulary pass in M6 still owns any variant we cannot yet prove venue-neutral, and extends this surface additively. This issue is the cheap precursor, not the freeze. It is also the natural sibling of nullislabs/videre-nexum-module#11 (venue-supplied denial classification): together they define the venue error and retry seam.

Acceptance criteria

• The venue-neutral, representable adapter conditions currently carried as invalid-body(string), at least venue: restore the dropped empty-receipt guard on status and cancel #590's empty-receipt and cow: reconcile the accepted receipt uid against the local derivation #589's uid mismatch, have dedicated venue-error variants.
• invalid-body and denied string payloads remain only for genuinely custom or unrepresentable errors.
• cow: reconcile the accepted receipt uid against the local derivation #589 and venue: restore the dropped empty-receipt guard on status and cancel #590 are migrated onto the typed variants; a caller can branch on them without parsing a string.
• The change lands before the carve (packaging: carve nexum-runtime, videre and shepherd into three repos #407 / carve: force-replace both carved repo mains at the cut #549) as an in-monorepo fold, not a post-cleave cross-repo ripple.

Related

• errors: replace stringly and anyhow error paths with typed enums nexum-runtime#51 (M8): replace Rust stringly and anyhow paths with typed enums; this is the WIT-vocabulary complement.
• errors: right-size seam error types and wire From conversions nexum-runtime#50 (M8): wire the missing From edges between the existing typed errors.
• keeper: let a venue supply denial classification to the generic retry path videre-nexum-module#11 (M6): venue-supplied denial classification for the retry path.
• sdk: prove venue-neutrality with a second venue and freeze the vocabulary videre-nexum-module#23 (M6): the second-venue vocabulary pass that extends this surface additively; this issue is its cheap pre-cleave precursor.
• packaging: carve nexum-runtime, videre and shepherd into three repos #407 / carve: force-replace both carved repo mains at the cut #549 (M5): the carve this must land before.
• wit: hold the value-flow freeze until the second venue proves the abstraction videre-nexum-module#22 and wit: freeze-gate decisions for value-flow videre-nexum-module#20: the value-flow freeze and the additive-extensibility mechanism.
• venue: restore or document the dropped empty-receipt validation #491, cow: reconcile the accepted receipt uid against the local derivation #589, venue: restore the dropped empty-receipt guard on status and cancel #590: the evidence.