docs: add custom workload MQTT contract guidance to AIO messaging paper

[Alain Uyidi (auyidi1)]

Pull Request

Description

Adds a Custom Workload Messaging Contracts section to docs/solution-technology-paper-library/aio-messaging-design.md. The section gives product-neutral guidance for custom workloads that publish to or consume from the AIO MQTT broker:

• Versioned topics: a major version segment, opaque non-identifying segments, and concrete publish topics. It explains how the grammar relates to ADR asset and UNS topics.
• Publish loops: recommends that workloads never publish to a topic matching any of their own subscription filters. This mirrors the AIO 2609 MQTT connector rule that rejects identical source and destination topics, and notes that the check doesn't cover wildcard overlap.
• Message envelopes: carried as CloudEvents attributes through the MQTT binding (binary mode, MQTTv5 user properties), consistent with the paper's existing Data Source convention. A table maps each field to its attribute and defines the version split between the topic and dataschema. Existing schemas such as the 507 image_snapshot v1 schema from feat(application): add transport-independent snapshot-normalizer-core crate to component 507 #831 are referenced, not redefined.
• Workload identity and least-privilege authorization:
  • TLS-only listeners and default-deny only when authorization is bound through authorizationRef.
  • Projected service account tokens or X.509, with client IDs that are unique per replica and stable for persistent sessions.
  • Connect rules scoped to each principal's client IDs, with principal token substitution for per-workload topic scoping.
  • AIO 2609 as the minimum for shared subscriptions, and TLS plus authentication for external brokers.
• Payload-safe diagnostics: randomly generated IDs, keyed digests only, and language-neutral guidance on string and debug representations.
• Synthetic contract validation: broker-independent unit cases, a separate authorization integration check, and deduplication scope, window, and replica-sharing rules.
• Contract ownership: producer, consumer, deployment-owner, and security-review responsibilities.

The guidance is documentation only. It adds no broker configuration, runtime code, or environment-specific values. The PR also updates the paper's existing schema-generation tool link (the old URL returns 404), its frontmatter description, keywords, and reading time, and adds SUBACK to the IoT Operations spelling dictionary.

Related Issue

Refs #835. Once the owner approvals below are recorded on this PR, #835 can be closed.

Owner Decisions From #835

#	Decision	Status
D1	Destination	✅ Marcel Bindseil (@bindsi): extending aio-messaging-design.md is fine
D2	Security owner	Marcel Bindseil (@bindsi) will review. His three required changes are applied: authorization bound through authorizationRef, Connect rules scoped to each principal's client IDs, and TLS for listeners and external brokers. Awaiting sign-off.
D3	Envelope alignment with CloudEvents	Applied: the envelope is carried as CloudEvents attributes through the MQTT binding, with a field mapping. Awaiting confirmation.
D4	Privacy review	Marcel Bindseil (@bindsi): not needed if identifier rules are tightened. Applied: {producer} and {resource-id} are opaque, logged topics exclude identifiers, IDs are generated randomly, and digests are keyed (HMAC). Awaiting confirmation.
D5	Principal substitution in topic rules	Included: {principal.attributes.<name>} on the {producer} segment, and {principal.clientId} only with client-ID-scoped Connect rules. Awaiting confirmation.
D6	Scope	Product-neutral content, synthetic examples, public Microsoft Learn and release-note sources
D7	Component 507 non-conflict	✅ Resolved 2026-10-07 by Alain Uyidi (@auyidi1). The section references the image_snapshot v1 schema and doesn't replace any component-owned schema.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Blueprint modification or addition
• Component modification or addition
• Documentation update
• CI/CD pipeline change
• Other (please describe):

Implementation Details

Sources:

• Configure MQTT broker authentication: SAT audience, token refresh, X.509
• Configure MQTT broker authorization:
  • allow-only rules;
  • authorizationRef binding, which also requires a linked BrokerAuthentication;
  • disabling authorization by omitting authorizationRef;
  • token substitution;
  • client-ID-scoped Connect rules
• Shared subscriptions
• AIO 2609 (1.4.112) release notes: publish-loop prevention, rejection of anonymous auth to external brokers, and the shared-subscription authorization fix
• MQTT QoS ADR: QoS 2 limitation
• CloudEvents MQTT protocol binding

Testing Performed

• Terraform plan/apply
• Blueprint deployment test
• Unit tests
• Integration tests
• Bug fix includes regression test (see Test Policy)
• Manual validation
• Other: documentation linting

Validation Steps

1. markdownlint, markdown-table-formatter, and cspell pass for the changed file.
2. markdown-link-check passes for the changed file, including the updated tool link, the release-notes and Learn links, and the relative link to image-snapshot-v1.schema.json.
3. The frontmatter validator passes.
4. Gitleaks finds no leaks.
5. Manual validation compared each broker-behavior claim with the linked Learn pages and the 2609 release notes. This covered the default-deny binding, token substitution, Connect client-ID scoping, SAT audience and token refresh, and the three 2609 changes. Each envelope mapping was checked against the CloudEvents attributes in the paper's Data Source section.

Checklist

• I have updated the documentation accordingly
• I have added tests to cover my changes
• All new and existing tests passed
• I have run terraform fmt on all Terraform code
• I have run terraform validate on all Terraform code
• I have run az bicep format on all Bicep code
• I have run az bicep build to validate all Bicep code
• I have checked for any sensitive data/tokens that should not be committed
• Lint checks pass (run applicable linters for changed file types)

Security Review

• No credentials, secrets, or tokens are hardcoded or logged
• RBAC and identity changes follow least-privilege principles: N/A, no RBAC change. The authorization guidance itself awaits security-owner sign-off (D2).
• No new network exposure or public endpoints introduced without justification: N/A, no network change
• Dependency additions or updates have been reviewed for known vulnerabilities
• Container image changes use pinned digests or SHA references

Additional Notes

• The frontmatter validator warns about ms.topic: solution-article on this file. The warning predates this change, and I left the value alone so the paper's documentation-site placement doesn't change.
• The new section keeps contractions, following the repository writing-style guidance. Happy to expand them to match the rest of the paper if you prefer.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-10-05 22:11:46 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	223
Infrastructure Components	232
Blueprints	40
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	538

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.

[Alain Uyidi (auyidi1)]

Decision 5 (component 507) is resolved: I confirmed the guidance doesn't conflict with the image_snapshot v1 schema from #831. Still open for reviewers: destination (1), security owner (2), and privacy review (3).

[Marcel Bindseil (bindsi)]

Thanks Alain, this is a solid, well-scoped addition and the core guidance is sound. On the owner decisions:

1. Destination: Extending aio-messaging-design.md is fine. The paper already covers custom workloads on AIO messaging.
2. Security: I'm OK to review this, with three changes needed before sign-off:
   • State that default-deny only applies when a BrokerAuthorization is bound to the listener via authorizationRef.
   • Scope Connect rules so a principal can only use its own client IDs, which prevents cross-workload session takeover.
   • Require TLS for listeners and external brokers.
3. Privacy: A separate review isn't needed if the identifier rules are tightened:
   • {producer} and {resource-id} stay opaque and non-identifying.
   • Logged topics contain no site, customer, or person identifiers.
   • Correlation IDs are random.
   • Any payload digest is keyed (HMAC).

The main blocker is #835 decision 3, which isn't in the PR's decision list. Earlier in the same paper, custom connectors are told to follow the CloudEvents MQTT binding. The new envelope defines parallel fields with no mapping and doesn't say whether they're carried as MQTTv5 properties or in the body. Please either map each field to its CloudEvents attribute, or explicitly scope the envelope away from that convention. Decision 5 (principal substitution in topic rules) should also be added or explicitly deferred.

Smaller items:

• Reconcile "no site identifiers in topics" with the paper's site01/... asset example and the UNS section.
• Broaden the publish-loop rule to wildcard subscriptions that match the workload's own output.
• Clarify dedup scope and window, and the meaning of "client ID per trust boundary" vs. "per replica".
• Link the AIO 2609 release notes for the three version-specific claims.
• Update estimated_reading_time and keywords.
• Rebase on main, since the branch is behind.
• Consider Refs #835 until the owner approvals are recorded on the PR.

Happy to re-review once these are in.

---

PR description items (not anchorable inline; document findings are inline):

• Owner Decisions list (Medium): add #835 D3 (envelope alignment with CloudEvents) and D5 (which topic segments may use authenticated-principal substitution), and name who resolved the Component 507 item.
• Closes #835 (Medium): merging closes #835 while documentation-owner confirmation, security-owner approval, and two reviewer approvals are still open. Record approvals here before merge, or switch to Refs #835.
• Branch BEHIND main (Medium): update and let the docs checks re-run on the new head.
• Security Review checkboxes (Low): "RBAC and identity changes follow least-privilege" and "No new network exposure" are checked, but this PR has no RBAC or network change. Mark them N/A pending security-owner review so they aren't read as sign-off.
• Republish rule wording (Low): the description calls it "the AIO 2609 rule that a workload never republishes to its source topic"; the doc correctly frames it as a recommendation mirroring the MQTT connector check. Suggest: "Recommends that workloads never republish to their source topic, mirroring the AIO 2609 MQTT connector rule that rejects identical source and destination topics."
• Sources and validation (Low): the MQTT QoS ADR link is repo-relative and 404s from the PR page; use https://github.com/microsoft/edge-ai/blob/main/docs/solution-adr-library/mqtt-qos.md. Also add the 2609 release-notes URL to Sources and describe what "Manual validation" covered.

[Alain Uyidi (auyidi1)]

Thanks Marcel Bindseil (@bindsi), really thorough review. All findings are addressed in e800345, and the branch is rebased on main.

• D3 (blocker): the envelope is now carried as CloudEvents attributes through the MQTT binding, with a mapping to specversion, type, dataschema, id, traceparent, time, datacontenttype, and source/subject.
• Security (your three required changes): authorization bound through authorizationRef, verified against Learn (it also needs a linked BrokerAuthentication); Connect rules scoped to each principal's client IDs; and TLS for listeners and external brokers.
• Privacy: opaque {producer}/{resource-id}, topics logged only without identifiers, IDs generated randomly, and HMAC digests only.
• D5: principal token substitution is included rather than deferred.
• Smaller items: wildcard-aware publish-loop rule, dedup scope and window, client-ID wording, release-notes citation, frontmatter, and Refs #835.
• PR description: the decisions table now includes D3 and D5 with status, the RBAC and network checkboxes are marked N/A, the republish wording is corrected, the sources use absolute links, and the manual validation steps are described.

One deviation: for SAT refresh I followed the Learn authentication page (read the current token on each connection and reconnect after an unauthorized error) instead of MQTTv5 re-authentication before expiry, which Learn doesn't describe. I replied on each thread and left them unresolved for you to confirm.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-10-07 17:25:51 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	223
Infrastructure Components	232
Blueprints	40
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	538

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-10-08 11:40:18 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	223
Infrastructure Components	232
Blueprints	40
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	538

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.

All requested changes were addressed in e800345 and fadc99f (CloudEvents envelope mapping, authorizationRef binding, client-ID-scoped Connect rules, TLS, privacy rules, D5 token substitution, and the smaller items), with a reply on each thread. Approved by @katriendg and @rezatnoMsirhC. Dismissing to unblock the dependent PRs; happy to follow up on anything further in a new PR.

[github-actions]

📚 Documentation Health Report

Generated on: 2026-10-08 13:22:13 UTC

📈 Documentation Statistics

Category	File Count
Main Documentation	224
Infrastructure Components	233
Blueprints	40
GitHub Resources	26
AI Assistant Guides (Copilot)	17
Total	540

🏗️ Three-Tree Architecture Status

• ✅ Bicep Documentation Tree: Auto-generated navigation
• ✅ Terraform Documentation Tree: Auto-generated navigation
• ✅ README Documentation Tree: Manual README organization

🔍 Quality Metrics

• Frontmatter Validation:
  success
• Link Validation: success

---

This report is automatically generated by the Documentation Automation workflow.