@pikku/core 0.12.79 → 0.12.80

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": []
 }