@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/runtime/workflow-v2-routing.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Routing of compiled workflow runs.
+ * Turns a step outcome into the next cursor: another step, a retry, or a pending verdict followed
+ * by the cleanup steps the run owes before it may close.
+ */
+import { AWAITING_FINALIZE, worseVerdict } from './workflow-v2-types.js';
+const VERDICTS = new Set(['PASS', 'FAIL', 'BLOCKED', 'CANCELLED', 'INCONCLUSIVE']);
+function targetRoute(slot, target, via, errorCode) {
+    const base = { slot, target, via, ...(errorCode ? { error_code: errorCode } : {}) };
+    if (VERDICTS.has(target)) {
+        return { ...base, kind: 'verdict', verdict: target };
+    }
+    if (target === 'stop') {
+        const verdict = slot === 'pass' ? 'PASS' : slot === 'fail' ? 'FAIL' : 'BLOCKED';
+        return { ...base, kind: 'verdict', verdict };
+    }
+    if (target === 'pause' || target === 'repair') {
+        return { ...base, kind: 'verdict', verdict: 'BLOCKED' };
+    }
+    return { ...base, kind: 'step' };
+}
+/**
+ * A route into a step that already ran `max_passes` times routes to FAIL instead, naming the
+ * step, its bound and its passes. `passes` are the run's `step_attempts`; the step being recorded
+ * has run `attempt` times. Without `passes`, as in an authoring preview, nothing is bounded.
+ */
+function boundedRoute(definition, step, attempt, route, passes) {
+    if (route.kind !== 'step' || passes === undefined)
+        return route;
+    const target = definition.steps.find((candidate) => candidate.id === route.target);
+    const bound = target?.max_passes;
+    if (!target || bound === undefined)
+        return route;
+    const done = target.id === step.id ? attempt : (passes[target.id] ?? 0);
+    if (done < bound)
+        return route;
+    return {
+        slot: route.slot,
+        kind: 'verdict',
+        target: 'FAIL',
+        verdict: 'FAIL',
+        via: 'max_passes',
+        ...(route.error_code ? { error_code: route.error_code } : {}),
+        exhausted: { step_id: target.id, max_passes: bound, passes: done },
+    };
+}
+/**
+ * Resolve the route of a step outcome. An error code consults `error_routes` first (a `retry`
+ * disposition repeats the step while `retry.max_attempts` allows), then the step's `retry.on_codes`,
+ * then `on.<slot>`. A route into a step whose `max_passes` are spent goes to FAIL (TASK-1024).
+ */
+export function resolveWorkflowRoute(definition, step, slot, attempt, errorCode, passes) {
+    const canRetry = attempt < step.retry.max_attempts;
+    if (errorCode) {
+        const errorRoute = definition.error_routes.find((route) => route.code === errorCode);
+        if (errorRoute?.disposition === 'retry' && canRetry) {
+            return { slot, kind: 'retry', target: step.id, via: 'error_route', error_code: errorCode };
+        }
+        if (step.retry.on_codes.some((code) => code === errorCode) && canRetry) {
+            return { slot, kind: 'retry', target: step.id, via: 'retry_policy', error_code: errorCode };
+        }
+        if (errorRoute) {
+            const routed = targetRoute(slot, errorRoute.target, 'error_route', errorCode);
+            return boundedRoute(definition, step, attempt, routed, passes);
+        }
+    }
+    return boundedRoute(definition, step, attempt, targetRoute(slot, step.on[slot], 'on', errorCode), passes);
+}
+/** Route of a human answer that maps directly to CANCELLED: the operator stops the run. */
+export function answerRoute(verdict) {
+    return { slot: 'fail', kind: 'verdict', target: verdict, verdict, via: 'answer' };
+}
+/**
+ * Cleanup steps the run owes: `kind: cleanup`, not yet completed, with at least one dependency that
+ * ran (has an output that is neither policy-denied nor skipped) and is not `read-only`. A skipped
+ * step changed nothing, so it owes no cleanup (BUG-144). Definition order decides the sequence.
+ */
+export function pendingCleanupSteps(definition, run) {
+    const outputs = run.outputs ?? {};
+    const completed = new Set(run.completed_step_ids ?? []);
+    const byId = new Map(definition.steps.map((step) => [step.id, step]));
+    return definition.steps.filter((step) => step.kind === 'cleanup' &&
+        !completed.has(step.id) &&
+        outputs[step.id]?.error_code !== 'POLICY_DENIED' &&
+        step.depends_on.some((dependency) => dependency in outputs &&
+            outputs[dependency]?.error_code !== 'POLICY_DENIED' &&
+            outputs[dependency]?.status !== 'skipped' &&
+            byId.get(dependency)?.side_effect !== 'read-only'));
+}
+/** Apply a routed step outcome to the run cursor. Version and timestamps stay with the caller. */
+export function advanceWorkflowCursor(definition, run, step, output, route) {
+    const outputs = { ...(run.outputs ?? {}), [step.id]: output };
+    const stepAttempts = { ...(run.step_attempts ?? {}), [step.id]: output.attempt };
+    const completed = (run.completed_step_ids ?? []).filter((id) => id !== step.id);
+    if (route.kind !== 'retry')
+        completed.push(step.id);
+    const next = {
+        ...run,
+        outputs,
+        step_attempts: stepAttempts,
+        completed_step_ids: completed,
+    };
+    if (route.kind === 'retry')
+        return { ...next, state: step.id };
+    const inCleanupPhase = run.pending_verdict !== null && run.pending_verdict !== undefined;
+    if (route.kind === 'step' && !inCleanupPhase)
+        return { ...next, state: route.target };
+    // In the cleanup phase a route into a step is ignored, so its spent bound changes nothing.
+    const bounded = route.via === 'max_passes' && inCleanupPhase;
+    const pendingVerdict = route.kind === 'verdict' && route.verdict && !bounded
+        ? worseVerdict(run.pending_verdict, route.verdict)
+        : (run.pending_verdict ?? 'INCONCLUSIVE');
+    const cleanup = pendingCleanupSteps(definition, next);
+    return {
+        ...next,
+        pending_verdict: pendingVerdict,
+        state: cleanup[0]?.id ?? AWAITING_FINALIZE,
+    };
+}
+//# sourceMappingURL=workflow-v2-routing.js.map

package/dist/runtime/workflow-v2-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-routing.js","sourceRoot":"","sources":["../../src/runtime/workflow-v2-routing.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workflow-v2-run-events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run events of v2 runs that move no cursor: step assignments here, step notes and revisions in
+ * their own modules. Each is a committed transition under the run lock, so the run's version
+ * moves, run.json changes and the event lands in events.jsonl, which is what a waiting agent
+ * watches (DEC-022).
+ * @see STORY-463
+ */
+import { z } from 'zod';
+import type { EvidenceFile } from './evidence.js';
+import type { ProcessEvent, ProcessRun, RuntimeActor } from './index.js';
+import { type WorkflowV2RunContext } from './workflow-v2-run.js';
+import { WorkflowParty } from './workflow-v2-types.js';
+/** Who writes a run event and when; the name is the signature, as on every v2 event. */
+export type WorkflowRunEventInput = Readonly<{
+    actor: RuntimeActor;
+    actorName?: string;
+    occurredAt?: string;
+}>;
+export type WorkflowRunEventApplication = Readonly<{
+    run: ProcessRun;
+    event: ProcessEvent;
+    evidenceFiles?: readonly EvidenceFile[];
+}>;
+/** The other party: an event written by one side is addressed to the other. */
+export declare function otherParty(actor: RuntimeActor): WorkflowParty;
+/** The run one event later, with nothing else changed. */
+export declare function bumpedRun(run: ProcessRun, occurredAt: string): ProcessRun;
+/** Commit one event that the builder derives from the current run and its events. */
+export declare function commitWorkflowRunEvent(context: WorkflowV2RunContext, runId: string, build: (run: ProcessRun, events: readonly ProcessEvent[]) => WorkflowRunEventApplication, options?: Readonly<{
+    checkManifest?: boolean;
+}>): Promise<ProcessRun>;
+export declare const WorkflowStepAssignment: z.ZodObject<{
+    step_id: z.ZodString;
+    to: z.ZodEnum<{
+        agent: "agent";
+        operator: "operator";
+    }>;
+}, z.core.$strip>;
+export type WorkflowStepAssignment = z.infer<typeof WorkflowStepAssignment>;
+/**
+ * Hand a step not yet recorded to the operator or the agent. The first assignment declares the
+ * run's mode, so from then on the party guard applies (DEC-023).
+ */
+export declare function applyStepAssignment(context: WorkflowV2RunContext, run: ProcessRun, assignment: WorkflowStepAssignment, input: WorkflowRunEventInput): WorkflowRunEventApplication;
+export declare function assignWorkflowRunStepV2(context: WorkflowV2RunContext, runId: string, assignment: WorkflowStepAssignment, input: WorkflowRunEventInput): Promise<ProcessRun>;
+//# sourceMappingURL=workflow-v2-run-events.d.ts.map

package/dist/runtime/workflow-v2-run-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-run-events.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-run-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAMzE,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAsB,MAAM,wBAAwB,CAAC;AAE3E,wFAAwF;AACxF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;IACpB,aAAa,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC,CAAC,CAAC;AAEH,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAE7D;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAEzE;AAED,qFAAqF;AACrF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,YAAY,EAAE,KAAK,2BAA2B,EACxF,OAAO,GAAE,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,CAAM,GAClD,OAAO,CAAC,UAAU,CAAC,CAkBrB;AAED,eAAO,MAAM,sBAAsB;;;;;;iBAGjC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE5E;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,sBAAsB,EAClC,KAAK,EAAE,qBAAqB,GAC3B,2BAA2B,CAgC7B;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,sBAAsB,EAClC,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAIrB"}

package/dist/runtime/workflow-v2-run-events.js

@@ -0,0 +1,85 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run events of v2 runs that move no cursor: step assignments here, step notes and revisions in
+ * their own modules. Each is a committed transition under the run lock, so the run's version
+ * moves, run.json changes and the event lands in events.jsonl, which is what a waiting agent
+ * watches (DEC-022).
+ * @see STORY-463
+ */
+import { z } from 'zod';
+import { workflowRunMode, workflowStepAssignee, workflowStepChannel, } from './workflow-v2-parties.js';
+import { assertCurrentManifest, isWorkflowV2Run, workflowV2Event, } from './workflow-v2-run.js';
+import { WorkflowParty, WorkflowRunV2Error } from './workflow-v2-types.js';
+/** The other party: an event written by one side is addressed to the other. */
+export function otherParty(actor) {
+    return actor === 'agent' ? 'operator' : 'agent';
+}
+/** The run one event later, with nothing else changed. */
+export function bumpedRun(run, occurredAt) {
+    return { ...run, version: run.version + 1, updated_at: occurredAt };
+}
+/** Commit one event that the builder derives from the current run and its events. */
+export async function commitWorkflowRunEvent(context, runId, build, options = {}) {
+    return context.store.withLock(runId, async () => {
+        await context.store.recoverPendingTransition(runId);
+        const run = await context.store.load(runId);
+        if (!isWorkflowV2Run(run)) {
+            throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Run ${runId} belongs to a v1 definition`);
+        }
+        if (run.terminal) {
+            throw new WorkflowRunV2Error('RUN_TERMINAL', `Run ${runId} is terminal (verdict ${run.verdict})`);
+        }
+        if (options.checkManifest !== false)
+            assertCurrentManifest(context, run);
+        const application = build(run, await context.store.readEvents(runId));
+        await context.store.writeEvidenceFiles(runId, application.evidenceFiles ?? []);
+        return context.store.commitTransition(application.run, application.event, run.version);
+    });
+}
+export const WorkflowStepAssignment = z.object({
+    step_id: z.string().min(1).max(100),
+    to: WorkflowParty,
+});
+/**
+ * Hand a step not yet recorded to the operator or the agent. The first assignment declares the
+ * run's mode, so from then on the party guard applies (DEC-023).
+ */
+export function applyStepAssignment(context, run, assignment, input) {
+    const parsed = WorkflowStepAssignment.safeParse(assignment);
+    if (!parsed.success) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `Invalid assignment: ${parsed.error.message}`);
+    }
+    const { step_id: stepId, to } = parsed.data;
+    const step = context.manifest.definition.steps.find((candidate) => candidate.id === stepId);
+    if (!step) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `The guide has no step ${stepId}`);
+    }
+    if (workflowStepChannel(step) === 'runtime') {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Step ${stepId} is decided by the runtime`);
+    }
+    if ((run.completed_step_ids ?? []).includes(stepId) || stepId in (run.outputs ?? {})) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Step ${stepId} is already recorded`);
+    }
+    const occurredAt = input.occurredAt ?? new Date().toISOString();
+    const from = workflowStepAssignee(run, step);
+    const next = {
+        ...bumpedRun(run, occurredAt),
+        mode: workflowRunMode(run),
+        assignments: { ...(run.assignments ?? {}), [stepId]: to },
+    };
+    const event = workflowV2Event(run, {
+        type: 'run.assign',
+        actor: input.actor,
+        actorName: input.actorName,
+        toState: run.state,
+        payload: { protocol: 'workflow-v2', submission: 'assign', step_id: stepId, from, to },
+        occurredAt,
+    });
+    return { run: next, event: { ...event, notify: otherParty(input.actor) } };
+}
+export async function assignWorkflowRunStepV2(context, runId, assignment, input) {
+    return commitWorkflowRunEvent(context, runId, (run) => applyStepAssignment(context, run, assignment, input));
+}
+//# sourceMappingURL=workflow-v2-run-events.js.map

package/dist/runtime/workflow-v2-run-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-run-events.js","sourceRoot":"","sources":["../../src/runtime/workflow-v2-run-events.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workflow-v2-run.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run lifecycle of compiled workflows (schema_version "2.0"): start, resume, and read.
+ * The run snapshot is the cursor; every accepted step is one event in the run's log.
+ */
+import type { WorkflowExecutionManifest } from '../core/workflow-compiler.js';
+import type { WorkflowRouteVerdict } from '../schemas/workflow-definition-v2.js';
+import type { ProcessEvent, ProcessRun, RuntimeActor } from './index.js';
+import type { RunStore } from './run-store.js';
+import type { WorkflowRunDispatch, WorkflowRunDispatchState } from './workflow-v2-dispatch.js';
+import { type WorkflowRunMode, type WorkflowRunPolicy } from './workflow-v2-types.js';
+export type WorkflowV2RunContext = Readonly<{
+    definitionId: string;
+    /** `metadata.workflow_revision` of the item, or the definition digest when none is pinned. */
+    definitionRevision: string;
+    manifest: WorkflowExecutionManifest;
+    store: RunStore;
+}>;
+export type WorkflowV2StartInput = Readonly<{
+    operation: 'new' | 'resume';
+    workspaceFingerprint: string;
+    runId?: string;
+    variables?: Readonly<Record<string, unknown>>;
+    policy?: WorkflowRunPolicy;
+    /** Non-terminal runs of the same definition, checked when parallel runs are not allowed. */
+    openRunIds?: readonly string[];
+    /**
+     * Who works the run; without it a human-guided guide is worked together and any other guide
+     * by the host profile's party (`startRunMode`, `workflowRunMode`).
+     */
+    mode?: WorkflowRunMode;
+}>;
+export type WorkflowV2StartResult = Readonly<{
+    run: ProcessRun;
+    note?: string;
+}>;
+export declare function isWorkflowV2Run(run: ProcessRun): boolean;
+/** A run executes against the manifest it was started with; any drift must be recompiled. */
+export declare function assertCurrentManifest(context: WorkflowV2RunContext, run: ProcessRun): void;
+export declare function startWorkflowRunV2(context: WorkflowV2RunContext, input: WorkflowV2StartInput, occurredAt?: string): Promise<WorkflowV2StartResult>;
+export declare function readWorkflowRunV2(store: RunStore, runId: string): Promise<ProcessRun>;
+export type WorkflowV2EventInput = Readonly<{
+    type: string;
+    actor: RuntimeActor;
+    /** The actor's name; the kind is `actor`. */
+    actorName?: string;
+    toState: string;
+    payload: Readonly<Record<string, unknown>>;
+    idempotencyKey?: string;
+    occurredAt: string;
+}>;
+/**
+ * Build the event for a cursor move; `sequence` is the run version the event consumes.
+ *
+ * `actor_name` is the one event field that is deliberately not redacted — a signature that gets
+ * redacted proves nothing — so a secret-shaped name is refused here instead. Redaction covers
+ * `payload` only (`sanitizeProcessEvent`), and without this check a pasted token in the name would
+ * be written to the append-only log verbatim.
+ */
+export declare function workflowV2Event(run: ProcessRun, input: WorkflowV2EventInput): ProcessEvent;
+export type WorkflowV2DispatchResult = Readonly<{
+    run: ProcessRun;
+    dispatch: WorkflowRunDispatch | null;
+    next_action: 'execute' | 'ask' | 'finalize' | 'none';
+    pending_verdict?: WorkflowRouteVerdict;
+    verdict?: WorkflowRouteVerdict | null;
+    /** Steps the runtime decided itself while advancing the cursor (predicate, bypass, policy). */
+    runtime_decisions?: readonly Readonly<{
+        step_id: string;
+        runtime: string;
+        outcome: string;
+        summary?: string;
+        to_state: string;
+    }>[];
+}>;
+/** Summarize a dispatch state for the caller: what to do next and with which step. */
+export declare function describeDispatchState(run: ProcessRun, state: WorkflowRunDispatchState): WorkflowV2DispatchResult;
+//# sourceMappingURL=workflow-v2-run.d.ts.map

package/dist/runtime/workflow-v2-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-run.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-run.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workflow-v2-run.js

@@ -0,0 +1,137 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run lifecycle of compiled workflows (schema_version "2.0"): start, resume, and read.
+ * The run snapshot is the cursor; every accepted step is one event in the run's log.
+ */
+import { containsSecretShape } from './redaction.js';
+import { initialStepLabels } from './workflow-v2-labels.js';
+import { startRunMode } from './workflow-v2-parties.js';
+import { WorkflowRunV2Error, } from './workflow-v2-types.js';
+import { validateWorkflowVariables } from './workflow-v2-variables.js';
+import { normalizeWorkspaceFingerprint, sameWorkspaceFingerprint, } from './workspace-fingerprint.js';
+export function isWorkflowV2Run(run) {
+    return run.definition_schema_version === '2.0';
+}
+function createRun(context, input, occurredAt) {
+    const { manifest } = context;
+    const variables = validateWorkflowVariables(manifest.definition, input.variables);
+    const firstStep = manifest.definition.steps[0];
+    if (!firstStep)
+        throw new WorkflowRunV2Error('AUTHORING_INVALID', 'Definition has no steps');
+    const mode = input.mode ?? startRunMode(manifest.definition, manifest.host_profile);
+    return {
+        schema_version: '2.0',
+        run_id: input.runId ?? crypto.randomUUID(),
+        process_type: manifest.process_type,
+        definition_id: context.definitionId,
+        definition_revision: context.definitionRevision,
+        definition_digest: manifest.definition_digest,
+        state: firstStep.id,
+        created_at: occurredAt,
+        updated_at: occurredAt,
+        workspace_fingerprint: normalizeWorkspaceFingerprint(input.workspaceFingerprint),
+        attempt: 1,
+        version: 1,
+        terminal: false,
+        definition_schema_version: '2.0',
+        manifest_digest: manifest.manifest_digest,
+        host_profile: manifest.host_profile,
+        variables,
+        policy: input.policy ?? {},
+        completed_step_ids: [],
+        outputs: {},
+        step_attempts: {},
+        pending_verdict: null,
+        verdict: null,
+        ...(mode ? { mode } : {}),
+        step_labels: initialStepLabels(manifest.definition.steps),
+    };
+}
+/** A run executes against the manifest it was started with; any drift must be recompiled. */
+export function assertCurrentManifest(context, run) {
+    if (run.manifest_digest !== context.manifest.manifest_digest) {
+        throw new WorkflowRunV2Error('MANIFEST_INTEGRITY', `Run ${run.run_id} was started with manifest ${run.manifest_digest} but the definition of ${context.definitionId} now compiles to ${context.manifest.manifest_digest} for host profile ${context.manifest.host_profile}; finalize the run as CANCELLED and start a new one`);
+    }
+}
+export async function startWorkflowRunV2(context, input, occurredAt = new Date().toISOString()) {
+    if (input.operation === 'new') {
+        const open = input.openRunIds ?? [];
+        if (!context.manifest.definition.allow_parallel_runs && open.length > 0) {
+            throw new WorkflowRunV2Error('POLICY_DENIED', `${context.definitionId} does not allow parallel runs and run ${open.join(', ')} is still open; resume it, finalize it as CANCELLED, or set allow_parallel_runs: true`);
+        }
+        const run = createRun(context, input, occurredAt);
+        await context.store.create(run);
+        return { run };
+    }
+    if (!input.runId)
+        throw new WorkflowRunV2Error('INPUT_INVALID', 'Resume requires a run_id');
+    const run = await readWorkflowRunV2(context.store, input.runId);
+    if (!sameWorkspaceFingerprint(run.workspace_fingerprint, input.workspaceFingerprint)) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `Workflow run ${run.run_id} was started with workspace fingerprint "${run.workspace_fingerprint}" but "${input.workspaceFingerprint}" was supplied`);
+    }
+    if (run.terminal) {
+        return { run, note: `run is terminal (verdict ${run.verdict ?? 'unknown'}); start a new run` };
+    }
+    assertCurrentManifest(context, run);
+    return { run };
+}
+export async function readWorkflowRunV2(store, runId) {
+    const run = await store.withLock(runId, async () => {
+        await store.recoverPendingTransition(runId);
+        return store.load(runId);
+    });
+    if (!isWorkflowV2Run(run)) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Run ${runId} belongs to a v1 definition; use the v1 event protocol`);
+    }
+    return run;
+}
+/**
+ * Build the event for a cursor move; `sequence` is the run version the event consumes.
+ *
+ * `actor_name` is the one event field that is deliberately not redacted — a signature that gets
+ * redacted proves nothing — so a secret-shaped name is refused here instead. Redaction covers
+ * `payload` only (`sanitizeProcessEvent`), and without this check a pasted token in the name would
+ * be written to the append-only log verbatim.
+ */
+export function workflowV2Event(run, input) {
+    if (input.actorName !== undefined && containsSecretShape(input.actorName)) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', 'actor_name looks like a secret; it is written to the run log unredacted, so it takes a name, not a credential');
+    }
+    return {
+        schema_version: '2.0',
+        event_id: crypto.randomUUID(),
+        run_id: run.run_id,
+        sequence: run.version,
+        type: input.type,
+        occurred_at: input.occurredAt,
+        from_state: run.state,
+        to_state: input.toState,
+        actor: input.actor,
+        actor_name: input.actorName,
+        idempotency_key: input.idempotencyKey,
+        payload: input.payload,
+    };
+}
+/** Summarize a dispatch state for the caller: what to do next and with which step. */
+export function describeDispatchState(run, state) {
+    switch (state.status) {
+        case 'dispatch':
+            return {
+                run,
+                dispatch: state.dispatch,
+                next_action: state.step.kind === 'human' ? 'ask' : 'execute',
+            };
+        case 'awaiting-finalize':
+            return {
+                run,
+                dispatch: null,
+                next_action: 'finalize',
+                pending_verdict: state.pending_verdict,
+            };
+        case 'terminal':
+            return { run, dispatch: null, next_action: 'none', verdict: state.verdict };
+    }
+}
+//# sourceMappingURL=workflow-v2-run.js.map

package/dist/runtime/workflow-v2-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-run.js","sourceRoot":"","sources":["../../src/runtime/workflow-v2-run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAGL,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,4BAA4B,CAAC;AA2BpC,MAAM,UAAU,eAAe,CAAC,GAAe;IAC7C,OAAO,GAAG,CAAC,yBAAyB,KAAK,KAAK,CAAC;AACjD,CAAC;AAED,SAAS,SAAS,CAChB,OAA6B,EAC7B,KAA2B,EAC3B,UAAkB;IAElB,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,SAAS,GAAG,yBAAyB,CAAC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,kBAAkB,CAAC,mBAAmB,EAAE,yBAAyB,CAAC,CAAC;IAC7F,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,YAAY,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IACpF,OAAO;QACL,cAAc,EAAE,KAAK;QACrB,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC,UAAU,EAAE;QAC1C,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,aAAa,EAAE,OAAO,CAAC,YAAY;QACnC,mBAAmB,EAAE,OAAO,CAAC,kBAAkB;QAC/C,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;QAC7C,KAAK,EAAE,SAAS,CAAC,EAAE;QACnB,UAAU,EAAE,UAAU;QACtB,UAAU,EAAE,UAAU;QACtB,qBAAqB,EAAE,6BAA6B,CAAC,KAAK,CAAC,oBAAoB,CAAC;QAChF,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,KAAK;QACf,yBAAyB,EAAE,KAAK;QAChC,eAAe,EAAE,QAAQ,CAAC,eAAe;QACzC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,SAAS;QACT,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;QAC1B,kBAAkB,EAAE,EAAE;QACtB,OAAO,EAAE,EAAE;QACX,aAAa,EAAE,EAAE;QACjB,eAAe,EAAE,IAAI;QACrB,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzB,WAAW,EAAE,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,qBAAqB,CAAC,OAA6B,EAAE,GAAe;IAClF,IAAI,GAAG,CAAC,eAAe,KAAK,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC7D,MAAM,IAAI,kBAAkB,CAC1B,oBAAoB,EACpB,OAAO,GAAG,CAAC,MAAM,8BAA8B,GAAG,CAAC,eAAe,0BAA0B,OAAO,CAAC,YAAY,oBAAoB,OAAO,CAAC,QAAQ,CAAC,eAAe,qBAAqB,OAAO,CAAC,QAAQ,CAAC,YAAY,qDAAqD,CAC5Q,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAA6B,EAC7B,KAA2B,EAC3B,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAErC,IAAI,KAAK,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,mBAAmB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxE,MAAM,IAAI,kBAAkB,CAC1B,eAAe,EACf,GAAG,OAAO,CAAC,YAAY,yCAAyC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,uFAAuF,CACvK,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAClD,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,OAAO,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,KAAK;QAAE,MAAM,IAAI,kBAAkB,CAAC,eAAe,EAAE,0BAA0B,CAAC,CAAC;IAC5F,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAChE,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,qBAAqB,EAAE,KAAK,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACrF,MAAM,IAAI,kBAAkB,CAC1B,eAAe,EACf,gBAAgB,GAAG,CAAC,MAAM,4CAA4C,GAAG,CAAC,qBAAqB,UAAU,KAAK,CAAC,oBAAoB,gBAAgB,CACpJ,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,4BAA4B,GAAG,CAAC,OAAO,IAAI,SAAS,oBAAoB,EAAE,CAAC;IACjG,CAAC;IACD,qBAAqB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,OAAO,EAAE,GAAG,EAAE,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAe,EAAE,KAAa;IACpE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;QACjD,MAAM,KAAK,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,kBAAkB,CAC1B,gBAAgB,EAChB,OAAO,KAAK,wDAAwD,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAe,EAAE,KAA2B;IAC1E,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,kBAAkB,CAC1B,eAAe,EACf,+GAA+G,CAChH,CAAC;IACJ,CAAC;IACD,OAAO;QACL,cAAc,EAAE,KAAK;QACrB,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE;QAC7B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,OAAO;QACrB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,UAAU;QAC7B,UAAU,EAAE,GAAG,CAAC,KAAK;QACrB,QAAQ,EAAE,KAAK,CAAC,OAAO;QACvB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,UAAU,EAAE,KAAK,CAAC,SAAS;QAC3B,eAAe,EAAE,KAAK,CAAC,cAAc;QACrC,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;AACJ,CAAC;AAkBD,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CACnC,GAAe,EACf,KAA+B;IAE/B,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,UAAU;YACb,OAAO;gBACL,GAAG;gBACH,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;aAC7D,CAAC;QACJ,KAAK,mBAAmB;YACtB,OAAO;gBACL,GAAG;gBACH,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,UAAU;gBACvB,eAAe,EAAE,KAAK,CAAC,eAAe;aACvC,CAAC;QACJ,KAAK,UAAU;YACb,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/runtime/workflow-v2-runtime-steps.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Steps the runtime completes itself without executing anything: predicate steps, which judge
+ * outputs already recorded. Each completion is an event with `actor: system`.
+ */
+import type { WorkflowExecutionManifest } from '../core/workflow-compiler.js';
+import type { WorkflowStep } from '../schemas/workflow-definition-v2.js';
+import type { ProcessRun } from './index.js';
+import type { WorkflowPredicateResult } from './predicates.js';
+import { type WorkflowRunDispatch } from './workflow-v2-dispatch.js';
+import { type StepApplication } from './workflow-v2-receipt.js';
+import { type WorkflowRouteSlot } from './workflow-v2-routing.js';
+export type RuntimeCompletion = Readonly<{
+    reason: 'predicate' | 'bypass' | 'policy';
+    slot: WorkflowRouteSlot;
+    predicates: readonly WorkflowPredicateResult[];
+    errorCode?: string;
+    outcome: string;
+    detail?: string;
+}>;
+/** Record a step the runtime decided without a host receipt. */
+export declare function applyRuntimeCompletion(manifest: WorkflowExecutionManifest, run: ProcessRun, step: WorkflowStep, dispatch: WorkflowRunDispatch, completion: RuntimeCompletion, occurredAt: string): StepApplication;
+/**
+ * The side-effect policy: a step above the run's `max_side_effect` is never dispatched, and a
+ * destructive, mutating, credentialed, or irreversible step (cleanup excepted) needs a PASS answer
+ * from an `approval` human step among its direct dependencies in this run.
+ */
+export declare function policyDenial(manifest: WorkflowExecutionManifest, run: ProcessRun, step: WorkflowStep): RuntimeCompletion | undefined;
+/** Decide a dispatched runtime step without constructing an event or advancing the cursor. */
+export declare function runtimeCompletionForStep(manifest: WorkflowExecutionManifest, run: ProcessRun, step: WorkflowStep): RuntimeCompletion | undefined;
+/** The runtime completion due at the cursor, if the cursor names a step the runtime decides. */
+export declare function nextRuntimeApplication(manifest: WorkflowExecutionManifest, run: ProcessRun, occurredAt: string): StepApplication | undefined;
+//# sourceMappingURL=workflow-v2-runtime-steps.d.ts.map

package/dist/runtime/workflow-v2-runtime-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-runtime-steps.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-runtime-steps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACxF,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAQlC,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,UAAU,EAAE,iBAAiB,EAC7B,UAAU,EAAE,MAAM,GACjB,eAAe,CA8DjB;AA4BD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,YAAY,GACjB,iBAAiB,GAAG,SAAS,CAiB/B;AAED,8FAA8F;AAC9F,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,YAAY,GACjB,iBAAiB,GAAG,SAAS,CAwB/B;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,MAAM,GACjB,eAAe,GAAG,SAAS,CAO7B"}