docs(research): archive planning-phase design notes under research/

[tannerlinsley]

Moves the five planning markdown files out of the repo root into a new `research/` directory, with a `README.md` framing them as historical context (not maintained docs).

Why

The five files were sitting untracked at the root from the design sprint. The user wants them in the repo for browsable context but not at the root — `research/` is the chosen home.

The README explains:

• These are point-in-time snapshots, not specs
• Current API may differ in places
• Which recommendations shipped vs evolved
• Briefly notes the "TanStack Run" naming detour

Test plan

• No source or test changes — engine unaffected
• CI green

Summary by CodeRabbit

• Documentation
  • Added research documentation archive covering workflow API design candidates (definition-object, builder-chain, hooks-style patterns), explicit versioning specifications with lock-file integrity and ESLint rules, prior art analysis of AI orchestration architectures, and operational risk assessments addressing source skew and resumption failures in durable workflows.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e328d4c3-81f2-4a31-80bd-bb7e13d17cce

📥 Commits

Reviewing files that changed from the base of the PR and between a443f75 and a39ac25.

📒 Files selected for processing (6)

• research/API_CANDIDATES.md
• research/EXPLICIT_VERSIONING.md
• research/PRIOR_ART_AI_ORCHESTRATION.md
• research/README.md
• research/RESEARCH.md
• research/SRC_SKEW_AND_RESUMPTION.md

---

📝 Walkthrough

Walkthrough

This PR introduces six research documents to research/ establishing foundational design decisions and operational strategies for TanStack Workflow. The documents move from design exploration through current implementation assessment to proposed solutions for durability and versioning challenges.

Changes

Workflow Design & Research Documentation

Layer / File(s)	Summary
Research Archive Navigation research/README.md	Index and historical context for research documents created during design sprint, directing readers to current production documentation in /docs and packages/workflow-core/README.md.
Three API Design Candidates research/API_CANDIDATES.md	Explores three API shapes (definition-object with ctx primitives, builder-chain with middleware, hooks-inspired with build transforms) tested against a canonical onboarding workflow. Compares composability, type inference, step identity strategies (string labels vs lexical IDs), and recommends shipping Candidate 1 first with optional phase 2 enhancements.
Comprehensive Strategic Research research/RESEARCH.md	Surveys competitive landscape (five workflow engine camps), catalogs eight technical patterns (event sourcing, checkpointing, DAG, coroutines, statecharts, actors, DB queues, sagas), proposes deployment-agnostic storage-first architecture, identifies market gaps, outlines six-package MVP scope with typed API skeleton, analyzes business models, and details go-to-market distribution strategy emphasizing AI app-builder leverage.
Prior Art: Generator-Based Implementation research/PRIOR_ART_AI_ORCHESTRATION.md	Documents existing @tanstack/ai-orchestration generator engine (async function*/yield* API, Function.prototype.toString() fingerprinting, React bindings, run storage), compares determinism and identity properties against API candidates, inventories shipped components and ecosystem gaps (adapters, non-React bindings, devtools), and recommends core engine extraction with adapter layering.
Source Skew & Resumption Analysis research/SRC_SKEW_AND_RESUMPTION.md	Analyzes operational risks in fingerprinting-based durability: documents strict and patch-versioned fingerprint semantics, enumerates failure modes from source changes, diagnoses positional-vs-textual identity mismatch, and proposes five missing layers (AST fingerprinting, build-time pinning, ESLint rules, automated version drain, orphaned-run inspector) with operational guidance across workflow-duration tiers.
Explicit Versioning Proposal research/EXPLICIT_VERSIONING.md	Replaces runtime fingerprinting with explicit workflow versioning: version plus previousVersions entries, (name, version) engine registration, run pinning at start with version-based resumption. Specifies .tanstack/workflows.lock with AST hashes, two ESLint rules, CLI codemod for bumping, and removal of patched() ceremony. Details engine changes, edge cases (stale lock, name collisions, bundle bloat), and operational expectations per deployment tier.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A rabbit hops through research paths so bright,
Three API shapes, each tested in the light,
From fingerprints to versions locked in place,
Strategic workflows find their perfect space! 🐰✨

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

[pkg-pr-new]

More templates

• @tanstack/template-example-react-basic
• @tanstack/template-example-react-devtools
• @tanstack/template-example-solid-basic
• @tanstack/template-example-solid-devtools

@tanstack/react-template

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/react-template@3

@tanstack/react-template-devtools

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/react-template-devtools@3

@tanstack/solid-template

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/solid-template@3

@tanstack/solid-template-devtools

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/solid-template-devtools@3

@tanstack/template

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/template@3

@tanstack/template-devtools

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/template-devtools@3

@tanstack/workflow-core

npm i https://pkg.pr.new/TanStack/workflow/@tanstack/workflow-core@3

commit: a39ac25