feat(gastown): Workflows — visual DAG builder with scheduled and event-triggered execution

[jrf0110]

Summary

Add a workflow system to Gastown that lets users define multi-step automation pipelines. Workflows can run on a schedule (cron), on events (bead closed, convoy landed, PR merged), on webhooks, or manually. Each node in the workflow is an action — sling a bead, run a convoy, call an API, send a notification, run a script, or talk to the Mayor.

This system is built around the canonical Gastown/Gascity mental model: formula (authored reusable definition) → molecule (durable runtime instance) → step runs (per-step tracked work). The implementation treats the existing in-repo molecule internals (createMolecule, advanceMoleculeStep, rig_molecules table) as disposable legacy and rebuilds from a clean definition/run model.

Architecture Review: This spec addresses all 15 findings from the Architecture Review comment. See the Critique Findings Tracker at the bottom for a mapping of each finding to its resolution.

---

Motivation

Convoys are great for one-shot batches of related work. But many real-world patterns are recurring or event-driven:

• "Every Monday, scan for dependency updates and create PRs for outdated packages"
• "When a PR is merged to main, run integration tests and deploy to staging"
• "Every night, generate a changelog from the last 24h of merged PRs"
• "When an issue is labeled gastown, sling it as a bead automatically"
• "Weekly: audit code for security vulnerabilities, create beads for anything critical"

Workflows turn Gastown from a task executor into an automation platform.

---

Naming / Canonical Compatibility

Canonical Term	Cloud Product Label	Data Model Name	Description
Formula	Workflow Definition	workflow_definition	Authored, reusable, versioned graph definition
Molecule	Workflow Run	workflow_run	Instantiated durable execution of a definition revision
Step	Run Step / Task	step_run	Per-step runtime state within a run
Wisp	Ephemeral Run	(future)	Lightweight run that doesn't persist long-term
Digest	Run Summary	workflow_run.summary	Final output/result of a completed run

Important: Avoid bare workflow as the sole object name in APIs where we actually mean definition or run — that ambiguity compounds quickly. Use definition vs run explicitly in the data model and API names.

Dual-label in UI: e.g. "Workflow Definitions (Formulas)", "Run Details (Molecule)". Preserve Gastown aliases in docs/tooltips/API descriptions.

---

Architecture Decision: One WorkflowDO Per Town

[Addresses P0-1] — Revised from "one WorkflowDO per definition" to "one WorkflowDO per town."

A new WorkflowDO Durable Object namespace. One WorkflowDO instance per town, keyed by townId. All workflow definitions, runs, and step states for a town live in a single DO's SQLite database.

Routing:  getWorkflowDOStub(env, townId)  // trivial — same as TownDO lookup

Why one-per-town, not one-per-definition?

• Event matching is local: When TownDO writes a durable notification (bead closed, convoy landed), WorkflowDO reads it on the next alarm tick via a local SQLite query over all definitions' trigger configs. No fan-out RPC to N definition-scoped DOs.
• Trivial routing: tRPC handlers just need townId to find the right WorkflowDO. One-per-definition would require a lookup table or definition→town mapping on every request.
• SQLite is more than enough: Even a busy town will have dozens of definitions and thousands of run records — well within DO SQLite capacity.
• Single alarm loop: One alarm manages all cron evaluations, event matching, and step progression for the town. No per-definition alarm overhead.

Why not TownDO? The TownDO alarm is already doing too much (#1855 — 47+ ops/tick). Workflows have fundamentally different scheduling needs (cron-based, potentially long-running waits). A dedicated DO keeps concerns separated and lets workflows scale independently.

---

Cross-DO Communication: Durable Outbox Pattern

[Addresses P0-2] — Replaced lossy cross-DO RPC with a durable outbox, mirroring the town_events pattern.

Cross-DO RPC is fire-and-forget. If the call fails, or either DO is evicted between the event and the notification, the workflow step stays waiting forever. We do not use direct RPC for event delivery.

Instead, we use a durable outbox pattern — the same pattern used by town_events for the TownDO reconciler (see events.ts: insertEvent → drainEvents → markProcessed).

How it works

TownDO side — when a workflow-relevant event fires (bead closed, convoy landed, PR merged), TownDO writes a row into a workflow_notifications table in its own SQLite:

INSERT INTO workflow_notifications (
  notification_id, event_type, town_id, bead_id, convoy_id, payload, created_at, processed_at
) VALUES (?, ?, ?, ?, ?, ?, ?, NULL)

This is a synchronous SQL write inside the existing alarm tick — zero latency, zero failure risk. TownDO also re-arms the WorkflowDO alarm to ensure timely processing.

WorkflowDO side — on each alarm tick, the engine drains unprocessed notifications:

SELECT * FROM workflow_notifications WHERE processed_at IS NULL ORDER BY created_at ASC

For each notification, it checks all enabled definitions' trigger configs for a match. On match, it starts a run. After processing, it marks the notification as processed (markProcessed pattern).

Sequence

TownDO                                    WorkflowDO
  │                                          │
  ├── bead.closed fires                      │
  ├── INSERT INTO workflow_notifications     │
  ├── workflowStub.ping() ─────────────────→│  (best-effort, just re-arms alarm)
  │                                          │
  │                                          ├── alarm tick
  │                                          ├── drain workflow_notifications
  │                                          ├── match event → definition triggers
  │                                          ├── start run(s)
  │                                          ├── mark notification processed
  │                                          └── re-arm alarm

The ping() RPC is purely an optimization to reduce latency — it re-arms the WorkflowDO alarm. If it fails, the WorkflowDO's own alarm (ticking every 60s when idle) will pick up the notification on the next cycle. No data is lost.

Notification table (in TownDO's SQLite)

CREATE TABLE IF NOT EXISTS workflow_notifications (
  notification_id TEXT PRIMARY KEY,
  event_type TEXT NOT NULL,            -- 'bead_closed', 'convoy_landed', 'pr_merged', etc.
  town_id TEXT NOT NULL,
  bead_id TEXT,
  convoy_id TEXT,
  payload TEXT NOT NULL DEFAULT '{}',  -- JSON: additional context
  created_at TEXT NOT NULL,
  processed_at TEXT                     -- NULL = unprocessed
);
CREATE INDEX idx_wf_notif_unprocessed ON workflow_notifications (processed_at) WHERE processed_at IS NULL;

Pruning: Processed notifications older than 7 days are cleaned up in TownDO's housekeeping phase (same pattern as pruneOldEvents).

---

Alarm Loop: Async Execution Model

[Addresses P0-3] — Node execution is async, not blocking. Mirrors TownDO's Phase 1 (SQL) → Phase 2 (side effects) separation.

Cloudflare DOs have a 30-second execution limit per alarm invocation. Node execution (Mayor Prompts, HTTP calls, script runs) must not run synchronously in the alarm tick.

The WorkflowDO alarm follows the same proven pattern as TownDO's reconciler:

Phase 0: Drain notifications

Read unprocessed notifications from TownDO (via shared SQLite or via the notification drain). Match against enabled definitions' triggers. For matches, create new workflow_run records and seed initial step states.

Phase 1: Reconcile — compute ready nodes, apply SQL mutations

Walk all active runs. For each run, evaluate the DAG:

• Identify nodes whose dependencies are satisfied (all upstream nodes completed)
• Transition ready nodes to dispatched status (SQL mutation)
• Transition completed wait nodes based on received events
• Collect async side effects as deferred functions (same as applyAction returning (() => Promise<void>) | null)

All SQL mutations happen synchronously in this phase. No I/O.

Phase 2: Execute side effects (async, best-effort)

// Identical to TownDO's Phase 2 pattern
if (sideEffects.length > 0) {
  const results = await Promise.allSettled(sideEffects.map(fn => fn()));
  for (const r of results) {
    if (r.status === 'fulfilled') metrics.sideEffectsSucceeded++;
    else metrics.sideEffectsFailed++;
  }
}

Side effects include:

• townStub.slingBead(...) — create a bead on TownDO for action_sling_bead nodes
• fetch(url, ...) — execute HTTP calls for action_http nodes
• mayorStub.prompt(...) — invoke Mayor for action_mayor_prompt nodes

Phase 3: Housekeeping

Prune old completed runs, prune processed notifications, emit metrics.

Result delivery: self-notification pattern

When a side effect completes, it writes the result back as a workflow event (into WorkflowDO's own workflow_events table) and re-arms the alarm:

// Inside a side effect for an action_http node:
async () => {
  try {
    const response = await fetch(url, options);
    const body = await response.text();
    workflowEvents.insertEvent(sql, 'step_completed', {
      run_id: runId,
      step_run_id: stepRunId,
      payload: { status: response.status, body },
    });
  } catch (err) {
    workflowEvents.insertEvent(sql, 'step_failed', {
      run_id: runId,
      step_run_id: stepRunId,
      payload: { error: String(err) },
    });
  }
  // Re-arm alarm so next tick processes the result
  ctx.storage.setAlarm(Date.now() + 100);
}

The next alarm tick drains these events, updates step status, and continues DAG traversal. This means:

• No blocking: The alarm tick returns quickly. Side effects run concurrently.
• Durable: Results are written to SQLite. If the DO is evicted mid-execution, the next alarm retries any dispatched steps that never wrote a result (with exponential backoff).
• Observable: Every state transition is recorded.

Step status lifecycle

pending → ready → dispatched → completed
                            → failed
                            → timed_out
         ready → skipped    (upstream failure with on_failure: 'skip')

---

Failure Handling: on_failure Semantics

[Addresses P0-4] — Diamond pattern and configurable failure propagation.

Each edge in the graph can specify an on_failure policy (default: 'skip'):

type WorkflowEdge = {
  id: string;
  source: string;       // source node ID
  target: string;       // target node ID
  condition?: EdgeCondition | null;
  on_failure: 'skip' | 'continue' | 'fail_run';
};

Semantics:

Policy	Behavior
skip (default)	If the source node failed, downstream nodes reachable only through this edge are marked skipped. Other paths to the same node are unaffected.
continue	Downstream nodes execute regardless. The failed step's output is null.
fail_run	The entire run is marked failed immediately. All pending/ready/dispatched steps are cancelled.

Diamond resolution: In a diamond (A→B, A→C, B→D, C→D), if B completes and C fails:

• Edge C→D has on_failure: 'skip' → D is skipped (both paths must succeed)
• Edge C→D has on_failure: 'continue' → D executes with C's output as null
• Edge C→D has on_failure: 'fail_run' → entire run fails

The engine evaluates all incoming edges to a node. A node is ready when:

• All incoming edges with on_failure: 'skip' or 'continue' have their source completed or failed
• No incoming edge with on_failure: 'fail_run' has a failed source
• At least one incoming edge has a completed (not failed) source, OR all failed sources have on_failure: 'continue'

---

Wrangler Configuration

Add to wrangler.jsonc:

// In durable_objects.bindings:
{ "name": "WORKFLOW", "class_name": "WorkflowDO" }

// In migrations (new tag):
{ "tag": "v3", "new_sqlite_classes": ["WorkflowDO"] }

File: src/dos/Workflow.do.ts with sub-modules in src/dos/workflow/:

dos/
  Workflow.do.ts              # Class definition, RPC surface, alarm loop
  workflow/
    definitions.ts            # Definition CRUD, versioning
    runs.ts                   # Run lifecycle, step state management
    engine.ts                 # DAG traversal, node readiness, side effect dispatch
    scheduling.ts             # Cron evaluation, trigger matching
    nodes.ts                  # Node type implementations (side effect factories)
    events.ts                 # Workflow-scoped event recording (outbox pattern)

---

SQLite Schema (WorkflowDO)

workflow_definitions

CREATE TABLE IF NOT EXISTS workflow_definitions (
  definition_id TEXT PRIMARY KEY,
  town_id TEXT NOT NULL,
  name TEXT NOT NULL,
  description TEXT DEFAULT '',
  revision INTEGER NOT NULL DEFAULT 1,
  enabled INTEGER NOT NULL DEFAULT 0,           -- 0 = disabled, 1 = enabled
  graph TEXT NOT NULL DEFAULT '{}',              -- JSON: nodes (without positions), edges (with on_failure)
  layout TEXT NOT NULL DEFAULT '{}',             -- JSON: React Flow positions only (visual, non-execution)
  variables_schema TEXT NOT NULL DEFAULT '{}',   -- JSON Schema for run-time variables
  triggers TEXT NOT NULL DEFAULT '[]',           -- JSON array of trigger configs
  schedule TEXT,                                 -- Cron expression (null = no schedule)
  timezone TEXT NOT NULL DEFAULT 'UTC',          -- IANA timezone for cron evaluation (SINGLE source of truth)
  durability TEXT NOT NULL DEFAULT 'standard' CHECK(durability IN ('standard', 'ephemeral')),
  max_concurrent_runs INTEGER NOT NULL DEFAULT 5,
  last_run_id TEXT,
  last_run_status TEXT,
  last_run_at TEXT,                              -- [P1-5] Timestamp of last run start
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
CREATE INDEX idx_wf_def_town ON workflow_definitions (town_id);
CREATE INDEX idx_wf_def_enabled ON workflow_definitions (enabled) WHERE enabled = 1;
CREATE INDEX idx_wf_def_schedule ON workflow_definitions (schedule) WHERE schedule IS NOT NULL;

[P1-5]: last_run_at column added.
[P1-7]: graph and layout are separate columns. graph contains execution-relevant data (nodes without positions, edges with on_failure config). layout contains React Flow position data. Layout-only changes don't bump the revision.
[P2-15]: timezone is defined at the definition level only (single source of truth). Removed from trigger config.

workflow_definition_revisions — deferred

[Addresses P1-6]: Revision history is deferred to Phase 3 (not MVP). For now, only the current graph/layout is stored. The revision field tracks the version number. When we add revision history, it will be:

-- DEFERRED: not in MVP or Phase 2
CREATE TABLE IF NOT EXISTS workflow_definition_revisions (
  revision_id TEXT PRIMARY KEY,
  definition_id TEXT NOT NULL,
  revision INTEGER NOT NULL,
  graph TEXT NOT NULL,
  layout TEXT NOT NULL,
  variables_schema TEXT NOT NULL,
  triggers TEXT NOT NULL,
  schedule TEXT,
  created_at TEXT NOT NULL,
  created_by TEXT,                              -- user/agent who made the change
  UNIQUE(definition_id, revision)
);

workflow_runs

CREATE TABLE IF NOT EXISTS workflow_runs (
  run_id TEXT PRIMARY KEY,
  definition_id TEXT NOT NULL,
  definition_revision INTEGER NOT NULL,         -- pinned at run creation
  graph_snapshot TEXT NOT NULL,                  -- full graph at time of run (immutable)
  status TEXT NOT NULL DEFAULT 'pending'
    CHECK(status IN ('pending', 'running', 'completed', 'failed', 'cancelled', 'timed_out')),
  trigger_type TEXT NOT NULL,                   -- 'manual', 'schedule', 'event', 'webhook'
  trigger_data TEXT NOT NULL DEFAULT '{}',       -- JSON: trigger context
  variables TEXT NOT NULL DEFAULT '{}',          -- JSON: resolved runtime variables
  summary TEXT,                                  -- Final output/digest
  error TEXT,                                    -- Error message if failed
  started_at TEXT NOT NULL,
  completed_at TEXT
);
CREATE INDEX idx_wf_run_def ON workflow_runs (definition_id);
CREATE INDEX idx_wf_run_status ON workflow_runs (status) WHERE status IN ('pending', 'running');

workflow_step_runs

CREATE TABLE IF NOT EXISTS workflow_step_runs (
  step_run_id TEXT PRIMARY KEY,
  run_id TEXT NOT NULL,
  node_id TEXT NOT NULL,                        -- reference to graph node
  status TEXT NOT NULL DEFAULT 'pending'
    CHECK(status IN ('pending', 'ready', 'dispatched', 'completed', 'failed', 'skipped', 'timed_out')),
  output TEXT,                                   -- JSON: step output
  error TEXT,
  bead_id TEXT,                                  -- if step created a bead
  dispatch_attempts INTEGER NOT NULL DEFAULT 0,
  last_dispatch_at TEXT,
  started_at TEXT,
  completed_at TEXT
);
CREATE INDEX idx_wf_step_run ON workflow_step_runs (run_id);
CREATE INDEX idx_wf_step_bead ON workflow_step_runs (bead_id) WHERE bead_id IS NOT NULL;
CREATE INDEX idx_wf_step_status ON workflow_step_runs (run_id, status);

workflow_events (WorkflowDO internal outbox)

CREATE TABLE IF NOT EXISTS workflow_events (
  event_id TEXT PRIMARY KEY,
  event_type TEXT NOT NULL,                     -- 'step_completed', 'step_failed', 'notification_received', etc.
  run_id TEXT,
  step_run_id TEXT,
  payload TEXT NOT NULL DEFAULT '{}',
  created_at TEXT NOT NULL,
  processed_at TEXT
);
CREATE INDEX idx_wf_evt_unprocessed ON workflow_events (processed_at) WHERE processed_at IS NULL;

---

Graph Definition Model

Separate graph from layout

[Addresses P1-7]

The graph column stores execution-relevant structure:

type WorkflowGraph = {
  nodes: WorkflowNode[];    // type, config — NO position data
  edges: WorkflowEdge[];    // source, target, condition, on_failure
};

The layout column stores visual-only data:

type WorkflowLayout = {
  positions: Record<string, { x: number; y: number }>;  // nodeId → position
  viewport?: { x: number; y: number; zoom: number };
};

Layout changes (dragging nodes, zooming) update layout without bumping revision. Graph changes (adding/removing nodes, changing edges, editing node config) bump revision.

Node types

Phase 1 (MVP): 3 node types

• trigger_manual — manual run trigger
• action_sling_bead — create a bead on TownDO
• control_condition — if/else branching

Phase 2: +5 node types

• trigger_schedule — cron-based trigger
• trigger_event — event-based trigger (bead closed, convoy landed)
• action_sling_convoy — create a convoy
• control_wait_bead — wait for a bead to reach a status
• control_delay — wait for a duration

Phase 3: +7 node types

• trigger_webhook — HTTP webhook trigger
• action_mayor_prompt — LLM inference via Mayor
• action_http — arbitrary HTTP request
• action_script — run a script (see security note below)
• control_wait_convoy — wait for convoy to land
• output_notify — send a notification
• output_update_bead — update an existing bead

Node Type Config Shapes

Each node type has a specific config schema validated at save time:

Node Type	Config Fields
trigger_schedule	{ cron: string } (timezone is definition-level)
trigger_event	{ event_type: 'bead_closed' | 'convoy_landed' | 'pr_merged', filter?: Record<string, string> }
trigger_webhook	{ secret?: string } (URL is auto-generated)
trigger_manual	{ input_schema?: Record<string, VariableSpec> }
action_sling_bead	{ rig_id: string, title: string, body?: string, priority?: string, labels?: string[] }
action_sling_convoy	{ rig_id: string, title: string, beads: ConvoyBeadSpec[] }
action_mayor_prompt	{ prompt_template: string } — supports {{step.<nodeId>.output}} interpolation
action_http	{ url: string, method: string, headers?: Record<string,string>, body_template?: string, allowed_domains?: string[] }
action_script	{ script: string, timeout_ms?: number } — runs in own container
control_wait_bead	{ bead_ref: string, target_status: 'closed' | 'failed', timeout_ms?: number }
control_wait_convoy	{ convoy_ref: string, timeout_ms?: number }
control_condition	{ expression: string } — evaluates to boolean, branches via edge conditions
control_delay	{ duration_ms: number }
output_notify	{ channel: 'slack' | 'webhook', target: string, message_template: string }
output_update_bead	{ bead_ref: string, fields: Record<string, unknown> }

Template interpolation

Use {{step.<nodeId>.output.<path>}} syntax for referencing outputs from upstream steps.

[Addresses P2-13]: Template interpolation in HTTP URL and body templates could exfiltrate data. Mitigation (deferred to implementation):

• action_http node config includes an optional allowed_domains list. If set, the resolved URL must match.
• Template values are sanitized (no control characters, length limits).
• Full sandboxing of template interpolation is tracked as a follow-up item.

action_script security

[Addresses P2-14]: action_script nodes run in their own short-lived container invocation, NOT in an agent's container. They get a fresh, isolated environment with:

• Read-only access to the repo
• No access to agent state or other containers
• Strict timeout (30s default, configurable up to 5min)
• Resource limits (memory, CPU)

This node type is deferred to Phase 4. The container strategy will be finalized during implementation.

---

DAG Execution Engine

Readiness evaluation

On each alarm tick, for each active run:

1. Query all step_run records for the run
2. For each pending step, check if all incoming edges' source nodes are in a terminal state (completed, failed, skipped)
3. Apply on_failure semantics per edge to determine if the step should be ready, skipped, or if the run should fail
4. Transition ready steps to dispatched (SQL mutation)
5. Return side effect functions for dispatched steps

Parallel execution

Steps with no dependency between them execute in parallel — they're all transitioned to dispatched in the same alarm tick, and their side effects run concurrently via Promise.allSettled.

Phase 1 (MVP): Linear execution only (no parallel branches). Simplifies the engine significantly.

Phase 2+: Full parallel branch support.

Cycle prevention

• At save time: Topological sort validation. If the graph has a cycle, the save is rejected with a validation error.
• At runtime: Max step count guard (1000 steps per run). If exceeded, run is marked timed_out.

Run cancellation

When a run is cancelled:

1. All pending, ready, and dispatched steps are marked skipped
2. In-flight side effects (already dispatched) will complete but their results are ignored (step is already skipped)
3. Run status → cancelled

Concurrent run limits

max_concurrent_runs (default: 5) on the definition. If a trigger fires while at the limit, the run is queued with pending status and starts when a slot opens.

---

Cron Scheduling

Evaluation

On each alarm tick, the engine queries all enabled definitions with a non-null schedule:

SELECT * FROM workflow_definitions
WHERE enabled = 1 AND schedule IS NOT NULL

For each, evaluate the cron expression against the definition's timezone. If the current time matches the cron and last_run_at is before the previous matching tick, start a new run.

Catch-up policy

[Addresses P2-11]: Skip missed ticks. On DO re-wake after eviction, only fire if the NEXT cron tick is in the future and last_run_at is before it. Do not backfill. This prevents a DO waking up after 4 hours of eviction from firing 240 runs for a per-minute schedule.

function shouldFireCron(schedule: string, timezone: string, lastRunAt: string | null): boolean {
  const now = Date.now();
  const prevTick = getPreviousCronTick(schedule, timezone, now);
  const nextTick = getNextCronTick(schedule, timezone, now);

  // Only fire if we haven't already run for this tick window
  if (lastRunAt && new Date(lastRunAt).getTime() >= prevTick) return false;

  // Only fire if the next tick is in the future (we're not waking up to ancient backlog)
  return nextTick > now;
}

---

Permissions

[Addresses P1-9]

Follows the resolveTownOwnership pattern:

Action	Who
Create / edit / delete definitions	Town owner, org admin
Enable / disable definitions	Town owner, org admin
Trigger manual runs	Town owner, org admin, org members
View definitions and runs	All org members
Webhook triggers	Authenticated via webhook secret (per-definition), rate-limited

Webhook secrets are generated per-definition and stored in the triggers JSON config. The webhook endpoint validates the secret before creating a run.

---

Billing & Rate Limiting

[Addresses P1-10]

Limit	Free	Pro	Enterprise
Workflow definitions per town	3	20	Unlimited
Runs per month	50	1,000	10,000
Steps per run	10	50	200
LLM tokens per mayor_prompt step	4K	16K	64K
LLM token budget per workflow per month	100K	1M	10M
Min cron interval	1 hour	5 min	1 min
Webhook triggers per minute	5	30	100
Concurrent runs per definition	1	5	20

Rate limiting is enforced at:

1. Run creation: Check monthly run count before starting
2. Step dispatch: Check step count per run before transitioning to dispatched
3. Webhook endpoint: Token bucket rate limiter per definition
4. Cron evaluation: Min interval check against tier

Tier info is read from the town's billing context (same pattern as existing feature gates).

---

Auto-save & Draft Model

[Addresses P2-12]

The visual editor uses a draft model:

• Auto-save writes to a draft_graph and draft_layout column (or a separate workflow_drafts table). No revision bump, no validation. The editor reads from the draft on load.
• "Save & Publish" validates the graph (cycle detection, required fields, node config validation), copies draft → graph/layout, bumps revision, and optionally updates the enabled state.
• If there's no draft (draft columns are null), the editor loads from the published graph/layout.

This prevents half-edited graphs from executing while still giving users a seamless editing experience.

---

tRPC API

Definition Management

workflows.definitions.list    // { townId } → WorkflowDefinition[]
workflows.definitions.get     // { townId, definitionId } → WorkflowDefinition
workflows.definitions.create  // { townId, name, graph, layout?, triggers?, schedule? } → WorkflowDefinition
workflows.definitions.update  // { townId, definitionId, ...partial } → WorkflowDefinition
workflows.definitions.delete  // { townId, definitionId } → void
workflows.definitions.setEnabled  // { townId, definitionId, enabled } → void
workflows.definitions.validate    // { townId, graph } → ValidationResult
workflows.definitions.saveDraft   // { townId, definitionId, graph, layout } → void
workflows.definitions.publishDraft // { townId, definitionId } → WorkflowDefinition (validates + bumps revision)

Run Management

workflows.runs.list     // { townId, definitionId?, status? } → WorkflowRun[]
workflows.runs.get      // { townId, runId } → WorkflowRun & { steps: StepRun[] }
workflows.runs.trigger  // { townId, definitionId, variables? } → WorkflowRun
workflows.runs.cancel   // { townId, runId } → void

Webhook HTTP endpoint

POST /api/webhooks/workflow/:definitionId
Headers: X-Webhook-Secret: <secret>
Body: JSON payload (passed as trigger_data)

---

UI: Phased Approach

Phase 1 (MVP): Form-based editor

4 routes:

• /towns/:townId/workflows — list of workflow definitions with status badges
• /towns/:townId/workflows/new — create form (name, description, linear step list)
• /towns/:townId/workflows/:defId/edit — edit form (same as create, plus enable/disable toggle)
• /towns/:townId/workflows/:defId/runs — run history list with status, duration, trigger type

The MVP editor is a form-based linear step editor, not React Flow. Users add steps in sequence. Each step has a type selector and config form. This is sufficient for linear workflows and dramatically reduces implementation complexity.

Phase 3: React Flow Visual Editor

Upgrade to a full visual DAG editor:

• Three-panel layout: node palette (left), canvas (center), inspector (right)
• Custom node components with status badges
• Drag-and-drop from palette
• Edge drawing with on_failure config in the inspector
• Auto-save → draft, explicit publish
• Run visualization overlay (step statuses on the graph)

---

Event Triggers / TownDO Integration

When Gastown events occur, TownDO writes them to the workflow_notifications outbox table (see Cross-DO Communication above). WorkflowDO drains these on each alarm tick and matches against trigger configs.

Event Types Available as Triggers

Using the existing TownEventType enum plus new workflow-specific events:

Event	Payload	When
bead_closed	{ bead_id, bead_type, rig_id, title }	Any bead reaches closed status
bead_failed	{ bead_id, bead_type, rig_id, title, error }	Any bead reaches failed status
convoy_landed	{ convoy_id, title, bead_count }	All beads in a convoy complete
convoy_started	{ convoy_id, title }	Convoy begins execution
pr_merged	{ bead_id, rig_id, pr_url }	PR associated with a bead is merged
pr_created	{ bead_id, rig_id, pr_url }	PR is created for a bead

---

Agent Ergonomics / Compatibility Bridge

Preserve gt_mol_current / gt_mol_advance semantics, backed by the new run model:

• gt_mol_current → query WorkflowDO for the current ready step(s) in the active run
• gt_mol_advance → mark a step as completed and advance the DAG

These are compatibility shims maintained as plugin tools, NOT structural constraints on the data model. The new API is the primary interface; these exist for agents that already use the molecule protocol.

---

Implementation Plan

Phase 0: Legacy Cleanup (1 week)

Goal: Mark current molecule internals as disposable legacy.

• Audit all references to rig_molecules table, createMolecule, advanceMoleculeStep, MoleculeStepper.tsx, FormulaLibrary
• Classify each as: keep (conceptually), shim (temporarily), or delete
• Fix the known formula shape mismatch bug: createMolecule() treats formula as array but API sends { steps: [...] }
• Remove or mark stale schema/docs as superseded
• Document the canonical mapping (formula→definition, molecule→run, step→step_run) in AGENTS.md or a spec doc

Phase 1: MVP (2 weeks)

[Addresses P1-8]: Scoped to a realistic 2-week deliverable.

Goal: End-to-end workflow execution with manual trigger, linear steps, form-based editor.

Backend:

• WorkflowDO skeleton (one per town, keyed by townId)
• workflow_definitions table + CRUD
• workflow_runs + workflow_step_runs tables
• workflow_events table (internal outbox)
• Alarm loop with Phase 0/1/2 pattern
• Linear DAG engine (no parallel branches)
• Manual trigger only
• 3 node types: trigger_manual, action_sling_bead, control_condition
• tRPC API: definition CRUD + run trigger/list/get/cancel
• workflow_notifications table in TownDO + write path for bead_closed events (wiring only — event triggers activate in Phase 2)

Frontend:

• Workflow list page with create button
• Form-based linear editor (add/remove/reorder steps)
• Run list with status badges
• Run detail view (step list with status, output, errors)

Not in Phase 1: Cron, event triggers, webhooks, parallel branches, React Flow, wait nodes, Mayor/HTTP/script nodes, revision history, draft model.

Phase 2: Event Triggers & Scheduling (2-3 weeks)

• Event trigger support (bead_closed, convoy_landed, pr_merged)
• Cron scheduling with timezone support + catch-up policy (skip missed ticks)
• trigger_schedule and trigger_event node types
• control_wait_bead, control_delay node types
• action_sling_convoy node type
• Parallel branch execution in the DAG engine
• Concurrent run limiting
• Billing/rate limiting enforcement
• Permissions enforcement

Phase 3: Visual Editor & Advanced Nodes (3-4 weeks)

• React Flow visual editor (three-panel layout)
• Auto-save draft model + publish flow
• trigger_webhook + webhook HTTP endpoint
• action_mayor_prompt node type
• action_http node type (with allowed_domains)
• output_notify, output_update_bead node types
• Revision history (workflow_definition_revisions table)
• Run visualization overlay on the graph

Phase 4: Polish & Templates (1-2 weeks)

• action_script node type (own container, sandboxed)
• Workflow templates (pre-built definitions for common patterns)
• Import/export definitions as JSON
• Run summary/digest generation
• Metrics dashboard (runs/day, success rate, avg duration)
• gt_mol_current / gt_mol_advance compatibility shims

Total realistic estimate: 9-12 weeks (including Phase 0)

[Addresses P1-8]: Previous estimate of 5-6 weeks was too aggressive. The reconciler (simpler scope) took ~3 weeks. This system adds a new DO + DAG engine + editor + cron + cross-DO communication + 15 node types + tRPC API + run visualization.

Future scope (not in this issue)

• Wisps (ephemeral runs that don't persist)
• Sub-workflow composition (a node that triggers another workflow)
• Approval gates (human-in-the-loop nodes)
• Workflow marketplace / sharing

---

References

• React Flow — visual DAG editor library
• perf(gastown): TownDO runs 47+ SQL queries per alarm tick — deduplicate and guard wasteful queries #1855 — TownDO alarm optimization (rationale for separate WorkflowDO)
• feat(gastown): Auto-resolve PR feedback — review comments and failing CI checks #1002 — Auto-resolve PR feedback (workflow template candidate)
• feat(gastown): Make the refinery optional — allow polecats to merge directly without review #1739 — Optional refinery (pr_only mode is a workflow-friendly pattern)
• feat(gastown): Slack integration — talk to the Mayor from Slack #1940 — Slack integration (Notify node target)
• Reconciler spec: reconciliation-spec.md
• TownDO event pattern: src/dos/town/events.ts
• TownDO alarm loop: src/dos/Town.do.ts (Phase 0-2 pattern)
• TownDO action model: src/dos/town/actions.ts (SQL mutations → deferred side effects)
• TownDO reconciler: src/dos/town/reconciler.ts (read-only state → Action[] → side effects)

---

Critique Findings Tracker

All 15 findings from the Architecture Review comment have been addressed:

#	Priority	Finding	Resolution	Section
1	P0	Instance model: one WorkflowDO per town, not per definition	✅ Rewritten — one WorkflowDO per town, keyed by townId	Architecture Decision
2	P0	Event delivery: durable outbox, not lossy RPC	✅ Rewritten — workflow_notifications outbox in TownDO, drain pattern	Cross-DO Communication
3	P0	Alarm loop: async execution, no blocking I/O	✅ Rewritten — Phase 0/1/2 pattern, side effects via Promise.allSettled, self-notification	Alarm Loop
4	P0	Diamond failure: on_failure semantics	✅ Added — skip, continue, fail_run per edge	Failure Handling
5	P1	Schema missing last_run_at	✅ Added to workflow_definitions schema	SQLite Schema
6	P1	No revision history storage	✅ Acknowledged — deferred to Phase 3, schema sketched	SQLite Schema
7	P1	Layout leaks into execution graph	✅ Separated — graph and layout are distinct columns	Graph Definition Model
8	P1	Effort estimates too aggressive	✅ Revised — 9-12 weeks total, 2-week MVP scoped	Implementation Plan
9	P1	Permissions model missing	✅ Added — follows resolveTownOwnership pattern	Permissions
10	P1	Billing/rate limiting missing	✅ Added — per-tier limits table, enforcement points	Billing & Rate Limiting
11	P2	Cron catch-up policy	✅ Explicit "skip missed ticks" with pseudocode	Cron Scheduling
12	P2	Auto-save + validation conflict	✅ Draft model — auto-save writes draft, publish validates	Auto-save & Draft Model
13	P2	Template interpolation security	✅ Acknowledged — allowed_domains, deferred to impl	Graph Definition Model
14	P2	action_script container strategy	✅ Stated — own container, deferred to Phase 4	Graph Definition Model
15	P2	Timezone in two places	✅ Fixed — definition-level only, removed from triggers	SQLite Schema

[jrf0110]

I dug through the canonical Gastown/Gascity workflow docs plus the current cloud codebase, and I think we should treat this as a compatibility-and-product-shaping effort rather than a straight React Flow feature build.

Canonical model summary

• In canonical Gastown/Gascity, a formula is the authored reusable workflow definition, a molecule is the durable runtime instance of that definition, and each step is a first-class tracked unit of work.
• The critical compatibility invariant is the template-to-instance lifecycle: resolve a formula, instantiate it into a molecule, then advance through durable step state with explicit current/ready/completed semantics.
• Runtime truth lives in the instantiated molecule, not just in the source definition. Step completion timing and per-step state matter because molecules double as execution scaffolding and audit trail.
• Dependency-aware progression is part of the model. Even if we do not reproduce every CLI verb (cook, pour, squash, etc.), Gastown-native users should still recognize the source definition vs runtime instance split, graph semantics, durable execution, and step-level history.
• Canonical docs also distinguish durable molecules from ephemeral wisps. We do not need full wisp parity on day one, but we should avoid baking in assumptions that every run is permanently durable.

Current state in cloud

• We already have a partial molecule implementation in cloudflare-gastown, but it is narrower than the issue body implies. Today the closest equivalents are: formula = JSON payload embedded in molecule metadata, molecule = parent bead with type='molecule', steps = child beads, progression = derived from child bead status/dependency order.
• cloudflare-gastown/src/dos/town/review-queue.ts has real lifecycle logic (createMolecule, getMoleculeCurrentStep, advanceMoleculeStep), and the plugin tools expose gt_mol_current / gt_mol_advance. So this is no longer just “future architecture”; there is already a real execution surface.
• The current model is bead-centric, not workflow-run-centric. There is no first-class definition registry, no explicit run object with inputs/outputs/transitions/retries, and no graph authoring model beyond sequential child-bead creation.
• The UI has promising pieces (src/components/gastown/MoleculeStepper.tsx, FormulaLibrary), but I did not find a fully wired end-user product around authoring, versioning, browsing, instantiation, and inspection.
• There is also architectural drift: some planning docs still describe molecules as mostly conceptual/schema-only, while the active Town DO code already implements a lightweight runtime.
• There is an immediate implementation bug/risk in the current create flow: the API accepts formula: { steps: [...] }, but createMolecule() currently treats formula as an array and falls back to [] for non-arrays. That means valid caller input can produce an empty molecule.

Gap analysis versus canonical Gastown/Gascity

1. Definition layer gap

• Canonical: formulas are first-class reusable definitions with identity, versioning, variables, and eventually layered resolution / registry semantics.
• Current: formula is embedded instance data, not a reusable first-class object.

2. Runtime layer gap

• Canonical: molecule is a durable workflow instance with explicit step state, readiness, advancement, and audit semantics.
• Current: runtime state is inferred from generic bead status and child ordering. This works for simple linear flows but is not yet a full execution model.

3. Graph/modeling gap

• Canonical: step dependencies are part of the authored definition, and richer formula docs anticipate composition, variables, and graph structure.
• Current: we effectively support linear chains. There is no first-class DAG/branching/condition model yet.

4. UX/mental-model gap

• Canonical users expect “show me the formula”, “instantiate it”, “what step is current”, “what steps are ready”, and “advance the molecule”.
• Current product language is overloaded with generic “workflow” terminology that already means several other things in cloud. Without an explicit naming bridge, Gastown-native users will not know which object maps to formula vs molecule vs run.

5. Lifecycle/portability gap

• Canonical workflows are designed around durable execution that survives session churn/handoffs, while also preserving a distinction between durable molecules and ephemeral wisps.
• Current implementation has durable bead state, which is a good base, but lacks an explicit portability story for ephemeral runs, summaries/digests, and template reuse.

Recommended implementation plan

Phase 0 — stabilize the existing molecule substrate before adding a visual builder
Goal: make the current runtime legible and correct before we add more surface area.

• Fix the formula shape mismatch in molecule creation so definition input and runtime creation agree.
• Decide and document the canonical internal mapping: formula = definition, molecule = run instance, step bead = runtime step/task.
• Persist step advancement summaries / outputs in a durable way instead of discarding them in advanceMoleculeStep.
• Add tests around creation, current-step lookup, advancement, dependency handling, and completion semantics so we stop accumulating drift.
• Audit stale schema/docs (rig_molecules table, older bead enums, proposal docs) and either remove them or explicitly mark them as superseded.

Phase 1 — introduce first-class workflow definitions
Goal: separate authored definitions from runtime instances.

• Create a first-class workflow-definition entity in cloud/Gastown, with canonical aliasing in product copy: primary label can be Workflow Definition if desired, but it should explicitly mention Formula.
• Definition schema should at minimum support: name, description, version/revision, variables/inputs, steps, dependencies, optional tags/capabilities, and durability mode (durable now, ephemeral ready for future wisps).
• Keep the initial schema intentionally smaller than the full canonical formula reference, but make sure it can evolve without migration pain into conditions/composition/registry metadata.
• Add CRUD, list/show, and “instantiate definition” APIs. This is the minimum needed to make the system feel canonical.

Phase 2 — promote molecule runs to a first-class runtime model
Goal: stop treating execution as only incidental bead relationships.

• Introduce a first-class run/molecule record that points back to a definition revision and captures instantiation inputs, status, timestamps, and summary.
• Keep beads as the execution substrate for step work, but make the molecule/run object the explicit owner of runtime state rather than deriving everything ad hoc.
• Add per-step runtime records or richer step metadata capturing status, started/completed timestamps, assigned agent, summary/output, and dependency readiness.
• Preserve compatibility with the existing hook/gt_mol_current/gt_mol_advance loop. Those semantics are a feature, not technical debt.
• Explicitly distinguish “definition graph” from “run state projection” in the API/UI so we can render both cleanly.

Phase 3 — expand from linear checklists to a graph-backed workflow model
Goal: earn the DAG editor rather than starting with it.

• Support authored dependencies as a graph, not just sequential next-step chains.
• MVP graph features should be: multiple prerequisites, multiple ready nodes, branch-on-status, and optional/manual convergence rules. I would avoid arbitrary scripting conditions in the first cut.
• Execution engine should compute readiness from dependency closure, then surface current/ready steps in both API and UI.
• Represent this graph in a way that can still compile down to bead-based execution. In other words: the graph is the definition model; beads remain the durable work execution primitives.
• Once graph semantics exist in the backend, then layer a visual editor on top. React Flow is still a good UI candidate, but it should render an already-coherent definition model rather than becoming the source of truth.

Phase 4 — build the product UX around canonical compatibility
Goal: make the system understandable to both Gastown-native and cloud-native users.

• Add a definitions library page with explicit mapping language, e.g. “Workflow Definitions (Formulas)”.
• Add a run detail page that clearly shows: source definition, inputs, status, current step, ready steps, completed steps, and final summary/digest.
• Add an execution-centric operator view optimized for the existing agent loop (current molecule, advance, history) plus a separate authoring view for creating/editing definitions.
• Keep canonical nouns visible in docs/tooltips/API docs even if we also expose friendlier product language. Recommended mapping:
  • Formula -> Workflow Definition
  • Molecule -> Workflow Run (Molecule)
  • Step bead -> Run Step / Task
  • Wisp -> Ephemeral Run
  • Digest -> Run Summary
• Avoid using bare workflow as the only object name in APIs where we actually mean definition or run. That ambiguity will compound quickly.

Phase 5 — scheduling, events, and external triggers
Goal: add automation-platform features on top of the canonical core, not instead of it.

• After definitions + runs + graph semantics exist, add trigger types: manual, event-driven, schedule, webhook.
• Model triggers as ways to instantiate a formula into a molecule/run, not as a separate workflow system. This keeps the architecture coherent.
• Scheduled/event/webhook execution can then produce the same run objects and step audit trail as manual instantiation, which keeps compatibility and observability aligned.
• Re-evaluate whether triggers live in Town DO or a dedicated Workflow DO after we have a clearer runtime model. Right now the Town DO already owns the bead/molecule substrate, so splitting too early could create awkward dual sources of truth.

Phase 6 — advanced canonical alignment / “more than Gastown” features
Goal: extend beyond canonical parity without breaking recognizability.

• Add definition versioning and immutable revisions so runs always point to the exact definition snapshot they were instantiated from.
• Add import/export and eventually layered resolution/registry semantics if we want Mol Mall–style sharing/installation.
• Add ephemeral-run support as the product analogue to wisps for recurring patrol/automation loops that do not need full long-term retention.
• Add composition only after the basics are stable. Canonical docs mention extends / composition, but I would not make that part of the MVP.

Naming and mental-model compatibility notes

• The safest approach is not to hide canonical terms; it is to dual-label them.
• Recommendation: use cloud-friendly labels in the UI, but preserve Gastown aliases in docs/tooltips/API descriptions. Example: “Create Workflow Definition (Formula)” and “Run Details (Molecule)”.
• Workflow by itself is too overloaded in this repo. We should reserve it for the umbrella product area and use definition vs run explicitly in the data model and API names.
• Beads remain an excellent low-level execution primitive and do not need to be hidden. For Gastown users, “a molecule run materializes into step beads” is a very natural explanation.
• If we eventually ship a visual DAG builder, the editor should edit the definition/formula, not the run. The run UI should be a separate execution monitor.

Key risks / open questions

• Backend-first vs UI-first: starting with React Flow before definition/run semantics are settled will likely produce a pretty editor backed by an unstable model.
• Single substrate vs separate WorkflowDO: a dedicated DO may become attractive for triggers/schedulers, but introducing it before we decide what the canonical runtime object is could increase drift.
• Scope creep: conditions, scripts, HTTP nodes, Mayor nodes, convoy nodes, schedules, webhooks, and templates are all valuable, but they are downstream of getting definition/run semantics right.
• Linear-to-graph migration: we should decide whether existing molecule payloads are upgraded into a graph shape or treated as legacy sequential definitions.
• Ephemeral runs: canonical wisps are conceptually important, but likely a second-wave feature unless we have an immediate product need.

Recommended sequencing

1. Fix and harden the existing molecule runtime.
2. Introduce first-class definitions and explicit runs.
3. Add graph semantics in the backend.
4. Build authoring and run-inspection UX around that model.
5. Add triggers/scheduling/webhooks.
6. Add sharing/versioning/ephemeral-run/composition features.

If we sequence it this way, someone coming from canonical Gastown will recognize the model immediately, while cloud still gets room to grow into a broader automation product without losing the formula/molecule mental model underneath.

[jrf0110]

Correction to my earlier framing: I still think the canonical formula/molecule model is the right product target, but I gave too much weight to the half-implemented molecule internals that already exist in cloud. After a second pass, I think we should treat the existing molecule/formula implementation as disposable legacy unless a specific piece is proven useful during extraction.

Why I think that now:

• The current runtime is real enough to create constraints, but not mature enough to preserve. createMolecule() in cloudflare-gastown/src/dos/town/review-queue.ts only handles formula as a raw array, while the HTTP handler already accepts formula: { steps: [...] }, so valid input can produce an empty molecule.
• advanceMoleculeStep() discards the provided summary instead of persisting step output/history.
• The active runtime is effectively "molecule bead + child step beads + derived current index". That is useful as a proof that beads can host execution, but not a foundation worth designing around.
• rig_molecules and older planning docs now look like stale architecture drift, not a compatibility boundary.
• The UI pieces (MoleculeStepper, FormulaLibrary) are presentation fragments, not evidence of a settled backend model.

Updated recommendation: optimize for greenfield delivery, not compatibility with abandoned internals.

Delete/replace boundary

• Safe to delete/replace: current molecule creation/advance internals, any stale rig_molecules assumptions, proposal text that describes molecules as schema-only or otherwise contradicts the live runtime, and any API/UI naming built around the current ad hoc shape.
• Safe to preserve conceptually, not structurally: the user-facing nouns formula, molecule, step, the agent-loop affordances behind gt_mol_current / gt_mol_advance, and the fact that beads are a good execution substrate for durable step work.
• Presume all current molecule storage/layout is replaceable unless we explicitly decide to keep a narrow compatibility shim for existing tool calls.

Greenfield plan

1. Define the canonical model first

• formula = authored reusable definition
• molecule = instantiated durable run of a formula revision
• step run = per-step runtime state for a molecule
• beads = one execution mechanism for durable work steps, not the entire workflow model

2. Build first-class definition and run objects before any visual editor

• Definitions need identity, revisioning, inputs, steps, dependencies, and durability mode.
• Runs need source definition revision, instantiated inputs, lifecycle status, per-step status/history, summary/digest, and timestamps.
• The graph definition should be its own source of truth; UI and execution both read from it.

3. Keep a thin compatibility bridge for agent ergonomics

• Preserve gt_mol_current / gt_mol_advance semantics, but back them with the new run model.
• Preserve Gastown/Gascity conceptual compatibility in docs/UI copy by dual-labeling: Workflow Definition (Formula), Workflow Run (Molecule).
• Do not preserve the current storage shape just because the names already exist.

4. Compile durable steps onto beads where that helps execution

• If a step needs assignment, audit trail, hook state, or inter-agent coordination, materialize it as a bead/task.
• Do not make "bead parent/child layout" the canonical runtime representation. That should be an implementation detail of the execution layer.

5. Add graph semantics in the backend before React Flow

• Dependencies, readiness, multiple ready nodes, and completion history need to exist server-side first.
• React Flow should edit/render a coherent definition model, not become the source of truth.

Recommended sequencing

• Phase 0: explicitly mark the current molecule internals as legacy, then decide what to delete immediately versus temporarily shim.
• Phase 1: define the new persisted model for formula definitions, molecule runs, and step runs.
• Phase 2: reimplement gt_mol_current / gt_mol_advance on top of that model.
• Phase 3: attach bead execution only where needed for durable step work.
• Phase 4: build definition library + run detail views.
• Phase 5: add graph authoring UI, then schedules/events/webhooks as run triggers.

Main risk

• The biggest risk is trying to evolve the current bead-centric molecule implementation into the final workflow architecture. That path will preserve accidental constraints, increase migration complexity, and still not give us a clean definition/run split.

Immediate next steps

• Inventory all live references to current molecule internals and classify them as keep/shim/delete.
• Write the new canonical schema/API design for formula definitions, molecule runs, and step runs.
• Decide whether gt_mol_* stays as a compatibility facade from day one of the rewrite.
• Remove or mark stale legacy artifacts (rig_molecules, outdated proposal sections, inconsistent create payload assumptions) so the implementation team is not designing against ghosts.

Net: we should preserve canonical Gastown/Gascity concepts for users, but we should not let the abandoned in-repo molecule implementation constrain the rebuild. Treat the old internals as disposable legacy and rebuild the workflow stack around a clean definition/run model.

[jrf0110]

Architecture Review — Critical Findings

A follow-up review of the revised issue identified several significant gaps. These should be addressed before implementation begins.

P0 — Must Fix

1. Instance model should be one WorkflowDO per town, not per definition.
One-per-definition means TownDO must fan out RPC calls to potentially dozens of WorkflowDOs per event (~5-10ms each). With one-per-town, event matching is a local SQLite query. The routing problem (tRPC needs to find the right WorkflowDO from a townId) is trivial with one-per-town (getWorkflowDOStub(env, townId)), but requires a lookup table with one-per-definition.

2. Event delivery from TownDO → WorkflowDO is unreliable.
Cross-DO RPC is fire-and-forget. If the RPC fails or either DO is evicted between the event and the notification, the workflow step stays waiting forever. Need a durable outbox pattern (like town_events for the reconciler) or WorkflowDO polling.

3. Alarm loop must not do blocking I/O.
The current design runs node execution (Mayor Prompts, HTTP calls) synchronously within the alarm tick. Cloudflare DOs have a 30-second execution limit per alarm invocation. A single slow Mayor Prompt blocks the entire alarm. Node execution should be fire-and-forget with callback-based resumption.

4. Diamond pattern failure handling.
If branch B completes and branch C fails in a diamond (B→D, C→D), node D is skipped under the current algorithm. There's no "continue on failure" option. Need on_failure: 'skip' | 'continue' | 'fail_run' per edge/node.

P1 — Should Fix

5. Schema missing last_run_at. The cron pseudocode references def.last_run_at but the schema only has last_run_id and last_run_status.

6. No revision history storage. revision field increments but only the current graph is stored. Need a workflow_definition_revisions table if "view revision history" is a feature.

7. Visual layout leaks into execution graph. React Flow position data is stored alongside execution-relevant fields. Separate layout from definition to avoid spurious revision bumps on auto-layout.

8. Effort estimates should roughly double. The reconciler (simpler scope) took ~3 weeks. This proposal (new DO + DAG engine + React Flow editor + cron + 15 node types + cross-DO RPC + tRPC API + run visualization) is realistically 8-10 weeks, not 5-6.

9. Permissions model missing. Who can create/edit/enable/trigger workflows? Can webhook triggers (unauthenticated) rack up costs?

10. Billing/rate limiting missing. Cron workflow running every minute with Mayor Prompt = thousands of LLM tokens/hour. Need per-tier run count limits, step execution limits, LLM token budgets.

P2 — Nice to Fix

11. Cron catch-up policy: Skip missed ticks on DO re-wake (don't run 4 hours of backlog).

12. Auto-save + validation conflict: Auto-save should save a draft, not trigger validation. Explicit Save validates and promotes to new revision.

13. Template interpolation security: {{step.X.output}} in HTTP URL templates could exfiltrate data. Need URL allowlists or sandboxing.

14. action_script shares the agent container. Security and resource contention concerns. Needs its own container strategy or explicit scoping.

15. Timezone defined in two places (definition-level and trigger config). Pick one.

Realistic MVP (2 weeks)

Strip to: WorkflowDO skeleton, manual trigger only, 3 node types (trigger_manual, action_sling_bead, control_condition), linear execution (no parallel), form-based editor (not React Flow), run list with status. React Flow, cron, events, and wait nodes are each their own phase after the MVP.

[jrf0110]

Final Architecture Review — Round 3

Critical (5 items)

1. Cross-DO SQL access is impossible. The alarm pseudocode shows WorkflowDO running SELECT * FROM workflow_notifications — but that table is in TownDO's SQLite. DOs have isolated storage. Need an explicit RPC: townStub.drainWorkflowNotifications() that returns rows AND marks them processed atomically. WorkflowDO writes them into its own workflow_events table for durable local replay.

2. WORKFLOW DO binding not fully specified. Need to add to wrangler.jsonc (both prod and dev), update worker-configuration.d.ts Env interface, add getWorkflowDOStub helper, export WorkflowDO from gastown.worker.ts. Both TownDO and WorkflowDO need each other's bindings (circular reference is fine in same Worker, but must be explicit).

3. action_sling_bead has no idempotency. If slingBead() RPC succeeds but WorkflowDO is evicted before recording the result, retry creates a duplicate bead. Need a step_run_id idempotency key passed to slingBead, with TownDO deduplicating.

4. control_condition expression language is undefined. What language? What context vars? What security model? This is in the Phase 1 MVP but has zero spec. Either remove from MVP (make it truly linear) or specify a simple comparator DSL ({{step.X.output.field}} == "value").

5. MVP says "linear execution" but includes control_condition (branching). Contradiction. Either MVP is truly linear (2 node types + no conditions) or MVP supports exclusive branching (not parallel). Clarify.

Significant (8 items)

6. EdgeCondition type referenced but never defined.
7. Schema uses raw SQL strings, not the Zod getTableFromZodSchema pattern per AGENTS.md.
8. (Combined with 7)
9. No Zod Record schemas shown — implementers need the pattern specified or an explicit "follow beads.table.ts" reference.
10. ping() RPC to wake WorkflowDO only works when the DO is idle — if alarm is already executing, setAlarm() is a no-op until current execution completes. Document this nuance.
11. Draft model (draft_graph/draft_layout) is ambiguous — is it columns or a separate table? No schema defined.
12. action_mayor_prompt async response mechanism undefined — sendMayorMessage is designed for streaming WebSocket, not fire-and-wait. Needs a separate pattern.
13. action_http allowed_domains should be required, not optional — SSRF risk with cloud metadata endpoints.

Moderate (9 items)

14. shouldFireCron pseudocode: nextTick > now is always true (no-op check).
15. workflow_runs missing created_at column (can't measure queue time).
16. No FOREIGN KEY constraints between workflow tables (inconsistent with beads table pattern). Also: CHECK constraints are used but beads.table.ts explicitly omits them.
17. durability column has no runtime effect in any phase — dead column on ship.
18. Phase 2 scope (event triggers + cron + parallel execution + billing + permissions) is too large for 2-3 weeks.
19. Webhook endpoint is HTTP, not tRPC — must be added to gastown.worker.ts routes per AGENTS.md.
20. React Flow version unspecified (v11 vs v12 API break). Bundle should be lazy-loaded (~150KB gzipped).
21. Zero testing strategy across all phases.
22. Step retry logic underspecified: no max retries, no backoff formula, no exhaustion behavior.
23. variables_schema uses JSON Schema but codebase uses Zod exclusively — tooling mismatch.

Recommendations

The issue is comprehensive and well-structured. The architectural direction (one WorkflowDO per town, durable outbox, async execution) is sound. The remaining issues are primarily:

1. Specify the RPC contract for cross-DO notification drain (refactor(bot): Extract platform-agnostic tool system #1)
2. Remove control_condition from MVP or fully specify the expression language (AppBuilder - Fix model selector not showing saved model on reload #4, Cloud Agent: prompt autocomplete (ghost text) #5)
3. Add idempotency keys to side effects (App Builder - Add session-based message pagination #3)
4. Follow AGENTS.md conventions for schema definition (App Builder - Unit and Integration tests #7, feat(share): implement shared session page with database integration #9)

Items #6-23 can be addressed during implementation without blocking the start.