@fabricorg/platform-host 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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.

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
@@ -29,6 +29,51 @@ adapter that already reached `succeeded`, and event, policy, and adapter writes
 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

package/dist/index.cjs

@@ -47,7 +47,9 @@ function createGovernedActionHost(options) {
         status: durableInvocation.status,
         workflowId: durableWorkflowId,
         result: durableInvocation.result,
-        ...durableInvocation.error ? { error: durableInvocation.error } : {}
+        ...durableInvocation.error ? { error: durableInvocation.error } : {},
+        ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
+        ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {}
       };
     }
     if (options.dispatcher) {
@@ -62,7 +64,9 @@ function createGovernedActionHost(options) {
           actionInvocationId: durableInvocation.id,
           status: durableInvocation.status,
           workflowId: dispatched.workflowId,
-          ...dispatched.runId ? { runId: dispatched.runId } : {}
+          ...dispatched.runId ? { runId: dispatched.runId } : {},
+          ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
+          ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {}
         };
       } catch (error) {
         const message = errorMessage(error);
@@ -82,19 +86,23 @@ function createGovernedActionHost(options) {
     );
     return { ...executed, workflowId: durableWorkflowId };
   }
-  async function executeInvocation(actionInvocationId, tenantId, spaceId) {
-    const invocation = await options.store.getActionInvocation(
+  async function executeInvocation(actionInvocationId, tenantId, spaceId, executionOptions = {}) {
+    const loadedInvocation = await options.store.getActionInvocation(
       actionInvocationId,
       tenantId,
       spaceId
     );
-    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
-    if (isTerminal(invocation.status)) {
+    if (!loadedInvocation) {
+      throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    }
+    let invocation = loadedInvocation;
+    if (isTerminal(invocation.status) || invocation.status === "waiting_for_approval") {
+      return actionResult(invocation);
+    }
+    if (invocation.status === "running" && invocation.leaseOwner && executionOptions.leaseOwner !== invocation.leaseOwner) {
       return {
-        actionInvocationId,
-        status: invocation.status,
-        result: invocation.result,
-        ...invocation.error ? { error: invocation.error } : {}
+        ...actionResult(invocation),
+        error: `Invocation is leased by ${invocation.leaseOwner}`
       };
     }
     const action = platform.resolveAction(invocation.actionId);
@@ -108,15 +116,68 @@ function createGovernedActionHost(options) {
         `Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
       );
     }
-    await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
-      status: "running"
-    });
+    if (invocation.status !== "running") {
+      await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
+        status: "running"
+      });
+    }
     try {
       const parsed = action.schema.safeParse(invocation.parameters);
       if (!parsed.success) {
         const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
         return fail(invocation, "validation_failed", message);
       }
+      if (invocation.actorType === "agent" && options.hitlEvaluator) {
+        const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
+        const approvalStore = asApprovalStore(options.store);
+        if (!approvalStore) {
+          return fail(
+            invocation,
+            "failed",
+            "The configured HITL evaluator requires a store with approval persistence support."
+          );
+        }
+        if (!invocation.hitlRoute) {
+          const decision = await options.hitlEvaluator({
+            actionId: action.actionId,
+            actorId: invocation.actorId,
+            actorType: invocation.actorType,
+            tenantId,
+            spaceId,
+            parameters: hitlParameters,
+            ...numberValue(hitlParameters.confidence) !== void 0 ? { confidence: numberValue(hitlParameters.confidence) } : {},
+            ...isRiskTier(hitlParameters.riskTier) ? { riskTier: hitlParameters.riskTier } : {},
+            ...stringValue(hitlParameters.agentSessionId) ? { agentSessionId: stringValue(hitlParameters.agentSessionId) } : {},
+            ...stringValue(hitlParameters.agentRunId) ? { agentRunId: stringValue(hitlParameters.agentRunId) } : {}
+          });
+          invocation = await approvalStore.recordHitlDecision(
+            actionInvocationId,
+            tenantId,
+            spaceId,
+            {
+              ...decision,
+              ...options.hitlPolicyVersion ? { policyVersion: options.hitlPolicyVersion } : {},
+              evaluatedAt: now()
+            }
+          );
+        }
+        if (invocation.hitlRoute === "rejected") {
+          return fail(
+            invocation,
+            "failed",
+            `HITL rejected: ${invocation.hitlReason ?? "no reason provided"}`
+          );
+        }
+        if ((invocation.hitlRoute === "needs-approval" || invocation.hitlRoute === "escalate") && !invocation.approvalDecision?.approved) {
+          await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
+            status: "waiting_for_approval"
+          });
+          return {
+            ...actionResult(invocation),
+            status: "waiting_for_approval"
+          };
+        }
+      }
       const authorizationInput = toAuthorizationInput(action, invocation);
       const definitions = options.resolvePolicies ? await options.resolvePolicies({
         ...authorizationInput,
@@ -329,11 +390,80 @@ function createGovernedActionHost(options) {
         status: "completed",
         result
       });
-      return { actionInvocationId, status: "completed", result };
+      return {
+        actionInvocationId,
+        status: "completed",
+        result,
+        ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+        ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+      };
     } catch (error) {
       return fail(invocation, "failed", errorMessage(error));
     }
   }
+  async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
+    if (!decision.approverId.trim()) throw new Error("approverId is required");
+    const invocation = await options.store.getActionInvocation(
+      actionInvocationId,
+      tenantId,
+      spaceId
+    );
+    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    if (isTerminal(invocation.status)) return actionResult(invocation);
+    if (invocation.status !== "waiting_for_approval") {
+      return {
+        ...actionResult(invocation),
+        error: `Invocation is not waiting for approval (status: ${invocation.status})`
+      };
+    }
+    const action = platform.resolveAction(invocation.actionId);
+    if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+    const approvalAuthorizationInput = toAuthorizationInput(action, {
+      tenantId,
+      spaceId,
+      actorId: decision.approverId,
+      actorType: decision.approverType
+    });
+    const entitled = await options.authorization.checkEntitlement(
+      approvalAuthorizationInput
+    );
+    const authorized = options.authorization.authorizeApproval ? await options.authorization.authorizeApproval({
+      ...approvalAuthorizationInput,
+      decision
+    }) : await options.authorization.authorize(approvalAuthorizationInput);
+    if (!entitled || !authorized) {
+      return {
+        ...actionResult(invocation),
+        error: `Actor ${decision.approverId} is not authorized to decide this approval`
+      };
+    }
+    const approvalStore = asApprovalStore(options.store);
+    if (!approvalStore) {
+      return {
+        ...actionResult(invocation),
+        error: "Approval resume requires a store with approval persistence support."
+      };
+    }
+    const transitionStartedAt = now();
+    const decidedAt = decision.decidedAt ?? transitionStartedAt;
+    const leaseOwner = `approval-resume-${platform.createFabricId("lease")}`;
+    const transition = await approvalStore.beginApprovalDecision({
+      actionInvocationId,
+      tenantId,
+      spaceId,
+      decision: { ...decision, decidedAt },
+      leaseOwner,
+      leaseDurationMs: options.approvalResumeLeaseDurationMs ?? 5 * 6e4,
+      now: transitionStartedAt
+    });
+    const transitioned = transition.invocation ?? await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!transition.applied || !transitioned) {
+      if (!transitioned) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+      return actionResult(transitioned);
+    }
+    if (!decision.approved) return actionResult(transitioned);
+    return executeInvocation(actionInvocationId, tenantId, spaceId, { leaseOwner });
+  }
   async function appendEvent(invocation, event, deduplicationKey) {
     const timestamp = now();
     const envelope = {
@@ -366,9 +496,38 @@ function createGovernedActionHost(options) {
       invocation.spaceId,
       { status, error }
     );
-    return { actionInvocationId: invocation.id, status, error };
+    return {
+      actionInvocationId: invocation.id,
+      status,
+      error,
+      ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+      ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+    };
   }
-  return { submitAction, executeInvocation };
+  return { submitAction, executeInvocation, resumeApprovedInvocation };
+}
+function actionResult(invocation) {
+  return {
+    actionInvocationId: invocation.id,
+    status: invocation.status,
+    result: invocation.result,
+    ...invocation.error ? { error: invocation.error } : {},
+    ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+    ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+  };
+}
+function asApprovalStore(store) {
+  const candidate = store;
+  return typeof candidate.recordHitlDecision === "function" && typeof candidate.beginApprovalDecision === "function" ? store : void 0;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isRiskTier(value) {
+  return value === "low" || value === "medium" || value === "high";
 }
 function toAuthorizationInput(action, input) {
   return {
@@ -446,6 +605,45 @@ var MemoryPlatformHostStore = class {
     const record = await this.getActionInvocation(id, tenantId, spaceId);
     if (!record) throw new Error(`ActionInvocation not found: ${id}`);
     Object.assign(record, patch, { updatedAt: /* @__PURE__ */ new Date() });
+    if (patch.status === "waiting_for_approval" || patch.status === "completed" || patch.status === "failed" || patch.status === "blocked_by_policy" || patch.status === "validation_failed") {
+      delete record.leaseOwner;
+      delete record.leaseExpiresAt;
+    }
+  }
+  async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
+    const record = await this.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!record) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    record.hitlRoute = decision.route;
+    record.hitlRiskTier = decision.riskTier;
+    record.hitlReason = decision.reason;
+    if (decision.policyVersion) record.hitlPolicyVersion = decision.policyVersion;
+    record.updatedAt = decision.evaluatedAt;
+    return record;
+  }
+  async beginApprovalDecision(input) {
+    const record = await this.getActionInvocation(
+      input.actionInvocationId,
+      input.tenantId,
+      input.spaceId
+    );
+    if (!record || record.status !== "waiting_for_approval") {
+      return { applied: false, ...record ? { invocation: record } : {} };
+    }
+    record.approvalDecision = input.decision;
+    record.updatedAt = input.now;
+    if (!input.decision.approved) {
+      record.status = "failed";
+      record.error = `Approval rejected: ${input.decision.reason ?? "no reason provided"}`;
+      delete record.leaseOwner;
+      delete record.leaseExpiresAt;
+      return { applied: true, invocation: record };
+    }
+    record.status = "running";
+    record.error = void 0;
+    record.leaseOwner = input.leaseOwner;
+    record.leaseExpiresAt = new Date(input.now.getTime() + input.leaseDurationMs);
+    record.attemptCount = Math.max(record.attemptCount, 1);
+    return { applied: true, invocation: record };
   }
   async appendPolicyEvaluation(record) {
     if (this.policyEvaluations.some((candidate) => candidate.id === record.id)) return;
@@ -523,14 +721,20 @@ var PostgresPlatformHostStore = class {
 				parameters jsonb NOT NULL, result jsonb NOT NULL DEFAULT '{}'::jsonb,
 				correlation_id text NOT NULL, causation_id text, idempotency_key text, error text,
 				attempt_count integer NOT NULL DEFAULT 0, lease_owner text,
-				lease_expires_at timestamptz,
+				lease_expires_at timestamptz, hitl_route text, hitl_risk_tier text,
+				hitl_reason text, hitl_policy_version text, approval_decision jsonb,
 				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL
 			);
 			ALTER TABLE fabric_platform.action_invocations
 				ADD COLUMN IF NOT EXISTS idempotency_key text,
 				ADD COLUMN IF NOT EXISTS attempt_count integer NOT NULL DEFAULT 0,
 				ADD COLUMN IF NOT EXISTS lease_owner text,
-				ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz;
+				ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz,
+				ADD COLUMN IF NOT EXISTS hitl_route text,
+				ADD COLUMN IF NOT EXISTS hitl_risk_tier text,
+				ADD COLUMN IF NOT EXISTS hitl_reason text,
+				ADD COLUMN IF NOT EXISTS hitl_policy_version text,
+				ADD COLUMN IF NOT EXISTS approval_decision jsonb;
 			CREATE UNIQUE INDEX IF NOT EXISTS action_invocations_idempotency_idx
 				ON fabric_platform.action_invocations
 				(tenant_id, space_id, action_id, idempotency_key)
@@ -614,9 +818,9 @@ var PostgresPlatformHostStore = class {
       `UPDATE fabric_platform.action_invocations SET
 			 status=COALESCE($4,status), result=COALESCE($5::jsonb,result),
 			 error=CASE WHEN $6::boolean THEN $7 ELSE error END,
-			 lease_owner=CASE WHEN $4 IN ('completed','failed','blocked_by_policy','validation_failed')
+			 lease_owner=CASE WHEN $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','validation_failed')
 			                  THEN NULL ELSE lease_owner END,
-			 lease_expires_at=CASE WHEN $4 IN ('completed','failed','blocked_by_policy','validation_failed')
+			 lease_expires_at=CASE WHEN $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','validation_failed')
 			                       THEN NULL ELSE lease_expires_at END,
 			 updated_at=now()
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3`,
@@ -631,6 +835,54 @@ var PostgresPlatformHostStore = class {
       ]
     );
   }
+  async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.action_invocations SET
+			 hitl_route=$4, hitl_risk_tier=$5, hitl_reason=$6,
+			 hitl_policy_version=$7, updated_at=$8
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3
+			 RETURNING *`,
+      [
+        actionInvocationId,
+        tenantId,
+        spaceId,
+        decision.route,
+        decision.riskTier,
+        decision.reason,
+        decision.policyVersion ?? null,
+        decision.evaluatedAt
+      ]
+    );
+    const row = result.rows[0];
+    if (!row) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    return toActionRecord(row);
+  }
+  async beginApprovalDecision(input) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.action_invocations SET
+			 approval_decision=$4::jsonb,
+			 status=CASE WHEN $5::boolean THEN 'running' ELSE 'failed' END,
+			 error=CASE WHEN $5::boolean THEN NULL ELSE $6 END,
+			 lease_owner=CASE WHEN $5::boolean THEN $7 ELSE NULL END,
+			 lease_expires_at=CASE WHEN $5::boolean THEN $8 ELSE NULL END,
+			 attempt_count=CASE WHEN $5::boolean THEN GREATEST(attempt_count,1) ELSE attempt_count END,
+			 updated_at=$9
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND status='waiting_for_approval'
+			 RETURNING *`,
+      [
+        input.actionInvocationId,
+        input.tenantId,
+        input.spaceId,
+        JSON.stringify({ ...input.decision, decidedAt: input.decision.decidedAt.toISOString() }),
+        input.decision.approved,
+        `Approval rejected: ${input.decision.reason ?? "no reason provided"}`,
+        input.leaseOwner,
+        new Date(input.now.getTime() + input.leaseDurationMs),
+        input.now
+      ]
+    );
+    return result.rows[0] ? { applied: true, invocation: toActionRecord(result.rows[0]) } : { applied: false };
+  }
   async appendPolicyEvaluation(record) {
     await this.sql.query(
       `INSERT INTO fabric_platform.policy_evaluations
@@ -838,11 +1090,27 @@ function toActionRecord(row) {
     attemptCount: Number(row.attempt_count ?? 0),
     ...row.lease_owner ? { leaseOwner: String(row.lease_owner) } : {},
     ...row.lease_expires_at ? { leaseExpiresAt: new Date(row.lease_expires_at) } : {},
+    ...row.hitl_route ? { hitlRoute: String(row.hitl_route) } : {},
+    ...row.hitl_risk_tier ? { hitlRiskTier: String(row.hitl_risk_tier) } : {},
+    ...row.hitl_reason ? { hitlReason: String(row.hitl_reason) } : {},
+    ...row.hitl_policy_version ? { hitlPolicyVersion: String(row.hitl_policy_version) } : {},
+    ...row.approval_decision ? { approvalDecision: toApprovalDecision(row.approval_decision) } : {},
     ...row.error ? { error: String(row.error) } : {},
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at)
   };
 }
+function toApprovalDecision(value) {
+  const decision = value;
+  return {
+    approved: Boolean(decision.approved),
+    approverId: String(decision.approverId),
+    approverType: String(decision.approverType),
+    ...decision.reason ? { reason: String(decision.reason) } : {},
+    ...decision.editsReference ? { editsReference: String(decision.editsReference) } : {},
+    decidedAt: new Date(decision.decidedAt)
+  };
+}
 function toEventRecord(row) {
   return {
     id: String(row.id),
@@ -883,21 +1151,29 @@ async function runPlatformActionWorkerCycle(options) {
   });
   let completed = 0;
   let failed = 0;
+  let waitingForApproval = 0;
   for (const invocation of claimed) {
     try {
       const result = await options.host.executeInvocation(
         invocation.id,
         invocation.tenantId,
-        invocation.spaceId
+        invocation.spaceId,
+        { leaseOwner: options.workerId }
       );
       if (result.status === "completed") completed += 1;
+      else if (result.status === "waiting_for_approval") waitingForApproval += 1;
       else failed += 1;
     } catch (error) {
       failed += 1;
       options.onError?.(error, invocation);
     }
   }
-  return { claimed: claimed.length, completed, failed };
+  return {
+    claimed: claimed.length,
+    completed,
+    failed,
+    ...waitingForApproval > 0 ? { waitingForApproval } : {}
+  };
 }
 async function runPlatformActionWorker(options) {
   while (!options.signal?.aborted) {