Repository Oom Audit

Repository OOM Audit

Purpose

Finds heap, native-memory, thread, file-descriptor, and retained-graph conditions that can exhaust a process. Produces an evidence-backed report without confusing lexical matches, plausible risks, and confirmed defects.

This is an audit method, not a pattern dump. Every tracked file receives a screening disposition, every positive finding is traced through ownership and cleanup, and important non-issues remain visible as coverage evidence.

Safety Invariants

1. Record the exact commit before analysis.
2. Keep the target repository read-only unless the user separately authorizes fixes.
3. Do not commit, push, open issues, or create pull requests unless explicitly asked.
4. Preserve unrelated work in dirty checkouts.
5. Store generated inventories and reports outside the target when repository policy forbids audit artifacts.
6. Do not copy substantial source into reports; cite and paraphrase.
7. Treat runtime profiling as optional and non-invasive. Never collect or expose sensitive heap contents without explicit authorization.

Completion Standard

An audit is complete only when:

• the commit and repository state are recorded;
• every tracked file has a disposition or explicit assessment limitation;
• every taxonomy category has a coverage result, including zero-result categories;
• heap, requested-array, native/direct, thread-stack, metaspace/class-loader, finalization/reference, and container/process memory domains are addressed;
• every candidate is classified as confirmed, plausible, or reviewed non-issue;
• every actionable finding has anchored evidence, severity, confidence, trigger, retained-memory analysis, remediation, and test guidance;
• exclusions, unavailable sources, and runtime limitations are explicit; and
• inventory and report consistency checks pass.

Workflow

1. Freeze identity and constraints

Record:

git rev-parse HEAD
git status --short
git remote -v
git submodule status

Capture repository guardrails, generated/vendor policy, authorized output location, build system, runtime versions, and whether source modifications are forbidden. Line citations refer to this commit even if the working tree later changes.

2. Build the exhaustive inventory

Use Git as the scope authority:

git ls-files -z

Classify every path by:

• language and file type;
• production, test, tooling, generated, vendored, configuration, or binary;
• module/component;
• screening disposition; and
• limitation or exclusion reason.

Required dispositions:

Do not silently exclude tests, tooling, generated files, or vendored code. They can cause test-runner OOMs, ship into production, or reveal unsafe producer/consumer contracts. Grouping is allowed only when each path remains present in the inventory.

Validate inventory completeness by comparing the sorted inventory path column with a fresh git ls-files result. The symmetric difference must be empty.

3. Map memory ownership and input boundaries

Identify long-lived roots:

• process and class statics;
• application/session/request objects;
• event loops, UI trees, actors, and service containers;
• executor workers, timers, and thread locals;
• native handles and callback registries;
• class loaders, plugins, reflection metadata, and generated-code caches.

Identify growth inputs:

• user files, uploads, clipboard, drag-and-drop, and command arguments;
• network responses, sockets, messages, subprocess output, and logs;
• archive entries, serialized graphs, parser nodes, media dimensions, and metadata;
• internal event rates, edit histories, retries, and concurrent task submission.

Trace: source -> allocation/growth -> owner -> retention root -> cleanup/bound -> concurrency multiplier.

4. Screen the complete taxonomy

Use language-aware semantic/code-intelligence tools first, then repository search. Search terms are candidate generators, never proof.

Record zero matches explicitly. Also search aliases and framework-specific equivalents for each detected language and dependency.

5. Trace and classify every candidate

Read declarations, constructors, mutators, owners, call sites, error paths, cancellation, shutdown, tests, and configuration. Verify whether limits are hard, configurable, attacker/user controlled, count-only, or weight-aware.

Classification:

• Confirmed defect: Static evidence proves a reachable unbounded/missing-lifecycle mechanism under stated conditions. Runtime reproduction strengthens but is not required.
• Plausible risk: The mechanism exists, but reachability, cardinality, ownership, lifetime, input trust, or practical trigger needs confirmation.
• Reviewed non-issue: Evidence proves a finite domain, effective bound/eviction, complete lifecycle, weak ownership, streaming behavior, or non-production isolation.

Never promote a regex match to a finding. Never omit a significant reviewed non-issue merely because it is not actionable.

6. Score severity and confidence separately

Severity:

Confidence:

• High: Direct code and ownership evidence; trigger and missing bound/cleanup are clear.
• Medium: Strong mechanism evidence with one unresolved lifecycle/input assumption.
• Low: Indirect signal requiring call-path or runtime confirmation.

7. Quantify retention and amplification

For each finding, estimate:

• retained objects and their root;
• per-item or per-task weight;
• growth variable and practical maximum;
• simultaneous representations/copies;
• native stack/direct/GPU/file-handle contribution;
• concurrency multiplier; and
• whether GC can reclaim the graph.

Use checked arithmetic. Distinguish retained leaks from transient peak amplification: both can produce OOM, but remediation differs.

Derive a provisional concurrency ceiling from measured peak retained/native bytes per task and the memory budget remaining after heap baseline, JVM/native overhead, and a safety margin. Do not select pool sizes from CPU count alone when tasks retain large images, documents, archives, or response graphs.

8. Use authoritative evidence

Prioritize current primary sources:

1. language and runtime specifications/API documentation;
2. framework/library/vendor documentation;
3. operating-system and file-format specifications;
4. maintained security/performance guidance from authoritative organizations;
5. reputable secondary sources only when primary guidance is unavailable.

Record source title, version, URL, and the claim it supports. If user-provided sources or runtime artifacts are unavailable, say so without inventing their contents.

9. Recommend behavior-compatible remediation

Recommendations must:

• preserve documented behavior or identify the intentional behavior change;
• add characterization tests before changing ambiguous behavior;
• bound by memory weight as well as count where item sizes vary;
• define overflow, rejection, coalescing, spill, or eviction semantics;
• close resources on success, exception, cancellation, timeout, and shutdown;
• avoid silent drops and broad exception swallowing; and
• include observability for limits, queue depth, evictions, rejections, and peak usage.

10. Validate without destabilizing the target

Static validation:

• inventory symmetric difference is empty;
• every inventory row has a disposition;
• every taxonomy row has a result;
• every citation resolves at the audited commit;
• every positive finding has all required fields;
• confirmed/plausible/non-issue counts match the report;
• exclusions and limitations are explicit; and
• the target Git status has not changed.

Optional runtime validation:

• reproduce under a deliberately small heap or memory limit;
• use JFR, heap histograms/dumps, native-memory tracking, descriptor counts, and thread dumps when safe;
• compare at least two equivalent post-GC snapshots or recordings across repeated workload cycles, including dominator and GC-root-path differences;
• correlate live-set growth with thread, class-loader, queue, cache, direct-buffer, file-descriptor, and process-RSS trends rather than assuming every OOM is a heap leak;
• compare dominators, retained sizes, queue/cache cardinality, and resource counts before and after repeated operations; and
• clean up all temporary data and processes.

Runtime failure to reproduce does not disprove a statically confirmed unbounded mechanism; document environment, workload, duration, and observed ceiling.

Required Report Format

# OOM and Memory-Retention Audit

## Audit identity
- Repository, commit, branch, dirty state, runtime/tool versions

## Scope and inventory
- Counts by production/test/tooling/generated/vendored
- Inventory artifact path/hash
- Per-file dispositions and limitations

## Method and taxonomy coverage
- Search/analysis tools
- Category result table, including zero matches

## Confirmed defects
### [ID] [Title]
- Classification
- Severity / confidence
- Evidence: repository-relative path:line-range, anchored to commit
- Trigger
- Retained memory and root
- Growth/amplification/concurrency analysis
- Existing bound/cleanup and why it fails
- Behavior-compatible remediation
- Test and runtime validation
- Authoritative sources

## Plausible risks
- Same fields, with unresolved assumptions stated

## Reviewed non-issues
- Candidate, evidence, and proven bound/cleanup/finite scope

## Coverage gaps and limitations
- Inaccessible files, generated/vendor treatment, unavailable sources,
  omitted runtime work, environment constraints

## Prioritized remediation plan
- Order by severity, confidence, effort, and behavior risk

Evidence Quality Gate

Reject or downgrade a finding when:

• the citation is only an import, declaration, or lexical match;
• no retention root or peak-allocation path is identified;
• a cleanup/eviction path was not inspected;
• the trigger is impossible under the input contract;
• the collection domain is demonstrably finite;
• test-only code is presented as production reachable;
• severity conflates impact with confidence; or
• claims rely on unavailable sources.

The final report should be reproducible by another reviewer at the recorded commit.