GLYPH Workflows

Provider-agnostic workflow orchestration for the GLYPH platform. The package validates directed acyclic workflows, plans parallel execution layers, normalizes triggers, pauses at approval gates, executes through injected @glyph-platform/core connector contracts, emits typed lifecycle events, records audit history, and enforces deterministic state transitions.

It contains no provider or application-specific implementation.

Lifecycle

draft → validated → queued → running
                              ├─→ waiting_approval → executing
                              └─→ executing
                                      ├─→ running (next plan layer)
                                      ├─→ completed
                                      ├─→ failed
                                      └─→ cancelled

completed, failed, and cancelled are terminal states. Invalid transitions throw InvalidStateTransitionError.

Core concepts

• Planner validates IDs, actions, dependencies, cycles, and retry settings.
• DependencyGraph builds stable topological layers.
• ExecutionPlanner marks layers containing independent steps as parallel.
• TriggerResolver supports manual, voice, API, event, and schedule signals.
• ApprovalGate evaluates injected policy and stores explicit grants.
• WorkflowExecutor maps a step into ConnectorActionRequest and consumes ConnectorActionResult; connector implementations are injected.
• WorkflowRuntime executes plan layers, pauses safely, retries retryable failures, emits events, and records outcomes.
• WorkflowEngine owns instance lifecycle and orchestration.

Example

import {
  ApprovalGate,
  AuditLogger,
  DefinitionApprovalPolicy,
  EventBus,
  ExecutionPlanner,
  Planner,
  StateMachine,
  WorkflowEngine,
  WorkflowExecutor,
  WorkflowRuntime,
} from "@glyph-platform/workflows";

const events = new EventBus();
const audit = new AuditLogger();
const approvals = new ApprovalGate(new DefinitionApprovalPolicy());
const state = new StateMachine();
const executor = new WorkflowExecutor({
  async execute(request) {
    return {
      ok: true,
      data: { acceptedCapability: request.capabilityId },
      audit: {
        connectorId: request.connectorId,
        capabilityId: request.capabilityId,
        actorId: request.context.actorId,
        profileId: request.context.profileId,
        correlationId: request.context.correlationId,
        completedAt: new Date().toISOString(),
      },
    };
  },
});
const runtime = new WorkflowRuntime(
  executor,
  approvals,
  state,
  events,
  audit,
);
const engine = new WorkflowEngine(
  new ExecutionPlanner(new Planner()),
  runtime,
  approvals,
  state,
  events,
  audit,
);

Create a definition, call create, validate, queue, and start. If the result is waiting_approval, call approve(instanceId, stepId, actorId) to resume execution.

Extension boundaries

All infrastructure is dependency-injected:

• connector execution
• approval policy
• event handlers
• audit sink
• clock and identifier generation
• schedule expression matcher

Adapters may implement those interfaces in other repositories. Provider names, SDKs, credentials, transport clients, and business rules do not belong here.

Development

npm ci
npm run typecheck
npm test
npm run test:coverage
npm run build