@pikku/core 0.12.78 → 0.12.80

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

@@ -0,0 +1,215 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { pikkuState } from '../../pikku-state.js'
+import { runWorkflowGraph } from './graph/graph-runner.js'
+import { assertWorkflowRunOwner } from './workflow-run-ownership.js'
+import { WorkflowStepFunctionMismatchError } from './workflow-errors.js'
+import { ForbiddenError } from '../../errors/errors.js'
+
+const silentLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+const seedSingletons = () =>
+  pikkuState(null, 'package', 'singletonServices', {
+    logger: silentLogger,
+    // `resumeWorkflow` hands the run back to the orchestrator queue; the tests
+    // here assert on what happened before that hand-off.
+    queueService: { add: async () => 'job-1' },
+  } as any)
+
+describe('a graph run starts at an entry node the graph declared', () => {
+  const meta = {
+    name: 'payout',
+    pikkuFuncId: 'payout',
+    source: 'graph' as const,
+    entryNodeIds: ['validate'],
+    graphHash: 'payout-hash',
+    nodes: {
+      validate: { nodeId: 'validate', rpcName: 'validatePayout' },
+      // Reachable only after validation, but its input is a literal — so
+      // `areDependenciesSatisfied` alone would happily start the run here.
+      transfer: {
+        nodeId: 'transfer',
+        rpcName: 'transferFunds',
+        input: { amount: 1000 },
+      },
+    },
+  }
+
+  test('a startNode outside entryNodeIds is rejected', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+
+    await assert.rejects(
+      runWorkflowGraph(
+        ws,
+        'payout',
+        {},
+        { rpcWithWire: async () => ({}) },
+        true,
+        'transfer',
+        undefined,
+        meta
+      ),
+      /'transfer' is not an entry node/
+    )
+  })
+
+  test('a declared entry node still starts the run', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+
+    const { runId } = await runWorkflowGraph(
+      ws,
+      'payout',
+      {},
+      { rpcWithWire: async () => ({}) },
+      true,
+      'validate',
+      undefined,
+      meta
+    )
+
+    assert.ok(runId, 'the graph ran from the entry node it declared')
+  })
+})
+
+describe('a step runs the function the workflow dispatched it with', () => {
+  test('a queue message naming another function is rejected', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'queue',
+    })
+    await ws.insertStepState(runId, 'notify', 'sendReceipt', {})
+
+    const invoked: string[] = []
+    await assert.rejects(
+      ws.executeWorkflowStep(runId, 'notify', 'deleteAllUsers', {}, {
+        rpcWithWire: async (rpcName: string) => {
+          invoked.push(rpcName)
+          return {}
+        },
+      } as any),
+      WorkflowStepFunctionMismatchError
+    )
+    assert.deepEqual(invoked, [], 'nothing was invoked')
+
+    const stepState = await ws.getStepState(runId, 'notify')
+    assert.equal(
+      stepState.status,
+      'pending',
+      'the forged message left the step untouched'
+    )
+  })
+
+  test('the dispatched function still runs', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'queue',
+    })
+    await ws.insertStepState(runId, 'notify', 'sendReceipt', {})
+
+    const invoked: string[] = []
+    await ws.executeWorkflowStep(runId, 'notify', 'sendReceipt', {}, {
+      rpcWithWire: async (rpcName: string) => {
+        invoked.push(rpcName)
+        return {}
+      },
+    } as any)
+
+    assert.deepEqual(invoked, ['sendReceipt'])
+  })
+})
+
+describe('workflow run ownership', () => {
+  test('a run started by a session is readable only by that session', () => {
+    assert.throws(
+      () =>
+        assertWorkflowRunOwner(
+          { type: 'http', pikkuUserId: 'user-a' },
+          {
+            userId: 'user-b',
+          }
+        ),
+      ForbiddenError
+    )
+    assert.throws(
+      () =>
+        assertWorkflowRunOwner(
+          { type: 'http', pikkuUserId: 'user-a' },
+          undefined
+        ),
+      ForbiddenError
+    )
+    assert.doesNotThrow(() =>
+      assertWorkflowRunOwner(
+        { type: 'http', pikkuUserId: 'user-a' },
+        {
+          userId: 'user-a',
+        }
+      )
+    )
+  })
+
+  test('a run with no recorded owner has no ownership to enforce', () => {
+    assert.doesNotThrow(() =>
+      assertWorkflowRunOwner({ type: 'trigger' }, { userId: 'user-b' })
+    )
+  })
+
+  test('approveStep refuses a caller who does not own the run', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'http',
+      pikkuUserId: 'owner',
+    })
+
+    await assert.rejects(
+      ws.approveStep(
+        runId,
+        'release-funds',
+        { ok: true },
+        {
+          userId: 'attacker',
+        }
+      ),
+      ForbiddenError
+    )
+
+    const state = await ws.getRunState(runId)
+    assert.deepEqual(
+      Object.keys(state),
+      [],
+      'no decision was recorded for the run'
+    )
+  })
+
+  test('approveStep accepts the run owner', async () => {
+    seedSingletons()
+    const ws = new InMemoryWorkflowService()
+    const runId = await ws.createRun('flow', {}, false, 'hash', {
+      type: 'http',
+      pikkuUserId: 'owner',
+    })
+
+    await ws.approveStep(
+      runId,
+      'release-funds',
+      { ok: true },
+      {
+        userId: 'owner',
+      }
+    )
+
+    const state = await ws.getRunState(runId)
+    assert.equal(
+      Object.keys(state).length,
+      1,
+      'the owner’s decision was recorded'
+    )
+  })
+})

package/src/wirings/workflow/workflow-run-engine.types.ts

@@ -0,0 +1,91 @@
+import type { PikkuRawWire, SerializedError } from '../../types/core.types.js'
+import type {
+  CoreWorkflow,
+  PikkuWorkflowWire,
+  StepState,
+  WorkflowRun,
+  WorkflowStatus,
+  WorkflowStepOptions,
+} from './workflow.types.js'
+
+export interface RunLifecycleContext {
+  runId: string
+  run: WorkflowRun
+  workflowMeta: any
+  workflow: CoreWorkflow
+  wire: PikkuRawWire
+  packageName: string | null
+}
+
+/**
+ * The subset of the workflow service a step executor is allowed to call back
+ * into.
+ */
+export interface WorkflowRunEngine {
+  inlineStep(
+    runId: string,
+    logicalStepName: string,
+    fn: Function,
+    stepOptions?: WorkflowStepOptions,
+    data?: any,
+    funcName?: string
+  ): Promise<any>
+  updateRunStatus(
+    runId: string,
+    status: WorkflowStatus,
+    output?: any,
+    error?: SerializedError
+  ): Promise<void>
+  onChildWorkflowFailed(run: WorkflowRun, error: unknown): Promise<void>
+  verifyStepName(stepName: unknown): void
+}
+
+/**
+ * Hooks a host may install to decorate runs it did not start. Used by the
+ * scenario service to attach its own per-run state.
+ */
+export interface WorkflowRunExtension {
+  attachRunContext(
+    runId: string,
+    workflowMeta: any,
+    options?: Record<string, any>
+  ): Promise<void>
+  detachRunContext(runId: string): void
+  decorateRunWire(
+    wire: PikkuRawWire,
+    context: {
+      runId: string
+      workflowMeta: any
+      workflowWire: PikkuWorkflowWire
+    }
+  ): void
+  decorateWorkflowWire(
+    workflowWire: PikkuWorkflowWire,
+    context: {
+      name: string
+      runId: string
+      rpcService: any
+      addonNamespace?: string | null
+    }
+  ): void
+  onBeforeRunFunc(context: RunLifecycleContext): Promise<void>
+  onAfterRunFunc(
+    context: RunLifecycleContext,
+    outcome: 'completed' | 'failed' | 'interrupted',
+    failure: unknown
+  ): Promise<void>
+}
+
+/**
+ * Per-run bookkeeping held only for the lifetime of an in-process execution.
+ */
+export type RunContext = {
+  activeExecutions: number
+  inline?: boolean
+  ordinals: Map<string, number>
+  lastStep?: string
+  replay?: {
+    steps?: Map<string, StepState>
+    run?: WorkflowRun
+  }
+}

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

@@ -0,0 +1,36 @@
+import { ForbiddenError } from '../../errors/errors.js'
+import { addError } from '../../errors/error-handler.js'
+import type { CoreUserSession } from '../../types/core.types.js'
+import type { WorkflowRunWire } from './workflow.types.js'
+
+export class WorkflowRunForbiddenError extends ForbiddenError {
+  constructor() {
+    super('Not authorized to access this workflow run')
+  }
+}
+addError(WorkflowRunForbiddenError, {
+  status: 403,
+  message: 'Not authorized to access this workflow run.',
+})
+
+/**
+ * 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.
+ *
+ * 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
+ * not a control that exists for it. Gate those with `auth` or `permissions` on
+ * the entrypoint instead.
+ */
+export const assertWorkflowRunOwner = (
+  wire: WorkflowRunWire | undefined,
+  session: CoreUserSession | undefined
+): void => {
+  const owner = wire?.pikkuUserId
+  if (!owner) {
+    return
+  }
+  if (!session?.userId || session.userId !== owner) {
+    throw new WorkflowRunForbiddenError()
+  }
+}

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

@@ -0,0 +1,61 @@
+import { WorkflowSuspendedException } from './workflow-errors.js'
+import type { ApprovalStore } from './workflow-approval.js'
+import type { StepState } from './workflow.types.js'
+
+/** The durable step name a suspension point is recorded under. */
+export const suspendStepNameFor = (reason: string): string =>
+  `__workflow_suspend:${reason}`
+
+/** What the suspend gate needs from the workflow service. */
+export type SuspendStore = Pick<
+  ApprovalStore,
+  'getStepState' | 'insertStepState' | 'setStepRunning' | 'setStepResult'
+>
+
+/**
+ * Record a suspension point and unwind the run.
+ *
+ * A suspension that has already succeeded returns instead of throwing, so a
+ * replay walks past a gate the run has already passed through.
+ */
+export const recordSuspension = async (
+  store: SuspendStore,
+  runId: string,
+  reason: string,
+  stepName: string,
+  fromStepName: string | undefined
+): Promise<void> => {
+  const insert = () =>
+    store.insertStepState(
+      runId,
+      stepName,
+      'pikkuWorkflowSuspend',
+      { reason },
+      undefined,
+      fromStepName
+    )
+
+  let stepState: StepState
+  try {
+    stepState = await store.getStepState(runId, stepName)
+  } catch {
+    stepState = await insert()
+  }
+  if (!stepState.stepId) {
+    stepState = await insert()
+  }
+
+  if (stepState.status === 'succeeded') {
+    return
+  }
+
+  if (stepState.status === 'pending') {
+    await store.setStepRunning(stepState.stepId)
+  }
+
+  await store.setStepResult(stepState.stepId, {
+    reason,
+    suspendedAt: new Date().toISOString(),
+  })
+  throw new WorkflowSuspendedException(runId, reason)
+}

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

@@ -120,6 +120,13 @@ export interface WorkflowRun {
 export interface StepState {
   stepId: string
   status: StepStatus
+  /**
+   * The function the workflow dispatched this step with, recorded so a worker
+   * can reject a queue message naming anything else. `null` is a step with no
+   * function of its own (inline work); `undefined` is a store that never
+   * recorded one, and cannot be compared against.
+   */
+  rpcName?: string | null
   result?: any
   error?: SerializedError
   attemptCount: number

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

@@ -0,0 +1,123 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, resolve, relative, sep } from 'node:path'
+
+const srcRoot = dirname(fileURLToPath(import.meta.url))
+const wiringsRoot = join(srcRoot, 'wirings')
+
+/** Type-only statements are erased, so they couple nothing at runtime. */
+const TYPE_ONLY = /^\s*(?:import|export)\s+type\b/
+
+/**
+ * Which wire may reach which, at runtime.
+ *
+ * A wire should be self-contained apart from what is genuinely common, so every
+ * entry here is a deliberate crossover point rather than an accident. Adding one
+ * is a visible diff — and worth asking whether the dependency could be
+ * type-only, which couples nothing at runtime.
+ */
+const ALLOWED: Record<string, string[]> = {
+  // A channel is an HTTP upgrade, so it builds on the HTTP wire.
+  channel: ['http'],
+  // `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'],
+  // `wire.rpc.agent` — the facade lives with the agent runtime it delegates to.
+  rpc: ['ai-agent'],
+  gateway: ['http'],
+  mcp: ['rpc'],
+  trigger: ['rpc'],
+  // A workflow step is dispatched to a queue, invoked over rpc, or slept on.
+  workflow: ['queue', 'rpc', 'scheduler'],
+  // A virtual user drives a scenario, which is a workflow, as a persona.
+  'virtual-user': ['role', 'workflow'],
+  persona: ['virtual-user'],
+}
+
+const sourceFiles = (directory: string): string[] =>
+  readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = join(directory, entry.name)
+    if (entry.isDirectory()) {
+      return entry.name === 'dist' ? [] : sourceFiles(entryPath)
+    }
+    return entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')
+      ? [entryPath]
+      : []
+  })
+
+/** Every wire each wire reaches at runtime, following value imports only. */
+const crossWireEdges = (): Map<string, Set<string>> => {
+  const edges = new Map<string, Set<string>>()
+
+  for (const file of sourceFiles(wiringsRoot)) {
+    const from = relative(wiringsRoot, file).split(sep)[0]!
+
+    for (const line of readFileSync(file, 'utf-8').split('\n')) {
+      if (TYPE_ONLY.test(line)) continue
+      const specifier = line.match(/\bfrom\s+'(\.[^']+)'/)?.[1]
+      if (!specifier) continue
+
+      const target = resolve(dirname(file), specifier)
+      if (!target.startsWith(wiringsRoot + sep)) continue
+
+      const to = relative(wiringsRoot, target).split(sep)[0]!
+      if (to === from) continue
+      if (!edges.has(from)) edges.set(from, new Set())
+      edges.get(from)!.add(to)
+    }
+  }
+
+  return edges
+}
+
+describe('wirings stay decoupled', () => {
+  test('no wire reaches a wire it is not declared to', () => {
+    const undeclared = [...crossWireEdges()]
+      .flatMap(([from, tos]) =>
+        [...tos]
+          .filter((to) => !(ALLOWED[from] ?? []).includes(to))
+          .map((to) => `${from} -> ${to}`)
+      )
+      .sort()
+
+    assert.deepEqual(
+      undeclared,
+      [],
+      'a wire gained a runtime dependency on another wire:\n' +
+        `${undeclared.join('\n')}\n` +
+        'Add it to ALLOWED only if it is genuinely necessary — a type-only ' +
+        'import couples nothing.'
+    )
+  })
+
+  test('every declared crossover still exists', () => {
+    const actual = crossWireEdges()
+    const stale = Object.entries(ALLOWED)
+      .flatMap(([from, tos]) =>
+        tos
+          .filter((to) => !actual.get(from)?.has(to))
+          .map((to) => `${from} -> ${to}`)
+      )
+      .sort()
+
+    assert.deepEqual(
+      stale,
+      [],
+      `these crossovers are declared but no longer real — delete them:\n${stale.join('\n')}`
+    )
+  })
+
+  test('the walker finds the edges it is meant to', () => {
+    // Guards both tests above: a walker that resolved nothing would pass
+    // whatever the wirings imported.
+    const edges = crossWireEdges()
+    assert.ok(
+      edges.get('channel')?.has('http'),
+      `expected channel -> http; walker found ${edges.size} wires with edges`
+    )
+  })
+})

package/tsconfig.json

@@ -9,6 +9,6 @@
     "moduleResolution": "node16",
     "tsBuildInfoFile": null
   },
-  "exclude": ["**/*.test.ts", "node_modules", "dist"],
+  "exclude": ["**/*.test.ts", "node_modules", "dist", "scripts"],
   "references": []
 }