@mastra/factory 0.13.0-alpha.9 → 0.13.0

package/dist/routes/work-items.js

@@ -1,11 +1,10 @@
-import { isFactoryRuleStage } from "../rules/types.js";
 import { createBoardRegistry } from "../boards/registry.js";
 import "../boards/index.js";
 import { FACTORY_PULL_REQUEST_RECONCILIATION_KEY, FACTORY_RULE_MATERIALIZATION_KEY, WorkItemRelationError, WorkItemUpdateConflictError } from "../storage/domains/work-items/base.js";
+import { FACTORY_ROUTE_CONTRACTS } from "./contracts.js";
 import { Route } from "./route.js";
 import { factoryDispatchFailureMetadata } from "../rules/dispatch-errors.js";
 import { FactoryStartTransitionError } from "../rules/start-coordinator.js";
-import { roleForStage } from "../rules/transition-service.js";
 import { thresholdsOrDefault } from "../storage/domains/queue-health/base.js";
 import { computeFactoryMetrics, parseMetricsRange } from "../storage/domains/work-items/metrics.js";
 import { factoryDecisionType } from "./attention-providers.js";
@@ -21,133 +20,29 @@ function toWireWorkItem(item) {
 		metadata: publicWorkItemMetadata(item.metadata) ?? {}
 	};
 }
-/** Session ids of the listed cards whose agent run is in flight. */
-function runningSessionIds(items, liveSessions) {
-	const running = /* @__PURE__ */ new Set();
-	for (const item of items) for (const { sessionId } of Object.values(item.sessions)) if (liveSessions.isRunning(sessionId)) running.add(sessionId);
-	return [...running];
+/** Session ids of the listed cards that the predicate picks, each once. */
+function sessionIdsWhere(items, predicate) {
+	const picked = /* @__PURE__ */ new Set();
+	for (const item of items) for (const { sessionId } of Object.values(item.sessions)) if (predicate(sessionId)) picked.add(sessionId);
+	return [...picked];
 }
 function loose(c) {
 	return c;
 }
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const MAX_STAGES = 16;
-const MAX_STAGE_LENGTH = 64;
-const MAX_METADATA_BYTES = 16 * 1024;
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function validStages(value) {
-	return Array.isArray(value) && value.length > 0 && value.length <= MAX_STAGES && value.every((stage) => typeof stage === "string" && stage.length <= MAX_STAGE_LENGTH && /^[a-z0-9][a-z0-9_-]*$/i.test(stage)) && new Set(value).size === value.length;
-}
-function validMetadata(value) {
-	if (value === null) return true;
-	if (!isRecord(value)) return false;
-	try {
-		return JSON.stringify(value).length <= MAX_METADATA_BYTES;
-	} catch {
-		return false;
-	}
-}
 function publicWorkItemMetadata(value) {
 	if (value === null) return null;
 	const { [FACTORY_RULE_MATERIALIZATION_KEY]: _materialization, [FACTORY_PULL_REQUEST_RECONCILIATION_KEY]: _reconciliation, ...metadata } = value;
 	return metadata;
 }
-function parseExternalSource(value) {
-	if (value === void 0 || value === null) return value;
-	if (!isRecord(value)) return void 0;
-	const { integrationId, type, externalId, url } = value;
-	if (typeof integrationId !== "string" || integrationId.length === 0 || integrationId.length > 128) return void 0;
-	if (typeof type !== "string" || type.length === 0 || type.length > 128) return void 0;
-	if (typeof externalId !== "string" || externalId.length === 0 || externalId.length > 512) return void 0;
-	if (url !== void 0 && (typeof url !== "string" || url.length > 2048)) return void 0;
-	return {
-		integrationId,
-		type,
-		externalId,
-		...url !== void 0 ? { url } : {}
-	};
-}
-function parseParentWorkItemId(value) {
-	if (value === null) return null;
-	if (typeof value !== "string" || !UUID_RE.test(value)) return void 0;
-	return value;
-}
-function parseSessions(value) {
-	if (!isRecord(value)) return void 0;
-	const out = {};
-	for (const [role, session] of Object.entries(value)) {
-		if (!role || role.length > 64 || !isRecord(session)) return void 0;
-		const { sessionId, branch, threadId } = session;
-		if (typeof sessionId !== "string" || sessionId.length === 0 || sessionId.length > 512) return void 0;
-		if (typeof branch !== "string" || branch.length === 0 || branch.length > 512) return void 0;
-		if (typeof threadId !== "string" || threadId.length === 0 || threadId.length > 512) return void 0;
-		out[role] = {
-			sessionId,
-			branch,
-			threadId
-		};
-	}
-	return out;
-}
 /** Validate an untrusted create body. Unknown keys are dropped. */
 function parseCreateWorkItem(body) {
-	if (!isRecord(body)) return null;
-	const { board, externalSource, title, stages, sessions, metadata } = body;
-	if (typeof title !== "string" || title.trim().length === 0 || title.length > 500) return null;
-	if (board !== void 0 && (typeof board !== "string" || board.length === 0 || board.length > 128)) return null;
-	const hasParentWorkItemId = "parentWorkItemId" in body;
-	const parentWorkItemId = hasParentWorkItemId ? parseParentWorkItemId(body.parentWorkItemId) : void 0;
-	if (hasParentWorkItemId && parentWorkItemId === void 0) return null;
-	const parsedSource = parseExternalSource(externalSource);
-	if (externalSource !== void 0 && parsedSource === void 0) return null;
-	if (stages !== void 0 && !validStages(stages)) return null;
-	const parsedSessions = sessions === void 0 ? void 0 : parseSessions(sessions);
-	if (sessions !== void 0 && parsedSessions === void 0) return null;
-	let parsedMetadata;
-	if (metadata !== void 0) {
-		if (!validMetadata(metadata)) return null;
-		parsedMetadata = publicWorkItemMetadata(metadata);
-	}
-	return {
-		title: title.trim(),
-		...board !== void 0 ? { board } : {},
-		...parsedSource !== void 0 ? { externalSource: parsedSource } : {},
-		...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
-		...stages !== void 0 ? { stages } : {},
-		...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
-		...parsedMetadata !== void 0 ? { metadata: parsedMetadata } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemCreate.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 /** Validate an untrusted patch body. Unknown keys are dropped. */
 function parseUpdateWorkItem(body) {
-	if (!isRecord(body)) return null;
-	const { board, title, stages, sessions, metadata, plansPreapproved } = body;
-	const hasParentWorkItemId = "parentWorkItemId" in body;
-	if (board === void 0 && title === void 0 && stages === void 0 && sessions === void 0 && metadata === void 0 && plansPreapproved === void 0 && !hasParentWorkItemId) return null;
-	if (board !== void 0 && (typeof board !== "string" || board.length === 0 || board.length > 128)) return null;
-	if (plansPreapproved !== void 0 && plansPreapproved !== true) return null;
-	const parentWorkItemId = hasParentWorkItemId ? parseParentWorkItemId(body.parentWorkItemId) : void 0;
-	if (hasParentWorkItemId && parentWorkItemId === void 0) return null;
-	if (title !== void 0 && (typeof title !== "string" || title.trim().length === 0 || title.length > 500)) return null;
-	if (stages !== void 0 && !validStages(stages)) return null;
-	const parsedSessions = sessions === void 0 ? void 0 : parseSessions(sessions);
-	if (sessions !== void 0 && parsedSessions === void 0) return null;
-	let parsedMetadata;
-	if (metadata !== void 0) {
-		if (!validMetadata(metadata)) return null;
-		parsedMetadata = publicWorkItemMetadata(metadata);
-	}
-	return {
-		...board !== void 0 ? { board } : {},
-		...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
-		...title !== void 0 ? { title: title.trim() } : {},
-		...stages !== void 0 ? { stages } : {},
-		...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
-		...parsedMetadata !== void 0 ? { metadata: parsedMetadata } : {},
-		...plansPreapproved === true ? { plansPreapproved: true } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemUpdate.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 async function readJson(c) {
 	try {
@@ -160,100 +55,28 @@ async function readJson(c) {
 function patchedFields(patch) {
 	return Object.keys(patch).filter((key) => patch[key] !== void 0);
 }
-function boundedText(value, max) {
-	if (typeof value !== "string") return void 0;
-	const normalized = value.trim();
-	return normalized.length > 0 && normalized.length <= max ? normalized : void 0;
-}
 function parseTransitionBody(body) {
-	if (!isRecord(body)) return null;
-	const board = typeof body.board === "string" && body.board.length > 0 ? body.board : void 0;
-	const stage = typeof body.stage === "string" && body.stage.length > 0 ? body.stage : void 0;
-	const requestId = boundedText(body.requestId, 256);
-	const cause = boundedText(body.cause, 256);
-	if (!board || !stage || !requestId || !UUID_RE.test(requestId) || !cause || !Number.isInteger(body.expectedRevision) || Number(body.expectedRevision) < 1) return null;
-	return {
-		board,
-		stage,
-		expectedRevision: Number(body.expectedRevision),
-		ingress: {
-			type: "human",
-			identity: requestId
-		},
-		cause,
-		...body.reenter === true ? { reenter: true } : {}
-	};
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemTransition.bodySchema.safeParse(body);
+	return parsed.success ? parsed.data : null;
 }
 function parseStartBody(body, tenant, factoryProjectId) {
-	if (!isRecord(body) || !isRecord(body.workItem)) return null;
-	const input = parseCreateWorkItem(body.workItem.input);
-	const sessionId = boundedText(body.sessionId, 256);
-	const threadTitle = boundedText(body.threadTitle, 512);
-	const kickoffKey = boundedText(body.kickoffKey, 256);
-	const role = boundedText(body.workItem.role, 32);
-	const id = boundedText(body.workItem.id, 64);
-	if (!input || !sessionId || !UUID_RE.test(sessionId) || !threadTitle || !kickoffKey || !UUID_RE.test(kickoffKey) || !id || !UUID_RE.test(id) || !role) return null;
-	return {
+	const parsed = FACTORY_ROUTE_CONTRACTS.workItemStart.bodySchema.safeParse(body);
+	return parsed.success ? {
 		...tenant,
 		factoryProjectId,
-		sessionId,
-		threadTitle,
-		kickoffKey,
-		workItem: {
-			id,
-			role,
-			input
-		}
-	};
-}
-const DECISION_STATUSES = /* @__PURE__ */ new Set([
-	"pending",
-	"proposed",
-	"dismissed",
-	"superseded",
-	"leased",
-	"retry",
-	"succeeded",
-	"failed"
-]);
-const DEFAULT_DECISION_PAGE_SIZE = 25;
-const MAX_DECISION_PAGE_SIZE = 50;
-function parseDecisionStatuses(raw) {
-	if (!raw) return void 0;
-	const statuses = [...new Set(raw.split(",").map((status) => status.trim()))].filter((status) => DECISION_STATUSES.has(status));
-	return statuses.length > 0 ? statuses : void 0;
-}
-function parseDecisionLimit(raw) {
-	const parsed = raw ? Number.parseInt(raw, 10) : DEFAULT_DECISION_PAGE_SIZE;
-	if (!Number.isFinite(parsed)) return DEFAULT_DECISION_PAGE_SIZE;
-	return Math.max(1, Math.min(MAX_DECISION_PAGE_SIZE, parsed));
+		...parsed.data
+	} : null;
 }
 function encodeDecisionCursor(decision) {
 	return Buffer.from(JSON.stringify([decision.createdAt.toISOString(), decision.id]), "utf8").toString("base64url");
 }
-function parseDecisionCursor(raw) {
-	if (!raw) return void 0;
-	try {
-		const decoded = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
-		if (!Array.isArray(decoded) || decoded.length !== 2 || typeof decoded[0] !== "string" || typeof decoded[1] !== "string") return;
-		const createdAt = new Date(decoded[0]);
-		if (Number.isNaN(createdAt.getTime()) || !UUID_RE.test(decoded[1])) return void 0;
-		return {
-			createdAt,
-			id: decoded[1]
-		};
-	} catch {
-		return;
-	}
-}
 /** A proposed transition names the seat its lane addresses, so the card can label what approving starts. */
-function summaryRole(decision) {
+function summaryRole(boards, decision) {
 	if (typeof decision.role === "string") return decision.role.slice(0, 32);
 	if (decision.type !== "transition") return null;
-	const board = decision.board;
-	const stage = decision.stage;
-	if (board !== "work" && board !== "review" || !isFactoryRuleStage(stage)) return null;
-	return roleForStage(board, stage);
+	const { board, stage } = decision;
+	if (typeof board !== "string" || typeof stage !== "string") return null;
+	return boards.get(board)?.roleForPhase(stage) ?? null;
 }
 /** A linked-card decision names where the card is synced from, so the UI can say "GitHub" rather than "a linked card". */
 function summarySource(decision) {
@@ -261,13 +84,13 @@ function summarySource(decision) {
 	const source = decision.source;
 	return source === "github-issue" || source === "github-pr" || source === "linear-issue" || source === "manual" ? source : null;
 }
-function decisionSummary(decision) {
+function decisionSummary(boards, decision) {
 	return {
 		id: decision.id,
 		evaluationId: decision.evaluationId,
 		workItemId: decision.workItemId,
 		type: factoryDecisionType(decision),
-		role: summaryRole(decision.decision),
+		role: summaryRole(boards, decision.decision),
 		source: summarySource(decision.decision),
 		status: decision.status,
 		attempts: decision.attempts,
@@ -281,6 +104,10 @@ function decisionSummary(decision) {
 	};
 }
 var WorkItemRoutes = class extends Route {
+	#defaultBoards;
+	get #boards() {
+		return this.deps.boardRegistry ?? (this.#defaultBoards ??= createBoardRegistry());
+	}
 	/** Resolve the `(orgId, userId)` tenant or a ready-to-return error response. */
 	async #resolveTenant(c) {
 		await this.deps.auth.ensureUser(c);
@@ -303,8 +130,9 @@ var WorkItemRoutes = class extends Route {
 	async #resolveProject(c) {
 		const tenant = await this.#resolveTenant(c);
 		if ("response" in tenant) return tenant;
-		const projectId = c.req.param("id");
-		if (!projectId || !UUID_RE.test(projectId)) return { response: c.json({ error: "Project not found" }, 404) };
+		const parsedPath = FACTORY_ROUTE_CONTRACTS.projectGet.pathSchema.safeParse({ id: c.req.param("id") });
+		if (!parsedPath.success) return { response: c.json({ error: "Project not found" }, 404) };
+		const projectId = parsedPath.data.id;
 		const { projects } = this.deps;
 		await projects.ensureReady();
 		const project = await projects.get({
@@ -373,15 +201,20 @@ var WorkItemRoutes = class extends Route {
 	/** Releasing a parked run and dropping it: same request, opposite outcomes, both audited as consent. */
 	#proposalRoute({ verb, settle }) {
 		const { audit, workItems } = this.deps;
-		return registerApiRoute(`/web/factory/projects/:id/decisions/:decisionId/${verb}`, {
-			method: "POST",
+		const contract = verb === "approve" ? FACTORY_ROUTE_CONTRACTS.decisionApprove : FACTORY_ROUTE_CONTRACTS.decisionDismiss;
+		return registerApiRoute(contract.path, {
+			method: contract.method,
 			requiresAuth: false,
 			handler: async (c) => {
 				const context = loose(c);
 				const resolved = await this.#resolveProject(context);
 				if ("response" in resolved) return resolved.response;
-				const decisionId = context.req.param("decisionId");
-				if (!decisionId || !UUID_RE.test(decisionId)) return c.json({ error: "invalid_decision_id" }, 422);
+				const parsedPath = contract.pathSchema.safeParse({
+					id: resolved.factoryProjectId,
+					decisionId: context.req.param("decisionId")
+				});
+				if (!parsedPath.success) return c.json({ error: "invalid_decision_id" }, 422);
+				const { decisionId } = parsedPath.data;
 				await workItems.ensureReady();
 				const now = /* @__PURE__ */ new Date();
 				const decision = await settle(resolved.orgId, resolved.factoryProjectId, decisionId, now, resolved.userId);
@@ -404,7 +237,7 @@ var WorkItemRoutes = class extends Route {
 						}
 					}
 				});
-				return c.json({ decision: decisionSummary(decision) });
+				return c.json({ decision: decisionSummary(this.#boards, decision) });
 			}
 		});
 	}
@@ -412,8 +245,31 @@ var WorkItemRoutes = class extends Route {
 	routes() {
 		const { audit, workItems, queueHealth, transitionService, startCoordinator, liveSessions } = this.deps;
 		return [
-			registerApiRoute("/web/factory/projects/:id/work-items", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.boardCatalog.path, {
+				method: FACTORY_ROUTE_CONTRACTS.boardCatalog.method,
+				requiresAuth: false,
+				handler: async (c) => {
+					const resolved = await this.#resolveProject(loose(c));
+					if ("response" in resolved) return resolved.response;
+					return c.json({ boards: [...this.#boards].map(([id, board]) => ({
+						id,
+						title: board.title,
+						initialPhase: board.initialPhase,
+						phases: Object.entries(board.phases).map(([phaseId, phase]) => ({
+							id: phaseId,
+							title: phase.title,
+							kind: phase.kind,
+							...phase.kind === "working" ? { role: phase.role } : {},
+							transitions: (board.transitions[phaseId] ?? []).map(({ outcome, to }) => ({
+								outcome,
+								to
+							}))
+						}))
+					})) });
+				}
+			}),
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemList.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemList.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -425,17 +281,24 @@ var WorkItemRoutes = class extends Route {
 					});
 					return c.json({
 						workItems: items.map(toWireWorkItem),
-						runningSessionIds: runningSessionIds(items, liveSessions)
+						runningSessionIds: sessionIdsWhere(items, (sessionId) => liveSessions.isRunning(sessionId)),
+						parkedSessionIds: sessionIdsWhere(items, (sessionId) => liveSessions.parked(sessionId) !== void 0)
 					});
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/metrics", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.metricsGet.path, {
+				method: FACTORY_ROUTE_CONTRACTS.metricsGet.method,
 				requiresAuth: false,
 				handler: async (c) => {
-					const resolved = await this.#resolveProject(loose(c));
+					const context = loose(c);
+					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const { windowStart, windowEnd } = parseMetricsRange(loose(c).req.query("from"), loose(c).req.query("to"), /* @__PURE__ */ new Date());
+					const query = FACTORY_ROUTE_CONTRACTS.metricsGet.querySchema.safeParse({
+						from: context.req.query("from"),
+						to: context.req.query("to")
+					});
+					if (!query.success) return c.json({ error: "invalid_metrics_range" }, 400);
+					const { windowStart, windowEnd } = parseMetricsRange(query.data.from, query.data.to, /* @__PURE__ */ new Date());
 					await workItems.ensureReady();
 					const items = await workItems.list({
 						orgId: resolved.orgId,
@@ -447,8 +310,8 @@ var WorkItemRoutes = class extends Route {
 					}) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/health/thresholds", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.path, {
+				method: FACTORY_ROUTE_CONTRACTS.healthThresholdsGet.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -458,27 +321,33 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ thresholds: thresholdsOrDefault(stored) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/decisions", {
-				method: "GET",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.decisionList.path, {
+				method: FACTORY_ROUTE_CONTRACTS.decisionList.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const context = loose(c);
 					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const cursorRaw = context.req.query("before");
-					const before = parseDecisionCursor(cursorRaw);
-					if (cursorRaw && !before) return c.json({ error: "invalid_cursor" }, 400);
+					const query = FACTORY_ROUTE_CONTRACTS.decisionList.querySchema.safeParse({
+						statuses: context.req.query("statuses"),
+						before: context.req.query("before"),
+						limit: context.req.query("limit")
+					});
+					if (!query.success) {
+						const field = query.error.issues[0]?.path[0];
+						return c.json({ error: field === "before" ? "invalid_cursor" : "invalid_decision_query" }, 400);
+					}
 					await workItems.ensureReady();
 					const page = await workItems.listDeferredDecisionPage({
 						orgId: resolved.orgId,
 						factoryProjectId: resolved.factoryProjectId,
-						statuses: parseDecisionStatuses(context.req.query("statuses")),
-						before,
-						limit: parseDecisionLimit(context.req.query("limit"))
+						statuses: query.data.statuses,
+						before: query.data.before,
+						limit: query.data.limit
 					});
 					const last = page.decisions.at(-1);
 					return c.json({
-						decisions: page.decisions.map(decisionSummary),
+						decisions: page.decisions.map((decision) => decisionSummary(this.#boards, decision)),
 						...page.hasMore && last ? { nextCursor: encodeDecisionCursor(last) } : {}
 					});
 				}
@@ -486,10 +355,12 @@ var WorkItemRoutes = class extends Route {
 			...buildAttentionRoutes({
 				workItems,
 				comments: this.deps.comments,
+				liveSessions,
 				resolveProject: (context) => this.#resolveProject(loose(context))
 			}),
 			...buildSupervisorRoutes({
 				workItems,
+				boards: this.#boards,
 				resolveProject: (context) => this.#resolveProject(loose(context))
 			}),
 			this.#proposalRoute({
@@ -500,25 +371,29 @@ var WorkItemRoutes = class extends Route {
 				verb: "dismiss",
 				settle: workItems.dismissDeferredDecision.bind(workItems)
 			}),
-			registerApiRoute("/web/factory/projects/:id/decisions/:decisionId/retry", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.decisionRetry.path, {
+				method: FACTORY_ROUTE_CONTRACTS.decisionRetry.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const context = loose(c);
 					const resolved = await this.#resolveProject(context);
 					if ("response" in resolved) return resolved.response;
-					const decisionId = context.req.param("decisionId");
-					if (!decisionId || !UUID_RE.test(decisionId)) return c.json({ error: "invalid_decision_id" }, 422);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.decisionRetry.pathSchema.safeParse({
+						id: resolved.factoryProjectId,
+						decisionId: context.req.param("decisionId")
+					});
+					if (!parsedPath.success) return c.json({ error: "invalid_decision_id" }, 422);
+					const { decisionId } = parsedPath.data;
 					await workItems.ensureReady();
 					const current = await workItems.getDeferredDecision(resolved.orgId, resolved.factoryProjectId, decisionId);
 					if (!current || current.status !== "failed" || !factoryDispatchFailureMetadata(current.failureCode).canRetry) return c.json({ error: "decision_not_retryable" }, 409);
 					const decision = await workItems.retryDeferredDecision(resolved.orgId, resolved.factoryProjectId, decisionId, /* @__PURE__ */ new Date());
 					if (!decision) return c.json({ error: "decision_not_retryable" }, 409);
-					return c.json({ decision: decisionSummary(decision) });
+					return c.json({ decision: decisionSummary(this.#boards, decision) });
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/work-items", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemCreate.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemCreate.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -528,7 +403,7 @@ var WorkItemRoutes = class extends Route {
 					const input = parseCreateWorkItem(body);
 					if (!input) return c.json({ error: "invalid_work_item" }, 400);
 					const boardId = input.board ?? (input.externalSource?.type === "pull-request" ? "review" : "work");
-					const board = (this.deps.boardRegistry ?? createBoardRegistry()).get(boardId);
+					const board = this.#boards.get(boardId);
 					if (!board) return c.json({
 						error: "invalid_board",
 						message: `Board '${boardId}' is not installed.`
@@ -625,15 +500,20 @@ var WorkItemRoutes = class extends Route {
 					}
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/work-items/:workItemId/transition", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemTransition.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemTransition.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
 					if ("response" in resolved) return resolved.response;
-					const workItemId = loose(c).req.param("workItemId");
-					if (!workItemId || !UUID_RE.test(workItemId)) return c.json({ error: "Work item not found" }, 404);
-					const parsed = parseTransitionBody(await readJson(loose(c)));
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemTransition.pathSchema.safeParse({
+						id: resolved.factoryProjectId,
+						workItemId: context.req.param("workItemId")
+					});
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { workItemId } = parsedPath.data;
+					const parsed = parseTransitionBody(await readJson(context));
 					if (!parsed) return c.json({ error: "invalid_transition_request" }, 400);
 					if (!transitionService) return c.json({ error: "factory_transition_unavailable" }, 503);
 					await workItems.ensureReady();
@@ -663,7 +543,7 @@ var WorkItemRoutes = class extends Route {
 							metadata: {
 								transitionId: result.transitionId,
 								ingressType: parsed.ingress.type,
-								ruleSetVersion: transitionService.ruleSetVersion,
+								configVersion: transitionService.configVersion,
 								...result.status === "accepted" ? {
 									to: result.stage,
 									revision: result.revision
@@ -678,8 +558,8 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ result }, result.code === "stale" ? 409 : 422);
 				}
 			}),
-			registerApiRoute("/web/factory/projects/:id/runs/start", {
-				method: "POST",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemStart.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemStart.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const resolved = await this.#resolveProject(loose(c));
@@ -718,15 +598,17 @@ var WorkItemRoutes = class extends Route {
 					return c.json({ prepared }, 202);
 				}
 			}),
-			registerApiRoute("/web/factory/work-items/:id", {
-				method: "PATCH",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemUpdate.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemUpdate.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const tenant = await this.#resolveTenant(loose(c));
 					if ("response" in tenant) return tenant.response;
-					const id = loose(c).req.param("id");
-					if (!id || !UUID_RE.test(id)) return c.json({ error: "Work item not found" }, 404);
-					const body = await readJson(loose(c));
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemUpdate.pathSchema.safeParse({ id: context.req.param("id") });
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { id } = parsedPath.data;
+					const body = await readJson(context);
 					if (body === void 0) return c.json({ error: "Invalid JSON body" }, 400);
 					const patch = parseUpdateWorkItem(body);
 					if (!patch) return c.json({ error: "invalid_work_item_patch" }, 400);
@@ -737,7 +619,7 @@ var WorkItemRoutes = class extends Route {
 					});
 					if (!existing) return c.json({ error: "Work item not found" }, 404);
 					if (patch.board !== void 0) {
-						const board = (this.deps.boardRegistry ?? createBoardRegistry()).get(patch.board);
+						const board = this.#boards.get(patch.board);
 						const stage = patch.stages?.length === 1 ? patch.stages[0] : void 0;
 						if (existing.board !== null) return c.json({ error: "board_already_assigned" }, 409);
 						if (!board) return c.json({ error: "board_not_installed" }, 400);
@@ -775,14 +657,16 @@ var WorkItemRoutes = class extends Route {
 					}
 				}
 			}),
-			registerApiRoute("/web/factory/work-items/:id", {
-				method: "DELETE",
+			registerApiRoute(FACTORY_ROUTE_CONTRACTS.workItemDelete.path, {
+				method: FACTORY_ROUTE_CONTRACTS.workItemDelete.method,
 				requiresAuth: false,
 				handler: async (c) => {
 					const tenant = await this.#resolveTenant(loose(c));
 					if ("response" in tenant) return tenant.response;
-					const id = loose(c).req.param("id");
-					if (!id || !UUID_RE.test(id)) return c.json({ error: "Work item not found" }, 404);
+					const context = loose(c);
+					const parsedPath = FACTORY_ROUTE_CONTRACTS.workItemDelete.pathSchema.safeParse({ id: context.req.param("id") });
+					if (!parsedPath.success) return c.json({ error: "Work item not found" }, 404);
+					const { id } = parsedPath.data;
 					await workItems.ensureReady();
 					const deleted = await workItems.delete({
 						orgId: tenant.orgId,