@vercel/factory 0.0.14 → 0.0.16

package/dist/store/task-messages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-messages.mjs","names":[],"sources":["../../src/store/task-messages.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { WorkNotification } from \"./work-notifications\";\nimport type { DateClock } from \"../schema/common\";\nimport { taskAttemptRefSchema, type TaskAttemptRef } from \"../schema/execution\";\nimport { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport { SCHEMA_VERSION } from \"../schema/common\";\nimport { taskIdSchema, type TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport {\n  MAX_TASK_INBOX_PENDING,\n  sendTaskMessageInputSchema,\n  taskInboxSchema,\n  taskMessageIdSchema,\n  taskMessageClaimSchema,\n  taskMessagePrincipalSchema,\n  taskMessageProcessingSchema,\n  taskMessageReservationSchema,\n  taskMessageSchema,\n  taskMessageDiscardSchema,\n  type SendTaskMessageInput,\n  type TaskInbox,\n  type TaskMessage,\n  type TaskMessageClaim,\n  type TaskMessageDiscard,\n  type TaskMessageId,\n  type TaskMessagePrincipal,\n  type TaskMessageProcessing,\n  type TaskMessageProtocolBinding,\n  type TaskMessageProtocols,\n} from \"../schema/task-message\";\nimport {\n  RecordExistsError,\n  VersionConflictError,\n  type CollectionName,\n  type StoreDriver,\n} from \"./driver\";\n\n/** Operation categories evaluated by the Task message authorization boundary. */\nexport type TaskMessageAction = \"send\" | \"send_result\" | \"read\" | \"claim\" | \"complete\" | \"discard\";\n/** Principal, requested action, and validated Task scope for one authorization decision. */\nexport interface TaskMessageAuthorizationInput {\n  readonly principal: TaskMessagePrincipal;\n  readonly action: TaskMessageAction;\n  readonly fromTask?: Task;\n  readonly toTask: Task;\n}\n/** Trusted application authorization, NOT HTTP authentication. Only literal true grants access. */\nexport type TaskMessageAuthorize = (\n  input: TaskMessageAuthorizationInput,\n) => boolean | Promise<boolean>;\n/** Engine-owned dependencies and deny-by-default policy used to create a Task message store. */\nexport interface CreateTaskMessageStoreOptions {\n  readonly driver: StoreDriver;\n  readonly now: DateClock;\n  /**\n   * Main engine supplies schema-validated snapshots. Task reads and inbox CAS are separate:\n   * cancellation/retry can race send, claim, and caller effects. The envelope retains expectAttempt;\n   * consumers must fence effects at their application boundary, not assume atomic cancellation here.\n   */\n  readonly getTask: (id: TaskId) => Promise<Task | null>;\n  readonly protocols: TaskMessageProtocols;\n  readonly authorize: TaskMessageAuthorize;\n  readonly notify?: (event: WorkNotification) => Promise<void>;\n}\n\n/** Authenticated principal and immutable message intent used for one send operation. */\nexport interface TaskMessageSendInput<\n  Type extends TaskMessageProtocolBinding = TaskMessageProtocolBinding,\n> {\n  readonly principal: TaskMessagePrincipal;\n  readonly message: SendTaskMessageInput<Type>;\n}\n\n/** Authenticated principal and recipient identifying one Task inbox. */\nexport interface TaskMessageRecipientInput {\n  readonly principal: TaskMessagePrincipal;\n  readonly toTaskId: TaskId;\n}\n\n/** Authenticated principal, recipient, and immutable message identifying one inbox record. */\nexport interface TaskMessageLookupInput extends TaskMessageRecipientInput {\n  readonly messageId: TaskMessageId;\n}\n\n/** Recipient attempt and bounded lease requested when claiming one Task message. */\nexport interface ClaimTaskMessageInput extends Pick<TaskMessageRecipientInput, \"principal\"> {\n  readonly task: TaskAttemptRef;\n  readonly leaseMs: number;\n  readonly recoverCompleted?: boolean;\n}\n\n/** Authenticated lease and committed-effects attestation used to acknowledge one message. */\nexport interface CompleteTaskMessageInput {\n  readonly principal: TaskMessagePrincipal;\n  readonly claim: TaskMessageClaim;\n  readonly effectsCommitted: true;\n}\n\n/** Authenticated lease whose current validity must be checked before an external effect. */\nexport interface AssertTaskMessageClaimInput {\n  readonly principal: TaskMessagePrincipal;\n  readonly claim: TaskMessageClaim;\n}\n\n/** Authorized reason for discarding one exact pending inbox head. */\nexport interface DiscardTaskMessageInput extends TaskMessageLookupInput {\n  readonly reason: string;\n}\n\n/** Message identity and stable operation name used to derive an external-effect key. */\nexport interface TaskMessageEffectKeyInput {\n  readonly messageId: TaskMessageId;\n  readonly operation: string;\n}\n\n/** Message and lease returned when one pending inbox head is claimed. */\nexport interface ClaimTaskMessageResult {\n  readonly claim: TaskMessageClaim;\n  readonly message: TaskMessage;\n}\n\n/** Trusted API for immutable Task messages, recipient inboxes, leases, and acknowledgments. */\nexport interface TaskMessageStore {\n  send<const Type extends TaskMessageProtocolBinding>(\n    input: TaskMessageSendInput<Type>,\n  ): Promise<TaskMessage<Type>>;\n  /** Trusted workflow delivery after the source outcome is persisted; requires separate send_result authorization. */\n  sendResult<const Type extends TaskMessageProtocolBinding>(\n    input: TaskMessageSendInput<Type>,\n  ): Promise<TaskMessage<Type>>;\n  get(input: TaskMessageLookupInput): Promise<TaskMessage | null>;\n  pending(input: TaskMessageRecipientInput): Promise<readonly TaskMessage[]>;\n  /**\n   * A stale attempt-fenced source or cancelled ordinary source raises TaskMessageSourceFenceError\n   * and leaves the head pending. Protocols default to attempt fencing; explicitly task-scoped\n   * protocols let workflow triggers survive source retries. Authorized discard can unblock the inbox.\n   * Source completion alone does not invalidate previously admitted messages from the same attempt.\n   * recoverCompleted defaults to false. It is a trusted application recovery capability for a\n   * succeeded/failed recipient: the caller must first validate an exact persisted decision for\n   * the pending message, then verify the claimed message matches it. It authorizes no new effects,\n   * never permits cancellation recovery, and does not bypass the authorization callback.\n   */\n  claim(input: ClaimTaskMessageInput): Promise<ClaimTaskMessageResult | null>;\n  /**\n   * Call only after effects commit. A matching recipient attempt may acknowledge in any state,\n   * including cancellation; acknowledgment authorizes no new effects. Leases are not exactly-once.\n   */\n  complete(input: CompleteTaskMessageInput): Promise<TaskMessageProcessing>;\n  /** Read-only claim/complete-authorized lease snapshot check, not a lease extension or external effect fence. Completed claims are invalid. */\n  assertClaim(input: AssertTaskMessageClaimInput): Promise<void>;\n  /** Discard only the pending head with no unexpired recipient lease, under explicit discard authorization. */\n  discard(input: DiscardTaskMessageInput): Promise<void>;\n  discarded(input: TaskMessageLookupInput): Promise<TaskMessageDiscard | null>;\n  processing(input: TaskMessageLookupInput): Promise<TaskMessageProcessing | null>;\n  /** Pure key derivation, not a read or an authorization capability. */\n  effectKey(input: TaskMessageEffectKeyInput): string;\n}\n/** Base error for Task message admission, authorization, and processing failures. */\nexport class TaskMessageError extends Error {}\n/** Error raised when an idempotency key is reused with different message intent. */\nexport class TaskMessageConflictError extends TaskMessageError {}\n/** Error raised when a configured Task message policy does not grant an operation. */\nexport class TaskMessageAuthorizationError extends TaskMessageError {}\n/** Error raised when a Task inbox claim is expired, replaced, or otherwise invalid. */\nexport class TaskMessageLeaseError extends TaskMessageError {}\n/** Error raised when an inbox head belongs to a stale or cancelled source attempt. */\nexport class TaskMessageSourceFenceError extends TaskMessageError {\n  constructor(\n    readonly messageId: TaskMessageId,\n    readonly source: TaskAttemptRef,\n    readonly currentAttempt: number,\n    readonly sourceState: Task[\"state\"],\n  ) {\n    super(\n      `Inbox blocked by message ${messageId}: source ${source.taskId} attempt ${source.attempt}, current attempt ${currentAttempt}, state ${sourceState}. Message remains pending; an explicitly authorized discard is required to unblock this inbox.`,\n    );\n    this.name = \"TaskMessageSourceFenceError\";\n  }\n}\n\n/**\n * Authorizes recipient-local operations and direct parent-child sends for a trusted\n * Task-bound principal while denying result delivery and discard.\n */\nexport const taskBoundMessagePolicy: TaskMessageAuthorize = ({\n  principal,\n  action,\n  fromTask,\n  toTask,\n}) => {\n  if (action === \"discard\" || action === \"send_result\") return false;\n  if (action !== \"send\") return principal.taskId === toTask.id;\n  if (!fromTask || !principal.taskId) return false;\n  return (\n    principal.taskId === fromTask.id &&\n    (fromTask.parentTaskId === toTask.id || toTask.parentTaskId === fromTask.id)\n  );\n};\nconst claimOptionsSchema = z.strictObject({\n  leaseMs: z\n    .number()\n    .int()\n    .min(1)\n    .max(300_000)\n    .describe(\"Processing lease duration, at most five minutes.\"),\n  recoverCompleted: z\n    .boolean()\n    .default(false)\n    .describe(\n      \"Trusted recovery of an exact existing decision on a succeeded/failed recipient at the same attempt; not permission for new effects or cancelled Tasks.\",\n    ),\n});\nconst acknowledgmentSchema = z.strictObject({\n  effectsCommitted: z.literal(true).describe(\"Effects committed before this acknowledgment.\"),\n});\nconst hash = (parts: readonly string[]): string =>\n  createHash(\"sha256\").update(JSON.stringify(parts)).digest(\"hex\");\nconst messageIdFor = (source: TaskId, operation: string): TaskMessageId =>\n  taskMessageIdSchema.parse(`msg_${hash([source, operation])}`);\nconst messageContent = ({ createdAt: _createdAt, ...content }: TaskMessage) => content;\nconst retryable = (error: unknown): boolean =>\n  error instanceof VersionConflictError || error instanceof RecordExistsError;\n\n/** Creates the trusted, CAS-backed Task message and recipient-inbox store. */\nexport function createTaskMessageStore(options: CreateTaskMessageStoreOptions): TaskMessageStore {\n  const { driver, now, getTask, protocols, authorize } = options;\n  if (typeof authorize !== \"function\")\n    throw new TaskMessageAuthorizationError(\n      \"Task messages require an explicit authorize callback; no access is granted by default\",\n    );\n\n  async function task(id: TaskId): Promise<Task> {\n    const value = await getTask(taskIdSchema.parse(id));\n    if (!value || value.id !== id) throw new TaskMessageError(`Missing Task ${id}`);\n    taskIdSchema.parse(value.rootTaskId);\n    return value;\n  }\n  async function scope(\n    principal: TaskMessagePrincipal,\n    action: TaskMessageAction,\n    toTaskId: TaskId,\n    fromTaskId?: TaskId,\n  ) {\n    const toTask = await task(toTaskId);\n    const fromTask = fromTaskId === undefined ? undefined : await task(fromTaskId);\n    if (fromTask && fromTask.rootTaskId !== toTask.rootTaskId)\n      throw new TaskMessageAuthorizationError(\"Cross-root Task messages are not permitted\");\n    if (\n      (action === \"send\" || action === \"send_result\") &&\n      principal.taskId !== undefined &&\n      principal.taskId !== fromTaskId\n    ) {\n      throw new TaskMessageAuthorizationError(\"Task-bound sender must equal fromTaskId\");\n    }\n    if ((await authorize(structuredClone({ principal, action, fromTask, toTask }))) !== true) {\n      throw new TaskMessageAuthorizationError(`Task message ${action} denied for ${principal.id}`);\n    }\n    return { fromTask, toTask };\n  }\n  function matchingAttempt(value: Task, expected: number): void {\n    if (value.attempt !== expected)\n      throw new TaskMessageError(\n        `Task ${value.id} requires current attempt ${value.attempt}; received ${expected}`,\n      );\n  }\n  function activeAttempt(value: Task, expected: number): void {\n    if (value.attempt !== expected || ![\"queued\", \"running\", \"needs_human\"].includes(value.state)) {\n      throw new TaskMessageError(\n        `Task ${value.id} requires current attempt ${value.attempt} and queued, running, or needs_human state`,\n      );\n    }\n  }\n  function resultAttempt(value: Task, expected: number): void {\n    matchingAttempt(value, expected);\n    if (![\"succeeded\", \"failed\", \"cancelled\"].includes(value.state)) {\n      throw new TaskMessageError(\n        `Task ${value.id} requires a persisted succeeded, failed, or cancelled outcome for result delivery`,\n      );\n    }\n  }\n  function claimableAttempt(value: Task, expected: number, recoverCompleted: boolean): void {\n    if (recoverCompleted && (value.state === \"succeeded\" || value.state === \"failed\"))\n      matchingAttempt(value, expected);\n    else activeAttempt(value, expected);\n  }\n  function parseMessage(value: unknown): TaskMessage {\n    // Zod retains explicit undefined, but JSON drivers omit it from immutable envelopes.\n    const { causationId, delivery, ...message } = taskMessageSchema.parse(value);\n    if (message.id !== messageIdFor(message.fromTaskId, message.operationId))\n      throw new TaskMessageConflictError(\n        \"Stored message ID does not match its source and operation\",\n      );\n    return {\n      ...message,\n      ...(causationId === undefined ? {} : { causationId }),\n      ...(delivery === undefined ? {} : { delivery }),\n      payload: protocols.validateStored(message.type, message.payload),\n    };\n  }\n  function correlateMessage<const Type extends TaskMessageProtocolBinding>(\n    message: TaskMessage,\n    type: Type,\n  ): TaskMessage<Type> {\n    if (message.type.id !== type.id || message.type.version !== type.version)\n      throw new TaskMessageConflictError(\"Message protocol differs from its send intent\");\n    const payload = protocols.validateStored(type, message.payload);\n    return structuredClone({ ...message, payload }) as TaskMessage<Type>;\n  }\n  async function deliveredMessage(intent: TaskMessage): Promise<TaskMessage | null> {\n    const stored = await driver.get(\"taskMessages\", intent.id);\n    if (!stored) return null;\n    const delivered = parseMessage(stored.value);\n    if (!isDeepStrictEqual(messageContent(delivered), messageContent(intent))) {\n      throw new TaskMessageConflictError(\n        `Operation ${intent.operationId} was reused with different content or attempt`,\n      );\n    }\n    return delivered;\n  }\n  async function immutable<T>(\n    collection: CollectionName,\n    id: string,\n    value: T,\n    parse: (value: unknown) => T,\n  ): Promise<T> {\n    const validated = parse(value);\n    try {\n      await driver.insert({ collection, id, value: validated });\n    } catch (error) {\n      if (!(error instanceof RecordExistsError)) throw error;\n      const stored = await driver.get(collection, id);\n      if (!stored || !isDeepStrictEqual(parse(stored.value), validated))\n        throw new TaskMessageConflictError(`Immutable record ${id} has different content`);\n    }\n    return validated;\n  }\n  async function inbox(toTaskId: TaskId) {\n    const stored = await driver.get(\"taskInboxes\", toTaskId);\n    const value = stored\n      ? taskInboxSchema.parse(stored.value)\n      : taskInboxSchema.parse({\n          schemaVersion: SCHEMA_VERSION,\n          toTaskId,\n          generation: 0,\n          pending: [],\n        });\n    if (value.toTaskId !== toTaskId) throw new TaskMessageError(\"Stored inbox recipient mismatch\");\n    value.pending = value.pending.map(parseMessage);\n    return { value, version: stored?.version };\n  }\n  async function saveInbox(value: TaskInbox, version: number | undefined): Promise<boolean> {\n    const validated = taskInboxSchema.parse(value);\n    try {\n      if (version === undefined)\n        await driver.insert({ collection: \"taskInboxes\", id: value.toTaskId, value: validated });\n      else\n        await driver.update({\n          collection: \"taskInboxes\",\n          id: value.toTaskId,\n          value: validated,\n          expectedVersion: version,\n        });\n      return true;\n    } catch (error) {\n      if (retryable(error)) return false;\n      throw error;\n    }\n  }\n  async function repair(\n    principal: TaskMessagePrincipal,\n    toTaskId: TaskId,\n    action: TaskMessageAction,\n    targetId?: TaskMessageId,\n  ) {\n    for (;;) {\n      await scope(principal, action, toTaskId);\n      const current = await inbox(toTaskId);\n      // Repair only projects validated, previously admitted intents and CAS-accepted resolutions.\n      // Callers must authorize each message they return or act on, not unrelated repair records.\n      for (const message of current.value.pending) {\n        if (targetId !== undefined && message.id !== targetId) continue;\n        await immutable(\"taskMessages\", message.id, message, parseMessage);\n      }\n      const { completion, rejection } = current.value;\n      const resolved = completion ?? rejection;\n      if (!resolved || (targetId !== undefined && resolved.messageId !== targetId)) return current;\n      if (completion)\n        await immutable(\"taskMessageProcessing\", completion.messageId, completion, (value) =>\n          taskMessageProcessingSchema.parse(value),\n        );\n      if (rejection)\n        await immutable(\"taskMessageDiscards\", rejection.messageId, rejection, (value) =>\n          taskMessageDiscardSchema.parse(value),\n        );\n      const next = {\n        ...current.value,\n        pending: current.value.pending.filter((message) => message.id !== resolved.messageId),\n        lease: undefined,\n        completion: undefined,\n        rejection: undefined,\n      };\n      if (await saveInbox(next, current.version)) continue;\n    }\n  }\n  async function reserve(message: TaskMessage, expectAttempt: number): Promise<TaskMessage> {\n    const key = `reservation_${message.id}`;\n    const reservation = taskMessageReservationSchema.parse({\n      schemaVersion: SCHEMA_VERSION,\n      message,\n      expectAttempt,\n    });\n    try {\n      await driver.insert({ collection: \"taskMessageProcessing\", id: key, value: reservation });\n      return message;\n    } catch (error) {\n      if (!(error instanceof RecordExistsError)) throw error;\n      const stored = await driver.get(\"taskMessageProcessing\", key);\n      if (!stored)\n        throw new TaskMessageConflictError(`Missing operation reservation ${message.id}`);\n      const existing = taskMessageReservationSchema.parse(stored.value);\n      const original = parseMessage(existing.message);\n      if (\n        existing.expectAttempt !== expectAttempt ||\n        !isDeepStrictEqual(messageContent(original), messageContent(message))\n      ) {\n        throw new TaskMessageConflictError(\n          `Operation ${message.operationId} was reused with different content or attempt`,\n        );\n      }\n      return original;\n    }\n  }\n  async function readMessage(\n    principal: TaskMessagePrincipal,\n    toTaskId: TaskId,\n    messageId: TaskMessageId,\n    action: TaskMessageAction,\n  ): Promise<TaskMessage | null> {\n    taskMessageIdSchema.parse(messageId);\n    await scope(principal, action, toTaskId);\n    await repair(principal, toTaskId, action, messageId);\n    const stored = await driver.get(\"taskMessages\", messageId);\n    if (!stored) return null;\n    const message = parseMessage(stored.value);\n    if (message.id !== messageId || message.toTaskId !== toTaskId)\n      throw new TaskMessageAuthorizationError(\"Message does not belong to this recipient\");\n    await scope(principal, action, toTaskId, message.fromTaskId);\n    return message;\n  }\n  async function processingRecord(messageId: TaskMessageId): Promise<TaskMessageProcessing | null> {\n    const stored = await driver.get(\"taskMessageProcessing\", messageId);\n    if (!stored) return null;\n    const record = taskMessageProcessingSchema.parse(stored.value);\n    if (record.messageId !== messageId)\n      throw new TaskMessageError(\"Processing record identity mismatch\");\n    return record;\n  }\n  async function discardRecord(messageId: TaskMessageId): Promise<TaskMessageDiscard | null> {\n    const stored = await driver.get(\"taskMessageDiscards\", messageId);\n    if (!stored) return null;\n    const record = taskMessageDiscardSchema.parse(stored.value);\n    if (record.messageId !== messageId)\n      throw new TaskMessageError(\"Discard record identity mismatch\");\n    return record;\n  }\n  async function requireLiveClaim(\n    principal: TaskMessagePrincipal,\n    claim: TaskMessageClaim,\n    current: TaskInbox,\n  ): Promise<Date> {\n    if (principal.id !== claim.principalId)\n      throw new TaskMessageAuthorizationError(\n        \"Only the claiming principal may validate this lease\",\n      );\n    matchingAttempt(await task(claim.toTaskId), claim.attempt);\n    const time = now();\n    if (\n      current.completion ||\n      current.rejection ||\n      current.generation !== claim.generation ||\n      !isDeepStrictEqual(current.lease, claim) ||\n      Date.parse(claim.expiresAt) <= time.getTime()\n    ) {\n      throw new TaskMessageLeaseError(\n        \"Lease expired, resolved, or was replaced; claim again before processing\",\n      );\n    }\n    return time;\n  }\n  function requireClaim(\n    record: TaskMessageProcessing,\n    claim: TaskMessageClaim,\n  ): TaskMessageProcessing {\n    const {\n      schemaVersion: _schemaVersion,\n      completedAt: _completedAt,\n      effectsCommitted: _effectsCommitted,\n      ...accepted\n    } = record;\n    if (!isDeepStrictEqual(accepted, claim))\n      throw new TaskMessageLeaseError(\n        \"Processing acknowledgment belongs to a different lease generation\",\n      );\n    return record;\n  }\n\n  async function send<const Type extends TaskMessageProtocolBinding>(\n    context: TaskMessagePrincipal,\n    input: SendTaskMessageInput<Type>,\n    delivery?: \"result\",\n  ): Promise<TaskMessage<Type>> {\n    const principal = taskMessagePrincipalSchema.parse(context);\n    const parsed = sendTaskMessageInputSchema.parse(input);\n    const payload = protocols.validate(input.type, parsed.payload);\n    const { expectAttempt } = parsed;\n    const action = delivery === \"result\" ? \"send_result\" : \"send\";\n    await scope(principal, action, parsed.toTaskId, parsed.fromTaskId);\n    const intent = correlateMessage(\n      parseMessage({\n        ...parsed,\n        payload,\n        delivery,\n        schemaVersion: SCHEMA_VERSION,\n        id: messageIdFor(parsed.fromTaskId, parsed.operationId),\n        createdAt: now().toISOString(),\n      }),\n      input.type,\n    );\n    const delivered = await deliveredMessage(intent);\n    if (delivery === \"result\") resultAttempt(await task(parsed.fromTaskId), expectAttempt);\n    if (delivered) return correlateMessage(delivered, input.type);\n    if (delivery !== \"result\") activeAttempt(await task(parsed.fromTaskId), expectAttempt);\n    const recipient = await task(parsed.toTaskId);\n    activeAttempt(recipient, recipient.attempt);\n    if (parsed.causationId) {\n      const stored = await driver.get(\"taskMessages\", parsed.causationId);\n      if (!stored)\n        throw new TaskMessageError(\"Causation message must already be durably delivered\");\n      const cause = parseMessage(stored.value);\n      await scope(principal, \"read\", cause.toTaskId, cause.fromTaskId);\n      if ((await task(cause.toTaskId)).rootTaskId !== recipient.rootTaskId)\n        throw new TaskMessageAuthorizationError(\"Causation must stay within the Task root\");\n    }\n    const message = correlateMessage(await reserve(intent, expectAttempt), input.type);\n    for (;;) {\n      await scope(principal, action, message.toTaskId, message.fromTaskId);\n      const current = await inbox(message.toTaskId);\n      const delivered = await deliveredMessage(message);\n      if (delivery === \"result\") resultAttempt(await task(message.fromTaskId), expectAttempt);\n      if (delivered) return correlateMessage(delivered, input.type);\n      if (delivery !== \"result\") activeAttempt(await task(message.fromTaskId), expectAttempt);\n      const recipient = await task(message.toTaskId);\n      activeAttempt(recipient, recipient.attempt);\n      const pending = current.value.pending.find((entry) => entry.id === message.id);\n      if (pending) {\n        if (!isDeepStrictEqual(pending, message))\n          throw new TaskMessageConflictError(\"Inbox message differs from reserved intent\");\n      } else {\n        if (current.value.pending.length >= MAX_TASK_INBOX_PENDING)\n          throw new TaskMessageError(\n            `Recipient inbox is full; maximum ${MAX_TASK_INBOX_PENDING} pending messages`,\n          );\n        if (\n          !(await saveInbox(\n            { ...current.value, pending: [...current.value.pending, message] },\n            current.version,\n          ))\n        )\n          continue;\n      }\n      return correlateMessage(\n        await immutable(\"taskMessages\", message.id, message, parseMessage),\n        input.type,\n      );\n    }\n  }\n\n  async function sendAndNotify<const Type extends TaskMessageProtocolBinding>(\n    principal: TaskMessagePrincipal,\n    input: SendTaskMessageInput<Type>,\n    delivery?: \"result\",\n  ): Promise<TaskMessage<Type>> {\n    const message = await send(principal, input, delivery);\n    if (options.notify) {\n      const recipient = await task(message.toTaskId);\n      await options.notify({ rootTaskId: recipient.rootTaskId, key: `message:${message.id}` });\n    }\n    return message;\n  }\n\n  return {\n    send: ({ principal, message }) => sendAndNotify(principal, message),\n    sendResult: ({ principal, message }) => sendAndNotify(principal, message, \"result\"),\n    async get({ principal: context, toTaskId, messageId }) {\n      return readMessage(taskMessagePrincipalSchema.parse(context), toTaskId, messageId, \"read\");\n    },\n    async pending({ principal: context, toTaskId }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      const current = await repair(principal, toTaskId, \"read\");\n      for (const message of current.value.pending)\n        await scope(principal, \"read\", toTaskId, message.fromTaskId);\n      return current.value.pending;\n    },\n    async claim({ principal: context, task: inputTask, ...input }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      const { taskId: toTaskId, attempt } = taskAttemptRefSchema.parse(inputTask);\n      const { leaseMs, recoverCompleted } = claimOptionsSchema.parse(input);\n      for (;;) {\n        const current = await repair(principal, toTaskId, \"claim\");\n        const message = current.value.pending[0];\n        if (message) await scope(principal, \"claim\", toTaskId, message.fromTaskId);\n        const recipient = await task(toTaskId);\n        claimableAttempt(recipient, attempt, recoverCompleted);\n        if (\n          current.value.lease &&\n          current.value.lease.attempt === recipient.attempt &&\n          Date.parse(current.value.lease.expiresAt) > now().getTime()\n        )\n          return null;\n        if (!message) return null;\n        const source = await task(message.fromTaskId);\n        const attemptFenced = protocols.sourceFence(message.type) === \"attempt\";\n        if (\n          (attemptFenced && source.attempt !== message.expectAttempt) ||\n          (source.state === \"cancelled\" && message.delivery !== \"result\")\n        ) {\n          throw new TaskMessageSourceFenceError(\n            message.id,\n            { taskId: source.id, attempt: message.expectAttempt },\n            source.attempt,\n            source.state,\n          );\n        }\n        claimableAttempt(await task(toTaskId), attempt, recoverCompleted);\n        const time = now();\n        const claim = taskMessageClaimSchema.parse({\n          messageId: message.id,\n          toTaskId,\n          generation: current.value.generation + 1,\n          principalId: principal.id,\n          attempt,\n          expiresAt: new Date(time.getTime() + leaseMs).toISOString(),\n        });\n        if (\n          await saveInbox(\n            { ...current.value, generation: claim.generation, lease: claim },\n            current.version,\n          )\n        )\n          return { claim, message };\n      }\n    },\n    async complete({ principal: context, claim: input, effectsCommitted }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      const claim = taskMessageClaimSchema.parse(input);\n      acknowledgmentSchema.parse({ effectsCommitted });\n      if (principal.id !== claim.principalId)\n        throw new TaskMessageAuthorizationError(\n          \"Only the claiming principal may acknowledge processing\",\n        );\n      const message = await readMessage(principal, claim.toTaskId, claim.messageId, \"complete\");\n      if (!message) throw new TaskMessageLeaseError(\"Claimed message does not exist\");\n      for (;;) {\n        await scope(principal, \"complete\", claim.toTaskId, message.fromTaskId);\n        const current = await inbox(claim.toTaskId);\n        const completed = await processingRecord(claim.messageId);\n        if (completed) return requireClaim(completed, claim);\n        if (current.value.completion) {\n          requireClaim(current.value.completion, claim);\n          await repair(principal, claim.toTaskId, \"complete\", claim.messageId);\n          continue;\n        }\n        const time = await requireLiveClaim(principal, claim, current.value);\n        const completion = taskMessageProcessingSchema.parse({\n          ...claim,\n          schemaVersion: SCHEMA_VERSION,\n          effectsCommitted: true,\n          completedAt: time.toISOString(),\n        });\n        // The inbox CAS accepts the acknowledgment before its immutable record is written.\n        // A replaced generation cannot commit here, even if its earlier read was valid.\n        if (!(await saveInbox({ ...current.value, completion }, current.version))) continue;\n        await repair(principal, claim.toTaskId, \"complete\", claim.messageId);\n        return completion;\n      }\n    },\n    async assertClaim({ principal: context, claim: input }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      const claim = taskMessageClaimSchema.parse(input);\n      if (principal.id !== claim.principalId)\n        throw new TaskMessageAuthorizationError(\n          \"Only the claiming principal may validate this lease\",\n        );\n      await scope(principal, \"claim\", claim.toTaskId);\n      const stored = await driver.get(\"taskMessages\", claim.messageId);\n      if (!stored) throw new TaskMessageLeaseError(\"Claimed message does not exist\");\n      const message = parseMessage(stored.value);\n      if (message.id !== claim.messageId || message.toTaskId !== claim.toTaskId)\n        throw new TaskMessageAuthorizationError(\"Claim does not belong to this recipient\");\n      await scope(principal, \"claim\", claim.toTaskId, message.fromTaskId);\n      await scope(principal, \"complete\", claim.toTaskId, message.fromTaskId);\n      const completed = await processingRecord(claim.messageId);\n      if (completed) {\n        requireClaim(completed, claim);\n        throw new TaskMessageLeaseError(\n          \"Message processing is already complete; the claim is no longer active\",\n        );\n      }\n      await requireLiveClaim(principal, claim, (await inbox(claim.toTaskId)).value);\n    },\n    async discard({ principal: context, toTaskId, messageId, reason: inputReason }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      const reason = taskMessageDiscardSchema.shape.reason.parse(inputReason);\n      const message = await readMessage(principal, toTaskId, messageId, \"discard\");\n      if (!message) throw new TaskMessageError(\"Cannot discard a missing message\");\n      for (;;) {\n        await scope(principal, \"discard\", toTaskId, message.fromTaskId);\n        const current = await repair(principal, toTaskId, \"discard\", messageId);\n        const discarded = await discardRecord(messageId);\n        if (discarded) {\n          if (\n            discarded.toTaskId !== toTaskId ||\n            discarded.reason !== reason ||\n            !isDeepStrictEqual(discarded.by, principal)\n          )\n            throw new TaskMessageConflictError(\"Message already has a different discard decision\");\n          return;\n        }\n        if (await processingRecord(messageId))\n          throw new TaskMessageConflictError(\"Processed messages cannot be discarded\");\n        if (current.value.pending[0]?.id !== messageId)\n          throw new TaskMessageError(\"Only the pending inbox head may be discarded\");\n        const time = now();\n        if (current.value.lease && Date.parse(current.value.lease.expiresAt) > time.getTime())\n          throw new TaskMessageLeaseError(\n            \"Cannot discard while the recipient has an unexpired lease, including a prior Task attempt\",\n          );\n        const rejection = taskMessageDiscardSchema.parse({\n          schemaVersion: SCHEMA_VERSION,\n          messageId,\n          toTaskId,\n          reason,\n          by: principal,\n          discardedAt: time.toISOString(),\n        });\n        if (!(await saveInbox({ ...current.value, lease: undefined, rejection }, current.version)))\n          continue;\n        await repair(principal, toTaskId, \"discard\", messageId);\n        return;\n      }\n    },\n    async discarded({ principal: context, toTaskId, messageId }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      if (!(await readMessage(principal, toTaskId, messageId, \"read\"))) return null;\n      const record = await discardRecord(messageId);\n      if (record && record.toTaskId !== toTaskId)\n        throw new TaskMessageError(\"Discard record recipient mismatch\");\n      return record;\n    },\n    async processing({ principal: context, toTaskId, messageId }) {\n      const principal = taskMessagePrincipalSchema.parse(context);\n      if (!(await readMessage(principal, toTaskId, messageId, \"read\"))) return null;\n      const record = await processingRecord(messageId);\n      if (record && record.toTaskId !== toTaskId)\n        throw new TaskMessageError(\"Processing record recipient mismatch\");\n      return record;\n    },\n    effectKey({ messageId, operation }) {\n      taskMessageIdSchema.parse(messageId);\n      z.string().min(1).max(256).parse(operation);\n      return `effect_${hash([messageId, operation])}`;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/store/task-work.d.mts

@@ -0,0 +1,180 @@
+import { TaskId } from "../schema/id.mjs";
+import { JsonValue, WorkflowBinding } from "../schema/work.mjs";
+import { ExecutionReference, Task, TaskState } from "../schema/task.mjs";
+import { WorkflowRegistry } from "../workflows.mjs";
+import { IsoDateTimeClock } from "../schema/common.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { StoreDriver } from "./driver.mjs";
+import { FactoryStores } from "./engine.mjs";
+//#region src/store/task-work.d.ts
+/** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */
+interface TaskWorkStore {
+  /**
+   * Completes through the dynamic registry boundary, which validates unknown output at runtime.
+   *
+   * @remarks
+   * The exact Task attempt is mandatory. The engine validates output against the Task's stored
+   * workflow, persists it with the `succeeded` transition, and returns only after that write. A
+   * replay with the same validated output returns the existing succeeded Task; different output
+   * is refused. This method does not authenticate a provider callback—use a fence and establish
+   * caller authority before invoking it.
+   *
+   * @param input - Exact Task attempt, unknown candidate output, and optional execution fence.
+   * @returns The durably succeeded Task containing its validated `workResult`.
+   * @throws When the attempt, lifecycle state, execution fence, or runtime output validation fails.
+   */
+  complete(input: CompleteTaskWorkInput): Promise<Task>;
+  /**
+   * Completes work while statically checking output against its exact workflow binding.
+   *
+   * @remarks
+   * In addition to `complete` semantics, the supplied binding must equal the Task's persisted
+   * workflow ID and version. Retain historical workflow definitions in the registry while stored
+   * Tasks may still use them. For Eve tools, authenticate first with `requireTaskExecution` and
+   * pass its attempt and execution as the completion fence.
+   *
+   * @param input - Exact Task attempt, typed workflow binding and output, and optional fence.
+   * @returns The durably succeeded Task containing its validated `workResult`.
+   * @throws When the workflow, attempt, lifecycle state, execution fence, or output is invalid.
+   */
+  completeWorkflow<Output extends JsonValue>(input: CompleteWorkflowTaskWorkInput<Output>): Promise<Task>;
+  /**
+   * Marks a running exact Task attempt as intentionally inactive while awaiting messages.
+   *
+   * @remarks
+   * This keeps the Task in `running`; it does not stall, cancel, or create a new attempt. The
+   * waiting marker and optional workflow phase are durable when the promise resolves. Repeating
+   * the same target state is a no-op. A stale attempt or non-running Task is refused, so callers
+   * should reread the Task before deciding whether a later attempt still needs the message.
+   *
+   * @param input - Exact running attempt and optional workflow phase.
+   * @returns The updated running Task with `waitingForMessages` set.
+   * @throws When the Task is absent, no longer running, or on a different attempt.
+   */
+  waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;
+  /**
+   * Resumes an exact message-waiting Task attempt and records fresh progress.
+   *
+   * @remarks
+   * The Task remains `running`, its waiting marker is cleared, and `lastProgressAt` advances. The
+   * write is durable when the promise resolves and repeating it for an already-resumed attempt is
+   * a no-op. Resuming does not claim or acknowledge messages; the workflow owns that ordering.
+   *
+   * @param input - Exact running attempt to resume.
+   * @returns The updated running Task with message waiting cleared.
+   * @throws When the Task is absent, no longer running, or on a different attempt.
+   */
+  resume(input: ResumeTaskWorkInput): Promise<Task>;
+  /**
+   * Repairs admitted creation snapshots by direct graph IDs, never by scanning the bucket.
+   *
+   * @remarks
+   * The canonical graph contains immutable admission snapshots. Recovery validates every
+   * admission against the exact registered workflow, restores only missing Task records, and
+   * returns existing records with their current mutable progress. It is safe to repeat after an
+   * interrupted Task creation.
+   *
+   * This operation repairs Factory persistence only. It does not start or reattach a provider
+   * execution, rerun workflow code, retry a Task, or migrate old Task JSON. After recovery, the
+   * caller must inspect each Task's lifecycle and recorded execution and apply workflow-owned
+   * reconciliation policy.
+   *
+   * @param rootTaskId - Root of the canonical Task graph to repair and read.
+   * @returns Every validated Task admitted to that graph.
+   * @throws When the graph is absent, a stored workflow version is not registered, persisted data
+   * is invalid, or a current Task no longer matches its immutable admission identity.
+   */
+  recover(rootTaskId: TaskId): Promise<readonly Task[]>;
+  /**
+   * Aggregates Task-local measured usage once without charging parent roll-ups again.
+   *
+   * @remarks
+   * This first performs the same persistence repair and validation as {@link recover}. For each
+   * Task, recorded step usage is authoritative; otherwise a settled amount is used, then zero.
+   * The result is a current snapshot, not a reservation or billing transaction, and calling it
+   * does not write settlement receipts.
+   *
+   * @param rootTaskId - Root of the canonical Task graph to aggregate.
+   * @returns Cost, token, and Task counts for the recovered graph.
+   * @throws The same persistence and validation errors as {@link recover}.
+   */
+  usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;
+}
+/** Exact Task attempt and candidate workflow output used to complete work. */
+interface CompleteTaskWorkInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
+  task: TaskAttemptRef;
+  /** Candidate value validated against the Task's exact registered output schema. */
+  output: unknown;
+  /**
+   * Optional source-state and execution fence for provider callbacks. Omit only when trusted
+   * workflow code already owns lifecycle authority.
+   */
+  fence?: TaskWorkCompletionFence;
+}
+/** Exact Task attempt, workflow contract, and statically checked output used to complete work. */
+interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {
+  /** Task ID and current positive attempt; stale attempts are refused. */
+  task: TaskAttemptRef;
+  /** Exact binding required to match the Task's persisted workflow. */
+  workflow: WorkflowBinding<JsonValue, Output>;
+  /** Candidate output statically carried by the binding and validated again at runtime. */
+  output: NoInfer<Output>;
+  /**
+   * Optional source-state and execution fence for provider callbacks. Omit only when trusted
+   * workflow code already owns lifecycle authority.
+   */
+  fence?: TaskWorkCompletionFence;
+}
+/** Atomic source-state and provider-execution conditions for a workflow completion write. */
+interface TaskWorkCompletionFence {
+  /** Lifecycle state required atomically with completion, normally `running`. */
+  readonly from: TaskState;
+  /** Provider execution reference required to remain current at the completion write. */
+  readonly execution: ExecutionReference;
+}
+/** Aggregated measured usage across one canonical Task graph. */
+interface TaskWorkUsage {
+  /** Sum of measured Task usage, falling back to settlement only when no usage is recorded. */
+  costUsd: number;
+  /** Sum of recorded provider input tokens across Tasks. */
+  inputTokens: number;
+  /** Sum of recorded provider output tokens across Tasks. */
+  outputTokens: number;
+  /** Number of Tasks admitted to the recovered canonical graph. */
+  taskCount: number;
+}
+/** Exact running Task attempt and optional workflow phase used to await messages. */
+interface WaitForTaskMessagesInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
+  task: TaskAttemptRef;
+  /** Optional durable workflow-owned phase label retained across waiting and resumption. */
+  phase?: string;
+}
+/** Exact running Task attempt to resume after message delivery. */
+interface ResumeTaskWorkInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
+  task: TaskAttemptRef;
+}
+/** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */
+type TaskWorkStores = Pick<FactoryStores, "graphs" | "receipts" | "tasks">;
+/** Engine-owned dependencies used to construct workflow-facing Task operations. */
+interface CreateTaskWorkStoreOptions {
+  /** Policy-free persistence driver used for direct canonical Task reads. */
+  driver: StoreDriver;
+  /** ISO timestamp source shared with the surrounding store engine. */
+  now: IsoDateTimeClock;
+  /** Lazily resolves graph, receipt, and Task operations after engine construction. */
+  stores: () => TaskWorkStores;
+  /** Exact workflow versions used to validate stored input and completion output. */
+  workflows: WorkflowRegistry;
+  /** Persists a validated Task with compare-and-swap semantics. */
+  update(task: Task, version: number): Promise<void>;
+  /** Recreates a missing canonical Task snapshot from its immutable graph admission. */
+  restore(task: Task): Promise<Task>;
+}
+/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */
+declare function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore;
+//#endregion
+export { CompleteTaskWorkInput, CompleteWorkflowTaskWorkInput, CreateTaskWorkStoreOptions, ResumeTaskWorkInput, TaskWorkCompletionFence, TaskWorkStore, TaskWorkStores, TaskWorkUsage, WaitForTaskMessagesInput, createTaskWorkStore };
+//# sourceMappingURL=task-work.d.mts.map

package/dist/store/task-work.mjs

@@ -0,0 +1,137 @@
+import { taskSchema } from "../schema/task.mjs";
+import { InvalidTransitionError } from "../schema/transitions.mjs";
+import { RecordNotFoundError, VersionConflictError } from "./driver.mjs";
+import { assertTaskAdmission } from "./task-graphs.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/task-work.ts
+/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */
+function createTaskWorkStore(options) {
+	const { driver, now, stores, workflows, update, restore } = options;
+	function parseTask(value) {
+		const task = taskSchema.parse(value);
+		workflows.validateStoredInput(task.work.workflow, task.work.input);
+		if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);
+		return task;
+	}
+	async function read(id) {
+		const record = await driver.get("tasks", id);
+		if (!record) throw new RecordNotFoundError("tasks", id);
+		const task = parseTask(record.value);
+		if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);
+		return {
+			task,
+			version: record.version,
+			work: task.work
+		};
+	}
+	async function recover(rootTaskId) {
+		const graph = await stores().graphs.get(rootTaskId);
+		if (!graph) throw new RecordNotFoundError("taskGraphs", rootTaskId);
+		const tasks = [];
+		for (const node of graph.nodes) {
+			const admission = parseTask(node.admission);
+			const task = parseTask(await stores().tasks.get(node.taskId) ?? await restore(admission));
+			assertTaskAdmission({
+				task,
+				admission
+			});
+			tasks.push(task);
+		}
+		return tasks;
+	}
+	function assertAttempt(task, expectAttempt) {
+		z.number().int().positive().parse(expectAttempt);
+		if (task.attempt !== expectAttempt) throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);
+	}
+	async function setWaiting(id, expectAttempt, waiting, phase) {
+		for (;;) {
+			const { task, version } = await read(id);
+			assertAttempt(task, expectAttempt);
+			if (task.state !== "running") throw new Error(`Task ${id} must be running to ${waiting ? "wait" : "resume"}`);
+			const next = taskSchema.parse({
+				...task,
+				waitingForMessages: waiting,
+				workflowPhase: phase ?? task.workflowPhase,
+				lastProgressAt: waiting ? task.lastProgressAt : now(),
+				updatedAt: now()
+			});
+			if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase) return task;
+			await stores().receipts.append({
+				taskId: id,
+				repositoryIds: task.repositoryIds,
+				kind: task.kind,
+				state: waiting ? "waiting" : "resumed",
+				phase: "workflow",
+				attempt: task.attempt,
+				reason: waiting ? "Workflow is waiting for Task messages" : "Workflow resumed message processing",
+				dedupeKey: `work:${id}:${version}:${waiting ? "wait" : "resume"}`
+			});
+			try {
+				await update(next, version);
+				return next;
+			} catch (error) {
+				if (!(error instanceof VersionConflictError)) throw error;
+			}
+		}
+	}
+	async function complete(input, expectedWorkflow) {
+		const { task: { taskId: id, attempt: expectAttempt }, output: value, fence } = input;
+		for (;;) {
+			const { task, work } = await read(id);
+			assertAttempt(task, expectAttempt);
+			if (fence !== void 0 && !isDeepStrictEqual(task.execution, fence.execution)) throw new Error(`Task ${id} execution has been replaced`);
+			if (expectedWorkflow !== void 0 && !isDeepStrictEqual(work.workflow, expectedWorkflow)) throw new Error(`Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`);
+			if (task.state === "succeeded") {
+				const output = workflows.validateOutput(work.workflow, value);
+				if (!isDeepStrictEqual(task.workResult?.output, output)) throw new Error(`Task ${id} already recorded a different workflow output`);
+				return task;
+			}
+			try {
+				return await stores().tasks.transition(id, "succeeded", {
+					output: value,
+					expectAttempt,
+					expectFrom: fence?.from ?? task.state,
+					...fence === void 0 ? {} : { expectExecution: fence.execution },
+					phase: "workflow"
+				});
+			} catch (error) {
+				if (error instanceof VersionConflictError) continue;
+				if (error instanceof InvalidTransitionError && (await read(id)).task.state === "succeeded") continue;
+				throw error;
+			}
+		}
+	}
+	return {
+		complete,
+		completeWorkflow: ({ task, workflow, output, fence }) => complete({
+			task,
+			output,
+			fence
+		}, workflow),
+		waitForMessages: ({ task: { taskId, attempt }, phase }) => setWaiting(taskId, attempt, true, phase),
+		resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),
+		recover,
+		async usage(rootTaskId) {
+			const tasks = await recover(rootTaskId);
+			let micros = 0;
+			let inputTokens = 0;
+			let outputTokens = 0;
+			for (const task of tasks) {
+				micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1e6);
+				inputTokens += task.usage?.inputTokens ?? 0;
+				outputTokens += task.usage?.outputTokens ?? 0;
+			}
+			return {
+				costUsd: micros / 1e6,
+				inputTokens,
+				outputTokens,
+				taskCount: tasks.length
+			};
+		}
+	};
+}
+//#endregion
+export { createTaskWorkStore };
+
+//# sourceMappingURL=task-work.mjs.map

package/dist/store/task-work.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-work.mjs","names":[],"sources":["../../src/store/task-work.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport type { IsoDateTimeClock } from \"../schema/common\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport type { TaskId } from \"../schema/id\";\nimport { taskSchema, type ExecutionReference, type Task, type TaskState } from \"../schema/task\";\nimport { InvalidTransitionError } from \"../schema/transitions\";\nimport type { JsonValue, WorkflowBinding } from \"../schema/work\";\nimport type { WorkflowRegistry } from \"../workflows\";\nimport { RecordNotFoundError, VersionConflictError, type StoreDriver } from \"./driver\";\nimport type { FactoryStores } from \"./engine\";\nimport { assertTaskAdmission } from \"./task-graphs\";\n\n/** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */\nexport interface TaskWorkStore {\n  /**\n   * Completes through the dynamic registry boundary, which validates unknown output at runtime.\n   *\n   * @remarks\n   * The exact Task attempt is mandatory. The engine validates output against the Task's stored\n   * workflow, persists it with the `succeeded` transition, and returns only after that write. A\n   * replay with the same validated output returns the existing succeeded Task; different output\n   * is refused. This method does not authenticate a provider callback—use a fence and establish\n   * caller authority before invoking it.\n   *\n   * @param input - Exact Task attempt, unknown candidate output, and optional execution fence.\n   * @returns The durably succeeded Task containing its validated `workResult`.\n   * @throws When the attempt, lifecycle state, execution fence, or runtime output validation fails.\n   */\n  complete(input: CompleteTaskWorkInput): Promise<Task>;\n  /**\n   * Completes work while statically checking output against its exact workflow binding.\n   *\n   * @remarks\n   * In addition to `complete` semantics, the supplied binding must equal the Task's persisted\n   * workflow ID and version. Retain historical workflow definitions in the registry while stored\n   * Tasks may still use them. For Eve tools, authenticate first with `requireTaskExecution` and\n   * pass its attempt and execution as the completion fence.\n   *\n   * @param input - Exact Task attempt, typed workflow binding and output, and optional fence.\n   * @returns The durably succeeded Task containing its validated `workResult`.\n   * @throws When the workflow, attempt, lifecycle state, execution fence, or output is invalid.\n   */\n  completeWorkflow<Output extends JsonValue>(\n    input: CompleteWorkflowTaskWorkInput<Output>,\n  ): Promise<Task>;\n  /**\n   * Marks a running exact Task attempt as intentionally inactive while awaiting messages.\n   *\n   * @remarks\n   * This keeps the Task in `running`; it does not stall, cancel, or create a new attempt. The\n   * waiting marker and optional workflow phase are durable when the promise resolves. Repeating\n   * the same target state is a no-op. A stale attempt or non-running Task is refused, so callers\n   * should reread the Task before deciding whether a later attempt still needs the message.\n   *\n   * @param input - Exact running attempt and optional workflow phase.\n   * @returns The updated running Task with `waitingForMessages` set.\n   * @throws When the Task is absent, no longer running, or on a different attempt.\n   */\n  waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;\n  /**\n   * Resumes an exact message-waiting Task attempt and records fresh progress.\n   *\n   * @remarks\n   * The Task remains `running`, its waiting marker is cleared, and `lastProgressAt` advances. The\n   * write is durable when the promise resolves and repeating it for an already-resumed attempt is\n   * a no-op. Resuming does not claim or acknowledge messages; the workflow owns that ordering.\n   *\n   * @param input - Exact running attempt to resume.\n   * @returns The updated running Task with message waiting cleared.\n   * @throws When the Task is absent, no longer running, or on a different attempt.\n   */\n  resume(input: ResumeTaskWorkInput): Promise<Task>;\n  /**\n   * Repairs admitted creation snapshots by direct graph IDs, never by scanning the bucket.\n   *\n   * @remarks\n   * The canonical graph contains immutable admission snapshots. Recovery validates every\n   * admission against the exact registered workflow, restores only missing Task records, and\n   * returns existing records with their current mutable progress. It is safe to repeat after an\n   * interrupted Task creation.\n   *\n   * This operation repairs Factory persistence only. It does not start or reattach a provider\n   * execution, rerun workflow code, retry a Task, or migrate old Task JSON. After recovery, the\n   * caller must inspect each Task's lifecycle and recorded execution and apply workflow-owned\n   * reconciliation policy.\n   *\n   * @param rootTaskId - Root of the canonical Task graph to repair and read.\n   * @returns Every validated Task admitted to that graph.\n   * @throws When the graph is absent, a stored workflow version is not registered, persisted data\n   * is invalid, or a current Task no longer matches its immutable admission identity.\n   */\n  recover(rootTaskId: TaskId): Promise<readonly Task[]>;\n  /**\n   * Aggregates Task-local measured usage once without charging parent roll-ups again.\n   *\n   * @remarks\n   * This first performs the same persistence repair and validation as {@link recover}. For each\n   * Task, recorded step usage is authoritative; otherwise a settled amount is used, then zero.\n   * The result is a current snapshot, not a reservation or billing transaction, and calling it\n   * does not write settlement receipts.\n   *\n   * @param rootTaskId - Root of the canonical Task graph to aggregate.\n   * @returns Cost, token, and Task counts for the recovered graph.\n   * @throws The same persistence and validation errors as {@link recover}.\n   */\n  usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;\n}\n\n/** Exact Task attempt and candidate workflow output used to complete work. */\nexport interface CompleteTaskWorkInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Candidate value validated against the Task's exact registered output schema. */\n  output: unknown;\n  /**\n   * Optional source-state and execution fence for provider callbacks. Omit only when trusted\n   * workflow code already owns lifecycle authority.\n   */\n  fence?: TaskWorkCompletionFence;\n}\n\n/** Exact Task attempt, workflow contract, and statically checked output used to complete work. */\nexport interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Exact binding required to match the Task's persisted workflow. */\n  workflow: WorkflowBinding<JsonValue, Output>;\n  /** Candidate output statically carried by the binding and validated again at runtime. */\n  output: NoInfer<Output>;\n  /**\n   * Optional source-state and execution fence for provider callbacks. Omit only when trusted\n   * workflow code already owns lifecycle authority.\n   */\n  fence?: TaskWorkCompletionFence;\n}\n\n/** Atomic source-state and provider-execution conditions for a workflow completion write. */\nexport interface TaskWorkCompletionFence {\n  /** Lifecycle state required atomically with completion, normally `running`. */\n  readonly from: TaskState;\n  /** Provider execution reference required to remain current at the completion write. */\n  readonly execution: ExecutionReference;\n}\n\n/** Aggregated measured usage across one canonical Task graph. */\nexport interface TaskWorkUsage {\n  /** Sum of measured Task usage, falling back to settlement only when no usage is recorded. */\n  costUsd: number;\n  /** Sum of recorded provider input tokens across Tasks. */\n  inputTokens: number;\n  /** Sum of recorded provider output tokens across Tasks. */\n  outputTokens: number;\n  /** Number of Tasks admitted to the recovered canonical graph. */\n  taskCount: number;\n}\n\n/** Exact running Task attempt and optional workflow phase used to await messages. */\nexport interface WaitForTaskMessagesInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Optional durable workflow-owned phase label retained across waiting and resumption. */\n  phase?: string;\n}\n\n/** Exact running Task attempt to resume after message delivery. */\nexport interface ResumeTaskWorkInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n}\n\n/** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */\nexport type TaskWorkStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** Engine-owned dependencies used to construct workflow-facing Task operations. */\nexport interface CreateTaskWorkStoreOptions {\n  /** Policy-free persistence driver used for direct canonical Task reads. */\n  driver: StoreDriver;\n  /** ISO timestamp source shared with the surrounding store engine. */\n  now: IsoDateTimeClock;\n  /** Lazily resolves graph, receipt, and Task operations after engine construction. */\n  stores: () => TaskWorkStores;\n  /** Exact workflow versions used to validate stored input and completion output. */\n  workflows: WorkflowRegistry;\n  /** Persists a validated Task with compare-and-swap semantics. */\n  update(task: Task, version: number): Promise<void>;\n  /** Recreates a missing canonical Task snapshot from its immutable graph admission. */\n  restore(task: Task): Promise<Task>;\n}\n\n/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */\nexport function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore {\n  const { driver, now, stores, workflows, update, restore } = options;\n  function parseTask(value: unknown): Task {\n    const task = taskSchema.parse(value);\n    workflows.validateStoredInput(task.work.workflow, task.work.input);\n    if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);\n    return task;\n  }\n  async function read(id: TaskId) {\n    const record = await driver.get(\"tasks\", id);\n    if (!record) throw new RecordNotFoundError(\"tasks\", id);\n    const task = parseTask(record.value);\n    if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);\n    return { task, version: record.version, work: task.work };\n  }\n  async function recover(rootTaskId: TaskId): Promise<readonly Task[]> {\n    const graph = await stores().graphs.get(rootTaskId);\n    if (!graph) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n    const tasks: Task[] = [];\n    for (const node of graph.nodes) {\n      const admission = parseTask(node.admission);\n      const existing = await stores().tasks.get(node.taskId);\n      const task = parseTask(existing ?? (await restore(admission)));\n      assertTaskAdmission({ task, admission });\n      tasks.push(task);\n    }\n    return tasks;\n  }\n  function assertAttempt(task: Task, expectAttempt: number) {\n    z.number().int().positive().parse(expectAttempt);\n    if (task.attempt !== expectAttempt)\n      throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);\n  }\n  async function setWaiting(\n    id: TaskId,\n    expectAttempt: number,\n    waiting: boolean,\n    phase?: string,\n  ): Promise<Task> {\n    for (;;) {\n      const { task, version } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (task.state !== \"running\")\n        throw new Error(`Task ${id} must be running to ${waiting ? \"wait\" : \"resume\"}`);\n      const next = taskSchema.parse({\n        ...task,\n        waitingForMessages: waiting,\n        workflowPhase: phase ?? task.workflowPhase,\n        lastProgressAt: waiting ? task.lastProgressAt : now(),\n        updatedAt: now(),\n      });\n      if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase)\n        return task;\n      await stores().receipts.append({\n        taskId: id,\n        repositoryIds: task.repositoryIds,\n        kind: task.kind,\n        state: waiting ? \"waiting\" : \"resumed\",\n        phase: \"workflow\",\n        attempt: task.attempt,\n        reason: waiting\n          ? \"Workflow is waiting for Task messages\"\n          : \"Workflow resumed message processing\",\n        dedupeKey: `work:${id}:${version}:${waiting ? \"wait\" : \"resume\"}`,\n      });\n      try {\n        await update(next, version);\n        return next;\n      } catch (error) {\n        if (!(error instanceof VersionConflictError)) throw error;\n      }\n    }\n  }\n  async function complete(\n    input: CompleteTaskWorkInput,\n    expectedWorkflow?: WorkflowBinding,\n  ): Promise<Task> {\n    const {\n      task: { taskId: id, attempt: expectAttempt },\n      output: value,\n      fence,\n    } = input;\n    for (;;) {\n      const { task, work } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (fence !== undefined && !isDeepStrictEqual(task.execution, fence.execution)) {\n        throw new Error(`Task ${id} execution has been replaced`);\n      }\n      if (expectedWorkflow !== undefined && !isDeepStrictEqual(work.workflow, expectedWorkflow)) {\n        throw new Error(\n          `Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`,\n        );\n      }\n      if (task.state === \"succeeded\") {\n        const output = workflows.validateOutput(work.workflow, value);\n        if (!isDeepStrictEqual(task.workResult?.output, output)) {\n          throw new Error(`Task ${id} already recorded a different workflow output`);\n        }\n        return task;\n      }\n      try {\n        return await stores().tasks.transition(id, \"succeeded\", {\n          output: value,\n          expectAttempt,\n          expectFrom: fence?.from ?? task.state,\n          ...(fence === undefined ? {} : { expectExecution: fence.execution }),\n          phase: \"workflow\",\n        });\n      } catch (error) {\n        if (error instanceof VersionConflictError) continue;\n        if (error instanceof InvalidTransitionError && (await read(id)).task.state === \"succeeded\")\n          continue;\n        throw error;\n      }\n    }\n  }\n  return {\n    complete,\n    completeWorkflow: ({ task, workflow, output, fence }) =>\n      complete({ task, output, fence }, workflow),\n    waitForMessages: ({ task: { taskId, attempt }, phase }) =>\n      setWaiting(taskId, attempt, true, phase),\n    resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),\n    recover,\n    async usage(rootTaskId) {\n      const tasks = await recover(rootTaskId);\n      let micros = 0;\n      let inputTokens = 0;\n      let outputTokens = 0;\n      for (const task of tasks) {\n        micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1_000_000);\n        inputTokens += task.usage?.inputTokens ?? 0;\n        outputTokens += task.usage?.outputTokens ?? 0;\n      }\n      return { costUsd: micros / 1_000_000, inputTokens, outputTokens, taskCount: tasks.length };\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/store/work-notifications.d.mts

@@ -0,0 +1,19 @@
+import "../schema/task.mjs";
+import { z } from "zod";
+//#region src/store/work-notifications.d.ts
+/** Validates a stable wakeup that addresses canonical work by root graph. */
+declare const workNotificationSchema: z.ZodObject<{
+  rootTaskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+  key: z.ZodString;
+}, z.core.$strict>;
+/** Retry-safe notification telling a consumer to reread one canonical Task graph. */
+type WorkNotification = z.infer<typeof workNotificationSchema>;
+/** Application transport for post-commit work wakeups and delivery-failure reporting. */
+interface WorkNotifications {
+  publish(event: WorkNotification): Promise<void>;
+  /** The source write already committed. Report transport failure without pretending it rolled back. */
+  onError(error: unknown, event: WorkNotification): void;
+}
+//#endregion
+export { WorkNotification, WorkNotifications, workNotificationSchema };
+//# sourceMappingURL=work-notifications.d.mts.map

package/dist/store/work-notifications.mjs

@@ -0,0 +1,48 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/work-notifications.ts
+/** Validates a stable wakeup that addresses canonical work by root graph. */
+const workNotificationSchema = z.strictObject({
+	rootTaskId: taskIdSchema.describe("Canonical graph to reconcile; never an execution authorization."),
+	key: z.string().min(1).max(256).describe("Stable identity of the committed source change.")
+}).describe("Durable work wakeup. Consumers reread canonical state and tolerate duplicate delivery.");
+/** Creates a best-effort post-commit notifier whose failures never roll back source writes. */
+function createWorkNotifier(options) {
+	async function publish(event) {
+		if (!options) return;
+		try {
+			await options.publish(event);
+		} catch (error) {
+			try {
+				options.onError(error, event);
+			} catch {}
+		}
+	}
+	function schedulingState(task) {
+		return [
+			task.state,
+			task.attempt,
+			task.approval,
+			task.waitingForMessages,
+			task.workflowPhase,
+			task.changeId,
+			task.questionTaskId,
+			task.answerEventIds
+		];
+	}
+	return {
+		publish,
+		async task(task, previous, version) {
+			if (previous && isDeepStrictEqual(schedulingState(task), schedulingState(previous))) return;
+			await publish({
+				rootTaskId: task.rootTaskId,
+				key: `task:${task.id}:${version}`
+			});
+		}
+	};
+}
+//#endregion
+export { createWorkNotifier, workNotificationSchema };
+
+//# sourceMappingURL=work-notifications.mjs.map

package/dist/store/work-notifications.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-notifications.mjs","names":[],"sources":["../../src/store/work-notifications.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport { taskIdSchema } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\n\n/** Validates a stable wakeup that addresses canonical work by root graph. */\nexport const workNotificationSchema = z\n  .strictObject({\n    rootTaskId: taskIdSchema.describe(\n      \"Canonical graph to reconcile; never an execution authorization.\",\n    ),\n    key: z.string().min(1).max(256).describe(\"Stable identity of the committed source change.\"),\n  })\n  .describe(\n    \"Durable work wakeup. Consumers reread canonical state and tolerate duplicate delivery.\",\n  );\n/** Retry-safe notification telling a consumer to reread one canonical Task graph. */\nexport type WorkNotification = z.infer<typeof workNotificationSchema>;\n/** Application transport for post-commit work wakeups and delivery-failure reporting. */\nexport interface WorkNotifications {\n  publish(event: WorkNotification): Promise<void>;\n  /** The source write already committed. Report transport failure without pretending it rolled back. */\n  onError(error: unknown, event: WorkNotification): void;\n}\n\n/** Creates a best-effort post-commit notifier whose failures never roll back source writes. */\nexport function createWorkNotifier(options?: WorkNotifications) {\n  async function publish(event: WorkNotification): Promise<void> {\n    if (!options) return;\n    try {\n      await options.publish(event);\n    } catch (error) {\n      // Reporting must not turn a committed CAS write into an apparent write failure.\n      try {\n        options.onError(error, event);\n      } catch {\n        /* Recovery rediscovers canonical work. */\n      }\n    }\n  }\n  function schedulingState(task: Task) {\n    return [\n      task.state,\n      task.attempt,\n      task.approval,\n      task.waitingForMessages,\n      task.workflowPhase,\n      task.changeId,\n      task.questionTaskId,\n      task.answerEventIds,\n    ];\n  }\n  return {\n    publish,\n    async task(task: Task, previous: Task | null, version: number) {\n      if (previous && isDeepStrictEqual(schedulingState(task), schedulingState(previous))) return;\n      await publish({ rootTaskId: task.rootTaskId, key: `task:${task.id}:${version}` });\n    },\n  };\n}\n"],"mappings":";;;;;AAMA,MAAa,yBAAyB,EACnC,aAAa;CACZ,YAAY,aAAa,SACvB,iEACF;CACA,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,iDAAiD;AAC5F,CAAC,CAAC,CACD,SACC,wFACF;;AAWF,SAAgB,mBAAmB,SAA6B;CAC9D,eAAe,QAAQ,OAAwC;EAC7D,IAAI,CAAC,SAAS;EACd,IAAI;GACF,MAAM,QAAQ,QAAQ,KAAK;EAC7B,SAAS,OAAO;GAEd,IAAI;IACF,QAAQ,QAAQ,OAAO,KAAK;GAC9B,QAAQ,CAER;EACF;CACF;CACA,SAAS,gBAAgB,MAAY;EACnC,OAAO;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;EACP;CACF;CACA,OAAO;EACL;EACA,MAAM,KAAK,MAAY,UAAuB,SAAiB;GAC7D,IAAI,YAAY,kBAAkB,gBAAgB,IAAI,GAAG,gBAAgB,QAAQ,CAAC,GAAG;GACrF,MAAM,QAAQ;IAAE,YAAY,KAAK;IAAY,KAAK,QAAQ,KAAK,GAAG,GAAG;GAAU,CAAC;EAClF;CACF;AACF"}

package/dist/sweep.d.mts

@@ -0,0 +1,79 @@
+import { TaskId } from "./schema/id.mjs";
+import { Repository } from "./schema/repository.mjs";
+import { ExecutionReference, Task } from "./schema/task.mjs";
+import { AgentRouteKey } from "./agent-routes.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+import { DispatchBudget, DispatchRefusalCode } from "./dispatch.mjs";
+//#region src/sweep.d.ts
+/** Graph, receipt, repository, and Task capabilities required by queued-work dispatch. */
+type SweepQueuedStores = Pick<FactoryStores, "graphs" | "receipts" | "repositories" | "tasks">;
+/**
+ * Single-repository adapter for an exact agent route. Supplied by the app, which knows its
+ * agents' addresses. Returns the provider's execution reference when it has one.
+ *
+ * @param task - Running Task already admitted by the dispatch gate.
+ * @param repository - Exact enabled repository selected from the Task scope.
+ * @returns Provider execution reference that dispatch can persist for recovery.
+ */
+type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference>;
+/** Exact-route launchers, budget gate, and pass bounds for queued Task dispatch. */
+interface SweepQueuedOptions {
+  /** Single-repository agent adapters keyed by routeKey(binding), e.g. code-change@1. */
+  launchers: Readonly<Partial<Record<AgentRouteKey, TaskLauncher>>>;
+  /** Reserve-before-execution limits, passed through to every dispatch. */
+  budget?: DispatchBudget;
+  /** Maximum task launches attempted in one pass; omitted means no limit. */
+  maxDispatches?: number;
+  /** A dispatcher-wide snapshot avoids another complete task read. */
+  tasks?: readonly Task[];
+}
+/** Tasks dispatched, deferred by a gate, or failed by one queued-work pass. */
+interface SweepQueuedResult {
+  /** Task IDs whose provider execution reference was durably recorded. */
+  readonly dispatched: readonly TaskId[];
+  /** Tasks left in the queue because a declared gate may become eligible later. */
+  readonly skipped: readonly {
+    readonly taskId: TaskId;
+    readonly reasonCode: SweepSkipReasonCode;
+    readonly reason: string;
+  }[];
+  /** Tasks whose routing is invalid or whose launch threw. */
+  readonly failed: readonly {
+    readonly taskId: TaskId;
+    readonly reasonCode: SweepFailureReasonCode;
+    readonly reason: string;
+  }[];
+}
+/** Stable reason a queued Task remained eligible for a later dispatch pass. */
+type SweepSkipReasonCode = DispatchRefusalCode | "workflow_owned" | "awaiting_approval" | "dispatch_limit" | "task_changed";
+/** Stable reason a queued Task could not be routed or launched. */
+type SweepFailureReasonCode = "invalid_repository_scope" | "repository_not_found" | "launcher_not_registered" | "launch_failed";
+/**
+ * Runs one bounded pass over queued Tasks and dispatches each eligible exact route.
+ *
+ * @remarks
+ * Candidates are ordered by newest attempt first and then creation time. Route-less work remains
+ * queued for its workflow owner; unmet dependencies, approvals, and pass limits appear in
+ * `skipped`. Invalid repository scope, missing repositories or launchers, and launch failures
+ * appear in `failed`, with unrouteable Tasks transitioned to `failed` when this sweep wins the
+ * race. A result entry describes this pass rather than guaranteeing the Task's lifecycle state:
+ * an ambiguously accepted launch is reported as `launch_failed` while its Task intentionally stays
+ * running for recovery. Callers should surface every failure, reread those Tasks before deciding
+ * remediation, and schedule another pass for skipped work.
+ *
+ * Overlapping passes are safe: {@link dispatchTask} atomically admits one winner before invoking a
+ * launcher. A supplied `tasks` snapshot bounds reads and candidate selection for this pass; it can
+ * become stale, and corresponding races are returned as `task_changed` rather than hidden.
+ * `maxDispatches` counts provider launches started during the pass, including launches that later
+ * fail, so `dispatched.length` may be smaller than the limit.
+ *
+ * @param stores - Graph, receipt, repository, and Task stores used during the pass.
+ * @param options - Exact-route launchers plus optional budget, Task snapshot, and dispatch limit.
+ * @returns IDs dispatched and structured skipped/failed outcomes for every considered candidate.
+ * @throws When `maxDispatches` is not a positive integer or an unexpected persistence error occurs.
+ * @see The shipped `docs/recipes/retry-recovery.md` recipe for scheduled recovery.
+ */
+declare function sweepQueued(stores: SweepQueuedStores, options: SweepQueuedOptions): Promise<SweepQueuedResult>;
+//#endregion
+export { SweepFailureReasonCode, SweepQueuedOptions, SweepQueuedResult, SweepQueuedStores, SweepSkipReasonCode, TaskLauncher, sweepQueued };
+//# sourceMappingURL=sweep.d.mts.map