45 sample contract

[ajtritt]

Close #45

Summary

dataset_contract.yaml is a plain dict validated by explicit checks (matching the config.yaml pattern in session.py), not a dataclass hierarchy — consistent with this codebase's existing schema style. No MCP tool or skill consumes the contract yet.

Code changes

• src/dsagt/contract.py (new): the sample-contract schema. validate_contract() checks sample keys (dtype, shape with symbolic dims, value range, role), per-key collation, split policy (strategy, group key, seed, ratios), the normalization-ownership flag, the pipeline fingerprint (required in mode: pipeline, forbidden in mode: standalone), and the reconciliation section (producer/consumer/resolution per key, key must be declared). load_contract() / save_contract() read and write <project>/dataset_contract.yaml, validating on both ends. Each closed-vocabulary constant (VALID_MODES, VALID_ROLES, VALID_NORMALIZATION_OWNERS, VALID_SPLIT_STRATEGIES) carries a comment defining what every one of its values means — the enum names alone weren't documentation, and that was a real gap in the first pass of this PR.
• src/dsagt/provenance.py: added compute_pipeline_fingerprint(), hashing only dependency_graph and terminal_outputs from a reconstruct_pipeline(fmt="json") payload — never records, so timestamps/stdout/exit codes that vary rerun to rerun don't perturb the hash. Updated the module docstring's pipeline-reconstruction summary to mention the JSON format (from Structured output format for reconstruct_pipeline #44) and the fingerprint.
• docs/dataset-contract.md (new): documents the schema, a field reference defining what each enum value means (mode, keys.<name>.role, normalization.owner, split.strategy), and both worked examples — a tabular case (standalone mode, group split by patient) and the XGC graph case from use_cases/fusion-fm/skills/xgc-ai-training/scripts/xgc_dataset.py (pipeline mode, symbolic N/E dims, PyG graph collation, split grouped by phi-plane). Added to the mkdocs nav under Capabilities.
• CLAUDE.md: added contract.py to the module list.
• tests/test_contract.py (new): both worked examples validated and round-tripped through disk; failure cases for every schema rule (missing version, bad mode, fingerprint required/forbidden by mode, empty keys, missing dtype, bad role, non-int/symbolic shape entry, bad normalization owner, bad split strategy, missing group_key, ratios not summing to 1, reconciliation referencing an undeclared key, missing reconciliation field); save_contract doesn't write the file when validation fails.
• tests/test_pipeline.py: added TestComputePipelineFingerprint — stable across a simulated rerun with different timestamps/stdout/exit code, changes when a step is added, changes when a step is removed, changes when an output path is renamed, and unaffected by noisy stdout/return_code mutations that don't touch the dependency graph or terminal outputs.