Reasoning graph engine — three entry points [Flow]

# Reasoning graph engine — three entry points `[Flow]`

The causal scaffold that grounds planning, projections, and merges. One graph shape — inference nodes over a spine substrate — generated from three different contexts, then rendered as a sequential path for prose. This is the *why* behind a Reading ([projection-anatomy](../concepts/projection-anatomy.md)) and a Merge ([tutor-resolution](tutor-resolution.md)).

```mermaid
flowchart TB
    subgraph Entries["three entry points — same graph, different context"]
        direction TB
        E1["**generateReasoningGraph**<br/>per-arc causal graph (scene planning)"]
        E2["**generateMergeGraph**<br/>CRG synthesised from a resolved Merge"]
        E3["**generateCoordinationPlan**<br/>multi-arc plan — peaks · valleys · moments"]
    end

    Entries -->|"build prompt<br/>reasoning mode · force prefs · network bias"| Gen

    Gen["callGenerate('plan')<br/>+ thinking budget (reasoningScale)<br/>+ strict parseJson"]
    Gen -->|"validateNodeReferences"| Graph

    subgraph Graph["the graph — inference over substrate"]
        direction LR
        Nodes["**nodes**: reasoning · pattern · warning ·<br/>chaos · conclusion (+ spine: peak/valley/moment,<br/>character/location/artifact/system/fate)"]
        Edges["**edges**: requires · opens · breaks"]
        Nodes --- Edges
    end

    Graph -->|"buildSequentialPath"| Path(["ordered narrative path — the reasoning as prose"])
    Graph -->|"saved"| Store[("domain.reasoningGraphs<br/>source: manual · coordination-plan · merge · loop")]
```

**Invariants**

- **One shape, three contexts.** All three entry points produce the same node/edge grammar; they differ only in what grounds the prompt (an arc's trajectory, a merge's resolved outcomes + priors, or multi-arc coordination). The *substrate* nodes (priors, spine) are context; the *inference* nodes (reasoning, pattern, warning, chaos, conclusion) are the work.
- **`conclusion` is the load-bearing answer.** When the direction is a question, exactly one `conclusion` node sits at the highest index with incoming `requires` edges. Its `detail` carries the answer concretely (named actors/events, not abstractions); `considered` / `breaks` / `opens` keep it falsifiable.
- **References are validated, not trusted.** `validateNodeReferences` checks integrity before the graph is used — a node can't cite a substrate id that isn't there. System context is capped and impact-ranked to keep the prompt dense.
- **The graph is stored and stands on its own.** Saved into `domain.reasoningGraphs` with a `source`; a merge graph has a deterministic id (`graph-⟨mergeId⟩`) and lives and dies with its merge. A graph grounding a reading or projection is protected while that artifact stands, but deleting the reading/projection **releases** it rather than deleting it (cascade is an explicit opt-in). `buildSequentialPath` turns the graph back into ordered prose for reading.

**Where it lives:** `src/lib/engine/ai/reasoning-graph.ts` (three entry points + `buildSequentialPath`), `src/lib/engine/ai/reasoning-graph/{types,shared,validate}.ts`, `src/lib/engine/prompts/reasoning/`, `src/lib/engine/ai/phase-graph.ts`. Grounds: [projection-anatomy](../concepts/projection-anatomy.md) · [tutor-resolution](tutor-resolution.md) · [phase-graph](../concepts/phase-graph.md) (the descriptive substrate all three entry points inherit). Thinking budgets: [ai-model-routing](../concepts/ai-model-routing.md).

Raw Markdown source