WDK gaps and how xFlow addresses each

// "use workflow" body re-runs from the top on every resume.
// Each await is an event; the sandbox replays the function until
// it reaches the next un-journaled await. 5,000 events ≈ near cap.
async function longAgent(input: AgentInput) {
  "use workflow"
  for (const tool of plan(input)) {
    const result = await callTool(tool)        // event
    await persistTrace(result)                  // event
    if (await needsApproval(result)) {          // event
      await waitForApproval()                   // event (suspend)
    }
  }
}

import { defineWorkflow, defineStep, link } from "@decoperations/xflow-core"

// Definitions are data. The runtime never re-runs the workflow body.
// On each appended event the substrate updates the FlowRun via reduceFlowRun;
// the scheduler reads current state and decides what's next.
const longAgent = defineWorkflow({
  id: "agent.long",
  version: "1.0.0",
  steps: {
    plan:    defineStep({ id: "plan",    type: "agent.plan",    sideEffects: { kind: "external", idempotencyRequired: true } }),
    execute: defineStep({ id: "execute", type: "agent.execute", sideEffects: { kind: "external", idempotencyRequired: true } }),
    persist: defineStep({ id: "persist", type: "agent.persist", sideEffects: { kind: "idempotent", idempotencyRequired: true } }),
  },
  links: [
    link("plan",    "execute", { when: { type: "step.succeeded" } }),
    link("execute", "persist", { when: { type: "step.succeeded" } }),
  ],
})

// 100,000 events on the run? Reducer cost is linear, runs once per change,
// no determinism sandbox, no replay timer. View is computed by the substrate
// (or cached). The scheduler reads it, picks the next step, fires it.

defineStep({
  id: "transcode",
  type: "media.transcode",
  // Only Docker peers (with ffmpeg) compete for this step
  placement: { required: ["docker", "ffmpeg-binary"] },
  // Lease-mode claim with hourly heartbeat
  claim: { mode: "lease", ttlMs: 60 * 60_000 },
  sideEffects: { kind: "external", idempotencyRequired: true },
})

// On the Docker box:
import { createXFlowRuntime } from "@decoperations/xflow-runtime"
import { detectLocalNode } from "@decoperations/xflow-provider-local"
import { xsyncSubstrate } from "@decoperations/xflow-substrate-xsync"

const runtime = createXFlowRuntime({
  node: detectLocalNode({ id: "render-box-1", capabilities: ["docker", "ffmpeg-binary"] }),
  substrate: xsyncSubstrate({ client: xsync }),
})

runtime.register("media.transcode", async (ctx, input) => {
  // Runs as long as needed. No 800s function cap.
  // Lease auto-extends via the substrate.
  await ctx.progress({ phase: "downloading" })
  const result = await runFfmpeg(input)
  await ctx.progress({ phase: "uploading" })
  return result
})

import { createXSync } from "@decoperations/xsync-client"
import { xflowS3WormStore } from "@decoperations/xflow-s3worm"
import { xsyncSubstrate } from "@decoperations/xflow-substrate-xsync"

const store = xflowS3WormStore({
  bucket: "xflow-prod",
  region: "us-east-1",
  // Cross-region replication is an S3 bucket setting; nothing else changes.
  // Retention is an S3 lifecycle policy on this bucket.
  endpoint: process.env.S3_ENDPOINT,
  rootPrefix: "tenants/acme",
})

const xsync = await createXSync({ store, views: { /* ... */ } })
const substrate = xsyncSubstrate({ client: xsync })

// In a Next.js client component:
"use client"

import { useEffect, useState } from "react"
import { useFlowRun } from "@decoperations/xflow-react"
import { createXFlowRuntime } from "@decoperations/xflow-runtime"
import { detectLocalNode } from "@decoperations/xflow-provider-local"
import { xsyncSubstrate } from "@decoperations/xflow-substrate-xsync"
import { createXSync } from "@decoperations/xsync-client"
import { flowRunView } from "@decoperations/xflow-substrate-xsync"

export function AgentSession({ runId, workflow }: Props) {
  const [handle, setHandle] = useState(null as any)

  useEffect(() => {
    void (async () => {
      // Browser-side xSync client (IndexedDB store, WS transport)
      const xsync = await createXSync({
        store: indexedDb(),
        transports: [websocket("/api/xsync")],
        views: { flowRun: flowRunView },
      })
      const substrate = xsyncSubstrate({ client: xsync })
      const runtime = createXFlowRuntime({
        node: detectLocalNode({ id: "browser", capabilities: ["browser-tab"] }),
        substrate,
      })

      // The browser registers an executor for an interactive step
      runtime.register("ui.confirm", async (ctx, input) => {
        return await showDialog(input)  // user clicks Approve
      })

      const h = await runtime.start({ workflow, runId })
      setHandle(h)
    })()
  }, [])

  // Reactive — re-renders on every event
  const run = useFlowRun(handle)
  return <RunTimeline run={run} />
}

import { defineStep } from "@decoperations/xflow-core"

// Irreversible — only the trusted server may execute
defineStep({
  id: "publish",
  type: "social.publish",
  claim: { mode: "authority", authorityActorId: "server-prod" },
  placement: { required: ["server"] },
  sideEffects: { kind: "irreversible", idempotencyRequired: true },
})

// Pure compute — any peer can compute, log resolves the winner
defineStep({
  id: "embed",
  type: "ai.embed",
  claim: { mode: "deterministic-election", tieBreaker: "lowest-hash" },
  sideEffects: { kind: "pure", idempotencyRequired: false },
})

// Cacheable — first valid output wins
defineStep({
  id: "summarize",
  type: "ai.summarize",
  claim: { mode: "optimistic-idempotent" },
  sideEffects: { kind: "idempotent", idempotencyRequired: false },
})

// Long-running — lease until TTL expiry, then queue re-opens
defineStep({
  id: "render",
  type: "media.render",
  claim: { mode: "lease", ttlMs: 30 * 60_000 },
  placement: { required: ["docker"] },
  sideEffects: { kind: "external", idempotencyRequired: true },
})

const mediaPipeline = defineWorkflow({
  id: "media.pipeline",
  version: "1.0.0",
  steps: {
    // Vercel function — short, cheap
    ingest: defineStep({
      id: "ingest", type: "media.ingest",
      placement: { required: ["server"], forbidden: ["browser-tab"] },
      sideEffects: { kind: "idempotent", idempotencyRequired: true },
    }),
    // Cloudflare edge — global, low-latency
    cdnSeed: defineStep({
      id: "cdnSeed", type: "media.cdn-seed",
      placement: { required: ["edge-worker"] },
      sideEffects: { kind: "idempotent", idempotencyRequired: true },
    }),
    // Docker box — GPU + ffmpeg
    transcode: defineStep({
      id: "transcode", type: "media.transcode",
      placement: { required: ["docker", "gpu"] },
      claim: { mode: "lease", ttlMs: 60 * 60_000 },
      sideEffects: { kind: "external", idempotencyRequired: true },
    }),
    // Browser tab — preview, optional, optimistic
    preview: defineStep({
      id: "preview", type: "media.preview",
      placement: { required: ["browser-tab"] },
      claim: { mode: "optimistic-idempotent" },
      sideEffects: { kind: "pure", idempotencyRequired: false },
    }),
  },
  links: [
    link("ingest", "cdnSeed"),
    link("ingest", "transcode"),
    link("transcode", "preview"),
  ],
})

import { reduceFlowRun, EVENT_TYPES, type XFlowEvent, type FlowRun } from "@decoperations/xflow-core"

// You can layer your own event types on top of xflow.* — and migrate them
// explicitly when shapes change. No sandbox, no replay drift.
function reduceWithMigration(state: FlowRun, event: XFlowEvent): FlowRun {
  // Your own event type whose payload changed v1 → v2
  if (event.type === "my-app.review.submitted") {
    const v = (event.payload as { version?: number }).version ?? 1
    if (v === 1) {
      // Migrate v1 payload shape into v2 before applying the v2 logic
      return applyReviewV2(state, migrateV1ToV2(event))
    }
    return applyReviewV2(state, event)
  }
  return reduceFlowRun(state, event)
}

// API endpoint: POST /api/workflows — tenant uploads a definition
import { defineWorkflow, type WorkflowDefinition } from "@decoperations/xflow-core"

export async function POST(req: Request) {
  const body = await req.json()
  const def = defineWorkflow(body) // throws if invalid
  await db.tenantWorkflows.put(req.tenantId, def.id, def)
  return Response.json({ id: def.id })
}

// Later: run a tenant-defined workflow
export async function startTenantWorkflow(tenantId: string, workflowId: string, input: unknown) {
  const def = await db.tenantWorkflows.get(tenantId, workflowId)
  return await runtime.start({ workflow: def, input })
}

// Definitions are just data. AI can generate them. UIs can edit them.
// Version history is a normal database concern.

// Works on Next, Nuxt, Astro, Hono, Vite, Bun, Deno, browser bundles —
// it's just JS. No "use workflow" directive, no SWC transform, no
// instrumentation.ts discovery rules.

import { defineWorkflow, defineStep, link } from "@decoperations/xflow-core"

export const ingest = defineWorkflow({
  id: "ingest.basic",
  version: "1.0.0",
  steps: {
    fetch: defineStep({ id: "fetch", type: "data.fetch", sideEffects: { kind: "external", idempotencyRequired: true } }),
    parse: defineStep({ id: "parse", type: "data.parse", sideEffects: { kind: "pure", idempotencyRequired: false } }),
  },
  links: [link("fetch", "parse")],
})