@vercel/factory 0.0.14 → 0.0.16

package/dist/execution-public.mjs

@@ -0,0 +1,7 @@
+import { codingExecutionRequestSchema, executionArtifactSchema, executionLaunchKeySchema, executionResultSchema, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema } from "./schema/execution.mjs";
+import { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionLaunchPendingError, dispatchTask } from "./dispatch.mjs";
+import { workNotificationSchema } from "./store/work-notifications.mjs";
+import { ExecutionFenceError, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage } from "./execution.mjs";
+import { sweepQueued } from "./sweep.mjs";
+import { stallWindowMinutes, sweepTaskStalls } from "./stall.mjs";
+export { BudgetExhaustedError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, ExecutionFenceError, ExecutionLaunchPendingError, cancelExecution, codingExecutionRequestSchema, dispatchTask, executionArtifactSchema, executionLaunchKey, executionLaunchKeySchema, executionResultSchema, inspectExecution, launchExecution, recordExecutionUsage, stallWindowMinutes, sweepQueued, sweepTaskStalls, taskAttemptRef, taskAttemptRefFromTask, taskAttemptRefSchema, workNotificationSchema };

package/dist/execution.d.mts

@@ -0,0 +1,183 @@
+import { ExecutionReference, Task } from "./schema/task.mjs";
+import { CodingExecutionRequest, ExecutionLaunchKey, ExecutionResult, TaskAttemptRef } from "./schema/execution.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+//#region src/execution.d.ts
+/** Validated request and stable idempotency key passed to an execution provider. */
+interface StartExecutionInput {
+  /** Exact Task-attempt request validated before the provider is called. */
+  readonly request: CodingExecutionRequest;
+  /** Stable key that must identify the same provider launch across retries and process restarts. */
+  readonly launchKey: ExecutionLaunchKey;
+}
+/** Current provider state when inspecting one recorded execution. */
+type ExecutionInspectionResult = {
+  /** The recorded execution still exists and is safe for the workflow to reattach. */
+  status: "active";
+} | {
+  /** The provider can no longer inspect or reattach the recorded execution. */
+  status: "expired";
+} | {
+  /** The provider has immutable final evidence for the recorded execution. */
+  status: "finished";
+  result: ExecutionResult;
+};
+/** Provider-neutral boundary for retry-safe execution start, inspection, and cancellation. */
+interface ExecutionAdapter {
+  /**
+   * Starts or recovers one launch by its stable key. Return only after provider acceptance is
+   * known. Throw `ExecutionLaunchPendingError` when acceptance is ambiguous; every other rejection
+   * promises that this call did not leave an untracked launch.
+   *
+   * @param input - Validated provider request and stable launch key.
+   * @returns The accepted execution reference for this logical launch.
+   */
+  start(input: StartExecutionInput): Promise<ExecutionReference>;
+  /**
+   * Observes one exact provider handle without starting replacement work. Only `active` confirms
+   * that reattachment is safe; `expired` and `finished` require workflow-owned reconciliation.
+   *
+   * @param execution - Exact provider handle previously recorded on the Task.
+   * @returns Current provider state and final result when finished.
+   */
+  inspect(execution: ExecutionReference): Promise<ExecutionInspectionResult>;
+  /**
+   * Idempotently requests a stop and returns the provider's final observed result and usage. An
+   * adapter may report cancellation even when immediate interruption is unsupported; callers that
+   * require proof of inactivity must use provider-specific confirmation.
+   *
+   * @param execution - Exact provider handle to stop or confirm inactive.
+   * @returns Immutable final result and usage for that execution.
+   */
+  stop(execution: ExecutionReference): Promise<ExecutionResult>;
+}
+/**
+ * Error raised when an execution no longer matches the current running Task attempt.
+ * Reread the Task and discard the stale observation; do not apply it to the replacement attempt.
+ */
+declare class ExecutionFenceError extends Error {}
+/** Store capabilities required to launch or reattach a coding execution. */
+type LaunchExecutionStores = Pick<FactoryStores, "repositories" | "tasks">;
+/** Store capabilities required to inspect a coding execution. */
+type InspectExecutionStores = Pick<FactoryStores, "tasks">;
+/** Store capabilities required to persist final execution usage. */
+type RecordExecutionUsageStores = Pick<FactoryStores, "receipts" | "tasks">;
+/** Store capabilities required to cancel and settle a coding execution. */
+type CancelExecutionStores = RecordExecutionUsageStores;
+/**
+ * Constructs the stable provider idempotency key for one exact Task attempt.
+ * Persist or deterministically recreate this key across launch recovery; a new attempt gets a new key.
+ */
+declare function executionLaunchKey(ref: TaskAttemptRef): ExecutionLaunchKey;
+/** Dependencies and request used to start or reattach one coding execution. */
+interface LaunchExecutionOptions {
+  /** Task and repository reads plus the durable execution-binding write. */
+  readonly stores: LaunchExecutionStores;
+  /** Exact running Task attempt and single repository supplied to the provider. */
+  readonly request: CodingExecutionRequest;
+  /** Provider boundary responsible for idempotent start and exact-handle inspection. */
+  readonly adapter: ExecutionAdapter;
+}
+/**
+ * Starts or reattaches one coding execution after dispatch has admitted its Task.
+ *
+ * @remarks
+ * The Task must still be `running` on the requested attempt and name exactly one enabled matching
+ * repository. If an execution is already recorded, this method inspects it and returns it only
+ * when the provider confirms it is active; it never starts an implicit replacement for a finished
+ * or expired handle.
+ *
+ * For a new launch, the adapter receives a stable key derived from the Task attempt. The method
+ * returns only after the provider reference is durably bound to that attempt. If acceptance or
+ * the binding write is ambiguous, it throws `ExecutionLaunchPendingError`; retry this operation
+ * with the same request so the same key can recover the launch. Reread the Task before applying
+ * any other error, because a concurrent writer may have replaced the attempt.
+ *
+ * @param options - Validated request, required stores, and provider adapter.
+ * @returns The recorded provider execution for the current running attempt.
+ * @throws `ExecutionFenceError` when Task attempt or execution ownership changes.
+ * @throws `ExecutionLaunchPendingError` when provider acceptance or durable binding is ambiguous.
+ */
+declare function launchExecution(options: LaunchExecutionOptions): Promise<ExecutionReference>;
+/** Dependencies and Task-attempt identity used to inspect one execution. */
+interface InspectExecutionOptions {
+  /** Task read used to establish and recheck the execution fence. */
+  readonly stores: InspectExecutionStores;
+  /** Exact running Task attempt whose recorded execution may be inspected. */
+  readonly task: TaskAttemptRef;
+  /** Provider boundary used only for observation. */
+  readonly adapter: ExecutionAdapter;
+}
+/**
+ * Inspects a recorded execution without granting provider evidence lifecycle authority.
+ *
+ * @remarks
+ * The Task must be running on the exact attempt and have a recorded execution. Ownership is
+ * checked again after the provider call so a concurrent replacement cannot attach stale results.
+ * Finished results are schema-validated and must identify that same execution. This method writes
+ * no Task state or usage; the workflow decides how to validate evidence and transition afterward.
+ *
+ * @param options - Exact Task attempt, Task store, and provider adapter.
+ * @returns Current provider state and a validated result when finished.
+ * @throws `ExecutionFenceError` when the attempt or execution changes during inspection.
+ */
+declare function inspectExecution(options: InspectExecutionOptions): Promise<ExecutionInspectionResult>;
+/** Dependencies, Task-attempt identity, and provider result used to record usage. */
+interface RecordExecutionUsageOptions {
+  /** Receipt and Task stores used for idempotent usage persistence. */
+  readonly stores: RecordExecutionUsageStores;
+  /** Exact Task attempt that owns the provider result. */
+  readonly task: TaskAttemptRef;
+  /** Final provider result whose execution must match the Task's recorded handle. */
+  readonly result: ExecutionResult;
+}
+/**
+ * Records one adapter's immutable final usage packet without changing Task lifecycle state.
+ *
+ * @remarks
+ * Known cost is delegated to the Task usage store under a deterministic turn key, making identical
+ * replay non-charging. This API records an immutable final usage packet; an adapter must not also
+ * report the same charges through per-step usage hooks, because those observations use independent
+ * idempotency keys and would be added twice. When cost is unknown, an idempotent `usage_unresolved`
+ * receipt is appended and the Task remains unsettled so its reservation is retained. The workflow
+ * or reconciler must later supply measured usage before settlement.
+ *
+ * @param options - Exact Task attempt, final provider result, and persistence stores.
+ * @returns The Task after usage persistence, or unchanged after unresolved-cost evidence.
+ * @throws `ExecutionFenceError` when the result belongs to another attempt or execution.
+ */
+declare function recordExecutionUsage(options: RecordExecutionUsageOptions): Promise<Task>;
+/** Dependencies and reason used to cancel one exact Task execution attempt. */
+interface CancelExecutionOptions {
+  /** Task and receipt stores used for cancellation, usage, and settlement. */
+  readonly stores: CancelExecutionStores;
+  /** Exact attempt to cancel; replacement attempts are refused. */
+  readonly task: TaskAttemptRef;
+  /** Provider boundary used to request an idempotent stop and read its final observed result. */
+  readonly adapter: ExecutionAdapter;
+  /** Human-readable cancellation reason retained in lifecycle evidence. */
+  readonly reason: string;
+}
+/**
+ * Cancels canonical Task work, then interrupts and settles its exact provider execution.
+ *
+ * @remarks
+ * The Task first durably enters `cancelled`, preventing later workflow completion from winning.
+ * Provider interruption happens afterward and cannot roll that transition back. An absent recorded
+ * execution produces durable `cancellation_unresolved` evidence and throws. Since execution
+ * binding accepts only running Tasks, a handle discovered after this point cannot be attached by
+ * retrying this helper; application-owned reconciliation must stop that handle and persist its
+ * cleanup evidence and measured settlement separately. If `adapter.stop` fails ambiguously, retry
+ * this same call—the cancelled transition and adapter stop are both expected to be idempotent.
+ *
+ * Returned final usage is recorded once. Known cost then settles the Task; unknown cost retains the
+ * reservation and leaves reconciliation evidence for later measurement.
+ *
+ * @param options - Exact Task attempt, cancellation reason, stores, and provider adapter.
+ * @returns The cancelled Task after provider usage recording and any possible settlement.
+ * @throws `ExecutionFenceError` when the attempt has been replaced.
+ * @throws When execution discovery is unresolved or the provider stop request fails.
+ */
+declare function cancelExecution(options: CancelExecutionOptions): Promise<Task>;
+//#endregion
+export { CancelExecutionOptions, CancelExecutionStores, ExecutionAdapter, ExecutionFenceError, ExecutionInspectionResult, InspectExecutionOptions, InspectExecutionStores, LaunchExecutionOptions, LaunchExecutionStores, RecordExecutionUsageOptions, RecordExecutionUsageStores, StartExecutionInput, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage };
+//# sourceMappingURL=execution.d.mts.map

package/dist/execution.mjs

@@ -0,0 +1,223 @@
+import { executionReferenceSchema } from "./schema/task.mjs";
+import { codingExecutionRequestSchema, executionLaunchKeySchema, executionResultSchema, taskAttemptRefSchema } from "./schema/execution.mjs";
+import { ExecutionLaunchPendingError } from "./dispatch.mjs";
+import { isDeepStrictEqual } from "node:util";
+//#region src/execution.ts
+/**
+* Error raised when an execution no longer matches the current running Task attempt.
+* Reread the Task and discard the stale observation; do not apply it to the replacement attempt.
+*/
+var ExecutionFenceError = class extends Error {};
+function sameExecution(left, right) {
+	return isDeepStrictEqual(left === void 0 ? void 0 : JSON.parse(JSON.stringify(left)), right === void 0 ? void 0 : JSON.parse(JSON.stringify(right)));
+}
+async function currentAttempt(stores, ref) {
+	const { taskId, attempt } = taskAttemptRefSchema.parse(ref);
+	const task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt || task.state !== "running") throw new ExecutionFenceError(`Execution requires running Task ${taskId} at attempt ${attempt}`);
+	return task;
+}
+/**
+* Constructs the stable provider idempotency key for one exact Task attempt.
+* Persist or deterministically recreate this key across launch recovery; a new attempt gets a new key.
+*/
+function executionLaunchKey(ref) {
+	const { taskId, attempt } = taskAttemptRefSchema.parse(ref);
+	return executionLaunchKeySchema.parse(`factory-task:${taskId}:${attempt}`);
+}
+/**
+* Starts or reattaches one coding execution after dispatch has admitted its Task.
+*
+* @remarks
+* The Task must still be `running` on the requested attempt and name exactly one enabled matching
+* repository. If an execution is already recorded, this method inspects it and returns it only
+* when the provider confirms it is active; it never starts an implicit replacement for a finished
+* or expired handle.
+*
+* For a new launch, the adapter receives a stable key derived from the Task attempt. The method
+* returns only after the provider reference is durably bound to that attempt. If acceptance or
+* the binding write is ambiguous, it throws `ExecutionLaunchPendingError`; retry this operation
+* with the same request so the same key can recover the launch. Reread the Task before applying
+* any other error, because a concurrent writer may have replaced the attempt.
+*
+* @param options - Validated request, required stores, and provider adapter.
+* @returns The recorded provider execution for the current running attempt.
+* @throws `ExecutionFenceError` when Task attempt or execution ownership changes.
+* @throws `ExecutionLaunchPendingError` when provider acceptance or durable binding is ambiguous.
+*/
+async function launchExecution(options) {
+	const { stores, adapter } = options;
+	const request = codingExecutionRequestSchema.parse(options.request);
+	const ref = {
+		taskId: request.taskId,
+		attempt: request.attempt
+	};
+	const task = await currentAttempt(stores, ref);
+	if (task.repositoryIds.length !== 1) throw new Error("Execution requires exactly one repository");
+	const repository = await stores.repositories.get(task.repositoryIds[0]);
+	if (!repository?.enabled || repository.slug !== request.repository.slug) throw new Error("Execution repository must match the Task's enabled repository");
+	if (task.execution) {
+		const observed = await adapter.inspect(task.execution);
+		if (!sameExecution((await currentAttempt(stores, ref)).execution, task.execution)) throw new ExecutionFenceError("Execution changed during reattachment");
+		if (observed.status !== "active") throw new Error(`Execution is ${observed.status}; workflow must reconcile its outcome before continuing`);
+		return task.execution;
+	}
+	const execution = executionReferenceSchema.parse(await adapter.start({
+		request,
+		launchKey: executionLaunchKey(ref)
+	}));
+	try {
+		await stores.tasks.recordExecution(task.id, {
+			execution,
+			expectAttempt: task.attempt
+		});
+	} catch (error) {
+		let current;
+		try {
+			current = await stores.tasks.get(task.id);
+		} catch (cause) {
+			throw new ExecutionLaunchPendingError("Execution binding requires recovery with its original key", { cause });
+		}
+		if (!current || current.attempt !== task.attempt || current.state !== "running" || current.execution && !sameExecution(current.execution, execution)) {
+			await adapter.stop(execution);
+			throw error;
+		}
+		throw new ExecutionLaunchPendingError("Execution binding requires recovery with its original key", { cause: error });
+	}
+	return execution;
+}
+/**
+* Inspects a recorded execution without granting provider evidence lifecycle authority.
+*
+* @remarks
+* The Task must be running on the exact attempt and have a recorded execution. Ownership is
+* checked again after the provider call so a concurrent replacement cannot attach stale results.
+* Finished results are schema-validated and must identify that same execution. This method writes
+* no Task state or usage; the workflow decides how to validate evidence and transition afterward.
+*
+* @param options - Exact Task attempt, Task store, and provider adapter.
+* @returns Current provider state and a validated result when finished.
+* @throws `ExecutionFenceError` when the attempt or execution changes during inspection.
+*/
+async function inspectExecution(options) {
+	const { stores, adapter } = options;
+	const task = await currentAttempt(stores, options.task);
+	if (!task.execution) throw new Error(`Task ${options.task.taskId} has no recorded execution`);
+	const observed = await adapter.inspect(task.execution);
+	if (!sameExecution((await currentAttempt(stores, options.task)).execution, task.execution)) throw new ExecutionFenceError("Execution changed during inspection");
+	if (observed.status !== "finished") return observed;
+	const result = executionResultSchema.parse(observed.result);
+	if (!sameExecution(result.execution, task.execution)) throw new ExecutionFenceError("Result belongs to another execution");
+	return {
+		status: "finished",
+		result
+	};
+}
+/**
+* Records one adapter's immutable final usage packet without changing Task lifecycle state.
+*
+* @remarks
+* Known cost is delegated to the Task usage store under a deterministic turn key, making identical
+* replay non-charging. This API records an immutable final usage packet; an adapter must not also
+* report the same charges through per-step usage hooks, because those observations use independent
+* idempotency keys and would be added twice. When cost is unknown, an idempotent `usage_unresolved`
+* receipt is appended and the Task remains unsettled so its reservation is retained. The workflow
+* or reconciler must later supply measured usage before settlement.
+*
+* @param options - Exact Task attempt, final provider result, and persistence stores.
+* @returns The Task after usage persistence, or unchanged after unresolved-cost evidence.
+* @throws `ExecutionFenceError` when the result belongs to another attempt or execution.
+*/
+async function recordExecutionUsage(options) {
+	const { stores } = options;
+	const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);
+	const result = executionResultSchema.parse(options.result);
+	const task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt || !sameExecution(task.execution, result.execution)) throw new ExecutionFenceError("Usage belongs to a different Task attempt or execution");
+	if (result.usage.costUsd === void 0) {
+		await stores.receipts.append({
+			taskId,
+			repositoryIds: task.repositoryIds,
+			kind: task.kind,
+			state: "usage_unresolved",
+			phase: "budget",
+			attempt,
+			execution: result.execution,
+			reason: "Execution cost is unknown; retain the reservation until measured usage is available",
+			dedupeKey: `execution:${taskId}:${attempt}:usage-unresolved`
+		});
+		return task;
+	}
+	return stores.tasks.recordUsage(taskId, {
+		step: {
+			turnId: `execution:${attempt}:${result.execution.provider}:${result.execution.sessionId}`,
+			stepIndex: 0,
+			costUsd: result.usage.costUsd,
+			inputTokens: result.usage.inputTokens,
+			outputTokens: result.usage.outputTokens
+		},
+		fence: {
+			attempt,
+			execution: result.execution
+		}
+	});
+}
+/**
+* Cancels canonical Task work, then interrupts and settles its exact provider execution.
+*
+* @remarks
+* The Task first durably enters `cancelled`, preventing later workflow completion from winning.
+* Provider interruption happens afterward and cannot roll that transition back. An absent recorded
+* execution produces durable `cancellation_unresolved` evidence and throws. Since execution
+* binding accepts only running Tasks, a handle discovered after this point cannot be attached by
+* retrying this helper; application-owned reconciliation must stop that handle and persist its
+* cleanup evidence and measured settlement separately. If `adapter.stop` fails ambiguously, retry
+* this same call—the cancelled transition and adapter stop are both expected to be idempotent.
+*
+* Returned final usage is recorded once. Known cost then settles the Task; unknown cost retains the
+* reservation and leaves reconciliation evidence for later measurement.
+*
+* @param options - Exact Task attempt, cancellation reason, stores, and provider adapter.
+* @returns The cancelled Task after provider usage recording and any possible settlement.
+* @throws `ExecutionFenceError` when the attempt has been replaced.
+* @throws When execution discovery is unresolved or the provider stop request fails.
+*/
+async function cancelExecution(options) {
+	const { stores, adapter, reason } = options;
+	const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);
+	let task = await stores.tasks.get(taskId);
+	if (!task || task.attempt !== attempt) throw new ExecutionFenceError("Cancellation belongs to a replaced attempt");
+	if (task.state !== "cancelled") task = await stores.tasks.transition(taskId, "cancelled", {
+		expectFrom: task.state,
+		expectAttempt: attempt,
+		reason
+	});
+	if (!task.execution) {
+		const reason = "Cancellation is recorded; execution discovery is still required before stop and settlement";
+		await stores.receipts.append({
+			taskId,
+			repositoryIds: task.repositoryIds,
+			kind: task.kind,
+			state: "cancellation_unresolved",
+			phase: "cleanup",
+			attempt,
+			reason,
+			dedupeKey: `execution:${taskId}:${attempt}:cancellation-unresolved`
+		});
+		throw new Error(reason);
+	}
+	const result = executionResultSchema.parse(await adapter.stop(task.execution));
+	task = await recordExecutionUsage({
+		stores,
+		task: {
+			taskId,
+			attempt
+		},
+		result
+	});
+	return result.usage.costUsd === void 0 ? task : stores.tasks.settle(taskId, { cost: { totalUsd: task.usage.costUsd } });
+}
+//#endregion
+export { ExecutionFenceError, cancelExecution, executionLaunchKey, inspectExecution, launchExecution, recordExecutionUsage };
+
+//# sourceMappingURL=execution.mjs.map

package/dist/execution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.mjs","names":[],"sources":["../src/execution.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { ExecutionLaunchPendingError } from \"./dispatch\";\nimport {\n  codingExecutionRequestSchema,\n  executionLaunchKeySchema,\n  executionResultSchema,\n  taskAttemptRefSchema,\n  type CodingExecutionRequest,\n  type ExecutionResult,\n  type ExecutionLaunchKey,\n  type TaskAttemptRef,\n} from \"./schema/execution\";\nimport { executionReferenceSchema, type ExecutionReference, type Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Validated request and stable idempotency key passed to an execution provider. */\nexport interface StartExecutionInput {\n  /** Exact Task-attempt request validated before the provider is called. */\n  readonly request: CodingExecutionRequest;\n  /** Stable key that must identify the same provider launch across retries and process restarts. */\n  readonly launchKey: ExecutionLaunchKey;\n}\n\n/** Current provider state when inspecting one recorded execution. */\nexport type ExecutionInspectionResult =\n  | {\n      /** The recorded execution still exists and is safe for the workflow to reattach. */\n      status: \"active\";\n    }\n  | {\n      /** The provider can no longer inspect or reattach the recorded execution. */\n      status: \"expired\";\n    }\n  | {\n      /** The provider has immutable final evidence for the recorded execution. */\n      status: \"finished\";\n      result: ExecutionResult;\n    };\n\n/** Provider-neutral boundary for retry-safe execution start, inspection, and cancellation. */\nexport interface ExecutionAdapter {\n  /**\n   * Starts or recovers one launch by its stable key. Return only after provider acceptance is\n   * known. Throw `ExecutionLaunchPendingError` when acceptance is ambiguous; every other rejection\n   * promises that this call did not leave an untracked launch.\n   *\n   * @param input - Validated provider request and stable launch key.\n   * @returns The accepted execution reference for this logical launch.\n   */\n  start(input: StartExecutionInput): Promise<ExecutionReference>;\n  /**\n   * Observes one exact provider handle without starting replacement work. Only `active` confirms\n   * that reattachment is safe; `expired` and `finished` require workflow-owned reconciliation.\n   *\n   * @param execution - Exact provider handle previously recorded on the Task.\n   * @returns Current provider state and final result when finished.\n   */\n  inspect(execution: ExecutionReference): Promise<ExecutionInspectionResult>;\n  /**\n   * Idempotently requests a stop and returns the provider's final observed result and usage. An\n   * adapter may report cancellation even when immediate interruption is unsupported; callers that\n   * require proof of inactivity must use provider-specific confirmation.\n   *\n   * @param execution - Exact provider handle to stop or confirm inactive.\n   * @returns Immutable final result and usage for that execution.\n   */\n  stop(execution: ExecutionReference): Promise<ExecutionResult>;\n}\n\n/**\n * Error raised when an execution no longer matches the current running Task attempt.\n * Reread the Task and discard the stale observation; do not apply it to the replacement attempt.\n */\nexport class ExecutionFenceError extends Error {}\n\nfunction sameExecution(\n  left: ExecutionReference | undefined,\n  right: ExecutionReference | undefined,\n): boolean {\n  // JSON persistence omits optional undefined fields; compare the persisted representation.\n  return isDeepStrictEqual(\n    left === undefined ? undefined : JSON.parse(JSON.stringify(left)),\n    right === undefined ? undefined : JSON.parse(JSON.stringify(right)),\n  );\n}\n\nasync function currentAttempt(\n  stores: Pick<FactoryStores, \"tasks\">,\n  ref: TaskAttemptRef,\n): Promise<Task> {\n  const { taskId, attempt } = taskAttemptRefSchema.parse(ref);\n  const task = await stores.tasks.get(taskId);\n  if (!task || task.attempt !== attempt || task.state !== \"running\") {\n    throw new ExecutionFenceError(\n      `Execution requires running Task ${taskId} at attempt ${attempt}`,\n    );\n  }\n  return task;\n}\n\n/** Store capabilities required to launch or reattach a coding execution. */\nexport type LaunchExecutionStores = Pick<FactoryStores, \"repositories\" | \"tasks\">;\n\n/** Store capabilities required to inspect a coding execution. */\nexport type InspectExecutionStores = Pick<FactoryStores, \"tasks\">;\n\n/** Store capabilities required to persist final execution usage. */\nexport type RecordExecutionUsageStores = Pick<FactoryStores, \"receipts\" | \"tasks\">;\n\n/** Store capabilities required to cancel and settle a coding execution. */\nexport type CancelExecutionStores = RecordExecutionUsageStores;\n\n/**\n * Constructs the stable provider idempotency key for one exact Task attempt.\n * Persist or deterministically recreate this key across launch recovery; a new attempt gets a new key.\n */\nexport function executionLaunchKey(ref: TaskAttemptRef): ExecutionLaunchKey {\n  const { taskId, attempt } = taskAttemptRefSchema.parse(ref);\n  return executionLaunchKeySchema.parse(`factory-task:${taskId}:${attempt}`);\n}\n\n/** Dependencies and request used to start or reattach one coding execution. */\nexport interface LaunchExecutionOptions {\n  /** Task and repository reads plus the durable execution-binding write. */\n  readonly stores: LaunchExecutionStores;\n  /** Exact running Task attempt and single repository supplied to the provider. */\n  readonly request: CodingExecutionRequest;\n  /** Provider boundary responsible for idempotent start and exact-handle inspection. */\n  readonly adapter: ExecutionAdapter;\n}\n\n/**\n * Starts or reattaches one coding execution after dispatch has admitted its Task.\n *\n * @remarks\n * The Task must still be `running` on the requested attempt and name exactly one enabled matching\n * repository. If an execution is already recorded, this method inspects it and returns it only\n * when the provider confirms it is active; it never starts an implicit replacement for a finished\n * or expired handle.\n *\n * For a new launch, the adapter receives a stable key derived from the Task attempt. The method\n * returns only after the provider reference is durably bound to that attempt. If acceptance or\n * the binding write is ambiguous, it throws `ExecutionLaunchPendingError`; retry this operation\n * with the same request so the same key can recover the launch. Reread the Task before applying\n * any other error, because a concurrent writer may have replaced the attempt.\n *\n * @param options - Validated request, required stores, and provider adapter.\n * @returns The recorded provider execution for the current running attempt.\n * @throws `ExecutionFenceError` when Task attempt or execution ownership changes.\n * @throws `ExecutionLaunchPendingError` when provider acceptance or durable binding is ambiguous.\n */\nexport async function launchExecution(\n  options: LaunchExecutionOptions,\n): Promise<ExecutionReference> {\n  const { stores, adapter } = options;\n  const request = codingExecutionRequestSchema.parse(options.request);\n  const ref = { taskId: request.taskId, attempt: request.attempt };\n  const task = await currentAttempt(stores, ref);\n  if (task.repositoryIds.length !== 1) throw new Error(\"Execution requires exactly one repository\");\n  const repository = await stores.repositories.get(task.repositoryIds[0]!);\n  if (!repository?.enabled || repository.slug !== request.repository.slug) {\n    throw new Error(\"Execution repository must match the Task's enabled repository\");\n  }\n  if (task.execution) {\n    const observed = await adapter.inspect(task.execution);\n    const current = await currentAttempt(stores, ref);\n    if (!sameExecution(current.execution, task.execution))\n      throw new ExecutionFenceError(\"Execution changed during reattachment\");\n    if (observed.status !== \"active\")\n      throw new Error(\n        `Execution is ${observed.status}; workflow must reconcile its outcome before continuing`,\n      );\n    return task.execution;\n  }\n  const execution = executionReferenceSchema.parse(\n    await adapter.start({ request, launchKey: executionLaunchKey(ref) }),\n  );\n  try {\n    await stores.tasks.recordExecution(task.id, {\n      execution: execution,\n      expectAttempt: task.attempt,\n    });\n  } catch (error) {\n    let current;\n    try {\n      current = await stores.tasks.get(task.id);\n    } catch (cause) {\n      throw new ExecutionLaunchPendingError(\n        \"Execution binding requires recovery with its original key\",\n        { cause },\n      );\n    }\n    if (\n      !current ||\n      current.attempt !== task.attempt ||\n      current.state !== \"running\" ||\n      (current.execution && !sameExecution(current.execution, execution))\n    ) {\n      await adapter.stop(execution);\n      throw error;\n    }\n    throw new ExecutionLaunchPendingError(\n      \"Execution binding requires recovery with its original key\",\n      { cause: error },\n    );\n  }\n  return execution;\n}\n\n/** Dependencies and Task-attempt identity used to inspect one execution. */\nexport interface InspectExecutionOptions {\n  /** Task read used to establish and recheck the execution fence. */\n  readonly stores: InspectExecutionStores;\n  /** Exact running Task attempt whose recorded execution may be inspected. */\n  readonly task: TaskAttemptRef;\n  /** Provider boundary used only for observation. */\n  readonly adapter: ExecutionAdapter;\n}\n\n/**\n * Inspects a recorded execution without granting provider evidence lifecycle authority.\n *\n * @remarks\n * The Task must be running on the exact attempt and have a recorded execution. Ownership is\n * checked again after the provider call so a concurrent replacement cannot attach stale results.\n * Finished results are schema-validated and must identify that same execution. This method writes\n * no Task state or usage; the workflow decides how to validate evidence and transition afterward.\n *\n * @param options - Exact Task attempt, Task store, and provider adapter.\n * @returns Current provider state and a validated result when finished.\n * @throws `ExecutionFenceError` when the attempt or execution changes during inspection.\n */\nexport async function inspectExecution(\n  options: InspectExecutionOptions,\n): Promise<ExecutionInspectionResult> {\n  const { stores, adapter } = options;\n  const task = await currentAttempt(stores, options.task);\n  if (!task.execution) throw new Error(`Task ${options.task.taskId} has no recorded execution`);\n  const observed = await adapter.inspect(task.execution);\n  const current = await currentAttempt(stores, options.task);\n  if (!sameExecution(current.execution, task.execution))\n    throw new ExecutionFenceError(\"Execution changed during inspection\");\n  if (observed.status !== \"finished\") return observed;\n  const result = executionResultSchema.parse(observed.result);\n  if (!sameExecution(result.execution, task.execution))\n    throw new ExecutionFenceError(\"Result belongs to another execution\");\n  return { status: \"finished\", result };\n}\n\n/** Dependencies, Task-attempt identity, and provider result used to record usage. */\nexport interface RecordExecutionUsageOptions {\n  /** Receipt and Task stores used for idempotent usage persistence. */\n  readonly stores: RecordExecutionUsageStores;\n  /** Exact Task attempt that owns the provider result. */\n  readonly task: TaskAttemptRef;\n  /** Final provider result whose execution must match the Task's recorded handle. */\n  readonly result: ExecutionResult;\n}\n\n/**\n * Records one adapter's immutable final usage packet without changing Task lifecycle state.\n *\n * @remarks\n * Known cost is delegated to the Task usage store under a deterministic turn key, making identical\n * replay non-charging. This API records an immutable final usage packet; an adapter must not also\n * report the same charges through per-step usage hooks, because those observations use independent\n * idempotency keys and would be added twice. When cost is unknown, an idempotent `usage_unresolved`\n * receipt is appended and the Task remains unsettled so its reservation is retained. The workflow\n * or reconciler must later supply measured usage before settlement.\n *\n * @param options - Exact Task attempt, final provider result, and persistence stores.\n * @returns The Task after usage persistence, or unchanged after unresolved-cost evidence.\n * @throws `ExecutionFenceError` when the result belongs to another attempt or execution.\n */\nexport async function recordExecutionUsage(options: RecordExecutionUsageOptions): Promise<Task> {\n  const { stores } = options;\n  const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);\n  const result = executionResultSchema.parse(options.result);\n  const task = await stores.tasks.get(taskId);\n  if (!task || task.attempt !== attempt || !sameExecution(task.execution, result.execution)) {\n    throw new ExecutionFenceError(\"Usage belongs to a different Task attempt or execution\");\n  }\n  if (result.usage.costUsd === undefined) {\n    await stores.receipts.append({\n      taskId,\n      repositoryIds: task.repositoryIds,\n      kind: task.kind,\n      state: \"usage_unresolved\",\n      phase: \"budget\",\n      attempt,\n      execution: result.execution,\n      reason: \"Execution cost is unknown; retain the reservation until measured usage is available\",\n      dedupeKey: `execution:${taskId}:${attempt}:usage-unresolved`,\n    });\n    return task;\n  }\n  return stores.tasks.recordUsage(taskId, {\n    step: {\n      turnId: `execution:${attempt}:${result.execution.provider}:${result.execution.sessionId}`,\n      stepIndex: 0,\n      costUsd: result.usage.costUsd,\n      inputTokens: result.usage.inputTokens,\n      outputTokens: result.usage.outputTokens,\n    },\n    fence: { attempt, execution: result.execution },\n  });\n}\n\n/** Dependencies and reason used to cancel one exact Task execution attempt. */\nexport interface CancelExecutionOptions {\n  /** Task and receipt stores used for cancellation, usage, and settlement. */\n  readonly stores: CancelExecutionStores;\n  /** Exact attempt to cancel; replacement attempts are refused. */\n  readonly task: TaskAttemptRef;\n  /** Provider boundary used to request an idempotent stop and read its final observed result. */\n  readonly adapter: ExecutionAdapter;\n  /** Human-readable cancellation reason retained in lifecycle evidence. */\n  readonly reason: string;\n}\n\n/**\n * Cancels canonical Task work, then interrupts and settles its exact provider execution.\n *\n * @remarks\n * The Task first durably enters `cancelled`, preventing later workflow completion from winning.\n * Provider interruption happens afterward and cannot roll that transition back. An absent recorded\n * execution produces durable `cancellation_unresolved` evidence and throws. Since execution\n * binding accepts only running Tasks, a handle discovered after this point cannot be attached by\n * retrying this helper; application-owned reconciliation must stop that handle and persist its\n * cleanup evidence and measured settlement separately. If `adapter.stop` fails ambiguously, retry\n * this same call—the cancelled transition and adapter stop are both expected to be idempotent.\n *\n * Returned final usage is recorded once. Known cost then settles the Task; unknown cost retains the\n * reservation and leaves reconciliation evidence for later measurement.\n *\n * @param options - Exact Task attempt, cancellation reason, stores, and provider adapter.\n * @returns The cancelled Task after provider usage recording and any possible settlement.\n * @throws `ExecutionFenceError` when the attempt has been replaced.\n * @throws When execution discovery is unresolved or the provider stop request fails.\n */\nexport async function cancelExecution(options: CancelExecutionOptions): Promise<Task> {\n  const { stores, adapter, reason } = options;\n  const { taskId, attempt } = taskAttemptRefSchema.parse(options.task);\n  let task = await stores.tasks.get(taskId);\n  if (!task || task.attempt !== attempt)\n    throw new ExecutionFenceError(\"Cancellation belongs to a replaced attempt\");\n  if (task.state !== \"cancelled\") {\n    task = await stores.tasks.transition(taskId, \"cancelled\", {\n      expectFrom: task.state,\n      expectAttempt: attempt,\n      reason,\n    });\n  }\n  if (!task.execution) {\n    const reason =\n      \"Cancellation is recorded; execution discovery is still required before stop and settlement\";\n    await stores.receipts.append({\n      taskId,\n      repositoryIds: task.repositoryIds,\n      kind: task.kind,\n      state: \"cancellation_unresolved\",\n      phase: \"cleanup\",\n      attempt,\n      reason,\n      dedupeKey: `execution:${taskId}:${attempt}:cancellation-unresolved`,\n    });\n    throw new Error(reason);\n  }\n  const result = executionResultSchema.parse(await adapter.stop(task.execution));\n  task = await recordExecutionUsage({ stores, task: { taskId, attempt }, result });\n  return result.usage.costUsd === undefined\n    ? task\n    : stores.tasks.settle(taskId, { cost: { totalUsd: task.usage!.costUsd } });\n}\n"],"mappings":"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"}

package/dist/finding-remediation/admission.d.mts

@@ -0,0 +1,53 @@
+import { ApprovalPolicy } from "../approval.mjs";
+import { RepositoryId, SignalId, TaskId } from "../schema/id.mjs";
+import { AgentRoute } from "../agent-routes.mjs";
+import { ReplyTo } from "../schema/common.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { Finding } from "../schema/finding.mjs";
+//#region src/finding-remediation/admission.d.ts
+/** Store capabilities required to admit a finding and its remediation Task. */
+type AdmitFindingStores = Pick<FactoryStores, "repositories" | "signals" | "tasks">;
+/** Routing, approval, provenance, and reply policy for admitting a finding to remediation. */
+interface AdmitFindingOptions {
+  /** Application-selected route for executing the resulting fix. */
+  readonly route: AgentRoute;
+  /** Signal source the finding is recorded under. Defaults to security_scan. */
+  readonly source?: string;
+  /** Which resulting Tasks wait for a human. Defaults to the neutral allow policy. */
+  readonly approval?: ApprovalPolicy;
+  /** Inherit a trusted originating Task's reply destination, when available. */
+  readonly replyTo?: ReplyTo;
+  /** Human initiator retained when a requested investigation creates a separate repair root. */
+  readonly operator?: string;
+}
+/** Repository finding and remediation policy supplied to one admission attempt. */
+interface AdmitFindingInput extends AdmitFindingOptions {
+  readonly repositoryId: RepositoryId;
+  readonly finding: Finding;
+}
+/** Outcome of admitting a finding, including missing-repository and duplicate no-ops. */
+type AdmitFindingResult = {
+  recorded: false;
+  reasonCode: "repository_not_found";
+  reason: string;
+} | {
+  recorded: false;
+  reasonCode: "duplicate";
+  reason: string;
+  duplicate: true;
+  signalId: SignalId;
+} | {
+  recorded: true;
+  signalId: SignalId;
+  taskId: TaskId;
+  approval: "required" | "not_required";
+};
+/**
+ * Admit one finding as an accepted Signal and a routed remediation Task.
+ * The finding fingerprint is the Signal delivery id, making repeated reports
+ * of the same problem idempotent.
+ */
+declare function admitFinding(stores: AdmitFindingStores, input: AdmitFindingInput): Promise<AdmitFindingResult>;
+//#endregion
+export { AdmitFindingInput, AdmitFindingOptions, AdmitFindingResult, AdmitFindingStores, admitFinding };
+//# sourceMappingURL=admission.d.mts.map

package/dist/finding-remediation/admission.mjs

@@ -0,0 +1,90 @@
+import { allowByDefaultApprovalPolicy, requiresApproval } from "../approval.mjs";
+import { routeTaskWork } from "../agent-routes.mjs";
+import { findingFingerprint } from "../findings/fingerprint.mjs";
+//#region src/finding-remediation/admission.ts
+function isLostRaceError(error) {
+	return error instanceof Error && (error.name === "VersionConflictError" || error.name === "InvalidTransitionError");
+}
+/**
+* Admit one finding as an accepted Signal and a routed remediation Task.
+* The finding fingerprint is the Signal delivery id, making repeated reports
+* of the same problem idempotent.
+*/
+async function admitFinding(stores, input) {
+	const { repositoryId, finding } = input;
+	const options = input;
+	if (options.route.taskKind !== "code_change") throw new Error("Finding fixes require a code_change agent route.");
+	const source = options.source ?? "security_scan";
+	if (await stores.repositories.get(repositoryId) === null) return {
+		recorded: false,
+		reasonCode: "repository_not_found",
+		reason: `repository ${repositoryId} does not exist`
+	};
+	const fingerprint = findingFingerprint(repositoryId, finding);
+	const signal = await stores.signals.create({
+		repositoryId,
+		source,
+		deliveryId: fingerprint,
+		replyTo: options.replyTo ?? {
+			channel: "finding",
+			address: fingerprint
+		},
+		payload: finding
+	});
+	if (signal.outcome !== "pending") return {
+		recorded: false,
+		reasonCode: "duplicate",
+		duplicate: true,
+		signalId: signal.id,
+		reason: `already recorded as ${signal.id}`
+	};
+	try {
+		await stores.signals.decide(signal.id, {
+			outcome: "accepted",
+			detail: finding.priority,
+			reason: `${finding.tool ?? "scanner"} reported it, ${finding.verification.level} by ${finding.verification.method}`
+		});
+	} catch (error) {
+		if (isLostRaceError(error)) {
+			const current = await stores.signals.get(signal.id);
+			if (current !== null && current.outcome !== "pending") return {
+				recorded: false,
+				reasonCode: "duplicate",
+				duplicate: true,
+				signalId: signal.id,
+				reason: `already recorded as ${signal.id}`
+			};
+		}
+		throw error;
+	}
+	const approval = requiresApproval(options.approval ?? allowByDefaultApprovalPolicy, {
+		source,
+		kind: "code_change",
+		priority: finding.priority
+	});
+	const task = await stores.tasks.create({
+		repositoryIds: [repositoryId],
+		kind: "code_change",
+		work: routeTaskWork({
+			route: options.route,
+			title: finding.title.trim().slice(0, 256),
+			input: { signalId: signal.id }
+		}),
+		origin: {
+			signalId: signal.id,
+			...options.operator === void 0 ? {} : { operator: options.operator }
+		},
+		replyTo: signal.replyTo,
+		...approval ? { approval: "required" } : {}
+	});
+	return {
+		recorded: true,
+		signalId: signal.id,
+		taskId: task.id,
+		approval: approval ? "required" : "not_required"
+	};
+}
+//#endregion
+export { admitFinding };
+
+//# sourceMappingURL=admission.mjs.map

package/dist/finding-remediation/admission.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.mjs","names":[],"sources":["../../src/finding-remediation/admission.ts"],"sourcesContent":["import { routeTaskWork, type AgentRoute } from \"../agent-routes\";\nimport { allowByDefaultApprovalPolicy, requiresApproval, type ApprovalPolicy } from \"../approval\";\nimport { findingFingerprint } from \"../findings/fingerprint\";\nimport type { ReplyTo } from \"../schema/common\";\nimport type { Finding } from \"../schema/finding\";\nimport type { RepositoryId, SignalId, TaskId } from \"../schema/id\";\nimport type { FactoryStores } from \"../store/engine\";\n\n/** Store capabilities required to admit a finding and its remediation Task. */\nexport type AdmitFindingStores = Pick<FactoryStores, \"repositories\" | \"signals\" | \"tasks\">;\n\n// Matched by name, not instanceof: the Blob driver is a separate package entry\n// point, so its error classes are distinct objects from any imported here.\nfunction isLostRaceError(error: unknown): boolean {\n  return (\n    error instanceof Error &&\n    (error.name === \"VersionConflictError\" || error.name === \"InvalidTransitionError\")\n  );\n}\n\n/** Routing, approval, provenance, and reply policy for admitting a finding to remediation. */\nexport interface AdmitFindingOptions {\n  /** Application-selected route for executing the resulting fix. */\n  readonly route: AgentRoute;\n  /** Signal source the finding is recorded under. Defaults to security_scan. */\n  readonly source?: string;\n  /** Which resulting Tasks wait for a human. Defaults to the neutral allow policy. */\n  readonly approval?: ApprovalPolicy;\n  /** Inherit a trusted originating Task's reply destination, when available. */\n  readonly replyTo?: ReplyTo;\n  /** Human initiator retained when a requested investigation creates a separate repair root. */\n  readonly operator?: string;\n}\n\n/** Repository finding and remediation policy supplied to one admission attempt. */\nexport interface AdmitFindingInput extends AdmitFindingOptions {\n  readonly repositoryId: RepositoryId;\n  readonly finding: Finding;\n}\n\n/** Outcome of admitting a finding, including missing-repository and duplicate no-ops. */\nexport type AdmitFindingResult =\n  | { recorded: false; reasonCode: \"repository_not_found\"; reason: string }\n  | {\n      recorded: false;\n      reasonCode: \"duplicate\";\n      reason: string;\n      duplicate: true;\n      signalId: SignalId;\n    }\n  | {\n      recorded: true;\n      signalId: SignalId;\n      taskId: TaskId;\n      approval: \"required\" | \"not_required\";\n    };\n\n/**\n * Admit one finding as an accepted Signal and a routed remediation Task.\n * The finding fingerprint is the Signal delivery id, making repeated reports\n * of the same problem idempotent.\n */\nexport async function admitFinding(\n  stores: AdmitFindingStores,\n  input: AdmitFindingInput,\n): Promise<AdmitFindingResult> {\n  const { repositoryId, finding } = input;\n  const options: AdmitFindingOptions = input;\n  if (options.route.taskKind !== \"code_change\") {\n    throw new Error(\"Finding fixes require a code_change agent route.\");\n  }\n  const source = options.source ?? \"security_scan\";\n  const repository = await stores.repositories.get(repositoryId);\n  if (repository === null) {\n    return {\n      recorded: false,\n      reasonCode: \"repository_not_found\",\n      reason: `repository ${repositoryId} does not exist`,\n    };\n  }\n\n  const fingerprint = findingFingerprint(repositoryId, finding);\n  const signal = await stores.signals.create({\n    repositoryId,\n    source,\n    deliveryId: fingerprint,\n    replyTo: options.replyTo ?? { channel: \"finding\", address: fingerprint },\n    payload: finding,\n  });\n  if (signal.outcome !== \"pending\") {\n    return {\n      recorded: false,\n      reasonCode: \"duplicate\",\n      duplicate: true,\n      signalId: signal.id,\n      reason: `already recorded as ${signal.id}`,\n    };\n  }\n\n  try {\n    await stores.signals.decide(signal.id, {\n      outcome: \"accepted\",\n      detail: finding.priority,\n      reason: `${finding.tool ?? \"scanner\"} reported it, ${finding.verification.level} by ${finding.verification.method}`,\n    });\n  } catch (error) {\n    if (isLostRaceError(error)) {\n      const current = await stores.signals.get(signal.id);\n      if (current !== null && current.outcome !== \"pending\") {\n        return {\n          recorded: false,\n          reasonCode: \"duplicate\",\n          duplicate: true,\n          signalId: signal.id,\n          reason: `already recorded as ${signal.id}`,\n        };\n      }\n    }\n    throw error;\n  }\n\n  const approval = requiresApproval(options.approval ?? allowByDefaultApprovalPolicy, {\n    source,\n    kind: \"code_change\",\n    priority: finding.priority,\n  });\n  const task = await stores.tasks.create({\n    repositoryIds: [repositoryId],\n    kind: \"code_change\",\n    work: routeTaskWork({\n      route: options.route,\n      title: finding.title.trim().slice(0, 256),\n      input: { signalId: signal.id },\n    }),\n    origin: {\n      signalId: signal.id,\n      ...(options.operator === undefined ? {} : { operator: options.operator }),\n    },\n    replyTo: signal.replyTo,\n    ...(approval ? { approval: \"required\" as const } : {}),\n  });\n\n  return {\n    recorded: true,\n    signalId: signal.id,\n    taskId: task.id,\n    approval: approval ? \"required\" : \"not_required\",\n  };\n}\n"],"mappings":";;;;AAaA,SAAS,gBAAgB,OAAyB;CAChD,OACE,iBAAiB,UAChB,MAAM,SAAS,0BAA0B,MAAM,SAAS;AAE7D;;;;;;AA4CA,eAAsB,aACpB,QACA,OAC6B;CAC7B,MAAM,EAAE,cAAc,YAAY;CAClC,MAAM,UAA+B;CACrC,IAAI,QAAQ,MAAM,aAAa,eAC7B,MAAM,IAAI,MAAM,kDAAkD;CAEpE,MAAM,SAAS,QAAQ,UAAU;CAEjC,IAAI,MADqB,OAAO,aAAa,IAAI,YAAY,MAC1C,MACjB,OAAO;EACL,UAAU;EACV,YAAY;EACZ,QAAQ,cAAc,aAAa;CACrC;CAGF,MAAM,cAAc,mBAAmB,cAAc,OAAO;CAC5D,MAAM,SAAS,MAAM,OAAO,QAAQ,OAAO;EACzC;EACA;EACA,YAAY;EACZ,SAAS,QAAQ,WAAW;GAAE,SAAS;GAAW,SAAS;EAAY;EACvE,SAAS;CACX,CAAC;CACD,IAAI,OAAO,YAAY,WACrB,OAAO;EACL,UAAU;EACV,YAAY;EACZ,WAAW;EACX,UAAU,OAAO;EACjB,QAAQ,uBAAuB,OAAO;CACxC;CAGF,IAAI;EACF,MAAM,OAAO,QAAQ,OAAO,OAAO,IAAI;GACrC,SAAS;GACT,QAAQ,QAAQ;GAChB,QAAQ,GAAG,QAAQ,QAAQ,UAAU,gBAAgB,QAAQ,aAAa,MAAM,MAAM,QAAQ,aAAa;EAC7G,CAAC;CACH,SAAS,OAAO;EACd,IAAI,gBAAgB,KAAK,GAAG;GAC1B,MAAM,UAAU,MAAM,OAAO,QAAQ,IAAI,OAAO,EAAE;GAClD,IAAI,YAAY,QAAQ,QAAQ,YAAY,WAC1C,OAAO;IACL,UAAU;IACV,YAAY;IACZ,WAAW;IACX,UAAU,OAAO;IACjB,QAAQ,uBAAuB,OAAO;GACxC;EAEJ;EACA,MAAM;CACR;CAEA,MAAM,WAAW,iBAAiB,QAAQ,YAAY,8BAA8B;EAClF;EACA,MAAM;EACN,UAAU,QAAQ;CACpB,CAAC;CACD,MAAM,OAAO,MAAM,OAAO,MAAM,OAAO;EACrC,eAAe,CAAC,YAAY;EAC5B,MAAM;EACN,MAAM,cAAc;GAClB,OAAO,QAAQ;GACf,OAAO,QAAQ,MAAM,KAAK,CAAC,CAAC,MAAM,GAAG,GAAG;GACxC,OAAO,EAAE,UAAU,OAAO,GAAG;EAC/B,CAAC;EACD,QAAQ;GACN,UAAU,OAAO;GACjB,GAAI,QAAQ,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU,QAAQ,SAAS;EACzE;EACA,SAAS,OAAO;EAChB,GAAI,WAAW,EAAE,UAAU,WAAoB,IAAI,CAAC;CACtD,CAAC;CAED,OAAO;EACL,UAAU;EACV,UAAU,OAAO;EACjB,QAAQ,KAAK;EACb,UAAU,WAAW,aAAa;CACpC;AACF"}

package/dist/finding-remediation/brief.d.mts

@@ -0,0 +1,14 @@
+import { Repository } from "../schema/repository.mjs";
+import { Task } from "../schema/task.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { Finding } from "../schema/finding.mjs";
+//#region src/finding-remediation/brief.d.ts
+/** Store capabilities required to recover a finding from a Task's source Signal. */
+type FindingLookupStores = Pick<FactoryStores, "signals">;
+/** Find the finding behind a Task when its originating Signal carries one. */
+declare function findFindingForTask(stores: FindingLookupStores, task: Task): Promise<Finding | null>;
+/** Format the factual starting brief for a finding-remediation Task. */
+declare function formatFindingRemediationBrief(task: Task, repository: Repository, finding: Finding | null): string;
+//#endregion
+export { FindingLookupStores, findFindingForTask, formatFindingRemediationBrief };
+//# sourceMappingURL=brief.d.mts.map