# Trigger Composition: Triggers, Schedules, and Workflows

## Overview

Three automation primitives exist in the platform: **triggers** (event-driven), **schedules**
(time-driven), and **workflows** (multi-step state machines). This document defines how they
compose without creating circular dependencies.

## Composition Rules

### Triggers can start workflows

A trigger's Starlark handler may call `workflow.start(workflow_id, data)` to create a new
workflow instance. This is the primary entry point for event-driven workflow initiation.

Example: a `ticket.created` trigger fires and starts an approval workflow.

### Schedules can start workflows

A schedule's Starlark handler may also call `workflow.start(...)`. This enables time-based
batch processing workflows.

Example: a daily 9am schedule starts a standup collection workflow.

### Workflows emit events that triggers listen to

Workflow lifecycle events (`workflow.started`, `workflow.advanced`, `workflow.completed`,
`workflow.signoff`, etc.) are published on the event bus. Triggers may subscribe to these
events to perform side effects (notifications, external API calls, audit logging).

### Workflows cannot start triggers or schedules

Workflows do not directly invoke triggers or create schedules. Workflow Starlark hooks
operate within the workflow's own context and do not have access to trigger/schedule
management APIs. This prevents uncontrolled fan-out.

## Circular Invocation Guard

The automated stage cycle guard (max 10 consecutive automated stages) already prevents
infinite loops within a single workflow. Cross-workflow cycles are prevented by this rule:

**A workflow event handler (trigger) may start a new workflow instance, but the new instance
is not processed synchronously.** It enters the work queue as a separate execution context.
The bus does not re-enter the originating workflow's advance call.

This means:
- `workflow.completed` trigger → `workflow.start(B)` is allowed (async).
- Workflow A automated stage → `workflow.start(B)` where B immediately completes and
  triggers A again → allowed but rate-limited by the cycle guard on each individual workflow.

## Not Supported (by design)

- Triggers cannot modify a running workflow instance (read-only access via Starlark builtins).
- Schedules cannot advance or cancel workflow instances directly.
- Workflows cannot create, modify, or delete triggers or schedules.

These restrictions keep the composition model simple and auditable.