refactor: organize workflow/src into 6 module folders

Move 34 flat modules into cas/, registry/, bundle/, extract/, engine/, util/.
Move gc.ts to engine/ (was in cas/) to avoid cas→engine reverse dependency.
Dependency direction: util ← cas ← extract ← engine, util ← registry ← bundle.
No logic changes — only file locations and import paths.

Refs #102

packages/cli-workflow/__tests__/bundle-fixture.ts

@@ -1,4 +1,4 @@
-import type { ParsedAddArgv } from "../src/commands/workflow/add.js";
+import type { ParsedAddArgv } from "../src/commands/workflow/add-argv.js";
 
 export function addCliArgs(name: string, filePath: string): ParsedAddArgv {
   return { name, filePath, typesPath: null };

packages/cli-workflow/__tests__/commands.test.ts

@@ -402,7 +402,7 @@ export const run = async function* (input, options) {
   });
 
   test("cas put/get/list/rm use global cas dir (thread id not required for storage)", async () => {
-    const put = await cmdCasPut(storageRoot, "nonexistent-thread-id", "phase doc");
+    const put = await cmdCasPut(storageRoot, "phase doc");
     expect(put.ok).toBe(true);
     if (!put.ok) {
       return;
@@ -411,24 +411,24 @@ export const run = async function* (input, options) {
     const blobPath = join(getGlobalCasDir(storageRoot), `${hash}.txt`);
     expect(await readFile(blobPath, "utf8")).toBe("phase doc");
 
-    const got = await cmdCasGet(storageRoot, "other-thread", hash);
+    const got = await cmdCasGet(storageRoot, hash);
     expect(got.ok).toBe(true);
     if (!got.ok) {
       return;
     }
     expect(got.value).toBe("phase doc");
 
-    const listed = await cmdCasList(storageRoot, "another-thread");
+    const listed = await cmdCasList(storageRoot);
     expect(listed.ok).toBe(true);
     if (!listed.ok) {
       return;
     }
     expect(listed.value).toContain(hash);
 
-    const removed = await cmdCasRm(storageRoot, "rm-thread", hash);
+    const removed = await cmdCasRm(storageRoot, hash);
     expect(removed.ok).toBe(true);
 
-    const missing = await cmdCasGet(storageRoot, "after-rm", hash);
+    const missing = await cmdCasGet(storageRoot, hash);
     expect(missing.ok).toBe(false);
   });
 

packages/cli-workflow/__tests__/thread-cli.test.ts

@@ -232,7 +232,7 @@ describe("cli thread commands", () => {
     const runningPath = join(dirname(dataPath), `${threadId}.running`);
     await waitUntilRunningFileAbsent(runningPath, 120);
 
-    const put = await cmdCasPut(storageRoot, threadId, "keep-after-thread-rm");
+    const put = await cmdCasPut(storageRoot, "keep-after-thread-rm");
     expect(put.ok).toBe(true);
     if (!put.ok) {
       return;

packages/cli-workflow/src/bundle-store.ts

@@ -1,16 +1,9 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { err, ok, type Result } from "@uncaged/workflow";
 
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
+import { pathExists } from "./fs-utils.js";
 
 export type BundleFileSource = { kind: "text"; text: string } | { kind: "path"; path: string };
 

packages/cli-workflow/src/cli-color.ts

@@ -0,0 +1,17 @@
+export function shouldUseColor(): boolean {
+  return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}
+
+export function highlightLiveRole(name: string): string {
+  if (!shouldUseColor()) {
+    return name;
+  }
+  return `\x1b[1m\x1b[36m${name}\x1b[0m`;
+}
+
+export function dimGreyLine(line: string): string {
+  if (!shouldUseColor()) {
+    return line;
+  }
+  return `\x1b[2m\x1b[90m${line}\x1b[0m`;
+}

packages/cli-workflow/src/cli-dispatch.ts

@@ -86,6 +86,7 @@ async function dispatchSkill(_storageRoot: string, argv: string[]): Promise<numb
 }
 
 async function dispatchHelp(_storageRoot: string, argv: string[]): Promise<number> {
+  printCliWarn('⚠ "help" is deprecated, use "skill" instead');
   const skillIdx = argv.indexOf("--skill");
   if (skillIdx !== -1) {
     return showSkillDocOrIndex(argv[skillIdx + 1]);

packages/cli-workflow/src/commands/cas/dispatch.ts

@@ -36,7 +36,7 @@ export async function dispatchCasGet(storageRoot: string, rest: string[]): Promi
     printCliError(`${usageText()}\n\nerror: cas get requires <thread-id> <hash>`);
     return 1;
   }
-  const result = await cmdCasGet(storageRoot, threadId, hash);
+  const result = await cmdCasGet(storageRoot, hash);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -52,7 +52,7 @@ export async function dispatchCasPut(storageRoot: string, rest: string[]): Promi
     printCliError(`${usageText()}\n\nerror: cas put requires <thread-id> <content>`);
     return 1;
   }
-  const result = await cmdCasPut(storageRoot, threadId, content);
+  const result = await cmdCasPut(storageRoot, content);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -67,7 +67,7 @@ export async function dispatchCasList(storageRoot: string, rest: string[]): Prom
     printCliError(`${usageText()}\n\nerror: cas list requires <thread-id>`);
     return 1;
   }
-  const result = await cmdCasList(storageRoot, threadId);
+  const result = await cmdCasList(storageRoot);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -85,7 +85,7 @@ export async function dispatchCasRm(storageRoot: string, rest: string[]): Promis
     printCliError(`${usageText()}\n\nerror: cas rm requires <thread-id> <hash>`);
     return 1;
   }
-  const result = await cmdCasRm(storageRoot, threadId, hash);
+  const result = await cmdCasRm(storageRoot, hash);
   if (!result.ok) {
     printCliError(result.error);
     return 1;

packages/cli-workflow/src/commands/cas/get.ts

@@ -2,7 +2,6 @@ import { createCasStore, err, getGlobalCasDir, ok, type Result } from "@uncaged/
 
 export async function cmdCasGet(
   storageRoot: string,
-  _threadId: string,
   hash: string,
 ): Promise<Result<string, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

packages/cli-workflow/src/commands/cas/list.ts

@@ -1,9 +1,6 @@
 import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
 
-export async function cmdCasList(
-  storageRoot: string,
-  _threadId: string,
-): Promise<Result<string[], string>> {
+export async function cmdCasList(storageRoot: string): Promise<Result<string[], string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));
   const hashes = await cas.list();
   return ok(hashes);

packages/cli-workflow/src/commands/cas/put.ts

@@ -2,7 +2,6 @@ import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workf
 
 export async function cmdCasPut(
   storageRoot: string,
-  _threadId: string,
   content: string,
 ): Promise<Result<string, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

packages/cli-workflow/src/commands/cas/rm.ts

@@ -1,10 +1,6 @@
 import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
 
-export async function cmdCasRm(
-  storageRoot: string,
-  _threadId: string,
-  hash: string,
-): Promise<Result<void, string>> {
+export async function cmdCasRm(storageRoot: string, hash: string): Promise<Result<void, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));
   await cas.delete(hash);
   return ok(undefined);

packages/cli-workflow/src/commands/init/template.ts

@@ -5,6 +5,14 @@ import { err, ok, type Result } from "@uncaged/workflow";
 
 import { pathExists } from "../../fs-utils.js";
 
+import {
+  templateIndexTs,
+  templateModeratorTs,
+  templatePackageJson,
+  templateRolesTs,
+  templateTsconfigJson,
+} from "./templates.js";
+
 export type CmdInitTemplateSuccess = {
   templatePath: string;
 };
@@ -67,108 +75,6 @@ async function findWorkflowWorkspaceRoot(startDir: string): Promise<Result<strin
   }
 }
 
-function templatePackageJson(templateName: string): string {
-  return `${JSON.stringify(
-    {
-      name: `template-${templateName}`,
-      version: "0.0.0",
-      private: true,
-      type: "module",
-      dependencies: {
-        "@uncaged/workflow": "^0.1.0",
-        zod: "^4.0.0",
-      },
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function templateTsconfigJson(): string {
-  return `${JSON.stringify(
-    {
-      extends: "../../tsconfig.json",
-      compilerOptions: {
-        rootDir: "src",
-        outDir: "dist",
-      },
-      include: ["src/**/*.ts"],
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function templateRolesTs(): string {
-  return `import type { RoleDefinition } from "@uncaged/workflow";
-import * as z from "zod/v4";
-
-export const HELLO_TEMPLATE_DESCRIPTION =
-  "Minimal starter template: one greeter role, then END.";
-
-export type HelloTemplateMeta = {
-  greeter: {
-    message: string;
-  };
-};
-
-const greeterMetaSchema = z.object({
-  message: z.string(),
-});
-
-export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
-  description: "Says hello — replace with your first role.",
-  systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
-  extractPrompt: "Extract the assistant's greeting as message.",
-  schema: greeterMetaSchema,
-  extractRefs: null,
-};
-`;
-}
-
-function templateModeratorTs(): string {
-  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
-
-import type { HelloTemplateMeta } from "./roles.js";
-
-export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
-  ctx: ModeratorContext<HelloTemplateMeta>,
-) => {
-  if (ctx.steps.length === 0) {
-    return "greeter";
-  }
-  return END;
-};
-`;
-}
-
-function templateIndexTs(): string {
-  return `import type { WorkflowDefinition } from "@uncaged/workflow";
-
-import { helloTemplateModerator } from "./moderator.js";
-import {
-  HELLO_TEMPLATE_DESCRIPTION,
-  type HelloTemplateMeta,
-  greeterRole,
-} from "./roles.js";
-
-export {
-  HELLO_TEMPLATE_DESCRIPTION,
-  type HelloTemplateMeta,
-  greeterRole,
-} from "./roles.js";
-export { helloTemplateModerator } from "./moderator.js";
-
-export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
-  description: HELLO_TEMPLATE_DESCRIPTION,
-  roles: {
-    greeter: greeterRole,
-  },
-  moderator: helloTemplateModerator,
-};
-`;
-}
-
 export async function cmdInitTemplate(
   startDir: string,
   templateName: string,

packages/cli-workflow/src/commands/init/templates.ts

@@ -0,0 +1,101 @@
+export function templatePackageJson(templateName: string): string {
+  return `${JSON.stringify(
+    {
+      name: `template-${templateName}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export function templateTsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      extends: "../../tsconfig.json",
+      compilerOptions: {
+        rootDir: "src",
+        outDir: "dist",
+      },
+      include: ["src/**/*.ts"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export function templateRolesTs(): string {
+  return `import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const HELLO_TEMPLATE_DESCRIPTION =
+  "Minimal starter template: one greeter role, then END.";
+
+export type HelloTemplateMeta = {
+  greeter: {
+    message: string;
+  };
+};
+
+const greeterMetaSchema = z.object({
+  message: z.string(),
+});
+
+export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
+  description: "Says hello — replace with your first role.",
+  systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
+  extractPrompt: "Extract the assistant's greeting as message.",
+  schema: greeterMetaSchema,
+  extractRefs: null,
+};
+`;
+}
+
+export function templateModeratorTs(): string {
+  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
+
+import type { HelloTemplateMeta } from "./roles.js";
+
+export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
+  ctx: ModeratorContext<HelloTemplateMeta>,
+) => {
+  if (ctx.steps.length === 0) {
+    return "greeter";
+  }
+  return END;
+};
+`;
+}
+
+export function templateIndexTs(): string {
+  return `import type { WorkflowDefinition } from "@uncaged/workflow";
+
+import { helloTemplateModerator } from "./moderator.js";
+import {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+
+export {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+export { helloTemplateModerator } from "./moderator.js";
+
+export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
+  description: HELLO_TEMPLATE_DESCRIPTION,
+  roles: {
+    greeter: greeterRole,
+  },
+  moderator: helloTemplateModerator,
+};
+`;
+}

packages/cli-workflow/src/commands/thread/dispatch.ts

@@ -5,7 +5,8 @@ import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
 import { parseLiveArgv } from "../../live-argv.js";
 import { parseRunArgv } from "../../run-argv.js";
 import { cmdKill, cmdPause, cmdResume } from "./control.js";
-import { cmdFork, parseForkArgv } from "./fork.js";
+import { cmdFork } from "./fork.js";
+import { parseForkArgv } from "./fork-argv.js";
 import { cmdThreads } from "./list.js";
 import { cmdLive } from "./live.js";
 import { cmdPs } from "./ps.js";

packages/cli-workflow/src/commands/thread/fork-argv.ts

@@ -0,0 +1,28 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+export function parseForkArgv(
+  argv: string[],
+): Result<{ threadId: string; fromRole: string | null }, string> {
+  if (argv.length === 0) {
+    return err("fork requires <thread-id>");
+  }
+  const threadId = argv[0];
+  if (threadId === undefined || threadId === "") {
+    return err("fork requires <thread-id>");
+  }
+  let fromRole: string | null = null;
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--from-role") {
+      const r = argv[i + 1];
+      if (r === undefined || r === "") {
+        return err("--from-role requires a role name");
+      }
+      fromRole = r;
+      i++;
+      continue;
+    }
+    return err(`unexpected argument: ${a}`);
+  }
+  return ok({ threadId, fromRole });
+}

packages/cli-workflow/src/commands/thread/fork.ts

@@ -6,33 +6,6 @@ import { pathExists, readTextFileIfExists } from "../../fs-utils.js";
 import { resolveThreadDataPath } from "../../thread-scan.js";
 import { ensureWorkerForHash, sendWorkerTcpCommand } from "../../worker-spawn.js";
 
-export function parseForkArgv(
-  argv: string[],
-): Result<{ threadId: string; fromRole: string | null }, string> {
-  if (argv.length === 0) {
-    return err("fork requires <thread-id>");
-  }
-  const threadId = argv[0];
-  if (threadId === undefined || threadId === "") {
-    return err("fork requires <thread-id>");
-  }
-  let fromRole: string | null = null;
-  for (let i = 1; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--from-role") {
-      const r = argv[i + 1];
-      if (r === undefined || r === "") {
-        return err("--from-role requires a role name");
-      }
-      fromRole = r;
-      i++;
-      continue;
-    }
-    return err(`unexpected argument: ${a}`);
-  }
-  return ok({ threadId, fromRole });
-}
-
 export async function cmdFork(
   storageRoot: string,
   threadId: string,

packages/cli-workflow/src/commands/thread/index.ts

@@ -1,5 +1,6 @@
 export { cmdKill, cmdPause, cmdResume } from "./control.js";
-export { cmdFork, parseForkArgv } from "./fork.js";
+export { cmdFork } from "./fork.js";
+export { parseForkArgv } from "./fork-argv.js";
 export { cmdThreads } from "./list.js";
 export type { LiveRoleRow } from "./live.js";
 export {

packages/cli-workflow/src/commands/thread/live.ts

@@ -12,6 +12,7 @@ import {
   type WorkflowCompletion,
 } from "@uncaged/workflow";
 
+import { dimGreyLine, highlightLiveRole } from "../../cli-color.js";
 import { printCliError, printCliLine } from "../../cli-output.js";
 import { pathExists } from "../../fs-utils.js";
 import type { ParsedLiveArgv } from "../../live-argv.js";
@@ -34,24 +35,6 @@ export function formatLiveTimeLabel(timestampMs: number): string {
   return `${hh}:${mm}:${ss}`;
 }
 
-function shouldUseColor(): boolean {
-  return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-}
-
-function highlightLiveRole(name: string): string {
-  if (!shouldUseColor()) {
-    return name;
-  }
-  return `\x1b[1m\x1b[36m${name}\x1b[0m`;
-}
-
-function dimGreyLine(line: string): string {
-  if (!shouldUseColor()) {
-    return line;
-  }
-  return `\x1b[2m\x1b[90m${line}\x1b[0m`;
-}
-
 export function formatLiveDebugLine(timestampMs: number, tag: string, message: string): string {
   const label = `[${formatLiveTimeLabel(timestampMs)}] [${tag}] ${message.replace(/\n/g, " ")}`;
   return dimGreyLine(label);

packages/cli-workflow/src/commands/workflow/add-argv.ts

@@ -0,0 +1,77 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+export type ParsedAddArgv = {
+  name: string;
+  filePath: string;
+  /** Override path to `.d.ts` when adding a bundle. */
+  typesPath: string | null;
+};
+
+type ParsedLongFlag = { advance: 2; kind: "types"; value: string };
+
+function tryParseAddLongFlag(argv: string[], index: number): Result<ParsedLongFlag | null, string> {
+  const tok = argv[index];
+  if (tok !== "--types") {
+    return ok(null);
+  }
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    return err("missing value for --types");
+  }
+  return ok({ advance: 2, kind: "types", value });
+}
+
+type PositionalSlots = {
+  name: string | undefined;
+  filePath: string | undefined;
+};
+
+function assignPositional(tok: string, slots: PositionalSlots): Result<void, string> {
+  if (slots.name === undefined) {
+    slots.name = tok;
+    return ok(undefined);
+  }
+  if (slots.filePath === undefined) {
+    slots.filePath = tok;
+    return ok(undefined);
+  }
+  return err("too many arguments");
+}
+
+export function parseAddArgv(argv: string[]): Result<ParsedAddArgv, string> {
+  const slots: PositionalSlots = { name: undefined, filePath: undefined };
+  let typesPath: string | null = null;
+
+  let i = 0;
+  while (i < argv.length) {
+    const flag = tryParseAddLongFlag(argv, i);
+    if (!flag.ok) {
+      return flag;
+    }
+    if (flag.value !== null) {
+      typesPath = flag.value.value;
+      i += flag.value.advance;
+      continue;
+    }
+
+    const tok = argv[i];
+    if (tok?.startsWith("--")) {
+      return err(`unknown add flag: ${tok}`);
+    }
+    if (tok === undefined) {
+      break;
+    }
+    const placed = assignPositional(tok, slots);
+    if (!placed.ok) {
+      return placed;
+    }
+    i += 1;
+  }
+
+  const { name, filePath } = slots;
+  if (name === undefined || name === "" || filePath === undefined || filePath === "") {
+    return err("add requires <name> <file>");
+  }
+
+  return ok({ name, filePath, typesPath });
+}

packages/cli-workflow/src/commands/workflow/add.ts

@@ -17,12 +17,7 @@ import {
 import { storeWorkflowBundleArtifacts } from "../../bundle-store.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";
 
-export type ParsedAddArgv = {
-  name: string;
-  filePath: string;
-  /** Override path to `.d.ts` when adding a bundle. */
-  typesPath: string | null;
-};
+import type { ParsedAddArgv } from "./add-argv.js";
 
 export type CmdAddSuccess = {
   hash: string;
@@ -37,75 +32,6 @@ function defaultTypesPath(bundlePath: string): string {
   return bundlePath.replace(/\.esm\.js$/i, ".d.ts");
 }
 
-type ParsedLongFlag = { advance: 2; kind: "types"; value: string };
-
-function tryParseAddLongFlag(argv: string[], index: number): Result<ParsedLongFlag | null, string> {
-  const tok = argv[index];
-  if (tok !== "--types") {
-    return ok(null);
-  }
-  const value = argv[index + 1];
-  if (value === undefined || value.startsWith("--")) {
-    return err("missing value for --types");
-  }
-  return ok({ advance: 2, kind: "types", value });
-}
-
-type PositionalSlots = {
-  name: string | undefined;
-  filePath: string | undefined;
-};
-
-function assignPositional(tok: string, slots: PositionalSlots): Result<void, string> {
-  if (slots.name === undefined) {
-    slots.name = tok;
-    return ok(undefined);
-  }
-  if (slots.filePath === undefined) {
-    slots.filePath = tok;
-    return ok(undefined);
-  }
-  return err("too many arguments");
-}
-
-export function parseAddArgv(argv: string[]): Result<ParsedAddArgv, string> {
-  const slots: PositionalSlots = { name: undefined, filePath: undefined };
-  let typesPath: string | null = null;
-
-  let i = 0;
-  while (i < argv.length) {
-    const flag = tryParseAddLongFlag(argv, i);
-    if (!flag.ok) {
-      return flag;
-    }
-    if (flag.value !== null) {
-      typesPath = flag.value.value;
-      i += flag.value.advance;
-      continue;
-    }
-
-    const tok = argv[i];
-    if (tok?.startsWith("--")) {
-      return err(`unknown add flag: ${tok}`);
-    }
-    if (tok === undefined) {
-      break;
-    }
-    const placed = assignPositional(tok, slots);
-    if (!placed.ok) {
-      return placed;
-    }
-    i += 1;
-  }
-
-  const { name, filePath } = slots;
-  if (name === undefined || name === "" || filePath === undefined || filePath === "") {
-    return err("add requires <name> <file>");
-  }
-
-  return ok({ name, filePath, typesPath });
-}
-
 async function registerHash(
   storageRoot: string,
   name: string,

packages/cli-workflow/src/commands/workflow/dispatch.ts

@@ -2,7 +2,8 @@ import type { CommandEntry, DispatchGroupFn } from "../../cli-command-types.js";
 import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
 import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
 import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
-import { cmdAdd, formatAddSuccess, parseAddArgv } from "./add.js";
+import { cmdAdd, formatAddSuccess } from "./add.js";
+import { parseAddArgv } from "./add-argv.js";
 import { cmdHistory } from "./history.js";
 import { cmdList, formatListLines } from "./list.js";
 import { cmdRemove } from "./rm.js";

packages/cli-workflow/src/commands/workflow/index.ts

@@ -1,5 +1,7 @@
-export type { CmdAddSuccess, ParsedAddArgv } from "./add.js";
-export { cmdAdd, formatAddSuccess, parseAddArgv } from "./add.js";
+export type { CmdAddSuccess } from "./add.js";
+export { cmdAdd, formatAddSuccess } from "./add.js";
+export type { ParsedAddArgv } from "./add-argv.js";
+export { parseAddArgv } from "./add-argv.js";
 export { cmdHistory } from "./history.js";
 export { cmdList, formatListLines } from "./list.js";
 export { cmdRemove } from "./rm.js";

packages/cli-workflow/src/thread-scan.ts

@@ -3,6 +3,23 @@ import { join } from "node:path";
 
 import { pathExists, readTextFileIfExists } from "./fs-utils.js";
 
+function parseFirstJsonLineObject(text: string): Record<string, unknown> | null {
+  const firstLine = text.split("\n")[0];
+  if (firstLine === undefined || firstLine.trim() === "") {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(firstLine) as unknown;
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return null;
+  }
+  return parsed as Record<string, unknown>;
+}
+
 export type RunningThreadRow = {
   threadId: string;
   hash: string;
@@ -20,20 +37,11 @@ async function readThreadStartTimestampMs(dataPath: string): Promise<number | nu
   if (text === null) {
     return null;
   }
-  const firstLine = text.split("\n")[0];
-  if (firstLine === undefined || firstLine.trim() === "") {
+  const parsed = parseFirstJsonLineObject(text);
+  if (parsed === null) {
     return null;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(firstLine) as unknown;
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return null;
-  }
-  const ts = (parsed as Record<string, unknown>).timestamp;
+  const ts = parsed.timestamp;
   return typeof ts === "number" && Number.isFinite(ts) ? ts : null;
 }
 
@@ -42,20 +50,11 @@ async function readWorkflowNameFromDataJsonl(dataPath: string): Promise<string |
   if (text === null) {
     return null;
   }
-  const firstLine = text.split("\n")[0];
-  if (firstLine === undefined || firstLine.trim() === "") {
+  const parsed = parseFirstJsonLineObject(text);
+  if (parsed === null) {
     return null;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(firstLine) as unknown;
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return null;
-  }
-  const name = (parsed as Record<string, unknown>).name;
+  const name = parsed.name;
   return typeof name === "string" ? name : null;
 }
 

packages/workflow/__tests__/base32.test.ts

@@ -5,7 +5,7 @@ import {
   decodeCrockfordToUint64,
   encodeCrockfordBase32Bits,
   encodeUint64AsCrockford,
-} from "../src/base32.js";
+} from "../src/util/base32.js";
 
 describe("Crockford Base32", () => {
   test("roundtrip 64-bit hash encoding", () => {

packages/workflow/__tests__/build-descriptor.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import * as z from "zod/v4";
 
-import { buildDescriptor } from "../src/build-descriptor.js";
+import { buildDescriptor } from "../src/bundle/build-descriptor.js";
+import { validateWorkflowDescriptor } from "../src/bundle/workflow-descriptor.js";
 import { END } from "../src/types.js";
-import { validateWorkflowDescriptor } from "../src/workflow-descriptor.js";
 
 describe("buildDescriptor", () => {
   test("produces a descriptor that validates and includes JSON schemas per role", () => {

packages/workflow/__tests__/bundle-validator.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { validateWorkflowBundle } from "../src/bundle-validator.js";
+import { validateWorkflowBundle } from "../src/bundle/bundle-validator.js";
 
 const minimalDescriptor = `export const descriptor = { description: "x", roles: {} };
 `;

packages/workflow/__tests__/cas.test.ts

@@ -3,8 +3,8 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore, createThreadCas } from "../src/cas.js";
-import { hashString } from "../src/hash.js";
+import { createCasStore, createThreadCas } from "../src/cas/cas.js";
+import { hashString } from "../src/cas/hash.js";
 
 describe("cas module exports", () => {
   test("createThreadCas is a deprecated alias of createCasStore", () => {

packages/workflow/__tests__/engine.test.ts

@@ -4,18 +4,18 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { createLogger } from "../src/logger.js";
+import { createCasStore } from "../src/cas/cas.js";
 import {
   createContentMerkleNode,
   getContentMerklePayload,
   parseMerkleNode,
   serializeMerkleNode,
-} from "../src/merkle.js";
+} from "../src/cas/merkle.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
+import { createExtract } from "../src/extract/extract-fn.js";
 import { END, type LlmProvider } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 
 const plannerMetaSchema = z.object({
   plan: z.string(),

packages/workflow/__tests__/fork-thread.test.ts

@@ -4,7 +4,7 @@ import {
   buildForkPlan,
   parseThreadDataJsonl,
   selectForkHistoricalSteps,
-} from "../src/fork-thread.js";
+} from "../src/engine/fork-thread.js";
 
 const sampleDataJsonl = `{"name":"demo","hash":"C9NMV6V2TQT81","threadId":"01AAA1111111111111111111","parameters":{"prompt":"hi","options":{"maxRounds":5}},"timestamp":100}
 {"role":"planner","contentHash":"HP0000000000000000000001","meta":{},"refs":[],"timestamp":101}

packages/workflow/__tests__/hash.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
-
-import { decodeCrockfordToUint64 } from "../src/base32.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { decodeCrockfordToUint64 } from "../src/util/base32.js";
 
 describe("hashWorkflowBundleBytes", () => {
   test("matches XXH64 reference for empty input", () => {

packages/workflow/__tests__/logger.test.ts

@@ -3,7 +3,7 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createLogger } from "../src/logger.js";
+import { createLogger } from "../src/util/logger.js";
 
 describe("createLogger", () => {
   test("writes JSONL records to a file sink", async () => {

packages/workflow/__tests__/merkle.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
-import { createContentMerkleNode, parseMerkleNode, serializeMerkleNode } from "../src/merkle.js";
+import {
+  createContentMerkleNode,
+  parseMerkleNode,
+  serializeMerkleNode,
+} from "../src/cas/merkle.js";
 
 describe("merkle", () => {
   test("content node roundtrips through YAML", () => {

packages/workflow/__tests__/react-extract.test.ts

@@ -4,9 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
-import { reactExtract } from "../src/react-extract.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
+import { reactExtract } from "../src/extract/react-extract.js";
 import type { LlmProvider } from "../src/types.js";
 
 const metaSchema = z.object({ seen: z.string() });

packages/workflow/__tests__/refs-tracking.test.ts

@@ -4,13 +4,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { buildForkPlan, parseThreadDataJsonl } from "../src/fork-thread.js";
-import { createLogger } from "../src/logger.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
+import { buildForkPlan, parseThreadDataJsonl } from "../src/engine/fork-thread.js";
+import { createExtract } from "../src/extract/extract-fn.js";
 import { END } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 
 const phaseSchema = z.object({
   hash: z.string(),

packages/workflow/__tests__/registry.test.ts

@@ -10,7 +10,7 @@ import {
   rollbackWorkflowToHistoryHash,
   unregisterWorkflow,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 
 describe("workflow registry", () => {
   test("roundtrips through workflow.yaml", async () => {

packages/workflow/__tests__/result.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { err, ok } from "../src/result.js";
+import { err, ok } from "../src/util/result.js";
 
 describe("result helpers", () => {
   test("ok wraps value", () => {

packages/workflow/__tests__/storage-root.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { join } from "node:path";
 
-import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "../src/storage-root.js";
+import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "../src/util/storage-root.js";
 
 describe("getGlobalCasDir", () => {
   test("joins cas segment under explicit storage root", () => {

packages/workflow/__tests__/thread-pause-gate.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { createThreadPauseGate } from "../src/thread-pause-gate.js";
+import { createThreadPauseGate } from "../src/engine/thread-pause-gate.js";
 
 describe("createThreadPauseGate", () => {
   test("pause blocks awaitAfterYield until resume", async () => {

packages/workflow/__tests__/ulid.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
-import { decodeCrockfordBase32Bits } from "../src/base32.js";
-import { generateUlid } from "../src/ulid.js";
+import { decodeCrockfordBase32Bits } from "../src/util/base32.js";
+import { generateUlid } from "../src/util/ulid.js";
 
 describe("generateUlid", () => {
   test("length and decodable Crockford payload", () => {

packages/workflow/__tests__/worker.test.ts

@@ -5,9 +5,9 @@ import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore } from "../src/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
-import { getWorkerHostScriptPath } from "../src/worker-entry-path.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
+import { getWorkerHostScriptPath } from "../src/engine/worker-entry-path.js";
 
 const bundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
 

packages/workflow/__tests__/workflow-as-agent-integration.test.ts

@@ -4,19 +4,19 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
-import { createLogger } from "../src/logger.js";
-import { getContentMerklePayload, parseMerkleNode } from "../src/merkle.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { getContentMerklePayload, parseMerkleNode } from "../src/cas/merkle.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
+import { createExtract } from "../src/extract/extract-fn.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 import { END } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 
 const callerMetaSchema = z.object({ done: z.literal(true) });

packages/workflow/__tests__/workflow-as-agent.test.ts

@@ -3,14 +3,14 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore } from "../src/cas.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
-import { parseMerkleNode } from "../src/merkle.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { parseMerkleNode } from "../src/cas/merkle.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 import { type AgentContext, START } from "../src/types.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 

packages/workflow/__tests__/workflow-descriptor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { validateWorkflowDescriptor } from "../src/workflow-descriptor.js";
+import { validateWorkflowDescriptor } from "../src/bundle/workflow-descriptor.js";
 
 describe("validateWorkflowDescriptor", () => {
   // 1. Valid minimal descriptor

packages/workflow/src/bundle/build-descriptor.ts

@@ -1,6 +1,6 @@
 import * as z from "zod/v4";
 
-import type { RoleMeta, WorkflowDefinition } from "./types.js";
+import type { RoleMeta, WorkflowDefinition } from "../types.js";
 import type { WorkflowDescriptor, WorkflowRoleSchema } from "./workflow-descriptor.js";
 
 function stripJsonSchemaMeta(json: Record<string, unknown>): WorkflowRoleSchema {

packages/workflow/src/bundle/bundle-validator.ts

@@ -24,7 +24,7 @@ function narrowNode<T extends Node>(node: Node): T {
 
 import * as acorn from "acorn";
 
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/result.js";
 
 export type WorkflowBundleValidationInput = {
   /** Absolute or relative path (used for `.esm.js` suffix checks). */

packages/workflow/src/bundle/ensure-uncaged-workflow-symlink.ts

@@ -2,9 +2,9 @@ import { mkdir, readlink, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** This module lives in `@uncaged/workflow/src`; parent dir is the package root. */
+/** This module lives in `@uncaged/workflow/src/bundle`; grandparent dir is the package root. */
 function installedWorkflowPackageDir(): string {
-  return fileURLToPath(new URL("..", import.meta.url));
+  return fileURLToPath(new URL("../..", import.meta.url));
 }
 
 /**

packages/workflow/src/bundle/extract-bundle-exports.ts

@@ -1,7 +1,7 @@
+import type { WorkflowFn } from "../types.js";
+import { err, ok, type Result } from "../util/result.js";
 import { importWorkflowBundleModule } from "./bundle-import-env.js";
 import { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";
-import { err, ok, type Result } from "./result.js";
-import type { WorkflowFn } from "./types.js";
 import type { WorkflowDescriptor } from "./workflow-descriptor.js";
 import { validateWorkflowDescriptor } from "./workflow-descriptor.js";
 

packages/workflow/src/bundle/workflow-descriptor.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/result.js";
 
 /** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
 export type WorkflowRoleSchema = Record<string, unknown>;

packages/workflow/src/cas/hash.ts

@@ -2,7 +2,7 @@ import { Buffer } from "node:buffer";
 
 import XXH from "xxhashjs";
 
-import { encodeUint64AsCrockford } from "./base32.js";
+import { encodeUint64AsCrockford } from "../util/base32.js";
 
 function digestToUint64(digest: { toString(radix?: number): string }): bigint {
   const hex = digest.toString(16).padStart(16, "0");

packages/workflow/src/engine/create-workflow.ts

@@ -1,8 +1,7 @@
-import type { CasStore } from "./cas.js";
-import { buildExtractUserContent, type ExtractFn } from "./extract-fn.js";
-import { putContentMerkleNode } from "./merkle.js";
-import { reactExtract } from "./react-extract.js";
-import { mergeRefsWithContentHash } from "./refs-field.js";
+import type { CasStore } from "../cas/cas.js";
+import { putContentMerkleNode } from "../cas/merkle.js";
+import { buildExtractUserContent, type ExtractFn } from "../extract/extract-fn.js";
+import { reactExtract } from "../extract/react-extract.js";
 import {
   type AgentBinding,
   type AgentContext,
@@ -20,7 +19,8 @@ import {
   type WorkflowDefinition,
   type WorkflowFn,
   type WorkflowFnOptions,
-} from "./types.js";
+} from "../types.js";
+import { mergeRefsWithContentHash } from "../util/refs-field.js";
 
 function isRoleNext<M extends RoleMeta>(
   next: (keyof M & string) | typeof END,

packages/workflow/src/engine/engine.ts

@@ -1,17 +1,17 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 
-import type { CasStore } from "./cas.js";
-import type { LogFn } from "./logger.js";
-import { getContentMerklePayload, putStepMerkleNode, putThreadMerkleNode } from "./merkle.js";
-import { normalizeRefsField } from "./refs-field.js";
+import type { CasStore } from "../cas/cas.js";
+import { getContentMerklePayload, putStepMerkleNode, putThreadMerkleNode } from "../cas/merkle.js";
 import type {
   ThreadInput,
   WorkflowCompletion,
   WorkflowFn,
   WorkflowFnOptions,
   WorkflowResult,
-} from "./types.js";
+} from "../types.js";
+import type { LogFn } from "../util/logger.js";
+import { normalizeRefsField } from "../util/refs-field.js";
 
 export type ExecuteThreadIo = {
   threadId: string;

packages/workflow/src/engine/fork-thread.ts

@@ -1,6 +1,6 @@
-import { normalizeRefsField } from "./refs-field.js";
-import { err, ok, type Result } from "./result.js";
-import type { RoleOutput, WorkflowCompletion } from "./types.js";
+import type { RoleOutput, WorkflowCompletion } from "../types.js";
+import { normalizeRefsField } from "../util/refs-field.js";
+import { err, ok, type Result } from "../util/result.js";
 
 /** Role steps replayed from `.data.jsonl`, including persisted timestamps. */
 export type ForkHistoricalStep = RoleOutput & { timestamp: number };

packages/workflow/src/engine/gc.ts

@@ -1,10 +1,9 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
-
-import { type CasStore, createCasStore } from "./cas.js";
+import { type CasStore, createCasStore } from "../cas/cas.js";
+import { err, ok, type Result } from "../util/result.js";
+import { getGlobalCasDir } from "../util/storage-root.js";
 import { parseThreadDataJsonl } from "./fork-thread.js";
-import { err, ok, type Result } from "./result.js";
-import { getGlobalCasDir } from "./storage-root.js";
 
 export type GcResult = {
   scannedThreads: number;

packages/workflow/src/engine/thread-pause-gate.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/result.js";
 
 export type ThreadPauseGate = {
   awaitAfterYield: () => Promise<void>;

packages/workflow/src/engine/worker.ts

@@ -1,17 +1,17 @@
 import { appendFile, mkdir, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
-import { importWorkflowBundleModule } from "./bundle-import-env.js";
-import { createCasStore } from "./cas.js";
+import { importWorkflowBundleModule } from "../bundle/bundle-import-env.js";
+import { ensureUncagedWorkflowSymlink } from "../bundle/ensure-uncaged-workflow-symlink.js";
+import { createCasStore } from "../cas/cas.js";
+import type { RoleOutput, WorkflowFn, WorkflowResult } from "../types.js";
+import { createLogger } from "../util/logger.js";
+import { normalizeRefsField } from "../util/refs-field.js";
+import { err, ok, type Result } from "../util/result.js";
+import { getGlobalCasDir } from "../util/storage-root.js";
 import type { PrefilledDiskStep } from "./engine.js";
 import { type ExecuteThreadIo, executeThread } from "./engine.js";
-import { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";
-import { createLogger } from "./logger.js";
-import { normalizeRefsField } from "./refs-field.js";
-import { err, ok, type Result } from "./result.js";
-import { getGlobalCasDir } from "./storage-root.js";
 import { createThreadPauseGate, type ThreadPauseGate } from "./thread-pause-gate.js";
-import type { RoleOutput, WorkflowFn, WorkflowResult } from "./types.js";
 
 const bootLog = createLogger({ sink: { kind: "stderr" } });
 

packages/workflow/src/extract-provider.ts

@@ -1,8 +1,8 @@
-import { readWorkflowRegistry } from "./registry.js";
-import type { WorkflowConfig } from "./registry-types.js";
-import { err, ok, type Result } from "./result.js";
-import { getDefaultWorkflowStorageRoot } from "./storage-root.js";
+import { readWorkflowRegistry } from "./registry/registry.js";
+import type { WorkflowConfig } from "./registry/registry-types.js";
 import type { LlmProvider } from "./types.js";
+import { err, ok, type Result } from "./util/result.js";
+import { getDefaultWorkflowStorageRoot } from "./util/storage-root.js";
 
 const DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH = 3;
 

packages/workflow/src/extract/extract-fn.ts

@@ -1,8 +1,7 @@
 import type * as z from "zod/v4";
-
+import { getContentMerklePayload } from "../cas/merkle.js";
+import type { ExtractContext, LlmProvider } from "../types.js";
 import { llmExtractWithRetry } from "./llm-extract.js";
-import { getContentMerklePayload } from "./merkle.js";
-import type { ExtractContext, LlmProvider } from "./types.js";
 
 export type ExtractFn = <T extends Record<string, unknown>>(
   schema: z.ZodType<T>,

packages/workflow/src/extract/llm-extract.ts

@@ -1,7 +1,6 @@
 import * as z from "zod/v4";
-
-import { err, ok, type Result } from "./result.js";
-import type { LlmProvider } from "./types.js";
+import type { LlmProvider } from "../types.js";
+import { err, ok, type Result } from "../util/result.js";
 
 export type LlmExtractArgs<T> = {
   text: string;

packages/workflow/src/extract/react-extract.ts

@@ -1,9 +1,9 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "./cas.js";
+import type { CasStore } from "../cas/cas.js";
+import type { LlmProvider } from "../types.js";
+import { err, ok, type Result } from "../util/result.js";
 import { extractFunctionToolFromZodSchema } from "./llm-extract.js";
-import { err, ok, type Result } from "./result.js";
-import type { LlmProvider } from "./types.js";
 
 export type ReactExtractArgs<T extends Record<string, unknown>> = {
   text: string;

packages/workflow/src/index.ts

@@ -1,48 +1,21 @@
+export { buildDescriptor } from "./bundle/build-descriptor.js";
 export {
-  CROCKFORD_BASE32_ALPHABET,
-  decodeCrockfordBase32Bits,
-  decodeCrockfordToUint64,
-  encodeCrockfordBase32Bits,
-  encodeUint64AsCrockford,
-} from "./base32.js";
-export { buildDescriptor } from "./build-descriptor.js";
-export { validateWorkflowBundle, type WorkflowBundleValidationInput } from "./bundle-validator.js";
-export { type CasStore, createCasStore, createThreadCas } from "./cas.js";
-export { createWorkflow } from "./create-workflow.js";
+  validateWorkflowBundle,
+  type WorkflowBundleValidationInput,
+} from "./bundle/bundle-validator.js";
 export {
-  type ExecuteThreadIo,
-  type ExecuteThreadOptions,
-  executeThread,
-  type PrefilledDiskStep,
-} from "./engine.js";
-export { type ExtractedBundleExports, extractBundleExports } from "./extract-bundle-exports.js";
-export { createExtract, type ExtractFn } from "./extract-fn.js";
-export { getExtractProvider } from "./extract-provider.js";
+  type ExtractedBundleExports,
+  extractBundleExports,
+} from "./bundle/extract-bundle-exports.js";
+export { stringifyWorkflowDescriptor } from "./bundle/generate-descriptor.js";
 export {
-  buildForkPlan,
-  type ForkHistoricalStep,
-  type ForkPlan,
-  type ParsedThreadStartRecord,
-  parseThreadDataJsonl,
-  selectForkHistoricalSteps,
-  tryParseRoleStepRecord,
-  tryParseWorkflowResultRecord,
-} from "./fork-thread.js";
-export { type GcResult, garbageCollectCas } from "./gc.js";
-export { stringifyWorkflowDescriptor } from "./generate-descriptor.js";
-export { hashString, hashWorkflowBundleBytes } from "./hash.js";
-export {
-  type LlmError,
-  llmErrorToCause,
-  llmExtract,
-  llmExtractWithRetry,
-} from "./llm-extract.js";
-export {
-  type CreateLoggerOptions,
-  createLogger,
-  type LogFn,
-  type LoggerSink,
-} from "./logger.js";
+  validateWorkflowDescriptor,
+  type WorkflowDescriptor,
+  type WorkflowRoleDescriptor,
+  type WorkflowRoleSchema,
+} from "./bundle/workflow-descriptor.js";
+export { type CasStore, createCasStore, createThreadCas } from "./cas/cas.js";
+export { hashString, hashWorkflowBundleBytes } from "./cas/hash.js";
 export {
   createContentMerkleNode,
   getContentMerklePayload,
@@ -55,8 +28,36 @@ export {
   type StepMerklePayload,
   serializeMerkleNode,
   type ThreadMerklePayload,
-} from "./merkle.js";
-export { type ReactExtractArgs, reactExtract } from "./react-extract.js";
+} from "./cas/merkle.js";
+export { createWorkflow } from "./engine/create-workflow.js";
+export {
+  type ExecuteThreadIo,
+  type ExecuteThreadOptions,
+  executeThread,
+  type PrefilledDiskStep,
+} from "./engine/engine.js";
+export {
+  buildForkPlan,
+  type ForkHistoricalStep,
+  type ForkPlan,
+  type ParsedThreadStartRecord,
+  parseThreadDataJsonl,
+  selectForkHistoricalSteps,
+  tryParseRoleStepRecord,
+  tryParseWorkflowResultRecord,
+} from "./engine/fork-thread.js";
+export { type GcResult, garbageCollectCas } from "./engine/gc.js";
+export { createThreadPauseGate, type ThreadPauseGate } from "./engine/thread-pause-gate.js";
+export { getWorkerHostScriptPath } from "./engine/worker-entry-path.js";
+export { createExtract, type ExtractFn } from "./extract/extract-fn.js";
+export {
+  type LlmError,
+  llmErrorToCause,
+  llmExtract,
+  llmExtractWithRetry,
+} from "./extract/llm-extract.js";
+export { type ReactExtractArgs, reactExtract } from "./extract/react-extract.js";
+export { getExtractProvider } from "./extract-provider.js";
 export {
   type ExtractProviderConfig,
   getRegisteredWorkflow,
@@ -73,10 +74,7 @@ export {
   type WorkflowRegistryFile,
   workflowRegistryPath,
   writeWorkflowRegistry,
-} from "./registry.js";
-export { err, ok, type Result } from "./result.js";
-export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
-export { createThreadPauseGate, type ThreadPauseGate } from "./thread-pause-gate.js";
+} from "./registry/registry.js";
 export {
   type AgentBinding,
   type AgentContext,
@@ -101,12 +99,20 @@ export {
   type WorkflowFnOptions,
   type WorkflowResult,
 } from "./types.js";
-export { generateUlid } from "./ulid.js";
-export { getWorkerHostScriptPath } from "./worker-entry-path.js";
-export { type WorkflowAsAgentOptions, workflowAsAgent } from "./workflow-as-agent.js";
 export {
-  validateWorkflowDescriptor,
-  type WorkflowDescriptor,
-  type WorkflowRoleDescriptor,
-  type WorkflowRoleSchema,
-} from "./workflow-descriptor.js";
+  CROCKFORD_BASE32_ALPHABET,
+  decodeCrockfordBase32Bits,
+  decodeCrockfordToUint64,
+  encodeCrockfordBase32Bits,
+  encodeUint64AsCrockford,
+} from "./util/base32.js";
+export {
+  type CreateLoggerOptions,
+  createLogger,
+  type LogFn,
+  type LoggerSink,
+} from "./util/logger.js";
+export { err, ok, type Result } from "./util/result.js";
+export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./util/storage-root.js";
+export { generateUlid } from "./util/ulid.js";
+export { type WorkflowAsAgentOptions, workflowAsAgent } from "./workflow-as-agent.js";

packages/workflow/src/registry/registry-normalize.ts

@@ -1,3 +1,4 @@
+import { err, ok, type Result } from "../util/result.js";
 import type {
   ExtractProviderConfig,
   WorkflowConfig,
@@ -5,7 +6,6 @@ import type {
   WorkflowRegistryEntry,
   WorkflowRegistryFile,
 } from "./registry-types.js";
-import { err, ok, type Result } from "./result.js";
 
 function resolveRegistryApiKey(raw: string): Result<string, Error> {
   if (raw.startsWith("env:")) {

packages/workflow/src/registry/registry.ts

@@ -2,14 +2,13 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { parseDocument, stringify } from "yaml";
-
+import { err, ok, type Result } from "../util/result.js";
 import { normalizeWorkflowRegistryRoot } from "./registry-normalize.js";
 import type {
   WorkflowHistoryEntry,
   WorkflowRegistryEntry,
   WorkflowRegistryFile,
 } from "./registry-types.js";
-import { err, ok, type Result } from "./result.js";
 
 export type {
   ExtractProviderConfig,

packages/workflow/src/types.ts

@@ -1,6 +1,6 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "./cas.js";
+import type { CasStore } from "./cas/cas.js";
 
 /** Sentinel values for automaton control flow. */
 export const START = "__start__" as const;

packages/workflow/src/workflow-as-agent.ts

@@ -1,14 +1,14 @@
 import { join } from "node:path";
 
-import { createCasStore } from "./cas.js";
-import { type ExecuteThreadIo, executeThread } from "./engine.js";
-import { extractBundleExports } from "./extract-bundle-exports.js";
+import { extractBundleExports } from "./bundle/extract-bundle-exports.js";
+import { createCasStore } from "./cas/cas.js";
+import { type ExecuteThreadIo, executeThread } from "./engine/engine.js";
 import { getWorkflowAsAgentMaxDepth } from "./extract-provider.js";
-import { createLogger } from "./logger.js";
-import { getRegisteredWorkflow, readWorkflowRegistry } from "./registry.js";
-import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
+import { getRegisteredWorkflow, readWorkflowRegistry } from "./registry/registry.js";
 import type { AgentContext, AgentFn, ThreadInput } from "./types.js";
-import { generateUlid } from "./ulid.js";
+import { createLogger } from "./util/logger.js";
+import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./util/storage-root.js";
+import { generateUlid } from "./util/ulid.js";
 
 export type WorkflowAsAgentOptions = {
   /** When `null`, uses `getDefaultWorkflowStorageRoot()`. */