@mastra/factory 0.0.0 → 0.1.0-alpha.3

package/dist/routes/work-items.js

@@ -0,0 +1,902 @@
+// src/routes/work-items.ts
+import { registerApiRoute } from "@mastra/core/server";
+
+// src/rules/start-coordinator.ts
+import { RequestContext } from "@mastra/core/request-context";
+import { formatSkillActivation } from "@mastra/core/workspace";
+var FactoryStartTransitionError = class extends Error {
+  result;
+  constructor(result) {
+    super(result.reason);
+    this.name = "FactoryStartTransitionError";
+    this.result = result;
+  }
+};
+
+// src/rules/types.ts
+var FACTORY_RULE_STAGES = ["intake", "triage", "planning", "execute", "review", "done", "canceled"];
+var FACTORY_RULE_BOARDS = ["work", "review"];
+
+// src/storage/domains/queue-health/base.ts
+import { FactoryStorageDomain, UniqueViolationError } from "@mastra/core/storage";
+var DEFAULT_QUEUE_HEALTH_CONFIG = {
+  thresholdsSeconds: [14400, 86400, 259200]
+};
+function assertValidThresholds(config) {
+  const t = config.thresholdsSeconds;
+  if (!Array.isArray(t) || t.length === 0 || t.some((v) => typeof v !== "number" || !Number.isFinite(v))) {
+    throw new Error("[QueueHealthStorage] thresholdsSeconds must be a non-empty array of finite numbers.");
+  }
+  for (let i = 1; i < t.length; i++) {
+    if (t[i] <= t[i - 1]) {
+      throw new Error("[QueueHealthStorage] thresholdsSeconds must be strictly ascending.");
+    }
+  }
+}
+function parseQueueHealthConfig(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const config = body;
+  if (!Array.isArray(config.thresholdsSeconds)) return null;
+  try {
+    assertValidThresholds(config);
+  } catch {
+    return null;
+  }
+  return { thresholdsSeconds: [...config.thresholdsSeconds] };
+}
+function thresholdsOrDefault(config) {
+  return parseQueueHealthConfig(config)?.thresholdsSeconds ?? DEFAULT_QUEUE_HEALTH_CONFIG.thresholdsSeconds;
+}
+
+// src/storage/domains/work-items/base.ts
+import { createHash } from "crypto";
+import { FactoryStorageDomain as FactoryStorageDomain2, UniqueViolationError as UniqueViolationError2 } from "@mastra/core/storage";
+var AUTOMATION_ACTORS = /* @__PURE__ */ new Set([
+  "factory",
+  "system",
+  "automation",
+  "factory-rule-dispatcher",
+  "factory-tool-result-rule"
+]);
+function isAutomationActor(by) {
+  if (by === void 0) return false;
+  return AUTOMATION_ACTORS.has(by) || by.startsWith("agent:") || by.startsWith("github:");
+}
+var WorkItemRelationError = class extends Error {
+  code = "invalid_work_item_relation";
+};
+
+// src/storage/domains/work-items/metrics.ts
+var DEFAULT_METRICS_WINDOW = 30;
+var MAX_METRICS_WINDOW = 366;
+var DAY_MS = 864e5;
+var DONE_STAGE = "done";
+var CANCELED_STAGE = "canceled";
+var TERMINAL_STAGES = /* @__PURE__ */ new Set([DONE_STAGE, CANCELED_STAGE]);
+var AGING_WIP_LIMIT = 10;
+var DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+var ZONED_DATETIME_RE = /(?:[Zz]|[+-]\d{2}:?\d{2})$/;
+function parseRangeParam(value, boundary) {
+  if (typeof value !== "string" || value.length === 0) return void 0;
+  const dateOnly = DATE_ONLY_RE.test(value);
+  if (!dateOnly && !ZONED_DATETIME_RE.test(value)) return void 0;
+  const time = Date.parse(value);
+  if (Number.isNaN(time)) return void 0;
+  return boundary === "to" && dateOnly ? time + DAY_MS : time;
+}
+function utcDayStart(time) {
+  return Date.parse(`${utcDay(time)}T00:00:00Z`);
+}
+function parseMetricsRange(fromParam, toParam, now) {
+  const nowMs = now.getTime();
+  const endOfToday = utcDayStart(nowMs) + DAY_MS;
+  const requestedEnd = parseRangeParam(toParam, "to") ?? endOfToday;
+  const windowEnd = Math.min(requestedEnd, endOfToday);
+  const lastIncludedDay = utcDayStart(windowEnd - 1);
+  const defaultStart = lastIncludedDay - (DEFAULT_METRICS_WINDOW - 1) * DAY_MS;
+  const parsedFrom = parseRangeParam(fromParam, "from");
+  let windowStart = parsedFrom !== void 0 && parsedFrom < windowEnd ? parsedFrom : defaultStart;
+  const earliestStart = lastIncludedDay - (MAX_METRICS_WINDOW - 1) * DAY_MS;
+  if (windowStart < earliestStart) windowStart = earliestStart;
+  return { windowStart, windowEnd };
+}
+function parseTime(iso) {
+  const time = Date.parse(iso);
+  return Number.isNaN(time) ? 0 : time;
+}
+function percentile(samples, fraction) {
+  if (samples.length === 0) return null;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const rank = Math.max(1, Math.ceil(fraction * sorted.length));
+  return sorted[rank - 1];
+}
+function utcDay(time) {
+  return new Date(time).toISOString().slice(0, 10);
+}
+function completedAt(item) {
+  if (!item.stages.includes(DONE_STAGE)) return void 0;
+  for (let i = item.stageHistory.length - 1; i >= 0; i--) {
+    const entry = item.stageHistory[i];
+    if (entry.stage === DONE_STAGE && entry.exitedAt === void 0) return parseTime(entry.enteredAt);
+  }
+  return void 0;
+}
+function openEntries(item) {
+  return item.stageHistory.filter(
+    (entry) => entry.exitedAt === void 0 && !TERMINAL_STAGES.has(entry.stage) && item.stages.includes(entry.stage)
+  );
+}
+function computeFactoryMetrics(items, opts) {
+  const { windowStart, windowEnd } = opts;
+  let earliest = Infinity;
+  for (const item of items) earliest = Math.min(earliest, item.createdAt.getTime());
+  const earliestItemAt = Number.isFinite(earliest) ? new Date(earliest).toISOString() : null;
+  const throughputByDay = /* @__PURE__ */ new Map();
+  const firstDay = utcDayStart(windowStart);
+  for (let day = firstDay; day < windowEnd; day += DAY_MS) {
+    throughputByDay.set(utcDay(day), 0);
+  }
+  const cycleSamples = [];
+  for (const item of items) {
+    const doneAt = completedAt(item);
+    if (doneAt === void 0 || doneAt < windowStart || doneAt >= windowEnd) continue;
+    const day = utcDay(doneAt);
+    throughputByDay.set(day, (throughputByDay.get(day) ?? 0) + 1);
+    cycleSamples.push(Math.max(0, doneAt - item.createdAt.getTime()));
+  }
+  const durationsByStage = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    for (const entry of item.stageHistory) {
+      if (entry.exitedAt === void 0 || TERMINAL_STAGES.has(entry.stage)) continue;
+      const exited = parseTime(entry.exitedAt);
+      if (exited < windowStart || exited >= windowEnd) continue;
+      const duration = Math.max(0, exited - parseTime(entry.enteredAt));
+      const samples = durationsByStage.get(entry.stage) ?? [];
+      samples.push(duration);
+      durationsByStage.set(entry.stage, samples);
+    }
+  }
+  const wipByStage = /* @__PURE__ */ new Map();
+  let wipTotal = 0;
+  const aging = [];
+  for (const item of items) {
+    for (const stage of item.stages) {
+      wipByStage.set(stage, (wipByStage.get(stage) ?? 0) + 1);
+    }
+    const inFlightStages = item.stages.filter((stage) => !TERMINAL_STAGES.has(stage));
+    if (inFlightStages.length === 0) continue;
+    wipTotal += 1;
+    const open = openEntries(item);
+    const oldest = open.reduce(
+      (best, entry) => !best || parseTime(entry.enteredAt) < parseTime(best.enteredAt) ? entry : best,
+      void 0
+    );
+    aging.push({
+      id: item.id,
+      title: item.title,
+      stage: oldest?.stage ?? inFlightStages[0],
+      enteredAt: oldest?.enteredAt ?? item.createdAt.toISOString(),
+      url: item.externalSource?.url ?? null
+    });
+  }
+  aging.sort((a, b) => parseTime(a.enteredAt) - parseTime(b.enteredAt));
+  const sourceCounts = /* @__PURE__ */ new Map();
+  let transitionsTotal = 0;
+  let transitionsHuman = 0;
+  for (const item of items) {
+    if (item.createdAt.getTime() >= windowStart && item.createdAt.getTime() < windowEnd) {
+      const source = item.externalSource ? `${item.externalSource.integrationId}:${item.externalSource.type}` : "manual";
+      sourceCounts.set(source, (sourceCounts.get(source) ?? 0) + 1);
+    }
+    for (const entry of item.stageHistory) {
+      const entered = parseTime(entry.enteredAt);
+      if (entered < windowStart || entered >= windowEnd) continue;
+      transitionsTotal += 1;
+      if (!isAutomationActor(entry.by)) transitionsHuman += 1;
+    }
+  }
+  const automationByStage = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const itemDone = completedAt(item) !== void 0;
+    const itemCanceled = item.stages.includes(CANCELED_STAGE);
+    for (let i = 0; i < item.stageHistory.length; i++) {
+      const entry = item.stageHistory[i];
+      if (entry.exitedAt === void 0 || TERMINAL_STAGES.has(entry.stage)) continue;
+      const exited = parseTime(entry.exitedAt);
+      if (exited < windowStart || exited >= windowEnd) continue;
+      let row = automationByStage.get(entry.stage);
+      if (!row) {
+        row = {
+          stage: entry.stage,
+          exits: 0,
+          automated: 0,
+          outcomes: { done: 0, canceled: 0, reworked: 0, inFlight: 0 }
+        };
+        automationByStage.set(entry.stage, row);
+      }
+      row.exits += 1;
+      const firstVisitIndex = item.stageHistory.findIndex((e) => e.stage === entry.stage);
+      if (firstVisitIndex !== i || !isAutomationActor(entry.by) || !isAutomationActor(entry.exitedBy)) continue;
+      row.automated += 1;
+      const reworked = item.stageHistory.some((e, j) => j > i && e.stage === entry.stage);
+      if (reworked) row.outcomes.reworked += 1;
+      else if (itemDone) row.outcomes.done += 1;
+      else if (itemCanceled) row.outcomes.canceled += 1;
+      else row.outcomes.inFlight += 1;
+    }
+  }
+  return {
+    windowDays: throughputByDay.size,
+    earliestItemAt,
+    throughput: [...throughputByDay.entries()].map(([date, count]) => ({ date, count })).sort((a, b) => a.date.localeCompare(b.date)),
+    cycleTime: {
+      medianMs: percentile(cycleSamples, 0.5),
+      p90Ms: percentile(cycleSamples, 0.9),
+      samples: cycleSamples.length
+    },
+    stageDurations: [...durationsByStage.entries()].map(([stage, samples]) => ({
+      stage,
+      medianMs: percentile(samples, 0.5),
+      samples: samples.length
+    })),
+    wip: [...wipByStage.entries()].map(([stage, count]) => ({ stage, count })),
+    wipTotal,
+    agingWip: aging.slice(0, AGING_WIP_LIMIT),
+    sourceMix: [...sourceCounts.entries()].map(([source, count]) => ({ source, count })).sort((a, b) => b.count - a.count),
+    transitions: { human: transitionsHuman, total: transitionsTotal },
+    stageAutomation: [...automationByStage.values()]
+  };
+}
+
+// src/routes/route.ts
+var Route = class {
+  deps;
+  constructor(deps) {
+    this.deps = deps;
+  }
+};
+
+// src/routes/work-items.ts
+function loose(c) {
+  return c;
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var MAX_STAGES = 16;
+var MAX_STAGE_LENGTH = 64;
+var 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 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;
+}
+function parseCreateWorkItem(body) {
+  if (!isRecord(body)) return null;
+  const { externalSource, title, stages, sessions, metadata } = body;
+  if (typeof title !== "string" || title.trim().length === 0 || title.length > 500) 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;
+  if (metadata !== void 0 && !validMetadata(metadata)) return null;
+  return {
+    title: title.trim(),
+    ...parsedSource !== void 0 ? { externalSource: parsedSource } : {},
+    ...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
+    ...stages !== void 0 ? { stages } : {},
+    ...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+}
+function parseUpdateWorkItem(body) {
+  if (!isRecord(body)) return null;
+  const { title, stages, sessions, metadata } = body;
+  const hasParentWorkItemId = "parentWorkItemId" in body;
+  if (title === void 0 && stages === void 0 && sessions === void 0 && metadata === void 0 && !hasParentWorkItemId)
+    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;
+  if (metadata !== void 0 && !validMetadata(metadata)) return null;
+  return {
+    ...hasParentWorkItemId ? { parentWorkItemId: parentWorkItemId ?? null } : {},
+    ...title !== void 0 ? { title: title.trim() } : {},
+    ...stages !== void 0 ? { stages } : {},
+    ...parsedSessions !== void 0 ? { sessions: parsedSessions } : {},
+    ...metadata !== void 0 ? { metadata } : {}
+  };
+}
+async function readJson(c) {
+  try {
+    return await c.req.json();
+  } catch {
+    return void 0;
+  }
+}
+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 = FACTORY_RULE_BOARDS.includes(body.board) ? body.board : void 0;
+  const stage = FACTORY_RULE_STAGES.includes(body.stage) ? 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
+  };
+}
+function parseInvocation(value) {
+  if (value === void 0) return void 0;
+  if (!isRecord(value)) return null;
+  if (value.type === "prompt") {
+    const prompt = boundedText(value.prompt, 16384);
+    return prompt ? { type: "prompt", prompt } : null;
+  }
+  if (value.type === "skill") {
+    const skillName = boundedText(value.skillName, 64);
+    const args = typeof value.arguments === "string" && value.arguments.length <= 16384 ? value.arguments : void 0;
+    return skillName && args !== void 0 ? { type: "skill", skillName, arguments: args } : null;
+  }
+  return 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 invocation = parseInvocation(body.invocation);
+  const destinationStage = FACTORY_RULE_STAGES.includes(body.destinationStage) ? body.destinationStage : void 0;
+  const role = boundedText(body.workItem.role, 32);
+  const id = body.workItem.id === void 0 ? void 0 : boundedText(body.workItem.id, 64);
+  if (body.workItem.id !== void 0 && (!id || !UUID_RE.test(id))) return null;
+  if (!input || !sessionId || !UUID_RE.test(sessionId) || !threadTitle || !kickoffKey || !UUID_RE.test(kickoffKey) || invocation === null || !destinationStage || !role) {
+    return null;
+  }
+  const threadTags = isRecord(body.threadTags) ? Object.fromEntries(
+    Object.entries(body.threadTags).filter(
+      (entry) => boundedText(entry[0], 64) !== void 0 && boundedText(entry[1], 256) !== void 0
+    ).map(([key, value]) => [key, value.trim()])
+  ) : void 0;
+  return {
+    ...tenant,
+    factoryProjectId,
+    sessionId,
+    threadTitle,
+    threadTags,
+    kickoffKey,
+    invocation,
+    destinationStage,
+    workItem: { id, role, input }
+  };
+}
+var DECISION_STATUSES = /* @__PURE__ */ new Set(["pending", "leased", "retry", "succeeded", "failed"]);
+var DEFAULT_DECISION_PAGE_SIZE = 25;
+var 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));
+}
+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 void 0;
+    }
+    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 void 0;
+  }
+}
+function decisionSummary(decision) {
+  const type = typeof decision.decision.type === "string" ? decision.decision.type.slice(0, 64) : "unknown";
+  return {
+    id: decision.id,
+    evaluationId: decision.evaluationId,
+    workItemId: decision.workItemId,
+    type,
+    status: decision.status,
+    attempts: decision.attempts,
+    lastError: decision.lastError?.slice(0, 512) ?? null,
+    createdAt: decision.createdAt.toISOString(),
+    updatedAt: decision.updatedAt.toISOString(),
+    completedAt: decision.completedAt?.toISOString() ?? null
+  };
+}
+var WorkItemRoutes = class extends Route {
+  /** Resolve the `(orgId, userId)` tenant or a ready-to-return error response. */
+  async #resolveTenant(c) {
+    await this.deps.auth.ensureUser(c);
+    const tenant = this.deps.auth.tenant(c);
+    if (!tenant) return { response: c.json({ error: "unauthorized" }, 401) };
+    if (!tenant.orgId) {
+      return {
+        response: c.json(
+          { error: "organization_required", message: "The Factory board requires an organization." },
+          403
+        )
+      };
+    }
+    return { orgId: tenant.orgId, userId: tenant.userId };
+  }
+  /**
+   * Resolve the tenant AND the org-owned project from the `:id` param. Work
+   * items hang off a project, so listing/creating requires the project to
+   * exist in the caller's org.
+   */
+  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 { projects } = this.deps;
+    await projects.ensureReady();
+    const project = await projects.get({ orgId: tenant.orgId, id: projectId });
+    if (!project) {
+      return { response: c.json({ error: "Project not found" }, 404) };
+    }
+    return { ...tenant, factoryProjectId: projectId };
+  }
+  /**
+   * Emit the audit events a successful work-item PATCH implies: always
+   * `updated`, plus `stage_moved` when the stages actually changed and one
+   * `run.started` per session role the patch introduced.
+   */
+  async #auditWorkItemPatch({
+    context,
+    item,
+    previous,
+    patch
+  }) {
+    const { audit } = this.deps;
+    const target = { type: "work_item", id: item.id, name: item.title };
+    await audit.emit({
+      context,
+      input: {
+        action: "factory.work_item.updated",
+        factoryProjectId: item.factoryProjectId,
+        targets: [target],
+        metadata: { fields: patchedFields(patch) }
+      }
+    });
+    const stagesChanged = patch.stages !== void 0 && (previous.stages.length !== item.stages.length || previous.stages.some((s, i) => s !== item.stages[i]));
+    if (stagesChanged) {
+      await audit.emit({
+        context,
+        input: {
+          action: "factory.work_item.stage_moved",
+          factoryProjectId: item.factoryProjectId,
+          targets: [target],
+          metadata: { from: previous.stages, to: item.stages }
+        }
+      });
+    }
+    const newRoles = Object.keys(item.sessions).filter((role) => !previous.sessionRoles.includes(role));
+    for (const role of newRoles) {
+      const session = item.sessions[role];
+      await audit.emit({
+        context,
+        input: {
+          action: "factory.run.started",
+          factoryProjectId: item.factoryProjectId,
+          targets: [target],
+          metadata: {
+            role,
+            branch: session?.branch,
+            threadId: session?.threadId,
+            sessionId: session?.sessionId
+          }
+        }
+      });
+    }
+  }
+  /** Build the Factory work-item routes as Mastra `apiRoutes`. */
+  routes() {
+    const { audit, workItems, queueHealth, transitionService, startCoordinator } = this.deps;
+    return [
+      // ── List the org's work items for a project ─────────────────────────────
+      registerApiRoute("/web/factory/projects/:id/work-items", {
+        method: "GET",
+        requiresAuth: false,
+        handler: async (c) => {
+          const resolved = await this.#resolveProject(loose(c));
+          if ("response" in resolved) return resolved.response;
+          await workItems.ensureReady();
+          const items = await workItems.list({
+            orgId: resolved.orgId,
+            factoryProjectId: resolved.factoryProjectId
+          });
+          return c.json({ workItems: items });
+        }
+      }),
+      // ── Flow metrics aggregated over the project's work items ───────────────
+      registerApiRoute("/web/factory/projects/:id/metrics", {
+        method: "GET",
+        requiresAuth: false,
+        handler: async (c) => {
+          const resolved = await this.#resolveProject(loose(c));
+          if ("response" in resolved) return resolved.response;
+          const { windowStart, windowEnd } = parseMetricsRange(
+            loose(c).req.query("from"),
+            loose(c).req.query("to"),
+            /* @__PURE__ */ new Date()
+          );
+          await workItems.ensureReady();
+          const items = await workItems.list({
+            orgId: resolved.orgId,
+            factoryProjectId: resolved.factoryProjectId
+          });
+          return c.json({ metrics: computeFactoryMetrics(items, { windowStart, windowEnd }) });
+        }
+      }),
+      // ── Per-project queue-health age-threshold config (seconds) ─────────────
+      registerApiRoute("/web/factory/projects/:id/health/thresholds", {
+        method: "GET",
+        requiresAuth: false,
+        handler: async (c) => {
+          const resolved = await this.#resolveProject(loose(c));
+          if ("response" in resolved) return resolved.response;
+          await queueHealth.ensureReady();
+          const stored = await queueHealth.getConfig(resolved.orgId, resolved.factoryProjectId);
+          return c.json({ thresholds: thresholdsOrDefault(stored) });
+        }
+      }),
+      // ── Bounded durable rule-decision status ────────────────────────────────
+      registerApiRoute("/web/factory/projects/:id/decisions", {
+        method: "GET",
+        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);
+          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"))
+          });
+          const last = page.decisions.at(-1);
+          return c.json({
+            decisions: page.decisions.map(decisionSummary),
+            ...page.hasMore && last ? { nextCursor: encodeDecisionCursor(last) } : {}
+          });
+        }
+      }),
+      registerApiRoute("/web/factory/projects/:id/decisions/:decisionId/retry", {
+        method: "POST",
+        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);
+          await workItems.ensureReady();
+          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) });
+        }
+      }),
+      // ── Create (upsert on sourceKey) a work item ─────────────────────────────
+      registerApiRoute("/web/factory/projects/:id/work-items", {
+        method: "POST",
+        requiresAuth: false,
+        handler: async (c) => {
+          const resolved = await this.#resolveProject(loose(c));
+          if ("response" in resolved) return resolved.response;
+          const body = await readJson(loose(c));
+          if (body === void 0) return c.json({ error: "Invalid JSON body" }, 400);
+          const input = parseCreateWorkItem(body);
+          if (!input) return c.json({ error: "invalid_work_item" }, 400);
+          if ((input.stages ?? ["intake"]).length !== 1 || (input.stages ?? ["intake"])[0] !== "intake") {
+            return c.json(
+              { error: "governed_transition_required", message: "New work items must enter through Factory intake." },
+              409
+            );
+          }
+          await workItems.ensureReady();
+          try {
+            const result = await workItems.upsert({
+              orgId: resolved.orgId,
+              userId: resolved.userId,
+              factoryProjectId: resolved.factoryProjectId,
+              input,
+              reuseMode: "non-stage"
+            });
+            let item = result.item;
+            if (result.created) {
+              if (!transitionService) {
+                await workItems.delete({ orgId: resolved.orgId, id: item.id });
+                return c.json({ error: "factory_transitions_unavailable" }, 503);
+              }
+              const entered = await transitionService.transition({
+                orgId: resolved.orgId,
+                factoryProjectId: resolved.factoryProjectId,
+                workItemId: item.id,
+                board: item.externalSource?.type === "pull-request" ? "review" : "work",
+                stage: "intake",
+                expectedRevision: item.revision,
+                actor: { type: "human", id: resolved.userId },
+                ingress: { type: "human", identity: `work-item:${item.id}:initial-entry` },
+                cause: "work_item_created",
+                initialEntry: true
+              });
+              if (entered.status === "rejected") {
+                await workItems.delete({ orgId: resolved.orgId, id: item.id });
+                return c.json({ status: "rejected", code: entered.code, reason: entered.reason }, 422);
+              }
+              item = await workItems.getForProject(resolved.orgId, resolved.factoryProjectId, item.id) ?? item;
+              await audit.emit({
+                context: loose(c),
+                input: {
+                  action: "factory.work_item.created",
+                  factoryProjectId: resolved.factoryProjectId,
+                  targets: [{ type: "work_item", id: item.id, name: item.title }],
+                  metadata: { externalSource: item.externalSource, stages: item.stages }
+                }
+              });
+            } else {
+              const { stages: _stages, sessions: _sessions, ...boundedPatch } = input;
+              await this.#auditWorkItemPatch({
+                context: loose(c),
+                item,
+                previous: result.previous,
+                patch: boundedPatch
+              });
+            }
+            return c.json({ workItem: item });
+          } catch (error) {
+            if (error instanceof WorkItemRelationError) {
+              return c.json({ error: error.code, message: error.message }, 400);
+            }
+            throw error;
+          }
+        }
+      }),
+      // ── Authoritative stage transition ──────────────────────────────────────
+      registerApiRoute("/web/factory/projects/:id/work-items/:workItemId/transition", {
+        method: "POST",
+        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)));
+          if (!parsed) return c.json({ error: "invalid_transition_request" }, 400);
+          if (!transitionService) {
+            return c.json({ error: "factory_transition_unavailable" }, 503);
+          }
+          await workItems.ensureReady();
+          const result = await transitionService.transition({
+            ...parsed,
+            orgId: resolved.orgId,
+            factoryProjectId: resolved.factoryProjectId,
+            workItemId,
+            actor: { type: "human", id: resolved.userId },
+            ingress: {
+              ...parsed.ingress,
+              identity: `human:${resolved.userId}:${parsed.ingress.identity}`
+            }
+          });
+          await audit.emit({
+            context: loose(c),
+            input: {
+              action: result.status === "accepted" ? "factory.work_item.stage_moved" : "factory.work_item.transition_rejected",
+              factoryProjectId: resolved.factoryProjectId,
+              targets: [{ type: "work_item", id: workItemId }],
+              metadata: {
+                transitionId: result.transitionId,
+                ingressType: parsed.ingress.type,
+                ruleSetVersion: transitionService.ruleSetVersion,
+                ...result.status === "accepted" ? { to: result.stage, revision: result.revision } : { code: result.code, reason: result.reason }
+              }
+            }
+          });
+          if (result.status === "accepted") return c.json({ result });
+          return c.json({ result }, result.code === "stale" ? 409 : 422);
+        }
+      }),
+      // ── Bind a Factory run before dispatching its kickoff ────────────────────
+      registerApiRoute("/web/factory/projects/:id/runs/start", {
+        method: "POST",
+        requiresAuth: false,
+        handler: async (c) => {
+          const resolved = await this.#resolveProject(loose(c));
+          if ("response" in resolved) return resolved.response;
+          if (!startCoordinator) {
+            return c.json({ error: "factory_start_unavailable" }, 503);
+          }
+          const input = parseStartBody(await readJson(loose(c)), resolved, resolved.factoryProjectId);
+          if (!input) return c.json({ error: "invalid_factory_start" }, 400);
+          input.requestContext = loose(c).get("requestContext");
+          if (!input.workItem.id && ((input.workItem.input.stages ?? ["intake"]).length !== 1 || (input.workItem.input.stages ?? ["intake"])[0] !== "intake")) {
+            return c.json(
+              { error: "governed_transition_required", message: "Create the work item in Intake before starting it." },
+              409
+            );
+          }
+          await workItems.ensureReady();
+          let prepared;
+          try {
+            prepared = await startCoordinator.prepare(input);
+          } catch (error) {
+            if (error instanceof FactoryStartTransitionError) {
+              return c.json({ result: error.result }, error.result.code === "stale" ? 409 : 422);
+            }
+            throw error;
+          }
+          await audit.emit({
+            context: loose(c),
+            input: {
+              action: "factory.run.started",
+              factoryProjectId: resolved.factoryProjectId,
+              targets: [{ type: "work_item", id: prepared.workItemId }],
+              metadata: {
+                role: input.workItem.role,
+                branch: prepared.branch,
+                threadId: prepared.threadId,
+                sessionId: prepared.sessionId,
+                bindingId: prepared.bindingId
+              }
+            }
+          });
+          return c.json({ prepared }, 202);
+        }
+      }),
+      // ── Patch non-stage metadata / sessions / title ──────────────────────────
+      registerApiRoute("/web/factory/work-items/:id", {
+        method: "PATCH",
+        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));
+          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);
+          if (patch.stages !== void 0) {
+            return c.json(
+              { error: "governed_transition_required", message: "Use the Factory transition endpoint to move stages." },
+              409
+            );
+          }
+          await workItems.ensureReady();
+          try {
+            const updated = await workItems.update({ orgId: tenant.orgId, id, userId: tenant.userId, patch });
+            if (!updated) return c.json({ error: "Work item not found" }, 404);
+            await this.#auditWorkItemPatch({
+              context: loose(c),
+              item: updated.item,
+              previous: updated.previous,
+              patch
+            });
+            return c.json({ workItem: updated.item });
+          } catch (error) {
+            if (error instanceof WorkItemRelationError) {
+              return c.json({ error: error.code, message: error.message }, 400);
+            }
+            throw error;
+          }
+        }
+      }),
+      // ── Remove a work item ───────────────────────────────────────────────────
+      registerApiRoute("/web/factory/work-items/:id", {
+        method: "DELETE",
+        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);
+          await workItems.ensureReady();
+          const deleted = await workItems.delete({ orgId: tenant.orgId, id });
+          if (!deleted) return c.json({ error: "Work item not found" }, 404);
+          await audit.emit({
+            context: loose(c),
+            input: {
+              action: "factory.work_item.deleted",
+              factoryProjectId: deleted.factoryProjectId,
+              targets: [{ type: "work_item", id: deleted.id, name: deleted.title }]
+            }
+          });
+          return c.json({ ok: true });
+        }
+      })
+    ];
+  }
+};
+export {
+  WorkItemRoutes,
+  parseCreateWorkItem,
+  parseUpdateWorkItem
+};
+//# sourceMappingURL=work-items.js.map