@oomol-lab/open-flow 0.1.0-beta.75 → 0.1.0-beta.77

package/src/state/common/conformance.ts

@@ -0,0 +1,86 @@
+import type { JsonValue } from '../../flow/common/model.ts'
+import type { DedupeConfig } from './state.ts'
+
+import { dequal } from 'dequal/lite'
+
+export interface StateConformanceHarness {
+  readonly maxIdentities: number
+  /** Executes Code on the same initially empty Flow and scope on every call; returns its `result` output. */
+  run(source: string): Promise<JsonValue>
+  /** Executes the same dedupe node across Runs, updating its business config and items. */
+  dedupe(config: DedupeConfig, items: JsonValue[]): Promise<{ items: JsonValue[]; duplicates: JsonValue[] }>
+}
+
+export const stateConformanceCases: readonly { name: string; verify(harness: StateConformanceHarness): Promise<void> }[] = [
+  {
+    name: 'persists watermarks by instant and resets changed modes atomically',
+    async verify(harness) {
+      const config: DedupeConfig = { field: '', mode: 'increasing', space: 'node' }
+      const first = await harness.dedupe(config, ['2026-10-30T09:00:00+08:00', '2026-10-30T01:00:00Z', '2026-10-30T02:00:00Z'])
+      if (!dequal(first, { items: ['2026-10-30T09:00:00+08:00', '2026-10-30T02:00:00Z'], duplicates: ['2026-10-30T01:00:00Z'] }))
+        throw new Error('Watermarks must compare instants and preserve item order.')
+      let rejected = false
+      try {
+        await harness.dedupe(config, [1])
+      } catch {
+        rejected = true
+      }
+      if (!rejected) throw new Error('Mixed watermark types must fail.')
+      const second = await harness.dedupe(config, ['2026-10-30T02:00:00Z', '2026-10-30T03:00:00Z'])
+      if (!dequal(second, { items: ['2026-10-30T03:00:00Z'], duplicates: ['2026-10-30T02:00:00Z'] }))
+        throw new Error('A failed batch must preserve the previous watermark.')
+      await harness.dedupe({ ...config, mode: 'new' }, [])
+      const reset = await harness.dedupe(config, [5, 3, 5])
+      if (!dequal(reset, { items: [5, 3], duplicates: [5] })) throw new Error('A mode reset must discard previous watermarks, including on empty batches.')
+    },
+  },
+  {
+    name: 'round-trips independent JSON values and deletes without exposing stored references',
+    async verify(harness) {
+      const result = await harness.run(`export default async (_, context) => {
+        await context.state.set('b', { nested: [1, null, false] });
+        const copy = await context.state.get('b');
+        copy.nested.push(2);
+        const retained = await context.state.get('b');
+        const inserted = await context.state.insert('b', 'replacement');
+        await context.state.set('a', 0);
+        const keys = await context.state.list();
+        await context.state.delete('a');
+        await context.state.set('b', null);
+        return {result: {retained, inserted, keys, missing: await context.state.get('a'), remaining: await context.state.list()}};
+      }`)
+      if (!dequal(result, { retained: { nested: [1, null, false] }, inserted: false, keys: ['a', 'b'], missing: null, remaining: [] }))
+        throw new Error('State JSON round-trip, conditional insertion or deletion differs from the contract.')
+    },
+  },
+  {
+    name: 'persists explicit values and dedupe history across Runs',
+    async verify(harness) {
+      const source = `export default async (_, context) => {
+        const first = await context.state.insert('count', 0);
+        const count = await context.state.get('count');
+        await context.state.set('count', count + 1);
+        return { result: { first, count, ids: await context.dedupe.insert(['a', 'a']) } };
+      }`
+      if (
+        !dequal(await harness.run(source), { first: true, count: 0, ids: [true, false] }) ||
+        !dequal(await harness.run(source), { first: false, count: 1, ids: [false, false] })
+      )
+        throw new Error('State must persist across Runs without replacing existing values on insert.')
+    },
+  },
+  {
+    name: 'rejects a full batch atomically while permitting duplicates at capacity',
+    async verify(harness) {
+      const result = await harness.run(`export default async (_, context) => {
+        const ids = Array.from({length: ${harness.maxIdentities}}, (_, index) => index);
+        await context.dedupe.insert(ids);
+        let error;
+        try { await context.dedupe.insert([0, 'extra']); } catch (failure) { error = failure.code; }
+        return { result: { error, extra: await context.dedupe.has(['extra']), duplicate: await context.dedupe.insert([0, 0]) } };
+      }`)
+      if (!dequal(result, { error: 'dedupe.full', extra: [false], duplicate: [false, false] }))
+        throw new Error('Dedupe capacity must fail atomically and preserve duplicate membership.')
+    },
+  },
+]

package/src/state/common/state.ts

@@ -0,0 +1,169 @@
+import type { JsonValue, ManagedTaskDefinitionOf } from '../../flow/common/model.ts'
+
+import { z } from 'zod'
+
+export { stateConformanceCases, type StateConformanceHarness } from './conformance.ts'
+
+export type StateScope = 'draft' | 'live'
+export const stateQuerySchema = z.strictObject({ scope: z.enum(['draft', 'live']), values: z.boolean().optional() })
+export const stateClearSchema = z.strictObject({
+  scope: z.enum(['draft', 'live']),
+  key: z
+    .string()
+    .min(1)
+    .refine((key) => new TextEncoder().encode(key).length <= 256)
+    .optional(),
+})
+export const dedupeClearSchema = z.strictObject({ scope: z.enum(['draft', 'live']), space: z.string().regex(/^(flow|node:.+)$/) })
+export type DedupeIdentity = string | number
+export const dedupeConfigSchema = z.strictObject({
+  field: z.string().default(''),
+  mode: z.enum(['new', 'increasing']).default('new'),
+  space: z.enum(['node', 'flow']).default('node'),
+})
+export type DedupeConfig = z.infer<typeof dedupeConfigSchema>
+export interface DedupeExecutor extends DedupeConfig {
+  readonly kind: 'dedupe'
+}
+export const dedupeExecutorSchema = dedupeConfigSchema.extend({ kind: z.literal('dedupe') })
+
+export function dedupeTask(config: DedupeConfig = dedupeConfigSchema.parse({}), name = 'Remove Duplicates'): ManagedTaskDefinitionOf<DedupeExecutor> {
+  return {
+    name,
+    executor: { ...config, kind: 'dedupe' },
+    inputs: [{ handle: 'items', jsonSchema: { type: 'array' }, nullable: false }],
+    outputs: ['items', 'duplicates'].map((handle) => ({ handle, jsonSchema: { type: 'array' }, nullable: false })),
+  }
+}
+
+export class StateError extends Error {
+  readonly retryable = false
+  readonly catchable: boolean
+  readonly code: 'capability.invalid' | 'capability.denied' | 'dedupe.full' | 'limit-exceeded'
+
+  constructor(code: StateError['code'], message: string) {
+    super(message)
+    this.name = 'StateError'
+    this.code = code
+    this.catchable = code === 'dedupe.full'
+  }
+}
+
+export function stateKey(key: unknown): string {
+  if (typeof key !== 'string' || key.length === 0 || new TextEncoder().encode(key).length > 256)
+    throw new StateError('capability.invalid', 'State keys require 1 to 256 UTF-8 bytes.')
+  return key
+}
+
+export function dedupeIdentities(value: unknown): DedupeIdentity[] {
+  if (!Array.isArray(value) || !Array.from(value).every((id) => typeof id === 'string' || (typeof id === 'number' && Number.isFinite(id))))
+    throw new StateError('capability.invalid', 'Identities must be strings or finite numbers.')
+  return value
+}
+
+export async function hashIdentities(ids: readonly DedupeIdentity[]): Promise<Uint8Array[]> {
+  return Promise.all(
+    ids.map(async (id) => new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${typeof id}:${String(id)}`))).slice(0, 16)),
+  )
+}
+
+export function watermarkValue(id: DedupeIdentity): number {
+  if (typeof id === 'number') {
+    if (!Number.isFinite(id)) throw new StateError('capability.invalid', 'Watermarks must be finite.')
+    return id
+  }
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(id)
+  if (match == null) throw new StateError('capability.invalid', 'Watermarks require RFC 3339 timestamps with an explicit timezone.')
+  const [, year, month, day, hour, minute, second, , zone] = match
+  const y = Number(year)
+  const days = [31, y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][Number(month) - 1] ?? 0
+  const result = Date.parse(id)
+  if (
+    Number(month) < 1 ||
+    Number(month) > 12 ||
+    Number(day) < 1 ||
+    Number(day) > days ||
+    Number(hour) > 23 ||
+    Number(minute) > 59 ||
+    Number(second) > 59 ||
+    (zone !== 'Z' && (Number(zone!.slice(1, 3)) > 23 || Number(zone!.slice(4)) > 59)) ||
+    !Number.isFinite(result)
+  )
+    throw new StateError('capability.invalid', 'Watermarks require valid calendar timestamps.')
+  return result
+}
+
+export function increasingIdentities(ids: readonly DedupeIdentity[], watermark: DedupeIdentity | null) {
+  const type = typeof (watermark ?? ids[0])
+  if (ids.some((id) => typeof id !== type)) throw new StateError('capability.invalid', 'Watermark types must not be mixed.')
+  const initial = watermark == null ? -Infinity : watermarkValue(watermark)
+  const seen = new Set<number>()
+  let maximum = initial
+  let next = watermark
+  const inserted = ids.map((id) => {
+    const value = watermarkValue(id)
+    const fresh = value > initial && !seen.has(value)
+    seen.add(value)
+    if (value > maximum) {
+      maximum = value
+      next = id
+    }
+    return fresh
+  })
+  return { inserted, watermark: next }
+}
+
+export function itemIdentities(items: JsonValue, field: string): DedupeIdentity[] {
+  if (!Array.isArray(items)) throw new StateError('capability.invalid', 'Deduplication requires an array of items.')
+  const path = field === '' ? [] : field.split('.')
+  return dedupeIdentities(
+    items.map((item) =>
+      path.reduce<JsonValue | undefined>(
+        (value, key) => (value != null && typeof value === 'object' && Object.hasOwn(value, key) ? (value as Record<string, JsonValue>)[key] : undefined),
+        item,
+      ),
+    ),
+  )
+}
+
+export interface FlowStateView {
+  readonly version: 1
+  readonly scope: StateScope
+  readonly limits: {
+    readonly maxValueBytes: number
+    readonly maxValues: number
+    readonly maxSpaces: number
+    readonly maxIdentities: number
+    readonly maxRunWrites: number
+  }
+  readonly values: readonly { readonly key: string; readonly size: number; readonly updatedAt: number; readonly value?: JsonValue }[]
+  readonly spaces: readonly {
+    readonly space: string
+    readonly mode: 'new' | 'increasing'
+    readonly count: number
+    readonly watermark: DedupeIdentity | null
+    readonly updatedAt: number
+  }[]
+}
+
+export const flowStateViewSchema = z.object({
+  version: z.literal(1),
+  scope: z.enum(['draft', 'live']),
+  limits: z.object({
+    maxValueBytes: z.number().positive(),
+    maxValues: z.number().int().positive(),
+    maxSpaces: z.number().int().positive(),
+    maxIdentities: z.number().positive(),
+    maxRunWrites: z.number().positive(),
+  }),
+  values: z.array(z.object({ key: z.string(), size: z.number().nonnegative(), updatedAt: z.number(), value: z.json().optional() })),
+  spaces: z.array(
+    z.object({
+      space: z.string(),
+      mode: z.enum(['new', 'increasing']),
+      count: z.number().nonnegative(),
+      watermark: z.union([z.string(), z.number(), z.null()]),
+      updatedAt: z.number(),
+    }),
+  ),
+})

package/src/trigger/common/config.ts

@@ -1,4 +1,4 @@
-import type { Group, InputPort, InputValues, JsonValue } from '../../flow/common/change.ts'
+import type { Group, InputPort, InputValues, JsonValue } from '../../flow/common/model.ts'
 
 import { inputValue } from '../../flow/common/inputValue.ts'
 import { matchesSchema } from '../../flow/common/schema.ts'

package/src/trigger/common/configOptions.ts

@@ -1,5 +1,5 @@
 import type { ConnectorProxy } from '../../connector/common/proxy.ts'
-import type { JsonValue } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../flow/common/model.ts'
 
 export interface TriggerConfigOption {
   readonly value: string

package/src/trigger/common/contract.ts

@@ -1,4 +1,5 @@
-import type { JsonValue, Port, PortDefinition, TriggerNode } from '../../flow/common/change.ts'
+import type { JsonValue, Port, PortDefinition } from '../../flow/common/model.ts'
+import type { TriggerNode } from './model.ts'
 
 import { isJsonObject } from '../../base/common/json.ts'
 import { matchesSchema } from '../../flow/common/schema.ts'

package/src/trigger/common/cron.ts

@@ -1,4 +1,5 @@
-import type { JsonValue, TriggerSchedule } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../flow/common/model.ts'
+import type { TriggerSchedule } from './model.ts'
 
 import { Cron } from 'croner'
 

package/src/trigger/common/integration.ts

@@ -1,7 +1,8 @@
 export { resolveTriggerConfig, triggerConfigValues } from './config.ts'
 import type { ConnectorProxy } from '../../connector/common/proxy.ts'
-import type { IntegrationEndpointMethod, JsonValue, TriggerKeySnapshot } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../flow/common/model.ts'
 import type { TriggerConfigOption, TriggerConfigOptionsContext } from './configOptions.ts'
+import type { IntegrationEndpointMethod, TriggerKeySnapshot } from './model.ts'
 
 import { dequal } from 'dequal/lite'
 import { isJsonObject, isJsonValue } from '../../base/common/json.ts'

package/src/trigger/common/model.ts

@@ -0,0 +1,87 @@
+import type { Group, InputPort, InputValues, Port } from '../../flow/common/model.ts'
+import type { WebhookMethod } from '../../flow/common/webhookMethod.ts'
+
+/** Trigger node shapes. The graph node union and its operations belong to flow/common/change.ts. */
+
+export type TriggerSchedule =
+  | { readonly expression: string; readonly timezone: string; readonly type: 'cron' }
+  | { readonly type: 'every'; readonly unit: 'day' | 'hour' | 'minute' | 'month' | 'week'; readonly value: number }
+
+interface TriggerKeySnapshotBase {
+  readonly configInputs: readonly (InputPort | Group)[]
+  readonly definitionVersion: number
+  readonly description: string
+  readonly displayName: string
+  readonly key: string
+  readonly name: string
+  readonly outputs: readonly Port[]
+  readonly provider: string
+}
+
+export type IntegrationEndpointMethod = 'DELETE' | 'GET' | 'HEAD' | 'PATCH' | 'POST' | 'PUT'
+
+export type IntegrationBodyFormat = 'form' | 'json' | 'multipart' | 'text'
+
+export interface IntegrationEndpointDeclaration {
+  readonly body: {
+    readonly allowArray: boolean
+    readonly allowEmpty: boolean
+    readonly formats: readonly IntegrationBodyFormat[]
+  }
+  readonly methods: readonly IntegrationEndpointMethod[]
+  readonly successStatus: number
+}
+
+export type TriggerKeySnapshot =
+  | (TriggerKeySnapshotBase & { readonly type: 'poll' })
+  | (TriggerKeySnapshotBase & { readonly endpoint: IntegrationEndpointDeclaration; readonly type: 'integration' })
+
+export interface WebhookBodyField extends InputPort {}
+
+export interface WebhookOptions {
+  readonly allowedOrigins?: readonly string[]
+  readonly responseBody?:
+    | { readonly kind: 'workflow-outputs'; readonly output?: string; readonly timeoutMs?: number }
+    | { readonly kind: 'webhook-response'; readonly nodeId?: string; readonly timeoutMs?: number }
+  readonly responseData?: string
+  readonly responseHeaders?: Readonly<Record<string, string>>
+  readonly responseHeadersSource?: {
+    readonly kind: 'workflow-outputs'
+    readonly output?: string
+  }
+  readonly responseHeaderOutputs?: Readonly<Record<string, string>>
+  readonly responseStatusCode?: number
+  readonly responseStatusCodeOutput?: string
+}
+
+interface TriggerNodeBase {
+  readonly onError?: never
+  readonly description?: string
+  readonly icon?: string
+  readonly name: string
+}
+
+export type TriggerNode =
+  | (TriggerNodeBase & { readonly kind: 'manual' })
+  | (TriggerNodeBase & { readonly kind: 'start'; readonly inputDefs: readonly Port[] })
+  | (TriggerNodeBase & { readonly kind: 'error'; readonly sourceFlowIds?: readonly string[] })
+  | (TriggerNodeBase & {
+      readonly bodyFields: readonly WebhookBodyField[]
+      readonly kind: 'webhook'
+      readonly method: WebhookMethod
+      readonly options?: WebhookOptions
+    })
+  | (TriggerNodeBase & { readonly cronTimes: readonly TriggerSchedule[]; readonly kind: 'cron' })
+  | (TriggerNodeBase & {
+      readonly connectionId?: string
+      readonly config: InputValues
+      readonly definition: TriggerKeySnapshot & { readonly type: 'poll' }
+      readonly kind: 'poll'
+      readonly pollTimes: readonly TriggerSchedule[]
+    })
+  | (TriggerNodeBase & {
+      readonly connectionId?: string
+      readonly config: InputValues
+      readonly definition: TriggerKeySnapshot & { readonly type: 'integration' }
+      readonly kind: 'integration'
+    })

package/src/trigger/common/poll.ts

@@ -1,7 +1,8 @@
 export { resolveTriggerConfig, triggerConfigValues } from './config.ts'
 import type { ConnectorProxy } from '../../connector/common/proxy.ts'
-import type { JsonValue, TriggerKeySnapshot, TriggerSchedule } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../flow/common/model.ts'
 import type { TriggerConfigOption, TriggerConfigOptionsContext } from './configOptions.ts'
+import type { TriggerKeySnapshot, TriggerSchedule } from './model.ts'
 
 const encoder = new TextEncoder()
 

package/src/trigger/common/webhook.ts

@@ -1,4 +1,6 @@
-import type { JsonValue, WebhookBodyField, WebhookMethod, WebhookOptions } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../flow/common/model.ts'
+import type { WebhookMethod } from '../../flow/common/webhookMethod.ts'
+import type { WebhookBodyField, WebhookOptions } from './model.ts'
 
 import { dequal } from 'dequal/lite'
 import { isJsonObject } from '../../base/common/json.ts'

package/src/trigger/providers/fieldDescriptions.ts

@@ -1,4 +1,4 @@
-import type { TriggerDisplay } from '../../control/common/triggerCatalog.ts'
+import type { TriggerDisplay } from './localization.ts'
 
 type FieldDescriptions = Pick<TriggerDisplay, 'configInputs' | 'outputs'>
 

package/src/trigger/providers/localization.ts

@@ -1,10 +1,17 @@
-import type { TriggerDisplay } from '../../control/common/triggerCatalog.ts'
-import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
 import type { UiLanguage } from '../../localization/common/languages.ts'
+import type { TriggerKeySnapshot } from '../common/model.ts'
 
 import { englishTriggerFieldDescriptions } from './fieldDescriptions.ts'
 import { triggerConfigFieldLabels } from './fieldLabels.ts'
 
+export interface TriggerDisplay {
+  readonly configInputs: Readonly<Record<string, string>>
+  readonly configInputLabels: Readonly<Record<string, string>>
+  readonly displayName: string
+  readonly description: string
+  readonly outputs: Readonly<Record<string, string>>
+}
+
 type Translations = Readonly<Record<string, Partial<TriggerDisplay>>>
 
 const loaders = {

package/src/trigger/providers/remote.ts

@@ -1,5 +1,4 @@
 import type { ConnectorProxy, TriggerOperationRequest } from '../../connector/common/proxy.ts'
-import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
 import type { TriggerConfigOption } from '../common/configOptions.ts'
 import type {
   IntegrationDefinition,
@@ -8,6 +7,7 @@ import type {
   IntegrationStateContext,
   ListenerPage,
 } from '../common/integration.ts'
+import type { TriggerKeySnapshot } from '../common/model.ts'
 import type { PollDefinition, PollResult } from '../common/poll.ts'
 
 import { isJsonObject } from '../../base/common/json.ts'

package/src/types/index.ts

@@ -22,21 +22,56 @@ export interface ArtifactRef {
   readonly kind: 'artifact'
   readonly id: string
   readonly name: string
-  readonly mediaType: string | undefined
+  readonly mediaType?: string
   readonly size: number
   readonly digest: string
 }
 
 export interface ArtifactPutOptions {
   readonly name: string
-  readonly mediaType?: string | undefined
+  readonly mediaType?: string
 }
 
-export type ArtifactData = Uint8Array | Blob | ReadableStream<Uint8Array>
+/** Strings are stored as UTF-8. */
+export type ArtifactData = string | Uint8Array
 
+/** Artifacts belong to the current Run; an ArtifactRef is JSON and can be passed to downstream nodes. */
 export interface ArtifactCapability {
   put(data: ArtifactData, options: ArtifactPutOptions): Promise<ArtifactRef>
-  open(ref: ArtifactRef): Promise<ReadableStream<Uint8Array>>
+  open(ref: ArtifactRef): Promise<Uint8Array>
+}
+
+export interface TaskFetchInit {
+  /** GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS. */
+  readonly method?: string
+  readonly headers?: Readonly<Record<string, string>> | Iterable<readonly [string, string]>
+  /** At most 1 MiB; strings are sent as UTF-8 text/plain unless a content-type header is supplied. */
+  readonly body?: string | Uint8Array | ArrayBuffer
+  readonly signal?: AbortSignal
+}
+
+export interface TaskFetchHeaders extends Iterable<[string, string]> {
+  get(name: string): string | null
+  has(name: string): boolean
+  entries(): IterableIterator<[string, string]>
+  keys(): IterableIterator<string>
+  values(): IterableIterator<string>
+  forEach(callback: (value: string, name: string) => void): void
+}
+
+/** A read-only subset of the Fetch Response; the body is buffered, at most 1 MiB, and readable once. */
+export interface TaskFetchResponse {
+  readonly status: number
+  readonly statusText: string
+  readonly ok: boolean
+  readonly redirected: false
+  readonly url: string
+  readonly headers: TaskFetchHeaders
+  readonly bodyUsed: boolean
+  bytes(): Promise<Uint8Array>
+  arrayBuffer(): Promise<ArrayBuffer>
+  text(): Promise<string>
+  json(): Promise<unknown>
 }
 
 export interface MediaPreviewPayload {
@@ -73,13 +108,6 @@ export interface CsvPreviewPayload {
 export type PreviewPayload = MediaPreviewPayload | TextPreviewPayload | ImagePreviewPayload | TablePreviewPayload | CsvPreviewPayload
 export type PreviewType = PreviewPayload['type']
 
-export interface TaskLogger {
-  debug(message: string, data?: unknown): void
-  info(message: string, data?: unknown): void
-  warn(message: string, data?: unknown): void
-  error(message: string, data?: unknown): void
-}
-
 export interface TaskContext<
   Actions extends object = Record<string, never>,
   Workflows extends object = { call: (name: never, input?: never) => Promise<never> },
@@ -91,13 +119,25 @@ export interface TaskContext<
   readonly inputs: Readonly<Record<string, unknown>>
   readonly runId: string
   readonly blockId: string
+  readonly state: {
+    get(key: string): Promise<JsonValue | null>
+    set(key: string, value: JsonValue): Promise<void>
+    insert(key: string, value: Exclude<JsonValue, null>): Promise<boolean>
+    delete(key: string): Promise<void>
+    list(): Promise<string[]>
+  }
+  readonly dedupe: {
+    insert(ids: readonly (string | number)[]): Promise<boolean[]>
+    has(ids: readonly (string | number)[]): Promise<boolean[]>
+  }
   readonly artifact: ArtifactCapability
-  readonly fetch: typeof fetch
-  readonly logger: TaskLogger
   /** Reads the selected direct predecessors, sorted by node ID; empty for a graph root. */
   getPrevious(): Promise<readonly PreviousNode[]>
-  preview(payload: PreviewPayload, id?: string): Promise<void>
-  reportProgress(progress: number): Promise<void>
+  /**
+   * Calls an HTTP(S) URL whose host the node declares in its `http` Capability. Redirects are returned, not followed,
+   * and no platform credentials are added. Network failures reject with a TypeError.
+   */
+  fetch(input: string | URL, init?: TaskFetchInit): Promise<TaskFetchResponse>
 }
 
 export type TaskResult<Outputs extends object> = keyof Outputs extends never ? Outputs | void : Outputs

package/src/workflow/common/workflow.ts

@@ -1,23 +1,11 @@
-import type {
-  TaskNode,
-  ManagedTaskDefinition,
-  Port,
-  JsonValue,
-  RevisionContent,
-  GraphNode,
-  WorkflowCapability,
-  AgentWorkflowTool,
-} from '../../flow/common/change.ts'
+import type { TaskNode, ManagedTaskDefinition, Port, JsonValue, RevisionContent, WorkflowCapability, AgentWorkflowTool } from '../../flow/common/change.ts'
 
 import { dequal } from 'dequal/lite'
 import { z } from 'zod'
 import { comparePorts, matchesSchema } from '../../flow/common/schema.ts'
 
-export interface WorkflowExecutor {
-  readonly kind: 'workflow'
-  readonly flowId: string
-  readonly revisionId: string
-}
+export type { WorkflowExecutor } from '../../flow/common/model.ts'
+export { nodeWorkflowReferences } from '../../flow/common/workflowReferences.ts'
 
 const portSchema = z.object({
   handle: z.string().min(1),
@@ -183,35 +171,6 @@ export const workflowReferencesSchema = z.object({
 })
 export type WorkflowReferences = z.infer<typeof workflowReferencesSchema>
 
-/** Workflow declarations share discovery across authoring, admission and resource indexing. */
-export function nodeWorkflowReferences(node: GraphNode): readonly {
-  readonly target: Omit<WorkflowCapability, 'kind' | 'name'>
-  readonly path: string
-  readonly tool?: string
-}[] {
-  if (node.kind != 'task') return []
-  if ('moduleId' in node.task)
-    return (node.task.capabilities ?? []).flatMap((item, index) =>
-      item.kind == 'workflow' ? [{ target: item, path: `task/capabilities/${index}`, tool: item.name }] : [],
-    )
-  if (node.task.executor.kind == 'workflow')
-    return [
-      {
-        target: {
-          ...node.task.executor,
-          inputs: node.task.inputs.filter((port) => 'handle' in port),
-          outputs: node.task.outputs.filter((port) => 'handle' in port),
-        },
-        path: 'task/executor',
-      },
-    ]
-  if (node.task.executor.kind == 'agent')
-    return node.task.executor.tools.flatMap((item, index) =>
-      item.kind == 'workflow' ? [{ target: item, path: `task/executor/tools/${index}`, tool: item.name }] : [],
-    )
-  return []
-}
-
 export function workflowCapability(name: string, target: WorkflowContract | WorkflowCandidate): WorkflowCapability {
   return {
     kind: 'workflow',