@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/server-output-contract.ts

@@ -0,0 +1,120 @@
+/**
+ * Workflows Module - server-side output-contract resolver.
+ *
+ * NOT pure: this is the concrete implementation server callers (the
+ * context-schema API route) inject into `computeContextLedger`'s
+ * `resolveOutputContract` seam. It is only meaningful in the server runtime,
+ * where the activity registry is bootstrapped (guaranteed by the bootstrap
+ * import below) and the command registry holds the loaded command handlers —
+ * `commandRegistry.outputSchemaOf` is sync over already-registered handlers,
+ * so UPDATE_ENTITY's outputContract resolves a real Zod schema there and
+ * degrades honestly to 'unknown' elsewhere. The browser-side ledger never
+ * resolves contracts locally; it consumes the resolved entries from the
+ * context-schema API response.
+ *
+ * A registry entry's `outputContract` yields `ZodTypeAny | 'unknown'`
+ * (activity-registry.ts); the instanceof guard also keeps third-party entries
+ * honest at runtime before flattening.
+ */
+
+import { ZodType } from 'zod'
+import './activity-registry-bootstrap'
+import { getActivityType } from './activity-registry'
+import {
+  bindAgentOutcomeSchemaResolver,
+  bindCallApiResponseSchemaResolver,
+  type AgentOutcomeContract,
+} from './activity-types'
+import { findEndpointResponseSchema } from './endpoint-catalog'
+import { flattenSchemaToContract } from './ledger-schema-flatten'
+import type { ResolveOutputContract } from './context-ledger'
+
+/**
+ * CALL_API's registry outputContract reaches the server-only endpoint
+ * catalog through this binding (mirroring bindActivityExecutor). The sync
+ * lookup reads the per-process catalog cache, so callers that want CALL_API
+ * contracts resolved must `await ensureWorkflowEndpointCatalog()` first —
+ * the context-schema route does; unwarmed processes degrade to 'unknown'.
+ */
+bindCallApiResponseSchemaResolver((endpoint, method) => findEndpointResponseSchema(endpoint, method) ?? 'unknown')
+
+/**
+ * INVOKE_AGENT's registry outputContract reaches the OPTIONAL agent_orchestrator
+ * peer the same way the executor does: through DI, never an import. The peer's
+ * `agentWorkflowBridge` service may expose `listAgentOutcomeContracts()` (an
+ * additive, optional method — an older peer without it is simply a peer without
+ * agent typing); this module caches the returned OUTCOME schemas per process and
+ * the bound resolver reads that cache synchronously. Callers that want agent
+ * contracts resolved must `await ensureWorkflowAgentOutcomeContracts(container)`
+ * first — the context-schema route does; unwarmed processes, an absent peer, and
+ * a failing lookup all degrade to 'unknown' without throwing.
+ */
+type AgentOutcomeContractSnapshot = {
+  agentId?: unknown
+  resultKind?: unknown
+  schema?: unknown
+}
+
+type AgentOutcomeBridgeLike = {
+  listAgentOutcomeContracts?: () => Promise<AgentOutcomeContractSnapshot[]>
+}
+
+type ServiceContainer = {
+  resolve: <T>(name: string) => T
+}
+
+let agentOutcomeContracts: Map<string, AgentOutcomeContract> | null = null
+let agentOutcomeWarmup: Promise<void> | null = null
+
+bindAgentOutcomeSchemaResolver((agentId) => agentOutcomeContracts?.get(agentId) ?? 'unknown')
+
+function toAgentOutcomeContract(snapshot: AgentOutcomeContractSnapshot): AgentOutcomeContract | null {
+  const { agentId, resultKind, schema } = snapshot
+  if (typeof agentId !== 'string' || agentId.length === 0) return null
+  if (resultKind !== 'research' && resultKind !== 'proposal') return null
+  if (!(schema instanceof ZodType)) return null
+  return { resultKind, schema }
+}
+
+async function loadAgentOutcomeContracts(container: ServiceContainer): Promise<void> {
+  let bridge: AgentOutcomeBridgeLike | undefined
+  try {
+    bridge = container.resolve<AgentOutcomeBridgeLike>('agentWorkflowBridge')
+  } catch {
+    bridge = undefined
+  }
+  if (!bridge || typeof bridge.listAgentOutcomeContracts !== 'function') {
+    agentOutcomeContracts = new Map()
+    return
+  }
+  const resolved = new Map<string, AgentOutcomeContract>()
+  try {
+    for (const snapshot of await bridge.listAgentOutcomeContracts()) {
+      const contract = toAgentOutcomeContract(snapshot)
+      if (contract && typeof snapshot.agentId === 'string') resolved.set(snapshot.agentId, contract)
+    }
+  } catch {
+    agentOutcomeContracts = new Map()
+    return
+  }
+  agentOutcomeContracts = resolved
+}
+
+export async function ensureWorkflowAgentOutcomeContracts(container: ServiceContainer): Promise<void> {
+  if (!agentOutcomeWarmup) agentOutcomeWarmup = loadAgentOutcomeContracts(container)
+  await agentOutcomeWarmup
+}
+
+export function clearWorkflowAgentOutcomeContractsForTests(): void {
+  agentOutcomeContracts = null
+  agentOutcomeWarmup = null
+}
+
+export const resolveServerOutputContract: ResolveOutputContract = (activityType, config) => {
+  const entry = getActivityType(activityType)
+  const contract = entry?.outputContract
+  if (typeof contract !== 'function') return 'unknown'
+  const resolved = contract(config)
+  if (!(resolved instanceof ZodType)) return 'unknown'
+  return flattenSchemaToContract(resolved)
+}

package/src/modules/workflows/lib/set-variable.ts

@@ -0,0 +1,94 @@
+/**
+ * Workflows Module - SET_VARIABLE context assignment helpers
+ *
+ * Pure path-application logic for the SET_VARIABLE activity type. The engine
+ * merges sync activity outputs into workflow context under a namespaced key
+ * (activityName || activityType); SET_VARIABLE instead lands each assignment
+ * at its dot path in top-level context (spec 2026-07-26-workflows-ux-redesign
+ * section 3.2). Both sync merge points — the intra-transition merge in
+ * activity-executor's executeActivities and the persistence merge in
+ * transition-handler — detect SET_VARIABLE outputs with `isSetVariableOutput`
+ * and apply `buildSetVariableContextPatch` instead of namespacing.
+ *
+ * Kept in its own pure module (no React, no ORM, no container) so
+ * transition-handler tests exercise the real path application even when the
+ * whole activity-executor module is mocked.
+ */
+
+export interface SetVariableAssignment {
+  path: string
+  value?: unknown
+}
+
+export interface SetVariableOutput {
+  assignments: SetVariableAssignment[]
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function isSetVariableOutput(output: unknown): output is SetVariableOutput {
+  if (!isPlainObject(output)) return false
+  const assignments = output.assignments
+  return (
+    Array.isArray(assignments) &&
+    assignments.every((assignment) => {
+      if (!isPlainObject(assignment) || typeof assignment.path !== 'string') return false
+      const segments = splitAssignmentPath(assignment.path)
+      return segments !== null && segments.length > 0
+    })
+  )
+}
+
+const FORBIDDEN_ASSIGNMENT_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * Splits a dot path into trimmed, non-empty segments. Returns `null` when any
+ * segment is a prototype-pollution vector (`__proto__`, `constructor`,
+ * `prototype`) — such an assignment is never legitimate, so callers reject the
+ * whole assignment instead of applying it.
+ */
+export function splitAssignmentPath(path: string): string[] | null {
+  const segments = path
+    .split('.')
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0)
+  if (segments.some((segment) => FORBIDDEN_ASSIGNMENT_SEGMENTS.has(segment))) return null
+  return segments
+}
+
+/**
+ * Build a shallow top-level patch that lands every assignment at its dot
+ * path. Nested paths clone the existing objects along the way (the base is
+ * never mutated) and preserve sibling keys; missing or non-object
+ * intermediates become fresh objects. Later assignments in the same batch see
+ * earlier ones. The result spreads into the engine's existing shallow context
+ * merge without clobbering untouched top-level keys.
+ */
+export function buildSetVariableContextPatch(
+  baseContext: Record<string, unknown>,
+  assignments: SetVariableAssignment[],
+): Record<string, unknown> {
+  const patch: Record<string, unknown> = {}
+  for (const assignment of assignments) {
+    const segments = splitAssignmentPath(assignment.path)
+    if (segments === null || segments.length === 0) continue
+    const [rootKey, ...nestedSegments] = segments
+    if (nestedSegments.length === 0) {
+      patch[rootKey] = assignment.value
+      continue
+    }
+    const currentRoot = rootKey in patch ? patch[rootKey] : baseContext[rootKey]
+    const clonedRoot: Record<string, unknown> = isPlainObject(currentRoot) ? { ...currentRoot } : {}
+    let cursor = clonedRoot
+    for (const segment of nestedSegments.slice(0, -1)) {
+      const nextValue = cursor[segment]
+      cursor[segment] = isPlainObject(nextValue) ? { ...nextValue } : {}
+      cursor = cursor[segment] as Record<string, unknown>
+    }
+    cursor[nestedSegments[nestedSegments.length - 1]] = assignment.value
+    patch[rootKey] = clonedRoot
+  }
+  return patch
+}

package/src/modules/workflows/lib/signal-handler.ts

@@ -9,11 +9,18 @@ import type { EntityManager as PostgreSqlEntityManager } from '@mikro-orm/postgr
 import type { AwilixContainer } from 'awilix'
 import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { WorkflowInstance, WorkflowBranchInstance, WorkflowDefinition, StepInstance } from '../data/entities'
+import { INVOKE_AGENT_SIGNAL_NAME, SUB_WORKFLOW_SIGNAL_NAME } from './activity-executor'
 import type * as eventLoggerModule from './event-logger'
 import type * as stepHandlerModule from './step-handler'
 import type * as transitionHandlerModule from './transition-handler'
 import type * as workflowExecutorModule from './workflow-executor'
 import { resolveCodeDefinitionForInstance } from './find-definition'
+import {
+  WORKFLOW_AGENT_OUTCOME_CONTEXT_KEY,
+  buildAgentOutcomeContextEntry,
+  mapDispositionToAgentOutcome,
+  type AgentOutcomeKind,
+} from './outcome-routing'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('workflows')
@@ -34,6 +41,12 @@ export interface SendSignalOptions {
    */
   payload?: Record<string, any>
 
+  /** Engine-owned outcome metadata kept separate from author-visible mappings. */
+  agentOutcome?: AgentOutcomeKind
+
+  /** Proposal identifier associated with `agentOutcome`, when present. */
+  agentProposalId?: string
+
   /**
    * User ID sending the signal
    */
@@ -65,7 +78,16 @@ export async function sendSignal(
   container: AwilixContainer,
   options: SendSignalOptions
 ): Promise<void> {
-  const { instanceId, signalName, payload, userId, tenantId, organizationId } = options
+  const {
+    instanceId,
+    signalName,
+    payload,
+    agentOutcome,
+    agentProposalId,
+    userId,
+    tenantId,
+    organizationId,
+  } = options
 
   const eventLogger = container.resolve<typeof eventLoggerModule>('eventLogger')
   const stepHandler = container.resolve<typeof stepHandlerModule>('stepHandler')
@@ -199,7 +221,32 @@ export async function sendSignal(
     (s: any) => s.stepId === instance.currentStepId
   )
 
-  if (!currentStep || currentStep.stepType !== 'WAIT_FOR_SIGNAL') {
+  // A dedicated WAIT_FOR_SIGNAL step — OR any step that parked while declaring a
+  // `signalConfig.signalName` (e.g. an AUTOMATED step whose INVOKE_AGENT activity
+  // routed its proposal to a human) — can be resumed by a matching signal. The
+  // resume path below (merge payload → exit step → run auto transitions) is
+  // step-type-agnostic, so widening this guard is additive and safe.
+  //
+  // INVOKE_AGENT steps run their agent asynchronously (off the workflow
+  // transaction) and park on `agent_orchestrator.proposal.ready`; recognize them
+  // even when the definition omits an explicit `signalConfig.signalName` (e.g.
+  // seeded blueprints not re-saved through the visual editor) so the activity
+  // worker can resume them after the agent completes.
+  const isInvokeAgentStep =
+    !!currentStep &&
+    Array.isArray(currentStep.activities) &&
+    currentStep.activities.some((a: any) => a?.activityType === 'INVOKE_AGENT')
+  // SUB_WORKFLOW steps park while their child instance runs its own async/agent
+  // steps and resume on SUB_WORKFLOW_SIGNAL_NAME once the child terminates;
+  // recognize them even without an explicit signalConfig.signalName.
+  const isSubWorkflowStep = !!currentStep && currentStep.stepType === 'SUB_WORKFLOW'
+  const stepCanReceiveSignal =
+    !!currentStep &&
+    (currentStep.stepType === 'WAIT_FOR_SIGNAL' ||
+      !!currentStep.signalConfig?.signalName ||
+      isInvokeAgentStep ||
+      isSubWorkflowStep)
+  if (!stepCanReceiveSignal) {
     throw new SignalError(
       'Workflow is not waiting for signal',
       'NOT_WAITING_FOR_SIGNAL',
@@ -208,7 +255,13 @@ export async function sendSignal(
   }
 
   // Check signal name matches
-  const expectedSignalName = currentStep.signalConfig?.signalName || currentStep.stepId
+  const expectedSignalName =
+    currentStep.signalConfig?.signalName ||
+    (isInvokeAgentStep
+      ? INVOKE_AGENT_SIGNAL_NAME
+      : isSubWorkflowStep
+        ? SUB_WORKFLOW_SIGNAL_NAME
+        : currentStep.stepId)
   if (expectedSignalName !== signalName) {
     throw new SignalError(
       'Signal name mismatch',
@@ -229,6 +282,31 @@ export async function sendSignal(
     }
   }
 
+  // Outcome routing (spec 7.2). The signal is how EVERY resolved disposition
+  // reaches a parked agent step — the activity worker's auto_approved and
+  // researcher resumes and the human dispose path alike — so this is the one
+  // place the disposition has to be translated into the engine-owned outcome
+  // marker the executor routes on. Recorded regardless of who sent the signal;
+  // the author-visible `disposition` key stays untouched and unread by routing.
+  if (isInvokeAgentStep && instance.currentStepId) {
+    const resolvedOutcome = agentOutcome ?? mapDispositionToAgentOutcome(
+      (payload as Record<string, unknown> | undefined)?.disposition,
+    )
+    if (resolvedOutcome) {
+      const proposalId = agentProposalId
+        ?? (payload as Record<string, unknown> | undefined)?.agentProposalId
+        ?? (payload as Record<string, unknown> | undefined)?.proposalId
+      instance.context = {
+        ...instance.context,
+        [WORKFLOW_AGENT_OUTCOME_CONTEXT_KEY]: buildAgentOutcomeContextEntry(
+          instance.currentStepId,
+          resolvedOutcome,
+          typeof proposalId === 'string' ? proposalId : undefined,
+        ),
+      }
+    }
+  }
+
   instance.updatedAt = now
 
   // Log signal received event
@@ -266,6 +344,49 @@ export async function sendSignal(
     })
   }
 
+  // Outcome routing (spec 7.2). A resumed agent step is advanced HERE, not by
+  // the executor loop, so the wired outcome route has to be honoured here too —
+  // routing it in only one of the two places would silently send every
+  // human-dispositioned proposal down the happy path.
+  //
+  // Resume from the paused wait BEFORE dispatching, exactly as the ordinary
+  // resume path below does. On this path the instance is PAUSED by definition —
+  // it is parked on the very signal being delivered — and two things depended on
+  // that being cleared first: the executor's defence-in-depth PAUSED guard stops
+  // a routed run at its first step, and `instance.status === 'PAUSED'` below
+  // could never mean "this dispatch parked the run" while the pre-existing pause
+  // was still set. Every routed outcome therefore returned early and the run sat
+  // on its route target, PAUSED, forever (TC-WF-051, TC-WF-052).
+  instance.status = 'RUNNING'
+  await em.flush()
+
+  // Imported lazily rather than read off the DI-resolved executor: the resolved
+  // service is the module, and reaching for a named export on it couples this
+  // path to every test double that stubs only the two methods it needed.
+  const { dispatchAgentOutcomeForCurrentStep } = await import('./workflow-executor')
+  const outcomeDispatch = await dispatchAgentOutcomeForCurrentStep(
+    em,
+    container,
+    instance,
+    definition.definition,
+    { workflowContext: instance.context, userId },
+  )
+  if (outcomeDispatch && outcomeDispatch.kind !== 'default') {
+    if (outcomeDispatch.kind === 'failed') {
+      await workflowExecutor.completeWorkflow(em, container, instance.id, 'FAILED', {
+        error: outcomeDispatch.error,
+      })
+      return
+    }
+    if (outcomeDispatch.kind === 'parked') return
+    // `paused` is the dispatch's own report that IT parked the run (a
+    // step-through release, a wait step on the far side of the route).
+    if (outcomeDispatch.paused) return
+    await em.flush()
+    await workflowExecutor.executeWorkflow(em, container, instance.id, { userId })
+    return
+  }
+
   // Find automatic transitions from current step
   const autoTransitions = (definition.definition.transitions || []).filter(
     (t: any) => t.fromStepId === instance.currentStepId && t.trigger === 'auto'
@@ -300,6 +421,15 @@ export async function sendSignal(
     return
   }
 
+  // Resume from the paused wait: flip to RUNNING before executing the transition
+  // and re-entering executeWorkflow. Without this the executor's defense-in-depth
+  // PAUSED check stops the run after the first traversed step, so an intermediate
+  // AUTOMATED step (e.g. an emit-event "flag") between the waiting step and END
+  // leaves the instance permanently parked — and any parent sub-workflow waiting on
+  // its completion never resumes. The no-transition branches above already do this.
+  instance.status = 'RUNNING'
+  await em.flush()
+
   // Execute transition to next step
   const transitionResult = await transitionHandler.executeTransition(
     em,
@@ -307,7 +437,7 @@ export async function sendSignal(
     instance,
     instance.currentStepId,
     firstValidTransition.transition.toStepId,
-    transitionContext
+    { ...transitionContext, transitionId: firstValidTransition.transition.transitionId },
   )
 
   if (!transitionResult.success) {

package/src/modules/workflows/lib/start-fixtures.ts

@@ -0,0 +1,93 @@
+/**
+ * Workflows Module — Start fixtures (spec section 8.1)
+ *
+ * *"fixtures (named start contexts — "happy path", "missing phone")"*.
+ *
+ * Fixtures are deliberately a DIFFERENT thing from pinned samples (section 3.6),
+ * and the spec says so: a sample is per-STEP data feeding previews and the
+ * ledger, a fixture is a whole START context. Conflating them would make "which
+ * one wins" a question with no answer. They share a home
+ * (`metadata.editor.*`) and a cap discipline, nothing else.
+ *
+ * Like samples, fixture data is stored VERBATIM and is neither redacted nor
+ * encrypted — keep the warning copy wherever a fixture is saved.
+ *
+ * PURE: no ORM, no DI, no React.
+ */
+
+export const WORKFLOW_START_FIXTURES_MAX_CHARS = 65536
+export const WORKFLOW_START_FIXTURE_NAME_MAX = 80
+export const WORKFLOW_START_FIXTURES_MAX_COUNT = 25
+
+export type WorkflowStartFixture = {
+  name: string
+  savedAt: string
+  context: Record<string, unknown>
+}
+
+export type WorkflowStartFixtures = Record<string, WorkflowStartFixture>
+
+export type FixtureWriteResult =
+  | { ok: true; fixtures: WorkflowStartFixtures }
+  | { ok: false; reason: 'emptyName' | 'nameTooLong' | 'tooMany' | 'tooLarge' }
+
+function normalizeName(name: string): string {
+  return name.trim()
+}
+
+/**
+ * Add or replace a fixture.
+ *
+ * Every limit is checked against the RESULT, not the input, so replacing an
+ * existing fixture with a smaller one always succeeds even when the collection
+ * is already at its cap — the alternative would strand an author who is trying
+ * to shrink their way back under it.
+ */
+export function upsertStartFixture(
+  fixtures: WorkflowStartFixtures | null | undefined,
+  name: string,
+  context: Record<string, unknown>,
+  savedAt: string,
+): FixtureWriteResult {
+  const trimmed = normalizeName(name)
+  if (!trimmed) return { ok: false, reason: 'emptyName' }
+  if (trimmed.length > WORKFLOW_START_FIXTURE_NAME_MAX) return { ok: false, reason: 'nameTooLong' }
+
+  const next: WorkflowStartFixtures = { ...(fixtures ?? {}) }
+  const isNew = !(trimmed in next)
+  if (isNew && Object.keys(next).length >= WORKFLOW_START_FIXTURES_MAX_COUNT) {
+    return { ok: false, reason: 'tooMany' }
+  }
+
+  next[trimmed] = { name: trimmed, savedAt, context }
+
+  if (JSON.stringify(next).length > WORKFLOW_START_FIXTURES_MAX_CHARS) {
+    return { ok: false, reason: 'tooLarge' }
+  }
+
+  return { ok: true, fixtures: next }
+}
+
+export function removeStartFixture(
+  fixtures: WorkflowStartFixtures | null | undefined,
+  name: string,
+): WorkflowStartFixtures {
+  const next: WorkflowStartFixtures = { ...(fixtures ?? {}) }
+  delete next[normalizeName(name)]
+  return next
+}
+
+/**
+ * List fixtures for display, newest save first, name as the stable tiebreaker
+ * (never a bare `.sort()` — an unordered picker reshuffles under the author's
+ * cursor between renders).
+ */
+export function listStartFixtures(
+  fixtures: WorkflowStartFixtures | null | undefined,
+): WorkflowStartFixture[] {
+  const entries = Object.values(fixtures ?? {})
+  return [...entries].sort((left, right) => {
+    if (left.savedAt !== right.savedAt) return left.savedAt < right.savedAt ? 1 : -1
+    return left.name.localeCompare(right.name)
+  })
+}