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

[mdheller]

What changed

Lands the MPCC (multi-party conversation control) conversation-event contract v0.1 plus the trading event family as first-class typed contracts, imported from SocioProphet/profit-mpcc and hardened from its loose drafts to the strictness bar set by profit-mpcc's own policy-integrity tranche-0001 snapshots: additionalProperties:false on every object, specVersion pinned to const 0.1.0 (per-family contract version, in the style of the in-repo *.v1.1.json control-plane contracts), anchored urn:srcos: id patterns, mandatory idempotency keys, and required fields limited to source-required fields or stated invariants.

Schemas added (10) + provenance

Schema	URN prefix	Source in SocioProphet/profit-mpcc
ConversationEvent.json	urn:srcos:conversation-event:	schemas/event.schema.json + docs/canonical-event-schema.md
EffectRequest.json	urn:srcos:effect:	schemas/effect-request.schema.json + exports/policy-integrity/tranche-0001/effect.schema.snapshot.json
EffectDecision.json	urn:srcos:effect-decision:	schemas/approval-event.schema.json + exports/policy-integrity/tranche-0001/decision.schema.snapshot.json + docs/effect-approval-semantics.md
EffectRecord.json	urn:srcos:effect-record:	schemas/effect-record.schema.json + exports/policy-integrity/tranche-0001/effect.schema.snapshot.json
NullAbsenceRecord.json	urn:srcos:null-absence:	schemas/null-absence.schema.json + docs/null-absence-taxonomy.md (12-kind taxonomy, verbatim)
MarketDataEvent.json	urn:srcos:market-data-event:	schemas/market-data-event.schema.json
OrderIntent.json	urn:srcos:order-intent:	schemas/order-intent-event.schema.json
ExecutionReport.json	urn:srcos:execution-report:	schemas/execution-report-event.schema.json
PositionChange.json	urn:srcos:position-change:	schemas/position-change-event.schema.json
ReconciliationRecord.json	urn:srcos:reconciliation-record:	schemas/reconciliation-event.schema.json

Plus: 10 canonical examples telling one end-to-end governed trade story (quote -> agent proposal -> effect request -> human approval w/ policy-narrowed rewrite -> order intent -> venue fill -> effect record -> position change -> EOD reconciliation, plus a typed feed-gap absence), negative conformance vectors (fixtures/mpcc-event-contract/conformance.json), tools/validate_mpcc_event_examples.py wired as make validate-mpcc-event-examples (and into make validate), a normative spec note (specs/mpcc-event-contract.md), and schemas/README.md + CHANGELOG.md entries.

One envelope, not two

The five trading events are structural profiles of the ConversationEvent envelope: they carry the identical shared vocabulary (specVersion, actorRef, workspaceRef, branchRef, visibilityScope, wallTime, logicalTime, causalParents, traceContext, provenanceLinks, policyLabels, riskLabels, plus the shared authorityContext block), with parity machine-enforced by the validator — any drift fails the build. Required-ness varies per family (venue-originated MarketDataEvent doesn't require actorRef; ConversationEvent/OrderIntent do); the vocabulary may not. allOf composition was rejected because this repo requires additionalProperties:false on every object (CONTRIBUTING.md), which is incompatible with allOf envelope reuse in draft 2020-12 short of introducing unevaluatedProperties — used nowhere in the v2 family. Self-contained strict files match both the house style and the tranche-0001 snapshots.

Overlap decisions (spec-first, nothing duplicated)

• EventEnvelope — kept as the AsyncAPI wire wrapper; MPCC events are domain objects that ride in its payload. Different layer, no competition.
• SourceOSInteractionEvent — surface/interaction telemetry stays there; ConversationEvent is the durable fabric record and bridges by reference via interactionEventRefs (urn:srcos:interaction-event: pattern).
• PolicyDecision — not duplicated; EffectDecision.policyDecisionRefs (urn:srcos:decision: pattern) references it as the policy-evaluation basis. EffectDecision remains necessary: neither existing decision type carries the approved effect shape or the requested->approved->actual chain.
• ExecutionDecision — not duplicated; EffectDecision.executionDecisionRef (urn:srcos:exec-decision: pattern) references it when an agent-session gate participated.
• runtime-effect-decision.v1.1 — distinct concern (control-plane event-pipeline dispatch); untouched.
• SettlementEvent — distinct concern (FogCompute usage-receipt settlement); ReconciliationRecord covers post-trade reconciliation incl. settlement-window scope, stated in its description.
• AbstentionEvent (in-flight on feat/sp-patt-warr-001-schemas, not on main) — no file or concept collision: that is a warrant-ceiling authority event; NullAbsenceRecord's abstention kind classifies an observed absence in the event fabric. Complementary — an abstention occurrence can be recorded as kind: abstention + relatedEventRef. No structural dependency taken.
• Topic — ConversationEvent.topics may carry urn:srcos:topic: URNs where the fog-layer Topic applies.
• decisionHash follows the existing PolicyDecision/ExecutionDecisionsha256: convention; scalar-map fields follow the AgentMachineReceipt.metrics convention.

Exact commands run

make validate
python3 scripts/check_duplicate_schema_ids.py
# CI example sweep (same logic as .github/workflows/validate.yml "Validate examples against schemas")
ajv compile -s schemas/<each of the 10>.json --strict=false --spec=draft2020

Pass/fail output summary

make validate — all family targets green, ending:

 "ok": true
}
OK: validate

validate-mpcc-event-examples (full check detail — 34/34 true):

{
"checks": {
"envelope-parity:ExecutionReport.json": true,
"envelope-parity:MarketDataEvent.json": true,
"envelope-parity:OrderIntent.json": true,
"envelope-parity:PositionChange.json": true,
"envelope-parity:ReconciliationRecord.json": true,
"envelope-parity:authorityContext": true,
"example:conversation_event.json": true,
"example:effect_decision.json": true,
"example:effect_record.json": true,
"example:effect_request.json": true,
"example:execution_report.json": true,
"example:market_data_event.json": true,
"example:null_absence_record.json": true,
"example:order_intent.json": true,
"example:position_change.json": true,
"example:reconciliation_record.json": true,
"lifecycle:effect-chain": true,
"lifecycle:trading-chain": true,
"negative:0:ConversationEvent.json": true,
"negative:1:EffectRecord.json": true,
"negative:2:MarketDataEvent.json": true,
"negative:3:EffectRequest.json": true,
"negative:4:NullAbsenceRecord.json": true,
"negative:5:OrderIntent.json": true,
"strictness:ConversationEvent.json": true,
"strictness:EffectDecision.json": true,
"strictness:EffectRecord.json": true,
"strictness:EffectRequest.json": true,
"strictness:ExecutionReport.json": true,
"strictness:MarketDataEvent.json": true,
"strictness:NullAbsenceRecord.json": true,
"strictness:OrderIntent.json": true,
"strictness:PositionChange.json": true,
"strictness:ReconciliationRecord.json": true
},
"ok": true
}

Guardrails:

OK: 298 unique schema $id values
Results: 189 passed, 81 skipped, 0 failed
schema schemas/ConversationEvent.json is valid (… all 10 "is valid" under ajv --spec=draft2020)

Known gaps (deliberate, v0.1)

• No OpenAPI/AsyncAPI operations or semantic/context.jsonld mappings yet — matches how the recent contract families (reasoning, agent-machine, pattern-warrant) landed; the context-mapping CI step warns without failing. Wiring follows once names settle.
• claims/entities are free-form stable references (typed claim/entity contracts are future work); workspaceRef/branchRef are free-form pending adoption of the profit-mpcc branch-id contract.
• The signal-event family and trading-approval variants beyond the effect lifecycle (profit-mpcc docs/trading-event-families.md §2/§4) are not yet landed.
• Merging this after feat/sp-patt-warr-001-schemas (or vice versa) will produce a trivial Makefile conflict (both append a validate target); either order resolves in seconds.

Blocked

Nothing blocked.