sbx-kits/usai-provider-kit/spec.yaml claims schemaVersion 2 but uses hybrid/v1 field names — fails sbx kit inspect on a clean repro

[wz-gsa]

Summary

integrations/isolation/sbx-kits/usai-provider-kit/spec.yaml declares schemaVersion: "2" (sbx's own native schema) but uses caps/commands — the neutral vocabulary that later became known as hybrid/v1 (introduced in PR #221, after this kit's own authorship in #191/#216 — confirmed via git log, this kit predates the hybrid/v1 split existing as a distinct, named thing to confuse it with). Real sbx (confirmed on the current latest, v0.43.0) rejects the file outright when inspected directly.

Repro (minimal, isolated — no acq, no translation layer involved)

schemaVersion: "2"
kind: mixin
name: v2-shape-repro
displayName: v2 Shape Repro
description: minimal repro
caps:
  network:
    allow:
      - example.com
commands:
  startup:
    - description: test
      user: "1000"
      command: [sh, -c, "echo hi"]

$ sbx kit inspect <dir-with-above>
ERROR: artifact: invalid spec.yaml: yaml: unmarshal errors:
  line 6: field caps not found in type spec.specFileV2
  line 10: field commands not found in type spec.specFileV2

Same result against the real file:

$ sbx kit inspect integrations/isolation/sbx-kits/usai-provider-kit
ERROR: artifact: invalid spec.yaml: yaml: unmarshal errors:
  line 42: field caps not found in type spec.specFileV2
  line 49: field commands not found in type spec.specFileV2

Why this matters

spec.specFileV2's real schema does not use caps/commands as field names (confirmed by the error itself: those two names are simply not recognized on a schemaVersion: "2" file). This means the kit has likely never been directly inspectable/validatable via sbx kit inspect since it was written — its only real-world path to functioning at all is whatever acq's own kit-resolution layer does with it, bypassing sbx's own native schema validation entirely. That is exactly the kind of silent, unverified assumption that has produced several other drift/staleness bugs found this session (patterns#417's catalog drift, quickstart#470's git-identity YAML shape) — this one is a step further: not drift between two artifacts, but a file that may have never matched its own declared schema version in the first place.

Cross-references

• Related, same root-cause class as GSA-TTS/agentic-coding-quickstart#470 (a different sbx-schema-shape mismatch, in acq's own hand-written git-identity mixin generator).
• Directly relevant to the standing retirement discussion for this exact kit: GSA-TTS/agentic-coding-patterns#273 / GSA-TTS/agentic-coding-quickstart#235 ("safe to retire sbx-kits/usai-provider-kit once acq can translate the acq-kits/usai-provider hybrid/v1 kit directly for the sbx backend"). This finding is additional evidence for that retirement: if the legacy kit's own spec.yaml doesn't validate against sbx's real native schema at all, its value as a "native sbx kit" fallback is questionable regardless of the retirement epic's own timeline.

Suggested fix (if NOT retiring the kit outright)

Either:

1. Rewrite spec.yaml using sbx v2's actual native field names (whatever spec.specFileV2 really expects — needs investigation against sbx's own real schema/docs), or
2. Change schemaVersion to whatever value correctly identifies this as a hybrid/v1-shaped file (if sbx supports resolving that version string directly, rather than only via acq's translation layer).

Given the retirement discussion above, option 3 — retire the kit per #273/#235 rather than fix its schema — may be the more efficient path; this issue documents the evidence, not a prescribed fix.

Environment

• sbx version: v0.43.0 (79805a6e3c6667520dc2da4f6bdeddae9b700969) — just upgraded from 0.42.1 via brew upgrade docker/tap/sbx while investigating this.

[wz-gsa]

This is already tracked for the right fix: #275 ("Phase 4 cleanup: remove the vestigial sbx-kits/ redirect", owned by @mogul) documents that sbx-kits/ is a byte-identical dupe of acq-kits/, nothing live consumes it (confirmed: quickstart pins only acq-kits/), and the one-release redirect window is long past (patterns is at v1.9+; the redirect landed ~v1.2.0).

This issue's own finding is additional evidence for that removal, not a reason to patch the redirect's schema: a file that was apparently never validated against sbx's real native schema in the first place has essentially zero value as a "native sbx fallback." Fixing its schemaVersion/field names just makes a soon-to-be-deleted dupe technically valid — not worth the effort vs. deleting it outright per #275.

I confirmed independently (live against real sbx v0.43.0, while investigating GSA-TTS/agentic-coding-quickstart#470) that spec.specFileV2's real install-command shape has no env field at all, which is consistent with this file's field-name mismatch being a genuine "never validated" gap rather than a version-drift issue.

Recommend closing this as subsumed by #275 rather than fixing in place — deferring to @mogul on #275's timing since he's driving that cleanup.