schemas: MPCC event contract v0.1 — conversation + trading event family

CHANGELOG.md

@@ -9,6 +9,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Thi
 ## [Unreleased]
 
 ### Added
+- MPCC event contract v0.1 (conversation + trading event family): `ConversationEvent` (the canonical 26-field conversation-fabric event — causal parents, authority context with delegation chain, visibility scope, requested/approved/actual effect references, modality, speech act), `EffectRequest` / `EffectDecision` / `EffectRecord` (the requested → approved → actual → compensated effect lifecycle with idempotency keys, referencing `PolicyDecision` / `ExecutionDecision` rather than duplicating them), `NullAbsenceRecord` (12-kind null/absence taxonomy), and the trading families `MarketDataEvent`, `OrderIntent`, `ExecutionReport`, `PositionChange`, `ReconciliationRecord` as profiles of the ConversationEvent envelope (one shared envelope vocabulary; parity machine-enforced). Includes canonical examples telling one end-to-end governed trade story, negative conformance vectors (`fixtures/mpcc-event-contract/conformance.json`), a `validate-mpcc-event-examples` target, and a normative spec note (`specs/mpcc-event-contract.md`). Provenance: SocioProphet/profit-mpcc, hardened to the policy-integrity tranche-0001 strictness bar.
 - Epistemic Assay contracts: `ReasoningAssay` (a typed verdict on a claim over five orthogonal axes — method, binding, verifier, agreement, authority — whose `ok`/`sad`/`bad` `projectedState` is a render-time projection, not a stored scalar) and `AssayStandard` (a verifier's measured, versioned reliability — the calibration reference every assay must point at). Includes canonical `ok`/`sad`/`bad` examples, ADR (`docs/adr/ADR-epistemic-assay-verdict-v0-1.md`), and a `validate-reasoning-examples` target that also enforces projection soundness (recomputes `assay()` from the stored axes and fails on drift) and retroactively brings the existing reasoning family under `make validate`.
 - `ReasoningReceipt.assay` (optional) — the reserved receipt landing spot for the Assay: a render-time, run-level epistemic summary that references its run's `ReasoningAssay` records by URN (`assayRefs`) and surfaces the projected `overallState`, weakest-link `binding`, verifier `calibrationRef`, per-state `counts`, and `projectedAt`. A cache of the referenced verdicts, not authoritative over them — re-projectable when an `AssayStandard` improves. Backward-compatible (optional field). The assay's `authority` axis continues to mirror `EventEnvelope.actor`/`integrity`, so the envelope needs no structural change.
 - Onboarding control-plane contract family: `WorkspaceScope`, `TrustMode`, `CapabilityPack`, `ConnectorActionScope`, `AutomationTemplate`, and `OnboardingReceipt`, with canonical first-run examples, semantic vocabulary seed, ADR, and `validate-onboarding-examples` validation target.

Makefile

@@ -1,8 +1,12 @@
-.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples
+.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples
 
-validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples
+validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-agentic-os-examples validate-triparty-examples validate-labor-market-examples validate-supply-chain-risk-examples validate-reasoning-examples validate-mpcc-event-examples
 	@echo "OK: validate"
 
+validate-mpcc-event-examples:
+	python3 -m pip install --user jsonschema >/dev/null
+	python3 tools/validate_mpcc_event_examples.py
+
 validate-reasoning-examples:
 	python3 -m pip install --user jsonschema >/dev/null
 	python3 tools/validate_reasoning_examples.py

examples/conversation_event.json

@@ -0,0 +1,70 @@
+{
+ "id": "urn:srcos:conversation-event:desk_alpha_msg_000117",
+ "type": "ConversationEvent",
+ "specVersion": "0.1.0",
+ "actorRef": "urn:srcos:agent:strategy_momentum_7",
+ "authorityContext": {
+ "principal": "agent",
+ "delegationChain": ["urn:srcos:subject:desk_operator_1"],
+ "capabilities": ["trading.order.propose"],
+ "approvalState": "pending",
+ "policyContext": ["urn:srcos:policy:desk_alpha_limits"]
+ },
+ "workspaceRef": "urn:srcos:workspace:trading_demo",
+ "branchRef": "urn:srcos:branch:desk_alpha_main",
+ "visibilityScope": ["shared"],
+ "wallTime": "2026-07-28T13:30:00.250Z",
+ "logicalTime": 117,
+ "causalParents": ["urn:srcos:market-data-event:xnas_acme_quote_000042"],
+ "traceContext": {
+ "traceId": "trace_desk_alpha_0001",
+ "spanId": "span_proposal_0117",
+ "baggage": {
+ "desk": "alpha"
+ }
+ },
+ "modality": "tool_call",
+ "codec": "utf-8",
+ "rawPayload": {
+ "tool": "propose_order",
+ "arguments": {
+ "instrument": "ACME.XNAS",
+ "side": "buy",
+ "quantity": "100",
+ "limitPrice": "184.20"
+ }
+ },
+ "canonicalPayload": {
+ "normalizationRegime": "mpcc-canonical-json-v0",
+ "proposal": {
+ "instrument": "ACME.XNAS",
+ "side": "buy",
+ "quantity": "100",
+ "limitPrice": "184.20",
+ "rationale": "momentum breakout above vwap"
+ }
+ },
+ "signalStats": {
+ "tokenCount": 42,
+ "proposalConfidence": 0.82
+ },
+ "speechAct": "request",
+ "claims": [],
+ "entities": ["ACME.XNAS"],
+ "topics": ["urn:srcos:topic:acme_momentum"],
+ "requestedEffects": ["urn:srcos:effect:place_order_acme_000117"],
+ "approvedEffects": ["urn:srcos:effect-decision:approve_place_order_acme_000117"],
+ "actualEffects": ["urn:srcos:effect-record:place_order_acme_000117_r1"],
+ "provenanceLinks": [
+ {
+ "rel": "source_feed",
+ "ref": "urn:srcos:market-data-event:xnas_acme_quote_000042"
+ }
+ ],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": [],
+ "evaluationMetrics": {
+ "latencyMs": 12
+ },
+ "interactionEventRefs": ["urn:srcos:interaction-event:noetica_msg_9f3a"]
+}

examples/effect_decision.json

@@ -0,0 +1,43 @@
+{
+ "id": "urn:srcos:effect-decision:approve_place_order_acme_000117",
+ "type": "EffectDecision",
+ "specVersion": "0.1.0",
+ "effectRequestRef": "urn:srcos:effect:place_order_acme_000117",
+ "subjectEventRef": "urn:srcos:conversation-event:desk_alpha_msg_000117",
+ "decision": "approved",
+ "decidedByActorRef": "urn:srcos:subject:desk_operator_1",
+ "authorityContext": {
+ "principal": "user",
+ "delegationChain": [],
+ "capabilities": ["trading.order.approve"],
+ "approvalState": "approved",
+ "policyContext": ["urn:srcos:policy:desk_alpha_limits"]
+ },
+ "rationale": "Within desk limits; quantity narrowed from 100 to 50 under the open-notional exposure cap.",
+ "ruleRefs": ["rule:desk_alpha:max_open_notional"],
+ "policyDecisionRefs": ["urn:srcos:decision:pf_desk_alpha_7d21"],
+ "executionDecisionRef": null,
+ "approvedEffect": {
+ "effectKind": "execute",
+ "capability": "trading.order.place",
+ "target": {
+ "kind": "venue_order_gateway",
+ "identifier": "XNAS",
+ "location": "us-east"
+ },
+ "parameters": {
+ "instrument": "ACME.XNAS",
+ "side": "buy",
+ "quantity": "50",
+ "orderType": "limit",
+ "limitPrice": "184.20",
+ "timeInForce": "day"
+ }
+ },
+ "evidenceRefs": ["urn:srcos:market-data-event:xnas_acme_quote_000042"],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": ["notional:small"],
+ "decidedAt": "2026-07-28T13:30:02.000Z",
+ "expiresAt": "2026-07-28T13:35:00.000Z",
+ "decisionHash": "sha256:9f2b4a8c1d3e5f7a9b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c9d1e3f5a"
+}

examples/effect_record.json

@@ -0,0 +1,34 @@
+{
+ "id": "urn:srcos:effect-record:place_order_acme_000117_r1",
+ "type": "EffectRecord",
+ "specVersion": "0.1.0",
+ "effectRequestRef": "urn:srcos:effect:place_order_acme_000117",
+ "effectDecisionRef": "urn:srcos:effect-decision:approve_place_order_acme_000117",
+ "autonomousPolicyRef": null,
+ "status": "executed",
+ "executorRef": "urn:srcos:agent:execution_gateway_1",
+ "executionContext": {
+ "gateway": "fix44",
+ "session": "XNAS_A"
+ },
+ "actualEffect": {
+ "effectKind": "execute",
+ "capability": "trading.order.place",
+ "venueOrderRef": "XNAS-99120031",
+ "filledQuantity": "50",
+ "averagePrice": "184.18"
+ },
+ "idempotencyKey": "place_order_acme_000117_v1",
+ "startedAt": "2026-07-28T13:30:02.150Z",
+ "completedAt": "2026-07-28T13:30:02.500Z",
+ "resultRefs": ["urn:srcos:execution-report:xnas_fill_88231"],
+ "compensationRefs": [],
+ "provenanceLinks": [
+ {
+ "rel": "executes",
+ "ref": "urn:srcos:effect:place_order_acme_000117"
+ }
+ ],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": []
+}

examples/effect_request.json

@@ -0,0 +1,30 @@
+{
+ "id": "urn:srcos:effect:place_order_acme_000117",
+ "type": "EffectRequest",
+ "specVersion": "0.1.0",
+ "requestedByEventRef": "urn:srcos:conversation-event:desk_alpha_msg_000117",
+ "requestedByActorRef": "urn:srcos:agent:strategy_momentum_7",
+ "workspaceRef": "urn:srcos:workspace:trading_demo",
+ "branchRef": "urn:srcos:branch:desk_alpha_main",
+ "effectKind": "execute",
+ "capability": "trading.order.place",
+ "target": {
+ "kind": "venue_order_gateway",
+ "identifier": "XNAS",
+ "location": "us-east"
+ },
+ "parameters": {
+ "instrument": "ACME.XNAS",
+ "side": "buy",
+ "quantity": "100",
+ "orderType": "limit",
+ "limitPrice": "184.20",
+ "timeInForce": "day"
+ },
+ "idempotencyKey": "place_order_acme_000117_v1",
+ "requiresHumanApproval": true,
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": ["notional:small"],
+ "requestedAt": "2026-07-28T13:30:00.300Z",
+ "notes": "Momentum entry proposed by strategy_momentum_7; desk approval required by policy."
+}

examples/execution_report.json

@@ -0,0 +1,32 @@
+{
+ "id": "urn:srcos:execution-report:xnas_fill_88231",
+ "type": "ExecutionReport",
+ "specVersion": "0.1.0",
+ "wallTime": "2026-07-28T13:30:02.480Z",
+ "logicalTime": 119,
+ "orderIntentRef": "urn:srcos:order-intent:acme_buy_000117",
+ "venueRef": "XNAS",
+ "reportKind": "fill",
+ "orderRef": "XNAS-99120031",
+ "fillQuantity": "50",
+ "fillPrice": "184.18",
+ "remainingQuantity": "0",
+ "sequenceRef": 4711187,
+ "causalParents": ["urn:srcos:order-intent:acme_buy_000117"],
+ "traceContext": {
+ "traceId": "trace_desk_alpha_0001",
+ "spanId": "span_report_0119"
+ },
+ "visibilityScope": ["shared"],
+ "provenanceLinks": [
+ {
+ "rel": "venue_report",
+ "ref": "drop_copy:xnas:session_a:88231"
+ }
+ ],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": [],
+ "details": {
+ "liquidityFlag": "removed"
+ }
+}

examples/market_data_event.json

@@ -0,0 +1,41 @@
+{
+ "id": "urn:srcos:market-data-event:xnas_acme_quote_000042",
+ "type": "MarketDataEvent",
+ "specVersion": "0.1.0",
+ "wallTime": "2026-07-28T13:30:00.125Z",
+ "logicalTime": 42,
+ "instrumentRef": "ACME.XNAS",
+ "venueRef": "XNAS",
+ "eventKind": "quote",
+ "sequenceRef": 4711042,
+ "feedRef": "feed_xnas_l1_a",
+ "rawPayload": {
+ "b": "184.15",
+ "a": "184.20",
+ "bs": 300,
+ "as": 500
+ },
+ "canonicalPayload": {
+ "normalizationRegime": "mpcc-canonical-quote-v0",
+ "bidPrice": "184.15",
+ "askPrice": "184.20",
+ "bidSize": "300",
+ "askSize": "500"
+ },
+ "nullAbsenceRef": null,
+ "qualityFlags": [],
+ "causalParents": [],
+ "traceContext": {
+ "traceId": "trace_desk_alpha_0001",
+ "spanId": "span_feed_0042"
+ },
+ "visibilityScope": ["shared"],
+ "provenanceLinks": [
+ {
+ "rel": "source_feed",
+ "ref": "feed_xnas_l1_a"
+ }
+ ],
+ "policyLabels": ["market-data:realtime"],
+ "riskLabels": []
+}

examples/null_absence_record.json

@@ -0,0 +1,22 @@
+{
+ "id": "urn:srcos:null-absence:xnas_feed_gap_000043",
+ "type": "NullAbsenceRecord",
+ "specVersion": "0.1.0",
+ "kind": "no_event_observed",
+ "observedAt": "2026-07-28T13:31:15.000Z",
+ "relatedEventRef": "urn:srcos:market-data-event:xnas_acme_quote_000042",
+ "relatedBranchRef": "urn:srcos:branch:desk_alpha_main",
+ "relatedWorkspaceRef": "urn:srcos:workspace:trading_demo",
+ "causalNotes": "Feed sequence gap after 4711042; venue heartbeat missed for 75 seconds. Recorded as no_event_observed, not transport_failure, until the feed handler attributes a cause.",
+ "policyLabels": ["feed:gap"],
+ "provenanceLinks": [
+ {
+ "rel": "detected_by",
+ "ref": "monitor:xnas_l1_a"
+ }
+ ],
+ "details": {
+ "expectedNextSequence": 4711043,
+ "gapSeconds": 75
+ }
+}

examples/order_intent.json

@@ -0,0 +1,46 @@
+{
+ "id": "urn:srcos:order-intent:acme_buy_000117",
+ "type": "OrderIntent",
+ "specVersion": "0.1.0",
+ "actorRef": "urn:srcos:agent:strategy_momentum_7",
+ "authorityContext": {
+ "principal": "agent",
+ "delegationChain": ["urn:srcos:subject:desk_operator_1"],
+ "capabilities": ["trading.order.propose"],
+ "approvalState": "approved",
+ "policyContext": ["urn:srcos:policy:desk_alpha_limits"]
+ },
+ "workspaceRef": "urn:srcos:workspace:trading_demo",
+ "branchRef": "urn:srcos:branch:desk_alpha_main",
+ "visibilityScope": ["shared"],
+ "wallTime": "2026-07-28T13:30:02.100Z",
+ "logicalTime": 118,
+ "causalParents": [
+ "urn:srcos:conversation-event:desk_alpha_msg_000117",
+ "urn:srcos:market-data-event:xnas_acme_quote_000042"
+ ],
+ "traceContext": {
+ "traceId": "trace_desk_alpha_0001",
+ "spanId": "span_intent_0118"
+ },
+ "strategyRef": "strat_momentum_7",
+ "instrumentRef": "ACME.XNAS",
+ "venueRef": "XNAS",
+ "intentKind": "new",
+ "side": "buy",
+ "orderType": "limit",
+ "quantity": "50",
+ "price": "184.20",
+ "timeInForce": "day",
+ "requestedEffectRef": "urn:srcos:effect:place_order_acme_000117",
+ "signalRefs": ["urn:srcos:market-data-event:xnas_acme_quote_000042"],
+ "provenanceLinks": [
+ {
+ "rel": "approved_by",
+ "ref": "urn:srcos:effect-decision:approve_place_order_acme_000117"
+ }
+ ],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": ["notional:small"],
+ "notes": "Quantity reflects the approved (narrowed) effect shape, not the original proposal."
+}

examples/position_change.json

@@ -0,0 +1,29 @@
+{
+ "id": "urn:srcos:position-change:acme_desk_alpha_000120",
+ "type": "PositionChange",
+ "specVersion": "0.1.0",
+ "wallTime": "2026-07-28T13:30:02.600Z",
+ "logicalTime": 120,
+ "instrumentRef": "ACME.XNAS",
+ "accountRef": "acct_desk_alpha",
+ "positionDelta": "50",
+ "cashDelta": "-9209.00",
+ "feeDelta": "-1.25",
+ "realizedPnlDelta": null,
+ "unrealizedPnlSnapshot": "12.50",
+ "sourceExecutionRefs": ["urn:srcos:execution-report:xnas_fill_88231"],
+ "causalParents": ["urn:srcos:execution-report:xnas_fill_88231"],
+ "traceContext": {
+ "traceId": "trace_desk_alpha_0001",
+ "spanId": "span_position_0120"
+ },
+ "visibilityScope": ["shared"],
+ "provenanceLinks": [
+ {
+ "rel": "derived_from",
+ "ref": "urn:srcos:execution-report:xnas_fill_88231"
+ }
+ ],
+ "policyLabels": ["desk:alpha"],
+ "riskLabels": []
+}