Workflow Execution

Purpose and authority boundary

Workflow Execution records what happened to planned nodes without adding mutable status to the compiled Workflow. It owns execution authority policy, the journal header, canonical transition events, attempts, replay, invalidation propagation, and successor binding. It does not own Screening or Full Text decisions, scheduler behavior, storage, plugin execution, or model execution.

Separation: Workflow owns the immutable DAG; WorkflowExecution owns the transition journal; conduct modules own scientific decisions; Provenance receives an outward projection. A completed execution node proves that a valid record was referenced—not that the external work was scientifically correct.

Closed state machine

pending ──dependencies-satisfied──→ ready
ready ──work-started──────────────→ active
active ──work-blocked─────────────→ blocked
blocked ──block-cleared───────────→ active
active ──work-completed───────────→ completed
active ──work-failed──────────────→ failed
failed ──retry-authorized─────────→ ready

pending | ready | active | blocked | completed | failed
  └─ work-invalidated → invalidated ──successor-bound→ superseded

Root DAG nodes begin ready; nodes with predecessors begin pending. A dependency transition requires every predecessor to be completed and current. No transition outside the table is admitted. Invalidated and superseded nodes never resume in the same execution.

Key types and services

• WorkflowExecutionAuthorityPolicy binds one execution scope, verified Workflow/Protocol, immutable actor-role assignments, and a human approver.
• WorkflowExecutionHeader binds the execution id, policy, workflow, protocol, node set, creating human, and chain-root digest.
• WorkflowExecutionEvent binds ordinal, prior head, request identity, node, prior/result states, actor, time, rationale, attempt, record references, approvals, errors, and invalidation/successor data.
• WorkflowExecutionJournal validates append commands, idempotency, optimistic concurrency, graph constraints, authority, outputs, invalidation closure, and replay.
• WorkflowExecutionProjection derives current node states and complete attempt history; it is not separately persisted scientific authority.
• WorkflowExecutionCanonicalCodec strictly rehydrates canonical records against a verified Workflow and IWorkflowExecutionRecordResolver.

Source: NexusScholar.WorkflowExecution. Accepted design: ADR 0030.

Hash chain, requests, and concurrency

The header digest is the chain root. Event one names it as PreviousDigest; later events name the immediately preceding event. Ordinals are one-based and contiguous. Event digest covers the full record. Removal, reordering, insertion, duplication, or cross-execution splicing therefore fails replay.

Every command supplies the expected current head and prior node state. A stale writer is rejected instead of rebased. RequestDigest is computed over the stable request content, while event time belongs to the resulting record. Repeating the same request id and digest is idempotent; reusing the id with different content is a conflict.

Attempts, people, approvals, and outputs

work-started, completion, and failure bind an attempt id and sequence. A retry appends a new attempt after explicit authorization; it never replaces failure history. Completion must include stable kind/id/digest references matching every artifact declared by the compiled node. Paths are never execution evidence identity.

Automated nodes may be performed by automation. Human and hybrid tasks require an actor and role admitted by both compiled gate/approval definitions and the digest-bound authority policy. Human-task completion must bind the owning conduct record. Approval nodes additionally enforce minimum count, required roles, distinct actors where configured, and human-only approval records.

Invalidation and successor execution

An invalidation binds an independently resolvable source record and the workflow invalidation-policy reference. The journal computes the full affected descendant closure and appends one ordered event per node; a partial batch is rejected because it would leave dependent work appearing current. A successor execution can be bound only after affected predecessor nodes are invalidated, producing superseded terminal state.

Typical developer flow

1. Resolve a VerifiedWorkflowDefinition and create a human-approved execution authority policy.
2. Create a header and journal; retain the header digest as the initial expected head.
3. Preview a transition against the current projection and expected state.
4. Construct stable input/output/conduct references through a resolver; append the event.
5. Persist canonical header/events atomically in order; do not persist projection as authority.
6. After restart, strictly rehydrate and replay the complete chain to reproduce states and head digest.

Failure and refusal behavior

Stable categories reject unverified authority, unknown nodes, dependency gaps, invalid transitions/attempts, stale heads, broken chains, forged roles, automation claiming human authority, missing declared outputs, invalid approvals, conflicting requests, partial invalidation, and bad successor binding. Canonical codecs reject unknown fields, noncanonical bytes, altered digests, gaps, and cross-journal records.

Tests, bridges, and nonclaims

WorkflowExecutionFixtureTests and the FE-03 fixture pack exercise replay and adversarial transitions. FE-03 completion evidence records focused validation.

NexusScholar.WorkflowExecution.Provenance projects accepted events outward; NexusScholar.Screening.WorkflowExecution binds conduct completion without reversing dependencies. The package provides no scheduler, queue, database, API, distributed lock, plugin host, AI runner, or guarantee of external side effects. A standalone CLI mutation remains outside the accepted authority path until durable verified Workflow resolution is available.