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

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

@@ -0,0 +1,112 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Declared fields of v2 steps (STORY-450): the values the operator fills in when reporting or
+ * answering a step, validated against the step's contract before anything is recorded, and kept
+ * as structured evidence with digests. A refusal names the field by its label. Fields add
+ * observation; the route still comes from the report's status or the answer's mapping.
+ * @see STORY-450
+ */
+import { captureEvidence } from './evidence.js';
+import { containsSecretShape } from './redaction.js';
+import { WorkflowRunV2Error } from './workflow-v2-types.js';
+const TEXT_LIMIT = 2000;
+function invalid(step, field, reason) {
+    throw new WorkflowRunV2Error('INPUT_INVALID', `Field "${field.label}" (${field.id}) of step ${step.id} ${reason}`);
+}
+function isEmpty(value) {
+    return value === undefined || (typeof value === 'string' && value.trim() === '');
+}
+function typedValue(step, field, raw) {
+    switch (field.kind) {
+        case 'number': {
+            const value = typeof raw === 'number' ? raw : Number(String(raw).trim());
+            if (!Number.isFinite(value))
+                invalid(step, field, 'takes a number');
+            return value;
+        }
+        case 'boolean': {
+            if (typeof raw === 'boolean')
+                return raw;
+            const text = String(raw).trim().toLowerCase();
+            if (text !== 'true' && text !== 'false')
+                invalid(step, field, 'takes yes (true) or no (false)');
+            return text === 'true';
+        }
+        case 'choice': {
+            const text = String(raw).trim();
+            if (!field.options?.includes(text)) {
+                invalid(step, field, `takes one of ${field.options?.join(', ') ?? 'its options'}`);
+            }
+            return text;
+        }
+        case 'text': {
+            const text = String(raw).trim();
+            if (text.includes('\n') || text.length > TEXT_LIMIT) {
+                invalid(step, field, `takes one line of at most ${TEXT_LIMIT} characters`);
+            }
+            return text;
+        }
+        default:
+            return String(raw).trim();
+    }
+}
+/**
+ * The step's fields with their values, in declared order. A required field must be filled when
+ * the step is reported done or answered positively; a value for an undeclared field, a value of
+ * the wrong kind and a secret-shaped value are refused.
+ */
+export function validateStepFields(step, values, positive) {
+    const declared = step.fields ?? [];
+    const unknown = Object.keys(values ?? {}).filter((id) => !declared.some((field) => field.id === id));
+    if (unknown.length > 0) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `Step ${step.id} declares no field ${unknown.join(', ')}`);
+    }
+    const recorded = [];
+    for (const field of declared) {
+        const raw = values?.[field.id];
+        if (raw === undefined || isEmpty(raw)) {
+            if (field.required && positive)
+                invalid(step, field, 'is required; fill it in first');
+            continue;
+        }
+        if (typeof raw === 'string' && containsSecretShape(raw)) {
+            invalid(step, field, 'looks like a secret; it would be written to the run log');
+        }
+        recorded.push({
+            id: field.id,
+            label: field.label,
+            kind: field.kind,
+            value: typedValue(step, field, raw),
+        });
+    }
+    return recorded;
+}
+/** The values as a step output reads them: `outputs.<step>.fields.<id>`. */
+export function fieldOutput(recorded) {
+    if (recorded.length === 0)
+        return {};
+    return { fields: Object.fromEntries(recorded.map((field) => [field.id, field.value])) };
+}
+/** One evidence entry with a digest per field; a long value is written out as a file. */
+export function fieldEvidence(stepId, recorded, at) {
+    const entries = [];
+    const files = [];
+    for (const field of recorded) {
+        const { entry, file } = captureEvidence({
+            stepId,
+            attempt: at.attempt,
+            sequence: at.sequence,
+            type: 'field',
+            suffix: field.id,
+            text: `${field.label}: ${String(field.value)}`,
+            capturedAt: at.capturedAt,
+        });
+        entries.push(entry);
+        if (file)
+            files.push(file);
+    }
+    return { entries, files };
+}
+//# sourceMappingURL=workflow-v2-fields.js.map

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Finalization of compiled workflow runs.
+ * A run closes with the verdict its routes reached, after every owed cleanup step has a receipt;
+ * CANCELLED closes from any non-terminal state and needs a reason. A receipt or human response
+ * passed to finalize is stored on the terminal event exactly as record would store it.
+ */
+import type { ProcessEvent, ProcessRun } from './index.js';
+import type { RunStore } from './run-store.js';
+import { type WorkflowV2Submission } from './workflow-v2-engine.js';
+import { type WorkflowV2RunContext } from './workflow-v2-run.js';
+export type WorkflowV2FinalizeInput = WorkflowV2Submission & Readonly<{
+    verdict: string;
+    reason?: string;
+}>;
+/** A context whose manifest may be missing when the definition no longer compiles; only CANCELLED works then. */
+export type WorkflowV2FinalizeContext = Readonly<{
+    store: RunStore;
+    context?: WorkflowV2RunContext;
+}>;
+export type WorkflowV2FinalizeResult = Readonly<{
+    run: ProcessRun;
+    replayed: boolean;
+    events: readonly ProcessEvent[];
+}>;
+export declare function finalizeWorkflowRunV2(target: WorkflowV2FinalizeContext, runId: string, input: WorkflowV2FinalizeInput): Promise<WorkflowV2FinalizeResult>;
+//# sourceMappingURL=workflow-v2-finalize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-finalize.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-finalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,GACxD,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,iHAAiH;AACjH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,GAAG,EAAE,UAAU,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,CAAC,CAAC;AAwLH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,yBAAyB,EACjC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAOnC"}

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

@@ -0,0 +1,167 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Finalization of compiled workflow runs.
+ * A run closes with the verdict its routes reached, after every owed cleanup step has a receipt;
+ * CANCELLED closes from any non-terminal state and needs a reason. A receipt or human response
+ * passed to finalize is stored on the terminal event exactly as record would store it.
+ */
+import { WorkflowRouteVerdict } from '../schemas/workflow-v2-vocabulary.js';
+import { applySubmission, assertExpectedVersion, assertSubmissionActor, findReplay, occurredAtOf, parseSubmission, } from './workflow-v2-engine.js';
+import { requestDigest } from './workflow-v2-receipt.js';
+import { writeWorkflowV2Reports } from './workflow-v2-report-render.js';
+import { pendingCleanupSteps } from './workflow-v2-routing.js';
+import { assertCurrentManifest, isWorkflowV2Run, workflowV2Event, } from './workflow-v2-run.js';
+import { nextRuntimeApplication } from './workflow-v2-runtime-steps.js';
+import { AWAITING_FINALIZE, WorkflowRunV2Error } from './workflow-v2-types.js';
+const OUTCOME_BY_VERDICT = {
+    PASS: 'recorded',
+    FAIL: 'failed',
+    BLOCKED: 'blocked',
+    INCONCLUSIVE: 'inconclusive',
+    CANCELLED: 'recorded',
+};
+function parseVerdict(value) {
+    const parsed = WorkflowRouteVerdict.safeParse(value);
+    if (!parsed.success) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `verdict must be one of PASS, FAIL, BLOCKED, CANCELLED, INCONCLUSIVE; received ${JSON.stringify(value)}`);
+    }
+    return parsed.data;
+}
+function planStepApplications(context, run, input, events) {
+    const submission = parseSubmission(input);
+    if (submission.kind === 'none')
+        return [];
+    const digest = requestDigest(submission.kind, submission.content);
+    if (findReplay(events, submission, digest, input.idempotencyKey))
+        return [];
+    const applications = [applySubmission(context, run, submission, input, digest)];
+    const occurredAt = occurredAtOf(input);
+    for (let count = 0; count < 100; count += 1) {
+        const current = applications[applications.length - 1]?.run ?? run;
+        const next = nextRuntimeApplication(context.manifest, current, occurredAt);
+        if (!next)
+            break;
+        applications.push(next);
+    }
+    return applications;
+}
+function assertFinalizable(manifest, run, verdict) {
+    if (run.state === AWAITING_FINALIZE) {
+        if (run.pending_verdict !== verdict) {
+            throw new WorkflowRunV2Error('PROTOCOL_ERROR', `verdict ${verdict} does not match the verdict the routes reached (${run.pending_verdict}); finalize with ${run.pending_verdict} or CANCELLED with a reason`);
+        }
+        return;
+    }
+    const cleanup = pendingCleanupSteps(manifest.definition, run);
+    if (run.pending_verdict && cleanup.length > 0) {
+        throw new WorkflowRunV2Error('CLEANUP_PENDING', `Run ${run.run_id} reached ${run.pending_verdict} but owes cleanup steps ${cleanup.map((step) => step.id).join(', ')}; dispatch and record them, or finalize as CANCELLED with a reason`, { missing_cleanup: cleanup.map((step) => step.id), pending_verdict: run.pending_verdict });
+    }
+    throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Run ${run.run_id} has not reached a verdict; the next step is ${run.state}. Dispatch and record it, or finalize as CANCELLED with a reason`);
+}
+async function commitAll(store, run, applications) {
+    let current = run;
+    for (const application of applications) {
+        await store.writeEvidenceFiles(run.run_id, application.evidenceFiles);
+        current = await store.commitTransition(application.run, application.event, current.version);
+    }
+    return current;
+}
+function terminalPayload(verdict, run, input, cleanupPending) {
+    return {
+        finalized: true,
+        verdict,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(cleanupPending.length > 0 ? { cleanup_pending: cleanupPending } : {}),
+        routed_verdict: run.pending_verdict ?? null,
+    };
+}
+async function finalizeLocked(target, runId, input) {
+    const { store, context } = target;
+    await store.recoverPendingTransition(runId);
+    const run = await store.load(runId);
+    if (!isWorkflowV2Run(run)) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Run ${runId} belongs to a v1 definition`);
+    }
+    const verdict = parseVerdict(input.verdict);
+    if (run.terminal) {
+        if (run.verdict === verdict)
+            return { run, replayed: true, events: [] };
+        throw new WorkflowRunV2Error('RUN_TERMINAL', `Run ${runId} is already terminal (verdict ${run.verdict})`);
+    }
+    assertExpectedVersion(run, input.expectedVersion);
+    if (verdict === 'CANCELLED' && !input.reason?.trim()) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', 'Finalizing as CANCELLED needs a reason');
+    }
+    const hasSubmission = input.receipt !== undefined || input.humanResponse !== undefined;
+    if (!context && (verdict !== 'CANCELLED' || hasSubmission)) {
+        throw new WorkflowRunV2Error('MANIFEST_INTEGRITY', `The definition of run ${runId} no longer compiles; only finalize with verdict CANCELLED and a reason is possible`);
+    }
+    if (context && (verdict !== 'CANCELLED' || hasSubmission))
+        assertCurrentManifest(context, run);
+    const applications = context
+        ? planStepApplications(context, run, input, await store.readEvents(runId))
+        : [];
+    const working = applications[applications.length - 1]?.run ?? run;
+    if (context && verdict !== 'CANCELLED')
+        assertFinalizable(context.manifest, working, verdict);
+    const occurredAt = occurredAtOf(input);
+    const cleanupPending = context && verdict === 'CANCELLED'
+        ? pendingCleanupSteps(context.manifest.definition, working).map((step) => step.id)
+        : [];
+    const terminal = {
+        state: verdict,
+        terminal: true,
+        verdict,
+        finished_at: occurredAt,
+        updated_at: occurredAt,
+        ...(input.reason ? { reason: input.reason } : {}),
+    };
+    const last = applications.pop();
+    const before = await commitAll(store, run, applications);
+    if (last)
+        await store.writeEvidenceFiles(runId, last.evidenceFiles);
+    const payloadExtra = terminalPayload(verdict, working, input, cleanupPending);
+    const event = last
+        ? {
+            ...last.event,
+            to_state: verdict,
+            payload: { ...last.event.payload, ...payloadExtra },
+        }
+        : workflowV2Event(before, {
+            type: 'finalize',
+            actor: input.actor,
+            actorName: input.actorName,
+            toState: verdict,
+            payload: { protocol: 'workflow-v2', outcome: OUTCOME_BY_VERDICT[verdict], ...payloadExtra },
+            idempotencyKey: input.idempotencyKey,
+            occurredAt,
+        });
+    const finalRun = {
+        ...(last?.run ?? before),
+        ...terminal,
+        version: before.version + 1,
+    };
+    // A closed run is news for the other party; a waiting agent stops waiting (DEC-022).
+    const addressed = {
+        ...event,
+        notify: input.actor === 'agent' ? 'operator' : 'agent',
+    };
+    const committed = await store.commitTransition(finalRun, addressed, before.version);
+    return {
+        run: committed,
+        replayed: false,
+        events: [...applications.map((a) => a.event), addressed],
+    };
+}
+export async function finalizeWorkflowRunV2(target, runId, input) {
+    assertSubmissionActor(input);
+    return target.store.withLock(runId, async () => {
+        const result = await finalizeLocked(target, runId, input);
+        if (!result.replayed)
+            await writeWorkflowV2Reports(target.store, result.run);
+        return result;
+    });
+}
+//# sourceMappingURL=workflow-v2-finalize.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Handing a v2 run to other hands (STORY-456): resume it under another host profile, or give it
+ * from the operator to the agent and back. A manifest is compiled per host profile, so the run
+ * takes the recompiled manifest as long as the definition behind it is unchanged — step ids,
+ * bindings, routes and predicates are the same definition. Recorded steps stay, the cursor stays,
+ * and the run records the hand-over as one event naming both profiles, both manifest digests and
+ * both modes. A definition that changed is refused, naming the digest, and nothing is written.
+ * @see STORY-456
+ */
+import type { ProcessRun } from './index.js';
+import { type WorkflowV2RunContext, type WorkflowV2StartInput, type WorkflowV2StartResult } from './workflow-v2-run.js';
+import { type WorkflowRunEventApplication, type WorkflowRunEventInput } from './workflow-v2-run-events.js';
+import { type WorkflowRunMode } from './workflow-v2-types.js';
+export declare const WORKFLOW_HANDOVER_EVENT = "run.handover";
+export type WorkflowRunHandoverInput = WorkflowRunEventInput & Readonly<{
+    /** Who works the run from now on; without it the rule of `handoverMode` decides. */
+    mode?: WorkflowRunMode;
+}>;
+/**
+ * The mode a run takes under another host profile: the operator's profile means the operator
+ * alone, a run that leaves the operator's profile for an agent's becomes the agent's, as a run the
+ * agent started is (DEC-028); between two agent profiles the mode stays.
+ */
+export declare function handoverMode(run: Pick<ProcessRun, 'mode' | 'host_profile'>, nextProfile: string): WorkflowRunMode;
+/**
+ * Plan the hand-over of `run` to the profile the context was compiled for, or refuse it with the
+ * reason. Undefined when nothing changes hands: same profile, same manifest, same mode.
+ */
+export declare function planWorkflowRunHandover(context: WorkflowV2RunContext, run: ProcessRun, input: WorkflowRunHandoverInput): WorkflowRunEventApplication | undefined;
+/** Commit the hand-over under the run lock; a run that changes no hands is returned as it is. */
+export declare function handOverWorkflowRunV2(context: WorkflowV2RunContext, runId: string, input: WorkflowRunHandoverInput): Promise<ProcessRun>;
+/**
+ * Resume a run, handing it over when the context was compiled for another host profile than the
+ * run's or the hand-over names another mode (BUG-207); under its own profile and mode this is the
+ * plain resume of `startWorkflowRunV2`.
+ */
+export declare function resumeWorkflowRunV2(context: WorkflowV2RunContext, input: Omit<WorkflowV2StartInput, 'operation'> & Readonly<{
+    handover: WorkflowRunHandoverInput;
+}>): Promise<WorkflowV2StartResult>;
+//# sourceMappingURL=workflow-v2-handover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-handover.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-handover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,wBAAwB,CAAC;AAGlF,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,GAC1D,QAAQ,CAAC;IACP,oFAAoF;IACpF,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB,CAAC,CAAC;AAEL;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC,EAC9C,WAAW,EAAE,MAAM,GAClB,eAAe,CAKjB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,wBAAwB,GAC9B,2BAA2B,GAAG,SAAS,CA4DzC;AAED,iGAAiG;AACjG,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,UAAU,CAAC,CAQrB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC;IAAE,QAAQ,EAAE,wBAAwB,CAAA;CAAE,CAAC,GAChG,OAAO,CAAC,qBAAqB,CAAC,CAqBhC"}

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

@@ -0,0 +1,124 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Handing a v2 run to other hands (STORY-456): resume it under another host profile, or give it
+ * from the operator to the agent and back. A manifest is compiled per host profile, so the run
+ * takes the recompiled manifest as long as the definition behind it is unchanged — step ids,
+ * bindings, routes and predicates are the same definition. Recorded steps stay, the cursor stays,
+ * and the run records the hand-over as one event naming both profiles, both manifest digests and
+ * both modes. A definition that changed is refused, naming the digest, and nothing is written.
+ * @see STORY-456
+ */
+import { OPERATOR_HOST_PROFILE, workflowRunMode } from './workflow-v2-parties.js';
+import { isWorkflowV2Run, readWorkflowRunV2, startWorkflowRunV2, workflowV2Event, } from './workflow-v2-run.js';
+import { bumpedRun, otherParty, } from './workflow-v2-run-events.js';
+import { WorkflowRunV2Error } from './workflow-v2-types.js';
+import { sameWorkspaceFingerprint } from './workspace-fingerprint.js';
+export const WORKFLOW_HANDOVER_EVENT = 'run.handover';
+/**
+ * The mode a run takes under another host profile: the operator's profile means the operator
+ * alone, a run that leaves the operator's profile for an agent's becomes the agent's, as a run the
+ * agent started is (DEC-028); between two agent profiles the mode stays.
+ */
+export function handoverMode(run, nextProfile) {
+    if (nextProfile === run.host_profile)
+        return workflowRunMode(run);
+    if (nextProfile === OPERATOR_HOST_PROFILE)
+        return 'operator';
+    if (run.host_profile === OPERATOR_HOST_PROFILE)
+        return 'agent';
+    return workflowRunMode(run);
+}
+/**
+ * Plan the hand-over of `run` to the profile the context was compiled for, or refuse it with the
+ * reason. Undefined when nothing changes hands: same profile, same manifest, same mode.
+ */
+export function planWorkflowRunHandover(context, run, input) {
+    const next = context.manifest;
+    if (!isWorkflowV2Run(run)) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Run ${run.run_id} belongs to a v1 definition`);
+    }
+    if (run.terminal) {
+        throw new WorkflowRunV2Error('RUN_TERMINAL', `Run ${run.run_id} is terminal (verdict ${run.verdict}); a closed run changes no hands`);
+    }
+    if (run.definition_digest !== next.definition_digest) {
+        throw new WorkflowRunV2Error('MANIFEST_INTEGRITY', `Run ${run.run_id} runs definition ${run.definition_digest}, but ${context.definitionId} now compiles to definition ${next.definition_digest}; a run changes hands only while its definition is unchanged, so finalize it as CANCELLED and start a new one`, {
+            definition_digest: run.definition_digest,
+            current_definition_digest: next.definition_digest,
+        });
+    }
+    const sameProfile = run.host_profile === next.host_profile;
+    if (sameProfile && run.manifest_digest !== next.manifest_digest) {
+        throw new WorkflowRunV2Error('MANIFEST_INTEGRITY', `Run ${run.run_id} was started with manifest ${run.manifest_digest}, but host profile ${next.host_profile} now compiles to ${next.manifest_digest}; finalize the run as CANCELLED and start a new one`);
+    }
+    const previousMode = workflowRunMode(run);
+    const mode = input.mode ?? handoverMode(run, next.host_profile);
+    // A run without a declared mode takes the one a hand-over names, so its party guard applies.
+    const declares = input.mode !== undefined && run.mode === undefined;
+    if (sameProfile && mode === previousMode && !declares)
+        return undefined;
+    const occurredAt = input.occurredAt ?? new Date().toISOString();
+    const nextRun = {
+        ...bumpedRun(run, occurredAt),
+        host_profile: next.host_profile,
+        manifest_digest: next.manifest_digest,
+        mode,
+    };
+    const event = workflowV2Event(run, {
+        type: WORKFLOW_HANDOVER_EVENT,
+        actor: input.actor,
+        actorName: input.actorName,
+        toState: run.state,
+        payload: {
+            protocol: 'workflow-v2',
+            submission: 'handover',
+            previous_host_profile: run.host_profile ?? null,
+            host_profile: next.host_profile,
+            previous_manifest_digest: run.manifest_digest ?? null,
+            manifest_digest: next.manifest_digest,
+            definition_digest: next.definition_digest,
+            previous_mode: previousMode,
+            mode,
+        },
+        occurredAt,
+    });
+    // The other party hears of it: the agent that receives the run, or the one that loses it.
+    return { run: nextRun, event: { ...event, notify: otherParty(input.actor) } };
+}
+/** Commit the hand-over under the run lock; a run that changes no hands is returned as it is. */
+export async function handOverWorkflowRunV2(context, runId, input) {
+    return context.store.withLock(runId, async () => {
+        await context.store.recoverPendingTransition(runId);
+        const run = await context.store.load(runId);
+        const application = planWorkflowRunHandover(context, run, input);
+        if (!application)
+            return run;
+        return context.store.commitTransition(application.run, application.event, run.version);
+    });
+}
+/**
+ * Resume a run, handing it over when the context was compiled for another host profile than the
+ * run's or the hand-over names another mode (BUG-207); under its own profile and mode this is the
+ * plain resume of `startWorkflowRunV2`.
+ */
+export async function resumeWorkflowRunV2(context, input) {
+    const { handover, ...resume } = input;
+    if (!resume.runId)
+        throw new WorkflowRunV2Error('INPUT_INVALID', 'Resume requires a run_id');
+    const run = await readWorkflowRunV2(context.store, resume.runId);
+    const sameProfile = run.host_profile === context.manifest.host_profile;
+    const sameMode = handover.mode === undefined || (run.mode !== undefined && handover.mode === run.mode);
+    if (run.terminal || (sameProfile && sameMode)) {
+        return startWorkflowRunV2(context, { ...resume, operation: 'resume' });
+    }
+    if (!sameWorkspaceFingerprint(run.workspace_fingerprint, resume.workspaceFingerprint)) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `Workflow run ${run.run_id} was started with workspace fingerprint "${run.workspace_fingerprint}" but "${resume.workspaceFingerprint}" was supplied`);
+    }
+    const handed = await handOverWorkflowRunV2(context, run.run_id, handover);
+    const note = sameProfile
+        ? `run mode changed from ${workflowRunMode(run)} to ${workflowRunMode(handed)}; recorded steps stay`
+        : `run handed over from ${run.host_profile} to ${handed.host_profile}; recorded steps stay`;
+    return { run: handed, note };
+}
+//# sourceMappingURL=workflow-v2-handover.js.map

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

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

package/dist/runtime/workflow-v2-human-response.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Human responses on compiled workflow runs.
+ * Maps the operator's answer through `response_mapping`, applies the negative-answer evidence
+ * rule, and routes; a declined required step carries HUMAN_DECLINED.
+ */
+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 { WorkflowRunDispatch } from './workflow-v2-dispatch.js';
+import type { StepApplication, StepApplicationInput } from './workflow-v2-receipt.js';
+import { type WorkflowHumanResponse } from './workflow-v2-types.js';
+/** Apply the operator's answer to the dispatched human step. */
+export declare function applyHumanResponse(manifest: WorkflowExecutionManifest, run: ProcessRun, dispatch: WorkflowRunDispatch, step: WorkflowStep, response: WorkflowHumanResponse, input: StepApplicationInput): StepApplication;
+//# sourceMappingURL=workflow-v2-human-response.d.ts.map

package/dist/runtime/workflow-v2-human-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-human-response.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-human-response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQrE,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAStF,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,wBAAwB,CAAC;AAuFhC,gEAAgE;AAChE,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,oBAAoB,GAC1B,eAAe,CAmEjB"}