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) and a Merge (tutor-resolution).

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 · tutor-resolution · phase-graph (the descriptive substrate all three entry points inherit). Thinking budgets: ai-model-routing.