MQTT Section Migration

[Ethan-Arrowood]

MQTT Section Migration

Summary

Migration of MQTT documentation from versioned_docs/ into the new v4 consolidated reference structure.

Files Created

• reference_versioned_docs/version-v4/mqtt/overview.md
• reference_versioned_docs/version-v4/mqtt/configuration.md

Source Files Used

mqtt/overview.md

• versioned_docs/version-4.7/developers/real-time.md (primary — MQTT section, Topics, Ordering, Events, Feature Support Matrix)
• release-notes/v4-tucker/4.2.0.md (confirmed MQTT introduction, QoS 0/1, durable sessions)
• release-notes/v4-tucker/4.3.0.md (confirmed mTLS, single-level wildcards, retain handling)
• release-notes/v4-tucker/4.5.0.md (confirmed improved message delivery)

mqtt/configuration.md

• versioned_docs/version-4.7/deployments/configuration.md (mqtt section, lines 1377–1446)
• versioned_docs/version-4.7/developers/real-time.md (configuration YAML example)
• release-notes/v4-tucker/4.2.0.md (confirmed mqtt config section added)
• release-notes/v4-tucker/4.3.0.md (confirmed mTLS config options added)

Version Annotations Added

High Confidence (Confirmed via release notes)

• MQTT support (QoS 0/1, durable sessions): Added in v4.2.0
• mTLS authentication for MQTT: Added in v4.3.0
• Single-level wildcard (+): Added in v4.3.0
• MQTT V5 retain handling: Added in v4.3.0

Needs Verification

• Last Will support: Listed as ✅ in the v4.7 feature matrix but release notes don't specify when it was added — annotated as "inferred from version comparison, needs verification"
• mqtt.network.mtls.certificateVerification: Present in v4.7 config docs but exact introduction version not confirmed in release notes

Link Placeholders Created

See migration-context/link-placeholders/mqtt-link-placeholders.md for complete list.

Summary:

• 4 placeholders to security/overview.md
• 2 placeholders to database/schema.md
• 2 placeholders to http/tls.md
• 1 placeholder to rest/overview.md
• 1 placeholder to configuration/overview.md

Images/Assets Noted

None — MQTT docs contain no images.

Conflicts & Questions for Human Review

Content Notes

• The migration map noted "Port change v4.5.0 (9925 → 9933)" for MQTT configuration. This port change was for the replication port, not the MQTT port. MQTT ports (1883/8883) have not changed across v4. The annotation in the configuration.md source comment has been preserved for awareness but not surfaced as a version annotation in the content.

• The v4.7 source says: "Harper currently only supports trailing multi-level wildcards (no single-level wildcards with *)" — but the feature matrix directly below in the same file marks single-level wildcards as ✅, and the 4.3.0 release notes confirm single-level wildcards were added. The body text appears to be outdated/stale. The generated docs use the feature matrix as authoritative. Human reviewer should confirm single-level wildcards work as expected.

• CRDT was noted in the migration map as a v4.3.0 MQTT feature. CRDT is a general data update mechanism surfaced via REST PATCH and Resource API — not MQTT-specific — so it is not included in the MQTT overview. If there's MQTT-specific CRDT behavior, please flag for addition.

Uncertainties

• mqtt.network.mtls.certificateVerification defaults and options: sourced from the v4.7 config docs. The HTTP mTLS config has a more detailed CRL+OCSP description; MQTT's config docs only mention OCSP. This may reflect a genuine difference (MQTT only supports OCSP, not CRL). Human reviewer should verify.

Migration Map Status

Updated status for overview.md and configuration.md to "In Progress"

Checklist for Human Reviewer

• Verify single-level wildcard (+) support — body text in source appears stale vs feature matrix
• Verify Last Will version annotation
• Confirm MQTT certificateVerification only supports OCSP (not CRL) unlike HTTP mTLS
• Review content accuracy and completeness
• Decide whether CRDT mention belongs in MQTT overview or only in database/schema
• Resolve link placeholders once target sections are created
• Update migration-map.md status to "Complete" after merge

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-449

This preview will update automatically when you push new commits.

[kriszyp]

This looks excellent!

[kriszyp]

Do you think it would be possible to have all our "Added in: version" text be in a smaller/different font? And/or maybe right aligned, so it is little more subtle.

[Ethan-Arrowood]

Yes absolutely. I'll not this as part of the follow up tasks. Will need to use some sort of custom mdx component to do it but absolutely possible.

[Ethan-Arrowood]

I'm merging in a number of the "(inferred from version..." notes that the AI left behind so that I'm forced to go back through these files and ensure everything is cleaned up (links is a big one). So i'll make stylistic updates part of that pass too.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-449

This preview will update automatically when you push new commits.