@fabricorg/platform-host 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @fabricorg/platform-host
 
+## 0.4.1 — 2026-07-20
+
+- Add runtime-local action resolution without process-wide registry mutation.
+- Pass the injected host clock to policy evaluators.
+- Treat empty state-machine targets as no-op transitions.
+- Default domain events to the action schema version while preserving explicit event versions.
+- Omit custom extracted-event carrier fields from durable invocation results.
+
+## 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.1
 ```
 
 Vertical packages register `FabricModule` definitions. Host applications provide tenant authorization,
@@ -11,13 +11,19 @@ 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
 worker entry point. With no dispatcher the host executes inline, which is intended for tests and local
 development only.
 
+Applications that assemble action catalogs per runtime can provide `resolveAction` instead of
+mutating the process-wide platform registry. A custom `extractEvents` implementation can pair with
+`eventResultFields` so its event carrier is removed from the durable invocation result. Domain events
+without an explicit `eventSchemaVersion` inherit the action version, while host lifecycle events stay
+at version 1. The injected `now` clock is also passed to ordinary policy evaluation.
+
 Production polling workers can use `createStoreBackedActionDispatcher()` plus
 `runPlatformActionWorker()`. The pending invocation row is the durable queue item; workers claim
 bounded batches with an atomic lease and `FOR UPDATE SKIP LOCKED`, and an expired `running` lease is
@@ -29,6 +35,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

@@ -12,8 +12,10 @@ function createGovernedActionHost(options) {
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const extractEvents = options.extractEvents ?? DEFAULT_EXTRACT_EVENTS;
+  const actionResolver = options.resolveAction ?? platform.resolveAction;
+  const eventResultFields = options.eventResultFields ?? ["_events"];
   async function submitAction(input) {
-    const action = platform.resolveAction(input.actionId);
+    const action = actionResolver(input.actionId);
     if (!action) throw new Error(`Unknown action: ${input.actionId}`);
     const authorizationInput = toAuthorizationInput(action, input);
     if (!await options.authorization.checkEntitlement(authorizationInput)) {
@@ -47,7 +49,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 +66,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,22 +88,26 @@ 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);
+    const action = actionResolver(invocation.actionId);
     if (!action) {
       return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     }
@@ -108,15 +118,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,
@@ -132,7 +195,8 @@ function createGovernedActionHost(options) {
         parameters: parsed.data,
         db: options.store.db,
         services: options.services,
-        mode: "execute"
+        mode: "execute",
+        now: now()
       });
       for (const outcome of outcomes) {
         await options.store.appendPolicyEvaluation({
@@ -165,15 +229,17 @@ function createGovernedActionHost(options) {
           entityId
         ) ?? initialState(binding.entityType) : initialState(binding.entityType);
         const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
-        const transition = platform.validateTransition(
-          binding.entityType,
-          currentState,
-          targetState,
-          action.actionId
-        );
-        const replayingAppliedTransition = action.idempotent && currentState === targetState;
-        if (!transition.valid && !replayingAppliedTransition) {
-          return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+        if (targetState !== "") {
+          const transition = platform.validateTransition(
+            binding.entityType,
+            currentState,
+            targetState,
+            action.actionId
+          );
+          const replayingAppliedTransition = action.idempotent && currentState === targetState;
+          if (!transition.valid && !replayingAppliedTransition) {
+            return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+          }
         }
       }
       let data;
@@ -202,7 +268,7 @@ function createGovernedActionHost(options) {
         domainEvents = extractEvents(data);
         if (action.eventPhase !== "after_adapters") {
           for (const [index, event] of domainEvents.entries()) {
-            await appendEvent(invocation, event, `domain:${index}`);
+            await appendEvent(invocation, event, `domain:${index}`, action.version);
           }
         }
       } catch (error) {
@@ -321,27 +387,96 @@ function createGovernedActionHost(options) {
       }
       if (action.eventPhase === "after_adapters") {
         for (const [index, event] of domainEvents.entries()) {
-          await appendEvent(invocation, event, `domain:${index}`);
+          await appendEvent(invocation, event, `domain:${index}`, action.version);
         }
       }
-      const result = withoutPrivateHostFields(data);
+      const result = withoutPrivateHostFields(data, eventResultFields);
       await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
         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 appendEvent(invocation, event, deduplicationKey) {
+  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 = actionResolver(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, defaultEventSchemaVersion = 1) {
     const timestamp = now();
     const envelope = {
       id: lifecycleId("evt", invocation.id, deduplicationKey),
       tenantId: invocation.tenantId,
       spaceId: invocation.spaceId,
       eventType: event.eventType,
-      eventSchemaVersion: event.eventSchemaVersion ?? 1,
+      eventSchemaVersion: event.eventSchemaVersion ?? defaultEventSchemaVersion,
       subjectType: event.subjectType,
       subjectId: event.subjectId,
       actorId: invocation.actorId,
@@ -366,9 +501,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 {
@@ -397,9 +561,10 @@ function initialState(entityType) {
 function isTerminal(status) {
   return ["completed", "failed", "blocked_by_policy", "validation_failed"].includes(status);
 }
-function withoutPrivateHostFields(data) {
-  const { _events: _ignored, ...result } = data;
-  return result;
+function withoutPrivateHostFields(data, eventResultFields) {
+  return Object.fromEntries(
+    Object.entries(data).filter(([key]) => !eventResultFields.includes(key))
+  );
 }
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -446,6 +611,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 +727,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 +824,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 +841,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 +1096,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 +1157,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) {