diff --git a/packages/workflow/__tests__/base32.test.ts b/packages/workflow/__tests__/base32.test.ts
index 1087be7..88f09d5 100644
--- a/packages/workflow/__tests__/base32.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/build-descriptor.test.ts b/packages/workflow/__tests__/build-descriptor.test.ts
index 46fd71a..3487f61 100644
--- a/packages/workflow/__tests__/build-descriptor.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/bundle-validator.test.ts b/packages/workflow/__tests__/bundle-validator.test.ts
index 370f567..d7a77a4 100644
--- a/packages/workflow/__tests__/bundle-validator.test.ts
+++ b/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: {} };
 `;
diff --git a/packages/workflow/__tests__/cas.test.ts b/packages/workflow/__tests__/cas.test.ts
index ea17771..e18c30f 100644
--- a/packages/workflow/__tests__/cas.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/engine.test.ts b/packages/workflow/__tests__/engine.test.ts
index 5e4de10..ae05a7c 100644
--- a/packages/workflow/__tests__/engine.test.ts
+++ b/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(),
diff --git a/packages/workflow/__tests__/fork-thread.test.ts b/packages/workflow/__tests__/fork-thread.test.ts
index 4e75084..27bd253 100644
--- a/packages/workflow/__tests__/fork-thread.test.ts
+++ b/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}
diff --git a/packages/workflow/__tests__/hash.test.ts b/packages/workflow/__tests__/hash.test.ts
index 1ddcf9d..b8b345b 100644
--- a/packages/workflow/__tests__/hash.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/logger.test.ts b/packages/workflow/__tests__/logger.test.ts
index 213f4bf..d6c39b9 100644
--- a/packages/workflow/__tests__/logger.test.ts
+++ b/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 () => {
diff --git a/packages/workflow/__tests__/merkle.test.ts b/packages/workflow/__tests__/merkle.test.ts
index 6aa4194..3598cd7 100644
--- a/packages/workflow/__tests__/merkle.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/react-extract.test.ts b/packages/workflow/__tests__/react-extract.test.ts
index 9555fa5..cfd659d 100644
--- a/packages/workflow/__tests__/react-extract.test.ts
+++ b/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() });
diff --git a/packages/workflow/__tests__/refs-tracking.test.ts b/packages/workflow/__tests__/refs-tracking.test.ts
index 521b2f2..d862940 100644
--- a/packages/workflow/__tests__/refs-tracking.test.ts
+++ b/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(),
diff --git a/packages/workflow/__tests__/registry.test.ts b/packages/workflow/__tests__/registry.test.ts
index a32fe94..41954ed 100644
--- a/packages/workflow/__tests__/registry.test.ts
+++ b/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 () => {
diff --git a/packages/workflow/__tests__/result.test.ts b/packages/workflow/__tests__/result.test.ts
index 310c028..14f3c4b 100644
--- a/packages/workflow/__tests__/result.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/storage-root.test.ts b/packages/workflow/__tests__/storage-root.test.ts
index 6bcb765..9a3ca2d 100644
--- a/packages/workflow/__tests__/storage-root.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/thread-pause-gate.test.ts b/packages/workflow/__tests__/thread-pause-gate.test.ts
index b703fde..9b568e0 100644
--- a/packages/workflow/__tests__/thread-pause-gate.test.ts
+++ b/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 () => {
diff --git a/packages/workflow/__tests__/ulid.test.ts b/packages/workflow/__tests__/ulid.test.ts
index f1998f1..7608cc3 100644
--- a/packages/workflow/__tests__/ulid.test.ts
+++ b/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", () => {
diff --git a/packages/workflow/__tests__/worker.test.ts b/packages/workflow/__tests__/worker.test.ts
index 78ccd2c..943a71a 100644
--- a/packages/workflow/__tests__/worker.test.ts
+++ b/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";
 
diff --git a/packages/workflow/__tests__/workflow-as-agent-integration.test.ts b/packages/workflow/__tests__/workflow-as-agent-integration.test.ts
index fdb643e..2761e79 100644
--- a/packages/workflow/__tests__/workflow-as-agent-integration.test.ts
+++ b/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) });
diff --git a/packages/workflow/__tests__/workflow-as-agent.test.ts b/packages/workflow/__tests__/workflow-as-agent.test.ts
index 7b184be..11bb7af 100644
--- a/packages/workflow/__tests__/workflow-as-agent.test.ts
+++ b/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";
 
diff --git a/packages/workflow/__tests__/workflow-descriptor.test.ts b/packages/workflow/__tests__/workflow-descriptor.test.ts
index 171df79..fd4708d 100644
--- a/packages/workflow/__tests__/workflow-descriptor.test.ts
+++ b/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
diff --git a/packages/workflow/src/build-descriptor.ts b/packages/workflow/src/bundle/build-descriptor.ts
similarity index 92%
rename from packages/workflow/src/build-descriptor.ts
rename to packages/workflow/src/bundle/build-descriptor.ts
index a5171a5..3930b22 100644
--- a/packages/workflow/src/build-descriptor.ts
+++ b/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 {
diff --git a/packages/workflow/src/bundle-import-env.ts b/packages/workflow/src/bundle/bundle-import-env.ts
similarity index 100%
rename from packages/workflow/src/bundle-import-env.ts
rename to packages/workflow/src/bundle/bundle-import-env.ts
diff --git a/packages/workflow/src/bundle-validator.ts b/packages/workflow/src/bundle/bundle-validator.ts
similarity index 99%
rename from packages/workflow/src/bundle-validator.ts
rename to packages/workflow/src/bundle/bundle-validator.ts
index 9c7f982..6e11dc5 100644
--- a/packages/workflow/src/bundle-validator.ts
+++ b/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). */
diff --git a/packages/workflow/src/ensure-uncaged-workflow-symlink.ts b/packages/workflow/src/bundle/ensure-uncaged-workflow-symlink.ts
similarity index 88%
rename from packages/workflow/src/ensure-uncaged-workflow-symlink.ts
rename to packages/workflow/src/bundle/ensure-uncaged-workflow-symlink.ts
index 82aaf1c..247444b 100644
--- a/packages/workflow/src/ensure-uncaged-workflow-symlink.ts
+++ b/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));
 }
 
 /**
diff --git a/packages/workflow/src/extract-bundle-exports.ts b/packages/workflow/src/bundle/extract-bundle-exports.ts
similarity index 94%
rename from packages/workflow/src/extract-bundle-exports.ts
rename to packages/workflow/src/bundle/extract-bundle-exports.ts
index 1a0c987..35f0d66 100644
--- a/packages/workflow/src/extract-bundle-exports.ts
+++ b/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";
 
diff --git a/packages/workflow/src/generate-descriptor.ts b/packages/workflow/src/bundle/generate-descriptor.ts
similarity index 100%
rename from packages/workflow/src/generate-descriptor.ts
rename to packages/workflow/src/bundle/generate-descriptor.ts
diff --git a/packages/workflow/src/workflow-descriptor.ts b/packages/workflow/src/bundle/workflow-descriptor.ts
similarity index 97%
rename from packages/workflow/src/workflow-descriptor.ts
rename to packages/workflow/src/bundle/workflow-descriptor.ts
index 3676081..ca86ce9 100644
--- a/packages/workflow/src/workflow-descriptor.ts
+++ b/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>;
diff --git a/packages/workflow/src/cas.ts b/packages/workflow/src/cas/cas.ts
similarity index 100%
rename from packages/workflow/src/cas.ts
rename to packages/workflow/src/cas/cas.ts
diff --git a/packages/workflow/src/hash.ts b/packages/workflow/src/cas/hash.ts
similarity index 93%
rename from packages/workflow/src/hash.ts
rename to packages/workflow/src/cas/hash.ts
index 3f85984..e332e8e 100644
--- a/packages/workflow/src/hash.ts
+++ b/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");
diff --git a/packages/workflow/src/merkle.ts b/packages/workflow/src/cas/merkle.ts
similarity index 100%
rename from packages/workflow/src/merkle.ts
rename to packages/workflow/src/cas/merkle.ts
diff --git a/packages/workflow/src/create-workflow.ts b/packages/workflow/src/engine/create-workflow.ts
similarity index 93%
rename from packages/workflow/src/create-workflow.ts
rename to packages/workflow/src/engine/create-workflow.ts
index 8d0090e..19b72ea 100644
--- a/packages/workflow/src/create-workflow.ts
+++ b/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,
diff --git a/packages/workflow/src/engine.ts b/packages/workflow/src/engine/engine.ts
similarity index 97%
rename from packages/workflow/src/engine.ts
rename to packages/workflow/src/engine/engine.ts
index 9a5cd59..931da51 100644
--- a/packages/workflow/src/engine.ts
+++ b/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;
diff --git a/packages/workflow/src/fork-thread.ts b/packages/workflow/src/engine/fork-thread.ts
similarity index 97%
rename from packages/workflow/src/fork-thread.ts
rename to packages/workflow/src/engine/fork-thread.ts
index 8a6aa76..6ee82bd 100644
--- a/packages/workflow/src/fork-thread.ts
+++ b/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 };
diff --git a/packages/workflow/src/gc.ts b/packages/workflow/src/engine/gc.ts
similarity index 94%
rename from packages/workflow/src/gc.ts
rename to packages/workflow/src/engine/gc.ts
index ef444a3..36674b5 100644
--- a/packages/workflow/src/gc.ts
+++ b/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;
diff --git a/packages/workflow/src/thread-pause-gate.ts b/packages/workflow/src/engine/thread-pause-gate.ts
similarity index 95%
rename from packages/workflow/src/thread-pause-gate.ts
rename to packages/workflow/src/engine/thread-pause-gate.ts
index e2640c9..109d8b2 100644
--- a/packages/workflow/src/thread-pause-gate.ts
+++ b/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>;
diff --git a/packages/workflow/src/worker-entry-path.ts b/packages/workflow/src/engine/worker-entry-path.ts
similarity index 100%
rename from packages/workflow/src/worker-entry-path.ts
rename to packages/workflow/src/engine/worker-entry-path.ts
diff --git a/packages/workflow/src/worker.ts b/packages/workflow/src/engine/worker.ts
similarity index 96%
rename from packages/workflow/src/worker.ts
rename to packages/workflow/src/engine/worker.ts
index 0edbbde..ce62cb3 100644
--- a/packages/workflow/src/worker.ts
+++ b/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" } });
 
diff --git a/packages/workflow/src/extract-provider.ts b/packages/workflow/src/extract-provider.ts
index 45a82e0..61ec220 100644
--- a/packages/workflow/src/extract-provider.ts
+++ b/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;
 
diff --git a/packages/workflow/src/extract-fn.ts b/packages/workflow/src/extract/extract-fn.ts
similarity index 93%
rename from packages/workflow/src/extract-fn.ts
rename to packages/workflow/src/extract/extract-fn.ts
index bb0baf4..19931d7 100644
--- a/packages/workflow/src/extract-fn.ts
+++ b/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>,
diff --git a/packages/workflow/src/llm-extract.ts b/packages/workflow/src/extract/llm-extract.ts
similarity index 98%
rename from packages/workflow/src/llm-extract.ts
rename to packages/workflow/src/extract/llm-extract.ts
index 85f25c6..b1d90df 100644
--- a/packages/workflow/src/llm-extract.ts
+++ b/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;
diff --git a/packages/workflow/src/react-extract.ts b/packages/workflow/src/extract/react-extract.ts
similarity index 98%
rename from packages/workflow/src/react-extract.ts
rename to packages/workflow/src/extract/react-extract.ts
index 6c038a5..732907b 100644
--- a/packages/workflow/src/react-extract.ts
+++ b/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;
diff --git a/packages/workflow/src/index.ts b/packages/workflow/src/index.ts
index 7071f99..4dfbdbd 100644
--- a/packages/workflow/src/index.ts
+++ b/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";
diff --git a/packages/workflow/src/registry-normalize.ts b/packages/workflow/src/registry/registry-normalize.ts
similarity index 98%
rename from packages/workflow/src/registry-normalize.ts
rename to packages/workflow/src/registry/registry-normalize.ts
index 29a98e3..9dd0020 100644
--- a/packages/workflow/src/registry-normalize.ts
+++ b/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:")) {
diff --git a/packages/workflow/src/registry-types.ts b/packages/workflow/src/registry/registry-types.ts
similarity index 100%
rename from packages/workflow/src/registry-types.ts
rename to packages/workflow/src/registry/registry-types.ts
diff --git a/packages/workflow/src/registry.ts b/packages/workflow/src/registry/registry.ts
similarity index 98%
rename from packages/workflow/src/registry.ts
rename to packages/workflow/src/registry/registry.ts
index c81d7e3..1a9a593 100644
--- a/packages/workflow/src/registry.ts
+++ b/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,
diff --git a/packages/workflow/src/types.ts b/packages/workflow/src/types.ts
index faa5dfd..e68aa6f 100644
--- a/packages/workflow/src/types.ts
+++ b/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;
diff --git a/packages/workflow/src/base32.ts b/packages/workflow/src/util/base32.ts
similarity index 100%
rename from packages/workflow/src/base32.ts
rename to packages/workflow/src/util/base32.ts
diff --git a/packages/workflow/src/logger.ts b/packages/workflow/src/util/logger.ts
similarity index 100%
rename from packages/workflow/src/logger.ts
rename to packages/workflow/src/util/logger.ts
diff --git a/packages/workflow/src/refs-field.ts b/packages/workflow/src/util/refs-field.ts
similarity index 100%
rename from packages/workflow/src/refs-field.ts
rename to packages/workflow/src/util/refs-field.ts
diff --git a/packages/workflow/src/result.ts b/packages/workflow/src/util/result.ts
similarity index 100%
rename from packages/workflow/src/result.ts
rename to packages/workflow/src/util/result.ts
diff --git a/packages/workflow/src/storage-root.ts b/packages/workflow/src/util/storage-root.ts
similarity index 100%
rename from packages/workflow/src/storage-root.ts
rename to packages/workflow/src/util/storage-root.ts
diff --git a/packages/workflow/src/ulid.ts b/packages/workflow/src/util/ulid.ts
similarity index 100%
rename from packages/workflow/src/ulid.ts
rename to packages/workflow/src/util/ulid.ts
diff --git a/packages/workflow/src/workflow-as-agent.ts b/packages/workflow/src/workflow-as-agent.ts
index 223dd1f..8bce743 100644
--- a/packages/workflow/src/workflow-as-agent.ts
+++ b/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()`. */