Simulation cockpit

Modeling Cockpit: Impact-first checks on guard blockers, history replay, and YAML regression tests before shipping process changes.

Status: Shipped (2026-05-22) — unified with editor-cockpit.md as the Modeling Cockpit

Overview

Simulation answers: If I merge this process change, which real cases break, which transitions are guard-blocked, and do declarative scenarios still pass?

Engine and API:

forecastTransitionBlockers() — guard-blocked exits via canTransition
runSimulationScenarios() — YAML simulations: runner
GET /workflows/:id/simulation-data — operational cases as workflow instances + process context + live lens
POST /workflows/:id/simulate — replay + forecast + scenarios

Modeling Cockpit tabs (web)

Open the editor toolbar Check change panel. Default landing is Impact; detail tabs:

Tab	Question
Impact	What breaks if I ship?
Cases	Which open cases are guard-blocked?
History	Do historical paths still work?
Tests	Do regression tests pass?
Ingestion	Do connected sources cover evidence?
Structure	Is the graph and schema valid?
Ship	Safe to save?

Deep-link a tab with ?simulate=1&tab=cases on the editor URL (for example /editor?file=.kiket/workflows/foo.yaml&simulate=1&tab=ship).

The cockpit header shows ready/blocked status, an operational summary (hover for proposal/baseline detail), baseline picker, and re-run controls. Blocker chips appear only when checks fail.

What is live: open cases use the saved workflow file on the linked repo path (currentConfigPath), not the in-editor buffer. Unsaved edits are preview-only until Save or autosave (~2s). Git commit is for history and CI — not a separate activation step. See editor-cockpit.md § What is live?.

Cases are built from live operational data via caseToWorkflowInstance (not legacy context.workflowData blobs).

YAML scenarios

Declare regression tests under simulations: (requires model_version: "2.0"):

simulations:
  - id: blocked-without-checklist
    title: Cannot approve with incomplete checklist
    initial_state: risk_review
    events:
      - type: transition
        to: approved
    expect:
      final_state: risk_review

Supported event types: created, transition, evidence_observed, approval_recorded, checklist_completed.

Operational vs simulation vocabulary

Adapters and the evidence graph use dotted operational event types (evidence.observed, approval.recorded, workflow.transitioned). YAML regression tests use snake_case simulation verbs (evidence_observed, approval_recorded, transition). The split is intentional: simulation events replay process guards and evidence requirements without requiring a live adapter.

When authoring regression tests in the editor Evidence & checks → Regression tests tab, use the vocabulary bridge to map operational types into simulation events. Example mappings:

Operational (ingestion)	Simulation (YAML)
`evidence.observed`	`evidence_observed` + requirement ids
`approval.recorded`	`approval_recorded`
`workflow.transitioned`	`transition` + target state
`case.created`	`created` + optional initial state

Use Capture test on a Cases row to seed a regression test from a guard blocker.

Canvas data lens

Toggle Live lens in the cockpit header to merge:

Forecast heat — blocked exits and affected case counts per state
Live operations — open cases, open findings, and SLA breaches per state

CLI / CI

Local: pnpm kiket:simulate path/to/workflow.yaml [--baseline base.yaml]
CI: flagship definition packs validated after package build (privacy-request, contract-review)
Ship tab output matches the CLI report shape (schema, graph, scenarios)

See editor-cockpit.md for branch compare, template gallery, and guided UX.