@fabricorg/platform-host 8.1.1 → 8.2.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @fabricorg/platform-host
 
+## 8.2.0
+
+### Minor Changes
+
+- 71d306f: Add optional action-level finalization for atomic, immediate after_adapters actions, including non-idempotent actions. Export JSON finalization types, registration validation, a manifest protocol descriptor and defineFinalizingAction to guard handlers against older hosts.
+
+  Host requires atomic transactions, invocation locking and transaction-scoped lease fencing before application execution. On normal success the hook consumes stored redacted outputs and commits transaction-local domain writes, declared events, outbox and the merged result together. Hook or validation failure rolls back finalization and settles reconciliation_required when durable provider effects exist, or failed when there are none, with redacted error text. Lease loss escapes without a stale-worker verdict. Handler preparation writes remain separately committed.
+
+  If entry to or COMMIT of the final success transaction (after adapters) fails with an unknown outcome, Host raises RecoverableFinalizationError and records no verdict. An uncommitted invocation stays running for recovery; a committed completed invocation retains its stored verdict and result for re-execution.
+
+  Explicit undefined on the optional hook return fields events, resultPatch and eventSchemaVersion is treated as omitted. Payloads and result-patch values retain strict JSON validation and reject undefined.
+
+  Failed, ambiguous, degraded and accepted/handoff outcomes do not invoke the hook. Existing actions retain their lifecycle.
+
+  Before adapters, normalize hook parameters and public handler data through a JSON round-trip, stripping private handler carriers. Dates become ISO strings and undefined object properties drop; serialization failures such as cycles or BigInt fail before provider execution. Handler events are normalized separately. Hook event schema versions default to the action version when omitted.
+
+  Add optional Host eventContracts name validation for events returned by the finalize hook. It checks eventType and subjectType membership only; handler events, payload schemas and schema-version compatibility are outside this option's scope. Recovery refusal also preserves ambiguity evidence for in-flight adapter rows alongside succeeded effects.
+
+- d5e7caa: Add optional adapter-step deadlineMs durations overriding the Host-wide duration,
+  including when the Host duration is unset or zero. Action and module registration, manifest export,
+  and manifest normalization reject step durations that are not positive finite integers.
+  Host validates resolved steps before handler or adapter execution. Invalid
+  durations fail a first execution without invoking adapters; retries with recorded
+  applied effects or unknown adapter outcomes require reconciliation instead.
+  Manifests preserve valid step durations.
+
+  Correct adapterDeadlineMs documentation: it is a duration starting just before
+  step retry execution, not an epoch timestamp. Host-wide behavior is unchanged.
+  Budgets span retries; expiry prevents a subsequent attempt and signals cooperative
+  cancellation of an in-flight call. An aborted call that throws retains the existing
+  ambiguous-outcome reconciliation semantics.
+
+- f32aae6: Commit versioned finalization preparation with handler writes, bounded to 256 KiB of canonical UTF-8 JSON. Recovery skips the handler, reuses succeeded adapter outputs and durable skips, and finalizes through the locked success transaction, including non-idempotent actions. Finalizing getInput callbacks receive normalized public data; legacy callbacks retain raw inputs.
+
+  Unknown adapter outcomes, incompatible protocol/action versions/ordered step identities, handoffs and governance refusal after effects retain reconciliation semantics. Missing checkpoints retain prior recovery behavior. Preparation validation/write failures roll back before adapters; unknown commit outcomes and lease loss remain recoverable without a stale verdict.
+
+  Apply migration 10 with ensureSchema before deploying checkpoint-writing Hosts. Updates omitting the field do not require its column.
+
+  A checkpoint bypasses non-idempotent interruption gates only when recorded adapter rows are succeeded. Failed rows preserve interruption settlement without repeating the provider call: failed without recorded success, reconciliation_required after another step succeeded. Leased non-idempotent replay additionally requires store-level and transaction-level writeAdapterInvocation fencing. Idempotent finalizing actions retain failed-row retry under existing adapter retry rules, using saved preparation.
+
+  On the live path, a finalizing action with an earlier succeeded adapter and a later permanent adapter failure now settles reconciliation_required instead of failed, without running the hook. Subsequent execution failures after a recorded provider effect likewise preserve reconciliation of partial progress.
+
+- 3d24330: Permit bounded leased retries of non-idempotent actions after retryable pre-effect governance errors. The additive deferredBeforeEffectAttempt record field proves only the immediately preceding claim deferred before handler or adapter effects. Missing or stale proof retains interruption failure. Marker-write failure retains terminal failure where persistence succeeds; lease loss preserves fencing errors. Approval resume, inline execution, exhausted budgets, and errors after the governance window retain their existing refusal semantics. Workspace dependents receive compatible patch releases.
+
+  PostgreSQL migration 9 (`pre_effect_governance_deferral`) adds the nullable marker column. Run `ensureSchema()` before deploying Hosts that may defer non-idempotent actions. Invocation updates that do not carry the marker omit its column, preserving writes on schemas without migration 9.
+
+## 8.1.2
+
+### Patch Changes
+
+- a297fcd: Republish workspace dependents of `@fabricorg/platform`, including transitive dependents, alongside the optional keyed privacy before-checksums (issue #104). Workspace ranges resolve to the released version when packed. Runtime source is unchanged.
+- 0a93df2: Republish workspace dependents of `@fabricorg/platform`, including transitive dependents, alongside the evidence-packet access-events section (issue #101). Workspace ranges resolve to the released version when packed. Runtime source is unchanged.
+
 ## 8.1.1
 
 ### Patch Changes

package/README.md

@@ -55,7 +55,8 @@ immediately before the first policy-evaluation record is written. Host rethrows
 without a failure/status write when:
 
 - the invocation has a lease owner and a defined lease token;
-- the action declares `idempotent: true`;
+- the action declares `idempotent: true`, or Host successfully records the current claim in
+  `deferredBeforeEffectAttempt` through a lease-fenced write;
 - `attemptCount` is below `retryableExecutionMaxAttempts`, a positive integer option defaulting to 5; and
 - execution is not a `resumeApprovedInvocation()` call.
 
@@ -65,12 +66,24 @@ deferrals do not increment `failed`. The worker counts by error type: a `Retryab
 that a store wrapper throws from Host's own reads or status writes also lands in `deferred`. In that
 case the row likewise stays leased for a later claim, but outside this cap. Retry becomes eligible when the current lease expires, so the
 delay is the remaining lease duration, followed by the worker's next claim; there is no immediate
-retry or separate backoff. The next claim increments `attemptCount`. At the cap, or for an unleased,
-non-idempotent, or approval-resume invocation, Host records `failed` with the reason retry was refused,
+retry or separate backoff. The next claim increments `attemptCount`. At the cap, or for an unleased
+or approval-resume invocation, Host records `failed` with the reason retry was refused,
 through the error-text redactor. Approval resume is excluded because its temporary lease does not
 establish that a recovery worker is configured. Ordinary application governance errors retain terminal failure behavior. Host store errors after
 a recorded provider effect follow the recovery rules below.
 
+Non-idempotent governance retry requires a durable `deferredBeforeEffectAttempt` equal to the
+preceding claim count. Each retry must record its own pre-effect deferral to permit another claim.
+A missing or stale marker retains interruption failure and manual reconciliation. Marker-write
+failure ends terminally when the verdict can be persisted; lease loss retains the recoverable
+fencing error. Handler and adapter errors are outside this deferral window.
+
+PostgreSQL migration 9 (`pre_effect_governance_deferral`) adds the nullable marker column.
+Run `ensureSchema()` before deploying Hosts that may defer non-idempotent actions. Invocation
+updates without the marker omit the column and continue to work on schemas without migration 9.
+If a marker write fails, Host refuses retry with `pre-effect marker could not be recorded` when
+it can persist the terminal verdict; lease loss preserves its fencing error.
+
 The retry region includes Host's single-record store writes for mutation-governance and HITL
 checkpoints. Later attempts reuse these persisted decisions through the `mutationFootprint` and
 `hitlRoute` guards. Callbacks should be safe to repeat and return stable invocation-scoped evidence.
@@ -133,7 +146,7 @@ Lifecycle records use deterministic checkpoint ids. Recovered idempotent actions
 adapter that already reached `succeeded`. Built-in stores deduplicate event and policy inserts by
 checkpoint ID. Adapter rows are mutable; stale-worker protection requires the optional
 `writeAdapterInvocation` capability described below. A
-reclaimed non-idempotent action inspects its adapter checkpoints: running or succeeded rows route
+reclaimed non-idempotent action without compatible finalization preparation inspects its adapter checkpoints: running or succeeded rows route
 to reconciliation; no rows or only failed rows retain terminal failure for manual review.
 
 Returned `ambiguous` or `timeout` outcomes, timeouts thrown from `adapter.execute` (including an
@@ -201,8 +214,8 @@ On a store without atomic support, if the verdict cannot be written at all, no d
 call succeeds: neither verdict nor checkpoint is saved, as after a crash mid-call. A leftover `running`
 step can then re-run on recovery for an idempotent action under the same `adapterInvocationId`
 idempotency key, within the worker recovery budget. A reclaimed non-idempotent action with a
-running row without a matching durable handoff settles that step as unknown. A succeeded row or
-durable handoff instead ends `reconciliation_required` as an applied effect. Adapters should be
+running row without a matching durable handoff settles that step as unknown. Without compatible
+finalization preparation, a succeeded row or durable handoff instead ends `reconciliation_required` as an applied effect. Adapters should be
 idempotent or carry that stable key. The same exposure applies if two atomic attempts roll back
 and the fallback verdict cannot be written.
 
@@ -212,7 +225,7 @@ This includes later adapter checkpoints, obligation reads, and the completion wr
 `before_adapters` and `after_adapters`. Recovery also protects Host store operations before
 and around the handler when an earlier provider effect is recorded. Authorization, policy and handler callbacks
 retain their own failure semantics. Idempotent recovery repairs recorded success/handoff evidence
-without calling that step's provider. Non-idempotent interruption ends `reconciliation_required`
+without calling that step's provider. Without compatible finalization preparation, non-idempotent interruption ends `reconciliation_required`
 instead of repairing the invocation. Lease loss retains its fencing error.
 
 If neither record is durable, Host retries the failed handoff or marker write once. After a
@@ -229,10 +242,12 @@ Recovery may replay that unrecorded outcome for an idempotent action under its s
 `adapterInvocationId`, within the worker budget. A reclaimed non-idempotent action instead
 ends `reconciliation_required`. A durable handoff takes precedence over its running row and is
 recorded as an applied effect with its external reference. A running row without such a handoff
-is settled as unknown. A succeeded row also ends `reconciliation_required`. With no rows or only failed rows, the existing
+is settled as unknown. Without compatible finalization preparation, a succeeded row also ends `reconciliation_required`. With no rows or only failed rows, the existing
 non-idempotent interruption gates still fail the invocation.
 
-For idempotent recovery, the handler still runs before the adapter loop. The loop reads each
+For idempotent recovery without an action finalizer, the handler still runs before the adapter loop.
+Finalizing actions with compatible durable preparation replay without rerunning the handler;
+missing or incompatible preparation retains effect-aware refusal. See [action-level finalization](#action-level-finalization). The loop reads each
 checkpoint before `getInput()` or adapter lookup. Succeeded rows and durable handoffs use stored
 adapter type, operation, vendor, input and output; a falsy new input or removed adapter does not
 skip evidence repair. Stable event IDs deduplicate replayed accepted and success events; newly
@@ -245,7 +260,7 @@ Host calls `extractExecutionAttestation` with stored input/output and checkpoint
 it must return deterministic evidence for the same input. A handoff checkpoint with no output,
 or withheld output, skips extraction. Repair errors remain recoverable within the budget.
 
-Known limits: a later step's definite provider failure or pre-call refusal can still end the
+Known limits for actions without checkpointed finalization: a later step's definite provider failure or pre-call refusal can still end the
 invocation `failed` after an earlier step succeeded. Authorization denials, ordinary handler
 failures, validation/state-guard rejection, and unsatisfied policy obligations on recovery retain
 their existing terminal outcomes. These are decisions or application failures, not Host store
@@ -398,7 +413,6 @@ still treats a failure inside the handler callback as a handler outcome.
 failing, the row stays `running` although the provider was not called. For an action not declared
 idempotent, the next claim settles that step as an unknown provider outcome.
 
-
 A deadline sweep retains the handoff and sets `pendingCompletion.overdueAt` with its
 `reconciliation_required` verdict. A late callback settles that verdict only when the handoff also
 has `parkedAt`, proving Host reached parking after its remaining steps and finalization. An unparked
@@ -466,6 +480,22 @@ in the `before_adapters` phase stay appended. If the breaker opens between retry
 retrying and records the refusal. See the `@fabricorg/platform` README for thresholds and outcome
 mapping.
 
+## Adapter execution deadlines
+
+`PlatformHostOptions.adapterDeadlineMs` is a duration in milliseconds, starting
+after step input preparation, just before the step enters retry execution.
+An action's `AdapterStep.deadlineMs` overrides that duration for the step, including
+when the Host option is unset or zero. Step durations must be positive finite integers;
+action and module registration, manifest normalization and export reject invalid
+values. Host also validates resolved steps before handler or adapter execution.
+
+The budget spans retry attempts and delays; it is not renewed per attempt.
+Host supplies an epoch-millisecond `AdapterExecutionContext.deadlineMs` and an
+`AbortSignal`. Adapters must observe the signal to abandon an in-flight call.
+Expiry before an attempt prevents that attempt; an aborted call that throws follows
+the existing ambiguous-outcome reconciliation path. With no step duration and an
+unset or zero Host duration, neither context field is supplied.
+
 ## Execution authorization
 
 Submission authorization proves that a caller may create an invocation. Applications that delegate
@@ -562,7 +592,116 @@ evidence, so concurrent transitions serialize. Retrying the same identity and ev
 reusing it with contradictory evidence fails closed, and a distinct transition cannot rewrite a
 terminal parent. `createSagaParentActivities()` supplies deterministic identities for Temporal callers.
 
-Actions can optionally declare `resultSchema`. The Host validates public handler result data after
+### Action-level finalization
+
+Define provider-dependent domain work with `defineFinalizingAction({ ...action, finalize })`.
+This helper guards the handler against older hosts by requiring
+`ctx.finalizationProtocol === "atomic-after-adapters-v1"`, including when no handler was
+provided. An optional callback alone cannot make an older host refuse execution.
+
+Finalizing actions declare `eventPhase: "after_adapters"`, atomic kind, and immediate
+completion (or omit kind/completion). Non-idempotent actions are supported. Host refuses
+execution before handler or adapters unless the store provides atomic mutation transactions,
+invocation locking, and transaction-scoped lease fencing. There is no fallback.
+
+`finalize(ctx, { params, handlerData, adapterOutputs })` receives transaction-bound `ctx.db`
+and identity/provenance, without services. Each ordered step is either skipped or succeeded
+with its index, adapter type, operation, invocation ID, and stored redacted JSON output.
+Before adapters, Host strips `eventResultFields` from handler data and normalizes the hook's
+parameters and public handler data using `JSON.parse(JSON.stringify(value))`, then validates
+the normalized JSON. Dates become ISO strings, undefined object properties drop, and class
+instances use their JSON representation; non-finite numbers become null. Cycles, BigInt or
+other serialization failures fail the handler phase before adapter calls or adapter rows.
+Handler events are normalized in that phase too. The hook receives copies of the saved
+normalized inputs, so adapter input preparation cannot change them.
+Perform transaction-local domain writes here; provider calls belong in adapters. Earlier
+handler writes commit separately and are outside this atomic completion.
+
+Return only `{ events?, resultPatch? }` with JSON-compatible values. Explicit `undefined` on
+`events`, `resultPatch`, or an event's `eventSchemaVersion` is treated as omitted; undefined
+payloads or nested payload/result-patch values are rejected. Events require non-empty
+event/subject identifiers, a payload, and an optional positive integer schema version;
+event types must be declared in `emitsEvents`. Host checks event and subject names against
+`eventContracts` when supplied for hook-returned events only; handler events are outside
+that option's scope. It checks name membership, without validating payload schemas or schema
+version compatibility. Host owns envelope identity, scope, actor and timestamps.
+Hook and handler events default `eventSchemaVersion` to `action.version` when omitted;
+an explicit event schema version is preserved.
+Handler events use `domain:<index>`, hook events use `finalize:<index>`, followed by
+`state:transition`. The result patch merges shallowly over the public handler data; keys
+in `eventResultFields` are rejected. For these actions `resultSchema` validates the merged
+result inside the final transaction.
+
+The final transaction locks and checks the running invocation before calling the hook.
+Hook, validation, event-append or completion-write failure rolls back finalizer domain
+writes, events, outbox and completion, then settles `reconciliation_required` through
+applied-effect settlement when durable provider effects exist. With zero steps or all steps
+skipped, it settles `failed` without claiming a provider effect. Error text uses Host error
+redaction. Lease loss rolls back and
+escapes without a stale-worker verdict. Failed, ambiguous, degraded and accepted/handoff
+outcomes do not call the hook.
+
+If transaction entry or COMMIT fails with an unknown outcome, Host raises
+`RecoverableFinalizationError` and records no verdict. An uncommitted invocation stays
+`running` for recovery; if COMMIT succeeded despite the error, its stored `completed`
+verdict and result remain intact and are returned on re-execution.
+
+**Durable preparation and recovery.** The handler transaction commits a JSON
+`finalizationCheckpoint` with protocol `atomic-after-adapters-v1`, action version, ordered
+adapter type/operation identities, normalized parameters and public handler data, handler
+events, public result, optional pending transition event and skipped indexes. Adapter inputs
+are excluded. Parameters derive from the already-redacted durable invocation input.
+Finalizing `getInput` callbacks receive copies of normalized parameters and public handler
+data on both paths; other actions retain raw inputs. Skip decisions are computed before
+preparation commits. Replay does not call `getInput` for recorded skips or succeeded rows.
+For an unstarted step, it recomputes input from the saved normalized values; callbacks must
+be deterministic for those values.
+
+On resumed running invocations or later attempts, a compatible checkpoint bypasses the
+handler, including for non-idempotent actions. Succeeded rows supply their stored redacted
+outputs; steps without rows can run because Host creates a running row before calling the
+provider. Recovery retains entitlement, authorization and policy checks. A refusal after
+an applied effect requires reconciliation. Finalization uses the same locked, lease-fenced
+success transaction as live execution. A completed invocation returns its stored result.
+
+Running or ambiguous adapter rows require reconciliation, before checkpoint compatibility
+checks. Protocol, action version or step count/order/type/operation changes refuse replay;
+retain compatible definitions while work is recoverable. Handoffs cannot replay a finalizer.
+Refusals reconcile when an effect exists or may exist, and fail when no effect is recorded.
+Missing checkpoints retain the previous recovery rules, including reconciliation after
+succeeded adapter evidence. Recovery-attempt budgets and deadline/capability refusals remain
+in force. A checkpoint bypasses non-idempotent interruption gates only when each recorded
+adapter row is succeeded; missing rows may start, but failed rows retain interruption
+settlement without another provider call. Failed rows do not prove the provider had no effect.
+Settlement fails without recorded success and reconciles when another step succeeded.
+For leased non-idempotent replay, both the store and mutation transaction must provide
+`writeAdapterInvocation` for lease-fenced adapter creation and updates. Without either
+capability the existing interruption gates remain in force. Idempotent finalizing actions
+retain failed-row retry through the adapter loop under existing retry rules, using saved
+preparation rather than rerunning the handler.
+
+On the live path, a finalizing action whose earlier adapter succeeded and whose later adapter
+returns a permanent failure settles `reconciliation_required`, rather than `failed`. The hook
+does not run. This also applies to subsequent execution failures after a recorded provider
+effect, so the terminal status preserves the need to reconcile partial progress.
+
+Canonical checkpoint JSON is limited to **256 KiB in UTF-8**, a conservative fixed bound on
+durable evidence and transaction size. Oversize or unserializable preparation fails before
+adapters and rolls back handler writes. Store entry/commit errors with unknown outcomes raise
+`RecoverableFinalizationError` without a terminal verdict. Checkpoint write failures roll
+back preparation, so adapters do not run.
+
+**Rollout:** apply PostgreSQL migration **10**, `finalization_preparation_checkpoint`, using
+`ensureSchema()` before deploying Hosts that write checkpoints. It adds nullable
+`action_invocations.finalization_checkpoint jsonb`. Updates without the checkpoint field do
+not name the column and remain usable on older schemas. Custom stores must persist the field
+atomically with handler writes and honor explicit `undefined` clearing. Memory storage follows
+the same patch semantics. The saved transition event preserves the original emission decision;
+`pendingStateTransition` alone cannot encode suppression by a handler-emitted transition.
+
+### Result validation
+
+Actions without a finalizer can optionally declare `resultSchema`. The Host validates public handler result data after
 the handler and before canonical event append or adapter execution. Invalid results fail the invocation,
 emit no domain/completion event, invoke no adapter, and persist only a sanitized validation failure.
 Domain writes roll back only when the configured store transaction provider includes those writes.
@@ -891,7 +1030,7 @@ must match the current state and invocation. Missing provenance leaves normal va
 custom stores can continue compiling without the optional method.
 
 After a valid transition for a binding with a non-empty entity ID and target, Host appends
-`StateTransitioned` immediately after the handler's domain events, following the action's
+`StateTransitioned` after the handler's domain events and any action-finalizer events, following the action's
 `eventPhase`. Its subject is the bound entity and its version-1 payload is
 `{ entityType, entityId, fromState, toState, causedByAction }`. `fromState` is the trusted state
 read before the handler, and `causedByAction` is the action ID. The event uses a stable
@@ -900,7 +1039,8 @@ can filter it. It does not need an `emitsEvents` declaration from the action.
 
 For `before_adapters`, the transition is appended with the handler's domain events. For
 `after_adapters`, it is deferred to finalization after required adapter steps succeed or
-accept a parked external handoff, immediately after domain events. Adapter failure withholds
+accept a parked external handoff, after domain events and any action-finalizer events.
+Actions with `finalize` reconcile accepted handoffs without calling the hook. Adapter failure withholds
 both domain events and the transition, leaving the built-in stores' ledger-derived entity state
 unchanged by that invocation even though handler writes may have committed. Custom stores that
 read domain rows can already observe the target state at this point. With `transactionWithEvents`, the