This file provides guidance to agents when working with code in this repository.
- OwnAudit is the canonical audit repo (since 2026-07-18): the lift-out from
Own.NET/audit/happened and the direction reversed —Own.NET/audit/is deprecated and Own.NET stays a pure SAST engine that emits findings. New aggregation/reporting/runtime/fix work lands here, not there. (Older docs in both repos may still state the pre-reversal boundary;docs/collector-plan.mdis the current word.) src/OwnAudit.Cliandsrc/OwnAudit.Runtimeintentionally targetnet8.0-windowsbecause runtime work depends on FlaUI/ClrMD; Linux work here is mainly the Python tooling/tests.OwnAudit.Runtimeis the home of the ClrMD heap collector (docs/collector-plan.md).- Python tests are designed to run as bare scripts because
pytestis not guaranteed in the dev shell:PYTHONUTF8=1 python3 arch/tests/test_arch.pyor any*/tests/test_*.pyfile directly. - Finding identity is a frozen contract, not a helper.
identity/pattern.pyimplementsfinding-pattern/v1andcontracts/finding-pattern-v1.jsonholds its canonical vectors;viz/apply_verdicts.finding_idis an alias for it. Every storedfp-verdicts.jsonoverlay is keyed by those exact bytes, so changing the algorithm, separator, truncation or field order orphans the verdicts — and the result is an empty report, not an error. Do not "clean up" the hash or normalize paths/messages. The SARIFpartialFingerprints["ownAudit/v1"]is a different, legacy GitHub-correlation key (normalized message, full digest,/ordinalsuffix) and must never be used as an identity. - Normalization is a ported stage with a byte-parity contract.
aggregate/normalize.py+aggregate/sarif_read.py+aggregate/taxonomy/categories.jsoncame from the deprecatedOwn.NET/audit/aggregate/(Own.NET#266 slice 1A) and must keep producing byte-identicalfindings.json;aggregate/tests/fixtures/parity/expected-findings.jsonwas generated by the reference implementation, so a diff there means the port drifted, not that the golden is stale. SetOWNNET_REF=/path/to/Own.NETto also re-derive the golden and re-verify the JSON taxonomy against the YAML it was transcribed from. The taxonomy is JSON, not YAML, because the Python tooling is stdlib-only — do not reintroduce a PyYAML dependency to read it. Seedocs/normalization.md. - Identity is refused, not approximated.
identity/occurrence.py(finding-occurrence/v1) mints anoccurrence_idonly when the producer run, the producer, the pattern and an UNAMBIGUOUS physical anchor are all known; otherwise it emitsnullplus machine-readableidentity_limitations. Its fields are LENGTH-PREFIXED, not separator-joined - a raw separator lets a control character shift between two fields and produce one preimage for two occurrences (the defectfinding-pattern/v1is frozen with); never "simplify" that back to a join. Never add an ordinal tiebreaker (it would make identity depend on SARIF emission order), never substitute a column the producer did not report (start_columnis nullable on purpose - Own.NET's_caret_colis a renderer heuristic, not a coordinate), and never call a SARIF file digest aproducer_run_id(that isinput_digest, a provenance field). Run identity comes only from aproducer-provenance/v1manifest via--provenance; a digest mismatch is rejected with exit 2, not degraded, and a malformed manifest raises rather than being coerced. One--sarifinput per producer name (provenance is keyed by producer, so two runs under one name cannot be represented) - it fails loudly.Run-Audit.ps1vouches only for what it observed: pre-existing Infer#/Roslyn SARIF getproducer_run_id: nullandsource_commit: null, a reused CodeQL DB getssource_commit: null, and a DIRTY target tree getssource_commit: nullbecause the analyzers read the working tree rather than HEAD. Seedocs/finding-identity.md. - The payload is
normalized-findings/v2: the ten frozen v1 fields plus four identity fields. The slice-1A parity golden is compared throughproject_v1and is NEVER regenerated from the code under test - a failing projection means v2 changed something it promised only to add to. - Full Linux-safe regression sweep:
PYTHONUTF8=1 python3 aggregate/tests/test_normalize.py && PYTHONUTF8=1 python3 identity/tests/test_occurrence.py && PYTHONUTF8=1 python3 arch/tests/test_arch.py && PYTHONUTF8=1 python3 fix/tests/test_orchestrate.py && PYTHONUTF8=1 python3 fix/tests/test_own_fix.py && PYTHONUTF8=1 python3 fix/tests/test_ai_fix.py && PYTHONUTF8=1 python3 leakmine/tests/test_leakmine.py && PYTHONUTF8=1 python3 report/tests/test_baseline.py && PYTHONUTF8=1 python3 report/tests/test_sarif.py && PYTHONUTF8=1 python3 report/tests/test_rules_map.py && PYTHONUTF8=1 python3 report/tests/test_annotate.py && PYTHONUTF8=1 python3 report/tests/test_exec.py && PYTHONUTF8=1 python3 viz/tests/test_dashboard_rules.py && PYTHONUTF8=1 python3 runtime/tests/test_runtime.py && PYTHONUTF8=1 python3 runtime/tests/test_member_aware.py && PYTHONUTF8=1 python3 oracle/fixtures/test_oracle_arch.py && PYTHONUTF8=1 python3 oracle/fixtures/test_oracle_runtime.py. - To run the collector against real STS documents, build the shipping stand first —
docs/sts-stand-build.md(worktree build intoSetup,SERIALIZERSIM_SETUP,leaktest --hold). Run-Audit.ps1is Windows-stand oriented and drives external Own.NET worktrees; it setsPYTHONUTF8=1, emits SARIF intoartifacts/, and clusters optional Infer#/Roslyn results only if their SARIF files already exist.- Use
Run-Audit.ps1 -Codeqlfor CodeQL corroboration. The clustering window is raised from 3 to 8 automatically when Infer# or Roslyn are folded in, because those tools report shifted/generated locations; the raise is announced on stdout. Passing-LineTolexplicitly always wins — even a value below 8, which is warned about and then honoured, never silently corrected. The decision isResolve-LineTolinscripts/LineTolPolicy.ps1, and its matrix is pinned byscripts/tests/Test-LineTolPolicy.ps1on Windows and Linux. Run-Infersharp.ps1consumes built STS.dll+.pdbfiles via WSL and filters third-party/generated SARIF beforeRun-Audit.ps1folds it.Run-Roslyn.ps1requires VS2022 BuildTools and injects analyzers with/p:OwnAudit=true; analyzer packs must stay in per-pack cache subdirs to avoidGu.Roslyn.Extensionsconflicts.- The three runners are pwsh-only, and say so where the engine can act on it.
Run-Audit.ps1,Run-Infersharp.ps1andRun-Roslyn.ps1each open with#Requires -Version 7and are kept byte-level ASCII (OwnAudit#64). The two go together: Windows PowerShell 5.1 reads a BOM-less file in the system ANSI codepage, so a single non-ASCII byte used to surface as a syntax error inside whatever word contained it - the requirement is unreachable if the file cannot be parsed to find it. The contract is NOT that the runners work under 5.1; it is that 5.1 can read them and refuse them for a true reason. Do not "fix" this with a BOM (it leaves the file non-ASCII and makes correctness depend on three bytes an editor may drop), and do not reintroduce typographic dashes into these files.scripts/tests/Test-RunnerShellContract.ps1enforces it on both editions. - Generated/derived outputs live under
artifacts/,arch/out/,report/out/,runtime/out/, andleakmine-out/; avoid treating them as source truth unless a test fixture explicitly depends on them. .editorconfighas a project-specific C# gotcha:*.csfiles use CRLF while JSON/YAML/Markdown/PowerShell use 2-space indentation.