Skip to content

spec(FIX-2162): One client: a single createClient for actions, sessions, requests and resources - #3810

Merged
jhoffner merged 6 commits into
mainfrom
spec/FIX-2162
Oct 24, 2026
Merged

jhoffner merged 6 commits into
mainfrom
spec/FIX-2162

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
starts a session, sends, and continues after a crash, from a script Builds three clients. One client binds the flow and the user; the other two take them on each call Builds one client from an address and a user. fsd.flow("support") sends. The request that it returns has continue()
saved a request id, and comes back after a restart or an approval Must also keep the flow and the session. The interrupted list returns only the records that the same call changed support.request(id) gives the request back, with continue(), retry() and resume(). fsd.requests.interrupted() reads the same records each time
runs FSD in their own process, with no web server Starts a web server, or writes a fetch function that sends to the engine. React request streams ignore that function Gives fetcher: createInProcessFetch(flowState) to the same client. All calls and streams stay in the process, React streams too
wants typed actions createTypedClient puts the flow definition in the bundle and refuses a collection flow fsd.flow<typeof supportFlow>("support") uses types only, and takes any instance by its id
renders FSD in React, or builds a workforce client FlowNavigator takes client and sessionClient. Panels take resourceClient Each takes the one client. The hooks do not change

Goal: 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.

flowchart LR
  H["two hosts · fsdev serve over HTTP · createInProcessFetch in a child process"] --> A["process 1 · one client · typed send · resource read · approval suspends · a send holds"]
  A --> K["SIGKILL the host mid-send · restart · wait past the stale threshold"]
  K --> C["process 2 · one client · interrupted then continue · request by id then resume"]
  C -->|"same ids · steps ran once · every call through its fetcher · census clean"| P["PASS · goal met"]
  X["controls · retry instead · a second client · a stream off the fetcher"] -.-> C
  C -.->|"under any control"| F["must FAIL · on its named signal"]
Loading

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/, model n/a. Controls: GOAL_CONTROL=retry-instead, two-clients and stream-off-fetcher, and the census --control. Why this goal and not a smaller one: SPEC.md.

Today: six ways to build a client, each binding the user and the flow in a different place, and a transport that is a URL only. After: one createClient holding the fetcher and the user, with flow handles and request handles inside, and a fetcher that is either a URL over HTTP or createInProcessFetch with no web server

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 createClient holds 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 through createInProcessFetch. 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, which node serves 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 · D1

D1: name a flow only through fsd.flow, chosen, beside an optional default flow on createClient. Decides it: how many ways to name a flow. Price: one line in a single-flow app

It 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

D2: a request object carrying its lifecycle, chosen, beside id-taking methods on the client. Decides it: what continue after a crash costs to write. Price: a read and two fields on the server

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

D3: the client's own user by default, chosen, beside every user's sessions when no sign-in is set. Decides it: an app before sign-in. Price: no client call lists everyone

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

  • Decisions → Decided, not asked → the server changes. Is a read of interrupted requests the smallest correct fix? Today check-interrupted returns only the records that the same call changed, so a sweep before it hides a lost request.
  • Decisions → Decided, not asked → the in-process transport and the one dispatch path. createInProcessFetch takes the path from the URL and calls the engine router, and node's server app delegates to it. Do streams and abort work the same as over HTTP, does any route need the socket, and does node keep everything that is a host's?
  • Spec → how we verify, and poc/caller-census/. The census is a name and prop gate: does --after fail 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 cli principal 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 checks

POC — 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:

  • The goal and the problem framing in 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?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • The debt in 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.
  • A case a person would hit that the people table misses, when it would invalidate the
    design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • The build plan. Order, file-level changes, the test list, the PR split. The set has no
    plan on purpose: the implementer works it out against the real code.
  • Names, signatures, file paths, and module layout, beyond the few a decision locks.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Edge cases that don't change the approach. The implementer's tests own them.
  • Documentation wording. It is written at implementation, against what shipped.
  • Micro-optimizations and style preferences.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    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 implementation polish. Experiments under the owning spec's 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 review
for the implementer to weigh against real code. It will not
be 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

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
@linear-code

linear-code Bot commented Oct 23, 2026

Copy link
Copy Markdown

FIX-2162

@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 23, 2026 11:39pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 23, 2026 11:39pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 23, 2026 11:39pm UTC

Request Review

@jhoffner jhoffner added the spec label Oct 23, 2026 — with Claude
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-23T23:49:50.869703Z d09bfb6 Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

@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:

  1. The interrupted read (a server change). Today POST /users/:userId/check-interrupted returns only the records that the same call changed (recovery-routes.ts). The startup sweep or the 30 s sweeper can mark a request first, and then that call returns nothing. The spec adds a read of the user's interrupted requests, with the same owner and tenant checks, and fsd.requests.interrupted() pokes and then reads. Is that the smallest correct fix? Does any path make the read lose or duplicate a record?
  2. createInProcessFetch (engine). It calls the router from getRouter() and takes the path from the URL with decodePathSegments. Does every route, the SSE streams and abort included, behave the same as over HTTP? Does any route depend on a socket, a remote address or a host-adapter step that this path skips? Is the caller source "http" correct for auth?
  3. The census gate (specs/issues/FIX-2162/poc/caller-census/check.mjs --after). Does it fail on each removal that the spec lists, and on a facade (sub-clients built inside the one client)? Can a facade pass it?

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Second-look + architecture review (spec PR, direction check per BP-040)

I read SPEC.md/DECISIONS.md and spot-checked the claims against main. The factory list (createClient, createTypedClient, createSessionClient, createRecoveryClient, createResourceClient, plus the 3 SSE factories) and callerReachesRequest on abort/recovery/resume routes match the spec's description. The direction is sound: one client, user once, flow on a handle, request as an object. Items below are things that change the approach or the build, ranked.

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 issue-multi-pr):

  • PR A (server + engine): interrupted-read route, sessionId on status (+ tenant check), flowId on interrupted/active lists, createInProcessFetch. Additive, independently testable, no caller moves.
  • PR B (client + callers): new createClient, removal of the old factories, all callers/docs in one change. This is the one that must be atomic (no aliases).
    The "no compat wrappers" rule only needs to hold on main after B lands, not between A and B.

2. D3 is a behavior change riding in a refactor (flag, don't bury)

FlowNavigator going from "lists everyone's sessions with no userId" to "lists the client's user's" is a privacy-default change. It's the right default, but it's listed under a "One client" refactor and only surfaced in a changeset. Suggest: keep D3 but make it its own commit (and its own test asserting the old leak is closed) so it's bisectable and revertable independently of the client reshape.

3. The new "interrupted" read may duplicate /active-requests (architecture)

The spec widens /active-requests with flowId but gives it "no client method, before or after", while adding a second list route for interrupted requests with the same owner/tenant checks and projection. Two near-identical per-user request listings is the kind of drift this issue is meant to remove. Check whether /active-requests with a status filter (or a shared projection helper behind both routes) covers D2 with one route instead of a new one. If the status values differ enough that they must be separate, say why in DECISIONS.md "Considered and dropped".

4. Settle baseUrl for the in-process case now, not "implementer's call"

The example passes baseUrl: "http://in-process" — a fake URL to satisfy a required option is a small wart that every embedded caller (and every doc) will copy. Cheaper to decide in the spec: baseUrl optional when fetcher is given (default a fixed internal origin the engine's fetch ignores). Otherwise the dummy string becomes de facto API.

5. Hidden round-trip in request(id).continue()

The session is read lazily from the status read for continue/retry. That's fine, but make it explicit in the spec that the handle caches it (one status read per handle, not per call) and that a status read racing a state change (request completed between read and continue) surfaces as a typed ClientHttpError, not a plain Error. The "second-path" checklist (BP-035: concurrent-409, cancel-error) isn't mentioned for these new methods.

6. React: one client, stable identity (BP-010)

Hooks "each build one client and pass its fetcher to every stream". Components now take client as a prop, so hooks that previously built a client internally from baseUrl/userId need that client memoized (useMemo), or a new client per render will re-open streams. Worth one line in the spec's React section and a test that a re-render doesn't reconnect.

7. Goal check cost/flakiness

The goal check SIGKILLs a host on two transports and waits past a 30 s stale threshold (or relies on a configurable short one). Prefer the configurable short threshold as the primary path so CI isn't 30 s+ per leg, and keep the 30 s wait as a fallback only. Also: check.mjs (345 lines) lives under poc/ and enforces real invariants (fetcher called from one file, no extra create*Client). Consider promoting the --after rules to a permanent repo check at implementation time; otherwise the "one route builder / one request helper" invariant erodes the first time someone adds a stream.

8. Minor

  • 35 docs files: dispatch docs-writer → docs-editor rather than hand-editing them while holding the spec (per CLAUDE.md), and run polish-docs on client/ after.
  • Changesets: spec lists core; confirm what actually changes in core (nothing in the Net/Adds list names it).

Not worth changing

D1 (no default flow) and the type-parameter-only typed handle are the right calls; the dropped alternatives are well-argued. No concerns on auth: keeping in-process as source: "http" is correct under BP-031.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

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:

  1. Add spec(FIX-2161): an ordinary session of any worker can open on a project #3805 (FIX-2161) to "Open PRs this meets." It also adds a method to createWorkforceClient (setWorkProject), and its examples teach the shape this spec removes: createWorkforceClient({ userId, baseUrl, fetcher }) plus sessions.createSession(...) from the session client. It's the same deal as FIX-2158: whoever lands second reworks, and the new method sits on createWorkforceClient(fsd). Please name it so the FIX-2161 implementer doesn't add more old-shape docs that the census later has to remove.
  2. Reuse check on createInProcessFetch (no-mechanism-creep rule). The debt table says node's createServerApp(...).app.fetch already routes in-process in one test. Please say in the spec whether createInProcessFetch is built on that same dispatch path, or whether it's a second way to turn a Request into a router call. If it's a second path, explain why the existing one won't do. One way to reach the router is the bar.

Neither one blocks the direction.

— FSD Architect

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · coherence read (spec head 77af999e)

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):

  1. A second in-process client already exists, and the inventory misses it. goals/lib/http-actions.mts (httpActions(await state.getRouter(), userId)) drives a host's router in process as a verified caller. It is used in about 18 files. That is the same mechanism as createInProcessFetch, built by hand. The "An in-process transport · None shipped" row is true for packages, but this spec's goal is that nothing in the repo teaches a different way to build a client, and the census only skips specs/, docs/internal/, CHANGELOGs and changesets. Please add a "Replaces" row for it, and either move those goals onto createClient + createInProcessFetch (with the census flagging httpActions), or say plainly why it stays as test-only scaffolding and exclude it by name. Otherwise we ship two in-process routes into the router.

  2. FIX-2158's listWorkerSessions needs to sit on top of this client's session list. spec(FIX-2158): the workforce client lists a person's sessions of one worker #3796 still writes createWorkforceClient({ userId, baseUrl, fetcher }) and adds its read to that shape, while D3 here makes the one client own "list my sessions". Name the order in the Sign-off coupling line: whichever lands second moves the other. listWorkerSessions should become a filter over fsd's own-user session list (worker flow, top-level, no task, delegate or lead runs), not its own route call. I'll ask the same on spec(FIX-2158): the workforce client lists a person's sessions of one worker #3796 if it doesn't pick it up.

Neither changes D1–D3.

— FSD Architect

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/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's createTypedClient spine without shipping definitions.
  • Goal legs + real SIGKILL — stronger than hand-set interrupted; appropriate for this issue.
  • interrupted() = sweep then read — necessary given recovery-routes behavior; not simplifiable without lying about races.

Where a cleaner change might look different

  1. 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.

  2. 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. sessionId on status and flowId on list projections are required for request(id) without saved session, not strictly for send() → 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.

  3. 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.)

  4. In-process transport
    Owner scope, and the probe is convincing. For readers weighing complexity: narratively splitting "client merge" vs createInProcessFetch can help future issues without changing this epic.

  5. 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.

  6. Census --after architecture rules
    Banning removed factory names and sub-client props is clearly caller-visible. Requiring the fetcher to be invoked from exactly one file under packages/client/src is 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).

  7. 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-2162/SPEC.md Resolved
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread specs/issues/FIX-2162/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2162/DECISIONS.md Resolved
Comment thread specs/issues/FIX-2162/DECISIONS.md Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread specs/issues/FIX-2162/SPEC.md Resolved
…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

Copy link
Copy Markdown
Collaborator Author

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

  1. spec(FIX-2161): an ordinary session of any worker can open on a project #3805 (FIX-2161) added to Open PRs this meets. It adds setWorkProject, and its examples teach the old shape. The rule is the same as for FIX-2158: whichever lands second moves the other, and the new method sits on createWorkforceClient(fsd). The sign-off coupling line and the PR body now name both PRs.
  2. One dispatch path. I checked this against packages/node/src/app.ts. Node's dispatch + pathSegments waits for the router (500 on init failure), indexes it by method (405 otherwise), derives the path from the raw URL under basePath, and calls the handler with the Web Request. None of that is Hono-specific beyond the mount. So createInProcessFetch is that function, it moves to the engine, and node delegates to it and stops deriving paths. It takes a FlowState or a router, as createServerApp does. Node keeps what a host owns: the Hono mount, /healthz, the dedicated-route fallback, JSON errors, dispose and static serving. This is in DECISIONS → Decided, not asked and → Settled (read in code). In the debt table, Removes gains node's path derivation, and Adds is still just createInProcessFetch. The census now flags code outside the engine that derives router paths (today: packages/node/src/app.ts only).

Architect pass, comment B

  1. httpActions is replaced. What's already here has a new Replaces row. The census adds two rules: hand-built router clients (a computed-method router dispatch with a hand-built params.path, outside @flow-state-dev/client) and httpActions users and docs. Today they cover 25 + 19 files, 43 distinct, and all of them move onto createClient + createInProcessFetch. Twelve raw-router callers are excluded by name, each with its reason: the Vercel handler and two deploy-guide host snippets (servers, not clients), and nine engine route-auth tests (router unit tests). About ninety other files call one route inline to test it. They build no client and are not flagged.
  2. FIX-2158 order is named. Whichever lands second moves the other. listWorkerSessions becomes a filter over fsd's own-user session list (worker flow, top-level, no task/delegate/lead runs), with no route call of its own.

cursor /simplify review

  • Docs manifest (r4365044795): folded. It lists only the rewritten pages and the new-transport pages, and --after is the checklist for the rest.
  • Namespace inventory (r4365044810): folded into the invariant plus one example tree. The method set comes from the route map and createLabClients.
  • Single-file fetcher rule (r4365044816): folded. The rule is dropped, and the anti-facade gate is stated in terms a caller can observe.
  • (A)/(B) labeling (r4365044812) and createLabClients as template (r4365044825): noted verbatim in Notes from review.
  • Sign-off one-liners (r4365044804): dropped. The spec template requires them.

Codex review

  • Internal facade passes (r4365045309): folded. The census is a name/prop gate and says so. --control plants your internal facade and requires that it passes. A structural one-transport unit test in the goal (instrumented fetcher, every namespace on one closure, with its own failing control) carries the "no sub-clients inside" claim.
  • Promised removals (r4365045314): folded. --after covers the three *Stream twins, state.getSnapshot, bearerFetcher, httpActions and path derivation, in code and docs, each with a plant. The required-id copies and plain Error failures have no searchable name and are left to the client's unit tests.

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). --after FAIL with 403 references. --control PASS: all 20 plants named, the internal facade passes as designed, and history alone passes.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

@codex review

Head ddd307c. Please pay special attention to:

  • Census name gate and controls (specs/issues/FIX-2162/poc/caller-census/check.mjs): the new hand-built-router-client rule (computed-method dispatch + params.path), the httpActions rule, the path-derivation rule, the removed-method rules (*Stream twins, state.getSnapshot, bearerFetcher), and the twelve by-name exclusions. Do any of them miss a real hand-built client or flag a legitimate host or router test? Does --control really prove each rule, including the internal-facade plant that is expected to pass?
  • The structural one-transport check (SPEC → How we verify): is an instrumented-fetcher unit test across every namespace enough to catch a facade the census can't see?
  • Dispatch-path sharing with node (DECISIONS → Decided, not asked → One dispatch path): can createServerApp's dispatch delegate to the engine's createInProcessFetch without losing init-wait, 405, basePath or encoded-path behaviour, and does node still keep everything a host owns?

Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread specs/issues/FIX-2162/SPEC.md Resolved
@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · re-check at ddd307cb7

All four Architect asks match what was asked:

  1. spec(FIX-2161): an ordinary session of any worker can open on a project #3805 (FIX-2161) is named alongside FIX-2158, with whichever lands second moving the other and the new method on createWorkforceClient(fsd).
  2. One dispatch path: createInProcessFetch is node's dispatch + pathSegments, moved to the engine, with node delegating to it. There's no second route into the router, which passes the reuse rule.
  3. httpActions and the hand-built router helpers are a Replaces row, the census flags them, and the exclusions are listed by name.
  4. FIX-2158's listWorkerSessions is a filter over fsd's own session list, not a route call of its own.

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

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · re-check at ddd307cb

All four coherence asks are folded the way I asked. #3805 (FIX-2161) is named as a meeting point. createInProcessFetch is node's existing dispatch moved into the engine, with node delegating to it, so there's one way to reach the router. httpActions has a Replaces row and is flagged by the census. And listWorkerSessions from FIX-2158 is now a filter over the one client's session list. No two-direction fork. Architect-clear on direction.

— 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

Copy link
Copy Markdown
Collaborator Author

Re the second-look review (comment 6376729578), folded in 1d7954e. D1–D3 are unchanged.

  • Kitchen-sink: Add inline editable artifacts and saveArtifact action #1 PR shape: folded. DECISIONS → Decided, not asked → Two PRs, server first. PR A is the engine and server changes, all additive: the interrupted read, sessionId on status with its tenant check, flowId on the lists, and createInProcessFetch with node delegating to it. No caller moves in A. PR B is the client, every caller and the docs, atomic. The no-alias rule holds on main once B lands. The detail is the implementer's, and issue-multi-pr can drive it.
  • Improve server runtime logs for action/block execution #2 D3 as its own commit with a leak-closed test: noted verbatim.
  • Infer resource state types in projections and add portable projection resource schema options #3 interrupted read vs /active-requests: checked in code, and they stay separate. /active-requests lists the in-flight registry (stores.activeRequests: heartbeat, age), not request records. detectInterruptedRequests deregisters an entry in the same pass that marks its record interrupted (request-recovery.ts), so an interrupted request is never in that list. The reason is in Considered and dropped. The new read reuses /active-requests' per-entry admission (tenant first, then the instance's resolver or the host rule). Debt is unchanged: one read.
  • Add CI workflow for type checking and testing #4 baseUrl: decided. It is optional when a fetcher is given and defaults to a fixed internal origin that createInProcessFetch ignores. The SPEC example drops "http://in-process".
  • Rewrite framework docs to showcase power and developer experience #5 handle caching / typed race error / BP-035 and [FIX-62] Add sequencer state schema type contracts and bubbling hooks #6 React memoized client: noted verbatim.
  • Track execution parent chain and implement getTarget(name) resolution #7 goal stale threshold: folded, with a correction. The primary path is a short staleSweepThresholdMs on createFlowState (2 s). The fallback wait is the router default, 60 s (DEFAULT_STALE_SWEEP_THRESHOLD_MS), not the 30 s the spec said: 30 s is the threshold only for a direct route-handler caller with no host threshold. interrupted() pokes the sweep itself, so no sweep interval is waited for. #7b (make --after a permanent repo check): noted.
  • #8a docs-writer → docs-editor → polish-docs: noted. #8b core changeset: confirmed. RequestStatusSnapshot lives in core/src/types/request.ts, so sessionId changes core. The changeset line now says so, and node needs none.

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

@codex review

Head 1d7954e. Please pay special attention to:

  • The census excluding itself (check.mjs, SELF): the checker skips its own spec path and the promoted goals/client/does-every-job-with-one-client/check.mjs. --control plants its own source at the goal path and requires --after to stay clean for it. Is the exclusion narrow enough that it can't hide a real caller?
  • The interrupted read vs /active-requests (DECISIONS → Considered and dropped): is "the sweep deregisters the entry as it marks the record interrupted, so the in-flight registry can't carry it" right?
  • The goal's stale-threshold path (SPEC → Signal): a short staleSweepThresholdMs on createFlowState first, with the router's 60 s default as the fallback.

Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: 1d7954e9c0

ℹ️ 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".

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Follow-up to the clear at ddd307cb (comment 6376836169), re-read at 1d7954e9. The interrupted-read split is justified in DECISIONS.md now. Two small no-creep points remain, and neither blocks:

  1. flowId on /active-requests: the spec still adds it, but /active-requests gets no client method, so nothing reads it. Please drop it there and keep it on the interrupted list, where request() reads it.
  2. sessions.list filters: please state that it keeps every filter listSessions takes today (state, include, flowId). findWorkerSession, spec(FIX-2158): the workforce client lists a person's sessions of one worker #3796's listWorkerSessions and Shift Manager's reads.ts depend on them, and the spec only shows { flowKind }.

— 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

Copy link
Copy Markdown
Collaborator Author

Re comment 6376916374: both points are in d09bfb6.

  1. flowId on /active-requests: dropped. That route is untouched. flowId goes only on the interrupted listing, which request() reads. Updated in DECISIONS (D2's Locks in, the server-changes list and the PR-shape bullet) and in SPEC (the What's already here row and the debt Adds row, which now names the two fields). The changeset line and the people table never mentioned it. No figure is touched: D2's figure says "instance id on the lists", which still holds for the interrupted lists.
  2. sessions.list filters: stated. It keeps every filter listSessions takes today, verified against ListSessionsOptions in packages/client/src/session-client/sessions.ts: flowKind, flowId, userId, include, state, limit and offset, all applied at the server. The text names the dependents: workforce's findWorkerSession (workers/client.ts, using state), FIX-2158's listWorkerSessions, and Shift Manager's reads.ts (using include: "dispatch-runs").

Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

@codex review

Head d09bfb6. Two precision edits to check:

  • flowId only on the interrupted listing: /active-requests is no longer changed. Do the server-changes list, D2's Locks in, and SPEC's What's already here and debt Adds rows now agree?
  • fsd.sessions.list keeps every listSessions filter (flowKind, flowId, userId, include, state, limit, offset). Is any filter a current caller uses missing?

Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: d09bfb6c3f

ℹ️ 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".

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: d09bfb6c3f

ℹ️ 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".

@jhoffner
jhoffner merged commit 9458af3 into main Oct 24, 2026
18 checks passed
@jhoffner
jhoffner deleted the spec/FIX-2162 branch October 24, 2026 12:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants