sourcecode 5.9.27__py3-none-any.whl → 5.9.28__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.9.27"
+__version__ = "5.9.28"

sourcecode/_build_commit.py

@@ -1,5 +1,5 @@
 """Generated at build time by hatch_build.py. Do not edit (AUD-592-D04)."""
 
-BUILD_COMMIT = '034ad2aa52cd47f3b55a26f58f19536458e15ef3'
+BUILD_COMMIT = 'adbbf9ca7652e2ad2dfdb2db911c12e1793dded5'
 CLOSURE_PROVENANCE = {'AUD-611-B05': {'commit': '', 'status': 'uncited'}, 'AUD-611-B06': {'commit': '', 'status': 'uncited'}, 'AUD-611-B07': {'commit': '', 'status': 'uncited'}, 'AUD-611-B08': {'commit': '', 'status': 'uncited'}, 'AUD-611-B09': {'commit': '', 'status': 'uncited'}, 'AUD-611-B10': {'commit': '', 'status': 'uncited'}, 'AUD-611-B11': {'commit': '', 'status': 'uncited'}, 'AUD-612-07': {'commit': '', 'status': 'uncited'}, 'AUD-612-09': {'commit': '', 'status': 'uncited'}, 'AUD-612-14': {'commit': '', 'status': 'uncited'}, 'AUD-612-B03': {'commit': '', 'status': 'uncited'}, 'AUD-612-B07': {'commit': '', 'status': 'uncited'}, 'AUD-612-B13': {'commit': '', 'status': 'uncited'}, 'AUD-612-E': {'commit': '', 'status': 'uncited'}, 'AUD-612-G': {'commit': '', 'status': 'uncited'}, 'AUD-612-I': {'commit': '', 'status': 'uncited'}, 'AUD-612-K': {'commit': '', 'status': 'uncited'}, 'AUD-612-M': {'commit': '', 'status': 'uncited'}, 'AUD-612-R': {'commit': '', 'status': 'uncited'}, 'AUD-613-ROOT': {'commit': '', 'status': 'uncited'}, 'AUD-614-07': {'commit': '', 'status': 'uncited'}, 'AUD-614-E': {'commit': '', 'status': 'uncited'}, 'AUD-614-F': {'commit': '', 'status': 'uncited'}, 'AUD-614-G': {'commit': '', 'status': 'uncited'}, 'AUD-614-I': {'commit': '', 'status': 'uncited'}, 'AUD-614-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-614-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-614-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-614-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-615-07': {'commit': '', 'status': 'uncited'}, 'AUD-615-COLD-COMPACT': {'commit': '', 'status': 'uncited'}, 'AUD-615-DRIFT': {'commit': '', 'status': 'uncited'}, 'AUD-615-E': {'commit': '', 'status': 'uncited'}, 'AUD-615-F': {'commit': '', 'status': 'uncited'}, 'AUD-615-INTENT-TIE': {'commit': '', 'status': 'uncited'}, 'AUD-615-JUNIT4': {'commit': '', 'status': 'uncited'}, 'AUD-615-RISK-L0': {'commit': '', 'status': 'uncited'}, 'AUD-615-SELFTEST-TIMEOUT': {'commit': '', 'status': 'uncited'}, 'AUD-616-E-PROV': {'commit': '', 'status': 'uncited'}, 'AUD-616-F, -RISK-L0, -SELFTEST-TIMEOUT, -INTENT-TIE, -DRIFT, -COLD-COMPACT, -E, -07': {'commit': '', 'status': 'uncited'}, 'AUD-616-INTENT-TIE-COV': {'commit': '', 'status': 'uncited'}, 'AUD-616-JUNIT4-SELF': {'commit': '', 'status': 'uncited'}, 'AUD-616-KOTLIN': {'commit': '', 'status': 'uncited'}, 'AUD-616-O': {'commit': '', 'status': 'uncited'}, 'AUD-616-P': {'commit': '', 'status': 'uncited'}, 'Window': {'commit': '', 'status': 'uncited'}, '`ASK-FIELD-01`': {'commit': '829f9fa', 'status': 'present'}, '`ASK-FIELD-02`': {'commit': '6a659fa', 'status': 'present'}, '`ASK-FIELD-03`': {'commit': '55b0d51', 'status': 'present'}, '`AUD-588-F05`': {'commit': '470e4a4', 'status': 'present'}, '`AUD-590-B01` / `B-01`, `F-01`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B02` / `B-02`, `F-02`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B03` / `B-03`, `F-03`': {'commit': '', 'status': 'uncited'}, '`AUD-590-B04` / `B-04`, `F-04`': {'commit': '', 'status': 'uncited'}, '`AUD-590-R01` / `R-01`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A01` / `A-1`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A02` / `A-2`, `A-4`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A03` / `A-3`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A05` / `A-5`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A06` / `A-6`, `A-7`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A08` / `A-8`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A09` / `A-9`': {'commit': '', 'status': 'uncited'}, '`AUD-591-A10` / `A-10`': {'commit': '', 'status': 'uncited'}, '`AUD-592-A02` / `A-1` second half, `§12.5`': {'commit': '63f3d61', 'status': 'present'}, '`AUD-592-B01` / `B-8`': {'commit': '8329614', 'status': 'present'}, '`AUD-592-D01` / `D-1`': {'commit': '0f8e03f', 'status': 'present'}, '`AUD-592-D02` / `D-2`': {'commit': '1d3db4d', 'status': 'present'}, '`AUD-592-D03` / `D-3`': {'commit': 'f28fe40', 'status': 'present'}, '`AUD-592-R01` / `A-1`': {'commit': '216025f', 'status': 'present'}, '`AUD-592-R02` / `N-4`, reopens `AUD-513-N04`': {'commit': 'ec3050d', 'status': 'present'}, '`AUD-593-N01` / `N-01`': {'commit': 'dd6a706', 'status': 'present'}, '`AUD-593-N02` / `N-02`': {'commit': 'f539787', 'status': 'present'}, '`AUD-593-N03` / `N-03`': {'commit': '1dd0b1c', 'status': 'present'}, '`AUD-593-N05` / `N-05`': {'commit': 'aa89388', 'status': 'present'}, '`AUD-593-N06` / `N-06`': {'commit': 'aa584a6', 'status': 'present'}, '`AUD-594-N04` / `D-5`, disclosure half of `B-3`': {'commit': 'a0060b7', 'status': 'present'}, '`AUD-594-X01` / `A-1`, residual of `AUD-593-N03`': {'commit': 'dd222b9', 'status': 'present'}, '`AUD-594-X02` / `A-1` second half': {'commit': '1193937', 'status': 'present'}, '`AUD-594-X03` / `X-03`, residual of `AUD-593-N01`': {'commit': 'e89e8f0', 'status': 'present'}, '`AUD-594-X04`': {'commit': '05b8cc9', 'status': 'present'}, '`AUD-595-A02` / `N-5`, advisory half of `AUD-588-B11`': {'commit': '3e15227', 'status': 'present'}, '`AUD-595-A03` / `B-6` exit-code half': {'commit': 'ab7285f', 'status': 'present'}, '`AUD-595-A05`': {'commit': 'e0b3d10', 'status': 'present'}, '`AUD-595-A07`, narrow half of `AUD-592-A02`': {'commit': 'cc15177', 'status': 'present'}, '`AUD-595-B01` / §B': {'commit': 'b77a1ad', 'status': 'present'}, '`AUD-595-Q01`': {'commit': '91a6566', 'status': 'present'}, '`AUD-596-A01` / `ASK-DET-001`': {'commit': 'fa508b4', 'status': 'present'}, '`AUD-596-A02` / `ASK-SELF-001`': {'commit': '4dfadc8', 'status': 'present'}, '`AUD-596-A03` / `ASK-C1-001`': {'commit': 'bffa3a6', 'status': 'present'}, '`AUD-596-A04` / `ASK-UX-003` + `ASK-UX-004`': {'commit': 'f0aac3c', 'status': 'present'}, '`AUD-596-B01` / `B-01`, harder witness for `BUG-6`': {'commit': '567d09d', 'status': 'present'}, '`AUD-596-B02` / `B-02`, class residual of `R2`': {'commit': '', 'status': 'uncited'}, '`AUD-596-B03` / `B-03`': {'commit': 'a8cb814', 'status': 'present'}, '`AUD-596-B06` / `B-06`': {'commit': '8107927', 'status': 'present'}, '`AUD-596-B07` / `B-07`, class residual of `AUD-592-R02`': {'commit': 'e060485', 'status': 'present'}, '`AUD-596-B09` / `B-09`': {'commit': '5b8146c', 'status': 'present'}, '`AUD-596-B10` / `B-10`': {'commit': '5cb994d', 'status': 'present'}, '`AUD-596-B16` / `B-16`': {'commit': '1507f69', 'status': 'present'}, '`AUD-596-D01` / `B-13` + `B-14`': {'commit': '0b1bdf0', 'status': 'present'}, '`AUD-596-D02` / `B-08`, residual of `AUD-594-N04`': {'commit': 'e7f73c3', 'status': 'present'}, '`AUD-596-D03` / `ASK-AGT-001`': {'commit': '8c46967', 'status': 'present'}, '`AUD-596-D04` / `B-18`': {'commit': '040f027', 'status': 'present'}, '`AUD-596-D05` / `B-19`': {'commit': 'fd2bf68', 'status': 'present'}, '`AUD-596-D06` / `B-20`': {'commit': '784cd83', 'status': 'present'}, '`AUD-596-D07` / `B-17`, half refuted': {'commit': 'c3ff822', 'status': 'present'}, '`AUD-596-D08` / `B-22`, class residual of `AUD-591-A06`': {'commit': 'b396c6a', 'status': 'present'}, '`AUD-596-D09` / `B-23`, surviving half of `B26`': {'commit': 'fd3d63f', 'status': 'present'}, '`AUD-596-D10` / `B-29`': {'commit': '', 'status': 'uncited'}, '`AUD-596-D11` / `ASK-UX-005`': {'commit': 'f4b4f77', 'status': 'present'}, '`AUD-596-D12` — six hints that send the reader back to the error': {'commit': '498df44', 'status': 'present'}, '`AUD-596-D13` / `B-28`': {'commit': '1014c72', 'status': 'present'}, '`AUD-596-D14` / `B-15`, narrow half of `B20`': {'commit': '10f2827', 'status': 'present'}, '`AUD-596-R01` / `B-05`': {'commit': '', 'status': 'uncited'}, '`AUD-596-X01` / `ASK-GATE-001`, gating half of `B24`': {'commit': 'e59c655', 'status': 'present'}, '`AUD-596-X02` / `ASK-UX-001` + `ASK-UX-002` + `B-21`': {'commit': 'f6ebf50', 'status': 'present'}, '`AUD-597-A01` / `ASK-UX-001` + `N-01`': {'commit': 'f8cf061', 'status': 'present'}, '`AUD-597-A02` / `ASK-UX-008` + `ASK-DOC-002`': {'commit': '9d47a4c', 'status': 'present'}, '`AUD-597-A03` / `ASK-DET-001`': {'commit': '4c7622a', 'status': 'present'}, '`AUD-597-A04` / `ASK-LEDGER-001`': {'commit': '46fb870', 'status': 'present'}, '`AUD-597-D01` / `B-04`': {'commit': '1094e6a', 'status': 'present'}, '`AUD-597-D02` / `ASK-DOC-001`': {'commit': 'ecb1bb7', 'status': 'present'}, '`AUD-597-D03` / `N-06`': {'commit': '9784333', 'status': 'present'}, '`AUD-597-D04` / `N-05`': {'commit': 'e51c087', 'status': 'present'}, '`AUD-597-D05` / `N-04`, fourth appearance of `C4-27`': {'commit': '9cccc15', 'status': 'present'}, '`AUD-597-D06` / `ASK-CLI-001`': {'commit': '178aa6d', 'status': 'present'}, '`AUD-597-D07` / `N-03`': {'commit': '9245e35', 'status': 'present'}, '`AUD-597-R01` / `ASK-PERF-001`': {'commit': '6910054', 'status': 'present'}, '`AUD-597-R02` / `ASK-ENC-001`': {'commit': 'ce6dac1', 'status': 'present'}, '`AUD-597-R03` / `ASK-UX-002`': {'commit': 'c57e50b', 'status': 'present'}, '`AUD-597-X01` / `ASK-BUILD-001` + `ASK-META-001` / `B-12`': {'commit': '354338b', 'status': 'present'}, '`AUD-598-B01` / `ASK-META-001`': {'commit': 'b2f7c65', 'status': 'present'}, '`AUD-598-B02` / `ASK-UX-002`': {'commit': '56a4bf7', 'status': 'present'}, '`AUD-598-B03` / `B-11`': {'commit': 'c63cb24', 'status': 'present'}, '`AUD-598-B04` / `N-02`': {'commit': '187937f', 'status': 'present'}, '`AUD-598-R01` / `ASK-PERF-002`': {'commit': '', 'status': 'uncited'}, '`AUD-598-X01` / `N-01` + `B-13` + `B-14` + `B-29` + `N-06`': {'commit': '6f2f5a4', 'status': 'present'}, '`AUD-600-B01` / `P-01`': {'commit': '366ffed', 'status': 'present'}, '`AUD-600-B02` / `P-02` + `ASK-PACK-002`': {'commit': '2a814c3', 'status': 'present'}, '`AUD-600-B03` / `ASK-PACK-001`': {'commit': '452f2a0', 'status': 'present'}, '`AUD-600-D01`': {'commit': '1224e1b', 'status': 'present'}, '`AUD-600-D02`': {'commit': 'eab8172', 'status': 'present'}, '`AUD-600-R01` / `R-01`': {'commit': '88add64', 'status': 'present'}, '`AUD-601-B01` / `N-02`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-B02` / `ASK-PACK-004`': {'commit': '', 'status': 'uncited'}, '`AUD-601-D01` / `N-01`, `ASK-UX-001`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-D02` / `B-13`, `B-14`, 5th round': {'commit': '', 'status': 'uncited'}, '`AUD-601-M01` / `B-26`, `B-27` retracted': {'commit': '', 'status': 'uncited'}, '`AUD-601-R01` / `R-02`': {'commit': '', 'status': 'uncited'}, '`AUD-619-WATCH`': {'commit': '', 'status': 'uncited'}, '`AUD-620-COMMAND-SURFACE`': {'commit': '', 'status': 'uncited'}, '`AUD-620-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`AUD-621-REVIEW-PR`': {'commit': '', 'status': 'uncited'}, '`B-3`': {'commit': '773268d', 'status': 'present'}, '`B-6`': {'commit': '17c6e06', 'status': 'present'}, '`B-8`': {'commit': '8329614', 'status': 'present'}, '`BUG-15`': {'commit': '', 'status': 'uncited'}, '`BUG-21`': {'commit': '', 'status': 'uncited'}, '`BUG-3` / `443b345`': {'commit': '', 'status': 'uncited'}, '`BUG-4a` / `AUD-588-B11` residual': {'commit': '24b4185', 'status': 'present'}, '`BUG-4b` / `AUD-588-B11` residual': {'commit': '0376350', 'status': 'present'}, '`E-39`, class residual of `AUD-593-N06`': {'commit': '25fc11f', 'status': 'present'}, '`N-5`': {'commit': 'c68083f', 'status': 'present'}, '`N-7`': {'commit': '082e9de', 'status': 'present'}, '`R-1`': {'commit': '424fb1c', 'status': 'present'}, '`R-2`': {'commit': '5158b92', 'status': 'present'}, '`R-3`': {'commit': '88aec04', 'status': 'present'}, '`R-4`': {'commit': '04fd04f', 'status': 'present'}, '`REG-01`': {'commit': '', 'status': 'uncited'}, '`REG-04`': {'commit': '', 'status': 'uncited'}}
 CLOSURE_COVERAGE = {'closed_rows': 169, 'present': 91, 'absent': 0, 'unresolved': 0, 'uncited': 78, 'unknown': 0}

sourcecode/_docs/DEFECT-LEDGER.md

@@ -14,8 +14,127 @@ Status values: `open` · `in-progress` · `closed <version>` · `by-design` (wit
 The facts these rows are keyed to are published: `ask schema facts-v1` prints the registry
 (authority, definition, consumers, parity test) that the release battery enforces.
 
+## Current Synchronization — Release `5.9.28`, nine rows closed on the 5.9.27 queue (2026-09-02)
+
+**`R-01`'s architectural question is answered in source, and the answer was
+"exclusive use".** `parallel.default_jobs()` returned `cpu_count() - 1` for
+each process independently, so `k` concurrent `ask` invocations started
+`k × (N-1)` parsing workers on `N` cores — and no field in any payload said the
+run had been sharing the machine. That is what four rounds of "same command,
+sometimes fast, sometimes hung, no per-process variable distinguishing the two"
+looks like from outside. The cache was *not* the same kind of defect: writes
+are unique-temp + `os.replace` with retry and every read is guarded, so a
+concurrent writer degrades a peer to a cache miss; the one operation that hurt
+a peer was eviction, which now defers while a peer is live.
+
+Every row marked **fixed** below is closed in release `5.9.28`; the two
+open rows say what closure still needs. This batch does not claim to close
+the erratic-failure row — one hang was
+observed with nothing else running, and that is unexplained. It removes the
+mechanism the 5.9.27 round evidenced, and gives the next round the variable it
+did not have: `_meta.concurrency` on every answer.
+
+**Measured here, for the two latency rows:** `ask --help` is 0.41–0.44 s on
+this machine over three consecutive runs (the audit measured 14.4–14.7 s under
+confirmed contention). That is not a refutation of the field figure — it is a
+different machine — but it does put the row behind `R-01` rather than beside
+it, and the next round can separate them with the disclosure block above.
+
+| ID | Severity | Status | Evidence and required closure |
+|---|---:|---|---|
+| `R-01` (contention) | Critical maximum | **mechanism removed, row open pending field re-measure** | `concurrency.py` keeps a best-effort census of live invocations (one lease per process, swept by pid liveness on POSIX and lease age everywhere — never `os.kill(pid, 0)` on Windows, where CPython maps a non-console signal onto `TerminateProcess` and the POSIX idiom would kill the peer it was counting). `parallel.default_jobs()` divides the worker budget by that census; `cache._gc` defers eviction while a peer is live; `_meta.concurrency` publishes peers at start, whether the budget was shared, and that a shared run is not an isolated-machine measurement. `ASK_NO_CONCURRENCY_CENSUS=1` restores the previous behaviour. Closure needs a field round measuring the same commands with the block attached. |
+| `BUG-22` / `REG-02` (enforcement half) | High | **fixed** | The ceiling was checked at phase boundaries only, so a phase could allocate without bound and be refused once it finished — the 2 029.92 MB peak under a 1 536 MB ceiling that was genuinely in force. `resource_budget` now arms a ceiling, samples it inside the parse loop (throttled to one footprint sample per 0.5 s; a per-file call costs one clock read) and raises a typed `CeilingExceeded` that the CLI renders as the same `MEMORY_TOO_LARGE` refusal the boundary check emits. Deliberately not a sampler thread: a thread can see the crossing but cannot unwind the main thread anywhere safe. `_meta.memory.enforcement` publishes when the ceiling is checked. |
+| `BUG-10` | High | **fixed** | The zero-endpoint answer had four named detections and everything else fell through to "no recognized routing construct was found", which reads as *no HTTP surface*. `unmodeled_routing_evidence` now publishes files declaring an annotation whose argument is a path-like string literal that produced no endpoint — a rule that names no framework, per this repository's vendor-agnostic convention. Measured: `struts` reports 4 files under `@Action`/`@Namespace` where the answer used to say nothing was found; `spring-petclinic` reports none. |
+| `NEW-02` / `BUG-05` | High | **fixed** | Overloaded handlers all inherited the final overload's line because the symbol index is keyed `Class#method` with no parameter types. The extractor has no signature to disambiguate with, so the row's other branch applies: `overload_count`, `anchor_ambiguity` and `anchor_candidate_lines` are published per entry, with `anchor_ambiguity_note` once beside the list, and an unambiguous anchor carries none of it. |
+| `BUG-13` | High | **fixed** | `selftest .` over nested repositories warned and then ran the ledger against the workspace — the shape behind `selftest` falling from 9/12 to 1/12 rows inside one 120 s deadline. The implicit `.` now refuses with `INVALID_USAGE` before any row runs, naming the count, with `--allow-nested` for a caller who means the workspace. |
+| `BUG-16` | High | **fixed** | The context cache's caps (30-day TTL, 256 entries) were real and lived inside `_gc`, so ~1.7 GB of growth had no readable contract. `cache.eviction_contract()` and `context_cache.eviction_contract()` are now the one authority each `_gc` reads, and `cache status` publishes them per store in JSON and text. The parse store already published its budget; its block projects those same figures rather than measuring them again. |
+| `ALT-08` (arithmetic half) | Low | **fixed** | `_truncation_summary.final_size_bytes` was measured before the summary and `_budget_note` were attached, so the one part of the payload the accounting omitted was the accounting. It is now measured over the assembled object and republished to a fixed point, with `final_size_basis` written before the fixed point is sought and `content_size_bytes` keeping the trimmed-content figure under a name that says which it is. |
+| `ALT-25` (`impact-chain` audit clock) | Low | **fixed** | `metadata.audit_time_ms` was always ~0.0 on the default path and the 5.9.25 round read it as a security phase skipped by `ALT-03`. It is not: `include_findings` is opt-in, so the clock measured the elapsed time of *not* running an audit. It is `null` when `findings_status` is `not_computed`, and `query_time_basis` states the rule. |
+| `retrieve security-surface --target` | Low | **fixed** | Four rounds tried it and got "No such option: --target". The intent is repository-wide by construction, and the refusal now says so and names `security-chain --target`, derived from `intent_router.ANCHOR_KINDS` rather than a second list. |
+| `ask --help` latency | Low | **open, not reproduced here** | 0.41–0.44 s over three runs on the engineering host against 14.4–14.7 s in the field under confirmed contention. Re-measure with `_meta.concurrency` attached before treating it as its own row. |
+| `ALT-07` (`remediate` hang), `ALT-10` (`onboard`) | Medium | **open, unchanged** | Both share the erratic signature `R-01` now instruments. No separate mechanism found in source this round; neither reproduces on the engineering host. |
+| `BUG-02`, `BUG-12` | Critical maximum | **open, unchanged** | Both need the field's own large repository to reproduce (`rc=127` with no output; multi-gigabyte RSS while building a small answer). `BUG-22`'s sampler bounds the second one's damage without closing it. |
+
+## Current Synchronization — Alternative External Audit `5.9.27`, shared-machine contention confirmed (2026-09-02)
+
+**First score uptick in four rounds (3.8 → 4.6/10), with a large
+qualification found mid-session: the audit machine was shared with a second,
+independent `ask` test harness.** The native-Windows auditor found
+`entry-trace.jsonl` (this ledger's own diagnostic, added last round) growing
+with invocations they never launched, against five OSS reference
+repositories under the exact same `timeout N ask ...` harness pattern they
+use, and confirmed a live foreign `ask.exe` process via `Get-CimInstance
+Win32_Process` under their own Windows user. Two of their own `spring-audit`
+hangs overlapped a 525-second window of 34 foreign invocations. Full
+evidence:
+[`AUDIT-2026-09-02-ALTERNATIVE-5.9.27.md`](AUDIT-2026-09-02-ALTERNATIVE-5.9.27.md).
+
+**`R-01` (new, highest priority):** if ASK's shared worker pool and cache do
+not isolate concurrent `ask` processes on one machine, contention could
+produce exactly the pattern reported since 5.9.23 — the same command
+sometimes hanging, sometimes returning empty near-instantly, no per-process
+variable distinguishing the two. This is a real, evidenced contributing
+factor, not a proven sole cause (one hang occurred after 20 seconds of no
+foreign activity at all). The open question for engineering: is ASK's worker
+pool designed to tolerate concurrent `ask` invocations on one machine, or
+does it assume exclusive use? If the latter, that is an architectural
+constraint, not a series of unrelated command bugs, and changes where the
+fix belongs.
+
+**Entry-point trace progress, confirmed:** the auditor's own invocations —
+including ones that returned empty or hung — now appear in `entry-trace.jsonl`
+(the fix from last round's `R-01`). This confirms `main_entry` is reached on
+the failing runs. `empty_answer_diagnostics.record()` still never fired on
+any observed failure this session, which narrows the search specifically to
+somewhere between `main_entry` and the output-promise guard — a materially
+smaller surface than "somewhere in the process," three rounds ago.
+
+| ID | Severity | Status | Evidence and required closure |
+|---|---:|---|---|
+| `R-01` (contention) | Critical maximum | **open, new evidenced hypothesis** | Confirmed shared-machine contention during this audit session (foreign `ask` process, matching harness pattern, overlapping timing with 2 of the auditor's own hangs). Needs an internal answer, not more external symptom-chasing: does the worker pool serialize or isolate concurrent invocations, or assume exclusive use? If it assumes exclusive use, `ALT-01`/`ALT-03`/`NEW-01` may be one architectural defect, not several. |
+| `R-01` (entry trace) | — | **confirmed working, narrows the search** | The auditor's own failing invocations now appear in `entry-trace.jsonl`. `main_entry` is reached; the gap is between there and `_fail_on_missing_required_answer`/`_fail_on_unkept_output_promise`, which still never fire. |
+| `ALT-09` | Critical | **fixed, reconfirmed a third session** | Piped `n` to `cache clear` aborts correctly. |
+| `BUG-15` / `BUG-21` | Low | **fixed, reconfirmed** | No markup leak; `--jobs` range validated. |
+| `R-05` from last round (`selftest` itemization) | High | **fixed, reconfirmed** | `"10 ledger row(s) could not run: ASK-16, B6, E-37, ..."` replaces the prior generic slug. |
+| `onboard` | Medium | **open, still the most erratic single measurement** | 904ms to a full 200s external kill, same invocation, same tree, within one session. Cross-reference against `entry-trace.jsonl` timing before assuming a cold/warm explanation. |
+| `ask --help` latency | Low | **open, persisted a second round** | 14.4-14.7s this session (was 3-4s last round, flagged then as "worth its own row if it persists"). It has persisted. Not verified in isolation from `R-01`'s contention this session. |
+
+The remaining rows (`BUG-01`, `BUG-03`, `BUG-06`, `BUG-08` through `BUG-23`,
+`REG-02`, `REG-03`, `NEW-02`) were not relaunched this round for time budget;
+no regression signal against them. `watch`'s ~55s warm-before-first-tick and
+`retrieve security-surface --target` remain unchanged, correctly understood
+as real cost and a known gap respectively, not new defects.
+
+**Corroborating data point, unverified in detail:** a separate exchange the
+same session referenced a distinct "External" lineage audit of 5.9.27 scoring
+**8.1/10** on the five OSS reference repositories found in the trace above —
+consistent with the shared-machine hypothesis (two lineages, two repo
+populations, one machine) but not independently confirmed here; the
+transcript fragment available was too corrupted to verify its table in
+detail and is not published as a standalone audit document.
+
 ## Current Synchronization — External Audit `5.9.26`, self-contradictory session (2026-09-02)
 
+> **Provenance correction, added during the 5.9.27 round.** The
+> native-Windows auditor for 5.9.27 states plainly that the "initial
+> 129-invocation pass ... 0/23 ... 7.4/10" described below does not
+> correspond to anything they ran. The 5.9.27 round independently confirmed
+> the audit machine was shared with a second, concurrent `ask` test harness
+> exercising five OSS reference repositories (`thingsboard`, `mall`,
+> `struts`, `spring-petclinic`, `jhipster-sample-app`) — a repo set and
+> pattern that matches the "External" multi-repository lineage this ledger
+> has tracked separately since 5.9.22 (`AUDIT-2026-09-02-EXTERNAL-5.9.26.md`
+> below, and the 6.3→3.8 scores it reflects). The likely explanation is that
+> the two-pass narrative below mixed observations from two independent,
+> concurrent sessions on one shared machine rather than being one
+> evaluator's self-revision. Left as written below rather than rewritten,
+> with this correction attached, per this ledger's own discipline of
+> recording when it got something wrong rather than quietly fixing the
+> record. See
+> [`AUDIT-2026-09-02-ALTERNATIVE-5.9.27.md`](AUDIT-2026-09-02-ALTERNATIVE-5.9.27.md)
+> for the evidence (`entry-trace.jsonl` cross-contamination, a live foreign
+> process confirmed via `Get-CimInstance Win32_Process`).
+
 **The 5.9.26 fix batch did not close the release gate, and new evidence
 narrows the failure to before the guard rather than inside it.** This audit
 round is internally contradictory and both halves are published rather than

sourcecode/_docs/USER_GUIDE.md

@@ -279,7 +279,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.27
+# ask 5.9.28
 ```
 
 Requires Python 3.9+.

sourcecode/cache.py

@@ -151,6 +151,49 @@ _DEFAULT_KEEP_COMMITS: int = 5
 _DEFAULT_MAX_CORES: int = 20
 _DEFAULT_MAX_SIZE_MB: int = 50
 
+
+def eviction_contract() -> "dict[str, Any]":
+    """The three caps this store evicts under, read once (BUG-16).
+
+    `_gc` used to read the environment inline, so the only way to learn what
+    bounded the cache was to read the sweep. A consumer asking `cache status`
+    what will be evicted, and when, now gets the same numbers the sweep uses.
+    """
+    def _int(name: str, default: int) -> int:
+        try:
+            return int(os.environ.get(name, default))
+        except (TypeError, ValueError):
+            return default
+
+    keep = _int("SOURCECODE_CACHE_KEEP_COMMITS", _DEFAULT_KEEP_COMMITS)
+    max_cores = _int("SOURCECODE_CACHE_MAX_CORES", _DEFAULT_MAX_CORES)
+    max_size_mb = _int("SOURCECODE_CACHE_MAX_SIZE_MB", _DEFAULT_MAX_SIZE_MB)
+    clauses = []
+    if keep > 0:
+        clauses.append(f"the last {keep} distinct commits are kept")
+    if max_cores > 0:
+        clauses.append(f"at most {max_cores} cores, least recently used evicted first")
+    if max_size_mb > 0:
+        clauses.append(f"the store is trimmed toward {max_size_mb} MB")
+    return {
+        "keep_commits": keep,
+        "max_cores": max_cores,
+        "max_size_mb": max_size_mb,
+        "keep_commits_env": "SOURCECODE_CACHE_KEEP_COMMITS",
+        "max_cores_env": "SOURCECODE_CACHE_MAX_CORES",
+        "max_size_env": "SOURCECODE_CACHE_MAX_SIZE_MB",
+        "policy": (
+            "; ".join(clauses) + ", swept after each write"
+            if clauses else
+            "no eviction — every cap was set to 0 deliberately"
+        ),
+        "deferred_while_shared": (
+            "A sweep is skipped while another `ask` invocation is live on this "
+            "machine (R-01): eviction would delete the working set a concurrent "
+            "run is reading."
+        ),
+    }
+
 #: Windows hardening for _atomic_write: os.replace can raise PermissionError
 #: (WinError 5/32) when an antivirus scanner, search indexer, or concurrent
 #: reader transiently holds the destination open. Retry briefly to ride it out.
@@ -501,27 +544,45 @@ def _store_breakdown(repo_root: Path, core_bytes: int) -> "dict[str, Any]":
             "bytes": core_bytes,
             "scope": "this repository",
             "holds": "core snapshots, rendered views and their CAS blobs",
+            "eviction": eviction_contract(),
         },
     }
     try:
         from sourcecode.context_cache import ContextCache  # noqa: PLC0415
 
         ctx = ContextCache.for_repo(repo_root).stats()
+        from sourcecode.context_cache import (  # noqa: PLC0415
+            eviction_contract as _ctx_eviction,
+        )
+
         out["shared_cir"] = {
             "cache_dir": ctx["cache_dir"],
             "entries": ctx["contexts"],
             "bytes": ctx["bytes_stored"],
             "scope": "this repository",
             "holds": "the shared Canonical IR that explain/impact/posture reuse",
+            # BUG-16: measured at ~1.7 GB in two rounds with nothing published
+            # about what bounds it. The caps were real and lived inside `_gc`.
+            "eviction": _ctx_eviction(),
         }
     except Exception:
         out["shared_cir"] = {"available": False}
     try:
         from sourcecode import parse_cache as _pc  # noqa: PLC0415
 
+        _parse_stats = _pc.store_stats()
         out["parse"] = {
-            **_pc.store_stats(),
+            **_parse_stats,
             "holds": "per-file parses, content-addressed across every repository",
+            # BUG-16: this store already published its budget under its own
+            # names; the block below is that same answer projected under the
+            # name every store now answers to, never a second measurement.
+            "eviction": {
+                "policy": _parse_stats.get("policy"),
+                "budget_mb": _parse_stats.get("budget_mb"),
+                "budget_env": _parse_stats.get("budget_env"),
+                "sweep_interval_mb": _parse_stats.get("sweep_interval_mb"),
+            },
         }
     except Exception:
         out["parse"] = {"available": False}
@@ -1080,9 +1141,25 @@ def _gc(cache_d: Path) -> None:
        oldest core+snapshot files until under budget.
     Views and CAS blobs are swept after each pass.
     """
-    keep = int(os.environ.get("SOURCECODE_CACHE_KEEP_COMMITS", _DEFAULT_KEEP_COMMITS))
-    max_cores = int(os.environ.get("SOURCECODE_CACHE_MAX_CORES", _DEFAULT_MAX_CORES))
-    max_size_bytes = int(os.environ.get("SOURCECODE_CACHE_MAX_SIZE_MB", _DEFAULT_MAX_SIZE_MB)) * 1024 * 1024
+    # R-01 (5.9.27): eviction is the one cache operation a concurrent peer can
+    # be hurt by. Writes are unique-temp + `os.replace` and every read is
+    # guarded, so a peer degrades to a cache miss at worst — but `_gc` deletes
+    # the working set a peer may be halfway through reading, turning its warm
+    # run into a cold one for reasons nothing in its payload could name. A
+    # deferred sweep costs disk until the machine is quiet; it is bounded by
+    # the same caps on the next single-tenant run.
+    try:
+        from sourcecode import concurrency as _concurrency
+
+        if _concurrency.peers() > 0:
+            return
+    except Exception:
+        pass
+
+    _contract = eviction_contract()
+    keep = int(_contract["keep_commits"])
+    max_cores = int(_contract["max_cores"])
+    max_size_bytes = int(_contract["max_size_mb"]) * 1024 * 1024
 
     try:
         all_snapshots = list(cache_d.glob("snapshot-*.json.gz"))

sourcecode/cli.py

@@ -2208,6 +2208,10 @@ def _stamp_envelope(content: str) -> str:
                 if _AGENT_MODE_ACTIVE else None
             ),
         )
+        # BUG-22: *when* the ceiling is enforced, not only what it is. Both
+        # 5.9.25 audits measured a peak above a ceiling that was genuinely in
+        # force, because the check ran only between phases.
+        extra["memory"]["enforcement"] = resource_budget.enforcement_disclosure()
     except Exception as _exc:  # a footprint sample is not the envelope
         degraded = degraded or f"memory disclosure unavailable: {type(_exc).__name__}"
 
@@ -2227,6 +2231,18 @@ def _stamp_envelope(content: str) -> str:
     except Exception as _exc:
         degraded = degraded or f"budget disclosure unavailable: {type(_exc).__name__}"
 
+    # R-01 (5.9.27): whether this run had the machine to itself. Four audit
+    # rounds could not separate a contended measurement from an isolated one
+    # because no payload carried the variable; the round that finally found a
+    # foreign `ask` process on the audit machine found it in this product's
+    # own diagnostics file, not in any answer it published.
+    try:
+        from sourcecode import concurrency as _concurrency
+
+        extra["concurrency"] = _concurrency.disclosure()
+    except Exception as _exc:
+        degraded = degraded or f"concurrency disclosure unavailable: {type(_exc).__name__}"
+
     # AUD-601-M01: the state a figure was taken in, from the lookups the layers
     # actually answered. Four retracted performance findings in six rounds were
     # all measured honestly against a cache state nobody could establish; a
@@ -3130,7 +3146,18 @@ def _analysis_failed(command: str, phase: str, exc: Exception) -> NoReturn:
     command-specific exception types.  These commands are consumed by CI, so an
     unexpected analysis exception must retain a machine-readable cause and a
     non-zero process status rather than relying on a framework traceback.
+
+    BUG-22 carved out one exception: a run stopped by its own RSS ceiling did
+    not fail — it was refused, deliberately, by a gate the caller configured.
+    Rendering that as `EXECUTION_FAILED: risk failed while composing risk
+    factors` with `exception_type: CeilingExceeded` buries the one fact the
+    operator needs (the ceiling, the peak, the variable that moves it) under a
+    generic crash report.
     """
+    from sourcecode.resource_budget import CeilingExceeded as _CeilingExceeded
+
+    if isinstance(exc, _CeilingExceeded):
+        raise exc
     _emit_error_json(
         EXECUTION_FAILED_CODE,
         f"{command} failed while {phase}.",
@@ -3639,6 +3666,48 @@ try:
             return str(getattr(exc, "message", "") or exc.format_message())
         return exc.format_message()
 
+    def _repository_wide_intent_hint(exc: Any) -> Optional[str]:
+        """`--target` on a `retrieve` intent that has no anchor to give it.
+
+        Four consecutive audit rounds tried `retrieve security-surface --target
+        <symbol>` and got *"No such option: --target"*, which is true and
+        useless: it does not say the intent is repository-wide by construction,
+        and it does not name the sibling intent that answers the question the
+        caller was asking. `intent_router.ANCHOR_KINDS` already holds the fact
+        (`""` means "takes no anchor"), so the hint is derived from it rather
+        than from a second list that would drift the first time an intent
+        changed shape.
+        """
+        option = str(getattr(exc, "option_name", None) or "").strip()
+        if option not in ("--target", "-t"):
+            return None
+        path = str(getattr(getattr(exc, "ctx", None), "command_path", "")).strip()
+        parts = path.split()
+        if len(parts) < 2 or parts[-2] != "retrieve":
+            return None
+        intent = parts[-1]
+        try:
+            from sourcecode.intent_router import ANCHOR_KINDS
+        except Exception:
+            return None
+        if ANCHOR_KINDS.get(intent, None) != "":
+            return None
+        family = intent.split("-")[0]
+        siblings = sorted(
+            name for name, kind in ANCHOR_KINDS.items()
+            if kind and name.split("-")[0] == family
+        )
+        pointer = (
+            f" For a target-scoped answer in the same family use "
+            f"`ask retrieve {siblings[0]} --target <symbol>`."
+            if siblings else
+            " `ask retrieve --help` lists the intents that take one."
+        )
+        return (
+            f"`retrieve {intent}` is repository-wide and takes no anchor, so it "
+            f"has no `--target` to accept.{pointer}"
+        )
+
     def _declared_options_hint(exc: Any) -> Optional[str]:
         """The command's real signature, for a refusal with no candidate.
 
@@ -3666,6 +3735,11 @@ try:
         _is_root_scope = _hint is not None
         if _numeric_context:
             _flag = str(_numeric_context["flag"])
+        if not _hint:
+            # Before the edit-distance suggester: `--target` on a
+            # repository-wide intent has a real answer, and a near-miss
+            # candidate would bury it.
+            _hint = _repository_wide_intent_hint(self)
         if not _hint:
             _nearby = _nearby_command_flag_hint(self)
             if _nearby:
@@ -6541,6 +6615,14 @@ def main(
             return
         from sourcecode import resource_budget
 
+        # BUG-22: `--agent` carries a default ceiling that no environment
+        # variable states, so the mid-phase sampler has to be told about it or
+        # it enforces nothing on exactly the mode that needs it most.
+        resource_budget.arm(
+            "ask --agent",
+            default_ceiling_mb=resource_budget.DEFAULT_AGENT_RSS_CEILING_MB,
+        )
+
         memory_error = resource_budget.exceeded(
             "ask --agent",
             default_ceiling_mb=resource_budget.DEFAULT_AGENT_RSS_CEILING_MB,
@@ -18660,6 +18742,12 @@ def selftest_cmd(
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o", help="Write the verdicts to a file instead of stdout.",
     ),
+    allow_nested: bool = typer.Option(
+        False, "--allow-nested",
+        help="Run anyway when the implicit `.` covers nested Git repositories "
+             "(BUG-13). The default refuses: an unscoped ledger run over a "
+             "workspace of repositories is not the run anyone asked for.",
+    ),
     format: str = _format_option(help="Output format: json (default) or yaml."),
     copy: bool = _copy_option(),
     progress_mode: Optional[str] = _progress_option(),
@@ -18696,13 +18784,27 @@ def selftest_cmd(
         from sourcecode.selftest import nested_repository_count
 
         nested = nested_repository_count(target)
-        if nested:
-            typer.echo(
-                f"selftest is scanning {nested} nested Git repository(s) under the "
-                "implicit current-directory path; pass an explicit repository path "
-                "to scope the ledger run",
-                err=True,
+        if nested and not allow_nested:
+            # BUG-13: this used to warn and then scan anyway. A warning on
+            # stderr does not stop the run, and what the run then does is
+            # drive every ledger row against a *workspace* — the shape behind
+            # `selftest` falling from 9/12 to 1/12 rows inside one 120-second
+            # deadline on the audited machine. The scope is the input, so the
+            # input is what has to change; `--allow-nested` is there for a
+            # caller who means it.
+            _emit_error_json(
+                INVALID_USAGE_CODE,
+                f"selftest refuses an unscoped run: the implicit `.` covers "
+                f"{nested} nested Git repository(s), so the ledger would run "
+                f"against a workspace rather than a repository.",
+                hint=(
+                    "Pass the repository explicitly (`ask selftest "
+                    "<path/to/repo>`), or `--allow-nested` to run over the "
+                    "workspace on purpose."
+                ),
+                nested_repositories=nested,
             )
+            raise typer.Exit(code=2)
     _enforce_format("selftest", format)
     selected = tuple(part.strip() for part in (rows or "").split(",") if part.strip())
 
@@ -20622,6 +20724,11 @@ def cache_status_cmd(
             f"Cache dir:   {stats['cache_dir']}"
             + (f"  (${_core_env} moves it)" if _core_env else "")
         )
+        # BUG-16: the per-repository store's own eviction contract, beside the
+        # directory it applies to.
+        _core_eviction = ((stats.get("stores") or {}).get("core") or {}).get("eviction")
+        if isinstance(_core_eviction, dict) and _core_eviction.get("policy"):
+            _answer.say(f"{'':<13}eviction: {_core_eviction['policy']}")
         # C4-18: this counts cached core entries, not CPU cores — and `cores` is
         # exactly what a captured baseline calls the machine's CPU count, so
         # `Cores: 0` beside `Views: 0` read as "empty cache" on a 20-core box.
@@ -20662,6 +20769,20 @@ def cache_status_cmd(
                     "written by another build and can never be read again — the next "
                     "analysis retires them"
                 )
+            # BUG-16: what evicts this store, and when. The context cache was
+            # measured at ~1.7 GB across two rounds with its caps visible only
+            # inside the sweep that applied them; every store that has an
+            # eviction contract now states it here, from the store's own
+            # figures rather than a second copy of them.
+            _eviction = _store.get("eviction")
+            if (
+                isinstance(_eviction, dict)
+                and _eviction.get("policy")
+                and "budget_bytes" not in _store
+            ):
+                # A store that publishes a byte budget states its policy in the
+                # budget line below; saying it twice is two catalogues again.
+                _answer.say(f"{'':<13}eviction: {_eviction['policy']}")
             # F-AR: a store in somebody else's home directory says what bounds it.
             if "budget_bytes" in _store:
                 _budget_mb = _store.get("budget_mb")
@@ -21704,12 +21825,33 @@ def main_entry() -> None:
     if any(tok in REQUIRED_ANSWER_COMMANDS for tok in sys.argv[1:]):
         from sourcecode import empty_answer_diagnostics as _diag
         _diag.record_entry_reached(sys.argv[1:])
+    # R-01 (5.9.27 alternative audit): announce this invocation on the machine
+    # before any work, so a peer that starts later sizes its worker pool
+    # against a census that includes this run — and so this run's own payload
+    # can say whether it was sharing the machine. Best-effort: a failure here
+    # leaves the pre-5.9.28 behaviour untouched.
+    try:
+        from sourcecode import concurrency as _concurrency
+
+        _concurrency.register(sys.argv[1:])
+    except Exception:
+        pass
     # AUD-596-B10: the earliest point in the process that knows a command is
     # starting. `timings.wall_ms` is published under a unit reading "THIS
     # process's wall clock", and until this mark existed it measured from
     # wherever the block happened to be constructed — which, on a run the budget
     # cut, is after the work. Marked before anything else so the number covers
     # what the reader was charged for.
+    # BUG-22: arm mid-phase RSS enforcement for the whole process. Without a
+    # configured ceiling this is inert (`armed()` is false and `checkpoint()`
+    # returns immediately); with one, the analysis loops stop where the
+    # crossing happens instead of at the end of the phase that caused it.
+    try:
+        from sourcecode import resource_budget as _rb_arm
+
+        _rb_arm.arm(" ".join(["ask", *sys.argv[1:2]]).strip())
+    except Exception:
+        pass
     from sourcecode.perf import mark_command_start as _mark_command_start
     _mark_command_start()
     _force_utf8_streams()
@@ -21753,6 +21895,7 @@ def main_entry() -> None:
         raise
     except typer.Exit as _exit:
         raise SystemExit(_exit.exit_code)
+    from sourcecode import resource_budget as _resource_budget
     try:
         # prog_name pins usage/help to the canonical `ask`, whatever the alias.
         app(prog_name="ask")
@@ -21762,6 +21905,18 @@ def main_entry() -> None:
         _fail_on_missing_required_answer(_sysexit.code)
         _fail_on_unkept_output_promise(_sysexit.code)
         raise
+    except _resource_budget.CeilingExceeded as _ceiling:
+        # BUG-22: the same refusal `_root_memory_seam` emits at a boundary,
+        # raised from inside the loop that crossed the ceiling. One envelope,
+        # one exit code, whichever seam noticed.
+        _payload = dict(_ceiling.payload)
+        _fail_on_missing_required_answer(1)
+        _emit_error_json(
+            _payload.pop("code"),
+            _payload.pop("message"),
+            **_payload,
+        )
+        raise SystemExit(1)
     except WriteRefused as _refused:
         # F-AS. "A command that cannot answer without writing says so instead of
         # writing" — and *says so* means one sentence in the error envelope every