@sapiom/orchestration 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sapiom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @sapiom/orchestration
+
+The versioned public contract for authoring Sapiom orchestrations.
+
+A lean, dependency-light package (types + a small protocol runtime, with a single
+strictly-pinned `zod` peer) shared by three consumers:
+
+- **Customer orchestration definitions** — authored against this package's types and
+  compiled by the build.
+- **The sandbox step-runner** — reads a step's input, builds `ctx`, runs one step.
+- **The engine** — uses the directive guards + manifest schema; it never runs
+  customer code, only validates the pure-data completion payload.
+
+## Install
+
+```sh
+npm install @sapiom/orchestration zod
+```
+
+`zod` is a peer dependency, pinned to the `3.25.x` line (the SDK uses the `zod/v4`
+subpath).
+
+## Authoring surface
+
+```ts
+import { defineOrchestration, defineStep, goto, terminate } from '@sapiom/orchestration';
+
+const start = defineStep({
+  name: 'start',
+  next: ['finish'],
+  async run(input, ctx) {
+    return goto('finish', { greeting: `hello ${input.name}` });
+  },
+});
+
+const finish = defineStep({
+  name: 'finish',
+  next: [],
+  terminal: true,
+  async run() {
+    return terminate({ done: true });
+  },
+});
+
+export const hello = defineOrchestration({
+  name: 'hello',
+  entry: 'start',
+  steps: { start, finish },
+});
+```
+
+A step declares the transitions it may take (`next` / `terminal` / `canFail` /
+`pause`); the `run` return type is derived from those declarations, so an
+undeclared transition is a compile error. The build reads those same declarations
+to render the orchestration graph without executing anything.

package/dist/cjs/build-manifest.d.ts

@@ -0,0 +1,15 @@
+import { type WorkflowManifest } from './manifest.js';
+import type { OrchestrationDefinition } from './workflow.js';
+export declare function buildManifest(def: OrchestrationDefinition, opts: {
+    sdkVersion: string;
+    artifact: {
+        sha256: string;
+        entryFile: string;
+    };
+}): WorkflowManifest;
+export interface GraphValidation {
+    readonly errors: string[];
+    readonly warnings: string[];
+}
+export declare function validateGraph(manifest: WorkflowManifest): GraphValidation;
+export declare function assertValidGraph(manifest: WorkflowManifest): string[];

package/dist/cjs/build-manifest.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildManifest = buildManifest;
+exports.validateGraph = validateGraph;
+exports.assertValidGraph = assertValidGraph;
+const introspection_js_1 = require("./introspection.js");
+const manifest_js_1 = require("./manifest.js");
+function buildManifest(def, opts) {
+    const steps = {};
+    for (const [stepName, step] of Object.entries(def.steps)) {
+        let inputSchema = null;
+        if (step.inputSchema) {
+            const raw = (0, introspection_js_1.zodToJsonSchema)(step.inputSchema);
+            inputSchema = dropDefaultedFromRequired(raw);
+        }
+        steps[stepName] = {
+            timeoutMs: step.timeoutMs ?? null,
+            inputSchema,
+            transitions: transitionsFor(step),
+        };
+    }
+    return {
+        protocol: manifest_js_1.MANIFEST_PROTOCOL,
+        name: def.name,
+        entry: def.entry,
+        sdkVersion: opts.sdkVersion,
+        artifact: opts.artifact,
+        steps,
+    };
+}
+function transitionsFor(step) {
+    const transitions = [];
+    for (const target of step.next ?? []) {
+        transitions.push({ kind: 'continue', target });
+    }
+    if (step.pause) {
+        transitions.push({ kind: 'pause', signal: step.pause.signal, resumeStep: step.pause.resumeStep });
+    }
+    if (step.terminal)
+        transitions.push({ kind: 'terminate' });
+    if (step.canFail)
+        transitions.push({ kind: 'fail' });
+    return transitions;
+}
+function validateGraph(manifest) {
+    const errors = [];
+    const names = new Set(Object.keys(manifest.steps));
+    if (!names.has(manifest.entry)) {
+        errors.push(`entry step '${manifest.entry}' is not in the steps map`);
+    }
+    const forward = buildForwardEdges(manifest, names, errors);
+    const warnings = [];
+    if (names.has(manifest.entry)) {
+        const reachable = bfs([manifest.entry], forward);
+        for (const name of names) {
+            if (!reachable.has(name))
+                warnings.push(`step '${name}' is unreachable from entry '${manifest.entry}'`);
+        }
+    }
+    warnings.push(...terminalReachabilityWarnings(manifest, names, forward));
+    return { errors, warnings };
+}
+function assertValidGraph(manifest) {
+    const { errors, warnings } = validateGraph(manifest);
+    if (errors.length > 0) {
+        throw new Error(`Invalid workflow graph for '${manifest.name}':\n  - ${errors.join('\n  - ')}`);
+    }
+    return warnings;
+}
+function buildForwardEdges(manifest, names, errors) {
+    const forward = new Map();
+    for (const [name, step] of Object.entries(manifest.steps)) {
+        const targets = new Set();
+        for (const t of step.transitions) {
+            if (t.kind === 'continue') {
+                if (names.has(t.target))
+                    targets.add(t.target);
+                else
+                    errors.push(`step '${name}' has a continue target '${t.target}' that is not in the steps map`);
+            }
+            else if (t.kind === 'pause' && names.has(t.resumeStep)) {
+                targets.add(t.resumeStep);
+            }
+        }
+        if (step.transitions.length === 0) {
+            errors.push(`step '${name}' is a dead-end: it declares no transitions (next/terminal/canFail/pause)`);
+        }
+        forward.set(name, targets);
+    }
+    return forward;
+}
+function terminalReachabilityWarnings(manifest, names, forward) {
+    const sinks = Object.entries(manifest.steps)
+        .filter(([, s]) => s.transitions.some((t) => t.kind === 'terminate' || t.kind === 'fail'))
+        .map(([name]) => name);
+    if (sinks.length === 0) {
+        return ['no step can terminate or fail — the workflow has no terminal state'];
+    }
+    const reverse = new Map();
+    for (const name of names)
+        reverse.set(name, new Set());
+    for (const [name, targets] of forward) {
+        for (const t of targets)
+            reverse.get(t)?.add(name);
+    }
+    const canReach = bfs(sinks, reverse);
+    const warnings = [];
+    for (const name of names) {
+        if (!canReach.has(name)) {
+            warnings.push(`step '${name}' cannot reach any terminate/fail (possible unbounded loop or missing terminal)`);
+        }
+    }
+    return warnings;
+}
+function bfs(starts, edges) {
+    const seen = new Set();
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const cur = queue.shift();
+        if (seen.has(cur))
+            continue;
+        seen.add(cur);
+        for (const next of edges.get(cur) ?? [])
+            if (!seen.has(next))
+                queue.push(next);
+    }
+    return seen;
+}
+function dropDefaultedFromRequired(schema) {
+    const required = schema.required;
+    const properties = schema.properties;
+    if (!Array.isArray(required) || !properties || typeof properties !== 'object') {
+        return schema;
+    }
+    const props = properties;
+    const filtered = required.filter((key) => {
+        if (typeof key !== 'string')
+            return true;
+        const prop = props[key];
+        return !(prop && typeof prop === 'object' && 'default' in prop);
+    });
+    if (filtered.length === required.length) {
+        return schema;
+    }
+    return { ...schema, required: filtered };
+}

package/dist/cjs/context.d.ts

@@ -0,0 +1,45 @@
+import type { NextStepDirective } from './directives.js';
+export interface StepLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+export type FinishedStepStatus = 'dispatched' | 'succeeded' | 'failed';
+export interface OrchestrationExecutionContext<TShared extends Record<string, unknown> = Record<string, unknown>> {
+    readonly executionId: string;
+    readonly workflowName: string;
+    readonly organizationId: string | null;
+    readonly tenantId: string | null;
+    readonly input: unknown;
+    readonly shared: TypedContextStore<TShared>;
+    readonly history: readonly StepExecutionRecord[];
+    readonly attempts: number;
+    readonly logger: StepLogger;
+}
+export interface TypedContextStore<TShared extends Record<string, unknown>> {
+    get<K extends keyof TShared>(key: K): TShared[K] | undefined;
+    set<K extends keyof TShared>(key: K, value: TShared[K]): void;
+    has<K extends keyof TShared>(key: K): boolean;
+    snapshot(): Partial<TShared>;
+}
+export interface StepExecutionRecord {
+    readonly stepName: string;
+    readonly attempt: number;
+    readonly status: FinishedStepStatus;
+    readonly input: unknown;
+    readonly output: unknown;
+    readonly error: unknown;
+    readonly nextDirective: NextStepDirective | null;
+    readonly sharedStateAfter: Record<string, unknown> | null;
+    readonly startedAt: Date;
+    readonly finishedAt: Date;
+}
+export declare class InMemoryContextStore<TShared extends Record<string, unknown>> implements TypedContextStore<TShared> {
+    private state;
+    constructor(initial?: Partial<TShared>);
+    get<K extends keyof TShared>(key: K): TShared[K] | undefined;
+    set<K extends keyof TShared>(key: K, value: TShared[K]): void;
+    has<K extends keyof TShared>(key: K): boolean;
+    snapshot(): Partial<TShared>;
+}

package/dist/cjs/context.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryContextStore = void 0;
+class InMemoryContextStore {
+    constructor(initial = {}) {
+        this.state = { ...initial };
+    }
+    get(key) {
+        return this.state[key];
+    }
+    set(key, value) {
+        this.state[key] = value;
+    }
+    has(key) {
+        return key in this.state;
+    }
+    snapshot() {
+        return { ...this.state };
+    }
+}
+exports.InMemoryContextStore = InMemoryContextStore;

package/dist/cjs/directives.d.ts

@@ -0,0 +1,89 @@
+export declare const DIRECTIVE_KIND: {
+    readonly CONTINUE: "continue";
+    readonly RETRY: "retry";
+    readonly PAUSE_UNTIL_SIGNAL: "pause_until_signal";
+    readonly TERMINATE: "terminate";
+    readonly FAIL: "fail";
+};
+export type DirectiveKind = (typeof DIRECTIVE_KIND)[keyof typeof DIRECTIVE_KIND];
+export type NextStepDirective = ContinueDirective | RetryDirective | PauseUntilSignalDirective | TerminateDirective | FailDirective;
+export interface ContinueDirective {
+    readonly kind: typeof DIRECTIVE_KIND.CONTINUE;
+    readonly stepName: string;
+    readonly input?: unknown;
+}
+export interface RetryDirective {
+    readonly kind: typeof DIRECTIVE_KIND.RETRY;
+    readonly delayMs?: number;
+    readonly reason?: string;
+}
+export interface PauseUntilSignalDirective {
+    readonly kind: typeof DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+    readonly signal: {
+        readonly name: string;
+        readonly correlationId?: string;
+    };
+    readonly timeoutMs?: number;
+    readonly resumeStep?: string;
+}
+export interface TerminateDirective {
+    readonly kind: typeof DIRECTIVE_KIND.TERMINATE;
+    readonly reason?: string;
+}
+export interface FailDirective {
+    readonly kind: typeof DIRECTIVE_KIND.FAIL;
+    readonly reason?: string;
+}
+export declare function isContinue(d: NextStepDirective): d is ContinueDirective;
+export declare function isRetry(d: NextStepDirective): d is RetryDirective;
+export declare function isPause(d: NextStepDirective): d is PauseUntilSignalDirective;
+export declare function isTerminate(d: NextStepDirective): d is TerminateDirective;
+export declare function isFail(d: NextStepDirective): d is FailDirective;
+export interface Goto<Target extends string> {
+    readonly kind: typeof DIRECTIVE_KIND.CONTINUE;
+    readonly stepName: Target;
+    readonly input?: unknown;
+}
+export interface Terminate {
+    readonly kind: typeof DIRECTIVE_KIND.TERMINATE;
+    readonly output?: unknown;
+    readonly reason?: string;
+}
+export interface Fail {
+    readonly kind: typeof DIRECTIVE_KIND.FAIL;
+    readonly reason?: string;
+    readonly output?: unknown;
+}
+export interface Pause<Resume extends string> {
+    readonly kind: typeof DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+    readonly signal: {
+        readonly name: string;
+        readonly correlationId?: string;
+    };
+    readonly resumeStep?: Resume;
+    readonly timeoutMs?: number;
+    readonly output?: unknown;
+}
+export interface Retry {
+    readonly kind: typeof DIRECTIVE_KIND.RETRY;
+    readonly delayMs?: number;
+    readonly reason?: string;
+}
+export declare function goto<const Target extends string>(target: Target, output?: unknown): Goto<Target>;
+export declare function terminate(output?: unknown, opts?: {
+    reason?: string;
+}): Terminate;
+export declare function fail(reason?: string, opts?: {
+    output?: unknown;
+}): Fail;
+export declare function pauseUntilSignal<const Resume extends string>(args: {
+    signal: string;
+    resumeStep?: Resume;
+    correlationId?: string;
+    timeoutMs?: number;
+    output?: unknown;
+}): Pause<Resume>;
+export declare function retry(opts?: {
+    delayMs?: number;
+    reason?: string;
+}): Retry;

package/dist/cjs/directives.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTIVE_KIND = void 0;
+exports.isContinue = isContinue;
+exports.isRetry = isRetry;
+exports.isPause = isPause;
+exports.isTerminate = isTerminate;
+exports.isFail = isFail;
+exports.goto = goto;
+exports.terminate = terminate;
+exports.fail = fail;
+exports.pauseUntilSignal = pauseUntilSignal;
+exports.retry = retry;
+exports.DIRECTIVE_KIND = {
+    CONTINUE: 'continue',
+    RETRY: 'retry',
+    PAUSE_UNTIL_SIGNAL: 'pause_until_signal',
+    TERMINATE: 'terminate',
+    FAIL: 'fail',
+};
+function isContinue(d) {
+    return d.kind === exports.DIRECTIVE_KIND.CONTINUE;
+}
+function isRetry(d) {
+    return d.kind === exports.DIRECTIVE_KIND.RETRY;
+}
+function isPause(d) {
+    return d.kind === exports.DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL;
+}
+function isTerminate(d) {
+    return d.kind === exports.DIRECTIVE_KIND.TERMINATE;
+}
+function isFail(d) {
+    return d.kind === exports.DIRECTIVE_KIND.FAIL;
+}
+function goto(target, output) {
+    return { kind: exports.DIRECTIVE_KIND.CONTINUE, stepName: target, input: output };
+}
+function terminate(output, opts) {
+    return { kind: exports.DIRECTIVE_KIND.TERMINATE, output, reason: opts?.reason };
+}
+function fail(reason, opts) {
+    return { kind: exports.DIRECTIVE_KIND.FAIL, reason, output: opts?.output };
+}
+function pauseUntilSignal(args) {
+    return {
+        kind: exports.DIRECTIVE_KIND.PAUSE_UNTIL_SIGNAL,
+        signal: { name: args.signal, correlationId: args.correlationId },
+        resumeStep: args.resumeStep,
+        timeoutMs: args.timeoutMs,
+        output: args.output,
+    };
+}
+function retry(opts) {
+    return { kind: exports.DIRECTIVE_KIND.RETRY, delayMs: opts?.delayMs, reason: opts?.reason };
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,19 @@
+import type { $ZodIssue } from 'zod/v4/core';
+export declare class WorkflowError extends Error {
+    constructor(message: string);
+}
+export declare class StepInputValidationError extends WorkflowError {
+    readonly stepName: string;
+    readonly issues: readonly $ZodIssue[];
+    constructor(stepName: string, issues: readonly $ZodIssue[]);
+}
+export declare class UnknownStepError extends WorkflowError {
+    readonly stepName: string;
+    constructor(stepName: string);
+}
+export declare class DisallowedTransitionError extends WorkflowError {
+    readonly stepName: string;
+    readonly directiveKind: string;
+    readonly target?: string;
+    constructor(stepName: string, directiveKind: string, target?: string);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisallowedTransitionError = exports.UnknownStepError = exports.StepInputValidationError = exports.WorkflowError = void 0;
+class WorkflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowError';
+    }
+}
+exports.WorkflowError = WorkflowError;
+class StepInputValidationError extends WorkflowError {
+    constructor(stepName, issues) {
+        super(`Input for step '${stepName}' failed validation: ${formatIssues(issues)}`);
+        this.name = 'StepInputValidationError';
+        this.stepName = stepName;
+        this.issues = issues;
+    }
+}
+exports.StepInputValidationError = StepInputValidationError;
+function formatIssues(issues) {
+    if (issues.length === 0)
+        return 'unknown validation error';
+    return issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `${path}: ${issue.message}`;
+    })
+        .join('; ');
+}
+class UnknownStepError extends WorkflowError {
+    constructor(stepName) {
+        super(`Unknown step: ${stepName}`);
+        this.name = 'UnknownStepError';
+        this.stepName = stepName;
+    }
+}
+exports.UnknownStepError = UnknownStepError;
+class DisallowedTransitionError extends WorkflowError {
+    constructor(stepName, directiveKind, target) {
+        super(`Step '${stepName}' returned a '${directiveKind}' directive` +
+            (target ? ` to '${target}'` : '') +
+            ` that is not in its declared transitions`);
+        this.name = 'DisallowedTransitionError';
+        this.stepName = stepName;
+        this.directiveKind = directiveKind;
+        this.target = target;
+    }
+}
+exports.DisallowedTransitionError = DisallowedTransitionError;

package/dist/cjs/index.d.ts

@@ -0,0 +1,17 @@
+export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
+export type { DirectiveKind, NextStepDirective, ContinueDirective, RetryDirective, PauseUntilSignalDirective, TerminateDirective, FailDirective, } from './directives.js';
+export { goto, terminate, fail, pauseUntilSignal, retry } from './directives.js';
+export type { Goto, Terminate, Fail, Pause, Retry } from './directives.js';
+export { defineStep } from './step.js';
+export type { Step, StepResult, StepDefinition, Allowed } from './step.js';
+export type { OrchestrationExecutionContext, TypedContextStore, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
+export { InMemoryContextStore } from './context.js';
+export type { OrchestrationDefinition } from './workflow.js';
+export { defineOrchestration, isOrchestrationDefinition, ORCHESTRATION_DEFINITION_BRAND } from './workflow.js';
+export { WorkflowError, UnknownStepError, StepInputValidationError, DisallowedTransitionError } from './errors.js';
+export { zodToJsonSchema, exampleFromJsonSchema, stepInputContract, workflowInputContract } from './introspection.js';
+export type { StepInputContract, WorkflowInputContract } from './introspection.js';
+export { MANIFEST_PROTOCOL, workflowManifestSchema } from './manifest.js';
+export type { WorkflowManifest, WorkflowStepManifest, ManifestTransition } from './manifest.js';
+export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
+export type { GraphValidation } from './build-manifest.js';

package/dist/cjs/index.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidGraph = exports.validateGraph = exports.buildManifest = exports.workflowManifestSchema = exports.MANIFEST_PROTOCOL = exports.workflowInputContract = exports.stepInputContract = exports.exampleFromJsonSchema = exports.zodToJsonSchema = exports.DisallowedTransitionError = exports.StepInputValidationError = exports.UnknownStepError = exports.WorkflowError = exports.ORCHESTRATION_DEFINITION_BRAND = exports.isOrchestrationDefinition = exports.defineOrchestration = exports.InMemoryContextStore = exports.defineStep = exports.retry = exports.pauseUntilSignal = exports.terminate = exports.goto = exports.isFail = exports.isTerminate = exports.isPause = exports.isRetry = exports.isContinue = exports.DIRECTIVE_KIND = void 0;
+var directives_js_1 = require("./directives.js");
+Object.defineProperty(exports, "DIRECTIVE_KIND", { enumerable: true, get: function () { return directives_js_1.DIRECTIVE_KIND; } });
+Object.defineProperty(exports, "isContinue", { enumerable: true, get: function () { return directives_js_1.isContinue; } });
+Object.defineProperty(exports, "isRetry", { enumerable: true, get: function () { return directives_js_1.isRetry; } });
+Object.defineProperty(exports, "isPause", { enumerable: true, get: function () { return directives_js_1.isPause; } });
+Object.defineProperty(exports, "isTerminate", { enumerable: true, get: function () { return directives_js_1.isTerminate; } });
+Object.defineProperty(exports, "isFail", { enumerable: true, get: function () { return directives_js_1.isFail; } });
+var directives_js_2 = require("./directives.js");
+Object.defineProperty(exports, "goto", { enumerable: true, get: function () { return directives_js_2.goto; } });
+Object.defineProperty(exports, "terminate", { enumerable: true, get: function () { return directives_js_2.terminate; } });
+Object.defineProperty(exports, "fail", { enumerable: true, get: function () { return directives_js_2.fail; } });
+Object.defineProperty(exports, "pauseUntilSignal", { enumerable: true, get: function () { return directives_js_2.pauseUntilSignal; } });
+Object.defineProperty(exports, "retry", { enumerable: true, get: function () { return directives_js_2.retry; } });
+var step_js_1 = require("./step.js");
+Object.defineProperty(exports, "defineStep", { enumerable: true, get: function () { return step_js_1.defineStep; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "InMemoryContextStore", { enumerable: true, get: function () { return context_js_1.InMemoryContextStore; } });
+var workflow_js_1 = require("./workflow.js");
+Object.defineProperty(exports, "defineOrchestration", { enumerable: true, get: function () { return workflow_js_1.defineOrchestration; } });
+Object.defineProperty(exports, "isOrchestrationDefinition", { enumerable: true, get: function () { return workflow_js_1.isOrchestrationDefinition; } });
+Object.defineProperty(exports, "ORCHESTRATION_DEFINITION_BRAND", { enumerable: true, get: function () { return workflow_js_1.ORCHESTRATION_DEFINITION_BRAND; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "WorkflowError", { enumerable: true, get: function () { return errors_js_1.WorkflowError; } });
+Object.defineProperty(exports, "UnknownStepError", { enumerable: true, get: function () { return errors_js_1.UnknownStepError; } });
+Object.defineProperty(exports, "StepInputValidationError", { enumerable: true, get: function () { return errors_js_1.StepInputValidationError; } });
+Object.defineProperty(exports, "DisallowedTransitionError", { enumerable: true, get: function () { return errors_js_1.DisallowedTransitionError; } });
+var introspection_js_1 = require("./introspection.js");
+Object.defineProperty(exports, "zodToJsonSchema", { enumerable: true, get: function () { return introspection_js_1.zodToJsonSchema; } });
+Object.defineProperty(exports, "exampleFromJsonSchema", { enumerable: true, get: function () { return introspection_js_1.exampleFromJsonSchema; } });
+Object.defineProperty(exports, "stepInputContract", { enumerable: true, get: function () { return introspection_js_1.stepInputContract; } });
+Object.defineProperty(exports, "workflowInputContract", { enumerable: true, get: function () { return introspection_js_1.workflowInputContract; } });
+var manifest_js_1 = require("./manifest.js");
+Object.defineProperty(exports, "MANIFEST_PROTOCOL", { enumerable: true, get: function () { return manifest_js_1.MANIFEST_PROTOCOL; } });
+Object.defineProperty(exports, "workflowManifestSchema", { enumerable: true, get: function () { return manifest_js_1.workflowManifestSchema; } });
+var build_manifest_js_1 = require("./build-manifest.js");
+Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return build_manifest_js_1.buildManifest; } });
+Object.defineProperty(exports, "validateGraph", { enumerable: true, get: function () { return build_manifest_js_1.validateGraph; } });
+Object.defineProperty(exports, "assertValidGraph", { enumerable: true, get: function () { return build_manifest_js_1.assertValidGraph; } });

package/dist/cjs/introspection.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod/v4';
+import type { OrchestrationDefinition } from './workflow.js';
+export interface StepInputContract {
+    readonly jsonSchema: Record<string, unknown>;
+    readonly example: unknown;
+}
+export type WorkflowInputContract = StepInputContract;
+export declare function zodToJsonSchema(schema: z.ZodType): Record<string, unknown>;
+export declare function stepInputContract(def: OrchestrationDefinition<unknown, Record<string, unknown>>, stepName: string): StepInputContract | null;
+export declare function workflowInputContract(def: OrchestrationDefinition<unknown, Record<string, unknown>>): StepInputContract | null;
+export declare function exampleFromJsonSchema(jsonSchema: Record<string, unknown>): unknown;

package/dist/cjs/introspection.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodToJsonSchema = zodToJsonSchema;
+exports.stepInputContract = stepInputContract;
+exports.workflowInputContract = workflowInputContract;
+exports.exampleFromJsonSchema = exampleFromJsonSchema;
+const v4_1 = require("zod/v4");
+function zodToJsonSchema(schema) {
+    return v4_1.z.toJSONSchema(schema);
+}
+function stepInputContract(def, stepName) {
+    const schema = def.steps[stepName]?.inputSchema;
+    if (!schema)
+        return null;
+    const jsonSchema = zodToJsonSchema(schema);
+    return { jsonSchema, example: exampleFromJsonSchema(jsonSchema) };
+}
+function workflowInputContract(def) {
+    return stepInputContract(def, def.entry);
+}
+function exampleFromJsonSchema(jsonSchema) {
+    const examples = jsonSchema.examples;
+    if (Array.isArray(examples) && examples.length > 0) {
+        return examples[0];
+    }
+    if ('example' in jsonSchema && jsonSchema.example !== undefined) {
+        return jsonSchema.example;
+    }
+    return skeletonFromJsonSchema(jsonSchema);
+}
+function skeletonFromJsonSchema(schema) {
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    const branches = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(branches) && branches.length > 0) {
+        return skeletonFromJsonSchema(branches[0]);
+    }
+    switch (schema.type) {
+        case 'object': {
+            const props = (schema.properties ?? {});
+            const out = {};
+            for (const [key, value] of Object.entries(props)) {
+                out[key] = skeletonFromJsonSchema(value);
+            }
+            return out;
+        }
+        case 'array':
+            return [];
+        case 'string':
+            return '';
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'null':
+            return null;
+        default:
+            return null;
+    }
+}