[markscott-ms]

Description

Part 3 of 4 of the CALM Hub extensions framework design for #3396. #3520 had all of this in one PR. It is now a stack of PRs, so that each part gets a better review.

Stack (merge in this order):

1. docs(calm-hub): propose extension runtime and security ADRs #3579 ADRs 0009–0012: runtime and security
2. docs(calm-hub): propose extension UI, CLI and MCP ADRs #3580 ADRs 0013–0014: UI, CLI and MCP
3. docs(calm-hub): propose architecture validation and store write seam ADRs #3581 ADRs 0015–0016: validation and write seam ← this PR
4. docs(calm-hub): model the CALM Hub extensions design in CALM #3582 CALM architecture

#3399 is the test case for these ADRs.

ADR	Decision
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

Findings that change the plan:

• 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.

All ADRs are Proposed.

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 architecture validation and store write seam ADRs

Testing

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

This PR adds documentation only. It changes no code.

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

[rocketstack-matt]

I agree with the direction: validation in Hub behind an SPI, results as validation decorators, and one write seam with an outbox for REST and MCP. Some requests before acceptance:

ADR 0015 L76–81 (only Hub writes validation)
Please make this a general rule: reserved decorator types. Hub keeps a map of type → allowed writers (for example validation → system, control-evaluation → policy-engine with its ADR 0010 service account). The ADR 0016 wrapper enforces it. Other types keep today's rule. Also, when a decorator names a $schema that Hub knows (for example a calm-schema Standard), Hub should check data against it on write.

ADR 0015 L78–79 (supersede, never edit)
Today updateDecorator edits in place (ADR 0004), and no ADR changes that. Please add a short ADR for decorator history: reserved types are append-only, with a supersedes link in a field that Hub owns, not in data.

ADR 0015 L82–84 (applies-to sentinel)
Agreed. Please make sure the control-evaluation Standard uses the same convention, and keep the calm-schema proposal.

ADR 0015 (result shape)
Please model the validation decorator Standard on the control-evaluation one (status, findings, engine, evaluated-at). Then one diagram overlay and one generic view can show both (#3620).

ADR 0016 L17–20 (@Decorator on producer beans)
The design depends on this. Please confirm it in a short spike before acceptance, not after.