---
title: Spine Primer
description: Tenant-facing primer for using an Organization Model catalog as the shared coordination spine between workflow producers, runtime state, API filters, and UI projections.
---
<!-- @generated by packages/sdk/scripts/copy-reference-docs.mjs -- DO NOT EDIT -->
<!-- Regenerate: pnpm scaffold:sync -->


# Spine Primer

Use this primer when a tenant domain has a closed set of stages, statuses, or catalog keys that multiple surfaces must share. A spine is the tenant Organization Model vocabulary that coordinates workflows, runtime state, API reads, and UI rendering without forcing those surfaces to import from each other.

The lead-generation pattern is the reference shape: `organizationModel.prospecting.stages` defines the stage vocabulary, workflow templates reference those stages, workflow factories validate stage keys before running, entity state stores sparse per-stage progress, and UI views render progress from the same vocabulary.

## What The Spine Owns

A spine owns the shared vocabulary for one domain. The vocabulary is not just a list of strings. Each key should carry enough metadata for consumers to derive behavior consistently:

- `key` identifies the stage or catalog member.
- `label` gives a human-readable name.
- `description` explains the business meaning.
- `order` gives stable display and workflow ordering.
- `entity` identifies which tenant entity the stage updates.

The same keys then appear in four places:

| Role | Tenant-facing shape |
| --- | --- |
| Vocabulary | `organizationModel.prospecting.stages` |
| Process | workflow templates and build steps that reference stage keys |
| Runtime state | entity state maps such as `{ [stageKey]: { status, updatedAt, data } }` |
| Consumer projection | API filters, progress summaries, and UI step rendering |

## Layering

```text
tenant Organization Model
- prospecting stages
- workflow templates
- capability bindings
        |
        +--> workflow factory
        |    - validates stage keys
        |    - runs producers
        |    - dispatches entity-tagged results
        |
        +--> API and query helpers
        |    - filter pending entities by stage key
        |    - aggregate progress from state maps
        |
        +--> UI projections
             - render labels and order from the catalog
             - distinguish known and unknown state keys

entity runtime state
{ [stageKey]: { status, updatedAt, data } }
```

The important boundary is that producers and consumers coordinate through the Organization Model vocabulary plus runtime state. They do not coordinate through direct imports, duplicated string constants, or workflow-specific side channels.

## Invariants

1. **The vocabulary is closed and validated.** Workflow factories should reject stage keys that are not present in the tenant Organization Model.

2. **The vocabulary carries metadata.** Labels, descriptions, ordering, and entity ownership should come from the catalog rather than being copied into each consumer.

3. **Runtime state is sparse and additive.** New stages appear in entity state when reached. Adding a catalog member should not require backfilling every entity.

4. **Producers return entity-tagged results.** Workflow steps should return which entity changed, its identifier, status, and optional data. The factory owns writing those results to the correct state map.

5. **Capability binding is separate from stage naming.** Workflow templates should point at capability keys, and the tenant environment can bind those capabilities to concrete workflow resources.

## Applying The Pattern

Use this checklist when adding or changing a tenant domain spine:

1. Define the domain catalog in the tenant Organization Model.
2. Include labels, descriptions, ordering, and entity ownership in each catalog entry.
3. Make workflow templates reference catalog keys instead of free-form strings.
4. Validate template stage keys when constructing workflow factories.
5. Store progress in sparse entity state maps keyed by catalog member.
6. Return entity-tagged workflow results and let the factory dispatch state updates.
7. Read progress through query helpers that use the same catalog keys.
8. Render UI labels, order, and status from the catalog plus state map.

Promote a vocabulary to a spine when the same catalog coordinates all three surfaces: at least one process definition, at least one workflow producer, and at least one independent consumer such as an API query or UI view.

## Counter-Patterns

Avoid these patterns in spine-governed domains:

- Free-form stage strings in workflow inputs.
- Duplicated UI-only labels or ordering.
- Per-workflow skip logic that bypasses the shared pending and progress contract.
- State writes from individual steps instead of the workflow factory.
- Hidden side channels for progress, such as ad hoc context keys.
- Direct coupling between producer code and consumer UI code.

When in doubt, update the Organization Model vocabulary first, then let workflow templates, factories, queries, and views project from it.
