legend-doctor 0.2.0 → 0.4.0

package/EXAMPLES.md

@@ -234,6 +234,37 @@ function Avatar({ url$ }: { url$: Observable<string> }) {
 This also shows `move-use-value-down` and `move-use-value-into-child`: the parent passes observable references, not
 rendered values.
 
+### Move one subscription into several children
+
+When one observable feeds separate small parts of a large owner, `move-use-value-down` can name several
+boundaries in one instruction. Move every named read together so the parent no longer subscribes.
+
+```tsx
+function Settings({ enabled$ }: { enabled$: Observable<boolean> }) {
+  return (
+    <main>
+      <UnrelatedSettings />
+      <section>
+        <EnabledInput enabled$={enabled$} label="Vertical" />
+      </section>
+      <aside>
+        <EnabledInput enabled$={enabled$} label="Horizontal" />
+      </aside>
+    </main>
+  );
+}
+
+function EnabledInput({ enabled$, label }: { enabled$: Observable<boolean>; label: string }) {
+  const enabled = useValue(enabled$);
+  return <input aria-label={label} disabled={!enabled} />;
+}
+```
+
+Define the children outside the parent, keep observable ownership unchanged, and pass other inputs as ordinary
+props. Keep the evaluation of those inputs in the parent. If a named boundary contains a conditional, keep the
+whole condition inside its always-mounted child. Prefer one cohesive child when it already isolates the reads;
+separate subscriptions add overhead and are justified only when their combined render work stays small.
+
 ### Remove selector work and legacy names
 
 Use `pass-observable-to-use-value` for a direct value and `replace-legacy-use-value` for old APIs.
@@ -246,7 +277,12 @@ useSelector(profile$.name); // Before
 useValue(profile$.name); // After
 ```
 
-Keep `useValue(() => ...)` when the selector derives a value from one or more observables.
+The same-node synchronous selector rewrite without options is `style`: it selects the same value, with no proven
+render or lifecycle saving. Inside `observer`, direct input can use the enclosing observer's tracking instead of a
+separate selector hook. Async selectors and calls with options remain unchanged because their Promise or tracking
+contracts can differ. An eager `useValue(profile$.name.get())` is still `change`: direct input establishes tracking in
+an ordinary component or avoids redundant selector hooks inside `observer`. Keep `useValue(() => ...)` when the
+selector derives a value from one or more observables, including boolean projections and formatted computed values.
 
 ### Compute a derived primitive as an observable
 
@@ -477,7 +513,7 @@ receives, so a raw array breaks it. `useValue(x$.get())` stays with `pass-observ
 
 ### Split a selector that only builds a literal
 
-`split-use-value-result` changes a destructured selector whose members are direct reads or inert expressions.
+`split-use-value-result` offers a `style` rewrite for a const destructured selector whose members are direct reads or inert expressions.
 
 ```tsx
 const { a, b } = useValue(() => ({ a: state$.a.get(), b: state$.b.get() })); // Before
@@ -485,9 +521,12 @@ const a = useValue(state$.a); // After
 const b = useValue(state$.b);
 ```
 
-The selector returns a new object on every tracked change, so each destructured consumer sees a fresh identity.
-Per-path subscriptions render on exactly the same changes and compare by value. Results used whole, block bodies,
-spreads, defaults, rest elements, computed members, and calls stay as they are.
+The aggregate object is fresh; its destructured values retain their own identities. This rewrite removes the result
+allocation and adds per-path subscriptions. It does not prove fewer owner renders, lower CPU cost, or less native
+work. Every observable read must remain represented, including reads in otherwise unused fields: they may invalidate
+ref-backed render snapshots. Omitted effects, duplicate properties, mutable declarations, results used whole, block
+bodies, async selectors, prototype-setting properties, reordered reads, spreads, defaults, rest elements, computed
+members, and calls stay as they are.
 
 ## Keep effect timing correct
 

package/README.md

@@ -1,25 +1,8 @@
 # Legend Doctor
 
-Your React app renders more than it needs to. Legend Doctor proves where, and shows the exact edit that cuts it.
-
-It is a read-only scanner for TypeScript and JavaScript. It reads your `useState`, `useEffect`, and
-[Legend State](https://legendapp.com/open-source/state/) code and reports:
-
-- proven edits that remove a render or an effect
-- edits that need one more fact before they are safe
-- code that is already right and should stay as it is
-
-It never edits files. It never guesses. It emits `change` only when the TypeScript structure proves the edit.
-
-## Why fewer renders
-
-Most React apps re-render whole trees when one value changes. Legend State fixes this by letting each leaf subscribe
-to exactly the value it renders. Jay Meistrich, who built Legend State, explains the idea and the numbers in his
-App.js Conf 2026 talk:
-
-[![How to Build the Fastest Apps: Break the Rules](https://i.ytimg.com/vi/K3flMIHS-cI/hqdefault.jpg)](https://youtu.be/K3flMIHS-cI)
-
-Legend Doctor is the tool that finds those cuts in an existing codebase, and holds every one of them to a proof.
+A read-only analyzer for React and Legend State in TypeScript and JavaScript.
+It reports suggested render and effect optimizations, unresolved opportunities, and code to keep.
+Results are JSON; source files are never modified.
 
 ## Quick start
 
@@ -46,17 +29,12 @@ Copy the skill into your project, then the agent scans before and after every st
 cp -r node_modules/legend-doctor/skills/legend-doctor /path/to/app/.claude/skills/
 ```
 
-The report JSON is stable and versioned. Agents apply `change` findings, read the named source for `candidate`
-findings, and rescan.
-
-To see the effect at runtime, pair it with [genie-react](https://github.com/Genie-sa/genie-react). Genie counts real
-renders in the running app, so the agent can record a render count before the edit and check it dropped after.
+Apply related findings together, validate the changes, and rescan. See [EXAMPLES.md](EXAMPLES.md).
 
 ## Run in CI
 
-The GitHub Action reviews every pull request and reports only the findings the change introduced, not the existing
-backlog. It posts one sticky summary comment, inline review comments on the changed lines, and a commit status. It is
-advisory by default. Add `.github/workflows/legend-doctor.yml`:
+The GitHub Action reports findings introduced by a pull request. It is advisory by default.
+Add `.github/workflows/legend-doctor.yml`:
 
 ```yaml
 name: Legend Doctor
@@ -80,29 +58,14 @@ jobs:
       - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
         with:
           fetch-depth: 0
-      - uses: Genie-sa/legend-doctor@v0.1.1
+      - uses: Genie-sa/legend-doctor@v0.3.0
         with:
           directory: src
 ```
 
 Keep `fetch-depth: 0`. The action diffs the pull request against its base branch and needs the history.
 
-Or paste this to your coding agent:
-
-> Add Legend Doctor to this repository so it reviews every pull request. Create a branch, add the workflow file shown
-> in the "Run in CI" section of https://github.com/Genie-sa/legend-doctor exactly as written, set `directory` to the
-> folder that holds our React components, commit only that file, and open a pull request titled "Add Legend Doctor
-> CI". Do not change application code.
-
-| Input            | Default   | Meaning                                                                                  |
-| ---------------- | --------- | ---------------------------------------------------------------------------------------- |
-| `directory`      | `.`       | Folder to scan                                                                           |
-| `scope`          | `changed` | `changed` reports what the PR introduced, `files` every finding in changed files, `full` |
-| `blocking`       | `none`    | Fail the check on `change`, `candidate`, or `style` findings                             |
-| `materiality`    | config    | `compact` also reports render cuts in components with 8 to 11 JSX elements               |
-| `ignore-actions` | config    | Comma-separated actions to hide, added to the config file's list                         |
-
-The action skips pull requests that change no React files. [action.yml](action.yml) lists every input and output.
+See [action.yml](action.yml) for scope, blocking, filtering, and other options.
 
 ## Configure
 
@@ -141,36 +104,8 @@ Every finding has a disposition:
 | `keep`      | Correct as is. Leave the React or lifecycle boundary alone.               |
 | `style`     | Cleaner form. Apply only when the installed Legend State API supports it. |
 
-Stdout is always one JSON document and stays valid JSON when the scan fails, so a caller parses a single channel and
-never prose. Nothing is written to stderr.
-
-`legend-doctor --help` documents every report field. [REPORT.md](REPORT.md) goes further: the `assumption` a
-`review-state` finding carries when one yes/no fact would turn it into a `change`, and how to record the answer.
-
-## The loop
-
-1. Scan.
-2. Apply one group of `change` findings.
-3. Read the source for each `candidate`. Edit only when the missing fact is proven.
-4. Run your formatter, typecheck, and tests.
-5. Scan again. Stop when every remaining finding is `keep` or an understood `candidate`.
-
-Check [EXAMPLES.md](EXAMPLES.md) before applying an action you have not seen before.
-
-## What it cuts
-
-| Cost                                               | Typical action                                         |
-| -------------------------------------------------- | ------------------------------------------------------ |
-| A parent render caused by one child's local state  | `move-state-down`, `use-observable`                    |
-| A render for a value only commands or cleanup read | `use-ref`                                              |
-| Derived state kept in sync by an effect            | `delete-derived-state`, `delete-effect`                |
-| An effect that runs after an event it could join   | `move-to-event`                                        |
-| A render used only to run an external reaction     | `use-observe-effect`                                   |
-| A subscription wider than the value rendered       | `narrow-use-value-subscription`, `move-use-value-down` |
-| A render read that never subscribes                | `use-value-for-render-read`                            |
-| A parent clone where one path changed              | `narrow-observable-write`, `assign-observable-fields`  |
-
-[EXAMPLES.md](EXAMPLES.md) has one worked example per action.
+See [REPORT.md](REPORT.md) for review blockers, grouped transitions, subscription plans, and runtime measurements.
+Validate suggested edits with your formatter, typecheck, and tests, then rescan.
 
 ## Commands
 
@@ -192,28 +127,8 @@ legend-doctor <root> --actionable --staged              # staged files
 legend-doctor <root> --actionable --since origin/main   # this branch
 ```
 
-By default a render cut proven by owner size needs a component with 12 or more JSX elements. `--materiality compact`
-lowers that to 8. Cuts proven another way — a transported read reaching a child that subscribes, or a custom hook
-owner — do not depend on the tier. Run `--help` for every flag and exit code.
-
-## Safety rules
-
-- One owner per value. Do not mirror React state and an observable.
-- `useObservable` for state tied to a component's lifetime.
-- `useValue` at the smallest stable leaf that renders the value.
-- `.peek()` only in a proven non-tracking command.
-- `.assign()` or `batch()` when several writes are one update.
-- Keep small, one-control state in React when an observable removes no render.
-- Keep an effect when its timing, replay, or cleanup is not proven equivalent.
-- Apply grouped findings together.
-- Check the installed `@legendapp/state` version before changing an API.
-
-Under `@legendapp/state` 2.x the tracking rule is off, because `enableReactTracking({ auto: true })` can make render
-reads track app-wide. In React Compiler projects, keep clone writes unless the report proves the in-place write safe.
-
-These rules follow the [Legend State React API](https://legendapp.com/open-source/state/v3/react/react-api/), the
-[reactivity guide](https://legendapp.com/open-source/state/v3/usage/reactivity/), and the
-[Legend State best-practices skill](https://github.com/LegendApp/legend-skills/tree/main/legend-state-best-practices).
+See `legend-doctor --help` for all flags and exit codes, [ACTIONS.md](ACTIONS.md) for actions, and
+[EXAMPLES.md](EXAMPLES.md) for worked examples.
 
 ## Develop
 

package/REPORT.md

@@ -0,0 +1,244 @@
+# Report reference
+
+Field-level detail for the JSON report. Read [README.md](README.md) first.
+
+Version-gate consumers with `schemaVersion`, currently `4`.
+
+Grouped state findings may also include additive `transitions` evidence. `writes` lists direct
+setter calls with state names, line/column positions, handler identities, and enclosing control
+contexts. `relations` refers to zero-based write indices in the same handler. `coexecution: proven`
+means a shared synchronous path exists; it does **not** mean all executions are one atomic update.
+`disproven` includes separate suspension phases and mutually exclusive/unreachable paths; `unknown`
+retains an explicit proof gap. No relation is inferred between different handlers.
+
+Only `fusion: adjacent-literals` identifies adjacent replacements of distinct fields with literal
+values that can form one `assign`. `preserve-source` means retain evaluation order, branches, and
+exception/suspension boundaries; it does not authorize moving those expressions into an object
+literal. Group reviews name unresolved pairs by exact source location. These are bounded source
+facts, not a complete migration plan or new permission to convert a review finding. Transported
+setters still depend on the existing child-contract proofs and are not listed as direct writes.
+
+Schema 4 removes the unused `diagnostics.semantic` field. Coverage schema 2 reports only `parser`, `lowering`,
+and `detector`: no detector consumed the former semantic stage. The experimental `createSemanticContext`,
+`AnalysisContextOptions.configFilePath`, and semantic context types have been removed.
+
+Important fields:
+
+| Field          | Meaning                                                                     |
+| -------------- | --------------------------------------------------------------------------- |
+| `status`       | `ok` or `error`                                                             |
+| `root`         | Base directory for every finding path                                       |
+| `analyzer`     | Tool `version` and compiled `build`                                         |
+| `findings`     | React state and effect findings                                             |
+| `practices`    | Legend State practice findings                                              |
+| `hidden`       | Findings removed by filters                                                 |
+| `capabilities` | Legend State version and exports, React Compiler status, and disabled rules |
+| `scope`        | Active scope flag and loaded context file count                             |
+
+Compare reports only when `analyzer.build` matches.
+
+Every `review-state` and `review-effect` finding has an `abstentionReason`. It names the main fact or safety rule that
+blocked a proven edit.
+
+Every review also carries `review: { kind, blockers, next }`. This is additive guidance in schema 4;
+the action and disposition remain authoritative. `blockers` combines the current reason, question facts,
+and any group members' known next blockers. It is not an exhaustive list of every missing proof.
+
+| `review.kind`       | Next step                                                                       |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `confirm`           | Research and answer the attached open question.                                 |
+| `recheck`           | Re-read changed source before renewing a stale answer.                          |
+| `declined`          | Preserve the current behavior; the recorded answer rejected the conversion.     |
+| `dependency`        | Resolve the question ids in `waitsOn`, then rescan.                             |
+| `unsupported`       | Resolve a binding, callback, or callable-state shape the analyzer cannot model. |
+| `no-proven-benefit` | Establish a render or lifecycle saving before proposing a migration.            |
+| `investigate`       | Follow `review.next`; no supported yes/no answer currently yields an edit.      |
+
+`async-command-origin-unresolved` means an async pending interval and leaf boundary are proven, but
+the command's event origin is not. This differs from `callback-timing-unresolved`, which concerns
+captured-value reads. Eligible direct JSX event references and inline adapters receive an event-origin
+question; known direct render calls do not. Confirming it preserves the existing async command and
+changes its pending writes and subscriber boundary. Old answers keyed to the former reason do not
+silently confirm this new question.
+
+Use an unfiltered scan to inventory all review kinds. `--actionable` still hides reviews without a
+confirmable question; guidance does not override that filter or make a review actionable.
+
+## Answer a review question
+
+When one yes/no fact is all that blocks a `review-state` finding, the finding also carries an `assumption`:
+
+| Field         | Meaning                                                                                      |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `id`          | Stable across line shifts: report file, owner, state name, blocker                           |
+| `question`    | The concrete fact to confirm, naming the states, targets, or read sites involved             |
+| `facts`       | The blockers a "yes" assumes away; one, or two when a second blocker stands behind the first |
+| `research`    | Distinct checks with `file`, first `line`, all `lines`, and the full source-site `total`     |
+| `ifConfirmed` | The action a confirmed answer produces; the tool re-ran its proofs with that fact assumed    |
+| `fingerprint` | Digest of the owner's source; an answer recorded for a different digest is reported `stale`  |
+| `renderCost`  | JSX elements the owner renders per update of this state                                      |
+| `updateSites` | Setter call sites; `renderCost × updateSites` is the `priority` used by `report.questions`   |
+| `status`      | `open`, `confirmed`, `rejected`, or `stale`                                                  |
+
+A question is asked only when the hypothetical run yields a conversion, so every "yes" has a concrete instruction.
+`report.questions` lists the open ones by `rank`. A group reports the first converting member's action in
+`ifConfirmed` and the number that convert in `convertingCount`; individual outcomes remain in `members`.
+Repeated research instructions list every relevant line and a full site count, including multiple sites on one line. A step without `lines` or `total` describes one site at `line`.
+Record answers in `<root>/.legend-doctor/confirmations.json`, which
+every scan of that root reads, or in any file passed with `--confirm`:
+
+```json
+{
+  "confirmations": [
+    {
+      "id": "src/panel.tsx::Panel::open::atomic-transition-unproven",
+      "fingerprint": "8444a887430f",
+      "answer": "yes",
+      "note": "both writes sit in fail(); Drawer renders open directly (drawer.tsx:12)"
+    },
+    {
+      "id": "src/panel.tsx::Panel::filter::render-cut-unproven",
+      "fingerprint": "4f22f4aca655",
+      "answer": "no"
+    }
+  ]
+}
+```
+
+```bash
+legend-doctor <root>
+```
+
+Or let the tool write the entry, fingerprint included, and report the scan that honours it in one command:
+
+```bash
+legend-doctor <root> --answer "src/panel.tsx::Panel::open::atomic-transition-unproven=yes" --note "both writes sit in fail()"
+```
+
+A `review-effect` finding can carry the same block: an empty-dependency setup effect asks whether `useMount`'s once-only
+semantics are intended. An effect whose verdict waits on a React state instead lists that state's open question ids in
+`waitsOn`, so the answer that settles the state settles the effect.
+
+When assuming the first blocker away still leaves a review verdict, the tool assumes the next one too and asks both
+facts in one question; the id then joins both reasons with `+`, and `facts` lists them in order. Two facts is the cap.
+
+States a handler writes together share one question and one id, `file::Owner::{a,b}::atomic-transition-unproven`.
+Its `members` list says what a "yes" does to each: members whose standalone proof already passes convert together under
+one cluster instruction written with `assign`, and a member another blocker still holds is re-examined without the
+co-write blocker and gets its next question on the same scan.
+
+A confirmed individual question turns its finding into `ifConfirmed` with disposition `change`; a group converts only the members whose outcome is actionable. The answer is recorded in each converted finding's evidence. Such a finding also carries `verification`: the conversion rests on an answer rather than a proof, so the
+recipe names the jsdom harness exported as `legend-doctor/runtime` (`mountDom`, `count`), the before/after comparison
+to run, and the render-count and DOM expectations that must hold; a failed comparison means the answer was wrong. A rejected id keeps the review verdict and stops the question from being asked again. When the owner's code
+changes, the fingerprint no longer matches: the answer is reported `stale`, not applied, and the question is asked
+again. The report's `confirmations` block counts applied, rejected, and stale answers, names the file they came from,
+and lists ids no finding produced.
+
+Failures are also valid JSON. They include `status: "error"`, a stable `reason`, a useful `message`, and
+sometimes a `next` command.
+
+## Compact provenance
+
+`materiality: "compact"` means compact mode changed the finding's action or made a new conversion confirmable.
+Kept findings and outcomes already available in broad mode are untagged. This comparison includes consumer-size
+thresholds for hook-owned state. Compact mode evaluates both policies on the same parsed source; it adds analysis
+work but does not reread or reparse files.
+
+## Coordinated subscriptions (version 1)
+
+`subscriptionAnalysis` is an additive section of schema 4. Its own `version` is `1`.
+
+- `inventory` records each recognized imported `useValue` call in eligible scanned files, including aliases.
+  Each entry contains its source location, binding, observable, classified reads, derivations, and status:
+  `planned`, `other-action`, or `unresolved`. Unresolved entries have explicit reasons; they are not findings.
+- `coverage` counts those three statuses and their total. This is subscription inventory coverage, separate
+  from hook coverage and manually labeled corpus recall. It does not count hidden subscriptions inside
+  arbitrary custom hooks or unrecognized imports.
+- `plans` groups actionable subscription cuts by owner. Overlapping JSX boundaries merge into one child.
+  Each plan lists subscriptions, complete derivation chains, child locations, remaining parent inputs,
+  implementation steps, and behavioral verification. Define new children at module scope and retain their
+  mount slots. Keep observable creation and atomic writes in their existing owner.
+- `impact.basis: "static-jsx"` ranks by owner JSX elements outside the proposed children. These are source
+  counts, not render counts, elapsed time, or a promised speedup. `rank` starts at 1.
+- `impact.basis: "provided-runtime-measurement"` identifies externally supplied before/after render counts.
+  Measurements do not bypass detector proofs or create findings.
+- `rejectedMeasurements` reports malformed, stale, duplicate, or unmatched measurement entries.
+
+A practice finding with a coordinated cut also has `subscription` metadata. Report filters remove matching
+plans and mark filtered inventory entries `excluded-by-report-filter`, so ignored actions do not reappear
+as implementation instructions. Filtering away any part of a plan also removes its runtime measurement;
+measurements of a complete edit cannot rank a partial edit.
+
+To attach runtime evidence, create `<analysis-root>/.legend-doctor/subscription-measurements.json`:
+
+```json
+[
+  {
+    "planId": "copy plans[i].id from the baseline report",
+    "fingerprint": "copy plans[i].fingerprint from the baseline report",
+    "scenario": "toggle the setting ten times with unrelated UI mounted",
+    "samples": 10,
+    "before": { "ownerRenders": 10, "siblingRenders": 30 },
+    "after": { "ownerRenders": 0, "siblingRenders": 0 },
+    "behaviorEquivalent": true
+  }
+]
+```
+
+Record equal interaction samples before and after in the same runtime configuration, excluding initial
+mounts. Verify visible values, drafts, callback snapshots, identity, effect cleanup, and atomic updates
+before setting `behaviorEquivalent`. The analyzer trusts this supplied assertion; it does not run the app.
+Attach the evidence when scanning the **baseline source**: the fingerprint hashes the owner's source text,
+so a scan of the edited owner rejects it as stale. External modules and runtime settings are not included
+in that fingerprint; repeat measurements when either changes. Programmatic `analyzePath` callers may pass
+`subscriptionMeasurements` instead of creating the file.
+
+Measured positive savings rank first, unmeasured static plans next, and measured zero/negative savings last.
+Within measured groups, ranking uses total owner-plus-sibling renders saved per sample. This ordering is a
+triage aid; scenario frequency and render duration still require application profiling.
+
+Closed `const` aliases/defaults and supported `useMemo` projections move with their subscriptions. Memo
+identity and dependencies remain intact. Literal primitive effect dependencies and explicitly typed primitive
+props can prove that an independent effect will not rerun on subscription-only updates. Missing/unstable
+or unresolved dependencies, callback snapshots, refs, overlapping parent subscriptions, repeated render
+callbacks, and unsupported expressions remain conservative blockers. General selector relocation is not
+implied by inventory coverage.
+
+### Imported source coverage
+
+With `--coverage`, `coverage.sourceContext` lists each target file's `requestedProofs` and
+`unavailable` runtime import/re-export edges reachable through indexed source. Each edge names the
+`importer`, `specifier`, selected `resolvedFile` when present, and one reason:
+
+- `module-unresolved`: TypeScript did not select a module under the current installation/configuration.
+- `declaration-only`: TypeScript selected a declaration file, which cannot supply implementation behavior.
+- `source-not-indexed`: the selected implementation is outside the source index or was rejected after parser recovery.
+
+Paths are relative to the scan root. Installed dependencies and package export conditions retain their
+normal precedence; this diagnostic never substitutes a same-named workspace implementation.
+`requestedProofs` names file-level source-symbol queries used by current consumers (such as observable,
+observable-factory, component, and callback contracts). An unavailable edge can block these proofs;
+it does not establish that any particular recommendation was missed. Known framework API contracts
+may still work without implementation source. Detector stage `analyzed` describes execution, not
+complete imported semantics. Empty `unavailable` does not prove export compatibility or successful
+symbol proofs. Type-only, side-effect-only, dynamic imports and CommonJS require edges are outside
+this static symbol-edge inventory. Ordinary reports and action scoring are unchanged.
+
+## Helper tracking reviews
+
+`review-helper-tracking` practices have `disposition: candidate`. They identify a direct local helper
+called from an imported `useValue`, `useObserve`, `useObserveEffect`, or `observe` selector. The
+selector must have independent direct reads. A direct parent read already covers a helper's child
+read; a helper's broader parent read can introduce sibling dependencies beyond a direct child read.
+Evidence lists helper reads, writes, and synchronous `batch` boundaries.
+Additional dependencies can repeat selector work; the review does not establish React render savings,
+a measured execution count, or permission to replace shared helper reads with `peek`.
+
+This first phase abstains on imported helpers, call chains, recursion, mutable or shadowed dispatch,
+async/generator functions, parameter defaults, conditional or abrupt control flow, unproven helper
+initialization, and unresolved calls. Nested
+callback bodies do not inherit tracking merely by lexical containment. Separate reaction arguments
+remain separate. These limits can miss opportunities; absence of a review is not proof of no tracking.
+
+Use `--disposition candidate` to inspect these reviews. `--actionable` hides them and counts them under
+`hidden.practices`. They are listed separately from optimization precision in corpus output.

package/dist/src/analysis/assumptions/async-command-hypothesis.d.ts

@@ -0,0 +1,4 @@
+import type { Hypothesis, HypothesisScope } from "./hypotheses.js";
+/** The async interval and leaf cut have already passed; only command origins may be assumed. */
+export declare function asyncCommandHypothesis(scope: HypothesisScope): Hypothesis | null;
+//# sourceMappingURL=async-command-hypothesis.d.ts.map

package/dist/src/analysis/assumptions/async-command-hypothesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-command-hypothesis.d.ts","sourceRoot":"","sources":["../../../../src/analysis/assumptions/async-command-hypothesis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAkGnE,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,GAAG,IAAI,CAiChF"}

package/dist/src/analysis/assumptions/async-command-hypothesis.js

@@ -0,0 +1,101 @@
+import { bindingDeclarationCount, isNonValueIdentifier, unwrapTransparentExpression, } from "../../core/analysis-ast.js";
+import { findAncestorUntil, identifiersNamed, nearestNestedFunction } from "../../core/ast.js";
+import { isBindingName } from "../../rules/child-contract/prop-bindings.js";
+import { runtimeFunctionName } from "../ast-helpers.js";
+import ts from "typescript";
+/** Timing confirmation cannot establish execution through arbitrary control flow. */
+function directAdapterCall(expression) {
+    const { body } = expression;
+    if (!ts.isBlock(body)) {
+        return body;
+    }
+    const [statement] = body.statements;
+    if (body.statements.length !== 1 || !statement) {
+        return undefined;
+    }
+    return ts.isExpressionStatement(statement) || ts.isReturnStatement(statement)
+        ? statement.expression
+        : undefined;
+}
+/** A direct JSX event reference or inline event adapter can be researched; an eager call cannot. */
+function eventReference(reference, scope) {
+    const attribute = findAncestorUntil(reference, ts.isJsxAttribute, scope.inputs.state.owner);
+    const initializer = attribute?.initializer;
+    if (!attribute ||
+        !/^on[A-Z]/u.test(attribute.name.getText()) ||
+        !initializer ||
+        !ts.isJsxExpression(initializer) ||
+        !initializer.expression) {
+        return null;
+    }
+    const expression = unwrapTransparentExpression(initializer.expression);
+    if (expression === reference) {
+        return attribute;
+    }
+    return isDirectAdapter(reference, expression, scope) ? attribute : null;
+}
+function isDirectAdapter(reference, expression, scope) {
+    if (!ts.isCallExpression(reference.parent) ||
+        reference.parent.expression !== reference ||
+        nearestNestedFunction(reference, scope.inputs.state.owner) !== expression ||
+        (!ts.isArrowFunction(expression) && !ts.isFunctionExpression(expression)) ||
+        expression.asteriskToken) {
+        return false;
+    }
+    const call = directAdapterCall(expression);
+    return Boolean(call && unwrapTransparentExpression(call) === reference.parent);
+}
+function commandEventReferences(scope) {
+    const { state, usage } = scope.inputs;
+    const commands = new Set(usage.setterCallNodes.map((call) => nearestNestedFunction(call, state.owner)));
+    const sites = [];
+    for (const command of commands) {
+        const events = command ? eventsForCommand(runtimeFunctionName(command), scope) : null;
+        if (!events) {
+            return null;
+        }
+        sites.push(...events);
+    }
+    return sites.length > 0 ? sites : null;
+}
+function eventsForCommand(name, scope) {
+    if (!name || bindingDeclarationCount(scope.inputs.state.owner, name) !== 1) {
+        return null;
+    }
+    const references = identifiersNamed(scope.inputs.state.owner.body, name).filter((reference) => !isBindingName(reference) && !isNonValueIdentifier(reference));
+    const events = references.map((reference) => eventReference(reference, scope));
+    return events.length === 0 || events.some((event) => event === null)
+        ? null
+        : events.filter((event) => event !== null);
+}
+/** The async interval and leaf cut have already passed; only command origins may be assumed. */
+export function asyncCommandHypothesis(scope) {
+    if (!scope.inputs.isUnprovenAsyncStatus) {
+        return null;
+    }
+    const sites = commandEventReferences(scope);
+    if (!sites) {
+        return null;
+    }
+    const lines = [
+        ...new Set(sites.map((site) => scope.inputs.sourceFile.getLineAndCharacterOfPosition(site.getStart()).line + 1)),
+    ].toSorted((left, right) => left - right);
+    const [line] = lines;
+    if (line === undefined) {
+        return null;
+    }
+    return {
+        inputs: { ...scope.inputs, isAsyncLeafStatus: true, isUnprovenAsyncStatus: false },
+        question: `The pending interval and leaf render boundary of \`${scope.inputs.state.valueName}\` are proven. Confirm every listed callback prop invokes its command only from a user event, never during render, memo calculation, effect setup, or subscription registration; keep the command and its async completion boundary unchanged.`,
+        research: [
+            {
+                file: scope.reportFile,
+                line,
+                lines,
+                total: sites.length,
+                check: "Open every receiving component and follow this callback prop through wrappers to its event handler; a prop name alone does not prove event timing.",
+            },
+        ],
+    };
+}
+//# sourceMappingURL=async-command-hypothesis.js.map

package/dist/src/analysis/assumptions/async-command-hypothesis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-command-hypothesis.js","sourceRoot":"","sources":["../../../../src/analysis/assumptions/async-command-hypothesis.ts"],"names":[],"mappings":"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"}

package/dist/src/analysis/assumptions/group-assumptions.js

@@ -75,7 +75,7 @@ function memberResearch(scope, { alone, member }) {
             ? []
             : [
                 {
-                    check: `this write to \`${member.valueName}\` runs in a handler that also writes other members of ${names}; confirm a render could never observe one member updated without the others`,
+                    check: `inspect each write to \`${member.valueName}\` in the connected group ${names}; preserve its branch, await, and exception phase, and verify which same-phase writes must publish together`,
                     file: scope.reportFile,
                     line: lines[0],
                     lines,
@@ -89,13 +89,13 @@ function groupQuestion(owner, outcomes) {
     const converting = convertingOutcomes(outcomes);
     const blocked = outcomes.filter((outcome) => groupConversion(outcome.alone) === null);
     const converts = converting.length > 0
-        ? ` A "yes" converts ${quotedList(converting.map(({ member }) => member.valueName))} into one observable object written with a single \`assign\`.`
+        ? ` A "yes" converts ${quotedList(converting.map(({ member }) => member.valueName))} into one observable object with a separate atomic update for each proven synchronous transition.`
         : "";
     const reasons = [...new Set(blocked.map(({ alone }) => remainingLabel(alone)))].join(", ");
     const remains = blocked.length > 0
         ? ` ${quotedList(blocked.map(({ member }) => member.valueName))} ${blocked.length === 1 ? "is" : "are"} not converted by this answer (${reasons}); a remaining blocker gets its own question next.`
         : "";
-    return `${names} are written together in ${owner}'s handlers; confirm they change as one atomic transition that no render may observe half-applied.${converts}${remains}`;
+    return `${names} are written together in ${owner}'s handlers; verify the individual write relations in \`transitions\` and confirm a migration that preserves each branch, await, and catch/finally phase. A connected group is not a single atomic transition; synchronous coexecution alone does not authorize merging expressions into one \`assign\`.${converts}${remains}`;
 }
 function confirmedVerdict(outcome, converting, hookOwned) {
     const { alone } = outcome;