@smithers-orchestrator/graph 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.24.0"
+    "@smithers-orchestrator/errors": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/TaskAspects.ts

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

package/src/dom/extract.js

@@ -3,15 +3,16 @@
 /** @typedef {import("../HostText.ts").HostText} HostText */
 // @smithers-type-exports-end
 
-import { resolveStableId } from "@smithers-orchestrator/graph/utils/tree-ids";
+import { resolveStableId } from "../utils/tree-ids.js";
 import { getTableName } from "drizzle-orm";
-import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR, } from "@smithers-orchestrator/graph/constants";
+import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR, } from "../constants.js";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
-import { resolveWorktreePath } from "@smithers-orchestrator/graph/worktree-path";
+import { resolveWorktreePath } from "../worktree-path.js";
 
 /** @typedef {import("../ExtractOptions.ts").ExtractOptions} ExtractOptions */
 /** @typedef {import("../ExtractResult.ts").ExtractResult} ExtractResult */
 /** @typedef {import("../HostNode.ts").HostNode} HostNode */
+/** @typedef {import("../TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("../XmlNode.ts").XmlNode} XmlNode */
 
 // TODO(migration): Delegate extractFromHost to
@@ -48,13 +49,13 @@ const DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 const DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS = envHeartbeatTimeoutMs();
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is any}
  */
 function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
         return false;
     try {
-        const name = getTableName(value);
+        const name = getTableName(/** @type {any} */ (value));
         return typeof name === "string" && name.length > 0;
     }
     catch {
@@ -63,7 +64,7 @@ function isDrizzleTable(value) {
 }
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is import("zod").ZodObject<any>}
  */
 function isZodObject(value) {
     return Boolean(value && typeof value === "object" && "shape" in value);
@@ -83,6 +84,15 @@ function parseHeartbeatTimeoutMs(raw) {
     }
     return Math.floor(candidate);
 }
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+function recordOrEmpty(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? /** @type {Record<string, unknown>} */ (value)
+        : {};
+}
 /**
  * @param {HostNode} node
  * @returns {XmlNode}
@@ -92,7 +102,7 @@ function toXmlNode(node) {
         return { kind: "text", text: node.text };
     }
     const element = {
-        kind: "element",
+        kind: /** @type {"element"} */ ("element"),
         tag: node.tag,
         props: node.props ?? {},
         children: node.children.map(toXmlNode),
@@ -112,11 +122,13 @@ function getRalphIteration(opts, id) {
     if (map instanceof Map) {
         return map.get(id) ?? fallback;
     }
-    const value = map[id];
+    const value = /** @type {Record<string, number>} */ (map)[id];
     return typeof value === "number" ? value : fallback;
 }
 /**
  * @param {Record<string, unknown>} raw
+ * @param {boolean} [isAgent]
+ * @returns {{ retries: number; retryPolicy: import("../RetryPolicy.ts").RetryPolicy | undefined }}
  */
 function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
@@ -139,7 +151,7 @@ function resolveRetryConfig(raw, isAgent = false) {
     const retryPolicy = hasExplicitRetryPolicy
         ? /** @type {import("../RetryPolicy.ts").RetryPolicy} */ (raw.retryPolicy)
         : retries > 0
-            ? { backoff: "exponential", initialDelayMs: 1000 }
+            ? /** @type {import("../RetryPolicy.ts").RetryPolicy} */ ({ backoff: "exponential", initialDelayMs: 1000 })
             : undefined;
     return { retries, retryPolicy };
 }
@@ -152,7 +164,9 @@ export function extractFromHost(root, opts) {
     if (!root) {
         return { xml: null, tasks: [], mountedTaskIds: [] };
     }
+    /** @type {TaskDescriptor[]} */
     const tasks = [];
+    /** @type {string[]} */
     const mountedTaskIds = [];
     const seen = new Set();
     const seenRalph = new Set();
@@ -251,7 +265,10 @@ export function extractFromHost(root, opts) {
             if (!pathVal) {
                 throw new SmithersError("WORKTREE_EMPTY_PATH", WORKTREE_EMPTY_PATH_ERROR);
             }
-            const normPath = resolveWorktreePath(pathVal, { baseRootDir: opts?.baseRootDir });
+            const normPath = resolveWorktreePath(pathVal, {
+                baseRootDir: opts?.baseRootDir,
+                workflowPath: opts?.workflowPath,
+            });
             const branch = node.rawProps?.branch ? String(node.rawProps.branch) : undefined;
             const baseBranch = node.rawProps?.baseBranch ? String(node.rawProps.baseBranch) : undefined;
             nextWorktreeStack = [...worktreeStack, { id, path: normPath, branch, baseBranch }];
@@ -276,7 +293,7 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
@@ -285,7 +302,9 @@ export function extractFromHost(root, opts) {
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const dependsOn = Array.isArray(raw.dependsOn)
                 ? raw.dependsOn.filter((v) => typeof v === "string")
                 : undefined;
@@ -340,9 +359,9 @@ export function extractFromHost(root, opts) {
                         }
                         return result.output;
                     },
-                    label: raw.label,
+                    label: typeof raw.label === "string" ? raw.label : undefined,
                     meta: {
-                        ...raw.meta,
+                        ...recordOrEmpty(raw.meta),
                         __subflow: true,
                         __subflowMode: mode,
                         __subflowInput: raw.__smithersSubflowInput,
@@ -374,7 +393,7 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
@@ -383,7 +402,9 @@ export function extractFromHost(root, opts) {
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw) ?? DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS;
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const dependsOn = Array.isArray(raw.dependsOn)
                 ? raw.dependsOn.filter((v) => typeof v === "string")
                 : undefined;
@@ -468,9 +489,9 @@ export function extractFromHost(root, opts) {
                         },
                     });
                 },
-                label: raw.label,
+                label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __sandbox: true,
                     __sandboxRuntime: runtime,
                     __sandboxProvider: provider,
@@ -520,12 +541,12 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
             const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
-            const outputSchema = raw.outputSchema ?? outputRef;
+            const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
             const waitAsync = Boolean(raw.waitAsync);
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const heartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
@@ -564,9 +585,9 @@ export function extractFromHost(root, opts) {
                 prompt: undefined,
                 staticPayload: undefined,
                 computeFn: undefined,
-                label: raw.label,
+                label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __waitForEvent: true,
                     __eventName: raw.__smithersEventName ?? raw.event,
                     __correlationId: raw.__smithersCorrelationId ?? raw.correlationId,
@@ -646,9 +667,9 @@ export function extractFromHost(root, opts) {
                 prompt: undefined,
                 staticPayload: undefined,
                 computeFn: undefined,
-                label: raw.label ?? `timer:${nodeId}`,
+                label: typeof raw.label === "string" ? raw.label : `timer:${nodeId}`,
                 meta: {
-                    ...raw.meta,
+                    ...recordOrEmpty(raw.meta),
                     __timer: true,
                     __timerType: hasDuration ? "duration" : "absolute",
                     ...(hasDuration ? { __timerDuration: duration } : {}),
@@ -698,19 +719,21 @@ export function extractFromHost(root, opts) {
             }
             const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
             const outputTableName = outputTable
-                ? getTableName(outputTable)
+                ? getTableName(/** @type {any} */ (outputTable))
                 : typeof outputRaw === "string"
                     ? outputRaw
                     : "";
             const outputRef = !outputTable && isZodObject(outputRaw) ? outputRaw : undefined;
-            const outputSchema = raw.outputSchema ?? outputRef;
+            const outputSchema = isZodObject(raw.outputSchema) ? raw.outputSchema : outputRef;
             const needsApproval = Boolean(raw.needsApproval);
             const waitAsync = Boolean(raw.waitAsync);
+            /** @type {TaskDescriptor["approvalMode"]} */
             const approvalMode = raw.approvalMode === "decision" ||
                 raw.approvalMode === "select" ||
                 raw.approvalMode === "rank"
                 ? raw.approvalMode
                 : "gate";
+            /** @type {TaskDescriptor["approvalOnDeny"]} */
             const approvalOnDeny = raw.approvalOnDeny === "continue" ||
                 raw.approvalOnDeny === "skip" ||
                 raw.approvalOnDeny === "fail"
@@ -735,31 +758,36 @@ export function extractFromHost(root, opts) {
             const approvalAllowedUsers = Array.isArray(raw.approvalAllowedUsers)
                 ? raw.approvalAllowedUsers.filter((value) => typeof value === "string")
                 : undefined;
-            const approvalAutoApprove = raw.approvalAutoApprove && typeof raw.approvalAutoApprove === "object" && !Array.isArray(raw.approvalAutoApprove)
+            const approvalAutoApproveRaw = raw.approvalAutoApprove && typeof raw.approvalAutoApprove === "object" && !Array.isArray(raw.approvalAutoApprove)
+                ? /** @type {Record<string, unknown>} */ (raw.approvalAutoApprove)
+                : undefined;
+            const approvalAutoApprove = approvalAutoApproveRaw
                 ? {
-                    ...(typeof raw.approvalAutoApprove.after === "number"
-                        ? { after: raw.approvalAutoApprove.after }
+                    ...(typeof approvalAutoApproveRaw.after === "number"
+                        ? { after: approvalAutoApproveRaw.after }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.audit === "boolean"
-                        ? { audit: raw.approvalAutoApprove.audit }
+                    ...(typeof approvalAutoApproveRaw.audit === "boolean"
+                        ? { audit: approvalAutoApproveRaw.audit }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.conditionMet === "boolean"
-                        ? { conditionMet: raw.approvalAutoApprove.conditionMet }
+                    ...(typeof approvalAutoApproveRaw.conditionMet === "boolean"
+                        ? { conditionMet: approvalAutoApproveRaw.conditionMet }
                         : {}),
-                    ...(typeof raw.approvalAutoApprove.revertOnMet === "boolean"
-                        ? { revertOnMet: raw.approvalAutoApprove.revertOnMet }
+                    ...(typeof approvalAutoApproveRaw.revertOnMet === "boolean"
+                        ? { revertOnMet: approvalAutoApproveRaw.revertOnMet }
                         : {}),
                 }
                 : undefined;
             const skipIf = Boolean(raw.skipIf);
-            const agent = raw.agent;
+            const agent = /** @type {TaskDescriptor["agent"]} */ (raw.agent);
             const kind = raw.__smithersKind;
             const isAgent = kind === "agent" || Boolean(agent);
             const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
             const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : null;
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const continueOnFail = Boolean(raw.continueOnFail);
-            const cachePolicy = raw.cache && typeof raw.cache === "object" ? raw.cache : undefined;
+            const cachePolicy = raw.cache && typeof raw.cache === "object"
+                ? /** @type {import("../CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
+                : undefined;
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
                 (isAgent ? DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS : null);
             const prompt = isAgent ? String(raw.children ?? "") : undefined;
@@ -767,8 +795,8 @@ export function extractFromHost(root, opts) {
                 throw new SmithersError("MDX_PRELOAD_INACTIVE", `Task "${raw.id ?? nodeId}" prompt resolved to [object Object] — MDX preload is likely not active.\n` +
                     `Check that bunfig.toml has a top-level preload (not under [run]) and mdxPlugin() is registered.`);
             }
-            const isCompute = kind === "compute" && typeof raw.__smithersComputeFn === "function";
-            const computeFn = isCompute ? raw.__smithersComputeFn : undefined;
+            const isCompute = (kind === "compute" || kind === "human") && typeof raw.__smithersComputeFn === "function";
+            const computeFn = isCompute ? /** @type {() => unknown} */ (raw.__smithersComputeFn) : undefined;
             const staticPayload = isAgent || isCompute
                 ? undefined
                 : (raw.__smithersPayload ?? raw.__payload ?? raw.children);
@@ -811,17 +839,23 @@ export function extractFromHost(root, opts) {
                 continueOnFail,
                 cachePolicy,
                 hijack: Boolean(raw.hijack),
-                onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
+                onHijackExit: /** @type {"reopen" | "complete"} */ (raw.onHijackExit === "reopen" ? "reopen" : "complete"),
                 agent,
                 prompt,
                 staticPayload,
                 computeFn,
-                label: raw.label,
-                meta: raw.meta,
-                scorers: raw.scorers,
+                label: typeof raw.label === "string" ? raw.label : undefined,
+                meta: raw.meta && typeof raw.meta === "object" && !Array.isArray(raw.meta)
+                    ? /** @type {Record<string, unknown>} */ (raw.meta)
+                    : undefined,
+                scorers: raw.scorers && typeof raw.scorers === "object" && !Array.isArray(raw.scorers)
+                    ? /** @type {import("../ScorersMap.ts").ScorersMap} */ (raw.scorers)
+                    : undefined,
                 parallelGroupId: parallelGroup?.id,
                 parallelMaxConcurrency: parallelGroup?.max,
-                memoryConfig: raw.memory ?? undefined,
+                memoryConfig: raw.memory && typeof raw.memory === "object" && !Array.isArray(raw.memory)
+                    ? /** @type {TaskDescriptor["memoryConfig"]} */ (raw.memory)
+                    : undefined,
             };
             // Worktree path is captured in typed fields (worktreeId/worktreePath) and
             // consumed by the engine; avoid attaching untyped ad-hoc properties.

package/src/extract.js

@@ -2,14 +2,12 @@ import { getTableName } from "drizzle-orm";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { validateForkSources } from "./validateForkSources.js";
 import { resolveWorktreePath } from "./worktree-path.js";
+import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR } from "./constants.js";
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("./XmlNode.ts").XmlNode} XmlNode */
 /** @typedef {import("./ExtractOptions.ts").ExtractOptions} ExtractOptions */
 /** @typedef {import("./HostNode.ts").HostNode} HostNode */
 /** @typedef {import("./WorkflowGraph.ts").WorkflowGraph} WorkflowGraph */
-
-const DEFAULT_MERGE_QUEUE_CONCURRENCY = 1;
-const WORKTREE_EMPTY_PATH_ERROR = "<Worktree> requires a non-empty path prop";
 // Default per-task heartbeat timeout. 10 min is the floor for agent-backed
 // tasks: LLM CLIs (claude, codex, gemini, kimi) can sit silent for several
 // minutes during long deliberation or large-context reads. The previous
@@ -60,13 +58,13 @@ function isZodObject(value) {
 }
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is any}
  */
 function isDrizzleTable(value) {
     if (!value || typeof value !== "object")
         return false;
     try {
-        const name = getTableName(value);
+        const name = getTableName(/** @type {any} */ (value));
         return typeof name === "string" && name.length > 0;
     }
     catch {
@@ -89,7 +87,7 @@ function resolveOutput(raw) {
     }
     const outputTable = isDrizzleTable(outputRaw) ? outputRaw : null;
     const outputTableName = outputTable
-        ? getTableName(outputTable)
+        ? getTableName(/** @type {any} */ (outputTable))
         : typeof outputRaw === "string"
             ? outputRaw
             : "";
@@ -119,6 +117,8 @@ function parseHeartbeatTimeoutMs(raw) {
 }
 /**
  * @param {Record<string, unknown>} raw
+ * @param {boolean} [isAgent]
+ * @returns {{ retries: number; retryPolicy: import("./RetryPolicy.ts").RetryPolicy | undefined }}
  */
 function resolveRetryConfig(raw, isAgent = false) {
     const noRetry = Boolean(raw.noRetry);
@@ -135,12 +135,12 @@ function resolveRetryConfig(raw, isAgent = false) {
         : defaultNoRetryForContinueOnFail
             ? (isAgent ? 1 : 0)
             : hasExplicitRetries
-                ? raw.retries
+                ? /** @type {number} */ (raw.retries)
                 : Infinity;
     const retryPolicy = hasExplicitRetryPolicy
-        ? raw.retryPolicy
+        ? /** @type {import("./RetryPolicy.ts").RetryPolicy} */ (raw.retryPolicy)
         : retries > 0
-            ? { backoff: "exponential", initialDelayMs: 1000 }
+            ? /** @type {import("./RetryPolicy.ts").RetryPolicy} */ ({ backoff: "exponential", initialDelayMs: 1000 })
             : undefined;
     return { retries, retryPolicy };
 }
@@ -153,7 +153,7 @@ function toXmlNode(node) {
         return { kind: "text", text: node.text };
     }
     const element = {
-        kind: "element",
+        kind: /** @type {"element"} */ ("element"),
         tag: node.tag,
         props: node.props ?? {},
         children: node.children.map(toXmlNode),
@@ -173,7 +173,7 @@ function getRalphIteration(opts, id) {
     if (map instanceof Map) {
         return map.get(id) ?? fallback;
     }
-    const value = map[id];
+    const value = /** @type {Record<string, number>} */ (map)[id];
     return typeof value === "number" ? value : fallback;
 }
 /**
@@ -236,7 +236,7 @@ function approvalAutoApprove(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return undefined;
     }
-    const raw = value;
+    const raw = /** @type {Record<string, unknown>} */ (value);
     return {
         ...(typeof raw.after === "number" ? { after: raw.after } : {}),
         ...(typeof raw.audit === "boolean" ? { audit: raw.audit } : {}),
@@ -248,6 +248,49 @@ function approvalAutoApprove(value) {
             : {}),
     };
 }
+/**
+ * Normalize the `__aspects` element prop attached by `<Task>` into the
+ * `TaskAspects` budget metadata the engine enforces. Only the budget configs
+ * are kept; the render-time accumulator and tracking flags are dropped (the
+ * engine keeps its own durable per-run accumulator and budgets enforce
+ * regardless of tracking).
+ *
+ * @param {unknown} value
+ * @returns {import("./types").TaskAspects | undefined}
+ */
+function aspects(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const raw = /** @type {Record<string, unknown>} */ (value);
+    /** @type {import("./types").TaskAspects} */
+    const out = {};
+    const token = raw.tokenBudget;
+    if (token && typeof token === "object" && !Array.isArray(token) &&
+        typeof (/** @type {Record<string, unknown>} */ (token).max) === "number") {
+        const t = /** @type {Record<string, unknown>} */ (token);
+        out.tokenBudget = {
+            max: /** @type {number} */ (t.max),
+            ...(typeof t.perTask === "number" ? { perTask: t.perTask } : {}),
+            ...(t.onExceeded === "warn" || t.onExceeded === "skip-remaining" || t.onExceeded === "fail"
+                ? { onExceeded: /** @type {"fail" | "warn" | "skip-remaining"} */ (t.onExceeded) }
+                : {}),
+        };
+    }
+    const latency = raw.latencySlo;
+    if (latency && typeof latency === "object" && !Array.isArray(latency) &&
+        typeof (/** @type {Record<string, unknown>} */ (latency).maxMs) === "number") {
+        const l = /** @type {Record<string, unknown>} */ (latency);
+        out.latencySlo = {
+            maxMs: /** @type {number} */ (l.maxMs),
+            ...(typeof l.perTask === "number" ? { perTask: l.perTask } : {}),
+            ...(l.onExceeded === "warn" || l.onExceeded === "fail"
+                ? { onExceeded: /** @type {"fail" | "warn"} */ (l.onExceeded) }
+                : {}),
+        };
+    }
+    return out.tokenBudget || out.latencySlo ? out : undefined;
+}
 /**
  * @param {"parallel" | "merge-queue"} tag
  * @param {Record<string, unknown>} raw
@@ -300,7 +343,9 @@ export function extractGraph(root, opts) {
     if (!root) {
         return { xml: null, tasks: [], mountedTaskIds: [] };
     }
+    /** @type {TaskDescriptor[]} */
     const tasks = [];
+    /** @type {string[]} */
     const mountedTaskIds = [];
     const seen = new Set();
     const seenRalph = new Set();
@@ -408,7 +453,7 @@ export function extractGraph(root, opts) {
                     heartbeatTimeoutMs: parseHeartbeatTimeoutMs(raw),
                     continueOnFail: Boolean(raw.continueOnFail),
                     cachePolicy: raw.cache && typeof raw.cache === "object"
-                        ? raw.cache
+                        ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                         : undefined,
                     label: typeof raw.label === "string" ? raw.label : undefined,
                     meta: {
@@ -441,7 +486,7 @@ export function extractGraph(root, opts) {
                 heartbeatTimeoutMs: parseHeartbeatTimeoutMs(raw) ?? DEFAULT_SANDBOX_TASK_HEARTBEAT_TIMEOUT_MS,
                 continueOnFail: Boolean(raw.continueOnFail),
                 cachePolicy: raw.cache && typeof raw.cache === "object"
-                    ? raw.cache
+                    ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                     : undefined,
                 label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: {
@@ -579,7 +624,7 @@ export function extractGraph(root, opts) {
             const kind = raw.__smithersKind;
             const isAgent = kind === "agent" || Boolean(raw.agent);
             const { retries, retryPolicy } = resolveRetryConfig(raw, isAgent);
-            const isCompute = kind === "compute" && typeof raw.__smithersComputeFn === "function";
+            const isCompute = (kind === "compute" || kind === "human") && typeof raw.__smithersComputeFn === "function";
             const parsedHeartbeatTimeoutMs = parseHeartbeatTimeoutMs(raw);
             const heartbeatTimeoutMs = parsedHeartbeatTimeoutMs ??
                 (isAgent ? DEFAULT_LOCAL_TASK_HEARTBEAT_TIMEOUT_MS : null);
@@ -606,28 +651,31 @@ export function extractGraph(root, opts) {
                 heartbeatTimeoutMs,
                 continueOnFail: Boolean(raw.continueOnFail),
                 cachePolicy: raw.cache && typeof raw.cache === "object"
-                    ? raw.cache
+                    ? /** @type {import("./CachePolicy.ts").CachePolicy<unknown>} */ (raw.cache)
                     : undefined,
                 hijack: Boolean(raw.hijack),
                 onHijackExit: raw.onHijackExit === "reopen" ? "reopen" : "complete",
-                agent: raw.agent,
+                agent: /** @type {TaskDescriptor["agent"]} */ (raw.agent),
                 prompt,
                 staticPayload: isAgent || isCompute
                     ? undefined
                     : (raw.__smithersPayload ?? raw.__payload ?? raw.children),
                 computeFn: isCompute
-                    ? raw.__smithersComputeFn
+                    ? /** @type {() => unknown} */ (raw.__smithersComputeFn)
                     : undefined,
                 label: typeof raw.label === "string" ? raw.label : undefined,
                 meta: raw.meta && typeof raw.meta === "object" && !Array.isArray(raw.meta)
-                    ? raw.meta
+                    ? /** @type {Record<string, unknown>} */ (raw.meta)
                     : undefined,
                 scorers: raw.scorers && typeof raw.scorers === "object" && !Array.isArray(raw.scorers)
-                    ? raw.scorers
+                    ? /** @type {import("./ScorersMap.ts").ScorersMap} */ (raw.scorers)
                     : undefined,
+                groundTruth: raw.groundTruth,
+                context: raw.context,
                 memoryConfig: raw.memory && typeof raw.memory === "object" && !Array.isArray(raw.memory)
                     ? raw.memory
                     : undefined,
+                aspects: aspects(raw.__aspects),
             });
         }
         let elementIndex = 0;

package/src/index.d.ts

@@ -109,6 +109,18 @@ type ApprovalOption$1 = {
     summary?: string;
     metadata?: Record<string, unknown>;
 };
+type TaskAspects$1 = {
+    tokenBudget?: {
+        max: number;
+        perTask?: number;
+        onExceeded?: "fail" | "warn" | "skip-remaining";
+    };
+    latencySlo?: {
+        maxMs: number;
+        perTask?: number;
+        onExceeded?: "fail" | "warn";
+    };
+};
 type TaskDescriptor$1 = {
     nodeId: string;
     ordinal: number;
@@ -116,6 +128,8 @@ type TaskDescriptor$1 = {
     ralphId?: string;
     dependsOn?: string[];
     needs?: Record<string, string>;
+    /** Logical id of the task whose final agent session this task forks. Gates execution and seeds the session. */
+    forkSource?: string;
     worktreeId?: string;
     worktreePath?: string;
     worktreeBranch?: string;
@@ -155,7 +169,10 @@ type TaskDescriptor$1 = {
     label?: string;
     meta?: Record<string, unknown>;
     scorers?: ScorersMap$1;
+    groundTruth?: unknown;
+    context?: unknown;
     memoryConfig?: TaskMemoryConfig$1;
+    aspects?: TaskAspects$1;
 };
 type WorkflowGraph$2 = {
     readonly xml: XmlNode$1 | null;
@@ -191,13 +208,18 @@ declare function extractGraph(root: HostNode$1 | null, opts?: ExtractOptions$1):
 declare function extractFromHost(root: HostNode$1 | null, opts?: ExtractOptions$1): WorkflowGraph$1;
 /**
  * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ * Relative paths are resolved against the launch root (`--root`, the nearest
+ * `.smithers` anchor, or the operator cwd), never `dirname(workflowPath)`.
+ * `workflowPath` is threaded through graph/engine rendering for workflow
+ * identity and diagnostics only; it is not a worktree path resolution base.
  *
  * @param {unknown} path
- * @param {{ baseRootDir?: string }} [opts]
+ * @param {{ baseRootDir?: string; workflowPath?: string | null }} [opts]
  * @returns {string}
  */
 declare function resolveWorktreePath(path: unknown, opts?: {
     baseRootDir?: string;
+    workflowPath?: string | null;
 }): string;
 type ExtractOptions$1 = ExtractOptions$2;
 type HostNode$1 = HostNode$2;
@@ -222,6 +244,7 @@ type ScorerBinding = ScorerBinding$1;
 type ScorerFn = ScorerFn$1;
 type ScorerInput = ScorerInput$1;
 type ScorersMap = ScorersMap$1;
+type TaskAspects = TaskAspects$1;
 type TaskDescriptor = TaskDescriptor$1;
 type TaskMemoryConfig = TaskMemoryConfig$1;
 type WorkflowGraph = WorkflowGraph$2;
@@ -229,4 +252,4 @@ type XmlElement = XmlElement$1;
 type XmlNode = XmlNode$1;
 type XmlText = XmlText$1;
 
-export { type AgentLike, type ApprovalOption, type CachePolicy, type ExtractGraph, type ExtractOptions, type GraphSnapshot, type HostElement, type HostNode, type HostText, type MemoryNamespace, type MemoryNamespaceKind, type RetryPolicy, type SamplingConfig, type ScoreResult, type Scorer, type ScorerBinding, type ScorerFn, type ScorerInput, type ScorersMap, type TaskDescriptor, type TaskMemoryConfig, type WorkflowGraph, type XmlElement, type XmlNode, type XmlText, extractFromHost, extractGraph, resolveWorktreePath };
+export { type AgentLike, type ApprovalOption, type CachePolicy, type ExtractGraph, type ExtractOptions, type GraphSnapshot, type HostElement, type HostNode, type HostText, type MemoryNamespace, type MemoryNamespaceKind, type RetryPolicy, type SamplingConfig, type ScoreResult, type Scorer, type ScorerBinding, type ScorerFn, type ScorerInput, type ScorersMap, type TaskAspects, type TaskDescriptor, type TaskMemoryConfig, type WorkflowGraph, type XmlElement, type XmlNode, type XmlText, extractFromHost, extractGraph, resolveWorktreePath };

package/src/index.js

@@ -22,6 +22,7 @@
 /** @typedef {import("./ScorerInput.ts").ScorerInput} ScorerInput */
 /** @typedef {import("./ScorersMap.ts").ScorersMap} ScorersMap */
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
+/** @typedef {import("./TaskAspects.ts").TaskAspects} TaskAspects */
 /** @typedef {import("./TaskMemoryConfig.ts").TaskMemoryConfig} TaskMemoryConfig */
 /** @typedef {import("./WorkflowGraph.ts").WorkflowGraph} WorkflowGraph */
 /** @typedef {import("./XmlElement.ts").XmlElement} XmlElement */

package/src/types.ts

@@ -123,6 +123,26 @@ export type ApprovalOption = {
   metadata?: Record<string, unknown>;
 };
 
+/**
+ * Resolved `<Aspects>` budget configuration that applies to a task, extracted
+ * from the `__aspects` element prop. The engine reads this at task-dispatch
+ * time to enforce per-run token and latency budgets. The render-time
+ * accumulator carried alongside the budgets in the component tree is dropped
+ * here; the engine keeps its own durable accumulator.
+ */
+export type TaskAspects = {
+  tokenBudget?: {
+    max: number;
+    perTask?: number;
+    onExceeded?: "fail" | "warn" | "skip-remaining";
+  };
+  latencySlo?: {
+    maxMs: number;
+    perTask?: number;
+    onExceeded?: "fail" | "warn";
+  };
+};
+
 export type TaskDescriptor = {
   nodeId: string;
   ordinal: number;
@@ -171,8 +191,12 @@ export type TaskDescriptor = {
   label?: string;
   meta?: Record<string, unknown>;
   scorers?: ScorersMap;
+  groundTruth?: unknown;
+  context?: unknown;
 
   memoryConfig?: TaskMemoryConfig;
+  /** Resolved `<Aspects>` budget configuration enforced by the engine at dispatch. */
+  aspects?: TaskAspects;
 };
 
 export type WorkflowGraph = {

package/src/validateForkSources.js

@@ -44,6 +44,10 @@ export function validateForkSources(tasks) {
     // fork edge. Used only for cycle detection.
     /** @type {Map<string, Set<string>>} */
     const adjacency = new Map();
+    /**
+     * @param {string} from
+     * @param {string} to
+     */
     const addEdge = (from, to) => {
         const cleanedFrom = logicalId(from);
         const cleanedTo = logicalId(to);

package/src/worktree-path.js

@@ -1,12 +1,16 @@
-import { isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { WORKTREE_EMPTY_PATH_ERROR } from "./constants.js";
 
 /**
  * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ * Relative paths are resolved against the launch root (`--root`, the nearest
+ * `.smithers` anchor, or the operator cwd), never `dirname(workflowPath)`.
+ * `workflowPath` is threaded through graph/engine rendering for workflow
+ * identity and diagnostics only; it is not a worktree path resolution base.
  *
  * @param {unknown} path
- * @param {{ baseRootDir?: string }} [opts]
+ * @param {{ baseRootDir?: string; workflowPath?: string | null }} [opts]
  * @returns {string}
  */
 export function resolveWorktreePath(path, opts) {
@@ -20,5 +24,43 @@ export function resolveWorktreePath(path, opts) {
     const base = typeof opts?.baseRootDir === "string" && opts.baseRootDir.length > 0
         ? opts.baseRootDir
         : process.cwd();
-    return resolve(base, pathVal);
+    const resolvedPath = resolve(base, pathVal);
+    warnRelativeWorktreePathOnce(pathVal, base, resolvedPath, opts?.workflowPath);
+    return resolvedPath;
+}
+
+let didWarnRelativeWorktreePath = false;
+
+/**
+ * Reset process-local relative worktree warning state for deterministic tests.
+ *
+ * @returns {void}
+ */
+export function resetRelativeWorktreePathWarningForTest() {
+    didWarnRelativeWorktreePath = false;
+}
+
+/**
+ * @param {string} pathVal
+ * @param {string} base
+ * @param {string} resolvedPath
+ * @param {string | null | undefined} workflowPath
+ * @returns {void}
+ */
+function warnRelativeWorktreePathOnce(pathVal, base, resolvedPath, workflowPath) {
+    if (didWarnRelativeWorktreePath) {
+        return;
+    }
+    didWarnRelativeWorktreePath = true;
+    const workflowDir = typeof workflowPath === "string" && workflowPath.length > 0
+        ? dirname(workflowPath)
+        : undefined;
+    console.warn("relative <Worktree path> resolved against launch root, not the workflow file directory", {
+        code: "WORKTREE_RELATIVE_PATH_BASE_ROOT",
+        path: pathVal,
+        base,
+        resolvedPath,
+        workflowPath,
+        workflowDir,
+    });
 }