Sample-contract schema and persisted artifact

[ajtritt]

Part of #43.

Define the YAML schema for a sample contract, the pivot artifact the whole dataset builder derives from.

The file is written to <project>/dataset_contract.yaml, at the project root rather than under .dsagt/, because it is a user-facing artifact the scientist is expected to read and sign off on, whereas .dsagt/ holds server-owned state most users never inspect.

Scope

• Fields: sample keys with dtype, shape (including symbolic dimensions such as N for a variable node count), value range, semantic role (input, target, mask, metadata); collation rule per key; split policy including grouping key and seed; the normalization ownership flag (whether a pipeline step already normalized, or __getitem__ must).
• The pipeline fingerprint: a hash over the terminal outputs and the dependency graph from the structured reconstruct_pipeline output (Structured output format for reconstruct_pipeline #44), used by the staleness check in the check-dataset code. Absent in standalone mode, where there is no pipeline to fingerprint.
• A worked example for a tabular case and a worked example for the XGC graph case (use_cases/fusion-fm/skills/xgc-ai-training/scripts/xgc_dataset.py), confirming the schema expresses both.
• The reconciliation section recording consumer-side versus producer-side differences and how the adapter resolves each: dtype casts, channel layout, normalization ownership, padding and ragged handling, label encoding.

Acceptance criteria

• Schema documented with both worked examples.
• The fingerprint is stable across reruns of an unchanged pipeline and changes when a step is added, removed, or has its output paths altered.

Blocks

Everything that consumes the contract: the check-dataset code, the dataset-builder skill, the package scaffolder, and the reference model.