@oomol-lab/open-flow 0.1.0-beta.72 → 0.1.0-beta.74

package/src/flow/common/graph.ts

@@ -0,0 +1,892 @@
+import type {
+  BindingSource,
+  FlowDocument,
+  Graph,
+  GraphNode,
+  InputMapping,
+  InputPortDefinition,
+  JsonValue,
+  NodeSource,
+  PortDefinition,
+  RevisionContent,
+  SchemaMismatch,
+  TriggerNode,
+} from './change.ts'
+import type { Diagnostic } from './semantics.ts'
+
+import { missingTriggerConfig, resolveTriggerConfig } from '../../trigger/common/config.ts'
+import { triggerOutputDefinitions, triggerOutputPorts, webhookSupportsBody } from '../../trigger/common/contract.ts'
+import { isTriggerNode, portsByHandle, validVariableName } from './change.ts'
+import { conditionInputPorts, nodeInputMappings, otherwiseOutput, unaryOperator, comparisonIssue, valueType } from './condition.ts'
+import { nodeSystemOutputPorts, supportsNodeErrorHandling } from './errorHandling.ts'
+import { supportsNodeRetry, retryConfigurationSchema } from './retry.ts'
+import { schemaObject, matchesSchema, comparePorts, portsAssignable, variableInputCompatible, hasRetiredRef } from './schema.ts'
+import { sourceFields, sourcePort, sourceOutputLabel } from './sourceField.ts'
+import { waitAutoContinueSchema } from './wait.ts'
+import {
+  webhookResponseInputs,
+  validWebhookStatus,
+  webhookHeaderValues,
+  webhookHeaderNameIssue,
+  webhookHeaderValuePort,
+  webhookHeadersPort,
+  webhookResponseAllowsBody,
+  webhookStatusCodePort,
+  workflowOutputsPort,
+} from './webhookResponse.ts'
+
+export function isResolutionNode(node: GraphNode | undefined): node is Extract<GraphNode, { readonly kind: 'approval' | 'wait' }> {
+  return node?.kind == 'approval' || node?.kind == 'wait'
+}
+function graphDiagnostic(
+  code: string,
+  message: string,
+  path: string,
+  values?: Readonly<Record<string, string | number>>,
+  mismatch?: SchemaMismatch,
+): Diagnostic {
+  return { code, column: 0, line: 1, message, mismatch, path, ...(values == null ? {} : { values }) }
+}
+
+/** Execution reachability is independent of data bindings and selected runtime branches. */
+export function executionReachableNodes(graph: Graph, source: string): ReadonlySet<string> {
+  const reachable = new Set([source])
+  for (const id of reachable) for (const edge of graph.edges) if (edge.source === id) reachable.add(edge.target)
+  return reachable
+}
+
+export function webhookResponseDiagnostics(graph: Graph, triggerId: string, path = `/document/graph/nodes/${triggerId}`): readonly Diagnostic[] {
+  const trigger = graph.nodes[triggerId]
+  if (trigger?.kind != 'webhook') return []
+  const options = trigger.options ?? {}
+  const response = options.responseBody
+  const statusOutput = options.responseStatusCodeOutput
+  const statusPath = `${path}/options/responseStatusCodeOutput`
+  const diagnostics: Diagnostic[] = []
+  const headersSource = options.responseHeadersSource
+  const headerOutputs = options.responseHeaderOutputs
+  const headersPath = `${path}/options/${headersSource == null ? 'responseHeaderOutputs' : 'responseHeadersSource'}`
+  if (response?.kind !== 'workflow-outputs') {
+    if (statusOutput != null)
+      diagnostics.push(
+        graphDiagnostic('trigger.webhook-response-status-source', 'Choose workflow outputs as the response source to use a status output.', statusPath),
+      )
+    if (headersSource != null || headerOutputs != null)
+      diagnostics.push(
+        graphDiagnostic('trigger.webhook-response-headers-source', 'Choose workflow outputs as the response source to use dynamic headers.', headersPath),
+      )
+    if (response?.kind === 'webhook-response') {
+      const location = `${path}/options/responseBody/nodeId`
+      const { nodeId } = response
+      if (nodeId == null || graph.nodes[nodeId]?.kind !== 'webhook-response')
+        diagnostics.push(graphDiagnostic('trigger.webhook-response-node-missing', 'Select a Webhook Response node.', location))
+      else if (!executionReachableNodes(graph, triggerId).has(nodeId))
+        diagnostics.push(graphDiagnostic('trigger.webhook-response-node-unreachable', 'Connect this Webhook to the selected Webhook Response node.', location))
+    }
+    return diagnostics
+  }
+  if (headersSource == null) {
+    for (const [headers, location] of [
+      [options.responseHeaders, `${path}/options/responseHeaders`],
+      [headerOutputs, headersPath],
+    ] as const) {
+      const names: string[] = []
+      for (const name of Object.keys(headers ?? {})) {
+        if (webhookHeaderNameIssue(name, names) != null)
+          diagnostics.push(graphDiagnostic('trigger.webhook-response-header-name', 'Use valid, unique HTTP header names.', location))
+        names.push(name)
+      }
+    }
+  }
+  const responsePath = `${path}/options/responseBody`
+  const outputs = Object.entries(graph.nodes).filter(([, node]) => node.kind == 'outputs')
+  if (outputs.length == 0) {
+    diagnostics.push(graphDiagnostic('trigger.webhook-response-outputs-missing', 'Add a workflow Outputs node for the HTTP response.', responsePath))
+  } else if (outputs.length == 1) {
+    const output = outputs[0]!
+    const reachable = executionReachableNodes(graph, triggerId)
+    if (!reachable.has(output[0]))
+      diagnostics.push(graphDiagnostic('trigger.webhook-response-unreachable', 'Connect this Webhook to the workflow Outputs node.', responsePath))
+    const field = response.output
+    if (field != null && output[1].kind == 'outputs' && !output[1].outputDefs.some((port) => port.handle == field))
+      diagnostics.push(
+        graphDiagnostic('trigger.webhook-response-output-missing', `Workflow output "${field}" does not exist.`, `${responsePath}/output`, { output: field }),
+      )
+    if (statusOutput != null && output[1].kind == 'outputs') {
+      const port = output[1].outputDefs.find((candidate) => candidate.handle == statusOutput)
+      if (port == null)
+        diagnostics.push(
+          graphDiagnostic('trigger.webhook-response-status-output-missing', `Workflow status output "${statusOutput}" does not exist.`, statusPath, {
+            output: statusOutput,
+          }),
+        )
+      else if (!portsAssignable(port, webhookStatusCodePort))
+        diagnostics.push(
+          graphDiagnostic('trigger.webhook-response-status-output-type', 'Choose a numeric workflow output for the response status code.', statusPath),
+        )
+    }
+    if (output[1].kind == 'outputs') {
+      const fields = output[1].outputDefs
+      const checkHeaderSource = (headerField: string | undefined, target: PortDefinition, location: string) => {
+        const port = headerField == null ? workflowOutputsPort(fields) : fields.find((candidate) => candidate.handle == headerField)
+        if (port == null)
+          diagnostics.push(
+            graphDiagnostic('trigger.webhook-response-header-output-missing', `Workflow output "${headerField}" does not exist.`, location, {
+              output: headerField!,
+            }),
+          )
+        else if (!portsAssignable(port, target))
+          diagnostics.push(
+            graphDiagnostic('trigger.webhook-response-header-output-type', 'Choose a compatible workflow output for the response headers.', location),
+          )
+      }
+      if (headersSource != null) checkHeaderSource(headersSource.output, webhookHeadersPort, headersPath)
+      else
+        for (const [name, headerField] of Object.entries(headerOutputs ?? {}))
+          checkHeaderSource(headerField, webhookHeaderValuePort, `${headersPath}/${name.replaceAll('~', '~0').replaceAll('/', '~1')}`)
+    }
+  }
+  if (statusOutput == null && !webhookResponseAllowsBody(options.responseStatusCode ?? 200))
+    diagnostics.push(
+      graphDiagnostic('trigger.webhook-response-status-invalid', 'Choose a response status code that permits a body.', `${path}/options/responseStatusCode`),
+    )
+  return diagnostics
+}
+
+function validateTrigger(triggerId: string, trigger: TriggerNode, path: string, diagnostics: Diagnostic[]): void {
+  if (trigger.kind == 'start') return
+  const outputs = triggerOutputDefinitions(trigger)
+  if (outputs.some((port) => hasRetiredRef(port.jsonSchema)))
+    diagnostics.push(graphDiagnostic('graph.schema-unsupported', 'Runtime Ref schemas are not supported.', path))
+  const outputHandles = outputs.map((port) => port.handle)
+  if (new Set(outputHandles).size !== outputHandles.length)
+    diagnostics.push(graphDiagnostic('graph.port-duplicate', 'Trigger output handles must be unique.', `${path}/definition/outputs`))
+  if (trigger.kind == 'webhook') {
+    if (!webhookSupportsBody(trigger.method) && trigger.bodyFields.length > 0) {
+      diagnostics.push(graphDiagnostic('trigger.webhook-body-unsupported', 'GET Webhook triggers cannot declare request body fields.', `${path}/bodyFields`))
+    }
+    const handles = new Set<string>()
+    for (const [index, input] of trigger.bodyFields.entries()) {
+      if (handles.has(input.handle)) {
+        diagnostics.push(
+          graphDiagnostic(
+            'trigger.input-duplicate',
+            `Webhook Trigger input "${input.handle}" is declared more than once.`,
+            `${path}/bodyFields/${index}/handle`,
+            { input: input.handle },
+          ),
+        )
+      }
+      handles.add(input.handle)
+    }
+    return
+  }
+  if (trigger.kind == 'error' || trigger.kind == 'cron' || trigger.kind == 'manual') return
+  if (trigger.connectionId == null)
+    diagnostics.push(graphDiagnostic('trigger.connection-missing', 'Select a connection account for this Trigger.', `${path}/connectionId`))
+  const missingConfig = missingTriggerConfig(trigger.definition.configInputs, trigger.config)
+  if (missingConfig.length > 0) {
+    diagnostics.push({
+      ...graphDiagnostic('trigger.config-incomplete', `Complete the required Trigger config fields: ${missingConfig.join(', ')}.`, `${path}/config`, {
+        fields: missingConfig.join(', '),
+      }),
+      fields: missingConfig,
+    })
+  } else {
+    try {
+      resolveTriggerConfig(trigger.definition.configInputs, trigger.config)
+    } catch {
+      diagnostics.push(
+        graphDiagnostic('trigger.config-invalid', `Trigger "${triggerId}" config does not match its fixed definition.`, `${path}/config`, { triggerId }),
+      )
+    }
+  }
+}
+
+export function nodeInputPorts(node: GraphNode): Readonly<Record<string, InputPortDefinition>> {
+  switch (node.kind) {
+    case 'webhook-response':
+      return portsByHandle(webhookResponseInputs)
+    case 'outputs':
+      return portsByHandle(node.outputDefs)
+    case 'condition':
+      return conditionInputPorts(node)
+    case 'value':
+      return {}
+    case 'task':
+      return portsByHandle([...node.task.inputs, ...(node.additionalInputs ?? [])])
+    case 'approval':
+    case 'wait':
+      return portsByHandle(node.inputDefinitions)
+    case 'cron':
+    case 'integration':
+    case 'poll':
+    case 'error':
+    case 'manual':
+    case 'start':
+    case 'webhook':
+      return {}
+  }
+}
+
+export function resolutionActions(node: Extract<GraphNode, { readonly kind: 'approval' | 'wait' }>): readonly ['continue'] | readonly ['approve', 'reject'] {
+  return node.kind == 'wait' ? ['continue'] : ['approve', 'reject']
+}
+
+const objectPort = (properties: Record<string, JsonValue>): PortDefinition => ({
+  nullable: false,
+  jsonSchema: { type: 'object', properties, required: Object.keys(properties), additionalProperties: false },
+})
+
+export function resolutionOutputPorts(node: Extract<GraphNode, { readonly kind: 'approval' | 'wait' }>): Readonly<Record<string, PortDefinition>> {
+  const actions = resolutionActions(node)
+  const inputs = {
+    type: 'object',
+    properties: Object.fromEntries(node.inputDefinitions.map((port) => [port.handle, {}])),
+    required: node.inputDefinitions.map((port) => port.handle),
+    additionalProperties: false,
+  }
+
+  return {
+    pending: objectPort({
+      inputs,
+      prompt: { type: 'string' },
+      pageUrl: { type: 'string' },
+      message: { type: 'string', minLength: 1, pattern: '\\S' },
+      ...Object.fromEntries(actions.map((action) => [`${action}Url`, { type: 'string' }])),
+      expiresAt: { type: 'string' },
+      ...(node.kind == 'wait' && node.autoContinue != null ? { autoContinueAt: { type: 'string' } } : {}),
+    }),
+    ...Object.fromEntries(
+      actions.map((action) => [
+        action,
+        objectPort({
+          inputs,
+          action: { const: action },
+          resolvedAt: { type: 'string' },
+          comment: { type: ['string', 'null'] },
+        }),
+      ]),
+    ),
+  }
+}
+
+export function nodeOutputPorts(node: GraphNode): Readonly<Record<string, PortDefinition>> {
+  switch (node.kind) {
+    case 'webhook-response':
+    case 'outputs':
+    case 'condition':
+      return {}
+    case 'value':
+      return portsByHandle(node.values)
+    case 'task':
+      return portsByHandle(node.task.outputs)
+    case 'approval':
+    case 'wait':
+      return resolutionOutputPorts(node)
+    case 'cron':
+    case 'integration':
+    case 'poll':
+    case 'error':
+    case 'manual':
+    case 'start':
+    case 'webhook':
+      return triggerOutputPorts(node)
+  }
+}
+
+function nodeSourceOutputPorts(node: GraphNode, system?: true): Readonly<Record<string, PortDefinition>> {
+  if (system) return nodeSystemOutputPorts(node)
+  const ports = nodeOutputPorts(node)
+  return node.onError == 'error' ? Object.fromEntries(Object.entries(ports).map(([key, port]) => [key, { ...port, nullable: true }])) : ports
+}
+
+export function nodeOutputDescription(graph: Graph, nodeId: string, output: string): string | undefined {
+  const node = graph.nodes[nodeId]
+  return node == null ? undefined : nodeOutputPorts(node)[output]?.description
+}
+
+function checkSource(
+  source: BindingSource | NodeSource,
+  graph: Graph,
+  document: FlowDocument,
+  targetInput: InputPortDefinition | undefined,
+  path: string,
+  diagnostics: Diagnostic[],
+): PortDefinition | undefined {
+  switch (source.kind) {
+    case 'binding':
+      if (document.bindings[source.bindingId] == null) {
+        diagnostics.push(graphDiagnostic('graph.binding-missing', `Binding "${source.bindingId}" does not exist.`, path, { bindingId: source.bindingId }))
+      } else if (document.bindings[source.bindingId].kind != 'variable') {
+        diagnostics.push(graphDiagnostic('graph.binding-invalid', `Binding "${source.bindingId}" must be a variable.`, path, { bindingId: source.bindingId }))
+      } else if (targetInput != null && !variableInputCompatible(targetInput.jsonSchema)) {
+        diagnostics.push(
+          graphDiagnostic('graph.variable-incompatible', `Variable binding "${source.bindingId}" is not compatible with this input.`, path, {
+            bindingId: source.bindingId,
+          }),
+        )
+      }
+      return
+    case 'node': {
+      const upstream = graph.nodes[source.nodeId]
+      if (upstream == null) {
+        diagnostics.push(
+          graphDiagnostic('graph.source-missing', `Upstream node "${source.nodeId}" does not exist.`, path, {
+            nodeId: source.nodeId,
+            variant: 'node',
+          }),
+        )
+        return
+      }
+      const output = nodeSourceOutputPorts(upstream, source.system)[source.output]
+      if (output == null) {
+        diagnostics.push(
+          graphDiagnostic('graph.source-missing', `Upstream node "${source.nodeId}" does not expose output "${source.output}".`, path, {
+            nodeId: source.nodeId,
+            output: source.output,
+            variant: 'output',
+          }),
+        )
+      }
+      if (output == null) return
+      const selected = sourcePort(output, source.field)
+      if (selected == null) {
+        diagnostics.push(
+          graphDiagnostic('graph.source-missing', `Output "${source.output}" does not declare field ${JSON.stringify(source.field)}.`, path, {
+            nodeId: source.nodeId,
+            output: source.output,
+            field: source.field!,
+            variant: 'field',
+          }),
+        )
+        return
+      }
+      if (targetInput != null) {
+        const comparison = comparePorts(selected, targetInput)
+        if (comparison.kind != 'compatible') {
+          diagnostics.push(
+            graphDiagnostic(
+              'graph.node-output-incompatible',
+              `Upstream node "${source.nodeId}" output ${JSON.stringify(sourceOutputLabel(source))} is not compatible with this input.`,
+              path,
+              { nodeId: source.nodeId, output: source.output, ...(source.field === undefined ? {} : { field: source.field }) },
+              comparison.kind == 'incompatible' ? comparison.mismatch : undefined,
+            ),
+          )
+        }
+      }
+      return selected
+    }
+  }
+}
+
+export function graphOrder(graph: Graph): readonly string[] {
+  const pending = new Map(Object.keys(graph.nodes).map((id) => [id, new Set<string>()]))
+  const children = new Map<string, Set<string>>()
+  for (const edge of graph.edges) {
+    if (!pending.has(edge.source) || !pending.has(edge.target)) continue
+    pending.get(edge.target)?.add(edge.source)
+    const targets = children.get(edge.source) ?? new Set<string>()
+    targets.add(edge.target)
+    children.set(edge.source, targets)
+  }
+  const ready = [...pending]
+    .filter(([, parents]) => parents.size == 0)
+    .map(([id]) => id)
+    .toSorted()
+  for (let index = 0; index < ready.length; index++) {
+    const id = ready[index]!
+    pending.delete(id)
+    for (const child of children.get(id) ?? []) {
+      const parents = pending.get(child)
+      parents?.delete(id)
+      if (parents?.size == 0) ready.push(child)
+    }
+  }
+  return [...ready, ...[...pending.keys()].toSorted()]
+}
+
+const pathsByGraph = new WeakMap<
+  Graph,
+  {
+    readonly paths: Map<string, readonly Route[]>
+    readonly ancestors: Map<string, Set<string>>
+    readonly resolutionOutputs: Map<string, Set<string>>
+  }
+>()
+
+// Each route fixes branch choices by node ID; $trigger identifies the selected trigger.
+// An absent key leaves that choice unrestricted, so {} covers every execution path.
+type Route = Readonly<Record<string, string>>
+
+function routeCovers(route: Route, target: Route): boolean {
+  return Object.entries(route).every(([key, value]) => target[key] == value)
+}
+
+function routesCompatible(left: Route, right: Route): boolean {
+  return Object.entries(left).every(([key, value]) => right[key] == null || right[key] == value)
+}
+
+function resolutionOutputKey(nodeId: string, output: string): string {
+  return JSON.stringify([nodeId, output])
+}
+
+function graphPaths(graph: Graph) {
+  const cached = pathsByGraph.get(graph)
+  if (cached != null) return cached
+  const paths = new Map<string, readonly Route[]>()
+  const ancestors = new Map<string, Set<string>>()
+  const resolutionOutputs = new Map<string, Set<string>>()
+  const incoming = new Map<string, Graph['edges'][number][]>()
+  for (const edge of graph.edges) {
+    const edges = incoming.get(edge.target) ?? []
+    edges.push(edge)
+    incoming.set(edge.target, edges)
+  }
+  const order = graphOrder(graph)
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const id of order) {
+      const node = graph.nodes[id]!
+      const edges = incoming.get(id) ?? []
+      const parents = new Set<string>()
+      const resolutions = new Set<string>()
+      const routes: Route[] = []
+      for (const edge of edges) {
+        parents.add(edge.source)
+        for (const output of resolutionOutputs.get(edge.source) ?? []) resolutions.add(output)
+        if (isResolutionNode(graph.nodes[edge.source]) && edge.sourceHandle != null) resolutions.add(resolutionOutputKey(edge.source, edge.sourceHandle))
+        for (const parent of ancestors.get(edge.source) ?? []) parents.add(parent)
+        for (const route of paths.get(edge.source) ?? []) {
+          const next =
+            edge.sourceHandle == null || (isResolutionNode(graph.nodes[edge.source]) && edge.sourceHandle == 'pending')
+              ? route
+              : {
+                  ...route,
+                  [edge.source]:
+                    graph.nodes[edge.source]?.kind == 'condition' &&
+                    (graph.nodes[edge.source] as import('./change.ts').ConditionNode).matchMode == 'all' &&
+                    edge.sourceHandle != otherwiseOutput
+                      ? '$matched'
+                      : edge.sourceHandle,
+                }
+          if (routes.some((known) => routeCovers(known, next))) continue
+          for (let index = routes.length - 1; index >= 0; index--) {
+            if (routeCovers(next, routes[index]!)) routes.splice(index, 1)
+          }
+          routes.push(next)
+        }
+      }
+      const nextRoutes = edges.length == 0 ? (isTriggerNode(node) ? [{ $trigger: id }] : [{}]) : routes
+      const previous = paths.get(id) ?? []
+      if (
+        parents.size != (ancestors.get(id)?.size ?? 0) ||
+        resolutions.size != (resolutionOutputs.get(id)?.size ?? 0) ||
+        nextRoutes.length != previous.length ||
+        nextRoutes.some((route) => !previous.some((known) => routeCovers(known, route) && routeCovers(route, known)))
+      )
+        changed = true
+      ancestors.set(id, parents)
+      resolutionOutputs.set(id, resolutions)
+      paths.set(id, nextRoutes)
+    }
+  }
+  const analysis = { ancestors, paths, resolutionOutputs }
+  pathsByGraph.set(graph, analysis)
+  return analysis
+}
+
+function sourcePaths(graph: Graph, paths: ReturnType<typeof graphPaths>['paths'], source: BindingSource | NodeSource) {
+  if (source.kind != 'node') return [{}]
+  const node = graph.nodes[source.nodeId]
+  const routes = paths.get(source.nodeId) ?? []
+  return node?.kind == 'condition' || (isResolutionNode(node) && source.output != 'pending')
+    ? routes.map((route) => ({ ...route, [source.nodeId]: source.output }))
+    : routes
+}
+
+function mappingAvailable(graph: Graph, target: string | undefined, mapping: InputMapping, analysis: ReturnType<typeof graphPaths>): boolean {
+  if (mapping.kind != 'sources') return true
+  const { ancestors, paths } = analysis
+  if (target != null && mapping.sources.some((source) => source.kind == 'node' && !ancestors.get(target)?.has(source.nodeId))) return false
+  if (
+    target != null &&
+    mapping.sources.some(
+      (source) =>
+        source.kind == 'node' &&
+        isResolutionNode(graph.nodes[source.nodeId]) &&
+        !analysis.resolutionOutputs.get(target)?.has(resolutionOutputKey(source.nodeId, source.output)),
+    )
+  )
+    return false
+  const sources = mapping.sources.map((source) => sourcePaths(graph, paths, source))
+  const targetPaths = target == null ? [{}] : (paths.get(target) ?? [])
+  // Sources may be absent, but must never overlap on the same execution path.
+  for (const [index, routes] of sources.entries()) {
+    for (const other of sources.slice(index + 1)) {
+      for (const left of routes) {
+        for (const targetRoute of targetPaths) {
+          if (!routesCompatible(left, targetRoute)) continue
+          const path = { ...targetRoute, ...left }
+          if (other.some((right) => routesCompatible(right, path))) return false
+        }
+      }
+    }
+  }
+  return true
+}
+
+export type InputSourceCheck =
+  | { readonly kind: 'available' }
+  | { readonly kind: 'source-missing' }
+  | { readonly kind: 'output-missing' }
+  | { readonly kind: 'field-missing' }
+  | { readonly kind: 'not-ready' }
+  | { readonly kind: 'schema'; readonly mismatch: SchemaMismatch }
+  | { readonly kind: 'schema-error' }
+
+export type InputSourceCandidateCheck = Extract<InputSourceCheck, { readonly kind: 'available' | 'schema' | 'schema-error' }>
+
+interface InputSourceFieldCandidate {
+  readonly system?: true
+  readonly description?: string
+  readonly output: string
+  readonly field: string
+  readonly check: InputSourceCandidateCheck
+}
+
+export interface InputSourceCandidate {
+  readonly system?: true
+  readonly description?: string
+  readonly field?: string
+  readonly fields?: readonly InputSourceFieldCandidate[]
+  readonly output: string
+  readonly check: InputSourceCandidateCheck
+}
+
+export interface InputSourcesCheck {
+  readonly conflict: boolean
+  readonly sources: readonly InputSourceCheck[]
+}
+
+function sourceCompatibility(source: PortDefinition, input: PortDefinition): InputSourceCandidateCheck {
+  const result = comparePorts(source, input)
+  if (result.kind == 'compatible') return { kind: 'available' }
+  return result.kind == 'incompatible' ? { kind: 'schema', mismatch: result.mismatch } : { kind: 'schema-error' }
+}
+
+/** Check one saved binding without enumerating candidate ports. */
+export function checkInputSource(
+  graph: Graph,
+  target: string,
+  handle: string,
+  source: Pick<NodeSource, 'nodeId' | 'output' | 'field' | 'system'>,
+): InputSourceCheck {
+  const node = graph.nodes[source.nodeId]
+  const targetNode = graph.nodes[target]
+  if (node == null) return { kind: 'source-missing' }
+  if (targetNode == null) return { kind: 'not-ready' }
+  const output = nodeSourceOutputPorts(node, source.system)[source.output]
+  const input = nodeInputPorts(targetNode)[handle]
+  if (output == null) return { kind: 'output-missing' }
+  if (input == null) return { kind: 'not-ready' }
+  const analysis = graphPaths(graph)
+  if (analysis.ancestors.get(target)?.has(source.nodeId) !== true) return { kind: 'not-ready' }
+  if (isResolutionNode(node) && !analysis.resolutionOutputs.get(target)?.has(resolutionOutputKey(source.nodeId, source.output))) return { kind: 'not-ready' }
+  const selected = sourcePort(output, source.field)
+  if (selected == null) return { kind: 'field-missing' }
+  return sourceCompatibility(selected, input)
+}
+
+export function checkInputSources(
+  graph: Graph,
+  target: string,
+  handle: string,
+  sources: readonly Pick<NodeSource, 'nodeId' | 'output' | 'field' | 'system'>[],
+): InputSourcesCheck {
+  const checks = sources.map((source) => checkInputSource(graph, target, handle, source))
+  const conflict =
+    checks.length > 1 &&
+    checks.every((check) => check.kind == 'available') &&
+    !mappingAvailable(graph, target, { kind: 'sources', sources: sources.map((source) => ({ kind: 'node', ...source })) }, graphPaths(graph))
+  return { conflict, sources: checks }
+}
+
+/** Enumerate structurally available outputs while retaining their compatibility with one input. */
+export function inputSourceCandidates(graph: Graph, target: string, handle: string): Readonly<Record<string, readonly InputSourceCandidate[]>> {
+  const targetNode = graph.nodes[target]
+  const input = targetNode == null ? undefined : nodeInputPorts(targetNode)[handle]
+  if (input == null) return {}
+  const analysis = graphPaths(graph)
+  return Object.fromEntries(
+    [...(analysis.ancestors.get(target) ?? [])].flatMap((nodeId) => {
+      const node = graph.nodes[nodeId]
+      if (node == null) return []
+      const ports = [
+        ...Object.entries(nodeSourceOutputPorts(node)).map(([output, definition]) => ({ output, definition, system: undefined })),
+        ...Object.entries(nodeSystemOutputPorts(node)).map(([output, definition]) => ({ output, definition, system: true as const })),
+      ]
+      const outputs = ports.flatMap(({ output, definition, system }) => {
+        if (!mappingAvailable(graph, target, { kind: 'sources', sources: [{ kind: 'node', nodeId, output, ...(system ? { system } : {}) }] }, analysis))
+          return []
+        const check = sourceCompatibility(definition, input)
+        const fields = sourceFields(definition).map(({ field, port }) =>
+          Object.assign(
+            { output, field, ...(system ? { system } : {}), check: sourceCompatibility(port, input) },
+            port.description == null ? {} : { description: port.description },
+          ),
+        )
+        return [
+          {
+            ...(system ? { system } : {}),
+            ...(definition.description == null ? {} : { description: definition.description }),
+            output,
+            check,
+            ...(fields.length > 0 ? { fields } : {}),
+          },
+        ]
+      })
+      return outputs.length == 0 ? [] : [[nodeId, outputs]]
+    }),
+  )
+}
+
+export function availableOutputs(graph: Graph, target: string, handle: string | undefined): Readonly<Record<string, readonly string[]>> {
+  const analysis = graphPaths(graph)
+  return Object.fromEntries(
+    [...(analysis.ancestors.get(target) ?? [])].flatMap((id) => {
+      const node = graph.nodes[id]
+      if (node == null) return []
+      const outputs = Object.keys(nodeOutputPorts(node)).filter(
+        (output) =>
+          mappingAvailable(graph, target, { kind: 'sources', sources: [{ kind: 'node', nodeId: id, output }] }, analysis) &&
+          (handle == null || portsAssignable(nodeOutputPorts(node)[output]!, nodeInputPorts(graph.nodes[target]!)[handle]!)),
+      )
+      return outputs.length == 0 ? [] : [[id, outputs]]
+    }),
+  )
+}
+
+function validateResolution(nodeId: string, node: Extract<GraphNode, { readonly kind: 'approval' | 'wait' }>, path: string, diagnostics: Diagnostic[]): void {
+  const fields = new Set(['description', 'icon', 'inputDefinitions', 'inputs', 'kind', 'maxExecutions', 'name', 'prompt'])
+  if (node.kind == 'wait') {
+    fields.add('autoContinue')
+    if (node.autoContinue != null && !waitAutoContinueSchema.safeParse(node.autoContinue).success)
+      diagnostics.push(
+        graphDiagnostic('wait.auto-continue-invalid', 'Enter a positive integer duration or a timestamp with an explicit timezone.', `${path}/autoContinue`),
+      )
+  }
+  const label = node.kind == 'wait' ? 'Wait' : 'Approval'
+  const unsupported = Object.keys(node).filter((field) => !fields.has(field))
+  if (unsupported.length > 0) {
+    diagnostics.push(
+      graphDiagnostic(`${node.kind}.field-unsupported`, `${label} node "${nodeId}" contains unsupported fields: ${unsupported.join(', ')}.`, path, {
+        fields: unsupported.join(', '),
+        nodeId,
+      }),
+    )
+  }
+  const names = node.inputDefinitions.map((port) => port.handle)
+  if (new Set(names).size != names.length)
+    diagnostics.push(graphDiagnostic(`${node.kind}.input-invalid`, `${label} input names must be unique.`, `${path}/inputDefinitions`))
+  if (typeof node.prompt != 'string' || node.prompt.trim().length == 0 || [...node.prompt].length > 1_000) {
+    diagnostics.push(graphDiagnostic(`${node.kind}.prompt-invalid`, `${label} prompt must contain between 1 and 1,000 Unicode code points.`, `${path}/prompt`))
+  }
+}
+
+function validateGraph(graph: Graph, document: FlowDocument, path: string, diagnostics: Diagnostic[]): void {
+  const analysis = graphPaths(graph)
+  const errorTriggers = Object.entries(graph.nodes).filter(([, node]) => node.kind == 'error')
+  if (errorTriggers.length > 1)
+    for (const [nodeId] of errorTriggers)
+      diagnostics.push(graphDiagnostic('graph.error-trigger-duplicate', 'A graph can contain only one Flow Error node.', `${path}/nodes/${nodeId}`))
+  const outputNodes = Object.entries(graph.nodes).filter(([, node]) => node.kind == 'outputs')
+  for (const [nodeId, node] of Object.entries(graph.nodes)) {
+    if (node.kind == 'webhook') diagnostics.push(...webhookResponseDiagnostics(graph, nodeId, `${path}/nodes/${nodeId}`))
+    if (node.kind === 'webhook-response') {
+      const status = node.inputs.statusCode
+      if (status?.kind === 'value' && !validWebhookStatus(status.value))
+        diagnostics.push(
+          graphDiagnostic(
+            'webhook.response-status-invalid',
+            'Use an integer status from 200 to 599, excluding 204, 205 and 304.',
+            `${path}/nodes/${nodeId}/inputs/statusCode`,
+          ),
+        )
+      const headers = node.inputs.headers
+      if (
+        headers?.kind === 'value' &&
+        (webhookHeaderValues(headers.value) == null || Object.values(headers.value as Record<string, unknown>).some((value) => typeof value !== 'string'))
+      )
+        diagnostics.push(
+          graphDiagnostic(
+            'webhook.response-headers-invalid',
+            'Use valid, unique HTTP header names and single-line text values.',
+            `${path}/nodes/${nodeId}/inputs/headers`,
+          ),
+        )
+    }
+  }
+  if (outputNodes.length > 1)
+    for (const [nodeId] of outputNodes)
+      diagnostics.push(graphDiagnostic('graph.outputs-duplicate', 'A graph can contain only one Outputs node.', `${path}/nodes/${nodeId}`))
+  const startTriggers = Object.entries(graph.nodes).filter(([, node]) => node.kind == 'manual' || node.kind == 'start')
+  if (startTriggers.length > 1) {
+    for (const [nodeId] of startTriggers) {
+      diagnostics.push(graphDiagnostic('graph.start-trigger-duplicate', 'A graph can contain only one Start Trigger.', `${path}/nodes/${nodeId}`))
+    }
+  }
+  const seen = new Set<string>()
+  for (const [index, edge] of graph.edges.entries()) {
+    const edgePath = `${path}/edges/${index}`
+    const source = graph.nodes[edge.source]
+    const target = graph.nodes[edge.target]
+    if (source == null || source.kind == 'outputs' || target == null || isTriggerNode(target)) {
+      diagnostics.push(graphDiagnostic('graph.edge-invalid', 'Execution edges require an existing source and an executable target.', edgePath))
+    } else if (source.kind == 'condition' || isResolutionNode(source)) {
+      const exits = isResolutionNode(source) ? Object.keys(resolutionOutputPorts(source)) : [...source.cases.map((item) => item.output), otherwiseOutput]
+      if (edge.sourceHandle == null || !exits.some((exit) => exit == edge.sourceHandle)) {
+        diagnostics.push(graphDiagnostic('graph.edge-invalid', 'Choose a declared execution branch.', edgePath))
+      }
+    } else if (edge.sourceHandle != null) {
+      diagnostics.push(graphDiagnostic('graph.edge-invalid', 'Ordinary execution edges do not select a data output.', edgePath))
+    }
+    const key = JSON.stringify([edge.source, edge.sourceHandle, edge.target])
+    if (seen.has(key)) diagnostics.push(graphDiagnostic('graph.edge-duplicate', 'Execution edge is duplicated.', edgePath))
+    seen.add(key)
+  }
+  for (const [nodeId, node] of Object.entries(graph.nodes)) {
+    const nodePath = `${path}/nodes/${nodeId}`
+    if (!isTriggerNode(node) && node.maxExecutions != null && (!Number.isSafeInteger(node.maxExecutions) || node.maxExecutions < 1)) {
+      diagnostics.push(graphDiagnostic('node.max-executions-invalid', 'Maximum executions must be a positive safe integer.', `${nodePath}/maxExecutions`))
+    }
+    if (node.onError != null && (!supportsNodeErrorHandling(node) || !['stop', 'error'].includes(node.onError)))
+      diagnostics.push(graphDiagnostic('node.error-handling-invalid', 'This node does not support this error handling setting.', `${nodePath}/onError`))
+    if ('retry' in node && node.retry != null) {
+      if (!supportsNodeRetry(node)) diagnostics.push(graphDiagnostic('node.retry-unsupported', 'This node does not support retries.', `${nodePath}/retry`))
+      if (!retryConfigurationSchema.safeParse(node.retry).success)
+        diagnostics.push(graphDiagnostic('node.retry-invalid', 'Retries must be 0–5 with an interval of 1–60 whole seconds.', `${nodePath}/retry`))
+    }
+    if (isTriggerNode(node)) {
+      validateTrigger(nodeId, node, nodePath, diagnostics)
+      continue
+    }
+    for (const [handle, mapping] of Object.entries(nodeInputMappings(node))) {
+      if (!mappingAvailable(graph, nodeId, mapping, analysis))
+        diagnostics.push(
+          graphDiagnostic(
+            'graph.source-unavailable',
+            'Input sources must reference execution ancestors, respect pending Wait decisions, and never provide multiple values on the same path.',
+            node.kind == 'outputs' ? `${nodePath}/outputMappings/${handle.replaceAll('~', '~0').replaceAll('/', '~1')}` : `${nodePath}/inputs/${handle}`,
+          ),
+        )
+    }
+    const inputPorts = nodeInputPorts(node)
+    if (node.kind == 'task') {
+      const ports = [...node.task.inputs, ...(node.additionalInputs ?? [])]
+      const handles = new Set<string>()
+      for (const port of ports) {
+        if (!('handle' in port)) continue
+        if (handles.has(port.handle)) {
+          diagnostics.push(
+            graphDiagnostic('graph.input-duplicate', `Node "${nodeId}" declares input "${port.handle}" more than once.`, nodePath, {
+              handle: port.handle,
+              nodeId,
+            }),
+          )
+        }
+        handles.add(port.handle)
+      }
+    }
+    const ports = [...Object.values(inputPorts), ...Object.values(nodeOutputPorts(node))]
+    if (ports.some((port) => hasRetiredRef(port.jsonSchema))) {
+      diagnostics.push(graphDiagnostic('graph.schema-unsupported', 'Runtime Ref schemas are not supported.', nodePath))
+    }
+    const inputs = new Set(Object.keys(inputPorts))
+    for (const [handle, mapping] of Object.entries(nodeInputMappings(node))) {
+      const mappingPath =
+        node.kind == 'outputs' ? `${nodePath}/outputMappings/${handle.replaceAll('~', '~0').replaceAll('/', '~1')}` : `${nodePath}/inputs/${handle}`
+      if (!inputs.has(handle)) {
+        diagnostics.push(graphDiagnostic('graph.input-missing', `Node "${nodeId}" does not expose input "${handle}".`, mappingPath, { handle, nodeId }))
+      }
+      if (mapping.kind == 'sources') {
+        const variableSources = mapping.sources.filter((source) => source.kind == 'binding' && document.bindings[source.bindingId]?.kind == 'variable')
+        if (variableSources.length > 0 && (variableSources.length != 1 || mapping.sources.length != 1)) {
+          diagnostics.push(graphDiagnostic('graph.variable-source-mixed', 'A variable must be the only source for an input.', mappingPath))
+        }
+        for (const source of mapping.sources) checkSource(source, graph, document, inputPorts[handle], mappingPath, diagnostics)
+      }
+    }
+    if (isResolutionNode(node)) validateResolution(nodeId, node, nodePath, diagnostics)
+    if (node.kind != 'condition') continue
+    if (Object.keys(node.inputs).length > 0)
+      diagnostics.push(graphDiagnostic('condition.invalid', 'Condition cannot declare node inputs.', nodePath, { variant: 'inputs' }))
+    const outputs = new Set<string>([otherwiseOutput])
+    for (const [index, condition] of node.cases.entries()) {
+      const casePath = `${nodePath}/cases/${index}`
+      if (condition.output.trim().length == 0 || condition.output == '__proto__' || outputs.has(condition.output))
+        diagnostics.push(
+          graphDiagnostic('condition.invalid', 'Case output must be nonempty, unique, and not reserved.', `${casePath}/output`, { variant: 'output' }),
+        )
+      outputs.add(condition.output)
+      if (condition.groups.length == 0)
+        diagnostics.push(graphDiagnostic('condition.invalid', 'Case requires at least one group.', casePath, { variant: 'case' }))
+      for (const [g, group] of condition.groups.entries()) {
+        const groupPath = `${casePath}/groups/${g}`
+        if (group.expressions.length == 0)
+          diagnostics.push(graphDiagnostic('condition.invalid', 'Group requires at least one expression.', groupPath, { variant: 'group' }))
+        for (const [e, expression] of group.expressions.entries()) {
+          const expressionPath = `${groupPath}/expressions/${e}`
+          const type = (operand: typeof expression.left | undefined): string | undefined => {
+            if (operand == null || (operand.kind == 'value' && operand.value === undefined)) {
+              diagnostics.push(graphDiagnostic('condition.invalid', 'Condition operand is incomplete.', expressionPath, { variant: 'operand' }))
+              return
+            }
+            if (operand.kind == 'value') {
+              if (operand.jsonSchema != null && !matchesSchema(operand.value!, operand.jsonSchema))
+                diagnostics.push(graphDiagnostic('condition.invalid', 'Operand does not match its declared schema.', expressionPath, { variant: 'schema' }))
+              return valueType(operand.value!)
+            }
+            if (operand.source.kind === 'binding') return 'string'
+            const port = checkSource(operand.source, graph, document, undefined, expressionPath, [])
+            const raw = schemaObject(port?.jsonSchema ?? {})?.type
+            return typeof raw == 'string' ? raw : undefined
+          }
+          const left = type(expression.left)
+          const right = unaryOperator(expression.operator) ? undefined : type(expression.right)
+          if (unaryOperator(expression.operator) && expression.right != null)
+            diagnostics.push(graphDiagnostic('condition.invalid', 'Unary operators cannot have a right operand.', expressionPath, { variant: 'unary' }))
+          const issue = comparisonIssue(expression.operator, left, right)
+          if (issue != null) diagnostics.push(graphDiagnostic('condition.invalid', issue.message, expressionPath, { variant: 'type' }))
+        }
+      }
+    }
+  }
+}
+
+export function validateFlowGraph(revision: RevisionContent): readonly Diagnostic[] {
+  const diagnostics: Diagnostic[] = []
+  for (const [id, node] of Object.entries(revision.document.graph.nodes)) {
+    if (node.kind != 'start' && node.kind != 'outputs') continue
+    const field = node.kind == 'start' ? 'inputDefs' : 'outputDefs'
+    const ports = node.kind == 'start' ? node.inputDefs : node.outputDefs
+    const path = `/document/graph/nodes/${id.replaceAll('~', '~0').replaceAll('/', '~1')}/${field}`
+    if (new Set(ports.map((port) => port.handle)).size != ports.length)
+      diagnostics.push(graphDiagnostic('graph.port-duplicate', 'Workflow interface names must be unique.', path))
+    if (ports.some((port) => hasRetiredRef(port.jsonSchema)))
+      diagnostics.push(graphDiagnostic('graph.schema-unsupported', 'Runtime Ref schemas are not supported.', path))
+  }
+  for (const [bindingId, binding] of Object.entries(revision.document.bindings)) {
+    if (binding.kind == 'variable' && !validVariableName(binding.target)) {
+      diagnostics.push(
+        graphDiagnostic('binding.variable-invalid', `Variable binding "${bindingId}" has an invalid target.`, `/document/bindings/${bindingId}/target`, {
+          bindingId,
+        }),
+      )
+    }
+  }
+  validateGraph(revision.document.graph, revision.document, '/document/graph', diagnostics)
+  return diagnostics
+}