@intx/workflow-host 0.2.2

package/dist/adapters/blob-substrate.js

@@ -0,0 +1,140 @@
+// Production `WorkflowRuntimeEnv.BlobSubstrate` adapter.
+//
+// Mirrors the in-memory `runlocal/blob-substrate.ts` ref shape so the
+// runtime body's `ref` contract is symmetric across substrates:
+//
+//   - `inline:<encoded-json>` for values whose JSON-stringified form
+//     fits inside the inline threshold (1 MiB by default). The ref's
+//     whole body after the `inline:` prefix is the verbatim JSON
+//     payload; `resolveRef` parses it back. Storing the encoded JSON
+//     instead of a substrate write avoids a commit per small output.
+//   - `blob:<sha256-prefix>` for values above the threshold. The
+//     encoded bytes land at `runs/<runId>/blobs/<sha256-prefix>` on
+//     the workflow-run repo via `writeTreePreservingPrefix`;
+//     `resolveRef` reads them back from the repo directory.
+//
+// Constructed per-run -- the `runId` is part of the on-disk path and
+// each run gets its own adapter. The sibling repo-store adapter is
+// per-deployment because every run shares the same events ref; the
+// blob-substrate's per-run path means the closure carries `runId`
+// rather than re-deriving it on every call.
+//
+// Error translation matches the sibling repo-store adapter: the
+// substrate's `path_violation:` prefix is stripped so the runtime sees
+// a clean reason; every other error propagates unchanged.
+//
+// `ephemeral: false` -- blob refs survive instance turnover because
+// they resolve back to bytes on the workflow-run repo.
+import { hexEncode } from "@intx/types";
+const ONE_MIB = 1024 * 1024;
+const SHA256_PREFIX_BYTES = 32;
+const RUNS_PREFIX = "runs";
+const BLOBS_DIR = "blobs";
+const INLINE_PREFIX = "inline:";
+const BLOB_PREFIX = "blob:";
+/**
+ * Construct the production `WorkflowRuntimeEnv.BlobSubstrate` adapter
+ * for the supplied run. The returned object satisfies the runtime-env
+ * interface; substrate handle, principal, repo routing, and run id
+ * live in closure.
+ */
+export function createWorkflowRunBlobSubstrate(opts) {
+    const inlineMax = opts.inlineMaxBytes ?? ONE_MIB;
+    return {
+        ephemeral: false,
+        async recordOutput(stepId, attempt, value) {
+            const encoded = JSON.stringify(value);
+            if (encoded === undefined) {
+                // Mirrors the in-memory adapter: JSON.stringify returns
+                // undefined for undefined, functions, and symbols. Surfacing
+                // it as an error keeps the contract honest -- silent coercion
+                // to null destroys information about the actual step output.
+                throw new Error(`step ${stepId} attempt ${String(attempt)} produced an output the blob substrate cannot serialize (typeof ${typeof value})`);
+            }
+            if (encoded.length <= inlineMax) {
+                return { ref: `${INLINE_PREFIX}${encoded}` };
+            }
+            const bytes = new TextEncoder().encode(encoded);
+            const key = await sha256Hex(bytes);
+            await writeBlob(opts, key, bytes);
+            return { ref: `${BLOB_PREFIX}${key}` };
+        },
+        async resolveRef(ref) {
+            if (ref.startsWith(INLINE_PREFIX)) {
+                return JSON.parse(ref.slice(INLINE_PREFIX.length));
+            }
+            if (ref.startsWith(BLOB_PREFIX)) {
+                const key = ref.slice(BLOB_PREFIX.length);
+                const bytes = await readBlob(opts, key);
+                return JSON.parse(new TextDecoder().decode(bytes));
+            }
+            throw new Error(`unrecognized ref ${ref}`);
+        },
+    };
+}
+function blobsPrefixFor(runId) {
+    return `${RUNS_PREFIX}/${runId}/${BLOBS_DIR}/`;
+}
+async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", 
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- ArrayBuffer-backed at the call site; Web Crypto's BufferSource type rejects Uint8Array<ArrayBufferLike> under TS 5.9 (microsoft/TypeScript#62240)
+    bytes);
+    const hex = hexEncode(new Uint8Array(digest));
+    // A SHA-256 hex string is always 64 chars, so this is unreachable
+    // today; kept as a cheap invariant pinning the on-disk blob-key
+    // shape should the digest width ever change.
+    if (hex.length !== SHA256_PREFIX_BYTES * 2) {
+        throw new Error(`unexpected sha256 hex length ${String(hex.length)}; expected ${String(SHA256_PREFIX_BYTES * 2)}`);
+    }
+    return hex;
+}
+async function writeBlob(opts, key, bytes) {
+    const prefix = blobsPrefixFor(opts.runId);
+    try {
+        await opts.substrate.writeTreePreservingPrefix(opts.principal, opts.repoId, opts.ref, {
+            preservePrefix: prefix,
+            merge: async (existing) => {
+                const files = {};
+                for (const [k, v] of existing)
+                    files[k] = v;
+                // Content-addressed by sha256: a re-recorded value with the
+                // same bytes lands at the same path. Overwriting the entry
+                // with identical bytes is harmless because the workflow-run
+                // kind handler's append-only checks compare prior-vs-
+                // prospective bytes and accept matches.
+                files[`${prefix}${key}`] = bytes;
+                return files;
+            },
+            message: `record blob ${key} for run ${opts.runId}`,
+        });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (message.startsWith("path_violation: ")) {
+            const reason = message.slice("path_violation: ".length);
+            throw new Error(reason, { cause });
+        }
+        throw cause;
+    }
+}
+async function readBlob(opts, key) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dir = opts.substrate.getRepoDir(opts.repoId);
+    const blobPath = path.join(dir, RUNS_PREFIX, opts.runId, BLOBS_DIR, key);
+    try {
+        return await fs.readFile(blobPath);
+    }
+    catch (cause) {
+        if (isErrnoNotFound(cause)) {
+            throw new Error(`workflow-runtime: blob ${key} for run ${opts.runId} not found on disk`, { cause });
+        }
+        throw cause;
+    }
+}
+function isErrnoNotFound(cause) {
+    if (cause === null || typeof cause !== "object")
+        return false;
+    const code = cause.code;
+    return code === "ENOENT";
+}

package/dist/adapters/repo-store.d.ts

@@ -0,0 +1,39 @@
+import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import type { RepoStore } from "@intx/workflow";
+export type WorkflowRunRepoStoreOpts = {
+    /**
+     * Substrate handle the adapter reads from and writes to. The caller
+     * wires this against the substrate's registered workflow-run kind
+     * handler -- the adapter's writes land under
+     * `runs/<runId>/events/<seq>.json` and the handler's `validatePush`
+     * is the layer that catches structural rejections.
+     */
+    substrate: SubstrateRepoStore;
+    /**
+     * Workflow-run repo identifying the owning deployment. A single
+     * adapter instance services every run inside this deployment; the
+     * adapter's `read` / `append` / `subscribe` calls take a `runId` to
+     * route within the repo.
+     */
+    repoId: RepoId;
+    /**
+     * Principal the adapter presents to the substrate. The workflow-run
+     * kind handler accepts a workflow-process principal scoped to the
+     * deployment as the runtime body's writer; that is the principal
+     * shape the production wiring supplies.
+     */
+    principal: Principal;
+    /**
+     * Events ref the adapter reads from and writes to. The workflow-run
+     * repo layout pins all `runs/<runId>/events/` blobs under a single
+     * moving ref. Callers typically supply `"refs/heads/main"`.
+     */
+    ref: string;
+};
+/**
+ * Construct the production `WorkflowRuntimeEnv.RepoStore` adapter for
+ * the supplied deployment. The returned object satisfies the
+ * runtime-env interface; the substrate handle and per-deployment
+ * routing live in closure.
+ */
+export declare function createWorkflowRunRepoStore(opts: WorkflowRunRepoStoreOpts): RepoStore;

package/dist/adapters/repo-store.js

@@ -0,0 +1,344 @@
+// Production `WorkflowRuntimeEnv.RepoStore` adapter.
+//
+// The runtime body sees the runtime-env shape: `read(runId)`,
+// `append(runId, event)`, `subscribe(runId, opts)`. This adapter
+// translates each call into operations against the workflow-run
+// substrate (`@intx/hub-sessions` RepoStore plus the workflow-run kind
+// handler) for a single deployment's workflow-run repo.
+//
+// On-disk envelope shape: every event blob committed under
+// `runs/<runId>/events/<seq>.json` carries `{ seq, type, ...rest }`
+// where `type` is the workflow-event discriminator (matching the
+// substrate's `subscribeKind` `type` field and the workflow-run kind
+// handler's `EventEnvelope` contract). The state-machine `WorkflowEvent`
+// uses `kind` as its discriminator; the adapter performs the
+// `kind` <-> `type` translation at the substrate boundary so the
+// runtime body and state machine never see a mismatched discriminator.
+//
+// Append-result error translation (interface-decisions Bonus 1):
+//   - `seq_conflict`: the caller supplied an `event.seq` that does not
+//     match the seq computed from the substrate's prior tree. The
+//     runtime body is the single writer to the run's event log; a
+//     mismatch here means a parallel writer landed in between the
+//     caller's read and the merge under the substrate's per-repo lock.
+//     Translated into a thrown Error naming the run and the diverging
+//     seqs. No retries: the runtime decides higher up.
+//   - `validate_failed`: the substrate's kind handler rejected the
+//     prospective tree via `validatePush`. Translated into a thrown
+//     Error carrying the handler's `reason` text. No retries.
+import { type } from "arktype";
+import { subscribeKind, WORKFLOW_RUN_EVENTS_FILE, splitCombinedEventLog, } from "@intx/hub-sessions/substrate";
+const RUNS_PREFIX = "runs";
+const EVENTS_DIR = "events";
+const EVENT_FILENAME_RE = /^(0|[1-9][0-9]*)\.json$/;
+/**
+ * On-disk envelope shape committed under
+ * `runs/<runId>/events/<seq>.json`. Carries the seq cross-check the
+ * workflow-run kind handler validates against the filename, the `type`
+ * discriminator the substrate's `subscribeKind` filters on, and an
+ * open object for the rest of the workflow-event fields. Switching
+ * from the catch-all `"+": "ignore"` to `"+": "delete"` would strip
+ * unknown fields; the adapter wants them preserved so the round-trip
+ * back into `WorkflowEvent` carries every state-machine field.
+ */
+const OnDiskEnvelope = type({
+    seq: "number >= 0",
+    type: "string",
+    "[string]": "unknown",
+});
+/**
+ * Every state-machine `WorkflowEvent` kind. Used to populate
+ * `subscribeKind`'s `kinds` filter so the substrate's typed tail
+ * surfaces every event blob the runtime cares about (the substrate
+ * helper filters on the `type` field; an empty filter would yield
+ * nothing).
+ */
+const ALL_WORKFLOW_EVENT_TYPES = [
+    "RunStarted",
+    "StepStarted",
+    "StepCompleted",
+    "StepFailed",
+    "AttemptScheduled",
+    "SignalAwaited",
+    "SignalReceived",
+    "TimerSet",
+    "TimerFired",
+    "CancelRequested",
+    "CancelPropagated",
+    "ChildSpawned",
+    "ChildCancelRequested",
+    "ChildCompleted",
+    "RunCompleted",
+    "RunFailed",
+    "RunCancelled",
+];
+/**
+ * Construct the production `WorkflowRuntimeEnv.RepoStore` adapter for
+ * the supplied deployment. The returned object satisfies the
+ * runtime-env interface; the substrate handle and per-deployment
+ * routing live in closure.
+ */
+export function createWorkflowRunRepoStore(opts) {
+    return {
+        async read(runId) {
+            return readAllEventsForRun(opts, runId);
+        },
+        async append(runId, event) {
+            await appendBatchEvents(opts, runId, [event]);
+        },
+        async appendBatch(runId, events) {
+            await appendBatchEvents(opts, runId, events);
+        },
+        subscribe(runId, subOpts) {
+            return subscribeRun(opts, runId, subOpts);
+        },
+    };
+}
+async function readAllEventsForRun(opts, runId) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dir = opts.substrate.getRepoDir(opts.repoId);
+    const runDir = path.join(dir, RUNS_PREFIX, runId);
+    const entries = [];
+    // A terminated run is sealed into a single combined `events.jsonl`; an
+    // in-flight run keeps per-event `events/<seq>.json` files. The combined
+    // file's presence selects the read path; the two forms are mutually
+    // exclusive in a run directory.
+    let combinedRaw;
+    try {
+        combinedRaw = await fs.readFile(path.join(runDir, WORKFLOW_RUN_EVENTS_FILE), "utf8");
+    }
+    catch (cause) {
+        if (!isErrnoNotFound(cause))
+            throw cause;
+        combinedRaw = null;
+    }
+    if (combinedRaw !== null) {
+        // The two forms are mutually exclusive; a run carrying both is a
+        // botched seal, and silently reading only the combined file would
+        // mask it, so surface it instead.
+        let perEventPresent = false;
+        try {
+            await fs.access(path.join(runDir, EVENTS_DIR));
+            perEventPresent = true;
+        }
+        catch (cause) {
+            if (!isErrnoNotFound(cause))
+                throw cause;
+        }
+        if (perEventPresent) {
+            throw new Error(`workflow-runtime: run ${runId} carries both a combined ${WORKFLOW_RUN_EVENTS_FILE} and a per-event ${EVENTS_DIR}/ directory`);
+        }
+        for (const line of splitCombinedEventLog(combinedRaw)) {
+            entries.push(parseEventEnvelope(line, `${opts.repoId.id}/${runId}/${WORKFLOW_RUN_EVENTS_FILE}`));
+        }
+        entries.sort((a, b) => a.seq - b.seq);
+        return entries.map((e) => e.event);
+    }
+    const eventsDir = path.join(runDir, EVENTS_DIR);
+    let filenames;
+    try {
+        filenames = await fs.readdir(eventsDir);
+    }
+    catch (cause) {
+        if (isErrnoNotFound(cause))
+            return [];
+        throw cause;
+    }
+    for (const name of filenames) {
+        const match = EVENT_FILENAME_RE.exec(name);
+        if (match === null)
+            continue;
+        const seqStr = match[1];
+        if (seqStr === undefined)
+            continue;
+        const seqFromName = Number.parseInt(seqStr, 10);
+        const raw = await fs.readFile(path.join(eventsDir, name), "utf8");
+        const source = `${opts.repoId.id}/${runId}/${EVENTS_DIR}/${name}`;
+        const entry = parseEventEnvelope(raw, source);
+        if (entry.seq !== seqFromName) {
+            throw new Error(`workflow-runtime: read ${source} body.seq ${String(entry.seq)} does not match filename seq ${String(seqFromName)}`);
+        }
+        entries.push(entry);
+    }
+    entries.sort((a, b) => a.seq - b.seq);
+    return entries.map((e) => e.event);
+}
+// Parse one on-disk event envelope -- a per-event file's bytes or one line
+// of a combined `events.jsonl` (which holds the same bytes verbatim). The
+// per-event caller additionally cross-checks the seq against the filename;
+// the combined form carries the seq only in the body.
+function parseEventEnvelope(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error(`workflow-runtime: read ${source} is not valid JSON`, {
+            cause,
+        });
+    }
+    const envelope = OnDiskEnvelope(parsed);
+    if (envelope instanceof type.errors) {
+        throw new Error(`workflow-runtime: read ${source} envelope invalid: ${envelope.summary}`);
+    }
+    return { seq: envelope.seq, event: onDiskToWorkflowEvent(envelope) };
+}
+/**
+ * Translate a validated on-disk envelope (`{seq, type, ...rest}`) into
+ * the state-machine `WorkflowEvent` shape (`{seq, kind, ...rest}`).
+ * The state-machine `WorkflowEvent` discriminated union is narrowed by
+ * the next layer (`applyEvent` / `resumeFromLog`); the adapter
+ * surfaces a structural object that carries the discriminator under
+ * its state-machine field name without re-asserting through the
+ * discriminated union here.
+ */
+function onDiskToWorkflowEvent(envelope) {
+    const { seq, type: typeStr, ...rest } = envelope;
+    const built = { ...rest, kind: typeStr, seq };
+    // The runtime body and state machine read events through
+    // `WorkflowEvent`'s `kind` discriminator; the adapter has confirmed
+    // the on-disk envelope carries a string `type` and integer `seq`, so
+    // the constructed object satisfies the discriminator contract. The
+    // narrow against the discriminated-union variants lives in the
+    // state machine (`applyEvent` / `resumeFromLog`), not here -- the
+    // in-memory store in `runlocal` follows the same pattern and stores
+    // `WorkflowEvent` objects opaquely. Synthesizing a 17-variant
+    // arktype validator at the adapter layer would duplicate the
+    // state-machine narrow.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- WorkflowEvent's discriminated union is narrowed downstream by the state machine; no runtime validator at this layer
+    return built;
+}
+/**
+ * Translate a state-machine `WorkflowEvent` (using `kind` as the
+ * discriminator) into the on-disk envelope shape (`{seq, type,
+ * ...rest}`) the workflow-run kind handler validates and the
+ * substrate's `subscribeKind` helper filters on.
+ */
+function workflowEventToOnDisk(event, seq) {
+    const { kind, seq: _eventSeq, ...rest } = event;
+    return { seq, type: kind, ...rest };
+}
+/**
+ * Append one or more contiguous events to a run's event log in a
+ * SINGLE durable commit. The events must carry strictly-monotonic,
+ * gap-free seqs continuing the prior tree's tip (the first event's seq
+ * is `priorLastSeq + 1`); the merge writes every `events/<seq>.json`
+ * blob into one `writeTreePreservingPrefix` tree-rewrite, so N events
+ * cost one tree-rewrite + one ref-advance instead of N. An empty
+ * `events` array is a no-op. The seq-contiguity check is performed
+ * against the supplied events themselves so a caller that buffered a
+ * gap surfaces a single-writer conflict rather than a silent gap in
+ * the tree.
+ */
+async function appendBatchEvents(opts, runId, events) {
+    if (events.length === 0)
+        return;
+    const prefix = `${RUNS_PREFIX}/${runId}/${EVENTS_DIR}/`;
+    const firstEvent = events[0];
+    if (firstEvent === undefined)
+        throw new Error("unreachable");
+    const lastEvent = events[events.length - 1];
+    if (lastEvent === undefined)
+        throw new Error("unreachable");
+    let seqConflict = null;
+    try {
+        await opts.substrate.writeTreePreservingPrefix(opts.principal, opts.repoId, opts.ref, {
+            preservePrefix: prefix,
+            merge: async (existing) => {
+                // The runtime body emits events at `state.lastSeq + 1` and
+                // `emptyState.lastSeq = 0`, so the first append on an empty
+                // events tree carries seq=1. The adapter mirrors that
+                // convention: the prior tree's lastSeq is the maximum seq
+                // observed under the prefix, or 0 when no events exist yet;
+                // the expected next seq is `priorLastSeq + 1`. Every event
+                // in the batch must continue contiguously from there.
+                let priorLastSeq = 0;
+                for (const filepath of existing.keys()) {
+                    const name = filepath.slice(prefix.length);
+                    const match = EVENT_FILENAME_RE.exec(name);
+                    if (match === null)
+                        continue;
+                    const seqStr = match[1];
+                    if (seqStr === undefined)
+                        continue;
+                    const seq = Number.parseInt(seqStr, 10);
+                    if (seq > priorLastSeq)
+                        priorLastSeq = seq;
+                }
+                const files = {};
+                for (const [k, v] of existing)
+                    files[k] = v;
+                let expectedSeq = priorLastSeq + 1;
+                for (const event of events) {
+                    if (event.seq !== expectedSeq) {
+                        // Capture the divergence and return an unchanged tree so
+                        // the substrate's commit short-circuits (the kind handler
+                        // accepts an empty diff against the same prior tree); the
+                        // throw happens outside the merge callback so the
+                        // adapter's error carries the full context. The empty
+                        // tree returned here preserves the existing prefix
+                        // bit-for-bit so the rollback path inside the substrate
+                        // does not need to fire.
+                        seqConflict = { expected: expectedSeq, supplied: event.seq };
+                        const passthrough = {};
+                        for (const [k, v] of existing)
+                            passthrough[k] = v;
+                        return passthrough;
+                    }
+                    const onDisk = workflowEventToOnDisk(event, expectedSeq);
+                    files[`${prefix}${String(expectedSeq)}.json`] =
+                        JSON.stringify(onDisk);
+                    expectedSeq += 1;
+                }
+                return files;
+            },
+            message: events.length === 1
+                ? `append workflow event ${firstEvent.kind} for run ${runId}`
+                : `append ${String(events.length)} workflow events ${firstEvent.kind}..${lastEvent.kind} for run ${runId}`,
+        });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (message.startsWith("path_violation: ")) {
+            const reason = message.slice("path_violation: ".length);
+            throw new Error(reason, { cause });
+        }
+        throw cause;
+    }
+    if (seqConflict !== null) {
+        const conflict = seqConflict;
+        throw new Error(`workflow-runtime: seq conflict on append to ${runId}; single-writer invariant violated (expected seq ${String(conflict.expected)} from prior tree, caller supplied ${String(conflict.supplied)})`);
+    }
+}
+async function* subscribeRun(opts, runId, subOpts) {
+    // `subscribeKind` requires a `kinds` filter; supplying every known
+    // workflow-event `type` keeps the runtime body's contract intact (it
+    // wants every event for the run, not a subset). The substrate helper
+    // also surfaces per-run attribution via the entry's `runId`, which
+    // we use to filter just this run's events. Replay-then-live mode
+    // mirrors `SubscribeOpts.from`: `"head"` emits only events committed
+    // strictly after subscription, `{ seq }` enumerates prior events at
+    // or after the supplied seq before transitioning to live.
+    const kindOpts = {
+        signal: subOpts.signal,
+        from: subOpts.from,
+        kinds: ALL_WORKFLOW_EVENT_TYPES,
+    };
+    if (subOpts.bufferLimit !== undefined) {
+        kindOpts.bufferLimit = subOpts.bufferLimit;
+    }
+    const iter = subscribeKind(opts.substrate, opts.principal, opts.repoId, opts.ref, OnDiskEnvelope, kindOpts);
+    for await (const entry of iter) {
+        if (entry.runId !== runId)
+            continue;
+        const event = onDiskToWorkflowEvent(entry.event);
+        yield { seq: entry.event.seq, event };
+    }
+}
+function isErrnoNotFound(cause) {
+    if (cause === null || typeof cause !== "object")
+        return false;
+    const code = cause.code;
+    return code === "ENOENT";
+}

package/dist/adapters/spawn-child.d.ts

@@ -0,0 +1,74 @@
+import type { Principal, RepoStore } from "@intx/hub-sessions/substrate";
+import type { SpawnChildWorkflow, WorkflowDefinition } from "@intx/workflow";
+/**
+ * The terminal-status shape the runtime body expects back from a
+ * spawn. Mirrored from `SpawnChildWorkflow`'s return type so the
+ * `runChild` callback's signature is symmetric with the adapter's.
+ */
+export type ChildTerminalStatus = "completed" | "failed" | "cancelled";
+/**
+ * Runtime-supplied child execution callback. The supervisor owns the
+ * child `WorkflowRuntimeEnv` construction (per-deployment substrate,
+ * per-run blob substrate, child director registry) and the
+ * `runtimeRun` invocation; the adapter is the single resolution
+ * point that hands the supervisor a concrete `WorkflowDefinition`
+ * alongside the parent attribution the runtime body produced.
+ *
+ * The callback receives the same `AbortSignal` the parent runtime
+ * passed into the adapter so a parent-initiated cancellation
+ * propagates to the child without an intermediate wrapper.
+ */
+export type RunChildWorkflow = (input: {
+    definition: WorkflowDefinition;
+    definitionRef: string;
+    childRunId: string;
+    input: unknown;
+    parentRunId: string;
+    parentStepId: string;
+    signal: AbortSignal;
+}) => Promise<{
+    terminalStatus: ChildTerminalStatus;
+}>;
+export interface WorkflowSpawnChildOpts {
+    /**
+     * Substrate the deploy orchestrator wrote the workflow asset into.
+     * The adapter reads the workflow envelope through
+     * `substrate.getRepoDir` -- the deploy-time `writeTree` already
+     * materialized the file under the returned directory and a flat
+     * `fs.readFile` does not need to walk the git object database.
+     */
+    substrate: RepoStore;
+    /**
+     * Principal the adapter presents to the substrate for any future
+     * authorize-gated read path. The current implementation does not
+     * gate `getRepoDir` (the substrate documents it as a pure path
+     * computation), but holding the principal in closure keeps the
+     * adapter symmetric with the sibling production adapters and ready
+     * for a future API that surfaces an authorize gate on the same
+     * read path.
+     */
+    principal: Principal;
+    /**
+     * Ref under the workflow asset's repo whose tree holds the
+     * deployed `workflow.json`. Callers typically supply
+     * `"refs/heads/main"` -- the workflow-kind handler enforces the
+     * envelope's structural shape at push time so a deploy ref read
+     * here either yields a valid envelope or surfaces a targeted
+     * parse/validation error.
+     */
+    deployRef: string;
+    /**
+     * Runtime-supplied child execution callback. The adapter delegates
+     * here once the `WorkflowDefinition` is resolved; the supervisor
+     * owns the child `WorkflowRuntimeEnv` and the `runtimeRun`
+     * invocation.
+     */
+    runChild: RunChildWorkflow;
+}
+/**
+ * Construct the production `WorkflowRuntimeEnv.SpawnChildWorkflow`
+ * adapter. The substrate handle, the principal, the deploy ref, and
+ * the runtime-supplied child callback live in closure; the returned
+ * callable satisfies the runtime-env interface.
+ */
+export declare function createWorkflowSpawnChild(opts: WorkflowSpawnChildOpts): SpawnChildWorkflow;