refactor(workflow-runtime): flatten package layout and centralize types

Collapse bundle/cas/extract/util stubs into types.ts; move createWorkflow and Result helpers to src root.

Co-authored-by: Cursor <cursoragent@cursor.com>

packages/dashboard/src/app.tsx

@@ -5,10 +5,12 @@ import { StatusBar } from "./components/status-bar.tsx";
 import { ThreadDetail } from "./components/thread-detail.tsx";
 import { ThreadList } from "./components/thread-list.tsx";
 import { WorkflowList } from "./components/workflow-list.tsx";
-import { useHashRoute } from "./use-hash-route.ts";
+
+type View = "threads" | "workflows";
 
 export function App() {
-  const { view, threadId, setView, setThreadId } = useHashRoute();
+  const [view, setView] = useState<View>("threads");
+  const [selectedThread, setSelectedThread] = useState<string | null>(null);
   const [showRun, setShowRun] = useState(false);
 
   return (
@@ -17,9 +19,9 @@ export function App() {
       <main className="flex-1 overflow-hidden flex flex-col">
         <StatusBar onRun={() => setShowRun(true)} />
         <div className="flex-1 overflow-auto p-6">
-          {view === "threads" && threadId === null && <ThreadList onSelect={setThreadId} />}
-          {view === "threads" && threadId !== null && (
-            <ThreadDetail threadId={threadId} onBack={() => setThreadId(null)} />
+          {view === "threads" && !selectedThread && <ThreadList onSelect={setSelectedThread} />}
+          {view === "threads" && selectedThread && (
+            <ThreadDetail threadId={selectedThread} onBack={() => setSelectedThread(null)} />
           )}
           {view === "workflows" && <WorkflowList />}
         </div>
@@ -29,7 +31,8 @@ export function App() {
           onClose={() => setShowRun(false)}
           onCreated={(id) => {
             setShowRun(false);
-            setThreadId(id);
+            setView("threads");
+            setSelectedThread(id);
           }}
         />
       )}

packages/dashboard/src/components/status-bar.tsx

@@ -1,47 +1,12 @@
-import { useCallback, useEffect, useRef, useState } from "react";
 import { getHealth } from "../api.ts";
-
-type HealthStatus = "connected" | "disconnected" | "reconnecting";
+import { useFetch } from "../hooks.ts";
 
 type Props = {
   onRun: () => void;
 };
 
-function statusLabel(status: HealthStatus): { text: string; color: string } {
-  if (status === "connected") {
-    return { text: "● Connected", color: "var(--color-success)" };
-  }
-  if (status === "reconnecting") {
-    return { text: "● Reconnecting...", color: "var(--color-warning, #f59e0b)" };
-  }
-  return { text: "● Offline", color: "var(--color-error)" };
-}
-
 export function StatusBar({ onRun }: Props) {
-  const [status, setStatus] = useState<HealthStatus>("disconnected");
-  const wasConnectedRef = useRef(false);
-
-  const checkHealth = useCallback(async () => {
-    try {
-      await getHealth();
-      wasConnectedRef.current = true;
-      setStatus("connected");
-    } catch {
-      if (wasConnectedRef.current) {
-        setStatus("reconnecting");
-      } else {
-        setStatus("disconnected");
-      }
-    }
-  }, []);
-
-  useEffect(() => {
-    checkHealth();
-    const interval = setInterval(checkHealth, 10_000);
-    return () => clearInterval(interval);
-  }, [checkHealth]);
-
-  const label = statusLabel(status);
+  const health = useFetch(() => getHealth(), []);
 
   return (
     <div
@@ -59,7 +24,15 @@ export function StatusBar({ onRun }: Props) {
           ▶ Run Thread
         </button>
       </div>
-      <span style={{ color: label.color }}>{label.text}</span>
+      <span>
+        {health.status === "loading" && "⏳ Connecting..."}
+        {health.status === "ok" && (
+          <span style={{ color: "var(--color-success)" }}>● Connected</span>
+        )}
+        {health.status === "error" && (
+          <span style={{ color: "var(--color-error)" }}>● Offline</span>
+        )}
+      </span>
     </div>
   );
 }

packages/dashboard/src/components/thread-detail.tsx

@@ -1,7 +1,6 @@
-import { useEffect, useRef, useState } from "react";
+import { useState } from "react";
 import { getThread, killThread, pauseThread, resumeThread } from "../api.ts";
 import { useFetch } from "../hooks.ts";
-import { useSSE } from "../use-sse.ts";
 
 type Props = {
   threadId: string;
@@ -9,22 +8,8 @@ type Props = {
 };
 
 export function ThreadDetail({ threadId, onBack }: Props) {
-  const sse = useSSE(threadId);
   const { status, data, error } = useFetch(() => getThread(threadId), [threadId]);
   const [actionStatus, setActionStatus] = useState<string | null>(null);
-  const recordsEndRef = useRef<HTMLDivElement>(null);
-
-  const liveActive = sse.connected && !sse.completed;
-  const records = liveActive
-    ? sse.records
-    : status === "ok"
-      ? data.records
-      : ([] as typeof sse.records);
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: scroll when the rendered record list grows
-  useEffect(() => {
-    recordsEndRef.current?.scrollIntoView({ behavior: "smooth" });
-  }, [records.length]);
 
   async function handleAction(action: "kill" | "pause" | "resume") {
     setActionStatus(`${action}ing...`);
@@ -76,34 +61,20 @@ export function ThreadDetail({ threadId, onBack }: Props) {
         </div>
       </div>
 
-      <h2 className="text-xl font-semibold mb-2 font-mono flex items-center gap-2 flex-wrap">
-        <span>{threadId}</span>
-        {sse.connected && (
-          <span
-            className="text-xs font-medium px-2 py-0.5 rounded"
-            style={{ background: "var(--color-success)", color: "var(--color-bg)" }}
-          >
-            Live
-          </span>
-        )}
-      </h2>
+      <h2 className="text-xl font-semibold mb-2 font-mono">{threadId}</h2>
       {actionStatus && (
         <p className="text-xs mb-4" style={{ color: "var(--color-text-muted)" }}>
           {actionStatus}
         </p>
       )}
 
-      {status === "loading" && !liveActive && records.length === 0 && (
-        <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>
-      )}
-      {status === "error" && !liveActive && (
-        <p style={{ color: "var(--color-error)" }}>Error: {error}</p>
-      )}
-      {(status === "ok" || liveActive || records.length > 0) && (
+      {status === "loading" && <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>}
+      {status === "error" && <p style={{ color: "var(--color-error)" }}>Error: {error}</p>}
+      {status === "ok" && (
         <div className="space-y-3">
-          {records.map((r, i) => (
+          {data.records.map((r) => (
             <div
-              key={i}
+              key={`${r.type}:${r.role ?? ""}:${r.timestamp ?? 0}:${String(r.content ?? "")}`}
               className="p-3 rounded border text-sm"
               style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
             >
@@ -119,7 +90,7 @@ export function ThreadDetail({ threadId, onBack }: Props) {
                     {r.role}
                   </span>
                 )}
-                {r.timestamp !== null && (
+                {r.timestamp && (
                   <span className="text-xs ml-auto" style={{ color: "var(--color-text-muted)" }}>
                     {new Date(r.timestamp).toLocaleTimeString()}
                   </span>
@@ -135,7 +106,6 @@ export function ThreadDetail({ threadId, onBack }: Props) {
               )}
             </div>
           ))}
-          <div ref={recordsEndRef} aria-hidden />
         </div>
       )}
     </div>

packages/dashboard/src/use-hash-route.ts

@@ -1,64 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-
-type View = "threads" | "workflows";
-
-type HashRoute = {
-  view: View;
-  threadId: string | null;
-};
-
-function parseHash(hash: string): HashRoute {
-  const raw = hash.replace(/^#\/?/, "");
-  if (raw.startsWith("threads/")) {
-    const id = raw.slice("threads/".length);
-    if (id.length > 0) {
-      return { view: "threads", threadId: id };
-    }
-  }
-  if (raw === "workflows") {
-    return { view: "workflows", threadId: null };
-  }
-  return { view: "threads", threadId: null };
-}
-
-function buildHash(route: HashRoute): string {
-  if (route.view === "workflows") {
-    return "#workflows";
-  }
-  if (route.threadId !== null) {
-    return `#threads/${route.threadId}`;
-  }
-  return "#threads";
-}
-
-export function useHashRoute(): {
-  view: View;
-  threadId: string | null;
-  setView: (v: View) => void;
-  setThreadId: (id: string | null) => void;
-} {
-  const [route, setRoute] = useState<HashRoute>(() => parseHash(window.location.hash));
-
-  useEffect(() => {
-    function onHashChange(): void {
-      setRoute(parseHash(window.location.hash));
-    }
-    window.addEventListener("hashchange", onHashChange);
-    return () => window.removeEventListener("hashchange", onHashChange);
-  }, []);
-
-  const navigate = useCallback((next: HashRoute) => {
-    const hash = buildHash(next);
-    window.location.hash = hash;
-    setRoute(next);
-  }, []);
-
-  const setView = useCallback((v: View) => navigate({ view: v, threadId: null }), [navigate]);
-
-  const setThreadId = useCallback(
-    (id: string | null) => navigate({ view: "threads", threadId: id }),
-    [navigate],
-  );
-
-  return { view: route.view, threadId: route.threadId, setView, setThreadId };
-}

packages/dashboard/src/use-sse.ts

@@ -1,161 +0,0 @@
-import {
-  type Dispatch,
-  type MutableRefObject,
-  type SetStateAction,
-  useEffect,
-  useRef,
-  useState,
-} from "react";
-
-import type { ThreadRecord } from "./api.ts";
-
-export type UseSSEReturn = {
-  records: ThreadRecord[];
-  connected: boolean;
-  completed: boolean;
-};
-
-function isWorkflowResult(record: ThreadRecord): boolean {
-  return record.type === "workflow-result";
-}
-
-function parseRecord(data: string): ThreadRecord | null {
-  try {
-    return JSON.parse(data) as ThreadRecord;
-  } catch {
-    return null;
-  }
-}
-
-type RecordEventContext = {
-  cancelled: boolean;
-  completedRef: MutableRefObject<boolean>;
-  setRecords: Dispatch<SetStateAction<ThreadRecord[]>>;
-  setCompleted: (value: boolean) => void;
-  setConnected: (value: boolean) => void;
-  cleanupEs: () => void;
-};
-
-function handleRecordEvent(ev: Event, ctx: RecordEventContext): void {
-  if (ctx.cancelled) {
-    return;
-  }
-  const msg = ev as MessageEvent;
-  const raw = typeof msg.data === "string" ? msg.data : "";
-  const parsed = parseRecord(raw);
-  if (parsed === null) {
-    return;
-  }
-  ctx.setRecords((prev) => [...prev, parsed]);
-  if (!isWorkflowResult(parsed)) {
-    return;
-  }
-  ctx.completedRef.current = true;
-  ctx.setCompleted(true);
-  ctx.setConnected(false);
-  ctx.cleanupEs();
-}
-
-export function useSSE(threadId: string | null): UseSSEReturn {
-  const [records, setRecords] = useState<ThreadRecord[]>([]);
-  const [connected, setConnected] = useState(false);
-  const [completed, setCompleted] = useState(false);
-
-  const completedRef = useRef(false);
-  const reconnectAttemptsRef = useRef(0);
-
-  useEffect(() => {
-    if (threadId === null) {
-      completedRef.current = false;
-      reconnectAttemptsRef.current = 0;
-      setRecords([]);
-      setConnected(false);
-      setCompleted(false);
-      return;
-    }
-
-    const tid = threadId;
-
-    completedRef.current = false;
-    reconnectAttemptsRef.current = 0;
-    setRecords([]);
-    setConnected(false);
-    setCompleted(false);
-
-    let es: EventSource | null = null;
-    let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-    let cancelled = false;
-
-    function cleanupEs(): void {
-      if (es !== null) {
-        es.close();
-        es = null;
-      }
-    }
-
-    function scheduleReconnect(): void {
-      if (cancelled || completedRef.current) {
-        return;
-      }
-      const delayMs = Math.min(1000 * 2 ** reconnectAttemptsRef.current, 8000);
-      reconnectAttemptsRef.current += 1;
-      reconnectTimer = setTimeout(() => {
-        reconnectTimer = null;
-        if (!cancelled && !completedRef.current) {
-          connect();
-        }
-      }, delayMs);
-    }
-
-    function connect(): void {
-      if (cancelled || completedRef.current) {
-        return;
-      }
-
-      cleanupEs();
-      const url = `/api/threads/${encodeURIComponent(tid)}/live`;
-      es = new EventSource(url);
-
-      es.onopen = () => {
-        if (cancelled) {
-          return;
-        }
-        reconnectAttemptsRef.current = 0;
-        setConnected(true);
-        setRecords([]);
-      };
-
-      es.addEventListener("record", (ev: Event) =>
-        handleRecordEvent(ev, {
-          cancelled,
-          completedRef,
-          setRecords,
-          setCompleted,
-          setConnected,
-          cleanupEs,
-        }),
-      );
-
-      es.onerror = () => {
-        if (cancelled || completedRef.current) {
-          return;
-        }
-        setConnected(false);
-        cleanupEs();
-        scheduleReconnect();
-      };
-    }
-
-    connect();
-
-    return () => {
-      cancelled = true;
-      if (reconnectTimer !== null) {
-        clearTimeout(reconnectTimer);
-      }
-      cleanupEs();
-    };
-  }, [threadId]);
-
-  return { records, connected, completed };
-}

packages/workflow-runtime/src/bundle/index.ts

@@ -1,2 +0,0 @@
-export type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
-export { validateWorkflowDescriptor } from "./workflow-descriptor.js";

packages/workflow-runtime/src/bundle/types.ts

@@ -1,13 +0,0 @@
-/** 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>;
-};

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

@@ -1,40 +0,0 @@
-import { err, ok, type Result } from "../util/index.js";
-
-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)) {
-    return err("descriptor must be a non-array object");
-  }
-  const root = value as Record<string, unknown>;
-  const description = root.description;
-  if (typeof description !== "string") {
-    return err("descriptor.description must be a string");
-  }
-  const rolesRaw = root.roles;
-  if (rolesRaw === null || typeof rolesRaw !== "object" || Array.isArray(rolesRaw)) {
-    return err("descriptor.roles must be a non-array object");
-  }
-
-  const roles: Record<string, WorkflowRoleDescriptor> = {};
-  for (const [roleName, specUnknown] of Object.entries(rolesRaw)) {
-    if (specUnknown === null || typeof specUnknown !== "object" || Array.isArray(specUnknown)) {
-      return err(`descriptor.roles.${roleName} must be a non-array object`);
-    }
-    const spec = specUnknown as Record<string, unknown>;
-    const roleDesc = spec.description;
-    if (typeof roleDesc !== "string") {
-      return err(`descriptor.roles.${roleName}.description must be a string`);
-    }
-    const schema = spec.schema;
-    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
-      return err(`descriptor.roles.${roleName}.schema must be a non-array object`);
-    }
-    roles[roleName] = {
-      description: roleDesc,
-      schema: schema as WorkflowRoleSchema,
-    };
-  }
-
-  return ok({ description, roles });
-}

packages/workflow-runtime/src/cas/index.ts

@@ -1 +0,0 @@
-export type { CasStore } from "./types.js";

packages/workflow-runtime/src/cas/types.ts

@@ -1,6 +0,0 @@
-export type CasStore = {
-  put(content: string): Promise<string>;
-  get(hash: string): Promise<string | null>;
-  delete(hash: string): Promise<void>;
-  list(): Promise<string[]>;
-};

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

@@ -1,10 +1,10 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "../cas/types.js";
 import {
   type AgentBinding,
   type AgentContext,
   type AgentFn,
+  type CasStore,
   END,
   type ExtractContext,
   type ModeratorContext,
@@ -18,8 +18,7 @@ import {
   type WorkflowDefinition,
   type WorkflowFn,
   type WorkflowRuntime,
-} from "../types.js";
-import { mergeRefsWithContentHash } from "../util/index.js";
+} from "./types.js";
 
 function isRoleNext<M extends RoleMeta>(
   next: (keyof M & string) | typeof END,
@@ -97,10 +96,11 @@ async function advanceOneRound<M extends RoleMeta>(
   );
 
   const contentHash = await putContentBlob(runtime.cas, raw);
-  const refs = mergeRefsWithContentHash(
-    resolveExtractedRefs(roleDef as unknown as RoleDefinition<Record<string, unknown>>, meta),
-    contentHash,
+  const refsFromMeta = resolveExtractedRefs(
+    roleDef as unknown as RoleDefinition<Record<string, unknown>>,
+    meta,
   );
+  const refs = refsFromMeta.includes(contentHash) ? refsFromMeta : [...refsFromMeta, contentHash];
 
   const step = {
     role: next,

packages/workflow-runtime/src/engine/index.ts

@@ -1 +0,0 @@
-export { createWorkflow } from "./create-workflow.js";

packages/workflow-runtime/src/extract/index.ts

@@ -1 +0,0 @@
-export type { ExtractFn } from "./types.js";

packages/workflow-runtime/src/extract/types.ts

@@ -1,9 +0,0 @@
-import type * as z from "zod/v4";
-
-import type { ExtractContext } from "../types.js";
-
-export type ExtractFn = <T extends Record<string, unknown>>(
-  schema: z.ZodType<T>,
-  prompt: string,
-  ctx: ExtractContext,
-) => Promise<T>;

packages/workflow-runtime/src/index.ts

@@ -1,20 +1,16 @@
-export type {
-  WorkflowDescriptor,
-  WorkflowRoleDescriptor,
-  WorkflowRoleSchema,
-} from "./bundle/types.js";
-export { validateWorkflowDescriptor } from "./bundle/workflow-descriptor.js";
-export type { CasStore } from "./cas/index.js";
-export { createWorkflow } from "./engine/index.js";
-export type { ExtractFn } from "./extract/index.js";
+export { createWorkflow } from "./create-workflow.js";
+export { err, ok } from "./result.js";
 export type {
   AgentBinding,
   AgentContext,
   AgentFn,
+  CasStore,
   ExtractContext,
+  ExtractFn,
   LlmProvider,
   Moderator,
   ModeratorContext,
+  Result,
   RoleDefinition,
   RoleMeta,
   RoleOutput,
@@ -23,10 +19,11 @@ export type {
   ThreadContext,
   WorkflowCompletion,
   WorkflowDefinition,
+  WorkflowDescriptor,
   WorkflowFn,
   WorkflowResult,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
   WorkflowRuntime,
 } from "./types.js";
 export { END, START } from "./types.js";
-export type { Result } from "./util/index.js";
-export { err, ok } from "./util/index.js";

packages/workflow-runtime/src/types.ts

@@ -1,12 +1,33 @@
 import type * as z from "zod/v4";
 
-import type { CasStore } from "./cas/index.js";
-import type { ExtractFn } from "./extract/types.js";
-
 /** Sentinel values for automaton control flow. */
 export const START = "__start__" as const;
 export const END = "__end__" as const;
 
+export type CasStore = {
+  put(content: string): Promise<string>;
+  get(hash: string): Promise<string | null>;
+  delete(hash: string): Promise<void>;
+  list(): Promise<string[]>;
+};
+
+/** 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>;
+};
+
+/** Expected success/failure outcome without throwing for recoverable errors. */
+export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
 /** Maps role names → their meta types. Single generic drives all inference. */
 export type RoleMeta = Record<string, Record<string, unknown>>;
 
@@ -96,6 +117,12 @@ export type ExtractContext<M extends RoleMeta = RoleMeta> = AgentContext<M> & {
   agentContent: string;
 };
 
+export type ExtractFn = <T extends Record<string, unknown>>(
+  schema: z.ZodType<T>,
+  prompt: string,
+  ctx: ExtractContext,
+) => Promise<T>;
+
 /** Raw string output from an LLM/CLI adapter; meta is extracted by the engine. */
 export type AgentFn = (ctx: AgentContext) => Promise<string>;
 
@@ -131,3 +158,8 @@ export type WorkflowDefinition<M extends RoleMeta> = {
   roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
   moderator: Moderator<M>;
 };
+
+/** Internal outcome of advancing one moderator round inside {@link createWorkflow}. */
+export type AdvanceOutcome<M extends RoleMeta> =
+  | { kind: "complete"; completion: WorkflowCompletion }
+  | { kind: "yield"; output: RoleOutput; step: RoleStep<M> };

packages/workflow-runtime/src/util/index.ts

@@ -1,3 +0,0 @@
-export { mergeRefsWithContentHash } from "./refs-field.js";
-export { err, ok } from "./result.js";
-export type { Result } from "./types.js";

packages/workflow-runtime/src/util/refs-field.ts

@@ -1,8 +0,0 @@
-/** Append `contentHash` to `refs` when not already present (dedupe by first occurrence order). */
-export function mergeRefsWithContentHash(refs: string[], contentHash: string): string[] {
-  const out = [...refs];
-  if (!out.includes(contentHash)) {
-    out.push(contentHash);
-  }
-  return out;
-}

packages/workflow-runtime/src/util/types.ts

@@ -1 +0,0 @@
-export type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

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

@@ -1 +1,40 @@
-export { validateWorkflowDescriptor } from "@uncaged/workflow-runtime";
+import { err, ok, type Result } from "../util/index.js";
+
+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)) {
+    return err("descriptor must be a non-array object");
+  }
+  const root = value as Record<string, unknown>;
+  const description = root.description;
+  if (typeof description !== "string") {
+    return err("descriptor.description must be a string");
+  }
+  const rolesRaw = root.roles;
+  if (rolesRaw === null || typeof rolesRaw !== "object" || Array.isArray(rolesRaw)) {
+    return err("descriptor.roles must be a non-array object");
+  }
+
+  const roles: Record<string, WorkflowRoleDescriptor> = {};
+  for (const [roleName, specUnknown] of Object.entries(rolesRaw)) {
+    if (specUnknown === null || typeof specUnknown !== "object" || Array.isArray(specUnknown)) {
+      return err(`descriptor.roles.${roleName} must be a non-array object`);
+    }
+    const spec = specUnknown as Record<string, unknown>;
+    const roleDesc = spec.description;
+    if (typeof roleDesc !== "string") {
+      return err(`descriptor.roles.${roleName}.description must be a string`);
+    }
+    const schema = spec.schema;
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+      return err(`descriptor.roles.${roleName}.schema must be a non-array object`);
+    }
+    roles[roleName] = {
+      description: roleDesc,
+      schema: schema as WorkflowRoleSchema,
+    };
+  }
+
+  return ok({ description, roles });
+}