fix(data ingest): preflight & message polish — schema-type validation, friendly missing-label, help copy, clearer errors (#213 #214 #215 #76)

[LukasWodka]

What

Four small, independent polish fixes to the data ingestlocal gate + its error messages, bundled into one review. Each closes a backlog ticket from the 2026-07-11 triage; all four sit in the same files (data.go / push / schema) and share one review + CI cycle.

#213 — validate --schema TYPE tokens locally. A bogus type (age:BANANA) used to pass every local check and only fail in-cluster. ParseSchema now validates the base type against the ingestor's real accepted set — acceptedSQLBaseTypes is a byte-exact mirror of data-ingestors database.py::_get_sqlalchemy_type (di#349, the source of truth), with sqlBaseType mirroring the ingestor's upper/strip/split-( extraction. Also closes the same false-green on the data validate YAML path (reusing the exported ValidateSchemaType so the two paths can't diverge) and fixes a pre-existing ParseSchema comma-split bug that tore DECIMAL(p,s)/NUMERIC(p,s) — types the ingestor accepts.

#214 — name the missing --label-column. Omitting --label-column on a tabular task used to dump a cryptic label: got string, want object … oneOf schema error. A targeted pre-check now returns a friendly exit-2 message naming --label-column and listing the inferred columns. Only the missing case is intercepted — a present-but-wrong label still flows to CheckLabelColumn, and all other schema errors still surface normally.

#215 — derived help copy. The ingest help hardcoded "Supports 9 tasks" (stale) and put the MLM example under a texts/ folder while the wired layout needs sequences/. Both are now derived — the count from push.SupportedCategoryIDs() (renders 15) and the text-family sidecar from the vendored layout contract — so they can't drift again.

#76 — clearer validation messages.

• (a) data delete "" pointed at --name, a flag delete doesn't have (it takes a positional arg). Now: "pass it as an argument: tracebloc data delete <dataset>".
• (b) --number-of-keypoints 0 (or negative) claimed you hadn't passed the flag. Now distinguishes unset ("requires …") from set-but-invalid ("must be a positive integer (got 0)"), via cmd.Flags().Changed.
• (c) A bad --label-policy leaked label: got object, want string above the real label.policy: value must be one of …. The generic oneOf type-noise is now suppressed when a more specific child error exists.

Deliberately NOT included: #77

#77 ("task-irrelevant flags silently ignored") was in the triage bundle but is dropped here on purpose: PR #224 (merged to develop 2026-07-10) already hard-rejects misapplied task flags with exit 2, so the original "silent" bug is gone. Whether to keep that hard-reject or soften it to a warn (Principle 6: the CLI drops the flag from the synthesized spec, so the ingestor would accept the run) is a design decision parked for @LukasWodka — this PR leaves #224's behavior untouched.

Tests / gates

• Adversarially reviewed: all four verified correct against the ingestor source of truth, no regressions to the happy path or sibling tasks. One test-vacuousness nit on data ingest/delete: misleading validation error messages (delete '(set --name)' on a positional arg, keypoints 0/neg, --label-policy type-noise) #76(c) — its live-schema assertion depends on the current jsonschema/v6 leaf wording; the hardcoded-string unit test TestSuppressOneOfTypeNoise still pins the filter, so coverage isn't lost.
• go build ./... / go vet ./... OK; gofmt -l clean; go test ./... green; coverage-floor.sh: internal/cli 74.4% ≥ 68%, internal/submit 76.1% ≥ 72%.

Closes#213#214#215#76.

🤖 Generated with Claude Code

---

Note

Low Risk
CLI-only validation and messaging in preflight paths; behavior mirrors existing ingestor rules and is covered by new tests, with no auth or cluster workflow changes.

Overview
This PR bundles local preflight and error-message polish for data ingest, data validate, and data delete—no change to cluster staging or submit behavior.

Schema types (#213) — --schema and YAML schema blocks now reject unsupported SQL base types using the same vocabulary as the ingestor (ValidateSchemaType / acceptedSQLBaseTypes). data validate adds schemaTypeViolations so bogus types like BANANA fail locally instead of after upload. ParseSchema also splits on commas only outside parentheses so DECIMAL(10,2) stays one entry.

Tabular missing label (#214) — Omitting --label-column on tabular/time-series tasks returns a short message naming the flag and listing inferred CSV columns, instead of a raw label oneOf schema dump.

Ingest help (#215) — Task count and text sidecar names in data ingest long help come from SupportedCategoryIDs() and TextSidecarDir (e.g. sequences/ for masked language modeling), not hardcoded copy.

Misc (#76) — data delete "" points at the positional argument; keypoint errors distinguish unset --number-of-keypoints from an explicit invalid value via ChangedFlags; schema validation suppresses parent-level got X, want Y oneOf noise when a nested path (e.g. label.policy) already reports the real issue.

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