@vercel/factory 0.0.17 → 0.0.19

package/dist/approval-access.d.mts

@@ -1,6 +1,6 @@
 import { TaskId } from "./schema/id.mjs";
-import { RepositorySlug } from "./schema/repository.mjs";
 import { Task } from "./schema/task.mjs";
+import { RepositorySlug } from "./schema/repository.mjs";
 import { FactoryStores } from "./store/engine.mjs";
 import { ApprovalView } from "./approval-contracts.mjs";
 //#region src/approval-access.d.ts

package/dist/approval-contracts.d.mts

@@ -1,9 +1,8 @@
-import { TaskId } from "./schema/id.mjs";
-import { RepositorySlug } from "./schema/repository.mjs";
 import { JsonValue } from "./schema/work.mjs";
 import { Task, TaskKind } from "./schema/task.mjs";
 import "./workflows.mjs";
 import { ReceiptKind, ReceiptPhase, ReceiptState } from "./schema/receipt.mjs";
+import { RepositorySlug } from "./schema/repository.mjs";
 import "./tasks.mjs";
 import "./receipts.mjs";
 import { z } from "zod";
@@ -678,7 +677,7 @@ declare const approvalPageSchema: z.ZodObject<{
     }, z.core.$strict>>;
   }, z.core.$strip>>>;
   totalCount: z.ZodOptional<z.ZodNumber>;
-  nextCursor: z.ZodNullable<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 /** Authorized Task proposal with repository, finding, and decision context. */
 type ApprovalView = z.infer<typeof approvalViewSchema>;
@@ -691,7 +690,7 @@ interface ApprovalListOptions {
   readonly query?: string;
   readonly sort?: "created" | "priority" | "decided";
   readonly limit?: number;
-  readonly cursor?: TaskId;
+  readonly cursor?: string;
 }
 //#endregion
 export { ApiPrincipal, ApprovalListOptions, ApprovalPage, ApprovalView, approvalPageSchema, approvalViewSchema };

package/dist/approval-contracts.mjs

@@ -1,4 +1,3 @@
-import { taskIdSchema } from "./schema/id.mjs";
 import { repositorySlugSchema } from "./schema/repository.mjs";
 import { taskSchema } from "./schema/task.mjs";
 import { receiptSchema } from "./schema/receipt.mjs";
@@ -19,7 +18,7 @@ const approvalPageSchema = z.object({
 	actor: z.string().describe("Authenticated actor used for decision attribution."),
 	items: z.array(approvalViewSchema).readonly().describe("Authorized approvals in the requested order."),
 	totalCount: z.number().int().nonnegative().optional().describe("Number of authorized approvals matching all filters, before pagination."),
-	nextCursor: taskIdSchema.nullable().describe("Continue this filtered listing after this Task ID.")
+	nextCursor: z.string().max(8192).nullable().describe("Opaque continuation bound to this approval query.")
 });
 //#endregion
 export { approvalPageSchema, approvalRequestSchema, approvalViewSchema };

package/dist/approval-contracts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"approval-contracts.mjs","names":[],"sources":["../src/approval-contracts.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { taskIdSchema, type TaskId } from \"./schema/id\";\nimport { taskSchema } from \"./schema/task\";\nimport { receiptSchema } from \"./schema/receipt\";\nimport { findingSchema } from \"./schema/finding\";\nimport { repositorySlugSchema, type RepositorySlug } from \"./schema/repository\";\n\n/** Workspace owner and optional individually authenticated actor at the approval boundary. */\nexport interface ApiPrincipal {\n  /** Workspace identity used for existing conversation ownership. */\n  readonly id: string;\n  /** Individually authenticated, provider-qualified actor; absent for anonymous/workload access. */\n  readonly actor?: string;\n}\n\n/** Validates the stable human reason attached to an approval decision. */\nexport const approvalRequestSchema = z.strictObject({\n  reason: z\n    .string()\n    .trim()\n    .min(1)\n    .max(2000)\n    .optional()\n    .describe(\"Reason for the decision; required for rejection. Retain unchanged for retries.\"),\n});\n/** Validates one authorized approval proposal and its immutable decision state. */\nexport const approvalViewSchema = z.object({\n  task: taskSchema.describe(\"Task requiring or carrying a human decision.\"),\n  repositories: z\n    .array(repositorySlugSchema)\n    .readonly()\n    .describe(\"Configured repository names for this Task.\"),\n  finding: findingSchema.nullable().describe(\"Finding that prompted the Task, when available.\"),\n  decision: receiptSchema\n    .nullable()\n    .describe(\"Immutable decision receipt, or null before a decision.\"),\n});\n/** Validates a filtered, cursor-paginated page of approval proposals. */\nexport const approvalPageSchema = z.object({\n  actor: z.string().describe(\"Authenticated actor used for decision attribution.\"),\n  items: z\n    .array(approvalViewSchema)\n    .readonly()\n    .describe(\"Authorized approvals in the requested order.\"),\n  totalCount: z\n    .number()\n    .int()\n    .nonnegative()\n    .optional()\n    .describe(\"Number of authorized approvals matching all filters, before pagination.\"),\n  nextCursor: taskIdSchema\n    .nullable()\n    .describe(\"Continue this filtered listing after this Task ID.\"),\n});\n/** Authorized Task proposal with repository, finding, and decision context. */\nexport type ApprovalView = z.infer<typeof approvalViewSchema>;\n/** Filtered, cursor-paginated approval proposals for one authorized actor. */\nexport type ApprovalPage = z.infer<typeof approvalPageSchema>;\n/** Filters, ordering, and cursor controls for approval discovery. */\nexport interface ApprovalListOptions {\n  readonly repository?: RepositorySlug;\n  readonly status?: \"pending\" | \"decided\" | \"all\";\n  readonly query?: string;\n  readonly sort?: \"created\" | \"priority\" | \"decided\";\n  readonly limit?: number;\n  readonly cursor?: TaskId;\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,wBAAwB,EAAE,aAAa,EAClD,QAAQ,EACL,OAAO,CAAC,CACR,KAAK,CAAC,CACN,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,CAAC,CACV,SAAS,gFAAgF,EAC9F,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,MAAM,WAAW,SAAS,8CAA8C;CACxE,cAAc,EACX,MAAM,oBAAoB,CAAC,CAC3B,SAAS,CAAC,CACV,SAAS,4CAA4C;CACxD,SAAS,cAAc,SAAS,CAAC,CAAC,SAAS,iDAAiD;CAC5F,UAAU,cACP,SAAS,CAAC,CACV,SAAS,wDAAwD;AACtE,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,oDAAoD;CAC/E,OAAO,EACJ,MAAM,kBAAkB,CAAC,CACzB,SAAS,CAAC,CACV,SAAS,8CAA8C;CAC1D,YAAY,EACT,OAAO,CAAC,CACR,IAAI,CAAC,CACL,YAAY,CAAC,CACb,SAAS,CAAC,CACV,SAAS,yEAAyE;CACrF,YAAY,aACT,SAAS,CAAC,CACV,SAAS,oDAAoD;AAClE,CAAC"}
+{"version":3,"file":"approval-contracts.mjs","names":[],"sources":["../src/approval-contracts.ts"],"sourcesContent":["import { z } from \"zod\";\n\nimport { taskSchema } from \"./schema/task\";\nimport { receiptSchema } from \"./schema/receipt\";\nimport { findingSchema } from \"./schema/finding\";\nimport { repositorySlugSchema, type RepositorySlug } from \"./schema/repository\";\n\n/** Workspace owner and optional individually authenticated actor at the approval boundary. */\nexport interface ApiPrincipal {\n  /** Workspace identity used for existing conversation ownership. */\n  readonly id: string;\n  /** Individually authenticated, provider-qualified actor; absent for anonymous/workload access. */\n  readonly actor?: string;\n}\n\n/** Validates the stable human reason attached to an approval decision. */\nexport const approvalRequestSchema = z.strictObject({\n  reason: z\n    .string()\n    .trim()\n    .min(1)\n    .max(2000)\n    .optional()\n    .describe(\"Reason for the decision; required for rejection. Retain unchanged for retries.\"),\n});\n/** Validates one authorized approval proposal and its immutable decision state. */\nexport const approvalViewSchema = z.object({\n  task: taskSchema.describe(\"Task requiring or carrying a human decision.\"),\n  repositories: z\n    .array(repositorySlugSchema)\n    .readonly()\n    .describe(\"Configured repository names for this Task.\"),\n  finding: findingSchema.nullable().describe(\"Finding that prompted the Task, when available.\"),\n  decision: receiptSchema\n    .nullable()\n    .describe(\"Immutable decision receipt, or null before a decision.\"),\n});\n/** Validates a filtered, cursor-paginated page of approval proposals. */\nexport const approvalPageSchema = z.object({\n  actor: z.string().describe(\"Authenticated actor used for decision attribution.\"),\n  items: z\n    .array(approvalViewSchema)\n    .readonly()\n    .describe(\"Authorized approvals in the requested order.\"),\n  totalCount: z\n    .number()\n    .int()\n    .nonnegative()\n    .optional()\n    .describe(\"Number of authorized approvals matching all filters, before pagination.\"),\n  nextCursor: z\n    .string()\n    .max(8192)\n    .nullable()\n    .describe(\"Opaque continuation bound to this approval query.\"),\n});\n/** Authorized Task proposal with repository, finding, and decision context. */\nexport type ApprovalView = z.infer<typeof approvalViewSchema>;\n/** Filtered, cursor-paginated approval proposals for one authorized actor. */\nexport type ApprovalPage = z.infer<typeof approvalPageSchema>;\n/** Filters, ordering, and cursor controls for approval discovery. */\nexport interface ApprovalListOptions {\n  readonly repository?: RepositorySlug;\n  readonly status?: \"pending\" | \"decided\" | \"all\";\n  readonly query?: string;\n  readonly sort?: \"created\" | \"priority\" | \"decided\";\n  readonly limit?: number;\n  readonly cursor?: string;\n}\n"],"mappings":";;;;;;;AAgBA,MAAa,wBAAwB,EAAE,aAAa,EAClD,QAAQ,EACL,OAAO,CAAC,CACR,KAAK,CAAC,CACN,IAAI,CAAC,CAAC,CACN,IAAI,GAAI,CAAC,CACT,SAAS,CAAC,CACV,SAAS,gFAAgF,EAC9F,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,MAAM,WAAW,SAAS,8CAA8C;CACxE,cAAc,EACX,MAAM,oBAAoB,CAAC,CAC3B,SAAS,CAAC,CACV,SAAS,4CAA4C;CACxD,SAAS,cAAc,SAAS,CAAC,CAAC,SAAS,iDAAiD;CAC5F,UAAU,cACP,SAAS,CAAC,CACV,SAAS,wDAAwD;AACtE,CAAC;;AAED,MAAa,qBAAqB,EAAE,OAAO;CACzC,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,oDAAoD;CAC/E,OAAO,EACJ,MAAM,kBAAkB,CAAC,CACzB,SAAS,CAAC,CACV,SAAS,8CAA8C;CAC1D,YAAY,EACT,OAAO,CAAC,CACR,IAAI,CAAC,CACL,YAAY,CAAC,CACb,SAAS,CAAC,CACV,SAAS,yEAAyE;CACrF,YAAY,EACT,OAAO,CAAC,CACR,IAAI,IAAI,CAAC,CACT,SAAS,CAAC,CACV,SAAS,mDAAmD;AACjE,CAAC"}

package/dist/blob/index.d.mts

@@ -1,5 +1,5 @@
-import { MillisecondClock } from "../schema/common.mjs";
 import { StoreDriver } from "../store/driver.mjs";
+import { MillisecondClock } from "../schema/common.mjs";
 import { ArtifactInput, ArtifactKind, ArtifactRef, ArtifactStore, ReadArtifactInput, artifactReference, createArtifactStore, parseArtifactRef } from "./artifacts.mjs";
 //#region src/blob/index.d.ts
 /** Blob content paired with the ETag required for compare-and-swap persistence. */

package/dist/budget.mjs

@@ -1,3 +1,4 @@
+import { collectFactoryRecords } from "./store/iterate.mjs";
 import { factoryIdSchema } from "./schema/id.mjs";
 import { budgetMonthSchema } from "./schema/budget.mjs";
 import { createHash } from "node:crypto";
@@ -10,6 +11,16 @@ import { createHash } from "node:crypto";
 function deriveFactoryId(seed) {
 	return factoryIdSchema.parse(`fac_${createHash("sha256").update(seed).digest("hex").slice(0, 32)}`);
 }
+async function budgetTasks(stores) {
+	const pages = await Promise.all(["reservedUsd", "settledUsd"].map((field) => collectFactoryRecords(stores.tasks.list, {
+		limit: 100,
+		fields: [{
+			path: [field],
+			test: "exists"
+		}]
+	})));
+	return [...new Map(pages.flat().map((task) => [task.id, task])).values()];
+}
 /** The budget month ("YYYY-MM", UTC) a timestamp falls into. */
 function budgetMonthOf(isoDateTime) {
 	return budgetMonthSchema.parse(isoDateTime.slice(0, 7));
@@ -61,7 +72,13 @@ async function sweepSettlements(stores, options = {}) {
 	const graceMs = (options.graceMinutes ?? 10) * 6e4;
 	const nowMs = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
 	const settled = [];
-	for (const task of options.tasks ?? await stores.tasks.list()) {
+	for (const task of options.tasks ?? await collectFactoryRecords(stores.tasks.list, {
+		limit: 100,
+		fields: [{
+			path: ["reservedUsd"],
+			test: "exists"
+		}]
+	})) {
 		if (task.reservedUsd === void 0 || task.settledUsd !== void 0) continue;
 		if (!TERMINAL_TASK_STATES.has(task.state)) continue;
 		if (nowMs - Date.parse(task.updatedAt) < graceMs) continue;
@@ -95,7 +112,7 @@ async function sweepBudget(stores, options) {
 		month,
 		limits: options.limits
 	});
-	const spendUsd = computeMonthSpendUsd(options.tasks ?? await stores.tasks.list(), month);
+	const spendUsd = computeMonthSpendUsd(options.tasks ?? await budgetTasks(stores), month);
 	if (options.enforce === false) return {
 		month,
 		spendUsd,
@@ -142,6 +159,6 @@ async function sweepBudget(stores, options) {
 	};
 }
 //#endregion
-export { budgetMonthOf, budgetStatus, canReserve, computeMonthSpendUsd, deriveFactoryId, sweepBudget, sweepSettlements };
+export { budgetMonthOf, budgetStatus, budgetTasks, canReserve, computeMonthSpendUsd, deriveFactoryId, sweepBudget, sweepSettlements };
 
 //# sourceMappingURL=budget.mjs.map

package/dist/budget.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"budget.mjs","names":[],"sources":["../src/budget.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { DateClock } from \"./schema/common\";\nimport { factoryIdSchema, type FactoryId, type TaskId } from \"./schema/id\";\nimport { budgetMonthSchema, type BudgetLimits, type BudgetMonth } from \"./schema/budget\";\nimport type { Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/**\n * Stable factory identity for budget rows. Nothing mints factory ids yet, so\n * the app derives one from a deployment-stable seed such as the Vercel\n * project id.\n */\nexport function deriveFactoryId(seed: string): FactoryId {\n  return factoryIdSchema.parse(\n    `fac_${createHash(\"sha256\").update(seed).digest(\"hex\").slice(0, 32)}`,\n  );\n}\n\n/** The budget month (\"YYYY-MM\", UTC) a timestamp falls into. */\nexport function budgetMonthOf(isoDateTime: string): BudgetMonth {\n  return budgetMonthSchema.parse(isoDateTime.slice(0, 7));\n}\n\n// Currency math runs in integer micro-dollars so decimal limits compare\n// exactly; 0.1 + 0.2 must never refuse an exact-fit reservation.\nfunction microsOf(usd: number): number {\n  return Math.round(usd * 1_000_000);\n}\n\n/**\n * Monthly spend is derived from task rows, never stored: each task counts its\n * settled cost once that exists, otherwise its held reservation. A task\n * settles once, so a settled row never also counts its reservation.\n * Attribution uses the reservation time so tasks that wait across a month\n * boundary charge the month they actually ran in.\n */\nexport function computeMonthSpendUsd(tasks: readonly Task[], month: BudgetMonth): number {\n  let spendMicros = 0;\n  for (const task of tasks) {\n    if (budgetMonthOf(task.reservedAt ?? task.createdAt) !== month) {\n      continue;\n    }\n    spendMicros += microsOf(task.settledUsd ?? task.reservedUsd ?? 0);\n  }\n  return spendMicros / 1_000_000;\n}\n\n/** Derived monthly capacity state before another per-Task reservation. */\nexport type BudgetStatus = \"ok\" | \"warning\" | \"exhausted\";\n\n/**\n * True when one more per-task slice fits under the monthly total. Dispatch\n * refuses on this exact predicate and budgetStatus reports \"exhausted\" on its\n * negation, so refusing and reporting can never disagree.\n */\nexport function canReserve(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">,\n): boolean {\n  return microsOf(spendUsd) + microsOf(limits.perTaskReservationUsd) <= microsOf(limits.totalUsd);\n}\n\n/** Classify monthly spend using the same exact-fit predicate enforced by dispatch. */\nexport function budgetStatus(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\" | \"warningPercent\">,\n): BudgetStatus {\n  if (!canReserve(spendUsd, limits)) {\n    return \"exhausted\";\n  }\n  // Integer comparison: spend/total * 100 >= warningPercent without float\n  // drift on decimal limits.\n  if (microsOf(spendUsd) * 100 >= microsOf(limits.totalUsd) * limits.warningPercent) {\n    return \"warning\";\n  }\n  return \"ok\";\n}\n\nconst TERMINAL_TASK_STATES = new Set<Task[\"state\"]>([\"succeeded\", \"failed\", \"cancelled\"]);\n\n/** Grace period, clock, and optional snapshot for terminal usage settlement. */\nexport interface SweepSettlementsOptions {\n  /** How long a terminal task waits for late usage before the sweep settles it. */\n  graceMinutes?: number;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/** Task-local charges newly settled by one reconciliation pass. */\nexport interface SweepSettlementsResult {\n  readonly settled: readonly { readonly taskId: TaskId; readonly totalUsd: number }[];\n}\n\n/** Task capability required to settle terminal reservations. */\nexport type SettlementSweepStores = Pick<FactoryStores, \"tasks\">;\n\n/**\n * Settle reserved terminal tasks the session hook did not: a task that ended\n * after its session (a change verified later) or whose session died. Settles\n * at the recorded usage, or at zero with a warning reason when none was\n * recorded within the grace window.\n */\nexport async function sweepSettlements(\n  stores: SettlementSweepStores,\n  options: SweepSettlementsOptions = {},\n): Promise<SweepSettlementsResult> {\n  const graceMs = (options.graceMinutes ?? 10) * 60_000;\n  const nowMs = (options.now ?? (() => new Date()))().getTime();\n  const settled: { taskId: TaskId; totalUsd: number }[] = [];\n  for (const task of options.tasks ?? (await stores.tasks.list())) {\n    if (task.reservedUsd === undefined || task.settledUsd !== undefined) {\n      continue;\n    }\n    if (!TERMINAL_TASK_STATES.has(task.state)) {\n      continue;\n    }\n    if (nowMs - Date.parse(task.updatedAt) < graceMs) {\n      continue;\n    }\n    // A concurrent writer (operator retry, another sweep) may move the task\n    // between the list and the settle; skip it rather than aborting the pass.\n    const totalUsd = task.usage?.costUsd ?? 0;\n    try {\n      const result = await stores.tasks.settle(task.id, {\n        cost: { totalUsd },\n        ...{\n          reason:\n            task.usage === undefined\n              ? \"usage missing after ten minutes; settled at zero\"\n              : \"measured usage settled by sweep\",\n        },\n      });\n      // Report this settlement's amount, not the task's accumulated total.\n      settled.push({ taskId: result.id, totalUsd });\n    } catch {\n      continue;\n    }\n  }\n  return { settled };\n}\n\n/** Owner-only notification emitted when monthly spend crosses a budget threshold. */\nexport interface BudgetNotice {\n  outcome: \"budget_warning\" | \"budget_exhausted\";\n  month: BudgetMonth;\n  spendUsd: number;\n  limits: BudgetLimits;\n}\n\n/** Monthly limits, delivery hook, and optional snapshot used for budget reconciliation. */\nexport interface BudgetSweepOptions {\n  factoryId: FactoryId;\n  limits: BudgetLimits;\n  /** Defaults to true. False reports spending without threshold checks or budget notices. */\n  enforce?: boolean;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  now?: DateClock;\n  /** Owner-only delivery; invoked at most once per month per outcome. */\n  notify?: (notice: BudgetNotice) => Promise<void>;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/**\n * Derived monthly spend and exact notice outcome produced by budget reconciliation.\n * `stamped` means this sweep recorded the threshold, `already_stamped` means no\n * new stamp was needed, and `delivery_failed` remains eligible for retry.\n */\nexport type BudgetSweepResult =\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"disabled\";\n      readonly noticeState: \"not_applicable\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"ok\";\n      readonly noticeState: \"not_applicable\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"warning\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"exhausted\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    };\n\n/** Budget and Task capabilities required to reconcile monthly budget thresholds. */\nexport type BudgetSweepStores = Pick<FactoryStores, \"budgets\" | \"tasks\">;\n\n/**\n * Ensure the month's budget row, derive spend, and record threshold crossings\n * write-once. Delivery comes first and the stamp only lands after it, so a\n * failed notification retries on the next sweep instead of being lost; the\n * write-once stamp still keeps each threshold to one message per month.\n */\nexport async function sweepBudget(\n  stores: BudgetSweepStores,\n  options: BudgetSweepOptions,\n): Promise<BudgetSweepResult> {\n  const now = options.now ?? (() => new Date());\n  const month = options.month ?? budgetMonthOf(now().toISOString());\n  const budget = await stores.budgets.ensure({\n    factoryId: options.factoryId,\n    month,\n    limits: options.limits,\n  });\n  const spendUsd = computeMonthSpendUsd(options.tasks ?? (await stores.tasks.list()), month);\n  if (options.enforce === false)\n    return { month, spendUsd, status: \"disabled\", noticeState: \"not_applicable\" };\n  const status = budgetStatus(spendUsd, options.limits);\n\n  async function crossThreshold(\n    notice: \"warning\" | \"exhausted\",\n    outcome: BudgetNotice[\"outcome\"],\n  ): Promise<\"stamped\" | \"already_stamped\" | \"delivery_failed\"> {\n    const field = notice === \"warning\" ? \"warningAt\" : \"exhaustedAt\";\n    if (budget.notices[field] !== undefined) {\n      return \"already_stamped\";\n    }\n    if (options.notify !== undefined) {\n      try {\n        await options.notify({ outcome, month, spendUsd, limits: options.limits });\n      } catch {\n        // Leave the notice unstamped so the next sweep retries delivery.\n        return \"delivery_failed\";\n      }\n    }\n    return (await stores.budgets.stampNotice(month, notice)).stamped\n      ? \"stamped\"\n      : \"already_stamped\";\n  }\n\n  if (status === \"exhausted\") {\n    const noticeState = await crossThreshold(\"exhausted\", \"budget_exhausted\");\n    // The warning threshold was necessarily crossed too; stamp it silently so\n    // a later settle-down cannot deliver \"warning\" after \"exhausted\".\n    if (budget.notices.warningAt === undefined) {\n      await stores.budgets.stampNotice(month, \"warning\");\n    }\n    return { month, spendUsd, status, noticeState };\n  }\n  if (status === \"warning\") {\n    const noticeState = await crossThreshold(\"warning\", \"budget_warning\");\n    return { month, spendUsd, status, noticeState };\n  }\n  return { month, spendUsd, status, noticeState: \"not_applicable\" };\n}\n"],"mappings":"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"}
+{"version":3,"file":"budget.mjs","names":[],"sources":["../src/budget.ts"],"sourcesContent":["import { collectFactoryRecords } from \"./store/iterate\";\nimport { createHash } from \"node:crypto\";\nimport type { DateClock } from \"./schema/common\";\nimport { factoryIdSchema, type FactoryId, type TaskId } from \"./schema/id\";\nimport { budgetMonthSchema, type BudgetLimits, type BudgetMonth } from \"./schema/budget\";\nimport type { Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/**\n * Stable factory identity for budget rows. Nothing mints factory ids yet, so\n * the app derives one from a deployment-stable seed such as the Vercel\n * project id.\n */\nexport function deriveFactoryId(seed: string): FactoryId {\n  return factoryIdSchema.parse(\n    `fac_${createHash(\"sha256\").update(seed).digest(\"hex\").slice(0, 32)}`,\n  );\n}\n\nexport async function budgetTasks(stores: Pick<FactoryStores, \"tasks\">): Promise<Task[]> {\n  const pages = await Promise.all(\n    [\"reservedUsd\", \"settledUsd\"].map((field) =>\n      collectFactoryRecords(stores.tasks.list, {\n        limit: 100,\n        fields: [{ path: [field], test: \"exists\" }],\n      }),\n    ),\n  );\n  return [...new Map(pages.flat().map((task) => [task.id, task])).values()];\n}\n\n/** The budget month (\"YYYY-MM\", UTC) a timestamp falls into. */\nexport function budgetMonthOf(isoDateTime: string): BudgetMonth {\n  return budgetMonthSchema.parse(isoDateTime.slice(0, 7));\n}\n\n// Currency math runs in integer micro-dollars so decimal limits compare\n// exactly; 0.1 + 0.2 must never refuse an exact-fit reservation.\nfunction microsOf(usd: number): number {\n  return Math.round(usd * 1_000_000);\n}\n\n/**\n * Monthly spend is derived from task rows, never stored: each task counts its\n * settled cost once that exists, otherwise its held reservation. A task\n * settles once, so a settled row never also counts its reservation.\n * Attribution uses the reservation time so tasks that wait across a month\n * boundary charge the month they actually ran in.\n */\nexport function computeMonthSpendUsd(tasks: readonly Task[], month: BudgetMonth): number {\n  let spendMicros = 0;\n  for (const task of tasks) {\n    if (budgetMonthOf(task.reservedAt ?? task.createdAt) !== month) {\n      continue;\n    }\n    spendMicros += microsOf(task.settledUsd ?? task.reservedUsd ?? 0);\n  }\n  return spendMicros / 1_000_000;\n}\n\n/** Derived monthly capacity state before another per-Task reservation. */\nexport type BudgetStatus = \"ok\" | \"warning\" | \"exhausted\";\n\n/**\n * True when one more per-task slice fits under the monthly total. Dispatch\n * refuses on this exact predicate and budgetStatus reports \"exhausted\" on its\n * negation, so refusing and reporting can never disagree.\n */\nexport function canReserve(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\">,\n): boolean {\n  return microsOf(spendUsd) + microsOf(limits.perTaskReservationUsd) <= microsOf(limits.totalUsd);\n}\n\n/** Classify monthly spend using the same exact-fit predicate enforced by dispatch. */\nexport function budgetStatus(\n  spendUsd: number,\n  limits: Pick<BudgetLimits, \"totalUsd\" | \"perTaskReservationUsd\" | \"warningPercent\">,\n): BudgetStatus {\n  if (!canReserve(spendUsd, limits)) {\n    return \"exhausted\";\n  }\n  // Integer comparison: spend/total * 100 >= warningPercent without float\n  // drift on decimal limits.\n  if (microsOf(spendUsd) * 100 >= microsOf(limits.totalUsd) * limits.warningPercent) {\n    return \"warning\";\n  }\n  return \"ok\";\n}\n\nconst TERMINAL_TASK_STATES = new Set<Task[\"state\"]>([\"succeeded\", \"failed\", \"cancelled\"]);\n\n/** Grace period, clock, and optional snapshot for terminal usage settlement. */\nexport interface SweepSettlementsOptions {\n  /** How long a terminal task waits for late usage before the sweep settles it. */\n  graceMinutes?: number;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/** Task-local charges newly settled by one reconciliation pass. */\nexport interface SweepSettlementsResult {\n  readonly settled: readonly { readonly taskId: TaskId; readonly totalUsd: number }[];\n}\n\n/** Task capability required to settle terminal reservations. */\nexport type SettlementSweepStores = Pick<FactoryStores, \"tasks\">;\n\n/**\n * Settle reserved terminal tasks the session hook did not: a task that ended\n * after its session (a change verified later) or whose session died. Settles\n * at the recorded usage, or at zero with a warning reason when none was\n * recorded within the grace window.\n */\nexport async function sweepSettlements(\n  stores: SettlementSweepStores,\n  options: SweepSettlementsOptions = {},\n): Promise<SweepSettlementsResult> {\n  const graceMs = (options.graceMinutes ?? 10) * 60_000;\n  const nowMs = (options.now ?? (() => new Date()))().getTime();\n  const settled: { taskId: TaskId; totalUsd: number }[] = [];\n  for (const task of options.tasks ??\n    (await collectFactoryRecords(stores.tasks.list, {\n      limit: 100,\n      fields: [{ path: [\"reservedUsd\"], test: \"exists\" }],\n    }))) {\n    if (task.reservedUsd === undefined || task.settledUsd !== undefined) {\n      continue;\n    }\n    if (!TERMINAL_TASK_STATES.has(task.state)) {\n      continue;\n    }\n    if (nowMs - Date.parse(task.updatedAt) < graceMs) {\n      continue;\n    }\n    // A concurrent writer (operator retry, another sweep) may move the task\n    // between the list and the settle; skip it rather than aborting the pass.\n    const totalUsd = task.usage?.costUsd ?? 0;\n    try {\n      const result = await stores.tasks.settle(task.id, {\n        cost: { totalUsd },\n        ...{\n          reason:\n            task.usage === undefined\n              ? \"usage missing after ten minutes; settled at zero\"\n              : \"measured usage settled by sweep\",\n        },\n      });\n      // Report this settlement's amount, not the task's accumulated total.\n      settled.push({ taskId: result.id, totalUsd });\n    } catch {\n      continue;\n    }\n  }\n  return { settled };\n}\n\n/** Owner-only notification emitted when monthly spend crosses a budget threshold. */\nexport interface BudgetNotice {\n  outcome: \"budget_warning\" | \"budget_exhausted\";\n  month: BudgetMonth;\n  spendUsd: number;\n  limits: BudgetLimits;\n}\n\n/** Monthly limits, delivery hook, and optional snapshot used for budget reconciliation. */\nexport interface BudgetSweepOptions {\n  factoryId: FactoryId;\n  limits: BudgetLimits;\n  /** Defaults to true. False reports spending without threshold checks or budget notices. */\n  enforce?: boolean;\n  /** Defaults to the current UTC month. */\n  month?: BudgetMonth;\n  now?: DateClock;\n  /** Owner-only delivery; invoked at most once per month per outcome. */\n  notify?: (notice: BudgetNotice) => Promise<void>;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n}\n\n/**\n * Derived monthly spend and exact notice outcome produced by budget reconciliation.\n * `stamped` means this sweep recorded the threshold, `already_stamped` means no\n * new stamp was needed, and `delivery_failed` remains eligible for retry.\n */\nexport type BudgetSweepResult =\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"disabled\";\n      readonly noticeState: \"not_applicable\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"ok\";\n      readonly noticeState: \"not_applicable\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"warning\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    }\n  | {\n      readonly month: BudgetMonth;\n      readonly spendUsd: number;\n      readonly status: \"exhausted\";\n      readonly noticeState: \"stamped\" | \"already_stamped\" | \"delivery_failed\";\n    };\n\n/** Budget and Task capabilities required to reconcile monthly budget thresholds. */\nexport type BudgetSweepStores = Pick<FactoryStores, \"budgets\" | \"tasks\">;\n\n/**\n * Ensure the month's budget row, derive spend, and record threshold crossings\n * write-once. Delivery comes first and the stamp only lands after it, so a\n * failed notification retries on the next sweep instead of being lost; the\n * write-once stamp still keeps each threshold to one message per month.\n */\nexport async function sweepBudget(\n  stores: BudgetSweepStores,\n  options: BudgetSweepOptions,\n): Promise<BudgetSweepResult> {\n  const now = options.now ?? (() => new Date());\n  const month = options.month ?? budgetMonthOf(now().toISOString());\n  const budget = await stores.budgets.ensure({\n    factoryId: options.factoryId,\n    month,\n    limits: options.limits,\n  });\n  const spendUsd = computeMonthSpendUsd(options.tasks ?? (await budgetTasks(stores)), month);\n  if (options.enforce === false)\n    return { month, spendUsd, status: \"disabled\", noticeState: \"not_applicable\" };\n  const status = budgetStatus(spendUsd, options.limits);\n\n  async function crossThreshold(\n    notice: \"warning\" | \"exhausted\",\n    outcome: BudgetNotice[\"outcome\"],\n  ): Promise<\"stamped\" | \"already_stamped\" | \"delivery_failed\"> {\n    const field = notice === \"warning\" ? \"warningAt\" : \"exhaustedAt\";\n    if (budget.notices[field] !== undefined) {\n      return \"already_stamped\";\n    }\n    if (options.notify !== undefined) {\n      try {\n        await options.notify({ outcome, month, spendUsd, limits: options.limits });\n      } catch {\n        // Leave the notice unstamped so the next sweep retries delivery.\n        return \"delivery_failed\";\n      }\n    }\n    return (await stores.budgets.stampNotice(month, notice)).stamped\n      ? \"stamped\"\n      : \"already_stamped\";\n  }\n\n  if (status === \"exhausted\") {\n    const noticeState = await crossThreshold(\"exhausted\", \"budget_exhausted\");\n    // The warning threshold was necessarily crossed too; stamp it silently so\n    // a later settle-down cannot deliver \"warning\" after \"exhausted\".\n    if (budget.notices.warningAt === undefined) {\n      await stores.budgets.stampNotice(month, \"warning\");\n    }\n    return { month, spendUsd, status, noticeState };\n  }\n  if (status === \"warning\") {\n    const noticeState = await crossThreshold(\"warning\", \"budget_warning\");\n    return { month, spendUsd, status, noticeState };\n  }\n  return { month, spendUsd, status, noticeState: \"not_applicable\" };\n}\n"],"mappings":"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"}

package/dist/change-verification/brief.d.mts

@@ -1,6 +1,6 @@
-import { Repository } from "../schema/repository.mjs";
 import { Task } from "../schema/task.mjs";
 import { Change } from "../schema/change.mjs";
+import { Repository } from "../schema/repository.mjs";
 //#region src/change-verification/brief.d.ts
 /** Format the starting brief for independently verifying a recorded Change. */
 declare function formatChangeVerificationBrief(task: Task, repository: Repository, change: Change): string;

package/dist/change-verification/dispatch.mjs

@@ -1,3 +1,4 @@
+import { collectFactoryRecords } from "../store/iterate.mjs";
 import { parseAgentRouteBinding } from "../schema/agent-route.mjs";
 import { routeKey, routeTaskWork } from "../agent-routes.mjs";
 import { applyVerificationReport, verificationDelivery, verificationParentAttempt, verificationReportSchema } from "./result.mjs";
@@ -37,7 +38,13 @@ async function ensureChangeVerificationTasks(options) {
 		id: "verification",
 		version: 1
 	});
-	const tasks = options.tasks ?? await stores.tasks.list();
+	const tasks = options.tasks ?? await collectFactoryRecords(stores.tasks.list, {
+		limit: 100,
+		match: [{
+			state: "verifying",
+			work: { route: { id: "code-change" } }
+		}, { work: { route } }]
+	});
 	const existingIds = new Set(tasks.map((task) => task.id));
 	const result = {
 		created: [],

package/dist/change-verification/dispatch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/change-verification/dispatch.ts"],"sourcesContent":["import {\n  parseAgentRouteBinding,\n  routeKey,\n  routeTaskWork,\n  type AgentRouteBinding,\n} from \"../agent-routes\";\nimport type { TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  applyVerificationReport,\n  verificationDelivery,\n  verificationParentAttempt,\n  verificationReportSchema,\n} from \"./result\";\nimport type { PresentVerificationResultInput } from \"./eve-tool\";\n\n/** Store capabilities required to inspect and create verification Tasks. */\nexport type ChangeVerificationStores = Pick<FactoryStores, \"tasks\" | \"changes\" | \"signals\">;\n\n/** Verification Tasks admitted or found idempotently by one reconciliation pass. */\nexport interface EnsureChangeVerificationTasksResult {\n  readonly created: readonly TaskId[];\n  readonly existing: readonly TaskId[];\n}\n\n/** Stores, optional snapshot, and exact verifier route used by one admission pass. */\nexport interface EnsureChangeVerificationTasksOptions {\n  readonly stores: ChangeVerificationStores;\n  readonly tasks?: readonly Task[];\n  readonly route?: AgentRouteBinding;\n  /** Idempotent presentation callback, replayed from the saved outcome after interruption. */\n  readonly presentResult?: (input: PresentVerificationResultInput) => Promise<void>;\n}\n\n/** One verifier snapshot and the workflow adapters needed to recover its saved result. */\nexport interface RecoverChangeVerificationResultOptions extends Omit<\n  EnsureChangeVerificationTasksOptions,\n  \"tasks\"\n> {\n  readonly task: Task;\n}\n\n/**\n * Recover an exact verifier attempt before generic lifecycle policy replaces or escalates it.\n * Returns false when no eligible report exists; storage or presentation errors propagate so callers\n * can defer lifecycle changes and retry the same attempt.\n */\nexport async function recoverChangeVerificationResult(\n  options: RecoverChangeVerificationResultOptions,\n): Promise<boolean> {\n  const { stores, task } = options;\n  const route = options.route ?? parseAgentRouteBinding({ id: \"verification\", version: 1 });\n  if (\n    !task.work.route ||\n    routeKey(task.work.route) !== routeKey(route) ||\n    ![\"running\", \"succeeded\", \"failed\"].includes(task.state)\n  )\n    return false;\n  const report = await stores.signals.getByDelivery(verificationDelivery(task));\n  if (!report) return false;\n  const outcome = await applyVerificationReport(stores, report);\n  if (!outcome.recorded) return false;\n  const { output } = verificationReportSchema.parse(report.payload);\n  await options.presentResult?.({\n    taskId: task.id,\n    changeId: output.changeId,\n    verdict: output.verdict,\n    summary: output.summary,\n  });\n  return true;\n}\n\n/** Admit one verification child per producer attempt and recover its recorded outcome. */\nexport async function ensureChangeVerificationTasks(\n  options: EnsureChangeVerificationTasksOptions,\n): Promise<EnsureChangeVerificationTasksResult> {\n  const { stores } = options;\n  const route = options.route ?? parseAgentRouteBinding({ id: \"verification\", version: 1 });\n  const tasks = options.tasks ?? (await stores.tasks.list());\n  const existingIds = new Set(tasks.map((task) => task.id));\n  const result: { created: TaskId[]; existing: TaskId[] } = { created: [], existing: [] };\n  for (const task of tasks) {\n    if (await recoverChangeVerificationResult({ ...options, task })) result.existing.push(task.id);\n  }\n  const sources = tasks.filter(\n    (task) =>\n      task.work.route?.id === \"code-change\" &&\n      task.state === \"verifying\" &&\n      task.changeId !== undefined,\n  );\n\n  for (const snapshot of sources) {\n    const source = await stores.tasks.get(snapshot.id);\n    if (\n      !source ||\n      source.state !== \"verifying\" ||\n      source.attempt !== snapshot.attempt ||\n      source.changeId !== snapshot.changeId\n    )\n      continue;\n    const existing = tasks.find(\n      (task) =>\n        task.work.route !== undefined &&\n        routeKey(task.work.route) === routeKey(route) &&\n        task.parentTaskId === source.id &&\n        task.changeId === source.changeId &&\n        verificationParentAttempt(task) === source.attempt,\n    );\n    if (existing !== undefined) {\n      if (!result.existing.includes(existing.id)) result.existing.push(existing.id);\n      continue;\n    }\n    const verification = await stores.tasks.create({\n      repositoryIds: source.repositoryIds,\n      kind: \"verification\",\n      work: routeTaskWork({\n        route: route,\n        title: `Verify change ${source.changeId}`,\n        input: {\n          changeId: source.changeId!,\n          parentAttempt: source.attempt,\n        },\n      }),\n      origin: {},\n      parentTaskId: source.id,\n      replyTo: source.replyTo,\n      changeId: source.changeId,\n      dedupeKey: `verification:${source.id}:${source.attempt}:${source.changeId}:${routeKey(route)}`,\n    });\n    (existingIds.has(verification.id) ? result.existing : result.created).push(verification.id);\n  }\n\n  return result;\n}\n"],"mappings":";;;;;;;;;AAgDA,eAAsB,gCACpB,SACkB;CAClB,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;EAAE,IAAI;EAAgB,SAAS;CAAE,CAAC;CACxF,IACE,CAAC,KAAK,KAAK,SACX,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,KAAK,KAC5C,CAAC;EAAC;EAAW;EAAa;CAAQ,CAAC,CAAC,SAAS,KAAK,KAAK,GAEvD,OAAO;CACT,MAAM,SAAS,MAAM,OAAO,QAAQ,cAAc,qBAAqB,IAAI,CAAC;CAC5E,IAAI,CAAC,QAAQ,OAAO;CAEpB,IAAI,EAAC,MADiB,wBAAwB,QAAQ,MAAM,EAAA,CAC/C,UAAU,OAAO;CAC9B,MAAM,EAAE,WAAW,yBAAyB,MAAM,OAAO,OAAO;CAChE,MAAM,QAAQ,gBAAgB;EAC5B,QAAQ,KAAK;EACb,UAAU,OAAO;EACjB,SAAS,OAAO;EAChB,SAAS,OAAO;CAClB,CAAC;CACD,OAAO;AACT;;AAGA,eAAsB,8BACpB,SAC8C;CAC9C,MAAM,EAAE,WAAW;CACnB,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;EAAE,IAAI;EAAgB,SAAS;CAAE,CAAC;CACxF,MAAM,QAAQ,QAAQ,SAAU,MAAM,OAAO,MAAM,KAAK;CACxD,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,EAAE,CAAC;CACxD,MAAM,SAAoD;EAAE,SAAS,CAAC;EAAG,UAAU,CAAC;CAAE;CACtF,KAAK,MAAM,QAAQ,OACjB,IAAI,MAAM,gCAAgC;EAAE,GAAG;EAAS;CAAK,CAAC,GAAG,OAAO,SAAS,KAAK,KAAK,EAAE;CAE/F,MAAM,UAAU,MAAM,QACnB,SACC,KAAK,KAAK,OAAO,OAAO,iBACxB,KAAK,UAAU,eACf,KAAK,aAAa,KAAA,CACtB;CAEA,KAAK,MAAM,YAAY,SAAS;EAC9B,MAAM,SAAS,MAAM,OAAO,MAAM,IAAI,SAAS,EAAE;EACjD,IACE,CAAC,UACD,OAAO,UAAU,eACjB,OAAO,YAAY,SAAS,WAC5B,OAAO,aAAa,SAAS,UAE7B;EACF,MAAM,WAAW,MAAM,MACpB,SACC,KAAK,KAAK,UAAU,KAAA,KACpB,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,KAAK,KAC5C,KAAK,iBAAiB,OAAO,MAC7B,KAAK,aAAa,OAAO,YACzB,0BAA0B,IAAI,MAAM,OAAO,OAC/C;EACA,IAAI,aAAa,KAAA,GAAW;GAC1B,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,EAAE,GAAG,OAAO,SAAS,KAAK,SAAS,EAAE;GAC5E;EACF;EACA,MAAM,eAAe,MAAM,OAAO,MAAM,OAAO;GAC7C,eAAe,OAAO;GACtB,MAAM;GACN,MAAM,cAAc;IACX;IACP,OAAO,iBAAiB,OAAO;IAC/B,OAAO;KACL,UAAU,OAAO;KACjB,eAAe,OAAO;IACxB;GACF,CAAC;GACD,QAAQ,CAAC;GACT,cAAc,OAAO;GACrB,SAAS,OAAO;GAChB,UAAU,OAAO;GACjB,WAAW,gBAAgB,OAAO,GAAG,GAAG,OAAO,QAAQ,GAAG,OAAO,SAAS,GAAG,SAAS,KAAK;EAC7F,CAAC;EACD,CAAC,YAAY,IAAI,aAAa,EAAE,IAAI,OAAO,WAAW,OAAO,QAAA,CAAS,KAAK,aAAa,EAAE;CAC5F;CAEA,OAAO;AACT"}
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/change-verification/dispatch.ts"],"sourcesContent":["import { collectFactoryRecords } from \"../store/iterate\";\nimport {\n  parseAgentRouteBinding,\n  routeKey,\n  routeTaskWork,\n  type AgentRouteBinding,\n} from \"../agent-routes\";\nimport type { TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport {\n  applyVerificationReport,\n  verificationDelivery,\n  verificationParentAttempt,\n  verificationReportSchema,\n} from \"./result\";\nimport type { PresentVerificationResultInput } from \"./eve-tool\";\n\n/** Store capabilities required to inspect and create verification Tasks. */\nexport type ChangeVerificationStores = Pick<FactoryStores, \"tasks\" | \"changes\" | \"signals\">;\n\n/** Verification Tasks admitted or found idempotently by one reconciliation pass. */\nexport interface EnsureChangeVerificationTasksResult {\n  readonly created: readonly TaskId[];\n  readonly existing: readonly TaskId[];\n}\n\n/** Stores, optional snapshot, and exact verifier route used by one admission pass. */\nexport interface EnsureChangeVerificationTasksOptions {\n  readonly stores: ChangeVerificationStores;\n  readonly tasks?: readonly Task[];\n  readonly route?: AgentRouteBinding;\n  /** Idempotent presentation callback, replayed from the saved outcome after interruption. */\n  readonly presentResult?: (input: PresentVerificationResultInput) => Promise<void>;\n}\n\n/** One verifier snapshot and the workflow adapters needed to recover its saved result. */\nexport interface RecoverChangeVerificationResultOptions extends Omit<\n  EnsureChangeVerificationTasksOptions,\n  \"tasks\"\n> {\n  readonly task: Task;\n}\n\n/**\n * Recover an exact verifier attempt before generic lifecycle policy replaces or escalates it.\n * Returns false when no eligible report exists; storage or presentation errors propagate so callers\n * can defer lifecycle changes and retry the same attempt.\n */\nexport async function recoverChangeVerificationResult(\n  options: RecoverChangeVerificationResultOptions,\n): Promise<boolean> {\n  const { stores, task } = options;\n  const route = options.route ?? parseAgentRouteBinding({ id: \"verification\", version: 1 });\n  if (\n    !task.work.route ||\n    routeKey(task.work.route) !== routeKey(route) ||\n    ![\"running\", \"succeeded\", \"failed\"].includes(task.state)\n  )\n    return false;\n  const report = await stores.signals.getByDelivery(verificationDelivery(task));\n  if (!report) return false;\n  const outcome = await applyVerificationReport(stores, report);\n  if (!outcome.recorded) return false;\n  const { output } = verificationReportSchema.parse(report.payload);\n  await options.presentResult?.({\n    taskId: task.id,\n    changeId: output.changeId,\n    verdict: output.verdict,\n    summary: output.summary,\n  });\n  return true;\n}\n\n/** Admit one verification child per producer attempt and recover its recorded outcome. */\nexport async function ensureChangeVerificationTasks(\n  options: EnsureChangeVerificationTasksOptions,\n): Promise<EnsureChangeVerificationTasksResult> {\n  const { stores } = options;\n  const route = options.route ?? parseAgentRouteBinding({ id: \"verification\", version: 1 });\n  const tasks =\n    options.tasks ??\n    (await collectFactoryRecords(stores.tasks.list, {\n      limit: 100,\n      match: [{ state: \"verifying\", work: { route: { id: \"code-change\" } } }, { work: { route } }],\n    }));\n  const existingIds = new Set(tasks.map((task) => task.id));\n  const result: { created: TaskId[]; existing: TaskId[] } = { created: [], existing: [] };\n  for (const task of tasks) {\n    if (await recoverChangeVerificationResult({ ...options, task })) result.existing.push(task.id);\n  }\n  const sources = tasks.filter(\n    (task) =>\n      task.work.route?.id === \"code-change\" &&\n      task.state === \"verifying\" &&\n      task.changeId !== undefined,\n  );\n\n  for (const snapshot of sources) {\n    const source = await stores.tasks.get(snapshot.id);\n    if (\n      !source ||\n      source.state !== \"verifying\" ||\n      source.attempt !== snapshot.attempt ||\n      source.changeId !== snapshot.changeId\n    )\n      continue;\n    const existing = tasks.find(\n      (task) =>\n        task.work.route !== undefined &&\n        routeKey(task.work.route) === routeKey(route) &&\n        task.parentTaskId === source.id &&\n        task.changeId === source.changeId &&\n        verificationParentAttempt(task) === source.attempt,\n    );\n    if (existing !== undefined) {\n      if (!result.existing.includes(existing.id)) result.existing.push(existing.id);\n      continue;\n    }\n    const verification = await stores.tasks.create({\n      repositoryIds: source.repositoryIds,\n      kind: \"verification\",\n      work: routeTaskWork({\n        route: route,\n        title: `Verify change ${source.changeId}`,\n        input: {\n          changeId: source.changeId!,\n          parentAttempt: source.attempt,\n        },\n      }),\n      origin: {},\n      parentTaskId: source.id,\n      replyTo: source.replyTo,\n      changeId: source.changeId,\n      dedupeKey: `verification:${source.id}:${source.attempt}:${source.changeId}:${routeKey(route)}`,\n    });\n    (existingIds.has(verification.id) ? result.existing : result.created).push(verification.id);\n  }\n\n  return result;\n}\n"],"mappings":";;;;;;;;;;AAiDA,eAAsB,gCACpB,SACkB;CAClB,MAAM,EAAE,QAAQ,SAAS;CACzB,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;EAAE,IAAI;EAAgB,SAAS;CAAE,CAAC;CACxF,IACE,CAAC,KAAK,KAAK,SACX,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,KAAK,KAC5C,CAAC;EAAC;EAAW;EAAa;CAAQ,CAAC,CAAC,SAAS,KAAK,KAAK,GAEvD,OAAO;CACT,MAAM,SAAS,MAAM,OAAO,QAAQ,cAAc,qBAAqB,IAAI,CAAC;CAC5E,IAAI,CAAC,QAAQ,OAAO;CAEpB,IAAI,EAAC,MADiB,wBAAwB,QAAQ,MAAM,EAAA,CAC/C,UAAU,OAAO;CAC9B,MAAM,EAAE,WAAW,yBAAyB,MAAM,OAAO,OAAO;CAChE,MAAM,QAAQ,gBAAgB;EAC5B,QAAQ,KAAK;EACb,UAAU,OAAO;EACjB,SAAS,OAAO;EAChB,SAAS,OAAO;CAClB,CAAC;CACD,OAAO;AACT;;AAGA,eAAsB,8BACpB,SAC8C;CAC9C,MAAM,EAAE,WAAW;CACnB,MAAM,QAAQ,QAAQ,SAAS,uBAAuB;EAAE,IAAI;EAAgB,SAAS;CAAE,CAAC;CACxF,MAAM,QACJ,QAAQ,SACP,MAAM,sBAAsB,OAAO,MAAM,MAAM;EAC9C,OAAO;EACP,OAAO,CAAC;GAAE,OAAO;GAAa,MAAM,EAAE,OAAO,EAAE,IAAI,cAAc,EAAE;EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;CAC7F,CAAC;CACH,MAAM,cAAc,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,EAAE,CAAC;CACxD,MAAM,SAAoD;EAAE,SAAS,CAAC;EAAG,UAAU,CAAC;CAAE;CACtF,KAAK,MAAM,QAAQ,OACjB,IAAI,MAAM,gCAAgC;EAAE,GAAG;EAAS;CAAK,CAAC,GAAG,OAAO,SAAS,KAAK,KAAK,EAAE;CAE/F,MAAM,UAAU,MAAM,QACnB,SACC,KAAK,KAAK,OAAO,OAAO,iBACxB,KAAK,UAAU,eACf,KAAK,aAAa,KAAA,CACtB;CAEA,KAAK,MAAM,YAAY,SAAS;EAC9B,MAAM,SAAS,MAAM,OAAO,MAAM,IAAI,SAAS,EAAE;EACjD,IACE,CAAC,UACD,OAAO,UAAU,eACjB,OAAO,YAAY,SAAS,WAC5B,OAAO,aAAa,SAAS,UAE7B;EACF,MAAM,WAAW,MAAM,MACpB,SACC,KAAK,KAAK,UAAU,KAAA,KACpB,SAAS,KAAK,KAAK,KAAK,MAAM,SAAS,KAAK,KAC5C,KAAK,iBAAiB,OAAO,MAC7B,KAAK,aAAa,OAAO,YACzB,0BAA0B,IAAI,MAAM,OAAO,OAC/C;EACA,IAAI,aAAa,KAAA,GAAW;GAC1B,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,EAAE,GAAG,OAAO,SAAS,KAAK,SAAS,EAAE;GAC5E;EACF;EACA,MAAM,eAAe,MAAM,OAAO,MAAM,OAAO;GAC7C,eAAe,OAAO;GACtB,MAAM;GACN,MAAM,cAAc;IACX;IACP,OAAO,iBAAiB,OAAO;IAC/B,OAAO;KACL,UAAU,OAAO;KACjB,eAAe,OAAO;IACxB;GACF,CAAC;GACD,QAAQ,CAAC;GACT,cAAc,OAAO;GACrB,SAAS,OAAO;GAChB,UAAU,OAAO;GACjB,WAAW,gBAAgB,OAAO,GAAG,GAAG,OAAO,QAAQ,GAAG,OAAO,SAAS,GAAG,SAAS,KAAK;EAC7F,CAAC;EACD,CAAC,YAAY,IAAI,aAAa,EAAE,IAAI,OAAO,WAAW,OAAO,QAAA,CAAS,KAAK,aAAa,EAAE;CAC5F;CAEA,OAAO;AACT"}

package/dist/changes/eve-record-change.mjs

@@ -39,7 +39,10 @@ function createRecordChangeTool(stores, options = {}) {
 			if (currentTask.state !== "running" && currentTask.changeId === void 0) throw new Error(`task ${taskId} has no recorded change`);
 			const linkedChange = currentTask.changeId === void 0 ? void 0 : await stores.changes.get(currentTask.changeId);
 			if (currentTask.changeId !== void 0 && linkedChange === null) throw new Error(`change ${currentTask.changeId} does not exist`);
-			let change = linkedChange ?? (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);
+			let change = linkedChange ?? (await stores.changes.list({
+				limit: 1,
+				match: { taskId }
+			})).items[0];
 			if (change !== void 0 && (change.repositoryId !== repositoryId || change.prNumber !== prNumber || change.prUrl !== prUrl)) throw new Error("Pull request does not match the Task's recorded Change");
 			if (currentTask.state === "running") {
 				await requireTaskExecution(stores, ctx, taskId);

package/dist/changes/eve-record-change.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"eve-record-change.mjs","names":[],"sources":["../../src/changes/eve-record-change.ts"],"sourcesContent":["import { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport type { ChangePresenter } from \"./presentation\";\nimport { changeLevelSchema, type Change } from \"../schema/change\";\nimport { repositoryIdSchema, taskIdSchema } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { PullRequestPublicationGateResult } from \"../pull-requests/contracts\";\nimport type { FactoryStores } from \"../store/engine\";\nimport { requireTaskExecution, requireTaskExecutionIdentity } from \"../eve/task-execution\";\n\n/** Change and Task capabilities required by the record-change tool. */\nexport type RecordChangeToolStores = Pick<FactoryStores, \"changes\" | \"tasks\">;\n\nconst recordChangeInputSchema = z.object({\n  taskId: taskIdSchema,\n  repositoryId: repositoryIdSchema,\n  prNumber: z.number().int().min(1),\n  prUrl: z.url(),\n  risk: changeLevelSchema.describe(\"Blast radius of the change if it is wrong.\"),\n  confidence: changeLevelSchema.describe(\"How certain you are the change is correct.\"),\n  summary: z.string().min(1).describe(\"One-sentence description of the change.\"),\n});\n\n/** Validated input accepted by the tool that links a pull request to its producing Task. */\nexport type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;\n\n/** Configures policy gates and durable presentation for the software record-change tool. */\nexport interface RecordChangeToolOptions {\n  /**\n   * PR association gate, run as an Eve approval policy and again after\n   * authentication before recording. Refusals include the gate's reason.\n   * Gates must fail closed: when they cannot verify, they refuse.\n   */\n  recordChangeGate?: (input: RecordChangeInput) => Promise<PullRequestPublicationGateResult>;\n  /** Whether recorded code changes wait for an independent verification task. Default: required. */\n  verification?: \"required\" | \"disabled\";\n  /** Present the pull request after record_change persists its durable state. */\n  presentChange?: ChangePresenter;\n}\n\n/** Change and producing Task returned after a pull request is recorded. */\nexport interface RecordChangeResult {\n  readonly change: Change;\n  readonly task: Task;\n}\n\n/** Eve outcome tool that links a pull request to its producing Task. */\nexport interface RecordChangeTool extends ToolDefinition<RecordChangeInput, RecordChangeResult> {\n  execute(input: RecordChangeInput, ctx: ToolContext): Promise<RecordChangeResult>;\n}\n\n/** Create the supplied software workflow's pull-request outcome tool. */\nexport function createRecordChangeTool(\n  stores: RecordChangeToolStores,\n  options: RecordChangeToolOptions = {},\n): RecordChangeTool {\n  const recordChangeGate = options.recordChangeGate;\n  const verification = options.verification ?? \"required\";\n  return defineTool({\n    description:\n      verification === \"required\"\n        ? \"Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying.\"\n        : \"Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.\",\n    inputSchema: recordChangeInputSchema,\n    ...(recordChangeGate === undefined\n      ? {}\n      : {\n          approval: async ({ toolInput }: { toolInput?: unknown }) => {\n            const parsed = recordChangeInputSchema.safeParse(toolInput);\n            if (!parsed.success) {\n              return {\n                type: \"denied\" as const,\n                reason: \"record_change input is malformed; fix the arguments and retry\",\n              };\n            }\n            const verdict = await recordChangeGate(parsed.data);\n            return verdict.ok\n              ? (\"not-applicable\" as const)\n              : { type: \"denied\" as const, reason: verdict.reason };\n          },\n        }),\n    async execute(\n      { taskId, repositoryId, prNumber, prUrl, risk, confidence, summary },\n      ctx,\n    ): Promise<RecordChangeResult> {\n      const currentTask = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (\n        currentTask.state !== \"running\" &&\n        currentTask.state !== \"verifying\" &&\n        currentTask.state !== \"succeeded\"\n      ) {\n        throw new Error(`task ${taskId} is ${currentTask.state}, not running`);\n      }\n      if (currentTask.repositoryIds.length !== 1 || currentTask.repositoryIds[0] !== repositoryId) {\n        throw new Error(\"Repository does not match the authenticated Task\");\n      }\n      if (currentTask.state !== \"running\" && currentTask.changeId === undefined) {\n        throw new Error(`task ${taskId} has no recorded change`);\n      }\n      const linkedChange =\n        currentTask.changeId === undefined\n          ? undefined\n          : await stores.changes.get(currentTask.changeId);\n      if (currentTask.changeId !== undefined && linkedChange === null) {\n        throw new Error(`change ${currentTask.changeId} does not exist`);\n      }\n      let change =\n        linkedChange ??\n        (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);\n\n      if (\n        change !== undefined &&\n        (change.repositoryId !== repositoryId ||\n          change.prNumber !== prNumber ||\n          change.prUrl !== prUrl)\n      ) {\n        throw new Error(\"Pull request does not match the Task's recorded Change\");\n      }\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        if (recordChangeGate !== undefined) {\n          const verdict = await recordChangeGate({\n            taskId,\n            repositoryId,\n            prNumber,\n            prUrl,\n            risk,\n            confidence,\n            summary,\n          });\n          if (!verdict.ok) throw new Error(verdict.reason);\n        }\n        await requireTaskExecution(stores, ctx, taskId);\n      }\n\n      if (change === undefined) {\n        if (currentTask.state !== \"running\") {\n          throw new Error(`task ${taskId} has no recorded change`);\n        }\n        change = await stores.changes.create({\n          repositoryId,\n          taskId,\n          prNumber,\n          prUrl,\n          author: \"factory\",\n          risk,\n          confidence,\n          evidence: {\n            reproVerified: false,\n            testsAdded: 0,\n            checksGreen: false,\n            attackPassed: false,\n            scopeMatches: false,\n          },\n        });\n      }\n      if (change === undefined) throw new Error(`task ${taskId} has no recorded change`);\n      let recordedChange = change;\n\n      if (currentTask.state === \"succeeded\") return { change: recordedChange, task: currentTask };\n\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        await options.presentChange?.({\n          taskId,\n          changeId: recordedChange.id,\n          verification,\n          summary,\n        });\n      }\n\n      let task: Task = currentTask;\n      if (task.state === \"running\") {\n        task = await stores.tasks.transition(taskId, \"verifying\", {\n          expectFrom: \"running\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          patch: { changeId: recordedChange.id },\n          reason: summary,\n        });\n      }\n      if (verification === \"required\") return { change: recordedChange, task };\n\n      const completion = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (completion.state !== \"verifying\" || completion.changeId !== recordedChange.id) {\n        throw new Error(\"Task is no longer awaiting this Change's completion\");\n      }\n      if (recordedChange.state === \"verifying\") {\n        recordedChange = await stores.changes.transition(recordedChange.id, \"ready\", {\n          reason: \"independent verification is not configured\",\n        });\n      }\n      if (task.state === \"verifying\") {\n        task = await stores.tasks.transition(taskId, \"succeeded\", {\n          expectFrom: \"verifying\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          reason: \"change recorded for human review without independent verification\",\n          output: {\n            changeId: recordedChange.id,\n            prUrl: recordedChange.prUrl,\n            summary,\n            verification,\n          },\n        });\n      }\n      return { change: recordedChange, task };\n    },\n  });\n}\n"],"mappings":";;;;;;AAaA,MAAM,0BAA0B,EAAE,OAAO;CACvC,QAAQ;CACR,cAAc;CACd,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;CAChC,OAAO,EAAE,IAAI;CACb,MAAM,kBAAkB,SAAS,4CAA4C;CAC7E,YAAY,kBAAkB,SAAS,4CAA4C;CACnF,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,yCAAyC;AAC/E,CAAC;;AA+BD,SAAgB,uBACd,QACA,UAAmC,CAAC,GAClB;CAClB,MAAM,mBAAmB,QAAQ;CACjC,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,OAAO,WAAW;EAChB,aACE,iBAAiB,aACb,wIACA;EACN,aAAa;EACb,GAAI,qBAAqB,KAAA,IACrB,CAAC,IACD,EACE,UAAU,OAAO,EAAE,gBAAyC;GAC1D,MAAM,SAAS,wBAAwB,UAAU,SAAS;GAC1D,IAAI,CAAC,OAAO,SACV,OAAO;IACL,MAAM;IACN,QAAQ;GACV;GAEF,MAAM,UAAU,MAAM,iBAAiB,OAAO,IAAI;GAClD,OAAO,QAAQ,KACV,mBACD;IAAE,MAAM;IAAmB,QAAQ,QAAQ;GAAO;EACxD,EACF;EACJ,MAAM,QACJ,EAAE,QAAQ,cAAc,UAAU,OAAO,MAAM,YAAY,WAC3D,KAC6B;GAC7B,MAAM,cAAc,MAAM,6BAA6B,QAAQ,KAAK,MAAM;GAC1E,IACE,YAAY,UAAU,aACtB,YAAY,UAAU,eACtB,YAAY,UAAU,aAEtB,MAAM,IAAI,MAAM,QAAQ,OAAO,MAAM,YAAY,MAAM,cAAc;GAEvE,IAAI,YAAY,cAAc,WAAW,KAAK,YAAY,cAAc,OAAO,cAC7E,MAAM,IAAI,MAAM,kDAAkD;GAEpE,IAAI,YAAY,UAAU,aAAa,YAAY,aAAa,KAAA,GAC9D,MAAM,IAAI,MAAM,QAAQ,OAAO,wBAAwB;GAEzD,MAAM,eACJ,YAAY,aAAa,KAAA,IACrB,KAAA,IACA,MAAM,OAAO,QAAQ,IAAI,YAAY,QAAQ;GACnD,IAAI,YAAY,aAAa,KAAA,KAAa,iBAAiB,MACzD,MAAM,IAAI,MAAM,UAAU,YAAY,SAAS,gBAAgB;GAEjE,IAAI,SACF,iBACC,MAAM,OAAO,QAAQ,KAAK,EAAA,CAAG,MAAM,cAAc,UAAU,WAAW,MAAM;GAE/E,IACE,WAAW,KAAA,MACV,OAAO,iBAAiB,gBACvB,OAAO,aAAa,YACpB,OAAO,UAAU,QAEnB,MAAM,IAAI,MAAM,wDAAwD;GAE1E,IAAI,YAAY,UAAU,WAAW;IACnC,MAAM,qBAAqB,QAAQ,KAAK,MAAM;IAC9C,IAAI,qBAAqB,KAAA,GAAW;KAClC,MAAM,UAAU,MAAM,iBAAiB;MACrC;MACA;MACA;MACA;MACA;MACA;MACA;KACF,CAAC;KACD,IAAI,CAAC,QAAQ,IAAI,MAAM,IAAI,MAAM,QAAQ,MAAM;IACjD;IACA,MAAM,qBAAqB,QAAQ,KAAK,MAAM;GAChD;GAEA,IAAI,WAAW,KAAA,GAAW;IACxB,IAAI,YAAY,UAAU,WACxB,MAAM,IAAI,MAAM,QAAQ,OAAO,wBAAwB;IAEzD,SAAS,MAAM,OAAO,QAAQ,OAAO;KACnC;KACA;KACA;KACA;KACA,QAAQ;KACR;KACA;KACA,UAAU;MACR,eAAe;MACf,YAAY;MACZ,aAAa;MACb,cAAc;MACd,cAAc;KAChB;IACF,CAAC;GACH;GACA,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,QAAQ,OAAO,wBAAwB;GACjF,IAAI,iBAAiB;GAErB,IAAI,YAAY,UAAU,aAAa,OAAO;IAAE,QAAQ;IAAgB,MAAM;GAAY;GAE1F,IAAI,YAAY,UAAU,WAAW;IACnC,MAAM,qBAAqB,QAAQ,KAAK,MAAM;IAC9C,MAAM,QAAQ,gBAAgB;KAC5B;KACA,UAAU,eAAe;KACzB;KACA;IACF,CAAC;GACH;GAEA,IAAI,OAAa;GACjB,IAAI,KAAK,UAAU,WACjB,OAAO,MAAM,OAAO,MAAM,WAAW,QAAQ,aAAa;IACxD,YAAY;IACZ,eAAe,YAAY;IAC3B,iBAAiB,YAAY;IAC7B,OAAO,EAAE,UAAU,eAAe,GAAG;IACrC,QAAQ;GACV,CAAC;GAEH,IAAI,iBAAiB,YAAY,OAAO;IAAE,QAAQ;IAAgB;GAAK;GAEvE,MAAM,aAAa,MAAM,6BAA6B,QAAQ,KAAK,MAAM;GACzE,IAAI,WAAW,UAAU,eAAe,WAAW,aAAa,eAAe,IAC7E,MAAM,IAAI,MAAM,qDAAqD;GAEvE,IAAI,eAAe,UAAU,aAC3B,iBAAiB,MAAM,OAAO,QAAQ,WAAW,eAAe,IAAI,SAAS,EAC3E,QAAQ,6CACV,CAAC;GAEH,IAAI,KAAK,UAAU,aACjB,OAAO,MAAM,OAAO,MAAM,WAAW,QAAQ,aAAa;IACxD,YAAY;IACZ,eAAe,YAAY;IAC3B,iBAAiB,YAAY;IAC7B,QAAQ;IACR,QAAQ;KACN,UAAU,eAAe;KACzB,OAAO,eAAe;KACtB;KACA;IACF;GACF,CAAC;GAEH,OAAO;IAAE,QAAQ;IAAgB;GAAK;EACxC;CACF,CAAC;AACH"}
+{"version":3,"file":"eve-record-change.mjs","names":[],"sources":["../../src/changes/eve-record-change.ts"],"sourcesContent":["import { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport type { ChangePresenter } from \"./presentation\";\nimport { changeLevelSchema, type Change } from \"../schema/change\";\nimport { repositoryIdSchema, taskIdSchema } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport type { PullRequestPublicationGateResult } from \"../pull-requests/contracts\";\nimport type { FactoryStores } from \"../store/engine\";\nimport { requireTaskExecution, requireTaskExecutionIdentity } from \"../eve/task-execution\";\n\n/** Change and Task capabilities required by the record-change tool. */\nexport type RecordChangeToolStores = Pick<FactoryStores, \"changes\" | \"tasks\">;\n\nconst recordChangeInputSchema = z.object({\n  taskId: taskIdSchema,\n  repositoryId: repositoryIdSchema,\n  prNumber: z.number().int().min(1),\n  prUrl: z.url(),\n  risk: changeLevelSchema.describe(\"Blast radius of the change if it is wrong.\"),\n  confidence: changeLevelSchema.describe(\"How certain you are the change is correct.\"),\n  summary: z.string().min(1).describe(\"One-sentence description of the change.\"),\n});\n\n/** Validated input accepted by the tool that links a pull request to its producing Task. */\nexport type RecordChangeInput = z.infer<typeof recordChangeInputSchema>;\n\n/** Configures policy gates and durable presentation for the software record-change tool. */\nexport interface RecordChangeToolOptions {\n  /**\n   * PR association gate, run as an Eve approval policy and again after\n   * authentication before recording. Refusals include the gate's reason.\n   * Gates must fail closed: when they cannot verify, they refuse.\n   */\n  recordChangeGate?: (input: RecordChangeInput) => Promise<PullRequestPublicationGateResult>;\n  /** Whether recorded code changes wait for an independent verification task. Default: required. */\n  verification?: \"required\" | \"disabled\";\n  /** Present the pull request after record_change persists its durable state. */\n  presentChange?: ChangePresenter;\n}\n\n/** Change and producing Task returned after a pull request is recorded. */\nexport interface RecordChangeResult {\n  readonly change: Change;\n  readonly task: Task;\n}\n\n/** Eve outcome tool that links a pull request to its producing Task. */\nexport interface RecordChangeTool extends ToolDefinition<RecordChangeInput, RecordChangeResult> {\n  execute(input: RecordChangeInput, ctx: ToolContext): Promise<RecordChangeResult>;\n}\n\n/** Create the supplied software workflow's pull-request outcome tool. */\nexport function createRecordChangeTool(\n  stores: RecordChangeToolStores,\n  options: RecordChangeToolOptions = {},\n): RecordChangeTool {\n  const recordChangeGate = options.recordChangeGate;\n  const verification = options.verification ?? \"required\";\n  return defineTool({\n    description:\n      verification === \"required\"\n        ? \"Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying.\"\n        : \"Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.\",\n    inputSchema: recordChangeInputSchema,\n    ...(recordChangeGate === undefined\n      ? {}\n      : {\n          approval: async ({ toolInput }: { toolInput?: unknown }) => {\n            const parsed = recordChangeInputSchema.safeParse(toolInput);\n            if (!parsed.success) {\n              return {\n                type: \"denied\" as const,\n                reason: \"record_change input is malformed; fix the arguments and retry\",\n              };\n            }\n            const verdict = await recordChangeGate(parsed.data);\n            return verdict.ok\n              ? (\"not-applicable\" as const)\n              : { type: \"denied\" as const, reason: verdict.reason };\n          },\n        }),\n    async execute(\n      { taskId, repositoryId, prNumber, prUrl, risk, confidence, summary },\n      ctx,\n    ): Promise<RecordChangeResult> {\n      const currentTask = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (\n        currentTask.state !== \"running\" &&\n        currentTask.state !== \"verifying\" &&\n        currentTask.state !== \"succeeded\"\n      ) {\n        throw new Error(`task ${taskId} is ${currentTask.state}, not running`);\n      }\n      if (currentTask.repositoryIds.length !== 1 || currentTask.repositoryIds[0] !== repositoryId) {\n        throw new Error(\"Repository does not match the authenticated Task\");\n      }\n      if (currentTask.state !== \"running\" && currentTask.changeId === undefined) {\n        throw new Error(`task ${taskId} has no recorded change`);\n      }\n      const linkedChange =\n        currentTask.changeId === undefined\n          ? undefined\n          : await stores.changes.get(currentTask.changeId);\n      if (currentTask.changeId !== undefined && linkedChange === null) {\n        throw new Error(`change ${currentTask.changeId} does not exist`);\n      }\n      let change =\n        linkedChange ?? (await stores.changes.list({ limit: 1, match: { taskId } })).items[0];\n\n      if (\n        change !== undefined &&\n        (change.repositoryId !== repositoryId ||\n          change.prNumber !== prNumber ||\n          change.prUrl !== prUrl)\n      ) {\n        throw new Error(\"Pull request does not match the Task's recorded Change\");\n      }\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        if (recordChangeGate !== undefined) {\n          const verdict = await recordChangeGate({\n            taskId,\n            repositoryId,\n            prNumber,\n            prUrl,\n            risk,\n            confidence,\n            summary,\n          });\n          if (!verdict.ok) throw new Error(verdict.reason);\n        }\n        await requireTaskExecution(stores, ctx, taskId);\n      }\n\n      if (change === undefined) {\n        if (currentTask.state !== \"running\") {\n          throw new Error(`task ${taskId} has no recorded change`);\n        }\n        change = await stores.changes.create({\n          repositoryId,\n          taskId,\n          prNumber,\n          prUrl,\n          author: \"factory\",\n          risk,\n          confidence,\n          evidence: {\n            reproVerified: false,\n            testsAdded: 0,\n            checksGreen: false,\n            attackPassed: false,\n            scopeMatches: false,\n          },\n        });\n      }\n      if (change === undefined) throw new Error(`task ${taskId} has no recorded change`);\n      let recordedChange = change;\n\n      if (currentTask.state === \"succeeded\") return { change: recordedChange, task: currentTask };\n\n      if (currentTask.state === \"running\") {\n        await requireTaskExecution(stores, ctx, taskId);\n        await options.presentChange?.({\n          taskId,\n          changeId: recordedChange.id,\n          verification,\n          summary,\n        });\n      }\n\n      let task: Task = currentTask;\n      if (task.state === \"running\") {\n        task = await stores.tasks.transition(taskId, \"verifying\", {\n          expectFrom: \"running\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          patch: { changeId: recordedChange.id },\n          reason: summary,\n        });\n      }\n      if (verification === \"required\") return { change: recordedChange, task };\n\n      const completion = await requireTaskExecutionIdentity(stores, ctx, taskId);\n      if (completion.state !== \"verifying\" || completion.changeId !== recordedChange.id) {\n        throw new Error(\"Task is no longer awaiting this Change's completion\");\n      }\n      if (recordedChange.state === \"verifying\") {\n        recordedChange = await stores.changes.transition(recordedChange.id, \"ready\", {\n          reason: \"independent verification is not configured\",\n        });\n      }\n      if (task.state === \"verifying\") {\n        task = await stores.tasks.transition(taskId, \"succeeded\", {\n          expectFrom: \"verifying\",\n          expectAttempt: currentTask.attempt,\n          expectExecution: currentTask.execution,\n          reason: \"change recorded for human review without independent verification\",\n          output: {\n            changeId: recordedChange.id,\n            prUrl: recordedChange.prUrl,\n            summary,\n            verification,\n          },\n        });\n      }\n      return { change: recordedChange, task };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/client-stream.d.mts

@@ -1,16 +1,20 @@
 import { TaskId } from "./schema/id.mjs";
 import { AgentSessionId } from "./schema/session.mjs";
+import { TranscriptBlock } from "./schema/transcript.mjs";
 import { Transcript } from "./client-transcript.mjs";
 import { FactoryClient } from "./client.mjs";
 import { SessionView } from "./api-contracts.mjs";
 //#region src/client-stream.d.ts
 /** Client operations required to hydrate and follow a Factory session stream. */
-type SessionStreamClient = Pick<FactoryClient, "getSessionTranscriptResponse" | "getSessionEventStreamResponse">;
+type SessionStreamClient = Pick<FactoryClient, "getSessionTranscriptResponse" | "getSessionEventStreamResponse" | "getSessionHistory">;
 /** Callbacks and exact execution identity used while following a session stream. */
 interface FollowSessionStreamOptions {
   readonly sessionId: AgentSessionId;
   readonly executionId: string | null;
   readonly taskId?: TaskId;
+  /** Task bound to the conversation; absent for direct Foreman conversations. */
+  readonly sessionTaskId?: TaskId;
+  readonly historyNextCursor?: string | null;
   readonly history?: readonly NonNullable<SessionView["history"]>[number][];
   readonly transcript: Transcript;
   readonly signal: AbortSignal;
@@ -21,8 +25,21 @@ interface FollowSessionStreamOptions {
   readonly onError: (error: unknown) => void;
   readonly onConflict: () => Promise<void>;
 }
+/** Loads one older page, preserving live cursor/state and execution ordering. */
+declare function loadPreviousTranscriptPage(client: SessionStreamClient, input: {
+  sessionId: AgentSessionId;
+  transcript: Transcript;
+  signal: AbortSignal;
+}): Promise<boolean>;
+/** Expands one saved block without replacing newer live content. */
+declare function expandTranscriptBlock(client: SessionStreamClient, input: {
+  sessionId: AgentSessionId;
+  transcript: Transcript;
+  block: TranscriptBlock;
+  signal: AbortSignal;
+}): Promise<void>;
 /** Hydrates a transcript and follows its current execution until completion or disconnection. */
 declare function followSessionStream(client: SessionStreamClient, options: FollowSessionStreamOptions): Promise<void>;
 //#endregion
-export { FollowSessionStreamOptions, SessionStreamClient, followSessionStream };
+export { FollowSessionStreamOptions, SessionStreamClient, expandTranscriptBlock, followSessionStream, loadPreviousTranscriptPage };
 //# sourceMappingURL=client-stream.d.mts.map

package/dist/client-stream.mjs

@@ -1,5 +1,5 @@
 import { readEvents } from "./client-events.mjs";
-import { transcriptSnapshotSchema } from "./schema/transcript.mjs";
+import { transcriptBlockSchema, transcriptPageSchema } from "./schema/transcript.mjs";
 import { Transcript } from "./client-transcript.mjs";
 import { ApiError } from "./client.mjs";
 //#region src/client-stream.ts
@@ -26,7 +26,20 @@ async function readSnapshot(client, input) {
 			...input.history ? { history: true } : {},
 			signal: requestSignal
 		});
-		input.transcript.hydrate(transcriptSnapshotSchema.parse(await response.json()));
+		if (response.status === 202) {
+			await response.body?.cancel();
+			await pause(input.pollIntervalMs, input.signal);
+			continue;
+		}
+		const page = transcriptPageSchema.parse(await response.json());
+		input.transcript.hydrate(page.snapshot, page.nextCursor === null);
+		input.transcript.historyPages.set(input.executionId, {
+			executionId: input.executionId,
+			taskId: input.taskId,
+			history: input.history,
+			nextCursor: page.nextCursor,
+			loaded: true
+		});
 		return;
 	} catch (error) {
 		if (input.signal.aborted) return;
@@ -36,55 +49,86 @@ async function readSnapshot(client, input) {
 		await pause(Math.min(15e3, input.pollIntervalMs * 2 ** Math.min(failures, 3)), input.signal);
 	}
 }
-async function loadHistory(client, options) {
-	const entries = options.history ?? [];
-	const results = /* @__PURE__ */ new Map();
-	let next = 0;
-	await Promise.all(Array.from({ length: Math.min(4, entries.length) }, async () => {
-		while (next < entries.length) {
-			const index = next++;
-			const entry = entries[index];
-			if (!entry) throw new Error("Historical transcript index is unavailable");
-			const id = entry.execution.sessionId;
-			const previous = new Transcript(entry.message, entry.attachments);
-			const header = {
-				id: "run",
-				kind: "status",
-				title: entry.agent,
-				text: entry.taskId ? `Earlier work · ${entry.taskId}` : "Earlier execution"
-			};
-			try {
-				const historySignal = AbortSignal.any([options.signal, AbortSignal.timeout(15e3)]);
-				await readSnapshot(client, {
-					sessionId: options.sessionId,
-					executionId: id,
-					history: true,
-					transcript: previous,
-					signal: historySignal,
-					pollIntervalMs: options.pollIntervalMs ?? 2e3
-				});
-				if (historySignal.aborted && !options.signal.aborted) throw new Error("Historical transcript loading timed out");
-			} catch (error) {
-				if (options.signal.aborted) return;
-				if (error instanceof ApiError && [401, 403].includes(error.status)) throw error;
-				previous.put({
-					id: "unavailable",
-					kind: "status",
-					title: "History unavailable",
-					text: "This execution's transcript could not be loaded."
-				});
-			}
-			previous.blocks.unshift(header);
-			results.set(index, {
-				id,
-				transcript: previous
+/** Loads one older page, preserving live cursor/state and execution ordering. */
+async function loadPreviousTranscriptPage(client, input) {
+	let reference = [...input.transcript.historyPages.values()].reverse().find((page) => !page.loaded || page.nextCursor !== null);
+	while (!reference && input.transcript.historyNextCursor && !input.signal.aborted) {
+		const page = await client.getSessionHistory(input.sessionId, {
+			cursor: input.transcript.historyNextCursor,
+			signal: input.signal
+		});
+		if (input.signal.aborted) return false;
+		const previous = new Map(input.transcript.historyPages);
+		input.transcript.historyPages.clear();
+		for (const entry of [...page.items].reverse()) {
+			if (entry.taskId && !input.transcript.sessionTaskId) continue;
+			input.transcript.historyPages.set(entry.execution.sessionId, {
+				executionId: entry.execution.sessionId,
+				history: true,
+				loaded: false,
+				nextCursor: null,
+				message: entry.message,
+				attachments: entry.attachments,
+				agent: entry.agent
 			});
 		}
-	}));
-	return entries.map((_, index) => {
-		const result = results.get(index);
-		if (!result) throw new Error("Historical transcript loading did not complete");
-		return result;
+		for (const [key, value] of previous) input.transcript.historyPages.set(key, value);
+		input.transcript.historyNextCursor = page.nextCursor;
+		reference = [...input.transcript.historyPages.values()].reverse().find((entry) => !entry.loaded || entry.nextCursor !== null);
+	}
+	if (!reference) return false;
+	const response = await client.getSessionTranscriptResponse({
+		sessionId: input.sessionId,
+		executionId: reference.executionId,
+		taskId: reference.taskId,
+		history: reference.history,
+		cursor: reference.nextCursor ?? void 0,
+		limit: 30,
+		signal: input.signal
+	});
+	if (response.status === 202) {
+		await response.body?.cancel();
+		throw new Error("Earlier messages are still being saved. Try loading them again shortly.");
+	}
+	const page = transcriptPageSchema.parse(await response.json());
+	if (input.signal.aborted) return false;
+	const previous = new Transcript(reference.message, reference.attachments);
+	previous.hydrate(page.snapshot, page.nextCursor === null);
+	if (reference.history && !reference.loaded) previous.blocks.unshift({
+		id: "run",
+		kind: "status",
+		title: reference.agent ?? "Earlier execution",
+		text: reference.label ?? "Earlier execution"
+	});
+	input.transcript.prependPage(previous.blocks, reference.history ? reference.executionId : void 0, page.nextCursor === null);
+	input.transcript.historyPages.set(reference.executionId, {
+		...reference,
+		loaded: true,
+		nextCursor: page.nextCursor
+	});
+	return true;
+}
+/** Expands one saved block without replacing newer live content. */
+async function expandTranscriptBlock(client, input) {
+	if (!input.block.contentRef) return;
+	const references = [...input.transcript.historyPages.values()];
+	const reference = references.find((page) => page.history && input.block.id.startsWith(`history:${page.executionId}:`)) ?? references.find((page) => !page.history);
+	if (!reference) throw new Error("Transcript execution is unavailable");
+	const cursor = input.transcript.cursor;
+	const response = await client.getSessionTranscriptResponse({
+		sessionId: input.sessionId,
+		executionId: reference.executionId,
+		taskId: reference.taskId,
+		history: reference.history,
+		blockId: input.block.contentRef.blockId,
+		signal: input.signal
+	});
+	const block = transcriptBlockSchema.parse(await response.json());
+	if (input.signal.aborted) return;
+	if (!reference.history && input.transcript.cursor !== cursor) throw new Error("Transcript changed while loading content; try again");
+	input.transcript.put({
+		...block,
+		id: input.block.id
 	});
 }
 async function hydrateCurrent(client, options) {
@@ -135,16 +179,34 @@ async function hydrateCurrent(client, options) {
 /** Hydrates a transcript and follows its current execution until completion or disconnection. */
 async function followSessionStream(client, options) {
 	const { sessionId, executionId, transcript, signal } = options;
-	let history;
+	transcript.sessionTaskId = options.sessionTaskId;
+	transcript.historyNextCursor = options.historyNextCursor ?? null;
+	for (const entry of options.history ?? []) {
+		if (entry.taskId && !options.sessionTaskId) continue;
+		transcript.historyPages.set(entry.execution.sessionId, {
+			executionId: entry.execution.sessionId,
+			history: true,
+			nextCursor: null,
+			loaded: false,
+			message: entry.message,
+			attachments: entry.attachments,
+			agent: entry.agent,
+			label: entry.taskId ? `Earlier work · ${entry.taskId}` : "Earlier execution"
+		});
+	}
 	let hydrated;
 	try {
-		[history, hydrated] = await Promise.all([loadHistory(client, options), hydrateCurrent(client, options)]);
+		hydrated = await hydrateCurrent(client, options);
+		if (executionId === null && !signal.aborted) await loadPreviousTranscriptPage(client, {
+			sessionId,
+			transcript,
+			signal
+		});
 	} catch (error) {
 		if (!signal.aborted) options.onError(error);
 		return;
 	}
 	if (signal.aborted || !hydrated) return;
-	transcript.prependHistory(history);
 	if (executionId === null) transcript.state = "waiting";
 	options.onHydrated();
 	if (executionId === null || ["completed", "failed"].includes(transcript.state)) return;
@@ -205,6 +267,6 @@ async function followSessionStream(client, options) {
 	}
 }
 //#endregion
-export { followSessionStream };
+export { expandTranscriptBlock, followSessionStream, loadPreviousTranscriptPage };
 
 //# sourceMappingURL=client-stream.mjs.map