Skip to content

feat(schema): publish Verdict v1.0-rc1 envelope schema#351

Merged
trilamsr merged 3 commits into
mainfrom
feat/verdict-schema-v1-rc1
Jun 1, 2026
Merged

feat(schema): publish Verdict v1.0-rc1 envelope schema#351
trilamsr merged 3 commits into
mainfrom
feat/verdict-schema-v1-rc1

Conversation

@trilamsr

@trilamsr trilamsr commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Publishes the v1.0-rc1 Verdict envelope schema and the lock test that
keeps every shipped detector honest against it. Closes v1-rc1 cut
criterion 2.

  • docs/schemas/verdict-1.0.0-rc1.json — canonical envelope (draft
    2020-12). $id: https://schema.tracecore.io/verdict/1.0.0-rc1.json
    (matches the CDN URL third-party SDKs key off). Required envelope
    fields: pattern.id, headline, remediation, evidence_trail.
    Optional: confidence, missing_layers. additionalProperties: true
    so per-pattern fields (gpu_id, xid_code, kind, ...) validate
    without re-listing here.
  • module/pkg/patterns/verdict_envelope_schema_test.go — three test
    groups: (1) every shipped Verdict (8 patterns: pod_evicted,
    nccl_hang, xid_correlation, hbm_ecc, thermal_throttle,
    pcie_aer, cuda_oom, ib_link_flap) round-trips through the
    published artifact; (2) ten envelope-drift falsifiers reject; (3)
    $id pinned literally — drift surfaces immediately.
  • docs/schemas/README.md — inventory + versioning policy (patch /
    minor / major SemVer semantics, when to bump, how a new pattern
    adds itself) cross-linked to the forthcoming docs/DEPRECATION.md
    (criterion 4).
  • docs/ATTRIBUTES.md — cross-link from the pattern.verdict_json
    column to the envelope.
  • docs/v1-rc1-cut-criteria.md — criterion 2 flipped ☐ → ☑ with
    **Landed:** pointer.

Design choice: envelope vs per-pattern split

The envelope is the union-superset of fields every pattern emits.
Per-pattern testdata schemas under
module/pkg/patterns/testdata/<pattern>_verdict.schema.json continue
to pin pattern-specific shape with additionalProperties: false.
Drift in envelope-level fields surfaces on the envelope test; drift
in pattern-specific fields surfaces on the per-pattern schema. The
per-pattern schemas were intentionally not rewritten to use
$ref against the envelope — the Go-side test is the load-bearing
conformance path, and a $ref rewrite would add resolution
complexity without bite. Documented in docs/schemas/README.md.

TDD

Two commits, RED → GREEN, kept separate per the loop discipline.

  • 670d19e test(schema): RED v1.0-rc1 envelope test suite — fails
    with no such file or directory on the schema artifact path.
  • 9f7a4a8 feat(schema): publish Verdict v1.0-rc1 envelope schema
    artifact + docs land; test goes green.

Test plan

  • cd module && go test ./pkg/patterns/... -count=1 clean
  • cd module && go test ./pkg/patterns/... -race clean
  • cd module && go vet ./... clean
  • bash scripts/attribute-namespace-check.sh clean (82/82)
  • bash scripts/doc-check.sh clean (no dead links)
  • CI green on all required checks
**Cut criterion 2 closed: Verdict v1.0-rc1 envelope schema published.**

The canonical Verdict envelope schema ships at
`docs/schemas/verdict-1.0.0-rc1.json` (draft 2020-12, `$id`
`https://schema.tracecore.io/verdict/1.0.0-rc1.json`). Every shipped
pattern detector — `pod_evicted`, `nccl_hang`, `xid_correlation`,
`hbm_ecc`, `thermal_throttle`, `pcie_aer`, `cuda_oom`, `ib_link_flap`
— emits Verdicts that round-trip through the envelope, enforced by
`module/pkg/patterns/verdict_envelope_schema_test.go`. External
verdict-consumption SDKs (criterion 12, forthcoming) pin to this
`$id`. Versioning + evolution policy at `docs/schemas/README.md`.

Tri Lam added 2 commits June 1, 2026 02:01
Adds verdict_envelope_schema_test.go pinning cut-criterion-2 contract
before the artifact lands: schema loadable from docs/schemas/verdict-
1.0.0-rc1.json, every shipped Verdict round-trips through it, ten
envelope-drift falsifiers reject, and $id matches the published CDN
URL contract for external SDK pinning.

Fails with file-not-found until the schema artifact is published.

Signed-off-by: Tri Lam <tri@maydow.com>
Publishes docs/schemas/verdict-1.0.0-rc1.json — the canonical Verdict
envelope every pattern detector emits. Per-pattern detectors layer
pattern-specific fields on top (gpu_id, xid_code, kind, …); per-pattern
testdata schemas pin those extensions. Envelope sets additionalProperties
true so per-pattern fields validate without re-listing here.

Closes v1-rc1 cut criterion 2:
- Schema at docs/schemas/verdict-1.0.0-rc1.json, draft 2020-12, $id
  https://schema.tracecore.io/verdict/1.0.0-rc1.json (matches the CDN
  contract third-party SDKs key off).
- Envelope-conformance + ten drift-falsifier rows already landed RED
  in the prior commit; this commit makes them GREEN.
- docs/schemas/README.md documents versioning + evolution policy and
  cross-links the forthcoming docs/DEPRECATION.md (criterion 4).
- docs/ATTRIBUTES.md cross-links the envelope from the
  pattern.verdict_json column.
- docs/v1-rc1-cut-criteria.md flips criterion 2 from planned to
  shipped with a Landed pointer.

Signed-off-by: Tri Lam <tri@maydow.com>
@trilamsr

trilamsr commented Jun 1, 2026

Copy link
Copy Markdown
Contributor Author

Addressed reviewer BLOCKERS in 2748007:

🔴 Fixed (3):

  1. Added SilentDataCorruptionVerdict fixture to TestVerdictEnvelopeV1RC1_AllShippedVerdictsValidate (now 9 patterns round-trip, including pattern [general] M1.6 hardening: lint + coverage + panic recovery + pipelinebuilder #13 from feat(sdc): pattern-13 silent data corruption detector #344).
  2. Added hw_gpu_sdc + gen_ai_training_eval_accuracy to evidence_trail[].kind enum in docs/schemas/verdict-1.0.0-rc1.json (canonical wire strings from module/pkg/patterns/silent_data_corruption.goEvidenceKindHwGPUSDC and EvidenceKindEvalAccuracy).
  3. $id switched to https://github.com/TraceCoreAI/tracecore/main/docs/schemas/verdict-1.0.0-rc1.json (resolves immediately, no infra needed). Brand-owned schema.tracecore.io CDN goal tracked as [infra] publish verdict schema to schema.tracecore.io CDN #354.

Root cause note: BLOCKERS 1 + 2 both trace to pattern #13 landing (#344) after this PR's RED commit was authored — fixture coverage didn't rebase forward. BLOCKER 3 traces to an aspirational $id URL pointing at infrastructure that doesn't exist.

🟡 Acknowledged: additionalProperties asymmetry between envelope (true) and per-pattern (false) is documented in docs/schemas/README.md as the dual-validation contract; SDKs must validate both layers. Future v1.0 GA may flip envelope to strict.

❓ Resolved: SDKs (criterion 12) ship with embedded schema copy, so $id remote fetch is nice-to-have not required for SDK functionality.

Validation:

  • cd module && go test ./pkg/patterns/... -run Verdict → clean (9 patterns round-trip; TestVerdictEnvelopeV1RC1_HasStableID pins the new raw github URL)
  • go vet ./... → clean
  • Pre-commit hooks (golangci-lint + attribute-namespace-check + autoupdate-check) → all green

@trilamsr trilamsr merged commit ec42a78 into main Jun 1, 2026
15 checks passed
@trilamsr trilamsr deleted the feat/verdict-schema-v1-rc1 branch June 1, 2026 09:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant