Design Discussion: Decorator Association Scalability Concerns

## Feature Proposal

### Target Project:

calm-hub (with implications for calm-spec decorator schema)

### Description of Feature:

The current mechanism for associating decorators with the architectures they decorate has scalability and reliability concerns.

To render decorator views for an architecture, CALM Hub must:
1. Take the architecture's full API path (e.g. `/api/calm/namespaces/finos/architectures/1/versions/1-0-0`)
2. Query all decorators in the namespace, filtering by `target` string match
3. Return matching decorators for rendering

This works at small scale but raises several concerns:

**Separate index required**: Decorators are stored independently from architectures. To find which decorators apply to a given architecture, CALM Hub must maintain and query a separate index (currently a filter scan over all decorators in a namespace). As the number of decorators grows, this becomes increasingly expensive.

**Brittle string-based association**: The `target` field is a free-form string (a file path or API URL). The association between a decorator and its architecture depends on an exact string match against a constructed API path. If the URL structure changes, path encoding differs, or the target was authored with a different format (relative path vs absolute URL vs API path), the association silently breaks.

**No reverse lookup**: Architectures have no knowledge of their decorators. The relationship is entirely one-directional (decorator → architecture via `target`). There's no way to ask an architecture "what decorators apply to you?" without scanning all decorators.

**Version mismatch**: Architectures are versioned (e.g. `1.0.0`, `1.1.0`, `2.0.0`), but decorators are not. A deployment decorator targeting version `1.0.0` of an architecture has no lifecycle relationship with version `2.0.0`. When the architecture is updated, do the old decorators still apply? Should they be migrated? There's no model for this.

### User Stories:

- As a **CALM Hub operator**, I want the decorator lookup to remain performant as the number of decorators grows, without needing to scan all decorators in a namespace.
- As an **architect**, I want to see all decorators that apply to my architecture without relying on exact string matching of API paths.
- As a **platform team**, I want to understand what happens to our deployment decorators when we publish a new version of the architecture; do they carry over, or do we need to re-create them?

### Current Limitations:

- Decorator-to-architecture association relies on exact string match of `target` field against constructed API paths
- No reverse index from architecture → decorators
- All decorators for a namespace stored in a single MongoDB document array (`$push` unbounded), with potential for hitting MongoDB's 16MB document size limit
- Decorators are not versioned, so there is no lifecycle relationship with the versioned architecture they target
- `target` format is not validated; can be file paths, URLs, or API paths with no normalisation

### Proposed Implementation:

This issue is primarily a design question. Possible approaches include:

1. **First-class association**: Instead of (or in addition to) the `target` string, decorators could reference architectures by namespace + resource ID + version range, giving CALM Hub a structured association it can index efficiently.

2. **Reverse references on architectures**: Architectures could maintain a list of decorator references, making lookup O(1) instead of a filter scan. This trades write complexity for read performance.

3. **Decorator versioning**: Decorators could gain version support (like other CALM Hub document types), with explicit lifecycle rules for how they relate to architecture versions.

4. **Normalised storage**: Move from the current nested-array-in-single-document storage to per-decorator documents with proper indexes on target references.

These aren't mutually exclusive; a combination may be appropriate.

### Alternatives Considered:

- **Keep current model**: works at small scale and is simple. Becomes a problem as decorator volume grows or when URL structures change.
- **Embed decorators in architectures**: would solve the association problem but contradicts the separation-of-concerns design (decorators are managed by different teams than architecture authors).

### Additional Context:

This issue is part of a series exploring CALM's decorator and document model. Consider reading the related issues for broader context:

- #2791 Documents vs Decorators
- #2792 Decorator Registry and VIews
- #2552 Decorator mechanism: close meta-schema and CLI gaps

Start by reading related issues #2791, #2792, and #2552, then inspect the current CALM Hub decorator lookup and MongoDB nested-array model described here. Done means the project has an agreed association, lookup, storage, and architecture-version lifecycle design; this issue names no files or tests.

Written by the indexing model from the issue text.