8000 Decompose useRuns and useDocumentLifecycle further · Issue #52 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content

Decompose useRuns and useDocumentLifecycle further #52

Open

Description

@kiran-brahma

What

src/useDocument.ts was decomposed from 1,777 lines into six hooks (594-line composer). Two of the
extracted hooks are still large and are the natural next step:

  • src/runs/useRuns.ts — 794 lines.
  • src/document/useDocumentLifecycle.ts — 564 lines.

Why they were left whole

Both have a real reason, so this is a considered deferral rather than an oversight:

  • useRuns holds all five Run kinds because they share runInFlightRef, abortRef, priceTable
    and sessionCost. Splitting per kind would add churn across four call sites without removing any
    shared state.
  • useDocumentLifecycle bundles persistence + Library + metadata + durability, which are cohesive
    around one DocumentRecord and one persistence controller.

What a follow-up should do

Find the seam that actually deletes shared state rather than just moving lines. Candidate: a single
run-state value (a discriminated union over the five Run kinds) replacing the five independent
{running, startedAt, error} triples — which would also remove the class of bug fixed in
anyRunInFlight (src/editor/announcements.ts), where one call site enumerated the flags
incorrectly.

Constraints

  • DocumentHandle is 98 members and is consumed by App.tsx, WorkingOrderRail, BandPanel,
    JudgePanel and WorkbenchView. Keep it stable, or change all consumers in the same commit.
  • send(ModelRequest) -> Promise<string> stays the only test seam. There is no DOM test layer, so a
    change here is verified by tsc, the existing suite and the build only — read the dependency
    arrays by hand.
  • Preserve existing useCallback/useMemo/useEffect closure semantics exactly.

Origin

The residual of finding M1 from the Thermos review.

Activity

  1. kiran-brahma commented on Sep 26, 2026

    @kiran-brahma
    OwnerAuthor

    Decision (Writer, 2026-09-26): hand to an agent, last. Relabelled ready-for-agent and blocked by every terminal v1.3 ticket so it does not conflict with the Rail and settings work. The constraints above stand: keep DocumentHandle stable or change every consumer in the same commit, preserve hook closure semantics exactly, verify by tsc, the suite and the build, and read the dependency arrays by hand. The run-state union is the seam to aim for; if it does not delete shared state, stop and report rather than moving lines.

  2. added
    ready-for-agentSpec is ready for an agent to implement
    and removed on Sep 26, 2026
  3. kiran-brahma commented on Sep 26, 2026

    @kiran-brahma
    OwnerAuthor

    Stopped before changing any code, per the Writer's decision: the run-state union does not delete shared state on v1.3 (55b0ad8).

    A single discriminated value over the five Run kinds only removes state if at most one Run can be in flight at a time. On v1.3, several can run at once, and the per-kind errors are shown independently of each other:

    1. Reader, Audit and Judge runs can start while other Runs are going. anyRunInFlight only gates the Findings Run buttons and the structural set (WorkingOrderRail.tsx, busy={runBusy}). The Reader and Audit Run buttons are disabled only by their own flag (BandPanel.tsx, disabled={!pass.enabled || running}), and so is the Judge (JudgePanel.tsx, canJudge … !running). The hook has no shared guard either: runReaderPass checks only readerInFlightRef, runAuditPass checks only auditInFlightRef, and runJudge has no ref guard at all. So a Findings Run, a Reader run, an Audit run and a Judge can all be in flight together, each showing its own RunningBadge or timer.
    2. The structural set and a model Pass are in flight together by design. runStructuralSet calls runModelPass, so structuralRunning and runningPassId are both set at once. announcementForTransition depends on that pair ("intermediate passes inside it do not announce finished").
    3. Errors outlive their Runs, one per kind. runError, readerError, auditError and judgeError each stay visible in their own panel until that kind runs again or resetReadouts fires. If a failed Findings Run is followed by a successful Reader run, the Findings error is still shown. A single value would lose it.

    So a union has two ways to go, and neither satisfies the ticket:

    • One value that really is a union. Starting any Run would replace the others' state. That forces Runs to be serialised (Reader, Audit and Judge buttons disabled during any Run, or the hook refusing them) and drops persisted errors. Both are behaviour changes, which the constraints rule out.
    • A per-kind record ({ model?: {passId, startedAt, structural}, reader?: {startedAt, error}, … }). This holds the same fields as today's triples, grouped differently. It moves lines and deletes nothing.

    The shared state the issue names doesn't shrink under either option. runInFlightRef and the three abort controllers from #46 stay, because each guards or cancels its own kind, and Cancel run already aborts all three. priceTable and sessionCost have nothing to do with run state. The per-kind *InFlightRefs have to stay too, since they are what stops a second click before React renders the running state.

    Other ways forward, for the Writer to choose from (none started):

    • Decide that one Run at a time is the rule. The doc comment on anyRunInFlight already says so ("a second Run must not start while any of them is going"), but only the Findings and structural buttons enforce it. If that is the intended behaviour, a separate behaviour ticket could gate Reader, Audit and Judge on anyRunInFlight and add one shared in-flight guard in useRuns. After that ships, the union really would delete state: one in-flight value plus one ref would replace four refs and the running/startedAt pairs, with errors kept per kind. Decompose useRuns and useDocumentLifecycle further #52 could then be done as the refactor on top of it.
    • Take a smaller, honest cut now. readerRunning is always set together with readerStartedAt, and auditRunning with auditStartedAt, so each flag could be derived from its timestamp. That removes two useStates and nothing else. I don't think it meets "delete shared state" and haven't made the change.
    • Close as won't fix. The five-kinds-in-one-hook design reflects a real product fact: independent Runs that can run concurrently.

    useDocumentLifecycle was not attempted: the Writer's decision points #52 at the run-state union.

    Labelled needs-info pending the Writer's call on whether one Run at a time is the intended rule.


    Generated by Claude Code

  4. added
    needs-infoWaiting on reporter for more information
    and removed
    ready-for-agentSpec is ready for an agent to implement
    on Sep 26, 2026
  5. kiran-brahma commented on Sep 26, 2026

    @kiran-brahma
    OwnerAuthor

    Handed back to a human (supervisor). The agent stopped as the 2026-09-26 decision instructs: on v1.3 the run-state union would not delete shared state, because Runs of different kinds can be in flight together and each kind's error stays on screen after its Run ends (details in the comment above). No code was changed.

    I verified the core finding: anyRunInFlight's doc comment (src/editor/announcements.ts:75) says "a second Run must not start while any of them is going", but only the Findings Run buttons and the structural set honour it; the Reader and Audit Run buttons check only their own flag (src/editor/BandPanel.tsx:537, :600), and the Judge the same. So either the comment or the gating is wrong.

    Decision needed: (a) make one-Run-at-a-time the enforced rule as a behaviour ticket first, after which the union genuinely deletes state and #52 can proceed; (b) the small cut (derive readerRunning/auditRunning from start times), which does not meet the "delete shared state" bar; or (c) close as won't fix.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs-infoWaiting on reporter for more informationready-for-humanRequires human implementation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0