Workflow compiler

Purpose and authority boundary

Workflow turns approved method intent into a reproducible plan of nodes, dependency edges, roles, gates, human approvals, capability requirements, artifacts, waivers, and invalidation policy. The output is VerifiedWorkflowDefinition. Runtime state belongs to Workflow Execution; provenance, scheduling, storage, plugin/model invocation, and UI state are deliberately outside this package.

Graph, not state machine: a compiled workflow is a DAG. An edge means “this node depends on that node.” Node progress and transitions are recorded by the separate execution journal.

Graph and compile model

VerifiedProtocolVersion + WorkflowTemplate + compile parameters
        ↓ validate authority, schemas, nodes, edges, gates, waivers
        ↓ reject cycles and dangling references
normalized WorkflowDefinition
        ├─ nodes: automated | human task | approval | export
        ├─ modes: automated | human | hybrid
        ├─ edges: directed dependencies
        ├─ resolved inputs and declared outputs
        └─ protocol/template/workflow digests

Cycles are rejected. Node, edge, input, artifact, role, gate, approval, capability, waiver, and invalidation references must resolve. Logical sets are normalized to deterministic order before the workflow digest is computed. A compiled definition never contains current execution status.

Key types and services

• WorkflowTemplate aggregates template inputs, nodes, edges, roles, gates, approval requirements, artifact declarations, capability requirements, waiver policy, and invalidation policy.
• WorkflowCompileInput carries the verified Protocol version plus compile parameters and supplemental authority.
• WorkflowCompiler performs authority, schema, graph, and reference closure and emits WorkflowDefinition.
• WorkflowCompiledNode and WorkflowCompiledEdge are the normalized graph; compiled approvals, capabilities, and artifacts remain separate typed records.
• WorkflowRehydrator and IWorkflowAuthorityResolver reconstruct authority from untrusted persisted claims and exact resolved Protocol/template inputs.
• VerifiedWorkflowDefinition.ResolvedTemplate exposes the digest-verified template so execution can enforce roles, gates, approval shape, and output declarations.
• RapidReviewProfileAuthority verifies an explicitly approved profile of declared shortcuts and consequences; it does not create a looser compiler.

Source: NexusScholar.Workflow. Contracts: ADR 0005, ADR 0006, and authority hardening in ADR 0018.

Deterministic identity and rehydration

The template digest identifies normalized template content. The workflow digest separately identifies the compiled plan and binds protocol id, version, content digest, template identity, compiler identity, resolved inputs, nodes, edges, approval/capability/artifact requirements, and invalidation plan. Caller-supplied template or Protocol digest text is never accepted as proof.

Persisted definitions enter as UnverifiedWorkflowDefinition. Rehydration resolves the authoritative approved Protocol and template, recompiles, checks all identity fields and the workflow digest, and only then returns a verified wrapper. This prevents a self-consistent forged payload from selecting its own authority.

Rapid Review profile

A verified Rapid Review profile is governed configuration layered over the strict Core contract. Each shortcut binds what is omitted or shortened, scientific consequence, mitigation, required disclosure, and verified human approval. The profile must match the exact Protocol and Workflow authorities. It cannot waive evidence identity, human authority, or audit history, and it does not silently alter a template digest.

Typical developer flow

1. Resolve a VerifiedProtocolVersion, including any verified waiver or amendment required by the plan.
2. Load a versioned WorkflowTemplate and explicit compile parameters.
3. Call WorkflowCompiler.Compile; handle stable rule categories rather than message text.
4. Persist the canonical definition, template, and bindings together.
5. At read time, use WorkflowRehydrator with an application-owned resolver.
6. Pass the verified definition to WorkflowExecution; never invent an execution from a workflow id alone.

Failure and refusal behavior

The compiler rejects draft/stale Protocol authority, invalid template or content digests, unresolved schema references, duplicate IDs, dangling edges, self-edges and cycles, invalid node modes, undeclared inputs/outputs, unknown roles, malformed gates, insufficient approval definitions, undeclared capabilities, unsupported waiver use, and incomplete amendment/invalidation witnesses. Rehydration rejects altered or reordered authority material, wrong resolver targets, stale supplemental records, and any definition that cannot be reproduced.

Tests, extension points, and nonclaims

WorkflowCompilerTests cover compilation, graph validation, authority, and ordering. WorkflowFixtureTests replay the workflow fixtures. RapidReviewProfileTests cover the governed FE-06 profile.

New workflow families extend the versioned template/schema surface and must retain deterministic compilation and explicit authority. This package is not a scheduler, job queue, plugin host, model runner, storage engine, UI framework, or claim that executing a graph produces scientifically correct work.