{"schema":"flow_bot_data_contract_v1","contract_id":"flow-bot-data-contract-v1","version":"2026.07.20.1","audience_tier":"tier_agnostic_until_hub_ratification","contract_sha256_policy":{"algorithm":"sha256","canonicalization":"json/deep-sorted-keys/compact/utf-8","excludes":["contract_sha256"]},"audience":{"tier_state":"tier_agnostic_until_hub_ratification","commercial_contract_status":"not_published","rule":"Read plan, tier, available, and daily_limit from authenticated Hub discovery; this contract does not invent a paid label, price, quota, or service level.","hub_discovery":{"method":"GET","path":"https://api.marketschema.com/v1/bot/auth/capabilities","auth_header":"X-API-Key","contract_name":"marketschema-bot-contract","contract_version":"3.0.0","published_sha256":null,"top_level_fields":["authenticated","user_id","email","timestamp","contract_version","plan","tier","api_key_scope","authentication","registration","recommended_polling","streaming","objective_asset_contract","sso_additive_contract","endpoint_capabilities"],"endpoint_capability_fields":["key","path","method","description","auth","daily_limit","available","recommended_poll_interval_seconds","quota_bucket"]}},"service_levels":{"uptime_percent":null,"latency_ms":null,"retention_days":null,"delivery_schedule":null,"promise":"receipt_proven_only","reason":"No uptime, latency, delivery, or retention SLA is published by the banked receipts."},"history":{"retention_floor":null,"retention_floor_unit":null,"max_points_per_request":5000,"storage_model":"append_only","pagination_cursor":"after","recomputation":false,"guarantee":"Coverage is bounded by stored append-only frames; no calendar-day or year floor is guaranteed.","response_depth_fields":["snapshot_count","iv_backfill_batch_count","available_point_count","point_count","available_point_count_by_archive_source","emitted_point_count_by_archive_source","available_point_count_by_signal","emitted_point_count_by_signal","latest_available_point_as_of","latest_emitted_point_as_of"]},"availability":{"grammar":"2026.07.family_availability.v1","states":["LIVE","LAST-GOOD","DEGRADED","LIMITED","WITHHELD UNTIL PROOF","RECOMPUTING","AWAITING NEXT CAPTURE","SIGN-IN REQUIRED"],"semantics":{"LIVE":"A present measurement is inside its source-specific freshness policy.","LAST-GOOD":"A present measurement is stale and keeps its original as_of clock.","DEGRADED":"A present measurement carries a named coverage or reliability limit.","LIMITED":"The measurement is missing, invalid, or future-skewed; no quiet value replaces it.","WITHHELD UNTIL PROOF":"A deliberate proof gate names its trigger and last-good context; it does not publish the gated lane early.","RECOMPUTING":"A new eligible frame is being derived; the trigger and last-good context remain visible and the prior clock is not advanced.","AWAITING NEXT CAPTURE":"The required natural observation window has not closed; the trigger and last-good context remain visible.","SIGN-IN REQUIRED":"The requested consumer surface requires its native identity boundary."}},"replay":{"pressure_points":{"path":"/v1/replay/pressure","as_of_policy":"point_as_of_at_or_before_requested_as_of","after_policy":"point_as_of_strictly_after_requested_after","survivorship_free":true,"append_only":true,"does_not_recompute":true,"scope":"Filters emitted pressure points by their point clocks; it does not claim packet-wide temporal validation for every legacy snapshot row.","stable_query_error_reasons":["as_of must be ISO-8601 parseable","after must be ISO-8601 parseable"],"storage_error_reason":"pressure_replay_unavailable","archive_error_policy":"PressureReplayArchiveError text passes through as reason in the public error packet; consumers must treat it as typed archive failure text, not as a closed enum.","framework_validation_policy":"Query bound and pattern failures use the framework validation detail packet before the replay handler runs."},"board_packet":{"paths":["/v1/board?as_of={cutoff}","/v1/assets/{symbol}?as_of={cutoff}"],"admissibility":"latest_archived_board_packet_at_or_before_requested_as_of_v1","future_measurements":"rejected_packet_wide","future_schedule_exception":"registered_catalyst_paths_only","append_only":true,"does_not_recompute":true,"does_not_backdate":true,"does_not_call_live_providers":true,"candidate_policy":"A future observation anywhere in a candidate board packet makes that packet inadmissible; readers page backward to the latest eligible packet.","schedule_policy":"A registered future catalyst timestamp remains admissible only as a schedule, never as a future measurement.","typed_errors":["point_in_time_replay_as_of_invalid","point_in_time_replay_not_found","point_in_time_replay_asset_absent_at_as_of","point_in_time_replay_archive_unavailable","point_in_time_replay_archive_entry_invalid"]}},"countersign":{"discovery":"https://api.marketschema.com/.well-known/ms1","algorithm":"Ed25519","canonicalization":"json/sorted-keys/compact/utf-8, signature fields excluded","message_prefix":"ms1-countersign/v0","message_template":"ms1-countersign/v0:{room}:{packet_id}:{issuer}:{payload_sha256}","packet_payload_sha256_format":"sha256:<lowercase_hex>","message_payload_sha256_format":"lowercase_hex_without_sha256_prefix","room":"flow","issuer":"marketschema.flow","unsigned_state":"typed_unsigned","unsigned_requirements":{"signature_object_required":true,"detached_signature":null,"detached_signature_status_values":["unsigned_pending_flow_room_grant_or_hub_countersign","unsigned_pending_hub_countersign_grant_not_configured","unsigned_pending_hub_countersign_unavailable","unsigned_pending_hub_countersign_invalid_response"]},"verification_steps":["Fetch the packet and remove its signature object before canonicalizing the payload.","Deep-sort object keys, serialize compact JSON as UTF-8, SHA-256 the bytes, and compare signature.payload_sha256.","Fetch Hub /.well-known/ms1 and select the public key whose key_id matches the packet.","Remove the exact sha256: prefix from signature.payload_sha256, then build ms1-countersign/v0:{room}:{packet_id}:{issuer}:{lowercase_hex}.","Base64url-decode the detached signature and public key, then verify the Ed25519 signature over that message.","For an unsigned packet, require a present signature object, signature.detached_signature=null, and a listed unsigned detached_signature_status; a missing signature object is invalid.","For a signed packet, require signature.detached_signature_status=hub_countersigned and a signed receipt with matching key and algorithm."]},"typed_absence":{"policy":"no_fake_neutral_or_backfill","neutral_substitute":false,"rule":"Missing, stale, blocked, ineligible, or unavailable data remains explicit; score null is never replaced by a neutral score.","surface_mappings":[{"surface":"signal_envelope","value_path":"score","absent_value":null,"freshness_path":"freshness","clock_path":"as_of","reason_paths":["confidence_cap_reason","components.reason"]},{"surface":"board_row","freshness_path":"freshness","clock_path":"as_of","reason_paths":["gaps[].reason","signal_fields[].confidence_cap_reason"]},{"surface":"pressure_replay_point","value_path":"score","absent_value":null,"freshness_path":"freshness","clock_path":"as_of","reason_paths":["confidence_cap_reason","components.reason"]},{"surface":"public_error_packet","status_path":"status","reason_paths":["reason"]}]},"lanes":[{"key":"event_risk","label":"Event risk","guarantee":"Measures proximity-weighted catalyst pressure; confirmed binary dates require valid primary provenance and estimated dates stay labeled.","freshness":"LIVE with a valid upcoming catalyst clock; DEGRADED or LIMITED when coverage or source provenance is incomplete.","history":"Only event-risk points already present in stored replay frames are returned.","absence":"score=null with a named no-catalyst, coverage, provenance, or provider reason.","evidence_refs":["methodology_contract","replay_contract"]},{"key":"volume_pressure","label":"Volume pressure","guarantee":"Measures completed-session volume against a trailing baseline of prior sessions that excludes the measured session, and reports the source session clock.","freshness":"LIVE when the completed-session baseline is available; otherwise DEGRADED or LIMITED with the source reason.","history":"Stored points retain the original score, state, freshness, and as_of clock.","absence":"score=null when provider data or baseline history is insufficient.","evidence_refs":["methodology_contract","replay_contract"]},{"key":"squeeze_risk","label":"Squeeze risk","guarantee":"Measures FINRA short-interest days-to-cover with relative volume; raw vendor records are not redistributed.","freshness":"LAST-GOOD while present and current for FINRA's public cadence; DEGRADED when the latest settlement is too old.","history":"Replay exposes only stored derived points, never reconstructed vendor rows.","absence":"score=null with a settlement-date, float, relative-volume, or provider reason.","evidence_refs":["methodology_contract","replay_contract"]},{"key":"iv_ramp","label":"IV ramp","guarantee":"Measures the derived implied-versus-realized move ratio when licensed options coverage is configured; raw chains are never emitted.","freshness":"LAST-GOOD by design on the provider's 15-minute delayed options snapshot, with option_snapshot_as_of preserved.","history":"Only stored snapshot or licensed flat-file-derived points appear; no missing options history is invented.","absence":"score=null with not-configured, entitlement, provider, or insufficient-history reason.","evidence_refs":["methodology_contract","replay_contract"]},{"key":"flow_divergence","label":"Flow divergence","guarantee":"Same-feed price/volume divergence is context-only and excluded from the headline pressure spine until its proof gate passes.","freshness":"LIVE only when the completed-session price and volume cross-section exists; otherwise DEGRADED or LIMITED.","history":"Stored context points remain visible without being promoted into the headline score.","absence":"Excluded until proof — this lane publishes only after its replay validates. This exclusion governs headline and DT weighting; the context field may remain emitted and stored.","publication_trigger":"/v1/scorecard signal_gates.gates.flow_divergence.proof_state=proven and dt_weighting_status=eligible_after_cp_072_signal_gate.","evidence_refs":["methodology_contract","scorecard_contract","family_grammar_receipt"]},{"key":"positioning_pressure","label":"Positioning pressure","guarantee":"Reports the derived aggregate and the component eligibility state used by the captured packet; gated lanes do not enter silently.","freshness":"Carries the packet as_of, aggregate freshness, component gaps, and confidence-cap reason.","history":"Board-packet as_of replay returns the captured aggregate exactly as stored. Pressure-point replay derives positioning_pressure at read time from stored native sleeve rows and preserves their source clocks; it does not claim stored aggregate identity.","absence":"score=null with explicit component gaps when no eligible aggregate exists.","evidence_refs":["board_replay_contract","replay_contract","two_anchor_receipt"]},{"key":"catalyst_clock","label":"Catalyst clock","guarantee":"Publishes scheduled macro, OPEX, and provider-backed earnings dates with confirmation and provenance fields.","freshness":"The packet carries source health and its capture clock; unsupported or stale coverage stays named.","history":"A future catalyst may appear in an admissible historical packet only as the schedule known at that packet's as_of.","absence":"Missing or unverified dates remain absent or estimated; no earnings or macro date is guessed.","evidence_refs":["methodology_contract","ms1_runtime_receipt"]}],"evidence":[{"id":"methodology_contract","label":"Flow methodology contract source","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/flowdensity/methodology.py","live_href":"/v1/methodology","binding":"immutable_source_sha256","sha256":"067edb6cdd570e48fdc542e907c08bb9a55b9927bc06c731dbd2fa78439d1a0d"},{"id":"replay_contract","label":"Pressure replay contract source","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/flowdensity/pressure_replay.py","live_href":"/v1/schema","binding":"immutable_source_sha256","sha256":"4145ed770e4f7e94567bece005c9506fe865ee9141c7f2730aee6edb6d271819"},{"id":"board_replay_contract","label":"Point-in-time board replay source","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/flowdensity/api/app.py","live_href":"/v1/schema","binding":"immutable_source_sha256","sha256":"eacefa4688115dede026b5ac0b5b6a089ec5de0b3dc97cc1ee9992a3cc24bd4c"},{"id":"scorecard_contract","label":"CP-072 scorecard contract source","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/flowdensity/calibration_scorecard.py","live_href":"/v1/scorecard","binding":"immutable_source_sha256","sha256":"66d07d4fb2684e2dc30c07613f2f46f54db4cb4f83644968318d456b71d5c49f"},{"id":"two_anchor_receipt","label":"Two-anchor admissible replay receipt","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/launch/fd-requested-symbol-two-anchor-admissible-replay-2026-07-17-v1.json","binding":"immutable_receipt","sha256":"f37cea4fa28a89f318987946d9478e6431df5e90052b88a893e7a7a74ae1ff87"},{"id":"ms1_runtime_receipt","label":"MS/1 countersign runtime receipt","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/launch/ms1-flow-countersign-runtime-2026-07-16-v2.json","binding":"immutable_receipt","sha256":"fe49d4e5dad6f09ec59c1600544bcd0b097b5d72859f95ac19799df8238bedb3"},{"id":"family_grammar_receipt","label":"Family availability grammar receipt","href":"https://github.com/FlyingMobula5/FlowDensity/blob/16e9bcd01e19457b4a5e9fbd6bbc45dbf40e0481/launch/flow-family-cohesion-doctrine-2026-07-20-v2.json","binding":"immutable_receipt","sha256":"cda29d606f96b22a42f69bc6d80b8d91ecb6dde108bfbf3d9b113c3527884c20"},{"id":"hub_bot_discovery_source","label":"Hub bot discovery source","href":"https://github.com/FlyingMobula5/MarketSchema/blob/e0f850ffe7bc0a9bbe71ae6f2b4af5db9b0650a5/src/api/v1/services/bot_capabilities.py","binding":"immutable_source_commit","sha256":"4922303b249b03c31d9648a4b5356539e0ff1e51344afe3e8d999bbefa797837"},{"id":"hub_ms1_signing_source","label":"Hub MS/1 signing source","href":"https://github.com/FlyingMobula5/MarketSchema/blob/e0f850ffe7bc0a9bbe71ae6f2b4af5db9b0650a5/src/api/services/ms1_signing.py","binding":"immutable_source_sha256","sha256":"edb64f73d9c489c0d44a3885ed6dcd6208555813356489b5502769c5c18f35e6"}],"contract_sha256":"24a52152c6644166eeba44b586a74b93d63d4aab2b050d98ca8607ebb6e71de1"}