refactor: organize workflow/src into 6 module folders

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

Refs #102

packages/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 { createCasStore, createThreadCas } from "../src/cas/cas.js";
-import { hashString } from "../src/hash.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 { createCasStore } from "../src/cas/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 {
   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 { hashWorkflowBundleBytes } from "../src/cas/hash.js";
-import { decodeCrockfordToUint64 } from "../src/base32.js";
+import { decodeCrockfordToUint64 } from "../src/util/base32.js";
-import { hashWorkflowBundleBytes } from "../src/hash.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 { createCasStore } from "../src/cas/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
-import { reactExtract } from "../src/react-extract.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 { createCasStore } from "../src/cas/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
-import { executeThread } from "../src/engine.js";
+import { executeThread } from "../src/engine/engine.js";
-import { createExtract } from "../src/extract-fn.js";
+import { buildForkPlan, parseThreadDataJsonl } from "../src/engine/fork-thread.js";
-import { buildForkPlan, parseThreadDataJsonl } from "../src/fork-thread.js";
+import { createExtract } from "../src/extract/extract-fn.js";
-import { createLogger } from "../src/logger.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 { decodeCrockfordBase32Bits } from "../src/util/base32.js";
-import { generateUlid } from "../src/ulid.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 { createCasStore } from "../src/cas/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
-import { getWorkerHostScriptPath } from "../src/worker-entry-path.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 { createCasStore } from "../src/cas/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
-import { executeThread } from "../src/engine.js";
+import { getContentMerklePayload, parseMerkleNode } from "../src/cas/merkle.js";
-import { createExtract } from "../src/extract-fn.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
+import { executeThread } from "../src/engine/engine.js";
-import { createLogger } from "../src/logger.js";
+import { createExtract } from "../src/extract/extract-fn.js";
-import { getContentMerklePayload, parseMerkleNode } from "../src/merkle.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 { createCasStore } from "../src/cas/cas.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
-import { parseMerkleNode } from "../src/merkle.js";
+import { parseMerkleNode } from "../src/cas/merkle.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 import { type AgentContext, START } from "../src/types.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 

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

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

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

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

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

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

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

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

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

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

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

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

packages/workflow/src/cas/hash.ts

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

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

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

packages/workflow/src/engine/engine.ts

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

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

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

packages/workflow/src/engine/gc.ts

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

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

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

packages/workflow/src/engine/worker.ts

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

packages/workflow/src/extract-provider.ts

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

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

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

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

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

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

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

packages/workflow/src/index.ts

@@ -1,48 +1,21 @@
+export { buildDescriptor } from "./bundle/build-descriptor.js";
 export {
-  CROCKFORD_BASE32_ALPHABET,
+  validateWorkflowBundle,
-  decodeCrockfordBase32Bits,
+  type WorkflowBundleValidationInput,
-  decodeCrockfordToUint64,
+} from "./bundle/bundle-validator.js";
-  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 ExtractedBundleExports,
-  type ExecuteThreadOptions,
+  extractBundleExports,
-  executeThread,
+} from "./bundle/extract-bundle-exports.js";
-  type PrefilledDiskStep,
+export { stringifyWorkflowDescriptor } from "./bundle/generate-descriptor.js";
-} 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,
+  validateWorkflowDescriptor,
-  type ForkHistoricalStep,
+  type WorkflowDescriptor,
-  type ForkPlan,
+  type WorkflowRoleDescriptor,
-  type ParsedThreadStartRecord,
+  type WorkflowRoleSchema,
-  parseThreadDataJsonl,
+} from "./bundle/workflow-descriptor.js";
-  selectForkHistoricalSteps,
+export { type CasStore, createCasStore, createThreadCas } from "./cas/cas.js";
-  tryParseRoleStepRecord,
+export { hashString, hashWorkflowBundleBytes } from "./cas/hash.js";
-  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";
 export {
   createContentMerkleNode,
   getContentMerklePayload,
@@ -55,8 +28,36 @@ export {
   type StepMerklePayload,
   serializeMerkleNode,
   type ThreadMerklePayload,
-} from "./merkle.js";
+} from "./cas/merkle.js";
-export { type ReactExtractArgs, reactExtract } from "./react-extract.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";
+} from "./registry/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";
 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,
+  CROCKFORD_BASE32_ALPHABET,
-  type WorkflowDescriptor,
+  decodeCrockfordBase32Bits,
-  type WorkflowRoleDescriptor,
+  decodeCrockfordToUint64,
-  type WorkflowRoleSchema,
+  encodeCrockfordBase32Bits,
-} from "./workflow-descriptor.js";
+  encodeUint64AsCrockford,
+} from "./util/base32.js";
+export {
+  type CreateLoggerOptions,
+  createLogger,
+  type LogFn,
+  type LoggerSink,
+} from "./util/logger.js";
+export { err, ok, type Result } from "./util/result.js";
+export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./util/storage-root.js";
+export { generateUlid } from "./util/ulid.js";
+export { type WorkflowAsAgentOptions, workflowAsAgent } from "./workflow-as-agent.js";

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

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

packages/workflow/src/registry/registry.ts

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

packages/workflow/src/types.ts

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

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

@@ -1,14 +1,14 @@
 import { join } from "node:path";
 
-import { createCasStore } from "./cas.js";
+import { extractBundleExports } from "./bundle/extract-bundle-exports.js";
-import { type ExecuteThreadIo, executeThread } from "./engine.js";
+import { createCasStore } from "./cas/cas.js";
-import { extractBundleExports } from "./extract-bundle-exports.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/registry.js";
-import { getRegisteredWorkflow, readWorkflowRegistry } from "./registry.js";
-import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.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()`. */