@boardwalk-labs/engine 0.1.0 → 0.1.2

package/README.md

@@ -32,6 +32,22 @@ docker run -v ./data:/data -p 8080:8080 ghcr.io/boardwalk-labs/boardwalk
 Then open `http://localhost:8080` for the run log, or hit the JSON API
 (`/api/workflows`, `/api/runs`). Webhook triggers land on `/hooks/<workflow>/<trigger-id>`.
 
+### Deploying a workflow
+
+Build your workflow to a single file and drop it in the engine's **workflows directory** — it's
+deployed on boot (re-synced every boot; idempotent by manifest name):
+
+```sh
+npx @boardwalk-labs/cli build index.ts --out ./data/workflows/my-routine.mjs
+docker run -v ./data:/data -p 8080:8080 ghcr.io/boardwalk-labs/boardwalk
+```
+
+The default workflows directory is `<data-dir>/workflows` (`/data/workflows` in Docker); override
+it with `BOARDWALK_WORKFLOWS_DIR`. Each `.mjs`/`.js` file is one workflow — single-file, with
+`@boardwalk-labs/workflow` left external (exactly what `boardwalk build` emits). From there the
+manifest's triggers take over: cron fires on schedule, `POST /api/workflows/<name>/runs` triggers
+a manual run, and webhooks land on `/hooks/<workflow>/<trigger-id>`.
+
 ### Configuration
 
 All configuration is environment variables (a `boardwalk.toml` file is deferred — see
@@ -40,6 +56,7 @@ All configuration is environment variables (a `boardwalk.toml` file is deferred
 | Variable                  | Default                                    | What it does                                                                                 |
 | ------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------- |
 | `BOARDWALK_DATA_DIR`      | `/data` in Docker, else `./boardwalk-data` | Where everything lives: SQLite DB, run dirs, artifacts                                       |
+| `BOARDWALK_WORKFLOWS_DIR` | `<data-dir>/workflows`                     | Directory of built workflows (`.mjs`/`.js`) deployed on boot                                 |
 | `BOARDWALK_HOST`          | `127.0.0.1` (`0.0.0.0` in Docker)          | Bind address — this surface has no auth beyond webhook auth, so binding wider logs a warning |
 | `BOARDWALK_PORT`          | `8080`                                     | Listen port (`0` picks a free port)                                                          |
 | `BOARDWALK_DEFAULT_MODEL` | —                                          | Model used when `agent()` omits one, e.g. `anthropic/claude-sonnet-4-5`                      |

package/bin/boardwalk-server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+
 // Thin launcher for `boardwalk-server` (SPEC §5). All real logic lives in compiled,
 // type-checked, tested TypeScript (src/server_main.ts) — this shim only exists so npm `bin`
 // and the Docker CMD share one entrypoint that resolves dist/ relative to the package.

package/dist/agent/conversation.js

@@ -1,4 +1,2 @@
-// The provider-neutral conversation model for the agent() loop. The leaf builds these;
-// each protocol adapter maps them to its wire format. Keeping the loop neutral is what lets
-// two adapters (Anthropic + OpenAI-compatible) cover every supported endpoint.
+// SPDX-License-Identifier: Apache-2.0
 export {};

package/dist/agent/leaf.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // The agent() leaf: a real agentic loop (SDK SPEC §2.1.1) — streamed model turns with tool
 // use (program-defined ToolDefs + memory file tools + MCP server tools), skills loaded into
 // context, schema output, secret redaction, and usage reporting. Runs IN THE PROGRAM PROCESS
@@ -150,7 +151,7 @@ async function executeToolCall(call, tools, io, turnId) {
     }
     io.emit(turnId, { kind: "tool_call_executing", toolCallId: call.id });
     try {
-        // Tool results enter model context → redact (MASTER_SPEC §6.2 covers tool results too).
+        // Tool results enter model context → redact (redaction covers tool results too).
         const content = io.redactor.redact(await tool.execute(call.input));
         io.emit(turnId, {
             kind: "tool_call_result",

package/dist/agent/providers.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Provider adapters for the agent() leaf — two wire protocols cover everything (SPEC §2.3):
 // Anthropic's Messages API (streamed) and OpenAI-style chat completions (the lingua franca of
 // OpenAI, Google's compat surface, vLLM, Ollama, Together, Fireworks, Groq…). Each adapter
@@ -5,7 +6,7 @@
 // model turn; the tool loop itself lives in leaf.ts.
 //
 // Zero SDK dependencies: plain fetch + Zod-validated responses (a provider's response is a
-// trust boundary like any other). Retry policy per CODE_QUALITY §4.3: exponential backoff with
+// trust boundary like any other). Retry policy: exponential backoff with
 // jitter on 429/5xx/network errors; a non-rate-limit 4xx never retries.
 import { z } from "zod";
 import { EngineError } from "../errors.js";
@@ -300,7 +301,7 @@ export async function chatOpenAi(args, io = {}) {
 // ----------------------------------------------------------------------------
 // Shared plumbing
 // ----------------------------------------------------------------------------
-/** Model-produced tool input is untrusted (CODE_QUALITY §2.1): parse, demand a JSON object. */
+/** Model-produced tool input is untrusted: parse, demand a JSON object. */
 function parseToolInput(raw, toolName) {
     const value = raw.trim().length === 0 ? {} : safeJson(raw);
     if (isPlainObject(value) && isJsonValue(value)) {

package/dist/agent/rates.js

@@ -1,10 +1,4 @@
-// The approximate token-price table behind budget.max_usd (SPEC §2.2: "USD via a bundled
-// approximate rate table, documented as approximate").
-//
-// This is a GUARDRAIL, not a bill: the engine never charges anyone — it terminates a run that
-// crosses the author's declared ceiling. Prices drift; entries here are deliberately coarse
-// pattern matches with a conservative default, so an unknown model still consumes budget
-// rather than running unmetered.
+// SPDX-License-Identifier: Apache-2.0
 // Order matters: first match wins, most-specific first.
 const RULES = [
     { pattern: /claude-opus/i, rate: { inUsdPerMtok: 15, outUsdPerMtok: 75 } },

package/dist/agent/redact.js

@@ -1,4 +1,5 @@
-// Secret redaction for the agent() leaf (MASTER_SPEC §6.2, CODE_QUALITY §7.4).
+// SPDX-License-Identifier: Apache-2.0
+// Secret redaction for the agent() leaf.
 //
 // The invariant: secret VALUES live only in deterministic program code; everything bound for a
 // model — prompts now, tool args/results/MCP traffic/skills/memory later — is scrubbed of every

package/dist/agent/resolve.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Model + provider resolution for the agent() leaf (SPEC §2.3 "model resolution").
 //
 // `provider` and `model` are ORTHOGONAL (decided 2026-06-12):
@@ -22,7 +23,7 @@ export const BOARDWALK_PROVIDER = "boardwalk";
 // Boardwalk inference gateway API; this engine sends model: "auto".
 const AUTO_MODEL = "auto";
 // The Boardwalk managed-inference gateway (OpenAI-compatible). `boardwalk.sh` is the placeholder
-// domain (MASTER_SPEC stack notes); override with BOARDWALK_INFERENCE_URL or config. The Auto
+// domain; override with BOARDWALK_INFERENCE_URL or config. The Auto
 // ROUTER itself lives in hosted Boardwalk — this engine only forwards to the gateway.
 const DEFAULT_BOARDWALK_INFERENCE_URL = "https://api.boardwalk.sh/v1";
 // Built-in direct-call providers — used only when NAMED explicitly; key from the conventional

package/dist/agent/sse.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Server-Sent Events parsing, shared by the provider adapters (streamed model turns) and the
 // MCP streamable-HTTP transport (a server may answer any POST with an SSE stream). One parser
 // so the two consumers can't drift on framing edge cases (CRLF, split chunks, [DONE]).

package/dist/agent/tools.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Capability assembly for an agent() call (SDK SPEC §2.1.1). Capabilities are PER-AGENT
 // (decided 2026-06-11): each call brings its own tools/skills/memory — there is nothing to
 // check against the manifest, but everything the call names must RESOLVE (fail loudly —
@@ -93,7 +94,7 @@ function wrapProgramTool(def) {
 // Server names prefix tool names (`<server>__<tool>`) — keep them tool-name-shaped.
 const MCP_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 // AgentOptions comes straight from user program code — the TS types are aspirational at
-// runtime, so each ref is Zod-checked before anything spawns or connects (CODE_QUALITY §2.1).
+// runtime, so each ref is Zod-checked before anything spawns or connects.
 const mcpServerRefSchema = z.discriminatedUnion("transport", [
     z.strictObject({
         name: z.string().regex(MCP_NAME_RE),

package/dist/clock.js

@@ -1,6 +1,4 @@
-// Injectable time source. The scheduler and lifecycle take a Clock instead of calling
-// Date.now()/setTimeout directly so tests can drive time deterministically (scheduler clock
-// tests, DST cases, catch-up policy) without real waits.
+// SPDX-License-Identifier: Apache-2.0
 /** The real wall clock. */
 export const systemClock = {
     now: () => Date.now(),

package/dist/cron/cron.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Cron parsing + next-fire computation for the scheduler (SPEC §2.1).
 //
 // One-validator philosophy: the SDK manifest schema only checks a cron trigger shallowly
@@ -14,8 +15,8 @@
 // Plus the modern (cronie/Quartz/AWS) extension `N/step` = `N-max/step`, because it is what
 // authors coming from any contemporary cron expect and accepting it loses nothing.
 //
-// Timezones use Intl only — this package takes no runtime dependency for cron (CODE_QUALITY
-// §10: every dependency is supply-chain surface). DST policy: a wall time erased by
+// Timezones use Intl only — this package takes no runtime dependency for cron (every dependency is
+// supply-chain surface). DST policy: a wall time erased by
 // spring-forward is skipped (it never occurs, so it never fires); a wall time repeated by
 // fall-back fires once, at its first (earlier-UTC) occurrence.
 import { EngineError } from "../errors.js";

package/dist/engine.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // The engine facade — the one object both consumers construct (SPEC §1):
 //   - SERVER mode: `start()` boots the recovery sweep + the cron scheduler loop and the
 //     process stays up (the HTTP surface sits on top of this object).

package/dist/errors.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Engine errors carry a stable machine-readable code (surfaced in run_status `failed` events
 // and API responses) plus an actionable message. Messages NEVER contain secret values.
 export const ENGINE_ERROR_CODES = [
@@ -12,7 +13,7 @@ export const ENGINE_ERROR_CODES = [
     "PROGRAM_ERROR", // the workflow program threw
     "CRASHED", // run process died and restarts were exhausted
     "CANCELLED",
-    "UNSUPPORTED", // capability not present on this engine (MASTER_SPEC §4)
+    "UNSUPPORTED", // capability not present on this engine
     "INTERNAL",
 ];
 /** Narrow a string (e.g. an error code off the IPC wire) to a known engine code. */

package/dist/ids.js

@@ -1,4 +1,5 @@
-// ULIDs — the engine's primary-key format (CODE_QUALITY §2.2): time-sortable, URL-safe,
+// SPDX-License-Identifier: Apache-2.0
+// ULIDs — the engine's primary-key format: time-sortable, URL-safe,
 // no auto-increment integers. Implemented in-house: 26 chars of Crockford base32 over
 // 48 bits of timestamp + 80 bits of crypto randomness. Zero dependencies on purpose —
 // every dependency in a public package is supply-chain surface.

package/dist/index.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // @boardwalk-labs/engine — the open-source single-node runtime.
 //
 // Two consumers, one implementation (SPEC §1): the CLI embeds it for `boardwalk dev`

package/dist/json_value.js

@@ -1,6 +1,4 @@
-// Runtime narrowing for JsonValue. Values arriving over the run process's JSON-serialized IPC
-// channel are JSON by construction, but "by construction" is exactly what trust boundaries
-// don't get to assume (CODE_QUALITY §2.1) — so narrow structurally instead of casting.
+// SPDX-License-Identifier: Apache-2.0
 import { EngineError } from "./errors.js";
 /** True when `value` is a plain JSON tree (no functions, symbols, bigints, class instances). */
 export function isJsonValue(value) {

package/dist/mcp/client.js

@@ -1,8 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
 // The MCP connection: the protocol conversation (initialize handshake, tools/list pagination,
 // tools/call) over any transport. Lives in the RUN PROCESS — tool execution must happen where
 // the program runs — while OAuth token state stays parent-side (the transport's hook brokers
 // it over IPC). Every server response is Zod-validated: an MCP server's output is untrusted
-// input like any provider's (CODE_QUALITY §2.1).
+// input like any provider's.
 import { z } from "zod";
 import { EngineError } from "../errors.js";
 import { JsonRpcClient } from "./jsonrpc.js";

package/dist/mcp/jsonrpc.js

@@ -1,8 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
 // JSON-RPC 2.0 request/notification correlation for the hand-rolled MCP client (the
 // @modelcontextprotocol/sdk dependency tree was rejected for the flagship — zero new deps).
 // The transport moves frames; this layer owns ids, correlation, timeouts, and the trust
 // boundary: every inbound frame is Zod-validated before anything dereferences it
-// (CODE_QUALITY §2.1 — an MCP server is as untrusted as any provider).
+// (an MCP server is as untrusted as any provider).
 import { z } from "zod";
 import { EngineError } from "../errors.js";
 // One loose schema for every inbound frame; classification happens after validation. A frame

package/dist/mcp/oauth.js

@@ -1,10 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
 // PARENT-side OAuth 2.1 for MCP servers (MCP authorization spec, 2025-06-18): discovery
 // (RFC 9728 protected-resource metadata → RFC 8414 AS metadata), RFC 7591 dynamic client
 // registration, the authorization-code + PKCE (S256) grant with a loopback redirect, RFC 8707
 // resource indicators, and the refresh grant. All of it runs in the ENGINE process: token
 // state never belongs to the run process, and the one interactive step is an explicit public
 // API (`Engine.authorizeMcpServer`) — a headless run that would need a human fails loudly
-// instead of prompting. Every external response is Zod-validated (CODE_QUALITY §2.1).
+// instead of prompting. Every external response is Zod-validated.
 import { createHash, randomBytes } from "node:crypto";
 import http from "node:http";
 import { z } from "zod";

package/dist/mcp/token_store.js

@@ -1,6 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
 // PARENT-side MCP OAuth token persistence. Tokens live with the engine — never in the run
 // process beyond the single brokered value a request needs — in one JSON file under the data
-// dir, mode 0600 (they are credentials; CODE_QUALITY §7.4 treats them like secrets: values
+// dir, mode 0600 (they are credentials, treated like secrets: values
 // never logged). Zod-validated on every read because a disk file is a trust boundary even
 // when we wrote it.
 import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";

package/dist/mcp/transport_http.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // MCP streamable-HTTP transport (spec rev 2025-06-18 §Transports): every client message is a
 // POST to the server URL; the response is either a single JSON body or an SSE stream of
 // JSON-RPC messages (one shared parser with the provider adapters — src/agent/sse.ts). The

package/dist/mcp/transport_stdio.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // MCP stdio transport: spawn the server command and speak newline-delimited JSON over its
 // stdin/stdout (the MCP stdio framing). Runs in the RUN PROCESS — the program is the trusted
 // layer, so its inline `command`/`env` are honored as-is; the server's stderr is inherited so

package/dist/run/child.js

@@ -1,7 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
 // The run-process entry point. Spawned by the supervisor with an IPC channel; never run
 // directly. Protocol: wait for `init`, install the SDK host + run inputs, then IMPORT the
 // program bundle — the module body is the program, so importing the file IS running it
-// (MASTER_SPEC §2.1; no entrypoint convention). Report `done`/`failed`, exit. A thrown error
+// (no entrypoint convention). Report `done`/`failed`, exit. A thrown error
 // anywhere is reported over IPC when possible — the supervisor treats an exit without a
 // report as a crash (which triggers restart-from-the-top, the documented semantics).
 import { pathToFileURL } from "node:url";

package/dist/run/child_host.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // The WorkflowHost installed in the run process.
 //
 // Split of responsibilities (SPEC §2.3): anything that only needs the local process happens
@@ -103,7 +104,7 @@ export function createChildHost(io, capabilities) {
 /** setTimeout's max delay (2^31-1 ms ≈ 24.8 days); longer sleeps are chunked. */
 const MAX_TIMEOUT_MS = 2_147_483_647;
 // Supervisor responses are validated like any other boundary input — the channel being ours
-// doesn't exempt it (CODE_QUALITY §2.1).
+// doesn't exempt it.
 const secretValueSchema = z.string();
 const runIdSchema = z.string().min(1);
 const artifactRefSchema = z.strictObject({

package/dist/run/idempotency.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Default idempotency keys for workflows.call / workflows.run.
 //
 // Contract (SDK CallOptions): "a deterministic key over (parent_run_id, target, input)" — a

package/dist/run/ipc.js

@@ -1,9 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
 // The supervisor ⇄ run-process IPC protocol.
 //
 // One run = one spawned Node process (SPEC §2.2). The child executes the user's program and
 // brokers its SDK hook calls back to the supervisor over Node's built-in IPC channel. Every
 // message is Zod-validated on receipt — the child runs user code, so everything it sends is a
-// trust boundary (CODE_QUALITY §2.1).
+// trust boundary.
 //
 // Envelope authority: the child sends event BODIES (no runId/turnId/seq/t); the supervisor is
 // the single place envelopes are stamped and cursors allocated, so cursor monotonicity holds

package/dist/run/run_dir.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // Per-run on-disk layout + the SDK-sharing symlink.
 //
 //   <dataDir>/runs/<runId>/
@@ -16,7 +17,7 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { z } from "zod";
 import { EngineError } from "../errors.js";
-// A file from disk is a trust boundary — parse, don't cast (CODE_QUALITY §2.1).
+// A file from disk is a trust boundary — parse, don't cast.
 const packageNameSchema = z.looseObject({ name: z.string().optional() });
 /** Lay out (or re-lay-out, on restart) the run directory for a program bundle. Idempotent. */
 export function prepareRunDir(dataDir, runId, program) {

package/dist/run/supervisor.js

@@ -1,8 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
 // The run supervisor — owns run-lifecycle state transitions and process supervision
-// (SPEC §2.2). Layering (CODE_QUALITY §7.2): knows nothing about HTTP or the CLI; persistence
+// (SPEC §2.2). Layering: knows nothing about HTTP or the CLI; persistence
 // goes through the Store; what workflows *do* lives in the child process.
 //
-// Semantics implemented here, identical in every engine (MASTER_SPEC §2.4):
+// Semantics implemented here, identical in every engine:
 //   - one run = one spawned process, isolated working directory
 //   - hold-and-pay: sleep holds the child; nothing here checkpoints
 //   - restart-on-crash: child death without a done/failed report restarts the run from the
@@ -308,7 +309,7 @@ export class RunSupervisor {
             if (deadline !== null) {
                 budgetTimer = setTimeout(() => {
                     entry.budgetReason ??= durationBudgetMessage(workflow.manifest);
-                    // Budget breach terminates immediately — enforced, not advisory (CODE_QUALITY §4.3).
+                    // Budget breach terminates immediately — enforced, not advisory.
                     child.kill("SIGKILL");
                 }, deadline - this.clock.now());
             }
@@ -377,7 +378,7 @@ export class RunSupervisor {
                         break;
                     case "memory_used":
                         // The child validated the path, but the parent persists it — re-check the shape
-                        // before it can ever reach a filesystem copy (CODE_QUALITY §2.1).
+                        // before it can ever reach a filesystem copy.
                         if (MEMORY_PATH_RE.test(msg.dir) && !msg.dir.includes("\\")) {
                             entry.memoryDirs.add(msg.dir);
                         }
@@ -511,7 +512,7 @@ export class RunSupervisor {
         if (target === null) {
             throw new EngineError("NOT_FOUND", `workflows.call target "${slug}" is not deployed on this engine.`, `Deploy it first — the engine only runs workflows it knows by name.`);
         }
-        // Crossed the JSON IPC channel, but narrow instead of assuming (CODE_QUALITY §2.1) — and
+        // Crossed the JSON IPC channel, but narrow instead of assuming — and
         // the canonical default key requires a JSON tree anyway.
         const jsonInput = input === undefined ? null : asJsonValue(input, "workflows.call input");
         const key = idempotencyKey ?? defaultIdempotencyKey(parentRunId, slug, jsonInput);

package/dist/scheduler/scheduler.d.ts

@@ -11,7 +11,7 @@ export interface SchedulerOptions {
     log?: (line: string) => void;
     /** Tick cadence of the background loop. Default 1s. */
     tickIntervalMs?: number;
-    /** Ticks slower than this are logged (CODE_QUALITY §4.2). Default 250ms. */
+    /** Ticks slower than this are logged. Default 250ms. */
     tickBudgetMs?: number;
 }
 export declare class Scheduler {

package/dist/server/http.d.ts

@@ -37,6 +37,6 @@ export declare function parseNonNegativeInt(url: URL, name: string, fallback: nu
 /**
  * The channel subscription for an event read (`/events` and `/stream` share this so a tail and
  * its catch-up reads can never disagree): `?verbose=true` = everything, `?channels=a,b` = an
- * explicit set, neither = MASTER_SPEC §2.5's default of lifecycle + phase + output.
+ * explicit set, neither = the default of lifecycle + phase + output.
  */
 export declare function parseChannelSelection(url: URL): readonly Channel[];

package/dist/server/http.js

@@ -1,8 +1,4 @@
-// Shared HTTP plumbing for the engine server: the error type every route throws, JSON
-// request/response helpers, and query/body parsing. Bare node:http is deliberate (no
-// third-party HTTP framework anywhere in the Boardwalk stack) — these helpers are the entire
-// "framework", so every trust boundary (bodies, query params, headers) is narrowed with Zod
-// or a type predicate before any engine call sees the data.
+// SPDX-License-Identifier: Apache-2.0
 import { z } from "zod";
 import { CHANNELS, DEFAULT_CHANNELS } from "@boardwalk-labs/workflow";
 import { EngineError } from "../errors.js";
@@ -160,7 +156,7 @@ function isChannel(value) {
 /**
  * The channel subscription for an event read (`/events` and `/stream` share this so a tail and
  * its catch-up reads can never disagree): `?verbose=true` = everything, `?channels=a,b` = an
- * explicit set, neither = MASTER_SPEC §2.5's default of lifecycle + phase + output.
+ * explicit set, neither = the default of lifecycle + phase + output.
  */
 export function parseChannelSelection(url) {
     const verbose = url.searchParams.get("verbose");

package/dist/server/routes/api.d.ts

@@ -10,7 +10,7 @@ export declare function handleGetRun(ctx: RouteContext, runId: string): void;
 /**
  * GET /api/runs/:id/events?after=&channels=|verbose= — persisted events after a cursor,
  * filtered server-side by channel. Cursors are run-global and untouched by filtering, so a
- * client can resume here (or on /stream) with any channel set (MASTER_SPEC §2.5).
+ * client can resume here (or on /stream) with any channel set.
  */
 export declare function handleListEvents(ctx: RouteContext, runId: string): void;
 /** POST /api/runs/:id/cancel — 202: accepted now, completes after the cooperative grace. */

package/dist/server/routes/api.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // The JSON API (SPEC §2.4): list workflows/runs, trigger a manual run, read a run + its
 // events, cancel. Handlers translate HTTP into engine/store calls and nothing else — all SQL
 // lives in the store, all run semantics in the engine.
@@ -80,7 +81,7 @@ export function handleGetRun(ctx, runId) {
 /**
  * GET /api/runs/:id/events?after=&channels=|verbose= — persisted events after a cursor,
  * filtered server-side by channel. Cursors are run-global and untouched by filtering, so a
- * client can resume here (or on /stream) with any channel set (MASTER_SPEC §2.5).
+ * client can resume here (or on /stream) with any channel set.
  */
 export function handleListEvents(ctx, runId) {
     if (ctx.engine.store.getRun(runId) === null) {

package/dist/server/routes/hooks.js

@@ -1,5 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
 // POST /hooks/:workflow/:triggerIndex — the webhook trigger endpoint, and this engine's v0
-// answer to MASTER_SPEC §10's open webhook-auth question (documented in SPEC §2.4):
+// answer to the open webhook-auth question (documented in SPEC §2.4):
 // per-workflow credentials live in *server* environment variables —
 //   token auth:     BOARDWALK_WEBHOOK_TOKEN__<NAME>   vs  `Authorization: Bearer <token>`
 //   signature auth: BOARDWALK_WEBHOOK_SECRET__<NAME>  vs  `X-Boardwalk-Signature: sha256=<hex>`

package/dist/server/routes/router.js

@@ -1,7 +1,4 @@
-// URL → handler resolution for the engine server. One flat match over decoded path segments —
-// the route table is small enough that a real trie/middleware stack would be pure ceremony.
-// Method mismatches on a known path get 405 + Allow (not 404), so clients can tell "wrong
-// verb" from "no such thing".
+// SPDX-License-Identifier: Apache-2.0
 import { HttpError } from "../http.js";
 import { handleCancelRun, handleGetRun, handleListEvents, handleListRuns, handleListWorkflows, handleStartRun, } from "./api.js";
 import { handleWebhook } from "./hooks.js";

package/dist/server/routes/stream.js

@@ -1,4 +1,5 @@
-// GET /api/runs/:id/stream — the SSE live tail (SPEC §2.4, MASTER_SPEC §2.5): replay
+// SPDX-License-Identifier: Apache-2.0
+// GET /api/runs/:id/stream — the SSE live tail (SPEC §2.4): replay
 // persisted events after the resume cursor, then follow live ones. Every frame carries
 // `id: <cursor>`, so a dropped client reconnects with Last-Event-ID and misses nothing —
 // cursors are run-global and independent of channel filtering, which keeps filtered resumes

package/dist/server/routes/ui.js

@@ -1,7 +1,4 @@
-// GET / — the local run-log page (SPEC §2.4): one self-contained HTML document, no build
-// step, no external assets. It is a log viewer, not a console: list workflows, list recent
-// runs, click a run to tail it over the SSE endpoint. All rendering uses textContent — no
-// markup is ever built from API data, so nothing a workflow prints can inject into the page.
+// SPDX-License-Identifier: Apache-2.0
 export function handleUiPage(ctx) {
     ctx.res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
     ctx.res.end(RUN_LOG_PAGE);

package/dist/server/server.js

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
 // The engine's HTTP surface (SPEC §2.4): JSON API + SSE live tail + webhook triggers + the
 // local run-log page, on bare node:http. This file owns the socket lifecycle only — routing
 // lives in routes/router.ts, and every handler goes through engine/store methods, never SQL.

package/dist/server_main.d.ts

@@ -11,6 +11,12 @@ export interface ServerConfig {
     inference: InferenceConfig | undefined;
     /** Explicit BOARDWALK_ENV_FILE path; undefined means "use <dataDir>/.env if it exists". */
     envFile: string | undefined;
+    /**
+     * Directory of built workflow programs deployed on boot (the self-host deploy mechanism):
+     * each `.mjs`/`.js` file is one workflow (single-file, `@boardwalk-labs/workflow` external —
+     * what `boardwalk build` emits). Defaults to `<dataDir>/workflows`.
+     */
+    workflowsDir: string;
 }
 /**
  * Parse server config from an environment map. Pure (no filesystem, no process globals) so

package/dist/server_main.js

@@ -1,13 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
 // The composition root for the `boardwalk-server` binary (SPEC §2.4 + §5): parse config,
 // construct the Engine, mount the HTTP surface, wire graceful shutdown. Everything here is
 // glue — run semantics live in the engine, routing in the server, so this file stays thin
 // enough that config parsing (tested below) plus the already-tested pieces carry the risk.
 //
 // Config is ENVIRONMENT VARIABLES ONLY in v0 (`BOARDWALK_` prefix). A `boardwalk.toml` file
-// is deferred: Node has no TOML built-in and the zero-dependency rule (CODE_QUALITY §10)
+// is deferred: Node has no TOML built-in and the zero-dependency rule
 // beats a hand-rolled parser. Env vars are also what Docker/systemd operators reach for
 // first, so the deferral costs nothing in practice.
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { parseEnv } from "node:util";
 import { z } from "zod";
@@ -115,8 +116,40 @@ export function loadServerConfig(env) {
         port: parsePort(get("BOARDWALK_PORT")),
         inference,
         envFile: get("BOARDWALK_ENV_FILE"),
+        workflowsDir: get("BOARDWALK_WORKFLOWS_DIR") ?? join(dataDir, "workflows"),
     };
 }
+/**
+ * Deploy every built workflow in `dir` on boot — the self-host deploy mechanism. Each `.mjs`/`.js`
+ * file is one workflow's program (single-file, `@boardwalk-labs/workflow` external — what
+ * `boardwalk build` emits). Idempotent by manifest name (re-boot re-syncs the dir into the store);
+ * a removed file leaves its last-deployed workflow in place (no un-deploy in v0). A missing dir is
+ * fine (an operator may deploy by other means); a bad file is logged and skipped, never fatal.
+ */
+function deployWorkflowsFromDir(engine, dir, log) {
+    if (!existsSync(dir))
+        return;
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter((name) => name.endsWith(".mjs") || name.endsWith(".js"))
+            .sort();
+    }
+    catch (err) {
+        log(`workflows dir ${dir} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    for (const file of files) {
+        try {
+            const program = readFileSync(join(dir, file), "utf8");
+            const workflow = engine.deployWorkflow({ program });
+            log(`deployed "${workflow.name}" from ${file}`);
+        }
+        catch (err) {
+            log(`skipped ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
 /**
  * Resolve the engine's secret/env source (SPEC §2.3 `secrets.get`): the configured
  * BOARDWALK_ENV_FILE, else `<dataDir>/.env` when present. An explicitly named file that does
@@ -157,6 +190,8 @@ export async function startServer(config, log) {
         const swept = engine.start();
         log(`recovery sweep: restarted ${String(swept.resumed.length)} run(s), ` +
             `cancelled ${String(swept.cancelled.length)}`);
+        // Self-host deploy: sync the workflows dir into the store before serving (idempotent).
+        deployWorkflowsFromDir(engine, config.workflowsDir, log);
         const server = createEngineServer(engine, { host: config.host, log });
         const { port } = await server.listen(config.port);
         log(`data dir: ${resolve(config.dataDir)}`);

package/dist/store/migrations.js

@@ -1,18 +1,8 @@
-// Versioned, forward-only schema migrations for the engine database.
-//
-// The schema version lives in SQLite's `PRAGMA user_version` (an integer in the database
-// header): reading it costs nothing, needs no bookkeeping table, and — crucially — setting it
-// participates in the same transaction as the migration's DDL. A crash mid-migration therefore
-// leaves the database exactly at the previous version with none of the new schema applied
-// (CODE_QUALITY §2.2: multi-row writes are transactional; a half-migrated database is a state
-// the engine could not recover from).
-//
-// Forward-only: an older engine refuses a newer database instead of guessing what future
-// columns mean. Downgrades are restore-from-backup, not code.
+// SPDX-License-Identifier: Apache-2.0
 import { EngineError } from "../errors.js";
 // v1 — the full SPEC §4 schema. STRICT tables so SQLite enforces the declared column types
 // (a TEXT primary key can never silently hold an integer; INTEGER columns reject REALs).
-// All timestamps are integer milliseconds since epoch; all ids are ULIDs (CODE_QUALITY §2.2).
+// All timestamps are integer milliseconds since epoch; all ids are ULIDs.
 const V1_SQL = `
 -- Workflows: the deployed unit. \`manifest\` is the validated JSON projection of the program's
 -- pure-literal meta; \`program\` is the bundled ESM source the run host executes; \`config\` is

package/dist/store/store.js

@@ -1,9 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
 // The engine's one persistence module — every SQL statement in the engine lives here
-// (CODE_QUALITY §7.2: "storage access goes through one persistence module"). The backend is
+// (storage access goes through one persistence module). The backend is
 // node:sqlite, synchronous on purpose: a single-node engine gains nothing from an async
 // driver, and synchronous statements make multi-row invariants trivially transactional.
 //
-// Conventions (CODE_QUALITY §2.2): ULID primary keys, integer-ms timestamps, and JSON columns
+// Conventions: ULID primary keys, integer-ms timestamps, and JSON columns
 // Zod-validated on READ — a row that fails validation throws EngineError("INTERNAL") naming
 // the table and column, so corrupt state surfaces as a loud error instead of flowing into the
 // scheduler as data.
@@ -14,7 +15,7 @@ import { EngineError } from "../errors.js";
 import { ulid } from "../ids.js";
 import { migrate } from "./migrations.js";
 // ============================================================================
-// Column schemas — every JSON/enum column has exactly one validator (CODE_QUALITY §2.2)
+// Column schemas — every JSON/enum column has exactly one validator
 // ============================================================================
 /**
  * Build a Zod enum from an exhaustive flag record. Why a Record and not a plain array: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boardwalk-labs/engine",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The Boardwalk single-node engine: cron scheduling, run lifecycle, SQLite state, and the local run log. Powers `boardwalk dev` and the self-hosted server.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,7 +40,7 @@
     "coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@boardwalk-labs/workflow": "^0.1.0",
+    "@boardwalk-labs/workflow": "^0.1.2",
     "zod": "^4.0.0"
   },
   "devDependencies": {