@fabricorg/platform-host 8.7.0 → 8.9.0

package/CHANGELOG.md

@@ -1,5 +1,332 @@
 # @fabricorg/platform-host
 
+## 8.9.0
+
+### Minor Changes
+
+- 7cb17c9: Add `RetryableHandlerError` and cross-copy recognition, plus optional confirmed rollback
+  retry inside one Host execution attempt. The default budget is three total tries (1–10).
+  Host requires a handler-call throw, identical-cause `ConfirmedTransactionRollback`, no adapter
+  or handoff evidence, fresh durable-derived inputs and transaction-scoped ownership fencing.
+  Policy evaluations, obligations, approvals and worker claim counts are retained; exhaustion
+  settles the last handler error through the existing redactor and statuses. Governance
+  `RetryableExecutionError`, returned failures and non-handler callback/commit errors retain
+  their existing failure semantics.
+
+  Expose `handlerRetry` classification, bounded jitter/delay and retry notification options,
+  and `isTransientPostgresTransactionError` for candidate SQLSTATE classification. Application
+  transaction providers can opt into rollback confirmation after successful rollback of a failed
+  callback. Built-in stores expose evidence for Host's internal handler callback request and
+  preserve prior error contracts for ordinary application transactions, approval, erasure and
+  other Host APIs, including callback-error identity and erasure's SQLSTATE mappings. Memory confirms after a configured provider's successful snapshot/restore
+  and ledger undo; commit failures and providerless internal transactions are not confirmed.
+  Custom stores exposing confirmation from their public transaction API remain supported through
+  normalization at non-handler Host and conformance boundaries. Retried callbacks must keep
+  effects inside the supplied transaction.
+
+  Retry observers run without awaiting them; synchronous throws and asynchronous rejections
+  are ignored. Memory rollback failures cannot authorize handler retry.
+
+- be0938a: Export runner-independent Host store conformance suites: `stagedInvocationChecks`,
+  `runStagedInvocationChecks`, `outboxRequeueChecks`, `runOutboxRequeueChecks`,
+  `approvalChecks`, and `runApprovalChecks`, with their subject, check, and result types.
+  The destructive probes cover staged lease fencing and dispatch, operator outbox
+  requeue, and recorded and inline approval behavior on isolated test stores.
+- db6ca3b: Export runner-independent `outboxRelayChecks` / `runOutboxRelayChecks` and
+  `invocationIdempotencyChecks` / `runInvocationIdempotencyChecks`, with subject,
+  check and result types. The destructive isolated-store probes pin shared relay
+  claim/settlement/renewal fences and first-row-wins invocation key arbitration,
+  including admission timestamp retention and optional refusal/admitted winners.
+  Document these store contracts without changing store signatures or conflict
+  classification, and leave claim result ordering unspecified.
+
+  The relay checks require numeric lease tokens that increase on each claim,
+  including reclaim, despite optional token fields in the general interfaces.
+  Use per-run future base times for relay and requeue probes so wall-clock
+  settlement guards can refuse expired leases, and set future relay availability
+  through retry settlement without requiring it to equal event recording time.
+
+- d09f378: Add optional `ErasablePlatformHostStore`, the separate `StoredRecordErasureHost` operator
+  and `createStoredRecordErasureHost`, plus erasure conformance checks. Built-in stores
+  atomically redact settled invocation/event copies, record scoped markers and append
+  sequenced `HostRecordsErased` evidence. Mixed batches can erase settled targets and report
+  active/missing ones. Invalid redactors roll the batch back; repeats process stored redacted
+  data again. Explicit structure paths protect Host state and identity while application
+  values, including reserved-looking keys in policy facts and metadata, remain visible.
+
+  Erasure requests require trusted `actorId` and `actorType`. `validateErasureInput` rejects
+  blank actor fields and NUL/lone-surrogate characters in `actorId`, and checks `actorType`
+  with Platform's `isActorType`. `createStoredRecordErasureHost(store, authorization)`
+  requires the authorization object; the integrated Host passes its own. The operator awaits
+  `authorization.authorizeStoredRecordErasure` after validation and before the store call,
+  preserving class receivers and doing no preceding record read. The hook receives exactly
+  actor ID/type, tenant, space, request ID and detached validated targets, without `redact`
+  or stored payloads. The strict `authorized !== true` guard refuses absent hooks and
+  non-`true` results with exported `StoredRecordErasureAuthorizationError`
+  (`refusal: "not_authorized"`). The missing-hook message differs from the actor-denied
+  message; neither discloses target existence. A thrown hook error propagates unchanged
+  before store access, distinguishing a failed check from a denial. Validation errors
+  and `ErasureBusyError` remain distinct. Both stores retain the actor in the
+  `HostRecordsErased` envelope as identifying metadata outside the redaction view.
+  The conformance kit's success probes require exactly one scoped `HostRecordsErased` event
+  with the request's actor ID/type, rejecting stores that omit or misattribute the audit.
+  The store capability remains an unauthenticated persistence port, not an authorization
+  boundary; direct callers enforce authorization themselves. This revises the unreleased
+  erasure API rather than preserving its unauthenticated factory signature.
+
+  Event targets cover canonical and delivery/requeue records. They do not erase copies in
+  invocation checkpoints/results because checkpoint events lack event IDs. Use invocation
+  targets for those copies. Erasure is the supported exception to append-only event payload
+  storage; normal append retains first-write-wins behavior, identity, sequence and order.
+
+  PostgreSQL erasure requires a transaction provider running READ COMMITTED; it checks
+  `SHOW transaction_isolation` and refuses other levels. Ordinary writers at stricter
+  isolation levels may receive a serialization failure instead of an erased outcome.
+  Apply migration 16, upgrade **all Host instances sharing the database**, then enable
+  erasure. Older Host SQL and direct application SQL bypass these guards and are unsupported
+  once erasure is enabled. Migration 16 adds metadata columns, markers and erasure-lookup
+  indexes without triggers or write-path functions. Like migrations 1–15 it runs in the
+  migration runner's transaction and takes table DDL locks; ordinary index builds block
+  writes for their duration on large tables. Plan an appropriate maintenance window.
+
+  `eraseStoredRecords` processes sorted targets inside individual savepoints. An invocation
+  target locks its invocation and dependent adapter, governance, staged parent/child, event,
+  outbox and requeue rows. It also locks the stage identified by the child's stored
+  `staged_parent_invocation_id` and `staged_stage_key`, even before that stage has recorded
+  its child ID. A pending or leased origin stage keeps the child active; a settled origin
+  stage is redacted with the child. This follows the stage, not the parent invocation's
+  payloads or other stages; target the parent separately for its checkpoint copies. An event target locks its event and delivery/requeue rows, without
+  locking its invocation owner or sibling rows. Canonical delivery copies are found by event
+  ID. Legacy outbox-only rows with null owner columns are found through the indexed envelope
+  `actionInvocationId`; new inserts populate the owner column explicitly. No advisory lock
+  is taken by erasure. The migration runner retains its separate schema advisory lock.
+
+  The first existing target lock may wait within `lockTimeoutMs` (default 250 ms, including
+  provider acquisition). While retaining target locks, subsequent row locks, including the
+  final tenant/space sequence-row lock, use `NOWAIT`; contention rolls back with
+  `ErasureBusyError`. The audit allocation and insert are the final SQL statements before
+  provider commit. Before opening that transaction, a separate provider transaction commits
+  an `event_sequences` row with `next_sequence=0` using `ON CONFLICT DO NOTHING`. It takes no
+  target locks. It attempts the insert only when it sees no committed row for the tenant and
+  space, so it can wait, within the acquisition budget, only for another transaction's
+  uncommitted first insert of that row. The zero seed consumes no event
+  sequence: the first allocation returns 1. The erasure transaction then locks the existing
+  row with `NOWAIT`; it does not try to insert a missing sequence row while holding targets.
+  The seed can remain after a refused or rolled-back erasure without consuming a sequence.
+  Steady event appends in the same tenant and space can starve erasure: it can repeatedly
+  report busy on this final nonwaiting lock. Each retry repeats callbacks and rewrites before
+  attempting that lock; busy rolls those rewrites back.
+
+  Dependent rows are locked before settlement and callbacks. A claim/renewal committed before
+  those locks is observed. Active/missing targets roll back to their savepoints, releasing
+  locks acquired for that target before processing the next. Locks retained from an earlier
+  overlapping accepted target stay held. Invocation settlement is evaluated on locked rows.
+  For an event-only target the owner's status, stages and sibling leases are observed after
+  the event closure is locked, but are not themselves locked. A concurrent change to that
+  owner/sibling activity can therefore race that observation. Target the invocation when
+  settlement of its complete closure must be serialized.
+
+  Ordinary invocation updates predicate on their own `records_erased_at`. Existing dependent
+  updates use their row stamp; insertion paths without a proven transaction-held owner lock
+  use a materialized owner read with `FOR KEY SHARE` inside the insertion statement. Host's
+  ordinary owner locks change from the released version's `FOR UPDATE` to `FOR NO KEY UPDATE`. Transaction-held owner reads are reused
+  for event and reconciliation insertion. Staged creation fences parent and initial child;
+  dispatch/failure attachment fences the newly attached child. An erased child cannot acquire
+  a stage containing old parameters through these methods. Host terminally rejects an
+  unsettled stage if an older/custom store nevertheless returns an erased child by origin,
+  so the attachment refusal cannot keep that stage retrying indefinitely. Replay conflict updates preserve
+  the stored row, and event reappend remains first-write-wins.
+
+  Outbox, stage and invocation claims lock actual candidate rows with `SKIP LOCKED`, without
+  a blocking parent lock. Stage cancellation also selects candidates with `SKIP LOCKED`; transactional approval
+  expiry uses the optional `lockDueApprovals` transaction member for that selection. Delivery of erased outbox records remains usable: claims,
+  renewals, publish/fail acknowledgement and requeue use stored redacted envelopes; failure
+  withholds supplied error text and requeue withholds supplied reason text while retaining
+  stored prior errors. The optional `renewOutboxLeaseAndRead` capability returns the stored
+  envelope atomically with renewal. Relays use that envelope and reject expired responses;
+  custom stores retain the boolean `renewOutboxLease` API. A custom store implementing
+  erasure without optional renew-and-read keeps a window in which the relay can publish an
+  envelope claimed before erasure.
+
+  These row acquisitions keep erasure from waiting on an ordinary row writer while retaining
+  its earlier target locks; it cannot supply the waiting edge of such a row-lock deadlock
+  cycle. They do not promise freedom from indirect waits in arbitrary application transactions,
+  DDL interference, writer-configured timeouts or external transaction-provider behavior.
+  Memory mirrors erased outcomes using its transaction queue and synchronous commit; it does
+  not provide PostgreSQL's row-level lock footprint.
+
+  Indexed selection, callbacks, rewrites and audit work use `workTimeoutMs` (default 5000 ms).
+  Remaining-budget checks and PostgreSQL statement/idle-transaction timeouts bound SQL and idle
+  lock retention. Neither budget preempts synchronous JavaScript or promises a hard real-time
+  network deadline. Timeout options accept integer milliseconds from 1 to 60000. Providers
+  should commit promptly, preserve original rollback errors and discard failed connections.
+  Ordinary query timeouts retain their PostgreSQL identity; database-caused `ErasureBusyError`
+  retains its cause.
+
+  Callers that do not use erasure still pay for the guarded paths. Owned inserts outside a
+  supplied mutation transaction take `FOR KEY SHARE` on the owning invocation row. Host adds
+  one locking invocation read per transactional event append (`src/host.ts`, `appendEvent`),
+  and built-in relays add one renew-and-read round trip per claimed record. A zero-row payload
+  write that classifies erasure adds a classification `SELECT`, including retried owned
+  duplicate event appends. Conditional boolean/lease writes and ownerless duplicate events
+  do not need that classification query.
+
+  Local PostgreSQL 16.15 measurements of invocation/adapter inserts and updates observed
+  approximately +0.05 to +1.6 ms per write, with one 64-KiB adapter-update sample at -0.08 ms.
+  The two-client, 600-update case took 842.6 ms baseline and 1135.1 ms with store guards,
+  about 35% longer. These compare current store paths with representative migration 1–15
+  SQL, including local transport, commit, serialization and hydration; they do not isolate
+  lock cost or predict application/cloud latency. Event/outbox write paths and lookup plans
+  were not re-measured. Erasure latency is outside these write measurements. Reproduce with
+  `FABRIC_ERASURE_MEASURE=1 pnpm test:postgres`; see `tests/erasure-measurements.ts`,
+  `measureErasure`.
+
+  Erasure removes the invocation `parameterDigest` (SQL `NULL`, including
+  `submission_refused` rows). Store-owned rewrites replace
+  `authorizationBinding.parameterDigest`, `externalCompletion.digest` and the
+  `parameterDigest` of rewritten stage rows with exported `ERASED_DIGEST = "erased"`.
+  The sentinel is outside the 64-hex SHA-256 output space and preserves required string
+  fields and the stage column's `NOT NULL` constraint. `ERASURE_PROTECTED_PATHS` keeps
+  these nested fields out of the callback view and rejects their insertion;
+  `redactStoredFields` overwrites them after merging protected structure. The stores
+  remove or replace top-level digests in the row rewrite, alongside its erasure stamp.
+  Repeating erasure leaves these digest fields absent or set to the same sentinel.
+
+  Private proposal/event comparison columns, memory maps and equality ports are removed.
+  Migration 16 is edited in place because it has not been published; migrations 1–15
+  retain their SQL. `packages/platform-host/tests/erasure-digest-cases.ts` checks raw records in both stores,
+  including repeat erasure, and `erasureChecks` checks the four digest outcomes.
+
+  Host keyed resubmission and recorded-refusal paths evaluate retained actor, binding ID
+  and action-version conflicts first. An enforce-mode conflict raises
+  `IdempotencyConflictError`; otherwise an erased row raises `StoredRecordsErasedError`,
+  including in audit-only mode, before the legacy callback or redacted-result return.
+  A caller that is itself refused while the key holds an erased row is handled separately:
+  against an erased recorded refusal, a retained-identity conflict leaves the caller's own
+  refusal in place and a matching identity raises `StoredRecordsErasedError`; an erased row
+  of any other status leaves the caller's own refusal in place.
+  `createDurableSagaParentLifecycle` preserves its event-type conflict check, then refuses
+  an erased prior event before comparing payloads. Erasure-capable custom stores expose
+  `storedRecordsErased` on the mutation transaction's `getEvent` result.
+  Store batch-replay paths refuse erased stage rows before digest comparisons, including
+  an origin stage erased with its child before child-ID attachment.
+  `packages/platform-host/tests/erasure-digest-cases.ts` pins same/different payload refusals and unchanged events.
+
+  Host overwrites only the digests it computes itself. A hash that another package or the
+  application places inside stored evidence is shown to the redactor and is kept unless the
+  redactor removes it. `@fabricorg/policy-opa` stores one by default: `inputHash`, a SHA-256
+  of the policy input, in the policy outcome's engine metadata. Remove it in the redactor
+  when the policy input can contain erased values, or configure the evaluator's `hashInput`.
+
+  The staged `batchDigest` formula now covers parent ID and sorted keys, actions,
+  versions and optional principals, excluding parameters and parameter digests.
+  Migration 16 replaces persisted `batch_digest` values with `LEGACY_BATCH_DIGEST`.
+  Custom `PlatformHostStore` implementations persisting stages should overwrite stored
+  batch digests with that placeholder and skip only the batch-digest comparison for
+  those rows; the remaining request identity and batch-size comparisons still apply.
+  `stagedInvocationRequestMatches` and `LEGACY_BATCH_DIGEST` are exported from
+  `@fabricorg/platform-host` for this comparison.
+  During a rolling upgrade, an old Host can write payload-covering digests after the
+  migration runs. Finish the rollout before relying on this guarantee, and replace
+  any such late-written digests with the placeholder.
+  Erasure replaces external reconciliation IDs with fresh random `rec_` IDs, including
+  on repeated erasure, following the existing reapplication of the redactor.
+  See `packages/platform-host/tests/erasure-digests.test.ts` and
+  `packages/platform-host/tests/staged-invocations.test.ts` for regression coverage.
+
+  Application hashes outside the protected Host paths remain visible to the redactor.
+
+  An older Host reading the missing invocation digest treats the erased row as a legacy
+  record and can accept a changed request under its existing key. This is an additional
+  reason to upgrade Host instances sharing storage before the first erasure; older writers
+  also bypass the erasure guards.
+
+  Store SQL guards fence later writes with typed `StoredRecordsErasedError`. Conditional settled and
+  adapter evidence writes return `false` in both stores. Late approval recording retains its
+  normal outcome without writing attempt evidence for an erased invocation.
+  `ExternalCompletionRefusal` gains `erased`; exhaustive switches must handle it. External
+  completion refuses before supplied payload access. Requeue retains redacted prior errors
+  and withholds fresh reason text; late publisher error text is discarded. Existing custom
+  base stores keep compiling; unsupported erasure checks report skipped.
+
+  Applications authorize operator calls and supply pure synchronous redactors. Payloads
+  handed off before commit cannot be recalled. Backups, downstream systems and application
+  data require separate erasure procedures.
+
+- 0d4204e: Add the separate `ApprovalDecisionRecordingHost.recordApprovalDecision` capability for HTTP
+  approval endpoints. Approved decisions commit to pending without executing handlers or adapters;
+  denials retain failed settlement. Scoped locked classification and optional events/outbox writes
+  commit together. PostgreSQL requires a transaction provider, with no non-atomic fallback.
+
+  Persist caller-stable request ids and recording attempt counts in decision JSON. Matching applied
+  retries preserve their original verdict after worker execution; contradictory verdicts or approvers
+  are already decided. The first post-approval claim uses approval_resume, excludes the earlier
+  parking count from that run's recovery budget and permits the approved non-idempotent first run.
+  Later claims compare their absolute attempt count to recoveryMaxAttempts, without subtraction,
+  and keep recovery checks and attempt history. Computed approval-resume executions retain
+  leased governance retry behavior; the existing inline resume override is unchanged.
+
+  Add opt-in ApprovalDecisionRefused events with invocation identity plus a SHA-256 digest of the
+  exact request id (digestParameters), preserving punctuation through lifecycleId sanitization.
+  Store event-id deduplication retains a refused request's first event. The factory runs after any
+  update with the pre-patch row; payloads carry scoped late approver identity without reason,
+  evidence or parameters. Non-applied outcomes omit the stored decision from the API result.
+  For different request ids, authorization refusal precedes existing-decision classification.
+  Previously expired rows with approvalExpiry and no decision return expired without another patch,
+  including authorized late retries and rows expired by a sweep; these remain replayed: false.
+  An unresolved waiting action returns unsupported without changing the row, with or without a
+  deadline. It skips approval authorization because the invocation remains unchanged; inline resume
+  retains its unknown-action settlement. After commit, an applied denial or expiry emits
+  invocation.failed telemetry. Recording stores return an applied flag so replays and unchanged
+  rows do not emit that transition again. Approval queues pending without a recording-time status
+  event; execution telemetry starts when the worker executes it. Keep inline resume and handwritten-host
+  compatibility. Saga-parent approvals are unsupported. Authorization still runs before the store
+  transaction (#141). Upgrade workers before calling the new API: older workers mishandle recorded
+  approvals' attempt/reason semantics. Hosts without a worker must arrange pending-row dispatch;
+  executeInvocation is not a concurrent-safe targeted claim.
+
+  Inline approval persistence allowlists documented decision fields, excluding caller-supplied
+  requestId and recordedAtAttempt so an interrupted inline execution cannot acquire the recording
+  path's first-claim exemption. Recording takes its attempt marker from the locked invocation row.
+
+- 1e46ff0: Add opt-in `idempotency.recordRefusals` to reserve keyed terminal submission refusals.
+  The new `submission_refused` status is inert, and refusal identity includes actor type.
+  Defaults retain the free-key refusal behavior. Admission-declaring actions omit refusal
+  digests to preserve their pre-admission parameter boundary; refusal rows store fixed evidence
+  without parameters, proposal or provenance attributes. Recorded errors confirm persistence,
+  and store failures surface unchanged. Apply migration 15 and upgrade all hosts sharing a
+  database before activation. Unauthorized callers can occupy keys, and callbacks returning
+  false during outages can permanently reserve them. Refusal codes must be fixed action codes.
+
+  With recording enabled, an empty string is a present idempotency key. Stores preserve empty
+  key and authorization-binding identities on hydration, and memory insertion arbitrates empty
+  keys consistently with PostgreSQL. Default Host submissions keep their keyless empty-string behavior.
+
+  Generic creation and status-update methods reject `submission_refused` as a write input;
+  the narrow refusal insert owns new refusal rows and their fixed payloads.
+
+  Validate request-only metadata before recording an eligible refusal so malformed submissions
+  leave their keys free. The public tenant-isolation kit adds an optional recorded-refusal scope
+  check, including ordinary creation against a refusal in another scope. Its result list gains
+  `fabric.tenancy.submission-refusal-scoped.v1`; stores without the method skip that check.
+  A PostgreSQL store must have migration 15 applied (`ensureSchema()`) before running the kit, or the new check fails.
+
+- 8644cc5: Add optional transaction-bound execution and approval authority hooks. Execution checks run after
+  state-machine validation directly before handler effects on both atomic and legacy transaction
+  paths. Approval checks run after the invocation row is locked and classified directly before a
+  decision write. False, thrown and non-boolean results commit nothing; approval stores advertise the
+  new transactional authorization capability. Existing pre-transaction callbacks remain unchanged.
+
+  A throw from the execution hook settles the invocation as `failed` and is not retried, including a
+  `RetryableExecutionError`. The execution hook shares the handler's transaction only on a store with
+  `transactionWithEvents`, and it does not run before a finalizing action's `finalize` transaction.
+
+## 8.8.0
+
+### Minor Changes
+
+- 385a989: Expose the optional execution lease owner and token in adapter execution context, using the same frozen identity as Host write fencing and omitting the key for unleased execution. Platform Host 8.8.0 is the first Host that supplies it, so with an older Host the key is also absent: an adapter that requires fencing must treat a missing lease as "cannot fence", not as "safe". Every new claim of the invocation, including a takeover by another worker, rotates the token. Adapters can check this evidence in the transaction that claims their domain row immediately before a provider call; Host does not check the lease during the adapter call.
+
 ## 8.7.0
 
 ### Minor Changes