DEV Community: opaopa6969

I built a state machine where invalid transitions can't compile

opaopa6969 — Thu, 09 Apr 2026 05:54:57 +0000

You know this bug.

You're building an OAuth flow. Ten states. Five callbacks. A token refresh that fires at exactly the wrong moment. And then, three hours into debugging:

"Wait — when we reach CALLBACK_RECEIVED, does authorizationCode definitely exist?"

You grep. You trace. You add a null check. You deploy. Two weeks later, a different state, a different missing field, the same three hours.

I got tired of this. So I built tramli.

What tramli does in 30 seconds

tramli is a constrained flow engine. You declare states, transitions, and — this is the key part — what data each processor needs and what it produces:

enum OrderState implements FlowState {
    CREATED(false, true),
    PAYMENT_PENDING(false, false),
    CONFIRMED(false, false),
    SHIPPED(true, false);
    // ...
}

var flow = Tramli.define("order", OrderState.class)
    .initiallyAvailable(OrderRequest.class)
    .from(CREATED).auto(PAYMENT_PENDING, new StartPayment())
    .from(PAYMENT_PENDING).external(CONFIRMED, new PaymentGuard())
    .from(CONFIRMED).auto(SHIPPED, new ShipOrder())
    .build();  // ← THIS is where the magic happens

build() runs 8 validation checks at build time:

Exactly one initial state
At least one terminal state
Every non-terminal state has outgoing transitions
Every state is reachable from initial
At least one terminal is reachable (unless perpetual)
No duplicate transitions from the same state
requires/produces chain is satisfied on every path
No orphan states

Check #7 is what kills the OAuth bug. If ShipOrder.requires() declares PaymentResult.class, but no processor on any path to CONFIRMED produces it — build() throws at startup. Not at 2 AM. Not in production. At startup.

"Just use XState"

Fair question. XState is great — 29K GitHub stars, proper Statecharts with hierarchy and parallel states. I respect it.

But XState doesn't have requires/produces. You can freely read and write context from any state. The type system helps, but it can't prove "this field is always present when we reach this state across every possible path."

tramli trades expressiveness for that guarantee:

XState:  hierarchy + parallel  → can't verify data-flow (exponential paths)
tramli:  flat enum only        → every path is enumerable → full verification

It's a deliberate tradeoff. If you need deep hierarchy and parallel regions, use XState. If you need proof that your data is always where you expect it, use tramli.

The data-flow graph

tramli doesn't just validate — it shows you the data flow:

flow.dataFlowGraph().toMermaid();

This generates a Mermaid diagram showing exactly which processor produces which type, and which processor consumes it. Your flow definition IS the documentation. They can never drift apart.

graph LR
    StartPayment -->|produces PaymentIntent| PaymentGuard
    PaymentGuard -->|produces PaymentResult| ShipOrder
    ShipOrder -->|produces ShipmentInfo| SHIPPED

Real example: OIDC auth flow

This is the flow that started it all. 9 states, 5 processors, and it looks like this:

var oidc = Tramli.define("oidc", AuthState.class)
    .initiallyAvailable(OidcConfig.class)
    .from(IDLE).auto(REDIRECTING, new BuildAuthUrl())
    .from(REDIRECTING).external(CALLBACK_RECEIVED, new CallbackGuard())
    .from(CALLBACK_RECEIVED).auto(EXCHANGING, new ExchangeCode())
    .from(EXCHANGING).auto(VALIDATING, new ValidateTokens())
    .from(VALIDATING).branch(new TokenValidator())
        .to(AUTHENTICATED, "valid")
        .to(REFRESH_NEEDED, "expired")
        .endBranch()
    .from(REFRESH_NEEDED).auto(EXCHANGING, new RefreshToken())
    .from(AUTHENTICATED).external(SESSION_EXPIRED, new ExpiryGuard())
    .from(SESSION_EXPIRED).auto(IDLE, new Cleanup())
    .onAnyError(AUTH_ERROR)
    .build();

50 lines. Every data dependency verified. The build() call proves that ExchangeCode will always have the authorizationCode that CallbackGuard produces. Every. Single. Time.

A procedural version of this was 1,800 lines and had the token bug I mentioned. This version has zero state-related bugs because they're structurally impossible.

Not just Java

tramli has implementations in three languages with a shared test suite:

Java — reference implementation, 3,000 lines
TypeScript — 2,200 lines, same API shape
Rust — 2,200 lines, same guarantees

Same validation rules, same requires/produces contracts, same Mermaid output. A shared test suite in YAML ensures all three behave identically.

Plugin system

tramli core is deliberately frozen — it's a verification kernel. Everything else is a plugin:

Plugin	What it does
`eventstore`	Append-only transition log + replay + compensation
`audit`	Produced-data diff capture per transition
`hierarchy`	Harel-style hierarchical authoring → flat enum code generation
`lint`	Policy-based design checks
`observability`	Telemetry sink integration
`idempotency`	Command-ID duplicate suppression
`diagram`	Mermaid + data-flow bundle
`docs`	Markdown catalog generation

The hierarchy plugin is interesting — it lets you author in Harel Statechart style, then compiles down to flat enums so data-flow verification still works. Best of both worlds.

Who is this for?

Honestly? Not most people.

If your state management is "button clicked → modal opens → modal closes", use Zustand. It's 3KB and it's great.

tramli is for the people who:

Built an OAuth/OIDC flow and lost hours to "which fields exist in which state?"
Wrote a payment processing pipeline and found out in production that a race condition skipped a validation step
Maintained a 2,000-line workflow handler and couldn't tell what would break if they changed line 847

If you've debugged a state transition bug at 2 AM and thought "why can't the compiler just catch this?", that's exactly what tramli does.

GitHub · API Cookbook · Why tramli Works · OIDC Example

Zero dependencies. MIT license. Built by someone who lost too many hours debugging state transitions.

AI Characters Arguing About Your Code. Yes, Really

opaopa6969 — Tue, 31 Mar 2026 00:10:21 +0000

AI Characters Arguing About Your Code. Yes, Really.

Plain AI reviews what you wrote. DGE finds what you forgot to write.

TL;DR

npm install @unlaxer/dge-toolkit && npx dge-install --lang en
Tell Claude Code "run DGE on this"
Characters argue about your design — and surface gaps plain AI misses
3 gaps in 2 minutes. The kind that change your architecture.

Demo (2 min)

The Problem With AI Code Review

AI review is great at checking what you wrote — missing validation, style violations, known best practices. It's a smart checklist.

But the hardest bugs live in what you didn't write. The unstated assumption. The two features that are fine alone but deadly together. The "why JWT?" that nobody asked.

DGE (Dialogue-driven Gap Extraction) creates a cast of characters who argue about your design. A quality guardian, a lazy genius, an attacker, a philosopher — each with a different blind spot they refuse to ignore.

In between their arguments, gaps emerge.

30-Second Setup

npm install @unlaxer/dge-toolkit
npx dge-install --lang en

Then in Claude Code:

Human: run DGE on the auth API design

That's it.

Live Demo: Auth API Review

Here's what actually happened when I DGE'd an auth API:

👤 Columbo: "Just one more thing... this refresh token lasts 30 days. Who decided that? Did anyone ask users if they want to stay logged in for a month?"

→ Gap: Refresh token expiration has no documented rationale

🎩 Picard: "The login response format is undefined. Do you return tokens in the body? Set-Cookie? And on error — if you tell them 'wrong email' vs 'wrong password', you've leaked whether the account exists."

→ Gap: Login response format undefined + error information leakage

🎭 Socrates: "Everyone is assuming JWT. I detect fallacy #5: 'JWT is the modern standard' — says who? If you have one server, sessions work fine. What's the actual reason for JWT?"

→ Gap: No technical rationale for JWT over sessions

3 gaps in 2 minutes. These aren't style nits — they change the architecture. The last one — questioning JWT itself — is something plain AI never does. Plain AI accepts your choices and tells you what's missing. DGE questions whether those choices were right.

DGE vs Plain AI: Same Spec, Honest Comparison

I ran both on the same auth API spec. The plain AI ran in an isolated subprocess — zero knowledge of DGE's results.

	DGE	Plain AI (isolated)
Total gaps	9	28
Critical	2	2
High	6	9
DGE-only findings	3	—

Plain AI found 3x more gaps. But look at the content:

Plain AI: "Missing CSRF protection", "No HTTPS enforcement", "No password reset flow" — a best practices checklist. Valid, but you'd find them in any auth guide.

DGE-only: "Why JWT?", "Token expiration doesn't match app type", "Schema breaks when you add OAuth" — these question design decisions themselves.

They're complementary. DGE toolkit v2 runs both in parallel and merges results automatically.

The Isolation Discovery

First time I ran "plain AI" in the same conversation as DGE, it found 15 gaps. In an isolated subprocess: 28 gaps — 87% more. The AI was unconsciously avoiding DGE's findings. Isolation matters.

Real World: DGE Found an Attack Chain Nobody Designed

This one's from an actual project. I ran DGE with 5 characters on a terminal multiplexer tool. 10 Critical gaps in one session. Here are two that no single-point review would catch:

Path Traversal → Data Exfiltration

⚔ Levi: "Show me the template duplicate code."

const source = path.join(USER_TEMPLATES_DIR, sourceName);
await fs.copy(source, dest);

"No sanitization on sourceName. Send ../../.ssh/id_ed25519 and your SSH private key gets copied to the templates directory. Then GET /api/templates reads it out."

→ Gap: CWE-22 Path Traversal — arbitrary file read via template API

Two Safe Features → One Dangerous Combo

🏥 House: "The /mnt/c/var mount is read-write. The auto-accept feature sends y to confirmation prompts. Now imagine a process asks Delete all files? (y/n) — auto-accept sends y. Two features, both fine alone, deadly together."

→ Gap: RW mount + auto-accept = unintended file destruction

These aren't single-point bugs. They're combinations that emerge because characters build on each other's findings. A checklist review says "add input validation" and "add authentication" separately. DGE characters chain them into attack paths.

What's Inside

19 characters (Columbo, Picard, Holmes, Red Team, Socrates...) — each with distinct blind spots
3 modes: Quick (instant), Design Review (structured), Brainstorm (ideas)
Custom characters: add Batman — personality analyzed, saved, available next session
20 conversation patterns × 8 dialogue techniques — not random arguing, structured exploration

Details: GitHub · INTERNALS.md · CUSTOMIZING.md

DGE catches what you forgot to write. Plain AI catches what you wrote wrong. You need both.

npm: @unlaxer/dge-toolkit · MIT License