06 / Technical brief

FridaiOS ↔ LangGraph equivalence

Basis
An independently built custom orchestration engine — dispatcher, run-state, model router, cost ledger — designed and running before I compared it to any framework.
Comparison
LangGraph's public concepts: nodes, graph state and threads, interrupts and checkpointers, tools, edges and routers, fallbacks, tracing and evals.
Status
Conceptual correspondence, not hands-on LangGraph experience.
Evidence
Public dispatcher and model-router exhibits (Exhibit 03, Exhibit 04), traced in the Capabilities register.
8
orchestration constructs mapped to LangGraph concepts, each rated direct, partial or analogous
4
named architecture gaps: process protocol, state persistence, tool protocol and ecosystem
2
human gates in a real run, both pausing on exit code 4 and resuming the same run ID
Public
dispatcher and model-router code behind the mapping, not just a description of it

I built a staged-orchestration engine for my own work before I had reason to learn a named framework, then checked it concept for concept against LangGraph's public documentation to see whether the vocabulary really lines up. Conceptual correspondence, not hands-on LangGraph experience: everything LangGraph-shaped below is read from public documentation and mapped onto code I already had, not code written against LangGraph's own APIs, run through its runtime, or traced through LangSmith or Langfuse.

Eight constructs are paired against their nearest LangGraph concept below, each one labelled by how closely it actually corresponds. A real content-production run shows those constructs pausing for a human choice and resuming from the same state. A differences section then states plainly where the two shapes diverge.

1. Eight constructs, mapped concept for concept

Each pair below names a FridaiOS construct against its nearest LangGraph concept, labelled by how far the correspondence actually holds — direct, partial or analogous.

  • Stage script ↔ Node — direct

    Both are one unit of work that hands back a typed result before control moves to the next step. Mine are numbered stage scripts, each emitting a STAGE_RESULT line.

  • Run-state file + run ID ↔ Graph state + thread — direct

    Both persist state between steps under one identifier that a paused run can be resumed against.

  • Exit code 4 · paused ↔ Interrupt + checkpointer — partial

    Both suspend for a human decision and resume from the same state, but mine exits the process to disk rather than suspending in-process. The exit code is 4, which the dispatcher maps to the paused status, and --resume carries the run forward.

  • Portable skill ↔ Tool — analogous

    Both are a documented, callable capability, but a skill is invoked by my dispatcher directly, not bound into a model's function-calling schema.

  • Dispatcher + stage order ↔ Edges + router — partial

    Both decide what runs next, including conditional skips, from a declared sequence rather than an ad hoc script (mine is the .stage-order file the dispatcher reads), but mine is a linear order with skips, not a general graph with branches and cycles.

  • Model-router fallback chain ↔ Fallbacks — partial

    Both retry an ordered provider list on failure; mine also enforces schema-validated retries a fallback wrapper alone doesn't specify.

  • Append-only token ledger ↔ Tracing ecosystem — analogous

    Mine is a local cost and token log (tokenlog). LangSmith and Langfuse are a run-tracing and debugging platform I have not operated.

  • Golden retrieval tests ↔ Evals — partial

    Both are regression-gated, dataset-driven checks, but mine is scoped to retrieval quality, not general output grading.

CORRESPONDENCE MAP / 01

Eight constructs paired

Eight FridaiOS orchestration constructs, each paired on the same row with the closest LangGraph concept.

  • construct or concept
flowchart LR
  accTitle: FridaiOS and LangGraph conceptual correspondence
  accDescr: Eight custom orchestration constructs on the left are each paired with the analogous LangGraph concept on the right, one pair per row.
  subgraph F["FridaiOS construct"]
    F1["Stage script"]
    F2["Run-state file + run ID"]
    F3["Exit code 4 · paused"]
    F4["Portable skill"]
    F5["Dispatcher + stage order"]
    F6["Model-router chain"]
    F7["Append-only token ledger"]
    F8["Golden retrieval tests"]
  end
  subgraph L["LangGraph concept · correspondence only"]
    L1["Node"]
    L2["Graph state + thread"]
    L3["Interrupt + checkpointer"]
    L4["Tool"]
    L5["Edges + router"]
    L6["Fallbacks"]
    L7["Tracing ecosystem"]
    L8["Evals"]
  end
  F1 --- L1
  F2 --- L2
  F3 --- L3
  F4 --- L4
  F5 --- L5
  F6 --- L6
  F7 --- L7
  F8 --- L8
A pairing of constructs, not a claim that the two systems are interchangeable — see Where they differ below.

2. A real paused run

The figure below is the actual shape of a content-production run through my pipeline, not a simplified stand-in: numbered stages, and a human gate wherever the pipeline should not choose on its own. A run selects a topic, researches it, proposes an angle, then produces assets and captions once a person has signed off both choices.

RUN SHAPE / 02

One real paused run

A real content-production run: topic select, research, angle, assets and captions, pausing at a human gate after the topic is proposed and again after the angle is proposed.

  • pipeline stage
  • human gate
flowchart TD
  accTitle: A real content run that pauses twice for a human choice
  accDescr: A content run selects a topic, pauses at a human gate to pick the topic, then researches and proposes an angle, pauses at a second human gate to pick the angle, and finally produces assets and captions, resuming with the same persisted state each time.
  A["Topic select"] --> G1{{"Human gate · pick topic"}}
  G1 --> B["Research"] --> C["Angle"] --> G2{{"Human gate · pick angle"}}
  G2 --> D["Assets"] --> E["Captions"]
  classDef human fill:#f6ad55,stroke:#c05621,color:#1a1a1a;
  class G1,G2 human;
Each human gate exits with code 4 and resumes the same run ID.

Exit code 4 fires at each gate: the run pauses, its state persists to disk, and a human picks — a topic, then later an angle — before --resume carries the same run ID forward into the next stage rather than starting over.

3. Where they differ

The correspondence above is real, but it stops at architecture. Four gaps matter if it is read as more than that:

  • Each FridaiOS stage is a shell or Python process that exits and hands control back to the dispatcher; LangGraph runs its nodes inside one long-lived in-process graph runtime.
  • My run state is a file on disk that I read and write myself; LangGraph's state is held by a framework checkpointer, with storage backends and an API of its own that I have not used.
  • A skill is a portable SKILL.md plus scripts that any agent can read; LangGraph tools are native abstractions bound into the framework's own function-calling and typing conventions.
  • My append-only cost log is a flat file I query by hand; LangSmith and Langfuse are a full observability ecosystem — tracing, evaluation, dashboards — that I have not operated.

None of that makes the fit worse for what it was actually built for. A working custom fit for my own pipeline is not the same claim as broader parity with a general-purpose framework, and I am not making that claim here.

4. Evidence

The dispatcher and model router behind the mapping above are public code, not description: both run inside the FridaiOS platform this brief compares.