execution.mdx

title	Execution
description	Execution protocol schemas

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

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 } from '@objectstack/spec/automation';
import type { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog } 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	Object	✅	What triggered this execution
steps	Object[]	✅	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	Object	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

---