chore: enforce folder module discipline in @uncaged/workflow

Each folder now has:
- types.ts for all type definitions
- index.ts with pure re-exports only
- Cross-folder imports go through index.ts

Closes #106

CLAUDE.md

@@ -97,6 +97,36 @@ type WorkflowEntry = {
 
 Workflow bundles (`.esm.js`) follow the same rule: export `const run` and `const descriptor`, not `export default`.
 
+### Folder Module Discipline
+
+Every folder under `src/` is a **module boundary**. Four rules:
+
+| # | Rule | Rationale |
+|---|------|-----------|
+| 1 | **Every folder exports via `index.ts`** | Single entry point for the module |
+| 2 | **Types live in `types.ts`** | Each folder's type definitions go in `<folder>/types.ts`, not scattered across files |
+| 3 | **Single export source** | Only `index.ts` may re-export. No file may re-export from another module's internals. Cross-module imports must go through `index.ts` — never reach past it to import a specific file |
+| 4 | **`index.ts` is pure re-exports** | No type definitions, no function implementations — only `export { ... } from` statements |
+
+```typescript
+// ✅ Good — import through module boundary
+import { createCasStore } from "../cas/index.js";
+import type { CasStore } from "../cas/index.js";
+
+// ❌ Bad — reaching past index.ts
+import { createCasStore } from "../cas/cas.js";
+
+// ❌ Bad — re-exporting from non-index file
+// in engine/engine.ts:
+export { createCasStore } from "../cas/cas.js";
+
+// ❌ Bad — types defined in index.ts
+// in cas/index.ts:
+export type CasStore = { ... };  // should be in cas/types.ts
+```
+
+**Exception**: The package-level `src/index.ts` is the public API surface and re-exports from folder `index.ts` files. Files that remain at `src/` root (e.g. `types.ts`, `workflow-as-agent.ts`) are not inside a folder module and follow normal rules.
+
 ## Naming
 
 | Type | Style | Example |
@@ -197,9 +227,8 @@ Test files (`__tests__/**`) are exempt.
 ### Commands
 
 ```bash
-bun run check       # biome check (lint + format)
+bun run check       # tsc --build + biome check
 bun run format      # biome format --write
-bun run build       # full build
 bun test            # run tests
 ```
 

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

@@ -30,13 +30,12 @@ export async function dispatchGc(storageRoot: string, argv: string[]): Promise<n
 }
 
 export async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const hash = rest[1];
-  if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usageText()}\n\nerror: cas get requires <thread-id> <hash>`);
+  const hash = rest[0];
+  if (hash === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas get requires <hash>`);
     return 1;
   }
-  const result = await cmdCasGet(storageRoot, threadId, hash);
+  const result = await cmdCasGet(storageRoot, hash);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -46,13 +45,12 @@ export async function dispatchCasGet(storageRoot: string, rest: string[]): Promi
 }
 
 export async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const content = rest[1];
-  if (threadId === undefined || content === undefined || rest.length > 2) {
-    printCliError(`${usageText()}\n\nerror: cas put requires <thread-id> <content>`);
+  const content = rest[0];
+  if (content === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas put requires <content>`);
     return 1;
   }
-  const result = await cmdCasPut(storageRoot, threadId, content);
+  const result = await cmdCasPut(storageRoot, content);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -62,12 +60,11 @@ export async function dispatchCasPut(storageRoot: string, rest: string[]): Promi
 }
 
 export async function dispatchCasList(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  if (threadId === undefined || rest.length > 1) {
-    printCliError(`${usageText()}\n\nerror: cas list requires <thread-id>`);
+  if (rest.length > 0) {
+    printCliError(`${usageText()}\n\nerror: cas list takes no arguments`);
     return 1;
   }
-  const result = await cmdCasList(storageRoot, threadId);
+  const result = await cmdCasList(storageRoot);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -79,13 +76,12 @@ export async function dispatchCasList(storageRoot: string, rest: string[]): Prom
 }
 
 export async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const hash = rest[1];
-  if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${usageText()}\n\nerror: cas rm requires <thread-id> <hash>`);
+  const hash = rest[0];
+  if (hash === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas rm requires <hash>`);
     return 1;
   }
-  const result = await cmdCasRm(storageRoot, threadId, hash);
+  const result = await cmdCasRm(storageRoot, hash);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -97,20 +93,20 @@ export async function dispatchCasRm(storageRoot: string, rest: string[]): Promis
 export const CAS_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   get: {
     handler: dispatchCasGet,
-    args: "<thread-id> <hash>",
-    description: "Retrieve content by hash from a thread's CAS",
+    args: "<hash>",
+    description: "Retrieve content by hash from CAS",
   },
   put: {
     handler: dispatchCasPut,
-    args: "<thread-id> <content>",
-    description: "Store content in a thread's CAS, returns hash",
+    args: "<content>",
+    description: "Store content in CAS, prints hash",
   },
   list: {
     handler: dispatchCasList,
-    args: "<thread-id>",
-    description: "List all CAS entries for a thread",
+    args: "",
+    description: "List all hashes in CAS",
   },
-  rm: { handler: dispatchCasRm, args: "<thread-id> <hash>", description: "Remove a CAS entry" },
+  rm: { handler: dispatchCasRm, args: "<hash>", description: "Remove a CAS entry by hash" },
   gc: { handler: dispatchGc, args: "", description: "Garbage-collect unreferenced CAS entries" },
 };
 

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/skill.ts

@@ -126,13 +126,13 @@ uncaged-workflow thread list
 
 ## CAS (Content-Addressable Storage)
 
-Store and retrieve content by hash, scoped to the current thread.
+Store and retrieve content by hash in workflow storage (global CAS directory).
 
 | Operation | Command |
 |-----------|---------|
-| **Store** | \`uncaged-workflow cas put <THREAD_ID> '<content>'\` → prints hash |
-| **Read** | \`uncaged-workflow cas get <THREAD_ID> <HASH>\` → prints content |
-| **List** | \`uncaged-workflow cas list <THREAD_ID>\` |
+| **Store** | \`uncaged-workflow cas put '<content>'\` → prints hash |
+| **Read** | \`uncaged-workflow cas get <HASH>\` → prints content |
+| **List** | \`uncaged-workflow cas list\` |
 
 CAS is the **only** supported way to persist structured data (phase plans, review notes, etc.) within a thread. Do not use temp files.
 

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,7 +1,7 @@
 import * as z from "zod/v4";
 
-import type { RoleMeta, WorkflowDefinition } from "./types.js";
-import type { WorkflowDescriptor, WorkflowRoleSchema } from "./workflow-descriptor.js";
+import type { RoleMeta, WorkflowDefinition } from "../types.js";
+import type { WorkflowDescriptor, WorkflowRoleSchema } from "./types.js";
 
 function stripJsonSchemaMeta(json: Record<string, unknown>): WorkflowRoleSchema {
   const { $schema: _drop, ...rest } = json;

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

@@ -10,6 +10,11 @@ import type {
   Program,
   VariableDeclaration,
 } from "acorn";
+import * as acorn from "acorn";
+
+import { err, ok, type Result } from "../util/index.js";
+
+import type { WorkflowBundleValidationInput } from "./types.js";
 
 /** Acorn Node with index-access for property traversal. */
 type AcornNode = Node & { [key: string]: unknown };
@@ -22,17 +27,6 @@ function narrowNode<T extends Node>(node: Node): T {
   return node as unknown as T;
 }
 
-import * as acorn from "acorn";
-
-import { err, ok, type Result } from "./result.js";
-
-export type WorkflowBundleValidationInput = {
-  /** Absolute or relative path (used for `.esm.js` suffix checks). */
-  filePath: string;
-  /** UTF-8 source of the bundle. */
-  source: string;
-};
-
 function endsWithEsmJs(path: string): boolean {
   return path.endsWith(".esm.js");
 }

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,20 +1,10 @@
+import type { WorkflowFn } from "../types.js";
+import { err, ok, type Result } from "../util/index.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 type { ExtractBundleExportsOptions, ExtractedBundleExports } from "./types.js";
 import { validateWorkflowDescriptor } from "./workflow-descriptor.js";
 
-export type ExtractedBundleExports = {
-  run: WorkflowFn;
-  descriptor: WorkflowDescriptor;
-};
-
-export type ExtractBundleExportsOptions = {
-  /** When set, ensures `node_modules/@uncaged/workflow` exists under this root before import. */
-  storageRoot: string | null;
-};
-
 /** Load a workflow `.esm.js` bundle and read its named exports (`run`, `descriptor`). */
 export async function extractBundleExports(
   bundlePath: string,

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

@@ -1,6 +1,6 @@
 import { stringify } from "yaml";
 
-import type { WorkflowDescriptor } from "./workflow-descriptor.js";
+import type { WorkflowDescriptor } from "./types.js";
 
 /** Serialize a validated workflow descriptor to YAML for storage next to the bundle. */
 export function stringifyWorkflowDescriptor(descriptor: WorkflowDescriptor): string {

packages/workflow/src/bundle/index.ts

@@ -0,0 +1,15 @@
+export { buildDescriptor } from "./build-descriptor.js";
+export { importWorkflowBundleModule } from "./bundle-import-env.js";
+export { validateWorkflowBundle } from "./bundle-validator.js";
+export { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";
+export { extractBundleExports } from "./extract-bundle-exports.js";
+export { stringifyWorkflowDescriptor } from "./generate-descriptor.js";
+export type {
+  ExtractBundleExportsOptions,
+  ExtractedBundleExports,
+  WorkflowBundleValidationInput,
+  WorkflowDescriptor,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
+} from "./types.js";
+export { validateWorkflowDescriptor } from "./workflow-descriptor.js";

packages/workflow/src/bundle/types.ts

@@ -0,0 +1,32 @@
+import type { WorkflowFn } from "../types.js";
+
+/** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
+export type WorkflowRoleSchema = Record<string, unknown>;
+
+export type WorkflowRoleDescriptor = {
+  description: string;
+  schema: WorkflowRoleSchema;
+};
+
+/** Workflow metadata exported as `export const descriptor` from `.esm.js` bundles. */
+export type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+};
+
+export type WorkflowBundleValidationInput = {
+  /** Absolute or relative path (used for `.esm.js` suffix checks). */
+  filePath: string;
+  /** UTF-8 source of the bundle. */
+  source: string;
+};
+
+export type ExtractedBundleExports = {
+  run: WorkflowFn;
+  descriptor: WorkflowDescriptor;
+};
+
+export type ExtractBundleExportsOptions = {
+  /** When set, ensures `node_modules/@uncaged/workflow` exists under this root before import. */
+  storageRoot: string | null;
+};

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

@@ -1,18 +1,6 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/index.js";
 
-/** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
-export type WorkflowRoleSchema = Record<string, unknown>;
-
-export type WorkflowRoleDescriptor = {
-  description: string;
-  schema: WorkflowRoleSchema;
-};
-
-/** Workflow metadata exported as `export const descriptor` from `.esm.js` bundles. */
-export type WorkflowDescriptor = {
-  description: string;
-  roles: Record<string, WorkflowRoleDescriptor>;
-};
+import type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
 
 export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescriptor, string> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {

packages/workflow/src/cas/cas.ts

@@ -2,13 +2,7 @@ import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/pro
 import { join } from "node:path";
 
 import { hashString } from "./hash.js";
-
-export type CasStore = {
-  put(content: string): Promise<string>;
-  get(hash: string): Promise<string | null>;
-  delete(hash: string): Promise<void>;
-  list(): Promise<string[]>;
-};
+import type { CasStore } from "./types.js";
 
 export function createCasStore(casDir: string): CasStore {
   async function ensureDir(): Promise<void> {

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/index.js";
 
 function digestToUint64(digest: { toString(radix?: number): string }): bigint {
   const hex = digest.toString(16).padStart(16, "0");

packages/workflow/src/cas/index.ts

@@ -0,0 +1,18 @@
+export { createCasStore, createThreadCas } from "./cas.js";
+export { hashString, hashWorkflowBundleBytes } from "./hash.js";
+export {
+  createContentMerkleNode,
+  getContentMerklePayload,
+  parseMerkleNode,
+  putContentMerkleNode,
+  putStepMerkleNode,
+  putThreadMerkleNode,
+  serializeMerkleNode,
+} from "./merkle.js";
+export type {
+  CasStore,
+  MerkleNode,
+  MerkleNodeType,
+  StepMerklePayload,
+  ThreadMerklePayload,
+} from "./types.js";

packages/workflow/src/cas/merkle.ts

@@ -1,14 +1,6 @@
 import { parse, stringify } from "yaml";
 
-import type { CasStore } from "./cas.js";
-
-export type MerkleNodeType = "content" | "step" | "thread";
-
-export type MerkleNode = {
-  type: MerkleNodeType;
-  payload: string | Record<string, unknown>;
-  children: string[];
-};
+import type { CasStore, MerkleNode, StepMerklePayload, ThreadMerklePayload } from "./types.js";
 
 export function serializeMerkleNode(node: MerkleNode): string {
   return stringify(
@@ -53,20 +45,6 @@ export function createContentMerkleNode(payload: string): MerkleNode {
   return { type: "content", payload, children: [] };
 }
 
-export type StepMerklePayload = {
-  role: string;
-  meta: Record<string, unknown>;
-};
-
-export type ThreadMerklePayload = {
-  workflow: string;
-  threadId: string;
-  result: {
-    returnCode: number;
-    summary: string;
-  };
-};
-
 /** Serializes a step Merkle node (role + meta + content child) and stores it in CAS. */
 export async function putStepMerkleNode(
   store: CasStore,

packages/workflow/src/cas/types.ts

@@ -0,0 +1,28 @@
+export type CasStore = {
+  put(content: string): Promise<string>;
+  get(hash: string): Promise<string | null>;
+  delete(hash: string): Promise<void>;
+  list(): Promise<string[]>;
+};
+
+export type MerkleNodeType = "content" | "step" | "thread";
+
+export type MerkleNode = {
+  type: MerkleNodeType;
+  payload: string | Record<string, unknown>;
+  children: string[];
+};
+
+export type StepMerklePayload = {
+  role: string;
+  meta: Record<string, unknown>;
+};
+
+export type ThreadMerklePayload = {
+  workflow: string;
+  threadId: string;
+  result: {
+    returnCode: number;
+    summary: string;
+  };
+};

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

@@ -1,8 +1,6 @@
-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/index.js";
+import { putContentMerkleNode } from "../cas/index.js";
+import { buildExtractUserContent, type ExtractFn, reactExtract } from "../extract/index.js";
 import {
   type AgentBinding,
   type AgentContext,
@@ -20,7 +18,8 @@ import {
   type WorkflowDefinition,
   type WorkflowFn,
   type WorkflowFnOptions,
-} from "./types.js";
+} from "../types.js";
+import { mergeRefsWithContentHash } from "../util/index.js";
 
 function isRoleNext<M extends RoleMeta>(
   next: (keyof M & string) | typeof END,

packages/workflow/src/engine/engine.ts

@@ -1,50 +1,22 @@
 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,
+  getContentMerklePayload,
+  putStepMerkleNode,
+  putThreadMerkleNode,
+} from "../cas/index.js";
 import type {
   ThreadInput,
   WorkflowCompletion,
   WorkflowFn,
   WorkflowFnOptions,
   WorkflowResult,
-} from "./types.js";
+} from "../types.js";
+import { type LogFn, normalizeRefsField } from "../util/index.js";
 
-export type ExecuteThreadIo = {
-  threadId: string;
-  hash: string;
-  dataJsonlPath: string;
-  infoJsonlPath: string;
-  cas: CasStore;
-};
-
-/** One persisted role line in `.data.jsonl` (engine adds these for fork replay before running the generator). */
-export type PrefilledDiskStep = {
-  role: string;
-  contentHash: string;
-  meta: Record<string, unknown>;
-  refs: string[];
-  timestamp: number;
-};
-
-export type ExecuteThreadOptions = {
-  maxRounds: number;
-  /** Passed to the bundle as `WorkflowFnOptions.depth`. */
-  depth: number;
-  signal: AbortSignal;
-  /** Invoked after each successful yield (and outer-loop checks); used for pause/resume. */
-  awaitAfterEachYield: () => Promise<void>;
-  /** When non-null, written into the start record so tooling can trace lineage. */
-  forkSourceThreadId: string | null;
-  /**
-   * Written to `.data.jsonl` immediately after the start record, before the generator runs.
-   * Must match `input.steps` length and order when present.
-   */
-  prefilledDiskSteps: PrefilledDiskStep[] | null;
-};
+import type { ExecuteThreadIo, ExecuteThreadOptions } from "./types.js";
 
 async function appendDataLine(path: string, record: unknown): Promise<void> {
   const line = `${JSON.stringify(record)}\n`;

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

@@ -1,18 +1,7 @@
-import { normalizeRefsField } from "./refs-field.js";
-import { err, ok, type Result } from "./result.js";
-import type { RoleOutput, WorkflowCompletion } from "./types.js";
+import type { WorkflowCompletion } from "../types.js";
+import { err, normalizeRefsField, ok, type Result } from "../util/index.js";
 
-/** Role steps replayed from `.data.jsonl`, including persisted timestamps. */
-export type ForkHistoricalStep = RoleOutput & { timestamp: number };
-
-export type ParsedThreadStartRecord = {
-  workflowName: string;
-  hash: string;
-  threadId: string;
-  prompt: string;
-  maxRounds: number;
-  depth: number;
-};
+import type { ForkHistoricalStep, ForkPlan, ParsedThreadStartRecord } from "./types.js";
 
 /** Recognizes a persisted workflow completion line (no `role`; has numeric `returnCode` and string `summary`). Omits `rootHash` when absent. */
 export function tryParseWorkflowResultRecord(
@@ -228,15 +217,6 @@ export function selectForkHistoricalSteps(
   return ok(roleSteps.slice(0, idx + 1));
 }
 
-export type ForkPlan = {
-  workflowName: string;
-  hash: string;
-  sourceThreadId: string;
-  prompt: string;
-  runOptions: { maxRounds: number; depth: number };
-  historicalSteps: ForkHistoricalStep[];
-};
-
 /**
  * Read `.data.jsonl` text and compute fork payload for the worker `run` command.
  */

packages/workflow/src/engine/gc.ts

@@ -1,17 +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/index.js";
+import { err, getGlobalCasDir, ok, type Result } from "../util/index.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;
-  activeRefs: number;
-  deletedEntries: number;
-  deletedHashes: string[];
-};
+import type { GcResult } from "./types.js";
 
 async function listThreadDataJsonlPaths(storageRoot: string): Promise<Result<string[], string>> {
   const logsRoot = join(storageRoot, "logs");

packages/workflow/src/engine/index.ts

@@ -0,0 +1,22 @@
+export { createWorkflow } from "./create-workflow.js";
+export { executeThread } from "./engine.js";
+export {
+  buildForkPlan,
+  parseThreadDataJsonl,
+  selectForkHistoricalSteps,
+  tryParseRoleStepRecord,
+  tryParseWorkflowResultRecord,
+} from "./fork-thread.js";
+export { garbageCollectCas } from "./gc.js";
+export { createThreadPauseGate } from "./thread-pause-gate.js";
+export type {
+  ExecuteThreadIo,
+  ExecuteThreadOptions,
+  ForkHistoricalStep,
+  ForkPlan,
+  GcResult,
+  ParsedThreadStartRecord,
+  PrefilledDiskStep,
+  ThreadPauseGate,
+} from "./types.js";
+export { getWorkerHostScriptPath } from "./worker-entry-path.js";

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

@@ -1,11 +1,6 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/index.js";
 
-export type ThreadPauseGate = {
-  awaitAfterYield: () => Promise<void>;
-  pause: () => Result<void, string>;
-  resume: () => Result<void, string>;
-  isPaused: () => boolean;
-};
+import type { ThreadPauseGate } from "./types.js";
 
 /**
  * Pause/resume gate for workflow threads: after each generator yield the engine awaits

packages/workflow/src/engine/types.ts

@@ -0,0 +1,71 @@
+import type { CasStore } from "../cas/index.js";
+import type { RoleOutput } from "../types.js";
+import type { Result } from "../util/index.js";
+
+export type ExecuteThreadIo = {
+  threadId: string;
+  hash: string;
+  dataJsonlPath: string;
+  infoJsonlPath: string;
+  cas: CasStore;
+};
+
+/** One persisted role line in `.data.jsonl` (engine adds these for fork replay before running the generator). */
+export type PrefilledDiskStep = {
+  role: string;
+  contentHash: string;
+  meta: Record<string, unknown>;
+  refs: string[];
+  timestamp: number;
+};
+
+export type ExecuteThreadOptions = {
+  maxRounds: number;
+  /** Passed to the bundle as `WorkflowFnOptions.depth`. */
+  depth: number;
+  signal: AbortSignal;
+  /** Invoked after each successful yield (and outer-loop checks); used for pause/resume. */
+  awaitAfterEachYield: () => Promise<void>;
+  /** When non-null, written into the start record so tooling can trace lineage. */
+  forkSourceThreadId: string | null;
+  /**
+   * Written to `.data.jsonl` immediately after the start record, before the generator runs.
+   * Must match `input.steps` length and order when present.
+   */
+  prefilledDiskSteps: PrefilledDiskStep[] | null;
+};
+
+/** Role steps replayed from `.data.jsonl`, including persisted timestamps. */
+export type ForkHistoricalStep = RoleOutput & { timestamp: number };
+
+export type ParsedThreadStartRecord = {
+  workflowName: string;
+  hash: string;
+  threadId: string;
+  prompt: string;
+  maxRounds: number;
+  depth: number;
+};
+
+export type ForkPlan = {
+  workflowName: string;
+  hash: string;
+  sourceThreadId: string;
+  prompt: string;
+  runOptions: { maxRounds: number; depth: number };
+  historicalSteps: ForkHistoricalStep[];
+};
+
+export type GcResult = {
+  scannedThreads: number;
+  activeRefs: number;
+  deletedEntries: number;
+  deletedHashes: string[];
+};
+
+export type ThreadPauseGate = {
+  awaitAfterYield: () => Promise<void>;
+  pause: () => Result<void, string>;
+  resume: () => Result<void, string>;
+  isPaused: () => boolean;
+};

packages/workflow/src/engine/worker.ts

@@ -1,17 +1,20 @@
 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 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";
+import { ensureUncagedWorkflowSymlink, importWorkflowBundleModule } from "../bundle/index.js";
+import { createCasStore } from "../cas/index.js";
+import type { RoleOutput, WorkflowFn, WorkflowResult } from "../types.js";
+import {
+  createLogger,
+  err,
+  getGlobalCasDir,
+  normalizeRefsField,
+  ok,
+  type Result,
+} from "../util/index.js";
+import { executeThread } from "./engine.js";
+import { createThreadPauseGate } from "./thread-pause-gate.js";
+import type { ExecuteThreadIo, PrefilledDiskStep, ThreadPauseGate } from "./types.js";
 
 const bootLog = createLogger({ sink: { kind: "stderr" } });
 

packages/workflow/src/extract-provider.ts

@@ -1,8 +1,7 @@
-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 type { WorkflowConfig } from "./registry/index.js";
+import { readWorkflowRegistry } from "./registry/index.js";
 import type { LlmProvider } from "./types.js";
+import { err, getDefaultWorkflowStorageRoot, ok, type Result } from "./util/index.js";
 
 const DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH = 3;
 

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

@@ -1,14 +1,9 @@
 import type * as z from "zod/v4";
 
+import { getContentMerklePayload } from "../cas/index.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>,
-  prompt: string,
-  ctx: ExtractContext,
-) => Promise<T>;
+import type { ExtractFn } from "./types.js";
 
 /** Builds the user-side extraction prompt (thread + agent output + instruction). */
 export async function buildExtractUserContent(

packages/workflow/src/extract/index.ts

@@ -0,0 +1,17 @@
+export {
+  buildExtractUserContent,
+  createExtract,
+} from "./extract-fn.js";
+export {
+  extractFunctionToolFromZodSchema,
+  llmErrorToCause,
+  llmExtract,
+  llmExtractWithRetry,
+} from "./llm-extract.js";
+export { reactExtract } from "./react-extract.js";
+export type {
+  ExtractFn,
+  LlmError,
+  LlmExtractArgs,
+  ReactExtractArgs,
+} from "./types.js";

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

@@ -1,21 +1,8 @@
 import * as z from "zod/v4";
 
-import { err, ok, type Result } from "./result.js";
-import type { LlmProvider } from "./types.js";
+import { err, ok, type Result } from "../util/index.js";
 
-export type LlmExtractArgs<T> = {
-  text: string;
-  schema: z.ZodType<T>;
-  provider: LlmProvider;
-};
-
-export type LlmError =
-  | { kind: "http_error"; status: number; body: string }
-  | { kind: "invalid_response_json"; message: string }
-  | { kind: "no_tool_call"; preview: string }
-  | { kind: "tool_arguments_invalid_json"; message: string }
-  | { kind: "schema_validation_failed"; message: string }
-  | { kind: "network_error"; message: string };
+import type { LlmError, LlmExtractArgs } from "./types.js";
 
 function chatCompletionsUrl(baseUrl: string): string {
   const trimmed = baseUrl.replace(/\/+$/, "");

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

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

packages/workflow/src/extract/types.ts

@@ -0,0 +1,31 @@
+import type * as z from "zod/v4";
+
+import type { CasStore } from "../cas/index.js";
+import type { ExtractContext, LlmProvider } from "../types.js";
+
+export type ExtractFn = <T extends Record<string, unknown>>(
+  schema: z.ZodType<T>,
+  prompt: string,
+  ctx: ExtractContext,
+) => Promise<T>;
+
+export type ReactExtractArgs<T extends Record<string, unknown>> = {
+  text: string;
+  schema: z.ZodType<T>;
+  provider: LlmProvider;
+  cas: CasStore;
+};
+
+export type LlmExtractArgs<T> = {
+  text: string;
+  schema: z.ZodType<T>;
+  provider: LlmProvider;
+};
+
+export type LlmError =
+  | { kind: "http_error"; status: number; body: string }
+  | { kind: "invalid_response_json"; message: string }
+  | { kind: "no_tool_call"; preview: string }
+  | { kind: "tool_arguments_invalid_json"; message: string }
+  | { kind: "schema_validation_failed"; message: string }
+  | { kind: "network_error"; message: string };

packages/workflow/src/index.ts

@@ -1,51 +1,23 @@
 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";
-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";
-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";
+  buildDescriptor,
+  type ExtractedBundleExports,
+  extractBundleExports,
+  stringifyWorkflowDescriptor,
+  validateWorkflowBundle,
+  validateWorkflowDescriptor,
+  type WorkflowBundleValidationInput,
+  type WorkflowDescriptor,
+  type WorkflowRoleDescriptor,
+  type WorkflowRoleSchema,
+} from "./bundle/index.js";
 export {
+  type CasStore,
+  createCasStore,
   createContentMerkleNode,
+  createThreadCas,
   getContentMerklePayload,
+  hashString,
+  hashWorkflowBundleBytes,
   type MerkleNode,
   type MerkleNodeType,
   parseMerkleNode,
@@ -55,8 +27,38 @@ export {
   type StepMerklePayload,
   serializeMerkleNode,
   type ThreadMerklePayload,
-} from "./merkle.js";
-export { type ReactExtractArgs, reactExtract } from "./react-extract.js";
+} from "./cas/index.js";
+export {
+  buildForkPlan,
+  createThreadPauseGate,
+  createWorkflow,
+  type ExecuteThreadIo,
+  type ExecuteThreadOptions,
+  executeThread,
+  type ForkHistoricalStep,
+  type ForkPlan,
+  type GcResult,
+  garbageCollectCas,
+  getWorkerHostScriptPath,
+  type ParsedThreadStartRecord,
+  type PrefilledDiskStep,
+  parseThreadDataJsonl,
+  selectForkHistoricalSteps,
+  type ThreadPauseGate,
+  tryParseRoleStepRecord,
+  tryParseWorkflowResultRecord,
+} from "./engine/index.js";
+export {
+  createExtract,
+  type ExtractFn,
+  type LlmError,
+  llmErrorToCause,
+  llmExtract,
+  llmExtractWithRetry,
+  type ReactExtractArgs,
+  reactExtract,
+} from "./extract/index.js";
+export { getExtractProvider } from "./extract-provider.js";
 export {
   type ExtractProviderConfig,
   getRegisteredWorkflow,
@@ -73,10 +75,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/index.js";
 export {
   type AgentBinding,
   type AgentContext,
@@ -101,12 +100,21 @@ 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,
+  type CreateLoggerOptions,
+  createLogger,
+  decodeCrockfordBase32Bits,
+  decodeCrockfordToUint64,
+  encodeCrockfordBase32Bits,
+  encodeUint64AsCrockford,
+  err,
+  generateUlid,
+  getDefaultWorkflowStorageRoot,
+  getGlobalCasDir,
+  type LogFn,
+  type LoggerSink,
+  ok,
+  type Result,
+} from "./util/index.js";
+export { type WorkflowAsAgentOptions, workflowAsAgent } from "./workflow-as-agent.js";

packages/workflow/src/registry/index.ts

@@ -0,0 +1,19 @@
+export {
+  getRegisteredWorkflow,
+  listRegisteredWorkflowNames,
+  parseWorkflowRegistryYaml,
+  readWorkflowRegistry,
+  registerWorkflowVersion,
+  rollbackWorkflowToHistoryHash,
+  stringifyWorkflowRegistryYaml,
+  unregisterWorkflow,
+  workflowRegistryPath,
+  writeWorkflowRegistry,
+} from "./registry.js";
+export type {
+  ExtractProviderConfig,
+  WorkflowConfig,
+  WorkflowHistoryEntry,
+  WorkflowRegistryEntry,
+  WorkflowRegistryFile,
+} from "./types.js";

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

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

packages/workflow/src/registry/registry.ts

@@ -2,22 +2,9 @@ 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/index.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,
-  WorkflowConfig,
-  WorkflowHistoryEntry,
-  WorkflowRegistryEntry,
-  WorkflowRegistryFile,
-} from "./registry-types.js";
+import type { WorkflowHistoryEntry, WorkflowRegistryEntry, WorkflowRegistryFile } from "./types.js";
 
 export function workflowRegistryPath(storageRoot: string): string {
   return join(storageRoot, "workflow.yaml");

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/index.js";
 
 /** Sentinel values for automaton control flow. */
 export const START = "__start__" as const;

packages/workflow/src/util/base32.ts

@@ -1,4 +1,5 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok } from "./result.js";
+import type { Result } from "./types.js";
 
 /** Crockford Base32 alphabet (no I, L, O, U) — exactly 32 symbols. */
 export const CROCKFORD_BASE32_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";

packages/workflow/src/util/index.ts

@@ -0,0 +1,13 @@
+export {
+  CROCKFORD_BASE32_ALPHABET,
+  decodeCrockfordBase32Bits,
+  decodeCrockfordToUint64,
+  encodeCrockfordBase32Bits,
+  encodeUint64AsCrockford,
+} from "./base32.js";
+export { createLogger } from "./logger.js";
+export { mergeRefsWithContentHash, normalizeRefsField } from "./refs-field.js";
+export { err, ok } from "./result.js";
+export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
+export type { CreateLoggerOptions, LogFn, LoggerSink, Result } from "./types.js";
+export { generateUlid } from "./ulid.js";

packages/workflow/src/util/logger.ts

@@ -1,6 +1,7 @@
 import { appendFileSync } from "node:fs";
 
 import { CROCKFORD_BASE32_ALPHABET } from "./base32.js";
+import type { CreateLoggerOptions, LogFn } from "./types.js";
 
 const TAG_LENGTH = 8;
 
@@ -22,14 +23,6 @@ function assertValidLogTag(tag: string): void {
   }
 }
 
-export type LoggerSink = { kind: "stderr" } | { kind: "file"; path: string };
-
-export type CreateLoggerOptions = {
-  sink: LoggerSink;
-};
-
-export type LogFn = (tag: string, content: string) => void;
-
 /** Append one JSONL log record: `{ tag, content, timestamp }` per RFC-001. */
 export function createLogger(options: CreateLoggerOptions): LogFn {
   if (options.sink.kind === "stderr") {

packages/workflow/src/util/result.ts

@@ -1,4 +1,4 @@
-export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+import type { Result } from "./types.js";
 
 export function ok<T>(value: T): Result<T, never> {
   return { ok: true, value };

packages/workflow/src/util/types.ts

@@ -0,0 +1,9 @@
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+export type LoggerSink = { kind: "stderr" } | { kind: "file"; path: string };
+
+export type CreateLoggerOptions = {
+  sink: LoggerSink;
+};
+
+export type LogFn = (tag: string, content: string) => void;

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

@@ -1,14 +1,18 @@
 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/index.js";
+import { createCasStore } from "./cas/index.js";
+import type { ExecuteThreadIo } from "./engine/index.js";
+import { executeThread } from "./engine/index.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/index.js";
 import type { AgentContext, AgentFn, ThreadInput } from "./types.js";
-import { generateUlid } from "./ulid.js";
+import {
+  createLogger,
+  generateUlid,
+  getDefaultWorkflowStorageRoot,
+  getGlobalCasDir,
+} from "./util/index.js";
 
 export type WorkflowAsAgentOptions = {
   /** When `null`, uses `getDefaultWorkflowStorageRoot()`. */