Fix workflow runtime and release surface

[tannerlinsley]

Changes

• Harden workflow runtime validation, output validation, and signal/approval delivery matching.
• Retain terminal run logs and make terminal resume/attach behavior idempotent.
• Add focused validation and delivery tests, update affected existing tests, and export the reserved middleware extension helper.
• Replace template docs/tooling surface with workflow-core docs, generated API reference, narrowed workspace config, and updated release metadata.
• Bump @tanstack/workflow-core to 0.0.2 with changelog entry for npm release.

Verification

• pnpm test
• pnpm run build
• git diff --check

Release Impact

• This change affects published code and includes the generated 0.0.2 release state.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Release Notes

• New Features

  • Added comprehensive API reference documentation for workflow-core.
  • Enhanced input and output schema validation with clear error reporting.
  • Improved durability: terminal runs retained in store for webhook retries and attachments.

• Bug Fixes

  • Fixed delivery matching validation for approvals and signals with distinct error codes.
  • Corrected deterministic behavior in deadline calculations for event waits.

• Documentation

  • Expanded product docs with installation, quick-start, primitives, and replay guides.
  • Added API reference for classes, interfaces, functions, and type aliases.

• Chores

  • Made Zod an optional peer dependency instead of required.
  • Reorganized test suite to focus on workflow-core.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4308098a-bda6-433b-a20d-a226957cdcf0

📥 Commits

Reviewing files that changed from the base of the PR and between 0de8e83 and 4b5d6dd.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (91)

• .github/pull_request_template.md
• CONTRIBUTING.md
• README.md
• docs/concepts/primitives.md
• docs/concepts/replay-and-resume.md
• docs/concepts/scheduling.md
• docs/config.json
• docs/installation.md
• docs/quick-start.md
• docs/reference/classes/LogConflictError.md
• docs/reference/classes/StepTimeoutError.md
• docs/reference/classes/WorkflowRequestParseError.md
• docs/reference/functions/createMiddleware.md
• docs/reference/functions/createWorkflow.md
• docs/reference/functions/createWorkflowRegistry.md
• docs/reference/functions/fail.md
• docs/reference/functions/handleWorkflowWebhook.md
• docs/reference/functions/inMemoryRunStore.md
• docs/reference/functions/parseWorkflowRequest.md
• docs/reference/functions/runWorkflow.md
• docs/reference/functions/selectWorkflowVersion.md
• docs/reference/functions/succeed.md
• docs/reference/index.md
• docs/reference/interfaces/ApprovalResult.md
• docs/reference/interfaces/ApproveOptions.md
• docs/reference/interfaces/BaseCtx.md
• docs/reference/interfaces/CreateMiddlewareBuilder.md
• docs/reference/interfaces/CreateWorkflowConfig.md
• docs/reference/interfaces/HandleWebhookOptions.md
• docs/reference/interfaces/InMemoryRunStoreOptions.md
• docs/reference/interfaces/Middleware.md
• docs/reference/interfaces/RunState.md
• docs/reference/interfaces/RunStore.md
• docs/reference/interfaces/RunWorkflowOptions.md
• docs/reference/interfaces/SerializedError.md
• docs/reference/interfaces/SignalDelivery.md
• docs/reference/interfaces/StepAttempt.md
• docs/reference/interfaces/StepContext.md
• docs/reference/interfaces/StepOptions.md
• docs/reference/interfaces/StepRetryOptions.md
• docs/reference/interfaces/WaitForEventOptions.md
• docs/reference/interfaces/WebhookPayload.md
• docs/reference/interfaces/WorkflowBuilder.md
• docs/reference/interfaces/WorkflowDefinition.md
• docs/reference/interfaces/WorkflowRegistry.md
• docs/reference/interfaces/WorkflowRequestParams.md
• docs/reference/type-aliases/AccumulateExtensions.md
• docs/reference/type-aliases/AnyMiddleware.md
• docs/reference/type-aliases/AnyWorkflowDefinition.md
• docs/reference/type-aliases/AssertNonReservedExtension.md
• docs/reference/type-aliases/CheckpointEvent.md
• docs/reference/type-aliases/Ctx.md
• docs/reference/type-aliases/DeleteReason.md
• docs/reference/type-aliases/InMemoryRunStore.md
• docs/reference/type-aliases/InferSchema.md
• docs/reference/type-aliases/MiddlewareServerFn.md
• docs/reference/type-aliases/Operation.md
• docs/reference/type-aliases/ReservedCtxFields.md
• docs/reference/type-aliases/RunStatus.md
• docs/reference/type-aliases/SchemaInput.md
• docs/reference/type-aliases/WorkflowCtx.md
• docs/reference/type-aliases/WorkflowEvent.md
• docs/reference/type-aliases/WorkflowInput.md
• docs/reference/type-aliases/WorkflowOutput.md
• docs/reference/type-aliases/WorkflowState.md
• knip.json
• package.json
• packages/workflow-core/CHANGELOG.md
• packages/workflow-core/README.md
• packages/workflow-core/package.json
• packages/workflow-core/src/define/define-workflow.ts
• packages/workflow-core/src/engine/run-workflow.ts
• packages/workflow-core/src/index.ts
• packages/workflow-core/src/middleware/create-middleware.ts
• packages/workflow-core/src/types.ts
• packages/workflow-core/tests/engine.attach.test.ts
• packages/workflow-core/tests/engine.delivery.test.ts
• packages/workflow-core/tests/engine.durability.test.ts
• packages/workflow-core/tests/engine.idempotency.test.ts
• packages/workflow-core/tests/engine.primitives.test.ts
• packages/workflow-core/tests/engine.validation.test.ts
• packages/workflow-core/tests/examples.alem-article.test.ts
• packages/workflow-core/tests/examples.alem-orchestrator.test.ts
• packages/workflow-core/tests/examples.kyle-ai-agent.test.ts
• packages/workflow-core/tests/examples.kyle-durable-agent.test.ts
• packages/workflow-core/tests/inference.test.ts
• packages/workflow-core/tests/test-utils.ts
• packages/workflow-core/vitest.config.ts
• pnpm-workspace.yaml
• scripts/generate-docs.ts
• vitest.workspace.ts

---

📝 Walkthrough

Walkthrough

This release encompasses complete API reference documentation generation for @tanstack/workflow-core, adds runtime schema validation for inputs and outputs, implements delivery matching for approvals and signals, enforces type-safe middleware extensions, and expands test coverage with validation and delivery matching suites. Terminal run retention replaces immediate deletion, and test infrastructure now derives approval IDs dynamically from event streams.

Changes

Documentation & API Reference

Layer / File(s)	Summary
Project & User Documentation README.md, CONTRIBUTING.md, docs/concepts/, docs/installation.md, docs/quick-start.md, docs/config.json	README replaced with @tanstack/workflow-core product overview, installation, and TypeScript example. CONTRIBUTING guide updated to point to workflow repo and clarify issue/discussion separation. Concept docs refined for deterministic deadlines. Installation and quick-start guide now use dynamically-derived approval IDs in examples.
API Reference: Classes & Error Types docs/reference/index.md, docs/reference/classes/*	Generated API reference landing page and error class documentation for LogConflictError, StepTimeoutError, and WorkflowRequestParseError with constructor signatures and property descriptions.
API Reference: Core Types & Interfaces docs/reference/interfaces/{BaseCtx, RunState, RunStore, SerializedError, SignalDelivery, StepAttempt, StepContext, StepOptions, StepRetryOptions, WaitForEventOptions, WebhookPayload}.md	Complete reference documentation for base context API, run state structure, event store interface, and step/event configuration options with all required/optional fields and type constraints.
API Reference: Workflow Builder & Middleware docs/reference/interfaces/{WorkflowBuilder, CreateWorkflowConfig, CreateMiddlewareBuilder, Middleware}.md	Full documentation of fluent workflow builder API, configuration parameters, and middleware system with type parameter constraints and method signatures.
API Reference: Execution Options & Payloads docs/reference/interfaces/{RunWorkflowOptions, HandleWebhookOptions, WorkflowRequestParams, ApprovalResult, ApproveOptions, InMemoryRunStoreOptions}.md	Reference documentation for workflow execution entry points, webhook handling options, and related structured types.
API Reference: Public Functions docs/reference/functions/{createWorkflow, createWorkflowRegistry, createMiddleware, runWorkflow, handleWorkflowWebhook, parseWorkflowRequest, succeed, fail, selectWorkflowVersion, inMemoryRunStore}.md	Complete function signatures and usage documentation for all public workflow APIs with parameter and return type descriptions.
API Reference: Type Aliases docs/reference/type-aliases/*	30+ type alias reference pages documenting WorkflowEvent discriminated union, run status types, schema inference helpers, middleware utilities, and context composition types.

Runtime & Test Infrastructure

Layer / File(s)	Summary
Type System: Reserved Ctx Fields Guard packages/workflow-core/src/types.ts, packages/workflow-core/src/index.ts, packages/workflow-core/src/define/define-workflow.ts	Add AssertNonReservedExtension conditional type to types.ts to prevent middleware extensions from shadowing reserved context fields at compile-time. Move re-export from define-workflow to types module.
Middleware: Type-Safe Context Extensions packages/workflow-core/src/middleware/create-middleware.ts	Update CreateMiddlewareBuilder.server() to wrap extension types with AssertNonReservedExtension. Update JSDoc examples to use destructured { ctx, next } parameter form matching new signature contract.
Runtime: Schema Validation on Start & Finish packages/workflow-core/src/engine/run-workflow.ts (validation logic)	Validate workflow input before handler execution and output before run completion via shared synchronous schema validation helpers. Emit RUN_ERRORED with validation_error code instead of throwing.
Runtime: Delivery Matching & Terminal Run Handling packages/workflow-core/src/engine/run-workflow.ts (delivery & attach logic)	Implement delivery matching validation for signals/approvals on resume. Switch terminal runs to attach mode instead of replay. Detect terminal events already in log to avoid duplication. Emit structured SignalLost/ApprovalLost codes on mismatch. Keep run records instead of deleting on terminal transitions.
Test Infrastructure: Approval ID Derivation packages/workflow-core/tests/test-utils.ts	Add findApprovalId helper to scan event streams for APPROVAL_REQUESTED and extract approvalId for dynamic test setup.
Test Suite: Schema Validation packages/workflow-core/tests/engine.validation.test.ts	New test suite covering input validation before handler execution, schema defaults application, and output validation before run completion.
Test Suite: Delivery Matching packages/workflow-core/tests/engine.delivery.test.ts	New test suite validating mismatched approval/signal deliveries are rejected with approval_lost/signal_lost codes, and matching deliveries allow run completion.
Test Updates: Terminal Run Handling & Idempotency packages/workflow-core/tests/engine.{attach,idempotency}.test.ts	Update engine.attach to expect RUN_FINISHED on completed runs and engine.idempotency to reflect TTL-based retention semantics instead of immediate deletion.
Test Updates: Dynamic Approval ID Tracking packages/workflow-core/tests/engine.{durability,primitives}.test.ts, packages/workflow-core/tests/examples.*.test.ts, packages/workflow-core/tests/inference.test.ts	Migrate all test files from hardcoded approval IDs to dynamic derivation via findApprovalId(phaseN) for accurate replay and resume testing.
Build & Workspace Configuration .github/pull_request_template.md, vitest.config.ts, vitest.workspace.ts, pnpm-workspace.yaml, knip.json, scripts/generate-docs.ts, package.json, packages/workflow-core/{CHANGELOG,package}.md/json	Update vitest root/project lists, narrow workspace to workflow-core, simplify knip ignores, wire doc generation for workflow-core, adjust package script comments, remove unused test dependency, and document v0.0.2 release notes.

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly Related PRs

• TanStack/workflow#2: Implements closure engine runtime changes that build on this PR's validation and delivery matching foundations for workflow execution control.

Poem

🐰 A workflow of docs so fine and wide,
From types to tests, with validation inside,
Approvals matched and terminals kept,
The reference guides where knowledge is swept.
Reserved fields guarded with type-level care,
A robust engine beyond compare! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​react@​19.2.15
	vite@​8.0.14
	react@​19.2.6
	@​vitejs/​plugin-react@​6.0.2
	react-dom@​19.2.6
	solid-js@​1.9.13

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm seroval is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: ? → npm/solid-js@1.9.13 → npm/seroval@1.5.4 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/seroval@1.5.4. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report