Stateful Flows & Statecharts

The problem: POST then GET-by-id

A flat recording matches on method + URI + body. But a freshly-created resource has an id the recording has never seen, so a follow-up read misses every recorded entry and falls through to a 404. That is the single most common reason a recorded mock library "works in the demo and breaks in the test."

POST /charges            → 201 { "id": "ch_9fA2", "status": "created", ... }
GET  /charges/ch_9fA2    → 404   ← the recording never saw ch_9fA2

The resource store fixes the read. The statechart engine fixes the writes that come after it — capture, refund, ship, cancel — so a multi-step flow behaves like the real upstream without anyone hand-authoring a single stub.

Where it sits in the match cascade

In MOCK mode every inbound request walks a fixed, deterministic cascade. The resource store and statechart transitions sit in the middle — after the cheap exact paths, before structural and AI tiers:

The resource store — linking create to read

When the proxy records a successful POST /collection whose response body carries an id, the store captures that body keyed by (service, collection, id). A later GET /collection/{id} looks up the captured body and serves it back as a 200 instead of a 404.

Id extraction tries an explicit field hint first, then id, _id, and {singular}_id (e.g. charge_id for a charges collection). It recurses into nested objects a few levels deep, so Stripe-style envelopes like data.attributes.id resolve. A string id is used as-is; a numeric id is stringified for autoincrement APIs.

POST /charges            → 201 { "id": "ch_9fA2", "status": "created", "amount": 4200 }
GET  /charges/ch_9fA2    → 200 { "id": "ch_9fA2", "status": "created", "amount": 4200 }
                                X-Ghost-Resource: true

Captures are held in memory and mirrored to an append-only JSONL file under the host data volume so they survive a restart; the file is compacted on load to one line per unique resource (last-write-wins). The original status and Content-Type are preserved so the synthetic GET serves the same shape the upstream did.

The statechart engine

A captured resource can be bound to a statechart: a flat, single-region state machine modelling a resource lifecycle. When the collection name matches a known machine id — singular or plural, charges binds to charge— the resource starts in the machine's initial state. State-changing requests then advance it:

A valid action moves the resource to the next state, rewrites the configured status field in the captured body (default status; fixtures can name it stage, phase, etc.), and re-serves the updated body as a 200 tagged with X-Ghost-Transition: <new-state>. An action that isn't valid in the current state is a no-op — the resource keeps its state and the request falls through to the next cascade tier.

# charge starts in "created"
POST /charges/ch_9fA2/capture    → 200 { ..., "status": "captured" }
                                       X-Ghost-Transition: captured

POST /charges/ch_9fA2/refund     → 200 { ..., "status": "refunded" }
                                       X-Ghost-Transition: refunded

# refund is only valid from "captured" — from "created" it no-ops
PATCH /charges/ch_other  { "action": "refund" }   → falls through

The interpreter is pure and immutable — applying a transition never mutates the machine definition, and an undefined transition returns nothing rather than panicking, so a misnamed action can never crash the proxy hot path. v1 scope is flat states only: no hierarchical/compound states, parallel regions, history pseudo-states, or guards.

Bundled fixtures

Gostly ships five lifecycle fixtures built in — no files to load or configure. They cover the common billing/commerce shapes that drive the POST→PATCH→GET failure mode. The bundled engine fires on every tier:

A machine is a JSON document: an id, an initial state, an optional status_field, and a states map where each state lists its outgoing action → target transitions. The charge fixture:

{
  "id": "charge",
  "initial": "created",
  "status_field": "status",
  "states": {
    "created":  { "transitions": { "capture": "captured", "void": "voided" } },
    "captured": { "transitions": { "refund": "refunded" } },
    "refunded": { "transitions": {} },
    "voided":   { "transitions": {} }
  }
}

Per-tenant overrides & the editor (Pro+)

The bundled engine is universal, but editing machines — overriding a fixture, authoring a brand-new lifecycle, and the dashboard graph editor — is a Pro+ capability, gated by the sequences feature flag. The management API is mounted at /v1/statecharts:

A write validates the graph at the boundary (every transition target must reference a defined state; initial must exist), persists it, and materialises a JSON file under the host data volume at statechart-overrides/<tenant>/<id>.json. The proxy then hot-reloads the change — no restart — merging your overrides on top of the bundled set, last-write-wins on id collision. A malformed override file is logged and skipped, never wedging the proxy.

Modeling a multi-step flow

To model a lifecycle the bundled fixtures don't cover — say a shipment that moves through ordered → in_transit → delivered and tracks its state in a stagefield — author a custom machine. Name the status field your API actually uses; the engine rewrites only that field, and only when it's already a top-level string, so other body fields stay untouched.

POST /v1/statecharts
X-API-Key: $GHOST_API_KEY
Content-Type: application/json

{
  "definition": {
    "id": "shipment",
    "initial": "ordered",
    "status_field": "stage",
    "states": {
      "ordered":    { "transitions": { "ship":    "in_transit" } },
      "in_transit": { "transitions": { "deliver": "delivered" } },
      "delivered":  { "transitions": {} }
    }
  }
}

Once it's live, record (or seed) a POST /shipments so the resource store captures a shipment id bound to the machine, then drive the flow:

POST /shipments                    → 201 { "id": "shp_1", "stage": "ordered" }
POST /shipments/shp_1/ship         → 200 { "id": "shp_1", "stage": "in_transit" }
POST /shipments/shp_1/deliver      → 200 { "id": "shp_1", "stage": "delivered" }
GET  /shipments/shp_1              → 200 { "id": "shp_1", "stage": "delivered" }

Observability

Every served response carries a header announcing which tier answered, so you can assert on the match path in a test:

On the agent's Prometheus endpoint (/metrics), a statechart transition increments ghost_requests_total{match_type="resource_transition"}, and the resource-store path emits its own labelled counter on each lookup outcome. Use these alongside the broader ghost_requests_total match-type series to see how much of your MOCK-mode traffic is being answered statefully.

Scope & limits

• Flat machines only. No hierarchical or parallel states, history pseudo-states, guards, or event payloads in this version.
• Single-tenant per deployment. A licensed deployment serves one tenant (the tenant id defaults to default). Override files are keyed by tenant directory and database rows carry row-level-security policies as defense-in-depth — but isolation rests on single-tenancy itself, not on cross-tenant policy enforcement.
• HTTP and HTTPS. Statecharts operate on recorded/replayed HTTP/1.1 and HTTP/2-over-TLS traffic. WebSocket frames are captured for observability but not replayed; there is no gRPC, async-messaging, or database mocking (roadmap).
• Editing is Pro+. The engine and the five bundled fixtures run on every tier; overrides, custom machines, and the editor are gated by the sequences feature.