Phase 1: embed ingest.v1.json + tracebloc ingest validate

[saadqbal]

Summary

Phase 1 of the v0.1 roadmap (tracebloc/client#147). Brings the cluster's jobs-manager schema validation onto the customer's workstation: a customer can run tracebloc ingest validate ./my-ingest.yaml and get the same error messages jobs-manager would emit, but locally and in milliseconds.

What lands

• scripts/sync-schema.sh — pulls ingest.v1.json from tracebloc/data-ingestors master into internal/schema/ingest.v1.json. --check mode exits non-zero on drift; wired into CI as a new schema-drift job so silent divergence between the CLI's view and the canonical schema becomes a PR-blocking signal.
• internal/schema/ — embedded schema bytes + a Validator that compiles once and validates many. Walks the jsonschema/v6 error tree to produce a flat []ValidationError{Path, Message} whose output format matches tracebloc_ingestor.cli.run._format_errors byte-for-byte (so customer-facing wording stays uniform across the two validator implementations).
• internal/cli/ingest.go — tracebloc ingest validate <path> subcommand. Three exit codes: 0 ok, 2 schema violations (printed to stderr), 3 file/parse problems.
• internal/cli/exit.go — exitError type + ExitCodeFromError helper for subcommand → main() exit-code propagation. Wired through cmd/tracebloc/main.go.

Test plan

• 23 new test cases across 2 files, all green locally. Coverage: internal/schema 80%, internal/cli 88%.
• Happy path across 6 categories (image, OD, semantic seg, text, tabular classification, tabular regression-with-bucket-policy)
• 5 negative-case schema rules (missing required, enum mismatch, image-category-without-images, regression-without-policy, tabular-without-schema)
• 4 parse-failure modes (empty, whitespace, top-level sequence, malformed YAML)
• Format contract pin (FormatErrors output shape)
• CLI dispatch + exit-code tests
• scripts/sync-schema.sh --check passes against current master of data-ingestors

Library choices

• github.com/santhosh-tekuri/jsonschema/v6 — the standard Go JSON Schema impl, supports draft-07 (which ingest.v1.json targets). One footgun: ErrorKind.LocalizedString(nil) segfaults inside golang.org/x/text (likely a library bug). Worked around defensively with a package-level English *message.Printer.
• golang.org/x/text pinned to v0.16.0 — Go 1.22-compatible. The latest text v0.37 requires Go 1.25 which would force the module's minimum version up.

Customer-facing UX (preview)

$ tracebloc ingest validate ./bad.yaml
./bad.yaml: schema validation failed (1 issue)
<root>: missing properties 'apiVersion', 'intent'
$ echo$?
2
$ tracebloc ingest validate ./good.yaml
./good.yaml: ok
$ echo$?
0

Closes

tracebloc/client#149

Next phase

Phase 2 (tracebloc/client#150) — cluster discovery via kubeconfig + ingestor SA token via TokenRequest. That unlocks the actual tracebloc dataset push flow (Phases 3 + 4).

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new user-facing validation command with custom exit-code/error-printing behavior and introduces JSON Schema/YAML parsing dependencies, which could affect CLI UX and error handling edge cases. Also adds a CI drift gate that may block PRs if the upstream schema changes unexpectedly.

Overview
Adds offline ingestion config validation via tracebloc ingest validate, backed by an embedded ingest.v1.json JSON Schema and a validator that formats violations consistently and returns distinct exit codes for schema vs file/parse errors.

Updates process-level error handling so cobra-silenced errors are still surfaced (while allowing handlers to opt into silent errors) and propagates command-specific exit codes from main().

Introduces scripts/sync-schema.sh plus a new CI schema-drift job and Makefile targets to keep the embedded schema in sync with tracebloc/data-ingestors, alongside updated contributor docs and new Go module dependencies (jsonschema/v6, yaml.v3, x/text).

^{Reviewed by Cursor Bugbot for commit d2cbee1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

👋 Heads-up — Code review queue is at 18 / 8

Above the WIP limit. The team convention is to review existing PRs before opening new work.

Open PRs currently in Code review (oldest first):

• client-runtime#36 — Bump requests from 2.32.3 to 2.33.0 in /Node-deploy · author: @dependabot · no reviewer assigned
• client-runtime#37 — Bump black from 25.1.0 to 26.3.1 in /Node-deploy · author: @dependabot · no reviewer assigned
• client-runtime#38 — Bump requests from 2.32.3 to 2.33.0 · author: @dependabot · no reviewer assigned
• client-runtime#39 — Bump black from 25.1.0 to 26.3.1 · author: @dependabot · no reviewer assigned
• data-ingestors#108 — Copy tokenizer.json to training pod for MLM datasets · author: @shujaatTracebloc · reviewer: @saadqbal
• design-system#19 — fix: un-track coverage/ and node_modules/ from git · author: @LukasWodka · no reviewer assigned
• docs#3 — Block bots from crawling Mintlify static assets · author: @LukasWodka · reviewer: @saadqbal
• model-zoo#74 — Add 9 MLM model variants and remove warmstart · author: @shujaatTracebloc · reviewer: @divyasinghds
• tracebloc-client#296 — chore(deps): bump ray from 2.44.1 to 2.55.0 in /use_cases · author: @dependabot · no reviewer assigned
• tracebloc-client#300 — feat(nlp): add token classification use case (shape Promote kubeconfig flags (--kubeconfig/--context/--namespace) to persistent on root #3) · author: @shujaatTracebloc · reviewer: @saadqbal, @divyasinghds

Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 42d9f75. Configure here.}