@boardwalk-labs/runner 0.1.2

package/dist/runtime/sandbox_config.js

@@ -0,0 +1,34 @@
+// sandbox_config — derive the sandbox tools' per-run configuration from a workflow manifest.
+//
+// The worker builds the `shell`/`git`/`filesystem` tools (build_registry's `sandbox` deps) once
+// the run's manifest is known. One manifest-driven knob feeds in here:
+//   * env split — `manifest.env` values are either non-secret literals (passed straight to the
+//     subprocess env) or `${{ secrets.X }}` references (turned into a `envVar → secretName` map the
+//     tools resolve per-run via `ctx.secrets`; the secret VALUE never sits in the manifest).
+// The shell command allowlist is the built-in default — there is no manifest-level tool grant or
+// `extra_commands` config (tools are selected per-`agent()` call, not granted in the manifest).
+//
+// Pure + manifest-only so the split/extraction is exhaustively unit-testable without a worker.
+import { parseSecretEnvRef } from "./wire/manifest.js";
+/**
+ * Split `manifest.env` into non-secret literals vs. `${{ secrets.X }}` references. Returns only the
+ * keys that have content, so the caller can spread it into the sandbox deps without injecting
+ * empty objects.
+ */
+export function sandboxConfigFromManifest(manifest) {
+    const env = {};
+    const secretEnv = {};
+    for (const [key, value] of Object.entries(manifest.env ?? {})) {
+        const secret = parseSecretEnvRef(value);
+        if (secret !== null)
+            secretEnv[key] = secret;
+        else
+            env[key] = value;
+    }
+    const config = {};
+    if (Object.keys(env).length > 0)
+        config.env = env;
+    if (Object.keys(secretEnv).length > 0)
+        config.secretEnv = secretEnv;
+    return config;
+}

package/dist/runtime/support/index.d.ts

@@ -0,0 +1,53 @@
+export declare enum ErrorCode {
+    VALIDATION_FAILED = "VALIDATION_FAILED",
+    IDEMPOTENCY_KEY_REUSED = "IDEMPOTENCY_KEY_REUSED",
+    MISSING_IDEMPOTENCY_KEY = "MISSING_IDEMPOTENCY_KEY",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    FORBIDDEN = "FORBIDDEN",
+    TWO_FACTOR_REQUIRED = "TWO_FACTOR_REQUIRED",
+    BUDGET_EXCEEDED = "BUDGET_EXCEEDED",
+    INSUFFICIENT_CREDITS = "INSUFFICIENT_CREDITS",
+    BILLING_GATED = "BILLING_GATED",
+    UPGRADE_REQUIRED = "UPGRADE_REQUIRED",
+    NOT_FOUND = "NOT_FOUND",
+    CONFLICT = "CONFLICT",
+    CONCURRENCY_LIMIT = "CONCURRENCY_LIMIT",
+    WORKFLOW_DISABLED = "WORKFLOW_DISABLED",
+    UNSUPPORTED_TRIGGER = "UNSUPPORTED_TRIGGER",
+    RATE_LIMIT = "RATE_LIMIT",
+    TOOL_ERROR = "TOOL_ERROR",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly httpStatus: number;
+    readonly detail?: unknown;
+    constructor(code: ErrorCode, message: string, detail?: unknown);
+}
+export declare function isAppError(err: unknown): err is AppError;
+/** Run-lease heartbeat period (ported from the platform's checkpoint module — the broker's
+ *  renew endpoint mirrors it). */
+export declare const DEFAULT_LEASE_MS: number;
+/** Opaque unique id (metering sessions, worker ids). Not a ULID — nothing here sorts by it. */
+export declare function newId(): string;
+type LogFields = Record<string, unknown>;
+export interface Logger {
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+}
+export declare function createLogger(module: string): Logger;
+export type OrgRole = "owner" | "admin" | "member" | "viewer";
+export type AuthSource = "session_jwt" | "oauth_jwt" | "api_key" | "workflow";
+export interface AuthContext {
+    userId: string;
+    source: AuthSource;
+    orgId: string;
+    role: OrgRole;
+    apiKeyId?: string;
+    scopes?: readonly string[];
+    boundOrgId?: string;
+    boundRole?: OrgRole;
+}
+export {};

package/dist/runtime/support/index.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// Runtime support shims — the small slice of the platform's `@boardwalk/common` +
+// `domain/authz` the worker runtime depends on, ported verbatim where it matters
+// (AppError taxonomy) and minimally where it doesn't (the logger: structured JSON to
+// stdout, same call surface as the platform's Powertools child logger).
+import { randomUUID } from "node:crypto";
+// ---- errors (ported from boardwalk-backend src/common/errors.ts; keep in sync until the
+// backend consumes this package and the copy there is deleted) ----
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+    ErrorCode["IDEMPOTENCY_KEY_REUSED"] = "IDEMPOTENCY_KEY_REUSED";
+    ErrorCode["MISSING_IDEMPOTENCY_KEY"] = "MISSING_IDEMPOTENCY_KEY";
+    ErrorCode["UNAUTHORIZED"] = "UNAUTHORIZED";
+    ErrorCode["FORBIDDEN"] = "FORBIDDEN";
+    ErrorCode["TWO_FACTOR_REQUIRED"] = "TWO_FACTOR_REQUIRED";
+    ErrorCode["BUDGET_EXCEEDED"] = "BUDGET_EXCEEDED";
+    ErrorCode["INSUFFICIENT_CREDITS"] = "INSUFFICIENT_CREDITS";
+    ErrorCode["BILLING_GATED"] = "BILLING_GATED";
+    ErrorCode["UPGRADE_REQUIRED"] = "UPGRADE_REQUIRED";
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ErrorCode["CONFLICT"] = "CONFLICT";
+    ErrorCode["CONCURRENCY_LIMIT"] = "CONCURRENCY_LIMIT";
+    ErrorCode["WORKFLOW_DISABLED"] = "WORKFLOW_DISABLED";
+    ErrorCode["UNSUPPORTED_TRIGGER"] = "UNSUPPORTED_TRIGGER";
+    ErrorCode["RATE_LIMIT"] = "RATE_LIMIT";
+    ErrorCode["TOOL_ERROR"] = "TOOL_ERROR";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+const ERROR_HTTP_STATUS = {
+    [ErrorCode.VALIDATION_FAILED]: 400,
+    [ErrorCode.IDEMPOTENCY_KEY_REUSED]: 409,
+    [ErrorCode.MISSING_IDEMPOTENCY_KEY]: 400,
+    [ErrorCode.UNAUTHORIZED]: 401,
+    [ErrorCode.FORBIDDEN]: 403,
+    [ErrorCode.TWO_FACTOR_REQUIRED]: 403,
+    [ErrorCode.BUDGET_EXCEEDED]: 402,
+    [ErrorCode.INSUFFICIENT_CREDITS]: 402,
+    [ErrorCode.BILLING_GATED]: 402,
+    [ErrorCode.UPGRADE_REQUIRED]: 402,
+    [ErrorCode.NOT_FOUND]: 404,
+    [ErrorCode.CONFLICT]: 409,
+    [ErrorCode.CONCURRENCY_LIMIT]: 409,
+    [ErrorCode.WORKFLOW_DISABLED]: 409,
+    [ErrorCode.UNSUPPORTED_TRIGGER]: 422,
+    [ErrorCode.RATE_LIMIT]: 429,
+    [ErrorCode.TOOL_ERROR]: 500,
+    [ErrorCode.INTERNAL_ERROR]: 500,
+};
+export class AppError extends Error {
+    code;
+    httpStatus;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.name = "AppError";
+        this.code = code;
+        this.httpStatus = ERROR_HTTP_STATUS[code];
+        this.detail = detail;
+    }
+}
+export function isAppError(err) {
+    return err instanceof AppError;
+}
+// ---- leases ----
+/** Run-lease heartbeat period (ported from the platform's checkpoint module — the broker's
+ *  renew endpoint mirrors it). */
+export const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+// ---- ids ----
+/** Opaque unique id (metering sessions, worker ids). Not a ULID — nothing here sorts by it. */
+export function newId() {
+    return randomUUID();
+}
+const LEVEL_ORDER = { DEBUG: 10, INFO: 20, WARN: 30, ERROR: 40 };
+/** Active log level: BOARDWALK_RUNNER_LOG_LEVEL (debug|info|warn|error), default info.
+ *  BOARDWALK_RUNNER_DEBUG=1 is a legacy alias for debug. Read per call so a CLI flag that
+ *  sets the env (e.g. `--verbose` / `--debug`) applies without logger re-creation. */
+function activeLevel() {
+    if (process.env.BOARDWALK_RUNNER_DEBUG === "1")
+        return LEVEL_ORDER.DEBUG ?? 10;
+    const name = process.env.BOARDWALK_RUNNER_LOG_LEVEL?.toUpperCase() ?? "INFO";
+    return LEVEL_ORDER[name] ?? 20;
+}
+function emit(level, module, message, fields) {
+    if ((LEVEL_ORDER[level] ?? 20) < activeLevel())
+        return;
+    const line = JSON.stringify({
+        level,
+        message,
+        timestamp: new Date().toISOString(),
+        module,
+        ...fields,
+    });
+    if (level === "ERROR" || level === "WARN")
+        process.stderr.write(`${line}\n`);
+    else
+        process.stdout.write(`${line}\n`);
+}
+export function createLogger(module) {
+    return {
+        debug: (m, f) => {
+            emit("DEBUG", module, m, f);
+        },
+        info: (m, f) => {
+            emit("INFO", module, m, f);
+        },
+        warn: (m, f) => {
+            emit("WARN", module, m, f);
+        },
+        error: (m, f) => {
+            emit("ERROR", module, m, f);
+        },
+    };
+}

package/dist/runtime/suspension.d.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import type { LeafCheckpoint, LeafResume } from "@boardwalk-labs/engine/core";
+import { AppError } from "./support/index.js";
+/**
+ * Sleeps at/above this hold-vs-release boundary SUSPEND (release the task; a timer re-dispatches the
+ * run when due); shorter ones HOLD the process in-memory, where a release + replay round-trip costs
+ * more than it saves. Mirrors the engine's `SUSPEND_THRESHOLD_MS` so the two runtimes draw the line
+ * in the same place.
+ */
+export declare const SUSPEND_THRESHOLD_MS = 30000;
+/** The durable-seam kinds the journal memoizes (mirrors `run_journal.kind` + the engine's IPC). */
+export type JournalKind = "agent" | "step" | "human_input" | "sleep" | "workflow_call";
+/** Why a seam suspended the run. */
+export type SuspendReason = "human_input" | "sleep" | "workflow_call";
+/** A human-in-the-loop gate carried out of a suspending seam (program-level or the in-leaf tool). */
+export interface HumanInputGate {
+    /** The stable key the responder answers by (an author/seq key, or the model's tool-call id). */
+    key: string;
+    prompt: string;
+    /** The response form ({@link import("@boardwalk-labs/workflow").HumanInputSpec}); validated on submit. */
+    inputSpec: unknown;
+    /** RBAC scopes (`role:…`, `user:…`) allowed to respond; absent ⇒ any member with `run:respond`. */
+    assignees?: string[];
+    /** When the gate auto-expires (ms since epoch), for a `timeout`; absent ⇒ waits indefinitely. */
+    expiresAt?: number;
+    /** What to do on expiry (`"fail"` | `{ value }`) — the SDK's `onTimeout`; jsonb passthrough. */
+    onTimeout?: unknown;
+}
+/** Everything the broker needs to persist a suspension + the wake condition. */
+export interface SuspendSignal {
+    reason: SuspendReason;
+    /** The journal seq of the suspending seam. */
+    seq: number;
+    /** The seam's determinism fingerprint (recorded on the pending journal entry). */
+    fingerprint: string;
+    /** Present for `reason: "human_input"` — the gate to register a request row for. */
+    humanInput?: HumanInputGate;
+    /** A tool-level gate's leaf transcript checkpoint, stored so the leaf resumes where it paused. */
+    leafCheckpoint?: LeafCheckpoint;
+    /** Relative wait (ms) for `reason: "sleep"`; the broker computes the absolute wake time. */
+    durationMs?: number;
+    /** The child run id for `reason: "workflow_call"` — the parent suspends `waiting_for_child` and is
+     *  woken when this child finalizes (the sweep wakes a parent whose child is terminal). */
+    childRunId?: string;
+}
+/**
+ * The control signal a host seam raises to suspend the run. Unlike the engine (a child process the
+ * supervisor kills out-of-band), the backend worker runs the program IN-PROCESS, so a suspend is
+ * surfaced by the host calling `onSuspend(signal)` and returning a NEVER-resolving promise; the
+ * worker races that against the program body and tears down. This class exists so a seam that has no
+ * `onSuspend` wired (the local/test path) can still raise a typed, catchable signal.
+ */
+export declare class SuspendError extends Error {
+    readonly signal: SuspendSignal;
+    constructor(signal: SuspendSignal);
+}
+/** Journal-entry states (mirrors `run_journal.state` + the engine's IPC). */
+export declare const JOURNAL_STATES: readonly ["pending", "suspended", "resolved"];
+export type JournalEntryState = (typeof JOURNAL_STATES)[number];
+/** A memoized journal entry, as the host reads it back on replay (mirrors the engine's IPC shape). */
+export interface JournalLookup {
+    seq: number;
+    kind: JournalKind;
+    fingerprint: string;
+    /** `resolved` ⇒ `result` is the memoized value; `suspended` ⇒ a parked agent leaf (result is the
+     *  {@link LeafResume} the host re-enters with); `pending` ⇒ awaiting an external event (re-suspend). */
+    state: JournalEntryState;
+    result: unknown;
+}
+/** Validate the broker's journal_get response (the worker's run token doesn't exempt the channel from
+ *  validation). The result is genuinely heterogeneous JSON (an agent return / a LeafResume / a
+ *  HumanInputResult), parsed per-kind downstream — so it stays `unknown` here, the validation seam. */
+export declare const journalLookupSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    kind: z.ZodEnum<{
+        sleep: "sleep";
+        agent: "agent";
+        step: "step";
+        human_input: "human_input";
+        workflow_call: "workflow_call";
+    }>;
+    fingerprint: z.ZodString;
+    state: z.ZodEnum<{
+        pending: "pending";
+        suspended: "suspended";
+        resolved: "resolved";
+    }>;
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+/** The journal the host reads (replay lookup) + writes (resolved seam results). Backed by the broker
+ *  over the run token on hosted runs; absent on the local/test path (no durable suspension). */
+export interface JournalSeam {
+    /** The memoized entry for a seam, or null on a replay miss. */
+    get(seq: number): Promise<JournalLookup | null>;
+    /** Record a RESOLVED seam result (idempotent on the run + seq; a resolved entry is immutable). */
+    put(entry: {
+        seq: number;
+        kind: JournalKind;
+        fingerprint: string;
+        label: string;
+        result: unknown;
+    }): Promise<void>;
+}
+/**
+ * The synchronous, monotonic durable-seam counter. Incremented at each journaled seam's ENTRY:
+ * because a program's synchronous call order is deterministic (even under `Promise.all`, whose
+ * `.map(...)` runs left-to-right synchronously), the same logical call gets the same `seq` on every
+ * execution — the journal key that lets a resumed run return a memoized result.
+ *
+ * It also drives SILENT REPLAY: a resume starts suppressed (observability — console output, phase
+ * markers — was already emitted last segment) and goes `live` the moment it reaches the suspending
+ * seam (the frontier = the highest journaled seq). A fresh run (frontier 0) is live immediately.
+ */
+export declare class SeamSequencer {
+    private readonly replayFrontier;
+    private count;
+    private liveFlag;
+    constructor(replayFrontier?: number);
+    next(): number;
+    /** True once execution has crossed the replay frontier — output after this point is NEW. */
+    get isLive(): boolean;
+    /** True while re-running already-journaled seams on a resume (observability suppressed). */
+    isReplaying(): boolean;
+}
+/** The child run id a `workflow_call` seam journals while it waits (parsed back on resume). */
+export declare const childRunIdSchema: z.ZodString;
+/** A stable content hash of a seam's salient args — the determinism check on replay. Identical
+ *  construction to the engine's `seamFingerprint` so a journal written by one runtime validates in
+ *  the other (the conformance promise). */
+export declare function seamFingerprint(parts: readonly unknown[]): string;
+/** A seam reached on replay didn't match what the journal recorded at that seq — the workflow's code
+ *  on the path to a suspend changed (a different prompt/model/step name, or a different seam kind).
+ *  Fails the run loudly rather than returning a stale memoized result for the wrong call. */
+export declare function determinismError(seq: number, got: JournalKind, recorded: JournalKind): AppError;
+/**
+ * The shape of a SUSPENDED agent leaf's journal result on resume: the transcript checkpoint plus the
+ * answers the broker joined from the resolved request rows, keyed by tool-call id. `messages` is the
+ * engine's own serialized transcript round-tripping through JSON — handed straight back to the leaf,
+ * not re-validated field-by-field. Structurally a {@link LeafResume}.
+ */
+export declare const leafResumeSchema: z.ZodType<LeafResume>;

package/dist/runtime/suspension.js

@@ -0,0 +1,120 @@
+// Durable-suspension primitives for the JS-body worker (docs/SUSPENSION.md).
+//
+// A run SUSPENDS at a durable seam — a long `sleep`, a `humanInput()` gate, or the in-leaf
+// `human_input` tool — by releasing its Fargate task and re-acquiring one on wake. The mechanism is
+// a JOURNAL: every memoizable seam (`agent` / `step` / `humanInput` / `sleep`) is keyed by a
+// synchronous monotonic `seq` and records its whole result, so a resumed run RESTARTS from the top
+// and replays through the journal (a hit returns the memoized value instantly; we never replay an
+// LLM turn — we memoize whole results, the `findChildCall` pattern generalized). This is NOT
+// Temporal-style turn replay, so it does not violate the no-replay-engine rule (CLAUDE.md).
+//
+// This file holds the SHARED pieces the host + worker + broker client agree on: the suspend signal a
+// seam raises, the journal seam the host reads/writes, the seq sequencer driving silent replay, and
+// the determinism fingerprint. The behavior is conformance-pinned to the OSS engine's
+// `src/run/child_host.ts` — the two runtimes must suspend + resume identically.
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { AppError, ErrorCode } from "./support/index.js";
+/**
+ * Sleeps at/above this hold-vs-release boundary SUSPEND (release the task; a timer re-dispatches the
+ * run when due); shorter ones HOLD the process in-memory, where a release + replay round-trip costs
+ * more than it saves. Mirrors the engine's `SUSPEND_THRESHOLD_MS` so the two runtimes draw the line
+ * in the same place.
+ */
+export const SUSPEND_THRESHOLD_MS = 30_000;
+/**
+ * The control signal a host seam raises to suspend the run. Unlike the engine (a child process the
+ * supervisor kills out-of-band), the backend worker runs the program IN-PROCESS, so a suspend is
+ * surfaced by the host calling `onSuspend(signal)` and returning a NEVER-resolving promise; the
+ * worker races that against the program body and tears down. This class exists so a seam that has no
+ * `onSuspend` wired (the local/test path) can still raise a typed, catchable signal.
+ */
+export class SuspendError extends Error {
+    signal;
+    constructor(signal) {
+        super(`run suspended (${signal.reason}) at seam ${String(signal.seq)}`);
+        this.name = "SuspendError";
+        this.signal = signal;
+    }
+}
+/** Journal-entry states (mirrors `run_journal.state` + the engine's IPC). */
+export const JOURNAL_STATES = ["pending", "suspended", "resolved"];
+/** Validate the broker's journal_get response (the worker's run token doesn't exempt the channel from
+ *  validation). The result is genuinely heterogeneous JSON (an agent return / a LeafResume / a
+ *  HumanInputResult), parsed per-kind downstream — so it stays `unknown` here, the validation seam. */
+export const journalLookupSchema = z.object({
+    seq: z.number().int().positive(),
+    kind: z.enum(["agent", "step", "human_input", "sleep", "workflow_call"]),
+    fingerprint: z.string(),
+    state: z.enum(JOURNAL_STATES),
+    result: z.unknown(),
+});
+/**
+ * The synchronous, monotonic durable-seam counter. Incremented at each journaled seam's ENTRY:
+ * because a program's synchronous call order is deterministic (even under `Promise.all`, whose
+ * `.map(...)` runs left-to-right synchronously), the same logical call gets the same `seq` on every
+ * execution — the journal key that lets a resumed run return a memoized result.
+ *
+ * It also drives SILENT REPLAY: a resume starts suppressed (observability — console output, phase
+ * markers — was already emitted last segment) and goes `live` the moment it reaches the suspending
+ * seam (the frontier = the highest journaled seq). A fresh run (frontier 0) is live immediately.
+ */
+export class SeamSequencer {
+    replayFrontier;
+    count = 0;
+    liveFlag;
+    constructor(replayFrontier = 0) {
+        this.replayFrontier = replayFrontier;
+        this.liveFlag = replayFrontier === 0;
+    }
+    next() {
+        const seq = ++this.count;
+        if (seq >= this.replayFrontier)
+            this.liveFlag = true;
+        return seq;
+    }
+    /** True once execution has crossed the replay frontier — output after this point is NEW. */
+    get isLive() {
+        return this.liveFlag;
+    }
+    /** True while re-running already-journaled seams on a resume (observability suppressed). */
+    isReplaying() {
+        return !this.liveFlag;
+    }
+}
+/** The child run id a `workflow_call` seam journals while it waits (parsed back on resume). */
+export const childRunIdSchema = z.string().min(1);
+/** A stable content hash of a seam's salient args — the determinism check on replay. Identical
+ *  construction to the engine's `seamFingerprint` so a journal written by one runtime validates in
+ *  the other (the conformance promise). */
+export function seamFingerprint(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/** A seam reached on replay didn't match what the journal recorded at that seq — the workflow's code
+ *  on the path to a suspend changed (a different prompt/model/step name, or a different seam kind).
+ *  Fails the run loudly rather than returning a stale memoized result for the wrong call. */
+export function determinismError(seq, got, recorded) {
+    const detail = got === recorded
+        ? `the same "${got}" seam but with different arguments (a changed prompt, model, or step name)`
+        : `a "${recorded}" call, but this execution reached a "${got}" call`;
+    return new AppError(ErrorCode.VALIDATION_FAILED, `Nondeterministic replay at seam ${String(seq)}: the journal recorded ${detail}. A workflow's ` +
+        `code on the path to a suspend/resume must be deterministic — route nondeterministic I/O ` +
+        `through agent(), step.run(), or workflows.call so it is journaled.`, { kind: "nondeterministic_replay", seq });
+}
+/**
+ * The shape of a SUSPENDED agent leaf's journal result on resume: the transcript checkpoint plus the
+ * answers the broker joined from the resolved request rows, keyed by tool-call id. `messages` is the
+ * engine's own serialized transcript round-tripping through JSON — handed straight back to the leaf,
+ * not re-validated field-by-field. Structurally a {@link LeafResume}.
+ */
+export const leafResumeSchema = z.object({
+    checkpoint: z.object({
+        messages: z.array(z.custom()),
+        iteration: z.number().int(),
+        totals: z.object({
+            inputTokens: z.number().int(),
+            outputTokens: z.number().int(),
+        }),
+    }),
+    answers: z.record(z.string(), z.unknown()),
+});

package/dist/runtime/testing_artifact_build.d.ts

@@ -0,0 +1,27 @@
+/** Entry module name inside the artifact (matches the CLI builder). */
+export declare const SINGLE_FILE_ENTRY = "index.mjs";
+/** A built program artifact + the metadata the version row records. */
+export interface BuiltServerArtifact {
+    tarball: Uint8Array;
+    digest: string;
+    size: number;
+    entry: string;
+    sdkVersion: string;
+    lockfileDigest: null;
+}
+/**
+ * Build a single-file program artifact from submitted source. Type-strips TS→ESM (no type-check;
+ * imports preserved so `@boardwalk-labs/workflow` stays external), packs `index.mjs` into a deterministic
+ * tar.gz, and content-addresses it. Pure (string in → bytes out) — no fs, no network.
+ */
+export declare function buildSingleFileArtifact(source: string, carryAssets?: readonly {
+    name: string;
+    data: Buffer;
+}[]): BuiltServerArtifact;
+/** Build a standards-compliant ustar archive holding the given regular files in order (deterministic:
+ *  mtime/uid/gid zeroed). Readable by node-tar / system tar (the worker extractor) and our own reader.
+ *  Exported so the multi-file package builder reuses the exact same packing. */
+export declare function tarFiles(files: {
+    name: string;
+    data: Buffer;
+}[]): Buffer;

package/dist/runtime/testing_artifact_build.js

@@ -0,0 +1,96 @@
+// Server-side single-file artifact build (web / MCP deploy surface, docs/WORKFLOW_RUNTIME.md §3.9).
+//
+// The CLI bundles packages locally; web + MCP submit a single TS/JS file with no client bundler, so
+// the api-server builds the IDENTICAL artifact shape: type-strip the source → `index.mjs`, pack a
+// one-file deterministic tar.gz, content-address by sha256. A single file's only import is the host
+// `@boardwalk-labs/workflow` SDK (left external at runtime), so there is nothing to bundle. The result
+// flows through the SAME finalize path as a CLI upload (verify digest → read entry → derive manifest),
+// so a server-built artifact gets the same integrity guarantees.
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import ts from "typescript";
+// Inlined from the platform's domain/workflow/artifact_storage.ts (test-only helper).
+const WORKFLOW_ARTIFACT_SOURCE_DIR = ".bw-src";
+const WORKFLOW_ARTIFACT_SINGLE_SOURCE = `${WORKFLOW_ARTIFACT_SOURCE_DIR}/index.ts`;
+/** Entry module name inside the artifact (matches the CLI builder). */
+export const SINGLE_FILE_ENTRY = "index.mjs";
+/** Single-file programs pin no SDK version — defer to whatever the worker image ships. */
+const UNPINNED_SDK = "*";
+/**
+ * Build a single-file program artifact from submitted source. Type-strips TS→ESM (no type-check;
+ * imports preserved so `@boardwalk-labs/workflow` stays external), packs `index.mjs` into a deterministic
+ * tar.gz, and content-addresses it. Pure (string in → bytes out) — no fs, no network.
+ */
+export function buildSingleFileArtifact(source, carryAssets = []) {
+    const js = ts.transpileModule(source, {
+        fileName: "index.ts",
+        compilerOptions: {
+            module: ts.ModuleKind.ESNext,
+            target: ts.ScriptTarget.ES2022,
+            verbatimModuleSyntax: false,
+        },
+    }).outputText;
+    // Pack the built (runnable) entry + the author's ORIGINAL source (verbatim, for display/quick-edit)
+    // under the unified `.bw-src/` tree — so the detail read surfaces single- and multi-file the same way.
+    // `carryAssets` are the prior version's bundled non-source files (skills/configs/templates), re-packed
+    // verbatim so a web quick-edit (which rebuilds from source only) never drops them. They arrive already
+    // sorted, so appending keeps a no-asset build byte-identical to before.
+    const tar = tarFiles([
+        { name: SINGLE_FILE_ENTRY, data: Buffer.from(js, "utf8") },
+        { name: WORKFLOW_ARTIFACT_SINGLE_SOURCE, data: Buffer.from(source, "utf8") },
+        ...carryAssets,
+    ]);
+    const tarball = new Uint8Array(gzipSync(tar, { level: 9 }));
+    return {
+        tarball,
+        digest: createHash("sha256").update(tarball).digest("hex"),
+        size: tarball.length,
+        entry: SINGLE_FILE_ENTRY,
+        sdkVersion: UNPINNED_SDK,
+        lockfileDigest: null,
+    };
+}
+const TAR_BLOCK = 512;
+/** Build a standards-compliant ustar archive holding the given regular files in order (deterministic:
+ *  mtime/uid/gid zeroed). Readable by node-tar / system tar (the worker extractor) and our own reader.
+ *  Exported so the multi-file package builder reuses the exact same packing. */
+export function tarFiles(files) {
+    const parts = files.map((f) => tarEntry(f.name, f.data));
+    parts.push(Buffer.alloc(TAR_BLOCK * 2, 0)); // two zero blocks = end-of-archive marker
+    return Buffer.concat(parts);
+}
+/** One ustar entry: a 512-byte header + the data padded to a block boundary (no end-of-archive). */
+function tarEntry(name, data) {
+    if (Buffer.byteLength(name) > 100) {
+        // Names are short (`index.mjs`, `.bw-src/lib/util.ts`); guard a long name (no PAX support).
+        throw new Error(`tar entry name too long: ${name}`);
+    }
+    const header = Buffer.alloc(TAR_BLOCK, 0);
+    header.write(name, 0, 100, "utf8"); // name
+    writeOctal(header, 0o644, 100, 8); // mode
+    writeOctal(header, 0, 108, 8); // uid
+    writeOctal(header, 0, 116, 8); // gid
+    writeOctal(header, data.length, 124, 12); // size
+    writeOctal(header, 0, 136, 12); // mtime (deterministic)
+    header.write("0", 156, 1, "ascii"); // typeflag = regular file
+    header.write("ustar\0", 257, 6, "binary"); // magic
+    header.write("00", 263, 2, "binary"); // version
+    // Checksum: sum every header byte with the checksum field initialized to 8 spaces, then write it as
+    // 6 octal digits + NUL + space (the conventional ustar form).
+    header.write("        ", 148, 8, "ascii");
+    let sum = 0;
+    for (const b of header)
+        sum += b;
+    const chk = sum.toString(8).padStart(6, "0").slice(-6);
+    header.write(`${chk}\0 `, 148, 8, "ascii");
+    const padLen = (TAR_BLOCK - (data.length % TAR_BLOCK)) % TAR_BLOCK;
+    return Buffer.concat([header, data, Buffer.alloc(padLen, 0)]);
+}
+/** Write a tar numeric field: (length-1) zero-padded octal digits + NUL. */
+function writeOctal(buf, value, offset, length) {
+    const digits = value
+        .toString(8)
+        .padStart(length - 1, "0")
+        .slice(-(length - 1));
+    buf.write(`${digits}\0`, offset, length, "ascii");
+}