@fabricorg/platform-host 7.6.0 → 8.1.0

package/CHANGELOG.md

@@ -1,5 +1,268 @@
 # @fabricorg/platform-host
 
+## 8.1.0
+
+### Minor Changes
+
+- e81defa: Add `eventAppendChecks()`, `runEventAppendChecks(subject)`, and their public subject, check,
+  and result types for custom store authors. Six checks exercise first-write-wins event appends
+  through plain, outbox and transaction paths, including buffered and committed duplicates and
+  plain-to-outbox behavior. Each check uses earlier and later duplicates with changed envelope and
+  metadata fields, including added map keys. Whole-record comparisons normalize key order, dates
+  and nulls; numeric strings are normalised only for `sequence`, `attemptCount` and `leaseToken`.
+  The first returned records supply snapshot references, allowing custom envelope fields and fields
+  the store omits or returns as null, including required fields. Transaction checks verify after commit
+  without requiring read-your-writes. Each committed-duplicate transaction also appends a fresh plain
+  control event after the duplicate and verifies its presence after commit to detect a silently
+  rolled-back unit of work.
+  Outbox snapshots cover pending, probe-leased, retry-pending and published rows, including lease
+  fields. Retry-pending accepts cleared or expired leases or the probe owner retained without an
+  expiry; a probe lease still live more than five seconds past the probe's clock reports a failure
+  to release it, and an expiry inside that margin is waited out as clock skew. Attempt counts and error formatting are
+  not prescribed. Retry and retirement availability use whole seconds a few seconds in the past,
+  tolerating coarse timestamp precision and small clock skew. Lease tokens come from claims, not
+  optional list views.
+  Absence checks require a fresh control outbox row.
+
+  These checks detect common first-write-wins violations: throwing, replacing or merging events,
+  keeping both events, selecting the earlier-ordered or later-ordered duplicate, adding outbox rows,
+  and resetting or rewriting an existing outbox row in the probed states. They are not exhaustive.
+  Known limits are rules comparing ordering fields in mixed directions, store-wide uniqueness across
+  spaces or tenants, the dead-letter state, and claims leasing foreign rows without returning them.
+  The checks also cannot detect a buffering transaction that merges fields the store never returns
+  (such as `includeProvenance`) from a buffered duplicate, or duplicate handling backed by an
+  in-process cache that works within one run but not across restarts. Stores requiring gapless
+  sequences, or unique keys over fields the control events share with the probe event, can fail
+  falsely.
+
+  Missing append capabilities skip; missing outbox verification or cleanup methods (including
+  `markOutboxPublished`) fail. Run in test or staging with outbox relays paused for the probe tenant.
+  Event timestamps use whole seconds slightly in the past; probes leave append-only events in dedicated
+  `event-append-probe` spaces. Successful outbox-creating checks mark the row published without
+  sending anything; final cleanup attempts to dead-letter visible pending control/failure rows.
+  Published exercises duplicate appends against that delivery state. Absence-control rows remain
+  dead-lettered; operator requeue tooling could publish them later, so exclude probe spaces from real
+  publication and requeue workflows.
+
+  Claims use real current time, a pending-probe-row limit and a 30-second lease. A filter-ignoring
+  claim can still lease foreign rows and make its own writes, such as incrementing attempts. The
+  checks write nothing to foreign rows and stop claiming for that run; later outbox checks fail as
+  skipped because of the earlier filter violation. Standalone checks stop claiming for that check.
+  After a filter violation, cleanup dead-letters only probe rows returned by that claim, using the
+  probe worker and claim tokens without further claims. The failure lists visible probe rows still
+  pending and instructs manual dead-lettering, including unreturned rows or failed retirements.
+  Leases lapse within the requested duration if the store honours it. Visible relay interference
+  fails with instructions to pause relays. These are additive exports; Host and shipped-store runtime behavior is unchanged.
+
+### Patch Changes
+
+- 1effb28: Document first-write-wins event appends for custom store authors. Host re-appends lifecycle events under stable IDs on retry and recovery, with a fresh sequence and timestamps and sometimes a different payload, so `appendEvent` and `appendEventWithOutbox` must treat an event ID the store already holds as a no-op that keeps the first event, without throwing, replacing or merging it. A store that refuses these appends can leave recovery unable to converge; custom stores that throw on a conflicting append need to change. The shipped memory and PostgreSQL stores already conform and enforce ID uniqueness across the whole store, not per tenant or space. `appendEventWithOutbox` for an ID already stored adds no outbox row, even when the first append had none, so `outbox.shouldPublish` should be deterministic for a given event ID. No runtime behavior changes.
+- 5af8a02: Lifecycle record ids no longer collide when their key is cut to length (issue #90).
+
+  Host derives event, attestation, reconciliation and policy-evaluation ids from a key that it sanitises and used to cut to 96 characters. Two keys that differed only after the cut used to get the same id, and since stores keep the first write for an existing id, the later record was dropped silently. The realistic case was a vendor `externalReference` long enough to cut off the outcome, which merged a second `ExternalOperationContradicted` event into the first.
+
+  A key longer than 96 characters after sanitising is now cut to 64 characters followed by `_` and a digest of the whole raw key, 97 characters in all. Being one character over the cap, it cannot equal the id of any key that fits. Ids whose key fits are byte-identical to earlier releases.
+
+  Upgrade note: only ids whose composed key exceeds 96 characters change. Getting there takes a long vendor-supplied value, such as an `externalReference` or external operation id, or an unusually long policy id, vendor, provider, operation name or custom invocation id. An invocation that is in flight across the upgrade and re-appends such a record during retry or recovery writes it under the new id, next to the one written before the upgrade.
+
+  Not changed: keys within the limit that differ only in characters outside `[A-Za-z0-9_-]` (for example policy ids `a.b` and `a/b`) still share an id. Changing that would alter almost every existing id, because host's own keys use `:` and policy ids conventionally use `.`.
+
+## 8.0.0
+
+### Major Changes
+
+- 8d87a36: Release note: failure semantics (issue #79)
+
+  Once any adapter step has a durable succeeded row or accepted handoff, subsequent Host store
+  read/write errors raise RecoverableFinalizationError instead of failing the invocation. This
+  includes later checkpoints, recovery-time store operations, obligation reads and final completion
+  in either event phase. Idempotent recovery repairs recorded evidence without repeating that
+  provider call. A later step's definite failure or pre-call refusal can still fail the invocation.
+  Authorization/handler failures, validation/state rejection and unsatisfied obligations on recovery
+  retain their existing outcomes. The handler still re-runs and saga compensation is unchanged.
+
+  Recovery reads checkpoints before input generation or adapter lookup, replays accepted/success
+  events by stable ID (`recovered: true` on newly repaired success events), reuses existing stable-ID
+  attestations, and reapplies their obligation updates. Missing attestations can be extracted again
+  from stored safe input/output and checkpoint timestamps. Extractors must be deterministic for the
+  same input. No stored output means no extraction, including lost-marker handoffs and withheld output.
+
+  With neither success marker nor handoff durable, Host retries the failed checkpoint write once.
+  A second failure selects existing degraded atomic finalization or a verdict-first fallback to
+  reconciliation_required. Fallback checkpoint/events are best effort; terminal verdicts can retain
+  evidence gaps and automatic recovery excludes them. If even the verdict cannot be written, Host
+  raises RecoverableFinalizationError and a running row remains eligible for idempotent replay under
+  its stable adapterInvocationId within the worker budget. Lease loss retains its fencing error.
+
+  The optional recoveryMaxAttempts is a positive integer. Its effective default is
+  max(5, retryableExecutionMaxAttempts); Infinity is rejected. An explicit recovery budget below the
+  governance retry cap is rejected. Both caps count the same worker claims. With default settings,
+  pre-policy deferrals exhaust on claim 5; recovery exhaustion settles on claim 6 before mutation work.
+  Adopters who raised the governance cap get a matching implicit recovery budget.
+
+  The plain budget verdict commits before evidence reads. Running rows without a matching handoff
+  settle ambiguous; older ambiguous rows enrich the verdict from recorded evidence. A durable handoff
+  takes precedence over its running row and is recorded as an applied effect with its external
+  reference in the message and supported reconciliation record. Failed resolution/reads leave the
+  plain verdict intact. Failed enrichment can retain gaps. Transition telemetry emits once when
+  status changes. Unwritable verdicts leave claims continuing without executing handlers or providers.
+
+  Inline/direct execution does not increment the counter. These callers can now receive an error
+  whose name is RecoverableFinalizationError where 7.x returned failed; the class is not exported.
+  An unleased invocation remains running and is not claimed by workers. Callers must re-run
+  executeInvocation themselves and cap their own retries. Approval acceptance sets the counter to
+  at least 1 without incrementing it on resume. Approval's temporary lease uses the existing budget:
+  equal is admitted, above settles reconciliation. Approval does not reset the budget. A worker dying
+  before the check consumes a claim without calling a provider there. Parked handoffs are unleased
+  and are not claimed. ADR 0003 records the bounded exception to recoverable finalization.
+
+  An empty-reference handoff refusal retains its specific error if its verdict cannot be saved and
+  does not mark the step succeeded through generic degraded handling.
+
+  Both inline and leased non-idempotent interruption gates inspect adapter checkpoints: running rows
+  without a matching handoff settle unknown. Succeeded rows and durable handoffs end reconciliation
+  because a provider effect was applied. No rows or only failed rows retain failure. Idempotent
+  recovery still replays definite failed rows when invocation failure persistence was interrupted.
+  Known limit: if a later step's attempt-preparation write keeps failing, its row stays `running`
+  although the provider was not called, and a non-idempotent action's next claim settles that step
+  as an unknown outcome. Public options only grow; no store method is added. Adapter-row lease
+  fencing and overdue-sweep/late-callback behavior are unchanged.
+
+- 4f56809: Fence adapter checkpoint creation and updates with the optional `writeAdapterInvocation` store
+  capability. Built-in stores atomically check the scoped parent lease or settled verdict and expected
+  adapter status; conditional writes cannot reset succeeded or ambiguous rows to running or failed.
+  Host captures execution credentials before reading live records. Lease/status refusal raises
+  `RecoverableFinalizationError`; changed verdict evidence is refused and reported through
+  `invocation.adapter_evidence_refused` telemetry. Memory transactions recheck at commit and
+  PostgreSQL locks the parent before updating or creating the child. Atomic finalizers require the
+  transaction-scoped capability when the store advertises it; callback writes use their transaction's
+  adapter-update seam. Parent enrichment joins the post-verdict evidence collector: a refusal is
+  reported through telemetry, a missing capability skips only enrichment, and a thrown error is raised
+  after the remaining evidence writes are attempted. Successful enrichment saves the parent error
+  and reconciliation outcome for replay. Verdict conditions carry `completionAdapterInvocationId`
+  and check the external-completion snapshot for that handoff row, preserving real callback output
+  even when its parent status/error
+  stays the same. Unrelated rows retain status/error and expected-row-status fencing. Isolation probes
+  retire their parent rows, and prepare-attempt lease refusals bypass provider retry/backoff.
+
+  This is part of the declared 8.0.0 major. No schema migration is added. Custom stores without the
+  capability remain compatible with unchecked adapter writes and a weaker stale-worker guarantee.
+  Inline guard reads and transactions apply only when the execution snapshot or patch carries a
+  handoff. Handoffs imported into running invocations by other writers are unsupported.
+  See MIGRATION-8.md.
+
+  Public API additions: `AdapterInvocationWriteCondition`, `AdapterInvocationPatch`,
+  `AdapterInvocationWriteInput`, and `UpdateSettledActionInvocationInput`;
+  optional `PlatformHostStore.writeAdapterInvocation` and `updateSettledActionInvocation`;
+  and optional `PlatformHostMutationTransaction.writeAdapterInvocation`.
+  `PlatformHostTelemetryEventName` gains `invocation.adapter_evidence_refused`, which requires
+  updates to exhaustive switches over that union. Subclasses customizing unchecked adapter writes
+  must also customize the checked write seam, or disable it and accept the weaker guarantee.
+
+- 438be3f: Release note: late completion semantics (issue #79).
+
+  Overdue sweeps retain the handoff and set optional
+  `pendingCompletion.overdueAt` with the reconciliation verdict. Callbacks for
+  parked running invocations can settle even past their deadline before the
+  sweep. From reconciliation, settlement requires parking and the marker or the
+  fallback below. Callbacks for unparked invocations already
+  `reconciliation_required` retain the verdict and record redacted provider
+  evidence without result-schema validation. Unparked `running` invocations
+  still refuse callbacks with `still_executing`. Any parked row without the
+  marker, including a 7.x row, retains the weaker `"did not complete by"`
+  error-substring compatibility path. PostgreSQL hydrates the marker as a Date
+  from existing JSONB; no migration changes are required.
+
+  Sweeps re-read eligibility under the transaction row lock where supported and
+  use transaction-scoped reconciliation evidence when available. Inline
+  post-handoff writes preserve the sweep verdict while committing independent
+  adapter evidence. Reaching parking records the handler result and `parkedAt`
+  while keeping status, error, and `overdueAt`. Successful `after_adapters`
+  finalization commits its deferred domain events; without a local handoff it
+  records the result/events without fabricating parking. Inline callers receive
+  the latest reconciliation record observed by the preserving writer, merged
+  with its evidence update, without another read or a stale attempt fallback.
+  Leased paths retain `RecoverableFinalizationError` on fencing failure.
+  Verdict-first fallbacks attempt evidence writes independently, including
+  accepted/succeeded/ambiguous events, governance reconciliation, the outer
+  refused-handoff reconciliation append, and adapter checkpoints. A failed write
+  does not skip later evidence; the first failure raises
+  `RecoverableFinalizationError` after the remaining attempts. This also replaces
+  post-success fallback error suppression. The verdict remains durable and failed
+  writes can leave terminal evidence gaps. Atomic finalization and its outer
+  logging behavior retain their existing semantics; sweep errors are preserved.
+  Stores without the transaction lock retain a read/write race; without transaction-scoped reconciliation appends,
+  evidence can survive a rolled-back verdict. Neither check cancels an adapter
+  already in flight or undoes previously committed domain writes. Custom stores
+  must preserve and reload the optional marker.
+
+  Refused handoffs now retain their provider reference in the step's succeeded
+  event, including when explicit output omits it. Capable transactions append
+  the refusal reconciliation record with that evidence; fallback writes attempt
+  it independently of the other evidence writes. The outer append uses the same
+  stable id. An event failure does not skip reconciliation or the adapter marker.
+
+  Inline callers should retry only before a handoff is durable: re-running
+  `executeInvocation()` on an unleased running handoff returns without resuming
+  (it first settles any step already recorded `ambiguous`).
+  If execution stopped before parking, callbacks refuse with `still_executing`
+  until a sweep. Declare `completionDeadlineMs` for actions that hand off, then
+  reconcile surfaced rows per the external-completion runbook.
+
+  Handoff-free inline writes skip the guard's extra read and transaction. The
+  sweep accepts null lease owners from custom stores. Custom transactions should
+  implement both invocation locking and reconciliation appends to avoid blocking
+  an outer append on the invocation lock. Upgrade hosts and workers together:
+  7.x sweeps omit the typed marker, and 7.x inline writers lack the new guard.
+
+- 8d87a36: Version 8 changes the meaning of some invocation statuses: outcomes Host cannot know, and Host's own write failures after a provider call, settle `reconciliation_required` where 7.x reported `failed`. The public API only grows. `MIGRATION-8.md` in the package lists what to check before upgrading.
+
+### Minor Changes
+
+- a205c48: Reconcile unknown adapter outcomes (issue #76). Platform's README describes the Host behavior; Platform runtime code is unchanged.
+
+  **Release note: failure semantics (issue #76).** Returned `timeout` outcomes, timeouts thrown from `adapter.execute` (including an aborted adapter deadline), contradictory results in either direction (`success: true` with a non-success outcome, or `success: false` with `outcome: "success"`), uninterpretable replies (non-objects, `null`, or arrays), getters that throw before Host interprets the reply, and unrecognised outcome strings such as `"timed_out"` now end `reconciliation_required` instead of `failed`, using the existing `adapter_outcome_ambiguous` kind and `AdapterInvocationAmbiguous` event payload and stable ID. Returned `ambiguous` outcomes use the same settlement path. These unknown outcomes are not retried by the retry helper. Governance stores receive `ExternalReconciliation` evidence even without provider `outcomeEvidence`, because a timed-out call may have applied its effect without returning an external reference.
+
+  Host detects a timeout thrown from `adapter.execute` from the adapter deadline's aborted signal or an error message matching `/timeout|deadline|timed?\s*out/i`. A definite rejection whose message matches therefore also routes to reconciliation; the matcher does not prove a provider timeout. Reverse contradictions are classified as ambiguous for retry and circuit-breaker accounting, rather than as success.
+
+  Host copies the reply's contract fields and other own enumerable fields into a plain object before interpretation, reading each top-level field once. A getter that throws during the copy takes the unreadable-reply path. Object replies retain Host's previous truthiness reading of `success`, including truthy non-boolean values from JavaScript adapters.
+
+  Unknown-outcome settlement uses `transactionWithEvents` when the transaction has `updateAdapterInvocation`, governance `appendExternalReconciliation` where applicable, and leased `updateLeasedActionInvocation` where required. Host commits the ambiguous checkpoint, stable ambiguity event, reconciliation record, and fenced terminal verdict together, in that write order. It retries the transaction once on a non-lease error; a second non-lease failure selects the verdict-first fallback. Lease loss raises `RecoverableFinalizationError` without retry or fallback.
+
+  The fallback writes `reconciliation_required` first through the existing verdict helper (one retry except on lease loss), then writes checkpoint, event, and reconciliation evidence. After the verdict commits, Host attempts each remaining evidence write (checkpoint, event, record), then surfaces the first error as `RecoverableFinalizationError`. This includes attempting the reconciliation record after an event-write failure and attempting both event and record when both checkpoint shapes fail. Evidence failure can leave a terminal evidence gap that recovery does not repair. If both verdict attempts fail, Host raises `RecoverableFinalizationError` without attempting an unfenced checkpoint. With the original action definition and step order available, recovery re-settles a saved ambiguous row before parked-handoff shortcuts, stale-action gates, authorization, or handler execution, for idempotent and non-idempotent actions. The pending-handoff shortcut retains its base condition (running with a pending handoff and no lease owner, without requiring `parkedAt`); its position after the new recorded-ambiguity check is the change. For a running invocation whose action resolves, `executeInvocation` reads each adapter step's row before the shortcut, stopping on recorded ambiguity or a failed read. A failed read surfaces `RecoverableFinalizationError`, where base 939bcad returned the parked result. If the action no longer resolves, the shortcut still returns the handoff before the unknown-action failure.
+
+  The optional `AdapterInvocationRecord.reconciliation` checkpoint preserves redacted reason, external reference, and the original event subject; the subject is excluded from the returned `AdapterReconciliationOutcome`. Recovery does not scan the space's event log. Legacy rows use the recorded error as message and reason, and default to the `AdapterInvocation` subject keyed by `adapterInvocationId`. Stable event and reconciliation IDs retain deduplication.
+
+  Ordinary adapter writes omit the migration 8 column. On checkpoint-write failure, fallback retries once without `reconciliation`, retaining legacy `status: "ambiguous"` plus `error`. Schemas without migration 8 still settle unknown outcomes, without the checkpoint metadata. Atomic PostgreSQL failures roll back before this legacy write runs outside the transaction. Apply migration 8 (`adapter_reconciliation_checkpoint`) through controlled `ensureSchema()` to retain metadata. Existing migration checksums are unchanged. Custom stores should persist the optional checkpoint through adapter create/update/read methods.
+
+  On a store without atomic support, if the verdict cannot be written at all, no durable write after the call succeeds (neither verdict nor checkpoint), as after a crash mid-call. Idempotent recovery may re-run a leftover running step under the same `adapterInvocationId` idempotency key. The same exposure applies if two atomic attempts roll back and the fallback verdict cannot be written. Non-idempotent recovery retains its stale-action gate without an ambiguous checkpoint. Before another provider attempt, Host resets a prior failed row to `running` and clears its old error.
+
+  Post-success Host write failures still end `failed`, as in 7.6.0, even though the provider succeeded. Accepted-handoff persistence and its `ExternalOperationAccepted` event, the succeeded marker, attestation extraction and recording, and `AdapterInvocationSucceeded` failures again write the adapter row `failed` and fail the invocation. Later execution returns that terminal verdict; lease loss retains its fencing error. If fencing refuses the failure verdict after the adapter row was saved as `failed`, idempotent recovery can re-run the step; this pre-existing 7.6.0 case remains for follow-up. A follow-up issue will cover these post-success failures. The existing 7.6.0 degraded-success paths for withheld output and refused handoffs retain their reconciliation semantics and documented re-call exposure when the verdict cannot be persisted. Final `after_adapters` domain-event/invocation completion retains its recovery path.
+
+  A deadline sweep followed by a late completion callback can settle `completed` when the `ambiguous` evidence of a later step was never written.
+
+  Circuit-open refusals, deadline expiry before execution (including between retry attempts), `prepareAttempt` store errors, returned `permanent_failure`, exhausted `transient_failure`, and exhausted non-timeout adapter throws retain `failed` and their existing event shapes. Adapters already express definite non-effects through `permanent_failure` and `transient_failure`; there is no new adapter-side definite-failure flag. `after_adapters` completion events remain withheld while reconciliation is required.
+
+### Patch Changes
+
+- 939bcad: Build packages with tsdown in place of tsup. Preserve the published ESM/CommonJS
+  entry paths, ES2022 target, declaration filenames, and raw external module
+  specifier spellings, including the existing Node built-in spellings.
+
+  Generated JavaScript, source-map contents, declaration formatting, and internal
+  chunk layout change. Comparison with the saved tsup build found unchanged named
+  runtime exports and public declaration signatures. Declaration maps remain
+  unpublished. Facade maps are no longer published for Platform's root, evidence,
+  and policies entries, or experience-runtime's contracts entry (both `.js.map`
+  and `.cjs.map`). Their new JavaScript output has no source-map URL comment.
+
+  CommonJS interop: 29 of 72 baseline CJS files expose an `__esModule` marker;
+  0 of 57 tsdown CJS files do. The compared package entries have no default runtime
+  export, and the emitted `.d.cts` files declare none. Typed consumers of the
+  unchanged declared exports are unaffected. For entries whose marker was removed,
+  an untyped CJS `import X from` compiled with a Babel-style default-interop helper
+  now yields the namespace instead of `undefined`.
+
 ## 7.6.0
 
 ### Minor Changes

package/MIGRATION-8.md

@@ -0,0 +1,247 @@
+# Migrating to @fabricorg/platform-host 8
+
+**Version 8 changes what some invocation statuses mean.** The public API only
+grows; no export is removed or renamed. But an invocation that 7.x recorded as
+`failed` may now end `reconciliation_required`, and code that reads `failed` as
+"the provider did nothing" has to handle the new outcome. That change in meaning
+is why this is a major release.
+
+## Unknown adapter outcomes settle `reconciliation_required` (issue #76)
+
+In 7.x, an adapter call whose outcome Host could not know ended `failed`. That
+covered a thrown timeout, a returned `timeout`, and a reply Host could not read.
+The provider may have acted, so a caller that retried on `failed` could repeat
+an SMS or a submission.
+
+From 8.0.0 these outcomes settle like a returned `ambiguous` always has:
+
+- the adapter row ends `ambiguous`;
+- Host appends an `AdapterInvocationAmbiguous` event and, on governance stores,
+  an `ExternalReconciliation` record;
+- the invocation ends `reconciliation_required` with `adapterReconciliation`.
+
+Refusals that made no call (circuit open, an expired deadline) and definite
+provider failures still end `failed`.
+
+### What to check
+
+- **Callers and retry logic.** Treat `reconciliation_required` as "a person or
+  a reconciliation job must establish what happened". Do not retry it the way
+  you retry `failed`.
+- **Status fences in your own store or domain code.** A fence that admits only
+  `completed` or `failed` as terminal statuses will refuse the new verdict, and
+  the invocation will stay `running` and be recovered again. Admit
+  `reconciliation_required`, at least when the invocation has an `ambiguous`
+  adapter row.
+- **PostgreSQL.** Run `ensureSchema()` to apply migration 8, which adds
+  `adapter_invocations.reconciliation`. Host still settles on a schema without
+  it, but stores less evidence.
+- **Custom stores.** Persist the optional
+  `AdapterInvocationRecord.reconciliation` field and accept it in
+  `updateAdapterInvocation` patches.
+
+## Truthful, bounded post-provider recovery (issue #79 part 1)
+
+In 7.x, a Host write could fail after the provider reported success and leave
+the invocation `failed`. Host 8 makes those errors recoverable once a success
+marker or handoff is durable. Host store reads and writes stay recoverable
+after that point in either event phase. This includes later checkpoints,
+obligation reads, and the final completion write. Idempotent recovery repairs
+the recorded step without calling its provider again. The handler still
+re-runs before the adapter loop.
+
+Non-idempotent recovery ends `reconciliation_required` instead of repairing
+the invocation. A durable handoff takes precedence over its running row. Host
+records it as an applied effect and keeps the external reference in the
+message. A governance store also receives that reference in its reconciliation
+record. A running row without a durable handoff is settled as unknown. A
+succeeded row ends `reconciliation_required` as an applied effect. No rows or
+only failed rows keep the existing interruption failure.
+
+If neither checkpoint is durable, Host retries the failed write once. A
+second failure selects degraded atomic finalization or a verdict-first
+fallback. The fallback attempts the succeeded marker and safe events
+independently, raising the first evidence error as
+`RecoverableFinalizationError` after the remaining writes are attempted. A
+terminal verdict can still have missing evidence. If the verdict cannot be
+saved, Host raises `RecoverableFinalizationError`. The row can remain
+running. An idempotent action can call the provider a second time for that
+unrecorded outcome. It can also call the provider again for a definite
+failed row whose invocation verdict was lost. An empty-reference handoff
+refusal keeps its specific message if its verdict write fails. That failure
+does not create a succeeded marker.
+
+The optional `recoveryMaxAttempts` must be a positive integer. Its effective
+default is `max(5, retryableExecutionMaxAttempts)`. Infinity is rejected. An
+explicit recovery budget below the governance retry cap is rejected too. Both
+settings count worker claims. The first execution claim counts as 1. With the
+default of 5, the first run and four recoveries can execute. The sixth claim
+settles `reconciliation_required` before the handler or adapters run.
+Transient governance deferrals reach their own default cap on claim 5 first.
+
+On exhaustion, Host writes a plain verdict before reading evidence. A readable
+running step without a handoff is settled as unknown. A recorded ambiguous row
+conditionally enriches the parent error and `adapterReconciliation` with its
+saved evidence; successful enrichment makes response and replay agree. A handoff is recorded as an
+applied effect instead. Failed reads leave the plain verdict already written
+standing. Enrichment refusal or a missing capability skips only that parent write;
+checkpoint, event and reconciliation evidence are still attempted. Store errors
+are raised after the remaining independent writes. If the verdict itself
+cannot be saved, later claims continue without running mutation code.
+
+Inline and direct execution do not increment the claim counter. Approval
+acceptance sets it to at least 1 without adding a claim on resume. Approval
+resume uses its temporary lease and the existing count. A count equal to the
+budget is admitted. A count above it settles reconciliation before the handler
+runs. Approval does not reset the budget. A worker dying before the check
+consumes a claim without calling a provider there. Parked handoffs have no
+lease and are not claimed by workers.
+
+Known limits remain. A later step's definite failure or pre-call refusal can
+still end `failed` after an earlier success. Authorization and ordinary
+handler failures on recovery keep their existing outcomes. Validation, state
+guards, and unsatisfied obligations also keep their terminal outcomes. These
+are not Host store errors. Saga compensation is unchanged.
+
+### What to check
+
+- **Worker budgets.** If you raised `retryableExecutionMaxAttempts`, the
+  implicit recovery budget now rises with it. An explicit
+  `recoveryMaxAttempts` must be at least that retry cap. Both settings use the
+  same claim counter. Recovery also bounds evidence and completion failures.
+- **Evidence extractors.** Return deterministic evidence for the same stored
+  input and output. Extraction can run again if the attestation was not saved.
+  Host reuses an existing stable-ID attestation and reapplies its obligation
+  updates. Missing output means extraction is skipped.
+- **Store and action definitions.** Retain adapter rows, stable IDs, safe
+  input/output, and the original step order. No new store method is required.
+  Terminal verdicts can need manual evidence repair. Recovery reads
+  checkpoints before input generation and adapter lookup.
+- **Callers.** Inline `submitAction()` without a dispatcher and direct
+  `executeInvocation()` can now throw where 7.x returned `failed`. Recognise
+  `name === "RecoverableFinalizationError"`. The class is not exported.
+  Without a lease, the invocation stays `running` and workers do not claim it.
+  Before a handoff is durable, re-run `executeInvocation()` yourself and cap
+  your own retries. Once a handoff is durable, re-running `executeInvocation()`
+  on the unleased running row returns without resuming execution (it first
+  settles any step already recorded `ambiguous`). If execution
+  stopped before parking, callbacks are refused with `still_executing` until a
+  sweep. Declare `completionDeadlineMs` for actions that hand off so the sweep
+  surfaces the row, then reconcile it per the
+  [external-completion runbook](../../docs/operations/runbooks.md#overdue-handoffs).
+  The worker budget does not bound unleased calls. A previously leased call can be
+  reclaimed after lease expiry. Handle terminal `reconciliation_required`
+  separately. Do not blindly resubmit an applied effect under a new key.
+
+## Late completion requires a parked, swept handoff (issue #79 part 3)
+
+In 7.x, any reconciliation error containing `"did not complete by"` could let a
+late callback settle an invocation, even if execution had stopped before parking.
+From 8.0.0, the sweep writes optional `pendingCompletion.overdueAt` alongside its
+verdict. Settlement from reconciliation requires `parkedAt` and that marker,
+subject to the markerless fallback below. Callbacks for unparked invocations
+already `reconciliation_required` record their redacted result/outcome as
+evidence without result-schema validation and retain the existing verdict.
+Callbacks for unparked `running` invocations are still refused with
+`still_executing`.
+
+Any parked row without the marker, including a 7.x row, still matches the old
+substring. This path is weaker because unrelated error text on such a row can
+also match.
+
+### What to check
+
+- **Operators and callbacks.** A provider's completion does not establish that
+  an unparked invocation finished its remaining steps. Inspect its callback
+  evidence and reconcile that work explicitly.
+- **Custom stores.** Preserve and hydrate optional `overdueAt` as a Date. No
+  PostgreSQL migration is needed for this JSONB member. Transaction-scoped
+  `getActionInvocationForUpdate` serializes the sweep's eligibility check with
+  the verdict; `appendExternalReconciliation` puts its evidence in the same
+  transaction. Without those capabilities, a read/write race or an evidence gap
+  remains; see the README.
+- **Inline callers.** Independent adapter evidence commits without replacing
+  the sweep verdict. Reaching parking records the handler result and `parkedAt`
+  while retaining the sweep's status, error and `overdueAt`. Successful
+  `after_adapters` finalization commits its deferred domain events.
+  Inline entry points return the latest record observed by the preserving
+  writer, merged with its evidence update, after these writes succeed. No
+  post-attempt read or stale attempt fallback is used. Leased paths retain
+  `RecoverableFinalizationError` on fencing failure. In-flight adapters and
+  earlier domain writes are not undone; stores without a transaction lock
+  retain a read/write race. Evidence writes retain their existing retry and
+  error handling.
+- **Mixed-version deployments.** Upgrade all inline hosts and workers together.
+  A 7.x sweep writes no `overdueAt`. An 8.x inline execution that was still
+  unparked under that verdict records its result but does not add `parkedAt`;
+  its callbacks stay evidence-only. A 7.x inline host can still overwrite an
+  8.x sweep verdict because it lacks the new write guard.
+
+## Lease-checked adapter rows (issue #79 part 2)
+
+Implement the optional `writeAdapterInvocation` on custom stores to
+atomically authorize adapter creates and updates against their scoped
+parent. Support both running owner/token lease conditions and exact settled
+status/error conditions, plus expected row statuses. Host captures the handoff
+row ID in `completionAdapterInvocationId`; only that row also checks
+`externalCompletionDigest` (absence requires no recorded completion; a supplied
+digest requires that same completion). A callback can retain status/error while
+changing completion and the handoff row's output. Unrelated adapter rows still
+use status/error and expected-row-status fencing, so their ambiguity evidence
+can be recorded after that callback. Omitting the captured row ID retains the
+conservative completion check on adapter writes. Reject conditional
+`succeeded`/`ambiguous` to `running`/`failed` transitions even without an
+expected-status list. Lock the parent before the adapter in PostgreSQL; an
+unlocked `EXISTS` is insufficient against concurrent claims under READ
+COMMITTED. Buffered memory implementations must recheck at commit. Expose
+the same method on mutation transactions to retain atomic leased
+finalization; otherwise Host chooses the verdict-first fallback before
+evidence writes.
+
+Built-in stores implement this without a new migration. Host captures
+execution credentials and uses conditional writes for leased checkpoints and
+post-verdict evidence. Lease/status refusal raises
+`RecoverableFinalizationError`; post-verdict refusal leaves the adapter row
+untouched and emits `invocation.adapter_evidence_refused` telemetry. Host
+still attempts ambiguity and reconciliation evidence, and
+withheld-output/refused-handoff success evidence may already have been
+appended. Callback adapter writes share the callback's transaction when its
+adapter-update member exists. A post-verdict refusal is not an
+evidence-collector error. Thrown store errors are raised after every
+independent fallback evidence write has been attempted, preserving the first
+error.
+
+A preserving inline write never adopts the sweep verdict as this execution's
+own. Its adapter evidence keeps the unchecked inline path, and
+settled-parent enrichment applies only to a verdict the execution wrote. The
+inline guard reads the current row only when the execution snapshot or its patch
+carries `pendingCompletion`. Handoffs written into running invocations by anything
+other than their executing step are not supported.
+
+Stores omitting the capability remain compatible and keep unchecked adapter
+writes, including the risk that a stale worker overwrites a newer
+checkpoint. After its own verdict, an inline execution uses verdict-conditioned
+adapter writes too; earlier unleased writes retain their existing path. Implement
+optional `updateSettledActionInvocation` to enrich a settled parent under the
+full status/error/completion snapshot condition, regardless of adapter row ID.
+The two optional methods are expected together. Without the parent-update method,
+only parent enrichment is skipped; adapter checkpoints, events and reconciliation
+evidence are still attempted. Refused enrichment emits
+`invocation.adapter_evidence_refused` with `evidence: "parent_enrichment"` and is not
+an error. A thrown enrichment error joins the evidence collector, which raises
+the first error after the remaining writes are attempted. Successful enrichment
+stores the budget error and `adapterReconciliation` before returning them;
+skipped or refused enrichment can leave replay with only the plain verdict.
+
+### Built-in store subclasses
+
+A subclass overriding `createAdapterInvocation` or `updateAdapterInvocation`
+to encrypt or audit adapter data must also override
+`writeAdapterInvocation`: checked writes can bypass the unchecked methods.
+Disabling the capability preserves those overrides and accepts weaker
+stale-worker protection. Parent annotations use
+`updateSettledActionInvocation`; override that seam too when customizing
+parent evidence persistence.
+
+`PlatformHostTelemetryEventName` adds `invocation.adapter_evidence_refused`.
+Update exhaustive switches over this union when upgrading.