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

package/dist/runtime/run-trail.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run trail
+ * Groups the rows of a run report by step: every attempt of a step, its notes, assignments and
+ * revisions, and one result per step. Pure; the report stays the single source, so history,
+ * replay and export never derive an outcome anywhere else.
+ * @see STORY-454 STORY-444 STORY-366
+ */
+import { type WorkflowV2ExecutorReport, type WorkflowV2Report, type WorkflowV2ReportField, type WorkflowV2ReportNote, type WorkflowV2ReportRevision } from './workflow-v2-report.js';
+import type { WorkflowStepOutput } from './workflow-v2-types.js';
+export type StepResult = 'completed' | 'failed' | 'skipped';
+/**
+ * The single rule for "did this recorded step pass": a skipped step is skipped; otherwise the
+ * routed slot decides, then the verdict, then the receipt status. A predicate step, or a receipt
+ * whose expected results failed, keeps status `succeeded` but routes through `fail`.
+ */
+export declare function stepResultOf(output: Pick<WorkflowStepOutput, 'status' | 'slot' | 'verdict'>): StepResult;
+export type RunTrailEvidence = Readonly<{
+    /** Which list of the row it came from; with `index` the pair is stable for a given report. */
+    source: 'evidence' | 'artifact';
+    index: number;
+    id?: string;
+    type: string;
+    path?: string;
+    summary?: string;
+    size?: number;
+}>;
+export type RunTrailAttempt = Readonly<{
+    sequence: number;
+    attempt: number;
+    actor: string;
+    actor_name?: string;
+    at: string;
+    /** The receipt's finished_at - started_at, else the gap to the previous event or run start. */
+    took_ms?: number;
+    status: string;
+    outcome: string;
+    exit_code?: number;
+    error_code?: string;
+    host_tool_name: string | null;
+    command?: string;
+    answer?: Readonly<Record<string, unknown>>;
+    executor_report?: WorkflowV2ExecutorReport;
+    fields?: readonly WorkflowV2ReportField[];
+    evidence: readonly RunTrailEvidence[];
+    stdout_preview?: string;
+    stderr_preview?: string;
+    skip?: Readonly<{
+        by: string;
+        reason: string;
+    }>;
+    confirmed_by_operator?: boolean;
+    route?: Readonly<{
+        slot: string;
+        target: string;
+        verdict?: string;
+    }>;
+    result: StepResult;
+}>;
+export type RunTrailAssignment = Readonly<{
+    sequence: number;
+    at: string;
+    by: string;
+    from: string;
+    to: string;
+}>;
+export type RunTrailNote = Readonly<{
+    sequence: number;
+    at: string;
+    by: string;
+}> & WorkflowV2ReportNote;
+export type RunTrailRevision = Readonly<{
+    sequence: number;
+    at: string;
+    by: string;
+}> & WorkflowV2ReportRevision;
+export type RunTrailStep = Readonly<{
+    step_id: string;
+    /** The step's outline label in this run, such as 2 or 1a (DEC-024). */
+    label?: string;
+    kind: string;
+    /** `blocked` = the last attempt ended inconclusive. */
+    result: StepResult | 'blocked';
+    attempts: readonly RunTrailAttempt[];
+    notes: readonly RunTrailNote[];
+    assignments: readonly RunTrailAssignment[];
+    revisions: readonly RunTrailRevision[];
+}>;
+/** A step with no attempt yet that still carries notes, assignments or revisions. */
+export type RunTrailUnreached = Readonly<{
+    step_id: string;
+    label?: string;
+    notes: readonly RunTrailNote[];
+    assignments: readonly RunTrailAssignment[];
+    revisions: readonly RunTrailRevision[];
+}>;
+export type RunTrail = Readonly<{
+    /** In execution order: the order of each step's first event. */
+    steps: readonly RunTrailStep[];
+    /** Read-ahead notes and pre-assignments on steps the run has not attempted. */
+    unreached?: readonly RunTrailUnreached[];
+    finalize?: Readonly<{
+        at: string;
+        verdict: string | null;
+        reason?: string;
+    }>;
+}>;
+/** Groups the report rows by step; notes, assignments and revisions never become steps. */
+export declare function projectRunTrail(report: WorkflowV2Report): RunTrail;
+//# sourceMappingURL=run-trail.d.ts.map

package/dist/runtime/run-trail.d.ts.map

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

package/dist/runtime/run-trail.js

@@ -0,0 +1,187 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run trail
+ * Groups the rows of a run report by step: every attempt of a step, its notes, assignments and
+ * revisions, and one result per step. Pure; the report stays the single source, so history,
+ * replay and export never derive an outcome anywhere else.
+ * @see STORY-454 STORY-444 STORY-366
+ */
+import { isRunEventRow, } from './workflow-v2-report.js';
+/**
+ * The single rule for "did this recorded step pass": a skipped step is skipped; otherwise the
+ * routed slot decides, then the verdict, then the receipt status. A predicate step, or a receipt
+ * whose expected results failed, keeps status `succeeded` but routes through `fail`.
+ */
+export function stepResultOf(output) {
+    if (output.status === 'skipped')
+        return 'skipped';
+    if (output.slot)
+        return output.slot === 'pass' ? 'completed' : 'failed';
+    if (output.verdict)
+        return output.verdict === 'PASS' ? 'completed' : 'failed';
+    return output.status === 'succeeded' ? 'completed' : 'failed';
+}
+const SLOTS = ['pass', 'fail', 'error'];
+function resultOfRow(row) {
+    const slot = row.route_taken?.slot;
+    const verdict = row.route_taken?.verdict ?? row.human_answer?.verdict;
+    return stepResultOf({
+        status: row.skip ? 'skipped' : row.status,
+        ...(slot && SLOTS.includes(slot) ? { slot: slot } : {}),
+        ...(typeof verdict === 'string' ? { verdict } : {}),
+    });
+}
+function evidenceOf(row) {
+    const entry = (source) => (item, index) => ({
+        source,
+        index,
+        ...(item.id ? { id: item.id } : {}),
+        type: item.type,
+        ...(item.path ? { path: item.path } : {}),
+        ...(item.summary ? { summary: item.summary } : {}),
+        ...(typeof item.size === 'number' ? { size: item.size } : {}),
+    });
+    return [...row.evidence.map(entry('evidence')), ...row.artifacts.map(entry('artifact'))];
+}
+function tookMs(row, previousAt) {
+    const started = row.started_at ? Date.parse(row.started_at) : Number.NaN;
+    const finished = row.finished_at ? Date.parse(row.finished_at) : Number.NaN;
+    const span = Number.isNaN(started) || Number.isNaN(finished) ? undefined : finished - started;
+    const gap = Date.parse(row.occurred_at) - Date.parse(previousAt);
+    const took = span ?? gap;
+    return Number.isNaN(took) ? undefined : Math.max(0, took);
+}
+function attemptOf(row, previousAt) {
+    const took = tookMs(row, previousAt);
+    const command = row.arguments.command;
+    const route = row.route_taken;
+    return {
+        sequence: row.sequence,
+        attempt: row.attempt,
+        actor: row.actor,
+        ...(row.actor_name ? { actor_name: row.actor_name } : {}),
+        at: row.occurred_at,
+        ...(took !== undefined ? { took_ms: took } : {}),
+        status: row.status,
+        outcome: row.outcome,
+        ...(row.exit_code !== undefined ? { exit_code: row.exit_code } : {}),
+        ...(row.error_code ? { error_code: row.error_code } : {}),
+        host_tool_name: row.host_tool_name,
+        ...(typeof command === 'string' ? { command } : {}),
+        ...(row.human_answer ? { answer: row.human_answer } : {}),
+        ...(row.executor_report ? { executor_report: row.executor_report } : {}),
+        ...(row.fields ? { fields: row.fields } : {}),
+        evidence: evidenceOf(row),
+        ...(row.stdout_preview ? { stdout_preview: row.stdout_preview } : {}),
+        ...(row.stderr_preview ? { stderr_preview: row.stderr_preview } : {}),
+        ...(row.skip ? { skip: row.skip } : {}),
+        ...(row.confirmed_by_operator ? { confirmed_by_operator: true } : {}),
+        ...(route
+            ? {
+                route: {
+                    slot: route.slot,
+                    target: route.target,
+                    ...(route.verdict ? { verdict: route.verdict } : {}),
+                },
+            }
+            : {}),
+        result: resultOfRow(row),
+    };
+}
+function finishStep(builder) {
+    const last = builder.attempts[builder.attempts.length - 1];
+    const blocked = last?.outcome.toLowerCase() === 'inconclusive';
+    return { ...builder, result: blocked ? 'blocked' : (last?.result ?? 'failed') };
+}
+/** Groups the report rows by step; notes, assignments and revisions never become steps. */
+export function projectRunTrail(report) {
+    const rows = [...report.steps].sort((left, right) => left.sequence - right.sequence);
+    const builders = new Map();
+    const events = [];
+    let finalize;
+    let previousAt = report.run.created_at;
+    for (const row of rows) {
+        if (row.kind === 'finalize') {
+            finalize = {
+                at: row.occurred_at,
+                verdict: report.verdict,
+                ...(report.reason ? { reason: report.reason } : {}),
+            };
+        }
+        else if (isRunEventRow(row)) {
+            events.push(row);
+        }
+        else {
+            let builder = builders.get(row.step_id);
+            if (!builder) {
+                builder = {
+                    step_id: row.step_id,
+                    ...(row.label ? { label: row.label } : {}),
+                    kind: row.kind,
+                    attempts: [],
+                    notes: [],
+                    assignments: [],
+                    revisions: [],
+                };
+                builders.set(row.step_id, builder);
+            }
+            builder.attempts.push(attemptOf(row, previousAt));
+        }
+        previousAt = row.occurred_at;
+    }
+    const unreached = new Map();
+    for (const row of events)
+        attach(builders, unreached, row);
+    return {
+        steps: [...builders.values()].map(finishStep),
+        ...(unreached.size > 0
+            ? {
+                unreached: [...unreached.values()].map(({ step_id, label, notes, assignments, revisions }) => ({
+                    step_id,
+                    ...(label ? { label } : {}),
+                    notes,
+                    assignments,
+                    revisions,
+                })),
+            }
+            : {}),
+        ...(finalize ? { finalize } : {}),
+    };
+}
+function attach(builders, unreached, row) {
+    const target = (id, label) => {
+        const existing = builders.get(id) ?? unreached.get(id);
+        if (existing)
+            return existing;
+        const created = {
+            step_id: id,
+            ...(label ? { label } : {}),
+            kind: '',
+            attempts: [],
+            notes: [],
+            assignments: [],
+            revisions: [],
+        };
+        unreached.set(id, created);
+        return created;
+    };
+    const stamp = { sequence: row.sequence, at: row.occurred_at, by: row.actor_name ?? row.actor };
+    if (row.note)
+        target(row.step_id, row.label).notes.push({ ...stamp, ...row.note });
+    if (row.assignment) {
+        target(row.step_id, row.label).assignments.push({ ...stamp, ...row.assignment });
+    }
+    // A revision names no single step: it belongs to every step it added, changed or removed.
+    if (row.revision) {
+        const named = new Set([
+            ...row.revision.added,
+            ...row.revision.changed,
+            ...row.revision.removed,
+        ]);
+        for (const id of named)
+            target(id).revisions.push({ ...stamp, ...row.revision });
+    }
+}
+//# sourceMappingURL=run-trail.js.map

package/dist/runtime/run-trail.js.map

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

package/dist/runtime/state-machine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Runtime state machine
+ * Applies declared events and guards to a process run without persistence.
+ * Storage and workflow-item concerns stay in their respective boundaries.
+ */
+import { type ProcessDefinition, type ProcessEvent, type ProcessRun, RuntimeActor } from './index.js';
+export type RuntimeGuardContext = Readonly<{
+    payload: Readonly<Record<string, unknown>>;
+    run: ProcessRun;
+}>;
+export type RuntimeTransitionInput = Readonly<{
+    actor: RuntimeActor;
+    event: string;
+    idempotencyKey?: string;
+    payload?: Readonly<Record<string, unknown>>;
+    occurredAt?: string;
+}>;
+export type RuntimeTransitionResult = Readonly<{
+    run: ProcessRun;
+    event: ProcessEvent;
+}>;
+export declare class RuntimeTransitionError extends Error {
+    readonly code: 'INVALID_STATE' | 'UNKNOWN_EVENT' | 'GUARD_FAILED' | 'INVALID_ACTOR';
+    constructor(code: RuntimeTransitionError['code'], message: string);
+}
+export declare function transitionRun(definition: ProcessDefinition, run: ProcessRun, input: RuntimeTransitionInput): RuntimeTransitionResult;
+//# sourceMappingURL=state-machine.d.ts.map

package/dist/runtime/state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.d.ts","sourceRoot":"","sources":["../../src/runtime/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,GAAG,EAAE,UAAU,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,GAAG,EAAE,UAAU,CAAC;IAChB,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC,CAAC;AAEH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAgB,IAAI,EAAE,eAAe,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;IAE3F,YAAmB,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAIvE;CACF;AAgJD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,iBAAiB,EAC7B,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,sBAAsB,GAC5B,uBAAuB,CAgDzB"}

package/dist/runtime/state-machine.js

@@ -0,0 +1,170 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Runtime state machine
+ * Applies declared events and guards to a process run without persistence.
+ * Storage and workflow-item concerns stay in their respective boundaries.
+ */
+import { RuntimeActor, } from './index.js';
+export class RuntimeTransitionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RuntimeTransitionError';
+        this.code = code;
+    }
+}
+function hasPathValue(value, path) {
+    return path.split('.').reduce((current, key) => {
+        if (typeof current !== 'object' || current === null || !(key in current)) {
+            return undefined;
+        }
+        return current[key];
+    }, value);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function renderRuntimeValue(value, run) {
+    const definitionItemIdPlaceholder = '$' + '{DEFINITION_ITEM_ID}';
+    const runIdPlaceholder = '$' + '{RUN_ID}';
+    if (typeof value === 'string') {
+        return value
+            .replaceAll(definitionItemIdPlaceholder, run.definition_id)
+            .replaceAll(runIdPlaceholder, run.run_id);
+    }
+    if (Array.isArray(value))
+        return value.map((entry) => renderRuntimeValue(entry, run));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, renderRuntimeValue(nested, run)]));
+    }
+    return value;
+}
+function containsUnredactedSecret(value, key = '') {
+    if (Array.isArray(value))
+        return value.some((entry) => containsUnredactedSecret(entry));
+    if (value && typeof value === 'object') {
+        return Object.entries(value).some(([nestedKey, nested]) => containsUnredactedSecret(nested, nestedKey));
+    }
+    if (typeof value !== 'string')
+        return false;
+    if (/(authorization|password|secret|token|credential|private.?key)/i.test(key)) {
+        return value !== '[REDACTED]';
+    }
+    return /\bbearer\s+(?!\[REDACTED\])\S+/i.test(value);
+}
+function evaluateMcpToolReceipt(parameters, context) {
+    const expectedToolName = parameters.tool_name;
+    const expectedArguments = renderRuntimeValue(parameters.arguments ?? {}, context.run);
+    const toolName = context.payload.tool_name;
+    const argumentsValue = context.payload.arguments;
+    const result = context.payload.result;
+    if (typeof expectedToolName !== 'string' ||
+        toolName !== expectedToolName ||
+        stableJson(argumentsValue) !== stableJson(expectedArguments) ||
+        typeof result !== 'object' ||
+        result === null ||
+        containsUnredactedSecret(result)) {
+        return false;
+    }
+    const successPath = parameters.success_path;
+    if (typeof successPath === 'string') {
+        if (hasPathValue(result, successPath) !== parameters.success_equals)
+            return false;
+    }
+    const requiredPaths = parameters.required_paths;
+    if (Array.isArray(requiredPaths) &&
+        requiredPaths.some((path) => typeof path !== 'string' || hasPathValue(result, path) === undefined)) {
+        return false;
+    }
+    const equals = parameters.equals;
+    if (equals && typeof equals === 'object' && !Array.isArray(equals)) {
+        for (const [path, expected] of Object.entries(equals)) {
+            if (stableJson(hasPathValue(result, path)) !==
+                stableJson(renderRuntimeValue(expected, context.run))) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function evaluateGuard(guard, context) {
+    // Guards inspect the current run and submitted evidence; they never mutate either value.
+    const path = typeof guard.parameters.path === 'string' ? guard.parameters.path : '';
+    const value = path ? hasPathValue(context.payload, path) : undefined;
+    switch (guard.kind) {
+        case 'always':
+            return true;
+        case 'payload-present':
+            return value !== undefined;
+        case 'payload-equals':
+            return value === guard.parameters.value;
+        case 'state-equals':
+            return context.run.state === guard.parameters.value;
+        case 'mcp-tool-receipt':
+            return evaluateMcpToolReceipt(guard.parameters, context);
+        default:
+            return false;
+    }
+}
+function createEvent(run, input, toState, payload) {
+    return {
+        schema_version: run.schema_version,
+        event_id: crypto.randomUUID(),
+        run_id: run.run_id,
+        sequence: run.version,
+        type: input.event,
+        occurred_at: input.occurredAt ?? new Date().toISOString(),
+        from_state: run.state,
+        to_state: toState,
+        actor: input.actor,
+        idempotency_key: input.idempotencyKey,
+        payload,
+    };
+}
+export function transitionRun(definition, run, input) {
+    // BUG-132: actor reaches the runtime untyped from the tool boundary, and an event without a
+    // valid one would be written and then make the whole run unreadable.
+    if (!RuntimeActor.safeParse(input.actor).success) {
+        throw new RuntimeTransitionError('INVALID_ACTOR', `actor is required and must be "agent", "human" or "system", not ${JSON.stringify(input.actor) ?? 'undefined'}`);
+    }
+    // Callers submit an event; the declared transition determines the target state.
+    if (!definition.states[run.state]) {
+        throw new RuntimeTransitionError('INVALID_STATE', `Unknown runtime state: ${run.state}`);
+    }
+    const transition = definition.transitions.find((candidate) => candidate.event === input.event && candidate.from.includes(run.state));
+    if (!transition) {
+        throw new RuntimeTransitionError('UNKNOWN_EVENT', `Event ${input.event} is not declared for state ${run.state}`);
+    }
+    const payload = input.payload ?? {};
+    const context = { payload, run };
+    if (!transition.guards.every((guard) => evaluateGuard(guard, context))) {
+        throw new RuntimeTransitionError('GUARD_FAILED', `Guards rejected event ${input.event}`);
+    }
+    const stateDefinition = definition.states[transition.to];
+    if (!stateDefinition) {
+        throw new RuntimeTransitionError('INVALID_STATE', `Unknown target state: ${transition.to}`);
+    }
+    const updatedAt = input.occurredAt ?? new Date().toISOString();
+    const nextRun = {
+        ...run,
+        state: transition.to,
+        updated_at: updatedAt,
+        version: run.version + 1,
+        terminal: stateDefinition.terminal,
+    };
+    return {
+        run: nextRun,
+        event: createEvent(run, input, transition.to, payload),
+    };
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/runtime/state-machine.js.map

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

package/dist/runtime/workflow-contract.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Generic workflow execution contract
+ * Adapts validated TASK definitions to the neutral runtime state machine.
+ * This layer coordinates start, resume, record, and terminal finalization.
+ */
+import { type ProcessRun, type RuntimeActor } from './index.js';
+import { type RunStore } from './run-store.js';
+export type WorkflowRunOperation = 'new' | 'resume';
+export type LoadedWorkflowDefinition = Readonly<{
+    item: Readonly<{
+        metadata: Readonly<{
+            id: string;
+        }>;
+    }>;
+    definition: Readonly<{
+        schema_version: string;
+        process_type: string;
+        states: Readonly<Record<string, Readonly<{
+            terminal?: boolean;
+        }>>>;
+        initial: string;
+        transitions: readonly unknown[];
+        [key: string]: unknown;
+    }>;
+    definitionRevision: string;
+    definitionDigest: string;
+}>;
+export type WorkflowRunStartInput = Readonly<{
+    operation: WorkflowRunOperation;
+    workspaceFingerprint: string;
+    runId?: string;
+}>;
+export type WorkflowRunRecordInput = Readonly<{
+    event: string;
+    actor: RuntimeActor;
+    idempotencyKey?: string;
+    payload?: Readonly<Record<string, unknown>>;
+    expectedVersion: number;
+    occurredAt?: string;
+}>;
+export type WorkflowRunFinalizeInput = Readonly<{
+    event: string;
+    actor: RuntimeActor;
+    idempotencyKey?: string;
+    payload?: Readonly<Record<string, unknown>>;
+    expectedVersion: number;
+    occurredAt?: string;
+}>;
+export declare class WorkflowRunContractError extends Error {
+    readonly code: 'INVALID_OPERATION' | 'MISSING_RUN_ID' | 'NOT_TERMINAL' | 'WORKSPACE_DRIFT' | 'IDEMPOTENCY_CONFLICT' | 'INPUT_INVALID';
+    constructor(code: WorkflowRunContractError['code'], message: string);
+}
+export declare function workflowRunStart(loaded: LoadedWorkflowDefinition, store: RunStore, input: WorkflowRunStartInput, occurredAt?: string): Promise<ProcessRun>;
+export declare function workflowRunGet(store: RunStore, runId: string): Promise<ProcessRun>;
+export declare function workflowRunRecord(loaded: LoadedWorkflowDefinition, store: RunStore, runId: string, input: WorkflowRunRecordInput): Promise<ProcessRun>;
+export declare function workflowRunFinalize(loaded: LoadedWorkflowDefinition, store: RunStore, runId: string, input: WorkflowRunFinalizeInput): Promise<ProcessRun>;
+//# sourceMappingURL=workflow-contract.d.ts.map

package/dist/runtime/workflow-contract.d.ts.map

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