[markscott-ms]

Description

This PR proposes a design for #3396, the CALM Hub extensions framework. It records the design as ADRs and models it in CALM. @rocketstack-matt, please review it against your proof of concept and the thread on #3396.

The design keeps the main points that the thread agreed: operator-only install, a proxy-only backend, one hubApi version, and a Hub-signed identity assertion. It adds answers to the open questions and changes to the delivery plan. #3399 is the test case for the server-side points.

ADR	Decision
0009	Extensions are external HTTP services behind a Hub proxy. Hub loads no extension code
0010	Hub sends a short-lived, request-bound assertion, never the user's token. An extension calls Hub with its own service account (Q4, Q5)
0011	Proxy rules: a scope on each route, the read-only exemption, host pinning, header allow-lists, a sandbox CSP, refusal to start with auth off (Q1, Q2)
0012	Manifest shape with route ids, vertx-json-schema validation, hubApi versioning, configuration by extension id (Q6)
0013	Tiered UI: Hub-rendered blocks by default, a cross-origin iframe later, no Module Federation (Q3)
0014	Generic calm hub ext dispatch in the CLI, and one MCP tool for each command
0015	Validation is a Hub feature behind an internal interface, with calm-server as the default. Results are recorded asynchronously first
0016	A write seam on the store producers and an outbox for post-write events

Architecture. calm-4.architecture.json is the system view. calm-hub-4-detail.architecture.json is the Hub detail, and the Hub node in calm-4 links to it. Controls in both files link to the ADRs. calm-4 is a moment after current-moment in the timeline, with no valid-from, so it is a future state.

Findings in the code that change the plan:

• X-Frame-Options: DENY applies to all routes, so Hub cannot frame a page that it serves.
• The proof of concept builds the backend URI from a string. With a path from the caller, this permits SSRF.
• calm-server rejects a Pattern that is not the $schema of the architecture, cannot accept resolved documents, and limits Hub to 100 calls in 15 minutes.
• applies-to in decorators.json needs at least one item, so a pass cannot be recorded.
• Versions are not immutable when allow.put.operations is on.

Not yet verified. A step-0 spike must test ToolManager, JWT signing and vertx-json-schema in a native image, and streaming on RESTEasy Classic. The ADRs give the fallback for each.

All ADRs are Proposed. This PR changes no code.

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)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Lab (calm-lab/)
• CALM Models (calm-models/)
• CALM Server (calm-server/)
• CALM Studio (calm-studio/)
• CALM Widgets (calm-widgets/)
• CALMGuard (calm-guard/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Commit Message Format ✅

docs(calm-hub): propose extensions framework design as ADRs and CALM architecture

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

calm validate passes with no errors or warnings for both architectures and for the timeline. Run it from calm/architecture, because the CLI finds detailed-architecture files from the working directory.

Do not open calm-4.architecture.json in CALM Canvas 0.9.2 and save it. The canvas removes fields from it (#3518, #3519).

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

[jpgough-ms]

@markscott-ms this is a lot to review in one go, any chance we could split up into related ADRs so there are 2-3 max per review?

[markscott-ms]

Closed in favour of a stack of four smaller PRs, for easier review. The content does not change. Each branch is based on the one before it:

#	Branch	Contents
1	docs/3396-extension-runtime-adrs	ADRs 0009–0012: proxy, identity, proxy rules, manifest
2	docs/3396-extension-surface-adrs	ADRs 0013–0014: UI, CLI and MCP
3	docs/3396-validation-write-seam-adrs	ADRs 0015–0016: validation, write seam and outbox
4	docs/3396-extensions-calm-architecture	calm-4, calm-hub-4-detail and the timeline moment

The PRs for these branches will be linked here when they are open.

[markscott-ms]

The stack is open: #3579 → #3580 → #3581 → #3582.