@fabricorg/platform-host 8.1.1 → 8.2.0

package/dist/index.d.cts

@@ -241,6 +241,25 @@ export interface PendingAssetEvent {
   payload: unknown;
   eventSchemaVersion?: number;
 }
+/** JSON preparation committed with the handler before adapter execution. */
+export interface FinalizationCheckpoint {
+  protocol: "atomic-after-adapters-v1";
+  actionVersion: number;
+  steps: {
+    adapterType: string;
+    operation: string;
+  }[];
+  params: import("@fabricorg/platform").FinalizationJson;
+  handlerData: import("@fabricorg/platform").FinalizationRecord;
+  handlerEvents: (Omit<PendingAssetEvent, "payload"> & {
+    payload: import("@fabricorg/platform").FinalizationJson;
+  })[];
+  result: import("@fabricorg/platform").FinalizationRecord;
+  stateTransition?: Omit<PendingAssetEvent, "payload"> & {
+    payload: import("@fabricorg/platform").FinalizationJson;
+  };
+  skipped: number[];
+}
 export interface ActionInvocationRecord {
   id: string;
   tenantId: string;
@@ -265,6 +284,8 @@ export interface ActionInvocationRecord {
   authorizationReconciliation?: AuthorizationReconciliationOutcome;
   /** Durable evidence when an adapter returned an ambiguous outcome requiring reconciliation. */
   adapterReconciliation?: AdapterReconciliationOutcome;
+  /** Durable normalized preparation; absent for invocations prepared by older Hosts. */
+  finalizationCheckpoint?: FinalizationCheckpoint;
   /**
    * Transition Host validated for an idempotent after_adapters action, saved
    * after handler/result/event validation inside a mutation transaction, or before
@@ -289,6 +310,8 @@ export interface ActionInvocationRecord {
   authorizationBindingId?: string;
   /** Worker claims including the first; approval acceptance sets a minimum of 1. */
   attemptCount: number;
+  /** Latest claim durably deferred in pre-effect governance; permits only the immediately next claim. */
+  deferredBeforeEffectAttempt?: number;
   leaseOwner?: string;
   leaseExpiresAt?: Date;
   /** Monotonic claim generation used to reject writes from expired workers. */
@@ -954,7 +977,7 @@ export interface ClaimActionInvocationsInput {
  * - `claimActionInvocations` must never claim a running invocation without a
  *   lease, which is what a parked invocation is.
  */
-export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
+export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
 export interface UpdateLeasedActionInvocationInput {
   id: string;
   tenantId: string;
@@ -1179,10 +1202,12 @@ export interface PlatformHostOptions<TDb> {
   adapterCircuitBreakers?: AdapterCircuitBreakerProvider;
   /**
    * Positive integer attempt cap for RetryableExecutionError during governance,
-   * before policy-evaluation persistence (default 5). A leased, idempotent action
-   * below the cap is left running for worker reclaim after lease expiry.
-   * Inline execution, approval resume, exhausted attempts, and non-idempotent
-   * actions fail. Policy persistence, obligation listing/resolution/persistence, state-machine checks,
+   * before policy-evaluation persistence (default 5). A leased action below the cap
+   * is left running for worker reclaim after lease expiry. Non-idempotent actions
+   * require a lease-fenced pre-effect deferral marker for the current claim; only
+   * the immediately next claim may proceed using that marker. Inline execution,
+   * approval resume, exhausted attempts, and marker-write failures are not retried.
+   * Policy persistence, obligation listing/resolution/persistence, state-machine checks,
    * the handler transaction, handlers, adapters, and finalization are excluded;
    * their failure/reconciliation/recovery semantics apply, subject to recoveryMaxAttempts.
    */
@@ -1294,6 +1319,12 @@ export interface PlatformHostOptions<TDb> {
   extractEvents?: (data: Record<string, unknown>) => PendingAssetEvent[];
   /** Handler-result fields consumed by extractEvents and omitted from the durable result. */
   eventResultFields?: readonly string[];
+  /**
+   * Optional name registry for hook-returned events from action.finalize.
+   * Checks eventType and subjectType membership; it does not validate handler events,
+   * eventSchemaVersion compatibility, or payload schemas.
+   */
+  eventContracts?: import("@fabricorg/platform").EventContractRegistry;
   redactAdapterInput?: (actionId: ActionId, adapterType: string, operation: string, input: Record<string, unknown>) => Record<string, unknown>;
   /**
    * Redact successful adapter output before row/event persistence and attestation extraction.
@@ -1330,8 +1361,9 @@ export interface PlatformHostOptions<TDb> {
   /** Vendor-neutral lifecycle and metric sink. Telemetry is best effort. */
   telemetry?: PlatformHostTelemetry;
   /**
-   * Epoch-millis deadline delivered to every adapter execution context.
-   * When omitted, no deadline is set and adapters receive no AbortSignal.
+   * Duration in milliseconds, measured before the step enters adapter retry execution.
+   * A step deadlineMs overrides this duration. When this is omitted or zero and
+   * the step has no deadlineMs, no deadline or AbortSignal is delivered.
    */
   adapterDeadlineMs?: number;
 }

package/dist/index.d.ts

@@ -241,6 +241,25 @@ export interface PendingAssetEvent {
   payload: unknown;
   eventSchemaVersion?: number;
 }
+/** JSON preparation committed with the handler before adapter execution. */
+export interface FinalizationCheckpoint {
+  protocol: "atomic-after-adapters-v1";
+  actionVersion: number;
+  steps: {
+    adapterType: string;
+    operation: string;
+  }[];
+  params: import("@fabricorg/platform").FinalizationJson;
+  handlerData: import("@fabricorg/platform").FinalizationRecord;
+  handlerEvents: (Omit<PendingAssetEvent, "payload"> & {
+    payload: import("@fabricorg/platform").FinalizationJson;
+  })[];
+  result: import("@fabricorg/platform").FinalizationRecord;
+  stateTransition?: Omit<PendingAssetEvent, "payload"> & {
+    payload: import("@fabricorg/platform").FinalizationJson;
+  };
+  skipped: number[];
+}
 export interface ActionInvocationRecord {
   id: string;
   tenantId: string;
@@ -265,6 +284,8 @@ export interface ActionInvocationRecord {
   authorizationReconciliation?: AuthorizationReconciliationOutcome;
   /** Durable evidence when an adapter returned an ambiguous outcome requiring reconciliation. */
   adapterReconciliation?: AdapterReconciliationOutcome;
+  /** Durable normalized preparation; absent for invocations prepared by older Hosts. */
+  finalizationCheckpoint?: FinalizationCheckpoint;
   /**
    * Transition Host validated for an idempotent after_adapters action, saved
    * after handler/result/event validation inside a mutation transaction, or before
@@ -289,6 +310,8 @@ export interface ActionInvocationRecord {
   authorizationBindingId?: string;
   /** Worker claims including the first; approval acceptance sets a minimum of 1. */
   attemptCount: number;
+  /** Latest claim durably deferred in pre-effect governance; permits only the immediately next claim. */
+  deferredBeforeEffectAttempt?: number;
   leaseOwner?: string;
   leaseExpiresAt?: Date;
   /** Monotonic claim generation used to reject writes from expired workers. */
@@ -954,7 +977,7 @@ export interface ClaimActionInvocationsInput {
  * - `claimActionInvocations` must never claim a running invocation without a
  *   lease, which is what a parked invocation is.
  */
-export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
+export type ActionInvocationPatch = Partial<Pick<ActionInvocationRecord, "finalizationCheckpoint" | "deferredBeforeEffectAttempt" | "status" | "result" | "error" | "authorizationReconciliation" | "adapterReconciliation" | "pendingStateTransition" | "pendingCompletion" | "externalCompletion">>;
 export interface UpdateLeasedActionInvocationInput {
   id: string;
   tenantId: string;
@@ -1179,10 +1202,12 @@ export interface PlatformHostOptions<TDb> {
   adapterCircuitBreakers?: AdapterCircuitBreakerProvider;
   /**
    * Positive integer attempt cap for RetryableExecutionError during governance,
-   * before policy-evaluation persistence (default 5). A leased, idempotent action
-   * below the cap is left running for worker reclaim after lease expiry.
-   * Inline execution, approval resume, exhausted attempts, and non-idempotent
-   * actions fail. Policy persistence, obligation listing/resolution/persistence, state-machine checks,
+   * before policy-evaluation persistence (default 5). A leased action below the cap
+   * is left running for worker reclaim after lease expiry. Non-idempotent actions
+   * require a lease-fenced pre-effect deferral marker for the current claim; only
+   * the immediately next claim may proceed using that marker. Inline execution,
+   * approval resume, exhausted attempts, and marker-write failures are not retried.
+   * Policy persistence, obligation listing/resolution/persistence, state-machine checks,
    * the handler transaction, handlers, adapters, and finalization are excluded;
    * their failure/reconciliation/recovery semantics apply, subject to recoveryMaxAttempts.
    */
@@ -1294,6 +1319,12 @@ export interface PlatformHostOptions<TDb> {
   extractEvents?: (data: Record<string, unknown>) => PendingAssetEvent[];
   /** Handler-result fields consumed by extractEvents and omitted from the durable result. */
   eventResultFields?: readonly string[];
+  /**
+   * Optional name registry for hook-returned events from action.finalize.
+   * Checks eventType and subjectType membership; it does not validate handler events,
+   * eventSchemaVersion compatibility, or payload schemas.
+   */
+  eventContracts?: import("@fabricorg/platform").EventContractRegistry;
   redactAdapterInput?: (actionId: ActionId, adapterType: string, operation: string, input: Record<string, unknown>) => Record<string, unknown>;
   /**
    * Redact successful adapter output before row/event persistence and attestation extraction.
@@ -1330,8 +1361,9 @@ export interface PlatformHostOptions<TDb> {
   /** Vendor-neutral lifecycle and metric sink. Telemetry is best effort. */
   telemetry?: PlatformHostTelemetry;
   /**
-   * Epoch-millis deadline delivered to every adapter execution context.
-   * When omitted, no deadline is set and adapters receive no AbortSignal.
+   * Duration in milliseconds, measured before the step enters adapter retry execution.
+   * A step deadlineMs overrides this duration. When this is omitted or zero and
+   * the step has no deadlineMs, no deadline or AbortSignal is delivered.
    */
   adapterDeadlineMs?: number;
 }