{
  "registry_version": "1.0.0",
  "reviewed_at": "2026-07-16",
  "matrix_path": "docs/public-data/full-data-surface-matrix.tsv",
  "matrix_join_key": "data_family",
  "schema_bundle": "docs/public-data/schemas/homecastr-data-contracts.schema.json",
  "policy_rule": "Every asset receives a canonical contract and surface target. Visibility remains asset-specific and is never inferred from technical availability.",
  "layers": {
    "raw": "Immutable source bytes or payload snapshots with hashes, retrieval metadata, and terms snapshots.",
    "normalized": "Long-form observations with canonical entity, time, metric, unit, missingness, and source references.",
    "engineered": "As-of-safe features with transform versions, parent records, and leakage checks.",
    "panelized": "Entity-by-period rows with feature-set versions and availability cutoffs.",
    "forecast": "Model or external forecast vintages with origins, cutoffs, horizons, quantiles, and scenarios.",
    "benchmark": "Immutable dataset snapshots, split definitions, model versions, scores, and reproducibility metadata.",
    "synthetic": "Explicitly labeled simulations, augmentations, imputations, or privacy-preserving samples that cannot claim to be observed facts.",
    "delivery": "Catalog, query, artifact, provenance, and schema resources shared across REST, MCP, OpenAPI, docs, and SDKs."
  },
  "profiles": {
    "forecast_output": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.forecast_series.v1", "hc.forecast_vintage.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Preserve model output bundles and served payload snapshots by model version and origin time.",
      "normalization": ["canonicalize entity IDs and geography vintages", "separate origin time from forecast time", "normalize target IDs, units, quantiles, and scenarios"],
      "engineering": ["derive growth and summary statistics from canonical forecast points", "retain the input forecast IDs used by every summary"],
      "synthesis_policy": "Scenario generation is allowed only as hc.synthetic_record.v1 with parent forecast snapshots and no observed-data claim.",
      "target_rest": ["/api/v1/data/forecasts", "/api/v1/data/vintages", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["query_forecasts", "get_forecast_vintage", "get_data_artifact"],
      "target_openapi": ["ForecastSeries", "ForecastVintage", "ArtifactManifest"],
      "target_docs": ["dataset card", "forecast semantics", "provenance and model card", "REST/MCP/SDK examples"],
      "target_sdk": ["client.forecasts.query", "client.vintages.get", "client.artifacts.download"],
      "default_export_formats": ["json", "jsonl", "csv"]
    },
    "backtest_output": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.forecast_vintage.v1", "hc.benchmark_result.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Preserve complete evaluation artifacts, configs, dataset snapshot IDs, and compact public summaries separately.",
      "normalization": ["normalize target and horizon identifiers", "record split and availability cutoffs", "distinguish model, public forecast, and persistence baselines"],
      "engineering": ["compute comparable score rows", "derive improvement and calibration summaries without dropping sample counts"],
      "synthesis_policy": "Bootstrap and stress-test samples are allowed as synthetic benchmark artifacts and never replace reported observed scores.",
      "target_rest": ["/api/v1/data/vintages", "/api/v1/data/benchmarks", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["get_forecast_vintage", "get_benchmark_result", "get_data_artifact"],
      "target_openapi": ["ForecastVintage", "BenchmarkResult", "ArtifactManifest"],
      "target_docs": ["benchmark card", "split methodology", "reproducibility guide", "score interpretation"],
      "target_sdk": ["client.vintages.get", "client.benchmarks.get", "client.artifacts.download"],
      "default_export_formats": ["json", "jsonl", "csv", "parquet"]
    },
    "benchmark_metadata": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.dataset_asset.v1", "hc.benchmark_result.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Version registry and runner configuration snapshots with content hashes.",
      "normalization": ["canonicalize dataset, suite, model, and jurisdiction identifiers", "resolve every registry entry to immutable snapshot IDs"],
      "engineering": ["derive searchable capabilities and compatibility labels"],
      "synthesis_policy": "Not applicable; generated compatibility summaries remain derived metadata.",
      "target_rest": ["/api/v1/data/catalog", "/api/v1/data/benchmarks"],
      "target_mcp": ["list_data_assets", "get_benchmark_result"],
      "target_openapi": ["DatasetAsset", "BenchmarkResult"],
      "target_docs": ["catalog reference", "benchmark registry", "adapter matrix"],
      "target_sdk": ["client.dataAssets.list", "client.benchmarks.get"],
      "default_export_formats": ["json", "csv"]
    },
    "benchmark_panel": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.panel_row.v1", "hc.benchmark_result.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Preserve each public fixture and extraction response before normalization.",
      "normalization": ["map planning geographies and metric names to canonical IDs", "record publication, retrieval, and availability dates"],
      "engineering": ["build leakage-safe panel rows", "materialize benchmark splits from immutable snapshot IDs"],
      "synthesis_policy": "Synthetic spatial-allocation tests are allowed only as separately labeled benchmark datasets.",
      "target_rest": ["/api/v1/data/observations", "/api/v1/data/panels", "/api/v1/data/benchmarks"],
      "target_mcp": ["query_observations", "get_panel_slice", "get_benchmark_result"],
      "target_openapi": ["Observation", "PanelRow", "BenchmarkResult"],
      "target_docs": ["dataset card", "geography mapping", "benchmark instructions"],
      "target_sdk": ["client.observations.query", "client.panels.getSlice", "client.benchmarks.get"],
      "default_export_formats": ["json", "jsonl", "csv", "parquet"]
    },
    "input_panel": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.feature_record.v1", "hc.panel_row.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Keep exact jurisdiction source files append-only, partitioned by source and retrieval snapshot.",
      "normalization": ["resolve property and geography identity", "normalize metric names, units, currencies, period semantics, and missingness", "retain source record IDs"],
      "engineering": ["create as-of-safe features", "panelize by entity and period", "version all crosswalks and feature sets"],
      "synthesis_policy": "Aggregation, imputation, and privacy-preserving samples require asset policy; raw high-sensitivity property rows are never silently synthesized or published.",
      "target_rest": ["/api/v1/data/observations", "/api/v1/data/features", "/api/v1/data/panels", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["query_observations", "query_features", "get_panel_slice", "get_data_artifact"],
      "target_openapi": ["Observation", "FeatureRecord", "PanelRow", "ArtifactManifest"],
      "target_docs": ["source card", "field mapping", "feature dictionary", "panel schema", "license and access note"],
      "target_sdk": ["client.observations.query", "client.features.query", "client.panels.getSlice", "client.artifacts.download"],
      "default_export_formats": ["jsonl", "csv", "parquet"]
    },
    "context_input": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.feature_record.v1", "hc.panel_row.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Keep immutable source extracts or API response snapshots with source-specific cadence and terms metadata.",
      "normalization": ["normalize geographies, metric IDs, units, seasonal adjustment, and publication lag", "separate event period, publication time, and retrieval time"],
      "engineering": ["apply as-of joins", "derive lags, rolling statistics, exposure measures, and geography rollups with transform versions"],
      "synthesis_policy": "Derived scenarios are allowed; observed context values and simulated context must remain different record types.",
      "target_rest": ["/api/v1/data/observations", "/api/v1/data/features", "/api/v1/data/panels"],
      "target_mcp": ["query_observations", "query_features", "get_panel_slice"],
      "target_openapi": ["Observation", "FeatureRecord", "PanelRow"],
      "target_docs": ["source card", "metric dictionary", "publication-lag semantics", "feature recipes"],
      "target_sdk": ["client.observations.query", "client.features.query", "client.panels.getSlice"],
      "default_export_formats": ["jsonl", "csv", "parquet"]
    },
    "prediction_market_input": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.feature_record.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Snapshot third-party market payloads with retrieval time and terms state.",
      "normalization": ["normalize market, contract, geography, price, probability, and close-time semantics", "record third-party identifiers"],
      "engineering": ["derive calibrated probabilities and aligned housing-market features without rewriting source observations"],
      "synthesis_policy": "Scenario probabilities must be labeled synthetic and preserve parent market snapshots.",
      "target_rest": ["/api/v1/data/observations", "/api/v1/data/features"],
      "target_mcp": ["query_observations", "query_features"],
      "target_openapi": ["Observation", "FeatureRecord"],
      "target_docs": ["source and terms card", "market semantics", "feature mapping"],
      "target_sdk": ["client.observations.query", "client.features.query"],
      "default_export_formats": ["json", "jsonl", "csv"]
    },
    "geography_reference": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Preserve boundary, label, and crosswalk vintages independently from derived simplifications.",
      "normalization": ["canonicalize entity IDs and namespaces", "version geography definitions and parent relationships", "record geometry CRS and precision"],
      "engineering": ["build versioned crosswalks, centroids, adjacency, and simplified geometries"],
      "synthesis_policy": "Generalized or simplified geometry is derived, not synthetic; simulated geography must use hc.synthetic_record.v1.",
      "target_rest": ["/api/v1/data/entities", "/api/v1/data/crosswalks", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["get_entity", "get_geography_crosswalk", "get_data_artifact"],
      "target_openapi": ["EntityReference", "Observation", "ArtifactManifest"],
      "target_docs": ["geography reference", "vintage and crosswalk guide", "geometry download guide"],
      "target_sdk": ["client.entities.get", "client.geographies.getCrosswalk", "client.artifacts.download"],
      "default_export_formats": ["json", "csv", "geojson", "parquet", "mvt", "pmtiles"]
    },
    "provenance_manifest": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.provenance_manifest.v1", "hc.dataset_asset.v1", "hc.access_policy.v1"],
      "raw_retention": "Version the original manifest and any source-term evidence used to create it.",
      "normalization": ["canonicalize source, snapshot, transform, artifact, and license identifiers", "make validated, pending, and rejected states explicit"],
      "engineering": ["derive lineage graphs and completeness checks"],
      "synthesis_policy": "Not applicable; inferred lineage must be explicitly marked inferred until validated.",
      "target_rest": ["/api/v1/data/provenance", "/api/v1/data/catalog"],
      "target_mcp": ["get_provenance", "list_data_assets"],
      "target_openapi": ["ProvenanceManifest", "DatasetAsset"],
      "target_docs": ["provenance reference", "source ledger", "license notes"],
      "target_sdk": ["client.provenance.get", "client.dataAssets.list"],
      "default_export_formats": ["json", "jsonl", "csv"]
    },
    "source_metadata": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.dataset_asset.v1", "hc.source_snapshot.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Retain discovery and review snapshots, including unresolved license status.",
      "normalization": ["canonicalize source family, geography, cadence, access method, terms, and review state"],
      "engineering": ["derive coverage, freshness, confidence, and missing-source summaries"],
      "synthesis_policy": "Not applicable; discovery hypotheses remain labeled unverified metadata.",
      "target_rest": ["/api/v1/data/sources", "/api/v1/data/catalog", "/api/v1/data/provenance"],
      "target_mcp": ["list_data_sources", "list_data_assets", "get_provenance"],
      "target_openapi": ["SourceSnapshot", "DatasetAsset", "ProvenanceManifest"],
      "target_docs": ["source catalog", "coverage ledger", "review-state definitions"],
      "target_sdk": ["client.sources.list", "client.dataAssets.list", "client.provenance.get"],
      "default_export_formats": ["json", "csv"]
    },
    "schema": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.dataset_asset.v1", "hc.artifact_manifest.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Version SQL, YAML, JSON Schema, migration, and compatibility snapshots by content hash.",
      "normalization": ["assign stable schema IDs and semantic versions", "record compatibility and deprecation state"],
      "engineering": ["generate language types, validators, OpenAPI components, and migration reports from canonical schemas"],
      "synthesis_policy": "Not applicable.",
      "target_rest": ["/api/v1/data/schemas", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["list_data_schemas", "get_data_schema"],
      "target_openapi": ["DatasetAsset", "ArtifactManifest"],
      "target_docs": ["schema reference", "compatibility policy", "migration guide"],
      "target_sdk": ["client.schemas.list", "client.schemas.get"],
      "default_export_formats": ["json"]
    },
    "training_panel": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.observation.v1", "hc.feature_record.v1", "hc.panel_row.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Training panels never replace raw or normalized parents; preserve snapshot and feature-manifest IDs.",
      "normalization": ["conform all released panels to entity, time, metric, unit, and availability contracts", "remove source-specific naming from the canonical export"],
      "engineering": ["materialize reproducible feature sets and splits", "validate leakage, missingness, duplicates, and geography continuity"],
      "synthesis_policy": "Optional synthetic augmentations must be separate partitions with generator and quality manifests.",
      "target_rest": ["/api/v1/data/panels", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["get_panel_slice", "get_data_artifact"],
      "target_openapi": ["PanelRow", "ArtifactManifest"],
      "target_docs": ["training dataset card", "feature dictionary", "split and leakage report", "loader examples"],
      "target_sdk": ["client.panels.getSlice", "client.panels.download"],
      "default_export_formats": ["jsonl", "csv", "parquet"]
    },
    "model_internal": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.model_artifact.v1", "hc.benchmark_result.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Preserve checkpoints, configs, feature manifests, and evaluation bundles under restricted immutable snapshots.",
      "normalization": ["assign stable model, code, training-data, and evaluation IDs", "separate model metadata from downloadable weights"],
      "engineering": ["derive public model cards and benchmark summaries from reviewed metadata"],
      "synthesis_policy": "Generated model documentation is derived metadata; weights and outputs retain original access policy.",
      "target_rest": ["/api/v1/internal/data/models", "/api/v1/data/benchmarks", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["get_model_metadata", "get_benchmark_result", "get_data_artifact"],
      "target_openapi": ["ModelArtifact", "BenchmarkResult", "ArtifactManifest"],
      "target_docs": ["model card", "evaluation report", "artifact access policy"],
      "target_sdk": ["client.admin.models.get", "client.benchmarks.get", "client.artifacts.download"],
      "default_export_formats": ["json"]
    },
    "ops_internal": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.operational_record.v1", "hc.product_event.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1", "hc.artifact_manifest.v1"],
      "raw_retention": "Retain operational records under least-privilege, purpose-limited policies with explicit retention windows.",
      "normalization": ["separate identities from events and measures", "normalize timestamps, operation types, and redaction state"],
      "engineering": ["produce deidentified or aggregate operational metrics only after policy review"],
      "synthesis_policy": "No public synthetic release by default; test fixtures must be unmistakably fake and disconnected from production subjects.",
      "target_rest": ["/api/v1/internal/data/operations"],
      "target_mcp": ["query_internal_operations"],
      "target_openapi": ["OperationalRecord", "ProductEvent"],
      "target_docs": ["internal data dictionary", "privacy and retention policy", "admin API reference"],
      "target_sdk": ["client.admin.operations.query"],
      "default_export_formats": ["json"]
    },
    "product_internal": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.product_event.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Retain user-linked product state only under product purpose and retention policy.",
      "normalization": ["normalize subject, portfolio, event, and timestamp semantics", "keep identity fields outside public records"],
      "engineering": ["derive deidentified aggregate product metrics when justified"],
      "synthesis_policy": "Use clearly fake fixtures for demos; never synthesize production user state into a public dataset.",
      "target_rest": ["/api/v1/internal/data/product-events"],
      "target_mcp": ["query_internal_product_events"],
      "target_openapi": ["ProductEvent"],
      "target_docs": ["internal product schema", "privacy policy", "admin examples"],
      "target_sdk": ["client.admin.productEvents.query"],
      "default_export_formats": ["json"]
    },
    "research_internal": {
      "source_contract": "hc.source_snapshot.v1",
      "canonical_contracts": ["hc.artifact_manifest.v1", "hc.provenance_manifest.v1", "hc.access_policy.v1"],
      "raw_retention": "Preserve original research artifacts and evidence snapshots with relationship and confidentiality controls where applicable.",
      "normalization": ["assign artifact, subject, source, date, and evidence IDs", "separate factual extraction from analyst inference"],
      "engineering": ["derive publishable aggregate research only through an explicit review artifact"],
      "synthesis_policy": "Generated summaries must cite parent artifacts and cannot be represented as source evidence.",
      "target_rest": ["/api/v1/internal/data/research", "/api/v1/data/artifacts/{artifact_id}"],
      "target_mcp": ["query_internal_research", "get_data_artifact"],
      "target_openapi": ["ArtifactManifest", "ProvenanceManifest"],
      "target_docs": ["internal research catalog", "evidence and inference policy", "artifact access guide"],
      "target_sdk": ["client.admin.research.query", "client.artifacts.download"],
      "default_export_formats": ["json"]
    }
  }
}