@adcp/sdk 14.0.0-beta.17 → 14.0.0-beta.19

package/dist/lib/schemas-data/v2.5/_provenance.json

@@ -4,5 +4,5 @@
   "source_sha": "4e553ad955f83b49c7d221ab5c3ff78237ad02e3",
   "source_tarball_sha256": "580656d6466ef9f0d1119985e6726c2efea718dc671e2ad30957fcb2fd54af0f",
   "upstream_adcp_version": "2.5.3",
-  "synced_at": "2026-08-29T18:18:11.038Z"
+  "synced_at": "2026-08-30T04:26:50.358Z"
 }

package/dist/lib/server/decisioning/context.d.mts

@@ -43,6 +43,10 @@ export interface RequestContext<TAccount = Account> {
      * `ctx_metadata`, account objects, task results, logs, or durable HITL
      * state. Background workers must re-resolve credentials; if durable work
      * only needs identity, snapshot a stable non-secret principal identifier.
+     * A native `AbortSignal` stored as a data property at
+     * `authInfo.extra.signal` retains its identity so later host cancellation
+     * remains observable. Other auth values retain the framework's existing
+     * clone-and-freeze behavior.
      */
     authInfo?: Readonly<ResolvedAuthInfo>;
     /** Framework-derived caller namespace for authenticated mutations. */

package/dist/lib/server/decisioning/context.d.ts

@@ -43,6 +43,10 @@ export interface RequestContext<TAccount = Account> {
      * `ctx_metadata`, account objects, task results, logs, or durable HITL
      * state. Background workers must re-resolve credentials; if durable work
      * only needs identity, snapshot a stable non-secret principal identifier.
+     * A native `AbortSignal` stored as a data property at
+     * `authInfo.extra.signal` retains its identity so later host cancellation
+     * remains observable. Other auth values retain the framework's existing
+     * clone-and-freeze behavior.
      */
     authInfo?: Readonly<ResolvedAuthInfo>;
     /** Framework-derived caller namespace for authenticated mutations. */

package/dist/lib/server/decisioning/index.d.mts

@@ -49,6 +49,7 @@ export { PlatformConfigError, validatePlatform } from './runtime/validate-platfo
 export { completeScopedTask, createInMemoryTaskRegistry, failScopedTask, updateScopedTaskProgress, type ScopedTaskRef, type TaskMutationOutcome, type TaskRegistry, type TaskRegistryMutationResult, type TaskRegistryScope, type TaskRecord, type TaskStatus, } from './runtime/task-registry.mjs';
 export { createPostgresTaskRegistry, getDecisioningTaskRegistryBootstrap, getDecisioningTaskRegistryMigration, getDecisioningTaskRegistryScopeV1Upgrade, type CreatePostgresTaskRegistryOptions, type DecisioningTaskRegistryScopeV1Upgrade, type DecisioningTaskRegistryScopeV1UpgradeOptions, type PgQueryable, type PgTransactionClient, type PgTransactionalPool, } from './runtime/postgres-task-registry.mjs';
 export { completeScopedPushTask, createPostgresTaskSettlementCoordinator, failScopedPushTask, TaskPushSettlementConfigurationError, type PostgresTaskSettlementCoordinator, type PostgresTaskSettlementCoordinatorOptions, type TaskPushDeliveryState, type TaskPushSettlementConfig, type TaskPushSettlementOutcome, } from './runtime/postgres-task-settlement.mjs';
+export { canonicalizeTaskSettlementIntent, createPostgresTaskSettlementIntentQueue, getTaskSettlementIntentMigration, TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS, TaskSettlementIntentConflictError, type CreatePostgresTaskSettlementIntentQueueOptions, type DurableTaskSettlementRef, type PostgresTaskSettlementIntentQueue, type PruneTaskSettlementIntentAcknowledgementsOptions, type RecoverTaskSettlementIntentsOptions, type TaskSettlementIntent, type TaskSettlementIntentCheckpoint, type TaskSettlementIntentRecoveryContext, type TaskSettlementIntentRecoveryErrorContext, type TaskSettlementIntentRecoveryMetrics, type TaskSettlementIntentWriteOptions, } from './runtime/postgres-task-settlement-intents.mjs';
 export { createTenantRegistry, createDefaultJwksValidator, createSelfSignedTenantKey, createNoopJwksValidator, type TenantRegistry, type TenantConfig, type TenantSigningKey, type TenantStatus, type TenantHealth, type TenantRegistryOptions, type JwksValidator, type JwksValidationResult, } from './tenant-registry.mjs';
 export { getAsset, getAssetSlot, requireAsset } from './manifest-helpers.mjs';
 export type { CreativeAssetsContainer } from './manifest-helpers.mjs';

package/dist/lib/server/decisioning/index.d.ts

@@ -49,6 +49,7 @@ export { PlatformConfigError, validatePlatform } from './runtime/validate-platfo
 export { completeScopedTask, createInMemoryTaskRegistry, failScopedTask, updateScopedTaskProgress, type ScopedTaskRef, type TaskMutationOutcome, type TaskRegistry, type TaskRegistryMutationResult, type TaskRegistryScope, type TaskRecord, type TaskStatus, } from './runtime/task-registry';
 export { createPostgresTaskRegistry, getDecisioningTaskRegistryBootstrap, getDecisioningTaskRegistryMigration, getDecisioningTaskRegistryScopeV1Upgrade, type CreatePostgresTaskRegistryOptions, type DecisioningTaskRegistryScopeV1Upgrade, type DecisioningTaskRegistryScopeV1UpgradeOptions, type PgQueryable, type PgTransactionClient, type PgTransactionalPool, } from './runtime/postgres-task-registry';
 export { completeScopedPushTask, createPostgresTaskSettlementCoordinator, failScopedPushTask, TaskPushSettlementConfigurationError, type PostgresTaskSettlementCoordinator, type PostgresTaskSettlementCoordinatorOptions, type TaskPushDeliveryState, type TaskPushSettlementConfig, type TaskPushSettlementOutcome, } from './runtime/postgres-task-settlement';
+export { canonicalizeTaskSettlementIntent, createPostgresTaskSettlementIntentQueue, getTaskSettlementIntentMigration, TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS, TaskSettlementIntentConflictError, type CreatePostgresTaskSettlementIntentQueueOptions, type DurableTaskSettlementRef, type PostgresTaskSettlementIntentQueue, type PruneTaskSettlementIntentAcknowledgementsOptions, type RecoverTaskSettlementIntentsOptions, type TaskSettlementIntent, type TaskSettlementIntentCheckpoint, type TaskSettlementIntentRecoveryContext, type TaskSettlementIntentRecoveryErrorContext, type TaskSettlementIntentRecoveryMetrics, type TaskSettlementIntentWriteOptions, } from './runtime/postgres-task-settlement-intents';
 export { createTenantRegistry, createDefaultJwksValidator, createSelfSignedTenantKey, createNoopJwksValidator, type TenantRegistry, type TenantConfig, type TenantSigningKey, type TenantStatus, type TenantHealth, type TenantRegistryOptions, type JwksValidator, type JwksValidationResult, } from './tenant-registry';
 export { getAsset, getAssetSlot, requireAsset } from './manifest-helpers';
 export type { CreativeAssetsContainer } from './manifest-helpers';

package/dist/lib/server/decisioning/index.js

@@ -46,7 +46,9 @@ __export(decisioning_exports, {
   ProductUnavailableError: () => import_errors_typed.ProductUnavailableError,
   RateLimitedError: () => import_errors_typed.RateLimitedError,
   ServiceUnavailableError: () => import_errors_typed.ServiceUnavailableError,
+  TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS: () => import_postgres_task_settlement_intents.TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS,
   TaskPushSettlementConfigurationError: () => import_postgres_task_settlement.TaskPushSettlementConfigurationError,
+  TaskSettlementIntentConflictError: () => import_postgres_task_settlement_intents.TaskSettlementIntentConflictError,
   UnsupportedFeatureError: () => import_errors_typed.UnsupportedFeatureError,
   batchPoll: () => import_helpers.batchPoll,
   buildListCreativesResponse: () => import_list_helpers.buildListCreativesResponse,
@@ -55,6 +57,7 @@ __export(decisioning_exports, {
   buildPricingOption: () => import_assembly_helpers.buildPricingOption,
   buildProduct: () => import_assembly_helpers.buildProduct,
   buildProductLegacy: () => import_assembly_helpers.buildProductLegacy,
+  canonicalizeTaskSettlementIntent: () => import_postgres_task_settlement_intents.canonicalizeTaskSettlementIntent,
   completeScopedPushTask: () => import_postgres_task_settlement.completeScopedPushTask,
   completeScopedTask: () => import_task_registry.completeScopedTask,
   composeMethod: () => import_compose.composeMethod,
@@ -66,6 +69,7 @@ __export(decisioning_exports, {
   createPostgresProposalStore: () => import_proposal.createPostgresProposalStore,
   createPostgresTaskRegistry: () => import_postgres_task_registry.createPostgresTaskRegistry,
   createPostgresTaskSettlementCoordinator: () => import_postgres_task_settlement.createPostgresTaskSettlementCoordinator,
+  createPostgresTaskSettlementIntentQueue: () => import_postgres_task_settlement_intents.createPostgresTaskSettlementIntentQueue,
   createSelfSignedTenantKey: () => import_tenant_registry.createSelfSignedTenantKey,
   createTenantAdminHandlers: () => import_admin_router.createTenantAdminHandlers,
   createTenantAdminRouter: () => import_admin_router.createTenantAdminRouter,
@@ -100,6 +104,7 @@ __export(decisioning_exports, {
   getHydratedLegacyFormatIds: () => import_from_platform.getHydratedLegacyFormatIds,
   getProposalStoreMigration: () => import_proposal.getProposalStoreMigration,
   getStatusChangeBus: () => import_status_changes.getStatusChangeBus,
+  getTaskSettlementIntentMigration: () => import_postgres_task_settlement_intents.getTaskSettlementIntentMigration,
   identityStatusMappers: () => import_status_mappers.identityStatusMappers,
   maybeHydrateRecipesForMediaBuyId: () => import_proposal.maybeHydrateRecipesForMediaBuyId,
   maybeInterceptFinalize: () => import_proposal.maybeInterceptFinalize,
@@ -145,6 +150,7 @@ var import_validate_platform = require('./runtime/validate-platform.js');
 var import_task_registry = require('./runtime/task-registry.js');
 var import_postgres_task_registry = require('./runtime/postgres-task-registry.js');
 var import_postgres_task_settlement = require('./runtime/postgres-task-settlement.js');
+var import_postgres_task_settlement_intents = require('./runtime/postgres-task-settlement-intents.js');
 var import_tenant_registry = require('./tenant-registry.js');
 var import_manifest_helpers = require('./manifest-helpers.js');
 var import_list_helpers = require('./list-helpers.js');
@@ -184,7 +190,9 @@ var import_assembly_helpers = require('./assembly-helpers.js');
   ProductUnavailableError,
   RateLimitedError,
   ServiceUnavailableError,
+  TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS,
   TaskPushSettlementConfigurationError,
+  TaskSettlementIntentConflictError,
   UnsupportedFeatureError,
   batchPoll,
   buildListCreativesResponse,
@@ -193,6 +201,7 @@ var import_assembly_helpers = require('./assembly-helpers.js');
   buildPricingOption,
   buildProduct,
   buildProductLegacy,
+  canonicalizeTaskSettlementIntent,
   completeScopedPushTask,
   completeScopedTask,
   composeMethod,
@@ -204,6 +213,7 @@ var import_assembly_helpers = require('./assembly-helpers.js');
   createPostgresProposalStore,
   createPostgresTaskRegistry,
   createPostgresTaskSettlementCoordinator,
+  createPostgresTaskSettlementIntentQueue,
   createSelfSignedTenantKey,
   createTenantAdminHandlers,
   createTenantAdminRouter,
@@ -238,6 +248,7 @@ var import_assembly_helpers = require('./assembly-helpers.js');
   getHydratedLegacyFormatIds,
   getProposalStoreMigration,
   getStatusChangeBus,
+  getTaskSettlementIntentMigration,
   identityStatusMappers,
   maybeHydrateRecipesForMediaBuyId,
   maybeInterceptFinalize,

package/dist/lib/server/decisioning/index.mjs

@@ -61,6 +61,13 @@ import {
   failScopedPushTask,
   TaskPushSettlementConfigurationError
 } from "./runtime/postgres-task-settlement.mjs";
+import {
+  canonicalizeTaskSettlementIntent,
+  createPostgresTaskSettlementIntentQueue,
+  getTaskSettlementIntentMigration,
+  TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS,
+  TaskSettlementIntentConflictError
+} from "./runtime/postgres-task-settlement-intents.mjs";
 import {
   createTenantRegistry,
   createDefaultJwksValidator,
@@ -145,7 +152,9 @@ export {
   ProductUnavailableError,
   RateLimitedError,
   ServiceUnavailableError,
+  TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS,
   TaskPushSettlementConfigurationError,
+  TaskSettlementIntentConflictError,
   UnsupportedFeatureError,
   batchPoll,
   buildListCreativesResponse,
@@ -154,6 +163,7 @@ export {
   buildPricingOption,
   buildProduct,
   buildProductLegacy,
+  canonicalizeTaskSettlementIntent,
   completeScopedPushTask,
   completeScopedTask,
   composeMethod,
@@ -165,6 +175,7 @@ export {
   createPostgresProposalStore,
   createPostgresTaskRegistry,
   createPostgresTaskSettlementCoordinator,
+  createPostgresTaskSettlementIntentQueue,
   createSelfSignedTenantKey,
   createTenantAdminHandlers,
   createTenantAdminRouter,
@@ -199,6 +210,7 @@ export {
   getHydratedLegacyFormatIds,
   getProposalStoreMigration,
   getStatusChangeBus,
+  getTaskSettlementIntentMigration,
   identityStatusMappers,
   maybeHydrateRecipesForMediaBuyId,
   maybeInterceptFinalize,

package/dist/lib/server/decisioning/runtime/postgres-task-registry.js

@@ -382,7 +382,7 @@ function rowToRecord(row) {
     ...row.owner_scope ? { ownerScope: row.owner_scope } : {},
     status: row.status,
     ...row.status_message !== null && { statusMessage: row.status_message },
-    ...row.result !== null && row.result !== void 0 && { result: row.result },
+    ...(row.has_result ?? (row.result !== null && row.result !== void 0)) && { result: row.result },
     ...row.error !== null && row.error !== void 0 && { error: row.error },
     ...row.progress !== null && row.progress !== void 0 && { progress: row.progress },
     ...row.has_webhook && { hasWebhook: true },
@@ -447,7 +447,8 @@ function createPostgresTaskRegistry(opts) {
       if (scope.registryId !== void 0 && scope.registryId !== registryId) return null;
       const { rows } = await query(
         "getTask",
-        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result, error, progress, has_webhook, created_at, updated_at
+        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result,
+                result IS NOT NULL AS has_result, error, progress, has_webhook, created_at, updated_at
          FROM ${table} WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
         [taskId, namespace, scope.accountId, scope.ownerScope]
       );
@@ -457,7 +458,8 @@ function createPostgresTaskRegistry(opts) {
     async list(listOpts) {
       const { rows } = await query(
         "list",
-        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result, error, progress, has_webhook, created_at, updated_at
+        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result,
+                result IS NOT NULL AS has_result, error, progress, has_webhook, created_at, updated_at
          FROM ${table}
          WHERE registry_namespace = $1 AND account_id = $2 AND owner_scope = $3
          ORDER BY created_at DESC, task_id DESC`,

package/dist/lib/server/decisioning/runtime/postgres-task-registry.mjs

@@ -355,7 +355,7 @@ function rowToRecord(row) {
     ...row.owner_scope ? { ownerScope: row.owner_scope } : {},
     status: row.status,
     ...row.status_message !== null && { statusMessage: row.status_message },
-    ...row.result !== null && row.result !== void 0 && { result: row.result },
+    ...(row.has_result ?? (row.result !== null && row.result !== void 0)) && { result: row.result },
     ...row.error !== null && row.error !== void 0 && { error: row.error },
     ...row.progress !== null && row.progress !== void 0 && { progress: row.progress },
     ...row.has_webhook && { hasWebhook: true },
@@ -420,7 +420,8 @@ function createPostgresTaskRegistry(opts) {
       if (scope.registryId !== void 0 && scope.registryId !== registryId) return null;
       const { rows } = await query(
         "getTask",
-        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result, error, progress, has_webhook, created_at, updated_at
+        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result,
+                result IS NOT NULL AS has_result, error, progress, has_webhook, created_at, updated_at
          FROM ${table} WHERE task_id = $1 AND registry_namespace = $2 AND account_id = $3 AND owner_scope = $4`,
         [taskId, namespace, scope.accountId, scope.ownerScope]
       );
@@ -430,7 +431,8 @@ function createPostgresTaskRegistry(opts) {
     async list(listOpts) {
       const { rows } = await query(
         "list",
-        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result, error, progress, has_webhook, created_at, updated_at
+        `SELECT task_id, tool, account_id, owner_scope, status, status_message, result,
+                result IS NOT NULL AS has_result, error, progress, has_webhook, created_at, updated_at
          FROM ${table}
          WHERE registry_namespace = $1 AND account_id = $2 AND owner_scope = $3
          ORDER BY created_at DESC, task_id DESC`,

package/dist/lib/server/decisioning/runtime/postgres-task-settlement-intents.d.mts

@@ -0,0 +1,136 @@
+/**
+ * Durable PostgreSQL queue for application-owned task settlement intents.
+ *
+ * `createPostgresTaskSettlementCoordinator()` makes the task transition and
+ * terminal webhook checkpoint atomic. This queue protects the boundary before
+ * that call: an application may commit a human approval or provider outcome
+ * and then die before it asks the SDK to settle the AdCP task.
+ */
+import type { AdcpStructuredError } from '../async-outcome.mjs';
+import type { PgQueryable } from './postgres-task-registry.mjs';
+import { type ScopedTaskRef } from './task-registry.mjs';
+/** Default conflict-retention window after an intent is acknowledged. */
+export declare const TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS: number;
+/** Complete, serializable task handle required by the durable intent queue. */
+export interface DurableTaskSettlementRef extends ScopedTaskRef {
+    registryId: string;
+    ownerScope: string;
+}
+export type TaskSettlementIntent = {
+    taskRef: DurableTaskSettlementRef;
+    action: 'complete';
+    result: unknown;
+} | {
+    taskRef: DurableTaskSettlementRef;
+    action: 'fail';
+    error: AdcpStructuredError;
+    result?: unknown;
+};
+export interface TaskSettlementIntentCheckpoint extends DurableTaskSettlementRef {
+    queueNamespace: string;
+    intentFingerprint: string;
+}
+export interface TaskSettlementIntentRecoveryContext {
+    attemptCount: number;
+    /** Extend this claim by the configured lease duration. Returns false if fencing ownership was lost. */
+    extendLease(): Promise<boolean>;
+}
+export interface TaskSettlementIntentRecoveryMetrics {
+    claimed: number;
+    settled: number;
+    retried: number;
+    deadLettered: number;
+    leaseLost: number;
+}
+export interface TaskSettlementIntentRecoveryErrorContext {
+    attemptCount: number;
+    taskRef: DurableTaskSettlementRef;
+    action: TaskSettlementIntent['action'];
+    disposition: 'retry' | 'dead_letter' | 'lease_lost';
+}
+export interface RecoverTaskSettlementIntentsOptions {
+    /**
+     * Apply the exact terminal intent and return the literal `settled` only
+     * after the intended state is proven. The implementation MUST be
+     * idempotent because a worker can die after settlement and before ack.
+     */
+    settle(intent: TaskSettlementIntent, context: TaskSettlementIntentRecoveryContext): Promise<'settled'>;
+    batchSize?: number;
+    leaseMs?: number;
+    retryAfterMs?: number;
+    maxRetryAfterMs?: number;
+    maxAttempts?: number;
+    workerId?: string;
+    /** Observability hook. Error messages are never persisted by the queue. */
+    onError?(error: unknown, context: TaskSettlementIntentRecoveryErrorContext): void | Promise<void>;
+}
+export interface TaskSettlementIntentWriteOptions {
+    /**
+     * Optional active transaction client. Use this to commit the domain outcome
+     * and settlement intent atomically in the same application transaction.
+     */
+    db?: PgQueryable;
+}
+export interface PruneTaskSettlementIntentAcknowledgementsOptions extends TaskSettlementIntentWriteOptions {
+    /** Maximum tombstones removed by this call. Defaults to 1000; maximum 10000. */
+    limit?: number;
+}
+export interface PostgresTaskSettlementIntentQueue {
+    readonly durability: 'durable';
+    enqueue(intent: TaskSettlementIntent, options?: TaskSettlementIntentWriteOptions): Promise<TaskSettlementIntentCheckpoint>;
+    /** Returns false when the exact checkpoint was already absent. */
+    acknowledge(checkpoint: TaskSettlementIntentCheckpoint, options?: TaskSettlementIntentWriteOptions): Promise<boolean>;
+    /** Remove a bounded batch of acknowledgement tombstones whose idempotency horizon elapsed. */
+    pruneAcknowledged(options?: PruneTaskSettlementIntentAcknowledgementsOptions): Promise<number>;
+    recover(options: RecoverTaskSettlementIntentsOptions): Promise<TaskSettlementIntentRecoveryMetrics>;
+    probe(): Promise<void>;
+}
+export interface CreatePostgresTaskSettlementIntentQueueOptions {
+    /** Pool used by recovery and by writes that do not supply a transaction. */
+    db: PgQueryable;
+    /** Trusted deployment or tenant namespace. */
+    namespace: string;
+    /** Defaults to `adcp_task_settlement_intents`. */
+    tableName?: string;
+    /**
+     * Retain acknowledged fingerprints for this long so a conflicting terminal
+     * artifact cannot rebind the same scoped task. Defaults to seven days.
+     */
+    idempotencyHorizonMs?: number;
+}
+/** An existing scoped task is already bound to a different terminal intent. */
+export declare class TaskSettlementIntentConflictError extends Error {
+    readonly name = "TaskSettlementIntentConflictError";
+}
+/** Bootstrap DDL for a new durable settlement-intent queue. */
+export declare function getTaskSettlementIntentMigration(options?: {
+    tableName?: string;
+}): string;
+/**
+ * Create a durable task-settlement intent queue.
+ *
+ * @example
+ * ```ts
+ * const queue = createPostgresTaskSettlementIntentQueue({
+ *   db: pool,
+ *   namespace: 'seller-prod',
+ * });
+ *
+ * await withTransaction(async tx => {
+ *   await saveApproval(tx, approval);
+ *   await queue.enqueue({ taskRef, action: 'complete', result }, { db: tx });
+ * });
+ *
+ * await queue.recover({
+ *   settle: async intent => {
+ *     await settleThroughRegistryOrPushCoordinator(intent);
+ *     return 'settled';
+ *   },
+ * });
+ * ```
+ */
+export declare function createPostgresTaskSettlementIntentQueue(options: CreatePostgresTaskSettlementIntentQueueOptions): PostgresTaskSettlementIntentQueue;
+/** Clone, validate, and reduce an intent to the exact artifact persisted by the task registry. */
+export declare function canonicalizeTaskSettlementIntent(intent: TaskSettlementIntent): TaskSettlementIntent & {
+    taskRef: DurableTaskSettlementRef;
+};

package/dist/lib/server/decisioning/runtime/postgres-task-settlement-intents.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Durable PostgreSQL queue for application-owned task settlement intents.
+ *
+ * `createPostgresTaskSettlementCoordinator()` makes the task transition and
+ * terminal webhook checkpoint atomic. This queue protects the boundary before
+ * that call: an application may commit a human approval or provider outcome
+ * and then die before it asks the SDK to settle the AdCP task.
+ */
+import type { AdcpStructuredError } from '../async-outcome';
+import type { PgQueryable } from './postgres-task-registry';
+import { type ScopedTaskRef } from './task-registry';
+/** Default conflict-retention window after an intent is acknowledged. */
+export declare const TASK_SETTLEMENT_INTENT_IDEMPOTENCY_HORIZON_MS: number;
+/** Complete, serializable task handle required by the durable intent queue. */
+export interface DurableTaskSettlementRef extends ScopedTaskRef {
+    registryId: string;
+    ownerScope: string;
+}
+export type TaskSettlementIntent = {
+    taskRef: DurableTaskSettlementRef;
+    action: 'complete';
+    result: unknown;
+} | {
+    taskRef: DurableTaskSettlementRef;
+    action: 'fail';
+    error: AdcpStructuredError;
+    result?: unknown;
+};
+export interface TaskSettlementIntentCheckpoint extends DurableTaskSettlementRef {
+    queueNamespace: string;
+    intentFingerprint: string;
+}
+export interface TaskSettlementIntentRecoveryContext {
+    attemptCount: number;
+    /** Extend this claim by the configured lease duration. Returns false if fencing ownership was lost. */
+    extendLease(): Promise<boolean>;
+}
+export interface TaskSettlementIntentRecoveryMetrics {
+    claimed: number;
+    settled: number;
+    retried: number;
+    deadLettered: number;
+    leaseLost: number;
+}
+export interface TaskSettlementIntentRecoveryErrorContext {
+    attemptCount: number;
+    taskRef: DurableTaskSettlementRef;
+    action: TaskSettlementIntent['action'];
+    disposition: 'retry' | 'dead_letter' | 'lease_lost';
+}
+export interface RecoverTaskSettlementIntentsOptions {
+    /**
+     * Apply the exact terminal intent and return the literal `settled` only
+     * after the intended state is proven. The implementation MUST be
+     * idempotent because a worker can die after settlement and before ack.
+     */
+    settle(intent: TaskSettlementIntent, context: TaskSettlementIntentRecoveryContext): Promise<'settled'>;
+    batchSize?: number;
+    leaseMs?: number;
+    retryAfterMs?: number;
+    maxRetryAfterMs?: number;
+    maxAttempts?: number;
+    workerId?: string;
+    /** Observability hook. Error messages are never persisted by the queue. */
+    onError?(error: unknown, context: TaskSettlementIntentRecoveryErrorContext): void | Promise<void>;
+}
+export interface TaskSettlementIntentWriteOptions {
+    /**
+     * Optional active transaction client. Use this to commit the domain outcome
+     * and settlement intent atomically in the same application transaction.
+     */
+    db?: PgQueryable;
+}
+export interface PruneTaskSettlementIntentAcknowledgementsOptions extends TaskSettlementIntentWriteOptions {
+    /** Maximum tombstones removed by this call. Defaults to 1000; maximum 10000. */
+    limit?: number;
+}
+export interface PostgresTaskSettlementIntentQueue {
+    readonly durability: 'durable';
+    enqueue(intent: TaskSettlementIntent, options?: TaskSettlementIntentWriteOptions): Promise<TaskSettlementIntentCheckpoint>;
+    /** Returns false when the exact checkpoint was already absent. */
+    acknowledge(checkpoint: TaskSettlementIntentCheckpoint, options?: TaskSettlementIntentWriteOptions): Promise<boolean>;
+    /** Remove a bounded batch of acknowledgement tombstones whose idempotency horizon elapsed. */
+    pruneAcknowledged(options?: PruneTaskSettlementIntentAcknowledgementsOptions): Promise<number>;
+    recover(options: RecoverTaskSettlementIntentsOptions): Promise<TaskSettlementIntentRecoveryMetrics>;
+    probe(): Promise<void>;
+}
+export interface CreatePostgresTaskSettlementIntentQueueOptions {
+    /** Pool used by recovery and by writes that do not supply a transaction. */
+    db: PgQueryable;
+    /** Trusted deployment or tenant namespace. */
+    namespace: string;
+    /** Defaults to `adcp_task_settlement_intents`. */
+    tableName?: string;
+    /**
+     * Retain acknowledged fingerprints for this long so a conflicting terminal
+     * artifact cannot rebind the same scoped task. Defaults to seven days.
+     */
+    idempotencyHorizonMs?: number;
+}
+/** An existing scoped task is already bound to a different terminal intent. */
+export declare class TaskSettlementIntentConflictError extends Error {
+    readonly name = "TaskSettlementIntentConflictError";
+}
+/** Bootstrap DDL for a new durable settlement-intent queue. */
+export declare function getTaskSettlementIntentMigration(options?: {
+    tableName?: string;
+}): string;
+/**
+ * Create a durable task-settlement intent queue.
+ *
+ * @example
+ * ```ts
+ * const queue = createPostgresTaskSettlementIntentQueue({
+ *   db: pool,
+ *   namespace: 'seller-prod',
+ * });
+ *
+ * await withTransaction(async tx => {
+ *   await saveApproval(tx, approval);
+ *   await queue.enqueue({ taskRef, action: 'complete', result }, { db: tx });
+ * });
+ *
+ * await queue.recover({
+ *   settle: async intent => {
+ *     await settleThroughRegistryOrPushCoordinator(intent);
+ *     return 'settled';
+ *   },
+ * });
+ * ```
+ */
+export declare function createPostgresTaskSettlementIntentQueue(options: CreatePostgresTaskSettlementIntentQueueOptions): PostgresTaskSettlementIntentQueue;
+/** Clone, validate, and reduce an intent to the exact artifact persisted by the task registry. */
+export declare function canonicalizeTaskSettlementIntent(intent: TaskSettlementIntent): TaskSettlementIntent & {
+    taskRef: DurableTaskSettlementRef;
+};