@pikku/core 0.12.80 → 0.12.83

package/src/wirings/workflow/workflow-approval.ts

@@ -8,6 +8,14 @@ import type {
   StepState,
   WorkflowApprovalOptions,
 } from './workflow.types.js'
+import type {
+  ApprovalDecider,
+  WorkflowApprovalPolicy,
+} from './dsl/workflow-dsl.types.js'
+import {
+  approvalPolicyRefusal,
+  WorkflowApprovalForbiddenError,
+} from './workflow-approval-policy.js'
 
 /** The durable step name an approval point is recorded under. */
 export const approvalStepNameFor = (reason: string): string =>
@@ -28,6 +36,21 @@ export const approvalStateKey = (stepName: string): string => {
   return `__approval_${hex}`
 }
 
+/**
+ * An answer to an approval gate, as the audit trail sees it.
+ *
+ * `denied` covers both a submission refused at the door and a decision cleared
+ * on replay — from the trail's point of view they are the same event, someone
+ * tried to answer a gate they could not.
+ */
+export type ApprovalAuditEvent = {
+  runId: string
+  reason: string
+  outcome: 'success' | 'denied'
+  decidedBy?: ApprovalDecider
+  refusal?: string
+}
+
 /** What the approval gate needs from the workflow service. */
 export type ApprovalStore = {
   getStepState: (runId: string, stepName: string) => Promise<StepState>
@@ -45,6 +68,18 @@ export type ApprovalStore = {
   updateRunState: (runId: string, key: string, value: unknown) => Promise<void>
   resumeWorkflow: (runId: string) => Promise<void>
   scheduleRunWake: (runId: string, delay: number) => Promise<void>
+  getRunOwner: (runId: string) => Promise<string | undefined>
+  auditApproval: (event: ApprovalAuditEvent) => Promise<void>
+}
+
+/** What run state holds for an approval point between suspension and replay. */
+type ApprovalRecord = {
+  decision?: unknown
+  decidedAt?: string
+  decidedBy?: ApprovalDecider
+  policy?: WorkflowApprovalPolicy
+  expiresAt?: string
+  error?: unknown
 }
 
 /**
@@ -53,12 +88,19 @@ export type ApprovalStore = {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
 export const recordApprovalDecision = async (
   store: ApprovalStore,
   runId: string,
   reason: string,
-  decision: unknown
+  decision: unknown,
+  decidedBy?: ApprovalDecider
 ): Promise<void> => {
   const stepName = approvalStepNameFor(reason)
   const stateKey = approvalStateKey(stepName)
@@ -78,13 +120,34 @@ export const recordApprovalDecision = async (
   }
 
   const state = await store.getRunState(runId)
-  const record = (state[stateKey] ?? {}) as Record<string, unknown>
+  const record = (state[stateKey] ?? {}) as ApprovalRecord
+
+  if (record.policy) {
+    const refusal = approvalPolicyRefusal(
+      record.policy,
+      await store.getRunOwner(runId),
+      decidedBy
+    )
+    if (refusal) {
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy,
+        refusal,
+      })
+      throw new WorkflowApprovalForbiddenError(reason, refusal)
+    }
+  }
+
   await store.updateRunState(runId, stateKey, {
     ...record,
     decision,
     decidedAt: new Date().toISOString(),
+    decidedBy,
     error: undefined,
-  })
+  } satisfies ApprovalRecord)
+  await store.auditApproval({ runId, reason, outcome: 'success', decidedBy })
   await store.resumeWorkflow(runId)
 }
 
@@ -95,6 +158,11 @@ export const recordApprovalDecision = async (
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export const evaluateApprovalStep = async (
   store: ApprovalStore,
@@ -109,7 +177,12 @@ export const evaluateApprovalStep = async (
       runId,
       approvalStepName,
       'pikkuWorkflowApproval',
-      { reason, expiry: options.expiry },
+      {
+        reason,
+        expiry: options.expiry,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+      },
       undefined,
       fromStepName
     )
@@ -129,15 +202,16 @@ export const evaluateApprovalStep = async (
   }
 
   const stateKey = approvalStateKey(approvalStepName)
-  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as {
-    decision?: unknown
-    decidedAt?: string
-    expiresAt?: string
-    error?: unknown
+  let record = ((await store.getRunState(runId))[stateKey] ?? {}) as ApprovalRecord
+
+  const policy: WorkflowApprovalPolicy = {
+    approvers: options.approvers,
+    approverScope: options.approverScope,
   }
 
   if (stepState.status === 'pending') {
     await store.setStepRunning(stepState.stepId)
+    record = { ...record, policy }
     if (options.expiry !== undefined && !record.expiresAt) {
       const expiry = getDurationInMilliseconds(options.expiry)
       record = {
@@ -146,10 +220,35 @@ export const evaluateApprovalStep = async (
       }
       await store.updateRunState(runId, stateKey, record)
       await store.scheduleRunWake(runId, expiry)
+    } else {
+      await store.updateRunState(runId, stateKey, record)
     }
   }
 
   if (record.decision !== undefined) {
+    const refusal = approvalPolicyRefusal(
+      policy,
+      await store.getRunOwner(runId),
+      record.decidedBy
+    )
+    if (refusal) {
+      await store.updateRunState(runId, stateKey, {
+        ...record,
+        decision: undefined,
+        decidedAt: undefined,
+        decidedBy: undefined,
+        error: [{ message: refusal }],
+      } satisfies ApprovalRecord)
+      await store.auditApproval({
+        runId,
+        reason,
+        outcome: 'denied',
+        decidedBy: record.decidedBy,
+        refusal,
+      })
+      throw new WorkflowSuspendedException(runId, reason)
+    }
+
     const validation = await options.schema['~standard'].validate(
       record.decision
     )
@@ -158,6 +257,7 @@ export const evaluateApprovalStep = async (
         ...record,
         decision: undefined,
         decidedAt: undefined,
+        decidedBy: undefined,
         error: validation.issues.map((issue) => ({
           message: issue.message,
           path: issue.path?.map((segment) =>
@@ -167,9 +267,13 @@ export const evaluateApprovalStep = async (
       })
       throw new WorkflowSuspendedException(runId, reason)
     }
+    // Spread rather than assigned, so a gate answered without a session keeps
+    // the shape it had before there was anything to record.
     const outcome: ApprovalOutcome<unknown> = {
       status: 'decided',
       data: validation.value,
+      ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
+      ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
     }
     await store.setStepResult(stepState.stepId, outcome)
     return outcome

package/src/wirings/workflow/workflow-run-authority.test.ts

@@ -160,7 +160,7 @@ describe('workflow run ownership', () => {
     )
   })
 
-  test('approveStep refuses a caller who does not own the run', async () => {
+  test('approveStep does not impose ownership on a gate that did not ask for it', async () => {
     seedSingletons()
     const ws = new InMemoryWorkflowService()
     const runId = await ws.createRun('flow', {}, false, 'hash', {
@@ -168,23 +168,20 @@ describe('workflow run ownership', () => {
       pikkuUserId: 'owner',
     })
 
-    await assert.rejects(
-      ws.approveStep(
-        runId,
-        'release-funds',
-        { ok: true },
-        {
-          userId: 'attacker',
-        }
-      ),
-      ForbiddenError
+    await ws.approveStep(
+      runId,
+      'release-funds',
+      { ok: true },
+      {
+        userId: 'not-the-owner',
+      }
     )
 
     const state = await ws.getRunState(runId)
-    assert.deepEqual(
-      Object.keys(state),
-      [],
-      'no decision was recorded for the run'
+    assert.equal(
+      Object.keys(state).length,
+      1,
+      'the decision was recorded, to be judged against the gate on replay'
     )
   })
 

package/src/wirings/workflow/workflow-run-ownership.ts

@@ -15,7 +15,8 @@ addError(WorkflowRunForbiddenError, {
 
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

package/src/wirings/workflow/workflow.types.ts

@@ -1,30 +1,18 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
-import type {
-  CorePikkuFunctionConfig,
-  CorePikkuFunctionHook,
-} from '../../function/functions.types.js'
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js'
 
 export type { WorkflowService } from '../../services/workflow-service.js'
 
 export type {
   WorkflowStepOptions,
-  WorkflowExpectEventuallyOptions,
-  WorkflowExpectErrorOptions,
-  WorkflowExpectServiceOptions,
   WorkflowWireDoRPC,
-  WorkflowWireDoInline,
-  WorkflowWireSleep,
-  WorkflowWireSuspend,
-  WorkflowWireApproval,
   WorkflowApprovalOptions,
   ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
-  SimpleCondition,
   Condition,
-  BranchCase,
   BranchStepMeta,
   ParallelGroupStepMeta,
   FanoutStepMeta,
@@ -39,22 +27,11 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './dsl/workflow-dsl.types.js'
 
-export type {
-  ScenarioStepPhase,
-  ScenarioStepOptions,
-  PikkuScenarioStepWire,
-  PikkuBrowserWire,
-  ScenarioBrowserProvider,
-} from './scenario-step.types.js'
-
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js'
 
 export interface WorkflowRunWire {
@@ -247,45 +224,6 @@ export type CoreWorkflow<
   tags?: string[]
 }
 
-export type CoreFeatureScenario =
-  | CorePikkuFunctionConfig<any, any, any>
-  | { scenario: CorePikkuFunctionConfig<any, any, any>; data: unknown }
-
-export type CoreFeature = {
-  name: string
-  description?: string
-  tags?: string[]
-  scenarios: readonly CoreFeatureScenario[]
-  before?: CorePikkuFunctionHook
-  after?: CorePikkuFunctionHook
-}
-
-export type FeatureMetaEntry = {
-  scenario: string
-  data?: unknown
-}
-
-export type FeatureMeta = {
-  id: string
-  name: string
-  description?: string
-  tags: string[]
-  entries: FeatureMetaEntry[]
-  unresolvedEntries: number
-  hasBefore: boolean
-  hasAfter: boolean
-}
-
-export type FeaturesMeta = Record<string, FeatureMeta>
-
-export type FeaturePlanEntry = {
-  featureId: string
-  featureName: string
-  scenarioName: string
-  data?: unknown
-  tags: string[]
-}
-
 export interface PikkuWorkflow {
   start: <I>(input: I) => Promise<{ runId: string }>
   getRun: (runId: string) => Promise<WorkflowRun>

package/src/wirings-stay-decoupled.test.ts

@@ -24,8 +24,12 @@ const ALLOWED: Record<string, string[]> = {
   // `remote` on a wire with no peer — one leaf module, not the channel runtime.
   http: ['channel'],
   cli: ['channel'],
-  // An agent streams over a channel and is invoked over rpc.
-  'ai-agent': ['channel', 'rpc'],
+  // An agent streams over a channel and is invoked over rpc, and grades itself
+  // as the last thing a finished run does.
+  'ai-agent': ['channel', 'rpc', 'ai-scorer'],
+  // A judge is a degenerate agent — it builds agent messages and runs them —
+  // and a grade is dispatched to a queue.
+  'ai-scorer': ['ai-agent', 'queue'],
   // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
   rpc: ['ai-agent'],
   gateway: ['http'],