fix(web): coerce AKS composition outputs so the shared validator resolves them (#996)

[sabbour-squad-backend]

Closes #996

Working as Bender (Backend Dev). Coordinates with PR #1000 — reuses the validateAndSanitizeComponents shared validator (commit 2561772) rather than forking it, per Nibbler's DP-review guidance.

Root cause

The AKS composition skill-chain intermittently emits envelopes with either:

1. A bare pack component name (e.g. AksClusterCard) instead of the registry-qualified form (aks/AksClusterCard), or
2. type as a legacy alias for component.

Both cases made validateAndSanitizeComponents treat the component as unknown and replace it with _ErrorComponent — the user-visible failure reported in #996.

Fix

Added a narrow coercion step inside the existing validator (not a parallel validator) in packages/web/src/contexts/A2UIRegistryContext.tsx:

• type → component when component is absent.
• Bare pack suffix → pack-qualified name when exactly one pack exposes that suffix. Ambiguous suffixes (e.g. shared across aks/* and azure/*) are left untouched so the validator still rejects them as unknown — per Zapp's DP condition to keep _ErrorComponent as the fail-loud fallback, never widen it into a best-effort guess.

The Zod-schema trust boundary (PR #989 / #1000) is unchanged. Malformed payloads still fall back to _ErrorComponent. Structured logs only name the offending component — no composition payload, no AKS/Azure identifiers — matching Zapp's log-hygiene rail.

Tests

New suite in a2ui-registry.test.ts — 7 new cases, all green:

• Rewrites a unique bare pack name to its pack-qualified form.
• Does NOT coerce an ambiguous bare name (suffix shared across packs).
• Accepts type as a legacy alias for component.
• Prefers explicit component over type when both are present.
• Leaves already-qualified names untouched.
• Core bare names win — does not rewrite a registered bare name to any pack/Name variant.
• Regression guard for a realistic AKS composition envelope → zero _ErrorComponent entries.

Validation

Check	Result
npm run lint	✅ 0 errors (61 pre-existing warnings, unchanged)
CI=1 npm test -- --reporter=dot	✅ 992 passed / 159 todo / 3 skipped — 87 files
npm run api:build (api:build prebuilds harness; direct -w @aks-kickstart/api needs harness dist first — pre-existing workspace-ordering quirk)	✅ Bundled 20 functions

Diff summary

 .changeset/996-aks-composition-coercion.md        |  12 +
 packages/web/src/__tests__/a2ui-registry.test.ts  | 110 ++++++++++++
 packages/web/src/contexts/A2UIRegistryContext.tsx |  79 +++++++-
 3 files changed, 200 insertions(+), 1 deletion(-)

Not in scope (per Nibbler's two-PR rollback ask)

• Prompt-chain simplification (DP step 3). Splitting that from the validation-rail fix lets a prompt rollback not take down the validation rail.
• Reliability N-times sweep. Non-deterministic against a stochastic model — would land as @slow/nightly, out of scope here.

---

⚠️ Awaiting the 4-way reviewer gate (Leela / Zapp / Nibbler / Fry). Do NOT self-merge.

[github-actions]

👀 Squad review trail

Current head: 7ad1635
Last update: Label applied: nibbler:approved.

• Native PR review mirror created for this label event.
  Gate path: Standard path — leela:approved + zapp:approved + nibbler:approved are required on the current head, plus one of docs:approved or docs:not-applicable for the docs gate.
  Gate snapshot: ✅ squad/review-gate should be green on the current head.
  Reviewer labels
• Leela: ✅ approved via leela:approved
• Zapp: ✅ approved via zapp:approved
• Nibbler: ✅ approved via nibbler:approved
• Docs: ✅ approved via docs:approved
  Active labels
• docs:approved — Docs review approved — user-facing docs updated or in-PR changeset landed
• leela:approved — Architecture review approved
• nibbler:approved — Code quality review approved
• zapp:approved — Security review approved

This sticky comment is maintained automatically so label-based squad review leaves an on-PR rationale even when the gate itself is status-check driven.

[github-actions]

Docs & changeset gate

• ✅ changeset added (.changeset/*.md)
• ℹ️ docs-site/docs/ not updated — consider updating if user-facing behavior or UI changed
• ℹ️ docs-site/docs/extending/api-endpoints.md not updated — consider updating if the API surface changed

Changeset present. Good.

---

Hard gate for user-facing package changes without docs or changeset. ✅ = done, ⚠️ = likely needed, ℹ️ = optional or bypassed.

[sabbour-squad-lead]

APPROVED: Bare-pack-name and type-alias coercion reuses shared validator per #1000 DP. 7 new tests all green. Zod trust boundary intact. Applying leela:approved label.

[github-actions]

✅ Leela recorded a architecture approved via leela:approved on head 7ad1635.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[github-actions]

✅ Docs recorded a documentation approved via docs:approved on head 7ad1635.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[sabbour-squad-lead]

Working as Zapp · Security Architect · see .squad/agents/zapp/charter.md

Security review — #1009 (AKS composition coercion)

I explicitly asked for fail-loud on ambiguous cases. This PR honours that.

Scope audit

coerceComponentForRegistry added as pre-processing inside validateAndSanitizeComponents. Reviewed the full helper + its tests.

Narrow-coercion invariants (all verified)

Invariant	Evidence
Coercion does ONLY type→component alias + unique-bare-pack-suffix resolution — nothing else	coerceComponentForRegistry has exactly two mutations (type→component when component absent; bare→qualified when exactly one match). No other transformations, no prop mutation, no schema relaxation.
Ambiguous bare names are NOT coerced (fail-loud)	buildBareNameIndex tracks collisions in ambiguous: Set<string>, calls index.delete(suffix) on first collision, and skips further collisions. Test 'does NOT coerce an ambiguous bare name (suffix shared across packs)' asserts _ErrorComponent is produced when AksClusterCard collides between aks/* and azure/*. ✅ fail-loud confirmed.
Unknown bare names are NOT coerced	bareNameIndex.get(next.component) returns undefined → falls through unchanged, validator rejects → _ErrorComponent.
Bare name that's already registered as a bare component wins (no silent aliasing to pack variant)	if (registry.getImpl(suffix)) continue; explicitly excludes such suffixes from the bare index. Test 'does not coerce a bare name when the bare form is itself registered (core wins)' confirms.
Zod gate is applied AFTER coercion	validateAndSanitizeComponents runs coerceComponentForRegistry(rawComp, bareNameIndex) first; the destructure + existing per-descriptor size guard + registry lookup + Zod parse path is unchanged downstream. Trust boundary intact.
_ErrorComponent fallback NOT relaxed	No change to the unknown-component branch; coercion only rewrites to a valid canonical name when unambiguous. Test envelope case with ambiguous suffix explicitly disambiguates manually and still relies on the existing reject path otherwise.
Log hygiene — name-only, never payload	No new console.* / logger calls added in the coercion helper or in the new validator prelude. Existing validator logs (which vi.spyOn(console, 'error') mocks in tests) are unchanged, and those existing logs emit the component name only. No payload / prop leakage introduced.

Standard PR-gate sweep

Check	Result
dangerouslySetInnerHTML / eval / new Function	✅ None.
External URL fetches	✅ None.
New workflow permissions / secrets	✅ None.
Schema/Zod weakening	✅ None — coercion is purely a key-rename step on the envelope shape, schema parse remains authoritative.

Minor observation (non-blocking)

coerceComponentForRegistry is exported. It's pure and the export is reasonable for test isolation. Fine.

Verdict

APPROVED (Security) ✅ — coercion is narrow, fail-loud on ambiguity, Zod gate intact, no log-hygiene regression.

[github-actions]

✅ Zapp recorded a security approved via zapp:approved on head 7ad1635.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[sabbour-squad-lead]

Working as Nibbler · see .squad/agents/nibbler/charter.md

Verdict: APPROVED ✅

Narrow, disciplined fix for #996. coerceComponentForRegistry is pre-processing for the existing validateAndSanitizeComponents trust boundary — it does not fork the validator, does not widen the schema contract, and declines to guess on ambiguity. The DP was "reuse, don't fork"; the diff delivers that.

✅ What I liked

• Coercion is narrow and reversible: only two rewrites (type → component when component is absent; bare → unique pack-qualified). Failure to normalise leaves the envelope untouched so the Zod rail still rejects garbage.
• Ambiguity guard is correct: buildBareNameIndex sees a second occurrence of a suffix → index.delete(suffix) + ambiguous.add(suffix) → subsequent occurrences skipped via ambiguous.has(...). Verified by the azure/AksClusterCard + aks/AksClusterCard test.
• Core-bare-wins invariant is explicit: if (registry.getImpl(suffix)) continue; — Button registered bare is never shadowed by aks/Button. Test does not coerce a bare name when the bare form is itself registered (core wins) pins it.
• Precedence is correct: explicit component beats legacy type alias. Test pins it.
• Test coverage matches the DP claim: the "coercion matrix" has all six cells covered (unique bare, ambiguous bare, legacy alias, component-over-type, already-qualified, bare-wins-over-pack) plus a realistic AKS composition-envelope regression guard that asserts zero _ErrorComponents.
• Clone-on-write via { ...comp } + changed flag — no hidden mutation of the caller's payload.
• Structured-log honesty preserved: the changeset explicitly notes "names only the offending component, never the surrounding composition payload" — matches #989/#1000 posture.

🟡 Concerns

1. Per-call rebuild of bareNameIndex: validateAndSanitizeComponents calls buildBareNameIndex(registry) once per payload. Cost is O(|registry names|) on every render — bounded, not a hotspot, but the registry is sealed (registry.seal()), so this is a memoisable pure function of the registry identity. WeakMap keyed on registry would make future large-pack additions cheap. Not blocking, but flag for #996-followup.

🟢 Nits

• if (!suffix) continue; guards name.endsWith('/'), which shouldn't occur in practice — fine as defence in depth.
• Docblock on coerceComponentForRegistry is excellent ("pre-processing for that validator, not a parallel validator") — please keep that comment intact through rebases.

No dead code, no silent catches, no ad-hoc as assertions in the coercion path, no new deep imports. The only any is inside a test spy (vi.spyOn(console, 'error')) which is unavoidable. Approving.

[github-actions]

✅ Nibbler recorded a code quality approved via nibbler:approved on head 7ad1635.

This native review mirrors the label-driven squad gate for visibility only.
Merge eligibility still comes from the squad/review-gate status check and the current approval labels.

[sabbour-squad-scribe]

Working as Scribe · see .squad/agents/scribe/charter.md

Retro entry

- 2026-04-21 | #1009 "fix(web): coerce AKS composition outputs so the shared validator resolves them (#996)" | M | impl=1m | review=12m | cycles=1 | merged | @sabbour-squad-backend[bot] | first_review=8m | ci=6m | reviewer=bot | human_comments=0 | issue=#996 | estimate=M | rejections_by_reviewer=nibbler:0,leela:0,zapp:0 | reverted=false

Queued via retro-log PR #1002: #1002
This update will land in .squad/retro-log.md after that PR merges.