@fabricorg/platform-host 8.3.0 → 8.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @fabricorg/platform-host
 
+## 8.5.0
+
+### Minor Changes
+
+- 08274e6: Add host-owned approval deadlines/expiry, bounded JSON decision evidence, and opt-in atomic approval lifecycle events. Evaluators can supply an absolute deadline, or Hosts can set a default TTL. Due decisions and bounded worker/operator sweeps settle `failed` with expiry evidence and no approval decision; store serialization prevents a concurrent decision or sweep from applying twice. No deadline preserves indefinite waits, and no new ActionStatus is introduced.
+
+  Decision evidence is limited to 16 KiB of plain JSON verification references, validated and copied before resume store access and authorization. Credentials and tokens must not be included. Approval requested/decided/expired events default off. Opting in requires transactional approval/outbox capabilities at Host creation; event/state write failures roll back together, parking failures surface for recovery, and event IDs remain stable on retry. Event payloads include evidence presence rather than the evidence object. PostgreSQL users must run ensureSchema to apply additive migration 12 for the nullable expiry columns and due-expiry index before deploying; migrations 1-11 retain their original SQL/checksums.
+
+  Built-in HITL checkpoints are first-write-wins, preventing a delayed evaluator from changing a parked deadline. Resume of an unavailable action fails an approval without a deadline, preserving the previous terminal behavior; an approval with a deadline stays waiting with an error so a sweep can record its expiry verdict. That `Unknown action` failure appends no approval lifecycle event. Host fails before parking if a custom store drops the evaluator-supplied deadline. Custom approval stores must atomically enforce deadline expiry in beginApprovalDecision and serialize decisions with sweeps.
+
+- 6002c61: Add the finalizing-action `ActionResult.adapterPreparation` channel and optional third
+  `AdapterStep.getInput` argument. The finalizing-action helper refuses returned preparation
+  without the Host's `adapterPreparationProtocol: "v1"` capability; actions returning none
+  retain their existing capability behavior. Non-finalizing actions returning preparation fail
+  before adapter delivery.
+
+  Preparation must be a strict-JSON plain-object record and counts toward the 256 KiB checkpoint
+  limit. It is persisted separately for crash replay, excluded from public results, handler data,
+  finalize input and event extraction, and removed with terminal settlement while retaining other
+  checkpoint evidence. Running and reconciliation-required invocations retain preparation.
+  Older checkpoints pass undefined to getInput. Derived adapter inputs remain subject to the
+  existing redactAdapterInput and adapter evidence retention contracts.
+
+  Preparation checkpoints use `atomic-after-adapters-v2`; checkpoints without preparation keep
+  `atomic-after-adapters-v1`. Replay accepts only the matching protocol/preparation shapes.
+  Settlement clears preparation and restores v1, including approval rejection. Handler capability
+  and manifest finalization protocols remain v1. Upgrade all workers before handlers return
+  preparation: older Hosts refuse in-flight v2 replay through interruption handling, requiring
+  reconciliation after recorded effects or settling failed without recorded effects. An older
+  Host does not clear preparation, so a row it settles keeps the v2 checkpoint and its
+  preparation; in PostgreSQL, find such rows by a terminal status with
+  `finalization_checkpoint->>'protocol' = 'atomic-after-adapters-v2'`. Reconcile in-flight v2
+  work before rolling workers back.
+
+## 8.4.0
+
+### Minor Changes
+
+- f1b6def: Add the parked action invocation ID and durable invocation record to `authorizeApproval` input so applications can authorize decisions for the specific proposal being resumed.
+
 ## 8.3.0
 
 ### Minor Changes

package/README.md

@@ -647,12 +647,46 @@ If transaction entry or COMMIT fails with an unknown outcome, Host raises
 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
+`finalizationCheckpoint` with protocol `atomic-after-adapters-v1` without preparation, or
+`atomic-after-adapters-v2` with preparation, plus 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
+Finalizing `getInput(params, handlerResult, adapterPreparation?)` callbacks receive copies of
+normalized parameters and public handler data on both paths. A handler can return a private
+strict-JSON plain-object `ActionResult.adapterPreparation` alongside `data`. The optional third
+argument receives a copy of that record (or `undefined`, including for older checkpoints).
+It is separate from public handler data, public results, `finalize` input, event payloads and
+`extractEvents` input. Only values the action explicitly derives into adapter inputs enter the
+existing adapter-row and success-event input evidence, governed by `redactAdapterInput`.
+
+Host validates the channel immediately after a successful handler returns, before staging,
+event extraction, or adapter preparation. Non-finalizing actions returning it fail before
+adapter delivery. Arrays, non-object records and lossy JSON values are rejected. Unlike public
+handler data, preparation does not normalize Dates or drop undefined values. It is saved under
+its own optional `finalizationCheckpoint.adapterPreparation` key and counts toward the 256 KiB
+checkpoint limit. Settlement rewrites the checkpoint without that key and restores protocol
+`atomic-after-adapters-v1`, preserving the remaining evidence:
+completion clears it in the success transaction, and terminal failure, policy/validation refusal
+or cancellation clears it with the status write. Running and `reconciliation_required`
+invocations retain it for recovery or reconciliation. This retention applies to the private
+checkpoint channel; derived adapter input evidence follows the existing retention contract.
+
+The Host advertises `ctx.adapterPreparationProtocol === "v1"` for finalizing handlers.
+`defineFinalizingAction` refuses a returned preparation record when that capability is absent,
+after the handler returns; its existing finalization capability check still runs before the
+handler. Returning no preparation preserves the earlier capability behavior.
+
+Replay accepts v1 only without the preparation key and v2 only with it. Other combinations
+use the existing interruption refusal path before adapter delivery. Older Hosts refuse v2
+checkpoints through that path: recorded effects require reconciliation; no recorded effect
+settles failed. An older Host does not clear preparation, so a row it settles keeps the v2
+checkpoint and its preparation; in PostgreSQL, find such rows by a terminal status with
+`finalization_checkpoint->>'protocol' = 'atomic-after-adapters-v2'`. Upgrade all workers before enabling handlers that return preparation, and
+reconcile in-flight v2 work if workers are rolled back. The handler capability and manifest
+finalization protocol remain `atomic-after-adapters-v1`; checkpoint versioning is separate.
+
+Other actions retain raw two-argument 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.
@@ -731,13 +765,16 @@ The evaluator returns `auto-execute`, `needs-approval`, `escalate`, or `rejected
 
 - `auto-execute` continues through policies, state validation, the handler, events, and adapters.
 - `needs-approval` and `escalate` persist the route and risk evidence, clear any worker lease, and park
-  the invocation as `waiting_for_approval`. Polling workers never claim that status.
+  the invocation as `waiting_for_approval`. The built-in polling stores exclude that status
+  from execution claims.
 - `rejected` terminally fails before policies and mutation code run.
 
 An approval workflow calls `resumeApprovedInvocation()` instead of invoking the handler directly. The
 host authorizes the approver (using `authorizeApproval` when provided), then atomically persists the
 decision and changes `waiting_for_approval` to either leased `running` or terminal `failed`. This keeps
 the decision in the mutation ledger and prevents an approval/worker race.
+`authorizeApproval` receives the parked `actionInvocationId` and durable, post-redaction `invocation`
+record so the application can verify the approver's authority over that specific invocation.
 
 ```ts
 await host.resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, {
@@ -753,6 +790,84 @@ Custom stores remain source-compatible when HITL is unused. To enable HITL they
 additive `ApprovalPlatformHostStore` capability. Both built-in stores implement it; Postgres users must
 call `ensureSchema()` so the HITL evidence and approval-decision columns are added.
 
+### Approval deadlines, evidence, and lifecycle events
+
+`HostHitlDecision.approvalExpiresAt` accepts an absolute, valid `Date`. Alternatively,
+`approvalDefaultTtlMs` supplies a positive safe integer of milliseconds from the successful
+park attempt. The evaluator's deadline takes precedence. With neither option, the wait has
+no deadline. An invalid deadline fails execution before parking; an invalid default TTL
+throws when constructing the Host. A deadline already due is permitted and expires on a
+sweep or decision attempt.
+
+`host.expireDueApprovals({ tenantId?, spaceId?, now?, limit? })` settles due approval waits.
+The default limit is 100, with valid limits from 1 to 1000. The worker calls it before claiming
+work and reports a positive count as `expiredApprovals`, separately from execution failures.
+The store compares the deadline to the transition's trusted `now`, including after approval
+authorization: `decidedAt` cannot backdate acceptance. At or after the deadline, a decision
+attempt settles expiry instead of recording that decision. Expiry uses `status: "failed"`,
+retains `approvalExpiresAt`, records `approvalExpiry: { expiresAt, expiredAt }`, and leaves
+`approvalDecision` absent. Rejections retain `approvalDecision.approved: false`. Repeated
+sweeps and racing decisions return only the transition each caller applied. Expiry emits
+ordinary failed-status telemetry. Saga coordination reads the child's terminal result and
+uses its existing parent failure/compensation path, as it does for rejection; the Host does
+not dispatch a saga signal itself.
+
+A custom approval store needs `parkApproval` and `expireDueApprovals` to enable deadlines;
+a Host requiring these capabilities fails the invocation before parking if they are missing.
+A store implementing `parkApproval`/`expireDueApprovals` must also enforce the stored deadline
+inside `beginApprovalDecision`: at or after it (`input.now >= approvalExpiresAt`), expire the row
+instead of applying the decision. Decisions and sweeps must serialize so each wait settles once;
+parking must check the lease and absence of a prior decision. Supplied lifecycle events/outbox
+writes must commit atomically with their state changes. Host refuses to park if
+`recordHitlDecision` drops a freshly evaluated deadline.
+Existing stores without these optional capabilities retain indefinite approval behavior.
+If an action definition is unavailable during resume, a wait without a deadline fails with
+`Unknown action`; a wait with a deadline stays waiting with that error so the sweep can expire it.
+That `Unknown action` failure is not an approval transition, so it appends no approval
+lifecycle event even when `approvalLifecycleEvents` is enabled: consumers tracking open approvals
+from these events should also close one when the invocation reaches a terminal status.
+HITL checkpoints are first-write-wins in the built-in stores, so a late evaluator cannot revise a
+parked deadline. Apply `PostgresPlatformHostStore.ensureSchema()` before deploying this feature:
+migration 12 (`approval_lifecycle_expiry`) adds nullable `approval_expires_at` and `approval_expiry`
+columns and a partial due-expiry index, preserving the SQL/checksums of migrations 1-11.
+
+An approval decision may include `evidence`, a plain JSON object containing verification
+references such as a binding ID, signature/verification reference, or receipt ID. Credentials
+and tokens must not be included. `MAX_APPROVAL_EVIDENCE_BYTES` exports the 16 KiB serialized
+UTF-8 limit. Host rejects non-JSON data, accessors, proxies, cycles, sparse arrays, non-finite
+numbers, nesting beyond 64 levels, and oversized objects with a thrown error at resume entry,
+before store reads or writes. It snapshots the decision before awaiting authorization and
+passes independent decision and invocation copies to `authorizeApproval`. Both stores retain
+evidence on `approvalDecision`; applications own the safety of its verification references.
+
+Set `approvalLifecycleEvents: true` to enable `APPROVAL_REQUESTED_EVENT` (`ApprovalRequested`),
+`APPROVAL_DECIDED_EVENT` (`ApprovalDecided`), and `APPROVAL_EXPIRED_EVENT` (`ApprovalExpired`).
+Their typed payloads are `ApprovalRequestedPayload`, `ApprovalDecidedPayload`, and
+`ApprovalExpiredPayload`. Request events contain route, risk tier, reason, and optional
+`expiresAt`; decision events contain approval outcome, approver identity/type, optional reason,
+`decidedAt`, and `evidencePresent`; expiry events contain `expiresAt` and `expiredAt`.
+Payload dates are ISO strings. Decision events do not copy the evidence object.
+
+The option defaults off. When enabled, Host construction requires `transactionalOutbox`,
+`transactionWithEvents`, and `transactionalApprovalLifecycle` plus the approval methods.
+Both built-in stores provide event atomicity when constructed with a transaction provider.
+A state transition and its lifecycle event/outbox row commit together; append or update
+failures roll them back. An expiry sweep commits its bounded batch as one unit, preventing
+a later append failure from hiding earlier transitions from the result or status telemetry.
+A parking transaction failure is surfaced for recovery without a
+terminal failure overwrite. Earlier execution-start and HITL checkpoints remain durable.
+Stable invocation-and-kind event IDs make transition retries first-write-wins. Event envelopes
+reuse Host's domain/lifecycle builder, including tenant, actor, correlation, causation,
+provenance, and declared consistency. The store allocates sequence inside the transaction.
+
+Approval lifecycle events explicitly enabled by this option go to the outbox even when
+`outbox.shouldPublish` excludes other Host lifecycle events. Existing classification,
+producer-version, trace, actor-disclosure, and provenance hooks apply when configured.
+Without `outbox` configuration, approval metadata uses `internal` classification, the action
+version string as producer version, provenance included, and actor disclosure excluded from
+the enterprise envelope. Configure those hooks before publishing approval reasons or approver
+identifiers outside the mutation ledger.
+
 Sensitive values must not be passed as action parameters. Stage them in tenant-bound encrypted storage
 and pass an opaque identifier instead; action parameters are intentionally durable audit evidence.
 Hosts should additionally configure `redactActionParameters` as a fail-safe allowlist for actions