execution.mdx

title	Execution
description	Execution protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Automation Execution Protocol

Defines schemas for execution logging, error tracking, checkpointing,

concurrency control, and scheduled execution persistence.

Industry alignment: Salesforce Flow Interviews, Temporal Workflow History,

AWS Step Functions execution logs.

**Source:** `packages/spec/src/automation/execution.zod.ts`

TypeScript Usage

import { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog, ScheduleState } from '@objectstack/spec/automation';
import type { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog, ScheduleState } from '@objectstack/spec/automation';

// Validate data
const result = Checkpoint.parse(data);

---

Checkpoint

Properties

Property	Type	Required	Description
id	string	✅	Checkpoint ID
executionId	string	✅	Parent execution ID
flowName	string	✅	Flow machine name
currentNodeId	string	✅	Node ID where execution is paused
variables	Record<string, any>	✅	Flow variable state at checkpoint
completedNodeIds	string[]	✅	List of node IDs already executed
createdAt	string	✅	Checkpoint creation timestamp
expiresAt	string	optional	Checkpoint expiration (auto-cleanup)
reason	Enum<'wait' | 'screen_input' | 'approval' | 'error' | 'manual_pause' | 'parallel_join' | 'boundary_event'>	✅	Why the execution was checkpointed

---

ConcurrencyPolicy

Properties

Property	Type	Required	Description
maxConcurrent	integer	✅	Maximum number of concurrent executions allowed
onConflict	Enum<'queue' | 'reject' | 'cancel_existing'>	✅	queue = enqueue for later, reject = fail immediately, cancel_existing = stop running instance
lockScope	Enum<'global' | 'per_record' | 'per_user'>	✅	Scope of the concurrency lock
queueTimeoutMs	integer	optional	Maximum time to wait in queue before timing out (ms)

---

ExecutionError

Properties

Property	Type	Required	Description
id	string	✅	Error record ID
executionId	string	✅	Parent execution ID
nodeId	string	optional	Node where the error occurred
severity	Enum<'warning' | 'error' | 'critical'>	✅	Error severity level
code	string	✅	Machine-readable error code
message	string	✅	Human-readable error message
stack	string	optional	Stack trace for debugging
context	Record<string, any>	optional	Additional diagnostic context (input data, config snapshot)
timestamp	string	✅	When the error occurred
retryable	boolean	✅	Whether this error can be retried
resolvedAt	string	optional	When the error was resolved (e.g., after successful retry)

---

ExecutionErrorSeverity

Allowed Values

• warning
• error
• critical

---

ExecutionLog

Properties

Property	Type	Required	Description
id	string	✅	Execution instance ID
flowName	string	✅	Machine name of the executed flow
flowVersion	integer	optional	Version of the flow that was executed
status	Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>	✅	Current execution status
trigger	{ type: string; recordId?: string; object?: string; userId?: string; … }	✅	What triggered this execution
steps	{ nodeId: string; nodeType: string; nodeLabel?: string; status: Enum<'success' | 'failure' | 'skipped'>; … }[]	✅	Ordered list of executed steps
variables	Record<string, any>	optional	Final state of flow variables
startedAt	string	✅	Execution start timestamp
completedAt	string	optional	Execution completion timestamp
durationMs	integer	optional	Total execution duration in milliseconds
runAs	Enum<'system' | 'user'>	optional	Execution context identity
tenantId	string	optional	Tenant ID for multi-tenant isolation

---

ExecutionStatus

Allowed Values

• pending
• running
• paused
• completed
• failed
• cancelled
• timed_out
• retrying

---

ExecutionStepLog

Properties

Property	Type	Required	Description
nodeId	string	✅	Node ID that was executed
nodeType	string	✅	Node action type (e.g., "decision", "http")
nodeLabel	string	optional	Human-readable node label
status	Enum<'success' | 'failure' | 'skipped'>	✅	Step execution result
startedAt	string	✅	When the step started
completedAt	string	optional	When the step completed
durationMs	integer	optional	Step execution duration in milliseconds
input	Record<string, any>	optional	Input data passed to the node
output	Record<string, any>	optional	Output data produced by the node
error	{ code: string; message: string; stack?: string }	optional	Error details if step failed
retryAttempt	integer	optional	Retry attempt number (0 = first try)
parentNodeId	string	optional	Enclosing structured-region container node ID (loop/parallel/try_catch)
iteration	integer	optional	Zero-based loop iteration or parallel branch index of the enclosing region
regionKind	string	optional	Region kind the step ran in: loop-body | parallel-branch | try | catch

---

ScheduleState

Properties

Property	Type	Required	Description
id	string	✅	Schedule instance ID
flowName	string	✅	Flow machine name
cronExpression	string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }	✅	Cron expression — cron0 9 * * MON-FRI
timezone	string	optional	IANA timezone for cron evaluation
status	Enum<'active' | 'paused' | 'disabled' | 'expired'>	optional	Current schedule status
nextRunAt	string	optional	Next scheduled execution timestamp
lastRunAt	string	optional	Last execution timestamp
lastExecutionId	string	optional	Execution ID of the last run
lastRunStatus	Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>	optional	Status of the last run
totalRuns	integer	optional	Total number of executions
consecutiveFailures	integer	optional	Consecutive failed executions
startDate	string	optional	Schedule effective start date
endDate	string	optional	Schedule expiration date
maxRuns	integer	optional	Maximum total executions before auto-disable
createdAt	string	✅	Schedule creation timestamp
updatedAt	string	optional	Last update timestamp
createdBy	string	optional	User who created the schedule

---