{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://homecastr.com/schemas/homecastr-data-contracts.v1.json",
  "title": "Homecastr canonical data contracts",
  "description": "Versioned contracts shared by files, REST, MCP, OpenAPI, documentation, and SDKs. Access policy determines whether a conforming record is public, authenticated, restricted, metadata-only, or unavailable.",
  "oneOf": [
    { "$ref": "#/$defs/DatasetAsset" },
    { "$ref": "#/$defs/SourceInventory" },
    { "$ref": "#/$defs/PublicRecordsAcquisition" },
    { "$ref": "#/$defs/SourceSnapshot" },
    { "$ref": "#/$defs/PanelLineage" },
    { "$ref": "#/$defs/DataCoverageSummary" },
    { "$ref": "#/$defs/Observation" },
    { "$ref": "#/$defs/FeatureRecord" },
    { "$ref": "#/$defs/PanelRow" },
    { "$ref": "#/$defs/ForecastSeries" },
    { "$ref": "#/$defs/ForecastVintage" },
    { "$ref": "#/$defs/BenchmarkResult" },
    { "$ref": "#/$defs/ProvenanceManifest" },
    { "$ref": "#/$defs/AccessPolicy" },
    { "$ref": "#/$defs/ArtifactManifest" },
    { "$ref": "#/$defs/SyntheticRecord" },
    { "$ref": "#/$defs/OperationalRecord" },
    { "$ref": "#/$defs/ProductEvent" },
    { "$ref": "#/$defs/ModelArtifact" }
  ],
  "$defs": {
    "ContractMetadata": {
      "$id": "hc.contract_metadata.v1",
      "type": "object",
      "required": ["schema_id", "schema_version", "record_id", "asset_id", "data_snapshot_id", "created_at"],
      "properties": {
        "schema_id": { "type": "string", "pattern": "^hc\\.[a-z0-9_]+\\.v[0-9]+$" },
        "schema_version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
        "record_id": { "type": "string", "minLength": 1 },
        "asset_id": { "type": "string", "minLength": 1 },
        "data_snapshot_id": { "type": "string", "minLength": 1 },
        "created_at": { "type": "string", "format": "date-time" },
        "provenance_id": { "type": ["string", "null"] },
        "access_policy_id": { "type": ["string", "null"] }
      }
    },
    "EntityReference": {
      "$id": "hc.entity_reference.v1",
      "type": "object",
      "required": ["entity_type", "entity_id"],
      "properties": {
        "entity_type": {
          "type": "string",
          "enum": ["address", "parcel", "unit", "building", "h3", "tabblock", "tract", "zcta", "zip3", "county", "state", "metro", "planning_area", "country", "global_cell", "organization", "model", "dataset"]
        },
        "entity_id": { "type": "string", "minLength": 1 },
        "id_namespace": { "type": ["string", "null"] },
        "parent_entity_ids": { "type": "array", "items": { "type": "string" } },
        "geometry_id": { "type": ["string", "null"] },
        "geography_vintage": { "type": ["string", "null"] }
      },
      "additionalProperties": false
    },
    "TimeReference": {
      "$id": "hc.time_reference.v1",
      "type": "object",
      "required": ["period_start", "period_end", "available_at"],
      "properties": {
        "event_time": { "type": ["string", "null"], "format": "date-time" },
        "period_start": { "type": "string", "format": "date-time" },
        "period_end": { "type": "string", "format": "date-time" },
        "available_at": { "type": "string", "format": "date-time" },
        "published_at": { "type": ["string", "null"], "format": "date-time" },
        "retrieved_at": { "type": ["string", "null"], "format": "date-time" },
        "as_of_date": { "type": ["string", "null"], "format": "date" },
        "source_vintage": { "type": ["string", "null"] }
      },
      "additionalProperties": false
    },
    "MetricReference": {
      "$id": "hc.metric_reference.v1",
      "type": "object",
      "required": ["metric_id", "value_kind", "unit"],
      "properties": {
        "metric_id": { "type": "string", "minLength": 1 },
        "target_family": { "type": ["string", "null"] },
        "value_kind": { "type": "string", "enum": ["count", "currency", "index", "percent", "probability", "rate", "area", "distance", "duration", "category", "text", "boolean", "geometry", "embedding"] },
        "unit": { "type": "string", "minLength": 1 },
        "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$" },
        "price_basis": { "type": ["string", "null"] },
        "aggregation": { "type": ["string", "null"], "enum": ["sum", "mean", "median", "min", "max", "first", "last", "weighted_mean", "mode", "none", null] },
        "seasonal_adjustment": { "type": ["string", "null"] }
      },
      "additionalProperties": false
    },
    "DatasetAsset": {
      "$id": "hc.dataset_asset.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "title", "asset_class", "support_levels", "canonical_contracts", "access_policy"],
          "properties": {
            "record_type": { "const": "dataset_asset" },
            "title": { "type": "string" },
            "description": { "type": ["string", "null"] },
            "asset_class": { "type": "string" },
            "support_levels": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "target_families": { "type": "array", "items": { "type": "string" } },
            "canonical_contracts": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "release_phase": { "type": ["string", "null"] },
            "public_status": { "type": "string", "enum": ["launch", "draft", "metadata_only", "hold", "not_public"] },
            "access_policy": { "$ref": "#/$defs/AccessPolicy" },
            "formats": { "type": "array", "items": { "type": "string", "enum": ["json", "jsonl", "csv", "parquet", "geojson", "mvt", "pmtiles"] } },
            "links": { "type": "object", "additionalProperties": { "type": "string" } }
          }
        }
      ]
    },
    "SourceSnapshot": {
      "$id": "hc.source_snapshot.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "source_id", "retrieved_at", "content_hash", "storage_uri", "license_status", "raw_immutability"],
          "properties": {
            "record_type": { "const": "source_snapshot" },
            "source_id": { "type": "string" },
            "source_url": { "type": ["string", "null"], "format": "uri" },
            "retrieved_at": { "type": "string", "format": "date-time" },
            "published_at": { "type": ["string", "null"], "format": "date-time" },
            "content_hash": { "type": "string" },
            "hash_algorithm": { "type": "string", "default": "sha256" },
            "storage_uri": { "type": "string" },
            "media_type": { "type": ["string", "null"] },
            "byte_size": { "type": ["integer", "null"], "minimum": 0 },
            "license_status": { "type": "string" },
            "terms_snapshot_uri": { "type": ["string", "null"] },
            "raw_immutability": { "const": "append_only" }
          }
        }
      ]
    },
    "SourceInventory": {
      "$id": "hc.source_inventory.v1",
      "type": "object",
      "required": ["source_id", "source_name", "source_family", "source_status", "panel_status", "official_urls", "license_status", "sensitivity", "geography", "resolution", "public_readiness", "training_eligibility", "provenance_id", "evidence_file"],
      "properties": {
        "source_id": { "type": "string" },
        "source_name": { "type": "string" },
        "source_family": { "type": "string" },
        "source_group": { "type": "string" },
        "source_tier": { "type": "string" },
        "source_status": { "type": "string" },
        "panel_status": { "type": "string" },
        "authority": { "type": "string" },
        "official_url": { "type": ["string", "null"] },
        "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } },
        "license_status": { "type": "string" },
        "sensitivity": { "type": "string", "enum": ["low", "medium", "high"] },
        "geography": { "type": "string" },
        "resolution": { "type": "string" },
        "cadence": { "type": "string" },
        "temporal_start": { "type": ["string", "null"] },
        "temporal_end": { "type": ["string", "null"] },
        "format": { "type": "string" },
        "raw_retention": { "type": "string" },
        "normalization": { "type": "array", "items": { "type": "string" } },
        "panels": { "type": "array", "items": { "type": "string" } },
        "targets": { "type": "array", "items": { "type": "string" } },
        "public_readiness": { "type": "string" },
        "training_eligibility": { "type": "string", "enum": ["benchmark_only", "consumer_feed", "training_candidate", "holdback"] },
        "provenance_id": { "type": "string" },
        "evidence_file": { "type": "string" },
        "notes": { "type": "string" },
        "access": { "$ref": "#/$defs/DataAccessSummary" },
        "_links": { "type": "object", "additionalProperties": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "DataAccessSummary": {
      "$id": "hc.data_access_summary.v1",
      "type": "object",
      "required": ["visibility", "support_level", "sensitivity", "training_eligibility", "license_status"],
      "properties": {
        "visibility": { "type": "string", "enum": ["public", "metadata_only", "restricted", "unavailable"] },
        "support_level": { "type": "string" },
        "sensitivity": { "type": "string", "enum": ["low", "medium", "high"] },
        "training_eligibility": { "type": "string", "enum": ["benchmark_only", "consumer_feed", "training_candidate", "holdback"] },
        "license_status": { "type": "string" }
      },
      "additionalProperties": false
    },
    "PanelLineage": {
      "$id": "hc.panel_lineage.v1",
      "type": "object",
      "required": ["panel_id", "panel_name", "source_id", "source_role", "join_keys", "join_method", "transform_id", "availability_rule", "output_fields", "status", "evidence_file"],
      "properties": {
        "panel_id": { "type": "string" },
        "panel_name": { "type": "string" },
        "source_id": { "type": "string" },
        "source_role": { "type": "string" },
        "join_keys": { "type": "array", "items": { "type": "string" } },
        "join_method": { "type": "string" },
        "transform_id": { "type": "string" },
        "availability_rule": { "type": "string" },
        "output_fields": { "type": "array", "items": { "type": "string" } },
        "status": { "type": "string" },
        "evidence_file": { "type": "string" },
        "source": {
          "type": ["object", "null"],
          "properties": {
            "source_name": { "type": "string" },
            "source_family": { "type": "string" },
            "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } },
            "public_readiness": { "type": "string" },
            "license_status": { "type": "string" }
          },
          "additionalProperties": false
        },
        "_links": { "type": "object", "additionalProperties": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "PublicRecordsAcquisition": {
      "$id": "hc.public_records_acquisition.v1",
      "type": "object",
      "required": ["lane_id", "source_family", "source_families", "geography", "geography_tokens", "current_status", "durable_cloud_evidence", "object_count", "byte_count", "public_route_evidence", "records_law_gate", "holdbacks", "next_step", "fold_in_source", "benchmark_role", "training_eligibility", "related_artifact_ids", "access", "_links"],
      "properties": {
        "lane_id": { "type": "string" },
        "source_family": { "type": "string" },
        "source_families": { "type": "array", "items": { "type": "string" } },
        "geography": { "type": "string" },
        "geography_tokens": { "type": "array", "items": { "type": "string" } },
        "current_status": { "type": "string" },
        "durable_cloud_evidence": { "type": "string" },
        "object_count": { "type": "string" },
        "byte_count": { "type": "string" },
        "public_route_evidence": { "type": "string" },
        "records_law_gate": { "type": "string" },
        "holdbacks": { "type": "string" },
        "next_step": { "type": "string" },
        "fold_in_source": { "type": "string" },
        "benchmark_role": { "type": "string" },
        "training_eligibility": { "enum": ["benchmark_only", "consumer_feed", "training_candidate", "holdback"] },
        "related_artifact_ids": { "type": "array", "items": { "type": "string" } },
        "access": {
          "type": "object",
          "required": ["visibility", "support_level", "sensitivity", "training_eligibility", "license_status"],
          "properties": {
            "visibility": { "type": "string" },
            "support_level": { "type": "string" },
            "sensitivity": { "type": "string" },
            "training_eligibility": { "enum": ["benchmark_only", "consumer_feed", "training_candidate", "holdback"] },
            "license_status": { "type": "string" }
          },
          "additionalProperties": false
        },
        "_links": { "type": "object", "additionalProperties": { "type": "string" } }
      },
      "additionalProperties": false
    },
    "DataCoverageSummary": {
      "$id": "hc.data_coverage_summary.v1",
      "type": "object",
      "required": ["source_count", "lineage_edge_count", "panel_count", "official_link_count", "missing_official_url_count", "source_coverage_index_count", "by_source_tier", "by_source_status", "by_source_family", "by_license_status", "by_geography", "by_resolution", "source_index", "map", "panels"],
      "properties": {
        "source_count": { "type": "integer", "minimum": 0 },
        "lineage_edge_count": { "type": "integer", "minimum": 0 },
        "panel_count": { "type": "integer", "minimum": 0 },
        "official_link_count": { "type": "integer", "minimum": 0 },
        "missing_official_url_count": { "type": "integer", "minimum": 0 },
        "source_coverage_index_count": { "type": "integer", "minimum": 0 },
        "by_source_tier": { "type": "object", "additionalProperties": { "type": "integer" } },
        "by_source_status": { "type": "object", "additionalProperties": { "type": "integer" } },
        "by_source_family": { "type": "object", "additionalProperties": { "type": "integer" } },
        "by_license_status": { "type": "object", "additionalProperties": { "type": "integer" } },
        "by_geography": { "type": "object", "additionalProperties": { "type": "integer" } },
        "by_resolution": { "type": "object", "additionalProperties": { "type": "integer" } },
        "source_index": {
          "type": "object",
          "required": ["record_count", "by_geometry_role", "by_native_boundary_status", "by_redistributable_geometry", "by_public_readiness", "by_training_eligibility"],
          "properties": {
            "record_count": { "type": "integer", "minimum": 0 },
            "by_geometry_role": { "type": "object", "additionalProperties": { "type": "integer" } },
            "by_native_boundary_status": { "type": "object", "additionalProperties": { "type": "integer" } },
            "by_redistributable_geometry": { "type": "object", "additionalProperties": { "type": "integer" } },
            "by_public_readiness": { "type": "object", "additionalProperties": { "type": "integer" } },
            "by_training_eligibility": { "type": "object", "additionalProperties": { "type": "integer" } }
          },
          "additionalProperties": false
        },
        "map": {
          "type": "object",
          "required": ["artifact_id", "data_snapshot_id", "region_count", "reference_boundary_count", "generalized_region_count", "source_count", "official_link_count", "by_geometry_role", "by_coverage_kind", "top_regions"],
          "properties": {
            "artifact_id": { "type": "string" },
            "data_snapshot_id": { "type": ["string", "null"] },
            "region_count": { "type": "integer", "minimum": 0 },
            "reference_boundary_count": { "type": "integer", "minimum": 0 },
            "generalized_region_count": { "type": "integer", "minimum": 0 },
            "source_count": { "type": "integer", "minimum": 0 },
            "official_link_count": { "type": "integer", "minimum": 0 },
            "by_geometry_role": { "type": "object", "additionalProperties": { "type": "integer" } },
            "by_coverage_kind": { "type": "object", "additionalProperties": { "type": "integer" } },
            "top_regions": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["region_id", "label", "coverage_kind", "geometry_role", "source_count", "official_link_count", "source_family_count", "panel_count", "reference_boundary_names", "source_index_href"],
                "properties": {
                  "region_id": { "type": "string" },
                  "label": { "type": "string" },
                  "coverage_kind": { "type": "string" },
                  "geometry_role": { "type": "string" },
                  "source_count": { "type": "integer", "minimum": 0 },
                  "official_link_count": { "type": "integer", "minimum": 0 },
                  "source_family_count": { "type": "integer", "minimum": 0 },
                  "panel_count": { "type": "integer", "minimum": 0 },
                  "reference_boundary_names": { "type": "array", "items": { "type": "string" } },
                  "source_index_href": { "type": "string" }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        "panels": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["panel_id", "panel_name", "source_count", "source_families", "source_tiers", "public_readiness"],
            "properties": {
              "panel_id": { "type": "string" },
              "panel_name": { "type": "string" },
              "source_count": { "type": "integer", "minimum": 0 },
              "source_families": { "type": "array", "items": { "type": "string" } },
              "source_tiers": { "type": "array", "items": { "type": "string" } },
              "public_readiness": { "type": "array", "items": { "type": "string" } }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "Observation": {
      "$id": "hc.observation.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "entity", "time", "metric", "value", "source_snapshot_id", "quality_flags"],
          "properties": {
            "record_type": { "const": "observation" },
            "entity": { "$ref": "#/$defs/EntityReference" },
            "time": { "$ref": "#/$defs/TimeReference" },
            "metric": { "$ref": "#/$defs/MetricReference" },
            "value": { "type": ["number", "integer", "string", "boolean", "null"] },
            "source_snapshot_id": { "type": "string" },
            "source_record_id": { "type": ["string", "null"] },
            "quality_flags": { "type": "array", "items": { "type": "string" } },
            "missing_reason": { "type": ["string", "null"] },
            "normalization_version": { "type": "string" }
          }
        }
      ]
    },
    "FeatureRecord": {
      "$id": "hc.feature_record.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "entity", "as_of_date", "feature_id", "value", "transform_id", "input_record_ids", "leakage_check"],
          "properties": {
            "record_type": { "const": "feature" },
            "entity": { "$ref": "#/$defs/EntityReference" },
            "as_of_date": { "type": "string", "format": "date" },
            "feature_id": { "type": "string" },
            "value": { "type": ["number", "integer", "string", "boolean", "null"] },
            "unit": { "type": ["string", "null"] },
            "transform_id": { "type": "string" },
            "transform_version": { "type": "string" },
            "input_record_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "leakage_check": { "type": "string", "enum": ["passed", "failed", "not_applicable"] },
            "quality_flags": { "type": "array", "items": { "type": "string" } }
          }
        }
      ]
    },
    "PanelRow": {
      "$id": "hc.panel_row.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "panel_id", "entity", "period", "feature_set_version", "values", "availability_cutoff"],
          "properties": {
            "record_type": { "const": "panel_row" },
            "panel_id": { "type": "string" },
            "entity": { "$ref": "#/$defs/EntityReference" },
            "period": { "$ref": "#/$defs/TimeReference" },
            "feature_set_version": { "type": "string" },
            "values": { "type": "object", "additionalProperties": { "type": ["number", "integer", "string", "boolean", "null"] } },
            "value_record_ids": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
            "availability_cutoff": { "type": "string", "format": "date-time" },
            "split": { "type": ["string", "null"], "enum": ["train", "validation", "test", "benchmark", null] }
          }
        }
      ]
    },
    "ForecastPoint": {
      "$id": "hc.forecast_point.v1",
      "type": "object",
      "required": ["forecast_time", "horizon", "p50"],
      "properties": {
        "forecast_time": { "type": "string", "format": "date-time" },
        "horizon": { "type": "integer", "minimum": 0 },
        "horizon_unit": { "type": "string", "enum": ["day", "week", "month", "quarter", "year"] },
        "point": { "type": ["number", "null"] },
        "p10": { "type": ["number", "null"] },
        "p25": { "type": ["number", "null"] },
        "p50": { "type": ["number", "null"] },
        "p75": { "type": ["number", "null"] },
        "p90": { "type": ["number", "null"] },
        "scenario": { "type": ["string", "null"] }
      },
      "additionalProperties": false
    },
    "ForecastSeries": {
      "$id": "hc.forecast_series.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "forecast_id", "entity", "metric", "origin_time", "model_version", "training_cutoff", "band_kind", "points"],
          "properties": {
            "record_type": { "const": "forecast_series" },
            "forecast_id": { "type": "string" },
            "entity": { "$ref": "#/$defs/EntityReference" },
            "metric": { "$ref": "#/$defs/MetricReference" },
            "origin_time": { "type": "string", "format": "date-time" },
            "model_version": { "type": "string" },
            "training_cutoff": { "type": "string", "format": "date-time" },
            "band_kind": { "type": "string", "enum": ["predictive_quantile", "scenario", "confidence_interval", "none"] },
            "baseline_value": { "type": ["number", "null"] },
            "points": { "type": "array", "items": { "$ref": "#/$defs/ForecastPoint" }, "minItems": 1 }
          }
        }
      ]
    },
    "ForecastVintage": {
      "$id": "hc.forecast_vintage.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "vintage_id", "publisher", "publication_date", "entity", "metric", "scenario", "values", "benchmark_role"],
          "properties": {
            "record_type": { "const": "forecast_vintage" },
            "vintage_id": { "type": "string" },
            "publisher": { "type": "string" },
            "publication_date": { "type": "string", "format": "date" },
            "retrieval_date": { "type": ["string", "null"], "format": "date" },
            "entity": { "$ref": "#/$defs/EntityReference" },
            "metric": { "$ref": "#/$defs/MetricReference" },
            "scenario": { "type": "string" },
            "values": { "type": "array", "items": { "$ref": "#/$defs/ForecastPoint" }, "minItems": 1 },
            "benchmark_role": { "type": "string" },
            "training_eligibility": { "type": "string", "enum": ["benchmark_only", "consumer_feed", "training_candidate", "holdback"] }
          }
        }
      ]
    },
    "BenchmarkScore": {
      "$id": "hc.benchmark_score.v1",
      "type": "object",
      "required": ["metric_name", "value", "aggregation_level"],
      "properties": {
        "metric_name": { "type": "string" },
        "value": { "type": ["number", "null"] },
        "aggregation_level": { "type": "string" },
        "target": { "type": ["string", "null"] },
        "horizon": { "type": ["integer", "null"] },
        "baseline_name": { "type": ["string", "null"] },
        "improvement": { "type": ["number", "null"] },
        "sample_count": { "type": ["integer", "null"], "minimum": 0 },
        "confidence_interval": { "type": ["array", "null"], "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }
      },
      "additionalProperties": false
    },
    "BenchmarkResult": {
      "$id": "hc.benchmark_result.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "benchmark_id", "dataset_snapshot_ids", "evaluation_cutoff", "split_definition", "model_versions", "scores", "reproducibility"],
          "properties": {
            "record_type": { "const": "benchmark_result" },
            "benchmark_id": { "type": "string" },
            "dataset_snapshot_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "evaluation_cutoff": { "type": "string", "format": "date-time" },
            "split_definition": { "type": "string" },
            "model_versions": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "scores": { "type": "array", "items": { "$ref": "#/$defs/BenchmarkScore" }, "minItems": 1 },
            "reproducibility": {
              "type": "object",
              "required": ["code_version", "config_id"],
              "properties": {
                "code_version": { "type": "string" },
                "config_id": { "type": "string" },
                "environment_id": { "type": ["string", "null"] },
                "artifact_ids": { "type": "array", "items": { "type": "string" } }
              },
              "additionalProperties": false
            }
          }
        }
      ]
    },
    "ProvenanceManifest": {
      "$id": "hc.provenance_manifest.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "source_snapshot_ids", "transform_steps", "license_note", "lineage_complete"],
          "properties": {
            "record_type": { "const": "provenance_manifest" },
            "source_snapshot_ids": { "type": "array", "items": { "type": "string" } },
            "parent_record_ids": { "type": "array", "items": { "type": "string" } },
            "transform_steps": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["transform_id", "version", "executed_at"],
                "properties": {
                  "transform_id": { "type": "string" },
                  "version": { "type": "string" },
                  "executed_at": { "type": "string", "format": "date-time" },
                  "parameters_hash": { "type": ["string", "null"] }
                },
                "additionalProperties": false
              }
            },
            "license_note": { "type": "string" },
            "lineage_complete": { "type": "boolean" },
            "quality_checks": { "type": "array", "items": { "type": "string" } }
          }
        }
      ]
    },
    "AccessPolicy": {
      "$id": "hc.access_policy.v1",
      "type": "object",
      "required": ["policy_id", "visibility", "sensitivity", "license_status", "allowed_uses", "denied_uses", "row_level_floor"],
      "properties": {
        "policy_id": { "type": "string" },
        "visibility": { "type": "string", "enum": ["public", "authenticated", "restricted", "metadata_only", "unavailable"] },
        "sensitivity": { "type": "string", "enum": ["low", "medium", "high"] },
        "license_status": { "type": "string" },
        "allowed_uses": { "type": "array", "items": { "type": "string", "enum": ["discovery", "benchmarking", "consumer_feed", "research", "training", "commercial", "internal_operations"] } },
        "denied_uses": { "type": "array", "items": { "type": "string" } },
        "row_level_floor": { "type": "string" },
        "authentication": { "type": ["string", "null"] },
        "retention_days": { "type": ["integer", "null"], "minimum": 0 },
        "license_note": { "type": ["string", "null"] },
        "reviewed_at": { "type": ["string", "null"], "format": "date-time" }
      },
      "additionalProperties": false
    },
    "ArtifactManifest": {
      "$id": "hc.artifact_manifest.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "artifact_id", "artifact_kind", "format", "content_hash", "byte_size", "download_policy"],
          "properties": {
            "record_type": { "const": "artifact_manifest" },
            "artifact_id": { "type": "string" },
            "artifact_kind": { "type": "string" },
            "format": { "type": "string" },
            "content_hash": { "type": "string" },
            "byte_size": { "type": "integer", "minimum": 0 },
            "download_policy": { "type": "string", "enum": ["direct", "signed", "authenticated", "metadata_only", "unavailable"] },
            "download_url": { "type": ["string", "null"], "format": "uri" },
            "expires_at": { "type": ["string", "null"], "format": "date-time" }
          }
        }
      ]
    },
    "SyntheticRecord": {
      "$id": "hc.synthetic_record.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "synthetic_id", "synthetic_kind", "generator_id", "generator_version", "parent_snapshot_ids", "privacy_review", "quality_report_id", "observed_data_claim", "payload"],
          "properties": {
            "record_type": { "const": "synthetic_record" },
            "synthetic_id": { "type": "string" },
            "synthetic_kind": { "type": "string", "enum": ["scenario", "augmentation", "imputation", "simulation", "privacy_preserving_sample"] },
            "generator_id": { "type": "string" },
            "generator_version": { "type": "string" },
            "parent_snapshot_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
            "privacy_review": { "type": "string", "enum": ["passed", "failed", "not_required"] },
            "quality_report_id": { "type": "string" },
            "observed_data_claim": { "const": false },
            "payload": { "type": "object" }
          }
        }
      ]
    },
    "OperationalRecord": {
      "$id": "hc.operational_record.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "operation_type", "occurred_at", "dimensions", "measures", "redaction_state"],
          "properties": {
            "record_type": { "const": "operational_record" },
            "operation_type": { "type": "string" },
            "occurred_at": { "type": "string", "format": "date-time" },
            "dimensions": { "type": "object" },
            "measures": { "type": "object" },
            "redaction_state": { "type": "string", "enum": ["raw_restricted", "deidentified", "aggregated"] }
          }
        }
      ]
    },
    "ProductEvent": {
      "$id": "hc.product_event.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "event_name", "occurred_at", "subject_type", "properties", "privacy_state"],
          "properties": {
            "record_type": { "const": "product_event" },
            "event_name": { "type": "string" },
            "occurred_at": { "type": "string", "format": "date-time" },
            "subject_type": { "type": "string" },
            "subject_id": { "type": ["string", "null"] },
            "properties": { "type": "object" },
            "privacy_state": { "type": "string", "enum": ["identified_restricted", "pseudonymous_restricted", "deidentified", "aggregate"] }
          }
        }
      ]
    },
    "ModelArtifact": {
      "$id": "hc.model_artifact.v1",
      "allOf": [
        { "$ref": "#/$defs/ContractMetadata" },
        {
          "type": "object",
          "required": ["record_type", "model_version", "artifact_kind", "training_snapshot_ids", "code_version", "evaluation_result_ids", "release_state"],
          "properties": {
            "record_type": { "const": "model_artifact" },
            "model_version": { "type": "string" },
            "artifact_kind": { "type": "string", "enum": ["checkpoint", "configuration", "feature_manifest", "evaluation_bundle", "serving_bundle"] },
            "training_snapshot_ids": { "type": "array", "items": { "type": "string" } },
            "code_version": { "type": "string" },
            "evaluation_result_ids": { "type": "array", "items": { "type": "string" } },
            "release_state": { "type": "string", "enum": ["internal", "candidate", "published_metadata", "published_artifact"] },
            "artifact_id": { "type": ["string", "null"] }
          }
        }
      ]
    }
  }
}