buffers: complete the counter set + sensitive/clear enforcement (OWN024)

[PhysShell]

Closes the small gaps from the stackalloc/logging design audit.

Counters (§10): emit the four metrics that were specified but missing — ScratchTotalRequestedBytes / ScratchMaxRequestedBytes (via Requested()), ScratchPoolBytesReturned (via PoolReturned(), inside the rented-null guard), and ScratchForcedClears (via ForcedClear(), next to a clear-on-release). All scratch-scoped and under [Conditional("OWNSHARP_COUNTERS")].

Sensitive buffers (OWN024, §12): a sensitive option / policy key, and a check that a buffer marked sensitive but not cleared on release is rejected -- pooled/scratch arrays return to a shared ArrayPool, native memory goes back to the allocator, so leaving secret bytes unzeroed is the silent leak the flag exists to prevent. The report (json + text) now carries sensitive.

README: document OWN024 + the full counter set; the unsafe-contract (UNS0xx, §6) and benchmark-matrix (§13) work stays flagged as roadmap.

Tests: 5 OWN024 analysis cases (option + policy, cleared/uncleared, malformed) and 2 codegen-content cases for the new counter emission. Suite: analysis 100/100, codegen content 23/23, property fuzz clean (20k draws).

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for sensitive buffer attribute and policy key.
  • Improved scratch/stack buffer runtime counter instrumentation (requested bytes/max, forced clears, pooled bytes returned).

• New Diagnostics

  • OWN024: emitted when a sensitive buffer isn’t cleared on release (clear = true expected).

• Documentation

  • Expanded buffer policy/validation rules and updated the runtime counters and metrics documentation.

• Reports & Tests

  • Reports now include a per-buffer “Sensitive” value.
  • Extended regression/codegen tests for the new attribute, diagnostics, and counters.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 548550b0-2cad-4a7f-9464-481e6f2ba6be

📥 Commits

Reviewing files that changed from the base of the PR and between 6cdec36 and 79956b1.

📒 Files selected for processing (1)

• ownlang/codegen.py

---

📝 Walkthrough

Walkthrough

Adds a sensitive boolean attribute to the buffer policy system. When sensitive = true is set without clear = true, the resolver emits the new OWN024 diagnostic. C# codegen is extended to emit OwnCounters.Requested, OwnCounters.ForcedClear, and OwnCounters.PoolReturned calls at scratch buffer allocation and release sites, backed by new runtime counter fields and methods in the emitted OwnCounters class. Reports, tests, and docs are updated accordingly.

Changes

sensitive attribute, OWN024 diagnostic, and scratch counter instrumentation

Layer / File(s)	Summary
sensitive attribute contract and OWN024 enforcement ownlang/diagnostics.py, ownlang/buffers.py	Registers OWN024 title in TITLES, extends VALID_OPTIONS and VALID_POLICY_KEYS to include sensitive, adds sensitive: bool field to BufferInfo, and implements the resolution rule that emits OWN024 when sensitive = true without clear = true.
Scratch OwnCounters instrumentation in codegen ownlang/codegen.py	Emits OwnCounters.Requested(size) at stack-alloc and pool scratch paths, OwnCounters.ForcedClear() on clear-on-release, and OwnCounters.PoolReturned(size) on pool return. Expands the emitted OwnCounters runtime class with ScratchTotalRequestedBytes, ScratchMaxRequestedBytes, ScratchPoolBytesReturned, ScratchForcedClears fields and corresponding conditional methods.
Report output, tests, and docs ownlang/report.py, tests/run_tests.py, tests/test_codegen.py, README.md	Adds sensitive field to JSON and text report output. Adds regression cases for sensitive buffer policies and extends smoke assertions for new OwnCounters symbols. Adds codegen test cases for ForcedClear and PoolReturned emissions. Updates README with OWN024 entry, expanded counter descriptions, and updated validation rules.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 Hop-hop, a secret buffer, marked so dear,
Must clear its bytes before it disappears!
OWN024 now guards the zeroed gate,
While counters tally bytes — both small and great.
ForcedClear, Requested, PoolReturned too,
The rabbit keeps the memory metrics true! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and concisely summarizes the two main objectives: completing the counter instrumentation set for buffers and implementing the sensitive buffer enforcement (OWN024 diagnostic).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/codegen-bugs-tests-670240

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

ownlang/codegen.py (1)

707-719: 💤 Low value

CAS loop is correct and thread-safe.

The compare-and-swap retry loop correctly updates the max value in a concurrent environment. The early return when bytes <= cur avoids unnecessary CAS attempts.

Optional: Add comment explaining retry logic

Consider adding a brief comment above the do-while loop:

         System.Threading.Interlocked.Add(ref ScratchTotalRequestedBytes, bytes);
+        // CAS retry loop: update max if bytes > current max; retry if concurrent update
         long cur;
         do

This helps future maintainers quickly understand the concurrency pattern.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ownlang/codegen.py` around lines 707 - 719, Add a brief explanatory comment
above the do-while loop in the Requested method to document the compare-and-swap
(CAS) retry pattern. The comment should explain that this loop safely updates
the ScratchMaxRequestedBytes maximum value in a concurrent environment by
repeatedly reading the current value with Interlocked.Read and attempting to
update it with Interlocked.CompareExchange, retrying if another thread modified
the value in between. This will help future maintainers quickly understand the
thread-safe concurrency pattern being used.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@ownlang/codegen.py`:
- Around line 707-719: Add a brief explanatory comment above the do-while loop
in the Requested method to document the compare-and-swap (CAS) retry pattern.
The comment should explain that this loop safely updates the
ScratchMaxRequestedBytes maximum value in a concurrent environment by repeatedly
reading the current value with Interlocked.Read and attempting to update it with
Interlocked.CompareExchange, retrying if another thread modified the value in
between. This will help future maintainers quickly understand the thread-safe
concurrency pattern being used.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3c808e4e-7c99-42b4-b828-c920151cf8d8

📥 Commits

Reviewing files that changed from the base of the PR and between 01da03d and 6cdec36.

📒 Files selected for processing (7)

• README.md
• ownlang/buffers.py
• ownlang/codegen.py
• ownlang/diagnostics.py
• ownlang/report.py
• tests/run_tests.py
• tests/test_codegen.py