Inventory the Current Elsa Runtime Architecture (Actor-Runtime Readiness)

## Goal
Produce a **high-fidelity inventory of the current Elsa Workflows runtime architecture** as it exists in this repo, focusing specifically on runtime/execution, concurrency, distribution, persistence, timers, triggers/bookmarks, and observability. This inventory will be used by a follow-up agent to design an **actor-model runtime** behind a **clear abstraction layer** that avoids tight coupling to any concrete actor framework (Orleans / Proto.Actor / etc.).

## Non-goals
- Do **not** propose the actor runtime design in this task.
- Do **not** refactor code.
- Do **not** implement anything.
- Do **not** “summarize vaguely.” The output must be actionable and anchored in code.

## Deliverable Format
Create a single markdown file:

- `docs/architecture/runtime-inventory.md`

It must contain:
1. An executive overview (1–2 pages max)
2. A detailed inventory with **code pointers** (namespaces, types, key methods, files)
3. A dependency and interaction map (text + mermaid diagrams)
4. A list of architectural invariants and runtime semantics inferred from code
5. A list of “actor-runtime interface requirements” extracted from the inventory (capabilities Elsa needs)
6. A list of unknowns / questions discovered (with precise locations in code)

**Hard requirement:** Every claim must be grounded in a code reference (file path + type/method name). If you can’t locate something, explicitly say so.

---

## Step-by-step Plan

### 1) Map runtime entry points and execution lifecycle
Find and document:
- How workflow execution is initiated (HTTP endpoints, message consumers, background services, triggers).
- The main orchestration services (e.g., workflow runner/executor/dispatcher).
- The lifecycle of a workflow instance from “start” to “complete/fault/suspend”.

For each entry point:
- Provide the call chain (top-down).
- Identify the message/command objects used.
- Identify where tenant resolution happens.
- Identify where correlation IDs / tracing context is created or propagated.

**Output section:** `## Runtime entry points`

---

### 2) Identify the core execution pipeline and state machine
Inventory the code responsible for:
- Creating/continuing workflow instances
- Bookmarking / resumption
- Trigger indexing and trigger execution
- Persistence of workflow instance state and any intermediate data
- Handling activity execution and outcomes
- Versioning and definition resolution during execution

Document:
- The key “units of work”
- Where state is read/written
- Where concurrency is controlled (locks, single-threaded guarantees, queues, partition keys)

**Output section:** `## Execution pipeline & state`

---

### 3) Inventory distribution and scaling mechanisms (current)
If there is any distributed runtime / clustering / leader election / partitioning:
- Identify exactly how it works today.
- Identify how “ownership” of a workflow instance is determined.
- Identify messaging transport(s) and topology (queues, topics).
- Identify how retries, deduplication, and idempotency are handled.

If there is no distribution logic:
- Confirm what currently assumes single-node.
- Note which components would break in multi-node.

**Output section:** `## Distribution, clustering, and ownership`

---

### 4) Concurrency, ordering, and reliability semantics
Extract from code and docs:
- Per-workflow-instance single-threading guarantees (if any)
- At-least-once vs exactly-once expectations
- Ordering guarantees for messages/events
- How concurrent resumes are prevented (locks? optimistic concurrency? queue?)
- Failure handling semantics (poison messages, DLQs, retries, compensation)

Provide:
- A table of “Semantics” with “Current behavior” + “Code evidence”.

**Output section:** `## Concurrency & reliability semantics`

---

### 5) Timers, scheduling, and reminders
Find and document:
- How timers are represented (delays, cron, scheduled activities)
- How they’re persisted and rehydrated
- Which scheduler is used (Quartz, Hangfire, custom, etc.)
- How scheduling behaves across restarts and across nodes

**Output section:** `## Timers & scheduling`

---

### 6) Persistence and storage dependencies
Inventory all persistence-related components:
- Stores (workflow instance store, bookmark store, trigger store, definition store, etc.)
- Database providers (SQL, Mongo, etc.)
- Transaction boundaries and outbox patterns (if present)
- Consistency model (event sourcing? snapshotting? mixed?)

Provide:
- A diagram of which runtime component reads/writes which store.

**Output section:** `## Persistence & consistency`

---

### 7) Observability: tracing, metrics, logging
Document:
- How tracing is done today (ActivitySource names, span boundaries)
- Correlation IDs and propagation (headers, message properties, ambient context)
- Any OpenTelemetry exporters and how runtime spans map to workflow/activity operations

Provide:
- A list of the top 10 spans emitted in a typical execution, and where they start/end.

**Output section:** `## Observability & correlation`

---

### 8) Dependency graph and interaction map
Produce:
- A component inventory list (runtime-relevant packages/projects/modules)
- A mermaid diagram:
- `flowchart LR` showing runtime components and arrows for calls/messaging
- A second mermaid diagram if needed:
- `sequenceDiagram` for “Start workflow” and “Resume from bookmark”

**Output section:** `## Component map`

---

### 9) Extract “Actor Runtime Capability Requirements”
Based on the inventory, derive a **capabilities checklist** that an actor runtime abstraction must provide for Elsa, phrased as “Elsa needs X”.

Examples (do not assume these are true—derive them):
- Route a command to the correct workflow instance “owner”
- Ensure single-threaded execution per instance
- Persist state and reload on activation
- Provide durable reminders
- Support tenant-scoped partitioning
- Propagate tracing context across messages

For each capability:
- Provide evidence where Elsa currently needs it (call site or behavior).

**Output section:** `## Actor-runtime capability requirements (extracted)`

---

### 10) Risks, tight coupling hotspots, and migration blockers
Identify:
- Where runtime concerns are currently “smeared” across layers
- Places where abstractions are missing and would likely cause tight coupling
- Code that assumes in-process execution
- Places where actor identity / placement keys should exist but don’t

**Output section:** `## Coupling hotspots & migration blockers`

---

## Search Targets (use these as anchors, expand as needed)
Locate classes / namespaces likely to exist around:
- `WorkflowRunner`, `WorkflowExecutor`, `WorkflowDispatcher`
- `IWorkflowInstanceStore`, `IBookmarkStore`, `ITriggerStore`
- `Bookmark`, `Trigger`, `Stimulus`, `Resume`, `Dispatch`
- `HostedService`, `BackgroundService`
- `Quartz`, `Hangfire`, `Scheduler`
- `DistributedLock`, `Medallion`, `Leader`, `Cluster`
- `MassTransit`, `RabbitMQ`, `ServiceBus` (if used)
- `ActivitySource`, `OpenTelemetry`, `Tracing`, `Diagnostics`

If names differ, follow the code trail and document the actual names.

---

## Output Quality Bar (do not skip)
- Be precise: file paths + type names + method names.
- Prefer reading the code over guessing.
- If a component exists in multiple repos/projects, indicate boundaries.
- If you find TODOs or comments implying intended semantics, quote them briefly (<=25 words) and cite exact location.

---

## Final Checklist (must be included at end of doc)
Include a section `## Inventory completeness checklist` and mark each item as:
- ✅ Found + documented with evidence
- ⚠️ Partially found (explain what’s missing)
- ❌ Not found (explain where you searched)

Checklist items must include at least:
- Entry points
- Execution pipeline
- Concurrency control
- Distribution/ownership
- Timers/scheduling
- Persistence/stores
- Observability/tracing
- Interaction maps
- Actor capability requirements
- Coupling hotspots

---

## Hand-off Note
End the document with:

`## Hand-off summary for Actor Runtime Design Agent`

Include:
- 10–20 bullet points of the most important facts discovered
- The extracted capability requirements list (short form)
- The top 5 coupling hotspots to address with an abstraction boundary