@fabricorg/platform-host 7.0.0 → 7.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @fabricorg/platform-host
 
+## 7.1.1
+
+### Patch Changes
+
+- 91f7d7e: A repeated completion was judged identical by outcome alone, so a second `completed` callback carrying a different result was absorbed as a replay and its evidence discarded. A recorded completion now carries a canonical digest of provider, reference, outcome, result, error, and evidence, with observation time left out because a redelivery carries a new one. A repeat with the same digest is absorbed; the same outcome with a different digest is a contradiction and is handled as one: reconciliation, the first outcome kept, the second logged, `ExternalOperationContradicted` emitted.
+
+## 7.1.0
+
+### Minor Changes
+
+- 4c358ad: The host now reads an action's `completion` mode. Before this the contract could declare `accepted` or `long-running` and nothing in the host behaved differently, so a render job, a financing decision, or an order acknowledgment that arrives by callback had nowhere to land except reconciliation.
+
+  An adapter that returns `acceptedExternalOperation` has its handoff persisted on the invocation the moment it is accepted, before the adapter step is marked done, so a worker that dies between the two leaves the handoff and not the marker; on re-execution the step is skipped and the handoff kept. Once finalized the invocation is `running` with no lease and a recorded `pendingCompletion`. The recovery worker does not claim it, a direct re-execution returns it as it stands, and an idempotent resubmission reports the pending completion. Domain events still go out at accept time, because the handler's writes committed.
+
+  `completeExternalInvocation` completes a parked invocation by external reference. Where the store is atomic, the read and write happen under one lock so two callbacks racing cannot both find nothing recorded. A reference the invocation is not waiting on is refused. A repeated identical completion is absorbed. A contradictory completion moves the invocation to `reconciliation_required`, keeps the first outcome on record, logs the second for reconciliation, and emits `ExternalOperationContradicted`. The callback's result is validated against the action's result schema and stripped of private fields. An invocation that ended for another reason while a handoff was pending, because a later step failed or a contract was violated, keeps its status and records the callback as evidence. A handoff under an `immediate` contract, or a second handoff in one invocation, is routed to reconciliation with the reference kept and a reconciliation row written, since the external effect is in flight; if the reconciliation log is unavailable the reference is still kept and the error says so. A callback that arrives before the invocation has parked, whether under a worker's lease, during an inline execution's remaining steps, or before a dispatched invocation runs, is refused rather than settling mid-execution; the handoff carries a `parkedAt` set at finalization and that is what the ingress checks. Refusals throw `ExternalCompletionError`, which carries a `refusal` code and a `retryable` flag; only `still_executing` is retryable and an unknown invocation is `not_found`, so a webhook handler maps refusals to responses without matching strings. Crash recovery between the durable handoff and the step marker replays the accept event by its stable id.
+
+  `reconcileOverdueCompletions` moves handoffs past their `completionDeadlineMs` to `reconciliation_required` while keeping the handoff, so a late completion can still land; the worker cycle runs the sweep before it claims, and a failure in the sweep is reported rather than stranding claimed work. `ListActionInvocationsInput` gains `awaitingCompletion`, `completionDueBefore`, and `unleased` so the sweep reads only what it needs; the sweep and the contradiction path refuse without a governance-capable store. `PostgresPlatformHostStore` gains migration 3 with the `pending_completion`, `external_completion`, and `completion_due_at` columns and a partial index on the due instant, verified against PostgreSQL 16. The worker accepts `sweepOverdueCompletions: false` for a store without the governance seam. Unsatisfied policy obligations after a handoff route to reconciliation rather than failure.
+
+  Disclosed as interface growth: `GovernedActionHost` gains two members, `completeExternalInvocation` and `reconcileOverdueCompletions`, which only the host implements in this repository. `PlatformHostStore.updateActionInvocation` and the transaction-scoped sibling accept the wider `ActionInvocationPatch`, which carries `pendingCompletion` and `externalCompletion`. A custom store has new obligations for those fields, documented on `ActionInvocationPatch` and in the README; a store that ignores them lets the worker re-run a handoff. The local certification suite gains an `accepted-completion-callback` case and its contract version moves to 3.
+
 ## 7.0.0
 
 ### Patch Changes

package/README.md

@@ -247,6 +247,59 @@ stores should expose transaction-scoped `getEntityState()` so the guard reads th
 snapshot used by the handler and event append. Existing custom stores without that optional
 transaction method fall back to the store-level authoritative read.
 
+## External completion
+
+An action declaring `completion: "accepted"` or `"long-running"` may hand its work to an external
+system. The adapter returns `acceptedExternalOperation: { externalReference }`; the Host parks the
+invocation as `running` with no lease, emits `ExternalOperationAccepted`, and leaves it for the
+external system to finish. The recovery worker never claims a parked invocation, and re-executing it
+returns it as it stands.
+
+```ts
+await host.completeExternalInvocation(actionInvocationId, tenantId, spaceId, {
+  externalReference: "vendor-op-123",
+  outcome: "completed",
+  result: { receipt: "r-1" },
+  observedAt: new Date(),
+});
+```
+
+Matching is by reference: a completion naming a reference the invocation is not waiting on is
+refused. A repeated identical completion is absorbed, identity being a digest of provider,
+reference, outcome, result, error, and evidence. A contradictory one, a flipped outcome or the same
+outcome with different evidence, moves the invocation to
+`reconciliation_required`, keeps the first outcome on record, logs the second, and emits
+`ExternalOperationContradicted`. Under an atomic store the read and write happen under one lock. The
+callback's result is validated against the action's result schema and stripped of private fields.
+An invocation that ended for another reason while a handoff was pending keeps its status and records
+the callback as evidence. Declare `completionDeadlineMs` on `long-running` actions;
+`reconcileOverdueCompletions()` moves overdue handoffs to reconciliation while keeping the handoff so
+a late completion can still land, and the worker cycle runs that sweep before it claims.
+
+The handoff is persisted the moment it is accepted, before the adapter step is marked done, so a
+worker that dies between the two leaves the handoff and not the marker. A custom store has four
+obligations here, documented on `ActionInvocationPatch`: a patch setting `pendingCompletion` with
+`status: "running"` parks the invocation and clears its lease; one setting it without a status keeps
+the lease; `pendingCompletion: undefined` clears it; and the claim query must never claim a running
+invocation without a lease. The recovery worker's guarantee of never re-running a handoff rests on
+those. A callback that arrives before the invocation has parked, whether a worker still holds the lease
+or an inline execution is still running the steps after the handoff, is refused with
+`ExternalCompletionError` whose `refusal` is `still_executing` and whose `retryable` is true, since
+settling mid-execution would report completion before the remaining steps ran; the handoff carries a
+`parkedAt` set at finalization, and that is what the ingress checks; every other refusal
+is permanent and typed the same way, so a webhook handler maps them to a retryable or a final
+response without matching strings. An expired lease a dead worker left behind refuses the same way
+until the claim loop reclaims the row; the overdue sweep also leaves leased rows alone, so both defer
+to the worker fleet and the health snapshot's expired-lease count is where a stalled fleet shows.
+The contradiction path and the overdue sweep refuse without a governance-capable store, and the
+worker's sweep can be turned off with `sweepOverdueCompletions: false` for such a store; a refused
+handoff keeps its reference on the invocation even when the reconciliation log is unavailable, and
+says so in its error. Unsatisfied policy obligations after a handoff route to reconciliation rather
+than failure, since a recovered handoff cannot attest what died with its worker. `PostgresPlatformHostStore`
+migration 3 adds the `pending_completion`, `external_completion`, and `completion_due_at` columns and
+a partial index on the due instant the overdue sweep uses; the due instant is a real column because a
+cast in an index expression is not immutable and PostgreSQL refuses it.
+
 ## Runtime observability and health
 
 Platform Host exposes vendor-neutral lifecycle telemetry through the optional `telemetry` sink on