docs(adr): draft ADR-027 Integration Versioning (exploratory)

[seanspeaks]

Summary

Partner ADR to ADR-013 Integration Version Migrations (merged in #617), which explicitly defers the version contract to a separate ADR. This is that ADR.

Renumbered from ADR-015 to ADR-027 after #617 and #621 both merged. Those two PRs claimed slots 012–014 (migration ADRs) and 015–026 (consolidated named cluster), so this ADR takes the next available number.

Deliberately exploratory rather than deciding. Per Sean's direction, global-routing behavior in serverless environments needs more research before any path is chosen. This ADR lays out the design space, four explored paths with tradeoffs, serverless-specific concerns, and a 12-item edge-case catalog. Path selection is deferred to a follow-up ADR (or a revision of this one) once the open research questions resolve.

Structure

• Current state (grep-verified in next): Definition.version is a label. Nothing in packages/core gates behavior on it. supportedVersions is declared but unread.
• Four dimensions: declaration, routing, storage, compatibility, and why they couple.
• Four explored paths:
  • Path A: bump-in-place with migration on read
  • Path B: side-by-side classes with per-version routing
  • Path C: version selector on appDefinition
  • Path D: version as a routing dimension outside the class
• Serverless-specific concerns: Lambda module-scope cache, edge vs origin routing, signed webhook URL survival, in-flight SQS jobs, EventBridge Scheduler drift, rollback semantics, encryption schema, deploy-time coordination with ADR-012 / ADR-013.
• 12-item edge-case catalog: mixed-version fleets, third-party-forced bumps, adopter calls to old URLs, credential/mapping/config shape changes, beta versions, multi-tenant pinning, cross-integration references, and more.
• 8 open questions + 4 research follow-ups Sean called out (global routing, signed URLs, Lambda aliases + weighted traffic, industry examples).

Placement

docs/architecture-decisions/027-integration-versioning.md in the consolidated numbered register (per ADR-014, now merged), directly cross-referencing ADR-013.

Test plan

• Read alongside ADR-013 Integration Version Migrations — confirm the two ADRs slot together cleanly
• Confirm the four explored paths cover the design space adopters would reach for
• Confirm the serverless concerns match reality — especially the signed-webhook-URL survival claim across HubSpot v3, Stripe, Slack, Salesforce Streaming, Frontify
• Confirm the deferred decision is the right call, or push back and ask for a preferred path

Notes

• Draft. Move to ready-for-review once the design-space enumeration is settled.
• No release / prerelease labels; docs-only.
• 264 lines (longer than the 200-line bar for concept ADRs; this one earns the length by being exploratory).
• Style bar consistent with the rest of the register: no em-dashes, no rhetorical contrast, no references to private repos.
• Branch rebased onto next after the two upstream merges; no other changes required.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud