Event contracts (external)¶
Partner-facing asynchronous contracts. Internal pipeline topic names are not part of the partner contract and are omitted here on purpose.
Separation rule¶
| Layer | Documented here? |
|---|---|
| HTTP callbacks and external message payloads/attributes you must consume | Yes |
| Platform-internal fan-out between MasteryHive services | No — internal docs only |
Fraud — report delivery¶
Primary partner async completion for TM reports is HTTP: Fraud report callback.
Scoring services may also emit post-action style messages for the banking application to consume. The consumer of those triggers is not verified in the AI documentation source tree — treat as programme-specific until your backend contract is agreed.
Reconciliation — exception resolve (messaging)¶
| Item | Contract |
|---|---|
| Transport | Message pull is primary in production where enabled; HTTP fallback exists |
| Payload | Same resolve body as HTTP — exception resolve |
| Idempotency | resolution_request_id required on the messaging path |
| Ordering | Not a global ordered queue guarantee — design for concurrent cluster updates |
| Retry | At-least-once; dedupe on resolution_request_id |
| DLQ | Failed resolves should not be silently dropped — environment-specific DLQ/replay is platform-operated |
Subscription names and project ids are environment configuration, not public constants.
Reconciliation — asset / software records¶
External record events for asset sessions: Asset event contract.
| Concern | Expectation |
|---|---|
| Envelope attributes | Include type / reconciliation type markers described in that contract |
| Delivery | At-least-once publish to the software backend |
| Ordering | Per-record progression unmatched → matched; do not assume total global order |
| Dedup | Consumers should upsert by record ids |
| DLQ | Platform-operated for publisher failures; consumer DLQ is your responsibility |
Delivery semantics (shared vocabulary)¶
| Term | Meaning |
|---|---|
| At-least-once | Duplicates possible — idempotent consumers required |
| Ordering | Only where a contract explicitly promises it |
| Retry | Transient transport/dependency failures |
| Deduplication | By stable business ids (resolution_request_id, record ids, prediction hash) |
| DLQ | Poison / exhausted messages — ops replay, not silent discard |