Activity catalog reference stability

# Activity Catalog Reference Stability PRD

Program-goal state: `none/free-flow` until adopted into a named hardening bucket or Speckit work unit.

## Problem Statement

Workflow definitions currently store activity nodes by persisted activity definition version id. During development this exposed a production-facing hazard: when activity catalog reconciliation regenerates catalog rows with new ids, existing workflow definitions can reference missing activity versions even when the underlying activity still exists.

From a user perspective, a workflow that worked before an update can reopen with an unknown activity node, missing inspector metadata, and no clear repair path. This is unacceptable for production upgrades because users should not lose authoring confidence or have to understand catalog internals after normal product updates.

## Solution

Make authored workflow graphs resilient to catalog row regeneration and activity catalog upgrades.

The system should treat activity catalog ids as storage identities, not the only durable authored reference. Built-in and reconciled catalog rows should receive deterministic stable ids where possible; old activity versions should remain resolvable as compatibility rows; workflow nodes should carry enough stable reference metadata to diagnose or repair missing catalog ids; and Studio should preserve authored node data with clear diagnostics instead of surfacing opaque ids.

## User Stories

1. As a workflow author, I want workflows created before an Elsa update to reopen correctly, so that normal updates do not break my authored work.
2. As a workflow author, I want existing activities to retain their display name, inputs, outputs, and inspector metadata after an update, so that I can keep editing with confidence.
3. As a workflow author, I want a missing activity message to name the activity when possible, so that I understand what needs attention.
4. As a workflow author, I want authored inputs and layout preserved even when an activity descriptor is temporarily unresolved, so that no work is lost.
5. As an administrator, I want startup or admin diagnostics to report workflow definitions that reference missing activity versions, so that I can fix upgrade issues before users encounter them.
6. As an administrator, I want safe automatic repair when an unresolved activity can be mapped to a compatible catalog entry, so that routine updates do not require manual workflow edits.
7. As an administrator, I want unresolved activity references to block publish/run but not destroy drafts, so that invalid workflows cannot be promoted while user data remains recoverable.
8. As a module developer, I want activity catalog reconciliation to upsert stable rows for unchanged activity type/version pairs, so that module rebuilds do not invalidate existing workflows.
9. As a module developer, I want incompatible activity changes to create a new logical version instead of replacing the old one, so that existing workflows continue to resolve against their original contract.
10. As a support engineer, I want clear telemetry or diagnostics for catalog-reference failures, so that upgrade reports can be triaged without inspecting raw database rows.
11. As a product owner, I want update compatibility rules for activity catalog references, so that production release notes can make reliable promises about workflow upgrade safety.

## Implementation Decisions

- Authored workflow state must not rely solely on volatile activity definition version ids.
- Built-in and CLR-reconciled activity definition ids should be deterministic from stable activity identity, such as activity type key.
- Built-in and CLR-reconciled activity definition version ids should be deterministic from stable activity identity plus logical activity version.
- Activity catalog reconciliation should upsert unchanged activity definitions and versions instead of creating fresh rows on each rebuild or deployment.
- Activity versions should be append-only for compatibility. Incompatible descriptor changes should create a new logical version and preserve the old row while workflows can still reference it.
- Workflow activity nodes should gain a recoverable catalog reference containing stable data such as activity type key and logical activity version. The current activity version id can remain as the fast primary lookup.
- Missing activity version resolution should first try the stored id, then fall back to the stable reference when present.
- Automatic repair should be explicit and auditable: either a startup/admin repair operation or a save-time rewrite after validation confirms compatibility.
- Studio should render unresolved authored nodes as preserved-but-invalid nodes, not as generic unknown blocks when stable metadata exists.
- Validation should distinguish unavailable-for-new-selection from missing/unresolvable. Activity availability policy must not invalidate existing authored nodes by itself.
- Upgrade diagnostics should enumerate affected workflow definition ids, version ids, node ids, missing activity version ids, and candidate repair targets when available.

## Testing Decisions

- Highest-value seam: end-to-end workflow design persistence and activity catalog reconciliation, because this is where users experience the compatibility guarantee.
- Existing unknown-activity-version validation should remain a blocking guard when no compatible catalog entry can be resolved.
- Add reconciliation tests proving that unchanged built-in/CLR activity versions keep stable ids across repeated reconciliation runs.
- Add workflow persistence tests proving that an old workflow can still resolve after a catalog refresh when the activity type and logical version are unchanged.
- Add migration/repair tests proving that missing ids can be mapped from stable references without losing node inputs, outputs, structure, or layout.
- Add negative tests proving that incompatible descriptor changes are not silently repaired to an unsafe version.
- Add API/Studio contract tests, or backend response tests if Studio tests live elsewhere, proving unresolved nodes expose actionable diagnostics instead of only opaque ids.

## Out of Scope

- Reworking the entire workflow graph model beyond activity catalog references.
- Solving Elsa 3 import compatibility.
- Changing runtime artifact execution semantics except where published artifacts need compatibility metadata.
- Making activity availability policy decide whether existing authored nodes may render.
- Deleting or rewriting user workflows without an explicit repair operation or validated save path.

## Candidate Agent Slices

1. Stabilize reconciliation ids for built-in and CLR activities, with repeat-reconciliation tests.
2. Add stable activity catalog reference metadata to authored activity nodes and API models.
3. Implement fallback resolution and validation diagnostics for missing activity version ids.
4. Add an admin/startup diagnostic report for unresolved workflow activity references.
5. Add an explicit repair operation that rewrites resolvable stale ids while preserving authored node data.
6. Improve Studio unresolved-node rendering once backend diagnostics expose stable metadata.
7. Document production activity compatibility rules for module authors and release upgrades.

## Further Notes

The observed local failure was a workflow node referencing old catalog ids while the current catalog still contained the underlying `WriteLine` and `Sequence` activities under new ids. Wiping the local development database is acceptable during active refactoring, but production must guarantee that catalog reconciliation and release upgrades do not strand authored workflows on missing activity definition version ids.

No source files are named. Start by locating activity catalog reconciliation, workflow-node persistence, and existing unknown-activity-version validation and tests; then select one of the seven agent slices. Done should be demonstrated by the focused reconciliation, persistence, repair, diagnostics, Studio contract, or documentation tests described in the issue.

Written by the indexing model from the issue text.