# machine PaymentProcessor

## context

| Field       | Type    | Default |
|-------------|---------|---------|
| order_id    | string  |         |
| amount      | decimal |         |
| retry_count | int     | 0       |

## events

- submit_payment
- payment_authorized
- payment_declined
- retry_requested
- settlement_confirmed

## state idle [initial]
> Waiting for a payment submission

## state authorizing
> Waiting for payment gateway response
- on_entry: send_authorization_request

## state declined
> Payment was declined

## state settled [final]
> Payment fully settled

## transitions

| Source      | Event                | Guard      | Target      | Action           |
|-------------|----------------------|------------|-------------|------------------|
| idle        | submit_payment       |            | authorizing |                  |
| authorizing | payment_authorized   |            | settled     |                  |
| authorizing | payment_declined     |            | declined    |                  |
| declined    | retry_requested      | can_retry  | authorizing | increment_retry  |
| declined    | retry_requested      | !can_retry | settled     | record_failure   |

## guards

| Name      | Expression              |
|-----------|-------------------------|
| can_retry | `ctx.retry_count < 3`   |

## actions

| Name                       | Signature                                | Effect      |
|----------------------------|------------------------------------------|-------------|
| send_authorization_request | `(ctx) -> Context`                       | AuthRequest |
| increment_retry            | `(ctx) -> Context`                       |             |
| record_failure             | `(ctx) -> Context`                       |             |

## effects

| Name        | Input                              | Output                   |
|-------------|------------------------------------|--------------------------|
| AuthRequest | `{ order_id: string, amount: decimal }` | `{ token: string }`  |

packages/
  orca-lang/       Core: parser, verifier, XState/Mermaid compiler, CLI
  runtime-ts/      TypeScript runtime
  runtime-python/  Python async runtime
  runtime-go/      Go runtime
  demo-ts/         Text adventure game (uses runtime-ts)
  demo-python/     Agent framework scenarios (uses runtime-python)
  demo-go/         Ride-hailing coordinator — 5 machines (uses runtime-go)
  demo-nanolab/    nanoGPT training orchestrator — 5 machines (uses runtime-python)
  mcp-server/      MCP server exposing Orca tools to Claude and other agents

# TypeScript packages
pnpm install
pnpm build

# Python packages (runtime + demos, requires Python >= 3.11)
pnpm run setup:python

# Go packages
pnpm run setup:go
pnpm run build:demo-go

cd packages/orca-lang

# Verify a machine
npx tsx src/index.ts verify examples/payment-processor.orca.md

# Compile to XState
npx tsx src/index.ts compile xstate examples/payment-processor.orca.md

# Compile to Mermaid
npx tsx src/index.ts compile mermaid examples/text-adventure.orca.md

# Convert legacy .orca to .orca.md
# npx tsx src/index.ts convert <path-to-legacy.orca>

## state processing [parallel]
> Payment and notification run concurrently
- on_done: -> completed

### region payment_flow

#### state charging [initial]
#### state paid [final]

### region notification_flow

#### state sending_email [initial]
#### state notified [final]

---

# machine OrderCoordinator

## state processing_payment
- invoke: PaymentProcessor
- on_done: payment_confirmed
- on_error: payment_failed

---

# machine PaymentProcessor

## state idle [initial]
## state settled [final]
...

## state waiting_for_response
> LLM call in progress
- timeout: 30s -> timed_out

// Save
const snap = machine.snapshot();
persistence.save('run-id', snap);

// Resume later (without re-running on_entry)
const snap = persistence.load('run-id');
await machine.resume(snap);

import { MultiSink, FileSink, ConsoleSink, makeEntry } from '@orcalang/orca-runtime-ts';

const sink = new MultiSink(new ConsoleSink(), new FileSink('audit.jsonl'));

const m = new OrcaMachine(def, bus, {
  onTransition: (oldState, newState) => {
    sink.write(makeEntry({ runId, machine: def.name, from: oldState.toString(), to: newState.toString(), ... }));
  }
});

import { parseOrcaAuto, OrcaMachine, EventBus } from '@orcalang/orca-runtime-ts';

const def = parseOrcaAuto(source);
const bus = new EventBus();
const machine = new OrcaMachine(def, bus);

machine.registerAction('send_authorization_request', (ctx, event) => {
  return { ...ctx, payment_token: 'tok_123' };
});

machine.start();
machine.send({ type: 'submit_payment', payload: { order_id: 'ord_1', amount: 99.99 } });

from orca_runtime_python import parse_orca_auto, OrcaMachine, EventBus

def_ = parse_orca_auto(source)
bus = EventBus()
machine = OrcaMachine(def_, bus)

@machine.register_action('send_authorization_request')
async def send_auth(ctx, event):
    return {**ctx, 'payment_token': 'tok_123'}

await machine.start()
await machine.send({'type': 'submit_payment', 'payload': {'order_id': 'ord_1', 'amount': 99.99}})

import "orca-runtime-go/orca_runtime_go"

def, _ := orca_runtime_go.ParseOrcaAuto(source)
bus := orca_runtime_go.NewEventBus()
machine := orca_runtime_go.NewOrcaMachine(def, bus, nil, nil)

machine.RegisterAction("send_authorization_request", func(ctx map[string]any, event orca_runtime_go.Event) map[string]any {
    ctx["payment_token"] = "tok_123"
    return ctx
})

machine.Start()
machine.Send(orca_runtime_go.Event{Type: "submit_payment"})

# Text adventure (TypeScript) — interactive CLI
cd packages/demo-ts && pnpm run cli

# Smoke test (non-interactive)
pnpm test:demo-ts

# Agent framework (Python)
pnpm run test:demo-python

# Ride-hailing coordinator (Go) — runs FareSettlement end-to-end
pnpm run test:demo-go
# With snapshot/resume:
cd packages/demo-go && ./trip --resume

# nanoGPT training orchestrator (Python, no torch required for tests)
pnpm run test:demo-nanolab