Org2 Performance Guard

ORG2 Performance Guard

Apply a lifecycle-first performance audit to every changed runtime path. Preserve correctness and realtime behavior while making idle work demand-driven, shared, bounded, scoped, and disposable.

Non-negotiable invariants

Require all applicable invariants before delivery:

• Keep idle CPU close to zero. Do not add continuous work merely to detect possible change.
• Prefer push invalidation over polling. Keep polling only as a documented, low-frequency safety net.
• Pause non-critical polling, scans, animation work, and retries while document.visibilityState === "hidden"; revalidate once on visibility/focus return.
• Treat durable outbox, lease, and safety work as explicit exceptions. Bound their frequency, backoff, and scope instead of disabling correctness-critical work blindly.
• Single-flight equivalent requests. Concurrent consumers must share one promise or coordinator.
• Key cloud/user data by endpoint + authenticated user + resource scope. Never key security-sensitive caches by orgId or sessionId alone.
• Bound every app-lifetime Map, Set, array, buffer, queue, log, and worker-owned session registry. Use LRU/TTL/pagination and explicit eviction.
• Evict per-session state on session deletion, worker crash/dispose, auth or endpoint switch, org removal, and feature unmount as applicable.
• Subscribe to the narrowest state slice. A session view must not rerender for unrelated sessions' streaming deltas.
• Coalesce bursty updates before crossing React, IPC, database, or serialization boundaries.
• Keep hot streaming/parser loops allocation-light. Avoid repeated clones, full-buffer parses, formatting, and JSON conversion per delta.
• Keep blocking filesystem, database, git, and process work off async executor threads and render-critical paths.
• Load large histories, request rounds, diffs, and replay segments on demand; do not eagerly materialize invisible data.
• Isolate secondary Tauri identities completely: data home, external-history home, ports, cookies/auth, and app-lifetime caches.
• Treat provider ingestion, local identity/listability, UI hydration, cloud transport, and remote rendering as separate verification boundaries. Passing A-to-B sync does not prove the upstream local lifecycle.
• Test every provider and raw source transition claimed by the change. Do not infer Claude Code compaction coverage from Codex append coverage, or vice versa.
• Keep rendered E2E strict. Missing UI must fail with diagnostics; never turn a regression into console.warn, catch-and-continue, or a debug-helper bypass.

Required workflow

1. Establish the performance surface

Read the changed call chain from its production entry point. Inventory every resource the change can create or retain:

• setInterval, recursive setTimeout, requestAnimationFrame, debounce, retry, backoff
• DOM/Tauri/network listeners and Realtime channels
• workers, subprocesses, watchers, file scans, git operations, database reads
• module globals, atom maps, per-store maps, promises, abort controllers, buffers
• React subscriptions, selectors, derived arrays, render-time sorting/grouping
• eager list/history/diff/replay loading

Use targeted searches, adapting paths to the diff:

rg -n "setInterval|setTimeout|requestAnimationFrame|addEventListener|listen\(|subscribe|channel\(" src src-tauri
rg -n "new Map|new Set|WeakMap|cache|inFlight|buffer|queue|history" src src-tauri
rg -n "poll|refresh|retry|scan|watch|stream|delta|dispose|cleanup|abort" src src-tauri

Do not treat grep hits as findings. Trace ownership, start conditions, steady-state behavior, and cleanup.

2. Build the lifecycle matrix

For each resource, record the required behavior in these states:

Flag any resource whose owner or terminal state is ambiguous.

3. Separate provider lifecycle from machine topology

For provider history, session identity, dedupe, or sync work, build a coverage matrix before testing:

Apply these validity rules:

• Treat each matrix cell as independent evidence. Two machines exercise topology; they do not create provider compaction, rotation, or lineage transitions automatically.
• Exercise the raw provider artifact or a faithful before/after fixture. Do not seed only normalized cache/database rows when the parser, watermark, identity, lineage, or dedupe contract is under test.
• Derive identity markers from the raw artifact. Do not fabricate identical group keys that merely restate the implementation assumption.
• Include an assumption-breaking fixture for identity logic: for example, a rewritten transcript head with a changed first-message UUID but a preserved ancestry marker.
• Observe local ingest and listability before enabling or asserting cloud upload. Then verify upload cursor/payload and remote rendering separately.
• Keep the previous session active, open, or pinned while applying the source transition when exact-id hydration or force-reveal paths exist.
• Repeat rescan/restart once to prove idempotence and stable row/resource counts.
• Name every unexecuted provider or transition. Never summarize partial coverage as “multi-provider,” “dual-machine,” or “full lifecycle.”

4. Choose the correct pattern

Apply the smallest applicable pattern:

• Push + safety TTL: subscribe to authoritative change events; use a slow TTL only to recover missed events.
• Visibility-aware recursive timeout: keep at most one timer, clear it while hidden, run once and reschedule on return. Prefer this over overlapping intervals.
• Single-flight coordinator: key by identity and resource, share the in-flight promise, carry an invalidation version/generation, and prevent stale completion from overwriting newer state.
• Bounded LRU/TTL: refresh recency on read, cap entry count, give failures a short TTL, and provide lifecycle eviction.
• Per-store state: use WeakMap<Store, ...> when multiple Jotai stores or rendered instances can exist in one process.
• Narrow subscription: use per-session atoms/selectors or keyed stores rather than reading a global delta map.
• Burst coalescing: batch updates once per frame or bounded debounce; preserve terminal/final events.
• Demand-driven loading: paginate or fetch details only after expansion/selection; retain only the visible or recently used window.
• Generation guard: discard late async results after stop, restart, account switch, endpoint switch, or a newer request.

5. Sweep equivalent paths

After finding one issue, search for every semantic peer. A fix is incomplete if another surface still owns a parallel implementation.

Typical ORG2 sweeps:

• Sidebar + management panel + share dialog + Work Item hooks fetching the same roster
• Visible and hidden polling paths
• Primary launcher and direct secondary executable startup
• Positive, negative, and in-flight cache entries
• Worker success, crash, dispose, session deletion, and app shutdown
• Local session, cloud member session, guest import, fork, and external CLI history
• Production action and rendered E2E action

Unify duplicate resource ownership before tuning individual call sites.

6. Protect correctness and privacy

Performance changes must not weaken:

• realtime propagation after push invalidation
• revocation/removal disappearance
• durable outbox retries and tombstones
• account/endpoint/org data isolation
• first-load and focus-return freshness
• session fork/history integrity
• terminal streaming events

Capture identity and generation at request start. Before committing a result, confirm the current identity/generation still matches. Do not display a previous identity's cached rows while refreshing.

7. Verify proportionally

Always run:

• targeted unit tests for cache bounds, coalescing, invalidation, visibility, and stale-result rejection
• TypeScript typecheck and lint for changed frontend files
• Rust unit tests/checks for changed backend modules; if the shared Cargo cache is corrupt or policy-blocked, report it and use the narrowest valid independent compilation without deleting broad caches
• git diff --check

For rendered/background changes, also run the real Tauri surface when available:

1. Isolate primary and secondary data homes, provider roots, auth, ports, and processes.
2. Capture a baseline: raw files, cache rows/listability, active/open/pinned row, cursor/epoch, payload count, process count, CPU, and RSS as applicable.
3. Apply the raw source transition while ORG2 is already open. For compaction/rewrite/rotation, stage or produce the actual before/after artifact instead of pre-populating the final database state.
4. Assert local parsing, identity/lineage, exact row count, listability, timestamp, and sidebar behavior before cloud transport can hide the owning-boundary failure.
5. Keep an old row active/open/pinned, rescan, and assert that hydration does not resurrect a superseded sibling or hide the active row entirely.
6. Verify A upload and B download/reconnect separately, including cursor/epoch and exact appended payload counts when incremental behavior is claimed.
7. Rescan and restart once; confirm data and request/subscription/timer/process counts remain stable.
8. Measure visible idle, hidden idle, active work, and post-close/post-delete behavior.
9. Exercise account switch, endpoint switch, and direct secondary launch when relevant.
10. Confirm strict rendered E2E uses user-visible actions for the behavior under assertion.

Do not claim a performance improvement from code shape alone. State the evidence actually collected and any environment blocker.

Review rejection rules

Reject or revise a change when any applicable answer is unknown or false:

• Who owns this background resource, and exactly when is it stopped?
• Can this timer overlap itself or continue while hidden?
• Why is polling necessary instead of invalidation?
• Can two mounted consumers issue the same request?
• Does the cache have a maximum size, freshness rule, identity key, and eviction event?
• Can an old async completion write after a newer request or identity switch?
• Does one session's update wake unrelated session views?
• Does a growing transcript/history/diff require full eager materialization?
• Does a direct secondary launch inherit primary external history or auth state?
• Which provider and raw source transition produced the evidence for each compatibility claim?
• Did the test inspect local ingest and identity before testing cloud transport?
• Did it keep the previous row active/open/pinned across rescan or only test a clean roster?
• Were family/identity keys parsed from raw artifacts, or fabricated to match the implementation?
• Did “dual-machine” testing merely replicate an already-normalized final state?
• Can a missing rendered element be skipped while the E2E still passes?

Required delivery output

Report findings and evidence in this compact form:

For provider ingestion, session identity, or sync work, also report:

Use one row per materially distinct matrix cell. A shared implementation permits shared unit coverage only at the shared boundary; each provider adapter still needs representative raw input before claiming compatibility.

End with:

• Performance verdict: pass only when every applicable invariant is evidenced.
• Performance verdict: blocked when required real measurement, provider transition, or compilation cannot run; name the blocker and the uncovered matrix cells.
• Performance verdict: fail when an unbounded, duplicate, hidden-active, stale-write, or cross-identity path remains.

Never promise that a skill can make regressions impossible. Enforce the gates, expose unknowns, and refuse an unsupported green verdict.