@juicesharp/rpiv-workflow 1.14.0

package/internal-utils.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal utilities shared across the rpiv-workflow package.
+ *
+ * Not part of the public surface — not re-exported from `index.ts`. If a
+ * helper graduates into the documented authoring or embedding contract,
+ * move it out of here and into the appropriate domain module.
+ */
+
+import { isAbsolute, join } from "node:path";
+import type { StageDef } from "./api.js";
+import type { Artifact } from "./handle.js";
+import type { RunState } from "./types.js";
+
+/** Exhaustiveness guard for discriminated-union switches. */
+export function assertNever(value: never): never {
+	throw new Error(`assertNever: unreachable value ${String(value)}`);
+}
+
+/**
+ * Canonical accessor for "the primary artifact the chain is currently
+ * carrying." Reads the rolling slot maintained by the runner —
+ * produces stages update it on success; side-effect stages leave it
+ * alone. Replaces the load-bearing single-string artifact_path mirror
+ * from the pre-collector shape.
+ */
+export function currentPrimaryArtifact(state: RunState): Artifact | undefined {
+	return state.primaryArtifact;
+}
+
+/**
+ * Resolve the `state.named` key a produces stage appends its `Output`
+ * envelope onto. Two layers of fallback, in priority order:
+ *   1. `stage.outcome?.name` — categorical name carried by the outcome.
+ *   2. The stage's record key — always defined.
+ *
+ * Single source of truth for the key derivation so the skill-stage path
+ * and the script-stage path stay in lockstep, and so `validateWorkflow`
+ * can compute the same key set at load time.
+ */
+export function resolvePublishName(def: StageDef, stageName: string): string {
+	return def.outcome?.name ?? stageName;
+}
+
+/**
+ * Race a promise against `ms`. The inner promise is NOT cancelled — Pi's
+ * `ctx.waitForIdle()` has no abort signal today; the dangling promise becomes
+ * inert when the next stage's `newSession` replaces the ctx.
+ */
+export async function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new Error(message)), ms);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+/**
+ * Resolve `p` against `cwd`. Returns `p` unchanged if it is already absolute;
+ * otherwise joins `cwd + p` with the platform path separator. Uses
+ * `path.isAbsolute` so Windows drive-letter paths are handled correctly
+ * (POSIX-only `startsWith("/")` checks miss `C:\...`).
+ */
+export function resolveUnderCwd(cwd: string, p: string): string {
+	return isAbsolute(p) ? p : join(cwd, p);
+}

package/internal.ts

@@ -0,0 +1,27 @@
+/**
+ * Test-only / framework-internal surface.
+ *
+ * Exports below are NOT part of the package's authoring or embedding
+ * contract. They exist solely for:
+ *
+ *   - rpiv-pi's `[I3]` regression test that exercises `recordStage`
+ *     directly (asserting the JSONL append + stageNumber monotonicity).
+ *   - `test/setup.ts`'s per-worker `beforeEach` reset of module-level
+ *     singleton state (the built-in workflow registry, the jiti import
+ *     cache).
+ *
+ * Anything that consumers can rely on for production work lives on
+ * `./index.js`. This file is reachable as
+ * `@juicesharp/rpiv-workflow/internal` via the package's `exports`
+ * field — keep that path stable so the rpiv-pi test + repo-wide
+ * setup don't break.
+ *
+ * Adding a new export here is a signal you have test-coupling to
+ * production state. Reach for it sparingly; prefer making the
+ * production module itself idempotent across `beforeEach` resets.
+ */
+
+export { recordStage } from "./audit.js";
+export { __resetBuiltIns, getBuiltIns } from "./built-ins.js";
+export { __resetLifecycleRegistry } from "./lifecycle.js";
+export { __resetLoadCache } from "./load/cache.js";

package/layers.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared layer-vocabulary for the workflow loader + validator.
+ *
+ * Lives in its own module so `load.ts` (loader / merge) and `validate-workflow.ts`
+ * (issue attribution) can both reference the same union without a circular
+ * import. `load.ts` depends on `validate-workflow.ts` for `validateWorkflow`, so
+ * declaring `ConfigLayer` here keeps the dependency direction strict and
+ * eliminates the silent-drift risk of two parallel string-literal unions.
+ */
+
+import { assertNever } from "./internal-utils.js";
+
+export type ConfigLayer = "built-in" | "user" | "project";
+
+/**
+ * Single source for layer → display string. Wrap every interpolation site
+ * (`${layer}` in template strings, banner builders, issue prefixes) in this
+ * helper so adding a new `ConfigLayer` value surfaces as a compile error at
+ * every consumer, not just at the loader's switch. The current display
+ * form is the layer name verbatim — keep that invariant if you change it.
+ */
+export function renderConfigLayer(layer: ConfigLayer): string {
+	switch (layer) {
+		case "built-in":
+			return "built-in";
+		case "user":
+			return "user";
+		case "project":
+			return "project";
+		default:
+			return assertNever(layer);
+	}
+}

package/lifecycle.ts

@@ -0,0 +1,274 @@
+/**
+ * Lifecycle callbacks — typed observation surface for in-flight runs.
+ *
+ * Two subscription paths converge through the same `LifecycleListeners`
+ * shape:
+ *
+ *   - **Per-call** — embedders set `RunWorkflowOptions.lifecycle?` when
+ *     driving `runWorkflow` directly.
+ *   - **Global** — sibling extensions (rpiv-pi widget, future metrics)
+ *     call `registerLifecycle(listeners)` at extension load. Returns a
+ *     disposer; multiple registrations fan out per event.
+ *
+ * Every event fires AFTER the corresponding JSONL row lands on disk
+ * (onStageEnd / onStageError / onRoute / onFanoutUnitEnd). Listeners
+ * thus see consistent state when they read past rows via
+ * `readLastStage` / `readAllStages`.
+ *
+ * Listener throws are caught + logged via `ctx.ui.notify(..., "warning")`
+ * and never halt the run — listeners are observers, not gates. Other
+ * registered listeners still fire normally.
+ *
+ * Pre-flight rejections (`workflow.start` not declared, continue-policy
+ * without a host) fire ZERO lifecycle events — the run never acquired
+ * a `runId` and lifecycle events would deliver an incomplete context.
+ * The `RunWorkflowResult` envelope still surfaces the error to the
+ * caller through the existing path.
+ */
+
+import type { FanoutUnit } from "./api.js";
+import { MSG_LIFECYCLE_THREW } from "./messages.js";
+import type { Output } from "./output.js";
+import type { RunWorkflowResult } from "./runner/runner.js";
+import type { RunTrigger } from "./triggers.js";
+import type { RunState } from "./types.js";
+
+/**
+ * Run-scoped context shared by every lifecycle callback. Mirrors the
+ * shape `EdgeContext` and `FanoutContext` already use (frozen identity
+ * + `Readonly<RunState>`) so listeners reconstruct "where am I" without
+ * widening the per-event payload.
+ */
+export interface LifecycleContext {
+	cwd: string;
+	runId: string;
+	workflow: string;
+	totalStages: number;
+	/** What triggered this run; defaulted at `runWorkflow` entry if `options.trigger` was omitted. */
+	trigger: RunTrigger;
+	state: Readonly<RunState>;
+}
+
+/**
+ * Projection of a stage as observed by a listener — the runner's
+ * internal resolved view minus its `def` field (which leaks DSL
+ * internals). Distinct from `StageDef` (authored shape) and
+ * `WorkflowStage` (JSONL row).
+ *
+ * Discriminated on `kind`:
+ *   - `"skill"`  — stage dispatches a Pi skill body (`/skill:<skill>`).
+ *   - `"script"` — stage runs a TS function; no skill body.
+ */
+export type StageRef =
+	| { kind: "skill"; name: string; stageNumber: number; skill: string }
+	| { kind: "script"; name: string; stageNumber: number };
+
+/**
+ * Opt-in lifecycle listeners. Single subscriber per slot per bundle —
+ * fan-out is a userland wrapper. Every callback may return a Promise;
+ * the runner awaits it before advancing (back-pressure for free).
+ *
+ * Every event fires AFTER its corresponding JSONL row lands on disk
+ * (onStageEnd / onStageError / onRoute / onFanoutUnitEnd), so a
+ * listener that calls `readLastStage(cwd, ctx.runId)` from inside the
+ * callback is guaranteed to observe the just-recorded row.
+ *
+ * Listener throws are caught + surfaced via `ctx.ui.notify(..., "warning")`
+ * and never halt the run — listeners are observers, not gates.
+ *
+ * @example Per-call observation from an embedder
+ * ```ts
+ * import { runWorkflow, type LifecycleListeners } from "@juicesharp/rpiv-workflow";
+ *
+ * const listeners: LifecycleListeners = {
+ *   onWorkflowStart: (ctx) =>
+ *     console.log(`▶ ${ctx.workflow} (${ctx.totalStages} stages) [${ctx.trigger.kind}]`),
+ *   onStageStart:    (stage)               => console.log(`  → ${stage.stageNumber}. ${stage.name}`),
+ *   onStageEnd:      (stage, output)       => console.log(`  ✓ ${stage.name}: ${output.kind}`),
+ *   onStageRetry:    (stage, attempt)      => console.warn(`  ⟲ ${stage.name} retry #${attempt}`),
+ *   onStageError:    (stage, error)        => console.error(`  ✗ ${stage.name}: ${error}`),
+ *   onRoute:         (from, to)            => console.log(`  ↪ ${from.name} → ${to}`),
+ *   onFanoutStart:   (stage, units)        => console.log(`  ⇉ ${stage.name} × ${units.length}`),
+ *   onFanoutUnitEnd: (stage, _u, i)        => console.log(`     · ${stage.name} #${i}`),
+ *   onWorkflowEnd:   (result)              =>
+ *     console.log(result.success ? "✓ done" : `✗ ${result.error ?? "halted"}`),
+ * };
+ *
+ * await runWorkflow({ workflow, input, host, lifecycle: listeners });
+ * ```
+ *
+ * @example Cross-package fan-out via `registerLifecycle`
+ * ```ts
+ * import { registerLifecycle } from "@juicesharp/rpiv-workflow";
+ *
+ * const dispose = registerLifecycle({
+ *   onWorkflowStart: (ctx) => widget.open(ctx.runId, ctx.workflow),
+ *   onStageEnd:      (stage, _o, ctx) => widget.markDone(ctx.runId, stage.name),
+ * });
+ * ```
+ */
+export interface LifecycleListeners {
+	/** After JSONL header lands; before the start stage's preflight. */
+	onWorkflowStart?(ctx: LifecycleContext): void | Promise<void>;
+
+	/** After preflight + skill check; before the Pi session opens (or `run()` is called for script stages). */
+	onStageStart?(stage: StageRef, ctx: LifecycleContext): void | Promise<void>;
+
+	/** After the stage's success row lands in JSONL. `output` is the validated envelope. */
+	onStageEnd?(stage: StageRef, output: Output, ctx: LifecycleContext): void | Promise<void>;
+
+	/** After `outputSchema` rejection, before the runner re-prompts. `attempt` is 1-based. */
+	onStageRetry?(stage: StageRef, attempt: number, ctx: LifecycleContext): void | Promise<void>;
+
+	/** After the stage's "failed"/"aborted" row lands in JSONL. Terminal for the run. */
+	onStageError?(stage: StageRef, error: string, ctx: LifecycleContext): void | Promise<void>;
+
+	/** After an `EdgeFn` picks and its routing-decision row lands. `to` may be the `STOP` sentinel literal `"stop"`. */
+	onRoute?(from: StageRef, to: string, ctx: LifecycleContext): void | Promise<void>;
+
+	/** After the `FanoutFn` returns ≥1 units; before unit 1's session opens. */
+	onFanoutStart?(stage: StageRef, units: readonly FanoutUnit[], ctx: LifecycleContext): void | Promise<void>;
+
+	/** Per-unit, before the unit's session opens. `unitIndex` is 1-based. */
+	onFanoutUnitStart?(
+		stage: StageRef,
+		unit: FanoutUnit,
+		unitIndex: number,
+		ctx: LifecycleContext,
+	): void | Promise<void>;
+
+	/** Per-unit, after the unit's JSONL row lands. */
+	onFanoutUnitEnd?(stage: StageRef, unit: FanoutUnit, unitIndex: number, ctx: LifecycleContext): void | Promise<void>;
+
+	/** Last call — `result` is the same envelope `runWorkflow` returns. */
+	onWorkflowEnd?(result: RunWorkflowResult, ctx: LifecycleContext): void | Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal — dispatcher (consumed by the runner; not exported publicly)
+// ---------------------------------------------------------------------------
+
+/** Subset of `WorkflowContext` the dispatcher needs for throw-safe logging. */
+export interface DispatchHost {
+	ui: { notify(message: string, level?: "info" | "warning" | "error"): void };
+}
+
+/**
+ * Fan-out + throw-safe invoker for one event across every registered
+ * listener bundle. Constructed once per `runWorkflow` call and threaded
+ * through `RunContext` so every firing site uses the same instance.
+ *
+ * Snapshot semantics: `collectBundles` is called per `fire(...)`, so a
+ * registration made mid-event (`registerLifecycle` from inside a
+ * callback) applies to subsequent events but not the in-flight one.
+ *
+ * Sequential await: bundles run in registration order; the per-call
+ * bundle (when present) fires after every globally-registered bundle.
+ * `await` between them gives listeners back-pressure for free.
+ */
+export class LifecycleDispatcher {
+	constructor(private readonly perCall: LifecycleListeners | undefined) {}
+
+	async fire<E extends keyof LifecycleListeners>(
+		host: DispatchHost,
+		event: E,
+		...args: Parameters<NonNullable<LifecycleListeners[E]>>
+	): Promise<void> {
+		for (const bundle of collectBundles(this.perCall)) {
+			const fn = bundle[event];
+			if (!fn) continue;
+			try {
+				await (fn as (...a: unknown[]) => unknown)(...(args as unknown[]));
+			} catch (e) {
+				const reason = e instanceof Error ? e.message : String(e);
+				host.ui.notify(MSG_LIFECYCLE_THREW(event, reason), "warning");
+			}
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Global registry — cross-package fan-out
+// ---------------------------------------------------------------------------
+
+/**
+ * Anchored on a `Symbol.for` slot so a duplicate module load (extension +
+ * sibling cross-package resolution) shares one registry. Same pattern
+ * `registerBuiltIns` uses for the workflow registry.
+ */
+const REGISTRY_KEY = Symbol.for("@juicesharp/rpiv-workflow:lifecycle");
+
+type Global = Record<symbol, unknown>;
+
+function getRegistry(): LifecycleListeners[] {
+	const g = globalThis as unknown as Global;
+	let registry = g[REGISTRY_KEY] as LifecycleListeners[] | undefined;
+	if (!registry) {
+		registry = [];
+		g[REGISTRY_KEY] = registry;
+	}
+	return registry;
+}
+
+/**
+ * Register a cross-package lifecycle-listener bundle. Returns a disposer
+ * that removes it. Multiple registrations coexist — every fired event walks
+ * the full registry in registration order, then the per-call bundle.
+ *
+ * Snapshot semantics: each `fire(...)` call observes the registry as it
+ * stands at that instant. A registration made mid-event applies to
+ * subsequent events but not the in-flight one.
+ *
+ * Throws from listeners are caught + logged via `ctx.ui.notify(..., "warning")`
+ * and never halt the run. One listener bug never affects other listeners
+ * or the run itself.
+ */
+export function registerLifecycle(listeners: LifecycleListeners): () => void {
+	const registry = getRegistry();
+	registry.push(listeners);
+	return () => {
+		const idx = registry.indexOf(listeners);
+		if (idx >= 0) registry.splice(idx, 1);
+	};
+}
+
+/**
+ * Test reset — wired into the repo-wide test setup so cross-test
+ * registration leaks don't bias the next case.
+ */
+export function __resetLifecycleRegistry(): void {
+	getRegistry().length = 0;
+}
+
+/**
+ * Globally-registered bundles fire first (in registration order), then
+ * the per-call bundle. Snapshot at fire time — a registration made
+ * inside a listener body applies to subsequent events, not the
+ * in-flight one.
+ */
+function collectBundles(perCall: LifecycleListeners | undefined): readonly LifecycleListeners[] {
+	const global = getRegistry();
+	return perCall ? [...global, perCall] : [...global];
+}
+
+/** Build a `LifecycleContext` from the runner's per-run identity. */
+export function buildLifecycleContext(args: {
+	cwd: string;
+	runId: string;
+	workflow: string;
+	totalStages: number;
+	trigger: RunTrigger;
+	state: Readonly<RunState>;
+}): LifecycleContext {
+	return args;
+}
+
+/** Build the `"skill"` arm of `StageRef`. */
+export function skillStageRef(name: string, stageNumber: number, skill: string): StageRef {
+	return { kind: "skill", name, stageNumber, skill };
+}
+
+/** Build the `"script"` arm of `StageRef` — skillless TS stages. */
+export function scriptStageRef(name: string, stageNumber: number): StageRef {
+	return { kind: "script", name, stageNumber };
+}

package/load/cache.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Direct tests for the mtime-keyed jiti import cache. Exercises both the
+ * cache-miss path (fresh `jiti.import`) and the cache-hit path (returns
+ * the stored parsed value without re-evaluating top-level code).
+ *
+ * `loadWorkflows` integration tests cover the cache miss every time
+ * (each `loadWorkflows` call hits the file once); the cache-hit branch
+ * only fires when the same path is imported twice within one
+ * `__resetLoadCache()` boundary, which `test/setup.ts:beforeEach`
+ * normally prevents. These tests opt out of the global reset by calling
+ * `cachedImport` directly.
+ */
+
+import { mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { __resetLoadCache, cachedImport } from "./cache.js";
+
+const TMP_ROOT = mkdtempSync(join(tmpdir(), "rpiv-workflow-cache-"));
+
+beforeEach(() => {
+	__resetLoadCache();
+});
+
+afterEach(() => {
+	__resetLoadCache();
+});
+
+// One-shot cleanup so we don't leak the tmp directory.
+process.on("exit", () => {
+	rmSync(TMP_ROOT, { recursive: true, force: true });
+});
+
+const writeFixture = (name: string, body: string): string => {
+	const path = join(TMP_ROOT, name);
+	writeFileSync(path, body, "utf-8");
+	return path;
+};
+
+describe("cachedImport", () => {
+	it("returns the parsed default export on first call (cache miss)", async () => {
+		const path = writeFixture("miss.ts", "export default 'first';\n");
+		const value = await cachedImport(path);
+		expect(value).toBe("first");
+	});
+
+	it("returns the cached value when mtime is unchanged (cache hit)", async () => {
+		const path = writeFixture("hit.ts", "export default { v: 1 };\n");
+		const first = await cachedImport(path);
+		const second = await cachedImport(path);
+		// Same reference — proves the second call short-circuited via the cache
+		// (a re-evaluated `jiti.import` would return a freshly-allocated object).
+		expect(second).toBe(first);
+	});
+
+	it("re-imports when mtime advances (edit invalidates the cache)", async () => {
+		const path = writeFixture("edit.ts", "export default 'v1';\n");
+		const first = await cachedImport(path);
+		expect(first).toBe("v1");
+
+		// Rewrite + bump mtime far enough that the cache key changes even on
+		// coarse-mtime filesystems.
+		writeFileSync(path, "export default 'v2';\n", "utf-8");
+		const future = new Date(Date.now() + 60_000);
+		utimesSync(path, future, future);
+
+		const second = await cachedImport(path);
+		expect(second).toBe("v2");
+	});
+
+	it("__resetLoadCache forces a fresh re-import on the next call", async () => {
+		const path = writeFixture("reset.ts", "export default { tag: 'x' };\n");
+		const first = await cachedImport(path);
+		__resetLoadCache();
+		const second = await cachedImport(path);
+		// Different references prove the reset cleared the entry — jiti returned
+		// a freshly-evaluated object.
+		expect(second).not.toBe(first);
+		expect(second).toEqual(first);
+	});
+});

package/load/cache.ts

@@ -0,0 +1,40 @@
+/**
+ * mtime-keyed jiti import cache. jiti's own caches are disabled so `/reload`
+ * picks up edits without restart; this wrapper layers a stat-driven cache
+ * on top so unchanged overlays don't re-evaluate top-level code on every
+ * `/wf` invocation.
+ *
+ * The `jiti` instance lives here so the cache and the underlying importer
+ * co-locate. Other loader modules import `cachedImport` — none touches
+ * `jiti` directly.
+ *
+ * The cache does not invalidate on file deletion — a stale entry for a
+ * deleted overlay sits dormant (the enumerator never passes it back to
+ * `cachedImport`). The cache resets on `__resetLoadCache()` (wired into
+ * `test/setup.ts` `beforeEach`) and on process exit.
+ */
+
+import { statSync } from "node:fs";
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, {
+	// Bypass jiti's module cache so /reload picks up edits without restart.
+	moduleCache: false,
+	fsCache: false,
+});
+
+const overlayCache = new Map<string, { mtimeMs: number; parsed: unknown }>();
+
+export async function cachedImport(path: string): Promise<unknown> {
+	const stat = statSync(path);
+	const cached = overlayCache.get(path);
+	if (cached && cached.mtimeMs === stat.mtimeMs) return cached.parsed;
+	const value = await jiti.import(path, { default: true });
+	overlayCache.set(path, { mtimeMs: stat.mtimeMs, parsed: value });
+	return value;
+}
+
+/** Test-only reset. Wired into `test/setup.ts` `beforeEach`. */
+export function __resetLoadCache(): void {
+	overlayCache.clear();
+}

package/load/index.ts

@@ -0,0 +1,159 @@
+/**
+ * jiti-based loader for user-authored workflows.
+ *
+ * Layered merge: `built-in` ← `user` ← `project`. Within each non-built-in
+ * layer, pack files merge first (alpha-sorted filename), then the
+ * config file — so the file the user wrote by hand wins over any packs
+ * they installed.
+ *
+ * Paths (per layer):
+ *   user    — config  `~/.config/rpiv-workflow/workflows.config.ts`
+ *             packs   `~/.config/rpiv-workflow/workflows/*.ts`
+ *   project — config  `<cwd>/.rpiv-workflow/workflows.config.ts`
+ *             packs   `<cwd>/.rpiv-workflow/workflows/*.ts`
+ *
+ * Config file — accepts three default-export shapes:
+ *   1. A single `Workflow`               — single-entry namespace
+ *   2. `Workflow[]`                      — multi-entry, default required if > 1
+ *   3. `{ workflows, default? }`         — full envelope, explicit default
+ *
+ * Pack file — accepts only `Workflow | Workflow[]`. The envelope form
+ * is rejected because `default` lives in the config file (one source of
+ * truth per layer).
+ *
+ * `default` cascades layer-by-layer (project config > user config >
+ * first registered workflow in insertion order). When no workflows are
+ * registered at all, `default` is `undefined` and `command.ts` surfaces
+ * a "no workflows registered" notify instead of running anything. Within
+ * a layer only the config file can set `default`.
+ *
+ * jiti loads `.ts` directly — no build step required of users. Loader
+ * failures (file throws on import, exports the wrong shape) are captured as
+ * `LoadIssue`s; the loader itself never throws to its caller.
+ *
+ * SECURITY NOTE — `jiti.import` synchronously evaluates every overlay
+ * file's top-level code on first load and on every edit (mtime-driven
+ * invalidation via `cache.ts`). The threat boundary is the same as
+ * `npm install` (post-install scripts), `tsx some-script.ts`, or any
+ * tool that respects `<cwd>` configuration: Pi already operates in a
+ * context that implicitly trusts the current working directory. Users
+ * running Pi in a freshly-cloned untrusted repo should diff
+ * `.rpiv-workflow/workflows.config.ts` and `.rpiv-workflow/workflows/*.ts`
+ * (the config file + pack files) before running `/wf`.
+ *
+ * Module map:
+ *   ./paths.ts            — OverlayPaths + per-layer path helpers
+ *   ./shape-guards.ts     — isWorkflow, isEnvelope, describe, formatError
+ *   ./normalize.ts        — normalizeDefaultExport + NormalizeResult
+ *   ./merge.ts            — LoadAccumulator, LayerOutcome, loadLayer, mergeOverlay, loadError
+ *   ./resolve-default.ts  — resolveDefault (first-workflow fallback)
+ *   ./cache.ts            — mtime-keyed jiti import cache + __resetLoadCache
+ */
+
+import type { Workflow } from "../api.js";
+import { getBuiltIns } from "../built-ins.js";
+import type { ConfigLayer } from "../layers.js";
+import { validateWorkflow, type WorkflowValidationIssue } from "../validate-workflow.js";
+import { type LoadAccumulator, loadLayer } from "./merge.js";
+import { projectOverlayPaths, userOverlayPaths } from "./paths.js";
+import { resolveDefault } from "./resolve-default.js";
+
+// ===========================================================================
+// Public types
+// ===========================================================================
+
+export type { ConfigLayer } from "../layers.js";
+export { __resetLoadCache } from "./cache.js";
+export type { OverlayPaths } from "./paths.js";
+export { projectOverlayPaths, userOverlayPaths } from "./paths.js";
+
+export interface LoadIssue {
+	kind: "load";
+	layer: ConfigLayer;
+	path?: string;
+	severity: "error" | "warning";
+	message: string;
+}
+
+export type Issue = LoadIssue | (WorkflowValidationIssue & { kind: "validation"; layer: ConfigLayer; path?: string });
+
+export interface LoadedWorkflows {
+	workflows: readonly Workflow[];
+	/**
+	 * Resolved default workflow name. `undefined` when no layer registered any
+	 * workflows — consumers must handle this (see `command.ts`'s
+	 * "no workflows registered" path).
+	 */
+	default: string | undefined;
+	/** Which layer each merged workflow name came from. */
+	workflowSources: ReadonlyMap<string, ConfigLayer>;
+	/** Every layer that registered at least one workflow, low-to-high. */
+	layers: readonly ConfigLayer[];
+	/** Aggregated load + validation issues. Errors block the runner; warnings are advisory. */
+	issues: readonly Issue[];
+}
+
+// ===========================================================================
+// Public lookup helpers
+// ===========================================================================
+
+/**
+ * Lookup a workflow by name in a merged `LoadedWorkflows`. Anticipates
+ * the "rerun by name" / `listRuns` past-runs API that will share the
+ * lookup; consolidated here so future callers don't reach back into
+ * `loaded.workflows.find(...)` ad-hoc.
+ */
+export function findWorkflow(loaded: LoadedWorkflows, name: string): Workflow | undefined {
+	return loaded.workflows.find((w) => w.name === name);
+}
+
+// ===========================================================================
+// Orchestrator
+// ===========================================================================
+
+/**
+ * Load every active layer, merge by workflow name, validate, and return the
+ * resolved set. Never throws — load + validation errors flow through `issues`.
+ */
+export async function loadWorkflows(cwd: string): Promise<LoadedWorkflows> {
+	const acc: LoadAccumulator = {
+		issues: [],
+		workflowMap: new Map(),
+		sources: new Map(),
+		sourcePaths: new Map(),
+	};
+	const layers: ConfigLayer[] = getBuiltIns().length > 0 ? ["built-in"] : [];
+
+	for (const w of getBuiltIns()) {
+		acc.workflowMap.set(w.name, w);
+		acc.sources.set(w.name, "built-in");
+		acc.sourcePaths.set(w.name, undefined);
+	}
+
+	const userOutcome = await loadLayer(userOverlayPaths(), "user", acc);
+	if (userOutcome.contributed) layers.push("user");
+
+	const projectOutcome = await loadLayer(projectOverlayPaths(cwd), "project", acc);
+	if (projectOutcome.contributed) layers.push("project");
+
+	// Validate every merged workflow once. Validation runs even on built-in so
+	// that a future built-in regression surfaces in the same channel as user
+	// errors. Each issue is attributed to the exact file the surviving workflow
+	// came from (pack or config) so `/wf` previews can render
+	// `[<layer> config (<path>)] workflow "X": ...` errors.
+	for (const w of acc.workflowMap.values()) {
+		const layer = acc.sources.get(w.name) ?? "built-in";
+		const path = acc.sourcePaths.get(w.name);
+		for (const v of validateWorkflow(w)) acc.issues.push({ ...v, kind: "validation", layer, path });
+	}
+
+	const defaultName = resolveDefault(projectOutcome.configDefault, userOutcome.configDefault, acc);
+
+	return {
+		workflows: [...acc.workflowMap.values()],
+		default: defaultName,
+		workflowSources: acc.sources,
+		layers,
+		issues: acc.issues,
+	};
+}