docs: document the class vs module-state convention (audit L3) - #576

Summary

Closes out audit finding L3 ("Class vs module-function patterns mixed without documented rule — document the rule; no code change needed"). Adds one CONVENTIONS bullet to lib/AGENTS.md writing down the rule the codebase already follows:

• Classes for state that needs multiple independent instances or dependency injection (AccountManager per pool, CircuitBreaker per account, SessionAffinityStore per proxy) and for the CodexError hierarchy.
• Module-level state + plain functions only for genuinely process-global concerns (auth rate-limit trackers, the routing mutex, UI runtime options, the storage-meta cache), and always paired with a test reset helper (reset*ForTests / resetVolatileRuntimeState-style) so suites can isolate it.
• Never module-level state for anything a caller might want two of.

Doc-only; no code paths touched. With this, the audit's L-tier items are either fixed (L1 partial via #517/#534 line), documented (L3 here), or roadmapped pending maintainer decisions (L2 rename, L4 postinstall, L5 pin rationale).

Validation

• Markdown only.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

doc-only change that closes audit finding L3 by writing down the class-vs-module-state convention the codebase already follows. no runtime code is touched.

• adds a single bullet to the CONVENTIONS section of lib/AGENTS.md explaining when to use a class (multiple independent instances or DI) vs module-level state (genuinely process-global, always paired with a test reset helper)
• explicitly bans module-level state for anything a caller might want two of, and requires a reset*ForTests/resetVolatileRuntimeState-style helper for any module that does carry global state

Confidence Score: 5/5

markdown-only edit to a dev-facing knowledge base file; no runtime code, no token handling, no filesystem paths altered.

the new bullet accurately captures the class-vs-module-state split already present in the codebase, includes concrete class names as examples, mandates the test-reset helper that existing module-level state already ships, and slots cleanly into the existing CONVENTIONS section without contradicting any prior rule.

no files require special attention

Important Files Changed

Class Diagram

%%{init: {'theme': 'neutral'}}%%
classDiagram
    direction LR
    class AccountManager {
        +per pool instance
        +dependency-injected
    }
    class CircuitBreaker {
        +per account instance
        +dependency-injected
    }
    class SessionAffinityStore {
        +per proxy instance
        +dependency-injected
    }
    class CodexError {
        +hierarchy root
    }
    note for AccountManager "USE A CLASS\nwhen caller may want\nmultiple independent instances"

    class moduleRateLimits {
        <<module-level state>>
        +process-global
        +resetForTests()
    }
    class moduleRoutingMutex {
        <<module-level state>>
        +process-global
        +resetForTests()
    }
    class moduleUIRuntimeOptions {
        <<module-level state>>
        +process-global
        +resetVolatileRuntimeState()
    }
    note for moduleRateLimits "USE MODULE STATE\nonly when truly global\n+ must have reset helper"

_{Reviews (1): Last reviewed commit: "docs: document the class vs module-state..." | Re-trigger Greptile}

Context used:

• Context used - lib/AGENTS.md (source)