feat(research): seal historical combo P1 roots

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

docs/historical_combo_p1_root_contract.md

@@ -0,0 +1,42 @@
+# Historical combo P1 immutable-root contract
+
+`qsl.us-equity-historical-combo-p1-root-manifest.v1` is the local, immutable
+storage boundary for an already-validated
+`qsl.us-equity-historical-combo-p1-input.v1` record.  It is deliberately
+small: it seals bytes that have already been acquired; it does not decide
+whether data are good enough to acquire or use.
+
+## What one root contains
+
+Each fresh private root has mode `0700`, each member has mode `0600`, and the
+root is published through an atomic no-replace operation.  It contains:
+
+- canonical `input.json`, the self-validating P1 metadata input;
+- `price-panel.raw`, whose SHA-256 equals the input's declared raw panel
+  digest;
+- `quality-report.raw`, whose SHA-256 equals the input's declared quality
+  report digest;
+- one `universe-source/NNNN.raw` byte stream for each P1 rebalance decision,
+  whose SHA-256 equals that decision's point-in-time universe source digest;
+  and
+- canonical `manifest.json`, which records every member's exact path, byte
+  length and digest, plus the P1 input digest.
+
+`verify_historical_combo_p1_root` checks the exact root layout, private file
+modes, canonical metadata, every member digest, and the links back to the P1
+price-panel and universe-source declarations.  It does not need network,
+credentials, a provider, strategy code, or a broker.
+
+## Intended use
+
+The producer receives local bytes explicitly.  For a scriptable entry point,
+use `seal-historical-combo-p1-root` with the input JSON, raw price panel,
+quality report, and one `--universe-source DECISION_AT=PATH` per rebalance.
+The output location must be new; retrying an already-created path intentionally
+fails instead of overwriting research evidence.
+
+This contract does **not** parse a vendor price format, repair missing data,
+certify a quality report, choose a candidate, run P2/P3, publish to cloud, or
+authorize paper/shadow/live activity.  A later real P3 adapter may consume a
+verified root only after it separately validates the panel format, data-quality
+criteria, point-in-time disclosure, cost model and frozen P1/P2 identity.

pyproject.toml

@@ -34,6 +34,7 @@ publish-platform-signal-handoff = "market_signal_sources.cli.publish_platform_si
 validate-quality-report = "market_signal_sources.cli.validate_quality_report:main"
 validate-research-export = "market_signal_sources.cli.validate_research_export:main"
 validate-signal-bundle = "market_signal_sources.cli.validate_signal_bundle:main"
+seal-historical-combo-p1-root = "market_signal_sources.cli.seal_historical_combo_p1_root:main"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

src/market_signal_sources/artifacts/__init__.py

@@ -117,6 +117,15 @@
     calculate_historical_combo_p1_input_sha256,
     validate_historical_combo_p1_input,
 )
+from .historical_combo_p1_root import (
+    HISTORICAL_COMBO_P1_ROOT_MANIFEST_SCHEMA,
+    ROOT_STATUS as HISTORICAL_COMBO_P1_ROOT_STATUS,
+    HistoricalComboP1RootError,
+    canonical_historical_combo_p1_root_manifest_bytes,
+    publish_historical_combo_p1_root,
+    validate_historical_combo_p1_root_manifest,
+    verify_historical_combo_p1_root,
+)
 from .validation import (
     REQUIRED_INDICATOR_FIELDS_BY_CONSUMER,
     SignalBundleValidationError,
@@ -155,6 +164,8 @@
     "POINT_IN_TIME_UNIVERSE_SCHEMA",
     "HISTORICAL_PRICE_PANEL_SCHEMA",
     "HISTORICAL_COMBO_P1_INPUT_SCHEMA",
+    "HISTORICAL_COMBO_P1_ROOT_MANIFEST_SCHEMA",
+    "HISTORICAL_COMBO_P1_ROOT_STATUS",
     "RESEARCH_EXPORT_SCHEMA_VERSION",
     "SIGNAL_OWNERSHIP_MATRIX_SCHEMA_VERSION",
     "SIGNAL_SOURCE_FAMILY_CATALOG_MANIFEST_SCHEMA_VERSION",
@@ -168,6 +179,7 @@
     "PointInTimeUniverseError",
     "HistoricalPricePanelError",
     "HistoricalComboP1InputError",
+    "HistoricalComboP1RootError",
     "build_btc_cycle_signal_bundle",
     "build_daily_technical_signal_bundle",
     "build_derived_indicator_signal_bundle",
@@ -176,6 +188,7 @@
     "build_point_in_time_universe_snapshot",
     "build_historical_price_panel",
     "build_historical_combo_p1_input",
+    "publish_historical_combo_p1_root",
     "consumer_contract_for",
     "audit_signal_consumption",
     "compatible_profiles_for_signal_source_family",
@@ -214,6 +227,8 @@
     "validate_point_in_time_universe_snapshot",
     "validate_historical_price_panel",
     "validate_historical_combo_p1_input",
+    "validate_historical_combo_p1_root_manifest",
+    "verify_historical_combo_p1_root",
     "validate_consumption_audit_file",
     "validate_runtime_adapter_config",
     "validate_runtime_adapter_config_set_files",
@@ -226,6 +241,7 @@
     "calculate_point_in_time_universe_sha256",
     "calculate_historical_price_panel_sha256",
     "calculate_historical_combo_p1_input_sha256",
+    "canonical_historical_combo_p1_root_manifest_bytes",
     "write_research_signal_handoff_manifest",
     "write_consumption_audit_artifact",
     "write_runtime_signal_injection_plan_artifact",