# Build a Regulated Deployment Approval Workflow with Capsulang

This is the canonical public demo for Capsulang. It shows why the language is a good fit for systems that are stateful, approval-heavy, effectful, and audit-sensitive.

The demo uses `examples/23_change_approval_workflow.caps` and walks through the full path:

```text
English requirement
  → Capsulang capsule
  → check + scenario test
  → machine diagram
  → effect graph
  → A2UI approval/status surface
  → semantic trace
  → replay ledger
  → compile plan
  → release preview
  → verification obligations
```

## 0. The requirement

> Build a regulated deployment approval workflow. A change request must be submitted, reviewed for risk, approved by security and management, and only then may it emit a deployment effect intent. Rejection and rollback must be explicit. The workflow must be replayable and auditable.

This is intentionally not a CRUD app. It tests the things Capsulang is for:

- finite lifecycle states;
- typed events;
- guarded transitions;
- declared effect intents;
- human approval surfaces;
- semantic traces;
- replay ledgers;
- release/compile/verification evidence.

## 1. Start from the pattern library

```bash
caps patterns list --json
caps patterns show regulated-deployment-approval --template --json
caps new regulated-deployment-approval --out examples/my_change_approval.caps
```

The checked demo source is already included:

```bash
examples/23_change_approval_workflow.caps
```

## 2. Check the capsule

```bash
caps check examples/23_change_approval_workflow.caps --json
```

Generated evidence:

```text
examples/guides/change_approval/01_check.json
```

The important result is that the module is parsed, type/effect checked, and recognized as one machine:

```json
{
  "module": "examples.change_approval",
  "status": "checked",
  "machines": 1
}
```

## 3. Visualize the lifecycle

```bash
caps visualize examples/23_change_approval_workflow.caps \
  --kind machine \
  --out examples/guides/change_approval/02_machine.mmd
```

Machine diagram:

```mermaid
stateDiagram-v2
  title ChangeApproval
  [*] --> idle
  idle --> awaiting_risk_review: SubmitChange
  awaiting_risk_review --> awaiting_approvals: RiskReviewed
  awaiting_approvals --> awaiting_approvals: SecurityApprove
  awaiting_approvals --> ready_to_deploy: ManagerApprove
  ready_to_deploy --> deployed: Deploy
  deployed --> rolled_back: Rollback
  ready_to_deploy --> rejected: Reject
  awaiting_approvals --> rejected: Reject
  rolled_back --> [*]
  rejected --> [*]
```

The workflow cannot jump directly from request submission to deployment. It must pass through risk review and approvals.

## 4. Visualize effects

```bash
caps visualize examples/23_change_approval_workflow.caps \
  --kind effects \
  --out examples/guides/change_approval/03_effects.mmd
```

Generated evidence:

```text
examples/guides/change_approval/03_effects.mmd
```

The important effect intents are:

```text
a2a.task security_reviewer.review_change
mcp.call ci.deploy
mcp.call ci.rollback
a2ui.emit change_status
a2ui.emit change_approval
a2ui.emit change_deployment
db.write operational.*
```

Capsulang does not grant ambient deployment authority. The machine emits typed effect intents. The host policy and adapters decide whether the intent is actually executed.

## 5. Run the scenario test

```bash
caps test examples/23_change_approval_workflow.caps \
  --scenario examples/scenarios/change_approval_happy_path.json \
  --json
```

The scenario drives:

```text
SubmitChange
RiskReviewed
SecurityApprove
ManagerApprove
Deploy
```

Expected final state:

```text
deployed
```

Generated evidence:

```text
examples/guides/change_approval/05_scenario_test.json
```

## 6. Preview one transition

```bash
caps machine-run examples/23_change_approval_workflow.caps \
  ChangeApproval SubmitChange \
  --mode dry-run \
  --context '{"change_id":0,"risk_score":0,"security_approved":false,"manager_approved":false,"deployed":false}' \
  --payload '{"change_id":1001}' \
  --trace-jsonl examples/guides/change_approval/12_trace.jsonl \
  --json
```

Generated evidence:

```text
examples/guides/change_approval/12_machine_run_submit.json
examples/guides/change_approval/12_trace.jsonl
```

The transition moves:

```text
idle → awaiting_risk_review
```

and emits:

```text
db.write operational.change_requests
a2a.task security_reviewer.review_change
a2ui.emit change_status
```

## 7. Render an A2UI-style status surface

The demo includes a mocked A2UI stream:

```text
examples/guides/change_approval/20_a2ui_mock.jsonl
```

It shows the status card, risk summary, and legal user actions. In production, user clicks would return typed machine events such as `SecurityApprove`, `ManagerApprove`, `Reject`, or `Deploy`.

## 8. Persist and replay the ledger

```bash
caps ledger-start examples/23_change_approval_workflow.caps ChangeApproval \
  --ledger examples/guides/change_approval/13_ledger.jsonl \
  --instance change-1001 \
  --context '{"change_id":0,"risk_score":0,"security_approved":false,"manager_approved":false,"deployed":false}' \
  --json

caps ledger-step examples/23_change_approval_workflow.caps ChangeApproval SubmitChange \
  --ledger examples/guides/change_approval/13_ledger.jsonl \
  --instance change-1001 \
  --payload '{"change_id":1001}' \
  --mode dry-run \
  --json

caps replay-ledger examples/23_change_approval_workflow.caps ChangeApproval \
  --ledger examples/guides/change_approval/13_ledger.jsonl \
  --instance change-1001 \
  --json
```

Generated evidence:

```text
examples/guides/change_approval/13_ledger.jsonl
examples/guides/change_approval/19_replay.json
```

The ledger records the authoritative sequence of machine events, snapshots, transition records, and effect intents. Replay reconstructs state from the event stream.

## 9. Inspect agent-facing graph and cost

```bash
caps agent-graph --json examples/23_change_approval_workflow.caps
caps cost examples/23_change_approval_workflow.caps --json
```

Generated evidence:

```text
examples/guides/change_approval/06_agent_graph.json
examples/guides/change_approval/07_cost.json
```

`caps cost` reports runtime/audit complexity, not money:

- states;
- transitions;
- unique effect intents;
- external adapters;
- trace/audit complexity.

## 10. Generate release preview

```bash
caps release-preview --json examples/23_change_approval_workflow.caps
```

Generated evidence:

```text
examples/guides/change_approval/08_release_preview.json
```

The release preview includes:

- semantic hash;
- diagnostics;
- backend readiness;
- verification status;
- caveats.

It is deliberately conservative: the workflow is checked and executable through the reference runtime, but machine execution is not compiled directly to Lean/Wasm/RISC-V as a free-running native binary.

## 11. Inspect compilation plan

```bash
caps compile-plan examples/23_change_approval_workflow.caps --target all
```

Generated evidence:

```text
examples/guides/change_approval/09_compile_plan.json
```

For this workflow, compilation means:

```text
pure functions and guards → future compiled targets
state-machine transitions → reference runtime / host ABI path
effect intents → host policy + adapters
```

For pure functions, Capsulang can emit WAT/Wasm/RISC-V assembly in the supported subset. For effectful workflows, the current safe path is checked Capsule Core plus runtime host authorization.

## 12. Generate verification obligations

```bash
caps verify-report examples/23_change_approval_workflow.caps --format json
```

Generated evidence:

```text
examples/guides/change_approval/10_verification_report.json
```

This does not claim full formal proof. It separates:

```text
checked semantics
runtime scenario evidence
open proof obligations
future Lean obligations
```

## 13. What this demo proves

This demo proves that Capsulang can express and inspect a real governed workflow:

- lifecycle states are explicit;
- external actions are typed effect intents;
- approval and deployment are separated;
- A2UI surfaces are projections of machine state;
- traces and ledgers are machine-readable;
- agents can inspect graph, cost, release, compile, and verification reports.

## 14. What this demo does not prove

It does not claim:

- direct native compilation of effectful workflows;
- completed Lean proof of all properties;
- live CI deployment;
- live SurrealDB or TypeDB persistence;
- live A2A/MCP calls unless adapters are configured.

That honesty is part of the design: Capsulang distinguishes checked, executable, compiled, deployed, and verified states.