@fabricorg/platform-host 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @fabricorg/platform-host
 
+## 0.4.0 — 2026-07-19
+
+- Add an optional agent-only HITL evaluator between schema validation and ordinary policies.
+- Persist HITL route, risk tier, reason, and ruleset version as durable invocation evidence.
+- Add authorized, atomic approval and rejection decisions with governed resume execution.
+- Keep parked invocations out of worker claims and report worker-parked work separately from failures.
+- Preserve existing behavior for hosts that do not configure HITL.
+
+## 0.3.1 — 2026-07-19
+
+- Make policy, event, and adapter checkpoints deterministic and replay-safe.
+- Resume idempotent interrupted actions without repeating succeeded adapters.
+- Fail stale non-idempotent work terminally for explicit operator reconciliation.
+
 ## 0.3.0 — 2026-07-19
 
 - Add tenant-scoped stable command idempotency and terminal replay.

package/README.md

@@ -3,7 +3,7 @@
 The canonical host for the `@fabricorg/platform` mutation pipeline.
 
 ```bash
-pnpm add @fabricorg/platform@^0.7.0 @fabricorg/platform-host@^0.2.0
+pnpm add @fabricorg/platform@^0.7.0 @fabricorg/platform-host@^0.4.0
 ```
 
 Vertical packages register `FabricModule` definitions. Host applications provide tenant authorization,
@@ -11,7 +11,7 @@ module entitlements, persistence, projections, and an optional durable dispatche
 ordering and lifecycle invariant:
 
 ```text
-Actor → ActionInvocation → PolicyEvaluation → StateMachine → Handler → AssetEvent → AdapterInvocation → Projection
+Actor → ActionInvocation → Schema → Agent HITL → PolicyEvaluation → StateMachine → Handler → AssetEvent → AdapterInvocation → Projection
 ```
 
 `submitAction()` creates the durable `ActionInvocation` before dispatch. `executeInvocation()` is the
@@ -24,6 +24,56 @@ bounded batches with an atomic lease and `FOR UPDATE SKIP LOCKED`, and an expire
 recoverable after interruption. Pass a stable `idempotencyKey` to `submitAction()` so retries resolve
 to the original tenant-scoped invocation instead of creating another mutation.
 
+Lifecycle records use deterministic checkpoint ids. Recovered idempotent actions do not repeat an
+adapter that already reached `succeeded`, and event, policy, and adapter writes are append-safe. A
+stale action that was not declared idempotent fails terminally for manual reconciliation instead of
+silently rerunning unknown side effects.
+
+## Agent HITL
+
+Hosts can inject a vertical-owned `hitlEvaluator`. It runs only for `actorType: "agent"`, after schema
+validation and before ordinary policies. Omitting it preserves the pre-0.4 behavior. The host owns the
+durable lifecycle; the vertical continues to own the rules and risk classification.
+
+```ts
+const host = createGovernedActionHost({
+  store,
+  authorization,
+  hitlPolicyVersion: "gtm-rules.v7",
+  hitlEvaluator: async (context) => ({
+    route: context.actionId === "gtm.send_message" ? "needs-approval" : "auto-execute",
+    riskTier: context.actionId === "gtm.send_message" ? "high" : "low",
+    reason: "Vertical-owned prospect-touching rule",
+  }),
+});
+```
+
+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.
+- `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.
+
+```ts
+await host.resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, {
+  approved: true,
+  approverId: reviewer.id,
+  approverType: "natural_person",
+  reason: "Reviewed prospect-facing draft",
+  editsReference: "draft-revision-2",
+});
+```
+
+Custom stores remain source-compatible when HITL is unused. To enable HITL they must implement the
+additive `ApprovalPlatformHostStore` capability. Both built-in stores implement it; Postgres users must
+call `ensureSchema()` so the HITL evidence and approval-decision columns are added.
+
 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