Repository navigation
spec(FIX-2162): One client: a single createClient for actions, sessions, requests and resources - #3810
Conversation
SPEC.md and DECISIONS.md for replacing the five client factories with one
createClient({ userId, baseUrl?, apiPath?, fetcher? }): flows through
fsd.flow(kind), a request object that carries its own lifecycle, and a
client that lists its own user's sessions by default. Figures rendered in
both themes; poc/caller-census re-derives the caller counts with a
totality assertion and a negative control.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
…ensus widened Re-draft before publication. The goal now covers every job the one client does (typed actions, sessions, resources, status/abort/continue/retry/resume) on both transports. The owner folded in an in-process transport (createInProcessFetch in engine) and allowed the server changes the client needs: a read of the user's interrupted requests, sessionId on request status with its tenant check, and flowId on the interrupted and active-request lists. The census gate now covers the SSE factories, sub-client props, standalone transcribe, packages/ui and facades. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
@codex review This is a spec PR: please review at direction altitude (see "How to review this" in the description). The areas I am least sure of:
Generated by Claude Code |
Second-look + architecture review (spec PR, direction check per BP-040)I read SPEC.md/DECISIONS.md and spot-checked the claims against 1. Don't ship this as one 153-file PR (changes the approach)"No aliases, every caller moves in the same change" is right for the end state, but not for the PR shape. 118 code files + 35 docs in one diff is unreviewable, and the spec itself says it couples with FIX-2158 (#3796) and depends on FIX-2063 (#3782). Recommend the spec state a PR plan up front (this fits
2. D3 is a behavior change riding in a refactor (flag, don't bury)
3. The new "interrupted" read may duplicate
|
|
Architect · coherence check on FIX-2162 No two-direction fork. One client replacing the five factories is the direction, and the meeting points with #3796 (FIX-2158), #2080 (FIX-1498) and #3782 (FIX-2063) are named. Two small asks:
Neither one blocks the direction. — FSD Architect |
|
FSD Architect · coherence read (spec head No two-direction fork. The coupling with FIX-2158 (#3796) and leg a's need for FIX-2063 (#3782) are named. Two things to settle before merge, both under Jake's reuse rule (no second mechanism where an existing piece would do):
Neither changes D1–D3. — FSD Architect |
There was a problem hiding this comment.
/simplify review (spec only)
Verdict: The core direction looks right for the stated goal — one createClient, one fetcher, recovery without re-supplying flowKind/sessionId, and fixing the sweep-only check-interrupted semantics with a real read. Rejecting a public facade over the five factories is coherent; createLabClients in shift-manager is already the shape you want, just not exported or enforced.
I do not think a third-party HTTP client (openapi-fetch, ofetch, etc.) simplifies this: the repo deliberately keeps @flow-state-dev/client free of HTTP deps, and the hard part is FSD-specific routes, SSE streams, recovery, and apiPath — not generic JSON fetch.
Where the spec may have gone farther than necessary is bundling several independent wins into one sign-off surface, and locking implementation architecture in the census/"Decided" sections.
What I'd keep as-is
- D1 (flow only via
fsd.flow(kind)) — small caller cost, directly attacks placeholder flow kinds. - D2's problem statement — request handles (or equivalent bound context) are the right fix for "Flow mismatch" after a crash; Temporal/LangGraph analogy is fair.
- Types-only
flow<typeof T>()— reuses today'screateTypedClientspine without shipping definitions. - Goal legs + real SIGKILL — stronger than hand-set
interrupted; appropriate for this issue. interrupted()= sweep then read — necessary givenrecovery-routesbehavior; not simplifiable without lying about races.
Where a cleaner change might look different
-
Split "product API" from "merge factories" in the written spec
DECISIONS "Decided, not asked" (L73–128) reads like a full public tree (sessions.debug, capabilities, transcribe placement, seven request methods, stream matrix). The six-people table only needs invariants: one fetcher, no second factory, recovery without re-supplying flow/session. Consider moving the namespace inventory to an implementer sketch derived from the route map, so the spec doesn't over-commit method names before implementation. -
Phase server work inside D2 (optional, if you want a thinner first implementation PR)
The interrupted read is required for the goal regardless of handle style.sessionIdon status andflowIdon list projections are required forrequest(id)without saved session, not strictly forsend()→continue()after crash. If you're committed to handles in one shot, say that explicitly; if not, labeling (A) vs (B) in DECISIONS would make sequencing obvious without changing direction. -
D3 is a privacy fix, not "one client"
Worth doing, but it's a breaking semantic change for unsigned servers. Fine if intentional — just know it expands review surface beyond factory deletion. (I wouldn't revert it; I'd avoid duplicating the argument in both SPEC and DECISIONS.) -
In-process transport
Owner scope, and the probe is convincing. For readers weighing complexity: narratively splitting "client merge" vscreateInProcessFetchcan help future issues without changing this epic. -
Docs manifest in SPEC (20+ paths)
High churn risk; census--after+ default inventory is already the checklist. A single sentence pointing at leg c may be enough. -
Census
--afterarchitecture rules
Banning removed factory names and sub-client props is clearly caller-visible. Requiring the fetcher to be invoked from exactly one file underpackages/client/srcis an internal module layout constraint — useful anti-facade guard, but easy for implementers to trip on while still shipping one public client. Consider keeping strict facade rules in the goal copy while softening or dropping the single-file rule in the retained spec POC (or document it as aspirational). -
SPEC ↔ DECISIONS duplication
Sign-off bullets re-list D1–D3; server "three changes" and census counts appear in both. Thinning SPEC to goal + verification + one Pi diff would reduce drift.
POC script
check.mjs is appropriate evidence for counts; perf is fine for a one-shot script (sync read of whole corpus). Triple-pass inventory + per-loop RegExp allocation is redundant CPU only at dev time — not a spec concern unless CI runs it on every push.
Skipped (needs owner call, not automation)
- Big-bang vs phased merge (you've already rejected public wrappers).
- Whether operator "all users" session list must stay on the client API (D3 "change my mind").
Bottom line: I'd sign the direction (one client, D1–D3, no facade). Before implementation, consider thinning the spec's API catalog and docs laundry list, and clarifying whether D2's server fields are one atomic deliverable or ordered slices. Not requesting spec rewrites as a merge blocker — inline notes flag the highest-leverage trim points.
Sent by Cursor Automation: Review For Best Approach
| fields and `createInProcessFetch` added. If wrong: the one client grows a namespace per feature | ||
| and becomes the next grab-bag. | ||
|
|
||
| 1. **[D1](DECISIONS.md#d1) · A flow is named only through `fsd.flow(kind)`; the client has no |
There was a problem hiding this comment.
These three bullets largely duplicate DECISIONS D1–D3 (and the figures). For a leaner spec, link to DECISIONS anchors only here and keep SPEC sign-off to goal size + debt net-down.
There was a problem hiding this comment.
Dropped, no change. docs/contributing/spec-template.md requires the sign-off one-liners in SPEC.md. They are the gate's index and link each card in DECISIONS.md, where the reasoning lives.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 77af999e1e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…name gate Round 1 of spec review on #3810: - createInProcessFetch is node's dispatch moved to the engine; node delegates and stops deriving router paths (Decided, not asked; debt table). - httpActions and 24 other hand-built router helpers are replaced; the census flags them, path derivation outside the engine, and the removed methods (stream twins, state.getSnapshot, bearerFetcher). Hosts and router unit tests excluded by name with reasons. - The census is a name/prop gate; the single-file fetcher rule is gone. One transport per client is proved by a structural unit test in the goal; the control plants an internal facade the census must pass. - Open PRs: FIX-2161 (#3805) added; FIX-2158 order and listWorkerSessions named. - Docs line trimmed to the rewritten pages, with --after as the checklist; namespaces stated as an invariant with one example; review notes recorded. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
|
Round 1 of spec review is folded in ddd307c. D1–D3 are unchanged, and the direction did not move, so there is no How it got here entry. Growth is 1.11× (385 → 428 lines), so no re-draft trailer. Architect pass, comment A
Architect pass, comment B
cursor /simplify review
Codex review
Census, re-run at e5a2786 (this branch's base): inventory PASS, with all 6,464 tracked text files classified. 195 files change (159 code, 61 of them tests; 36 docs). Generated by Claude Code |
|
@codex review Head ddd307c. Please pay special attention to:
Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ddd307cb7a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
FSD Architect · re-check at All four Architect asks match what was asked:
No two-direction fork. Architect-clear on direction. The PR-shape point (split server/engine from client/callers) from the second-look review is still open for the author to answer, but it doesn't affect coherence. — FSD Architect |
|
FSD Architect · re-check at All four coherence asks are folded the way I asked. #3805 (FIX-2161) is named as a meeting point. — FSD Architect |
Round 2 of spec review on #3810 (Codex r4365075513): once check.mjs is promoted to goals/client/does-every-job-with-one-client/, --after would flag its own name lists and control fixtures. The checker now excludes itself at both paths, and --control plants the promoted copy and requires it to stay clean. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
… threshold Round 2 of spec review on #3810 (second-look comment 6376729578): - Two PRs, server first (additive engine/server + node delegation), then the client, callers and docs atomically. - The interrupted read stays a listing of its own: /active-requests lists the in-flight registry, and the sweep deregisters an entry as it marks the record interrupted. Recorded in Considered and dropped; admission shared. - baseUrl is optional with a fetcher; the in-process example drops the fake URL. - The goal's primary path is a short staleSweepThresholdMs on createFlowState; the fallback wait is the router's 60 s default, not 30 s. - core's changeset is for sessionId on RequestStatusSnapshot; node needs none. - Five notes recorded verbatim for the implementer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
|
Re the second-look review (comment 6376729578), folded in 1d7954e. D1–D3 are unchanged.
Generated by Claude Code |
|
@codex review Head 1d7954e. Please pay special attention to:
Generated by Claude Code |
|
Codex Review: Didn't find any major issues. Nice work! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
Follow-up to the clear at
— FSD Architect |
…eps its filters Precision fixes from the architect at 1d7954e (comment 6376916374): - /active-requests is untouched: no client method reads it, so flowId goes only on the interrupted listing, where request() reads it. - fsd.sessions.list keeps every filter listSessions takes today (flowKind, flowId, userId, include, state, limit, offset), naming its dependents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQR4aH3gxXUWdqTMpT1EH3
|
Re comment 6376916374: both points are in d09bfb6.
Generated by Claude Code |
|
@codex review Head d09bfb6. Two precision edits to check:
Generated by Claude Code |
|
Codex Review: Didn't find any major issues. Swish! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
Codex Review: Didn't find any major issues. 🚀 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |


fsd.flow("support")sends. The request that it returns hascontinue()support.request(id)gives the request back, withcontinue(),retry()andresume().fsd.requests.interrupted()reads the same records each timefetcher: createInProcessFetch(flowState)to the same client. All calls and streams stay in the process, React streams toocreateTypedClientputs the flow definition in the bundle and refuses a collection flowfsd.flow<typeof supportFlow>("support")uses types only, and takes any instance by its idFlowNavigatortakesclientandsessionClient. Panels takeresourceClientGoal: a person who drives FSD from code, against a server or in their own process, does all jobs with one client: send an action, typed or not; use sessions and resources; get the status of a request, stop it, continue it, retry it, or resume it, also after a crash of the host. Nothing in the repo teaches a different way to build a client.
The check reads requests, sessions and resources through the client that a user holds, on the two transports. It reads the repo through the census. Each dashed control must fail. Check:
goals/client/does-every-job-with-one-client/, modeln/a. Controls:GOAL_CONTROL=retry-instead,two-clientsandstream-off-fetcher, and the census--control. Why this goal and not a smaller one: SPEC.md.Look where the user, the flow and the transport are. Today each box binds them in a different place. After, the user is on the client, the flow is on its handle, and the transport is one fetcher.
How: one
createClientholds the user and one fetcher. All calls and streams go through one route builder and one transport. The fetcher sends to a host over HTTP, or to the engine in the same process throughcreateInProcessFetch. That function is the one way a Request becomes a router call:node's server app calls it too, and the goals' hand-built in-process client,httpActions, goes. The server gets one read and two fields, so that a request found by its id can act.Sign off
The goal, at that size. If wrong: we ship a facade, the docs teach two ways, and an embedded host still needs a web server.
The debt: net down. Six ways to build a client, and the goals' own, become one, and two ways to dispatch a Request become one. The change adds one read of interrupted requests, two response fields and
createInProcessFetch, whichnodeserves through too. If wrong: the one client gets a new namespace for each feature, and becomes the next grab-bag.A flow has one name path:
fsd.flow(kind). The client has no default flow · D1It comes down to the number of ways to name a flow: a default makes two. If wrong: each single-flow app has one more line, always.
A request is an object. A send, an id or the interrupted list gives it, and its lifecycle is on it · D2
It comes down to the crash path: with id methods, each caller must keep the flow and the session. If wrong: all recovery code uses a public type, and the server has a read and two fields that it must keep.
A client lists the sessions of its own user, unless it asks for a different user · D3
It comes down to an app before sign-in: today it shows the sessions of all users, and that changes when sign-in starts. If wrong: a tool that must list the sessions of all users must call the route directly.
Open: none. D1 is the one to weigh. Reasoning and what lost: DECISIONS.md.
Reviewers · look here
check-interruptedreturns only the records that the same call changed, so a sweep before it hides a lost request.createInProcessFetchtakes the path from the URL and calls the engine router, andnode's server app delegates to it. Do streams and abort work the same as over HTTP, does any route need the socket, and doesnodekeep everything that is a host's?poc/caller-census/. The census is a name and prop gate: does--afterfail on each removal the spec lists and on a hand-built router client? Structure (one transport per client) is the goal's unit test; is that test enough?Not here: verified identity (FIX-1503), and a trusted
cliprincipal for embedded callers.Spec · Decisions · Linear FIX-2162 · no epic · amends FIX-1788 · couples with #3796 (FIX-2158) and #3805 (FIX-2161), where whichever lands second moves the other onto
createWorkforceClient(fsd); with #2080 (FIX-1498); and with #3782 (FIX-2063) for leg a · merges after human approval and required checksPOC — the caller census (retained, not production code)
Run from the repo root. It answers: which files the change must touch, and does the gate fail on each removal, each named facade and each hand-built router client?
node specs/issues/FIX-2162/poc/caller-census/check.mjs— the inventory. Every tracked text file is classified.node specs/issues/FIX-2162/poc/caller-census/check.mjs --after— the gate. It fails today with 403 references.node specs/issues/FIX-2162/poc/caller-census/check.mjs --control— the negative control. It names all 20 plants, and passes a facade built from neutrally named helpers, which the census can't see by design.How to review this — altitude, what's in scope, what's deliberately unsettled
This is a direction set, not an implementation and not a build plan. Reviewing it well means
answering one question: is this the right approach?
In scope to challenge:
SPEC.md— is the goal the real need at full size,for the people named, or a smaller goal that would let us call this done early? Would the
named check fail if the goal were not met?
docs/philosophy.md?DECISIONS.md— that's the sign-off surface.SPEC.md→ What's already here, and the debt — an existing primitive,method or prior design the change overlaps and doesn't name; something it adds that is debt
and isn't listed; a net verdict the tables don't support.
design.
Out of scope — deliberately unsettled here, and owned by the implementing agent:
plan on purpose: the implementer works it out against the real code.
or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
decisions don't say is.
poc/are retained,not production code. Read them for directional evidence, not production completeness.
Their isolation from production/default discovery and absence of secrets or generated
dependencies are in scope; retention is not permission to weaken repository checks.
One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.
Feedback in the second list is welcome and gets recorded verbatim in
DECISIONS.md → Notes from reviewfor the implementer to weigh against real code. It will notbe argued with, and it will not be folded into the design prose. Please don't re-raise it: one
mention is enough.
The one exception is the POC. Line-level feedback on it is dropped, not recorded — there
is nothing for an implementer to weigh about code that isn't shipping. Feedback about its
direction is not line-level and is treated like any other above-the-bar finding.
Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.
Generated by Claude Code