@pikku/core 0.12.63 → 0.12.64

package/src/wirings/scope/wire-scope.ts

@@ -0,0 +1,34 @@
+import type { CoreScopes } from './scope.types.js'
+
+/**
+ * No-op function for declaring scopes.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `ScopeId` union,
+ * so a function referencing an undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * wireScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export const wireScope = (_config: CoreScopes): void => {}

package/src/wirings/workflow/dsl/index.ts

@@ -9,6 +9,9 @@ export type {
   WorkflowWireDoInline,
   WorkflowWireSleep,
   WorkflowWireSuspend,
+  WorkflowWireApproval,
+  WorkflowApprovalOptions,
+  ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
@@ -22,6 +25,7 @@ export type {
   SleepStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  ApprovalStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,
   FilterStepMeta,

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

@@ -3,6 +3,8 @@
  * These types define the step-based workflow format extracted by the inspector
  */
 
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+
 import type { WorkflowRun } from '../workflow.types.js'
 import type { ScenarioActor } from '../../../services/scenario-actors-service.js'
 
@@ -87,6 +89,48 @@ export type WorkflowWireSleep = (
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>
 
+/**
+ * Options for workflow.approval().
+ */
+export interface WorkflowApprovalOptions<
+  TSchema extends StandardSchemaV1 = StandardSchemaV1,
+> {
+  /**
+   * Schema the decision payload is validated against. This is a VALUE, not a
+   * type generic: the payload arrives from an untrusted caller over the approve
+   * wire, and a generic is erased at compile time — it would validate nothing.
+   * Any standard-schema library (zod, valibot, arktype) satisfies this.
+   */
+  schema: TSchema
+  /**
+   * Give up waiting after this long (e.g. '3d'), yielding `{ status: 'expired' }`
+   * instead of waiting forever. Evaluated on replay from a recorded deadline, so
+   * the answer is correct even if the wake-up timer is never delivered.
+   */
+  expiry?: string | number
+}
+
+/**
+ * The result of an approval gate. A union rather than a throw so that callers
+ * must handle the deadline case, and so "skip it and carry on" stays trivial.
+ * `decided` means a human answered — whether that answer was yes or no is
+ * carried in `data` and is the application's business, not the framework's.
+ */
+export type ApprovalOutcome<T> =
+  | { status: 'decided'; data: T }
+  | { status: 'expired' }
+
+/**
+ * Type signature for workflow.approval() - used by inspector.
+ * Like {@link WorkflowWireSuspend}, `reason` is the approval point's stable
+ * durable identity. Unlike suspend, the gate stays closed until a decision is
+ * recorded against it, and the decision is handed back to the caller.
+ */
+export type WorkflowWireApproval = <TSchema extends StandardSchemaV1>(
+  reason: string,
+  options: WorkflowApprovalOptions<TSchema>
+) => Promise<ApprovalOutcome<StandardSchemaV1.InferOutput<TSchema>>>
+
 /**
  * Input source for step arguments in DSL workflows
  */
@@ -285,6 +329,19 @@ export interface SuspendStepMeta {
   reason: string
 }
 
+/**
+ * Approval step metadata (workflow.approval())
+ */
+export interface ApprovalStepMeta {
+  type: 'approval'
+  /** Reason string passed to workflow.approval() — becomes the durable step key */
+  reason: string
+  /** Output variable name (if assigned) */
+  outputVar?: string
+  /** Expiry duration, when one was given */
+  expiry?: string | number
+}
+
 /**
  * Filter step metadata (array.filter)
  */
@@ -330,6 +387,7 @@ export type WorkflowStepMeta =
   | SleepStepMeta
   | CancelStepMeta
   | SuspendStepMeta
+  | ApprovalStepMeta
   | SwitchStepMeta
   | FilterStepMeta
   | ArrayPredicateStepMeta
@@ -388,6 +446,9 @@ export interface PikkuWorkflowWire {
 
   /** Suspend workflow until explicitly resumed */
   suspend: WorkflowWireSuspend
+
+  /** Suspend workflow until a human records a decision against this gate */
+  approval: WorkflowWireApproval
 }
 
 export interface PikkuScenarioWire extends PikkuWorkflowWire {

package/src/wirings/workflow/graph/graph-node.ts

@@ -180,6 +180,8 @@ type GraphNodeConfigMap<
     onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[]
     retries?: number
     retryDelay?: string | number
+    /** Free-text node documentation. Non-semantic — excluded from graphHash. */
+    notes?: string
   }
 }
 

package/src/wirings/workflow/graph/graph-runner.test.ts

@@ -913,4 +913,62 @@ describe('graph-runner bugs', () => {
       'default retries get exponential backoff so they ride out transient outages'
     )
   })
+
+  test('$item refs pass through resolveSerializedInput unresolved so a fanout node can bind them per-item', async () => {
+    const ws = new InMemoryWorkflowService()
+
+    let received: any = null
+    const mockRpcService = {
+      rpcWithWire: async (rpcName: string, data: any) => {
+        if (rpcName === 'mapFn') {
+          received = data
+          return { ok: true }
+        }
+        return {}
+      },
+    }
+
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState['testItemPassthrough'] = {
+      name: 'testItemPassthrough',
+      pikkuFuncId: 'testItemPassthrough',
+      source: 'graph',
+      entryNodeIds: ['map'],
+      graphHash: 'inline-item-passthrough-hash',
+      nodes: {
+        map: {
+          nodeId: 'map',
+          rpcName: 'mapFn',
+          input: {
+            child: 'postVideo',
+            childInput: {
+              url: { $ref: '$item', path: 'URL VIDEO' },
+              title: { $ref: 'trigger', path: 'campaign' },
+            },
+          },
+        },
+      },
+    } as unknown as WorkflowRuntimeMeta
+
+    await runWorkflowGraph(
+      ws,
+      'testItemPassthrough',
+      { campaign: 'launch' },
+      mockRpcService,
+      true
+    )
+
+    assert.deepEqual(
+      received?.childInput?.url,
+      { $ref: '$item', path: 'URL VIDEO' },
+      '$item ref must survive verbatim so the fanout function can resolve it per element'
+    )
+    assert.equal(
+      received?.childInput?.title,
+      'launch',
+      'non-$item refs must still resolve normally (constant across items)'
+    )
+
+    delete metaState['testItemPassthrough']
+  })
 })

package/src/wirings/workflow/graph/graph-runner.ts

@@ -308,6 +308,9 @@ function resolveTemplate(
 
 function resolveValue(value: unknown, nodeResults: Record<string, any>): any {
   if (isDataRef(value)) {
+    if (value.$ref === '$item') {
+      return value
+    }
     const source = nodeResults[value.$ref]
     return value.path ? getValueAtPath(source, value.path) : source
   }

package/src/wirings/workflow/graph/wire-workflow-graph.ts

@@ -8,6 +8,11 @@ export interface PikkuWorkflowGraphConfig<
   tags?: string[]
   nodes: FuncMap
   config?: T
+  /**
+   * Graph-level free-text notes (e.g. imported sticky notes). Non-semantic:
+   * excluded from the graph topology hash.
+   */
+  notes?: string[]
 }
 
 export interface PikkuWorkflowGraphResult {
@@ -15,6 +20,7 @@ export interface PikkuWorkflowGraphResult {
   name?: string
   description?: string
   tags?: string[]
+  notes?: string[]
 }
 
 export function pikkuWorkflowGraph<
@@ -25,5 +31,6 @@ export function pikkuWorkflowGraph<
     name: config.name,
     description: config.description,
     tags: config.tags,
+    notes: config.notes,
   }
 }

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

@@ -69,6 +69,11 @@ export interface GraphNodeConfig<NodeIds extends string = string> {
   retries?: number
   /** Delay between retries — milliseconds, duration string, or 'exponential' */
   retryDelay?: string | number
+  /**
+   * Free-text documentation for this node. Non-semantic: excluded from the
+   * graph topology hash, so editing a note never marks the workflow as changed.
+   */
+  notes?: string
 }
 
 /**

package/src/wirings/workflow/index.ts

@@ -8,6 +8,7 @@ export {
   WorkflowDispatchException,
   WorkflowNotFoundError,
   WorkflowRunNotFoundError,
+  WorkflowApprovalResolvedError,
   DEFAULT_STEP_RETRIES,
 } from './pikku-workflow-service.js'
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js'
@@ -88,6 +89,9 @@ export type {
   WorkflowWireDoInline,
   WorkflowWireSleep,
   WorkflowWireSuspend,
+  WorkflowWireApproval,
+  WorkflowApprovalOptions,
+  ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
@@ -102,6 +106,7 @@ export type {
   SleepStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  ApprovalStepMeta,
   SetStepMeta,
   SwitchCaseMeta,
   SwitchStepMeta,

package/src/wirings/workflow/pikku-workflow-service.test.ts

@@ -1,10 +1,12 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addWorkflow } from './dsl/workflow-runner.js'
 import {
+  WorkflowApprovalResolvedError,
   WorkflowSuspendedException,
   type PikkuWorkflowWire,
 } from './pikku-workflow-service.js'
@@ -463,3 +465,342 @@ describe('pikku-workflow-service suspend', () => {
     pikkuState(null, 'workflows', 'registrations').delete(workflowName)
   })
 })
+
+/**
+ * A minimal StandardSchemaV1 — the same interface zod/valibot/arktype expose via
+ * `~standard`. Hand-rolled here because @pikku/core deliberately has no zod
+ * dependency: schemas reach it through the standard-schema spec only.
+ */
+const approvalDecisionSchema: StandardSchemaV1<
+  { approved: boolean; comment?: string },
+  { approved: boolean; comment?: string }
+> = {
+  '~standard': {
+    version: 1,
+    vendor: 'test',
+    validate: (value: unknown) => {
+      if (typeof value !== 'object' || value === null) {
+        return { issues: [{ message: 'expected an object' }] }
+      }
+      const { approved, comment } = value as Record<string, unknown>
+      if (typeof approved !== 'boolean') {
+        return {
+          issues: [
+            { message: 'approved must be a boolean', path: ['approved'] },
+          ],
+        }
+      }
+      if (comment !== undefined && typeof comment !== 'string') {
+        return {
+          issues: [{ message: 'comment must be a string', path: ['comment'] }],
+        }
+      }
+      return { value: { approved, ...(comment ? { comment } : {}) } }
+    },
+  },
+}
+
+const registerApprovalWorkflow = (
+  workflowName: string,
+  graphHash: string,
+  func: (
+    services: any,
+    data: any,
+    wire: { workflow: PikkuWorkflowWire }
+  ) => Promise<any>
+) => {
+  pikkuState(null, 'package', 'singletonServices', {
+    queueService: {
+      add: async () => {},
+    },
+  } as any)
+
+  const metaState = pikkuState(null, 'workflows', 'meta')
+  metaState[workflowName] = {
+    name: workflowName,
+    pikkuFuncId: workflowName,
+    source: 'dsl',
+    graphHash,
+  }
+  const functionMetaState = pikkuState(null, 'function', 'meta')
+  functionMetaState[workflowName] = {
+    name: workflowName,
+    sessionless: true,
+    permissions: [],
+  } as any
+
+  addWorkflow(workflowName, { func })
+
+  return () => {
+    delete metaState[workflowName]
+    delete functionMetaState[workflowName]
+    pikkuState(null, 'workflows', 'registrations').delete(workflowName)
+  }
+}
+
+describe('pikku-workflow-service approval', () => {
+  test('resuming without a decision must NOT fall through the approval', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalNoFallthrough'
+    const graphHash = 'approval-no-fallthrough'
+    let bodyRuns = 0
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        bodyRuns++
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+    assert.equal((await ws.getRun(runId))?.status, 'suspended')
+
+    // THE point of an approval vs a suspend: a bare resume with no decision
+    // recorded must re-suspend, not walk past the gate.
+    await ws.resumeWorkflow(runId)
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+    assert.equal((await ws.getRun(runId))?.status, 'suspended')
+    assert.equal(bodyRuns, 2)
+
+    cleanup()
+  })
+
+  test('approveStep records a decision the workflow then returns', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalDecision'
+    const graphHash = 'approval-decision'
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    await ws.approveStep(runId, 'Approve invoice', {
+      approved: true,
+      comment: 'lgtm',
+    })
+    await ws.runWorkflowJob(runId, {})
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+    assert.deepEqual(run?.output, {
+      decision: {
+        status: 'decided',
+        data: { approved: true, comment: 'lgtm' },
+      },
+    })
+
+    cleanup()
+  })
+
+  test('approveStep rejects a payload that fails the schema', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalSchema'
+    const graphHash = 'approval-schema'
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    // The resume payload crosses an HTTP boundary from an untrusted caller.
+    // approveStep only records it; validation happens on replay, inside the
+    // workflow body, which is the only place the schema value is in scope.
+    await ws.approveStep(runId, 'Approve invoice', { approved: 'yes-please' })
+
+    // An invalid decision must leave the gate closed rather than fail the run.
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+    assert.equal((await ws.getRun(runId))?.status, 'suspended')
+
+    // ...and the rejection is legible to whoever tries to approve next.
+    const state = await ws.getRunState(runId)
+    assert.match(
+      JSON.stringify(state),
+      /approved/,
+      'expected the validation failure to be recorded in run state'
+    )
+
+    // A subsequent valid decision still lands.
+    await ws.approveStep(runId, 'Approve invoice', { approved: false })
+    await ws.runWorkflowJob(runId, {})
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+    assert.deepEqual(run?.output, {
+      decision: { status: 'decided', data: { approved: false } },
+    })
+
+    cleanup()
+  })
+
+  test('an expired approval returns { status: expired } instead of hanging', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalExpiry'
+    const graphHash = 'approval-expiry'
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+          expiry: '10ms',
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    await new Promise((resolve) => setTimeout(resolve, 25))
+
+    await ws.resumeWorkflow(runId)
+    await ws.runWorkflowJob(runId, {})
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+    assert.deepEqual(run?.output, { decision: { status: 'expired' } })
+
+    cleanup()
+  })
+
+  test('a decision arriving after the gate resolved is rejected, not dropped', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalAfterResolved'
+    const graphHash = 'approval-after-resolved'
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+          expiry: '10ms',
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    // Let the gate expire and resolve.
+    await new Promise((resolve) => setTimeout(resolve, 25))
+    await ws.resumeWorkflow(runId)
+    await ws.runWorkflowJob(runId, {})
+    assert.equal((await ws.getRun(runId))?.status, 'completed')
+
+    // The gate caches its outcome and never re-reads state, so accepting this
+    // would discard it silently. The approver must be told it did not land.
+    await assert.rejects(
+      ws.approveStep(runId, 'Approve invoice', { approved: true }),
+      (error: unknown) =>
+        error instanceof WorkflowApprovalResolvedError &&
+        error.payload.outcome === 'expired'
+    )
+
+    // The resolved outcome stands.
+    const run = await ws.getRun(runId)
+    assert.deepEqual(run?.output, { decision: { status: 'expired' } })
+
+    cleanup()
+  })
+
+  test('a decision that landed before expiry wins over the expiry', async () => {
+    const ws = new InMemoryWorkflowService()
+    const workflowName = 'testApprovalExpiryRace'
+    const graphHash = 'approval-expiry-race'
+
+    const cleanup = registerApprovalWorkflow(
+      workflowName,
+      graphHash,
+      async (_services, _data, { workflow }) => {
+        const decision = await workflow.approval('Approve invoice', {
+          schema: approvalDecisionSchema,
+          expiry: '10ms',
+        })
+        return { decision }
+      }
+    )
+
+    const runId = await ws.createRun(workflowName, {}, false, graphHash, {
+      type: 'test',
+    })
+    await assert.rejects(
+      ws.runWorkflowJob(runId, {}),
+      (error: unknown) => error instanceof WorkflowSuspendedException
+    )
+
+    await ws.approveStep(runId, 'Approve invoice', { approved: true })
+
+    // Expiry fires unconditionally (an enqueued durable timer can't be
+    // retracted), so it must no-op once a decision has landed.
+    await new Promise((resolve) => setTimeout(resolve, 25))
+    await ws.resumeWorkflow(runId)
+    await ws.runWorkflowJob(runId, {})
+
+    const run = await ws.getRun(runId)
+    assert.equal(run?.status, 'completed')
+    assert.deepEqual(run?.output, {
+      decision: { status: 'decided', data: { approved: true } },
+    })
+
+    cleanup()
+  })
+})