fix workflow runtime release surface

Author: tannerlinsley

.github/pull_request_template.md

@@ -4,7 +4,7 @@
 
 ## ✅ Checklist
 
-- [ ] I have followed the steps in the [Contributing guide](https://github.com/TanStack/template/blob/main/CONTRIBUTING.md).
+- [ ] I have followed the steps in the [Contributing guide](https://github.com/TanStack/workflow/blob/main/CONTRIBUTING.md).
 - [ ] I have tested this code locally with `pnpm run test:pr`.
 
 ## 🚀 Release Impact

CONTRIBUTING.md

@@ -7,11 +7,11 @@ id: contributing
 
 ## Questions
 
-If you have questions about implementation details, help or support, then please use our dedicated community forum at [Github Discussions](https://github.com/tanstack/template/discussions) **PLEASE NOTE:** If you choose to instead open an issue for your question, your issue will be immediately closed and redirected to the forum.
+If you have questions about implementation details, help, or support, use [GitHub Discussions](https://github.com/tanstack/workflow/discussions). Issues should be reserved for reproducible bugs and concrete feature requests.
 
 ## Reporting Issues
 
-If you have found what you think is a bug, please [file an issue](https://github.com/tanstack/template/issues/new). **PLEASE NOTE:** Issues that are identified as implementation questions or non-issues will be immediately closed and redirected to [Github Discussions](https://github.com/tanstack/template/discussions)
+If you have found what you think is a bug, please [file an issue](https://github.com/tanstack/workflow/issues/new) with a minimal reproduction and the expected behavior.
 
 ## Suggesting new features
 
@@ -27,7 +27,7 @@ Before proceeding with development, ensure you match one of the following criter
 
 ## Development Workflow
 
-- Fork this repository, we prefer the `feat-*` branch name style
+- Fork this repository; we prefer the `feat-*` branch name style
 - Ensure you have `pnpm` installed
 - Install projects dependencies and linkages by running `pnpm install`
 - Auto-build and auto-test files as you edit by running `pnpm dev`

README.md

@@ -1,130 +1,87 @@
-<div align="center">
-  <img src="./media/header_template.png" alt="TanStack Template" />
-</div>
+# TanStack Workflow
 
-<br />
+Type-safe durable execution for TypeScript. Workflows are ordinary async functions that can pause, persist progress to an append-only log, and resume after approvals, webhooks, timers, or process restarts.
 
-<div align="center">
-  <a href="https://www.npmjs.com/package/@tanstack/template" target="\_parent">
-    <img alt="npm downloads" src="https://img.shields.io/npm/dm/@tanstack/template.svg" />
-  </a>
-  <a href="https://github.com/TanStack/template" target="\_parent">
-    <img alt="GitHub stars" src="https://img.shields.io/github/stars/TanStack/template.svg?style=social&label=Star" />
-  </a>
-  <a href="https://bundlephobia.com/result?p=@tanstack/react-template@latest" target="\_parent">
-    <img alt="Bundle size" src="https://badgen.net/bundlephobia/minzip/@tanstack/react-template@latest" />
-  </a>
-</div>
-
-<div align="center">
-  <a href="#badge">
-    <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
-  </a>
-  <a href="#badge">
-    <img src="https://img.shields.io/github/v/release/tanstack/template" alt="Release"/>
-  </a>
-  <a href="https://twitter.com/tan_stack">
-    <img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
-  </a>
-</div>
-
-<div align="center">
-
-### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
-
-</div>
-
-# TanStack Template
-
-> [!NOTE]
-> TanStack Template is a starting point for new TanStack libraries. Replace this README content with product-specific copy before release.
-
-Build a TanStack library with a framework-agnostic core, React and Solid adapters, devtools packages, documentation, examples, CI, release automation, and package quality checks already wired together.
+```bash
+pnpm add @tanstack/workflow-core
+```
 
-- Framework-agnostic core package ready for domain logic
-- React and Solid adapters with matching examples and docs structure
-- Devtools package placeholders for framework-specific integrations
-- pnpm, Nx, TypeScript, tsdown, Vitest, ESLint, Prettier, Changesets, and TypeDoc setup
-- GitHub workflows for PR checks, release, preview publishing, provenance, and autofix
+Install `zod` or another Standard Schema-compatible library if you want runtime validation for workflow inputs, outputs, state, or signal payloads.
+
+## Example
+
+```ts
+import {
+  createWorkflow,
+  inMemoryRunStore,
+  runWorkflow,
+} from '@tanstack/workflow-core'
+import { z } from 'zod'
+
+const checkout = createWorkflow({
+  id: 'checkout',
+  input: z.object({ userId: z.string(), amount: z.number() }),
+  output: z.object({ status: z.enum(['approved', 'rejected']) }),
+}).handler(async (ctx) => {
+  const charge = await ctx.step('charge-card', (stepCtx) =>
+    stripe.charges.create(
+      { customer: ctx.input.userId, amount: ctx.input.amount },
+      { idempotencyKey: stepCtx.id },
+    ),
+  )
+
+  if (ctx.input.amount > 10_000) {
+    const decision = await ctx.approve({ title: 'Approve large charge?' })
+    if (!decision.approved) return { status: 'rejected' as const }
+  }
+
+  await ctx.step('send-receipt', () => sendReceipt(charge.id))
+  return { status: 'approved' as const }
+})
+
+const store = inMemoryRunStore()
+
+for await (const event of runWorkflow({
+  workflow: checkout,
+  input: { userId: 'cus_123', amount: 4200 },
+  runStore: store,
+})) {
+  console.log(event.type, event)
+}
+```
 
-### <a href="https://tanstack.com/template">Read the docs -></a>
+## Core Ideas
 
-<br />
+- Side effects live inside `ctx.step(id, fn)`, which records results and skips re-execution on replay.
+- `ctx.waitForEvent`, `ctx.approve`, `ctx.sleep`, and `ctx.sleepUntil` pause runs until the host delivers a matching signal or approval.
+- `ctx.now()` and `ctx.uuid()` record deterministic values for replay.
+- Middleware can extend `ctx` with typed dependencies such as users, database handles, or tracing.
+- Storage is pluggable through `RunStore`; the package ships an in-memory store for local development and tests.
 
-> [!NOTE]
-> New libraries created from this template currently include these adapter packages:
->
-> - [**React Template**](https://tanstack.com/template/latest/docs/framework/react/adapter)
-> - [**Solid Template**](https://tanstack.com/template/latest/docs/framework/solid/adapter)
+## Packages
 
-## Template Usage
+- `@tanstack/workflow-core`: engine, workflow builder, middleware, event types, request parsing helpers, version routing, and in-memory `RunStore`.
 
-Start with [TEMPLATE_GUIDE.md](./TEMPLATE_GUIDE.md), then replace the placeholder names, package descriptions, docs, examples, source code, issue templates, and README copy with the new library's product-specific content.
+Storage adapters, framework bindings, and devtools are planned as follow-up packages.
 
-## Development Commands
+## Development
 
 ```bash
 pnpm install
-pnpm build:all
-pnpm test:lib
-pnpm test:pr
-pnpm lint:all
-pnpm format
-pnpm generate-docs
-pnpm watch
+pnpm --filter @tanstack/workflow-core test:lib
+pnpm --filter @tanstack/workflow-core test:types
+pnpm --filter @tanstack/workflow-core build
+pnpm test
 ```
 
-## Get Involved
-
-- We welcome issues and pull requests.
-- Participate in [GitHub discussions](https://github.com/TanStack/template/discussions).
-- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ).
-- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions.
-
-## Partners
-
-<div align="center">
-
-<table align="center">
-  <tr>
-    <td>
-      <a href="https://www.coderabbit.ai/?via=tanstack">
-        <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-D643Zkrv.svg" height="40" />
-          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-CIzGLYU_.svg" height="40" />
-          <img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
-        </picture>
-      </a>
-    </td>
-    <td>
-      <a href="https://www.cloudflare.com?utm_source=tanstack">
-        <picture>
-          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-Co-Tyjbl.svg" height="60" />
-          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-6Ojsn8yh.svg" height="60" />
-          <img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
-        </picture>
-      </a>
-    </td>
-  </tr>
-</table>
-
-</div>
-
-## Explore the TanStack Ecosystem
-
-- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> - Tooling for JS/TS packages
-- <a href="https://github.com/tanstack/db"><b>TanStack DB</b></a> - Reactive sync client store
-- <a href="https://github.com/tanstack/devtools"><b>TanStack DevTools</b></a> - Unified devtools panel
-- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> - Type-safe form state
-- <a href="https://github.com/tanstack/hotkeys"><b>TanStack Hotkeys</b></a> - Type-safe keyboard shortcuts
-- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> - Async state and caching
-- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> - Type-safe routing, caching and URL state
-- <a href="https://github.com/tanstack/start"><b>TanStack Start</b></a> - Full-stack SSR and streaming
-- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> - Reactive data store
-- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> - Headless datagrids
-- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> - Virtualized rendering
-
-... and more at <a href="https://tanstack.com"><b>TanStack.com &raquo;</b></a>
+## Docs
+
+- [Overview](./docs/overview.md)
+- [Installation](./docs/installation.md)
+- [Quick start](./docs/quick-start.md)
+- [Primitives](./docs/concepts/primitives.md)
+- [Replay and resume](./docs/concepts/replay-and-resume.md)
+- [Scheduling](./docs/concepts/scheduling.md)
 
 ## License
 

docs/concepts/primitives.md

@@ -45,10 +45,11 @@ await ctx.sleepUntil(nextMidnight()) // wake at a wall-clock time
 Pause until the host delivers a signal with this `name`. Returns the payload.
 
 ```ts
+const now = await ctx.now()
 const payload = await ctx.waitForEvent('webhook-received', {
   schema: z.object({ reference: z.string() }),
-  meta: { source: 'stripe' },        // visible to the host driver
-  deadline: Date.now() + 86_400_000, // host wakes if not delivered
+  meta: { source: 'stripe' },     // visible to the host driver
+  deadline: now + 86_400_000,     // host wakes if not delivered
 })
 ```
 
@@ -103,23 +104,6 @@ await ctx.step('long-fetch', (stepCtx) =>
 )
 ```
 
-## `retry(fn, opts)`
-
-Library-level helper for retrying a **composite** of multiple yields. Prefer `ctx.step({ retry })` for single steps.
-
-```ts
-import { retry } from '@tanstack/workflow-core'
-
-await retry(
-  async () => {
-    const a = await ctx.step('a', fetchA)
-    const b = await ctx.step('b', () => fetchB(a))
-    return { a, b }
-  },
-  { attempts: 3, backoff: 'exponential' },
-)
-```
-
 ## `succeed` / `fail`
 
 Tagged return helpers. Avoids `as const` clutter on discriminated unions.

docs/concepts/replay-and-resume.md

@@ -12,6 +12,10 @@ Append-only. Optimistic-CAS on `expectedNextIndex`. Stored via `RunStore.appendE
 - `NOW_RECORDED` / `UUID_RECORDED`
 - `RUN_FINISHED` / `RUN_ERRORED`
 
+**Coordination events** — persisted so hosts and resume calls can identify the pending wait:
+- `SIGNAL_AWAITED`
+- `APPROVAL_REQUESTED`
+
 **Observability-only events** — emit-only, not persisted:
 - `RUN_STARTED`, `STEP_STARTED`
 - `STATE_DELTA`
@@ -120,7 +124,7 @@ Same engine. One invocation drives the run to its next pause or completion. The
 
 ## Cleanup
 
-`RunStore.deleteRun(runId, reason)` fires automatically on `finished` / `errored` / `aborted`. Paused runs persist until the host cleans them up or a TTL expires (in-memory store: 1h default).
+Terminal runs remain in the store so attach calls and webhook retries can read the final log. Stores decide their retention policy; the in-memory store expires non-paused runs after its TTL (1h default). Hosts can still call `RunStore.deleteRun(runId, reason)` when they want immediate cleanup.
 
 ## What the log contains, end to end
 

docs/concepts/scheduling.md

@@ -215,7 +215,7 @@ async function tickAllSchedules(schedules: Array<Schedule>, runStore: RunStore)
 setInterval(() => tickAllSchedules(schedules, runStore), 30_000)
 ```
 
-A more durable version persists `nextFireAt` alongside each schedule definition; a deeper one elects a single leader to avoid duplicate ticks across instances. That whole layer is what a future `@tanstack/workflow-cron` package would provide — see [research/SCHEDULING.md](../../research/SCHEDULING.md) for the design sketch.
+A more durable version persists `nextFireAt` alongside each schedule definition; a deeper one elects a single leader to avoid duplicate ticks across instances. That whole layer is what a future `@tanstack/workflow-cron` package would provide. The design sketch lives in [`research/SCHEDULING.md`](https://github.com/TanStack/workflow/blob/main/research/SCHEDULING.md).
 
 ## Test pattern
 

docs/config.json

@@ -43,6 +43,15 @@
           "to": "concepts/scheduling"
         }
       ]
+    },
+    {
+      "label": "API Reference",
+      "children": [
+        {
+          "label": "workflow-core",
+          "to": "reference/index"
+        }
+      ]
     }
   ]
 }

docs/installation.md

@@ -1,10 +1,10 @@
 # Installation
 
 ```bash
-pnpm add @tanstack/workflow-core zod
+pnpm add @tanstack/workflow-core
 ```
 
-`zod` is a peer requirement only if you use `input` / `output` / `state` / `waitForEvent({ schema })` validation. Any [Standard Schema](https://github.com/standard-schema/standard-schema) library works.
+Install `zod` or another [Standard Schema](https://github.com/standard-schema/standard-schema) library if you use `input` / `output` / `state` / `waitForEvent({ schema })` validation.
 
 ## Storage
 

docs/quick-start.md

@@ -1,6 +1,6 @@
 # Quick start
 
-Copy-paste recipes. Each block runs as-is against `@tanstack/workflow-core` + `zod`.
+Minimal recipes for `@tanstack/workflow-core` + `zod`. Snippets use small local helpers like `collect(...)` and `findRunId(...)` when they need to drain an event stream.
 
 ## Install
 
@@ -56,13 +56,14 @@ const order = createWorkflow({
 const store = inMemoryRunStore()
 const start = await collect(runWorkflow({ workflow: order, input: { amount: 1500 }, runStore: store }))
 const runId = findRunId(start)
+const approvalId = start.find((e) => e.type === 'APPROVAL_REQUESTED')!.approvalId
 
 // Resume — same workflow, same runStore, new approval delivery
 await collect(runWorkflow({
   workflow: order,
   runId,
   runStore: store,
-  approval: { approvalId: 'a-1', approved: true },
+  approval: { approvalId, approved: true },
 }))
 ```
 
@@ -126,11 +127,13 @@ const v2 = createWorkflow({ id: 'pipeline', version: 'v2' })
   .handler(async (ctx) => { /* v2 body */ })
 
 // Engine reads workflowVersion from RunState and routes to the matching code.
+// startEvents are the events from the original v1 run.
+const approvalId = startEvents.find((e) => e.type === 'APPROVAL_REQUESTED')!.approvalId
 await collect(runWorkflow({
   workflow: v2,                // current version
   runId,                       // started under v1
   runStore: store,
-  approval: { approvalId: 'a-1', approved: true },
+  approval: { approvalId, approved: true },
 }))
 ```