[chain-pr 10/10] Documentation updates

[maxep]

This PR is part of a chain split from maxep/message-bus-subscription by chain-pr.

What and why?

As the chain migrates all SDK modules off the legacy FeatureMessage API, ARCHITECTURE.md and AGENTS.md become misleading: they describe FeatureMessage, FeatureMessageReceiver, and CombinedFeatureMessageReceiver as the canonical patterns, with no mention of the replacement. Developers touching the bus would follow the wrong path.

This PR is the documentation layer: it adds a dedicated MESSAGE_BUS.md reference, updates ARCHITECTURE.md to deprecate the old sections in-place, and wires AGENTS.md so contributors land on the right doc immediately.

How?

New file — docs/MESSAGE_BUS.md

Comprehensive reference for the typed bus:

Section	Content
Core protocols	BusMessage, BusMessageReceiver, MessageBus, MessageBusSubscription — role and location of each
Receiver-based subscription	How to implement BusMessageReceiver, when to use it (long-lived feature objects), where to subscribe (in enable(with:in:))
Closure-based subscription	subscribe(block:) / MessageBusSubscription pattern for ad-hoc subscriptions; CrashContextCoreProvider as a canonical example
Sending messages	send(message:) and send(message:else:) with fallback; note on async dispatch
Supported messages	Full table of every BusMessage type: key, sender, consumer(s)
Adding a new message	Step-by-step guide: define the type, conform to BusMessage, subscribe, send
Threading	Bus dispatches on its own serial queue — do not block
Testing	How to use PassthroughMessageBusMock and TelemetryReceiverMock in unit tests

Updated — docs/ARCHITECTURE.md

The "Message Types", ".context Pattern", ".payload Pattern", and "CombinedFeatureMessageReceiver" sections are struck through and annotated as deprecated, with inline replacement guidance pointing to the new BusMessage API. The RUMCoreContext section is explicitly noted as not deprecated.

Updated — AGENTS.md

• MESSAGE_BUS.md added to the docs/ directory listing with a one-line description
• "Send or receive messages between features" added to the navigation table, pointing to docs/MESSAGE_BUS.md

Review checklist

• Feature or bugfix MUST have appropriate tests (unit, integration)
• Make sure each commit and the PR mention the Issue number or JIRA reference
• Add CHANGELOG entry for user facing changes
• Add Objective-C interface for public APIs - see our guidelines (internal)
• Run make api-surface when adding new APIs

---

Chain overview

#	PR	Title
1	#2927	Typed MessageBus protocol and shared message types
2	#2928	Test infrastructure for typed message bus
3	#2929	DatadogCore: CoreMessageBus implementation and rename
4	#2930	DatadogCrashReporting: typed-bus migration
5	#2931	DatadogLogs: typed-bus migration
6	#2932	DatadogTrace: typed-bus migration
7	#2933	DatadogFlags: typed-bus migration
8	#2934	DatadogRUM: typed-bus migration and TelemetryInterceptor merge
9	#2935	DatadogSessionReplay and DatadogWebViewTracking: typed-bus migration
10	← this PR	Documentation updates

graph LR
    G1["1 — Typed MessageBus protocol and shared message types"]
    G2["2 — Test infrastructure for typed message bus"]
    G3["3 — DatadogCore: CoreMessageBus implementation and rename"]
    G4["4 — DatadogCrashReporting: typed-bus migration"]
    G5["5 — DatadogLogs: typed-bus migration"]
    G6["6 — DatadogTrace: typed-bus migration"]
    G7["7 — DatadogFlags: typed-bus migration"]
    G8["8 — DatadogRUM: typed-bus migration and TelemetryInterceptor merge"]
    G9["9 — DatadogSessionReplay and DatadogWebViewTracking: typed-bus migration"]
    G10["10 — Documentation updates"]
    G1 --> G2
    G2 --> G3
    G3 --> G4
    G3 --> G5
    G5 --> G6
    G3 --> G7
    G6 --> G8
    G7 --> G8
    G8 --> G9
    G1 --> G10

Loading

Merge in dependency order. PRs with no incoming edges from un-merged PRs can be reviewed in parallel.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d7175062cd

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Point contributors at the wired bus implementation

In this branch there is no DatadogCore/Sources/Core/CoreMessageBus.swift (repo-wide rg "CoreMessageBus" finds only this doc), and DatadogCore still owns DatadogCore/Sources/Core/MessageBus.swift, which dispatches legacy FeatureMessage; DatadogCoreProtocol.messageBus currently falls back to NOPMessageBus() with no concrete override. Following this new reference would make feature authors subscribe/send through an unwired no-op typed bus instead of the implementation that actually delivers messages in this commit.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Use the actual bus message type name

The public message type in DatadogInternal/Sources/Models/RUM/RUMPayloadMessages.swift is RUMViewResetMessage, not RUMViewReset (confirmed with repo-wide rg "RUMViewReset"). The sending example as written will not compile for anyone following the new guide, and the same wrong name is repeated in the supported-message table.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Correct the documented message keys

These keys do not match the source: DatadogContext.key is "core-context" in DatadogInternal/Sources/Context/DatadogContext.swift, and LogMessage.key is "log" in DatadogInternal/Sources/Models/Logs/LogMessage.swift. Since this table is the new uniqueness reference for adding bus messages, the wrong values can lead contributors to choose colliding or incompatible keys.

Useful? React with 👍 / 👎.