Every event and record shape that crosses a process or system boundary, with where it is written and read, what identifies it, and what lineage it keeps.
Five shapes exist in the code. The one ingest envelope at the end (ADR 0060 seam S4, docs/adr/0060-self-learning-seams.md) is built: the webhook ingest route and the eventbus carry it; connector streams, the realtime feed and platform events do not yet.
Canonical post-transform shape per target stream; 29 streams in TARGET_STREAMS (packages/connectors/core/src/mapping/spec.ts:14). Bronze raw_events holds orders, creators, inventory; every other stream lands in import_staging_rows (§17).
POST /api/ingest/webhook/<tiktok-shop|shopee>/<connectorId>; HMAC header x-yng-signature (route.ts:101-120). The derived values below become one eventEnvelopeSchema envelope (route.ts:157-175); a delivery whose values do not fit it answers 400 invalid_payload. The body lands in raw_events.payload unchanged. Body cap and rate limit: Limits and budgets.
Derived value
Source fields, in order
Fallback
Code
eventType
eventType, type, code, topic
'webhook.received'
route.ts:240-242
streamName
inventory when the type contains inventory/stock or skuId/item_id is set
Producers validate the payload (bus.ts:164); subscribers parse the payload only, not the envelope (packages/eventbus/src/subscribe.ts:188-189, :500-501). EventEnvelope fields: id, schema_version (both absent on entries published before S4), topic, payload, publishedAt (ISO), producer (bus.ts:55-69). Broadcast topics use one stream for all orgs (bus.ts:126-135).
Topic
Payload fields
Publisher
Subscriber
chat.tool_called
orgId, brandId, conversationId, toolName, durationMs, ok (bus.ts:40-47)
apps/web/src/server/chat/tools/factory.ts:118-129
none; stream length counted by apps/worker/src/metrics.ts:384
One stream per org, fields type, orgId, at, payload (untyped record). Read by tRPC subscription.events (subscription.ts:23-58) for apps/web/src/app/(dashboard)/workspaces/ops/realtime-feed.tsx:18.
Type
Publisher and payload keys
order.created
one OrderEventPayloadSchema (realtime.ts): platform, platformOrderId, optional orderId, status; webhook (phase-b.ts) sets all four, polling sync (apps/worker/src/processors/sync.ts) the first two
Envelope id, type, org_id, occurred_at, data; id is also X-MSO-Event-Id (webhooks.ts:5-17). Payload fields, signing, retries and deduplication: Platform API and events, section "Signing, retries and idempotency".
Type
Direction
Writer
Reader
org.app.changed
MSO to app
apps/web/src/server/platform/org-app-changed.ts:32 via writePlatformEventapps/web/src/server/platform/outbox.ts:26
webhook ingest and eventbus carry schema_version; connector streams, the realtime feed and platform events do not; a stream field change is a code release (streams.ts:16-19)
Realtime feed carries no event id
each publish mints a Redis entry id (apps/worker/src/events-bus.ts:12)
Declared types with no publisher
creator.hour_spike
payload_hash ignores nested values
a key array as the JSON.stringify replacer filters every level (bronze-util.ts:13): {data:{status:'PAID'}} and {data:{status:'SHIPPED'}} hash equal, so the second hits onConflictDoNothing on both bronze writers (route.ts:171, apps/worker/src/processors/bronze.ts:72, :76)
Webhook identity falls back to receive time and a hash
route.ts:224-240; the bronze row has no brand_id or source_batch_id (route.ts:160-170)
Webhook payload is open-ended
.passthrough() (route.ts:37)
Gold and decisions have no watermark writer
source_watermark exists on agg_* and decision_episodes (0253); nothing writes it yet
One Zod eventEnvelopeSchema in packages/platform-contract/src/event-envelope.ts (@younetgroup/platform-contract 0.3.0); eventEnvelopeOf(dataSchema) types data. Guard: scripts/audit/event-envelope-single-schema.py (§205).
Field
Type
Webhook ingest
Eventbus
id
string 1-128; idempotency key
deriveEventEnvelopeId: sha256 of the raw_events dedupe tuple
randomUUID() per publish
type
string 1-160
derived eventType
topic
org_id
uuid
the authenticated connector's org
orgId in the payload
brand_id
uuid, nullable, optional
not set (a webhook carries no brand, ADR 0028 D5)
brandId in the payload
occurred_at
ISO 8601 with offset
derived occurredAt
publishedAt
source_system
string 1-64
connector type
producer
source_ref
string 1-256
derived externalId
none
schema_version
integer ≥ 1; EVENT_ENVELOPE_SCHEMA_VERSION
1
1
data
any
the vendor body, verbatim
payload
The eventbus keeps its wire field names (the right column) so entries already in Redis still parse, and adds id and schema_version. Platform events keep their 0.2.0 shape (id, type, org_id, occurred_at, data).