wip(g2): park change-scoped attempt + full diagnosis (NOT the fix)

Scope+bound (change-first ordering, adaptive budget-fitted portioning, _context_pass scoped to changed files, evidence_pass_bounded degradation) is preserved here but does NOT unblock analysis: query_seconds stayed 0 across every live re-verify. Uncontended measurement proved why -- the evidence pass is ~150s fixed (first-query graph-load + census) + ~93ms/pair, so ~200s fixed overhead (with the 48s build) precedes any analysis and a 300s budget leaves ~100s. Pair-count scoping only trims the ~86s per-pair tail. The warm-session env (OUSAST_ENGINE_SESSION=1) times out at startup under contention and, even working, spares only subsequent batches -- not the first evidence query's load. Parked per decision to finish the G0 baseline first; resume on a clean host. Branch unmerged. 95 model tests pass; no push-suite regression. Co-Authored-By: Claude Opus 4.8 <[email protected]>
feat(g2): change-scoped, budget-bounded evidence pass (unblock push analysis)
2026-10-17 20:19:29 +00:00 · 2026-10-11 13:31:54 +02:00 · 2026-10-11 12:28:35 +02:00 · 2026-10-11 12:11:57 +02:00 · 2026-10-11 11:50:41 +02:00 · 2026-10-11 11:24:43 +02:00
143 changed files with 28153 additions and 7602 deletions
@@ -21,3 +21,10 @@ OPENROUTER_API_KEY=
 # AWS_SESSION_TOKEN=
 # The bucket must have versioning enabled, a lifecycle rule expiring runs/, S3 Select and readable object tags
 # (see docs/rustfs.md); the store verifies them at startup and refuses to run otherwise.
 # Operator notifications (Discord). Status of OpenUltraSAST processes and their results for the
 # system/AI operator -- not developer debugging, and not k3s/ax infra health. See
 # .kiro/steering/operator-notifications.md. Webhook posts to the operator channel; the operator id
 # is the account to @mention on a stuck/impaired alert. Leave blank to disable notifications.
 DISCORD_WEBHOOK_URL=
 DISCORD_OPERATOR_ID=
@@ -3,16 +3,11 @@ on:
  workflow_dispatch:
  push:
    branches: [main]
    tags: ['v*']
    paths:
-      - 'src/**'
+      - 'plane/Dockerfile.*'
-      - 'benchmarks/learn/engine_trace*.py'
+      - 'plane/task-base.digest'
      - 'benchmarks/learn/engine_task_entry.py'
      - 'benchmarks/learn/engine_worker_service.py'
      - 'Dockerfile'
      - 'plane/Dockerfile.engine-task'
      - 'ops/frontend-retention/install.py'
      - 'pyproject.toml'
      - '.github/workflows/engine-image.yml'
 permissions:
  contents: read
  packages: write
@@ -20,7 +15,40 @@ concurrency:
  group: engine-image-${{ github.ref }}
  cancel-in-progress: false
 jobs:
  pins:
    runs-on: ubuntu-latest
    outputs:
      base_tag: ${{ steps.pins.outputs.base_tag }}
      base_digest: ${{ steps.pins.outputs.base_digest }}
      browser_tag: ${{ steps.pins.outputs.browser_tag }}
      browser_digest: ${{ steps.pins.outputs.browser_digest }}
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
      # No login: every pinned base must be anonymously pullable.
      - id: pins
        run: |
          python3 - <<'PYTHON'
          import json, os, re, subprocess
          from pathlib import Path
          pins = json.loads(Path("plane/task-base.digest").read_text())
          manifests = {}
          for key, output in (("base", "base"), ("base-browser", "browser")):
              ref = pins.get(key)
              pattern = r"ghcr.io/norandom/ousast-task-base:(base-[a-z0-9-]+)@(sha256:[0-9a-f]{64})"
              match = re.fullmatch(pattern, ref or "")
              if not match:
                  raise SystemExit(f"{key}: unpublished/invalid pin; run task-base-image and update plane/task-base.digest")
              raw = subprocess.check_output(["docker", "buildx", "imagetools", "inspect", "--raw", ref])
              manifests[key] = json.loads(raw)["layers"]
              with open(os.environ["GITHUB_OUTPUT"], "a") as out:
                  out.write(f"{output}_tag={match[1]}\n{output}_digest={match[2]}\n")
          base = manifests["base"]
          if not base or manifests["base-browser"][:len(base)] != base:
              raise SystemExit("Browser pin does not share the pinned base's layers")
          PYTHON
  image:
    needs: pins
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
@@ -28,8 +56,8 @@ jobs:
        include:
          - package: openultrasast
            dockerfile: Dockerfile
-          - package: ousast-engine-task
+          - package: ousast-search-task
-            dockerfile: plane/Dockerfile.engine-task
+            dockerfile: plane/Dockerfile.search-task
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
@@ -52,6 +80,16 @@ jobs:
          file: ${{ matrix.dockerfile }}
          platforms: linux/amd64
          push: true
          provenance: false
          build-args: |
            TASK_BASE_TAG=${{ needs.pins.outputs.base_tag }}
            TASK_BASE_DIGEST=${{ needs.pins.outputs.base_digest }}
            TASK_BROWSER_TAG=${{ needs.pins.outputs.browser_tag }}
            TASK_BROWSER_DIGEST=${{ needs.pins.outputs.browser_digest }}
          cache-from: |
            type=gha,scope=${{ matrix.package }}
            type=gha,scope=ousast-engine-task
          cache-to: type=gha,mode=max,scope=${{ matrix.package }}
          tags: |
            ${{ steps.names.outputs.image }}:${{ steps.names.outputs.sha }}
            ${{ steps.names.outputs.image }}:main
@@ -61,3 +99,101 @@ jobs:
        run: |
          echo "$IMAGE@$DIGEST"
          echo "$IMAGE@$DIGEST" >> "$GITHUB_STEP_SUMMARY"
          docker logout ghcr.io
          docker buildx imagetools inspect "$IMAGE@$DIGEST"
  engine:
    needs: pins
    runs-on: ubuntu-latest
    outputs:
      image: ${{ steps.names.outputs.image }}
      digest: ${{ steps.build.outputs.digest }}
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: names
        env:
          OWNER: ${{ github.repository_owner }}
          PACKAGE: ousast-engine-task
        run: |
          echo "image=ghcr.io/${OWNER,,}/$PACKAGE" >> "$GITHUB_OUTPUT"
          echo "sha=sha-${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
      - id: build
        uses: docker/build-push-action@v6
        with:
          context: .
          file: plane/Dockerfile.engine-task
          target: engine
          platforms: linux/amd64
          push: true
          provenance: false
          build-args: |
            TASK_BASE_TAG=${{ needs.pins.outputs.base_tag }}
            TASK_BASE_DIGEST=${{ needs.pins.outputs.base_digest }}
            TASK_BROWSER_TAG=${{ needs.pins.outputs.browser_tag }}
            TASK_BROWSER_DIGEST=${{ needs.pins.outputs.browser_digest }}
          cache-from: type=gha,scope=ousast-engine-task
          cache-to: type=gha,mode=max,scope=ousast-engine-task
          tags: |
            ${{ steps.names.outputs.image }}:${{ steps.names.outputs.sha }}
            ${{ steps.names.outputs.image }}:main
      - env:
          IMAGE: ${{ steps.names.outputs.image }}
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          echo "$IMAGE@$DIGEST"
          echo "$IMAGE@$DIGEST" >> "$GITHUB_STEP_SUMMARY"
          docker logout ghcr.io
          docker buildx imagetools inspect "$IMAGE@$DIGEST"
  replay:
    needs: [pins, engine]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: names
        env:
          OWNER: ${{ github.repository_owner }}
          PACKAGE: ousast-replay-task
        run: |
          echo "image=ghcr.io/${OWNER,,}/$PACKAGE" >> "$GITHUB_OUTPUT"
          echo "sha=sha-${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
      - id: build
        uses: docker/build-push-action@v6
        with:
          context: .
          file: plane/Dockerfile.engine-task
          target: replay
          platforms: linux/amd64
          push: true
          provenance: false
          build-args: |
            ENGINE_REF=${{ needs.engine.outputs.image }}@${{ needs.engine.outputs.digest }}
            TASK_BASE_TAG=${{ needs.pins.outputs.base_tag }}
            TASK_BASE_DIGEST=${{ needs.pins.outputs.base_digest }}
            TASK_BROWSER_TAG=${{ needs.pins.outputs.browser_tag }}
            TASK_BROWSER_DIGEST=${{ needs.pins.outputs.browser_digest }}
          cache-from: |
            type=gha,scope=ousast-replay-task
            type=gha,scope=ousast-engine-task
          cache-to: type=gha,mode=max,scope=ousast-replay-task
          tags: |
            ${{ steps.names.outputs.image }}:${{ steps.names.outputs.sha }}
            ${{ steps.names.outputs.image }}:main
      - env:
          IMAGE: ${{ steps.names.outputs.image }}
          DIGEST: ${{ steps.build.outputs.digest }}
        run: |
          echo "$IMAGE@$DIGEST"
          echo "$IMAGE@$DIGEST" >> "$GITHUB_STEP_SUMMARY"
          docker logout ghcr.io
          docker buildx imagetools inspect "$IMAGE@$DIGEST"
@@ -0,0 +1,78 @@
 name: Task base image
 on:
  workflow_dispatch:
  push:
    branches: [main]
    paths:
      - 'plane/Dockerfile.base'
      - 'pyproject.toml'
      - 'uv.lock'
 permissions:
  contents: read
  packages: write
 concurrency:
  group: task-base-image
  cancel-in-progress: false
 jobs:
  base:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: names
        run: |
          echo "tag=base-${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
          content=$(cat plane/Dockerfile.base pyproject.toml uv.lock | sha256sum | cut -d' ' -f1)
          echo "content=base-content-$content" >> "$GITHUB_OUTPUT"
      - id: base
        uses: docker/build-push-action@v6
        with:
          context: .
          file: plane/Dockerfile.base
          target: base
          platforms: linux/amd64
          push: true
          provenance: false
          sbom: false
          tags: |
            ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.tag }}
            ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.content }}
          cache-from: type=gha,scope=task-base
          cache-to: type=gha,mode=max,scope=task-base
      - id: browser
        uses: docker/build-push-action@v6
        with:
          context: .
          file: plane/Dockerfile.base
          target: base-browser
          platforms: linux/amd64
          push: true
          provenance: false
          sbom: false
          build-args: |
            TASK_BASE_REF=ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.tag }}@${{ steps.base.outputs.digest }}
          tags: |
            ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.tag }}-browser
            ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.content }}-browser
          cache-from: type=gha,scope=task-base-browser
          cache-to: type=gha,mode=max,scope=task-base-browser
      - name: Print manual pin update and verify public access
        env:
          BASE: ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.tag }}@${{ steps.base.outputs.digest }}
          BROWSER: ghcr.io/norandom/ousast-task-base:${{ steps.names.outputs.tag }}-browser@${{ steps.browser.outputs.digest }}
        run: |
          python3 - <<'PYTHON' >> "$GITHUB_STEP_SUMMARY"
          import json, os
          print("Replace plane/task-base.digest with this JSON after both public checks pass:")
          print("```json")
          print(json.dumps({"base": os.environ["BASE"], "base-browser": os.environ["BROWSER"]}, indent=2))
          print("```")
          PYTHON
          docker logout ghcr.io
          docker buildx imagetools inspect "$BASE"
          docker buildx imagetools inspect "$BROWSER"
@@ -36,3 +36,9 @@ workspace/
 # MkDocs build output (mkdocs build)
 site/
 # Unseen evaluation pointers for non-permissive repositories.
 benchmarks/unseen/private/
 # Feasibility pilot identities remain local; only aggregate records are tracked.
 benchmarks/search/private/
@@ -0,0 +1,140 @@
 # Engine change-scoped analysis (G2 workstream)
 Status: **proposed / in progress** (opened 2026-10-11). Owner: engine. Tracks a concrete lever for the
 engine-detection gap found while driving the G0 baseline. This is G2 ("improve what moves the unseen-repo
 numbers"), gated on the pool metric; it is NOT part of the G0 record-07 baseline (that runs on the quick-rule tier).
 ## Problem (measured, not assumed)
 On real unseen vulnerability changes the engine produces **no finding** — but the diagnosis (live, 300 s long-deadline
 replays) shows it is usually **not a detection-capability gap**:
 - **Clean Python injection change** (`aws/bedrock-agentcore-sdk-python`, `install_packages`, introducing, 3-file
  diff): `wall=303 s`, hit the deadline. The ranker found candidates (`static_rank=1.0`) but **`selected: []`** and
  every candidate `deferred` with `reason: deadline_exhausted`, `analysis_not_started=deadline_exhausted`,
  `change_context_incomplete`. **Zero analyses ran.** And the ranked candidates were **repo-wide and unrelated to
  the push** (`auth.py` access_control/config_secrets), not the changed `install_packages`. The engine is trying to
  re-audit the whole repo and runs out of budget before analyzing the change.
 - **Noisy last_touch config_secrets change** (`jenkinsci/metrics-plugin`, 14-file diff): finished in 206 s but
  `comparison_unknown` + `capability_unavailable` + `eligibility_provenance_mismatch` +
  `contributor-scan ... projection_unavailable`. Multi-causal; correspondence was one part (fixed separately,
  commit c39fbb8), capability registry is Task 8.3.
 ## Hypothesis
 A pre-push hook should vet **the code this push changed**, not re-scan the whole repository. Seeding/scoping the
 engine's analysis to the **changed declarations and their dataflow neighborhood** (the `change_sites` are already in
 the replay spec) should let analysis **actually run within budget** instead of being deferred — which is where
 detection is being lost, not in Joern's capability.
 ## Anchors (confirm in increment 1)
 - `src/openultrasast/rank.py` — the static-evidence ranker (`ranking_mode="evidence"`, `existing-static-evidence-v1`).
 - `src/openultrasast/mapping.py` — builds the `selected`/`deferred` scope + the budget allocation that defers on
  `deadline_exhausted`.
 - `src/openultrasast/push/policy.py`, `push/runner.py` — consume the scope; change_sites arrive via the push input.
 - `benchmarks/unseen/replay_entry.py` — carries `changed_paths` / `declaration_paths` in the spec.
 ## Increments (progress tracking)
 - [x] **0. Cost split confirmed (2026-10-11, timed live replay).** `build_seconds=66.69` (CPG build is cheap),
  `query_seconds=0.0` (no query ever executed), total 303 s (hit the deadline), **4,095** candidate questions all
  `analysis_not_started=deadline_exhausted`, `selected: []`, `regions_scanned=0`. So of the 303 s, ~67 s built the
  CPG and ~236 s went to enumerating/ranking/preparing 4,095 repo-wide candidate questions for a **3-file** change —
  the budget was spent before a single query ran. The CPG build is NOT the bottleneck; the over-broad candidate set
  is. Change-scoping is confirmed as the right lever, and because per-candidate prep includes the line-correspondence
  work, fewer candidates also cuts that cost (the two fixes compound).
 - [x] **1. Located (2026-10-11).** The over-enumeration is upstream of the scan, not inside it:
  - `push/runner.py:345-348` — `head_regions = discovery(tip.root, …)` discovers regions across the **whole head
    tree** (the ~4,095), independent of the change.
  - `push/runner.py:397-407` — those regions are passed wholesale to `scan_repository(..., change_context=context)`;
    `change_context` is threaded in but **never scopes the region set**.
  - `model/scan.py:167` and `:364` — `[_identity(unit, r, f) for r in regions for f in r.families]` enumerates all
    regions × families; with `order_by_evidence=True` (`runner.py:288/403`) the scan evidence-tiers **every** pair
    before analysis — that pre-work is the ~236 s measured in increment 0, so the deadline hits at `query_seconds=0`.
  - Primitive already present: `model/regions.py:279` computes the changed-path set from the context;
    `compare_targeted_base` (`runner.py:411`) is a precedent for change-targeted work.
  - **Fix locus (increment 2):** restrict the *analyzed* region set to the change's declarations + dataflow
    neighbourhood (filter `head_regions` by `context.changed_paths` before the scan, or scope the enumeration inside
    `scan_repository`). Keep the **CPG whole-repo** so taint queries can still trace sources from unchanged code into
    the changed regions — only the question set is change-scoped.
  **Correction (2026-10-11), after a reverted first attempt — two things the naive filter got wrong:**
  - **The engine already reaches into unchanged code by design, and it is tested.** A changed `source` that reaches
    an unchanged `sink` must still select the unchanged sink's question
    (`tests/test_model_change_context.py::test_changed_dependency_reaches_unchanged_ranked_question`;
    `test_change_does_not_replace_ranker_selection` pins that change context must NOT alter the ranker's selection).
    `_changed_files` feeds `_evidence_pass` only as `contextFilter`/`contextPaths` — which locations to itemise vs
    summarise — NOT to shrink the tier population. A "changed files only" scope deletes the reach-into-unchanged
    behaviour. Any scope must keep changed regions **plus the regions they reach** (the affected/`relationships`
    neighbourhood), not changed files alone.
  - **The 236 s is now split (2026-10-11, saved artifacts).** `total=291s build=52s query=0s arbitrate=238.75s`,
    and `query_seconds_by_kind["evidence"]=238.54s` — the evidence-tier pass is **99.9 %** of the arbitrate phase;
    `affected_context` + `_scope_work` are **0.21 s**. The pass tiered 1,015 pairs (`tier_counts 0:1009, 1:6`) at
    **~235 ms/pair** (contended; ~120 ms uncontended) and that alone blew the budget — `selected=0`,
    `deferred=1365` all `deadline_exhausted`. Secondary anomaly: the design assumes ~2.5 ms/pair
    ("17,700 in 44 s"); here it is 50–100× that, i.e. the evidence query is pathologically slow on a cold large
    CPG — a separate optimisation from cutting the pair count.
  - **So increment 2's single target is the evidence pass** (`scan.py:338-359`, `_evidence_pass`). The fork is HOW
    to cut it without deleting reach-into-unchanged:
    - (i) **Scope + bound:** order the evidence candidates change-first and bound the pass to a fraction of the
      budget so analysis queries still run; reached unchanged regions are tiered only while budget lasts.
    - (ii) **Neighbourhood pass:** tier the changed regions, read the reached regions from the context rows the
      pass already returns, tier those in a second small pass — exact reach-into-unchanged, more code.
    - (iii) **Per-pair speedup:** attack the ~235 ms/pair (warm server / batching) rather than the pair count —
      helps every scan but is a deeper engine change and does not by itself bound a huge repo.
  **CORRECTION (2026-10-11, after implementing (i) + four live re-verifies — the cost model was wrong).**
  Scope + bound was built and tested (change-first ordering, adaptive budget-fitted portioning, `_context_pass`
  scoped to changed files, honest `evidence_pass_bounded` degradation; branch `engine-change-scoped-evidence-pass`).
  It correctly cut the tiered pair count — but `query_seconds` stayed **0** every time. The live numbers show why:
  | pairs tiered | run_batch calls | evidence s | build s |
  |---|---|---|---|
  | 1015 | 1 | 238 | 52 |
  | 512 | 1 | 219 | 68 |
  | 64 | 2 | 220 | 68 |
  | 4 (probe) | 1 | 160 | 127 |
  Evidence time is **flat regardless of pair count** → the cost is **per-*call* fixed** (~150–220 s: loading the CPG
  into the query engine + the census the evidenceOnly batch computes), ~85 ms/pair on top. Pair-count scoping
  therefore cannot free budget, and portioning re-pays the fixed cost per call (so (i) can be counterproductive).
  Build is also large and swings 52→127 s — two engines thrashing the 7 GB host (the record-07 baseline shares it).
  The real levers are now (iii)-shaped, not (i): **warm/persistent query engine or a cached census** to kill the
  ~150 s per-call fixed cost, and/or a **bigger engine-arm budget** than 300 s; plus a **clean (uncontended)
  measurement**, because contention alone may be inflating build + fixed cost 2–3×. Scope+bound is NOT merged.
  **UNCONTENDED measurement (2026-10-11, baseline paused via SIGSTOP + container kill, then resumed).** Shipped
  engine, one evidence call over 1,015 pairs: `build=48 s`, `evidence=243.79 s`, `query=0`. The evidence pass is
  **the same ~244 s uncontended as ~238 s contended** → the cost is **INTRINSIC, not contention**; contention only
  inflated `build` (48 → 127 s) and added run-to-run noise. The model is `evidence ≈ 150 s fixed (CPG load into the
  query engine + the census the evidenceOnly batch computes) + ~93 ms/pair` (244 = 150 + 1015×0.093). Consequences:
  - **~200 s of fixed overhead** (`build` + evidence-load) precedes any analysis, so a 300 s budget leaves only
    ~100 s for everything else. This is why `query=0` even on a clean host.
  - **Change-scoping still helps, but only by cutting the per-pair tail** (~1,015×93 ms ≈ 95 s): one evidence call
    over ~30 changed pairs is ~150 s + 3 s instead of 244 s, which would free ~90 s — possibly enough for analysis,
    but marginal.
  - **It must be ONE call, not portioned.** The ~150 s is a first-call load, so the adaptive probe attributed it to
    its 4 probe pairs (per-pair≈37 s), concluded the budget fit ~0 more, and tiered only 4 — the implemented
    scope+bound is doubly wrong for this cost model. The correct shape: change-first candidates, count-capped, ONE
    evidence call, `deadline=None`.
  - **Pre-push viability:** the ~200 s fixed floor means the engine arm cannot be a fast (≤30 s) pre-push check on a
    repo this size without a warm/persistent session or a cached census. A larger budget (e.g. 600 s) makes the
    benchmark arm run but is not a realistic pre-push deadline. The lever that matters for the product is killing
    the ~150 s fixed cost, not scoping pairs.
 - [ ] **2. Seed analysis from the change.** Prioritize (or restrict first-pass to) the changed declarations plus
  their call/data neighborhood over repo-wide static rank, within budget.
 - [ ] **3. Soundness.** Keep cross-file dataflow INTO the changed function (don't scope to literal changed lines);
  add tests; keep existing push tests green.
 - [ ] **4. Live re-test.** Re-run the bedrock change: does analysis now RUN and produce a finding on
  `install_packages` (vs `deferred`)? Re-run metrics-plugin.
 - [ ] **5. Measure the delta.** Engine-arm sample on the pool (catch/false-alarm + engine-coverage rate) — needs the
  kube lane (blocked on the AX completion path) for scale.
 ## Dependencies / notes
 - Coverage `complete_within_scope` also needs the capability registry (Task 8.3) regardless of this work; the win
  here is findings moving from `comparison_unknown`/deferred to a decided novelty → advisory engine finding.
 - Implement directly and verify on the LIVE instrument (a fake-client/unit pass is not evidence the live engine
  changed); the kube-lane and store endpoints are operator-owned infra, not assumptions to make here.
 </content>
@@ -132,6 +132,13 @@ rule hits.
   - **t_quiet**: per family, the highest threshold keeping >= 90% of the paired positives at or above it (chosen
     on training folds, its held-out recall reported); findings below it are silent.
   - No held-out label moves a threshold or a normalisation map; candidates whose verdict is `unsure` never block.
 5. *(Amended 2026-10-05, maintainer decision, with `search-with-proof`.)* Where a family has an owned demonstration
   oracle, the engine is **triage, not the gate**: BLOCK comes only from a verified demonstration (`search-with-proof`
   Req 3, 6.3), and the engine's job is to put the true vulnerable function among the top K candidates of a push.
   For those families the engine is judged by (a) top-K recall per push (K = 3 to start) on the unseen-repo pool and
   (b) its advisory false-alarm rate there; the pooled block gate of 6.4 then governs only families without an
   oracle (access control, deserialisation, configuration and secrets), where the engine remains the only signal.
   Every arm reports top-K recall next to its catch and false-alarm rates.
 ### Requirement 7: Built for unseen repositories -- a repo safety net
@@ -237,3 +237,30 @@ rate per push. Within-pair AUC stays a development signal. Tasks 11-14 below fol
  - Planned, roadmap G3. The exp-004 design with the family floor (Req 6.4), together with the pool's false-alarm
    rate per family.
  - _Requirements: 6.4, 7.3_
 - [ ] 15. Trained classifier arm (maintainer decision 2026-10-04: train a model, not hand-set profiles; judged on the
  unseen-repo pool, roadmap G1)
  - [ ] 15.1 Features: code embedding of the excerpt (stored vectors) + every allow-listed signal; no hand-picked
    profile. Automated screening: a signal that separates pair sides by itself on training folds above the leak
    threshold is dropped for that fold (the leak audit as a filter, fitted per fold).
  - [ ] 15.2 Models: regularised logistic regression and gradient-boosted trees, fitted per repository-held-out outer
    fold with inner-fold hyper-parameter search; per-family and pooled variants.
  - [ ] 15.3 Scores on held-out folds: within-pair AUC, pooled AUC, top-k precision, Wilson bound at the pooled
    threshold; compared with the current LLM programs on the same units.
  - [ ] 15.4 Scored on the unseen-repo pool when G0 exists: catch rate at fixed false-alarm budgets.
  - _Requirements: 3 (revised 2026-10-04 by maintainer decision), 6, 7_
 - [ ] 16. Jointly optimised LLM program arm (judged on the unseen-repo pool)
  - Search input fields, retrieval parameters, k, instruction and demonstrations together (DSPy MIPRO-style) on
    training folds; no hand-set input profile. Budget go-ahead before paid search.
  - _Requirements: 3, 6, 7_
 - [ ] 17. Triage objective (Req 6.5, amended 2026-10-05 with `search-with-proof`)
  - [ ] 17.1 Metric: top-K recall per push (K = 1, 3, 5) of the true vulnerable function among changed functions,
    on held-out folds and on the unseen-repo pool; added to the pool scorer next to catch and false alarm.
  - [ ] 17.2 Score the existing arms on it ($0 replay): trained logistic (cheapest per candidate, likely default),
    LLM programs (exp-005 A), engine-evidence ordering, and an averaged ensemble.
  - [ ] 17.3 Re-scope 14 (pooled block gate) to families without a demonstration oracle; 15.4 and 16 report top-K
    recall as their primary unseen-pool number for families with an oracle.
  - _Requirements: 6.5, 7_
@@ -0,0 +1,67 @@
 # Brief: MCP shift-left agent + skills
 Status: brief / not yet specced. Proposed 2026-10-07. Delivery surface for the
 qualified safety net; builds on the existing `ousast mcp` server and the product
 skills. Related: `proof-arm-opencode` (the proof model), `pre-push-safety-net`
 (the gate), `unseen-repo-evaluation` (the qualification).
 ## Motivation
 The pre-push hook is the gate. Developers and their coding agents want the same
 security feedback **earlier**, while the code is still being written, not only at
 push. And in an agent-driven workflow, a mandatory security check is how a human
 oversees agents: the agent's output has to clear it before it ships.
 Proposal: expose the safety net through an MCP agent and a small set of skills so
 an editor or a coding agent can ask for a security read of the changed code on
 demand, shift-left, and so a coding agent can be required to pass it before it
 proposes a push.
 ## Shape
 - **Transport:** extend the existing narrow MCP server (`ousast mcp`, stdio) that
  OpenCode and other agents already speak. No new network surface; same
  no-secret, bounded contract.
 - **What the agent offers:**
  1. Scan the current diff with the static arm (fast, no model, no cluster) and
     return findings scoped to the change, with location and a concrete repair
     direction, not a confidence label.
  2. Triage a finding: explain it in plain terms and whether it is reachable.
  3. Prove on demand: hand the top candidate to the proof arm when a runnable
     harness exists, and return the demonstrated proof-of-concept.
 - **Skills:** the existing `openultrasast-scan` and `openultrasast-triage`
  product skills, plus shift-left additions (scan-the-diff, explain-a-finding,
  suggest-a-fix-direction) that a coding agent invokes mid-task.
 - **Oversight mode:** a coding agent can be configured to call the scan as a
  required step before it finalizes a change, so security review is automatic
  rather than remembered.
 ## Control (same model as the hook)
 Advisory by default; blocking is opt-in. Budget and a push/call deadline bound
 the work. The inline path runs the fast static arm only; heavy proof is explicit
 and lane-selected. Models and spend caps stay in `.env`.
 ## Open questions for the spec
 1. Inline latency budget: in-editor feedback must return in seconds, so the
   static arm must be fast on a single diff. What is the time contract, and does
   the large-repo latency problem block it?
 2. Return contract: exactly what a coding agent gets back (findings, locations,
   repair direction, optional proof) and how it decides pass/fail in oversight
   mode. The return should be ticket-ready evidence a busy developer can paste
   into the issue tracker to win capacity in a prioritization discussion with a
   product owner, since a reproducible proof is what moves a security fix out of
   the backlog.
 3. Does oversight mode need a signed/attestable result so a reviewer can trust
   that the agent actually ran the check?
 4. Reuse: the `ousast mcp` tool set already exists; which tools are enough and
   what is genuinely new.
 ## Scope and sequencing
 This is a delivery and adoption surface, correctly **after** the safety net is
 qualified on unseen repositories (G0 through G5). It is not a detection change;
 it is how developers and agents consume the detection early. The proof model
 improvement lives in `proof-arm-opencode`; this brief is the dev- and
 agent-facing feedback channel.
@@ -0,0 +1,10 @@
 {
  "feature_name": "mcp-shift-left-agent",
  "created_at": "2026-10-07T15:10:00Z",
  "updated_at": "2026-10-07T15:10:00Z",
  "language": "en",
  "phase": "brief",
  "approvals": {"requirements": {"generated": false, "approved": false}, "design": {"generated": false, "approved": false}, "tasks": {"generated": false, "approved": false}},
  "ready_for_implementation": false,
  "summary": "MCP agent + skills so developers and coding agents get the safety net's feedback early (shift-left, in-editor) and so a coding agent can be required to pass a security check before it ships. Delivery surface after G0-G5 qualification; builds on the existing ousast mcp server."
 }
@@ -0,0 +1,104 @@
 # Brief: OpenCode-MCP proof arm (follow-up to search-with-proof)
 Status: brief / not yet specced. Proposed 2026-10-07 by the maintainer. Builds on
 `search-with-proof` (see `../search-with-proof/verification-architecture.md`).
 ## Motivation
 The search arm (directed, Cairn-inspired) works. The **proof-authoring** last mile is the drag:
 1. **Safety-classifier refusals.** Authoring exploit demos repeatedly tripped a safety classifier
   this session when exploit payloads or step-by-step attack prose passed through the model or a
   tool prompt. The mitigation so far (keep payloads on disk, treat demos as opaque) is a workaround,
   not a fix, and it limits how directly the proof model can reason about the exploit.
 2. **Nondeterministic wiring.** The agent authors a demo but intermittently mis-wires the app to
   the oracle fixture (served directory for path, database URL for SQL), so a demonstrable pair
   comes back inconclusive until a retry. Each miss has cost a paid run.
 Proposal: drive the proof with an **agentic coding tool (OpenCode MCP)** running **inside gVisor**,
 using a model chosen for exploit authoring rather than one that refuses it, and **learn** the
 proof-authoring policy with DSPy from **traces logged in OpenObserve**.
 ## Shape
 - **Search model:** DeepSeek (current). Good at the directed fact/intent search.
 - **Proof model:** GLM 5.3 (Anthropic-recommended) and/or an abliterated model via
  `ABLITERATION_BASE_URL` (`abliterated large v2`). The abliterated model authors exploit **demos**
  without the refusals that block a safety-trained model on this defensive task.
 - **Proof driver:** OpenCode MCP (github.com/AlaeddineMessadi/opencode-mcp) as the agentic
  demo-author, running inside the gVisor verification task so the exploit-authoring is sandboxed.
 - **Learning:** DSPy compiles/optimizes the proof-authoring program (demo schema, wiring, steps)
  from past traces, instead of the per-family hand-guidance we keep adding (which is now hitting
  the prompt character budget — a signal the hand-rule approach is near its limit). Matches the
  maintainer's "learned decisions, not hand-tuning" direction.
 - **Tracing:** proof runs (reason/explore/author/verify, timings, outcomes, error classes) log to
  **OpenObserve AI** at `OPENOBSERVE_URL` (org `OPENOBSERVE_ORG`, stream `OPENOBSERVE_TRACES_STREAM`).
  DSPy consumes these traces as its training signal.
 - **Credentials:** stored in `.env` like the existing keys, referenced by name only:
  `ABLITERATION_API_KEY`, `ABLITERATION_BASE_URL`, `ABLITERATION_MODEL`, `OPENOBSERVE_URL`,
  `OPENOBSERVE_ORG`, `OPENOBSERVE_TRACES_STREAM`, `OPENOBSERVE_TOKEN`. No secret value ever enters a
  tracked file, a prompt, a log stream, or a commit.
 ## The trust-domain decision (must be resolved first)
 The current design keeps the **model key on the VM only**; cluster tasks carry no secrets and have
 restricted egress (verify tasks reach the files host only). Running the proof **model** inside gVisor
 (as OpenCode MCP would) breaks both: the task would hold a model key and need egress to the model
 API host. Two options:
 - **A. Scoped key + egress in the cluster (operator-managed).** Inject a spend-limited proof-model
  key into the proof task (like the existing `gemini-api-secret` slot) and add a per-host egress
  allowlist for the proof-model API. Keeps the fully-sandboxed agentic authoring the maintainer
  wants; requires an operator change and widens the cluster's secret/egress surface.
 - **B. Brain on the VM, execution in gVisor (current split preserved).** OpenCode MCP and the proof
  model run on the VM; only the DAST execution stays in gVisor. No new cluster secret or egress;
  but the agentic authoring loop is not itself sandboxed.
 Recommendation: start with **B** (no trust-domain change, fastest to try the abliterated proof model
 and DSPy loop), and move to **A** only if sandboxing the authoring loop itself proves necessary.
 ## Security scope (why an abliterated model is in-scope here)
 This is authorized **defensive** work: authoring proof-of-concept demos for **known CVE fix-pairs**
 in a **gVisor-isolated** corpus, to demonstrate a regression before push. Guardrails to keep:
 - Demos are **data**, not agent code; they stay in the gitignored private area, never echoed.
 - No real-world or third-party live targets; only the frozen fix-pair corpus and owned oracles.
 - gVisor is the execution boundary; the abliterated model never runs code itself, it only writes a
  declarative demo the trusted verifier executes.
 - The abliterated model is confined to proof-authoring; the search and all reporting stay on the
  normal models.
 ## Open questions for the spec
 1. A or B for the trust domain (above).
 2. Does the abliterated proof model actually raise the demonstrated rate and remove the wiring
   misses, measured on the pairs already shown demonstrable (xiaomusic, glance)? Qualify before scaling.
 3. DSPy program shape: what is the proof-authoring signature (inputs: candidate + oracle contract;
   output: a valid, wired demo), and what metric does it optimize (demonstrated rate at zero false
   proofs) from OpenObserve traces?
 4. Does OpenCode MCP fit the existing executor/verifier task contract (no-secret, presigned I/O,
   scratch/egress limits), or does it need a new task kind?
 5. Cost envelope per proof vs the current DeepSeek authoring.
 ## OpenCode MCP as the endpoint for both PoC and fix
 Maintainer note (2026-10-07): OpenCode MCP is a good server endpoint for the PoC **and** the fix,
 not only proof authoring. The same agentic endpoint can:
 1. Author the PoC (the demonstrated proof) for a caught finding.
 2. Write a candidate fix against the finding's repair direction and the failing PoC.
 3. Hand the fix back to the differential verifier, which re-runs the PoC and confirms absence
   (the proof flips from failing to passing).
 This turns the "no auto-patch" gap in `../../../docs/use-case-fix-and-reverify.md` into "the proof
 endpoint also proposes the fix, and the fix is accepted only when the proof it generated goes green."
 The PoC is the acceptance test for the fix, so a wrong fix is caught, not trusted. The fix stays a
 proposal for the developer to review; the verifier's green proof is the objective signal, not the
 model's say-so. This fix capability is specced alongside the proof authoring when this arm is built.
 ## Not in scope
 Changing the search arm, the oracle differential, or the abstract-interpretation triage. This brief
 is about the **proof-authoring and fix** driver and its learning loop, planned as a full spec after
 the safety net is qualified.
@@ -0,0 +1,10 @@
 {
  "feature_name": "proof-arm-opencode",
  "created_at": "2026-10-07T14:40:00Z",
  "updated_at": "2026-10-07T14:40:00Z",
  "language": "en",
  "phase": "brief",
  "approvals": {"requirements": {"generated": false, "approved": false}, "design": {"generated": false, "approved": false}, "tasks": {"generated": false, "approved": false}},
  "ready_for_implementation": false,
  "summary": "OpenCode-MCP proof-authoring arm for search-with-proof: abliterated/GLM proof model, DSPy-optimized from OpenObserve traces; trust-domain decision (A scoped-key-in-cluster vs B brain-on-VM) must be resolved first. Creds in .env by name."
 }
@@ -0,0 +1,103 @@
 # Search-with-proof — handoff (2026-10-06)
 State at handoff, for resuming on the search problem and abstract interpretation.
 ## RESOLVED 2026-10-07 — the one open question is CLOSED: first cluster demonstration achieved
 The "first `demonstrated`" question below is answered. search-with-proof produced its first autonomous
 `demonstrated` finding end to end on kube-ax, and a blind negative confirmed no false proof.
 - **Pair:** hanxi/xiaomusic (pilot pair 13), family `path`, vulnerability class **prefix-check bypass**
  (`startswith(root)` without a trailing separator; the fix adds `os.sep`). Image `e2c8b460`.
 - **Vulnerable side:** `demonstrated` — owned effect in 3/3 affected runs, 0/3 safe runs. $0.37, 55 calls.
 - **Fixed side (blind negative, Req 6.3):** `inconclusive`, **0 false proofs**. $0.56, 85 calls.
 - **Pair total:** $1.22. Record: `benchmarks/measurements/2026-10-07-search-first-cluster-demonstration/`.
 **The original pair-6 both-sides-false was a TWO-part diagnosis, both now fixed:** the demo did not reach the
 observable (demo/agent), and — the decisive one — the path oracle only modelled **classic parent traversal** while
 many real path CVEs (xiaomusic included) are **prefix-bypass**, which reaches a sibling that string-extends the served
 dir, not the parent. The oracle now also plants a prefix-sibling canary.
 **Fix chain that enabled the demonstration (each merged to main and validated by a paid run):**
 1. Parity — agent is told the observable's location (path oracle reached parity with command/ssrf).
 2. Verify-time-only — the observable is injected at verify time and absent during exploration; stop the explore-time
   reachability trap that burned budget without authoring a demo.
 3. Fair-share pilot budget — each search gets a fair share of `--ceiling-usd` with rollover, so one expensive search
   no longer starves the rest.
 4. Served-root guidance — the demo MUST set the app's served directory to the `${served_root}` placeholder.
 5. Oracle prefix-bypass coverage — plant a sibling canary for the `startswith`-without-separator class.
 6. Control-signal feedback — the keystone control (does the app serve `${served_root}`?) is fed back to the agent as a
   `served-root` hint so it self-corrects its wiring. This was the decisive last step.
 **Keystone (honest measurement), merged earlier:** the verifier runs a benign positive control; a broken or mis-wired
 app yields `could_not_run`/annotation, never a silent clean-looking `inconclusive`.
 **Next toward the pilot exit (Req 6.2):** fan out the path family to ≥5 demonstrations with 0 false proofs, then the
 ≥73-negative BLOCK qualification (Req 6.3). The glance pair (classic traversal) also demonstrates once its npm
 dependency build-break (`filed`→`mime@4`) is pinned.
 ---
 ## The one open question (HISTORICAL — resolved above)
 The full chain runs end to end on kube-ax. Every execution layer is cleared. The **first `demonstrated` has not
 happened yet**, and the remaining gap is narrow and reproducible at **$0 model cost** via `demo_replay`.
 No-model replay of pilot pair 6 (path / Node / npm build), both sides, image `aa54880`:
 - Both sides **build, start, and run** (ready ~18–20 s, "fresh task run completed", no `could_not_run`).
 - Oracle observed **no effect on either side** → `inconclusive`, "no consistent differential".
 Both-sides-false means it is **not the harness** any more. It is one of:
 1. The demo's attack step as written does not trigger the effect even on the vulnerable revision, or
 2. The oracle does not capture the app's output where the effect would show.
 ## How to close it (no model spend)
 - Control: the **probe path app** (`src/openultrasast/search/probe_apps/`) is known-good and *does* observe through the
  same verifier code path. Diff its behaviour against the real app: how the served directory is wired
  (`${served_root}` substitution in `start.arguments`), and where the oracle reads the nonce from (app stdout/response
  capture in `oracles.py` `PathOracle.observe`).
 - Re-run with `python -m benchmarks.search.demo_replay --both --demo <stored demo.json> --family path --lane ax
  --image <digest> ...`. Stored demos live under `benchmarks/search/private/runs/*/<pair>/demo/demo.json` (gitignored).
 - **Classifier note:** keep exploit payloads on disk. Hand Codex file-path tasks that treat demo contents as opaque;
  print outcomes / phase timings / error *classes*, never request strings, env values, or step bodies. See memory
  `search-with-proof-direction` and the classifier false-positive note. Code changes never tripped it; echoing
  payloads or step-by-step attack prose did.
 ## What is done and merged (main)
 - Trust-domain split: model key on the VM only; executor and verifier tasks carry no secrets; exchange via presigned
  objects. Declarative demos (data, not agent code). gVisor is the cluster boundary.
 - Verifier + 5 oracles pass inside a gVisor task (probe: 5/5 demonstrated, gaming demos inconclusive).
 - Shared task base image, code-last layers; `plane/task-base.digest` pins it; `engine-image.yml` builds only on
  dispatch / tags / Dockerfile / pin changes. Measured unpacked: search 2.07 GB, engine 3.61 GB.
 - Pilot driver (`benchmarks/search/pilot_run.py`), budgets with reservation, named exhaustion limits, `demo_replay`.
 - Per-host egress live: exec → any 443; verify/probe/pass → files host; replay → files + github. Task names carry
  the right prefixes.
 ## Plumbing defects fixed along the way (each cost one run)
 step allowance → family-vs-oracle mapping → build memory (256 MB SIGTRAP) → manifest path appended positionally →
 startup env + data files → dead-end intent dedupe → archive size (edge ~100 MB, now split+gzip) → two-interpreter
 image (pip 3.13 vs venv 3.12 → use `sys.executable`) → checkout root on sys.path → `node_modules` path.
 ## Next, once a demo demonstrates
 1. Fan out the pilot across all 20 pairs, both sides (feasibility: demonstrated rate per family, zero false proofs on
   fixed sides). Exit: ≥1 family with ≥5 demonstrations and zero false proofs (Req 6.2).
 2. BLOCK qualification per family: 0 false proofs over ≥73 negatives from ≥73 repos (Req 6.3).
 3. G1 arm on the unseen pool vs the triage/decision arms at equal false-alarm budgets (Req 6.5).
 ## Cluster / spend facts
 - kube-ax: **2 tasks in flight, one per worker** (operator `--max-actors=1`). Dispatcher caps AX concurrency at 2;
  raise it only when the operator raises worker count. "no free workers available" = retry, not failure.
 - `/workspace` ~3 GiB free per node until the volume move; scratch guard 2 GiB/task.
 - Pilot spend to date ~$11 across 9 paid runs; the decisive replay was $0.
 ## Decision model vs search — current read
 - Decision/classification: measured, **promising as triage** (within-pair AUC 0.762; trained logistic ties at 0.721),
  **capped as a blocker** (cannot prove 95% precision). Reframed as triage (`learned-decision-engine` Req 6.5).
 - Search-with-proof: **not yet demonstrated**, but no observation so far argues against the idea — every failure was
  our execution, now cleared. The pair-6 demo/oracle question is the first verdict on the method itself.
@@ -0,0 +1,40 @@
 # Brief: search with proof
 Maintainer, 2026-10-05, after reviewing Cairn (github.com/oritera/Cairn): "we are still not progressing through the
 state space search / not finding what we need and the progress is sort of slow ... i think something is missing."
 And: "I'd move to primarily executing in the cluster."
 ## What was missing
 Every detection step so far classifies: it scores one function excerpt and then tries to make the score precise
 enough to block. Calibration, Wilson bounds, pooled block gates, prompt variants and trained models all hit the same
 wall: ranking is decent (within-pair AUC about 0.76), but precision at the top cannot be proven to 95% on our data.
 Cairn treats a security problem as a directed search with an objectively checkable goal. A shared board holds
 confirmed facts, open intents and human hints. A reasoner proposes independent intents; explorers with real tools
 each confirm one fact; the loop ends when the goal is demonstrably met.
 Three things follow for OpenUltraSAST:
 1. **An objective success condition.** A finding is demonstrated when a test or proof of concept fails on the
   vulnerable code and passes on the fixed code (or, for a push, fails on head and passes on base where applicable).
   A demonstrated finding is right by construction; it needs no calibration and no training data, so it generalises
   to unseen repositories by construction.
 2. **Exploration with tools.** Agents that read other files, follow callers, build and run the code, instead of a
   single-shot judgement of one excerpt.
 3. **Search state per repository and push.** Facts and intents accumulate on a board instead of every question
   starting from zero.
 ## Shape
 - The cheap layers (quick rules, engine, classifier) become triage: they rank candidates.
 - Agentic search runs only on the top-ranked candidates of a push, under a per-push budget.
 - BLOCK only on a demonstrated finding. Advisory for plausible, unproven ones. "Could not demonstrate" is recorded as
  such, never as "not vulnerable".
 - Execution is primarily in the kube-ax cluster: reason and explore steps are AX Tasks; the VM coordinates.
 - Model access: a scoped, budget-limited key in the cluster, managed by the operator.
 ## Not in scope
 Copying Cairn code (AGPL-3.0; this repository is Apache-2.0). Offensive use against systems we do not own: all
 execution is against code under analysis, inside gVisor sandboxes.
@@ -0,0 +1,25 @@
 # Design: search with proof (v2, after two Codex reviews; the Claude Doc is the readable version)
 ## Why: from scoring excerpts to proving findings
 BLOCK will mean a vulnerability was demonstrated and re-run by the system, not that a score passed a threshold. Every detection step so far classified one function excerpt, then tried to make the score precise enough to block. Same wall in every experiment: LLM programs (exp-005 A) within-pair AUC 0.762, pooled gate needs >=73 clean flags; trained logistic 0.721 (tie, CI spans zero); gradient boosting 0.597 (worse). Cairn (AGPL, design only) treats a security problem as directed search with a checkable goal. Three things follow: (1) objective goal: test/PoC fails on vulnerable, passes on fixed; needs no calibration or training data, so it carries over to unseen repos; (2) exploration with tools (read other files, follow callers, build, run); (3) search state: facts and intents accumulate on a board per search.
 ## Architecture
 VM coordinates and is the only writer to the board (memory store); every model call and execution runs as an AX Task on kube-ax. Triage (quick rules, engine, classifier) -> top K candidates -> first facts on the board. Reason task (reads snapshot, returns complete or <=3 intents) <-> board; Explore tasks (one per intent; read, grep, run, write demo/; return one fact) <-> board; Verify task (fresh sandbox, planted canary, vulnerable vs fixed / head vs base) -> outcome: BLOCK only if demonstrated, else advisory or silent. Scheduler and budgets on the VM check caps before every dispatch. Tasks read/write via presigned links; store credentials stay on the VM. VM is fallback lane, kind local fallback, same image.
 ## The demonstration contract (v2)
 The verifier, not the agent, observes the effect, on one side and not the other, consistently, in fresh sandboxes. Artefact: demo/ with build.sh and attack.sh (or a request file) touching only the documented external interface; its exit code and output are ignored. Oracles owned by the verifier per family: injection SQL = canary row seen in verifier's query log/response capture; path = canary file outside root read, seen by file-access watch; XSS = script executes in verifier's headless browser; SSRF = request arrives at verifier's in-sandbox listener; injection (command) = canary side effect seen by process watch. Deserialisation, access control, config/secrets: no owned oracle yet -> plausible_unproven at most. Attacker boundary excludes source tree, dependencies, runtime, fixtures; checkout and dependencies read-only during run; untracked files, dependency swaps, runtime patching refused. Differential: fix pair vulnerable-vs-fixed; push head-vs-base. Both sides must build and pass readiness independently; each side 3 runs from fresh state; inconsistent runs rejected; a side that fails to build or start => inconclusive, never a pass. Outcomes: demonstrated (BLOCK once the family is qualified), plausible_unproven (advisory, a visible finding), could_not_build/could_not_run/inconclusive (advisory if facts support, else silent; never "not vulnerable"), no_oracle (as plausible_unproven), no_evidence (silent). REGRESS's nonzero-exit-is-triggerable rule (regress/verdict.py) is not reused for proof; its sandbox plumbing is.
 ## Agent worker and sandbox tools
 Own small tool loop in src/openultrasast/search/ via the existing OpenAI-compatible client (provider swappable, spend metered, Apache-2.0). Image ousast-search-task from the AX task runner, toolchains for Python, Node and TypeScript, PHP, Java; repo fetched over HTTPS. Tools: list_files, read_file (400 lines/call), grep (200 matches), run (per-call timeout, truncated output), write_demo (only write, under demo/), finish (one fact or recorded failure). Engine evidence (taint path, sinks, missing guards) is in the explore prompt. Reason step uses no tools.
 ## Triage, budgets and model access (v2)
 Top K per push (K=3); candidate carries family hint + engine evidence as first facts. Caps (ceilings, not estimates): reason rounds 4/search, intents 3/round, explore 15 min/intent, $0.50/search, $1.50/push, 3 demos x 2 sides x 3 runs. Spend reserved before each model call at max cost and settled after (plane/budget.py gets a reservation step); per-task memory/disk/cleanup limits sized to workers (~3 vCPU, 5-5.75 GiB, two heavy lanes); total run wall-time and retry cap. Worst case 120 task-hours for 40 searches (~60 h on two lanes); a 1,300-change slice at K=3 could reach $1,950. First 3 pilot searches measure real cost; pilot ceiling set from that and asked for. Model key: operator scoped secret (AX injects only GEMINI_API_KEY; operator decides mechanism); never in manifest/log/board/record; repository code cannot read it: model client runs in a separate process as its own user.
 ## Pilot, qualification, then the unseen pool (v2)
 1. Feasibility pilot: 20 dev-corpus pairs (never v3/pool), the four pool families with an owned oracle (injection, path, output encoding, untrusted destination), across the pool's five languages (Python, JS, TS, PHP, Java). Candidate = labelled function (measures proof, not triage); advantages recorded; fixed-side search never sees the vulnerable revision or its demo. Reported: demonstrated rate per family/language, false proofs, could_not_build/run/inconclusive/no_oracle rates, spend/tasks/wall. Exit: >=1 family with >=5 verified demonstrations and zero false proofs, else stop.
 2. BLOCK qualification per family: 0/20 still allows 16.1% (Wilson 95%); a family BLOCKs only after >=73 negative-side searches (fixed revisions + ordinary changes) with zero demonstrated (upper bound 5%, same bar as the pooled gate). Until then demonstrations show as advisories.
 3. G1 arm on the unseen pool: triage top K on every replayed change in a fresh slice; scored with the pool's rules on every visible finding incl. advisories, family + location match; 1/5/10% FA budgets beside classifier arms; adopted only under the no-regression rule. No evaluation label, fixing revision or evaluation board is ever an input to unseen search.
 Every run reports the coverage ceiling (true candidate x owned oracle x both sides runnable x genuine differential, build failures in the denominator) next to catch. Delayed results go via push/background.py and are scored separately from push-time results.
 ## Decisions, risks and open questions
 Largest risk: environment failure caps the demonstrated rate. Risks: builds fail; agent games oracle (mitigated by re-run, canary, differential, tracked-file check); repo code misuses egress (gVisor; ask operator for no-egress verify class); cost (hard caps); minutes per search too slow for synchronous hook (decide product path after pilot). Open: operator key mechanism + no-egress class; own tool loop vs CLI agent; pilot go-ahead $20; how a minutes-long search reaches the pre-push user.
@@ -0,0 +1,80 @@
 # Declarative verification and separate execution domains
 Implemented on `search-with-proof`, 2026-10-05, under the maintainer's explicit instructions.
 `git merge -q main` failed because the shared Git metadata is read-only. The amended requirements
 were read from the main checkout, including Requirements 3.1 and 5.2. No commits or network operations.
 ## Changes
 - Strict, bounded JSON demonstration schema, also supplied to the model's `write_demo` tool.
  Verifier-owned recipes cover pip, npm, composer, Maven, Gradle and no build. Runtime entrypoints,
  CLI/HTTP sequences and earlier-response captures are validated; private fixtures, environment
  substitutions, canary captures and script artefacts are rejected. Injection/traversal strings remain
  legitimate request payload data, never executable verifier instructions.
 - The verifier owns build, readiness and request execution. Local runs retain Bubblewrap (`userns`
  on this host). HTTP requests require an acknowledged readiness gate; incomplete observations fail
  closed. Build-generated internal symlinks are supported without accepting external or cyclic links.
 - A supplied AX side dispatcher selects `task-boundary` and creates three separate fresh tasks per
  side. Failure of local isolation without a dispatcher fails closed.
 - The model-holding worker delegates list/read/grep/run to an executor interface. Production uses
  presigned command/result objects; the in-process adapter is for tests. Commands have sequence
  numbers, identical-retry caching, deadlines, stop and bounded results. Uncertain outcomes prevent
  later commands from reusing that executor session.
 - AX executor tasks use the `ousast-engine-search-exec-` prefix. Task entrypoints reject inherited
  credentials before reading checkout input, then use an explicit environment allowlist.
 ## Changed files
 Production:
 - `src/openultrasast/search/demo.py`
 - `src/openultrasast/search/executor.py`
 - `src/openultrasast/search/worker.py`
 - `src/openultrasast/search/verify.py`
 - `src/openultrasast/search/verify_task.py`
 - `src/openultrasast/search/_sandbox.py`
 - `src/openultrasast/search/oracles.py`
 - `src/openultrasast/search/probe.py`
 - `src/openultrasast/search/probe_apps/app.py.txt`
 - `benchmarks/ax/batch.py`
 - `benchmarks/ax/search_verify.py`
 - `plane/Dockerfile.search-task`
 Tests and audit:
 - `tests/test_search_demo.py`
 - `tests/test_search_executor.py`
 - `tests/test_search_verify_transport.py`
 - `tests/test_search_verify.py`
 - `tests/test_search_worker.py`
 - `tests/test_search_isolation.py`
 - `tests/test_search_probe.py`
 - `tests/test_ax_batch.py`
 - `benchmarks/measurements/2026-09-08-module-audit.json`
 This report is the additional documentation file.
 ## Fresh validation
 `/home/mc/Source/OpenUltraSAST/.venv/bin/pytest -q tests/test_search_*.py tests/test_ax_batch.py tests/test_plane_literals.py tests/test_module_audit.py -rs`
 Result: **171 passed, 3 skipped, exit 0**, in 35.46 seconds.
 The three skips are Chromium isolation/network setup, SSRF localhost sockets and HTTP localhost sockets,
 all prohibited by this host's policy. Host verification mode was explicitly checked: `userns`.
 Ruff passes for search sources, AX changes and affected tests. Targeted strict mypy passes for the seven
 changed Python search implementation modules checked. Independent review approved the implementation,
 including follow-up timeout, readiness, capture, credential and generated-link regressions.
 Module audit: **171 modules**, **165 load-bearing**, **6 standalone capabilities**, **0 orphaned**.
 The audit read the worktree source explicitly with `PYTHONPATH=src`.
 ## Remaining validation gaps
 - No live AX/gVisor/kind dispatch, image build/pull/publish, or paid model calls were performed.
 - Actual ecosystem dependency installations remain unqualified. Python dependency loading was tested
  with a controlled offline build output and real isolated execution.
 - The three socket/browser integrations need a host or task where those operations are permitted.
 - Hard aggregate disk isolation in `task-boundary` mode requires an outer task storage quota. The
  executor records this requirement and additionally bounds individual files and monitors checkout
  growth; it cannot enforce a quota across every writable task path without that outer resource limit.
 - AX tasks configured to inject a model credential will fail closed; executor and verifier task classes
  must be provisioned without that injection.
@@ -0,0 +1,101 @@
 # Host launcher repair and kube-ax operator constraints
 2026-10-05, branch `search-with-proof`. Implemented under the maintainer's explicit
 instructions. No commits or network operations. Existing uncommitted work was preserved.
 This supersedes the build/transport and disk-bound statements in
 `implementation-trust-domains.md` where they differ.
 ## Root cause and repair
 The HTTP driver calls `subprocess.Popen(..., stdin=DEVNULL, stdout=DEVNULL,
 stderr=DEVNULL)` inside bubblewrap. Its filesystem had no `/dev/null`; Python failed
 in `_get_handles` before starting the app, binding port 18765, or applying captures.
 Other probe apps do not use this nested HTTP launcher path.
 A socket-free before/after reproduction read a 19-byte instrument input. Removing
 `--dev /dev` reproduced exit 1 and the reported `subprocess.py:992 → _get_handles`
 stack, ending with `FileNotFoundError: [Errno 2] No such file or directory: '/dev/null'`.
 With the private device mount, the identical launcher exited 0 with empty stderr.
 The original HTTP capture test's fixed port, token exchange, and differential
 assertion remain unchanged. Reasons now retain the last 2,000 stderr characters;
 executor result truncation retains stderr tails too.
 ## Operator contract
 - Shared two-slot AX reservations cover workload lane instances and long-lived
  search executors. Capacity rejection retries the identical manifest with 15–30
  seconds of jitter until the deadline. Exhaustion is `capacity_timeout`, never
  `sandbox_failure`, and does not trigger another execution attempt or VM fallback.
  Uncertain task cleanup retains the reservation and halts dispatch.
 - Task entrypoints configure temporary files and the specified package caches under
  `/workspace`. The aggregate guard defaults to 2 GiB, configurable through
  `OUSAST_SCRATCH_BYTES`. It checks workspace files, caches, and unlinked output logs
  during child execution and after exit. Exceeding it returns `could_not_build` with
  `scratch limit`; unreadable scratch is not interpreted as zero usage.
 - The default AX side dispatcher first builds/packages each side in an executor,
  retrieves its digest-checked archive, and deletes the executor before verification.
  One archive contains the checkout, products, and spec. Three fresh verifier tasks
  consume that archive through `VERIFY_INPUT_URL`; results use `RESULT_URL`.
  Verifiers reject dependency builds. Git metadata is omitted from source archives;
  safe internal generated links are materialized before export.
 - Search tasks receive source archives. Executor tool guidance and project/operator
  documentation require HTTPS GitHub git clone or codeload, never `api.github.com`.
  First-download retries tolerate delayed egress activation for up to 60 seconds.
 ## Files changed in this follow-up
 Production:
 - `src/openultrasast/search/_sandbox.py`
 - `src/openultrasast/search/verify.py`
 - `src/openultrasast/search/executor.py`
 - `src/openultrasast/search/verify_task.py`
 - `src/openultrasast/search/task_storage.py` (new)
 - `src/openultrasast/search/worker.py`
 - `benchmarks/ax/batch.py`
 - `benchmarks/ax/search_verify.py`
 Tests:
 - `tests/test_search_isolation.py`
 - `tests/test_search_verify.py`
 - `tests/test_search_verify_transport.py`
 - `tests/test_search_task_storage.py` (new)
 - `tests/test_ax_batch.py`
 Documentation/evidence:
 - `.kiro/steering/kube-ax.md` (new)
 - `ops/ax/README.md`
 - `benchmarks/measurements/2026-09-08-module-audit.json`
 - This report (new).
 Other files already modified/untracked at session start remain uncommitted.
 ## Fresh verification
 - Requested suite, with `-rs` for skip reasons:
  `/home/mc/Source/OpenUltraSAST/.venv/bin/pytest -q tests/test_search_*.py tests/test_ax_batch.py tests/test_plane_literals.py -rs`
  — **181 passed, 3 skipped, exit 0**, 24.94 seconds.
 - Final executor/storage regression and module audit tests after tightening stderr
  truncation: **34 passed, exit 0**, including all **6 module audit tests**.
 - Shared dispatcher consumer `tests/test_unseen_calibrate.py`: **10 passed, exit 0**.
 - Module audit regenerated from the worktree using `PYTHONPATH=src`, with an explicit
  source read/byte count: **172 modules, 166 load-bearing, 6 standalone capabilities,
  0 orphaned**.
 - Ruff passes across search, AX, and changed tests; strict mypy passes for the six
  changed typed implementation modules. `git diff --check` passes.
 ## Gaps
 - Host policy prohibits Chromium network/isolation setup, SSRF localhost sockets,
  and the full HTTP capture test. These are the three skips. The exact missing-device
  failure is reproduced and repaired without sockets; full HTTP host confirmation
  remains necessary.
 - No live AX tasks, image builds/pulls, registry installs, or external downloads were
  run. Mocked transport plus local real child processes establish code contracts,
  not deployed cluster readiness. Verifier egress to
  `files.because-security.com:443` is requested from the operator and still pending.
 - Scratch enforcement is a polling guard, not an instantaneous filesystem quota.
  Programs that hardcode RAM-backed paths can still consume the worker memory limit.
  Archive bounds remain 64 MiB compressed / 256 MiB file contents / 20,000 entries;
  larger built projects fail explicitly and require a separately qualified envelope.
 - Multi-ecosystem dependency build/runtime qualification remains open. The offline
  preparation tests cover no-build projects and controlled Python build products.
@@ -0,0 +1,146 @@
 # Requirements Document
 ## Introduction
 Add a search-with-proof stage: for the top-ranked candidates of a push or a labelled pair, sandboxed tool-using agents
 search for a demonstration of the vulnerability, coordinated through a fact/intent board, executing primarily in the
 kube-ax cluster. BLOCK becomes "demonstrated", not "scored above a threshold". Context: `brief.md`, roadmap G1-G2,
 `unseen-repo-evaluation` (the pool and metric this arm is judged by).
 ## Boundary Context
 - **In scope**: the board (facts, intents, hints) in the memory store; reason and explore steps as AX Tasks; the
  demonstration contract and its verification; triage-to-search budgeting; a pilot on known fix pairs; a G1 arm on the
  unseen pool; model access through an operator-managed scoped key.
 - **Out of scope**: copying Cairn code (AGPL-3.0); network actions against anything but the code under analysis;
  changing the existing quick rules, engine or classifier (they are inputs here).
 - **Adjacent expectations**: `unseen-repo-evaluation` scores this arm; the AX batch dispatcher (`benchmarks/ax/batch.py`)
  and the kube-ax constraints (2 heavy lanes, `ousast-engine-` names, egress to public HTTPS) apply;
  `learned-decision-engine` Req 6.4 BLOCK rule is superseded for this arm by "demonstrated".
 ## Requirements
 ### Requirement 1: The board
 **User Story:** As the maintainer, I want each search to keep its state, so exploration builds on what is already
 known instead of restarting.
 #### Acceptance Criteria
 1. Per search (one candidate or one push), the board holds facts (confirmed, objective, with the evidence that
   confirmed them), intents (declared directions, open or concluded, with the facts they start from) and hints (human
   input, absorbed on the next read).
 2. The board lives in the memory store, versioned, and every fact and intent carries the step and the task that wrote
   it.
 3. A search ends when a fact meets the goal (Requirement 3), when its budget is spent, or when the reasoner proposes no
   new intent and none is open; the end reason is recorded.
 ### Requirement 2: Reason and explore steps
 **User Story:** As the maintainer, I want the search driven by the board's state, not by fixed roles.
 #### Acceptance Criteria
 1. A reason step reads the board and returns: the goal is met (citing facts), or at most N new, independent,
   non-overlapping intents, or no new intent.
 2. An explore step claims one intent, works it with tools inside the sandbox (read files, search the repository,
   follow callers, build, run tests and scripts against the code under analysis), and returns exactly one new fact or
   a recorded failure.
 3. Both run as AX Tasks in the kube-ax cluster by default; the VM coordinates (board, dispatch, budgets) and is a
   fallback lane only.
 4. Parallel explores of one search never race on the board (claims as in the batch dispatcher).
 ### Requirement 3: The demonstration contract
 **User Story:** As the maintainer, I want BLOCK to mean "shown", so precision does not depend on calibration.
 #### Acceptance Criteria
 1. *(Amended 2026-10-05, maintainer decision after the kube-ax probe: AX tasks have no capabilities, so gVisor and one
   fresh task per side are the only isolation.)* A demonstration is **declarative data, never agent-written code**: a
   build recipe chosen from the verifier's fixed per-ecosystem recipes, a start command of the form runtime + path +
   arguments (no shell), and a request sequence (HTTP requests or CLI invocations, with values captured from earlier
   responses) that the verifier itself sends. The system, not the agent, runs it in fresh sandboxes. The **verifier observes the effect itself** through a per-family oracle it owns (for
   example a request log, a planted resource it watches, a browser execution check for XSS); the artefact's own exit
   code or output is never the oracle.
 2. Each family's oracle states the attacker boundary (what the artefact may touch: only the documented external
   inputs of the code under analysis, never the verifier's fixtures, the source tree, dependencies or the runtime).
   Inputs are immutable during a run; untracked files, dependency replacement and runtime patching are refused.
 3. Differential: for a labelled pair the effect is observed on the vulnerable revision and not on the fixed one; for a
   push, on head and not on base. Both sides must build and pass a readiness check independently; a side that fails
   to build or start makes the result **inconclusive**, never a pass. Each side is run at least three times from fresh
   state; inconsistent runs are rejected.
 4. Only a verified demonstration counts as `demonstrated`. Outcomes: `demonstrated`, `plausible_unproven`,
   `could_not_build`, `could_not_run`, `inconclusive`, `no_oracle` (family without an owned oracle), `no_evidence`;
   none of the failure outcomes is ever reported as "not vulnerable".
 5. Families without an owned oracle (for now: deserialisation, access control, configuration and secrets) can reach
   `plausible_unproven` at most until an oracle is specified and reviewed.
 ### Requirement 4: Triage and budget
 **User Story:** As the maintainer, I want search spent where it matters, at a known cost.
 #### Acceptance Criteria
 1. Candidates come from the existing layers (quick rules, engine, classifier scores); only the top K per push or per
   pair side are searched; K and the per-search and per-push budgets (model spend, task count, wall time) are
   configuration, enforced by the coordinator.
 2. Every search records its model spend, task count and wall time. Spend is **reserved before each model call** (the
   call's maximum cost) and released after; wall time, memory, disk and retries are capped per task and in total; a
   budget is never exceeded, including by calls in flight.
 3. Paid runs need the maintainer's budget go-ahead with a ceiling, as all paid steps do.
 ### Requirement 5: Model access in the cluster
 **User Story:** As the maintainer, I want agents in the cluster to reach a model without spreading keys.
 #### Acceptance Criteria
 1. The agents' model key is a scoped, budget-limited key provided by the operator inside the cluster (AX v0.3.1
   injects only `gemini-api-secret` as `GEMINI_API_KEY`; the design names the exact mechanism agreed with the
   operator). Store credentials stay out of the cluster (presigned links, as today). For this arm, model calls inside
   the cluster supersede `unseen-repo-evaluation` Req 4.4 (model calls on the VM); that boundary is unchanged for all
   other arms. *(maintainer decision 2026-10-05: scoped key in the cluster)*
 2. The key never appears in a manifest, a log, a board entry or a record, and never shares a sandbox with repository
   code. *(Amended 2026-10-05, maintainer decision: trust domains are separated instead of isolated inside one task.)*
   The agent loop (the "brain", holding the key) runs on the VM or in its own AX task and executes no repository code;
   every tool call that touches the repository runs in a separate executor AX task without the key, exchanging
   commands and results through presigned store objects. A Firecracker executor runtime is considered only if the
   pilot's `could_not_build` rate shows gVisor cannot build the projects.
 ### Requirement 6: Feasibility pilot, false-proof qualification, then the unseen pool
 **User Story:** As the maintainer, I want to know quickly whether search with proof works, and to admit BLOCK only on
 evidence that meets the 95% precision bar.
 #### Acceptance Criteria
 1. **Feasibility pilot** (amended 2026-10-05 after review): about 20 known fix pairs from development corpora. It
   measures feasibility only and is reported as such: demonstrated rate on vulnerable sides, false proofs on fixed
   sides, `could_not_build` / `could_not_run` / `inconclusive` / `no_oracle` rates, spend, tasks and wall time. Its
   advantages (known location, labelled family, runnable-project bias) are stated in the record. Fixed-side searches
   never receive the vulnerable revision or its demo.
 2. Before any paid search, an infrastructure probe without model calls proves each owned oracle works inside a gVisor
   AX Task (database fixture for SQL, in-sandbox listener for SSRF, headless browser for XSS, file and process
   watches), that the artefact cannot reach the observers directly, and records image size, RAM and the full
   verification cost (up to 3 demos x 2 sides x 3 runs per search). Pilot exit: at least one family with at least 5 verified demonstrations on vulnerable sides and zero false proofs;
   otherwise the result is recorded and the arm is not scaled.
 3. **BLOCK admission per family** (deferred until the pilot passes; not part of the first tasks) requires a false-proof
   qualification. A **negative** is a search on code that should be safe: a fixed revision searched on its own (the
   search never sees the vulnerable revision), or an ordinary change. A **false proof** is the verifier observing the
   effect on that safe code, confirmed by adjudication (an ordinary-change alarm may be a real new bug and is
   adjudicated before it counts either way). Qualification needs zero false proofs over at least 73 negatives drawn
   from at least 73 distinct repositories, so the Wilson 95% upper bound on the false-proof rate per negative is at
   most 5%. This bounds the false-proof rate, not precision among flags; precision is reported separately from the
   pool. Repeated runs and repeated searches of one repository are one negative.
 4. **Coverage ceilings**: every run reports, separately, (a) the demonstrated ceiling: the share of vulnerable changes
   with a true candidate selected, an owned oracle, both sides runnable and a genuine differential, build and run
   failures in the denominator; and (b) the advisory ceiling: the share with a true candidate selected. Families
   without an owned oracle (access control, deserialisation, configuration and secrets) have a demonstrated and BLOCK
   ceiling of zero today; their advisory ceiling need not be zero.
 5. **G1 arm on the unseen pool**: scored with the pool's rules on **every visible finding** (BLOCK and advisory), with
   its family and location match; catch at the 1%, 5% and 10% false-alarm budgets; compared with the classifier arms;
   adopted only under the pool's no-regression rule on a fresh slice. No evaluation label, fixing revision or board
   from evaluation searches is ever an input to unseen search.
 6. Delayed results (a search finishing after the push) reach the user through the existing background delivery and
   are scored separately from results available at push time.
@@ -0,0 +1,29 @@
 {
  "feature_name": "search-with-proof",
  "created_at": "2026-10-05T12:00:00Z",
  "updated_at": "2026-10-07T13:30:00Z",
  "language": "en",
  "phase": "tasks-generated",
  "approvals": {
    "requirements": {
      "generated": true,
      "approved": true
    },
    "design": {
      "generated": true,
      "approved": true
    },
    "tasks": {
      "generated": true,
      "approved": false
    }
  },
  "ready_for_implementation": false,
  "pilot": {
    "status": "in_progress",
    "first_cluster_demonstration": "2026-10-07",
    "pair": "xiaomusic (path, prefix-bypass)",
    "false_proofs": 0,
    "exit_remaining": "path family >=5 demonstrations / 0 false proofs (Req 6.2), then >=73-negative BLOCK qualification (Req 6.3)"
  }
 }
@@ -0,0 +1,130 @@
 # Implementation Plan
 Scope: infrastructure probe and feasibility pilot only (Req 6.1-6.2). BLOCK qualification (6.3), the unseen-pool arm
 (6.5) and delivery (6.6) are deferred until the pilot passes. Implementation via Codex in a worktree; Claude reviews,
 gates, runs every networked or paid step.
 - [ ] 1. Operator prerequisites (Claude, no code)
  - [ ] 1.1 Ask the operator: scoped spend-limited model key mechanism (reuse `gemini-api-secret` slot or a new
    injection), and whether a no-egress task class exists for verify runs. _Requirements: 5.1, 3.2_
  - [ ] 1.2 Record the answers in `kube-ax-cluster` memory and design.md; no key value anywhere. _Requirements: 5.2_
 - [x] 2. Verifier and oracles (no model calls)
  - [x] 2.1 `src/openultrasast/search/verify.py`: fresh-sandbox runner per side; build, readiness check, read-only
    checkout and dependencies, untracked-file and runtime-patch refusal, 3 runs per side, consistency check,
    outcomes `demonstrated|inconclusive|could_not_build|could_not_run|no_oracle`. Artefact exit code ignored.
    _Requirements: 3.1-3.4_
  - [x] 2.2 Oracles owned by the verifier: SQL (database fixture + query log), path (file-access watch on a planted
    canary), XSS (headless browser execution check), SSRF (in-sandbox listener), command injection (process watch).
    Observers unreachable from the artefact. _Requirements: 3.1, 3.2, 3.5_
  - [x] 2.3 Unit tests with hand-written vulnerable/fixed toy apps per oracle, including gaming attempts (reading the
    canary, revision sniffing, patching a dependency, contacting the listener directly): each must not yield
    `demonstrated`. _Requirements: 3.2, 3.3_
 - [ ] 3. Image and infrastructure probe (no model calls)
  - [ ] 3.1 `ousast-search-task` image from the AX task runner: Python, Node/TypeScript, PHP, Java toolchains, the
    oracle fixtures, headless browser; built by CI to GHCR, pinned by digest. _Requirements: 2.3_
  - [ ] 3.2 Probe: the toy apps from 2.3 verified as AX Tasks on kube-ax (gVisor) and on kind. Record image size,
    RAM peak, disk, wall time per verification and per 18-run search, oracle success per family, and that observers
    are unreachable. Record `benchmarks/measurements/2026-10-xx-search-probe/record.json`. _Requirements: 6.2_
  - [ ] 3.3 Gate: every oracle works under gVisor, or the family is marked `no_oracle` for the pilot.
 - [x] 4. Board, coordinator, budgets
  - [x] 4.1 Board in the memory store as immutable versioned blobs (`plane/memory.py`); facts, intents, hints with
    writer step and task; coordinator is the only writer; tasks read and write through presigned links.
    _Requirements: 1.1-1.3_
  - [x] 4.2 Spend reservation before each model call in `plane/budget.py`, settled after; per-task memory, disk,
    cleanup caps; total wall-time and retry caps; tests that in-flight calls cannot overrun. _Requirements: 4.1, 4.2_
  - [x] 4.3 Dispatch reason, explore and verify as AX Tasks through `benchmarks/ax/batch.py` (extend its environment
    contract beyond numeric deadlines), VM lane as fallback, resume from checkpoints. _Requirements: 2.3, 2.4_
 - [ ] 5. Agent worker
  - [x] 5.1 Reason step (no tools): board snapshot in, `complete` / up to 3 intents / nothing out. _Requirements: 2.1_
  - [x] 5.2 Explore step: tool loop (`list_files`, `read_file`, `grep`, `run`, `write_demo`, `finish`) via the
    existing OpenAI-compatible client; model client in a separate process and user from executed code; one fact
    or a recorded failure. _Requirements: 2.2, 5.2_
  - [ ] 5.3 Smoke test with a stub model (no spend) end to end on one toy pair on kube-ax.
 - [ ] 6. Feasibility pilot (paid, after go-ahead)
  - [x] 6.1 Select 20 development-corpus pairs (never v3 or the unseen pool) in the four pool families with an owned
    oracle, across the five languages; record selection advantages. _Requirements: 6.1_
  - [ ] 6.2 Run 3 searches, measure real cost per search, ask the maintainer for the pilot ceiling. _Requirements: 4.3_
  - [ ] 6.3 Run the pilot: both sides per pair, fixed side blind to the vulnerable revision; record demonstrated
    rate, false proofs, failure-outcome rates, both coverage ceilings, spend, tasks, wall time.
    _Requirements: 6.1, 6.4_
  - [ ] 6.4 Exit decision against 6.2 and report to the maintainer; on pass, spec tasks for qualification and the
    unseen-pool arm. _Requirements: 6.2_
 ## Implementation Notes
 - Group 2 (2026-10-05): independently reviewed; `tests/test_search_verify.py` has 32 passing tests and one
  skipped SSRF integration test because this host forbids even localhost sockets. The namespace handoff and
  listener request parsing are tested separately; the full SSRF effect still needs the task 3.2 probe before
  claiming that oracle operational. The module audit and neighbouring sandbox/regression tests pass.
 - The local lane requires Linux Bubblewrap and util-linux, reuses `SandboxJob`/`SandboxResult`, and fails closed
  without isolation. Artefacts receive a batch CLI `TARGET` bridge and private scratch; HTTP apps need a trusted
  CLI adapter. Only trusted `Side.build_command` outputs can enter the app runtime (read-only `/build`);
  artefact `build.sh` writes scratch only. XSS requires a trusted browser executor, otherwise `no_oracle`.
 - Tasks 3.1 (files only) and group 4 (2026-10-05): independent review approved; final offline validation:
  107 passed, 2 skipped (Chromium namespace/socket restrictions and the existing SSRF localhost restriction).
  Ruff and changed-source mypy pass; module audit: 160 load-bearing, 6 standalone, zero orphaned. No network
  actions, model calls, image builds, pushes or commits were performed. Task 3.1 remains unchecked until the
  image is built/published and a real digest is available; CI now includes `plane/Dockerfile.search-task`.
 - The coordinator accepts an injected executor. `BatchExecutor` uses the repository's `benchmarks.ax.batch`
  transport with one attempt per admission; coordinator owns the global retry budget and VM fallback. It requires
  a repository checkout import path and a trusted worker command; reason/explore workers remain group 5.
  Per-task memory, disk and cleanup ceilings are passed in the worker contract; worker enforcement and gVisor
  compatibility still require group 5 and the 3.2 probe. Only trusted verification results can meet the goal.
 - Board heads are immutable memory-store hashes; retain the returned head with the host run to resume. Unknown
  interrupted model calls conservatively consume their full reservation; settled failures with zero spend release
  it. Cleanup exceptions stop dispatch. Chromium uses a fresh profile in a private network namespace; injected
  script must call `alert("ousast-xss")`, while escaped/reflected payloads cannot produce the verifier DOM marker.
 - Tasks 3.2 and 5.1–5.3 offline implementation (2026-10-05, explicitly authorized): packaged five-family
  toy pairs and real/two-gaming demos in `search/probe_apps/`; `python -m openultrasast.search.probe` reports
  per-side stage times, image versions, child/self peak RSS, retained scratch usage and sampled verification
  scratch peak. Generic isolation and later oracle namespace failures are instrument failures, never misses.
  Optional RESULT_URL uses an object-scoped urllib PUT. `benchmarks.ax.search_probe` reuses AX/Docker lanes
  (kind via its kubeconfig), with `ousast-engine-search-probe-` task names.
 - Worker reason/explore uses the existing OpenAI-compatible client with retries disabled and SpendBudget
  reservation before each call. Repository commands run only in the scrubbed sandbox with bounded tmpfs;
  the key-absence, timeout, output limit and disk limit tests execute real isolated processes. The scripted
  model/fake coordinator executor smoke reaches `demonstrated` through the real path oracle verifier.
 - Independent review APPROVED the requested offline scope. Fresh requested search/AX/plane tests plus module
  audit: 87 passed, 2 skipped, exit 0; focused new tests: 15 passed; Ruff and changed-source mypy pass.
  Audit: 162 load-bearing, 6 standalone, zero orphaned. Tasks 3.2 and 5.3 remain unchecked for their original
  live-cluster criteria; their code/local smoke is implemented. No network, paid calls, image builds, pushes
  or commits. Offline wheel build could not resolve the uncached uv-build backend, so installed-wheel and
  real AX/gVisor/kind/Docker image validation remain gaps.
 - Task 6.1 and executor smoke (2026-10-05, explicitly authorized): added
  `benchmarks/search/executor_smoke.py` and `pilot_select.py`, with offline tests and usage documentation.
  The smoke drives one managed, key-free executor mailbox and records per-command timing/output measurements
  and sampled workspace peak; AX and Docker lifecycle cleanup is covered by fake-lane tests. No live task ran.
  Pilot selection read 10 development catalogs (873 rows, 904,050 bytes), retained 192 eligible pairs and selected
  20 distinct repositories: four per language and five per family. Identities live only in the gitignored local
  manifest; the aggregate record is `benchmarks/measurements/2026-10-05-search-pilot-selection/record.json`.
  All 20 selections have unknown manifest/test-suite evidence; no matching local cache or frozen unseen-pool
  metadata was present. These are feasibility inputs, not proof of buildability or qualification.
  Both task-local independent reviews approved after a reserved-cache-symlink regression was fixed.
  Fresh requested search/AX/plane tests, module audit, independent/reserved and unseen guards, and label guards:
  287 passed, four skipped, exit 0. Skips: Chromium isolation, two localhost-socket cases, and no frozen pool.
  Ruff and changed-source mypy pass; audit: 166 load-bearing, six standalone, zero orphaned.
  No network or commits. The requested main merge could not update read-only Git metadata; HEAD and main
  had identical file trees. Live AX/Docker executor smoke and oracle probes remain unmeasured.
 - **FIRST CLUSTER DEMONSTRATION (2026-10-07) — pilot is live (6.2/6.3 in progress).** search-with-proof produced its
  first autonomous `demonstrated` finding end to end on kube-ax: pair 13 (hanxi/xiaomusic, path, prefix-check-bypass
  class), vulnerable side `demonstrated` (3/3 affected, 0/3 safe, $0.37), fixed side blind negative `inconclusive`
  with 0 false proofs ($0.56); pair total $1.22, image e2c8b460. Record:
  `benchmarks/measurements/2026-10-07-search-first-cluster-demonstration/`. This closes the handoff's open question.
  The infra probe (3.2) passed earlier; the pilot (6.x) has run many times. Enabling fix chain, each merged + paid-run
  validated: (1) parity (name the observable to the agent), (2) verify-time-only (observable injected at verify time,
  absent in exploration — ends the explore reachability trap), (3) fair-share pilot budget (no starvation across
  searches), (4) served-root guidance (demo MUST serve `${served_root}`), (5) oracle prefix-bypass coverage (sibling
  canary for `startswith`-without-separator path traversal), (6) control-signal feedback (served-root hint so the
  agent self-corrects wiring). Plus the keystone (positive control → `could_not_run`, never a silent clean-looking
  `inconclusive`). NEXT: fan out the path family to ≥5 demonstrations / 0 false proofs (6.2 exit), then the
  ≥73-negative BLOCK qualification (6.3). glance (classic traversal) also demonstrates once its npm `filed`→`mime@4`
  build-break is pinned.
@@ -0,0 +1,52 @@
 # Search-with-proof: where each stage runs (verification architecture)
 Recorded 2026-10-07. search-with-proof has two stages across a trust boundary: a Cairn-inspired
 directed state-space **search**, then a DAST-style **proof (verification)**.
 ## The two stages
 1. **Search (Cairn-inspired).** A blackboard of facts, intents and hints. A reasoner proposes
   independent, non-overlapping intents; tool-using explorers each confirm one fact against the
   code. The goal is a declarative demo (a candidate PoC), never proof by itself.
 2. **Proof (DAST verification).** The verifier builds and starts the app, drives the demo's steps
   through the app's real interface, and watches a verifier-owned canary for a **differential**
   between the vulnerable and fixed revisions: the owned effect appears on the vulnerable side and
   not on the fixed side (3/3 vs 0/3). Only this differential earns `demonstrated`.
 ## Trust boundary — what runs where
 The brain runs on the VM; the agent's tool executions and the DAST proof run as isolated tasks in
 the kube-ax cluster. Secrets never enter the cluster.
 | Component | Location | Notes |
 |-----------|----------|-------|
 | Coordinator, board, budgets | VM (host) | Orchestrates the search; owns the global budget. |
 | Reasoner + explorer **model calls** | VM (host) | The model key lives only on the VM. This is the brain. |
 | Explorer **tool runs** (`list_files`, `read_file`, `grep`, `run`, build) | kube-ax AX Task (gVisor) | Carry no secrets; inputs/results via presigned object links. |
 | **DAST proof / verification** | kube-ax AX Task (gVisor) | Builds, starts, attacks and observes the app. One task per revision. |
 - **gVisor is the isolation boundary.** The proof runs untrusted exploit code against a running
  app, so it is sandboxed per-task in the cluster.
 - **Secrets stay on the VM.** Executor and verifier tasks carry no credentials; they exchange
  checkout archives, demos and results through presigned object-store links. Per-host egress is
  restricted (verify tasks reach the files host only).
 ## Verification lanes (the `--verify-lane` choice)
 - **`ax` (default for paid pilot runs):** verification runs **inside kube-ax** as gVisor AX Tasks,
  one per side. This is how every paid pilot run this session executed the proof.
 - **`vm` (local):** verification runs in **Bubblewrap on the host**, no cluster. Used for the
  zero-cost ceiling proofs (a hand-authored demo verified locally with no model and no cluster),
  which is how glance and xiaomusic were confirmed demonstrable before any spend.
 - **`docker` (replay):** `benchmarks.search.demo_replay` runs a stored demo with no model calls in
  a local Docker lane.
 ## Why the proof is dynamic, not abstract interpretation
 Abstract interpretation (the static engine and the decision model) is the cheap, generalizable
 **triage/ranker**: it selects and orders candidate regions across any repo without executing. It
 plateaued as a **blocking** gate because it could not prove the required precision. search-with-proof
 is the **dynamic** confirmation: a demonstrated finding is ground truth by execution, so it earns a
 block without calibration. The per-app harness cost (building and running the app, wiring its served
 directory or database to the oracle fixture) is the price of the dynamic proof and is why proof pays
 off where a runnable harness exists, with abstract interpretation remaining the static backbone.
@@ -0,0 +1,518 @@
 # Design Document
 ## Overview
 This spec builds the instrument for roadmap G0: a frozen pool of repositories that no development step has seen,
 and a push-level score on it. The score is what a user of the hook sees. On a vulnerability-introducing push, did
 the hook say so (catch rate)? On an ordinary push, did it say anything (false-alarm rate)? Replays run as AX Tasks
 on kube-ax. kind and the VM run the same tasks as fallbacks.
 Four facts from the code shape the design:
 - **Populations already have a freeze-and-guard pattern.** `benchmarks/independent/freeze.py` verifies cases by
  reading git only, `evaluate.py` scores with fixed rules and Wilson intervals, and
  `tests/test_independent_population.py` fails when a reserved repository is named anywhere in `benchmarks/`,
  `src/` or `tests/` outside its directory. Harvest batch 3 used that guard as a black box: candidates written,
  guard run with output discarded, subsets bisected on red. That is how v3 stays unread.
 - **The hook can already replay a change.** `ousast pre-push PATH --base B --head H --artifact F` resolves two
  local commits (`snapshot.py`, `resolve_replay`: no fetch, no merge-base), runs quick rules and the engine inside
  one deadline (default 30 s, engine inline) and writes a JSON artifact. The terminal text has one `Skipped:` line
  per skipped check. The artifact holds three finding streams: admitted defects, advisory engine findings
  (new or worsened, vetoed only by capability) and quick-rule matches with their CWE.
 - **The AX pattern works but lives in one script.** `engine_trace_ax.py` (manifest, egress checks, presigned
  objects, retry once under a new name, cleanup) and the lane scheduler in `engine_trace.py` (`run_plan`: fixed
  lanes, fallback queue, `progress.json`, `STOP`, resume by input digest) are engine-specific.
 - **Placement on kube-ax is random.** One worker per node, shared by all actors. Two heavy tasks fit per worker,
  but only two concurrent tasks in all guarantee at most two on one worker.
 ### Goals
 - A pool frozen by code against every used source (Req 1), with two kinds of change per repository (Req 2).
 - A scorer whose numbers mean what the hook shows, with silent zeros visible (Req 3).
 - One replay is one AX Task via a dispatcher shared with the engine (Req 4); a baseline and fresh slices (Req 5).
 ### Non-Goals
 Detection changes, population v3, model calls in the cluster, languages the hook does not analyse.
 ## Architecture
 ```mermaid
 flowchart LR
    M[pool manifest slice] --> D[batch dispatcher on VM]
    D --> P[presign spec GET and record PUT]
    P --> T[AX Task ousast-engine-replay]
    T --> G[shallow fetch base and head from GitHub]
    G --> H[ousast pre-push --base --head]
    H --> R[record tar: artifact, text, instrument]
    R --> S[(store via presigned PUT)]
    D -->|sandbox died twice or OOM| V[VM docker lane]
    D -->|cluster down| K[kind lane, same tasks]
    V --> S
    K --> S
    S --> C[scorer: catch, false alarm, coverage]
    S --> A[model arms on VM, budgeted]
    A --> C
    C --> O[record: counts and digests]
 ```
 ## Components and Interfaces
 ### 1. Pool sourcing and eligibility (Req 1)
 **Decision 1.1: sources and ecosystems.** Candidates come from GitHub reviewed advisories (`gh api /advisories`,
 the enumeration harvest-3 used) for pip, npm, maven and composer, published 2019 or later, whose CWE maps to one of
 the seven families through the project's family CWE table. Each needs a linked fix commit with one parent in one
 repository. OSV records for the same advisory give the first affected version. That version is a cross-check for
 the introducing commit (section 2). Reason: these four ecosystems are the five languages the hook analyses
 (Python, JavaScript, TypeScript, PHP, Java). GHSA links commits and CWEs; OSV adds version brackets. Rejected:
 drawing from every ecosystem (Go, Ruby, C#). That would mostly measure missing frontends, which is already known.
 Coverage still reports uncovered files inside the drawn repositories. Rejected: NVD and published fix datasets.
 NVD links commits weakly, and the datasets are mined corpora that development or model training has likely seen.
 **Decision 1.2: eligibility by code against every used source.** `benchmarks/unseen/eligibility.py` builds the
 used set before the draw. It never prints names; it records counts per source and a digest of the set.
 | Source (Req 1.1) | Where it is read |
 | --- | --- |
 | Pair corpora | every catalog, recipe and dataset file under `benchmarks/pairs/`, plus the local pointer-pair manifests |
 | Populations v1, v2 | `population-v1.toml`, `population-v2.toml`, read directly |
 | Population v3 | never opened; the existing guard test only (below) |
 | Harvest records | the batch catalogs under `benchmarks/pairs/advisory-fixes*` (the records hold counts only) |
 | Memory examples | `example` rows of the local FileStore and the S3 store (`repo` field) |
 | Experiment units | `plane/experiments/*.units.jsonl` and registered units files |
 | Measurement records | everything under `benchmarks/measurements/` and `benchmarks/experiments/` |
 | Anything else | a text sweep for `github.com/<owner>/<name>` over `benchmarks/`, `src/`, `tests/`, `plane/`, `.kiro/` |
 Names are normalised (lower case, no `.git`, no trailing slash). Each candidate is resolved through the GitHub API
 to its canonical `full_name`, its former names (redirects) and its fork network (`parent`, `source`). A candidate
 is out if any of these is in the used set. A fork shares code with what it was forked from.
 v3 is checked like harvest-3 did. The draft manifest is written into `benchmarks/unseen/`. Then
 `pytest -q tests/test_independent_population.py -k referenced` runs with its output discarded. The guard already
 sweeps `benchmarks/` outside the population directory. On red, the candidate list is bisected by rewriting the
 draft until green, and the dropped count is recorded. No v3 name is ever printed or read by a person.
 **Decision 1.3: post-cutoff preference.** An advisory published after 2026-06-01 (harvest-3's cutoff for the
 decision engine's model) is flagged `post_cutoff`. Within each ecosystem stratum post-cutoff advisories are drawn
 first. Results are reported for both groups. Reason: a post-cutoff advisory cannot be in the model's training
 data as a known vulnerability. Rejected: post-cutoff only. Harvest-3 kept 12 post-cutoff pairs out of 251, and
 three slices of 100 repositories cannot be filled from that window.
 **Decision 1.4: licences.** The licence is read at the pinned head commit (LICENSE file, then the API's SPDX id).
 Only permissive licences are published by name: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD, Unlicense,
 Zlib, PostgreSQL, BSL-1.0. Everything else (copyleft, source-available, none) goes to the gitignored
 `benchmarks/unseen/private/pool-p1.toml`. The committed manifest then holds an opaque id and the sha256 of
 (URL, commits) for that entry, so the freeze digest still covers it. Reason: Req 1.4 read literally. Rejected:
 "OSI-approved" as the bar, as population v2 used. It is wider than the requirement says (open question 1,
 resolved 2026-10-04: copyleft stays private).
 Also required: anonymous HTTPS, at most 500 MB, at least 40 eligible ordinary commits, one per fork network.
 ### 2. Change extraction (Req 2.1, 2.2)
 Extraction runs on the VM over a full `--filter=blob:none` clone in a scratch cache. It uses git only, like
 `freeze.py`. No scanner, engine or model touches a pool repository before the freeze.
 **Decision 2.1: the vulnerability-introducing range.** Let F be the fix and P its parent. The vulnerable lines are
 the old-side lines of F's hunks in the vulnerable function. For a pure-addition fix (an absence bug such as a
 missing guard), they are the vulnerable function's own lines.
 1. **`introducing` (preferred).** `git blame -w -M -C --porcelain P -L <lines> -- <file>`. The candidate V is the
   commit that last wrote the sink line (for absence bugs, the function's declaration). V is accepted if all hold:
   at V's first parent the sink line's normalised text is absent from the file's vulnerable function; V is not a
   merge or root commit; V changes at most 50 files and 2,000 lines; when OSV names a first affected version, V is
   reachable from that tag and not from the previous release tag. If the text is present at V's parent, blame
   walks back from there, at most five steps. The replay is `base = V^`, `head = V`.
 2. **`last_touch` (fallback).** When no V passes, `git log -L :<function>:<file> P` gives the newest commit L
   before F that changed the vulnerable function. The replay is `base = L^`, `head = P`. The vulnerable code is in
   head, and the range contains a change to the vulnerable function.
 Each change records its method, family, vulnerable function (resolved in head), head-side changed lines,
 `post_cutoff` and the advisory id.
 Bias of each, stated in the record. `introducing` inherits SZZ noise: blame finds the last writer, not the author
 of the flaw. A refactor, a move the heuristics miss or a reformat can stand in for the real introduction. The
 absence check, the walk-back and the version bracket cut this down, but do not remove it. The bias runs both
 ways: a wrong V may introduce nothing (a miss is not the hook's fault) or may move a flaw (the delta-based hook is
 right to call it existing). `last_touch` is pessimistic for a delta hook. The flaw is often already in base, so
 the hook's novelty rule correctly stays quiet and the change counts as a miss. Catch is therefore reported per
 method. The headline is `introducing`; `last_touch` is a lower bound. Rejected: fix-parent against a fixed old
 base (for example 50 commits back). The range often misses the vulnerable function entirely and grows without
 bound on busy repositories.
 Label check: every third `introducing` change is read by an agent before the freeze, with no model call, as
 harvest-3 reviewed diffs. It is marked `confirmed`, `refactor` or `unclear`. The confirmed share is the label
 noise estimate. The scorer also reports catch on the confirmed subset.
 **Decision 2.2: ordinary commits.** The candidates are non-merge commits on the first-parent line of the default
 branch that change at least one source file of an analysed language. Excluded:
 - explicit security signals in the message: `secur|cve|ghsa|vuln|inject|xss|csrf|ssrf|exploit|sanitiz|escap`;
 - reverts (`^Revert`, `This reverts commit`);
 - dependency bumps (bot authors such as dependabot and renovate, `bump|upgrade .* from`, or only manifest and lock
  files changed);
 - commits whose source changes are all generated or vendored (`vendor/`, `node_modules/`, `dist/`, `*.min.js`,
  lock files, `linguist-generated` in `.gitattributes`, "generated" headers);
 - any fix commit of any advisory of the repository, and any commit touching a known vulnerable function of it;
 - commits over 1,000 changed source lines (counted, reported).
 Twelve are drawn per repository with a seeded random draw. Strata are three time thirds of the repository's
 history crossed with four size buckets of changed source lines (1-10, 11-50, 51-200, 201-1,000). Allocation is
 proportional to the repository's own commits per cell, with at least one per time third. Each change records base
 (its first parent), head, changed files and line ranges. Reason: proportional allocation keeps the false-alarm
 rate a per-push rate as a user meets it. Rejected: `freeze.py`'s broad `SECURITY_WORDS`. It also drops commits
 saying "query", "token", "session" or "valid", which removes the ordinary commits where false alarms are most
 likely, and the rate would look better than it is. Rejected: docs-only commits. They are trivially quiet and
 would dilute the rate.
 Label noise: an ordinary commit may itself introduce an unknown vulnerability, so a flag counted as a false alarm
 may be true. The false-alarm rate stays as Req 3.2 defines it. Flagged ordinary changes are adjudicated beside it
 (all if 30 or fewer, else every third) against protocol-v2's standard, and the adjudicated share is reported.
 ### 3. Sizing and slices (Req 2.3, 5.2)
 Wilson 95% interval, z = 1.96: centre (p + z²/2n)/(1 + z²/n), half width z·sqrt(p(1-p)/n + z²/4n²)/(1 + z²/n).
 Taking the larger distance from p as the width, the smallest n that meets the bar, computed exactly:
 | Rate | Assumed p | Bar | n needed |
 | --- | --- | --- | --- |
 | false alarm | 0.05 | +/- 3 points | 315 |
 | false alarm | 0.10 | +/- 3 points | 483 |
 | false alarm | 0.20 | +/- 3 points | 756 |
 | catch | 0.10 | +/- 10 points | 62 |
 | catch | 0.25 | +/- 10 points | 88 |
 | catch | 0.40 | +/- 10 points | 97 |
 Catch: 100 vulnerability-introducing changes per slice, one per repository. At p = 0.4, Wilson gives
 [0.309, 0.498], within 10 points. One per repository keeps them independent.
 False alarm: ordinary changes of one repository are correlated (noisy code flags often). Wilson assumes
 independence, so the count is inflated by a design effect 1 + (m - 1)·ICC. With m = 12 per repository and an
 assumed ICC of 0.05, that is 1.55. 100 repositories × 12 = 1,200 changes, effective n 774 ≥ 756. The plain Wilson
 interval at p = 0.2, n = 1,200 is about +/- 2.3 points. A repository-cluster bootstrap interval is reported beside
 it, and the ICC measured on slice 1 is recorded. If it exceeds 0.05, the next pool sizes up. A frozen slice is
 never changed.
 **Decision 3.1: slices.** Pool p1 has three slices of 100 repositories each (100 + 1,200 changes per slice; 300
 repositories and 3,900 changes in all). Repositories are assigned by a seeded shuffle, stratified by ecosystem and
 `post_cutoff`. Slice 1 serves the baseline and the G1 arms table. Slices 2 and 3 serve the first two adoption
 decisions. When they are spent, pool p2 is drawn by the same code, and it excludes p1. Reason: each slice alone
 meets the Req 2.3 widths, so any decision can stand on one slice. Rejected: one large pool scored whole. Every
 decision would then see every repository, which Req 5.2 forbids. Rejected: ten small slices. None would meet the
 widths. Per family, 100 changes split over seven families give intervals of about +/- 20 to 25 points. They are
 reported, not sized (open question 3).
 Use ledger: `benchmarks/unseen/usage-p1.jsonl` is append-only, one row per use (slice, decision or experiment id,
 date, result digest). A slice with a row whose purpose is `informed` cannot appear again as `qualifies` for that
 change. A test checks this.
 ### 4. Scoring rules (Req 3.1, 3.2, 3.3)
 Each replay uses the hook's defaults: `--deadline 30`, `--engine inline`, `--max-regions 500`, `--mode advisory`.
 That is what a user's push gets. The text output is kept with every `Skipped:` line, and so is the artifact.
 **Decision 4.0: a registered long-deadline arm** (maintainer decision 2026-10-04, open question 5). Beside the
 default replay, slice 1 is replayed once more with `--deadline 300` and every other flag unchanged. The arm is
 registered (manifest committed, `unseen: {pool: p1, slice: 1}`) before its first replay. G1 then reports both
 what the user sees (30 s) and what the engine could catch given time (300 s), so a miss caused by the deadline is
 told apart from a miss by the engine. It is a measurement arm, not a proposed default: adopting a longer hook
 deadline would be a separate decision under 7.2.
 **Decision 4.0a: calibrated cluster deadline and native check** (maintainer, 2026-10-05).
 The gVisor proof exhausted 30 seconds in snapshot preparation on a 1,725-file repository.
 Cluster replays therefore scale the 30/300-second arms by the median paired cluster/native
 time through the quick tier, rounded to integer seconds. Native runc replays retain 30/300 seconds.
 A deterministic sample (default 20, or all of a smaller proof manifest) runs both lanes at
 600 seconds for calibration. Report per-change stage times and median slowdown with bootstrap
 95% intervals for time through quick, engine build and engine queries separately. Incomplete
 timings or degraded scans invalidate calibration. Records contain counts, times and opaque digests.
 A deterministic native sample accompanies the cluster slice. Compare whether each push flags
 anything, with a Wilson 95% interval. If its lower bound is below 95%, or any sample pair is
 missing/failed, flag the run and exclude cluster results from the baseline. Disagreements name
 change IDs only. The scorer reports applied deadlines and factors. Docker pulls explicitly after
 checking its data-root free space against an unpacked image size upper bound plus 1 GiB; failures
 retain sanitized stderr tails and exit codes. See the unseen README for coordinator commands.
 **Decision 4.1: catch, per family.** A finding counts if its family is the change's family. Engine streams carry a
 family; a quick-rule match maps its CWE through the family CWE table. Its head location must also be in the
 vulnerable function or within 10 lines of the change's head-side hunks (protocol v1's window).
 | Family | Location rule |
 | --- | --- |
 | injection, path, deserialization, output_encoding, untrusted_destination | sink line in the vulnerable function, or the changed lines +/- 10 |
 | access_control | the vulnerable function itself (the handler that lacks the check), or the changed lines +/- 10 |
 | config_secrets | the changed file and lines +/- 10 (file scope; function `<global>`) |
 All three streams count: admitted defects, advisory engine findings and quick-rule matches. Each catch also names
 the stream that made it. Reason: the hook shows all three to the user. Rejected: admitted defects only. That
 scores the blocking path, which G3 decides separately, and would hide what users read.
 **Decision 4.2: false alarm.** An ordinary change is a false alarm when any of the three streams holds at least one
 finding, of any family, anywhere. The alerts-only rate (admitted defects) is reported beside it.
 **Decision 4.3: coverage, so zeros cannot hide.** Every change gets exactly one state:
 - `instrument_failure`: no record, a failed fetch, the head commit not verified, or zero bytes of the changed files
  read. It is re-run once, then reported. It never counts as quiet or missed.
 - `unanalysable`: no changed file is in a language the hook covers (the hook's `language_not_covered` notice).
 - `quick_only`: the quick tier read the changed files, but no engine question completed on them.
 - `engine_covered`: at least one engine question completed on a changed file.
 The task entry proves its input as AGENTS.md requires. It records files and bytes in the checkout, bytes of each
 changed file, the JVM's wall time and the hook's exit code. A replay faster than a JVM can start is flagged
 `suspect_fast` and goes to the failure path. Catch and false alarm are reported over all changes and over each
 coverage state.
 ### 5. The AX workload (Req 4)
 **Decision 5.1: the image.** `plane/Dockerfile.engine-task` gains a second stage, `FROM engine AS replay`, built
 with `--target replay` and pinned by digest. It adds `git`, the package with its runtime dependencies and
 `benchmarks/unseen/replay_entry.py`. Joern, php-cli, Java 21 and the frontend-retention patch come from the engine
 stage, so both lanes run the same Joern. The import smoke runs `ousast pre-push --help`. The root image stays
 `ghcr.io/norandom/ax-task-runner:v0.3.1`. Rejected: a separate Dockerfile. It would duplicate the Joern install,
 and two Joern copies are two instruments that drift. Rejected: one stage for both. The engine image's isolated
 venv without yaml and boto3 is proven, and replay dependencies would change its digest on every bump.
 **Decision 5.2: the task entry.** `replay_entry.py` is standard library only, like `engine_task_entry.py`, and
 reuses its `transfer` (egress readiness wait, three attempts, no URL text in errors).
 1. GET `SPEC_URL` (presigned, `.json`): repository URL, base, head, change id, hook flags.
 2. `git init`, then `git fetch --depth 1 origin <head>` and `git fetch --depth 1 origin <base>` over HTTPS
   (GitHub serves commits by SHA). Verify both with `git cat-file -e`. The fetch is bounded at 180 s; the 500 MB
   repository cap bounds its size.
 3. Run `ousast pre-push <checkout> --base <base> --head <head> --artifact /tmp/out/push.json` with defaults, the
   backend heap at 1700 MB and the cluster JVM flags of `engine_trace_worker.py`. Capture stdout.
 4. Pack `push.json`, `push.txt`, `engine.json` (the head and base scan records and witness rows from the artifact,
   keyed by repository and revision, for engine-evidence arms) and `instrument.json` (section 4.3, image digest,
   step timings). PUT to `RESULT_URL` as `.dat`. The PUT is completion.
 On any error it PUTs a failure record naming the step and HTTP status, as the engine entry does. Task names are
 `ousast-engine-replay-<slug>-<digest>`, the prefix the operator's egress watcher matches. No key or store
 credential enters the manifest. Only the two presigned URLs do, and the spec object keeps repository names out of
 AX status and cluster telemetry.
 **Decision 5.3: the generic dispatcher.** `benchmarks/ax/batch.py` takes over from `engine_trace_ax.AX` and
 `engine_trace.run_plan`:
 - `Item`: id, input objects (name to bytes), the result object name, command, extra env, input digest.
 - `Workload`: image digest, allowed URL env names, deadline, how to validate a received result.
 - Lanes: `ax` (manifest, apply, poll the result object and AX phase, delete, clean objects), `kind` (the same
  manifest against the kind AX), `docker` (the VM image, one container at a time).
 - Scheduler: two AX lanes plus one VM lane by default. A sandbox death is retried once under a new name; a second
  death or a JVM OOM goes to the VM fallback queue, which beats overflow on the VM lane. `progress.json` is written
  only by the scheduler. A `STOP` file halts new launches. Resume skips items whose stored record has the same
  input digest. Cleanup failure stops dispatching.
 The engine pass becomes a workload over it, with the same tests. Reason: the egress, secrecy and cleanup logic took
 several fixes and must exist once. Rejected: a replay-specific copy of `engine_trace_ax.py`. Rejected: putting it in
 `src/` now. G4's `ousast plane scan` may need it there, and it moves when G4 is planned.
 Concurrency is two AX tasks. Placement is random, and only two guarantees two per worker at most. Four would need
 the operator to add placement (open question 2, resolved 2026-10-04: stays at two, no placement change
 requested). Estimated wall time per slice: about 75 s per replay (fetch, 30 s hook, setup), 1,300 replays over
 three lanes, about 9 hours. The long-deadline arm (4.0) is bounded at about 345 s per replay; at that bound 1,300
 replays over three lanes take about 42 hours, less where the hook finishes early. It runs with `STOP` and resume
 across sessions.
 **Decision 5.4: model arms on the VM.** Arms that need DeepSeek (the decision engine, the combiner) read the stored
 records on the VM. They build candidates from the head side's changed functions, score them, and take the change
 score as the maximum. Each runs under its experiment manifest's `budget_usd` through the metered client, dry run
 first, with responses cached. Nothing in the cluster calls a model.
 **kind (Req 4.5)** runs the identical manifest and image through the `kind` lane. Every new task is proven there
 before kube-ax, as `plane-on-kubernetes` requires.
 ### 6. Records and the guard (Req 1.2, 1.3, 5.1)
 `benchmarks/unseen/` holds `pool-p1.toml` (repositories, licences, slices, changes with base, head, method,
 family, function, lines), `freeze-p1.json` (used-set digests and counts per source, guard result, label-check
 counts, freeze digest = sha256 of the canonical manifest), `protocol-p1.md` (the scoring rules of section 4,
 committed before the first replay) and `usage-p1.jsonl`. The `private/` directory is gitignored.
 The guard grows by one parametrised reservation. The existing sweep becomes a list of (reservation directory,
 names): `benchmarks/independent/` for populations and `benchmarks/unseen/` for pools, including the private
 manifest when present. It also sweeps `plane/`. A second test asserts that pool and population names are disjoint,
 and prints only a count on failure. A third asserts that a frozen pool's digest matches `freeze-p1.json`, so the
 pool is never edited. Raw per-change records stay outside the repository (`~/ousast-results/unseen/` and the
 store). Committed result records under `benchmarks/measurements/` carry counts, rates, intervals and digests,
 never names.
 ### 7. Metrics and reporting (Req 3.3, 3.4, 5.3)
 `benchmarks/unseen/score.py` reports per family and overall: catch and false-alarm rate with Wilson 95%
 intervals, the cluster bootstrap interval for false alarms, coverage counts per state, catch per method,
 post-cutoff and per stream, and the alerts-only rate.
 **Decision 7.1: arms at fixed budgets.** An arm with a score is thresholded per budget (1%, 5%, 10%). The
 threshold is the lowest score whose false-alarm rate on the slice's ordinary changes stays within the budget.
 Catch at that threshold is reported with its Wilson interval and the realised false-alarm rate. That in-slice
 threshold is labelled exploratory. For a qualification, the threshold is fixed beforehand on an earlier slice or
 on held-out folds, and it is applied unchanged. A binary arm (today's hook) has one operating point, reported with
 the budgets it meets. Rejected: AUC over changes (it averages operating points no user runs).
 **Decision 7.2: next to held-out folds.** Experiment manifests registered after this spec lands carry
 `unseen: {pool, slice}`. `analyse` writes an `unseen` block into `result.json` next to the fold estimates: catch at
 each budget for each arm, and the paired difference B - A with an exact McNemar test on the 100 changes. The
 fold rule decides as today. The slice is recorded in the usage ledger.
 **Decision 7.3: adoption gate on the unseen slice** (amended 2026-10-04, maintainer decision; Req 5.4; open
 question 4 resolved). Reporting is not enough. An arm B is adopted over the production arm A only if, on the
 untouched slice that qualifies it, both hold:
 - catch at the 5% budget, with B's threshold fixed beforehand (7.1), is not significantly lower than A's: exact
  two-sided McNemar on the paired vulnerability-introducing changes, alpha 0.05;
 - for an arm with one operating point (a binary arm such as a hook setting), its false-alarm rate is not
  significantly higher than A's: exact two-sided McNemar on the paired ordinary changes, alpha 0.05, with the
  repository-cluster bootstrap interval of the difference reported beside it, since those changes are clustered.
 `analyse` writes `unseen.gate: pass | regression | not_run` into `result.json`. `not_run` (no slice, slice
 already `informed` for this change, or more than 5% `instrument_failure`) blocks adoption like `regression`. The
 fold rule and this gate must both pass.
 ### 8. Increments
 1. **Used set and guard.** `eligibility.py`, the extended guard and the usage-ledger test. Exit: guard green on an
   empty pool; a planted used repository, a renamed one and a fork are each rejected in tests.
 2. **Sourcing and extraction.** Candidates, both change kinds and the label check, on the VM. Exit: a draft for 300
   repositories with method counts, the confirmed share and exclusion counts.
 3. **Freeze p1.** Guard bisection for v3, then manifest, freeze record and protocol committed. Exit: freeze digest
   committed and guard green.
 4. **Dispatcher.** `benchmarks/ax/batch.py`, with the engine pass moved onto it. Exit: existing tests green and a
   two-pin engine smoke on kube-ax matching its stored records.
 5. **Replay task.** Image stage and entry, proven on kind, then kube-ax on five changes from this repository's own
   history (never pool changes). Exit: instrument fields show bytes read and realistic JVM time, and quick-tier
   output matches the VM lane.
 6. **Scorer.** `score.py` on synthetic records, including every coverage state and an instrument failure. Exit:
   unit tests green.
 7. **Baseline.** Today's hook, from a frozen export of HEAD, on slice 1 (1,300 replays). Exit: the record committed
   (counts and digests only) and a `baseline` row in the usage ledger. That is G0's exit.
 8. **Arms on slice 1 (G1)** (added 2026-10-04 with decisions 4.0 and 7.3). The registered long-deadline arm,
   the engine-evidence arm from the stored records, the model arms on the VM (5.4) under their budgets, and the
   `unseen` block with the adoption gate in `analyse`. Exit: one committed table of arms on slice 1 at the 1/5/10%
   budgets (counts, rates, intervals, digests), and `exploratory` rows in the usage ledger.
 ## Error Handling
 A failed fetch, a missing commit or a hook crash gives a failure record, never an empty success. A dead sandbox is
 retried once, then the VM runs it. A store or AX cleanup error stops the dispatcher. A slice with more than 5%
 `instrument_failure` after re-runs is not scored; the cause is fixed first.
 ## Testing Strategy
 Unit tests: used-set normalisation (case, `.git`, renames, forks), blame acceptance on a synthetic repository,
 ordinary-commit exclusions, Wilson values against section 3, budget thresholds, coverage states, the task manifest
 and dispatcher resume and fallback with a fake lane. Guard tests run in CI; cluster runs stay manual.
 ## Requirement Traceability
 | Requirement | Design |
 | --- | --- |
 | 1.1 eligibility against every source, v3 via the guard | 1.2 |
 | 1.2 frozen manifest, never edited | 6, increment 3 |
 | 1.3 pool directory, guard extended | 6 |
 | 1.4 licences, private manifest | 1.4 |
 | 2.1 introducing changes, family, function, post-cutoff | 1.1, 1.3, 2.1 |
 | 2.2 ordinary changes across time and size | 2.2 |
 | 2.3 sizes for interval widths | 3 |
 | 3.1 default replay, skipped checks kept | 4, 5.2 |
 | 3.2 catch and false-alarm rules | 4.1, 4.2 |
 | 3.3 per family, Wilson, coverage | 4.3, 7 |
 | 3.4 arms at 1/5/10% budgets | 4.0, 7.1, increment 8 |
 | 4.1 one change one Task, prefix, image by digest | 5.1, 5.2 |
 | 4.2 HTTPS fetch, presigned record, no keys | 5.2 |
 | 4.3 generic dispatcher, concurrency, retry, fallback, resume | 5.3 |
 | 4.4 model arms on the VM within budgets | 5.4 |
 | 4.5 kind runs the same tasks | 5.3, 5 (kind paragraph) |
 | 5.1 baseline on slice 1, counts and digests | 6, increment 7 |
 | 5.2 fresh slice per decision | 3.1, usage ledger |
 | 5.3 experiments report unseen next to folds | 7.2 |
 | 5.4 adoption needs no significant unseen regression | 7.3 |
 ## Amendments (2026-10-11)
 Folded in after the G0 pool was frozen; the original sections above stay as the design of record, these refine it
 where reality differed.
 - **Persistence is bucket-first, not local disk.** The draw streams every stage to the `ousast-corpus` RustFS
  bucket and resumes from it, so a restart (even after a code change) is cheap. Layout: `unseen/<seed>/decisions/`
  (accept/reject per repo, key `sha256(repo+fix)`, idempotent), `unseen/<seed>/resolved/` (per-advisory
  resolution), `unseen/<seed>/advisories/list.json`, `unseen/repos/` (get_repo cache, **not** seed-scoped, shared
  across seeds), and `unseen/<seed>/pool/` (the frozen pool + provenance — the "don't redo sourcing" archive). The
  local journal is a within-process cursor only. Implementation: `benchmarks/unseen/bank.py` (`CorpusBank`). The
  VM's local disk is the scarce resource; run artifacts and replay outputs belong on RustFS (see steering
  `storage-streaming.md`). Credentials: `.env` `CORPUS_S3_*`; boto3 needs path-style + SigV4.
 - **Harvest cost is GitHub-rate-limit bound, measured yield ~2.2%.** Through the strict change criteria (1 vuln +
  12 stratified ordinary, >=40 eligible commits) ~2.2% of candidates are accepted, so "100 repos" is ~4,500
  candidate attempts at ~4 GitHub calls each — the bottleneck is the 5,000/hr API limit, not CPU or cores. Pure
  GitHub-API harvesting cannot replace the clone: the positive is the SZZ introducing commit and the negatives are
  stratified over full history, both needing repo history. The convergence fix was a full-objects clone (dropping
  `--filter=blob:none`, which caused ~600 per-blob lazy fetches) plus the bucket caches above.
 - **Record 07 is a machine-label baseline.** The pool's 100 vulnerability labels are SZZ-derived and unchecked
  (`freeze-p1.json` `label_check_counts`: 100 unchecked). The G0 baseline is reported as a machine-label number
  with that caveat; a human label pass is a later quality refinement, required before any published precision
  claim, not before record 07.
 - **Replay image provenance is pinned.** CI `engine-image.yml` builds `ghcr.io/norandom/ousast-replay-task` (the
  replay harness, which `COPY`s `/app/benchmarks/unseen/replay_entry.py`) and `ousast-engine-task` (the Joern
  hook), publicly pullable by digest. `ousast-runner` (the 248 MB ax-task-runner, no `/app/benchmarks`, no Joern)
  is **not** the replay image. The AX lane's store check (`benchmarks/ax/batch.py`) requires a public-HTTPS DNS
  presign-capable endpoint; how that and the cluster's store access are provided is operator-owned infra, not
  assumed here.
 - **AX lane blocker (2026-10-11) — kube is the target lane, so this is tracked, not dismissed.** The replay
  *dispatches* correctly but tasks do not *complete*: `pins_done` stayed 0 for both the 5-change proof and the
  1,300-change slice 1. Sub-issues resolved along the way: (a) the replay image is `ousast-replay-task` (public);
  (b) the ax CLI must be `~/go/bin/ax` — the `~/.local/ax-v0.3.1/ax` build calls an `UpdateTask` RPC the deployed
  ax-server answers `Unimplemented` (client/server version mismatch); (c) the store endpoint
  `files.because-security.com` / `sast-memory` passes the egress check. **Remaining blocker (AX/cluster-internal,
  operator-owned):** dispatched tasks reach the `ousast-pool` workers and the replay actors execute and checkpoint,
  but the result never returns to the coordinator and no completion is recorded. `ousast-pool` logs show a gVisor
  cleanup failure: `runsc delete ... connecting to control server at PID NNN: connection refused` and `failed to
  terminate workload after checkpoint ... runsc delete: exit status 128`. Until the completion / checkpoint-cleanup
  path is fixed, the ax lane cannot produce results; the G0 baseline (7.2) was taken on the **docker lane**
  instead. The ax lane must be restored before it is the baseline/G1 lane (the stated target).
 - **Engine coverage gap is comparison, not deadline (2026-10-11, preliminary n=1).** The cold-cache default arm
  (30s) times out the Joern CPG build → `quick_only`. But a long-deadline sample (`--arm long_deadline`, 300s) on a
  vulnerability change ran **206s with no timeout and still did not cover** (`coverage_status: incomplete`,
  `quick_only`): the reasons were `ambiguous_line_correspondence`, `unmatched_added_deleted_path_correspondence`,
  `eligibility_provenance_mismatch`, `witness_unresolved`, `comparison_unknown` — i.e. the engine could not
  correspond the replayed diff's lines between base and head. So **calibration / a longer deadline alone will not
  give engine coverage**; the blocker is the engine's base↔head comparison on real replayed diffs (consistent with
  the earlier "engine near-blind to fixes" slice-leak audit). This is G2 engine-fix territory (comparison /
  line-correspondence), not a G0 deadline knob. To confirm beyond n=1, the long-deadline arm must run at scale
  (needs the kube lane). Implication: the record-07 baseline is measured on the **quick-rule tier** (the default
  arm), and the engine arm's value is gated on fixing the comparison path, not on calibration.
 - **Line-correspondence fix made, but it is necessary-not-sufficient (2026-10-11).** Root cause confirmed in
  `src/openultrasast/push/snapshot.py`: equal-region base↔head line pairs were mapped only when the line content
  was *globally unique in the file*, so common lines (`}`, blanks, imports) tripped `ambiguous_line_correspondence`
  and the finding's anchor was discarded → `comparison_unknown` → finding suppressed. Fixed to **run-aware
  positional anchoring**: a pair maps when its content occupies exactly one contiguous equal run per side (intra-run
  duplicates are forced/safe; cross-run duplicates stay withheld — soundness preserved, `test_push_snapshot.py`
  moved-operation guard still passes). 163 push tests pass. BUT live-testing the fix (mounted over the installed
  package, 300s) on a real messy change (a 14-file Java diff) did **not** flip coverage: it stayed `incomplete`
  because the binding constraints are elsewhere — `capability_unavailable` (empty capability registry always blocks
  `coverage_status=complete` until Task 8.3), the engine produced **no actionable defect at all**
  (`actionable_defect_ids: []`, a detection gap, not correspondence), plus `eligibility_provenance_mismatch` and
  `contributor-scan ... projection_unavailable`. So "near-blind to fixes" is **multi-causal**; the correspondence
  fix removes one real cause but engine coverage on unseen diffs also needs the capability registry (Task 8.3), the
  engine's actual vuln detection, and the eligibility/projection paths. Validating the correspondence fix's benefit
  needs a change where correspondence is the sole blocker (a small single-file diff), or the engine arm at scale.
 ## Open Questions
 Maintainer decisions of 2026-10-04 resolve questions 1, 2, 4 and 5; question 3 stays open for G3.
 1. **Resolved 2026-10-04.** Licences: only permissively licensed repositories are published by name. Copyleft and
   all other licences go to the gitignored private manifest, covered in the committed manifest by an opaque id and
   a digest (Req 1.4 as written; decision 1.4). Population v2's OSI-approved bar is not used.
 2. **Resolved 2026-10-04.** Concurrency stays at two AX lanes plus the VM lane. No operator placement change is
   requested (5.3).
 3. Per-family BLOCK (G3) needs about 100 changes per family. Pool slices together, or draw a family-enriched pool
   for G3?
 4. **Resolved 2026-10-04.** An adoption requires no significant regression on the unseen slice, not only a report
   (Req 5.4, amended; decision 7.3).
 5. **Resolved 2026-10-04.** G1 adds a registered long-deadline arm (`--deadline 300`) next to the default 30 s, so
   the table shows both what the user sees and what the engine could catch (decision 4.0, increment 8).
@@ -101,3 +101,7 @@ worn out by tuning.
   slice, recorded with its freeze digest.
 3. Every learned-decision-engine experiment from now on reports its unseen-repo score from this pool next to its
   held-out-fold score.
 4. An arm is adopted only if, on the untouched slice that qualifies it, it shows no significant regression against
   the current production arm: catch at the 5% false-alarm budget not significantly lower, and for an arm with one
   operating point the false-alarm rate not significantly higher (exact paired tests, two-sided, alpha 0.05).
   Reporting the unseen score alone is not enough to adopt. *(amended 2026-10-04, maintainer decision)*
@@ -1,22 +1,22 @@
 {
  "feature_name": "unseen-repo-evaluation",
  "created_at": "2026-10-04T18:00:00Z",
-  "updated_at": "2026-10-04T18:30:00Z",
+  "updated_at": "2026-10-04T20:00:00Z",
  "language": "en",
-  "phase": "requirements-approved",
+  "phase": "implementation",
  "approvals": {
    "requirements": {
      "generated": true,
      "approved": true
    },
    "design": {
-      "generated": false,
+      "generated": true,
-      "approved": false
+      "approved": true
    },
    "tasks": {
-      "generated": false,
+      "generated": true,
-      "approved": false
+      "approved": true
    }
  },
-  "ready_for_implementation": false
+  "ready_for_implementation": true
 }
@@ -0,0 +1,402 @@
 # Implementation Plan
 One task group per increment of `design.md` section 8, in that order. A group starts only after the previous
 group's exit is recorded. Maintainer decisions of 2026-10-04 are folded in: a registered long-deadline arm
 (`--deadline 300`) beside the hook's default 30 s (design 4.0, group 8); adoption needs no significant regression
 on the unseen slice (Req 5.4 as amended, design 7.3, tasks 6.4 and 8.2); only permissively licensed repositories
 are published by name, everything else goes to the gitignored private manifest under a digest (Req 1.4, design
 1.4); concurrency stays at two AX lanes plus the VM lane (design 5.3).
 **2026-10-11 amendments folded in** (see design.md "Amendments (2026-10-11)"):
 - **Pool p1 is frozen.** `benchmarks/unseen/pool-p1.toml` = 100 repos, slice 1; `freeze-p1.json` guard=0,
  dropped=0, deterministic (manifest `6bd2fa5d`); archived to `ousast-corpus/unseen/20260601/pool/`. Groups 1-3 are
  effectively done (the draw, draft and freeze ran end to end); formal records 02/03 were not written as separate
  `record.json` files — the freeze was run directly (`bisect_guard` then `freeze`). Freeze recipe: `bisect_guard
  --root $PWD --draft $CACHE/journal/draft-p1.toml` then `freeze --root $PWD --used-report <FILE>` where the file
  is the draw report's `used_set` object (not the whole report).
 - **Persistence is bucket-first** (`ousast-corpus`, `benchmarks/unseen/bank.py`); the local journal is a
  within-process cursor only. Raw per-change replay records go to **RustFS**, not `~/ousast-results/` on local disk
  — amend tasks 5.3/7.2's `--out` accordingly.
 - **Group 5 image note:** the replay image is the CI-built `ghcr.io/norandom/ousast-replay-task` (+ engine-task),
  publicly pullable by digest — not a local export-HEAD build and not `ousast-runner`. Task 7.1's "build and push
  the replay image" is satisfied by the CI `engine-image.yml` run; use that digest.
 - **Record 07 is a machine-label baseline** (labels SZZ-derived, 100 unchecked); state the caveat in the record.
 - **Baseline lane (7.2):** run on kube (`--lane ax`). The `ax` binary and the AX-lane store endpoint are
  operator-owned infra to stand up before 7.2; do not assume the cluster/network state.
 Execution rules:
 - **Who does what.** Codex implements every coding task offline: no network, no model, no store, no cluster. The
  coordinator runs every networked step (GitHub and OSV API calls, git fetches and clones, the S3 store, image
  pushes, kind and kube-ax). Those tasks are marked **(coordinator, network)**. Steps that need the coordinator but
  no network (agent label reads, adjudication, the v3 guard bisection, commits) are marked **(coordinator)**.
  Steps that spend model money are marked **paid: needs a budget go-ahead**. Each starts only after the maintainer
  confirms a ceiling against the provider balance read just before it.
 - **Done means.** A coding task is done when its tests pass in the host suite, `ruff check`, `ruff format --check`
  and `mypy` are clean, and the reserved-repository guard is green. No test makes a network, model or cluster call.
 - **Names stay in the pool directory.** Pool repository names and URLs appear only under `benchmarks/unseen/`
  (copyleft and other non-permissive ones only under the gitignored `benchmarks/unseen/private/`). Raw per-change
  records live in `~/ousast-results/unseen/` and the store, never in the repository.
 - **Population v3 is never opened.** It is checked only through the guard test, run as a black box with its
  output discarded.
 - **Every group ends with a measured exit** and a record at
  `benchmarks/measurements/<date>-unseen-NN-<slug>/record.json`: commit, image digests where used, the instrument
  checks (bytes read, JVM time, exit codes), counts and digests. No repository names. The guard sweeps these
  records.
 - **Instrument first** (AGENTS.md). A zero, an empty draft or a fast run is treated as an instrument failure until
  bytes read and wall time prove otherwise.
 - [x] 1. Used set and guard (design 1.2, 6; increment 1)
 - [x] 1.1 Used-set builder
  - `benchmarks/unseen/eligibility.py`: normalises names (lower case, no `.git`, no trailing slash) and builds the
    used set from every source of design table 1.2: pair catalogs, recipes and datasets under `benchmarks/pairs/`
    plus the local pointer-pair manifests as `benchmarks/pairs/catalog_gen.py` reads them; `population-v1.toml`
    and `population-v2.toml`; the advisory-fix batch catalogs; memory `example` rows (`repo` field) through an
    injected `MemoryStore` (`FileStore` locally, the S3 store when the coordinator passes one); experiment units
    under `plane/experiments/`; `benchmarks/measurements/` and `benchmarks/experiments/`; a text sweep for
    `github.com/<owner>/<name>` over `benchmarks/`, `src/`, `tests/`, `plane/` and `.kiro/`. It never reads
    population v3 and never prints a name. Output: counts per source and the sha256 of the sorted set.
  - `tests/test_unseen_eligibility.py`: a synthetic tree with one repository per source, each found; case, `.git`
    and trailing-slash variants collapse; stdout and the output JSON contain no name; a v3-shaped file planted in
    the synthetic tree is not opened (open is patched to fail on it).
  - _Requirements: 1.1_
 - [x] 1.2 Canonical resolution, renames and forks
  - `eligibility.py`: `resolve(candidate, api)` with an injected GitHub client returns the canonical `full_name`,
    former names (redirects) and the fork network (`parent`, `source`). A candidate is ineligible when any of them
    is in the used set; one candidate per fork network is kept.
  - Tests with a fake client: a planted used repository, a renamed one and a fork of a used one are each
    rejected; two forks of one network keep one; the rejection reason is a source label, not a name.
  - _Requirements: 1.1_
 - [x] 1.3 Guard extended to pools
  - `tests/test_independent_population.py`: the sweep becomes a list of (reservation directory, names):
    `benchmarks/independent/` for populations, `benchmarks/unseen/` for pools (public manifests, plus
    `benchmarks/unseen/private/*.toml` when present). The sweep also covers `plane/`. New tests: pool and
    population names are disjoint (failure prints a count only); a frozen pool's manifest digest equals its
    `freeze-pN.json` (skipped while no pool is frozen). The existing v3 handling is unchanged.
  - Each reservation is exempt only inside its own directory: population names (v3 included) are still swept in
    `benchmarks/unseen/`, the gitignored `private/` files included. Task 3.1 depends on this.
  - `.gitignore`: `benchmarks/unseen/private/`.
  - Evidence: the guard is green with an empty `benchmarks/unseen/`, and red when a test fixture names a pool
    repository in `benchmarks/measurements/` (shown once in the record).
  - _Requirements: 1.2, 1.3, 1.4_
 - [x] 1.4 Usage ledger
  - `benchmarks/unseen/ledger.py`: append-only `usage-pN.jsonl`, one row per use (slice, decision or experiment
    id, purpose `baseline | exploratory | informed | qualifies`, date, result digest, freeze digest). It refuses a
    `qualifies` row for a change whose slice already has an `informed` row for it, and refuses to rewrite rows.
  - `tests/test_unseen_ledger.py`: append, the refusal, a rewritten row detected by a digest chain.
  - _Requirements: 5.2_
 - [x] 1.5 Used-set measurement and record 01 **(coordinator, network)**
  - Run `eligibility.py` against the real sources, the S3 memory store included (read only).
  - Instrument: each source reports files read and bytes; a source with zero rows fails the run unless it is
    known empty.
  - `benchmarks/measurements/<date>-unseen-01-used-set/record.json`: counts per source, used-set digest, guard
    result (green on the empty pool), test counts of 1.1-1.4.
  - _Requirements: 1.1, 1.3_
 - [ ] 2. Sourcing and extraction (design 1.1, 1.3, 1.4, 2, 3; increment 2)
 - [x] 2.1 Advisory candidates and repository filters
  - `benchmarks/unseen/source.py`: from GHSA advisory JSON (pip, npm, maven, composer; published 2019 or later)
    keep those whose CWE maps to a family through `src/openultrasast/model/taxonomy.py` and that link one fix
    commit with one parent in one repository; attach the OSV first affected version; flag `post_cutoff` when
    published after 2026-06-01. Repository filters: anonymous HTTPS, at most 500 MB, licence at the pinned head
    (LICENSE file, then the API's SPDX id) classed `permissive` (the design 1.4 list) or `private`.
  - `tests/test_unseen_source.py` on recorded fixture JSON (no network): CWE mapping, multi-parent and
    multi-repository fixes dropped, cutoff flag, licence classing (GPL, AGPL, LGPL, none and source-available go
    private).
  - _Requirements: 1.4, 2.1_
 - [x] 2.2 Vulnerability-introducing range
  - `benchmarks/unseen/extract.py`: the `introducing` method of design 2.1 (blame of the sink line, or the
    declaration for an absence bug; absence at V's first parent; no merge or root; at most 50 files and 2,000
    lines; OSV version bracket when present; walk-back of at most five steps) and the `last_touch` fallback. Each
    change records method, family, vulnerable function resolved in head, head-side lines, `post_cutoff`, advisory
    id. Git only; no scanner or engine.
  - `tests/test_unseen_extract.py` on a synthetic repository built in a temp dir: accepted V; a reformat walked
    back; a merge rejected; size cap; bracket rejection; fallback chosen when no V passes.
  - _Requirements: 2.1_
 - [x] 2.3 Ordinary-commit draw
  - `extract.py`: first-parent, non-merge commits touching an analysed language; the exclusions of design 2.2
    (security words of the narrow pattern, reverts, bot and bump commits, manifest- or lock-only, generated or
    vendored, advisory fix commits, commits touching a known vulnerable function, more than 1,000 source lines,
    counted). Seeded draw of 12 per repository over three time thirds by four size buckets, proportional, at least
    one per third; a repository with fewer than 40 eligible commits is dropped.
  - Tests: each exclusion; the narrow pattern keeps "query", "token", "session"; allocation and the seed
    reproduce the same draw; the 40-commit floor.
  - _Requirements: 2.2, 2.3_
 - [x] 2.4 Draft manifest and slices
  - `benchmarks/unseen/draft.py`: writes `benchmarks/unseen/draft-p1.toml` (permissive entries by name) and
    `benchmarks/unseen/private/draft-p1.toml` (the rest); the public file holds an opaque id and
    sha256(URL, commits) per private entry. Seeded shuffle into three slices of 100 repositories, stratified by
    ecosystem and `post_cutoff`; each repository has one introducing change and 12 ordinary changes.
  - Tests: the digest covers private entries; no private URL in the public file; the same seed gives the same
    slices; per-slice strata within one repository of proportional.
  - _Requirements: 1.2, 1.4, 2.3, 5.2_
 - [ ] 2.5 Sourcing run **(coordinator, network)**
  - `gh api /advisories` enumeration, OSV lookups, canonical resolution against the used set (1.2), blobless
    clones into a scratch cache, extraction (2.2, 2.3), draft (2.4).
  - Instrument: clones counted with bytes on disk; a repository whose clone reads zero source files is an
    instrument failure, not a drop. Fewer than 300 eligible repositories stops the run with counts; the
    eligibility bars are not relaxed to fill it.
  - Observable: a draft of 300 repositories (3,900 changes) on disk.
  - _Requirements: 1.1, 1.4, 2.1, 2.2, 2.3_
 - [ ] 2.6 Label check and record 02 **(coordinator)**
  - Every third `introducing` change read by an agent, no model call, marked `confirmed | refactor | unclear`
    in the draft.
  - `benchmarks/measurements/<date>-unseen-02-draft/record.json`: candidates per ecosystem, rejections per used
    source, licence split (public, private), method counts, post-cutoff counts, confirmed share, ordinary-commit
    exclusion counts. No names.
  - _Requirements: 2.1, 2.2_
 - [ ] 3. Freeze p1 (design 1.2, 6; increment 3)
 - [x] 3.1 Guard bisection tool
  - `benchmarks/unseen/bisect_guard.py`: rewrites the draft with a candidate subset, runs
    `.venv/bin/pytest -q -p no:cacheprovider tests/test_independent_population.py -k referenced` with stdout and
    stderr discarded, reads only the exit code, and bisects until green. Reports the dropped count only.
  - `tests/test_unseen_bisect.py` with an injected fake guard (a hidden set): finds and drops exactly the hidden
    members; never logs a candidate; an exit code other than 0 or 1 aborts (instrument failure).
  - _Requirements: 1.1_
 - [x] 3.2 Freeze writer
  - `benchmarks/unseen/freeze.py`: canonical `pool-p1.toml` (and the private counterpart) from the bisected draft;
    `freeze-p1.json` with used-set digest and per-source counts, guard result, dropped count, label-check counts
    and the freeze digest (sha256 of the canonical manifest). Refuses to write over a frozen pool; a correction
    is `p2`.
  - Tests: digest stable under key order; overwrite refused; the guard's digest test (1.3) passes on a fixture
    pool.
  - _Requirements: 1.2_
 - [x] 3.3 Protocol p1
  - `benchmarks/unseen/protocol-p1.md`: the scoring rules of design section 4 (default flags, decision 4.0's
    long-deadline arm, catch and location rules, false alarm, coverage states), the statistics of section 3 and
    7, and the adoption gate of 7.3, stated before any replay.
  - Observable: the file exists and its sha256 is listed in `freeze-p1.json`.
  - _Requirements: 3.1, 3.2, 3.3, 3.4, 5.4_
 - [ ] 3.4 Freeze run and record 03 **(coordinator)**
  - Run the bisection (3.1), then the freeze (3.2). Guard green, digest test active.
  - `benchmarks/measurements/<date>-unseen-03-freeze/record.json`: freeze digest, protocol digest, dropped
    count, final counts per slice and kind.
  - _Requirements: 1.1, 1.2, 1.3_
 - [ ] 4. Dispatcher (design 5.3; increment 4)
 - [x] 4.1 Items, workloads and the AX lane
  - `benchmarks/ax/batch.py`: `Item` (id, input objects, result object name, command, extra env, input digest),
    `Workload` (image digest, allowed URL env names, deadline, result validator) and the `ax` lane, moved from
    `benchmarks/learn/engine_trace_ax.py`: manifest render, egress readiness, presigned GET and PUT as `.dat`,
    apply, poll result object and AX phase, delete, object cleanup. The `kind` lane is the same lane with the
    kind context.
  - `tests/test_ax_batch.py` with a fake `ax` CLI and a fake store: manifest holds only the allowed URL env
    names and no credential; names carry the `ousast-engine-` prefix; cleanup on success and failure.
  - _Requirements: 4.1, 4.2, 4.5_
 - [x] 4.2 Scheduler, fallback and resume
  - `batch.py`: two AX lanes and one VM `docker` lane by default (one container at a time); sandbox death retried
    once under a new name, a second death or a JVM OOM goes to the VM fallback queue ahead of overflow;
    `progress.json` written by the scheduler only; a `STOP` file halts launches; resume skips items whose stored
    record has the same input digest; a cleanup failure stops dispatching.
  - Tests with fake lanes: retry then fallback; OOM straight to fallback; resume skips; `STOP`; cleanup failure
    halts; never more than two AX tasks in flight.
  - _Requirements: 4.3_
 - [x] 4.3 Engine pass on the dispatcher
  - `benchmarks/learn/engine_trace_ax.py` and `engine_trace.run_plan` become an engine `Workload` over `batch.py`;
    no behaviour change.
  - Observable: `tests/test_ax_executor.py` and `tests/test_engine_trace.py` pass with their assertions unchanged
    (moved imports only).
  - _Requirements: 4.3_
 - [ ] 4.4 Engine smoke on kube-ax and record 04 **(coordinator, network)**
  - Two pins through the new dispatcher on kube-ax, compared with their stored records.
  - `benchmarks/measurements/<date>-unseen-04-dispatcher/record.json`: image digest, per-pin wall time and JVM
    time, record digests equal to the stored ones (or the diff counted), cleanup result.
  - _Requirements: 4.3_
 - [ ] 5. Replay task (design 5.1, 5.2; increment 5)
 - [x] 5.1 Image stage
  - `plane/Dockerfile.engine-task`: second stage `FROM engine AS replay` adding `git`, the package with its
    runtime dependencies and `benchmarks/unseen/replay_entry.py`; smoke `ousast pre-push --help`. The root image
    stays `ghcr.io/norandom/ax-task-runner:v0.3.1`; the engine stage is unchanged.
  - `tests/test_unseen_image.py`: parses the Dockerfile; the `replay` stage builds from `engine`; the root image
    pin; the engine stage's text is byte-identical to before.
  - _Requirements: 4.1_
 - [x] 5.2 Task entry
  - `benchmarks/unseen/replay_entry.py`, standard library only, reusing `engine_task_entry.transfer`: GET the spec;
    `git init` and depth-1 fetches of head and base over HTTPS (180 s bound), verified with `git cat-file -e`; run
    `ousast pre-push` with the spec's hook flags (defaults, or `--deadline 300` for the long-deadline arm), heap
    1700 MB and the cluster JVM flags; pack `push.json`, `push.txt`, `engine.json`, `instrument.json` (files and
    bytes in the checkout, bytes of each changed file, JVM wall time, hook exit code, step timings, image
    digest); PUT as `.dat`. Any error PUTs a failure record naming the step and status, never URL text.
  - `tests/test_unseen_replay_entry.py`: a local bare repository and a localhost presign stub; success record
    fields; a missing commit, a failed fetch and a hook crash each give a failure record; zero bytes read and a
    replay faster than JVM start are flagged `suspect_fast`.
  - _Requirements: 3.1, 4.1, 4.2_
 - [x] 5.3 Replay workload
  - `benchmarks/unseen/replay.py`: builds `Item`s from a frozen slice and an arm (`default` or `long_deadline`);
    the spec object carries the repository URL so names stay out of AX status and telemetry; task names
    `ousast-engine-replay-<slug>-<digest>` with an opaque slug; the validator rejects a record without
    `instrument.json`; records go to `~/ousast-results/unseen/<pool>/<slice>/<arm>/` and the store.
  - Tests: no repository name in any task name or manifest; only the two presigned URLs in the env; input
    digest changes with the arm's flags; `instrument_failure` items queued for one re-run.
  - _Requirements: 3.1, 4.1, 4.2, 4.3_
 - [ ] 5.4 Proof on kind, then kube-ax, and record 05 **(coordinator, network)**
  - Build and push the `replay` target, pinned by digest. Five changes from this repository's own history (never
    pool changes) on kind, then the same five on kube-ax, then on the VM lane.
  - Exit: instrument fields show bytes read and realistic JVM time on every lane; quick-tier findings equal
    across lanes.
  - `benchmarks/measurements/<date>-unseen-05-replay-task/record.json`: image digest, per-lane timings, bytes,
    exit codes, the quick-tier comparison.
  - _Requirements: 4.1, 4.2, 4.5_
 - [x] 6. Scorer (design 3, 4, 7.1, 7.3; increment 6)
 - [x] 6.1 Coverage states
  - `benchmarks/unseen/score.py`: each record gets one state (`instrument_failure`, `unanalysable`, `quick_only`,
    `engine_covered`) from `instrument.json` and the artifact; `suspect_fast` goes to failure; a slice above 5%
    `instrument_failure` after re-runs is refused.
  - `tests/test_unseen_score.py` on synthetic records: every state; the refusal; a failure never counts as quiet
    or missed.
  - _Requirements: 3.3_
 - [x] 6.2 Catch and false-alarm rules
  - `score.py`: family match (engine family, quick-rule CWE through `taxonomy.py`), the location table of design
    4.1, all three streams with the stream named per catch; false alarm on any finding of any stream; the
    alerts-only rate.
  - Tests: right family wrong place misses; `access_control` on the handler; `config_secrets` file scope; a
    quick-rule-only catch; one advisory finding on an ordinary change is a false alarm.
  - _Requirements: 3.2_
 - [x] 6.3 Rates, intervals and breakdowns
  - `score.py`: Wilson 95% intervals; repository-cluster bootstrap for false alarms; ICC; breakdowns per family,
    method, `post_cutoff`, stream, coverage state and the confirmed subset.
  - Tests: the n values of design section 3 (315, 483, 756, 62, 88, 97) reproduced; bootstrap seeded; ICC on a
    synthetic clustered set.
  - _Requirements: 2.3, 3.3_
 - [x] 6.4 Budgets, paired tests, the gate and record 06
  - `score.py`: per-budget thresholds (1%, 5%, 10%), labelled `exploratory` in-slice and `fixed` when supplied;
    a binary arm's single operating point with the budgets it meets; exact two-sided McNemar for catch and for
    false alarm; `gate(A, B)` returning `pass | regression | not_run` per design 7.3.
  - Tests: thresholds on a synthetic score set; McNemar exact values; a binary arm with a significant
    false-alarm increase gives `regression`; missing slice or excess failures give `not_run`.
  - `benchmarks/measurements/<date>-unseen-06-scorer/record.json`: test counts and the digest of the scorer's
    output on the committed synthetic fixture.
  - _Requirements: 3.4, 5.4_
 - [ ] 7. Baseline (design 4, 6; increment 7; G0 exit)
 - [ ] 7.1 Frozen source and dry run **(coordinator, network)**
  - Export HEAD to a frozen tree; build and push the `replay` image from it, pinned by digest.
  - `benchmarks/push/python_overhead.py` run with the stub engine to size per-replay Python cost; dispatcher dry
    run on slice 1 lists 1,300 items without launching.
  - _Requirements: 5.1, 4.1_
 - [ ] 7.2 Baseline replay of slice 1 **(coordinator, network)**
  - Default arm, 1,300 replays over two AX lanes and the VM lane (about 9 hours); `instrument_failure` items
    re-run once; the run stops for a cause above 5% failures.
  - Observable: 1,300 records in `~/ousast-results/unseen/p1/1/default/` and the store, each with
    `instrument.json`.
  - _Requirements: 3.1, 4.3, 5.1_
 - [ ] 7.3 Adjudication **(coordinator)**
  - Flagged ordinary changes adjudicated against protocol-v2's standard (all if 30 or fewer, else every third);
    the adjudicated share kept beside the false-alarm rate. ICC measured; above 0.05 noted as "next pool sizes
    up".
  - _Requirements: 3.2, 2.3_
 - [ ] 7.4 Record 07 and the ledger **(coordinator)**
  - `benchmarks/measurements/<date>-unseen-07-baseline/record.json`: `score.py` output (counts, rates, Wilson and
    bootstrap intervals, coverage per state, per family, method, stream), freeze digest, image digest, commit.
    `usage-p1.jsonl` row `baseline`.
  - Observable: guard green over the record; G0's exit met.
  - _Requirements: 5.1, 5.2, 3.3_
 - [ ] 8. Arms on slice 1 (design 4.0, 5.4, 7.1-7.3; increment 8; G1)
 - [ ] 8.1 Registered long-deadline arm
  - `plane/experiments/` manifest for the long-deadline arm: hook flags with `--deadline 300`, budget 0,
    `unseen: {pool: p1, slice: 1}`, committed before its first replay. `src/openultrasast/learn/experiments.py`
    accepts `unseen` and a hook-flag arm.
  - `tests/test_learn_experiments.py`: the manifest loads; an `unseen` block without pool or slice is refused.
  - _Requirements: 3.4, 5.3_
 - [ ] 8.2 `unseen` block and adoption gate in `analyse`
  - `experiments.py` `analyse`: writes `unseen` into `result.json` (catch at each budget per arm, paired B - A,
    McNemar, `gate`) from `score.py`; checks the usage ledger; adoption requires the fold rule and
    `gate == pass`.
  - Tests: `regression` and `not_run` each block adoption; an `informed` slice cannot qualify; result JSON shape.
  - _Requirements: 5.2, 5.3, 5.4_
 - [ ] 8.3 Engine-evidence arm
  - `benchmarks/unseen/arms.py`: a score per change from `engine.json` (witness rows on head-side changed
    functions), no model; plugs into the budget thresholds of 6.4.
  - Tests on synthetic records: score monotone in witness strength; a change without engine coverage gets no
    score and is reported, not counted quiet.
  - _Requirements: 3.4_
 - [ ] 8.4 Model-arm adapter
  - `arms.py`: candidates from head-side changed functions of stored records, scored by the current decision
    engine program (and the combiner when its program exists; else its row reads `not_built`); change score is the
    maximum; metered client, dry run first, response cache, the manifest's `budget_usd` as the hard ceiling.
  - Tests with a scripted client: dry-run estimate, ceiling stop, cache replay; no model call.
  - _Requirements: 4.4, 3.4_
 - [ ] 8.5 Long-deadline replay of slice 1 **(coordinator, network)**
  - 1,300 replays of the `long_deadline` arm, bounded at about 345 s each (up to about 42 hours over three
    lanes), with `STOP` and resume across sessions; failures re-run once.
  - Observable: 1,300 records under `~/ousast-results/unseen/p1/1/long_deadline/`, JVM time in each.
  - _Requirements: 3.1, 3.4, 4.3_
 - [ ] 8.6 Model arms on slice 1 **(coordinator, network; paid: needs a budget go-ahead)**
  - Dry run gives the candidate count; estimate at the injection slice's measured cost (about $0.008 per
    candidate at k = 5); the maintainer sets the ceiling against the balance read just before. Then the decision
    engine arm (and the combiner if built) on the VM.
  - _Requirements: 4.4, 3.4_
 - [ ] 8.7 Record 08: the arms table **(coordinator)**
  - `benchmarks/measurements/<date>-unseen-08-arms/record.json`: per arm (hook 30 s, hook 300 s, engine evidence,
    decision engine, combiner or `not_built`) catch at 1/5/10% budgets with Wilson intervals and realised
    false-alarm rates, coverage per state, spend; `exploratory` rows in `usage-p1.jsonl`.
  - Observable: one committed table of arms on slice 1; G1's table exists.
  - _Requirements: 3.4, 5.2, 5.3_
 ## Implementation Notes
 - 2026-10-04: Tasks 1.1–1.4 implemented offline and independently reviewed. Task 1.5 remains for the
  coordinator; no networked measurement or commit was performed. Command and API contracts:
  `benchmarks/unseen/README.md`. Offline evidence:
  `benchmarks/measurements/2026-10-04-unseen-01-offline/record.json`.
 - Population guard scope is preserved under the maintainer's hard rule: benchmarks/src/tests for
  populations, plus plane for pools. Each directory exemption is reservation-specific, including private
  pool manifests. Extending population scope to plane exposed 30 existing references; no historical
  records were changed or exempted inside the existing population scope.
 - S3 inventory opens through `open_store(read_only=True)` because ordinary store construction writes a
  Select capability probe. Default store behavior is unchanged; inventory uses LIST/GET only.
 - The freeze writer must match the canonical TOML digest encoding documented in the pool README and
  exercised by `test_independent_population.py`; final pool discovery does not trust mutable status.
 ### Group 2 implementation evidence (2026-10-04)
 Tasks 2.1–2.4 are implemented offline and independently reviewed. Task 2.5 is
 `python -m benchmarks.unseen.draft --root "$PWD" --s3-store s3:// --seed 20260601`
 with the documented PATH/PYTHONPATH and GH_TOKEN environment. No networked draw,
 label check, group-2 measurement record, guard bisection, or commit was performed.
 The group header remains pending its coordinator exits 2.5/2.6.
 The command rebuilds the group-1 used set, resolves renamed/fork repositories,
 uses disposable external blobless clones, re-reads licences at extracted heads,
 and emits counts/digests only. The README documents injected clients, method bias,
 the hard 300-repository floor, and an explicitly unmeasured resource estimate.
 Independent review caught and fixed ambiguous parent-function absence and stale
 candidate-404 handling; regression tests cover both.
 Validation: requested pytest selection 103 passed, 1 skipped, exit 0 (population-test
 output discarded); `ruff check .` exit 0; `ruff format --check .` exit 0 (411 files);
 `mypy src/openultrasast` exit 0 (160 source files). The CLI `--help` smoke exited 0.
 Source-read instrumentation printed 20,101 bytes for the extraction implementation.
 ### Groups 4–6 offline implementation (2026-10-04)
 Tasks 4.1–4.3, 5.1–5.3 and 6.1–6.4 are implemented and independently reviewed.
 Tasks 4.4 and 5.4 remain coordinator-owned network proofs; group headers 4 and 5 stay
 pending those exits. No commit, network request, Docker, AX or kubectl command was run.
 The sourcing job's draft.py, source.py, extract.py and journal.py are unchanged.
 The shared dispatcher retains the engine adapter's historical questions.json object
 name to preserve its unchanged assertions; replay uses spec.dat and result.dat.
 The engine Dockerfile body is unchanged except its required AS engine alias; CI builds
 engine and replay separately. S3Store's read_only class default preserves existing
 constructor-bypassing transport fixtures; initialized read-only stores still refuse writes.
 Exact coordinator commands and input contracts are in benchmarks/unseen/README.md,
 including frozen TOML/private pointer verification, scoring joins, own-history proof
 preparation and anonymous measurement-record generation. JVM wall time is the hook's
 aggregate scan build/query timing and is labelled as such. Unsupported-only partitions
 with explicit language_not_covered evidence do not pretend to have launched a JVM.
 Record 06 contains the committed synthetic fixture and scorer-output digests. The
 reserved-repository guard was run as a black box with both output streams discarded.
 Independent review: APPROVED; all reported integration and coverage defects resolved.
 Final verification: requested pytest command 279 passed, 8 skipped, exit 0; separate
 `tests/test_ax_batch.py` 5 passed, exit 0; `ruff check .`, `ruff format --check .`,
 `mypy src/openultrasast`, and the output-discarded reserved-repository guard all exit 0.
 The own-history proof preparer and replay dry run read five items and exit 0.
@@ -0,0 +1,32 @@
 # kube-ax operator constraints
 Verified by the operator on 2026-10-05. These constraints apply across all workloads.
 - Two workers, one task per worker, at most two tasks in flight cluster-wide. AX has no
  queue: a third apply returns `no free workers available`. Treat this as back-pressure,
  retry the same task/lane with 15–30 seconds of jitter until its deadline, and never
  count it as a sandbox failure or trigger VM fallback. The host dispatcher shares a
  two-slot reservation across workload instances and long-lived search executors.
 - `/` and `/tmp` are RAM-backed and consume the worker's 3 GiB. `/workspace` is the only
  disk-backed path, with about 2 GiB usable per task. Executor and verifier entrypoints
  use `/workspace/tmp`, `/workspace/.npm`, `/workspace/.m2`, `/workspace/.composer`,
  `/workspace/.pip`, and `/workspace/.gradle` through the respective tool environment
  variables. Builds and extracted checkouts live under `/workspace` too. The default
  aggregate workspace scratch guard is 2 GiB; `OUSAST_SCRATCH_BYTES` configures it.
  Exceeding it returns `could_not_build`, reason `scratch limit`. The guard polls
  during child execution and checks after exit; it is not an instantaneous filesystem
  quota or a replacement for the worker memory limit.
 - `ousast-engine-search-verify-*` tasks have no egress. The requested exception for
  `files.because-security.com:443` is **pending**, not operationally verified. They
  receive a presigned manifest for a gzip level-6 archive containing `checkout/`,
  `products/`, and `spec.json`, built/exported by an executor. Compressed archives
  retain the 1 GiB cap and travel in parts of at most 90 MB, each digest-checked
  before assembly and extraction under `/workspace`. Only `VERIFY_INPUT_URL` and `RESULT_URL` cross the
  verifier boundary. Verifiers reject build recipes and do not install dependencies
  or fetch repositories. Executors finish and release their slots before verifier
  repetitions start. Both task types must be provisioned without model credentials.
 - All tasks share one public IP. Repository acquisition uses HTTPS git clone from
  `github.com` or archives from `codeload.github.com`, never `api.github.com`. Host-side
  metadata queries are a separate concern. Search tasks receive checkout archives;
  executor tool guidance carries the same acquisition rule. Retain the 60-second
  first-download retry for delayed task egress policy activation.
@@ -0,0 +1,60 @@
 # Operator notifications (Discord)
 Recorded 2026-10-09 from the maintainer's direction. OpenUltraSAST notifies the operator on
 Discord about the status and results of its own processes, and especially when a process is
 **stuck or otherwise impaired**. This is an operator channel, not a developer or infrastructure
 one.
 ## Audience
 The **system operator** and the **AI operator** who run and oversee the tool. Not developers
 debugging the code, and not an infrastructure on-call. The messages answer "is the work moving,
 did it finish, what did it produce, is it stuck" for someone supervising a run, not "why does this
 function throw".
 ## Scope: OpenUltraSAST processes and their results
 Notify on the actual OpenUltraSAST workloads and what they produce:
 - scans and pre-push checks (a completed check and its verdict/degradations),
 - unseen-repo sourcing / draft, freeze, and replay / baseline runs,
 - learning and evaluation runs (compile, evaluate, experiments) and their recorded results,
 - fusion / adjudication and any long-running job.
 **Not** k3s or ax cluster infrastructure. Cluster, node, and ax-task health is a separate
 infrastructure concern monitored elsewhere; this channel does not carry it. The line is: a message
 here is about an OpenUltraSAST process or result, never about the plane's plumbing.
 ## When to notify
 - **Completion:** a process finished, with a one-line result summary (counts, status, digest).
 - **Stuck or impaired (the important case):** a stall, a clean-but-short result
  (`insufficient_*`), an abort or `instrument_failure`, a timeout or deadline hit, budget
  exhaustion, or a resource limit (disk, memory). These @mention the operator so a supervised run
  does not sit silently broken.
 Advisory and low-volume by design: a start/finish and the impaired cases, not per-step chatter.
 ## Transport and secrets
 A Discord webhook, with credentials referenced by name only and stored in gitignored `.env`, like
 every other credential (`.env.example` lists the names, blank):
 - `DISCORD_WEBHOOK_URL` — the operator channel webhook.
 - `DISCORD_OPERATOR_ID` — the account to @mention on a stuck/impaired alert.
 The webhook URL is a secret (anyone holding it can post to the channel): it never enters a tracked
 file, a prompt, a log, or a commit, and it is rotated if exposed. Notifications are **off** when the
 webhook is unset, so the tool runs the same with or without it.
 ## Content discipline
 Messages carry status, counts, and digests only, under the same redaction as the hardening and
 measurement-record conventions: no exploit payloads or request strings, no secrets, no customer
 content, no repository contents. A notification is safe to read in a shared channel.
 ## Status
 Policy recorded; the notifier (reading the env-named webhook, quiet when unset, honoring the
 redaction above) is to be wired into the process entry points and may be specced separately. Until
 then this steering states the intended behavior for any process that adds notifications.
@@ -41,6 +41,36 @@ Correction recorded 2026-10-04: the previous two days went mostly into infrastru
 not move a generalisation number. From here, infrastructure and engine work is done only when it removes a
 bottleneck for the measurements below.
 ### Where we are (2026-10-11)
 The G0 measurement is now runnable: the unseen pool is **frozen** and the whole pipeline is hardened and
 **bucket-first**. The baseline replay is the one remaining step, to run on kube.
 | Area | State | Evidence |
 | --- | --- | --- |
 | Unseen pool (G0.1) | **Frozen.** `pool-p1.toml` = 100 repos (slice 1); `freeze-p1.json` guard=0, dropped=0; deterministic (manifest `6bd2fa5d`). License 49 permissive / 51 private; methods 81 introducing / 19 last_touch. | `benchmarks/unseen/pool-p1.toml`; archived `ousast-corpus/unseen/20260601/pool/` |
 | Labels | 100 machine-derived (SZZ), **unchecked**. Record 07 is a **machine-label baseline** (caveat stated); a human label pass is a later refinement, before any published claim. | `freeze-p1.json` label_check_counts |
 | Harvest | Rebuilt to converge. Pure GitHub-API harvesting is a dead end for this benchmark (it needs the SZZ introducing commit + 12 stratified history negatives, not one commit). The fix: a full-objects clone (drop `--filter=blob:none`, which caused ~600 per-blob lazy fetches) + bucket-first durability + a get_repo cache that paid the 4,499-name used-set canonicalization once. Yield ~2.2%; **GitHub-rate-limit bound, not CPU**. | 95bed70, 857263d, 21aebe8, 7b711a6 |
 | Persistence | **Bucket-first, not local disk.** `ousast-corpus` is the source of truth: enumeration, resolution, get_repo, and accept/reject decisions all stream to and resume from it. The host disk (~9-13 GB free) is the scarce resource; RustFS/S3 has the room, so run artifacts and **replay outputs go to RustFS too**, not `~/ousast-results` on local disk. | `storage-streaming.md`, `bank.py` |
 | Replay image | Provenance pinned. CI `engine-image.yml` builds `ousast-replay-task` (harness with `/app/benchmarks/unseen/replay_entry.py`) + `ousast-engine-task` (Joern hook), publicly pullable by digest. The old `ousast-runner:dev` (248 MB ax-runner, no `/app/benchmarks`, no Joern) is the **wrong** image for replay. | CI run 38116281676 |
 | Baseline (G0.2) | **Not yet.** Replay reads the frozen pool cleanly (dry-run = 1,300 changes, `freeze_digest` verified). Remaining: mirror CI's passing `replay` job wiring, and stand up the kube lane (`ax` binary + a public-HTTPS presign-capable store endpoint; GHCR pull already public). | CI `replay` job (passed) |
 Lesson, recorded so it is not re-paid: sourcing and engine-image work cost real time. The durable takeaway now lives
 in the pipeline and these docs — bucket-first persistence, pinned image provenance, a measured yield — so the next
 pool or arm is cheap, not a rediscovery.
 ### Readiness plan (to G0 exit = record 07)
 1. **Kube replay lane (infra, operator-owned):** install the `ax` binary; provide the store endpoint the AX lane
   needs. The only thing settled in-repo is a code fact: `benchmarks/ax/batch.py` currently expects a public-HTTPS
   DNS, presign-capable S3 endpoint. How that endpoint and the cluster's access to the store are provided is an
   operator/AX decision, not an assumption to make here. GHCR pull of the images is verified public.
 2. **Unblock the replay** by mirroring CI's passing `replay` job (replay-task + engine-task wired, store + network).
 3. **Run slice-1 baseline on kube:** `--lane ax --arm default`, 1,300 changes, no model cost, resumable; outputs to
   RustFS.
 4. **Adjudicate (7.3) -> record 07 (7.4)** = the measured machine-label unseen baseline = **G0 exit**.
 5. Then **G1 arms** (DeepSeek decision engine) on the frozen pool.
 ### Phases
 **G0. The unseen-repository pool and the push-level metric** (new spec `unseen-repo-evaluation`)
@@ -67,6 +97,19 @@ Candidates, each admitted only if it improves the pool metric on a fresh slice:
 (approved plan, now one arm, not the spine), engine coverage and TypeScript, decision-engine prompt and retrieval
 changes, more labelled pairs from more distinct repositories.
 Active G2 workstreams (2026-10-11, opened while driving G0; progress tracked in their briefs):
 - **Change-scoped engine analysis** (`.kiro/specs/engine-change-scoped-analysis/brief.md`). Live diagnosis on the
  frozen pool showed the engine's "no finding" on unseen changes is usually *analysis-never-runs*: the engine ranks
  repo-wide candidates and `deferred: deadline_exhausted` before analyzing anything (even at 300 s), and the ranked
  sites are unrelated to the pushed change. Lever: seed analysis from the change's declarations + dataflow
  neighbourhood (`rank.py`/`mapping.py`) so it runs within budget. Increment 0 (confirm CPG-build-vs-analysis cost
  split) gates the rest. Scale measurement needs the kube lane.
 - **Line-correspondence (done, necessary-not-sufficient).** `snapshot.py` discarded base↔head anchors on
  non-globally-unique lines → `comparison_unknown` → suppressed findings; fixed to run-aware anchoring
  (commit c39fbb8, 163 tests). Removes one cause; coverage still needs change-scoped analysis + the capability
  registry (Task 8.3).
 **G3. Decide BLOCK per family** on the pool's false-alarm rate and the pooled precision bound (Req 6.4).
 **G4. Detection on push for any repository** (`plane-on-kubernetes` P4 work: `ousast plane scan --base --head`,
@@ -142,3 +142,19 @@ promising but does not qualify security queries or hook latency. The contributor
 vendor/correspondence completeness vetoes, and query-to-operation identity as the next
 shared-contract work. Resolving a boundary requires evidence of its relevance and scope;
 do not simply drop completeness checks to increase admissions. Rollout remains NO-GO.
 On 2026-10-07, the **search-with-proof** arm reached its first milestone: an autonomous,
 execution-backed `demonstrated` finding end to end on the kube-ax cluster. On a real CVE
 fix-pair (hanxi/xiaomusic, path traversal of the prefix-check-bypass class), the agent
 found the vulnerability, authored a declarative demo, and the differential verifier
 confirmed the owned effect on the vulnerable revision and its absence on the fixed one;
 a blind search of the fixed revision produced zero false proofs. This is the proof-based
 BLOCK mechanism the maintainer directed after classification hit a precision wall: a BLOCK
 rests on a demonstrated finding with a direct execution trace, not a confidence score.
 Scope note: this is feasibility-pilot evidence on a development-corpus pair (known location,
 labelled family, runnable-project selection bias), not release readiness. The pilot exit
 (≥5 demonstrations in one family with 0 false proofs, Req 6.2) and the ≥73-negative BLOCK
 qualification (Req 6.3) remain open, and no capability is enabled. The decision/classification
 engine is retained as a triage ranker (it could not prove 95% precision as a gatekeeper);
 proof is the BLOCK gate. See `search-with-proof/HANDOFF.md` and
 `benchmarks/measurements/2026-10-07-search-first-cluster-demonstration/`.
@@ -0,0 +1,80 @@
 # Stream run artifacts to RustFS, one bucket per purpose
 Recorded 2026-10-09 from the maintainer's direction. The host's local disk is the scarce
 resource (it runs near full, and the draw stops itself at under 2 GB free). Runs should stream
 their durable artifacts to RustFS instead of accumulating them on local disk, and should spread
 them across **purpose-specific buckets** rather than one shared bucket. This relieves the disk and
 simplifies runs: local state becomes mostly a scratch cache that can be rebuilt or resumed from the
 object store.
 ## Why per-purpose buckets
 One shared bucket (`sast-memory`) already bit us: an append-rewritten key on a versioned bucket
 with no noncurrent-version expiry ballooned to >10 GB (see the `engine-queue` command-upload fix and
 the lifecycle rules added 2026-10-09). Separate buckets let each kind of artifact carry the
 lifecycle it actually needs, and keep a transient firehose from polluting durable data.
 Proposed split (names illustrative; the admin creates them and grants the store key):
 - `sast-memory` — the plane memory store (existing): facts, excerpts, embeddings, index. Durable,
  versioned, with the noncurrent-version lifecycle now in place.
 - `sast-pools` — frozen unseen pools and their provenance: `pool-pN.toml`, `freeze-pN.json`, and the
  draw journal needed to resume/reproduce. Durable, versioned. This is also the "don't redo the
  sourcing" archive.
 - `sast-runs` (or `sast-journals`) — ephemeral run and queue state (engine-queue, replay results,
  per-run journals). Aggressive lifecycle: short current expiry + 1-day noncurrent expiry, since it
  is a transient firehose.
 - optionally `sast-traces` — engine/replay traces, if kept.
 ## Principles
 - **Stream, don't hoard.** Write a run's durable outputs to its bucket as they are produced; keep
  only a working scratch (e.g. the live git clone, which cannot be streamed) on local disk, and let
  the disk guard stay as the backstop.
 - **Lifecycle per bucket**, tuned to the artifact: durable+versioned for pools/memory;
  short+noncurrent-expiry for transient run/queue state. Never a versioned bucket without a
  noncurrent-version rule.
 - **Resume from the object store**, so a wiped or small local disk does not lose a long run.
 - **Least privilege per bucket.** A run gets a key scoped to the bucket it writes; the store never
  creates or configures a bucket (admin does that once), consistent with the current S3Store.
 - Content discipline unchanged: no secrets, no exploit payloads; pool manifests keep the existing
  public/private (licence) split.
 ## Foundation and dependency
 `src/openultrasast/plane/memory.py` already speaks boto3 to RustFS (S3Store) with startup
 verification of versioning/lifecycle/Select/tags; this direction extends that pattern to more
 buckets rather than inventing a new transport. New buckets and their grants are an **operator
 admin** action — the store credentials cannot create buckets or set lifecycle (confirmed by the
 `AccessDenied` on the 2026-10-09 lifecycle apply).
 ## Default: RustFS over local disk
 Local disk on the VM is the scarce resource (it runs near full; the draw stops itself under 2 GB free).
 RustFS/S3 has far more room. So the default for any run's durable state and large artifacts is the bucket,
 not local disk. Local files are a rebuildable scratch cache only (the live git clone, a within-process
 journal). A long run must be resumable purely from the bucket, and its outputs — including replay result
 records — are written to RustFS, not `~/ousast-results` on local disk.
 ## Status (implemented 2026-10-10/11)
 Bucket-first persistence is live, not a future spec. The unseen draw streams every stage to the
 `ousast-corpus` bucket (`http://10.0.0.54:9001`, creds in `.env` as `CORPUS_S3_*`; boto3 needs path-style +
 SigV4) and resumes from it:
 - `unseen/<seed>/decisions/<sha256(repo+fix)>.json` — accept/reject per repository (idempotent; content dedup).
 - `unseen/<seed>/resolved/<sha256(ghsa)>.json` — per-advisory resolution.
 - `unseen/<seed>/advisories/list.json` — the enumerated advisory list.
 - `unseen/repos/<sha256(name)>.json` — get_repo cache, **not** seed-scoped (shared across seeds/runs), so the
  thousands of used-set canonicalization lookups are paid once ever.
 - `unseen/<seed>/pool/` — the frozen pool and its provenance (`pool-p1.toml`, `private-pool-p1.toml`,
  `freeze-p1.json`, `bisect-p1.json`, `protocol-p1.md`): the durable "don't redo the sourcing" archive.
 Implementation: `benchmarks/unseen/bank.py` (`CorpusBank`, `corpus_settings`). The old local journal is a
 within-process cursor only; the bucket is the cross-run source of truth, so a restart (even after a code
 change) resumes cheaply. Still to do and consistent with the default above: replay result records
 (`replay.py --out`) currently default to `~/ousast-results/unseen/...` on local disk — point them at RustFS
 for the slice-1 baseline and after. The AX (kube) lane already uses presigned object transfer, which is the
 same principle. One in-repo code fact: `benchmarks/ax/batch.py` currently expects a public-HTTPS DNS,
 presign-capable endpoint. How the store endpoint and the cluster's access to it are provided is operator/AX-owned
 infra, not something this doc should presume.
@@ -1,26 +1,14 @@
-# OpenUltraSAST with its CPG engine, in one image.
+# syntax=docker/dockerfile:1
-#
+# Supply digests from plane/task-base.digest; deliberately no floating fallback.
-# The model layer's arbiter is Joern, and `openultrasast.cpg.backend` reaches it by subprocess. Shipping both
+ARG TASK_BASE_TAG=base-unpublished
-# in one image is what makes that simple: Joern is on PATH inside, so there is no container-to-container call,
+ARG TASK_BASE_DIGEST
-# no docker socket, no path translation between host and container, and no second code path in the backend to
+FROM ghcr.io/norandom/ousast-task-base:${TASK_BASE_TAG}@${TASK_BASE_DIGEST} AS joern-build
-# get wrong. The alternative -- tool and engine as sibling services -- needs the tool to exec into the other
+ENV PATH="/opt/joern-cli:${PATH}"
 # container, which means mounting the docker socket, and that is a large amount of privilege for a linter.
 #
 # The image is big (a JRE plus ~2 GB of Joern). That is the honest cost of bundling an engine, and it buys a
 # contributor a working tool from `docker compose run` with nothing installed on their machine.
 FROM eclipse-temurin:21-jre-noble
 LABEL org.opencontainers.image.licenses="Apache-2.0" \
      org.opencontainers.image.source="https://github.com/norandom/OpenUltraSAST"
 ARG JOERN_VERSION=v4.0.625
 ARG ARCHIVE=joern-cli-linux-x86_64.zip
 # php-cli is required by php2cpg, which drives PHP-Parser and shells out to a real interpreter. Without it a
 # PHP tree fails with an opaque "Process exited with code 1" -- measured on this project, not assumed.
 RUN apt-get update \
- && apt-get install -y --no-install-recommends \
+ && apt-get install -y --no-install-recommends curl unzip \
      python3 python3-venv python3-pip unzip curl ca-certificates git php-cli \
 && rm -rf /var/lib/apt/lists/*
 RUN set -eux; \
@@ -32,39 +20,28 @@ RUN set -eux; \
    unzip -q "${ARCHIVE}" -d /opt; \
    rm -f "${ARCHIVE}" "${ARCHIVE}.sha512" checksum.sha512; \
    /opt/joern-cli/joern-parse --help > /dev/null
 ENV PATH="/opt/joern-cli:${PATH}"
 # This release ships the JS launcher with a .sh suffix; the backend's direct fallback uses
 # the same extensionless command convention as the other frontends.
 RUN if [ ! -e /opt/joern-cli/jssrc2cpg ] && [ -x /opt/joern-cli/jssrc2cpg.sh ]; then \
      ln -s jssrc2cpg.sh /opt/joern-cli/jssrc2cpg; \
    fi
 COPY ops/frontend-retention/install.py /tmp/frontend-retention-install.py
 RUN python3 /tmp/frontend-retention-install.py /opt/joern-cli \
 && rm /tmp/frontend-retention-install.py
-WORKDIR /app
+FROM ghcr.io/norandom/ousast-task-base:${TASK_BASE_TAG}@${TASK_BASE_DIGEST} AS engine
-COPY pyproject.toml README.md ./
+ENV PATH="/opt/joern-cli:${PATH}"
-COPY src ./src
+COPY --from=joern-build /opt/joern-cli /opt/joern-cli
-COPY benchmarks ./benchmarks
+# Create runtime identity before the application layers.
 # The core install is zero-dependency by design; `semantic` adds the tree-sitter grammars the candidate
 # enumerator uses. The LLM endpoint stays optional and is configured by environment, never baked in.
 RUN python3 -m venv /venv \
 && /venv/bin/pip install --no-cache-dir -e ".[semantic,s3]"
 ENV PATH="/venv/bin:${PATH}"
 # Analysis never needs root.
 # Noble may already provide the ubuntu account at UID 1000. Reuse that identity rather than
 # failing installation or creating a second account with the same UID.
 RUN if getent passwd 1000 > /dev/null; then \
      usermod --login ousast --home /home/ousast --move-home "$(getent passwd 1000 | cut -d: -f1)"; \
-    else \
+    else useradd --create-home --uid 1000 ousast; fi
-      useradd --create-home --uid 1000 ousast; \
+WORKDIR /app
-    fi \
+COPY pyproject.toml README.md LICENSE ./
- && chown -R ousast /app
+COPY src ./src
 RUN --mount=type=cache,target=/root/.cache/pip \
    /venv/bin/pip install --no-deps --no-cache-dir .
 COPY --chown=1000 benchmarks ./benchmarks
 RUN chown -R ousast /app
 USER ousast
 ENTRYPOINT ["python", "-m", "openultrasast.cli"]
 CMD ["--help"]
@@ -14,6 +14,11 @@ A scan combines up to four parts:
 Every finding carries the evidence that earned its place. When a scan could not look at
 something, it records a degradation. It does not report a clean result.
 Where a repository's application can be built and run, an experimental proof arm goes further. It
 demonstrates a finding by executing it: the issue triggers on the vulnerable revision and not on
 the fixed one, so a demonstrated finding is a reproducible fact, not a score. This arm is in pilot
 and being qualified on repositories the tool has never seen; see [Status](#status).
 `ousast` is the interface. Model work over whole repositories runs on a separate agentic plane
 (google/ax). A learned decision engine is in development. A scan needs neither of them.
@@ -23,17 +28,30 @@ The site is published at <https://norandom.github.io/OpenUltraSAST/>. Its source
 ## Status
-**v2.0.0, state as of 2026-10-02.** The pre-push safety net is **NO-GO** against every M4 gate.
+**v2.0.1, state as of 2026-10-08.** The pre-push safety net is **not yet released**. Blocking on
 the static analyser by hand is **NO-GO** against every M4 gate, and the project no longer tries to
 reach them that way.
- No hook capability is enabled.
+- No blocking hook capability is enabled; the pre-push hook is advisory only.
- Two independent populations (case sets frozen before any scan) have been spent so far. Engine
+- Two independent populations (case sets frozen before any scan) have been spent on the static
-  recall was 1 of 11 and then 0 of 17.
+  engine: recall was 1 of 11, then 0 of 17. The learned decision engine ranks but blocks for no
- The learned decision engine ranks but may not block. BLOCK is offered for no family.
+  family.
 - Why blocking is hard: static abstract interpretation could not prove the precision a block
  needs. So the current work is a **dynamic proof arm**. It builds and runs a repository's app and
  demonstrates a finding by a differential: the issue triggers on the vulnerable revision and not
  on the fixed one. A demonstrated finding is ground truth by execution, so it can earn a block
  without calibration. Pilot demonstrations exist, including one executed on the cluster; the arm
  is being qualified, not shipped.
 - The release gate is a **measured** catch-rate and false-alarm number on repositories the tool
  has never seen (the unseen-repo evaluation), produced rather than asserted. Until that number
  exists, treat all output as advisory.
-The project has stopped trying to reach the gates by hand. Every detection change now has to win
+Every detection change has to win a controlled measurement on held-out repositories. One page
-a controlled measurement on held-out repositories. One page states all of this, with the record
+states where things stand, with the record behind each figure:
-behind each figure: [docs/where-we-stand.md](docs/where-we-stand.md). The release history is in
+[docs/where-we-stand.md](docs/where-we-stand.md). For developers, the pre-push check and its
-[RELEASE_NOTES.md](RELEASE_NOTES.md).
+honest limits: [docs/pre-push-for-developers.md](docs/pre-push-for-developers.md); the
 catch–prove–fix–re-verify loop: [docs/use-case-fix-and-reverify.md](docs/use-case-fix-and-reverify.md).
 The release history is in [RELEASE_NOTES.md](RELEASE_NOTES.md).
 ## Install and first scan
@@ -0,0 +1,809 @@
 """Host-only AX Task transport; credentials never enter task manifests."""
 from __future__ import annotations
 import hashlib
 import ipaddress
 import json
 import logging
 import os
 import queue
 import random
 import re
 import shutil
 import subprocess
 import threading
 import time
 import uuid
 from collections import Counter, deque
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
 from dataclasses import dataclass, field
 from datetime import timedelta
 from pathlib import Path
 from urllib.parse import urlsplit
 import yaml
 from openultrasast.config import load_dotenv
 from openultrasast.plane.memory import PRESIGNED_ARCHIVE_SUFFIX, S3Store, open_store
 from openultrasast.search.task_storage import diagnostic, exception_reason
 class EgressError(ValueError):
    """Safe diagnostic without presigned URL contents."""
 class SandboxFailure(Exception):
    """A terminal AX task without an authoritative result object."""
 class NoFreeWorkers(Exception):
    """Capacity back-pressure, never a sandbox or instrument failure."""
 class ClusterUnavailable(Exception):
    """No running workers were observed in the worker namespace."""
 class CapacityDeadline(Exception):
    """No worker became available before the task deadline."""
 # Shared by every workload/lane instance in this dispatcher process, including
 # long-lived search executors. The operator runs one task per worker, two workers.
 AX_SLOTS = threading.BoundedSemaphore(2)
 def apply_when_available(lane, document, end):
    started = lane.clock()
    next_health_check = started + 60
    while lane.clock() < end:
        try:
            lane.ax("apply", "-f", "-", manifest=document, timeout=min(30, end - lane.clock()))
            return
        except NoFreeWorkers:
            # A failed apply is not proof that the server did not create a task.
            # Never send another create while the preceding task can still run.
            try:
                lane.ax("delete", "task", document["metadata"]["name"])
            except Exception as exc:
                raise RuntimeError("capacity cleanup failed: " + exception_reason(exc)) from None
            if lane.clock() >= next_health_check:
                lane.check_cluster_health(timeout=min(10, max(0.01, end - lane.clock())))
                next_health_check = lane.clock() + 60
            # Substrate's golden-snapshot copy holds the other worker for about a second after each new task
            # (operator, 2026-10-05): retry quickly for the first minute, then back off while real tasks run.
            delay = random.uniform(2, 5) if lane.clock() - started < 60 else random.uniform(15, 30)
            lane.pause(min(delay, max(0, end - lane.clock())))
    raise CapacityDeadline("no free workers available before deadline")
 def public_endpoint(url):
    """Reject endpoints the actor's hostname-based HTTPS egress policy cannot reach."""
    parts = urlsplit(url)
    host = parts.hostname or ""
    try:
        ipaddress.ip_address(host)
        is_ip = True
    except ValueError:
        is_ip = False
    if (
        parts.scheme != "https"
        or not host
        or is_ip
        or "." not in host
        or host.endswith((".localhost", ".local", ".internal"))
        or parts.port not in (None, 443)
        or parts.username
        or parts.password
    ):
        raise EgressError(
            "AX requires a public HTTPS DNS hostname in S3_ENDPOINT and presigned URLs: "
            "the egress policy allows the store hostname on port 443 only (no IP or plain HTTP)"
        )
    return host.lower()
 def task_state(text, name):
    """Accept AX YAML/JSON output and its human-readable tasks table."""
    try:
        doc = yaml.safe_load(text)
    except yaml.YAMLError:
        doc = None
    rows = doc.get("items", doc.get("tasks", [doc])) if isinstance(doc, dict) else doc if isinstance(doc, list) else []
    for row in rows:
        if not isinstance(row, dict) or row.get("metadata", {}).get("name", row.get("name")) != name:
            continue
        status = row.get("status", {})
        ip = next(
            (status.get(key) or row.get(key) for key in ("workerIP", "workerIp", "worker_ip", "ip") if status.get(key) or row.get(key)),
            None,
        )
        worker = status.get("worker")
        if not ip and isinstance(worker, dict):
            ip = worker.get("ip") or worker.get("address")
        return str(status.get("phase", row.get("phase", ""))), ip
    lines = [line.split() for line in text.splitlines() if line.strip()]
    if lines:
        headers = [re.sub(r"[^a-z]", "", cell.lower()) for cell in lines[0]]
        for cells in lines[1:]:
            if name not in cells:
                continue
            row = dict(zip(headers, cells, strict=False))
            phase = row.get("phase", row.get("status", ""))
            ip = row.get("workerip") or row.get("ip")
            if not ip:
                for cell in cells:
                    try:
                        ipaddress.ip_address(cell)
                        ip = cell
                        break
                    except ValueError:
                        pass
            return phase, None if ip in {"<none>", "-", ""} else ip
    listed = isinstance(doc, (dict, list)) or bool(lines and "name" in headers and {"phase", "status"}.intersection(headers))
    return "Missing" if listed else "", None
 def bounded_read(read, timeout):
    """Do not let SDK retries postpone task teardown beyond the pin deadline.
    Only the read runs in a daemon thread; it cannot publish a late result to disk.
    No executor shutdown waits for an SDK call whose socket has stopped responding.
    """
    if timeout <= 0:
        raise TimeoutError("AX result deadline")
    replies = queue.Queue(maxsize=1)
    def fetch():
        try:
            replies.put((True, read()))
        except Exception as exc:
            replies.put((False, exc))
    threading.Thread(target=fetch, daemon=True, name="engine-ax-result-read").start()
    try:
        ok, result = replies.get(timeout=timeout)
    except queue.Empty:
        raise TimeoutError("AX result deadline") from None
    if not ok:
        raise result
    return result
 class AXLane:
    def __init__(self, args, workload, store=None, pause=time.sleep, clock=time.monotonic, runner=None):
        self.runner = runner or subprocess.run
        self.workload = workload
        self.args = args
        self.pause, self.clock = pause, clock
        self.run = uuid.uuid4().hex
        load_dotenv()
        self.host = public_endpoint(os.environ.get("S3_ENDPOINT", ""))
        # Validate the image before opening a store, whose constructor probes the bucket.
        validate_image(workload.image)
        self.store = store if store is not None else open_store()
        if store is None and not isinstance(self.store, S3Store):
            raise ValueError("AX requires OUSAST_MEMORY=s3://bucket[/prefix]")
    def __call__(self, item, output, attempt):
        attempts = []
        # Docker has its own capacity and must not hold an AX worker slot.
        slot = not isinstance(self, DockerLane)
        if slot and not AX_SLOTS.acquire(timeout=self.workload.deadline):
            return {"status": "capacity_timeout", "ax_attempts": attempts}
        try:
            done, worker = self._execute_attempt(item, output, attempt, attempts)
        except CapacityDeadline:
            return {"status": "capacity_timeout", "ax_attempts": attempts}
        except SandboxFailure:
            return {"status": "sandbox_failure", "ax_attempts": attempts}
        except RuntimeError:
            # Teardown did not prove the worker free; retain its reservation.
            slot = False
            raise
        finally:
            if slot:
                AX_SLOTS.release()
        if done is None or done.returncode:
            return {
                "status": "instrument_failure",
                "reason": diagnostic(done.stderr) if done is not None else "TimeoutError: task result deadline",
                "ax_attempts": attempts,
            }
        record = json.loads((output / "result.json").read_text())
        return {**record, "worker_ip": worker, "ax_attempts": attempts}
    def check_cluster_health(self, *, timeout=10):
        env = dict(os.environ)
        if self.args.kubeconfig:
            env["KUBECONFIG"] = str(Path(self.args.kubeconfig).expanduser())
        done = self.runner(
            ["kubectl", "-n", "ax-workers", "get", "pods", "-o", "json"],
            env=env,
            capture_output=True,
            text=True,
            timeout=timeout,
        )
        if done.returncode:
            raise RuntimeError(f"worker pod health check failed (exit {done.returncode})")
        try:
            pods = json.loads(done.stdout)["items"]
            if not isinstance(pods, list):
                raise ValueError("invalid pod list")
            phases = [pod["status"]["phase"] for pod in pods]
        except (ValueError, KeyError, TypeError):
            raise RuntimeError("worker pod health check returned invalid pod data") from None
        running = phases.count("Running")
        if not running:
            raise ClusterUnavailable(f"worker pods: total={len(pods)}, running=0, pending={phases.count('Pending')}")
    def ax(self, *args, manifest=None, timeout=30):
        env = dict(os.environ)
        if self.args.kubeconfig:
            env["KUBECONFIG"] = str(Path(self.args.kubeconfig).expanduser())
        done = self.runner(
            [str(Path(self.args.ax_bin).expanduser()), *args, *(["--atespace", self.args.atespace] if args[0] != "apply" else [])],
            input=json.dumps(manifest) if manifest is not None else None,
            env=env,
            capture_output=True,
            text=True,
            timeout=max(0.01, timeout),
        )
        if done.returncode:
            if args[0] == "apply" and "no free workers available" in (done.stdout + done.stderr).lower():
                raise NoFreeWorkers("no free workers available")
            if args[0] == "delete" and "notfound" in (done.stdout + done.stderr).lower().replace(" ", ""):
                return done
            # AX errors may echo manifest URLs; sanitize before recording.
            raise ValueError(f"ax {args[0]} failed (exit {done.returncode}): " + diagnostic(done.stderr))
        return done
    def _execute_attempt(self, item, output, attempt, attempts):
        pin_id = item.id
        digest = hashlib.sha256(f"{self.run}/{pin_id}/attempt-{attempt}".encode()).hexdigest()[:12]
        kind = re.sub(r"[^a-z0-9]+", "-", self.workload.kind.lower()).strip("-") or "pin"
        # Names are capped at 49 bytes: 14 (prefix) + kind + 1 + slug + 1 + 12 (digest).
        slug = re.sub(r"[^a-z0-9]+", "-", str(pin_id).lower()).strip("-")[: max(4, 21 - len(kind))]
        name = f"ousast-engine-{kind}-{slug or 'pin'}-{digest}"
        key_id = hashlib.sha256(str(pin_id).encode()).hexdigest()
        prefix = f"engine-queue/{self.run}/{key_id}/attempt-{attempt}/"
        keys = [prefix + item.object_names.get(key, key.lower() + PRESIGNED_ARCHIVE_SUFFIX) for key in item.inputs]
        keys.append(prefix + item.result_object)
        part_keys = []
        expires = timedelta(seconds=self.workload.deadline + 600)
        worker_ip = None
        submitted = False
        started = self.clock()
        phase = ""
        try:
            for env, key, data in zip(item.inputs, keys, item.inputs.values(), strict=False):
                if env == "VERIFY_INPUT_URL":
                    import io
                    from openultrasast.search.verify_task import MAX_PART_BYTES, upload_parts
                    count = (len(data) + MAX_PART_BYTES - 1) // MAX_PART_BYTES
                    destinations = [key + f".part-{index}" for index in range(count)]
                    part_keys.extend(destinations)
                    put_urls = [self.store.presign_put(part, expires) for part in destinations]
                    get_urls = [self.store.presign_get(part, expires) for part in destinations]
                    if any(public_endpoint(url) != self.host for url in put_urls + get_urls):
                        raise EgressError("archive part hostname must match store egress policy")
                    from openultrasast.search.executor import URLTransport
                    data = upload_parts(
                        io.BytesIO(data), lambda url, block: URLTransport().put(url, block, self.workload.deadline), put_urls
                    )
                    data = json.loads(data)
                    for part, url in zip(data["parts"], get_urls, strict=True):
                        part["url"] = url
                    data = json.dumps(data).encode()
                self.store._put(key, data)
            urls = {env: self.store.presign_get(key, expires) for env, key in zip(item.inputs, keys, strict=False)}
            urls["RESULT_URL"] = self.store.presign_put(keys[-1], expires)
            if any(public_endpoint(url) != self.host for url in urls.values()):
                raise EgressError("AX presign hostname must match S3_ENDPOINT for the store egress policy")
            document = manifest(name, self.workload, item, urls, self.args.atespace)
            end = self.clock() + self.workload.deadline
            # An apply timeout can still have created the task; cleanup must cover it.
            submitted = True
            try:
                apply_when_available(self, document, end)
            except CapacityDeadline:
                submitted = False  # All applies were explicitly rejected.
                raise
            while self.clock() < end:
                result = bounded_read(lambda: self.store._get(keys[-1]), end - self.clock())
                if self.clock() >= end:
                    return None, worker_ip
                phase = ""
                try:
                    state = self.ax("get", "tasks", timeout=min(30, end - self.clock())).stdout
                    phase, ip = task_state(state, name)
                    worker_ip = ip or worker_ip
                except (ValueError, OSError, subprocess.SubprocessError):
                    # The object is authoritative even when AX status is temporarily unavailable.
                    pass
                if self.clock() >= end:
                    return None, worker_ip
                if result is not None:
                    self.workload.validate(result[0], output)
                    return subprocess.CompletedProcess([], 0, "", ""), worker_ip
                if phase.lower() in {"failed", "missing"}:
                    # The worker may have uploaded while we were reading AX status.
                    result = bounded_read(lambda: self.store._get(keys[-1]), end - self.clock())
                    if self.clock() >= end:
                        return None, worker_ip
                    if result is not None:
                        self.workload.validate(result[0], output)
                        return subprocess.CompletedProcess([], 0, "", ""), worker_ip
                    raise SandboxFailure
                self.pause(min(2, max(0, end - self.clock())))
            return None, worker_ip
        except (subprocess.TimeoutExpired, TimeoutError) as exc:
            return subprocess.CompletedProcess([], 1, "", exception_reason(exc)), worker_ip
        except (SandboxFailure, CapacityDeadline):
            raise
        except Exception as exc:
            # Never expose exception strings which may contain object-scoped bearer URLs.
            detail = exception_reason(exc)
            return subprocess.CompletedProcess([], 1, "", "AX transport failed: " + detail), worker_ip
        finally:
            attempts.append({"name": name, "phase": phase, "seconds": self.clock() - started})
            errors = []
            if submitted:
                try:
                    self.ax("delete", "task", name)
                except Exception as exc:
                    # A successful list already confirmed a disappeared task is gone.
                    if phase != "Missing":
                        errors.append("task: " + exception_reason(exc))
            for key in [*keys, *part_keys]:
                try:
                    self.store._delete(key)
                except Exception as exc:
                    errors.append("object: " + exception_reason(exc))
            if errors:
                raise RuntimeError("AX cleanup failed; stop dispatching: " + ", ".join(errors))
@dataclass
 class Item:
    id: str
    inputs: dict[str, bytes]
    result_object: str
    command: tuple[str, ...]
    extra_env: dict[str, str]
    input_digest: str
    object_names: dict[str, str] = field(default_factory=dict)
@dataclass(frozen=True)
 class Workload:
    image: str
    url_env: frozenset[str]
    deadline: float
    validate: object
    # Task-name prefix after "ousast-engine-"; the operator's per-host egress rules match on it.
    kind: str = "pin"
 def validate_image(image):
    if not re.fullmatch(r"[^\s@]+@sha256:[0-9a-f]{64}", image):
        raise ValueError("AX --image must be pinned by sha256 digest")
 def manifest(name, workload, item, urls, atespace="default", *, validate_name=True):
    validate_image(workload.image)
    if validate_name and (not re.fullmatch(r"ousast-engine-[a-z0-9-]+", name) or len(name.encode()) > 49):
        raise ValueError("invalid AX task name")
    if set(urls) != workload.url_env:
        raise ValueError("unexpected URL environment names")
    # Fixed names and semantic values, never inherited environment or credentials.
    patterns = {
        "OUSAST_SCRATCH_BYTES": r"[1-9][0-9]*",
        "DEADLINE": r"[0-9]+(?:\.[0-9]+)?",
        "QUESTION_DEADLINE": r"[0-9]+(?:\.[0-9]+)?",
        "SEARCH_STEP": r"reason|explore|verify",
        "SEARCH_ID": r"[a-z0-9][a-z0-9-]{0,63}",
        "SEARCH_TASK_ID": r"[a-z0-9][a-z0-9-]{0,63}",
    }
    if any(key not in patterns or not re.fullmatch(patterns[key], str(value)) for key, value in item.extra_env.items()):
        raise ValueError("unexpected task environment")
    if set(item.extra_env) & set(urls):
        raise ValueError("overlapping task environment")
    for key, value in urls.items():
        if key == "PREPARED_PART_URLS":
            from openultrasast.search.verify_task import MAX_PARTS
            parts = json.loads(value)
            if not isinstance(parts, list) or len(parts) != MAX_PARTS:
                raise ValueError("invalid prepared part URLs")
            for url in parts:
                public_endpoint(url)
        else:
            public_endpoint(value)
    env = [{"name": key, "value": str(value)} for key, value in {**urls, **item.extra_env}.items()]
    if len(json.dumps(env).encode()) >= 32768:
        raise ValueError("AX Task env exceeds the 32 KB limit")
    return {
        "apiVersion": "ax.io/v1alpha1",
        "kind": "Task",
        "metadata": {"name": name, "atespace": atespace},
        "spec": {"image": workload.image, "env": env, "command": list(item.command)},
    }
 def write_json(path, record):
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_suffix(".tmp")
    temporary.write_text(json.dumps(record, sort_keys=True) + "\n")
    temporary.replace(path)
 def schedule(pending, lanes, out, execute, complete, *, fallbacks=(), overflow=True, progress=None):
    """The sole progress writer; callbacks carry workload-specific records, never transport."""
    if sum(lane in {"ax", "kind"} for lane in lanes) > 2 or lanes.count("docker") > 1:
        raise ValueError("at most two AX lanes and one VM lane")
    pending, fallbacks = deque(pending), deque(fallbacks)
    progress = progress if progress is not None else {"pins_done": 0, "pins_total": len(pending) + len(fallbacks)}
    progress["lanes"] = dict(Counter(lanes))
    active = {}
    failures = False
    def persist():
        progress.update(pins_in_flight=len(active), active_lanes=dict(Counter(lane for _, lane in active.values())))
        if any(lane in {"ax", "kind"} for lane in lanes):
            progress["fallbacks_pending"] = len(fallbacks)
        write_json(out / "progress.json", progress)
    with ThreadPoolExecutor(max_workers=len(lanes)) as pool:
        def launch(lane):
            if (out / "STOP").exists():
                return
            if lane == "docker" and fallbacks:
                item, previous = fallbacks.popleft()
            elif pending and (lane != "docker" or overflow):
                item, previous = pending.popleft(), None
            else:
                return
            active[pool.submit(execute, item, lane, previous)] = item, lane
        for lane in lanes:
            launch(lane)
        persist()
        try:
            while active:
                finished, _ = wait(active, return_when=FIRST_COMPLETED)
                # Resolve ALL completed futures before launching; cleanup exceptions stop launches.
                results = [(active.pop(future), future.result()) for future in finished]
                for (item, lane), result in results:
                    failed, fallback = complete(item, lane, result, progress)
                    if fallback is not None:
                        fallbacks.append((item, fallback))
                    else:
                        failures |= failed
                        progress["pins_done"] += 1
                for lane, count in (Counter(lanes) - Counter(lane for _, lane in active.values())).items():
                    for _ in range(count):
                        launch(lane)
                persist()
        finally:
            persist()
    return failures
 def dispatch(items, workload, out, executors, *, lanes=("ax", "ax", "docker"), overflow=True, max_attempts=2):
    """Digest checkpoints, one instrument rerun, sandbox retry, priority VM fallback."""
    if not isinstance(max_attempts, int) or not 1 <= max_attempts <= 2:
        raise ValueError("batch attempts must be one or two")
    out.mkdir(parents=True, exist_ok=True)
    items = list(items)
    if len({item.id for item in items}) != len(items):
        raise ValueError("duplicate dispatch item id")
    pending, fallbacks = [], []
    def path(item):
        return out / (hashlib.sha256(item.id.encode()).hexdigest() + ".json")
    for item in items:
        previous = json.loads(path(item).read_text()) if path(item).exists() else {}
        if previous.get("input_digest") == item.input_digest:
            if previous.get("fallback_pending"):
                fallbacks.append((item, previous))
                continue
            if previous.get("done"):
                continue
        pending.append(item)
    def execute(item, lane, previous):
        output = out / hashlib.sha256(item.id.encode()).hexdigest()
        output.mkdir(exist_ok=True)
        attempts = []
        for attempt in range(max_attempts):
            attempt_output = output / ("attempt-" + uuid.uuid4().hex)
            attempt_output.mkdir()
            record = executors[lane](item, attempt_output, attempt)
            for artifact in attempt_output.iterdir():
                if artifact.is_file():
                    shutil.copyfile(artifact, output / artifact.name)
            attempts.append(
                {
                    "lane": lane,
                    "status": record.get("status"),
                    "attempt": attempt,
                    "transport": record.get("ax_attempts", []),
                    "docker_errors": record.get("docker_errors", []),
                }
            )
            if record.get("status") not in {"sandbox_failure", "instrument_failure"}:
                break
        return {**record, "attempts": (previous or {}).get("attempts", []) + attempts, "input_digest": item.input_digest, "done": True}
    def complete(item, lane, record, progress):
        fallback = lane in {"ax", "kind"} and record.get("status") in {"sandbox_failure", "oom"} and "docker" in lanes
        record["fallback_pending"] = fallback
        write_json(path(item), record)
        progress["last_item"] = hashlib.sha256(item.id.encode()).hexdigest()
        return record.get("status") not in {"ok", "unanalysable", "quick_only", "engine_covered"}, record if fallback else None
    return schedule(pending, lanes, out, execute, complete, fallbacks=fallbacks, overflow=overflow)
 def docker_diagnostic(text):
    """Bound diagnostics and remove bearer URLs, environment secrets and assignments."""
    return diagnostic(text or "", maximum=4000)
 class DockerLane(AXLane):
    """VM lane uses the same presigned-object protocol and pinned replay image."""
    def __init__(self, *args, runner=None, **kwargs):
        super().__init__(*args, **kwargs)
        self.runner = runner or subprocess.run
        self._prepared = False
    def __call__(self, item, output, attempt):
        self._diagnostics = []
        try:
            if not self._prepared:
                self._prepare_image()
                self._prepared = True
        except (ValueError, OSError, subprocess.SubprocessError) as exc:
            if not self._diagnostics:
                self._diagnostics.append({"step": "preflight", "exit_code": None, "stderr": docker_diagnostic(str(exc))})
            record = {"status": "instrument_failure", "docker_errors": self._diagnostics}
            write_json(output / "docker-error.json", record)
            return record
        try:
            record = super().__call__(item, output, attempt)
        finally:
            if self._diagnostics:
                write_json(output / "docker-error.json", {"docker_errors": self._diagnostics})
        if self._diagnostics:
            record["docker_errors"] = self._diagnostics
        return record
    def _run_docker(self, command, timeout):
        try:
            done = self.runner(command, capture_output=True, text=True, timeout=timeout)
        except (OSError, subprocess.SubprocessError) as exc:
            self._diagnostics.append(
                {"step": command[1], "exit_code": None, "stderr": docker_diagnostic(getattr(exc, "stderr", "") or exception_reason(exc))}
            )
            raise
        if done.returncode:
            self._diagnostics.append({"step": command[1], "exit_code": done.returncode, "stderr": docker_diagnostic(done.stderr)})
            raise ValueError(f"docker {command[1]} failed (exit {done.returncode}): " + diagnostic(done.stderr))
        return done
    def _prepare_image(self):
        # Docker's data root, not the coordinator checkout, is where layers consume space.
        root = self._run_docker(["docker", "info", "--format", "{{.DockerRootDir}}"], 30).stdout.strip()
        size = getattr(self.args, "docker_image_bytes", None)
        if not isinstance(size, int) or size <= 0:
            raise ValueError("set --docker-image-bytes to the unpacked image size upper bound before pulling")
        free = self.runner(["df", "-B1", "--output=avail", root], capture_output=True, text=True, timeout=30)
        if free.returncode:
            raise ValueError("cannot check free space on Docker data root")
        available = int(free.stdout.splitlines()[-1].strip())
        required = size + 1024**3
        if available < required:
            raise ValueError(f"refusing Docker pull: free bytes {available} below image + 1 GiB ({required})")
        self._run_docker(["docker", "pull", self.workload.image], 900)
    def _execute_attempt(self, item, output, attempt, attempts):
        # Reuse all object/validation/cleanup logic, replacing only the task runner.
        import copy
        lane = copy.copy(self)
        lane.ax = lane._docker_command
        lane._docker_name = None
        return AXLane._execute_attempt(lane, item, output, attempt, attempts)
    def _docker_command(self, *args, manifest=None, timeout=30):
        if args[0] == "apply":
            self._docker_name = manifest["metadata"]["name"]
            self._docker_created = True  # Even a failed run can leave a created container.
            command = [
                "docker",
                "run",
                "-d",
                "--runtime",
                "runc",
                "--pull",
                "never",
                "--name",
                self._docker_name,
                "--entrypoint",
                manifest["spec"]["command"][0],
            ]
            for env in manifest["spec"]["env"]:
                command += ["-e", env["name"] + "=" + env["value"]]
            command += [manifest["spec"]["image"], *manifest["spec"]["command"][1:]]
            if not {"openultrasast.search.executor", "openultrasast.search.verify_task"}.intersection(manifest["spec"]["command"]):
                command += ["--heap-profile", "vm"]
        elif args[0] == "get":
            command = ["docker", "inspect", "--format", "{{.State.Running}} {{.State.ExitCode}}", self._docker_name]
        else:
            if not getattr(self, "_docker_created", False):
                return subprocess.CompletedProcess([], 0, "", "")
            command = ["docker", "rm", "-f", self._docker_name or args[2]]
        try:
            done = self._run_docker(command, timeout)
        except ValueError:
            if args[0] == "delete" and "No such container" in self._diagnostics[-1]["stderr"]:
                self._diagnostics.pop()
                return subprocess.CompletedProcess(command, 0, "", "")
            raise
        if args[0] == "apply":
            self._docker_created = True
        if args[0] == "get":
            phase = "Running" if done.stdout.startswith("true") else "Failed"
            if phase == "Failed":
                logs = self._run_docker(["docker", "logs", "--tail", "10", self._docker_name], timeout)
                self._diagnostics.append(
                    {"step": "container", "exit_code": int(done.stdout.split()[-1]), "stderr": docker_diagnostic(logs.stderr)}
                )
            done.stdout = json.dumps({"metadata": {"name": self._docker_name}, "status": {"phase": phase}})
        return done
 class SearchExecutorTask:
    """Host-owned executor lifecycle using the shared AX/presigning transport.
    Supply a bounded tar archive of the checkout. The brain receives only the
    command PUT/result GET pair; the task receives their opposite permissions.
    Closing the context deletes the task even after an uncertain command.
    """
    def __init__(self, lane, checkout_archive, *, deadline=900):
        if not 0 < deadline <= 3600 or len(checkout_archive) > 128 * 1024**2:
            raise ValueError("executor task input limit")
        if isinstance(lane, DockerLane):
            import copy
            lane = copy.copy(lane)
            lane._diagnostics = []
            lane.ax = lane._docker_command
        self.lane, self.archive, self.deadline = lane, checkout_archive, deadline
        token = uuid.uuid4().hex[:20]
        self.name = "ousast-engine-search-exec-" + token
        self.keys = [f"engine-queue/search-exec/{token}/{name}" for name in ("repo.tar", "command.json", "result.json", "prepared.json")]
        from openultrasast.search.verify_task import MAX_PARTS
        self.keys.extend(self.keys[3] + f".part-{index}" for index in range(MAX_PARTS))
        self.submitted = False
        self.slot = False
    def __enter__(self):
        from openultrasast.search.executor import ObjectStoreExecutor
        self.end = time.monotonic() + self.deadline
        if not isinstance(self.lane, DockerLane):
            if not AX_SLOTS.acquire(timeout=self.deadline):
                raise CapacityDeadline("no free workers available before deadline")
            self.slot = True
        expires = timedelta(seconds=self.deadline + 600)
        store = self.lane.store
        try:
            if isinstance(self.lane, DockerLane):
                self.lane._run_docker(["docker", "image", "inspect", self.lane.workload.image], min(30, self.deadline))
            store._put(self.keys[0], self.archive)
            urls = {
                "REPO_URL": store.presign_get(self.keys[0], expires),
                "COMMAND_GET_URL": store.presign_get(self.keys[1], expires),
                "EXECUTOR_RESULT_PUT_URL": store.presign_put(self.keys[2], expires),
                "PREPARED_PUT_URL": store.presign_put(self.keys[3], expires),
            }
            part_urls = [store.presign_put(key, expires) for key in self.keys[4:]]
            command_put = store.presign_put(self.keys[1], expires)
            result_get = store.presign_get(self.keys[2], expires)
            if any(public_endpoint(url) != self.lane.host for url in [*urls.values(), *part_urls, command_put, result_get]):
                raise EgressError("executor presign hostname must match store egress policy")
            urls["PREPARED_PART_URLS"] = json.dumps(part_urls)
            work = Workload(self.lane.workload.image, frozenset(urls), self.deadline, None)
            item = Item(
                self.name,
                {},
                "result.json",
                (
                    "python3",
                    "-m",
                    "openultrasast.search.executor",
                    "--repo",
                    "/workspace/checkout",
                    "--task-boundary",
                    "--deadline",
                    str(self.deadline),
                ),
                {},
                "",
            )
            document = manifest(self.name, work, item, urls, self.lane.args.atespace)
            self.submitted = True
            try:
                apply_when_available(self.lane, document, self.end)
            except CapacityDeadline:
                self.submitted = False
                raise
            self.client = ObjectStoreExecutor(command_put, result_get)
            return self
        except BaseException as exc:
            self.__exit__(type(exc), exc, exc.__traceback__)
            raise
    def prepare(self, spec):
        """Check the export manifest and every fragment before handing off the archive."""
        remaining = min(300, self.end - time.monotonic())
        result = self.client.submit("prepare_verification", spec, timeout_seconds=remaining)
        self.preparation_result = result
        if result.get("status") != "ok":
            from openultrasast.search.task_storage import CommandFailure
            raise CommandFailure(
                result.get("phase", "build"), result.get("exit_code"), result.get("stderr", ""), result.get("reason", "could_not_build")
            )
        stored = bounded_read(lambda: self.lane.store._get(self.keys[3]), self.end - time.monotonic())
        if stored is None or hashlib.sha256(stored[0]).hexdigest() != result.get("sha256"):
            raise ValueError("executor archive missing or digest mismatch")
        import io
        from openultrasast.search.verify_task import assemble_parts
        def get(part):
            value = bounded_read(lambda: self.lane.store._get(self.keys[4 + part["index"]]), self.end - time.monotonic())
            if value is None:
                raise ValueError("executor archive part missing")
            return value[0]
        archive = io.BytesIO()
        assemble_parts(stored[0], archive, get)
        return archive.getvalue()
    def __exit__(self, exc_type, exc, traceback):
        errors = []
        if self.submitted:
            try:
                self.lane.ax("delete", "task", self.name)
                self.submitted = False
            except Exception as error:
                errors.append(exception_reason(error))
        for key in self.keys:
            try:
                self.lane.store._delete(key)
            except Exception as error:
                errors.append(exception_reason(error))
        if self.slot and not errors:
            AX_SLOTS.release()
            self.slot = False
        if errors:
            reason = "executor cleanup failed: " + ", ".join(errors)
            logging.getLogger(__name__).error("%s", reason)
            if exc is not None:
                exc.executor_cleanup_reason = reason
                exc.args = (str(exc) + "; " + reason,)
                return False
            raise RuntimeError(reason)
@@ -0,0 +1,67 @@
 """Dispatch the packaged no-model probe using the shared engine/replay transport.
 python -m benchmarks.ax.search_probe --lane ax --image IMAGE@sha256:DIGEST --out /tmp/probe
 For kind, select --lane kind and supply its --kubeconfig; Docker uses the same PUT protocol.
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 from pathlib import Path
 from benchmarks.ax.batch import AXLane, DockerLane, Item, Workload, dispatch, validate_image
 def validate_result(data: bytes, output: Path) -> None:
    if len(data) > 1024 * 1024:
        raise ValueError("oversized probe result")
    record = json.loads(data)
    if not isinstance(record, dict) or record.get("status") not in ("ok", "instrument_failure"):
        raise ValueError("invalid probe result")
    if record["status"] == "ok" and (
        set(record.get("oracles", {})) != {"sql", "path", "command", "ssrf", "xss"}
        or record.get("isolation_check", {}).get("status") not in ("ok", "skipped")
    ):
        raise ValueError("incomplete probe")
    (output / "result.json").write_text(json.dumps(record))
 def probe_workload(image: str, deadline: float = 900) -> Workload:
    validate_image(image)
    return Workload(image, frozenset({"RESULT_URL"}), deadline, validate_result, kind="search-probe")
 def probe_item(image: str) -> Item:
    return Item(
        "v1",
        {},
        "result.json",
        ("python3", "-m", "openultrasast.search.probe"),
        {},
        hashlib.sha256(("search-probe-v1:" + image).encode()).hexdigest(),
    )
 def run_probe(args) -> bool:
    workload = probe_workload(args.image, args.deadline)
    transport = (DockerLane if args.lane == "docker" else AXLane)(args, workload)
    return dispatch([probe_item(args.image)], workload, args.out, {args.lane: transport}, lanes=(args.lane,), max_attempts=1)
 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--image", required=True)
    parser.add_argument("--lane", choices=("ax", "kind", "docker"), default="ax")
    parser.add_argument("--out", required=True, type=Path)
    parser.add_argument("--deadline", type=float, default=900)
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--atespace", default="default")
    parser.add_argument("--kubeconfig")
    parser.add_argument("--docker-image-bytes", type=int)
    return 1 if run_probe(parser.parse_args()) else 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,124 @@
 """Dispatch three fresh key-free AX tasks for each verification side."""
 from __future__ import annotations
 import hashlib
 import json
 import math
 import uuid
 from pathlib import Path
 from benchmarks.ax.batch import AXLane, CapacityDeadline, Item, SearchExecutorTask, Workload, validate_image
 from openultrasast.search.budget import verification_run_seconds
 from openultrasast.search.verify import RunObservation, SideRecord
 from openultrasast.search.verify_task import MAX_RESULT_BYTES, pack_checkout
 def side_record(value):
    if not isinstance(value, dict) or value.get("isolation_mode") != "task-boundary":
        raise ValueError("missing task-boundary attestation")
    fields = SideRecord.__dataclass_fields__
    # AXLane adds transport metadata outside the task record.
    data = {key: value[key] for key in fields if key in value}
    if data.get("outcome") not in {"observed", "could_not_run", "could_not_build", "no_oracle", "inconclusive"}:
        raise ValueError("invalid side outcome")
    runs = data.get("runs")
    if not isinstance(runs, list) or len(runs) > 1:
        raise ValueError("task must return one repetition")
    for run in runs:
        if not isinstance(run, dict):
            raise ValueError("invalid observation")
        if type(run.get("observed")) is not bool or not isinstance(run.get("evidence"), str):
            raise ValueError("invalid observation")
    if data["outcome"] == "observed" and len(runs) != 1:
        raise ValueError("missing completed observation")
    for number in [
        data.get("elapsed_seconds"),
        *(data.get(k, 0) for k in ("build_seconds", "ready_seconds", "run_seconds", "scratch_peak_bytes")),
        *(run.get("elapsed_seconds") for run in runs),
    ]:
        if type(number) not in (int, float) or not math.isfinite(number) or number < 0:
            raise ValueError("invalid observation measurement")
    if not isinstance(data.get("reason"), str):
        raise ValueError("invalid side reason")
    data["runs"] = tuple(RunObservation(**run) for run in runs)
    return SideRecord(**data)
 def validate_result(data, output):
    if len(data) > MAX_RESULT_BYTES:
        raise ValueError("oversized side result")
    side_record(json.loads(data))
    output.mkdir(parents=True, exist_ok=True)
    (output / "result.json").write_bytes(data)
 class AXSideDispatcher:
    """Host adapter passed as verify(task_dispatcher=...); never caches runs."""
    def __init__(self, args, image, output, *, lane=None, prepare=None):
        validate_image(image)
        self.output = Path(output)
        self.args, self.image, self.lane = args, image, lane
        self.prepare = prepare
    def __call__(self, *, side, demo, family, timeout_seconds, fresh_task):
        if fresh_task is not True or side.command or side.build_command or side.dependencies:
            raise ValueError("verification accepts checkout and declarative inputs only")
        # The trusted host selects an executor for this side. Build/package work
        # finishes there before any verifier worker slot is acquired.
        workload = Workload(
            self.image,
            frozenset({"VERIFY_INPUT_URL", "RESULT_URL"}),
            verification_run_seconds(demo, timeout_seconds) + 60,
            validate_result,
            kind="search-verify",
        )
        lane = self.lane or AXLane(self.args, workload)
        spec = {"demo": demo, "family": family, "timeout_seconds": timeout_seconds}
        try:
            if self.prepare is not None:
                archive = self.prepare(side, spec)
            else:
                with SearchExecutorTask(lane, pack_checkout(side.checkout)) as executor:
                    archive = executor.prepare(spec)
        except (ValueError, CapacityDeadline) as exc:
            return SideRecord("could_not_build", (), 0, str(exc), isolation_mode="task-boundary")
        records = []
        for _ in range(3):
            identity = uuid.uuid4().hex
            item = Item(
                identity,
                {"VERIFY_INPUT_URL": archive},
                "result.json",
                ("python3", "-m", "openultrasast.search.verify_task"),
                {},
                hashlib.sha256(archive).hexdigest(),
            )
            output = self.output / identity
            output.mkdir(parents=True)
            raw = lane(item, output, 1)
            # Roundtrip enforces JSON types for test adapters as for remote tasks.
            if raw.get("status") == "capacity_timeout":
                return SideRecord("could_not_run", (), 0, "AX capacity deadline", isolation_mode="task-boundary")
            result = side_record(json.loads(json.dumps(raw)))
            records.append(result)
            if result.outcome != "observed":
                break
        last = records[-1]
        return SideRecord(
            last.outcome,
            tuple(run for r in records for run in r.runs),
            sum(r.elapsed_seconds for r in records),
            last.reason,
            sum(r.build_seconds for r in records),
            sum(r.ready_seconds for r in records),
            sum(r.run_seconds for r in records),
            max(r.scratch_peak_bytes for r in records),
            isolation_mode="task-boundary",
            chromium_no_sandbox=any(r.chromium_no_sandbox for r in records),
            phase=last.phase,
            exit_code=last.exit_code,
            stderr=last.stderr,
            stdout=last.stdout,
        )
@@ -16,13 +16,13 @@ import os
 import re
 import shutil
 import subprocess
 import sys
 import tempfile
 import textwrap
 import threading
 import time
 import tomllib
-from collections import Counter, defaultdict, deque
+from collections import Counter, defaultdict
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
 from pathlib import Path
 from engine_trace_k8s import IMAGE, Kubernetes
@@ -39,6 +39,9 @@ from openultrasast.plane.memory import FileStore
 from openultrasast.plane.tasks.alerts import engine_languages
 from openultrasast.preprocess import detect_language
 sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 from benchmarks.ax.batch import schedule
 ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_OUT = Path.home() / "ousast-results/plane/engine-trace"
 SNAPSHOT_FILES = (
@@ -47,6 +50,7 @@ SNAPSHOT_FILES = (
    "benchmarks/learn/engine_trace_k8s.py",
    "benchmarks/learn/engine_trace_queue.py",
    "benchmarks/learn/engine_trace_ax.py",
    "benchmarks/ax/batch.py",
    "benchmarks/learn/engine_task_entry.py",
    "benchmarks/learn/engine_worker_service.py",
    "benchmarks/learn/engine_trace_parse.py",
@@ -175,9 +179,11 @@ def make_plan(
 class Inputs:
    """Resolve spent corpora; fetch pair source commits into the host cache."""
-    def __init__(self, root, cache, allow_excerpt_fallback=False):
+    def __init__(self, root, cache, allow_excerpt_fallback=False, *, keep_sources=False, source_cache_mb=500):
        self.cache = cache
        self.allow_excerpt_fallback = allow_excerpt_fallback
        self.keep_sources = keep_sources
        self.source_cache_bytes = source_cache_mb * 1024 * 1024
        self.catalog_rows = defaultdict(list)
        for catalog in (root / "benchmarks/pairs").rglob("catalog.toml"):
            for item in tomllib.loads(catalog.read_text()).get("pair", []):
@@ -255,8 +261,30 @@ class Inputs:
            raise ValueError(f"missing catalog repository for {case.name}")
        return repo, parent if side == "vuln" else commit
    def source_path(self, repo, commit, roots):
        return self.cache / "trace-sources" / digest([repo, commit, roots])
    def prepare_source_cache(self):
        cache = self.cache / "trace-sources"
        cache.mkdir(parents=True, exist_ok=True)
        entries = []
        for entry in cache.iterdir():
            if entry.is_dir() and not entry.is_symlink():
                size = sum(p.stat().st_size for p in entry.rglob("*") if not p.is_symlink() and p.is_file())
                entries.append((entry.stat().st_mtime_ns, entry, size))
        total = sum(size for _, _, size in entries)
        for _, entry, size in sorted(entries):
            if total <= self.source_cache_bytes:
                break
            shutil.rmtree(entry)
            total -= size
        free = shutil.disk_usage(cache).free
        if free < 1.5 * 1024**3:
            raise OSError(f"refusing source fetch: {free / 1024**3:.2f} GB free at {cache}; at least 1.5 GB required")
    def fetch_source(self, repo, commit, roots):
-        clone = self.cache / "trace-sources" / digest([repo, commit, roots])
+        self.prepare_source_cache()
        clone = self.source_path(repo, commit, roots)
        clone.mkdir(parents=True, exist_ok=True)
        url = repo if repo.startswith("https://") else f"https://github.com/{repo.removesuffix('.git')}.git"
        env = {**os.environ, "GIT_TERMINAL_PROMPT": "0"}
@@ -344,6 +372,13 @@ class Inputs:
                for case, side in resolved:
                    _materialize_side(target, case, side=side)
                return {"mode": "excerpt-fallback", "reason": str(exc), "repo": repo, "commit": commit}
            finally:
                # Only the exported copy is used by executors. Drop the clone even
                # on a partial fetch, timeout, failed export or excerpt fallback.
                if not self.keep_sources:
                    clone = self.source_path(repo, commit, roots)
                    if clone.exists():
                        shutil.rmtree(clone)
            verify_functions(target, rows)
            return {**proof, "mode": "source", "repo": repo, "commit": commit}
        if all(r["source"] == "dev-php" for r in rows):
@@ -791,8 +826,8 @@ def run_plan(plan, source, provenance, inputs, args):
        "active_lanes": {},
    }
    counts = Counter()
-    pending = deque(plan)
+    pending = list(plan)
-    fallbacks = deque()
+    fallbacks = []
    if args.executor in {"ax", "mixed-ax"}:
        pending.clear()
        for pin in plan:
@@ -803,12 +838,6 @@ def run_plan(plan, source, provenance, inputs, args):
                fallbacks.append((pin, old))
            else:
                pending.append(pin)
    active = {}
    failures = False
    def persist():
        progress.update(pins_in_flight=len(active), active_lanes=dict(Counter(lane for _, lane in active.values())))
        write_json(args.out / "progress.json", progress)
    def execute(pin, lane, attempt=None):
        if not any(u["supported"] for u in pin["units"]):
@@ -825,52 +854,20 @@ def run_plan(plan, source, provenance, inputs, args):
            options.image = getattr(args, "docker_image", args.image)
        return run_pin(pin, source, provenance, inputs, args.out, options)
-    with ThreadPoolExecutor(max_workers=len(lanes)) as pool:
+    def complete(pin, lane, failed, progress):
        result = json.loads((args.out / pin_name(pin)).read_text())
        selected = {u["unit"] for u in pin["units"]}
        reasons = [u.get("reason", "") for u in result["units"] if u["unit"] in selected]
        sandbox_failed = args.executor == "mixed-ax" and result.get("container_exit") == 1 and "AX sandbox failed twice" in reasons
        if lane == "ax" and (sandbox_failed or any("JVM out of memory" in reason for reason in reasons)):
            result.update(fallback="vm-sandbox" if sandbox_failed else "vm-oom", fallback_pending=True)
            write_json(args.out / pin_name(pin), result)
            return False, result
        counts.update(u["status"] for u in result["units"] if u["unit"] in selected)
        progress.update(last_pin={"repo": pin["repo"], "pin": pin["pin"]}, statuses=dict(counts))
        return failed, None
-        def launch(lane):
+    return schedule(pending, lanes, args.out, execute, complete, fallbacks=fallbacks, overflow=args.executor != "ax", progress=progress)
            if (args.out / "STOP").exists():
                return
            attempt = None
            if lane == "docker" and fallbacks:
                pin, attempt = fallbacks.popleft()
            elif pending and not (args.executor == "ax" and lane == "docker"):
                pin = pending.popleft()
            else:
                return
            active[pool.submit(execute, pin, lane, attempt)] = (pin, lane)
        for lane in lanes:
            launch(lane)
        persist()
        while active:
            completed, _ = wait(active, return_when=FIRST_COMPLETED)
            for future in completed:
                pin, lane = active.pop(future)
                failed = future.result()
                result = json.loads((args.out / pin_name(pin)).read_text())
                selected = {u["unit"] for u in pin["units"]}
                reasons = [u.get("reason", "") for u in result["units"] if u["unit"] in selected]
                sandbox_failed = args.executor == "mixed-ax" and result.get("container_exit") == 1 and "AX sandbox failed twice" in reasons
                if lane == "ax" and (sandbox_failed or any("JVM out of memory" in reason for reason in reasons)):
                    result.update(fallback="vm-sandbox" if sandbox_failed else "vm-oom", fallback_pending=True)
                    write_json(args.out / pin_name(pin), result)
                    fallbacks.append((pin, result))
                    continue
                failures |= failed
                selected = {u["unit"] for u in pin["units"]}
                counts.update(u["status"] for u in result["units"] if u["unit"] in selected)
                progress.update(
                    pins_done=progress["pins_done"] + 1, last_pin={"repo": pin["repo"], "pin": pin["pin"]}, statuses=dict(counts)
                )
            idle = Counter(lanes) - Counter(lane for _, lane in active.values())
            # Give a waiting fallback priority over overflow on the single VM lane.
            for lane, count in idle.items():
                for _ in range(count):
                    launch(lane)
            if args.executor in {"ax", "mixed-ax"}:
                progress["fallbacks_pending"] = len(fallbacks)
            persist()
    return failures
 def main():
@@ -879,6 +876,8 @@ def main():
    parser.add_argument("--examples", type=Path, help="frozen example JSONL instead of the local memory store")
    parser.add_argument("--memory", type=Path, default=Path.home() / "ousast-results/plane/memory")
    parser.add_argument("--cache", type=Path, default=Path.home() / ".cache/openultrasast")
    parser.add_argument("--keep-sources", action="store_true", help="retain fetched sources after export (still subject to cache eviction)")
    parser.add_argument("--source-cache-mb", type=int, default=500, help="maximum retained source MB before each fetch (default: 500)")
    parser.add_argument("--out", type=Path, default=DEFAULT_OUT)
    parser.add_argument("--image", help="default: openultrasast:dev for Docker; public 2.0.1 image for k8s/mixed")
    parser.add_argument("--executor", choices=("docker", "k8s", "k8s-jobs", "mixed", "queue", "ax", "mixed-ax"), default="docker")
@@ -906,6 +905,8 @@ def main():
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--summary", action="store_true")
    args = parser.parse_args()
    if args.source_cache_mb < 0:
        parser.error("--source-cache-mb must be nonnegative")
    if args.parallel is None:
        args.parallel = 2 if args.executor in {"ax", "mixed-ax"} else 1
    if args.executor in {"ax", "mixed-ax"}:
@@ -946,7 +947,7 @@ def main():
        units = join_units(read_jsonl(args.units), examples, args.include_typescript)
    except ValueError as exc:
        parser.error(str(exc))
-    inputs = Inputs(ROOT, args.cache, args.allow_excerpt_fallback)
+    inputs = Inputs(ROOT, args.cache, args.allow_excerpt_fallback, keep_sources=args.keep_sources, source_cache_mb=args.source_cache_mb)
    # Resolve pair source names for leak-audit coverage before calculating the resume key.
    for unit in units:
        if unit.get("excerpt") or unit["source"].startswith("advisory-fixes"):
@@ -1,184 +1,50 @@
-"""Host-only AX Task transport; credentials never enter task manifests."""
+"""Engine workload adapter for the shared AX transport."""
 from __future__ import annotations
 import hashlib
 import io
 import ipaddress
 import json
 import os
 import queue
 import re
 import shutil
 import subprocess
 import sys
 import tarfile
 import tempfile
 import threading
 import time
 import uuid
 from datetime import timedelta
 from pathlib import Path
 from urllib.parse import urlsplit
-import yaml
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 from engine_trace_k8s import pack
-from openultrasast.config import load_dotenv
+from benchmarks.ax.batch import AXLane, Item, SandboxFailure, Workload, manifest
-from openultrasast.plane.memory import PRESIGNED_ARCHIVE_SUFFIX, S3Store, open_store
+from benchmarks.ax.batch import task_state as task_state
-
+from openultrasast.plane.memory import open_store as open_store
 class EgressError(ValueError):
    """Safe diagnostic without presigned URL contents."""
 class SandboxFailure(Exception):
    """A terminal AX task without an authoritative result object."""
 def public_endpoint(url):
    """Reject endpoints the actor's hostname-based HTTPS egress policy cannot reach."""
    parts = urlsplit(url)
    host = parts.hostname or ""
    try:
        ipaddress.ip_address(host)
        is_ip = True
    except ValueError:
        is_ip = False
    if (
        parts.scheme != "https"
        or not host
        or is_ip
        or "." not in host
        or host.endswith((".localhost", ".local", ".internal"))
        or parts.port not in (None, 443)
        or parts.username
        or parts.password
    ):
        raise EgressError(
            "AX requires a public HTTPS DNS hostname in S3_ENDPOINT and presigned URLs: "
            "the egress policy allows the store hostname on port 443 only (no IP or plain HTTP)"
        )
    return host.lower()
 def task_manifest(name, args, urls):
-    if not re.fullmatch(r"[^\s@]+@sha256:[0-9a-f]{64}", args.image):
+    return manifest(
-        raise ValueError("AX --image must be pinned by sha256 digest")
+        name, engine_workload(args, lambda *_: None), engine_item({}, "pin", b"", args), urls, args.atespace, validate_name=False
    if set(urls) != {"SOURCE_URL", "QUESTIONS_URL", "RESULT_URL"}:
        raise ValueError("AX Task accepts only source, questions and result presigned URLs")
    for url in urls.values():
        public_endpoint(url)
    env = [{"name": key, "value": value} for key, value in urls.items()]
    env.extend(
        {"name": key, "value": str(value)}
        for key, value in {"DEADLINE": args.deadline, "QUESTION_DEADLINE": args.question_deadline}.items()
    )
    if len(json.dumps(env).encode()) >= 32768:
        raise ValueError("AX Task env exceeds the 32 KB limit")
    return {
        "apiVersion": "ax.io/v1alpha1",
        "kind": "Task",
        "metadata": {"name": name, "atespace": args.atespace},
        "spec": {"image": args.image, "env": env, "command": ["python3", "/app/benchmarks/learn/engine_task_entry.py"]},
    }
-def task_state(text, name):
+def engine_workload(args, validate):
-    """Accept AX YAML/JSON output and its human-readable tasks table."""
+    return Workload(args.image, frozenset({"SOURCE_URL", "QUESTIONS_URL", "RESULT_URL"}), args.deadline, validate, kind="pass")
    try:
        doc = yaml.safe_load(text)
    except yaml.YAMLError:
        doc = None
    rows = doc.get("items", doc.get("tasks", [doc])) if isinstance(doc, dict) else doc if isinstance(doc, list) else []
    for row in rows:
        if not isinstance(row, dict) or row.get("metadata", {}).get("name", row.get("name")) != name:
            continue
        status = row.get("status", {})
        ip = next(
            (status.get(key) or row.get(key) for key in ("workerIP", "workerIp", "worker_ip", "ip") if status.get(key) or row.get(key)),
            None,
        )
        worker = status.get("worker")
        if not ip and isinstance(worker, dict):
            ip = worker.get("ip") or worker.get("address")
        return str(status.get("phase", row.get("phase", ""))), ip
    lines = [line.split() for line in text.splitlines() if line.strip()]
    if lines:
        headers = [re.sub(r"[^a-z]", "", cell.lower()) for cell in lines[0]]
        for cells in lines[1:]:
            if name not in cells:
                continue
            row = dict(zip(headers, cells, strict=False))
            phase = row.get("phase", row.get("status", ""))
            ip = row.get("workerip") or row.get("ip")
            if not ip:
                for cell in cells:
                    try:
                        ipaddress.ip_address(cell)
                        ip = cell
                        break
                    except ValueError:
                        pass
            return phase, None if ip in {"<none>", "-", ""} else ip
    listed = isinstance(doc, (dict, list)) or bool(lines and "name" in headers and {"phase", "status"}.intersection(headers))
    return "Missing" if listed else "", None
-def bounded_read(read, timeout):
+def engine_item(pin, pin_id, source, args):
-    """Do not let SDK retries postpone task teardown beyond the pin deadline.
+    return Item(
-
+        pin_id,
-    Only the read runs in a daemon thread; it cannot publish a late result to disk.
+        {"SOURCE_URL": source, "QUESTIONS_URL": json.dumps(pin).encode()},
-    No executor shutdown waits for an SDK call whose socket has stopped responding.
+        "result.dat",
-    """
+        ("python3", "/app/benchmarks/learn/engine_task_entry.py"),
-    if timeout <= 0:
+        {"DEADLINE": str(args.deadline), "QUESTION_DEADLINE": str(args.question_deadline)},
-        raise TimeoutError("AX result deadline")
+        "",
-    replies = queue.Queue(maxsize=1)
+        {"SOURCE_URL": "source.dat", "QUESTIONS_URL": "questions.json"},
-
+    )
    def fetch():
        try:
            replies.put((True, read()))
        except Exception as exc:
            replies.put((False, exc))
    threading.Thread(target=fetch, daemon=True, name="engine-ax-result-read").start()
    try:
        ok, result = replies.get(timeout=timeout)
    except queue.Empty:
        raise TimeoutError("AX result deadline") from None
    if not ok:
        raise result
    return result
-class AX:
+class AX(AXLane):
    def __init__(self, args, store=None, pause=time.sleep, clock=time.monotonic):
-        self.args = args
+        super().__init__(args, engine_workload(args, lambda *_: None), store, pause, clock)
        self.pause, self.clock = pause, clock
        self.run = uuid.uuid4().hex
        load_dotenv()
        self.host = public_endpoint(os.environ.get("S3_ENDPOINT", ""))
        # Validate the image before opening a store, whose constructor probes the bucket.
        task_manifest("validate", args, {key: f"https://{self.host}/" for key in ("SOURCE_URL", "QUESTIONS_URL", "RESULT_URL")})
        self.store = store if store is not None else open_store()
        if store is None and not isinstance(self.store, S3Store):
            raise ValueError("AX requires OUSAST_MEMORY=s3://bucket[/prefix]")
    def ax(self, *args, manifest=None, timeout=30):
        env = dict(os.environ)
        if self.args.kubeconfig:
            env["KUBECONFIG"] = str(Path(self.args.kubeconfig).expanduser())
        done = subprocess.run(
            [str(Path(self.args.ax_bin).expanduser()), *args, *(["--atespace", self.args.atespace] if args[0] != "apply" else [])],
            input=json.dumps(manifest) if manifest is not None else None,
            env=env,
            capture_output=True,
            text=True,
            timeout=max(0.01, timeout),
        )
        if done.returncode:
            # AX errors may echo manifest URLs; report only verb and exit code.
            raise ValueError(f"ax {args[0]} failed (exit {done.returncode})")
        return done
    def receive(self, data, output, pin):
        # Validate in isolation: malformed results must never become usable checkpoints.
@@ -220,11 +86,15 @@ class AX:
            shutil.copytree(root, output, dirs_exist_ok=True)
    def execute(self, checkout, output, pin, pin_id):
        import copy
        self = copy.copy(self)
        self.workload = engine_workload(self.args, lambda data, target: self.receive(data, target, pin))
        attempts = []
        try:
            for attempt in range(2):
                try:
-                    return self._execute_attempt(checkout, output, pin, pin_id, attempt, attempts)
+                    return self._execute_attempt(engine_item(pin, pin_id, pack(checkout), self.args), output, attempt, attempts)
                except SandboxFailure:
                    if attempt == 0:
                        self.pause(10)
@@ -236,84 +106,3 @@ class AX:
                record = json.loads(result_path.read_text())
                record["ax_attempts"] = attempts
                result_path.write_text(json.dumps(record))
    def _execute_attempt(self, checkout, output, pin, pin_id, attempt, attempts):
        digest = hashlib.sha256(f"{self.run}/{pin_id}/attempt-{attempt}".encode()).hexdigest()[:12]
        slug = re.sub(r"[^a-z0-9]+", "-", str(pin_id).lower()).strip("-")[:22]
        name = f"ousast-engine-{slug or 'pin'}-{digest}"
        key_id = hashlib.sha256(str(pin_id).encode()).hexdigest()
        prefix = f"engine-queue/{self.run}/{key_id}/attempt-{attempt}/"
        keys = [prefix + suffix for suffix in (f"source{PRESIGNED_ARCHIVE_SUFFIX}", "questions.json", f"result{PRESIGNED_ARCHIVE_SUFFIX}")]
        expires = timedelta(seconds=self.args.deadline + 600)
        worker_ip = None
        submitted = False
        started = self.clock()
        phase = ""
        try:
            self.store._put(keys[0], pack(checkout))
            self.store._put(keys[1], json.dumps(pin).encode())
            urls = {
                "SOURCE_URL": self.store.presign_get(keys[0], expires),
                "QUESTIONS_URL": self.store.presign_get(keys[1], expires),
                "RESULT_URL": self.store.presign_put(keys[2], expires),
            }
            if any(public_endpoint(url) != self.host for url in urls.values()):
                raise EgressError("AX presign hostname must match S3_ENDPOINT for the store egress policy")
            manifest = task_manifest(name, self.args, urls)
            end = self.clock() + self.args.deadline
            # An apply timeout can still have created the task; cleanup must cover it.
            submitted = True
            self.ax("apply", "-f", "-", manifest=manifest, timeout=min(30, self.args.deadline))
            while self.clock() < end:
                result = bounded_read(lambda: self.store._get(keys[2]), end - self.clock())
                if self.clock() >= end:
                    return None, worker_ip
                phase = ""
                try:
                    state = self.ax("get", "tasks", timeout=min(30, end - self.clock())).stdout
                    phase, ip = task_state(state, name)
                    worker_ip = ip or worker_ip
                except (ValueError, OSError, subprocess.SubprocessError):
                    # The object is authoritative even when AX status is temporarily unavailable.
                    pass
                if self.clock() >= end:
                    return None, worker_ip
                if result is not None:
                    self.receive(result[0], output, pin)
                    return subprocess.CompletedProcess([], 0, "", ""), worker_ip
                if phase.lower() in {"failed", "missing"}:
                    # The worker may have uploaded while we were reading AX status.
                    result = bounded_read(lambda: self.store._get(keys[2]), end - self.clock())
                    if self.clock() >= end:
                        return None, worker_ip
                    if result is not None:
                        self.receive(result[0], output, pin)
                        return subprocess.CompletedProcess([], 0, "", ""), worker_ip
                    raise SandboxFailure
                self.pause(min(2, max(0, end - self.clock())))
            return None, worker_ip
        except (subprocess.TimeoutExpired, TimeoutError):
            return None, worker_ip
        except SandboxFailure:
            raise
        except Exception as exc:
            # Never expose exception strings which may contain object-scoped bearer URLs.
            detail = str(exc) if isinstance(exc, EgressError) else type(exc).__name__
            return subprocess.CompletedProcess([], 1, "", "AX transport failed: " + detail), worker_ip
        finally:
            attempts.append({"name": name, "phase": phase, "seconds": self.clock() - started})
            errors = []
            if submitted:
                try:
                    self.ax("delete", "task", name)
                except Exception as exc:
                    # A successful list already confirmed a disappeared task is gone.
                    if phase != "Missing":
                        errors.append("task: " + type(exc).__name__)
            for key in keys:
                try:
                    self.store._delete(key)
                except Exception as exc:
                    errors.append("object: " + type(exc).__name__)
            if errors:
                raise RuntimeError("AX cleanup failed; stop dispatching: " + ", ".join(errors))
@@ -1,8 +1,8 @@
 {
-  "modules": 159,
+  "modules": 172,
  "counts": {
-    "load_bearing": 154,
+    "load_bearing": 166,
-    "standalone_capability": 5
+    "standalone_capability": 6
  },
  "orphaned": [],
  "standalone": {
@@ -10,6 +10,7 @@
    "mcp": "narrow MCP server over stdio; its own `ousast mcp` entry point and OpenCode integration",
    "push_inputs": "pre-push-safety-net task 1.2: offline input provenance validator; python -m openultrasast.push_inputs",
    "push_scoring": "pre-push-safety-net task 1.3: frozen-profile diagnostic outcome scorer; python -m openultrasast.push_scoring",
    "search.coordinator": "search-with-proof Req 1/2/4: injected search executor and offline board checkpoint inspector; agent worker pending",
    "skills": "skill router; consumed by mcp and by the OpenCode integration, not by the scan path"
  },
  "rows": [
@@ -637,6 +638,7 @@
        "push.runner",
        "push.snapshot",
        "push.vetoes",
        "search.worker",
        "tool_hunter"
      ]
    },
@@ -707,6 +709,7 @@
        "plane.budget",
        "plane.generate",
        "push.assistance",
        "search.worker",
        "tool_hunter"
      ]
    },
@@ -897,7 +900,10 @@
        "plane.tasks.remember",
        "plane.tasks.roles",
        "plane.tasks.verify",
-        "plane.workspaces"
+        "plane.workspaces",
        "search.board",
        "search.coordinator",
        "search.worker"
      ]
    },
    {
@@ -913,7 +919,9 @@
        "learn.program",
        "plane.generate",
        "plane.tasks.roles",
-        "plane.tasks.verify"
+        "plane.tasks.verify",
        "search.coordinator",
        "search.worker"
      ]
    },
    {
@@ -1000,7 +1008,9 @@
        "plane.generate",
        "plane.reconciler",
        "plane.tasks.loop",
-        "plane.tasks.remember"
+        "plane.tasks.remember",
        "search.board",
        "search.coordinator"
      ]
    },
    {
@@ -1229,6 +1239,7 @@
        "learn.compile",
        "learn.program",
        "model.endpoint",
        "search.worker",
        "tool_hunter"
      ]
    },
@@ -1241,6 +1252,7 @@
        "learn.compile",
        "learn.program",
        "model.endpoint",
        "search.worker",
        "tool_hunter"
      ]
    },
@@ -1553,7 +1565,10 @@
        "regress.candidate",
        "regress.recipes",
        "regress.safety",
-        "regress.verdict"
+        "regress.verdict",
        "search._sandbox",
        "search.executor",
        "search.verify"
      ]
    },
    {
@@ -1592,6 +1607,125 @@
        "scoring"
      ]
    },
    {
      "module": "search",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.coordinator",
        "search.executor",
        "search.oracles",
        "search.probe",
        "search.verify",
        "search.verify_task",
        "search.worker"
      ]
    },
    {
      "module": "search._sandbox",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.executor",
        "search.oracles",
        "search.probe",
        "search.verify",
        "search.worker"
      ]
    },
    {
      "module": "search.board",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.coordinator"
      ]
    },
    {
      "module": "search.budget",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.coordinator"
      ]
    },
    {
      "module": "search.coordinator",
      "classification": "standalone_capability",
      "reason": "search-with-proof Req 1/2/4: injected search executor and offline board checkpoint inspector; agent worker pending",
      "importers": [
        "search.worker"
      ]
    },
    {
      "module": "search.demo",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.executor",
        "search.verify",
        "search.verify_task",
        "search.worker"
      ]
    },
    {
      "module": "search.executor",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.executor",
      "importers": [
        "search.verify_task",
        "search.worker"
      ]
    },
    {
      "module": "search.oracles",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.oracles",
      "importers": [
        "search.probe",
        "search.verify"
      ]
    },
    {
      "module": "search.probe",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.probe",
      "importers": []
    },
    {
      "module": "search.task_storage",
      "classification": "load_bearing",
      "reason": "reachable from gate, map_gate, pair_gate, cli",
      "importers": [
        "search.executor",
        "search.verify",
        "search.verify_task"
      ]
    },
    {
      "module": "search.verify",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.verify",
      "importers": [
        "search.executor",
        "search.probe",
        "search.verify_task"
      ]
    },
    {
      "module": "search.verify_task",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.verify_task",
      "importers": [
        "search.executor"
      ]
    },
    {
      "module": "search.worker",
      "classification": "load_bearing",
      "reason": "python -m openultrasast.search.worker",
      "importers": []
    },
    {
      "module": "semantic",
      "classification": "load_bearing",
@@ -0,0 +1,86 @@
 {
  "count": 1029,
  "guard": "green",
  "sha256": "5a644a1e93c68a0a35c794e653286d0532b7eb8d757123ccce5f08b11bf9a4a2",
  "sources": {
    "harvest": {
      "bytes": 501031,
      "count": 467,
      "files": 3,
      "known_empty": false,
      "rows": 446,
      "skipped_values": 446
    },
    "measurements": {
      "bytes": 21169903,
      "count": 278,
      "files": 221,
      "known_empty": false,
      "rows": 376,
      "skipped_values": 681
    },
    "memory_local": {
      "bytes": 8084523,
      "count": 192,
      "files": 776,
      "known_empty": false,
      "rows": 759,
      "skipped_values": 2
    },
    "memory_s3": {
      "bytes": 15928676,
      "count": 572,
      "files": 1499,
      "known_empty": false,
      "rows": 1490,
      "skipped_values": 2
    },
    "pairs": {
      "bytes": 1680480,
      "count": 728,
      "files": 28,
      "known_empty": false,
      "rows": 900,
      "skipped_values": 1260
    },
    "pointers": {
      "bytes": 892448,
      "count": 537,
      "files": 7,
      "known_empty": false,
      "rows": 586,
      "skipped_values": 666
    },
    "populations": {
      "bytes": 32431,
      "count": 28,
      "files": 2,
      "known_empty": false,
      "rows": 28,
      "skipped_values": 0
    },
    "sweep": {
      "bytes": 34006439,
      "count": 1029,
      "files": 1619,
      "known_empty": false,
      "rows": 2155,
      "skipped_values": 0
    },
    "units": {
      "bytes": 319641,
      "count": 229,
      "files": 9,
      "known_empty": false,
      "rows": 642,
      "skipped_values": 0
    }
  },
  "test_exit_code": 0,
  "tests": {
    "errors": 0,
    "failures": 0,
    "skipped": 1,
    "tests": 41
  }
 }
@@ -0,0 +1,110 @@
 {
  "cleanup": "completed-before-checkpoint",
  "commit": "5dc86c2f3f54b4dfb59060c88fb3ab5b307ef448",
  "differences": 0,
  "image": "ghcr.io/norandom/ousast-engine-task@sha256:b73c9bbd48fbf39c14ac013e5b0ff0a9d536b3d6388b50b1bd4cddfa22264b91",
  "pins": [
    {
      "baseline_digest": "c12c675f816a24ab33a63336a21efdc93db10a37dcf83437d91bec6f728cef1f",
      "equal": true,
      "instrument": [
        {
          "bytes": 1761,
          "cpg_bytes": 138723,
          "jvm": [
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 11.88592994,
              "success": null
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 35.821929360999995,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 7.4493522819999995,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 2.9803447330000026,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 0.5151375319999971,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 9.691500790999996,
              "success": true
            }
          ]
        }
      ],
      "pin_digest": "63c992b500590a9d4b643c9458df1d6cf71d770b06cc70594acbdba99b06c00b",
      "record_digest": "c12c675f816a24ab33a63336a21efdc93db10a37dcf83437d91bec6f728cef1f",
      "seconds": 158.85258329089265
    },
    {
      "baseline_digest": "5a60ed069d99f9325a1d3f3a7612fcf0d853d4fabfd53add81151b051132a5ee",
      "equal": true,
      "instrument": [
        {
          "bytes": 1791,
          "cpg_bytes": 138886,
          "jvm": [
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 7.656527941999999,
              "success": null
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 27.532885242,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 9.524187851,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 5.0155780199999995,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 0.6809096819999993,
              "success": true
            },
            {
              "exit_code": null,
              "heap_mb": 1700,
              "seconds": 13.824248304000001,
              "success": true
            }
          ]
        }
      ],
      "pin_digest": "8bd2f48dfb2d00cfc5b60a5dee3a8c87e6970671121caa17221f2449c1254fb2",
      "record_digest": "5a60ed069d99f9325a1d3f3a7612fcf0d853d4fabfd53add81151b051132a5ee",
      "seconds": 142.5083134449087
    }
  ]
 }
@@ -0,0 +1,41 @@
 {
  "commit": "48ae918dec25119142ae781607ba99306ae5ec17",
  "fixture_bytes": 15374,
  "fixture_sha256": "dd3c774a47d553105ed85b9cea8810736c233f870e5a015559a1524d5db5a14d",
  "implementation_sha256": {
    "benchmarks/ax/batch.py": "37aecac93beb25c02826e81eacaf064fbebb447a998fe139f6d94a07035b8685",
    "benchmarks/unseen/replay.py": "32efb3e0b9e9d247f2780b5f3ceeb01b4c2cbda3656c75a741f9925621cfdfbc",
    "benchmarks/unseen/replay_entry.py": "994d8e239eb505dc2c5bad4cdb8b5d45967a8a2aa9ef48fb4c2f20ba45736280",
    "benchmarks/unseen/score.py": "56e0a7b34482b5d84df39824b8ee447c283e35bd932f38cfe692cf84cb52cef7"
  },
  "network_proofs": {
    "4.4": "coordinator_pending",
    "5.4": "coordinator_pending"
  },
  "scope": "offline synthetic scorer only",
  "score_command_exit": 0,
  "scorer_output_sha256": "77f154eedb6a4acd098ab63a0b17434291f0d226dabe8ac66f2e0b362154d002",
  "scorer_test_exit": 0,
  "scorer_tests": 14,
  "synthetic_records": 20,
  "uncommitted": true,
  "validation": {
    "generic_dispatcher_tests": {
      "exit_code": 0,
      "passed": 5
    },
    "mypy": 0,
    "proof_and_scorer_tests": {
      "exit_code": 0,
      "passed": 16
    },
    "requested_pytest": {
      "exit_code": 0,
      "passed": 279,
      "skipped": 8
    },
    "reserved_repository_guard": 0,
    "ruff_check": 0,
    "ruff_format_check": 0
  }
 }
@@ -0,0 +1,74 @@
 {
  "biases": [
    "known_vulnerable_location",
    "labelled_family",
    "runnable_project_preference"
  ],
  "catalogs": {
    "bytes": 904050,
    "files": 10,
    "rows": 873
  },
  "eligible_pairs": 192,
  "eligible_repositories": 192,
  "exclusions": {
    "bytes": 0,
    "count": 0,
    "files": 0,
    "ledger_rows": 0,
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "gap_to_target": 0,
  "guard": {
    "guard": "green",
    "test_exit_code": 0,
    "tests": {
      "errors": 0,
      "failures": 0,
      "skipped": 1,
      "tests": 41
    }
  },
  "language_floor_gaps": {
    "java": 0,
    "javascript": 0,
    "php": 0,
    "python": 0,
    "typescript": 0
  },
  "local_metadata": {
    "config_bytes": 0,
    "manifest_bytes": 0,
    "matched_checkouts": 0
  },
  "manifest_sha256": "b593d2760f525c38b205fb33866c383fead4666102a84a805150b32c55ceeb62",
  "per_family": {
    "injection": 5,
    "output_encoding": 5,
    "path": 5,
    "untrusted_destination": 5
  },
  "per_language": {
    "java": 4,
    "javascript": 4,
    "php": 4,
    "python": 4,
    "typescript": 4
  },
  "purpose": "feasibility_only",
  "qualification": "not_an_unseen_evaluation_or_block_admission",
  "rejected": {
    "commits": 60,
    "family": 62,
    "language": 100,
    "location": 1,
    "not_development_fix": 453,
    "repository": 5
  },
  "seed": 20261005,
  "selected": 20,
  "status": "selected",
  "target": 20,
  "unknown_manifest": 20,
  "unknown_test_suite": 20
 }
@@ -0,0 +1,36 @@
 # Search-with-proof: first `demonstrated` (ceiling proof), 2026-10-06
 First end-to-end `demonstrated` verdict for the search-with-proof verifier. No model, no cluster, $0.
 Run locally in-process via `openultrasast.search.verify.verify` (non-task bubblewrap lane, userns, node v18.19.1).
 - Pair: glance (jarofghosts/glance), family **path**, index.js `Glance$serveRequest`.
 - Verdict: **demonstrated** — owned effect in 3/3 affected runs, 0/3 safe runs (zero false proof on the fixed side).
 - Vulnerable side: canary observed 3/3 (parent traversal reaches the out-of-root nonce file; app reflects it).
 - Fixed side: 0/3 (the fix commit's parent-escape guard returns 403; the traversal cannot escape).
 - Wall ~65 s for both sides x 3 runs; ready ~2 s/side.
 ## What this proves
 The execution harness, the path oracle, and the differential verifier are correct and CAN produce a
 `demonstrated` verdict on a real third-party app. The method's ceiling is reachable. Every prior pilot
 `inconclusive` on this pair was an instrument artifact, not a method verdict.
 ## Two defects that had masked this (both isolated, neither is the method)
 1. **Broken build.** `[email protected]` depends on an unpinned `mime >=1.2.6`; the checkout's regenerated
   lockfileVersion-3 pins `[email protected]`, where `.lookup()` was removed. glance crashes serving ANY file
   (`TypeError: mime.lookup is not a function`). Directory listing (readiness GET /) survives; the first
   file serve kills the process, so the nonce never reaches the response. Fixed here by installing a
   compatible `[email protected]` before the run.
 2. **Wrong demo target.** The stored agent demo traversed to a filename that is not the canary, so it
   404s even on the vulnerable side. The path oracle is the only owned oracle that hides its target from
   the demo author. The corrected demo targets the conventional `canary` file one level above the served
   root (same convention the known-good probe uses).
 ## Reproduction
 Demo schema + driver stored (gitignored) at `benchmarks/search/private/ceiling-proof-2026-10-06/`.
 Prepared checkouts need their npm symlinks stripped (the verifier refuses links) and a compatible
 `mime@1`. Payloads stay on disk per the classifier-safety note; never echoed.
 ## Follow-on for honest qualification at scale (not covered by this $0 proof)
 - Keystone: positive-control in `verify.py` so a broken app yields `could_not_run`, never `inconclusive`.
 - Build-repro: distrust generated npm locks; pin/override incompatible transitive deps; audit all 20 pairs.
 - Demo-authoring: document the path-oracle target convention so the search AGENT can author a hitting demo.
@@ -0,0 +1,123 @@
 {
  "record": "2026-10-06 search-with-proof feasibility pilot (path family, vulnerable side, cluster verify lane)",
  "image": "ghcr.io/norandom/ousast-search-task@sha256:60bfd73f...",
  "note": "First pilot after the verify-side keystone and the agent-side path-oracle target-parity fix. Feasibility only; payloads/boards live in the gitignored private area.",
  "ceiling_usd": 3.0,
  "searches": [
    {
      "pair_index": 3,
      "language": "php",
      "family": "path",
      "outcome": "inconclusive",
      "end_reason": "budget_spent",
      "end_detail": "demonstrations",
      "model_calls": 78,
      "executor_tasks": 12,
      "verify_tasks": 6,
      "settled_usd": 0.5779,
      "wall_seconds": 439,
      "failure_classes": [
        {
          "phase": "explore",
          "class": "no cli entrypoint exists"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify",
          "class": "noconsistentdifferential"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify",
          "class": "noconsistentdifferential"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from"
        },
        {
          "phase": "verify",
          "class": "noconsistentdifferential"
        }
      ]
    },
    {
      "pair_index": 9,
      "language": "typescript",
      "family": "path",
      "outcome": "plausible_unproven",
      "end_reason": "budget_spent",
      "end_detail": "reason_rounds",
      "model_calls": 154,
      "executor_tasks": 12,
      "verify_tasks": 0,
      "settled_usd": 1.1979,
      "wall_seconds": 2300,
      "failure_classes": []
    },
    {
      "pair_index": 13,
      "language": "python",
      "family": "path",
      "outcome": "plausible_unproven",
      "end_reason": "budget_spent",
      "end_detail": "run_ceiling",
      "model_calls": 118,
      "executor_tasks": 9,
      "verify_tasks": 0,
      "settled_usd": 1.1739,
      "wall_seconds": 564,
      "failure_classes": [
        {
          "phase": "explore",
          "class": "as predicted the parent"
        },
        {
          "phase": "explore",
          "class": "passfalse canary workspacecheckoutcanary passfalse"
        },
        {
          "phase": "explore",
          "class": "with the servedroot prefix"
        },
        {
          "phase": "explore",
          "class": "h check at filepy"
        },
        {
          "phase": "explore",
          "class": "are plain attribute reads"
        }
      ]
    }
  ],
  "aggregate": {
    "outcomes": {
      "inconclusive": 1,
      "plausible_unproven": 2
    },
    "demonstrations": 0,
    "false_proofs_fixed_side": 0,
    "settled_usd": 2.9496,
    "searches": 3
  },
  "finding": "Parity fix validated: the agent now runs directed, target-aware search toward the named observable (pair 13 reasoned explicitly about reaching it and inspected the app's file-serving guard). No demonstration: all three exhausted their per-pair allowance (demonstrations/reason_rounds/run_ceiling) before a differential; pairs 9 and 13 wrote 0 verify demos (budget consumed in reason/explore). Pair 3 (php) hit entrypoint-discovery failures (no CLI entrypoint / runtime entry missing). Cost ~$0.98/search, higher than the $0.2-0.5 estimate."
 }
@@ -0,0 +1,66 @@
 {
  "date": "2026-10-06",
  "image": "ghcr.io/norandom/ousast-search-task@sha256:32c7d23a41936c841b91edf27ded2d1fef5df9d656171e3ae199e7ed51ba0264",
  "image_tools": {
    "bwrap": "bubblewrap 0.12.0",
    "chromium": "Chromium 154.0.8037.92 built on Debian G",
    "java": "openjdk version \"21.0.12.1\" 2026-08-18\nO",
    "node": "v20.19.2",
    "php": "PHP 8.4.26 (cli) (built: Sep 24 2026 17:",
    "python": "Python 3.13.5",
    "sqlite": "3.46.1 2024-08-13 09:16:08 c9c2ab54ba1f5",
    "tsc": "Version 4.9.5"
  },
  "isolation_check": {
    "reason": "task-boundary",
    "status": "skipped"
  },
  "isolation_mode": "task-boundary",
  "lane": "kube-ax (AX task, gVisor, task-boundary)",
  "namespaces": {
    "cgroup": 1,
    "ipc": 1,
    "mount": 1,
    "net": 1,
    "pid": 1,
    "setpriv": 127,
    "user": 1,
    "uts": 1
  },
  "oracles": {
    "command": {
      "observer_access": "inconclusive",
      "real": "demonstrated",
      "revision_patch": "inconclusive"
    },
    "path": {
      "observer_access": "inconclusive",
      "real": "demonstrated",
      "revision_patch": "inconclusive"
    },
    "sql": {
      "observer_access": "inconclusive",
      "real": "demonstrated",
      "revision_patch": "inconclusive"
    },
    "ssrf": {
      "observer_access": "inconclusive",
      "real": "demonstrated",
      "revision_patch": "inconclusive"
    },
    "xss": {
      "observer_access": "inconclusive",
      "real": "demonstrated",
      "revision_patch": "inconclusive"
    }
  },
  "peak_rss_kib": {
    "children": 460152,
    "self": 42172,
    "sum": 502324
  },
  "scratch_disk_bytes": 23040,
  "status": "ok",
  "task": "search-with-proof 3.2",
  "wall_seconds": 38.368433234
 }
@@ -0,0 +1,46 @@
 {
  "record": "2026-10-07 FIRST CLUSTER DEMONSTRATION for search-with-proof",
  "pair": {
    "index": 13,
    "repo": "hanxi/xiaomusic",
    "family": "path",
    "class": "prefix-check-bypass (startswith without separator)",
    "language": "python"
  },
  "image": "ghcr.io/norandom/ousast-search-task@sha256:e2c8b460...",
  "side": "vulnerable",
  "outcome": "demonstrated",
  "verify_tasks": 18,
  "model_calls": 55,
  "settled_usd": 0.3686,
  "wall_seconds": 2170,
  "false_proofs_fixed_side": 0,
  "demo_wires_served_root": true,
  "finding": "The agent autonomously produced a demonstrated finding on a real CVE fix-pair end to end on the kube-ax cluster: it found the prefix-bypass sink, wired the app's served directory to ${served_root} (prompted by the new served-root control-signal hint after an earlier mis-wire), targeted the oracle's prefix-sibling canary, and the differential verifier confirmed the owned effect on the vulnerable revision and its absence on the fixed revision. Cost $0.37, 55 model calls.",
  "fix_chain_that_enabled_it": [
    "parity: agent targets the observable",
    "verify-time-only: no explore reachability trap",
    "fair-share budget: authors+verifies within budget",
    "served-root guidance: wire the served dir to ${served_root}",
    "oracle prefix-bypass coverage: sibling canary for startswith-without-separator vulns",
    "control-signal feedback: served-root hint so the agent self-corrects wiring"
  ],
  "both_sides": {
    "vulnerable": {
      "outcome": "demonstrated",
      "settled_usd": 0.3686,
      "verify_tasks": 18,
      "model_calls": 55
    },
    "fixed_blind_negative": {
      "outcome": "inconclusive",
      "false_proof": false,
      "settled_usd": 0.5632,
      "verify_tasks": 18,
      "model_calls": 85,
      "note": "Agent searched the FIXED (safe) revision blind (no vuln knowledge); authored demos but the verifier found no effect -> no false proof (Req 6.3 negative)."
    },
    "pair_total_settled_usd": 1.224,
    "verdict": "True positive on the vulnerable revision, zero false proof on the fixed revision."
  }
 }
@@ -0,0 +1,58 @@
 {
  "record": "2026-10-07 search-with-proof validation of the explore-time reachability-trap fix (path family, vulnerable, cluster)",
  "compares_against": "benchmarks/measurements/2026-10-06-search-pilot-path",
  "ceiling_usd": 2.0,
  "searches": [
    {
      "pair_index": 9,
      "language": "typescript",
      "outcome": "inconclusive",
      "end_reason": "budget_spent",
      "end_detail": "reason_rounds",
      "model_calls": 170,
      "verify_tasks": 2,
      "settled_usd": 1.6032,
      "wall_seconds": 2281,
      "failure_classes": [
        {
          "phase": "explore",
          "class": "valueerror fact requires tool evidence"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from checkout"
        },
        {
          "phase": "verify/could_not_build",
          "class": "runtime entry missing from checkout"
        },
        {
          "phase": "verify",
          "class": "no consistent differential"
        }
      ]
    },
    {
      "pair_index": 13,
      "language": "python",
      "outcome": "plausible_unproven",
      "end_reason": "budget_spent",
      "end_detail": "run_ceiling",
      "model_calls": 36,
      "verify_tasks": 0,
      "settled_usd": 0.3418,
      "wall_seconds": 254,
      "failure_classes": []
    }
  ],
  "aggregate": {
    "outcomes": {
      "inconclusive": 1,
      "plausible_unproven": 1
    },
    "demonstrations": 0,
    "false_proofs_fixed_side": 0,
    "settled_usd": 1.945
  },
  "finding": "Trap fix validated behaviourally. TypeScript pair 9: now AUTHORS a demo (verify_tasks 0->2) where it wrote none before; the demo fails could_not_build ('runtime entry missing from checkout') -- an entrypoint/build issue, same class as the php pair. Python pair 13: no longer burns budget on the reachability dead-end (calls 118->36, $1.17->$0.34); its board shows efficient directed analysis that traced the full route-to-sink path and the app entrypoint, but it hit the per-run budget ceiling (run_ceiling) before authoring/verifying a demo. Still 0 demonstrations, 0 false proofs. Remaining blockers: (1) per-run budget/step allocation leaves no room to author+verify after analysis; (2) demo entrypoint/build (start.path) for compiled/served apps (ts, php)."
 }
@@ -0,0 +1,14 @@
 {
  "record": "2026-10-07 search-with-proof: Python pair re-validation of the per-search fair-share budget fix",
  "ceiling_usd": 1.5,
  "pair": {"index": 13, "language": "python", "family": "path"},
  "outcome": "inconclusive",
  "end_detail": "demonstrations",
  "verify_tasks": 18,
  "model_calls": 98,
  "settled_usd": 0.7411,
  "wall_seconds": 2722,
  "false_proofs_fixed_side": 0,
  "finding": "Budget fix VALIDATED: with a fair per-search share the Python agent completed the full loop and ran 18 verify tasks (0 before), authoring and verifying demos within budget. Still inconclusive ('no consistent differential'), zero false proofs. Structural root cause confirmed from the authored demo: it does NOT reference ${served_root} anywhere; the agent set the app's served-directory config (an app env var) to a value of its own rather than to the oracle placeholder ${served_root}, so the app served the wrong tree and the planted observable (which lives relative to ${served_root}) was never reachable. Next guidance lever: require the agent to point the application's served/root directory at ${served_root} (via arg, env, or config) for the path oracle, so the observable is in the served tree.",
  "progression": "parity fix -> agent targets observable; verify-time-only fix -> agent stops the explore reachability trap; budget fair-share -> agent authors+verifies within budget; remaining -> wire served dir to ${served_root}."
 }
@@ -0,0 +1,15 @@
 {
  "record": "2026-10-07 search-with-proof: Python pair re-validation after served-root-wiring guidance fix",
  "ceiling_usd": 1.5,
  "pair": {"index": 13, "language": "python", "family": "path"},
  "outcome": "inconclusive",
  "end_detail": "run_ceiling",
  "verify_tasks": 6,
  "model_calls": 164,
  "settled_usd": 1.4661,
  "wall_seconds": 2025,
  "false_proofs_fixed_side": 0,
  "demo_wires_served_root": true,
  "finding": "Served-root fix VALIDATED: the authored demo now references ${served_root} (it did not before). Still inconclusive, 0 false proofs. Two remaining issues: (1) the agent spread its budget across multiple disclosure vectors (the served-root traversal plus a separate temp-path approach) and hit the per-run ceiling (164 calls, $1.47 of $1.50) before converging on one working demo; (2) the committed demo's single traversal step did not produce a differential, so the exact traversal reaching the observable is not yet right. This is now the per-app exploit-authoring + convergence layer, the same layer the $0 local glance ceiling proof handled by a hand-authored demo.",
  "progression": "parity -> target-aware; verify-time-only -> no explore trap; fair-share budget -> authors+verifies; served-root -> wires the served dir; remaining -> exact traversal + convergence within budget."
 }
@@ -0,0 +1,12 @@
 {
  "record": "2026-10-07 xiaomusic vulnerable-side search on the oracle-broadened image (prefix-bypass canary present)",
  "image": "ghcr.io/norandom/ousast-search-task@sha256:e2c8b460...",
  "ceiling_usd": 1.5,
  "outcome": "inconclusive",
  "verify_tasks": 6,
  "model_calls": 49,
  "settled_usd": 0.2922,
  "false_proofs_fixed_side": 0,
  "finding": "Oracle broadening landed in the agent: the authored demo now TARGETS the new prefix-sibling vector (references the sibling leak file) instead of the parent-only canary. But it did not demonstrate: the agent set the app's served-directory env var to a value of its OWN instead of the ${served_root} placeholder, so the app served the wrong tree and the sibling canary was outside it (unreachable). This is the served-root-wiring behaviour recurring NONDETERMINISTICALLY (a prior run did wire ${served_root}; this one did not). Cheap ($0.29), ended naturally at 49 calls, not on budget. Remaining gap = agent RELIABILITY on one demo detail: the served-directory config VALUE must be the literal ${served_root}, not the agent's explore-time test path.",
  "progression": "oracle now covers the vuln class and the agent targets it; last-mile blocker is reliably setting the served-dir config to ${served_root}."
 }
@@ -0,0 +1,142 @@
 # Search feasibility tools
 Run these host-side tools from the repository root. Selection and executor smoke
 make no model calls; the pilot driver calls the configured model unless `--dry-run`
 is specified.
 ## Executor smoke
 ```sh
 python -m benchmarks.search.executor_smoke \
  --lane ax --image REGISTRY/IMAGE@sha256:DIGEST \
  --repo-url https://github.com/OWNER/REPOSITORY --commit FULL_SHA \
  --out /tmp/executor-smoke.json
 ```
 `--lane docker` uses the same object-store mailbox and an already available local
 image (`--pull never`). Both lanes need the existing batch transport's S3 store
 configuration; credentials stay on the host. Running this command contacts the
 store and task runner; the task fetches a shallow HTTPS checkout and installs
 dependencies. Offline unit tests replace those network operations with a fake lane.
 One managed executor receives clone, list, read, grep, install, trivial run, and
 stop commands. Acquisition uses `git init` plus a depth-one fetch of the exact
 commit, retrying initial egress failures for up to 60 seconds. Install recipes are
 fixed and chosen from root pip/npm/composer/Maven manifests. Caches, temporary
 files, and pip products live under `/workspace`. A repository without a recognised
 manifest produces an instrument failure. If no README exists, the smoke reads
 another listed file and records its size to establish that input was opened.
 The JSON record holds per-command executor and round-trip wall times, exit codes
 (null for file tools), observed output sizes, and sampled allocated workspace
 peak, including unlinked command logs. Samples are not an instantaneous disk
 quota. Output text and presigned URLs are omitted. Zero clone files, a successful
 install with no output in under one second, command failure, missing runtime
 output, and cleanup errors produce `instrument_failure` and CLI exit 1. Context
 cleanup attempts task deletion and removal of mailbox objects on failure as well
 as success.
 ## Pilot selection
 ```sh
 python -m benchmarks.search.pilot_select --seed 20261005
 ```
 Selection uses development catalog metadata only; it performs no downloads or
 model calls. It excludes unseen reservations and used sets, validates usage
 ledgers, and runs the existing reserved-repository guard as a black box. Additional
 local unseen metadata/ledgers can be supplied with `--exclude` and `--ledger`.
 Use `--cache` to inspect matching local checkouts for manifest/test-suite evidence;
 the default cache is `~/.cache/openultrasast/repos`. Cached metadata affects
 preference only and does not establish that the pinned revision builds.
 The selector never opens population v3 files itself.
 The default identity-bearing manifest is
 `benchmarks/search/private/pilot.json`, explicitly gitignored. The summary is
 `benchmarks/measurements/2026-10-05-search-pilot-selection/record.json`; it contains
 counts, selection biases, input instrumentation, and digests only. Neither output
 is overwritten. A successful selection is feasibility input, not evidence of
 buildability, oracle operation, unseen performance, or BLOCK eligibility.
 ## One-sided pilot driver (task 6.2)
 The shared virtualenv may be installed against another worktree; `PYTHONPATH`
 below explicitly selects this worktree's source.
 Offline probe, using a scripted model and in-process repository executor with real
 host verification (no network or provider calls):
 ```sh
 PYTHONPATH="$PWD/src" /home/mc/Source/OpenUltraSAST/.venv/bin/python -m benchmarks.search.pilot_run \
  --dry-run --side vulnerable --pairs 0 --ceiling-usd 0.50 \
  --out /tmp/search-pilot-dry.jsonl
 ```
 For three **live** searches, after the oracle infrastructure probe and budget
 approval, set `SEARCH_TASK_IMAGE` to the tested search image's complete
 `REGISTRY/IMAGE@sha256:DIGEST` reference, then run:
 ```sh
 PYTHONPATH="$PWD/src" /home/mc/Source/OpenUltraSAST/.venv/bin/python -m benchmarks.search.pilot_run \
  --manifest benchmarks/search/private/pilot.json \
  --side vulnerable --pairs 0,1,2 --ceiling-usd 1.50 \
  --verify-lane vm --image "${SEARCH_TASK_IMAGE:?Set the tested digest-pinned search image}" \
  --out benchmarks/measurements/2026-10-05-search-pilot-vulnerable.jsonl
 ```
 This command spends money and contacts AX and the store. The ceiling shown is an
 example for the three $0.50 searches, not evidence that a live run was approved or
 performed. Use a fresh output path; output files are never overwritten.
 The existing DeepSeek key/base URL environment variables and provider model/prices
 are reused (`deepseek-flash` by default). `.env` does not override exported values.
 Retries are disabled. Unknown models require both `--usd-per-mtok-in` and
 `--usd-per-mtok-out`. Every call reserves its conservative input-token bound plus
 `--max-tokens` output allowance against the task allowance and shared run ceiling;
 failed calls and calls with missing usage settle the maximum. Reservations in the
 record are cumulative admitted maxima, not outstanding spend. Their sum can exceed
 the ceiling when usage settlements release unused allowances. Settled spend remains
 bounded by the run ceiling and $0.50/search. Search defaults also cap reason rounds
 at 4, intents at 3 per round, explore at 15 minutes including acquisition, and demos
 at 3. Physical AX submissions and coordinator steps have separate 32-task caps.
 The board defaults to a private local FileStore under a fresh directory in
 `benchmarks/search/private/runs/`; `--board-memory` selects another board store URI.
 The AX mailbox still requires the existing `OUSAST_MEMORY=s3://bucket/prefix`, public
 HTTPS `S3_ENDPOINT`, and host store credentials. Board storage does not replace the
 mailbox. Executors receive only presigned object URLs. The brain runs on the VM;
 repository tools and build/export run in key-free AX executors. VM verification
 requires working user namespaces and consumes executor-built archives. `--verify-lane
 ax` switches to the existing dispatcher, with three fresh verifier tasks per side
 and no executor holding a worker slot during those repetitions.
 Each selected index produces a JSON line followed by one run summary: Req 3.4
 outcome, reserved/settled spend, calls, tokens, physical tasks, coordinator steps,
 phase timings, failure codes, input bytes, board bytes, end reason, and hashed
 repository/revision identities. The private board and checkouts contain identity-bearing
 data. The public JSONL omits raw model/executor diagnostics. Selection advantages
 are explicit in the summary; this is feasibility evidence, not BLOCK qualification.
 A fixed invocation creates a fresh board/demo and retains only the fixed revision.
 Its verifier runs two independent sets of repetitions on that same fixed revision;
 no vulnerable checkout or previously generated vulnerable demo is passed in.
 `fixed_effect_observed` reports a consistent owned effect on the first three fixed
 runs (`null` when unavailable or inconsistent). Such an effect requires adjudication;
 it is not promoted to a differential `demonstrated` outcome. The normal safe probe
 therefore ends `inconclusive`, never “not vulnerable”.
 Generic `injection` needs an `oracle` value of `sql` or `command` in the private
 manifest; without a subtype verification returns `no_oracle`. No subtype is guessed
 from repository names. The selected manifest's pair 1 currently lacks this metadata.
 Live transport, provider authentication/cost, real project buildability, and AX
 oracle operation must still be measured; an offline probe cannot establish them.
 ## Status (2026-10-07)
 The feasibility pilot achieved its first cluster `demonstrated` finding (xiaomusic, path /
 prefix-check-bypass): vulnerable side demonstrated, fixed side blind search produced no
 false proof. See `benchmarks/measurements/2026-10-07-search-first-cluster-demonstration/`.
 Outcomes and spend are aggregates only; stored demos and boards stay in the gitignored
 `benchmarks/search/private/` area. Pilot exit (≥5 demonstrations / 0 false proofs per
 family) and the ≥73-negative BLOCK qualification remain open.
@@ -0,0 +1,241 @@
 """Replay a stored pilot demo without a board or model; output DIR/record.json.
 Live execution acquires repositories inside executor tasks. Offline tests inject
 an in-process executor and a fake lane; this CLI itself is not an offline clone.
 """
 from __future__ import annotations
 import argparse
 import copy
 import json
 import re
 import tempfile
 import time
 from dataclasses import asdict
 from pathlib import Path
 from benchmarks.ax.batch import DockerLane
 from benchmarks.search.pilot_run import (
    FAMILY_ORACLES,
    AXLane,
    AXSideDispatcher,
    BrowserExecutor,
    Pilot,
    Side,
    Workload,
    diagnostic,
    digest,
    exception_reason,
    load_demo,
    validate_image,
    validate_oracle,
    validate_result,
    verification_run_seconds,
    verification_timeout,
    verify,
 )
 from openultrasast.search.verify import SideRecord
 class Replay(Pilot):
    """Reuse pilot acquisition/redaction without constructing its board or worker."""
    def __init__(self, args, root, lane, demo):
        self.args, self.root, self.lane = args, root, lane
        self.deadline = float("inf")
        self.row = dict(repo=args.repo_url, vulnerable=args.commit, fixed=args.fixed_commit or args.commit, file=demo["start"]["path"])
        self.record = dict(tasks_submitted=0, executor_tasks=0, verify_tasks=0, input_bytes=0, failures=[])
        self.preparations = []
    def prepare(self, revision, spec):
        row = dict(
            revision_digest=digest(revision),
            wall_seconds_by_phase={},
            build_exit_code=None,
            build_stderr_tail="",
            archive_bytes=0,
            archive_parts=0,
        )
        self.preparations.append(row)
        started = time.monotonic()
        task = None
        try:
            with self._executor(revision) as task:
                row["wall_seconds_by_phase"]["acquisition"] = time.monotonic() - started
                before = time.monotonic()
                try:
                    return task.prepare(spec)
                finally:
                    row["wall_seconds_by_phase"]["prepare_roundtrip"] = time.monotonic() - before
        except Exception as exc:
            self.failure("build_export", exc)
            # The dispatcher preserves build failure semantics and we retain diagnostics.
            raise ValueError(self.record["failures"][-1]["reason"]) from exc
        finally:
            result = getattr(task, "preparation_result", {})
            row["wall_seconds_by_phase"].update(result.get("wall_seconds_by_phase", {}))
            row.update(
                build_exit_code=result.get("exit_code"),
                build_stderr_tail=result.get("stderr", ""),
                archive_bytes=result.get("archive_bytes", 0),
                archive_parts=result.get("archive_parts", 0),
                wall_seconds=time.monotonic() - started,
            )
 def run_replay(args, root, *, lane=None):
    started = time.monotonic()
    demo = load_demo(args.demo)
    timeout = verification_timeout(demo)
    replay = Replay(args, root, lane, demo)
    record = dict(
        type="demo_replay",
        repo_digest=digest(args.repo_url),
        revision_digest=digest(args.commit),
        family=args.family,
        lane=args.lane,
        both=args.both,
        model_calls=0,
        spend_usd=0,
    )
    if args.both:
        record["fixed_revision_digest"] = digest(args.fixed_commit)
    if not FAMILY_ORACLES[args.family]:
        result = SideRecord("no_oracle", (), 0, "no configured owned oracle")
        sides = [] if args.both else [result]
    else:
        validate_oracle(args.family, demo["oracle"])
        workload = Workload(
            args.image,
            frozenset({"VERIFY_INPUT_URL", "RESULT_URL"}),
            verification_run_seconds(demo, timeout) + 60,
            validate_result,
            kind="search-verify",
        )
        lane = lane or (DockerLane if args.lane == "docker" else AXLane)(args, workload)
        if isinstance(lane, DockerLane):
            lane._diagnostics = []
            lane._prepare_image()
            lane._prepared = True
        replay.lane = copy.copy(lane)
        if isinstance(lane, DockerLane):
            replay.lane.ax = replay.lane._docker_command
        keys = [Side(root / "affected"), Side(root / "fixed")]
        pins = {keys[0].checkout: args.commit, keys[1].checkout: args.fixed_commit}
        def counted_lane(*a, **kw):
            replay.admit_task()
            replay.record["verify_tasks"] += 1
            return lane(*a, **kw)
        dispatcher = AXSideDispatcher(
            args, args.image, root / "verify", lane=counted_lane, prepare=lambda side, spec: replay.prepare(pins[side.checkout], spec)
        )
        def dispatch(**kwargs):
            before = time.monotonic()
            try:
                return dispatcher(**kwargs)
            except Exception as exc:
                replay.failure("verify", exc)
                return SideRecord(
                    "could_not_run", (), time.monotonic() - before, replay.record["failures"][-1]["reason"], isolation_mode="task-boundary"
                )
        if args.both:
            result = verify(
                *keys,
                args.demo,
                args.family,
                timeout_seconds=timeout,
                oracle=demo["oracle"],
                task_dispatcher=dispatch,
                browser=BrowserExecutor(task_boundary=True) if demo["oracle"] == "xss" else None,
            )
            sides = result.sides
        else:
            result = dispatch(side=keys[0], demo=demo, family=args.family, timeout_seconds=timeout, fresh_task=True)
            sides = [result]
    phases = {}
    for preparation in replay.preparations:
        for phase, seconds in preparation["wall_seconds_by_phase"].items():
            phases[phase] = phases.get(phase, 0) + seconds
    for phase in ("build", "ready", "run"):
        phases["verify_" + phase] = sum(getattr(s, phase + "_seconds") for s in sides)
    record.update(
        outcome=result.outcome,
        reason=result.reason,
        sides=[asdict(s) for s in sides],
        preparations=replay.preparations,
        **replay.record,
        wall_seconds_by_phase=phases,
        wall_seconds=time.monotonic() - started,
    )
    # Apply the pilot's diagnostic redaction to every free-form string, including evidence.
    private = tuple(str(v) for v in replay.row.values()) + (str(root), args.repo_url.removeprefix("https://github.com/"))
    def redact(value):
        if isinstance(value, str):
            return diagnostic(value, maximum=1500, private=private)
        if isinstance(value, list):
            return [redact(v) for v in value]
        if isinstance(value, dict):
            return {k: redact(v) for k, v in value.items()}
        return value
    return redact(record)
 def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    for flag in ("repo-url", "commit", "image"):
        parser.add_argument("--" + flag, required=True)
    parser.add_argument("--demo", type=Path, required=True)
    parser.add_argument("--family", choices=tuple(FAMILY_ORACLES), required=True)
    parser.add_argument("--lane", choices=("ax", "docker"), required=True)
    parser.add_argument("--out", type=Path, required=True)
    parser.add_argument("--both", action="store_true")
    parser.add_argument("--fixed-commit")
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--atespace", default="default")
    parser.add_argument("--kubeconfig")
    parser.add_argument("--docker-image-bytes", type=int)
    args = parser.parse_args(argv)
    if args.both != bool(args.fixed_commit):
        parser.error("--both and --fixed-commit must be supplied together")
    if not re.fullmatch(r"https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", args.repo_url):
        parser.error("credential-free GitHub HTTPS repository URL required")
    if any(not re.fullmatch(r"[0-9a-f]{40}", pin) for pin in (args.commit, args.fixed_commit) if pin is not None):
        parser.error("full lowercase commit SHA required")
    try:
        validate_image(args.image)
        load_demo(args.demo)
    except (ValueError, OSError) as exc:
        parser.error(str(exc))
    if args.lane == "docker" and (args.docker_image_bytes is None or args.docker_image_bytes <= 0):
        parser.error("docker requires --docker-image-bytes (unpacked image upper bound)")
    args.out.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory(prefix="demo-replay-") as directory:
        try:
            record = run_replay(args, Path(directory))
        except Exception as exc:
            record = dict(
                type="demo_replay",
                repo_digest=digest(args.repo_url),
                revision_digest=digest(args.commit),
                outcome="could_not_run",
                reason=exception_reason(exc, private=(args.repo_url, args.commit, args.fixed_commit or "", directory)),
                model_calls=0,
                spend_usd=0,
                sides=[],
            )
            if args.both:
                record["fixed_revision_digest"] = digest(args.fixed_commit)
    (args.out / "record.json").write_text(json.dumps(record, indent=2, allow_nan=False) + "\n")
    print(json.dumps(record, allow_nan=False))
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,190 @@
 """One no-model executor task; run as python -m benchmarks.search.executor_smoke.
 Runtime acquisition/install needs network inside the executor. Unit tests are offline.
 Records contain measurements and sanitized failure tails, never presigned bearer URLs.
 """
 from __future__ import annotations
 import argparse
 import io
 import json
 import re
 import tarfile
 import time
 from pathlib import Path
 from urllib.parse import urlsplit
 from benchmarks.ax.batch import AXLane, DockerLane, SearchExecutorTask, Workload, validate_image
 from openultrasast.search.task_storage import diagnostic, exception_reason
 # URL and pin are positional shell arguments, never interpolated into shell code.
 # Retry the initial acquisition for delayed task egress activation (at most 60 s).
 CLONE = """git init -q .
 git remote add origin "$1"
 end=$(($(date +%s) + 60))
 until git -c protocol.version=2 fetch --depth=1 origin "$2"; do
  test "$(date +%s)" -lt "$end" || exit 1
  sleep 3
 done
 git checkout -q --detach FETCH_HEAD
 test "$(git rev-parse HEAD)" = "$2"
 """
 def install_recipe(files):
    """Fixed recipes, selected from checkout root manifests only."""
    files = set(files)
    if "requirements.txt" in files:
        return "pip", ["python3", "-m", "pip", "install", "--target", "/workspace/packages", "-r", "requirements.txt"]
    if files & {"pyproject.toml", "setup.py", "setup.cfg"}:
        return "pip", ["python3", "-m", "pip", "install", "--target", "/workspace/packages", "."]
    if "package.json" in files:
        return "npm", ["npm", "ci" if "package-lock.json" in files else "install"]
    if "composer.json" in files:
        return "composer", ["composer", "install", "--no-interaction", "--prefer-dist"]
    if "pom.xml" in files:
        return "maven", ["mvn", "-B", "-Dmaven.repo.local=/workspace/.m2", "-DskipTests", "package"]
    raise ValueError("no recognised install manifest")
 def run_smoke(lane, repo_url, commit, *, deadline=900):
    record = {
        "status": "instrument_failure",
        "commands": [],
        "scratch_peak_bytes": 0,
        "scratch_measurement": "sampled workspace allocated bytes plus command logs",
        "model_calls": 0,
    }
    parts = urlsplit(repo_url)
    private = tuple(p for p in parts.path.split("/") if p) + (parts.path.rsplit("/", 1)[-1].removesuffix(".git"),)
    started = time.monotonic()
    try:
        parts = urlsplit(repo_url)
        if parts.scheme != "https" or not parts.hostname or parts.username or parts.password or parts.query or parts.fragment:
            raise ValueError("credential-free HTTPS repository URL required")
        if not re.fullmatch("[0-9a-f]{40}", commit):
            raise ValueError("full lowercase commit SHA required")
        archive = io.BytesIO()
        with tarfile.open(fileobj=archive, mode="w"):
            pass
        # The empty checkout is filled by the first command inside the key-free task.
        with SearchExecutorTask(lane, archive.getvalue(), deadline=deadline) as task:
            record["task"] = task.name
            def command(step, name, args):
                remaining = deadline - (time.monotonic() - started) - 2
                if remaining <= 0:
                    raise TimeoutError("smoke deadline")
                timeout = min(300, remaining)
                if name == "run":
                    args = {**args, "timeout_seconds": timeout}
                before = time.monotonic()
                try:
                    result = task.client.submit(
                        name, args, timeout_seconds=timeout, limits={"memory_bytes": 2 * 1024**3, "disk_bytes": 2 * 1024**3}
                    )
                except Exception as exc:
                    result = {
                        "error": type(exc).__name__,
                        "reason": exception_reason(exc, private=private),
                        "phase": "timeout" if isinstance(exc, TimeoutError) else "result upload",
                        "exit_code": None,
                        "stderr": "",
                    }
                output_bytes = sum(result.get(k + "_bytes", len(result.get(k, "").encode())) for k in ("stdout", "stderr"))
                if name != "run":
                    output_bytes = len(json.dumps(result).encode())
                row = {
                    "step": step,
                    "command": name,
                    "wall_seconds": result.get("wall_seconds", time.monotonic() - before),
                    "roundtrip_seconds": time.monotonic() - before,
                    "exit_code": result.get("exit_code"),
                    "output_bytes": output_bytes,
                    "scratch_peak_bytes": result.get("scratch_peak_bytes"),
                    "truncated": result.get("truncated", False),
                }
                if "input_bytes" in result:
                    row["input_bytes"] = result["input_bytes"]
                failed = (
                    result.get("error")
                    or result.get("timed_out")
                    or result.get("status") == "could_not_build"
                    or (name == "run" and result.get("exit_code") != 0)
                )
                if failed:
                    row.update(
                        phase=result.get("phase", "timeout" if result.get("timed_out") else "run"),
                        reason=diagnostic(
                            result.get("reason") or result.get("error") or f"CommandFailure: exit code {result.get('exit_code')}",
                            private=private,
                        ),
                        stderr=diagnostic(result.get("stderr", ""), maximum=4000, private=private),
                    )
                record["commands"].append(row)
                record["scratch_peak_bytes"] = max(record["scratch_peak_bytes"], result.get("scratch_peak_bytes", 0))
                if result.get("error") or result.get("timed_out") or result.get("status") == "could_not_build":
                    raise ValueError(step + " executor failure: " + row["reason"])
                if name == "run" and result.get("exit_code") != 0:
                    raise ValueError(step + " nonzero or missing exit code: " + row["reason"])
                if step == "install" and output_bytes == 0 and row["wall_seconds"] < 1:
                    raise ValueError("empty fast install: exit 0 with empty output in under 1 s")
                return result
            command("clone", "run", {"command": ["sh", "-ec", CLONE, "clone", repo_url, commit]})
            files = command("list_files", "list_files", {}).get("files", [])
            if not files:
                raise ValueError("clone yielded zero files")
            record["files_listed"] = len(files)
            readme = next((p for p in files if Path(p).name.lower().startswith("readme")), None)
            # Always open input even when the repository has no README.
            read = command("read_file", "read_file", {"path": readme or files[0]})
            record["readme_present"] = readme is not None
            record["input_bytes"] = read.get("input_bytes")
            if not isinstance(record["input_bytes"], int):
                raise ValueError("file read lacks input size")
            command("grep", "grep", {"pattern": "test"})
            recipe, argv = install_recipe(files)
            record["recipe"] = recipe
            command("install", "run", {"command": argv})
            trivial = ["node", "-e", "console.log(1)"] if recipe == "npm" else ["python3", "-c", "print(1)"]
            ran = command("trivial", "run", {"command": trivial})
            if ran.get("stdout", "").strip() != "1":
                raise ValueError("trivial command did not print 1")
            if not command("stop", "stop", {}).get("stopped"):
                raise ValueError("stop not acknowledged")
            record["status"] = "ok"
    except Exception as exc:
        record["status"] = "instrument_failure"
        record["reason"] = exception_reason(exc, private=private)
    record["wall_seconds"] = time.monotonic() - started
    return record
 def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--lane", choices=("ax", "docker"), required=True)
    parser.add_argument("--image", required=True)
    parser.add_argument("--repo-url", required=True)
    parser.add_argument("--commit", required=True)
    parser.add_argument("--out", type=Path, required=True, help="One JSON record")
    parser.add_argument("--deadline", type=float, default=900)
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--atespace", default="default")
    parser.add_argument("--kubeconfig")
    args = parser.parse_args(argv)
    try:
        validate_image(args.image)
        lane = (DockerLane if args.lane == "docker" else AXLane)(args, Workload(args.image, frozenset(), args.deadline, None))
        record = run_smoke(lane, args.repo_url, args.commit, deadline=args.deadline)
    except Exception as exc:
        record = {"status": "instrument_failure", "reason": "lane setup: " + exception_reason(exc)}
    args.out.parent.mkdir(parents=True, exist_ok=True)
    args.out.write_text(json.dumps(record, indent=2, sort_keys=True) + "\n")
    print(json.dumps(record))
    return int(record["status"] != "ok")
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,573 @@
 """One-sided feasibility searches. Live mode is opt-in by omitting --dry-run."""
 from __future__ import annotations
 import argparse
 import copy
 import hashlib
 import io
 import json
 import math
 import os
 import re
 import tarfile
 import time
 import uuid
 from collections import Counter
 from contextlib import contextmanager
 from dataclasses import replace
 from pathlib import Path
 from benchmarks.ax.batch import AXLane, ClusterUnavailable, SearchExecutorTask, Workload, validate_image
 from benchmarks.ax.search_verify import AXSideDispatcher, validate_result
 from benchmarks.search.executor_smoke import CLONE
 from openultrasast.config import load_dotenv
 from openultrasast.model.endpoint import (
    DEEPSEEK_BASE_ENV,
    DEEPSEEK_BASE_URL,
    DEEPSEEK_KEY_ENV,
    DEFAULT_DETECTOR_MODEL,
    Prices,
    price_of,
 )
 from openultrasast.plane.budget import BudgetExhausted, SpendBudget
 from openultrasast.plane.memory import FileStore, open_store
 from openultrasast.provider.openrouter import OpenRouterChatClient
 from openultrasast.search import _sandbox
 from openultrasast.search.board import Board
 from openultrasast.search.budget import SearchBudget, verification_run_seconds, verification_timeout
 from openultrasast.search.coordinator import Coordinator
 from openultrasast.search.demo import FAMILY_ORACLES, load_demo, validate_oracle
 from openultrasast.search.executor import InProcessExecutor
 from openultrasast.search.oracles import BrowserExecutor
 from openultrasast.search.probe import materialise
 from openultrasast.search.task_storage import diagnostic, exception_reason
 from openultrasast.search.verify import Side, VerificationRecord, verify
 from openultrasast.search.verify_task import extract_checkout, validate_spec
 from openultrasast.search.worker import StubModel, Worker
 def digest(value):
    return hashlib.sha256(value.encode()).hexdigest()
 def tool(name, **args):
    return {"tool_calls": [{"id": "call", "type": "function", "function": {"name": name, "arguments": json.dumps(args)}}]}
 def scripted(schema):
    return StubModel(
        [
            tool("read_file", path="app.py"),
            tool("write_demo", schema=schema),
            tool("finish", fact={"text": "Candidate demo", "evidence_refs": ["tool:1"], "demo": "demo/"}),
            *[{"content": "{}"} for _ in range(4)],
        ]
    )
 class RepositoryFailure(ValueError):
    """The selected checkout or candidate cannot be read."""
 class Pilot:
    def __init__(self, args, row, index, root, store, run_budget, client, prices, lane=None):
        self.args, self.root, self.lane = args, root, lane
        # Fixed searches retain no vulnerable pin, even in trusted verification state.
        self.row = {k: v for k, v in row.items() if args.side != "fixed" or k != "vulnerable"}
        self.phase = "setup"
        self.deadline = float("inf")
        self.record = dict(
            type="search",
            pair_index=index,
            side=args.side,
            repo_digest=digest(row["repo"]),
            revision_digest=digest(row[args.side]),
            family=row["family"],
            language=row["language"],
            dry_run=args.dry_run,
            fixed_effect_observed=None,
            outcome="no_evidence",
            end_reason="exhausted",
            end_detail=None,
            task_metrics=[],
            executor_task_metrics=[],
            tasks_submitted=0,
            executor_tasks=0,
            verify_tasks=0,
            input_bytes=0,
            wall_seconds_by_phase={},
            failures=[],
        )
        self.board = Board(store, "pilot-" + uuid.uuid4().hex, coordinator="pilot")
        self.board.commit(
            writer="pilot",
            hints=[
                dict(
                    id="candidate",
                    step="reason",
                    task_id="manifest",
                    text=json.dumps({k: row[k] for k in ("family", "file", "function", "oracle") if k in row}),
                )
            ],
        )
        self.worker = Worker(
            client,
            repo=root / "unmounted",
            demo=root / "demo",
            model=args.model,
            prices=prices,
            run_budget=run_budget,
            max_output_tokens=args.max_tokens,
        )
        self.family = row["family"]
        self.sides = None
        self.verifications = []
    def failure(self, phase, reason, command=None):
        private = tuple(str(v) for k, v in self.row.items() if k in {"repo", "file", "function", "vulnerable", "fixed"})
        private += (str(self.root), self.row["repo"].removeprefix("https://github.com/"))
        if isinstance(reason, BaseException):
            safe = exception_reason(reason, private=private)
        elif isinstance(reason, str) and re.match(r"^[A-Za-z_]\w*: ", reason):
            # Worker errors already carry a type. Preserve it when identity redaction
            # expands the message beyond the public record's tail limit.
            kind, message = reason.split(": ", 1)
            safe = kind + ": " + diagnostic(message, maximum=max(0, 298 - len(kind)), private=private)
        else:
            safe = diagnostic(reason, private=private)
        entry = dict(phase=phase, reason=safe)
        command = command if command is not None else reason
        if hasattr(command, "exit_code"):
            entry.update(
                command_phase=diagnostic(command.phase),
                exit_code=command.exit_code,
                stderr=diagnostic(command.stderr, maximum=1500, private=private),
                stdout=diagnostic(getattr(command, "stdout", ""), maximum=1500, private=private),
                ready_seconds=getattr(command, "ready_seconds", 0),
            )
        if (phase == "verify" or phase.startswith("verify/")) and entry.get("stderr"):
            entry["reason"] = entry["stderr"][-300:]
        self.record["failures"].append(entry)
    @contextmanager
    def executor(self, revision, deadline=900):
        before = time.monotonic()
        metrics = dict(self.worker.metrics)
        self.executor_end = "ok"
        submitted = self.record["executor_tasks"]
        try:
            with self._executor(revision, deadline) as task:
                yield task
        except BudgetExhausted as exc:
            self.executor_end = exc.end_detail
            raise
        except Exception:
            self.executor_end = "execution_failure"
            raise
        finally:
            if self.record["executor_tasks"] > submitted:
                self.record["executor_task_metrics"].append(
                    {
                        "executor_task": submitted + 1,
                        **{key: value - metrics[key] for key, value in self.worker.metrics.items()},
                        "wall_seconds": time.monotonic() - before,
                        "end": self.executor_end,
                    }
                )
    @contextmanager
    def _executor(self, revision, deadline=900):
        deadline = min(deadline, self.deadline - time.monotonic())
        if deadline < 1:
            raise BudgetExhausted("task deadline", usd=0, calls=0, end_detail="task_wall")
        acquired_at = time.monotonic()
        empty = io.BytesIO()
        with tarfile.open(fileobj=empty, mode="w"):
            pass
        self.admit_task()
        self.record["executor_tasks"] += 1
        with SearchExecutorTask(self.lane, empty.getvalue(), deadline=deadline) as task:
            remaining = deadline - (time.monotonic() - acquired_at)
            if remaining < 1:
                raise BudgetExhausted("acquisition deadline", usd=0, calls=0, end_detail="task_wall")
            timeout = min(180, remaining)
            result = task.client.submit(
                "run",
                {"command": ["sh", "-ec", CLONE, "clone", self.row["repo"], revision], "timeout_seconds": timeout},
                timeout_seconds=timeout,
            )
            if result.get("exit_code") != 0 or result.get("error"):
                self.failure("acquisition", "checkout_command_failed")
                raise RepositoryFailure("checkout failed")
            remaining = deadline - (time.monotonic() - acquired_at)
            if remaining < 1:
                raise BudgetExhausted("acquisition deadline", usd=0, calls=0, end_detail="task_wall")
            result = task.client.submit("read_file", {"path": self.row["file"]}, timeout_seconds=min(30, remaining))
            if not isinstance(result.get("input_bytes"), int) or result["input_bytes"] <= 0:
                self.failure("acquisition", "candidate_input_unreadable")
                raise RepositoryFailure("unreadable input")
            self.record["input_bytes"] += result["input_bytes"]
            yield task
    def admit_task(self):
        if self.record["tasks_submitted"] >= 32:
            raise BudgetExhausted("executor task cap", usd=0, calls=0, end_detail="tasks")
        self.record["tasks_submitted"] += 1
    def prepare(self, revision, spec):
        before = time.monotonic()
        try:
            with self.executor(revision) as task:
                return task.prepare(spec)
        except BudgetExhausted:
            raise
        except Exception as exc:
            self.failure("build_export", exc)
            raise
        finally:
            wall = self.record["wall_seconds_by_phase"]
            wall["build_export"] = wall.get("build_export", 0) + time.monotonic() - before
    def verification(self, limits=None):
        if not FAMILY_ORACLES[self.family]:
            return VerificationRecord("no_oracle", (), 0, "no configured owned oracle")
        demo = load_demo(self.root / "demo")
        validate_oracle(self.family, demo["oracle"])
        timeout = verification_timeout(demo, limits or self.worker.limits)
        if self.args.dry_run:
            sides = self.sides if self.args.side == "vulnerable" else (self.sides[1], self.sides[1])
            return verify(*sides, self.root / "demo", self.family, timeout_seconds=timeout, oracle=demo["oracle"])
        revisions = [self.row[self.args.side], self.row["fixed"]]
        if self.args.verify_lane == "ax":
            # Side paths are opaque lookup keys; no checkout or opposite revision reaches the brain.
            sides = [Side(self.root / str(i)) for i in range(2)]
            pins = {s.checkout: pin for s, pin in zip(sides, revisions, strict=True)}
            parent = self
            verify_lane = copy.copy(self.lane)
            verify_lane.workload = Workload(
                self.args.image,
                frozenset({"VERIFY_INPUT_URL", "RESULT_URL"}),
                verification_run_seconds(demo, timeout) + 60,
                validate_result,
                kind="search-verify",
            )
            class CountingLane:
                def __call__(self, *a, **kw):
                    parent.admit_task()
                    parent.record["verify_tasks"] += 1
                    return verify_lane(*a, **kw)
            dispatcher = AXSideDispatcher(
                self.args,
                self.args.image,
                self.root / "verify",
                lane=CountingLane(),
                prepare=lambda side, spec: self.prepare(pins[side.checkout], spec),
            )
            return verify(
                *sides,
                self.root / "demo",
                self.family,
                timeout_seconds=timeout,
                oracle=demo["oracle"],
                task_dispatcher=dispatcher,
                browser=BrowserExecutor(task_boundary=True) if demo["oracle"] == "xss" else None,
            )
        if _sandbox.isolation_mode() != "userns":
            raise _sandbox.IsolationUnavailable("VM verification requires userns")
        sides = []
        spec = dict(demo=demo, family=self.family, timeout_seconds=timeout)
        for revision in revisions:
            archive = self.prepare(revision, spec)
            bundle = self.root / ("built-" + uuid.uuid4().hex)
            extract_checkout(archive, bundle)
            sides.append(Side(bundle / "checkout", products=bundle / "products"))
            # Export contains the executor's build-free schema.
            (self.root / "verify-demo").mkdir(exist_ok=True)
            built_spec = validate_spec(json.loads((bundle / "spec.json").read_text()))
            expected_demo = {**demo, "build": {"recipe": "none", "arguments": []}}
            if built_spec != {**spec, "demo": expected_demo}:
                raise ValueError("executor altered verification contract")
            (self.root / "verify-demo/demo.json").write_text(json.dumps(built_spec["demo"]))
        return verify(
            *sides,
            self.root / "verify-demo",
            self.family,
            timeout_seconds=timeout,
            oracle=demo["oracle"],
            browser=BrowserExecutor() if demo["oracle"] == "xss" else None,
        )
    def dispatch(self, task):
        self.phase = task.step
        before = time.monotonic()
        self.deadline = before + task.limits.get("task_wall_seconds", 900)
        metrics_before = dict(self.worker.metrics)
        result = {}
        end = "execution_failure"
        try:
            if task.step == "verify":
                result = self.verification(task.limits)
                self.verifications.append(result.outcome)
                self.record["outcome"] = result.outcome
                if self.args.side == "fixed" and result.sides:
                    observations = result.sides[0]
                    if observations.outcome == "observed" and len(observations.runs) == 3:
                        effects = {r.observed for r in observations.runs}
                        if len(effects) == 1:
                            self.record["fixed_effect_observed"] = effects.pop()
                wall = self.record["wall_seconds_by_phase"]
                for phase in ("build", "ready", "run"):
                    wall["verify_" + phase] = wall.get("verify_" + phase, 0) + sum(getattr(s, phase + "_seconds") for s in result.sides)
                for side in result.sides:
                    if side.outcome != "observed":
                        self.failure("verify/" + side.outcome, side.reason, command=side)
                if result.outcome != "demonstrated":
                    self.failure("verify", "no_consistent_differential" if result.outcome == "inconclusive" else result.outcome)
                end = result.outcome
                return dict(
                    status="ok",
                    outcome=result.outcome,
                    evidence_refs=["verify:owned"],
                    cost_usd=0,
                    control_observed=result.sides[0].control_observed if result.sides else None,
                )
            if task.step == "explore":
                if self.args.dry_run:
                    self.worker.executor = InProcessExecutor(self.sides[0 if self.args.side == "vulnerable" else 1].checkout)
                    result = self.worker(task)
                else:
                    with self.executor(self.row[self.args.side], deadline=task.limits["task_wall_seconds"]) as remote:
                        self.worker.executor = remote.client
                        remaining = task.limits["task_wall_seconds"] - (time.monotonic() - before)
                        if remaining < 1:
                            raise BudgetExhausted("explore deadline", usd=0, calls=0, end_detail="task_wall")
                        result = self.worker(replace(task, limits={**task.limits, "task_wall_seconds": remaining}))
                        self.executor_end = result.get("end_detail") or result.get("status", "execution_failure")
            else:
                result = self.worker(task)
            end = result.get("end_detail") or result.get("status", "execution_failure")
            if result.get("status") != "ok":
                self.failure(task.step, result.get("failure", "worker_execution_failed"))
                if self.worker.metrics["model_calls"] == 0 and not result.get("budget_exhaustion"):
                    raise RuntimeError(self.record["failures"][-1]["reason"])
                if not self.verifications:
                    self.record["outcome"] = "inconclusive"
            return result
        except BudgetExhausted as exc:
            end = exc.end_detail
            raise
        finally:
            self.record["task_metrics"].append(
                {
                    "task_id": task.id,
                    "step": task.step,
                    **{key: value - metrics_before[key] for key, value in self.worker.metrics.items()},
                    "wall_seconds": time.monotonic() - before,
                    "end": end,
                }
            )
            wall = self.record["wall_seconds_by_phase"]
            wall[task.step] = wall.get(task.step, 0) + time.monotonic() - before
    def run(self):
        started = time.monotonic()
        coordinator = Coordinator(self.board, self.dispatch, budget=SearchBudget(retries=0))
        try:
            state = coordinator.run()
            self.record["end_reason"] = state["end_reason"]
            self.record["end_detail"] = state.get("end_detail")
            if not self.verifications and any(f.get("step") == "explore" for f in state["facts"]):
                self.record["outcome"] = "plausible_unproven"
        except Exception as exc:
            self.failure(self.phase, exc)
            self.record["outcome"] = (
                "could_not_build"
                if self.record["failures"] and any(f["phase"] in ("build_export", "acquisition") for f in self.record["failures"])
                else "inconclusive"
            )
            self.record["end_reason"] = "instrument_failure"
            if isinstance(exc, ClusterUnavailable) or (self.worker.metrics["model_calls"] == 0 and not isinstance(exc, RepositoryFailure)):
                self.record["aborted_reason"] = self.record["failures"][-1]["reason"]
        metrics = self.worker.metrics
        self.record.update(
            spend={k: metrics[k] for k in ("reserved", "settled")},
            **{k: metrics[k] for k in ("model_calls", "tokens_in", "tokens_out")},
            coordinator_tasks=coordinator.progress["tasks"],
            board_bytes=len(json.dumps(self.board.state).encode()),
            wall_seconds=time.monotonic() - started,
        )
        return self.record
 def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--side", choices=("vulnerable", "fixed"), required=True)
    parser.add_argument("--pairs", required=True)
    parser.add_argument("--ceiling-usd", required=True, type=float)
    parser.add_argument("--manifest", type=Path, default=Path("benchmarks/search/private/pilot.json"))
    parser.add_argument("--private-root", type=Path, default=Path("benchmarks/search/private/runs"))
    parser.add_argument("--out", type=Path, required=True)
    parser.add_argument("--board-memory", help="Memory store URI; defaults to a private local FileStore")
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--verify-lane", choices=("vm", "ax"), default="vm")
    parser.add_argument("--model", default=DEFAULT_DETECTOR_MODEL)
    parser.add_argument("--max-tokens", type=int, default=4096)
    parser.add_argument("--usd-per-mtok-in", type=float)
    parser.add_argument("--usd-per-mtok-out", type=float)
    parser.add_argument("--image")
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--atespace", default="default")
    parser.add_argument("--kubeconfig")
    args = parser.parse_args(argv)
    if not math.isfinite(args.ceiling_usd) or args.ceiling_usd < 0:
        parser.error("ceiling must be finite and nonnegative")
    remaining_ceiling = args.ceiling_usd
    if not re.fullmatch(r"\d+(,\d+)*", args.pairs) or args.max_tokens < 1:
        parser.error("pairs must be comma-separated nonnegative indices; max tokens must be positive")
    indices = [int(i) for i in args.pairs.split(",")]
    if len(indices) != len(set(indices)):
        parser.error("duplicate pair indices")
    prices = price_of(args.model)
    if args.usd_per_mtok_in is not None or args.usd_per_mtok_out is not None:
        if any(v is None or not math.isfinite(v) or v < 0 for v in (args.usd_per_mtok_in, args.usd_per_mtok_out)):
            parser.error("both finite nonnegative prices required")
        prices = Prices(args.usd_per_mtok_in, args.usd_per_mtok_in, args.usd_per_mtok_out)
    if prices is None:
        parser.error("unknown model: supply both price flags")
    lane = None
    if args.dry_run:
        if indices != [0] or args.verify_lane != "vm" or args.board_memory:
            parser.error("dry run uses probe index 0, VM verifier and private FileStore only")
        rows = [
            dict(
                repo="probe",
                vulnerable="probe-before",
                fixed="probe-after",
                family="path",
                language="python",
                file="app.py",
                function="main",
            )
        ]
    else:
        try:
            validate_image(args.image or "")
        except ValueError:
            parser.error("image must be pinned by sha256 digest")
        if not args.private_root.resolve().is_relative_to(Path("benchmarks/search/private").resolve()):
            parser.error("live working files must stay in benchmarks/search/private")
        if args.verify_lane == "vm":
            if _sandbox.isolation_mode() != "userns":
                parser.error("VM verification requires userns")
            try:
                _sandbox.isolation_check(timeout_seconds=5)
            except _sandbox.IsolationUnavailable:
                parser.error("VM userns isolation probe failed")
        # Validate private manifest before opening any remote store or client.
        if not args.manifest.resolve().is_relative_to(Path("benchmarks/search/private").resolve()):
            parser.error("manifest must stay in benchmarks/search/private")
        try:
            rows = json.loads(args.manifest.read_bytes())["pairs"]
            if not isinstance(rows, list) or any(index >= len(rows) for index in indices):
                parser.error("pair index outside manifest")
        except (OSError, ValueError, KeyError, TypeError):
            parser.error("private manifest unreadable or invalid")
        for index in indices:
            row = rows[index]
            if not isinstance(row, dict) or not all(
                isinstance(row.get(k), str) and row[k] for k in ("repo", args.side, "fixed", "family", "language", "file", "function")
            ):
                parser.error("invalid manifest pair")
            if row["family"] not in (
                "injection",
                "path",
                "output_encoding",
                "untrusted_destination",
                "sql",
                "command",
                "xss",
                "ssrf",
                "access_control",
                "deserialization",
                "configuration",
                "secrets",
            ):
                parser.error("unknown manifest family")
            if row["language"] not in ("python", "javascript", "typescript", "php", "java"):
                parser.error("unknown manifest language")
            path = Path(row["file"])
            if path.is_absolute() or ".." in path.parts or "\\" in row["file"]:
                parser.error("invalid candidate path")
            if not re.fullmatch(r"https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", row["repo"]):
                parser.error("invalid repository URL")
            if not all(re.fullmatch("[0-9a-f]{40}", row[s]) for s in (args.side, "fixed")):
                parser.error("invalid revision")
        load_dotenv()
        if not os.environ.get(DEEPSEEK_KEY_ENV):
            parser.error("DeepSeek key is not configured")
        client = OpenRouterChatClient(
            api_key=os.environ[DEEPSEEK_KEY_ENV], base_url=os.environ.get(DEEPSEEK_BASE_ENV, DEEPSEEK_BASE_URL), max_attempts=1
        )
    root = args.private_root / uuid.uuid4().hex
    root.mkdir(parents=True, mode=0o700)
    records = []
    started = time.monotonic()
    args.out.parent.mkdir(parents=True, exist_ok=True)
    with args.out.open("x") as output:
        aborted_reason = None
        try:
            store = open_store(args.board_memory) if args.board_memory else FileStore(root / "boards")
            if not args.dry_run:
                lane = AXLane(
                    args, Workload(args.image, frozenset({"VERIFY_INPUT_URL", "RESULT_URL"}), 900, validate_result, kind="search-verify")
                )
        except Exception as exc:
            aborted_reason = exception_reason(exc)
        for position, index in enumerate(indices if aborted_reason is None else []):
            local = root / str(index)
            local.mkdir()
            if args.dry_run:
                sides, demos = materialise(local / "probe", "path")
                client = scripted(load_demo(demos["real"]))
            searches_remaining = len(indices) - position
            per_search = remaining_ceiling / searches_remaining if searches_remaining > 0 and remaining_ceiling > 0 else 0.0
            pilot = Pilot(args, rows[index], index, local, store, SpendBudget(per_search), client, prices, lane)
            if args.dry_run:
                pilot.sides = sides
                pilot.record["input_bytes"] = len((sides[0 if args.side == "vulnerable" else 1].checkout / "app.py").read_bytes())
            record = pilot.run()
            remaining_ceiling = max(0.0, remaining_ceiling - record["spend"]["settled"])
            records.append(record)
            output.write(json.dumps(record, allow_nan=False) + "\n")
            output.flush()
            if record.get("aborted_reason"):
                aborted_reason = record["aborted_reason"]
                break
        summary = dict(
            type="summary",
            end_reason="instrument_failure" if aborted_reason else "completed",
            aborted_reason=aborted_reason,
            skipped_pairs=indices[len(records) :],
            searches=len(records),
            dry_run=args.dry_run,
            side=args.side,
            ceiling_usd=args.ceiling_usd,
            purpose="feasibility_only",
            advantages=["known_location", "labelled_family", "runnable_project_selection_bias"],
            fixed_effects_observed=sum(r["fixed_effect_observed"] is True for r in records),
            outcomes=dict(Counter(r["outcome"] for r in records)),
            spend={k: sum(r["spend"][k] for r in records) for k in ("reserved", "settled")},
            **{k: sum(r[k] for r in records) for k in ("model_calls", "tokens_in", "tokens_out", "tasks_submitted")},
            wall_seconds=time.monotonic() - started,
        )
        output.write(json.dumps(summary, allow_nan=False) + "\n")
    return int(bool(aborted_reason) or any(r["end_reason"] == "instrument_failure" for r in records))
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,370 @@
 """Offline development-pair feasibility pilot; identities stay in a gitignored manifest.
 Run from the repository root with python -m benchmarks.search.pilot_select.
 The existing reserved guard is executed as a black box: this module never reads v3.
 """
 from __future__ import annotations
 import argparse
 import configparser
 import hashlib
 import json
 import os
 import re
 import subprocess
 from collections import Counter
 from pathlib import Path
 from urllib.parse import urlsplit
 from benchmarks.unseen import eligibility, ledger
 from openultrasast.model.taxonomy import load_families
 from openultrasast.search.task_storage import exception_reason
 LANGUAGES = ("python", "javascript", "typescript", "php", "java")
 FAMILIES = ("injection", "path", "output_encoding", "untrusted_destination")
 SHA = re.compile(r"[0-9a-f]{40}")
 MANIFESTS = {
    "requirements.txt": "pip",
    "pyproject.toml": "pip",
    "setup.py": "pip",
    "Pipfile": "pip",
    "package.json": "npm",
    "composer.json": "composer",
    "pom.xml": "maven",
    "build.gradle": "gradle",
    "build.gradle.kts": "gradle",
 }
 def encoded(value) -> bytes:
    return (json.dumps(value, sort_keys=True, indent=2) + "\n").encode()
 def safe(path: Path) -> bool:
    return not eligibility.excluded(path) and not eligibility.excluded(path.resolve()) and not path.is_symlink()
 def load_catalogs(root: Path) -> tuple[list[dict], dict]:
    """Read raw metadata only; PairCase materialization would unnecessarily open source excerpts."""
    rows = []
    counts = {"files": 0, "bytes": 0, "rows": 0}
    directory = (root / "benchmarks/pairs").resolve()
    for path in sorted(directory.rglob("catalog.toml")):
        if not safe(path) or not path.resolve().is_relative_to(directory):
            continue
        raw = path.read_bytes()
        items = eligibility.parse(path, raw).get("pair", [])
        if not isinstance(items, list) or not all(isinstance(row, dict) for row in items):
            raise ValueError("invalid_catalog")
        rows.extend(items)
        counts["files"] += 1
        counts["bytes"] += len(raw)
        counts["rows"] += len(items)
    if not counts["bytes"] or not rows:
        raise ValueError("empty_catalogs")
    return rows, counts
 def exclusions(root: Path, extra: tuple[Path, ...] = (), ledgers: tuple[Path, ...] = ()) -> tuple[set[str], dict]:
    """Unseen-local reservations/used sets, including private journals; never the development used set.
    eligibility.build_used collects development data itself, so its union cannot exclude a
    development pilot. The unseen usage ledger has opaque slices, not identities: every pool
    is excluded in full regardless of usage, and ledger integrity is checked separately.
    """
    directory = root / "benchmarks/unseen"
    paths = {
        p
        for p in directory.rglob("*")
        if p.suffix in {".toml", ".json", ".jsonl", ".yaml", ".yml"} and "fixtures" not in p.relative_to(directory).parts
    }
    paths.update(extra)
    ledger_paths = set(ledgers)
    ledger_paths.update(p for p in paths if any(word in p.stem.lower() for word in ("ledger", "usage")))
    paths.update(ledger_paths)
    names: set[str] = set()
    report = {"files": 0, "bytes": 0, "ledger_rows": 0}
    for path in sorted(paths):
        if not safe(path):
            raise ValueError("unsafe_exclusion_source")
        raw = path.read_bytes()
        report["files"] += 1
        report["bytes"] += len(raw)
        if path in ledger_paths:
            report["ledger_rows"] += len(ledger.read(path))
        else:
            value = eligibility.parse(path, raw)
            # TOML [[repository]] is a collection, whereas repositories() treats
            # a scalar "repository" field as an identity. Walk containers too.
            def collect(item):
                names.update(eligibility.repositories(item))
                if isinstance(item, str) and eligibility.NAME.fullmatch(item):
                    names.add(eligibility.normalize(item))
                if isinstance(item, dict):
                    for child in item.values():
                        if isinstance(child, (dict, list)):
                            collect(child)
                elif isinstance(item, list):
                    for child in item:
                        collect(child)
            collect(value)
    report.update(count=len(names), sha256=hashlib.sha256("\n".join(sorted(names)).encode()).hexdigest())
    return names, report
 def cache_safe(path: Path) -> bool:
    # Git config is intentionally readable here; every other exclusion and all
    # symlink ancestors remain forbidden before opening files or listing trees.
    lexical = path.absolute()
    resolved = path.resolve()
    return not any("v3" in part.lower() or part in {"__pycache__", ".venv"} for p in (lexical, resolved) for part in p.parts) and not any(
        p.is_symlink() for p in (lexical, *lexical.parents)
    )
 def enrich(rows: list[dict], caches: tuple[Path, ...], *, excluded: set[str] | None = None) -> dict:
    """Prefer metadata actually present in a matching local clone, without fetching.
    This is only a preference: a cached checkout is not proof the pinned revision builds.
    Only development-candidate paths are opened; unrelated cached repositories are not read.
    """
    report = {"matched_checkouts": 0, "config_bytes": 0, "manifest_bytes": 0}
    seen = {}
    for row in rows:
        try:
            name = eligibility.normalize(row.get("repo", ""))
        except (ValueError, TypeError):
            continue
        if name in (excluded or set()):
            continue
        if name not in seen:
            seen[name] = []
            for cache in caches:
                for checkout in (cache / name, cache / name.rsplit("/", 1)[-1]):
                    config = checkout / ".git/config"
                    if not cache_safe(config) or not config.is_file():
                        continue
                    parser = configparser.ConfigParser()
                    raw = config.read_bytes()
                    parser.read_string(raw.decode())
                    origin = parser.get('remote "origin"', "url", fallback="")
                    try:
                        matching = eligibility.normalize(origin) == name
                    except ValueError:
                        matching = False
                    if not matching:
                        continue
                    files = []
                    for manifest in MANIFESTS:
                        path = checkout / manifest
                        if cache_safe(path) and path.is_file():
                            report["manifest_bytes"] += len(path.read_bytes())
                            files.append(manifest)
                    for folder in ("tests", "test", "spec", "__tests__", "src/test"):
                        directory = checkout / folder
                        if cache_safe(directory) and directory.is_dir() and any(directory.iterdir()):
                            files.append(folder + "/")
                    seen[name] = files
                    report["matched_checkouts"] += 1
                    report["config_bytes"] += len(raw)
                    break
                if seen[name]:
                    break
        row["files"] = sorted(set(row.get("files", []) + seen[name]))
    return report
 def candidates(rows: list[dict], excluded: set[str]) -> tuple[list[dict], dict]:
    taxonomy = load_families()
    used = eligibility.UsedSet(sources={"unseen": excluded})
    out, rejected = [], Counter()
    for row in rows:
        reason = None
        try:
            raw_repo = row.get("repo", "")
            repo = eligibility.normalize(raw_repo)
            if "://" in raw_repo and not raw_repo.startswith("https://"):
                raise ValueError
            url = raw_repo if raw_repo.startswith("https://") else "https://github.com/" + repo
            if repo.count("/") != 1:
                raise ValueError
            parsed = urlsplit(url)
            if (
                parsed.netloc != "github.com"
                or parsed.query
                or parsed.fragment
                or parsed.path.strip("/").removesuffix(".git").lower() != repo
            ):
                raise ValueError
            if row.get("fix_repo") and eligibility.normalize(row["fix_repo"]) != repo:
                raise ValueError
        except (ValueError, TypeError):
            rejected["repository"] += 1
            continue
        if row.get("split", "train") != "train" or row.get("provenance") == "synthetic":
            reason = "not_development_fix"
        elif row.get("language") not in LANGUAGES:
            reason = "language"
        elif eligibility.rejection(eligibility.Resolution(repo, frozenset({repo}), repo), used, set()):
            reason = "unseen"
        vulnerable, fixed = row.get("parent", ""), row.get("commit", "")
        if not all(isinstance(s, str) and SHA.fullmatch(s) for s in (vulnerable, fixed)) or vulnerable == fixed:
            reason = reason or "commits"
        expected = row.get("expected", [])
        families = {row["family"]} if row.get("family") else set()
        for item in [row, *expected]:
            family = taxonomy.family_of_cwe(item.get("cwe", ""))
            if family:
                families.add(family.id)
        families &= set(FAMILIES)
        function = row.get("function") or next((r.get("function") for r in expected if r.get("function")), "")
        file = row.get("path") or row.get("relpath", "")
        if len(families) != 1:
            reason = reason or "family"
        if not function or function in {"<anon>", "<module>", "*"} or not file:
            reason = reason or "location"
        if reason:
            rejected[reason] += 1
            continue
        files = row.get("files", [])
        manifest = next((MANIFESTS[Path(f).name] for f in sorted(files) if Path(f).name in MANIFESTS), None)
        tests = True if any(re.search(r"(^|/)(tests?|__tests__|spec)(/|$)|(^|/)test_[^/]+", f) for f in files) else None
        out.append(
            {
                "repo": url.removesuffix(".git").rstrip("/"),
                "vulnerable": vulnerable,
                "fixed": fixed,
                "family": next(iter(families)),
                "language": row["language"],
                "file": file,
                "function": function,
                "manifest": manifest,
                "has_tests": tests,
            }
        )
    return out, dict(sorted(rejected.items()))
 def select(rows: list[dict], *, seed: int, count: int = 20) -> list[dict]:
    """Balance language/family representation, then prefer evidenced runnable projects.
    Seeded SHA ordering is invariant to catalog ordering and Python hash randomization.
    At most one pair per normalized repository is selected.
    """
    if count < 1:
        raise ValueError("invalid_count")
    remaining = sorted(rows, key=lambda row: hashlib.sha256(str(seed).encode() + encoded(row)).digest())
    selected, used = [], set()
    languages, families = Counter(), Counter()
    while remaining and len(selected) < count:
        row = min(
            remaining,
            key=lambda r: (
                languages[r["language"]] >= 3,
                languages[r["language"]],
                families[r["family"]],
                not (r["has_tests"] and r["manifest"]),
                not r["manifest"],
                not r["has_tests"],
            ),
        )
        selected.append(row)
        used.add(eligibility.normalize(row["repo"]))
        languages[row["language"]] += 1
        families[row["family"]] += 1
        remaining = [r for r in remaining if eligibility.normalize(r["repo"]) not in used]
    return selected
 def summary(rows: list[dict], *, seed: int, manifest: bytes, target: int = 20) -> dict:
    languages = Counter(row["language"] for row in rows)
    return {
        "status": "selected" if len(rows) == target else "insufficient_candidates",
        "purpose": "feasibility_only",
        "seed": seed,
        "target": target,
        "selected": len(rows),
        "gap_to_target": max(0, target - len(rows)),
        "per_language": {lang: languages[lang] for lang in LANGUAGES},
        "per_family": {family: sum(r["family"] == family for r in rows) for family in FAMILIES},
        "language_floor_gaps": {lang: max(0, 3 - languages[lang]) for lang in LANGUAGES},
        "unknown_test_suite": sum(r["has_tests"] is None for r in rows),
        "unknown_manifest": sum(r["manifest"] is None for r in rows),
        "manifest_sha256": hashlib.sha256(manifest).hexdigest(),
        "biases": ["known_vulnerable_location", "labelled_family", "runnable_project_preference"],
        "qualification": "not_an_unseen_evaluation_or_block_admission",
    }
 def main(argv=None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path.cwd())
    parser.add_argument("--seed", type=int, default=20261005)
    parser.add_argument("--count", type=int, default=20)
    parser.add_argument("--exclude", type=Path, action="append", default=[])
    parser.add_argument("--ledger", type=Path, action="append", default=[])
    parser.add_argument("--cache", type=Path, action="append", default=[])
    parser.add_argument("--manifest", type=Path, default=Path("benchmarks/search/private/pilot.json"))
    parser.add_argument("--output", type=Path, default=Path("benchmarks/measurements/2026-10-05-search-pilot-selection/record.json"))
    args = parser.parse_args(argv)
    private = args.root / args.manifest
    created = False
    try:
        if not private.resolve().is_relative_to((args.root / "benchmarks/search/private").resolve()):
            raise ValueError("manifest_must_be_private")
        ignored = subprocess.run(["git", "check-ignore", "-q", str(private)], cwd=args.root, capture_output=True)
        if ignored.returncode != 0:
            raise ValueError("manifest_not_gitignored")
        guard = eligibility.verify_tests(args.root)
        rows, instrument = load_catalogs(args.root)
        excluded, exclusion_report = exclusions(args.root, tuple(args.exclude), tuple(args.ledger))
        # The black-box guard has already approved the development catalogs.
        metadata = enrich(rows, tuple(args.cache) or (Path.home() / ".cache/openultrasast/repos",), excluded=excluded)
        available, rejected = candidates(rows, excluded)
        selected = select(available, seed=args.seed, count=args.count)
        payload = encoded({"seed": args.seed, "pairs": selected})
        private.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
        with private.open("xb") as handle:
            created = True
            os.chmod(private, 0o600)
            handle.write(payload)
        # The URL-bearing private selection now lies in the guard's development tree,
        # so even catalog bare-name aliases are checked without reading v3 ourselves.
        guard = eligibility.verify_tests(args.root)
        record = summary(selected, seed=args.seed, manifest=payload, target=args.count)
        record.update(
            catalogs=instrument,
            exclusions=exclusion_report,
            rejected=rejected,
            local_metadata=metadata,
            eligible_pairs=len(available),
            eligible_repositories=len({r["repo"] for r in available}),
            guard=guard,
        )
        output = args.root / args.output
        output.parent.mkdir(parents=True, exist_ok=True)
        with output.open("xb") as handle:
            handle.write(encoded(record))
        print(encoded(record).decode(), end="")
        return 0 if len(selected) == args.count else 2
    except Exception as exc:
        if created:
            private.unlink(missing_ok=True)
        print(
            json.dumps(
                {
                    "status": "instrument_failure",
                    "reason": exception_reason(
                        exc, private=tuple(part for row in locals().get("rows", []) for part in str(row.get("repo", "")).split("/") if part)
                    ),
                }
            )
        )
        return 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,375 @@
 # Unseen evaluation, group 1
 The coordinator runs task 1.5 from the repository root:
 ```sh
 export PATH=/home/mc/Source/OpenUltraSAST/.venv/bin:$PATH
 export PYTHONPATH=$PWD/src
 python -m benchmarks.unseen.eligibility --s3-store s3:// --verify-tests --output benchmarks/measurements/2026-10-04-unseen-01-used-set/record.json
 ```
 This is the networked command; implementation tests use fakes. It loads `.env` with
 `openultrasast.config.load_dotenv` (exported values win), opens the local FileStore and
 S3 MemoryStore through `openultrasast.plane.memory.open_store(..., read_only=True)`,
 and uses `GH_TOKEN` for GitHub GET resolution. `s3://` selects `S3_BUCKET`; pass
 `--s3-store s3://BUCKET/PREFIX` for a prefixed store and `--local-store file:///PATH`
 for a different local store. Read-only S3 opening skips the normal write/Select probe;
 collection uses LIST/GET only. Existing normal store opening is unchanged.
 Pair catalogs/recipes include local pointer rows (`vendored = false`, including
 `fix_repo`). Additional external manifests can be supplied with repeatable
 `--pointer-manifest PATH`. Registered units in memory and experiment YAML are followed;
 missing units with a registered digest fail. Plans without frozen units are not used data.
 Experiment units identify repositories in `group`. Binary measurement artifacts are
 read and counted; structured JSON, TOML and multi-document YAML are parsed strictly.
 Each source records files/objects read, bytes read, repository-bearing rows (distinct
 names per input), and distinct repository counts. The digest is SHA-256 of sorted,
 normalized names joined with newlines. Source counts overlap. An empty source fails;
 only after establishing it is empty may the coordinator pass `--known-empty LABEL`.
 The output records that declaration. Missing/unreadable inputs still fail.
 GitHub redirects add the requested and canonical names, plus parent/source fork
 identities. Used names are also resolved so an old used name excludes a renamed
 candidate. GitHub cannot enumerate all historical names: injected clients may supply
 `former_names`; actual historical aliases come from used references and redirects.
 A 404 for a historical/synthetic used identity retains its literal identity; other
 API failures stop collection. Candidate resolution always fails closed on a 404.
 `resolve(candidate, api)` and `rejection(resolution, used, selected_networks)` are
 available to the later sourcing task. Names stay in memory; output contains only
 counts, labels and SHA-256 digests. Output files are created exclusively, never overwritten.
 `--verify-tests` runs the three group-1 test modules with both output streams discarded,
 including the existing population guard. Only aggregate test counts and the exit code
 enter the record; a failed test prevents the record. V3 paths are excluded before
 eligibility reads; only the existing guard handles v3 inside its black-box test process.
 Population reservations retain their existing sweep over `benchmarks/`, `src/`, and
 `tests/`. Pool reservations also cover `plane/`. Each reservation exempts only its own
 directory; population checks include all of `benchmarks/unseen/private/`. This preserves
 the existing population behavior while adding pools (the hard rule for this increment).
 All `pool-pN.toml` files require a matching `freeze-pN.json`; drafts use `draft-pN.toml`.
 The freeze digest is SHA-256 of parsed public TOML encoded as UTF-8 JSON with sorted
 keys, compact separators and `ensure_ascii=False`. Private entries must be represented
 by opaque digests in that public manifest, as task 3.2 requires.
 The ledger exposes `append(path, row)` and `read(path)`. Rows contain `slice`, `decision`
 (an opaque decision or experiment label), `purpose`, ISO `date`, `result_digest`, and
 `freeze_digest`. Appends lock and validate the existing chain, reject duplicates or a
 changed freeze, and reject qualification of an informed slice for the same decision.
 Keep the published final digest to authenticate history: the chain detects row edits,
 but cannot independently prove that an entire history was not replaced or truncated.
 ## Sourcing and extraction (tasks 2.1–2.4)
 The coordinator's networked task **2.5** is now:
 ```sh
 export PATH=/home/mc/Source/OpenUltraSAST/.venv/bin:$PATH
 export PYTHONPATH=$PWD/src
 python -m benchmarks.unseen.draft --root "$PWD" --s3-store s3:// --seed 20260601 \
  --cache /home/mc/ousast-results/plane/unseen-draft --max-hours 8
 ```
 Export `GH_TOKEN` first, or supply it through the root `.env` (exported values win).
 The same read-only local/S3 stores, `--pointer-manifest`, and explicit `--known-empty`
 options as task 1.5 apply. Missing or unreadable sources fail. The used set is rebuilt
 and canonicalized before candidate selection, including redirects and fork networks.
 No population v3 file is opened and no guard/bisection is run by this command; that is
 reserved for group 3. An existing draft is never overwritten.
 The command writes `--cache/journal/draft-p1.toml` and
 `--cache/journal/private-draft-p1.toml` only after all sourcing stages complete.
 Both stay outside the repository, with mode 0600. The public-format file contains permissive entries
 and, for every private entry, only an opaque ID, slice, private marker, and SHA-256
 of canonical JSON containing its URL and ordered `[base, head]` pairs. Private entries
 carry the complete records, including licences, in the private-format file.
 Licensing is re-read through GitHub's licence endpoint **at the actual extracted
 vulnerability replay head**; the candidate's earlier fix-parent classification is
 provisional. An explicit SPDX declaration in the pinned file takes precedence over
 the API's classification. Missing/unknown/compound licences remain private.
 Three seeded slices each contain 100 repositories, one vulnerability range and twelve
 ordinary changes per repository. Each ecosystem/post-cutoff stratum differs from its
 proportional per-slice target by less than one repository. Post-cutoff candidates are
 attempted first within each ecosystem. Below 300 eligible repositories the command
 exits 1 with counts and does not write a partial draft or relax any selection bar.
 The group-2 measured exit and label confirmation remain coordinator tasks 2.5/2.6;
 passing implementation tests does not assert that 300 eligible repositories exist.
 Clones and checkpoints default to `results_root()/unseen-draft` (normally
 `~/ousast-results/plane/unseen-draft`), overridable by `--cache /outside/path`.
 The cache cannot lie inside `--root`. One opaque, disposable clone exists at a time;
 it is removed on success, rejection, or failure. A full-objects `--no-checkout` clone
 brings the whole commit graph and every blob in one pack, so temporal thirds, blame,
 and release-tag ancestry read locally; `--no-checkout` still skips the working tree.
 This is a full clone, not a shallow history, and has no blob:none promisor, so a
 genuinely missing object errors loudly instead of silently round-tripping (the old
 promisor path fetched blobs one at a time, hundreds of round-trips per repo). The
 500 MiB disk cap is checked after Git commands; one in-flight command can transiently
 exceed it before rejection and cleanup.
 Git output is captured, never forwarded. Each repository must read a nonempty source
 blob before extraction. Summary instrumentation includes source read operations and
 actual bytes, clone count, cumulative/peak disk bytes, wall time, and logical API calls
 and HTTP attempts. Zero source bytes or a failed Git read is an instrument failure,
 not an eligibility drop. Stdout is a JSON summary of counts/digests only; no names or
 URLs enter stdout or a measurement record. Raw per-change data stays in the external journal and manifests.
 Extraction uses Git and syntax boundaries, with no scanner, engine, or model. Python
 uses stdlib AST; Java/PHP/JS/TS use conservative named-function brace matching. Ambiguous
 or unparseable functions can reject a candidate. The first removed code line per
 fix-touched function is the SZZ sink proxy; pure-addition fixes use its declaration.
 Normalized text absence, non-root/non-merge ancestry, file/line limits, and the OSV
 release bracket are checked before accepting `introducing`. Matching tags are `VERSION`
 or `vVERSION`; an absent/ambiguous tag or missing prior release cannot certify the
 bracket. After at most five walk-backs, `last_touch` uses `git log -L` with the resolved
 numeric function extent (also works where Git lacks a language-specific function driver).
 Method, bias, fallback reasons, head function/range, files/hunks, family, advisory, and
 cutoff flag are recorded. Task 2.6 must review every third `introducing` label.
 All reviewed advisories are enumerated to exclude **all** known repository fixes from
 ordinary changes, including old advisories and advisories outside the four candidate
 ecosystems. Fix URLs are canonicalized before indexing so renames cannot hide them.
 The ordinary filter uses only the design's narrowed security pattern. It counts
 rejections (including oversized commits and repositories failing the 40-commit floor),
 checks both sides for touches to known vulnerable functions, and inspects generated
 headers and inherited `.gitattributes`. Sampling allocates twelve draws proportionally
 across three history-time thirds and four source-size buckets, with one per third.
 For offline tests, inject GitHub/OSV clients, the clone context, and `UsedSet` into
 `draft.run`; HTTP transports and Git subprocess runners also accept fakes. Tests use
 sanitized REST-shaped data and a temporary synthetic local Git history. No implementation
 test contacts GitHub, OSV, a model, or a cluster. HTTP retries are bounded to five attempts;
 rate-limit reset/Retry-After waits and transient 5xx backoff are tested with fake clocks
 and sleepers. A stale candidate 404 is counted; other service failures fail the run.
 ### Checkpoint and resume
 The command above uses journal directory
 `/home/mc/ousast-results/plane/unseen-draft/journal`. Run the same command to resume.
 `--max-hours` is a per-invocation budget; changing it does not invalidate checkpoints.
 Create `journal/STOP` to stop between units, then remove it before resuming. A page,
 repository resolution, candidate decision, or repository extraction already running
 finishes first, so the time budget is not a hard timeout on a large repository.
 Clean stops exit 0 with `status: stopped`; failures and shortfalls exit 1. Completion
 exits 0 with `status: draft`. No partial manifest is published.
 `inputs.json` binds the seed, source-labelled used-set digest, known-empty declarations,
 clone cap, and design fingerprints (sourcing/extraction/eligibility/publication code and
 family taxonomy). A mismatch refuses resume and prints only the changed parameter
 labels. Use a new external cache for a deliberately changed design or population.
 The used set is rebuilt each invocation; repository resolutions, including 404s, are
 reused from the journal. Live GitHub metadata for unfinished units can still change;
 completed pages and decisions are the durable sourcing snapshot.
 Each completed unit is appended to its stage JSONL and fsynced before work advances:
 `advisories.jsonl` (pages), `resolution.jsonl` (alias/fork metadata),
 `eligibility.jsonl` (candidate decisions), `extraction.jsonl` (repository/advisory
 results, vulnerable range, ordinary draws, pinned licence, method and counts), and
 `completion.jsonl` (final manifest digest). A lock permits only one writer.
 `progress.json` is atomically rewritten after every unit with stage counts, last unit,
 last observed GitHub rate-limit headers, and cumulative active elapsed seconds.
 These files may contain identities and must stay outside version control. Stdout and
 repository records contain only counts, digests and fixed labels.
 Replaying completed units makes no GitHub/OSV or clone calls. Final manifests are
 reconstructed deterministically from journal results; an interrupted publication can
 be retried, but a different existing manifest is refused. Completed JSONL rows are
 never rewritten. Malformed or torn records fail closed instead of being interpreted
 as completed work. Tests interrupt each stage with fakes, then compare resumed and
 uninterrupted manifests byte for byte.
 ### Planning estimate for task 2.5 (not measured)
 Let A be all reviewed advisories, R distinct fix-linked repository identities, U used
 identities not already cached, C candidate advisories passing early filters, and K
 repositories surviving extraction. GitHub requests are approximately
 `ceil(A/100) + R + U + 2*C + K` (enumeration, canonical repositories, fix metadata,
 provisional licence, final licence), plus retries. OSV requests are at most C. Git
 fetches and lazy blob transfers are additional network operations, not GitHub API calls.
 For a planning scenario of A=40,000, R=15,000, U≈1,000, C=600–1,500, K=300:
 about **18,000–20,000 GitHub calls** and **600–1,500 OSV calls**. The all-advisory index
 makes this substantially more than 300 repository lookups. At an assumed 5,000-request
 hourly allowance, allow several rate-limit windows. Actual token limits can differ.
 For 300–1,000 attempted clones averaging 20–100 MB after source hydration, plan roughly
 **6–100 GB transferred**, with one clone occupying about 500 MiB at most between commands
 plus the retained journal and manifests after completion. Transfer volume is an estimate; disk bytes
 are only a proxy. A working planning range is **8–48 hours**, potentially longer on
 large histories: every first-parent commit is inspected and lazy blobs can dominate.
 These are assumptions, not evidence from a network run. The command reports actual
 counts and wall time; task 2.5 establishes the measured estimate.
 ## Dispatcher, replay and scoring (groups 4–6)
 `benchmarks.ax.batch` owns Task transport and the shared scheduler. New workloads supply
 `Item` input bytes/commands and a `Workload` image, URL allowlist, deadline and result
 validator. Two AX slots and one VM slot are the default; sandbox death gets one fresh
 Task before VM fallback, OOM goes straight to VM, and instrument failures get one rerun.
 Cleanup failure prevents further launches. Create `STOP` in the output directory to stop
 launching; remove it and repeat the command to resume matching input digests. The legacy
 engine adapter retains its `questions.json` object name for compatibility; replay inputs
 and outputs use `.dat`. Both use the same object polling and cleanup implementation.
 Replay reads `pool-pN.toml`, verifies its adjacent `freeze-pN.json` canonical digest,
 selects `--slice`, and resolves private pointers through `private/pool-pN.toml` (or
 `--private-manifest`). It never reads a draft. `--dry-run` prints only counts and digests.
 The five-change proof uses a separate frozen JSON manifest from this project's own
 source-changing history. Raw output must be outside the repository.
 Each output root contains `inputs.json` and digest-keyed records and artifact directories.
 The scorer accepts that root directly, joins change labels, and includes missing or stale
 results as instrument failures. It refuses a slice above 5% failure after reruns. Example:
 ```sh
 python -m benchmarks.unseen.score "$HOME/ousast-results/unseen/p1/1/default" \
  --out "$HOME/ousast-results/unseen/p1/1/default-score.json"
 ```
 For paired binary arms add `--against BASELINE_ROOT --slice-id p1/2`; `--informed` forces
 `unseen.gate=not_run`. The later experiment integration owns ledger verification; callers
 of `gate` must pass that ledger decision. Score-bearing arms use `budgets` with fixed
 thresholds and `gate(..., binary=False, threshold=..., threshold_fixed=True)`. In-slice
 thresholds are exploratory and cannot qualify adoption. JVM wall time is explicitly the
 sum of the hook artifact's scan build/query times, not a separately observed process timer.
 ### Coordinator task 4.4
 Run from the merged repository root. Set `ENGINE_IMAGE` to the **engine** digest printed
 by Engine image CI, `ENGINE_UNITS` and `ENGINE_EXAMPLES` to the frozen input files for the
 two stored pins, `ENGINE_BASELINE` to their stored record directory, and `AX_KUBECONFIG`
 to the operator's kube-ax kubeconfig. Host store credentials stay on the VM; use the public
 HTTPS `S3_ENDPOINT=https://files.because-security.com` and the operator's `OUSAST_MEMORY`.
 Use a fresh output directory, so the smoke executes instead of resuming prior records.
 ```sh
 export PATH=/home/mc/Source/OpenUltraSAST/.venv/bin:$PATH
 export PYTHONPATH=$PWD/src
 export S3_ENDPOINT=https://files.because-security.com
 python benchmarks/learn/engine_trace.py \
  --units "$ENGINE_UNITS" --examples "$ENGINE_EXAMPLES" \
  --executor ax --parallel 2 --limit 2 --image "$ENGINE_IMAGE" \
  --kubeconfig "$AX_KUBECONFIG" --out "$HOME/ousast-results/unseen/proof-04"
 python -m benchmarks.unseen.proof engine --image "$ENGINE_IMAGE" \
  --records "$HOME/ousast-results/unseen/proof-04" --baseline "$ENGINE_BASELINE" \
  --out "benchmarks/measurements/$(date +%F)-unseen-04-dispatcher/record.json"
 ```
 ### Coordinator task 5.4
 Merge before running this proof. `.github/workflows/engine-image.yml` builds the `engine`
 and `replay` targets on push to main; it publishes `ousast-engine-task` and
 `ousast-replay-task` separately and prints their digests. Set `REPLAY_IMAGE` to the latter
 full `ghcr.io/...@sha256:...` reference. No manual image build is needed. Set
 `KIND_KUBECONFIG` and `AX_KUBECONFIG` to the corresponding AX kubeconfigs; the kind lane
 uses the identical Task API/manifest, never a Kubernetes Job.
 ```sh
 export PATH=/home/mc/Source/OpenUltraSAST/.venv/bin:$PATH
 export PYTHONPATH=$PWD/src
 export S3_ENDPOINT=https://files.because-security.com
 python -m benchmarks.unseen.replay --proof-history \
  --manifest "$HOME/ousast-results/unseen/proof-05-inputs.json"
 python -m benchmarks.unseen.replay --manifest "$HOME/ousast-results/unseen/proof-05-inputs.json" \
  --image "$REPLAY_IMAGE" --lane kind --kubeconfig "$KIND_KUBECONFIG" \
  --out "$HOME/ousast-results/unseen/proof-05-kind"
 python -m benchmarks.unseen.replay --manifest "$HOME/ousast-results/unseen/proof-05-inputs.json" \
  --image "$REPLAY_IMAGE" --lane ax --kubeconfig "$AX_KUBECONFIG" \
  --out "$HOME/ousast-results/unseen/proof-05-ax"
 python -m benchmarks.unseen.replay --manifest "$HOME/ousast-results/unseen/proof-05-inputs.json" \
  --image "$REPLAY_IMAGE" --lane docker \
  --out "$HOME/ousast-results/unseen/proof-05-vm"
 python -m benchmarks.unseen.proof replay --image "$REPLAY_IMAGE" \
  --kind-records "$HOME/ousast-results/unseen/proof-05-kind" \
  --ax-records "$HOME/ousast-results/unseen/proof-05-ax" \
  --vm-records "$HOME/ousast-results/unseen/proof-05-vm" \
  --out "benchmarks/measurements/$(date +%F)-unseen-05-replay-task/record.json"
 ```
 The record command fails if fewer than five results exist, identities differ, bytes/JVM
 proof is missing, or quick-tier findings differ. It does not convert a quick-only run
 without a JVM into an engine proof. Pool replays use `--lane mixed` (default) for the two
 AX slots and single VM overflow/fallback lane; `--arm long_deadline` changes only the
 hook deadline to 300 seconds and is a separate input digest.
 ### Deadline calibration and native agreement
 The 2026-10-05 maintainer decision supersedes the unscaled cluster deadline above.
 gVisor snapshot preparation can consume 30 seconds before any analysis. Calibrate
 the pinned replay image against the VM's native Docker **runc** runtime first.
 The default deterministic sample is the first 20 changes ordered by SHA-256 of
 change ID; a smaller manifest (including the five-change proof) uses all changes.
 Sampling never depends on manifest order.
 `calibrate` runs both lanes with a 600-second hook deadline (override `--deadline`
 if stages still time out). It reads resolution, provenance, preparation, snapshot,
 and quick timings from the push artifact; snapshot is nested in preparation.
 `quick_total` sums resolution + provenance + preparation + quick, without counting
 snapshot twice. Engine build and query times sum across the hook's scans. Hook
 wall time comes from the instrument block. Missing/nonpositive timings, deadline
 exhaustion, degraded engine scans or failed instruments prevent a successful
 calibration; failed changes are never silently dropped. Each factor is the median
 of paired cluster/native ratios with a deterministic 2,000-resample percentile
 bootstrap 95% interval. The measurement record contains opaque change digests,
 counts and timings, with no repository names. Raw artifacts remain outside the repo.
 Set `REPLAY_IMAGE` to the newly built replay image's pinned digest and
 `REPLAY_IMAGE_BYTES` to an **unpacked image size upper bound in bytes** from the
 image build. Do not use compressed registry layer size. Docker refuses to pull
 without this bound or when `df` at its data root reports less than that bound plus
 1 GiB free. It then explicitly pulls the image before issuing presigned task URLs.
 Supply `--docker-image-bytes "$REPLAY_IMAGE_BYTES"` to VM and mixed replay commands,
 including the earlier VM proof command.
 Launch/pull failures retain exit codes and the last ten sanitized stderr lines in
 `docker-error.json`, the result record and attempt history. URLs, known environment
 secrets and credential assignments are redacted. The original VM failure's cause
 remains unconfirmed until this diagnostic is captured; the old transport discarded it.
 Coordinator commands (these run networked workloads; offline tests use fakes):
 ```sh
 export PATH=/home/mc/Source/OpenUltraSAST/.venv/bin:$PATH
 export PYTHONPATH=$PWD/src
 export S3_ENDPOINT=https://files.because-security.com
 CALIBRATION_RECORD="benchmarks/measurements/$(date +%F)-unseen-calibration/record.json"
 python -m benchmarks.unseen.calibrate \
  --manifest "$HOME/ousast-results/unseen/proof-05-inputs.json" \
  --sample 20 --deadline 600 --image "$REPLAY_IMAGE" \
  --docker-image-bytes "$REPLAY_IMAGE_BYTES" --kubeconfig "$AX_KUBECONFIG" \
  --out "$HOME/ousast-results/unseen/calibration" --record "$CALIBRATION_RECORD"
 python -m benchmarks.unseen.replay --manifest benchmarks/unseen/pool-p1.toml \
  --pool p1 --slice 1 --arm default --lane ax --image "$REPLAY_IMAGE" \
  --calibration "$CALIBRATION_RECORD" --native-sample 100 \
  --docker-image-bytes "$REPLAY_IMAGE_BYTES" --kubeconfig "$AX_KUBECONFIG" \
  --out "$HOME/ousast-results/unseen/p1/1/calibrated-default"
 python -m benchmarks.unseen.score "$HOME/ousast-results/unseen/p1/1/calibrated-default" \
  --out "$HOME/ousast-results/unseen/p1/1/calibrated-default-score.json"
 ```
 For a 20-change slice calibration, replace the proof manifest with
 `benchmarks/unseen/pool-p1.toml --slice 1`; both commands accept `--private-manifest`.
 For the long arm use `--arm long_deadline` and a separate output root. Calibration
 requires the same image digest as replay. An explicit `--deadline-scale FACTOR`
 is an alternative to `--calibration`, not an additional multiplier.
 Cluster deadlines are `round(30 * factor)` or `round(300 * factor)` seconds;
 native deadlines remain 30 or 300, including VM fallback in mixed runs.
 Records carry configured and applied scale, base/applied deadline and actual lane;
 the scorer reports their counts. Task, subprocess and presigned-object budgets
 grow with the applied deadline.
 Use `--lane ax` (or `kind`) with `--native-sample K` for an agreement run, so every
 sampled change has a cluster counterpart. The native sample lives in `OUT/native`;
 the scorer detects it automatically, or accepts `--native PATH`. Missing, failed,
 wrong-lane or mismatched-image/arm pairs are unknown, never quiet agreements.
 The decision is whether any of the three finding streams flags the push, not
 whether the finding matches the vulnerability label.
 **Decision rule:** if the Wilson 95% agreement lower bound is below 95%, do not use
 the cluster results for the baseline. The score sets `flagged=true`,
 `baseline_eligible=false` and the adoption gate to `not_run`. Unknown pairs also
 flag the run. Disagreements are listed by change ID only, alongside per-change
 flagged/not-flagged decisions. Even perfect agreement needs at least 73 pairs to
 clear this bound; the five-change proof or a 20-change sample cannot qualify it.
@@ -0,0 +1,267 @@
 """Durable, content-addressed draw decisions; object I/O stays on the coordinator."""
 from __future__ import annotations
 import hashlib
 import json
 import os
 from collections.abc import Mapping
 from datetime import UTC, datetime
 from urllib.parse import urlencode, urlsplit
 CORPUS_KEYS = ("CORPUS_S3_ENDPOINT", "CORPUS_S3_BUCKET", "CORPUS_AWS_ACCESS_KEY_ID", "CORPUS_AWS_SECRET_ACCESS_KEY")
 def corpus_settings(environ: Mapping[str, str] | None = None) -> dict:
    """Read corpus-only credentials, naming missing settings without exposing values."""
    if environ is None:
        from openultrasast.config import load_dotenv
        load_dotenv()
        environ = os.environ
    missing = [key for key in CORPUS_KEYS if not environ.get(key)]
    if missing:
        raise ValueError(f"Corpus bank needs {', '.join(missing)} in .env or the environment")
    endpoint = environ["CORPUS_S3_ENDPOINT"].strip()
    try:
        parsed = urlsplit(endpoint)
        valid_endpoint = parsed.scheme in ("http", "https") and bool(parsed.netloc)
    except ValueError:
        valid_endpoint = False
    if not valid_endpoint:
        raise ValueError("CORPUS_S3_ENDPOINT must be a URL with a scheme (https://host[:port])")
    settings = {
        "endpoint": endpoint,
        "bucket": environ["CORPUS_S3_BUCKET"],
        "access_key": environ["CORPUS_AWS_ACCESS_KEY_ID"],
        "secret_key": environ["CORPUS_AWS_SECRET_ACCESS_KEY"],
    }
    if environ.get("CORPUS_S3_REGION"):
        settings["region"] = environ["CORPUS_S3_REGION"]
    return settings
 class CorpusObjects:
    """Plain S3 put/get/list, with no bucket administration or capability probes."""
    def __init__(self, *, endpoint: str, bucket: str, access_key: str, secret_key: str, region: str | None = None):
        import boto3
        from botocore.config import Config
        self.bucket = bucket
        self.client = boto3.client(
            "s3",
            endpoint_url=endpoint,
            aws_access_key_id=access_key,
            aws_secret_access_key=secret_key,
            region_name=region or "us-east-1",
            # RustFS/MinIO at an IP endpoint needs path-style addressing
            # (virtual-host bucket.<ip> does not resolve) and SigV4. Verified
            # against ousast-corpus @ 10.0.0.54:9001.
            config=Config(
                signature_version="s3v4",
                s3={"addressing_style": "path"},
                retries={"total_max_attempts": 1},
            ),
        )
    def get(self, key: str) -> tuple[bytes, str] | None:
        try:
            result = self.client.get_object(Bucket=self.bucket, Key=key)
        except Exception as error:
            if getattr(error, "response", {}).get("Error", {}).get("Code") in {"NoSuchKey", "404", "NotFound"}:
                return None
            raise
        body = result["Body"]
        try:
            return body.read(), result.get("VersionId") or result.get("ETag", "")
        finally:
            body.close()
    def put(self, key: str, data: bytes, labels: dict) -> None:
        self.client.put_object(
            Bucket=self.bucket,
            Key=key,
            Body=data,
            ContentType="application/json",
            Tagging=urlencode(labels),
        )
    def keys(self, prefix: str) -> list[str]:
        pages = self.client.get_paginator("list_objects_v2").paginate(Bucket=self.bucket, Prefix=prefix)
        return [item["Key"] for page in pages for item in page.get("Contents", [])]
 def _retry(operation, *args, **kwargs):
    """Retry one object operation once; a second failure is fatal to durability."""
    try:
        return operation(*args, **kwargs)
    except Exception:
        return operation(*args, **kwargs)
 class CorpusBank:
    def __init__(self, client, *, seed: int, prefix: str = "unseen"):
        self.client = client
        self.seed = seed
        self.decisions_prefix = f"{prefix}/{seed}/decisions/"
        self.resolved_prefix = f"{prefix}/{seed}/resolved/"
        self.advisories_key = f"{prefix}/{seed}/advisories/list.json"
        self.repositories_prefix = f"{prefix}/{seed}/repositories/"
        # get_repo metadata is seed-independent GitHub data: share it across seeds
        # so the ~thousands of used-set canonicalization lookups are paid once ever.
        self.repos_prefix = f"{prefix}/repos/"
    @staticmethod
    def advisory_key(advisory_id: str) -> str:
        return hashlib.sha256(advisory_id.encode()).hexdigest()
    def _put(self, key: str, body: dict, *, labels: dict) -> None:
        existing = _retry(self.client.get, key)
        if existing is not None:
            previous = json.loads(existing[0])
            if {field: value for field, value in previous.items() if field != "ts"} == body:
                return
        body = {**body, "ts": datetime.now(UTC).isoformat()}
        data = json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
        _retry(self.client.put, key, data, labels=labels)
    def bank_resolution(self, advisory_id: str, result: dict, *, contract: str) -> None:
        decision = "candidate" if "candidate" in result else "reject"
        self._put(
            self.resolved_prefix + self.advisory_key(advisory_id) + ".json",
            {
                "advisory": advisory_id,
                "decision": decision,
                "result": result,
                "reason": result.get("rejected"),
                "resolution_contract": contract,
                "seed": self.seed,
            },
            labels={"decision": decision, "contract": contract},
        )
    def _listed(self, prefix: str, identity: str) -> dict[str, dict]:
        results = {}
        for key in sorted(self.client.keys(prefix)):
            stored = _retry(self.client.get, key)
            if stored is None:
                raise ValueError("corpus_resolution_missing")
            body = json.loads(stored[0])
            name = body[identity]
            if key != prefix + self.advisory_key(name) + ".json" or body["seed"] != self.seed:
                raise ValueError("corpus_resolution_identity")
            results[name] = body
        return results
    def resolved(self) -> dict[str, dict]:
        results = self._listed(self.resolved_prefix, "advisory")
        for body in results.values():
            expected = "candidate" if "candidate" in body["result"] else "reject"
            if body["decision"] != expected:
                raise ValueError("corpus_resolution_invalid")
        return results
    def cache_advisories(self, rows: list, *, contract: str) -> None:
        if self.cached_advisories(contract=contract) is not None:
            return
        self._put(
            self.advisories_key,
            {"advisories": rows, "advisories_contract": contract, "seed": self.seed},
            labels={"contract": contract},
        )
    def cached_advisories(self, *, contract: str) -> list | None:
        stored = _retry(self.client.get, self.advisories_key)
        if stored is None:
            return None
        body = json.loads(stored[0])
        if body["seed"] != self.seed:
            raise ValueError("corpus_advisories_identity")
        return body["advisories"] if body["advisories_contract"] == contract else None
    def bank_repository(self, name: str, result: dict | None, *, contract: str) -> None:
        """Retain redirects, fork identity and 404s needed by the all-fix index."""
        self._put(
            self.repositories_prefix + self.advisory_key(name) + ".json",
            {"repository": name, "result": result, "resolution_contract": contract, "seed": self.seed},
            labels={"contract": contract},
        )
    def repositories(self, *, contract: str) -> dict[str, dict | None]:
        return {
            name: body["result"]
            for name, body in self._listed(self.repositories_prefix, "repository").items()
            if body["resolution_contract"] == contract
        }
    def cache_repo(self, name: str, metadata: dict | None, *, contract: str) -> None:
        """Persist one get_repo result (metadata, or None for a 404) by normalized name."""
        self._put(
            self.repos_prefix + hashlib.sha256(name.encode()).hexdigest() + ".json",
            {"name": name, "metadata": metadata, "resolution_contract": contract},
            labels={"contract": contract},
        )
    def get_cached_repo(self, name: str, *, contract: str) -> tuple[bool, dict | None]:
        """Return (found, metadata). found is True even when metadata is None (a cached 404)."""
        stored = _retry(self.client.get, self.repos_prefix + hashlib.sha256(name.encode()).hexdigest() + ".json")
        if stored is None:
            return (False, None)
        body = json.loads(stored[0])
        if body.get("name") != name or body.get("resolution_contract") != contract:
            return (False, None)
        return (True, body["metadata"])
    @staticmethod
    def key_for(repository: str, fix: str) -> str:
        return hashlib.sha256(f"{repository}\n{fix}".encode()).hexdigest()
    def bank(self, repository: str, fix: str, result: dict, *, contract: str) -> None:
        decision = {
            "repository": repository,
            "fix": fix,
            "decision": "accept" if "entry" in result else "reject",
            "reason": result.get("rejected"),
            "entry": result.get("entry"),
            "ordinary_exclusions": result.get("ordinary_exclusions", {}),
            "counts": result.get("counts", {}),
            "contract": contract,
            "seed": self.seed,
        }
        key = self.decisions_prefix + self.key_for(repository, fix) + ".json"
        existing = _retry(self.client.get, key)
        if existing is not None:
            previous = json.loads(existing[0])
            if {field: value for field, value in previous.items() if field != "ts"} == decision:
                return  # Preserve the first timestamp and avoid an unnecessary object version.
        decision["ts"] = datetime.now(UTC).isoformat()
        data = json.dumps(decision, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
        _retry(self.client.put, key, data, labels={"decision": decision["decision"], "contract": contract})
    def decided(self) -> dict[str, dict]:
        decisions = {}
        for key in sorted(self.client.keys(self.decisions_prefix)):
            stored = _retry(self.client.get, key)
            if stored is None:
                raise ValueError("corpus_decision_missing")
            decision = json.loads(stored[0])
            digest = self.key_for(decision["repository"], decision["fix"])
            if key != self.decisions_prefix + digest + ".json" or decision["seed"] != self.seed:
                raise ValueError("corpus_decision_identity")
            if decision["decision"] not in {"accept", "reject"}:
                raise ValueError("corpus_decision_invalid")
            decisions[digest] = decision
        return decisions
 def split_decided(decisions: Mapping[str, dict], *, contract: str) -> tuple[list[dict], set[str]]:
    """Split reusable results, sorted independently of bucket listing order.
    The coordinator merges entries into the full advisory population before seeded
    ordering: shuffling only the accepted subset would change the draw's order.
    """
    accepted = [row["entry"] for row in decisions.values() if row["decision"] == "accept"]
    accepted.sort(key=lambda entry: (entry.get("advisory", ""), entry["repository"], entry["fix"]))
    reusable = {key for key, row in decisions.items() if row["decision"] == "accept" or row["contract"] == contract}
    return accepted, reusable
@@ -0,0 +1,171 @@
 """Stage a cache draft, bisect with the black-box guard, and retain a digest receipt.
 Coordinator: python -m benchmarks.unseen.bisect_guard --draft CACHE/draft-p1.toml
 The cache is never changed. Successful subsets remain at benchmarks/unseen/draft-p1.toml
 and private/draft-p1.toml; failures remove only this invocation's staging files.
 Stdout reports only the dropped count. No reservation is opened by this module.
 """
 from __future__ import annotations
 import argparse
 import json
 import os
 import subprocess
 import tomllib
 from pathlib import Path
 from .draft import manifest, private_digest
 from .extract import InstrumentFailure
 from .journal import atomic, digest
 from .source import PERMISSIVE
 def read_manifest(path: Path) -> dict:
    try:
        raw = path.read_bytes()
        if not raw:
            raise ValueError
        data = tomllib.loads(raw.decode("utf-8"))
        if set(data) - {"status", "pool", "seed", "repository"}:
            raise ValueError
        if data["status"] != "draft" or data["pool"] != "p1" or type(data["seed"]) is not int:
            raise ValueError
        if not isinstance(data.get("repository", []), list):
            raise ValueError
        return data
    except (OSError, ValueError, KeyError, TypeError):
        raise InstrumentFailure("invalid_draft") from None
 def read_pair(public_path: Path, private_path: Path) -> tuple[dict, dict]:
    """Validate the licensing split and every private pointer before staging names."""
    public, private = read_manifest(public_path), read_manifest(private_path)
    try:
        if public["seed"] != private["seed"]:
            raise ValueError
        hidden = {row["id"]: row for row in private.get("repository", [])}
        rows = public.get("repository", [])
        if len(hidden) != len(private.get("repository", [])) or len({r["id"] for r in rows}) != len(rows):
            raise ValueError
        if set(hidden) != {r["id"] for r in rows if r.get("private")}:
            raise ValueError
        # Slice IDs come from the draft; bisect may leave sparse slices.
        for row in rows:
            if type(row["slice"]) is not int or row["slice"] < 1:
                raise ValueError
            if row.get("private"):
                full = hidden[row["id"]]
                expected = {"id": full["id"], "slice": full["slice"], "private": True, "sha256": private_digest(full)}
                if row != expected or full["license_class"] != "private":
                    raise ValueError
            elif row["license_class"] != "permissive" or row["license_spdx"] not in PERMISSIVE:
                raise ValueError
        return public, private
    except (ValueError, KeyError, TypeError):
        raise InstrumentFailure("invalid_draft_pair") from None
 def pytest_guard(root: Path) -> int:
    """Read only the exit code; never capture, inspect or forward either stream."""
    try:
        return subprocess.run(
            [".venv/bin/pytest", "-q", "-p", "no:cacheprovider", "tests/test_independent_population.py", "-k", "referenced"],
            cwd=root,
            stdin=subprocess.DEVNULL,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
        ).returncode
    except OSError:
        raise InstrumentFailure("guard_launch") from None
 def run(root: Path, draft: Path, *, private_draft: Path | None = None, guard_runner=None) -> dict:
    """Inject guard_runner(root) -> exit code for offline tests; default is pytest_guard.
    Run from an otherwise clean reservation directory. Existing staging/receipt or a
    frozen p1 is refused, so a crash cannot silently turn a partial subset into input.
    The receipt binds both retained manifests; freeze refuses edits after the guard.
    """
    private_draft = private_draft or draft.with_name("private-draft-p1.toml")
    public, private = read_pair(draft, private_draft)
    rows = public.get("repository", [])
    if not rows:
        raise InstrumentFailure("empty_draft")
    directory = root / "benchmarks/unseen"
    public_path = directory / "draft-p1.toml"
    private_path = directory / "private/draft-p1.toml"
    receipt_path = directory / "bisect-p1.json"
    targets = (private_path, public_path, receipt_path)
    if any(p.exists() for p in (*targets, directory / "pool-p1.toml", directory / "freeze-p1.json")):
        raise FileExistsError("staging_exists")
    private_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
    runner = guard_runner or pytest_guard
    created = []
    def check(subset):
        ids = {r["id"] for r in subset}
        selected = [r for r in private.get("repository", []) if r["id"] in ids]
        atomic(private_path, manifest(selected, private["seed"]).encode("utf-8"))
        atomic(public_path, manifest(subset, public["seed"]).encode("utf-8"))
        try:
            code = runner(root)
        except Exception:
            raise InstrumentFailure("guard_launch") from None
        if type(code) is not int or code not in (0, 1):
            raise InstrumentFailure("guard_exit")
        return code
    def retain(subset):
        if not subset or check(subset) == 0:
            return subset
        if len(subset) == 1:
            return []
        middle = len(subset) // 2
        return retain(subset[:middle]) + retain(subset[middle:])
    try:
        # Reserve destinations exclusively before any rewrites; never truncate an
        # existing coordinator's files. Empty manifests establish the control.
        for path in targets:
            with path.open("xb") as handle:
                created.append(path)
                os.fchmod(handle.fileno(), 0o600)
        if check([]) != 0:
            raise InstrumentFailure("guard_baseline")
        kept = retain(rows)
        if check(kept) != 0:
            raise InstrumentFailure("guard_final")
        result = {
            "guard_result": 0,
            "dropped_count": len(rows) - len(kept),
            "input_count": len(rows),
            "draft_digest": digest(read_manifest(public_path)),
            "private_draft_digest": digest(read_manifest(private_path)),
        }
        atomic(receipt_path, (json.dumps(result, sort_keys=True) + "\n").encode())
        return result
    except BaseException:
        for path in reversed(created):
            path.unlink(missing_ok=True)
        raise
 def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path.cwd())
    parser.add_argument("--draft", type=Path, required=True)
    parser.add_argument("--private-draft", type=Path)
    args = parser.parse_args(argv)
    try:
        result = run(args.root, args.draft, private_draft=args.private_draft)
    except Exception:
        print(json.dumps({"status": "instrument_failure"}))
        return 1
    print(json.dumps({"dropped_count": result["dropped_count"]}))
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,128 @@
 """Paired native/cluster deadline calibration; publish only opaque IDs and numbers."""
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import math
 import random
 import re
 import statistics
 from datetime import date
 from pathlib import Path
 from benchmarks.ax.batch import write_json
 from benchmarks.unseen.replay import canonical, load_slice, run_replays, sample_changes
 from benchmarks.unseen.score import coverage, load_records
 def stage_times(record):
    if coverage(record) == "instrument_failure":
        raise ValueError("calibration instrument failed")
    push = record["push"]
    if "deadline_exhausted" in json.dumps(push) or any(t.get("status") == "failed" for t in push.get("quick_tier", [])):
        raise ValueError("calibration deadline exhausted or quick tier failed; increase deadline")
    raw = push.get("timings", {})
    timings = {}
    for key, value in raw.items():
        key = re.sub(r"^comparison_\d+_", "", key)
        if not isinstance(value, (int, float)) or not math.isfinite(value) or value < 0:
            raise ValueError("invalid stage timing")
        timings[key] = timings.get(key, 0) + value
    required = ("resolution_seconds", "provenance_seconds", "preparation_seconds", "quick_seconds", "snapshot_seconds")
    if any(key not in timings for key in required):
        raise ValueError("missing completed quick-stage timings")
    scans = [r["scan"] for r in push.get("scans", [])]
    if any(s.get("degradations") for s in scans):
        raise ValueError("incomplete engine stages; calibration cannot use degraded scans")
    if not scans or any(k not in s for s in scans for k in ("build_seconds", "query_seconds")):
        raise ValueError("missing engine timings")
    result = {
        "snapshot": timings["snapshot_seconds"],  # Nested inside preparation; never counted twice.
        "preparation": timings["preparation_seconds"],
        "quick": timings["quick_seconds"],
        "quick_total": sum(timings[k] for k in required if k != "snapshot_seconds"),
        "engine_build": sum(s["build_seconds"] for s in scans),
        "engine_queries": sum(s["query_seconds"] for s in scans),
        "hook": record["instrument"].get("timings", {}).get("pre-push"),
    }
    if any(not isinstance(v, (int, float)) or not math.isfinite(v) or v <= 0 for v in result.values()):
        raise ValueError("missing or nonpositive stage timing")
    return result
 def slowdown(native, cluster, *, seed=0, draws=2000):
    if not native or len(native) != len(cluster):
        raise ValueError("calibration needs paired timings")
    if any(not math.isfinite(v) or v <= 0 for v in [*native, *cluster]):
        raise ValueError("timings must be finite and positive")
    ratios = [b / a for a, b in zip(native, cluster, strict=True)]
    rng = random.Random(seed)
    bootstrap = sorted(statistics.median(rng.choices(ratios, k=len(ratios))) for _ in range(draws))
    return {
        "n": len(ratios),
        "factor": statistics.median(ratios),
        "bootstrap95": [bootstrap[int(0.025 * (draws - 1))], bootstrap[int(0.975 * (draws - 1))]],
    }
 def calibration_record(native, cluster):
    nn, cc = ({r["id"]: r for r in rows} for rows in (native, cluster))
    if not nn or nn.keys() != cc.keys() or len(nn) != len(native) or len(cc) != len(cluster):
        raise ValueError("calibration requires exactly paired unique changes")
    pairs = []
    for key in sorted(nn):
        if nn[key].get("lane") != "docker" or cc[key].get("lane") != "ax":
            raise ValueError("calibration requires native docker and cluster ax lanes")
        pairs.append(
            {"change_id": hashlib.sha256(str(key).encode()).hexdigest(), "native": stage_times(nn[key]), "cluster": stage_times(cc[key])}
        )
    return {
        "status": "ok",
        "changes": len(pairs),
        "pairs": pairs,
        **{
            stage: slowdown([p["native"][stage] for p in pairs], [p["cluster"][stage] for p in pairs])
            for stage in ("quick_total", "engine_build", "engine_queries")
        },
    }
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--manifest", type=Path, required=True)
    parser.add_argument("--private-manifest", type=Path)
    parser.add_argument("--slice", default="1")
    parser.add_argument("--sample", type=int, default=20)
    parser.add_argument("--deadline", type=int, default=600)
    parser.add_argument("--image", required=True)
    parser.add_argument("--docker-image-bytes", type=int, required=True, help="unpacked image size upper bound")
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--kubeconfig", type=Path)
    parser.add_argument("--atespace", default="default")
    parser.add_argument("--out", type=Path, default=Path.home() / "ousast-results/unseen/calibration")
    parser.add_argument("--record", type=Path, default=Path("benchmarks/measurements") / f"{date.today()}-unseen-calibration/record.json")
    args = parser.parse_args()
    if args.deadline < 1 or args.sample < 1:
        parser.error("deadline and sample must be positive")
    args.arm = "default"
    changes = sample_changes(load_slice(args.manifest, args.slice, args.private_manifest), args.sample)
    failed = False
    for lane, directory in (("docker", "native"), ("ax", "cluster")):
        failed |= run_replays(changes, args, args.out / directory, lane, deadline=args.deadline)
    result = {"status": "failed", "changes": len(changes)}
    if not failed:
        try:
            result = calibration_record(load_records(args.out / "native"), load_records(args.out / "cluster"))
        except ValueError as exc:
            result["reason"] = str(exc)  # Only locally controlled diagnostics.
    result.update(
        image=args.image, deadline_seconds=args.deadline, sample_digest=hashlib.sha256(canonical([c["id"] for c in changes])).hexdigest()
    )
    write_json(args.record, result)
    return 0 if result["status"] == "ok" else 2
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,910 @@
 """Coordinator-only sourcing command: python -m benchmarks.unseen.draft --help.
 All network and git operations are injected at the run() boundary. Only counts,
 digests and fixed failure codes go to stdout; identity-bearing output stays in the
 private journal or corpus bucket. No population guard is run here.
 """
 from __future__ import annotations
 import argparse
 import copy
 import hashlib
 import json
 import multiprocessing
 import os
 import random
 import subprocess
 import tempfile
 import time
 from collections import Counter, defaultdict, deque
 from concurrent.futures import FIRST_COMPLETED, ProcessPoolExecutor, wait
 from concurrent.futures.process import BrokenProcessPool
 from contextlib import ExitStack, contextmanager
 from dataclasses import asdict
 from pathlib import Path
 from . import eligibility, extract, source
 from .bank import CorpusBank, CorpusObjects, corpus_settings, split_decided
 from .extract import EXTRACTION_CONTRACT, RESOLUTION_CONTRACT, Git, InstrumentFailure
 from .journal import Journal, ResolvedGitHub, ResumeMismatch, Stopped, atomic, digest, external
 def canonical(value) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
 def private_digest(row: dict) -> str:
    return hashlib.sha256(canonical({"url": row["url"], "commits": [[c["base"], c["head"]] for c in row["changes"]]})).hexdigest()
 def validate_pool(pool_size: int, slices: int) -> None:
    if pool_size < 1:
        raise ValueError("--pool-size must be at least 1")
    if slices < 1 or slices > pool_size:
        raise ValueError("--slices must be between 1 and --pool-size")
    if pool_size % slices:
        raise ValueError("--pool-size must be divisible by --slices")
 def assign_slices(rows: list[dict], *, seed: int, pool_size: int = 300, slices: int = 3) -> list[dict]:
    validate_pool(pool_size, slices)
    if len(rows) != pool_size or len({r["repository"] for r in rows}) != pool_size:
        raise ValueError("pool_size")
    for row in rows:
        kinds = Counter(c["kind"] for c in row["changes"])
        if kinds != {"vulnerability": 1, "ordinary": 12}:
            raise ValueError("change_count")
        if row["license_class"] not in {"permissive", "private"}:
            raise ValueError("license_class")
        if row["license_class"] == "permissive" and row["license_spdx"] not in source.PERMISSIVE:
            raise ValueError("license_class")
    rng = random.Random(seed)
    groups = defaultdict(list)
    for row in sorted(rows, key=lambda r: r["repository"]):
        groups[row["ecosystem"], row["post_cutoff"]].append(row)
    sizes = Counter({i: 0 for i in range(1, slices + 1)})
    assigned = []
    for key in sorted(groups):
        group = groups[key]
        rng.shuffle(group)
        quotient, remainder = divmod(len(group), slices)
        # Give each stratum its floor on all slices, then fill globally least-full slices.
        quotas = {i: quotient for i in sizes}
        order = list(sizes)
        rng.shuffle(order)
        order.sort(key=lambda i: sizes[i])
        for i in order[:remainder]:
            quotas[i] += 1
        offset = 0
        for slice_id in sorted(quotas):
            for row in group[offset : offset + quotas[slice_id]]:
                digest = private_digest(row)
                assigned.append({**row, "id": "r-" + digest[:24], "slice": slice_id})
            sizes[slice_id] += quotas[slice_id]
            offset += quotas[slice_id]
    if set(sizes.values()) != {pool_size // slices}:
        raise ValueError("slice_size")
    return sorted(assigned, key=lambda r: (r["slice"], r["id"]))
 def toml(value) -> str:
    """Inline TOML values keep nested change records structured without a new dependency."""
    if isinstance(value, bool):
        return "true" if value else "false"
    if isinstance(value, str):
        return json.dumps(value, ensure_ascii=False)
    if isinstance(value, int):
        return str(value)
    if isinstance(value, list):
        return "[" + ", ".join(toml(v) for v in value) + "]"
    if isinstance(value, dict):
        return "{" + ", ".join(json.dumps(k) + " = " + toml(v) for k, v in sorted(value.items()) if v is not None) + "}"
    raise ValueError("unsupported_manifest_type")
 def manifest(rows: list[dict], seed: int) -> str:
    lines = ['status = "draft"', 'pool = "p1"', f"seed = {seed}"]
    for row in rows:
        lines.append("\n[[repository]]")
        lines.extend(f"{key} = {toml(value)}" for key, value in sorted(row.items()) if value is not None)
    return "\n".join(lines) + "\n"
 def write_draft(root: Path, assigned: list[dict], *, seed: int) -> tuple[Path, Path]:
    public_path = root / "benchmarks/unseen/draft-p1.toml"
    private_path = root / "benchmarks/unseen/private/draft-p1.toml"
    if public_path.exists() or private_path.exists():
        raise FileExistsError("draft_exists")
    public, private = [], []
    for row in assigned:
        if row["license_class"] == "permissive":
            public.append(row)
        else:
            private.append(row)
            public.append({"id": row["id"], "sha256": private_digest(row), "slice": row["slice"], "private": True})
    private_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
    # Exclusive creates protect drafts awaiting human label review. Private first: never
    # publish a pointer whose private manifest failed to write.
    with private_path.open("x") as handle:
        os.chmod(private_path, 0o600)
        handle.write(manifest(private, seed))
    with public_path.open("x") as handle:
        handle.write(manifest(public, seed))
    return public_path, private_path
 class Clones:
    """Disposable blobless clones; each worker receives its own counter accumulator."""
    def __init__(
        self,
        root: Path,
        cache: Path,
        *,
        runner=None,
        limit_bytes=500 * 1024 * 1024,
        deadline_seconds: float | None = None,
        parse_deadline_seconds: float | None = 120.0,
        extract_workers: int = 6,
    ):
        if extract_workers < 1:
            raise ValueError("invalid_extract_workers")
        self.extract_workers = extract_workers
        self.cache = external(root, cache)
        self.runner = runner or subprocess.run
        self.limit_bytes = limit_bytes
        self.deadline_seconds = deadline_seconds
        self.parse_deadline_seconds = parse_deadline_seconds
        self.counts = Counter()
    @contextmanager
    def open(self, url: str):
        self.cache.mkdir(parents=True, exist_ok=True)
        started = time.monotonic()
        with tempfile.TemporaryDirectory(prefix="clone-", dir=self.cache) as directory:
            path = Path(directory)
            git = Git(path, runner=self.runner, limit_bytes=self.limit_bytes, deadline_seconds=self.deadline_seconds)
            try:
                # Full commit graph is needed for temporal thirds and OSV brackets.
                # A full-objects clone (no blob:none promisor) brings every blob in
                # one pack, so blame/log/diff read locally instead of fetching each
                # blob on demand (the old promisor path cost ~hundreds of round-trips
                # per repo). --no-checkout still skips the working tree. With no
                # promisor remote, a genuinely missing object errors loudly rather
                # than silently round-tripping. Disk is bounded by limit_bytes below.
                done = self.runner(
                    ["git", "-c", "credential.helper=", "clone", "--quiet", "--no-checkout", url, str(path)],
                    stdin=subprocess.DEVNULL,
                    stdout=subprocess.PIPE,
                    stderr=subprocess.PIPE,
                    check=False,
                    timeout=git.command_timeout(),
                    env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
                )
                if done.returncode:
                    raise InstrumentFailure("clone_failed")
                self.counts["clones"] += 1
                if git.disk_bytes() > self.limit_bytes:
                    raise InstrumentFailure("clone_size_cap")
                yield git
            except subprocess.TimeoutExpired:
                raise extract.ExtractionTimeout("extraction_timeout") from None
            finally:
                size = git.disk_bytes()
                self.counts["clone_bytes"] += size
                self.counts["peak_clone_bytes"] = max(self.counts["peak_clone_bytes"], size)
                self.counts["source_bytes_read"] += git.bytes_read
                self.counts["source_files_read"] += git.files_read
                self.counts["clone_wall_seconds"] += round(time.monotonic() - started, 3)
 def prove_source(git, revision: str) -> dict:
    files = git.run("ls-tree", "-r", "--name-only", revision).splitlines()
    for path in files:
        if Path(path).suffix in extract.LANGUAGES and not extract.generated_path(path):
            text = git.blob(revision, path)
            if text:
                return {"files": 1, "bytes": getattr(git, "last_blob_bytes", len(text.encode()))}
    raise InstrumentFailure("zero_source_bytes")
 class BankedGitHub(ResolvedGitHub):
    """Stream the fix index's repository metadata before continuing the draw."""
    def __init__(self, github, journal, bank):
        super().__init__(github, journal)
        self.bank = bank
        self.resolutions = bank.repositories(contract=RESOLUTION_CONTRACT)
        journal.rows["resolution"].update({name: body["metadata"] if body is not None else None for name, body in self.resolutions.items()})
    def get_repo(self, name):
        # Bucket-cache get_repo (the universal resolution choke point) so the
        # ~thousands of used-set canonicalization lookups and candidate resolves
        # are not re-fetched from GitHub every run. 404s are cached as None too.
        key = eligibility.normalize(name)
        if key not in self.journal.rows["resolution"]:
            found, value = self.bank.get_cached_repo(key, contract=RESOLUTION_CONTRACT)
            if not found:
                self.journal.boundary()
                try:
                    value = self.github.get_repo(key)
                except eligibility.RepositoryNotFound:
                    value = None
                self.bank.cache_repo(key, value, contract=RESOLUTION_CONTRACT)
            self.journal.put("resolution", key, value)
        value = self.journal.rows["resolution"][key]
        if value is None:
            raise eligibility.RepositoryNotFound("not_found")
        return value
    def resolve(self, name):
        key = eligibility.normalize(name)
        if key not in self.resolutions:
            try:
                resolved = eligibility.resolve(name, self)
            except eligibility.RepositoryNotFound:
                body = None
            else:
                body = {
                    "metadata": self.journal.rows["resolution"].get(key),
                    "full_name": resolved.full_name,
                    "names": sorted(resolved.names),
                    "network": resolved.network,
                }
            self.bank.bank_repository(key, body, contract=RESOLUTION_CONTRACT)
            self.resolutions[key] = body
        body = self.resolutions[key]
        if body is None:
            raise eligibility.RepositoryNotFound("not_found")
        return eligibility.Resolution(body["full_name"], frozenset(body["names"]), body["network"])
 def resolve_repository(name, github):
    if isinstance(github, BankedGitHub):
        return github.resolve(name)
    return eligibility.resolve(name, github)
 def advisory_index(rows: list[dict], github) -> dict[str, set[str]]:
    """Include ALL fixes in the enumerated population, even from rejected candidates.
    Canonicalize link names as well, so an old advisory URL survives repository renames.
    A 404 is not treated as proof that an advisory is unrelated to a selected repository.
    """
    index = defaultdict(set)
    for row in rows:
        for name, sha in source.fix_links(row):
            try:
                resolved = resolve_repository(name, github)
            except eligibility.RepositoryNotFound:
                index[name].add(sha)
                continue
            index[resolved.full_name].add(sha)
    return dict(index)
 def repository_changes(git, candidate, fixes: set[str], *, seed: int):
    resolved = []
    for fix in sorted(fixes | {candidate.fix}):
        try:
            if fix != candidate.fix:
                # Extra advisory fixes are best-effort exclusions. The candidate
                # was fetched strictly by extract_repository. Do not import extra
                # tags before introducing() checks the candidate's version bracket.
                git.run("fetch", "--quiet", "--no-tags", "origin", fix)
            resolved.append(git.run("rev-parse", fix).strip())
        except InstrumentFailure as exc:
            if fix == candidate.fix or not str(exc).startswith("git_exit_"):
                raise
    proof = prove_source(git, candidate.parent)
    change = extract.introducing(git, candidate)
    known = set()
    expanded = set()
    for full in resolved:
        expanded.add(full)
        for parent in git.parents(full):
            sites = extract.fix_sites(git, full, parent, global_ok=True)
            known.update((site["path"], site["function"]) for site in sites)
    rows = extract.ordinary_history(git, "HEAD")
    ordinary, exclusions = extract.draw_ordinary(rows, expanded, known, seed=seed)
    return [change, *ordinary], exclusions, proof
 def inputs(used, seed, known_empty, clones, *, pool_size=300, slices=3):
    from openultrasast.model.taxonomy import DEFAULT_FAMILIES_PATH
    parameters = {
        "seed": seed,
        "used_set_digest": digest({label: sorted(names) for label, names in used.sources.items()}),
        "known_empty": sorted(known_empty),
        "clone_limit_bytes": getattr(clones, "limit_bytes", 500 * 1024 * 1024),
        "journal_version": 4,
        "pool_size": pool_size,
        "slices": slices,
    }
    # Hardcoded design thresholds and algorithms are covered as well as taxonomy data.
    for name in ("draft", "source", "extract", "eligibility", "journal"):
        parameters["design_" + name] = hashlib.sha256(Path(__file__).with_name(name + ".py").read_bytes()).hexdigest()
    parameters["design_taxonomy"] = hashlib.sha256(DEFAULT_FAMILIES_PATH.read_bytes()).hexdigest()
    return parameters
 def enumerate_advisories(github, journal):
    records = {}
    for ecosystem in source.ECOSYSTEMS:
        page = 1
        next_url = None
        while True:
            key = f"{ecosystem}:{page}"
            if key not in journal.rows["advisories"]:
                journal.boundary()
                result = github.advisory_page(next_url, ecosystem=ecosystem)
                journal.put(
                    "advisories", key, {"rows": [source.reduce_advisory(row) for row in result["rows"]], "next_url": result["next_url"]}
                )
            result = journal.rows["advisories"][key]
            records.update((row["ghsa_id"], row) for row in result["rows"])
            next_url = result["next_url"]
            if next_url is None:
                break
            page += 1
    if not records:
        raise InstrumentFailure("empty_advisories")
    return list(records.values())
 def decide(row, github, osv, used, selected_networks=()):
    # selected_networks is retained for callers; only ordered acceptance consults it.
    network = {}
    try:
        links = source.fix_links(row)
        if len(links) != 1:
            raise source.Rejected("fix_links")
        name, _ = next(iter(links))
        resolved = resolve_repository(name, github)
        rejected_by = eligibility.rejection(resolved, used, set())
        if rejected_by:
            raise source.Rejected("used_" + rejected_by)
        network = {"network": resolved.network}
        candidate = source.candidate(row, github, osv)
        return {"candidate": asdict(candidate), "network": resolved.network}
    except source.Rejected as exc:
        return {"rejected": str(exc), **network}
    except eligibility.RepositoryNotFound:
        return {"rejected": "repository_or_commit_not_found", **network}
    except ValueError as exc:
        # A per-candidate transport failure (e.g. get_commit on an unresolvable fix ref)
        # skips this advisory; the run loop's systemic guard catches a broken instrument.
        if str(exc) == "http_failure":
            return {"rejected": "decide_http_failure", **network}
        raise
 def extract_repository(candidate, github, clones, fixes, seed):
    before = dict(clones.counts)
    deadline = getattr(clones, "deadline_seconds", None)
    total = (deadline or 0) + (getattr(clones, "parse_deadline_seconds", None) or 0) if deadline is not None else None
    try:
        with extract.process_deadline(total):
            with clones.open(candidate.url) as git:
                git.run("fetch", "--quiet", "origin", candidate.fix)
                changes, exclusions, proof = repository_changes(git, candidate, fixes, seed=seed)
                entry = {**asdict(candidate), "changes": changes, "instrument": proof}
            result = {"entry": entry, "ordinary_exclusions": exclusions}
    except source.Rejected as exc:
        result = {"rejected": str(exc), "ordinary_exclusions": getattr(exc, "counts", {})}
    except eligibility.RepositoryNotFound:
        result = {"rejected": "repository_or_commit_not_found", "ordinary_exclusions": {}}
    except (extract.InstrumentFailure, OSError) as exc:
        result = {"rejected": "extract_" + str(exc), "ordinary_exclusions": {}}
    result["counts"] = {key: value - before.get(key, 0) for key, value in clones.counts.items()}
    return finish_license(result, github) if github is not None else result
 def finish_license(result, github):
    """REST stays on the coordinator, including the license at the extracted pin."""
    if "entry" not in result:
        return result
    try:
        entry = result["entry"]
        pinned = entry["changes"][0]["head"]
        record = github.get_license(entry["repository"], pinned)
        spdx, license_class = source.license_info(record)
        entry.update(license_spdx=spdx, license_class=license_class, license_ref=pinned, license_path=record.get("path", ""))
    except (source.Rejected, eligibility.RepositoryNotFound) as exc:
        reason = "repository_or_commit_not_found" if isinstance(exc, eligibility.RepositoryNotFound) else str(exc)
        return {"rejected": reason, "ordinary_exclusions": {}, "counts": result["counts"]}
    except (extract.InstrumentFailure, OSError) as exc:
        return {"rejected": "extract_" + str(exc), "ordinary_exclusions": {}, "counts": result["counts"]}
    except ValueError as exc:
        if str(exc) != "http_failure":
            raise
        return {"rejected": "extract_http_failure", "ordinary_exclusions": {}, "counts": result["counts"]}
    return result
@contextmanager
 def ordered_extractions(
    rows,
    api,
    osv,
    used,
    clones,
    fixes,
    seed,
    checkpoint,
    entries,
    workers,
    pool_size,
    bank: CorpusBank | None = None,
    decided=None,
    stale_resolutions=(),
 ):
    """Bounded in-flight work, completion journaling, and seed-order acceptance.
    Only running jobs count against `workers`; completed results wait in the
    journal while the acceptance cursor is blocked. Counters are private to each
    job, including clone cleanup, and merged exactly once on completion here.
    Graceful STOP/guard/target exits drain started work into the journal for resume;
    a hard interrupt may lose unjournaled work but cannot change accepted order.
    """
    decided = dict(decided or {})
    identities = {}
    pending = deque()  # Seed-order acceptance cursor; contains no futures/results.
    in_flight = {}  # Future -> extraction key, independent of the cursor.
    # Fork shares the coordinator's memory copy-on-write. Jobs receive only the
    # picklable extraction inputs, never the journal, REST clients or stores.
    context = multiprocessing.get_context("fork")
    pool = ProcessPoolExecutor(max_workers=workers, mp_context=context)
    def resolution(row):
        key = row["ghsa_id"]
        if key not in checkpoint.rows["eligibility"]:
            result = decide(row, api, osv, used)
            if bank is not None:
                bank.bank_resolution(key, result, contract=RESOLUTION_CONTRACT)
            checkpoint.put("eligibility", key, result)
        return checkpoint.rows["eligibility"][key]
    def remember(repository, fix, result):
        bank.bank(repository, fix, result, contract=EXTRACTION_CONTRACT)
        # Reuse decisions made during this invocation too: another advisory for
        # the same pair must not overwrite an earlier accept with a rejection.
        decided[bank.key_for(repository, fix)] = {
            "repository": repository,
            "fix": fix,
            "decision": "accept" if "entry" in result else "reject",
            "entry": result.get("entry"),
            "reason": result.get("rejected"),
            "ordinary_exclusions": result.get("ordinary_exclusions", {}),
            "counts": result.get("counts", {}),
        }
    def collect(future):
        key = in_flight.pop(future)
        try:
            result = future.result()
        except BrokenProcessPool:
            # A killed worker also fails unrelated outstanding futures. Do not
            # mistake these collateral failures for a broken git instrument.
            result = {"rejected": "worker_crash", "ordinary_exclusions": {}, "counts": {}}
        except Exception:
            # Includes task/result serialization failures. Keep diagnostics
            # identity-free; repeated task errors still reach the normal guard.
            result = {"rejected": "extract_worker_failure", "ordinary_exclusions": {}, "counts": {}}
        for name, value in result["counts"].items():
            if name == "peak_clone_bytes":
                clones.counts[name] = max(clones.counts[name], value)
            else:
                clones.counts[name] += value
        result = finish_license(result, api)
        if bank is not None:
            repository, fix = identities[key]
            remember(repository, fix, result)
        checkpoint.put("extraction", key, result)
    def iterate():
        nonlocal pool
        ordered = iter(rows)
        exhausted = False
        def ready():
            return pending and (pending[0][2] is None or pending[0][2] in checkpoint.rows["extraction"])
        while (pending or not exhausted) and len(entries) < pool_size:
            # Only this cursor feeds acceptance, fork deduplication and the guard.
            # Replayed results follow the same path and need no worker submission.
            while ready():
                checkpoint.boundary()
                row, decision, key = pending.popleft()
                yield row, decision, checkpoint.rows["extraction"].get(key)
                if len(entries) == pool_size:
                    return
            while not exhausted and len(in_flight) < min(workers, pool_size - len(entries)):
                checkpoint.boundary()
                row = next(ordered, None)
                if row is None:
                    exhausted = True
                    break
                key = row["ghsa_id"]
                if key in stale_resolutions:
                    resolution(row)
                identity = None
                if bank is not None:
                    links = source.fix_links(row)
                    if len(links) == 1:
                        repository, fix = next(iter(links))
                        try:
                            resolved = resolve_repository(repository, api)
                            repository = resolved.full_name
                        except eligibility.RepositoryNotFound:
                            resolved = None
                        except ValueError as exc:
                            if str(exc) != "http_failure":
                                raise
                            resolved = None  # decide() records this as a resilient skip.
                        identity = (repository, fix)
                        saved = decided.get(bank.key_for(*identity))
                        if saved is None and len(fix) < 40:
                            matches = [
                                value for value in decided.values() if value["repository"] == repository and value["fix"].startswith(fix)
                            ]
                            if len(matches) == 1:
                                saved = matches[0]
                                identity = (repository, saved["fix"])
                        if saved is None:
                            # A duplicate advisory can arrive before its pair's
                            # worker finishes. Share that pending result as well.
                            matching = [key for key, pair in identities.items() if pair[0] == repository and pair[1].startswith(fix)]
                            if len(matching) == 1:
                                pending.append((row, {"network": resolved.network if resolved else repository}, matching[0]))
                                break
                        if saved is not None:
                            decision = {"network": resolved.network if resolved is not None else repository}
                            blocked = eligibility.rejection(resolved, used, set()) if resolved is not None else None
                            if blocked:
                                decision["rejected"] = "used_" + blocked
                                pending.append((row, decision, None))
                            else:
                                result = {"ordinary_exclusions": saved["ordinary_exclusions"], "counts": saved["counts"]}
                                if saved["decision"] == "accept":
                                    result["entry"] = saved["entry"]
                                else:
                                    result["rejected"] = saved["reason"]
                                extraction_key = bank.key_for(*identity)
                                if extraction_key not in checkpoint.rows["extraction"]:
                                    checkpoint.put("extraction", extraction_key, result)
                                pending.append((row, decision, extraction_key))
                            break
                decision = resolution(row)
                extraction_key, future = None, None
                if "candidate" in decision:
                    candidate = source.Candidate(**decision["candidate"])
                    extraction_key = digest({"repository": candidate.repository, "advisory": key, "fix": candidate.fix})
                    if bank is not None:
                        extraction_key = bank.key_for(candidate.repository, candidate.fix)
                        identities[extraction_key] = (candidate.repository, candidate.fix)
                    if extraction_key not in checkpoint.rows["extraction"] and extraction_key not in in_flight.values():
                        checkpoint.boundary()
                        local = copy.copy(clones)
                        local.counts = Counter()
                        args = (candidate, None, local, fixes.get(candidate.repository, set()), seed)
                        try:
                            future = pool.submit(extract_repository, *args)
                        except BrokenProcessPool:
                            # Already-submitted jobs retain their ordered crash
                            # skips; only new jobs enter the replacement pool.
                            pool.shutdown(wait=True, cancel_futures=True)
                            pool = ProcessPoolExecutor(max_workers=workers, mp_context=context)
                            future = pool.submit(extract_repository, *args)
                        in_flight[future] = extraction_key
                elif bank is not None and identity is not None:
                    remember(*identity, decision)
                pending.append((row, decision, extraction_key))
                # Finalize cached decisions promptly (especially on resume), and
                # service completed jobs even during a long run of decide skips.
                if ready() or any(future.done() for future in in_flight):
                    break
            if ready():
                continue
            if in_flight:
                checkpoint.boundary()
                done, _ = wait(in_flight, return_when=FIRST_COMPLETED)
                for future in done:
                    collect(future)
                # Freed slots are refilled on the next pass even if the oldest
                # candidate is still running. No result() waits on that cursor.
    interrupted = False
    stopped = None
    try:
        yield iterate()
    except BaseException as exc:
        interrupted = not isinstance(exc, Exception)
        stopped = str(exc) if isinstance(exc, Stopped) else None
        raise
    finally:
        pool.shutdown(wait=True, cancel_futures=True)
        if not interrupted:
            for future in list(in_flight):
                if not future.cancelled():
                    collect(future)
            if stopped is not None:
                checkpoint.progress("stopped", reason=stopped)
 def publish(journal, assigned, seed, *, destination=None):
    """Idempotent publication from completed journal data, never inside the checkout."""
    public, private = [], []
    for row in assigned:
        if row["license_class"] == "permissive":
            public.append(row)
        else:
            private.append(row)
            public.append({"id": row["id"], "sha256": private_digest(row), "slice": row["slice"], "private": True})
    for name, rows in (("private-draft-p1.toml", private), ("draft-p1.toml", public)):
        path = (destination or journal.path) / name
        data = manifest(rows, seed).encode()
        if path.exists():
            if path.read_bytes() != data:
                raise ValueError("draft_exists")
        else:
            atomic(path, data)
 def run(
    root: Path,
    *,
    github,
    osv,
    clones,
    used: eligibility.UsedSet,
    seed: int,
    known_empty=None,
    journal_path=None,
    max_hours=None,
    clock=None,
    extract_workers=None,
    pool_size=300,
    slices=3,
    bank: CorpusBank | None = None,
 ) -> dict:
    validate_pool(pool_size, slices)
    workers = extract_workers if extract_workers is not None else getattr(clones, "extract_workers", 6)
    if workers < 1:
        raise ValueError("invalid_extract_workers")
    workers = min(workers, os.cpu_count() or 4)
    started = time.monotonic()
    report = {"status": "sourcing", "seed": seed, "candidates": {}, "rejections": {}, "ordinary_exclusions": {}}
    # Operational budget only: changing it must not invalidate journal resume inputs.
    report["extract_workers"] = workers
    report["extract_deadline_seconds"] = getattr(clones, "deadline_seconds", None)
    report["parse_deadline_seconds"] = getattr(clones, "parse_deadline_seconds", None)
    counts, rejected, ordinary_counts = Counter(), Counter(), Counter()
    checkpoint = None
    scratch = ExitStack()
    try:
        decided = bank.decided() if bank is not None else {}
        banked = bank.resolved() if bank is not None else {}
        accepted, reusable = split_decided(decided, contract=EXTRACTION_CONTRACT)
        decided = {key: value for key, value in decided.items() if key in reusable}
        known_empty = set(known_empty or ())
        used.report(known_empty)
        cache = getattr(clones, "cache", root.parent / (root.name + "-cache"))
        path = external(root, journal_path or cache / "journal")
        journal_directory = path
        if bank is not None:
            # Local records are a disposable cursor, never a cross-run authority.
            path.mkdir(parents=True, exist_ok=True, mode=0o700)
            journal_directory = Path(scratch.enter_context(tempfile.TemporaryDirectory(prefix="cursor-", dir=path)))
        checkpoint = Journal(
            journal_directory,
            max_hours=max_hours,
            clock=clock,
            rate_limit=lambda: getattr(getattr(github, "transport", None), "rate_limit", {}),
        )
        with checkpoint.open(inputs(used, seed, known_empty, clones, pool_size=pool_size, slices=slices)):
            checkpoint.boundary()
            api = BankedGitHub(github, checkpoint, bank) if bank is not None else ResolvedGitHub(github, checkpoint)
            checkpoint.rows["eligibility"].update(
                {key: body["result"] for key, body in banked.items() if body["resolution_contract"] == RESOLUTION_CONTRACT}
            )
            used = copy.deepcopy(used)  # canonicalization must not mutate the resume input
            eligibility.canonicalize_used(used, api)
            report["used_set"] = used.report(known_empty)
            rows = bank.cached_advisories(contract=RESOLUTION_CONTRACT) if bank is not None else None
            if rows is None:
                try:
                    rows = enumerate_advisories(api, checkpoint)
                except InstrumentFailure as exc:
                    if str(exc) != "empty_advisories" or not accepted:
                        raise
                    rows = []
                if bank is not None:
                    bank.cache_advisories(rows, contract=RESOLUTION_CONTRACT)
            if bank is not None:
                # Retain accepted entries even if their advisory disappeared upstream.
                present = {row["ghsa_id"] for row in rows}
                for entry in accepted:
                    if entry["advisory"] not in present:
                        rows.append(
                            {
                                "ghsa_id": entry["advisory"],
                                "published_at": "2026-06-02" if entry["post_cutoff"] else "2026-06-01",
                                "vulnerabilities": [{"package": {"ecosystem": entry["ecosystem"]}}],
                                "references": [f"https://github.com/{entry['repository']}/commit/{entry['fix']}"],
                            }
                        )
                        present.add(entry["advisory"])
            report["advisories"] = len(rows)
            fixes_by_repo = advisory_index(rows, api)
            selected_networks, entries = set(), []
            instrument_failures = 0
            with ordered_extractions(
                source.ordered_advisories(rows, seed),
                api,
                osv,
                used,
                clones,
                fixes_by_repo,
                seed,
                checkpoint,
                entries,
                workers,
                pool_size,
                bank=bank,
                decided=decided,
                stale_resolutions={key for key, body in banked.items() if body["resolution_contract"] != RESOLUTION_CONTRACT},
            ) as outcomes:
                for row, decision, result in outcomes:
                    counts[source.ecosystem(row)] += 1
                    if decision.get("network") in selected_networks:
                        # Serial decide skipped this candidate entirely. Even a failed
                        # speculative extraction must not affect the systemic guard.
                        rejected["fork_network"] += 1
                    elif "rejected" in decision:
                        rejected[decision["rejected"]] += 1
                        instrument_failures += int(decision["rejected"] == "decide_http_failure")
                    else:
                        ordinary_counts.update(result["ordinary_exclusions"])
                        if "rejected" in result:
                            rejected[result["rejected"]] += 1
                            instrument_failures += int(
                                result["rejected"].startswith("extract_") or result["rejected"] == "decide_http_failure"
                            )
                        else:
                            selected_networks.add(decision["network"])
                            entries.append(result["entry"])
                    # A low-yield draw can accumulate unbounded candidate failures;
                    # only zero accepted entries indicate a systemic failure.
                    if instrument_failures >= 25 and not entries:
                        raise extract.InstrumentFailure("systemic_extraction_failure")
                    if len(entries) == pool_size:
                        break
            report.update(
                {
                    "repositories": len(entries),
                    "candidates": dict(counts),
                    "rejections": dict(rejected),
                    "ordinary_exclusions": dict(ordinary_counts),
                }
            )
            checkpoint.boundary()
            if len(entries) != pool_size:
                report["status"] = "insufficient_repositories"
                checkpoint.progress(report["status"])
                return report
            assigned = assign_slices(entries, seed=seed, pool_size=pool_size, slices=slices)
            completion = {"manifest_sha256": digest(assigned), "repositories": len(entries)}
            if "all" not in checkpoint.rows["completion"]:
                checkpoint.put("completion", "all", completion)
            elif checkpoint.rows["completion"]["all"] != completion:
                raise ValueError("journal_completion_mismatch")
            checkpoint.boundary()
            publish(checkpoint, assigned, seed, destination=path if bank is not None else None)
            report.update(
                {
                    "status": "draft",
                    "changes": pool_size * 13,
                    "slices": slices,
                    "license_split": dict(Counter(e["license_class"] for e in entries)),
                    "methods": dict(Counter(e["changes"][0]["method"] for e in entries)),
                    "post_cutoff": sum(e["post_cutoff"] for e in entries),
                    **completion,
                }
            )
            checkpoint.progress("draft")
            return report
    except ResumeMismatch as exc:
        report.update({"status": "resume_refused", "changed_parameters": exc.parameters})
        return report
    except Stopped as exc:
        report.update({"status": "stopped", "reason": str(exc)})
        return report
    except Exception as exc:
        report.update({"status": "instrument_failure", "error_type": type(exc).__name__})
        return report
    finally:
        scratch.close()
        report.update({"candidates": dict(counts), "rejections": dict(rejected), "ordinary_exclusions": dict(ordinary_counts)})
        report["instrument"] = dict(clones.counts)
        report["wall_seconds"] = round(time.monotonic() - started, 3)
        report["github_calls"] = github.calls
        report["osv_calls"] = osv.calls
        report["github_http_attempts"] = getattr(getattr(github, "transport", None), "attempts", github.calls)
        report["osv_http_attempts"] = getattr(getattr(osv, "transport", None), "attempts", osv.calls)
 def main(argv: list[str] | None = None) -> int:
    from openultrasast import config
    from openultrasast.plane import memory
    from openultrasast.plane.reconciler import results_root
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path.cwd())
    parser.add_argument("--cache", type=Path)
    parser.add_argument("--max-hours", type=float, help="Stop between units after this many hours per invocation")
    parser.add_argument("--extract-deadline", type=float, default=240.0, help="Extraction wall-clock budget per repository in seconds")
    parser.add_argument(
        "--parse-deadline",
        type=float,
        default=120.0,
        help="Extra wall-clock budget in seconds for the Python parse phase beyond --extract-deadline",
    )
    parser.add_argument("--extract-workers", type=int, default=6, help="Maximum extraction processes, capped to CPU cores (default: 6)")
    parser.add_argument("--pool-size", type=int, default=300, help="Repositories to accept (default: 300)")
    parser.add_argument("--slices", type=int, default=3, help="Equal-sized slices (default: 3)")
    parser.add_argument("--seed", type=int, default=20260601)
    parser.add_argument("--bank", nargs="?", const="unseen", default="", help="Corpus bucket prefix; enables durable decisions")
    parser.add_argument("--local-store")
    parser.add_argument("--s3-store", default="s3://")
    parser.add_argument("--pointer-manifest", type=Path, action="append", default=[])
    parser.add_argument("--known-empty", choices=(*eligibility.SOURCES, "memory_local", "memory_s3"), action="append", default=[])
    args = parser.parse_args(argv)
    try:
        validate_pool(args.pool_size, args.slices)
    except ValueError as exc:
        parser.error(str(exc))
    if args.extract_workers < 1:
        parser.error("--extract-workers must be at least 1")
    try:
        config.load_dotenv(args.root / ".env")
        # Refuse an existing draft before doing any network work.
        if any((args.root / p).exists() for p in ("benchmarks/unseen/draft-p1.toml", "benchmarks/unseen/private/draft-p1.toml")):
            raise FileExistsError("draft_exists")
        clones = Clones(
            args.root,
            args.cache or results_root() / "unseen-draft",
            deadline_seconds=args.extract_deadline,
            parse_deadline_seconds=args.parse_deadline,
            extract_workers=args.extract_workers,
        )
        stores = {
            "local": memory.open_store(args.local_store or "file://" + str(results_root() / "memory"), read_only=True),
            "s3": memory.open_store(args.s3_store, read_only=True),
        }
        used = eligibility.build_used(args.root, stores=stores, pointer_manifests=args.pointer_manifest)
        bank = CorpusBank(CorpusObjects(**corpus_settings()), seed=args.seed, prefix=args.bank) if args.bank else None
        report = run(
            args.root,
            github=source.GitHub(os.environ.get("GH_TOKEN", "")),
            osv=source.OSV(),
            clones=clones,
            used=used,
            seed=args.seed,
            pool_size=args.pool_size,
            slices=args.slices,
            known_empty=set(args.known_empty),
            journal_path=clones.cache / "journal",
            max_hours=args.max_hours,
            bank=bank,
        )
    except Exception as exc:
        report = {"status": "instrument_failure", "error_type": type(exc).__name__}
    print(json.dumps(report, sort_keys=True))
    return 0 if report["status"] in {"draft", "stopped"} else 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,379 @@
 """Read-only used-set collection. Only counts, source labels and digests leave this module's CLI.
 Run from the repository root: python -m benchmarks.unseen.eligibility --help.
 Population v3 is exclusively the existing guard's responsibility.
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import re
 import tomllib
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
 from urllib.parse import urlsplit
 import yaml
 from openultrasast.plane.memory import MemoryStore
 URL = re.compile(r"github\.com/([\w.-]+/[\w.-]+)", re.I)
 NAME = re.compile(r"[\w.-]+/[\w.-]+")
 SOURCES = ("pairs", "pointers", "populations", "harvest", "units", "measurements", "sweep")
 def normalize(value: str) -> str:
    text = value.strip().lower().rstrip("/")
    if NAME.fullmatch(text):
        name = text.removesuffix(".git")
    else:
        # Structured fields must be identities, not prose containing a URL.
        if any(char.isspace() for char in text):
            raise ValueError("invalid_repository")
        url = urlsplit(text if "://" in text else "https://" + text)
        if url.scheme not in {"http", "https", "ssh", "git"} or not url.hostname or "." not in url.hostname:
            raise ValueError("invalid_repository")
        parts = url.path.strip("/").split("/")
        if len(parts) < 2:
            raise ValueError("invalid_repository")
        name = "/".join(parts[:2]).removesuffix(".git")
        if not NAME.fullmatch(name):
            raise ValueError("invalid_repository")
        if url.hostname != "github.com":
            return url.hostname + "/" + name
    if not NAME.fullmatch(name) or any(part in {".", ".."} for part in name.split("/")):
        raise ValueError("invalid_repository")
    return name
 def excluded(path: Path) -> bool:
    return any("v3" in part.lower() or part in {".git", "__pycache__", ".venv"} for part in path.parts)
 def repositories(value: object, counts: dict[str, int] | None = None) -> set[str]:
    """Structured repo fields include bare owner/name pointers; URLs also occur in prose."""
    found = set()
    if isinstance(value, dict):
        for key, item in value.items():
            if key in {"repo", "fix_repo", "repository", "full_name", "origin"} or (key == "group" and "unit" in value):
                try:
                    if not isinstance(item, str):
                        raise ValueError("invalid_repository")
                    found.add(normalize(item))
                except ValueError:
                    if counts is not None:
                        counts["skipped_values"] = counts.get("skipped_values", 0) + 1
            else:
                found.update(repositories(item, counts))
    elif isinstance(value, list):
        for item in value:
            found.update(repositories(item, counts))
    elif isinstance(value, str):
        found.update(normalize(m[1]) for m in URL.finditer(value))
    return found
 def pointer_repositories(value: object, counts: dict[str, int] | None = None) -> set[str]:
    if isinstance(value, dict):
        if value.get("vendored") is False:
            return repositories(value, counts)
        return set().union(*(pointer_repositories(v, counts) for v in value.values()))
    if isinstance(value, list):
        return set().union(*(pointer_repositories(v, counts) for v in value))
    return set()
 def parse(path: Path, raw: bytes) -> object:
    structured = path.suffix in {".toml", ".json", ".jsonl", ".yaml", ".yml"}
    text = raw.decode("utf-8", errors="strict" if structured else "ignore")
    if path.suffix == ".toml":
        return tomllib.loads(text)
    if path.suffix == ".json":
        return json.loads(text)
    if path.suffix == ".jsonl":
        return [json.loads(line) for line in text.splitlines() if line.strip()]
    if path.suffix in {".yaml", ".yml"}:
        documents = list(yaml.safe_load_all(text))
        return documents[0] if len(documents) == 1 else documents
    return text
@dataclass
 class UsedSet:
    sources: dict[str, set[str]] = field(default_factory=lambda: {label: set() for label in SOURCES})
    instrument: dict[str, dict[str, int]] = field(default_factory=dict)
    def add(self, label: str, names: set[str], size: int, files: int = 1, skipped_values: int = 0) -> None:
        self.sources.setdefault(label, set()).update(names)
        counts = self.instrument.setdefault(label, {"files": 0, "bytes": 0, "rows": 0, "skipped_values": 0})
        counts["files"] += files
        counts["bytes"] += size
        counts["rows"] += len(names)
        counts["skipped_values"] += skipped_values
    def report(self, known_empty: set[str] | None = None) -> dict:
        known_empty = known_empty or set()
        if known_empty - self.sources.keys():
            raise ValueError("unknown_source_label")
        records = {}
        for label, names in self.sources.items():
            counts = self.instrument.get(label, {"files": 0, "bytes": 0, "rows": 0, "skipped_values": 0})
            if not counts["rows"] and label not in known_empty:
                raise ValueError("empty_source:" + label)
            records[label] = {**counts, "count": len(names), "known_empty": label in known_empty}
        names = set().union(*self.sources.values())
        return {"sources": records, "count": len(names), "sha256": hashlib.sha256("\n".join(sorted(names)).encode()).hexdigest()}
 def build_used(root: Path, *, stores: Mapping[str, MemoryStore] | None = None, pointer_manifests: Iterable[Path] = ()) -> UsedSet:
    used = UsedSet()
    def read(label: str, paths: Iterable[Path], structured: bool = True) -> list[object]:
        values = []
        for path in sorted(set(paths)):
            if excluded(path):
                continue
            raw = path.read_bytes()  # failure is an instrument failure, never a quiet empty source
            value = parse(path, raw) if structured else raw.decode("utf-8", errors="ignore")
            counts: dict[str, int] = {}
            names = repositories(value, counts)
            used.add(label, names, len(raw), skipped_values=counts.get("skipped_values", 0))
            if label == "pairs":
                pointer_counts: dict[str, int] = {}
                pointers = pointer_repositories(value, pointer_counts)
                if pointers or pointer_counts:
                    used.add("pointers", pointers, len(raw), skipped_values=pointer_counts.get("skipped_values", 0))
            values.append(value)
        return values
    pairs = root / "benchmarks/pairs"
    read("pairs", (p for p in pairs.rglob("*") if p.is_file() and p.suffix in {".toml", ".json", ".jsonl", ".csv", ".yaml", ".yml"}))
    read("pointers", pointer_manifests)
    read("populations", (p for p in (root / "benchmarks/independent").glob("population-v[12].toml")))
    read("harvest", (p for directory in pairs.glob("advisory-fixes*") for p in directory.rglob("*.toml")))
    units = set((root / "plane/experiments").glob("*.units.jsonl"))
    for path in (root / "plane/experiments").glob("*.y*ml"):
        if excluded(path):
            continue
        raw = path.read_bytes()
        manifest = parse(path, raw)
        counts = {}
        names = repositories(manifest, counts)
        used.add("units", names, len(raw), skipped_values=counts.get("skipped_values", 0))
        if isinstance(manifest, dict) and manifest.get("units_file"):
            declared = root / Path(manifest["units_file"]).expanduser()
            if declared.exists():  # an unregistered plan may not have frozen units yet
                units.add(declared)
    for label, store in (stores or {}).items():
        if label not in {"local", "s3"}:
            raise ValueError("unknown_store_label")
        source = "memory_" + label
        used.add(source, set(), 0, 0)
        # Read actual objects, not a serialized row size masquerading as bytes read.
        for key in store._keys("repos/"):
            if not key.endswith(".jsonl") or excluded(Path(key)):
                continue
            result = store._get(key)
            if result is None:
                raise ValueError("missing_memory_object")
            raw = result[0]
            rows = parse(Path("rows.jsonl"), raw)
            names = set()
            counts = {}
            for row in rows:
                if row.get("kind") == "example" and "repo" in row:
                    names.update(repositories({"repo": row["repo"]}, counts))
                if row.get("kind") == "experiment" and row.get("units_file"):
                    registered = root / Path(row["units_file"]).expanduser()
                    if row.get("units_digest") or registered.exists():
                        units.add(registered)
            used.add(source, names, len(raw), skipped_values=counts.get("skipped_values", 0))
    read("units", units)
    read("measurements", (p for top in ("measurements", "experiments") for p in (root / "benchmarks" / top).rglob("*") if p.is_file()))
    read(
        "sweep",
        (
            p
            for top in ("benchmarks", "src", "tests", "plane", ".kiro")
            for p in (root / top).rglob("*")
            if p.is_file() and not p.is_relative_to(root / "benchmarks/unseen") and not excluded(p)
        ),
        structured=False,
    )
    return used
@dataclass(frozen=True)
 class Resolution:
    full_name: str
    names: frozenset[str]
    network: str
 def resolve(candidate: str, api) -> Resolution:
    name = normalize(candidate)
    if name.count("/") > 1:
        return Resolution(name, frozenset({name}), name)
    data = api.get_repo(name)
    canonical = normalize(data["full_name"])
    names = {name, canonical, *(normalize(n) for n in data.get("former_names", []))}
    for key in ("parent", "source"):
        if data.get(key):
            names.add(normalize(data[key]["full_name"]))
    network = normalize((data.get("source") or data.get("parent") or data)["full_name"])
    return Resolution(canonical, frozenset(names), network)
 def canonicalize_used(used: UsedSet, api) -> None:
    """Resolve old used names too: GitHub exposes redirects, not a complete rename history."""
    cache = {}
    for names in used.sources.values():
        for name in sorted(names):
            if name not in cache:
                try:
                    cache[name] = resolve(name, api)
                except RepositoryNotFound:
                    cache[name] = Resolution(name, frozenset({name}), name)
            names.update(cache[name].names)
 def rejection(candidate: Resolution, used: UsedSet, selected: set[str]) -> str | None:
    for label, names in used.sources.items():
        if candidate.names & names:
            return label
    if candidate.network in selected:
        return "fork_network"
    selected.add(candidate.network)
    return None
 class RepositoryNotFound(ValueError):
    """A historical or synthetic used identity no longer resolves; retain it verbatim."""
 class GitHub:
    """Coordinator-only GET client. Exceptions never disclose request URLs or tokens."""
    def __init__(self, token: str):
        if not token:
            raise ValueError("missing_gh_token")
        self.token = token
    def get_repo(self, name: str) -> dict:
        from urllib.error import HTTPError
        from urllib.request import Request, urlopen
        request = Request(
            "https://api.github.com/repos/" + normalize(name),
            headers={
                "Authorization": "Bearer " + self.token,
                "Accept": "application/vnd.github+json",
            },
        )
        try:
            with urlopen(request, timeout=30) as response:
                return json.load(response)
        except HTTPError as exc:
            if exc.code == 404:
                raise RepositoryNotFound("github_not_found") from None
            raise ValueError("github_resolution_failed") from None
        except Exception:
            raise ValueError("github_resolution_failed") from None
 def verify_tests(root: Path) -> dict:
    """The coordinator runs the guard as a black box; only exit codes and counts escape."""
    import subprocess
    import sys
    import tempfile
    from xml.etree import ElementTree
    with tempfile.TemporaryDirectory() as directory:
        report = Path(directory) / "tests.xml"
        done = subprocess.run(
            [
                sys.executable,
                "-m",
                "pytest",
                "-q",
                "-p",
                "no:cacheprovider",
                "tests/test_unseen_eligibility.py",
                "tests/test_unseen_ledger.py",
                "tests/test_independent_population.py",
                "--junitxml=" + str(report),
            ],
            cwd=root,
            stdin=subprocess.DEVNULL,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
        )
        if done.returncode != 0:
            raise ValueError("guard_or_tests_failed")
        suites = ElementTree.parse(report).getroot().iter("testsuite")
        counts = {key: 0 for key in ("tests", "failures", "errors", "skipped")}
        for suite in suites:
            for key in counts:
                counts[key] += int(suite.attrib[key])
        if not counts["tests"]:
            raise ValueError("empty_test_run")
        return {"guard": "green", "test_exit_code": done.returncode, "tests": counts}
 def main(argv: list[str] | None = None) -> int:
    import os
    from openultrasast import config
    from openultrasast.plane import memory
    from openultrasast.plane.reconciler import results_root
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path.cwd())
    parser.add_argument("--local-store", default=None)
    parser.add_argument("--s3-store", default="s3://")
    parser.add_argument("--pointer-manifest", type=Path, action="append", default=[])
    parser.add_argument("--known-empty", choices=(*SOURCES, "memory_local", "memory_s3"), action="append", default=[])
    parser.add_argument("--output", type=Path)
    parser.add_argument("--verify-tests", action="store_true")
    args = parser.parse_args(argv)
    step = "open_stores"
    try:
        config.load_dotenv(args.root / ".env")
        stores = {
            "local": memory.open_store(args.local_store or "file://" + str(results_root() / "memory"), read_only=True),
            "s3": memory.open_store(args.s3_store, read_only=True),
        }
        step = "build_used"
        used = build_used(args.root, stores=stores, pointer_manifests=args.pointer_manifest)
        step = "report"
        used.report(set(args.known_empty))  # prove inputs before API work
        step = "canonicalize"
        canonicalize_used(used, GitHub(os.environ.get("GH_TOKEN", "")))
        step = "report"
        report = used.report(set(args.known_empty))
        if args.verify_tests:
            step = "verify_tests"
            report.update(verify_tests(args.root))
        step = "report"
        text = json.dumps(report, sort_keys=True, indent=2) + "\n"
        if args.output:
            args.output.parent.mkdir(parents=True, exist_ok=True)
            with args.output.open("x") as handle:
                handle.write(text)
        print(text, end="")
        return 0
    except Exception as exc:
        # Source paths, store exceptions and JSON parser errors can contain repository names.
        report = {"status": "instrument_failure", "step": step, "type": type(exc).__name__}
        if str(exc) in {"empty_source:" + label for label in (*SOURCES, "memory_local", "memory_s3")}:
            report["source"] = str(exc).partition(":")[2]
        print(json.dumps(report))
        return 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,548 @@
 """Git-only change extraction; clients and subprocess execution are injectable.
 No scanner, engine or model runs here. Function boundaries are syntax, not a security
 judgement: the first removed code line of a fix is the SZZ sink proxy. Ambiguous sites
 are dropped, and the recorded SZZ bias remains subject to task 2.6's label check.
 """
 from __future__ import annotations
 import ast
 import json
 import re
 import signal
 import subprocess
 import threading
 import time
 from contextlib import contextmanager
 from pathlib import Path
 from .source import Candidate, Rejected
 # Bump only when accept/reject outcomes or accepted entry bytes change.
 EXTRACTION_CONTRACT = "v1"
 # Bump only when enumeration, eligibility or source.candidate outputs change.
 RESOLUTION_CONTRACT = "v1"
 LANGUAGES = {".py", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".php", ".java"}
 HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@", re.M)
 SHA = re.compile(r"[a-f0-9]{40}")
 BIAS = {
    "introducing": "SZZ last-writer proxy: refactors, moves and reformats can misidentify the introduction in either direction.",
    "last_touch": "Pessimistic lower bound: the flaw may already exist in base, so a delta hook can correctly stay quiet.",
 }
 class InstrumentFailure(ValueError):
    """A failed read or command must never masquerade as an empty history."""
 class ExtractionTimeout(Rejected):
    """A slow repository is skipped without aborting the draft."""
@contextmanager
 def process_deadline(seconds: float | None):
    """Bound Python work in a worker's main thread; cancel the alarm on exit."""
    if (
        seconds is None
        or seconds <= 0
        or threading.current_thread() is not threading.main_thread()
        or not all(hasattr(signal, name) for name in ("SIGALRM", "ITIMER_REAL", "setitimer"))
    ):
        yield
        return
    def expired(signum, frame):
        raise ExtractionTimeout("wallclock_timeout")
    previous = signal.getsignal(signal.SIGALRM)
    installed = False
    try:
        try:
            signal.signal(signal.SIGALRM, expired)
            installed = True
            signal.setitimer(signal.ITIMER_REAL, seconds)
        except ValueError:
            # Unsupported signal operations must not prevent extraction.
            if installed:
                signal.signal(signal.SIGALRM, previous)
                installed = False
        yield
    finally:
        if installed:
            try:
                signal.setitimer(signal.ITIMER_REAL, 0)
            finally:
                signal.signal(signal.SIGALRM, previous)
 class Git:
    def __init__(self, path: Path, *, runner=None, limit_bytes: int | None = None, deadline_seconds: float | None = None, _now=None):
        self._now = _now or time.monotonic
        self.started = self._now()
        self.deadline_seconds = deadline_seconds
        self.path = path
        self.runner = runner or subprocess.run
        self.bytes_read = 0
        self.files_read = 0
        self.last_blob_bytes = 0
        self.limit_bytes = limit_bytes
    def command_timeout(self) -> float:
        if self.deadline_seconds is None:
            return 180
        remaining = self.deadline_seconds - (self._now() - self.started)
        if remaining <= 0:
            raise ExtractionTimeout("extraction_timeout")
        return min(180, remaining)
    def run(self, *args: str, allowed=(0,)) -> str:
        timeout = self.command_timeout()
        try:
            done = self.runner(
                ["git", "-c", "core.quotePath=false", "-C", str(self.path), *args],
                stdin=subprocess.DEVNULL,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
                timeout=timeout,
                check=False,
            )
        except subprocess.TimeoutExpired:
            raise ExtractionTimeout("extraction_timeout") from None
        except ExtractionTimeout:
            raise
        except Exception:
            raise InstrumentFailure("git_launch_failed") from None
        if done.returncode not in allowed:
            raise InstrumentFailure("git_exit_" + str(done.returncode))
        if self.limit_bytes is not None and self.disk_bytes() > self.limit_bytes:
            raise InstrumentFailure("clone_size_cap")
        self.last_blob_bytes = len(done.stdout)
        return done.stdout.decode("utf-8", errors="replace")
    def disk_bytes(self) -> int:
        # git churns .git/objects/pack (incl. transient *.rev) during on-demand blob
        # fetches, so a path rglob just listed can vanish before stat(): skip it.
        total = 0
        for p in self.path.rglob("*"):
            try:
                if p.is_file() and not p.is_symlink():
                    total += p.stat().st_size
            except OSError:
                continue
        return total
    def parents(self, sha: str) -> list[str]:
        return self.run("rev-list", "--parents", "-n", "1", sha).split()[1:]
    def blob(self, sha: str, path: str) -> str | None:
        # Missing is established by a successful tree read, never by swallowing a show error.
        if not self.run("ls-tree", sha, "--", path).strip():
            return None
        text = self.run("show", f"{sha}:{path}")
        if Path(path).suffix in LANGUAGES:
            self.files_read += 1
            self.bytes_read += self.last_blob_bytes
        return text
    def stats(self, base: str, head: str) -> list[tuple[str, int, int]]:
        rows = []
        for line in self.run("diff", "--no-renames", "--numstat", base, head, "--").splitlines():
            added, removed, path = line.split("\t", 2)
            rows.append((path, int(added) if added.isdigit() else 0, int(removed) if removed.isdigit() else 0))
        return rows
    def hunks(self, base: str, head: str, path: str) -> list[tuple[int, int, int, int]]:
        diff = self.run("diff", "--no-ext-diff", "--no-renames", "-U0", base, head, "--", path)
        return [(int(m[1]), int(m[2] or 1), int(m[3]), int(m[4] or 1)) for m in HUNK.finditer(diff)]
    def ancestor(self, older: str, newer: str) -> bool:
        # rev-list avoids interpreting a command failure as a negative ancestry result.
        return not self.run("rev-list", "--max-count=1", older, "--not", newer).strip()
    def blame(self, revision: str, path: str, line: int) -> tuple[str, str, int]:
        text = self.run("blame", "-w", "-M", "-C", "--porcelain", f"-L{line},{line}", revision, "--", path)
        header = text.splitlines()[0].split()
        if len(header) < 3 or not SHA.fullmatch(header[0]):
            raise InstrumentFailure("invalid_blame")
        filename = next((row[9:] for row in text.splitlines() if row.startswith("filename ")), path)
        if filename.startswith('"'):
            filename = json.loads(filename)
        return header[0], filename, int(header[1])
 def functions(path: str, text: str) -> list[tuple[str, int, int]]:
    """Conservative syntax boundaries. No scanner import; unresolved sites are rejected."""
    if Path(path).suffix == ".py":
        try:
            tree = ast.parse(text)
        except SyntaxError:
            raise Rejected("function_parse") from None
        return [
            (n.name, n.lineno, n.end_lineno or n.lineno) for n in ast.walk(tree) if isinstance(n, ast.FunctionDef | ast.AsyncFunctionDef)
        ]
    # Blank comments and quoted strings before brace matching. Keep newlines/offsets.
    masked = re.sub(
        r'/\*.*?\*/|//[^\n]*|\#[^\n]*|"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\'|`(?:\\.|[^`\\])*`',
        lambda m: "".join("\n" if c == "\n" else " " for c in m[0]),
        text,
        flags=re.S,
    )
    declaration = re.compile(
        r"\bfunction\s*&?\s*(\w+)\s*\([^)]*\)\s*(?::[^\n{]+)?\s*\{|"
        r"\b(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|\w+)\s*=>\s*\{|"
        r"\b([\w$]+)\s*\([^;{}]*\)\s*(?:throws\s+[\w., ]+)?\s*\{"
    )
    found = []
    for match in declaration.finditer(masked):
        name = next(g for g in match.groups() if g)
        if name in {"if", "while", "for", "switch", "catch", "with", "synchronized"}:
            continue
        depth = 1
        end = match.end()
        while end < len(masked) and depth:
            depth += (masked[end] == "{") - (masked[end] == "}")
            end += 1
        if depth == 0:
            found.append((name, masked.count("\n", 0, match.start()) + 1, masked.count("\n", 0, end) + 1))
    return found
 def enclosing(path: str, text: str, line: int, *, global_ok=False) -> tuple[str, int, int] | None:
    spans = [s for s in functions(path, text) if s[1] <= line <= s[2]]
    if spans:
        return min(spans, key=lambda s: s[2] - s[1])
    return ("<global>", 1, max(1, len(text.splitlines()))) if global_ok else None
 def normalized(text: str) -> str:
    return re.sub(r"\s+", "", text)
 def site_at(git, revision: str, path: str, name: str):
    text = git.blob(revision, path)
    if text is None:
        return None
    spans = [("<global>", 1, max(1, len(text.splitlines())))] if name == "<global>" else [s for s in functions(path, text) if s[0] == name]
    if len(spans) != 1:
        return None
    return text, spans[0]
 def fix_sites(git, fix: str, parent: str, *, global_ok=False) -> list[dict]:
    sites = []
    for path, _, _ in git.stats(parent, fix):
        if Path(path).suffix not in LANGUAGES:
            continue
        text = git.blob(parent, path)
        if text is None:
            continue
        lines = text.splitlines()
        for start, count, _, _ in git.hunks(parent, fix, path):
            for line in range(max(1, start), max(1, start) + max(1, count)):
                if line > len(lines):
                    continue
                span = enclosing(path, text, line, global_ok=global_ok)
                if span is None:
                    continue
                sink_line = line if count else span[1]
                sink = lines[sink_line - 1]
                if not sink.strip() or sink.lstrip().startswith(("#", "//", "/*", "*")):
                    continue
                key = (path, span[0])
                if any((s["path"], s["function"]) == key for s in sites):
                    continue
                sites.append({"path": path, "function": span[0], "line": sink_line, "text": sink, "absence": count == 0, "span": span})
    return sites
 def version_bracket(git, candidate: Candidate, revision: str) -> bool:
    if not candidate.first_affected:
        return True
    tags = git.run("tag", "--sort=version:refname").splitlines()
    matching = [t for t in tags if t.removeprefix("v") == candidate.first_affected]
    if len(matching) != 1:
        return False
    affected = matching[0]
    earlier = [t for t in tags[: tags.index(affected)] if git.ancestor(t, affected)]
    return bool(earlier) and git.ancestor(revision, affected) and not git.ancestor(revision, earlier[-1])
 def change_files(git, base: str, head: str) -> list[dict]:
    return [
        {"path": path, "head_lines": [[max(1, new), max(1, new + max(count, 1) - 1)] for _, _, new, count in git.hunks(base, head, path)]}
        for path, _, _ in git.stats(base, head)
    ]
 def introducing(git, candidate: Candidate) -> dict:
    from collections import Counter
    if git.parents(candidate.fix) != [candidate.parent]:
        raise Rejected("fix_parents")
    sites = fix_sites(git, candidate.fix, candidate.parent, global_ok=candidate.family == "config_secrets")
    reasons = Counter()
    def record(method, base, head, path, name):
        resolved = site_at(git, head, path, name)
        if resolved is None:
            return None
        return {
            "kind": "vulnerability",
            "base": base,
            "head": head,
            "method": method,
            "family": candidate.family,
            "function": name,
            "path": path,
            "function_lines": list(resolved[1][1:]),
            "files": change_files(git, base, head),
            "post_cutoff": candidate.post_cutoff,
            "advisory": candidate.advisory,
            "bias": BIAS[method],
            "fallback_reasons": dict(reasons),
        }
    for site in sites:
        revision, path, line = candidate.parent, site["path"], site["line"]
        for _ in range(6):  # initial blame plus at most five walk-back steps
            blamed, blamed_path, blamed_line = git.blame(revision, path, line)
            parents = git.parents(blamed)
            if len(parents) != 1:
                reasons["merge_or_root"] += 1
                break
            base = parents[0]
            head_site = site_at(git, blamed, blamed_path, site["function"])
            if head_site is None:
                reasons["unresolved_function"] += 1
                break
            parent_text = git.blob(base, blamed_path)
            if parent_text is not None and site["function"] != "<global>":
                matching = [span for span in functions(blamed_path, parent_text) if span[0] == site["function"]]
                if len(matching) > 1:
                    reasons["ambiguous_parent"] += 1
                    break
            old_site = site_at(git, base, blamed_path, site["function"])
            occurrences = []
            if old_site:
                text, (_, start, end) = old_site
                occurrences = [
                    i for i, value in enumerate(text.splitlines(), 1) if start <= i <= end and normalized(value) == normalized(site["text"])
                ]
            if occurrences:
                reasons["text_present"] += 1
                revision, path, line = base, blamed_path, occurrences[0]
                continue
            stats = git.stats(base, blamed)
            if len(stats) > 50 or sum(a + d for _, a, d in stats) > 2000:
                reasons["size_cap"] += 1
                break
            if not version_bracket(git, candidate, blamed):
                reasons["version_bracket"] += 1
                break
            result = record("introducing", base, blamed, blamed_path, site["function"])
            if result:
                return result
        else:
            reasons["walkback_limit"] += 1
    for site in sites:
        # Numeric function extent implements log -L for all five languages, including
        # languages for which Git has no built-in :function: driver.
        _, start, end = site["span"]
        history = git.run("log", "--format=%H", "--no-patch", f"-L{start},{end}:{site['path']}", candidate.parent).splitlines()
        if not history:
            continue
        latest = history[0]
        parents = git.parents(latest)
        if len(parents) != 1:
            continue
        result = record("last_touch", parents[0], candidate.parent, site["path"], site["function"])
        if result:
            return result
    raise Rejected("no_range")
 SECURITY = re.compile(r"secur|cve|ghsa|vuln|inject|xss|csrf|ssrf|exploit|sanitiz|escap", re.I)
 DEPENDENCY = re.compile(r"\bbump\b|\bupgrade .* from\b", re.I)
 MANIFESTS = {
    "package.json",
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "composer.json",
    "composer.lock",
    "pom.xml",
    "build.gradle",
    "build.gradle.kts",
    "gradle.lockfile",
    "pyproject.toml",
    "setup.py",
    "setup.cfg",
    "Pipfile",
    "Pipfile.lock",
    "poetry.lock",
    "uv.lock",
 }
 def generated_path(path: str) -> bool:
    return bool({"vendor", "node_modules", "dist"} & set(Path(path).parts)) or path.endswith(".min.js")
 def manifest(path: str) -> bool:
    name = Path(path).name
    return name in MANIFESTS or name.endswith(".lock") or bool(re.fullmatch(r"requirements[^/]*\.txt", name))
 def ordinary_rejection(row: dict, fixes: set[str], known_functions: set[tuple[str, str]]) -> str | None:
    if len(row["parents"]) != 1:
        return "merge_or_root"
    if row["head"] in fixes:
        return "advisory_fix"
    if SECURITY.search(row["message"]):
        return "security"
    if re.search(r"^Revert|This reverts commit", row["message"], re.I | re.M):
        return "revert"
    if re.search(r"dependabot|renovate|\[bot\]", row["author"], re.I) or DEPENDENCY.search(row["message"]):
        return "dependency"
    files = row["files"]
    if files and all(manifest(f["path"]) for f in files):
        return "manifest_only"
    source = [f for f in files if Path(f["path"]).suffix in LANGUAGES and not manifest(f["path"])]
    if not source:
        return "no_source"
    if all(f["generated"] or generated_path(f["path"]) for f in source):
        return "generated"
    if any((f["path"], name) in known_functions for f in files for name in f["functions"]):
        return "vulnerable_function"
    if any((f["path"], "<global>") in known_functions for f in files):
        return "vulnerable_function"
    if sum(f["added"] + f["removed"] for f in source) > 1000:
        return "size_cap"
    return None
 def generated(git, revision: str, path: str, text: str) -> bool:
    import fnmatch
    if generated_path(path):
        return True
    header = "\n".join(text.splitlines()[:20])
    if re.search(r"(?im)^\s*(?:#|//|/\*|\*|<!--).*?(?:@generated|auto.?generated|generated\s+(?:by|file|code)|do not edit)", header):
        return True
    result = False
    parts = Path(path).parts
    for index in range(len(parts)):
        directory = "/".join(parts[:index])
        attributes = git.blob(revision, (directory + "/" if directory else "") + ".gitattributes") or ""
        relative = "/".join(parts[index:])
        for line in attributes.splitlines():
            tokens = line.split()
            if not tokens or tokens[0].startswith("#"):
                continue
            pattern = tokens[0].lstrip("/")
            target = relative if "/" in pattern else Path(relative).name
            if fnmatch.fnmatchcase(target, pattern):
                for token in tokens[1:]:
                    if token in {"linguist-generated", "linguist-generated=true"}:
                        result = True
                    elif token in {"-linguist-generated", "!linguist-generated", "linguist-generated=false"}:
                        result = False
    return result
 def ordinary_history(git, head: str) -> list[dict]:
    raw = git.run("log", "--first-parent", "--format=%H%x00%P%x00%ct%x00%an%x00%B%x1e", head)
    rows = []
    for entry in raw.split("\x1e"):
        if not entry.strip():
            continue
        fields = entry.strip().split("\x00")
        if len(fields) != 5 or not SHA.fullmatch(fields[0]):
            raise InstrumentFailure("invalid_history")
        sha, parents, timestamp, author, message = fields
        row = {"head": sha, "parents": parents.split(), "timestamp": int(timestamp), "author": author, "message": message, "files": []}
        rows.append(row)
        if len(row["parents"]) != 1:
            continue
        base = row["parents"][0]
        for path, added, removed in git.stats(base, sha):
            hunks = git.hunks(base, sha, path)
            info = {
                "path": path,
                "added": added,
                "removed": removed,
                "head_lines": [[max(1, n), max(1, n + max(c, 1) - 1)] for _, _, n, c in hunks],
                "functions": [],
                "generated": False,
            }
            if Path(path).suffix in LANGUAGES:
                # Inspect both sides: deleting a vulnerable function is still touching it.
                for revision, side in ((base, 0), (sha, 2)):
                    text = git.blob(revision, path)
                    if text is None:
                        continue
                    spans = functions(path, text)
                    for hunk in hunks:
                        start, count = hunk[side : side + 2]
                        for name, lo, hi in spans:
                            if max(1, start) <= hi and start + max(count, 1) - 1 >= lo:
                                info["functions"].append(name)
                    info["generated"] |= generated(git, revision, path, text)
            row["files"].append(info)
    return rows
 def draw_ordinary(rows: list[dict], fixes: set[str], known_functions: set[tuple[str, str]], *, seed: int) -> tuple[list[dict], dict]:
    import random
    from collections import Counter, defaultdict
    counts = Counter()
    eligible = []
    for row in rows:
        reason = ordinary_rejection(row, fixes, known_functions)
        counts[reason or "eligible"] += 1
        if reason is None:
            eligible.append(row)
    if len(eligible) < 40:
        failure = Rejected("ordinary_floor")
        failure.counts = dict(counts)
        raise failure
    earliest, latest = min(r["timestamp"] for r in rows), max(r["timestamp"] for r in rows)
    cells = defaultdict(list)
    for row in eligible:
        third = min(2, 3 * (row["timestamp"] - earliest) // max(1, latest - earliest + 1))
        size = sum(f["added"] + f["removed"] for f in row["files"] if Path(f["path"]).suffix in LANGUAGES and not manifest(f["path"]))
        bucket = 0 if size <= 10 else 1 if size <= 50 else 2 if size <= 200 else 3
        cells[third, bucket].append(row)
    if {t for t, _ in cells} != {0, 1, 2}:
        failure = Rejected("time_thirds")
        failure.counts = dict(counts)
        raise failure
    # Largest-deficit rounding with the mandatory minimum of one per time third.
    # No cell can receive more draws than it has eligible commits.
    allocation = Counter()
    targets = {cell: 12 * len(items) / len(eligible) for cell, items in cells.items()}
    for third in range(3):
        cell = max(sorted(c for c in cells if c[0] == third), key=lambda c: targets[c])
        allocation[cell] = 1
    while sum(allocation.values()) < 12:
        cell = max(sorted(c for c in cells if allocation[c] < len(cells[c])), key=lambda c: targets[c] - allocation[c])
        allocation[cell] += 1
    rng = random.Random(seed)
    drawn = []
    for cell in sorted(cells):
        for row in rng.sample(sorted(cells[cell], key=lambda r: r["head"]), allocation[cell]):
            drawn.append(
                {
                    "kind": "ordinary",
                    "base": row["parents"][0],
                    "head": row["head"],
                    "method": "first_parent",
                    "time_third": cell[0],
                    "size_bucket": cell[1],
                    "files": [{"path": f["path"], "head_lines": f["head_lines"]} for f in row["files"]],
                }
            )
    return drawn, dict(counts)
@@ -0,0 +1,9 @@
 {
  "ghsa_id": "GHSA-test-test-test",
  "published_at": "2026-06-02T00:00:00Z",
  "type": "reviewed",
  "withdrawn_at": null,
  "cwes": [{"cwe_id": "CWE-89"}],
  "vulnerabilities": [{"package": {"ecosystem": "pip", "name": "fixture"}}],
  "references": ["https://github.com/fixture/project/commit/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
 }
@@ -0,0 +1,860 @@
 [
  {
    "id": "0",
    "repo": "0",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": [
            {
              "cwe": "CWE-89",
              "path": "app.py",
              "line": 10
            }
          ]
        }
      ]
    }
  },
  {
    "id": "1",
    "repo": "0",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "2",
    "repo": "1",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "3",
    "repo": "1",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "4",
    "repo": "2",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "5",
    "repo": "2",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "6",
    "repo": "3",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "7",
    "repo": "3",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "8",
    "repo": "4",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "9",
    "repo": "4",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "10",
    "repo": "5",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "11",
    "repo": "5",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "12",
    "repo": "6",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "13",
    "repo": "6",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "14",
    "repo": "7",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "15",
    "repo": "7",
    "kind": "ordinary",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "16",
    "repo": "8",
    "kind": "vulnerability",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": [
            {
              "cwe": "CWE-89",
              "path": "app.py",
              "line": 10
            }
          ]
        }
      ]
    }
  },
  {
    "id": "17",
    "repo": "8",
    "kind": "vulnerability",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": [
            {
              "cwe": "CWE-89",
              "path": "app.py",
              "line": 10
            }
          ]
        }
      ]
    }
  },
  {
    "id": "18",
    "repo": "9",
    "kind": "vulnerability",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  },
  {
    "id": "19",
    "repo": "9",
    "kind": "vulnerability",
    "family": "injection",
    "method": "introducing",
    "post_cutoff": true,
    "label_check": "confirmed",
    "path": "app.py",
    "function": "handler",
    "files": [
      {
        "path": "app.py",
        "head_lines": [
          [
            10,
            12
          ]
        ]
      }
    ],
    "instrument": {
      "head_verified": true,
      "base_verified": true,
      "changed_bytes": {
        "app.py": 20
      },
      "hook_bytes_read": 20,
      "hook_exit": 0
    },
    "push": {
      "quick_tier": [
        {
          "files": [
            "app.py"
          ],
          "bytes_read": 20,
          "findings": []
        }
      ]
    }
  }
 ]
@@ -0,0 +1,150 @@
 """Freeze the staged, bisected p1 without running a guard, git, network or model.
 Coordinator: python -m benchmarks.unseen.freeze --used-report USED-SET-REPORT.json
 The report is eligibility.UsedSet.report() output. Label-check counts are derived
 from retained vulnerability changes' label_check fields (missing means unchecked).
 A matching retry is a no-op; any changed frozen artifact requires a new pool id.
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import os
 import re
 import tomllib
 from pathlib import Path
 from .bisect_guard import read_pair
 from .draft import manifest
 from .eligibility import SOURCES
 from .journal import digest, sync_directory
 def count(value) -> int:
    if type(value) is not int or value < 0:
        raise ValueError("invalid_count")
    return value
 def sha256(value) -> str:
    if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{64}", value):
        raise ValueError("invalid_digest")
    return value
 def metadata(used_report: dict) -> dict:
    """Only known source labels and numeric counts can enter the public record."""
    try:
        used_digest = sha256(used_report["sha256"])
        sources = used_report["sources"]
        if not sources or set(sources) - {*SOURCES, "memory_local", "memory_s3"}:
            raise ValueError
        return {"used_set_digest": used_digest, "source_counts": {k: count(v["count"]) for k, v in sources.items()}}
    except (ValueError, KeyError, TypeError, AttributeError):
        raise ValueError("invalid_used_report") from None
 def verify_receipt(receipt: dict, public: dict, private: dict) -> None:
    try:
        if type(receipt["guard_result"]) is not int or receipt["guard_result"] != 0:
            raise ValueError
        if sha256(receipt["draft_digest"]) != digest(public) or sha256(receipt["private_draft_digest"]) != digest(private):
            raise ValueError
        if count(receipt["input_count"]) != len(public.get("repository", [])) + count(receipt["dropped_count"]):
            raise ValueError
    except (ValueError, KeyError, TypeError):
        raise ValueError("invalid_guard_receipt") from None
 def frozen_text(data: dict) -> bytes:
    # Reuse the draft serializer, changing only the status. Hash its parsed value,
    # not the TOML bytes: table/key order and whitespace are not pool identity.
    text = manifest(data.get("repository", []), data["seed"])
    return text.replace('status = "draft"', 'status = "frozen"', 1).encode("utf-8")
 def matches(path: Path, payload: bytes) -> bool:
    try:
        if path.suffix == ".toml":
            return digest(tomllib.loads(path.read_text(encoding="utf-8"))) == digest(tomllib.loads(payload.decode("utf-8")))
        return digest(json.loads(path.read_bytes())) == digest(json.loads(payload))
    except (OSError, ValueError):
        return False
 def run(root: Path, *, used_report: dict) -> dict:
    directory = root / "benchmarks/unseen"
    record = metadata(used_report)
    public, private = read_pair(directory / "draft-p1.toml", directory / "private/draft-p1.toml")
    try:
        receipt = json.loads((directory / "bisect-p1.json").read_bytes())
    except (OSError, ValueError):
        raise ValueError("invalid_guard_receipt") from None
    verify_receipt(receipt, public, private)
    if not public.get("repository"):
        raise ValueError("empty_pool")
    labels = dict.fromkeys(("confirmed", "refactor", "unclear", "unchecked"), 0)
    hidden = {r["id"]: r for r in private.get("repository", [])}
    try:
        for pointer in public["repository"]:
            row = hidden[pointer["id"]] if pointer.get("private") else pointer
            for change in row["changes"]:
                if change["kind"] == "vulnerability":
                    labels[change.get("label_check", "unchecked")] += 1
    except (KeyError, TypeError):
        raise ValueError("invalid_label_check") from None
    try:
        protocol = (directory / "protocol-p1.md").read_bytes()
        if not protocol:
            raise ValueError
    except (OSError, ValueError):
        raise ValueError("invalid_protocol") from None
    public_bytes, private_bytes = frozen_text(public), frozen_text(private)
    record.update(
        guard_result=0,
        dropped_count=receipt["dropped_count"],
        label_check_counts=labels,
        freeze_digest=digest(tomllib.loads(public_bytes.decode("utf-8"))),
        protocol_digest=hashlib.sha256(protocol).hexdigest(),
    )
    outputs = (
        (directory / "private/pool-p1.toml", private_bytes),
        (directory / "pool-p1.toml", public_bytes),
        (directory / "freeze-p1.json", (json.dumps(record, sort_keys=True, indent=2) + "\n").encode()),
    )
    # Check EVERY existing artifact before writing anything. The record is the
    # completion marker and is written last; matching interrupted writes can resume.
    if any(path.exists() and not matches(path, payload) for path, payload in outputs):
        raise FileExistsError("frozen_pool_differs_use_new_pool")
    for path, payload in outputs:
        try:
            with path.open("xb") as handle:
                os.fchmod(handle.fileno(), 0o600)
                handle.write(payload)
                handle.flush()
                os.fsync(handle.fileno())
            sync_directory(path.parent)
        except FileExistsError:
            if not matches(path, payload):
                raise FileExistsError("frozen_pool_differs_use_new_pool") from None
    return record
 def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--root", type=Path, default=Path.cwd())
    parser.add_argument("--used-report", type=Path, required=True)
    args = parser.parse_args(argv)
    try:
        report = run(args.root, used_report=json.loads(args.used_report.read_bytes()))
    except Exception:
        print(json.dumps({"status": "freeze_refused"}))
        return 1
    print(json.dumps(report, sort_keys=True))
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,184 @@
 """Private, append-only sourcing checkpoints. No identity-bearing data leaves this directory."""
 from __future__ import annotations
 import fcntl
 import hashlib
 import json
 import math
 import os
 import time
 from contextlib import contextmanager
 from pathlib import Path
 STAGES = ("advisories", "resolution", "eligibility", "extraction", "completion")
 def encoded(value) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
 def digest(value) -> str:
    return hashlib.sha256(encoded(value)).hexdigest()
 class ResumeMismatch(ValueError):
    def __init__(self, parameters):
        self.parameters = parameters
        super().__init__("resume_inputs_changed")
 class Stopped(Exception):
    pass
 def external(root: Path, path: Path) -> Path:
    path = path.expanduser().resolve()
    # Also reject the actual checkout when a different --root is supplied.
    if any(path.is_relative_to(p.resolve()) for p in (root, Path(__file__).resolve().parents[2])):
        raise ValueError("cache_inside_repository")
    return path
 def atomic(path: Path, payload: bytes) -> None:
    temporary = path.with_suffix(path.suffix + ".tmp")
    with temporary.open("wb") as handle:
        os.chmod(temporary, 0o600)
        handle.write(payload)
        handle.flush()
        os.fsync(handle.fileno())
    temporary.replace(path)
    sync_directory(path.parent)
 def sync_directory(path: Path) -> None:
    fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
    try:
        os.fsync(fd)
    finally:
        os.close(fd)
 class Journal:
    def __init__(self, path: Path, *, max_hours=None, clock=None, rate_limit=None):
        if max_hours is not None and (not math.isfinite(max_hours) or max_hours < 0):
            raise ValueError("invalid_max_hours")
        self.path = path
        self.clock = clock or time.monotonic
        self.started = self.clock()
        self.max_seconds = None if max_hours is None else max_hours * 3600
        self.rate_limit = rate_limit or (lambda: {})
        self.rows = {stage: {} for stage in STAGES}
        self.elapsed_before = 0.0
        self.last = None
        self.previous_rate = {}
    @contextmanager
    def open(self, parameters):
        self.path.mkdir(parents=True, exist_ok=True, mode=0o700)
        with (self.path / "LOCK").open("a") as lock:
            try:
                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
            except BlockingIOError:
                raise ValueError("journal_busy") from None
            metadata = self.path / "inputs.json"
            if metadata.exists():
                old = json.loads(metadata.read_bytes())
                # Only current, fixed parameter labels can enter stdout.
                changed = [key for key in parameters if old.get(key) != parameters[key]]
                if old.keys() != parameters.keys():
                    changed.append("parameter_schema")
                if changed:
                    raise ResumeMismatch(changed)
            else:
                if any(self.path.glob("*.jsonl")):
                    raise ValueError("journal_missing_inputs")
                atomic(metadata, encoded(parameters))
            for stage in STAGES:
                path = self.path / (stage + ".jsonl")
                if not path.exists():
                    continue
                with path.open("rb") as handle:
                    for line in handle:
                        # Fail closed on torn/corrupt writes; never silently lose a completed unit.
                        if not line.endswith(b"\n"):
                            raise ValueError("journal_incomplete_record")
                        row = json.loads(line)
                        if row["id"] in self.rows[stage]:
                            raise ValueError("journal_duplicate_unit")
                        self.rows[stage][row["id"]] = row["value"]
                        if row["elapsed_seconds"] >= self.elapsed_before:
                            self.elapsed_before = row["elapsed_seconds"]
                            self.last = {"stage": stage, "id": row["id"]}
                            self.previous_rate = row["rate_limit"]
            self.progress("sourcing")
            yield self
    def boundary(self):
        reason = None
        if (self.path / "STOP").exists():
            reason = "STOP"
        elif self.max_seconds is not None and self.clock() - self.started >= self.max_seconds:
            reason = "max_hours"
        if reason:
            self.progress("stopped", reason=reason)
            raise Stopped(reason)
    def elapsed(self):
        return self.elapsed_before + self.clock() - self.started
    def progress(self, status, **extra):
        atomic(
            self.path / "progress.json",
            encoded(
                {
                    "status": status,
                    "counts": {stage: len(rows) for stage, rows in self.rows.items()},
                    "last_unit": self.last,
                    "rate_limit": self.rate_limit() or self.previous_rate,
                    "elapsed_seconds": self.elapsed(),
                    **extra,
                }
            ),
        )
    def put(self, stage, key, value):
        if key in self.rows[stage]:
            raise ValueError("journal_duplicate_unit")
        row = {"id": key, "value": value, "elapsed_seconds": self.elapsed(), "rate_limit": self.rate_limit() or self.previous_rate}
        path = self.path / (stage + ".jsonl")
        with path.open("ab") as handle:
            os.chmod(path, 0o600)
            handle.write(encoded(row) + b"\n")
            handle.flush()
            os.fsync(handle.fileno())
        sync_directory(self.path)
        self.rows[stage][key] = value
        self.last = {"stage": stage, "id": key}
        self.progress("sourcing")
 class ResolvedGitHub:
    """Persist successful repository lookups and 404s used by both eligibility and the fix index."""
    def __init__(self, github, journal):
        self.github, self.journal = github, journal
    def __getattr__(self, name):
        return getattr(self.github, name)
    def get_repo(self, name):
        from .eligibility import RepositoryNotFound, normalize
        key = normalize(name)
        if key not in self.journal.rows["resolution"]:
            self.journal.boundary()
            try:
                value = self.github.get_repo(key)
            except RepositoryNotFound:
                value = None
            self.journal.put("resolution", key, value)
        value = self.journal.rows["resolution"][key]
        if value is None:
            raise RepositoryNotFound("not_found")
        return value
@@ -0,0 +1,88 @@
 """Append-only slice usage; a hash chain detects rewritten rows, not a rebuilt entire history.
 Keep the published final digest to authenticate a history against truncation or wholesale replacement.
 Only opaque decision/experiment labels belong here; repository identities are never accepted.
 """
 from __future__ import annotations
 import fcntl
 import hashlib
 import json
 import re
 from datetime import date
 from pathlib import Path
 FIELDS = {"slice", "decision", "purpose", "date", "result_digest", "freeze_digest"}
 PURPOSES = {"baseline", "exploratory", "informed", "qualifies"}
 ZERO = "0" * 64
 def digest(row: dict) -> str:
    return hashlib.sha256(json.dumps(row, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
 def validate(row: dict) -> None:
    if set(row) != FIELDS or row["purpose"] not in PURPOSES:
        raise ValueError("invalid_usage_fields")
    if type(row["slice"]) is not int or row["slice"] < 1:
        raise ValueError("invalid_slice")
    if not isinstance(row["decision"], str) or not re.fullmatch(r"[A-Za-z0-9_-]+", row["decision"]):
        raise ValueError("invalid_decision_label")
    for key in ("result_digest", "freeze_digest"):
        if not isinstance(row[key], str) or not re.fullmatch(r"[0-9a-f]{64}", row[key]):
            raise ValueError("invalid_digest")
    try:
        if date.fromisoformat(row["date"]).isoformat() != row["date"]:
            raise ValueError
    except (ValueError, TypeError):
        raise ValueError("invalid_date") from None
 def _read(text: str) -> list[dict]:
    previous = ZERO
    rows = []
    if text and not text.endswith("\n"):
        raise ValueError("broken_digest_chain")
    for line in text.splitlines():
        try:
            row = json.loads(line)
            stored = row.pop("digest")
            if row["previous"] != previous or digest(row) != stored:
                raise ValueError
            validate({k: v for k, v in row.items() if k != "previous"})
        except (ValueError, KeyError, TypeError, AttributeError):
            raise ValueError("broken_digest_chain") from None
        rows.append({**row, "digest": stored})
        previous = stored
    return rows
 def read(path: Path) -> list[dict]:
    if not path.exists():
        return []
    with path.open() as handle:
        fcntl.flock(handle, fcntl.LOCK_SH)
        return _read(handle.read())
 def append(path: Path, row: dict) -> str:
    validate(row)
    path.parent.mkdir(parents=True, exist_ok=True)
    with path.open("a+") as handle:
        fcntl.flock(handle, fcntl.LOCK_EX)
        handle.seek(0)
        rows = _read(handle.read())
        if any(all(old[key] == row[key] for key in FIELDS) for old in rows):
            raise ValueError("duplicate_usage")
        if rows and rows[0]["freeze_digest"] != row["freeze_digest"]:
            raise ValueError("freeze_digest_changed")
        if row["purpose"] == "qualifies" and any(
            old["slice"] == row["slice"] and old["decision"] == row["decision"] and old["purpose"] == "informed" for old in rows
        ):
            raise ValueError("slice_informed_decision")
        entry = {**row, "previous": rows[-1]["digest"] if rows else ZERO}
        sha = digest(entry)
        handle.write(json.dumps({**entry, "digest": sha}, sort_keys=True) + "\n")
        handle.flush()
        return sha
@@ -0,0 +1,128 @@
 """Build anonymous coordinator proof records from completed dispatcher outputs."""
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import subprocess
 from pathlib import Path
 def digest(value):
    return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
 def records(root):
    return [json.loads(path.read_text()) for path in sorted(root.glob("*.json")) if path.name not in {"progress.json", "inputs.json"}]
 def replay_proof(roots):
    lanes = {lane: records(root) for lane, root in roots.items()}
    if any(len(rows) != 5 for rows in lanes.values()):
        raise ValueError("proof requires exactly five completed changes per lane")
    keys = [{row["input_digest"] for row in rows} for rows in lanes.values()]
    if not all(key == keys[0] for key in keys):
        raise ValueError("lane input identities differ")
    quick = {}
    evidence = {}
    for lane, rows in lanes.items():
        quick[lane] = {}
        evidence[lane] = []
        for row in rows:
            inst = row.get("instrument", {})
            if (
                row.get("status") not in {"quick_only", "engine_covered"}
                or not inst.get("hook_bytes_read")
                or inst.get("suspect_fast")
                or inst.get("jvm_wall_seconds", 0) < 5
            ):
                raise ValueError("proof instrument has unread input or implausible JVM time")
            quick[lane][row["input_digest"]] = digest([t.get("findings", []) for t in row["push"].get("quick_tier", [])])
            evidence[lane].append(
                {
                    "input_digest": row["input_digest"],
                    "seconds": inst["seconds"],
                    "jvm_seconds": inst["jvm_wall_seconds"],
                    "bytes": inst["hook_bytes_read"],
                    "exit_code": inst["hook_exit"],
                }
            )
    equal = all(value == next(iter(quick.values())) for value in quick.values())
    if not equal:
        raise ValueError("quick-tier findings differ across lanes")
    return {"lanes": evidence, "quick_tier_equal": True, "quick_digests": quick, "cleanup": "completed-before-checkpoint"}
 def engine_proof(root, baseline):
    current = records(root)
    old = {digest([r["repo"], r["pin"]]): r for r in records(baseline) if "repo" in r and "pin" in r}
    current = [r for r in current if "repo" in r and "pin" in r and not all(u.get("status") == "unsupported" for u in r["units"])]
    if len(current) != 2:
        raise ValueError("engine proof requires exactly two pins")
    evidence = []
    def stable(record):
        return [
            {key: u.get(key) for key in ("unit", "status", "questions_asked", "questions_completed", "witness_rows", "traces")}
            for u in record["units"]
        ]
    for row in current:
        key = digest([row["repo"], row["pin"]])
        previous = old[key]
        instruments = [u.get("instrument", {}) for u in row["units"]]
        if (
            not row.get("done")
            or not any(i.get("bytes", 0) > 0 for i in instruments)
            or not any(stage.get("seconds", 0) >= 5 for i in instruments for stage in i.get("jvm", []))
        ):
            raise ValueError("engine proof lacks bytes or realistic JVM time")
        evidence.append(
            {
                "pin_digest": key,
                "seconds": row.get("seconds"),
                "record_digest": digest(stable(row)),
                "baseline_digest": digest(stable(previous)),
                "equal": stable(row) == stable(previous),
                "instrument": [
                    {
                        "bytes": u.get("instrument", {}).get("bytes", 0),
                        "cpg_bytes": u.get("instrument", {}).get("cpg_bytes", 0),
                        "jvm": [
                            {key: stage.get(key) for key in ("seconds", "exit_code", "success", "heap_mb")}
                            for stage in u.get("instrument", {}).get("jvm", [])
                        ],
                    }
                    for u in row["units"]
                ],
            }
        )
    return {"pins": evidence, "differences": sum(not e["equal"] for e in evidence), "cleanup": "completed-before-checkpoint"}
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("kind", choices=("engine", "replay"))
    parser.add_argument("--image", required=True)
    parser.add_argument("--out", type=Path, required=True)
    parser.add_argument("--records", type=Path)
    parser.add_argument("--baseline", type=Path)
    parser.add_argument("--kind-records", type=Path)
    parser.add_argument("--ax-records", type=Path)
    parser.add_argument("--vm-records", type=Path)
    args = parser.parse_args()
    result = (
        engine_proof(args.records, args.baseline)
        if args.kind == "engine"
        else replay_proof({"kind": args.kind_records, "ax": args.ax_records, "vm": args.vm_records})
    )
    result.update(
        image=args.image, commit=subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True, check=True).stdout.strip()
    )
    args.out.parent.mkdir(parents=True, exist_ok=True)
    args.out.write_text(json.dumps(result, sort_keys=True, indent=2) + "\n")
 if __name__ == "__main__":
    main()
@@ -0,0 +1,180 @@
 # Pool p1: frozen scoring protocol
 This protocol fixes the scoring, uncertainty estimates and adoption gate before any
 p1 replay. Its authority is the approved
 [unseen-repo-evaluation design](../../.kiro/specs/unseen-repo-evaluation/design.md),
 sections 3, 4 and 7 (including decisions 4.0, 4.0a and 7.3). The freeze record binds
 these exact UTF-8 file bytes by `protocol_digest`. Corrections require a new pool;
 neither p1 nor this protocol is revised in response to results.
 ## Population, slices and use
 Design section 3 fixes three seeded, ecosystem- and `post_cutoff`-stratified slices
 of 100 repositories: one vulnerability change and 12 ordinary changes per
 repository, 100 + 1,200 = 1,300 changes per slice, 300 repositories and 3,900 changes
 overall. Guard-rejected candidates are dropped before freezing; actual retained
 counts are reported, with no replacement or silent claim that reduced slices meet
 the planned precision. Frozen slices are never resized.
 Slice 1 supplies the baseline and G1 arms table. Slices 2 and 3 qualify the first
 two adoption decisions. Once spent, p2 is drawn by the same code and excludes p1.
 Every use is appended to `usage-p1.jsonl` with slice, decision or experiment id,
 purpose (`baseline`, `exploratory`, `informed`, `qualifies`), date, result digest and
 freeze digest. A slice that informed a change cannot qualify that change (3.1).
 The label check reads every third `introducing` change before freezing, marking
 `confirmed`, `refactor` or `unclear`; report the confirmed share and catch on the
 confirmed subset. Report catch separately for `introducing` (the headline) and
 `last_touch` (a lower bound). The former inherits SZZ last-writer/refactor noise;
 the latter may already contain the flaw in base, making novelty-based silence
 correct even though scoring counts a miss (design 2.1).
 ## Replay arms
 The default hook replay uses `--deadline 30 --engine inline --max-regions 500
 --mode advisory` (section 4). Retain the artifact and full text output, including
 every `Skipped:` line.
 Decision 4.0 registers a second slice-1 arm with `--deadline 300` and every other
 flag unchanged. Commit its experiment manifest with
 `unseen: {pool: p1, slice: 1}` before its first replay. Report both arms to
 distinguish deadline misses from engine misses. This arm is a measurement;
 adopting a longer default deadline is a separate decision under section 7.2.
 Decision 4.0a calibrates cluster overhead against native Docker runc. Use a
 deterministic paired sample of 20 changes by default, or all of a smaller proof
 manifest, at a 600-second calibration deadline. Record per-change stage times and
 median cluster/native slowdown with bootstrap 95% intervals separately for time
 through quick, engine build and engine queries. Incomplete timings or degraded
 scans invalidate calibration. Cluster arm deadlines are the 30/300-second
 deadlines multiplied by the median paired slowdown through quick, rounded to
 integer seconds; native deadlines stay at 30/300 seconds. Report applied
 deadlines and factors.
 A deterministic native sample accompanies the cluster slice. Compare whether
 each push flags anything and report a Wilson 95% agreement interval. If its lower
 bound is below 95%, or any sample pair is missing or failed, flag the run and
 exclude cluster results from the baseline. Identify disagreements by opaque
 change IDs only. Calibration records contain counts, times and opaque digests.
 Docker checks its data-root free space against the unpacked image size upper
 bound plus 1 GiB before explicitly pulling; retain sanitized stderr tails and
 exit codes on failure (4.0a).
 ## Catch and false alarm
 A vulnerability change is caught only if a finding matches its labelled family
 and head location (4.1). Engine findings carry the family; quick-rule CWEs map
 through the project's family CWE table. Match locations in the corresponding
 file using the following rules:
 | Family | Required head location |
 | --- | --- |
 | `injection`, `path`, `deserialization`, `output_encoding`, `untrusted_destination` | Sink line in the vulnerable function, or within 10 lines of the head-side changed hunks |
 | `access_control` | The vulnerable function itself (the handler lacking the check), or within 10 lines of the head-side changed hunks |
 | `config_secrets` | The changed file and head-side changed lines ±10, at file scope (`<global>`) |
 All three user-visible streams count: admitted defects, advisory engine findings
 and quick-rule matches. Record the stream responsible for each catch. A matching
 family at the wrong location does not count.
 An ordinary change is a false alarm if **any** of those three streams contains at
 least one finding, of any family, anywhere (4.2). Report the admitted-defects-only
 alerts rate beside it. An ordinary change may contain an unknown vulnerability;
 adjudication does not change this definition. Adjudicate all flagged ordinary
 changes if there are 30 or fewer, otherwise every third, against the standard
 of protocol v2, and report the adjudicated share separately (design 2.2).
 ## Coverage and degradation
 Assign exactly one state to every change (4.3):
 | State | Definition |
 | --- | --- |
 | `instrument_failure` | No record, failed fetch, head commit not verified, or zero bytes of changed files read; also the `suspect_fast` failure path |
 | `unanalysable` | No changed file uses a language the hook covers (`language_not_covered`) |
 | `quick_only` | Quick read the changed files but no engine question completed on them |
 | `engine_covered` | At least one engine question completed on a changed file |
 Prove input access: record checkout files and bytes, bytes of each changed file,
 JVM wall time and hook exit code. A replay faster than JVM startup is
 `suspect_fast`, never a clean zero. Failed fetches, missing commits and hook
 crashes yield failure records, never empty successes. Re-run an instrument
 failure once, then report it; it never counts as quiet or missed. Refuse to score
 a slice with more than 5% instrument failures after re-runs (design Error
 Handling). Preserve skipped/degraded coverage rather than interpreting silence
 as analysis. Report catch and false alarm overall and by coverage state, with
 failure counts explicit and failures excluded from outcome denominators.
 ## Intervals and planned precision
 Use Wilson 95% intervals with z = 1.96 (section 3). For observed proportion p and
 denominator n, the centre is `(p + z²/(2n)) / (1 + z²/n)` and the half width is
 `z * sqrt(p*(1-p)/n + z²/(4n²)) / (1 + z²/n)`. The precision bar uses the larger
 distance from p to either bound, not just the interval's half width.
 The design's exact minimum sample sizes are:
 | Rate | Assumed p | Maximum distance | Required n |
 | --- | --- | --- | --- |
 | False alarm | 0.05 | 3 percentage points | 315 |
 | False alarm | 0.10 | 3 percentage points | 483 |
 | False alarm | 0.20 | 3 percentage points | 756 |
 | Catch | 0.10 | 10 percentage points | 62 |
 | Catch | 0.25 | 10 percentage points | 88 |
 | Catch | 0.40 | 10 percentage points | 97 |
 At n = 100 and catch p = 0.4 the Wilson interval is [0.309, 0.498], within
 10 points. One vulnerability change per repository keeps those observations
 independent. The 12 ordinary changes within a repository are correlated. With
 m = 12 and assumed ICC = 0.05 the design effect `1 + (m - 1)*ICC` is 1.55;
 1,200 ordinary changes give effective n ≈774 ≥756. At p = 0.2 their plain Wilson
 interval is about ±2.3 points.
 Report a repository-cluster bootstrap 95% interval beside the ordinary-change
 Wilson interval: resample whole repositories, retaining their within-repository
 changes. Measure and record ICC on slice 1. If ICC exceeds 0.05, increase the next
 pool's size, never the frozen slice's. Per-family intervals are reported but not
 sized; splitting 100 changes over seven families gives roughly ±20–25 points.
 The design leaves per-family BLOCK sizing to a later decision.
 Report counts, denominators, rates and intervals overall and per family, method,
 post-cutoff group, stream, coverage state and confirmed subset (sections 3 and 7).
 Use actual observed counts, not planned sample sizes, for intervals.
 ## Fixed budgets and adoption gate
 For score-bearing arms, report catch at false-alarm budgets of 1%, 5% and 10%
 (7.1). Choose the lowest score threshold whose ordinary-change false-alarm rate
 stays within the budget; report catch with its Wilson interval and realised
 false-alarm rate. A threshold selected on the same slice is `exploratory`. For
 qualification, fix it beforehand on an earlier slice or held-out folds and
 apply it unchanged. A binary arm has one operating point; report which budgets
 it meets. Do not substitute AUC for these operating points.
 Registered experiments identify `unseen: {pool, slice}`. Write the unseen
 estimates beside held-out fold estimates, including each arm's catch at each
 budget and paired difference B − A with an exact McNemar test on the paired
 vulnerability changes (planned n = 100; 7.2). Record use in the ledger.
 Adopt candidate B over production A only when both the existing fold rule and
 the untouched-slice gate pass (7.3):
 1. At the 5% budget with B's threshold fixed beforehand, B's catch is not
   significantly lower than A's: exact two-sided McNemar on paired vulnerability
   changes, alpha 0.05.
 2. For a binary arm, B's false-alarm rate is not significantly higher than A's:
   exact two-sided McNemar on paired ordinary changes, alpha 0.05. Report the
   repository-cluster bootstrap interval for the false-alarm difference beside
   the test because those changes are clustered.
 Write `unseen.gate: pass | regression | not_run`. No slice, a slice already
 `informed` for this change, or more than 5% instrument failures yields `not_run`;
 it blocks adoption just as `regression` does. Decision 4.0a also excludes flagged
 cluster/native agreement runs from baseline use. Failure to detect a significant
 regression is the specified gate, not evidence that the arms are equivalent.
 Raw per-change artifacts remain outside the repository. Committed measurement
 records contain counts, rates, intervals and digests, never repository names or
 URLs. Public p1 names stay only in the permissive pool manifest; private entries
 remain in the gitignored private manifest and are bound through opaque pointers
 (design 1.4 and 6).
@@ -0,0 +1,247 @@
 """Dispatch frozen unseen changes or a five-change project-history proof."""
 from __future__ import annotations
 import argparse
 import hashlib
 import io
 import json
 import math
 import subprocess
 import tarfile
 import tomllib
 from pathlib import Path
 from benchmarks.ax.batch import AXLane, DockerLane, Item, Workload, dispatch, write_json
 from benchmarks.unseen.score import coverage
 def make_item(change, arm, image, *, deadline_scale=1.0, lane="ax", deadline=None):
    if arm not in {"default", "long_deadline"}:
        raise ValueError("unknown replay arm")
    identity = hashlib.sha256(str(change["id"]).encode()).hexdigest()[:14]
    if not math.isfinite(deadline_scale) or deadline_scale <= 0:
        raise ValueError("deadline scale must be finite and positive")
    base = deadline if deadline is not None else 30 if arm == "default" else 300
    applied = round(base * (1 if lane == "docker" else deadline_scale))
    if applied < 1:
        raise ValueError("scaled deadline must be at least one second")
    spec = {
        **change,
        "id": identity,
        "hook_flags": ["--deadline", str(applied)],
        "image": image,
        "base_deadline_seconds": base,
        "deadline_seconds": applied,
        "deadline_scale": deadline_scale,
        "applied_deadline_scale": 1.0 if lane == "docker" else deadline_scale,
    }
    data = json.dumps(spec, sort_keys=True).encode()
    digest = hashlib.sha256(data).hexdigest()
    return Item(
        "replay-" + identity,
        {"SPEC_URL": data},
        "result.dat",
        ("python3", "/app/benchmarks/unseen/replay_entry.py"),
        {},
        digest,
        {"SPEC_URL": "spec.dat"},
    )
 def validate_result(data, output):
    with tarfile.open(fileobj=io.BytesIO(data)) as archive:
        members = archive.getmembers()
        required = {"push.json", "push.txt", "engine.json", "instrument.json"}
        if {m.name for m in members} != required or any(not m.isfile() for m in members):
            raise ValueError("replay result requires push, engine and instrument.json")
        payload = {m.name: archive.extractfile(m).read() for m in members}
    instrument = json.loads(payload["instrument.json"])
    push = json.loads(payload["push.json"])
    record = {"instrument": instrument, "push": push}
    record["status"] = coverage(record)
    # Transport/scheduler needs an explicit OOM signal, not a quiet failed replay.
    if "OutOfMemoryError" in json.dumps(push) or "JVM out of memory" in json.dumps(push):
        record["status"] = "oom"
    output.mkdir(parents=True, exist_ok=True)
    for name, body in payload.items():
        (output / name).write_bytes(body)
    (output / "result.dat").write_bytes(data)
    write_json(output / "result.json", record)
    return record
 def proof_changes(root):
    """Only the operator's project history; no pool data or fetches."""
    def git(*args):
        return subprocess.run(["git", "-C", str(root), *args], capture_output=True, text=True, check=True).stdout.strip()
    changes = []
    for head in git("rev-list", "--no-merges", "--max-count=100", "HEAD", "--", "src").splitlines():
        base = git("rev-parse", head + "^")
        changed = git("diff", "--name-only", base, head).splitlines()
        if not any(name.startswith("src/") and name.endswith(".py") for name in changed):
            continue
        changes.append(
            {
                "id": hashlib.sha256(head.encode()).hexdigest(),
                "repository_url": "https://github.com/norandom/OpenUltraSAST.git",
                "repo": "project-proof",
                "kind": "ordinary",
                "base": base,
                "head": head,
            }
        )
        if len(changes) == 5:
            break
    if len(changes) != 5:
        raise ValueError("history lacks five source changes")
    return changes
 def canonical(value):
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()
 def load_slice(path, slice_id, private_path=None):
    if path.suffix != ".toml":
        frozen = json.loads(path.read_text())
        changes = frozen["changes"]
        if frozen["sha256"] != hashlib.sha256(json.dumps(changes, sort_keys=True).encode()).hexdigest():
            raise ValueError("frozen changes digest mismatch")
        return changes
    if not path.name.startswith("pool-"):
        raise ValueError("replay requires a frozen pool, never a draft")
    pool = tomllib.loads(path.read_text())
    freeze = json.loads(path.with_name("freeze-" + path.stem.removeprefix("pool-") + ".json").read_text())
    if hashlib.sha256(canonical(pool)).hexdigest() != freeze["freeze_digest"]:
        raise ValueError("frozen pool digest mismatch")
    private_path = private_path or path.parent / "private" / path.name
    private = {}
    if private_path.exists():
        private = {row["id"]: row for row in tomllib.loads(private_path.read_text()).get("repository", [])}
    changes = []
    for public in pool.get("repository", []):
        if str(public["slice"]) != str(slice_id):
            continue
        row = public
        if public.get("private"):
            row = private.get(public["id"])
            if row is None:
                raise ValueError("missing private pool entry")
            payload = {"url": row["url"], "commits": [[c["base"], c["head"]] for c in row["changes"]]}
            if hashlib.sha256(canonical(payload)).hexdigest() != public["sha256"]:
                raise ValueError("private pool digest mismatch")
        for change in row["changes"]:
            identity = hashlib.sha256(canonical([public["id"], change["kind"], change["base"], change["head"]])).hexdigest()
            changes.append(
                {
                    **change,
                    "id": identity,
                    "repo": public["id"],
                    "repository_url": row["url"],
                    "freeze_digest": freeze["freeze_digest"],
                    "slice": slice_id,
                }
            )
    if not changes:
        raise ValueError("frozen slice has no changes")
    return changes
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--manifest", type=Path, required=True, help="frozen JSON: changes array plus sha256 of canonical changes JSON")
    parser.add_argument("--proof-history", action="store_true", help="write a five-change own-history manifest, then exit")
    parser.add_argument("--image")
    parser.add_argument("--private-manifest", type=Path)
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--arm", choices=("default", "long_deadline"), default="default")
    parser.add_argument("--pool", default="p1")
    parser.add_argument("--slice", default="1")
    parser.add_argument("--out", type=Path)
    parser.add_argument("--lane", choices=("ax", "kind", "docker", "mixed"), default="mixed")
    group = parser.add_mutually_exclusive_group()
    group.add_argument("--deadline-scale", type=float, default=1.0)
    group.add_argument("--calibration", type=Path)
    parser.add_argument("--native-sample", type=int, default=0)
    parser.add_argument("--docker-image-bytes", type=int, help="unpacked image size upper bound, required for VM pull")
    parser.add_argument("--ax-bin", default="ax")
    parser.add_argument("--kubeconfig", type=Path)
    parser.add_argument("--atespace", default="default")
    args = parser.parse_args()
    if args.proof_history:
        changes = proof_changes(Path.cwd())
        write_json(args.manifest, {"changes": changes, "sha256": hashlib.sha256(json.dumps(changes, sort_keys=True).encode()).hexdigest()})
        return 0
    if not args.image:
        parser.error("--image digest is required")
    changes = load_slice(args.manifest, args.slice, args.private_manifest)
    factor = args.deadline_scale
    if args.calibration:
        calibration = json.loads(args.calibration.read_text())
        if calibration.get("status") != "ok" or calibration.get("image") != args.image:
            parser.error("calibration must be successful and match the replay image")
        factor = calibration["quick_total"]["factor"]
    if args.native_sample < 0 or (args.native_sample and args.lane not in {"ax", "kind"}):
        parser.error("--native-sample requires an ax or kind cluster run and a positive K")
    items = [make_item(change, args.arm, args.image, deadline_scale=factor, lane=args.lane) for change in changes]
    if len({i.id for i in items}) != len(items):
        parser.error("duplicate change identity")
    args.out = args.out or Path.home() / "ousast-results/unseen" / args.pool / args.slice / args.arm
    if args.dry_run:
        print(json.dumps({"items": len(items), "input_digest": hashlib.sha256(canonical([i.input_digest for i in items])).hexdigest()}))
        return 0
    if args.out.resolve().is_relative_to(Path(__file__).resolve().parents[2]):
        parser.error("raw replay output must be outside the repository")
    failed = run_replays(changes, args, args.out, args.lane, deadline_scale=factor)
    if args.native_sample:
        failed |= run_replays(sample_changes(changes, args.native_sample), args, args.out / "native", "docker", deadline_scale=factor)
    return 2 if failed else 0
 def sample_changes(changes, count):
    if count < 1:
        raise ValueError("sample size must be positive")
    if len({str(c["id"]) for c in changes}) != len(changes):
        raise ValueError("duplicate change identity")
    return sorted(changes, key=lambda c: hashlib.sha256(str(c["id"]).encode()).digest())[:count]
 def run_replays(changes, args, out, lane, *, deadline_scale=1.0, deadline=None):
    if out.resolve().is_relative_to(Path(__file__).resolve().parents[2]):
        raise ValueError("raw replay output must be outside the repository")
    items = [make_item(c, args.arm, args.image, deadline_scale=deadline_scale, lane=lane, deadline=deadline) for c in changes]
    write_json(
        out / "inputs.json",
        [{"item_id": item.id, "change": change, "input_digest": item.input_digest} for item, change in zip(items, changes, strict=True)],
    )
    maximum = max(
        max(json.loads(i.inputs["SPEC_URL"])["deadline_seconds"], json.loads(i.inputs["SPEC_URL"])["base_deadline_seconds"]) for i in items
    )
    workload = Workload(args.image, frozenset({"SPEC_URL", "RESULT_URL"}), maximum + 600, validate_result, kind="replay")
    lanes = ("ax", "ax", "docker") if lane == "mixed" else (lane,) * (2 if lane in {"ax", "kind"} else 1)
    original = {item.id: change for item, change in zip(items, changes, strict=True)}
    executors = {}
    for name in set(lanes):
        transport = (DockerLane if name == "docker" else AXLane)(args, workload)
        def execute(item, output, attempt, transport=transport, name=name):
            spec = original[item.id]
            # Re-render on placement, including VM fallback: native is always unscaled.
            placed = make_item(spec, args.arm, args.image, deadline_scale=deadline_scale, lane=name, deadline=deadline)
            placed.id = item.id
            record = {**json.loads(placed.inputs["SPEC_URL"]), "lane": name, **transport(placed, output, attempt)}
            if (output / "result.dat").exists():
                key = f"unseen/{placed.input_digest}/{name}/result.dat"
                transport.store._put(key, (output / "result.dat").read_bytes())
                record["result_object"] = key
            return record
        executors[name] = execute
    return dispatch(items, workload, out, executors, lanes=lanes)
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,224 @@
 """Credential-free replay actor. Standard library only; PUT is completion."""
 from __future__ import annotations
 import argparse
 import json
 import os
 import re
 import subprocess
 import sys
 import tarfile
 import time
 import urllib.error
 import urllib.request
 from pathlib import Path
 from urllib.parse import urlsplit
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "learn"))
 from engine_task_entry import transfer
 CLUSTER_FLAGS = (
    "-Xms1700m -Xmx1700m -XX:MaxMetaspaceSize=256m -XX:ReservedCodeCacheSize=128m "
    "-XX:MaxDirectMemorySize=256m -Xss512k -XX:ActiveProcessorCount=2 -XX:+UseG1GC"
 )
 class ReplayFailure(Exception):
    """Locally controlled diagnostic only."""
 def validate_spec(spec):
    parts = urlsplit(spec["repository_url"])
    if (
        parts.scheme != "https"
        or not parts.hostname
        or "." not in parts.hostname
        or parts.username
        or parts.password
        or parts.query
        or parts.fragment
    ):
        raise ReplayFailure("repository must be public HTTPS")
    if parts.port not in (None, 443) or parts.hostname.endswith((".local", ".internal", ".localhost")):
        raise ReplayFailure("repository must be public HTTPS")
    import ipaddress
    try:
        ipaddress.ip_address(parts.hostname)
    except ValueError:
        pass
    else:
        raise ReplayFailure("repository must use public DNS")
    if any(not re.fullmatch("[0-9a-f]{40,64}", spec[key]) for key in ("base", "head")):
        raise ReplayFailure("invalid revision")
    flags = spec.get("hook_flags", [])
    if flags and (len(flags) != 2 or flags[0] != "--deadline" or not re.fullmatch(r"[1-9][0-9]*", str(flags[1]))):
        raise ReplayFailure("unsupported hook flags")
 def main(*, work_root=Path("/tmp"), runner=subprocess.run, heap_profile="cluster", clock=time.monotonic):
    output = work_root / "out"
    output.mkdir(parents=True, exist_ok=True)
    instrument = {
        "status": "instrument_failure",
        "head_verified": False,
        "base_verified": False,
        "changed_bytes": {},
        "checkout_files": 0,
        "checkout_bytes": 0,
        "hook_bytes_read": 0,
        "jvm_wall_seconds": 0,
        "jvm_time_basis": "scan build_seconds + query_seconds",
        "hook_exit": None,
        "timings": {},
        "heap_profile": heap_profile,
    }
    spec = {}
    step = "GET spec"
    started = clock()
    def run(command, *, timeout=180, env=None):
        before = clock()
        result = runner(command, capture_output=True, text=True, timeout=timeout, env=env)
        instrument["timings"][step] = instrument["timings"].get(step, 0) + clock() - before
        if result.returncode:
            raise ReplayFailure(f"exit {result.returncode}")
        return result
    try:
        spec_path = work_root / "spec.dat"
        transfer(os.environ["SPEC_URL"], spec_path, readiness_budget=60)
        step = "validate spec"
        spec = json.loads(spec_path.read_text())
        instrument["image"] = spec.get("image")
        validate_spec(spec)
        instrument["deadline_seconds"] = int(spec["hook_flags"][1]) if spec.get("hook_flags") else 30
        instrument["deadline_scale"] = spec.get("deadline_scale", 1.0)
        case = work_root / "case"
        case.mkdir()
        git = ["git", "-c", "core.hooksPath=/dev/null", "-c", "protocol.file.allow=never", "-C", str(case)]
        step = "git init"
        run([*git, "init", "-q"])
        run([*git, "remote", "add", "origin", spec["repository_url"]])
        # One total fetch budget, independent of the hook deadline.
        fetch_end = clock() + 180
        for key in ("head", "base"):
            step = "fetch " + key
            remaining = fetch_end - clock()
            if remaining <= 0:
                raise ReplayFailure("fetch deadline")
            run([*git, "fetch", "--no-tags", "--depth", "1", "origin", spec[key]], timeout=remaining)
            step = "verify " + key
            run([*git, "cat-file", "-e", spec[key] + "^{commit}"])
            instrument[key + "_verified"] = True
        step = "checkout"
        run([*git, "checkout", "--detach", spec["head"]])
        paths = run([*git, "ls-files", "-z"]).stdout.split("\0")
        for name in filter(None, paths):
            path = case / name
            if path.is_file() and not path.is_symlink():
                data = path.read_bytes()
                instrument["checkout_files"] += 1
                instrument["checkout_bytes"] += len(data)
                if instrument["checkout_bytes"] > 500 * 1024 * 1024:
                    raise ReplayFailure("checkout size limit")
        step = "changed files"
        changed = run([*git, "diff", "--name-only", "--diff-filter=ACMRT", "-z", spec["base"], spec["head"]]).stdout.split("\0")
        for name in filter(None, changed):
            path = case / name
            if path.is_file() and not path.is_symlink() and path.resolve().is_relative_to(case.resolve()):
                instrument["changed_bytes"][name] = len(path.read_bytes())
        if not instrument["checkout_bytes"] or not sum(instrument["changed_bytes"].values()):
            instrument["suspect_fast"] = True
            raise ReplayFailure("no changed bytes read")
        step = "pre-push"
        env = {
            key: value for key, value in os.environ.items() if key not in {"SPEC_URL", "RESULT_URL", "_JAVA_OPTIONS", "JDK_JAVA_OPTIONS"}
        }
        env["OPENULTRASAST_CPG_HEAP_MB"] = "1700" if heap_profile == "cluster" else "2560"
        env["JAVA_TOOL_OPTIONS"] = CLUSTER_FLAGS if heap_profile == "cluster" else "-Xmx2560m"
        command = [
            "ousast",
            "pre-push",
            str(case),
            "--base",
            spec["base"],
            "--head",
            spec["head"],
            "--artifact",
            str(output / "push.json"),
            *spec.get("hook_flags", []),
        ]
        before = clock()
        completed = runner(
            command, capture_output=True, text=True, timeout=int(spec["hook_flags"][1]) + 30 if spec.get("hook_flags") else 60, env=env
        )
        instrument["timings"][step] = clock() - before
        instrument["hook_exit"] = completed.returncode
        (output / "push.txt").write_text(completed.stdout)
        if completed.returncode not in (0, 1):
            raise ReplayFailure(f"hook exit {completed.returncode}")
        step = "read push artifact"
        push = json.loads((output / "push.json").read_text())
        instrument["hook_bytes_read"] = sum(t.get("bytes_read", 0) for t in push.get("quick_tier", []))
        scans = push.get("scans", [])
        instrument["jvm_wall_seconds"] = sum(s.get("scan", {}).get(k, 0) for s in scans for k in ("build_seconds", "query_seconds"))
        uncovered = "language_not_covered" in json.dumps(push.get("admission", {}).get("coverage_reasons", []))
        partitions = [part for scan in scans for part in scan.get("scan", {}).get("partitions", [])]
        unsupported_only = (
            uncovered
            and instrument["hook_bytes_read"] == 0
            and bool(partitions)
            and all(part.get("status") == "unsupported" for part in partitions)
        )
        instrument["suspect_fast"] = bool(scans) and not unsupported_only and instrument["jvm_wall_seconds"] < 5
        if instrument["suspect_fast"] or (instrument["hook_bytes_read"] <= 0 and not uncovered):
            instrument["suspect_fast"] = True
            raise ReplayFailure("suspect_fast or unread hook input")
        engine = {
            "repository": spec["repository_url"],
            "revisions": {key: spec[key] for key in ("base", "head")},
            "scans": scans,
            "admission": push.get("admission", {}),
        }
        (output / "engine.json").write_text(json.dumps(engine))
        instrument["status"] = "ok"
    except Exception as exc:
        detail = (
            f"HTTP {exc.code}"
            if isinstance(exc, urllib.error.HTTPError)
            else str(exc)
            if isinstance(exc, ReplayFailure)
            else type(exc).__name__
        )
        instrument["failure"] = {"step": step, "status": detail}
        # A crash artifact must never be mistaken for a completed scan.
        if not (output / "push.json").exists():
            (output / "push.json").write_text("{}")
        if not (output / "push.txt").exists():
            (output / "push.txt").write_text("")
        if not (output / "engine.json").exists():
            (output / "engine.json").write_text("{}")
    instrument["seconds"] = clock() - started
    (output / "instrument.json").write_text(json.dumps(instrument))
    try:
        archive = work_root / "result.dat"
        with tarfile.open(archive, "w") as tar:
            for name in ("push.json", "push.txt", "engine.json", "instrument.json"):
                tar.add(output / name, arcname=name)
        request = urllib.request.Request(
            os.environ["RESULT_URL"], data=archive.read_bytes(), method="PUT", headers={"Content-Type": "application/x-tar"}
        )
        transfer(request, readiness_budget=60)
    except Exception as exc:
        detail = f"HTTP {exc.code}" if isinstance(exc, urllib.error.HTTPError) else type(exc).__name__
        print("PUT result: " + detail, file=sys.stderr)
        return 1
    return int(instrument["status"] != "ok")
 if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--heap-profile", choices=("cluster", "vm"), default="cluster")
    raise SystemExit(main(heap_profile=parser.parse_args().heap_profile))
@@ -0,0 +1,363 @@
 """Push-level unseen evaluation, explicit coverage and paired adoption evidence."""
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import math
 import random
 from collections import Counter, defaultdict
 from pathlib import Path
 from openultrasast.model.taxonomy import load_families
 from openultrasast.push.report import CAPABILITY_VETOES
 STATES = ("instrument_failure", "unanalysable", "quick_only", "engine_covered")
 def coverage(record):
    instrument = record.get("instrument", {})
    push = record.get("push")
    if (
        not isinstance(push, dict)
        or not instrument.get("head_verified")
        or not instrument.get("base_verified")
        or instrument.get("suspect_fast")
        or instrument.get("failure")
        or instrument.get("hook_exit") not in (0, 1)
        or sum(instrument.get("changed_bytes", {}).values()) <= 0
    ):
        return "instrument_failure"
    if "language_not_covered" in json.dumps([push.get("skipped", []), push.get("admission", {}).get("coverage_reasons", [])]) and not any(
        tier.get("bytes_read", 0) for tier in push.get("quick_tier", [])
    ):
        return "unanalysable"
    if instrument.get("hook_bytes_read", 0) <= 0:
        return "instrument_failure"
    changed = set(instrument["changed_bytes"])
    if any(
        outcome.get("status") == "completed" and outcome.get("identity", {}).get("path") in changed
        for scan in push.get("scans", [])
        if scan.get("side") == "head"
        for outcome in scan.get("scan", {}).get("question_outcomes", [])
    ):
        return "engine_covered"
    return "quick_only"
 def findings(record):
    push = record.get("push", {})
    admission = push.get("admission", {})
    for defect in admission.get("defects", []):
        for path, line in defect.get("locations", []):
            yield "alerts", {**defect, "path": path, "line": line}
    seen = set()
    for disposition in admission.get("dispositions", []):
        delta = disposition.get("candidate", {}).get("delta", {})
        operation = delta.get("head_operation")
        if (
            disposition.get("admitted")
            or delta.get("novelty") not in {"new", "worsened"}
            or not set(disposition.get("reasons", [])) <= CAPABILITY_VETOES
            or operation is None
            or delta.get("witness") is None
            or delta.get("defect_id") in seen
        ):
            continue
        seen.add(delta.get("defect_id"))
        yield "advisory", {**operation, "family": delta.get("family")}
    taxonomy = load_families()
    for tier in push.get("quick_tier", []):
        for finding in tier.get("findings", []):
            family = taxonomy.family_of_cwe(finding.get("cwe") or "")
            yield "quick", {**finding, "family": family.id if family else None}
 def location_match(record, finding):
    for file in record.get("files", []):
        if finding.get("path") != file["path"]:
            continue
        line = finding.get("line", 0)
        if any(start - 10 <= line <= end + 10 for start, end in file.get("head_lines", [])):
            return True
        if record.get("family") != "config_secrets" and file["path"] == record.get("path", file["path"]):
            function = record.get("function")
            if function and function != "<global>" and finding.get("function") == function:
                return True
            span = record.get("function_lines") or file.get("function_lines")
            if span and span[0] <= line <= span[1]:
                return True
    return False
 def catches(record):
    return sorted(
        {
            stream
            for stream, finding in findings(record)
            if finding.get("family") == record.get("family") and location_match(record, finding)
        }
    )
 def false_alarm(record, *, alerts_only=False):
    return any(not alerts_only or stream == "alerts" for stream, _ in findings(record))
 def wilson(successes, n):
    if n == 0:
        return [None, None]
    p, z = successes / n, 1.96
    centre = (p + z * z / (2 * n)) / (1 + z * z / n)
    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / (1 + z * z / n)
    return [max(0, centre - half), min(1, centre + half)]
 def required_n(p, width):
    for n in range(1, 1000000):
        low, high = wilson(p * n, n)
        if max(p - low, high - p) <= width:
            return n
    raise ValueError("requested precision exceeds sizing range")
 def rate(values):
    n, k = len(values), sum(values)
    return {"n": n, "count": k, "rate": k / n if n else None, "wilson95": wilson(k, n)}
 def cluster_interval(rows, *, seed=0, draws=2000):
    clusters = defaultdict(list)
    for repo, value in rows:
        clusters[repo].append(value)
    if not clusters:
        return [None, None]
    rng = random.Random(seed)
    groups = list(clusters.values())
    samples = []
    for _ in range(draws):
        values = [value for group in rng.choices(groups, k=len(groups)) for value in group]
        samples.append(sum(values) / len(values))
    samples.sort()
    return [samples[int(0.025 * (draws - 1))], samples[int(0.975 * (draws - 1))]]
 def icc(rows):
    clusters = defaultdict(list)
    for repo, value in rows:
        clusters[repo].append(value)
    n, k = len(rows), len(clusters)
    if k < 2 or n <= k:
        return None
    mean = sum(v for _, v in rows) / n
    between = sum(len(v) * (sum(v) / len(v) - mean) ** 2 for v in clusters.values()) / (k - 1)
    within = sum(sum((x - sum(v) / len(v)) ** 2 for x in v) for v in clusters.values()) / (n - k)
    size = (n - sum(len(v) ** 2 for v in clusters.values()) / n) / (k - 1)
    denominator = between + (size - 1) * within
    return (between - within) / denominator if denominator else 0.0
 def mcnemar(a, b):
    pairs = list(zip(a, b, strict=True))
    losses = sum(x and not y for x, y in pairs)
    gains = sum(y and not x for x, y in pairs)
    n = losses + gains
    return min(1.0, 2 * sum(math.comb(n, i) for i in range(min(losses, gains) + 1)) / 2**n) if n else 1.0
 def score(records, *, seed=0):
    counts = Counter(coverage(r) for r in records)
    if not records or counts["instrument_failure"] / len(records) > 0.05:
        raise ValueError("slice exceeds 5% instrument_failure (or is empty)")
    usable = [r for r in records if coverage(r) != "instrument_failure"]
    def metrics(rows):
        ordinary = [r for r in rows if r["kind"] == "ordinary"]
        vulnerable = [r for r in rows if r["kind"] != "ordinary"]
        clustered = [(r["repo"], int(false_alarm(r))) for r in ordinary]
        return {
            "catch": rate([bool(catches(r)) for r in vulnerable]),
            "false_alarm": {
                **rate([false_alarm(r) for r in ordinary]),
                "cluster95": cluster_interval(clustered, seed=seed),
                "icc": icc(clustered),
            },
            "alerts_only": rate([false_alarm(r, alerts_only=True) for r in ordinary]),
        }
    breakdown = {}
    for key in ("family", "method", "post_cutoff"):
        groups = defaultdict(list)
        for r in usable:
            groups[str(r.get(key, "unknown"))].append(r)
        breakdown[key] = {key: metrics(rows) for key, rows in sorted(groups.items())}
    breakdown["coverage"] = {state: metrics([r for r in usable if coverage(r) == state]) for state in STATES[1:]}
    breakdown["stream"] = {
        stream: rate([stream in catches(r) for r in usable if r["kind"] != "ordinary"]) for stream in ("alerts", "advisory", "quick")
    }
    return {
        **metrics(usable),
        "total": len(records),
        "deadlines": [
            {"lane": lane, "deadline_seconds": deadline, "deadline_scale": factor, "applied_deadline_scale": applied, "count": count}
            for (lane, deadline, factor, applied), count in sorted(
                Counter(
                    (r.get("lane", "unknown"), r.get("deadline_seconds"), r.get("deadline_scale"), r.get("applied_deadline_scale"))
                    for r in records
                ).items(),
                key=lambda pair: str(pair[0]),
            )
        ],
        "coverage": {state: counts[state] for state in STATES},
        "breakdowns": breakdown,
        "confirmed": metrics([r for r in usable if r.get("label_check", r.get("confirmed")) in ("confirmed", True)]),
    }
 def agreement(cluster, native):
    """Missing, failed or wrong-lane records are unknown, never matching quiet pushes."""
    cc = {r["id"]: r for r in cluster}
    if len(cc) != len(cluster) or len({r["id"] for r in native}) != len(native):
        raise ValueError("duplicate agreement identities")
    pairs, unknown, disagreements = [], [], []
    for n in sorted(native, key=lambda r: r["id"]):
        c = cc.get(n["id"])
        if (
            c is None
            or c.get("lane") not in {"ax", "kind"}
            or n.get("lane") != "docker"
            or c.get("image") != n.get("image")
            or c.get("base_deadline_seconds") != n.get("base_deadline_seconds")
            or coverage(c) == "instrument_failure"
            or coverage(n) == "instrument_failure"
        ):
            unknown.append(n["id"])
            continue
        cluster_flag, native_flag = false_alarm(c), false_alarm(n)
        same = cluster_flag == native_flag
        pairs.append({"change_id": n["id"], "cluster_flagged": cluster_flag, "native_flagged": native_flag, "same": same})
        if not same:
            disagreements.append(n["id"])
    report = rate([p["same"] for p in pairs])
    eligible = bool(pairs) and not unknown and report["wilson95"][0] >= 0.95
    return {
        **report,
        "requested": len(native),
        "pairs": pairs,
        "unknown": unknown,
        "disagreements": disagreements,
        "baseline_eligible": eligible,
        "flagged": not eligible,
    }
 def budgets(rows, *, thresholds=None, binary=False):
    ordinary = [r for r in rows if r["kind"] == "ordinary"]
    vulnerable = [r for r in rows if r["kind"] != "ordinary"]
    if binary:
        fa = rate([r["prediction"] for r in ordinary])
        return {
            "catch": rate([r["prediction"] for r in vulnerable]),
            "false_alarm": fa,
            "budgets_met": [f"{budget}%" for budget in (1, 5, 10) if fa["rate"] is not None and fa["rate"] <= budget / 100],
        }
    output = {}
    for budget in (1, 5, 10):
        key = f"{budget}%"
        if thresholds is not None and key not in thresholds:
            continue
        if not ordinary:
            output[key] = {"label": "not_run"}
            continue
        if thresholds is not None:
            threshold = thresholds[key]
        else:
            candidates = sorted({r["score"] for r in rows})
            candidates.append(math.nextafter(candidates[-1], math.inf))
            threshold = next(t for t in candidates if sum(r["score"] >= t for r in ordinary) / len(ordinary) <= budget / 100)
        output[key] = {
            "threshold": threshold,
            "label": "fixed" if thresholds is not None else "exploratory",
            "catch": rate([r["score"] >= threshold for r in vulnerable]),
            "false_alarm": rate([r["score"] >= threshold for r in ordinary]),
        }
    return output
 def gate(a, b, *, slice_id=None, informed=False, binary=True, threshold=None, threshold_fixed=False, seed=0):
    not_run = {"gate": "not_run"}
    if not slice_id or informed or not a or not b or (not binary and (not threshold_fixed or threshold is None)):
        return not_run
    try:
        score(a, seed=seed)
        score(b, seed=seed)
    except ValueError:
        return not_run
    aa, bb = {r["id"]: r for r in a}, {r["id"]: r for r in b}
    if len(aa) != len(a) or len(bb) != len(b) or aa.keys() != bb.keys():
        return not_run
    pairs = [
        (aa[key], bb[key]) for key in sorted(aa) if coverage(aa[key]) != "instrument_failure" and coverage(bb[key]) != "instrument_failure"
    ]
    if any(x["kind"] != y["kind"] or x["repo"] != y["repo"] for x, y in pairs):
        return not_run
    vulnerable = [(x, y) for x, y in pairs if x["kind"] != "ordinary"]
    ordinary = [(x, y) for x, y in pairs if x["kind"] == "ordinary"]
    if not vulnerable or not ordinary:
        return not_run
    ca = [bool(catches(x)) for x, _ in vulnerable]
    cb = [bool(catches(y)) if binary else y["score"] >= threshold for _, y in vulnerable]
    fa = [false_alarm(x) for x, _ in ordinary]
    fb = [false_alarm(y) if binary else y["score"] >= threshold for _, y in ordinary]
    catch_p, fa_p = mcnemar(ca, cb), mcnemar(fa, fb)
    regression = (sum(cb) < sum(ca) and catch_p < 0.05) or (binary and sum(fb) > sum(fa) and fa_p < 0.05)
    return {
        "gate": "regression" if regression else "pass",
        "slice": slice_id,
        "catch": {"difference": sum(cb) / len(cb) - sum(ca) / len(ca), "mcnemar_p": catch_p},
        "false_alarm": {
            "difference": sum(fb) / len(fb) - sum(fa) / len(fa),
            "mcnemar_p": fa_p,
            "cluster95": cluster_interval([(x["repo"], int(v) - int(u)) for (x, _), u, v in zip(ordinary, fa, fb, strict=True)], seed=seed),
        },
    }
 def load_records(path):
    if path.is_file():
        return json.loads(path.read_text())
    rows = []
    for entry in json.loads((path / "inputs.json").read_text()):
        result = path / (hashlib.sha256(entry["item_id"].encode()).hexdigest() + ".json")
        record = json.loads(result.read_text()) if result.exists() else {}
        if record.get("input_digest") != entry["input_digest"]:
            record = {}
        rows.append({**entry["change"], **record, "id": entry["change"]["id"]})
    return rows
 def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("records", type=Path, help="JSON array of joined change/instrument/push records")
    parser.add_argument("--out", type=Path, required=True)
    parser.add_argument("--against", type=Path, help="production-arm records for a paired adoption gate")
    parser.add_argument("--native", type=Path, help="native sample root; auto-detected under replay root")
    parser.add_argument("--slice-id")
    parser.add_argument("--informed", action="store_true")
    args = parser.parse_args()
    current = load_records(args.records)
    result = score(current)
    native = args.native or (args.records / "native" if args.records.is_dir() and (args.records / "native").exists() else None)
    if native:
        result["native_agreement"] = agreement(current, load_records(native))
        result["baseline_eligible"] = result["native_agreement"]["baseline_eligible"]
        result["flagged"] = result["native_agreement"]["flagged"]
    result["unseen"] = gate(load_records(args.against) if args.against else [], current, slice_id=args.slice_id, informed=args.informed)
    if native and result["flagged"]:
        result["unseen"] = {"gate": "not_run", "reason": "native_agreement"}
    args.out.write_text(json.dumps(result, sort_keys=True, indent=2) + "\n")
 if __name__ == "__main__":
    main()
@@ -0,0 +1,331 @@
 """Advisory selection. Network adapters are constructed only by the coordinator CLI."""
 from __future__ import annotations
 import base64
 import json
 import random
 import re
 from dataclasses import dataclass
 from datetime import date
 from urllib.parse import urlencode, urlsplit
 from openultrasast.model.taxonomy import load_families
 from .eligibility import RepositoryNotFound, normalize
 ECOSYSTEMS = ("pip", "npm", "maven", "composer")
 OSV_ECOSYSTEMS = dict(zip(ECOSYSTEMS, ("PyPI", "npm", "Maven", "Packagist"), strict=True))
 FAMILIES = {"injection", "path", "deserialization", "access_control", "output_encoding", "untrusted_destination", "config_secrets"}
 PERMISSIVE = {"MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC", "0BSD", "Unlicense", "Zlib", "PostgreSQL", "BSL-1.0"}
 FIX = re.compile(r"https://github\.com/([\w.-]+/[\w.-]+)/commit/([a-fA-F0-9]{7,40})(?:[/?#].*)?$", re.I)
 class Rejected(ValueError):
    """Expected eligibility rejection; messages are fixed reason codes, never names."""
@dataclass(frozen=True)
 class Candidate:
    repository: str
    url: str
    fix: str
    parent: str
    advisory: str
    ecosystem: str
    family: str
    post_cutoff: bool
    first_affected: str | None
    license_spdx: str
    license_class: str
    license_ref: str
    license_path: str
 def post_cutoff(row: dict) -> bool:
    return date.fromisoformat(row["published_at"][:10]) > date(2026, 6, 1)
 def fix_links(row: dict) -> set[tuple[str, str]]:
    links = set()
    for reference in row.get("references", []):
        url = reference if isinstance(reference, str) else reference.get("url", "")
        match = FIX.fullmatch(url)
        if match:
            links.add((normalize(match[1]), match[2].lower()))
    return links
 def ecosystem(row: dict) -> str | None:
    values = {v["package"]["ecosystem"].lower() for v in row.get("vulnerabilities", [])}
    return next((e for e in ECOSYSTEMS if e in values), None)
 def reduce_advisory(row: dict) -> dict:
    """Keep only selection inputs, including every fix needed by the exclusion index.
    Preserve the parser's shape so fresh and resumed pages follow the same path.
    Commit parents, licenses and OSV brackets are resolved later into Candidate.
    """
    return {
        "ghsa_id": row["ghsa_id"],
        "published_at": row["published_at"],
        "type": row.get("type", "reviewed"),
        "withdrawn_at": row.get("withdrawn_at"),
        "cwes": [{"cwe_id": c["cwe_id"]} for c in row.get("cwes", [])],
        "vulnerabilities": [{"package": {key: v["package"][key] for key in ("ecosystem", "name")}} for v in row.get("vulnerabilities", [])],
        "references": [f"https://github.com/{name}/commit/{sha}" for name, sha in sorted(fix_links(row))],
    }
 def ordered_advisories(rows: list[dict], seed: int) -> list[dict]:
    """Stable seeded ordering, post-cutoff first in each ecosystem; round-robin strata."""
    rng = random.Random(seed)
    groups = []
    for eco in ECOSYSTEMS:
        group = sorted((r for r in rows if ecosystem(r) == eco), key=lambda r: r["ghsa_id"])
        rng.shuffle(group)
        group.sort(key=lambda r: not post_cutoff(r))
        groups.append(group)
    return [group[i] for i in range(max(map(len, groups), default=0)) for group in groups if i < len(group)]
 def first_affected(record: dict, row: dict, eco: str) -> str | None:
    packages = {v["package"]["name"] for v in row["vulnerabilities"] if v["package"]["ecosystem"].lower() == eco}
    versions = set()
    for affected in record.get("affected", []):
        package = affected.get("package", {})
        if package.get("ecosystem") != OSV_ECOSYSTEMS[eco] or package.get("name") not in packages:
            continue
        for span in affected.get("ranges", []):
            if span.get("type") not in {"ECOSYSTEM", "SEMVER"}:
                continue
            for event in span.get("events", []):
                if event.get("introduced") not in {None, "0"}:
                    versions.add(event["introduced"])
    if len(versions) > 1:
        raise Rejected("ambiguous_version_bracket")
    return next(iter(versions), None)
 def license_info(record: dict) -> tuple[str, str]:
    # Explicit pinned-file SPDX wins. For GitHub-recognized full texts its license endpoint
    # provides the detected SPDX. Unknown/custom/compound declarations stay private.
    declared = re.search(r"SPDX-License-Identifier:\s*([^\r\n]+)", record.get("text", ""))
    spdx = declared[1].strip().removesuffix("*/").strip() if declared else record.get("spdx_id") or "NONE"
    return spdx, "permissive" if spdx in PERMISSIVE else "private"
 def candidate(row: dict, github, osv) -> Candidate:
    if date.fromisoformat(row["published_at"][:10]) < date(2019, 1, 1):
        raise Rejected("date")
    if row.get("type", "reviewed") != "reviewed" or row.get("withdrawn_at"):
        raise Rejected("advisory_status")
    eco = ecosystem(row)
    if eco is None:
        raise Rejected("ecosystem")
    taxonomy = load_families()
    families = {f.id for c in row.get("cwes", []) if (f := taxonomy.family_of_cwe(c["cwe_id"])) and f.id in FAMILIES}
    if len(families) != 1:
        raise Rejected("family")
    links = fix_links(row)
    if len(links) != 1:
        raise Rejected("fix_links")
    name, fix = next(iter(links))
    repo = github.get_repo(name)
    url = urlsplit(repo.get("clone_url", ""))
    if (
        repo.get("private", True)
        or not 0 <= repo.get("size", -1) <= 500 * 1024
        or url.scheme != "https"
        or url.hostname != "github.com"
        or url.username
        or url.password
        or url.query
        or url.fragment
        or normalize(repo["clone_url"]) != normalize(repo["full_name"])
    ):
        raise Rejected("repository")
    commit = github.get_commit(repo["full_name"], fix)
    if len(commit["parents"]) != 1:
        raise Rejected("parents")
    parent = commit["parents"][0]["sha"]
    license_record = github.get_license(repo["full_name"], parent)
    spdx, license_class = license_info(license_record)
    return Candidate(
        normalize(repo["full_name"]),
        repo["clone_url"],
        commit["sha"],
        parent,
        row["ghsa_id"],
        eco,
        next(iter(families)),
        post_cutoff(row),
        first_affected(osv.get(row["ghsa_id"]), row, eco),
        spdx,
        license_class,
        parent,
        license_record.get("path", ""),
    )
 class JSONTransport:
    """Coordinator GET transport with bounded retries; all I/O and waits are injectable."""
    def __init__(self, *, opener=None, sleeper=None, clock=None):
        import time
        from urllib.request import urlopen
        self.opener = opener or urlopen
        self.sleeper = sleeper or time.sleep
        self.clock = clock or time.time
        self.attempts = 0
        self.rate_limit = {}
        self.response_headers = {}
    def get(self, url: str, headers: dict) -> object:
        from http.client import IncompleteRead
        from urllib.error import HTTPError, URLError
        from urllib.request import Request
        for attempt in range(5):
            self.attempts += 1
            retry_headers, limited = {}, False
            try:
                with self.opener(Request(url, headers=headers), timeout=60) as response:
                    retry_headers = getattr(response, "headers", {})
                    self.record_rate(retry_headers)
                    body = json.load(response)
                    self.response_headers = retry_headers
                    return body
            except HTTPError as exc:
                self.record_rate(exc.headers)
                if exc.code == 404:
                    raise RepositoryNotFound("not_found") from None
                limited = exc.code == 429 or (
                    exc.code == 403 and (exc.headers.get("X-RateLimit-Remaining") == "0" or exc.headers.get("Retry-After"))
                )
                transient = exc.code in {500, 502, 503, 504}
                if attempt == 4 or not (limited or transient):
                    raise ValueError("http_failure") from None
                retry_headers = exc.headers
            except (URLError, TimeoutError, ConnectionError, IncompleteRead, json.JSONDecodeError):
                if attempt == 4:
                    raise ValueError("http_failure") from None
            except Exception:
                raise ValueError("http_failure") from None
            try:
                delay = float(retry_headers.get("Retry-After", "0"))
                if limited and not delay:
                    delay = max(60, float(retry_headers.get("X-RateLimit-Reset", "0")) - self.clock() + 1)
                delay = max(delay, 2**attempt)
                if delay > 3605:
                    raise ValueError("retry_window")
            except (TypeError, ValueError):
                raise ValueError("http_retry_failed") from None
            self.sleeper(delay)
        raise ValueError("http_failure")
    def record_rate(self, headers):
        self.rate_limit = {
            key: headers.get(header)
            for key, header in (
                ("remaining", "X-RateLimit-Remaining"),
                ("limit", "X-RateLimit-Limit"),
                ("reset", "X-RateLimit-Reset"),
                ("retry_after", "Retry-After"),
            )
            if headers.get(header) is not None
        }
 class GitHub:
    def __init__(self, token: str, transport=None):
        if not token:
            raise ValueError("missing_gh_token")
        self.transport = transport or JSONTransport()
        self.headers = {"Authorization": "Bearer " + token, "Accept": "application/vnd.github+json"}
        self.repos: dict[str, dict] = {}
        self.calls = 0
    def get(self, path: str):
        self.calls += 1
        url = path if path.startswith("https://api.github.com/") else "https://api.github.com" + path
        return self.transport.get(url, self.headers)
    def get_repo(self, name: str) -> dict:
        name = normalize(name)
        if name not in self.repos:
            self.repos[name] = self.get("/repos/" + name)
        return self.repos[name]
    def get_commit(self, name: str, sha: str) -> dict:
        return self.get("/repos/" + normalize(name) + "/commits/" + sha)
    def get_license(self, name: str, ref: str) -> dict:
        try:
            row = self.get("/repos/" + normalize(name) + "/license?" + urlencode({"ref": ref}))
        except RepositoryNotFound:
            return {"spdx_id": "NONE", "text": "", "path": ""}
        return {
            "spdx_id": (row.get("license") or {}).get("spdx_id"),
            "path": row.get("path", ""),
            "text": base64.b64decode(row.get("content", "")).decode("utf-8", errors="replace"),
        }
    def advisory_page(self, next_url: str | None = None, *, ecosystem: str) -> dict:
        if ecosystem not in ECOSYSTEMS:
            raise ValueError("invalid_ecosystem")
        # Oldest first: newly published advisories do not shift already persisted pages.
        parameters = {
            "type": "reviewed",
            "per_page": 100,
            "sort": "published",
            "direction": "asc",
            "ecosystem": ecosystem,
            # Inclusive syntax used in benchmarks/independent/research-2026-09-30-php.md.
            "published": ">=2019-01-01",
        }
        taxonomy = load_families()
        cwes = {cwe for family in taxonomy.families if family.id in FAMILIES for cwe in family.cwes}
        # family_of_cwe uses exact membership. If the taxonomy gains non-exact tokens,
        # fetch broadly rather than risk excluding a client-selectable advisory.
        # GitHub's advisories `cwes` filter expects bare numbers (89), not "CWE-89".
        if cwes and all(re.fullmatch(r"CWE-[1-9][0-9]*", cwe) for cwe in cwes):
            parameters["cwes"] = ",".join(sorted((cwe.removeprefix("CWE-") for cwe in cwes), key=int))
        rows = self.get(next_url or "/advisories?" + urlencode(parameters))
        if not isinstance(rows, list):
            raise ValueError("invalid_advisory_page")
        link = self.transport.response_headers.get("Link", "")
        match = re.search(r'<([^>]+)>;\s*rel="next"', link)
        return {"rows": rows, "next_url": match[1] if match else None}
    def advisories(self):
        """Enumerate the candidate population, deduplicating multi-ecosystem advisories."""
        seen = set()
        for ecosystem in ECOSYSTEMS:
            next_url = None
            while True:
                result = self.advisory_page(next_url, ecosystem=ecosystem)
                for row in result["rows"]:
                    if row["ghsa_id"] not in seen:
                        seen.add(row["ghsa_id"])
                        yield row
                next_url = result["next_url"]
                if next_url is None:
                    break
 class OSV:
    def __init__(self, transport=None):
        self.transport = transport or JSONTransport()
        self.calls = 0
    def get(self, identifier: str) -> dict:
        if not re.fullmatch(r"GHSA-[\w-]+", identifier):
            raise ValueError("invalid_advisory_id")
        self.calls += 1
        try:
            return self.transport.get("https://api.osv.dev/v1/vulns/" + identifier, {})
        except RepositoryNotFound:
            return {}  # No OSV bracket is distinct from a failed service call.
@@ -0,0 +1,88 @@
 # Pre-push security for developers
 You push code. This checks it for security regressions first. You do not annotate
 anything, you do not need a security background, and you do not change how you work.
 ## The short version
 Install a git pre-push hook once. On every push it reads the code you changed,
 compares it against the known risks of the frameworks you already use, and warns
 you before the push leaves your machine. Where it can build and run your app, it
 goes further and proves an issue with a demonstration: a check that triggers the
 problem on your change and stops triggering once the problem is fixed. By default
 it only advises; it never blocks until you turn blocking on.
 ## Why this matters now
 Your backlog is full and your schedule is not yours. Security findings compete
 with feature tickets, and a vague "possible vulnerability" loses that fight every
 time: no one gets capacity to chase a maybe. Meanwhile you and your coding agents
 ship quickly, and an agent writing code does not pause to audit itself. A
 pre-push check is the place to catch a regression that you, or an agent acting
 for you, introduced, before it reaches the remote. In an agent-driven workflow it
 is the oversight step: the gate that reviews what the agent wrote, every push,
 without you having to become the security reviewer.
 ## From a finding to capacity
 The point of the proof is the prioritization conversation, not just your terminal.
 A theoretical warning dies in the backlog. A demonstrated proof does not: it is a
 reproducible check that triggers the problem on the current code and stops once
 the code is fixed. That is the thing you take to a product owner or to the
 business when you need capacity. It turns "security thinks this might be a
 problem" into "here is the exact input, the exact behavior, and the one-line
 difference that stops it," which is something a product owner can weigh against a
 feature with real information instead of fear.
 So the output is built to drop into your ticket system as evidence: a location, a
 concrete repair direction, and, where the app is runnable, the reproduction
 itself. That is what gets a fix scheduled rather than deferred.
 ## What you do
 1. Install the hook in a repo: `ousast pre-push install`.
 2. Push normally. Findings print at push time.
 3. Optionally set model keys and a spend cap in `.env`; nothing else is required.
 No code annotations. No markup. No per-project security config.
 ## How it decides, without annotations
 - **The tool brings the security knowledge.** It ships framework facts: the
  sources, sinks, sanitizers, and guards for common frameworks. Your code does
  not declare any of this.
 - **It looks only at your change.** It builds a graph of the changed code and
  checks it against those framework facts, scoped to the diff, not the whole repo.
 - **It can prove, not just warn.** When the app is runnable, the proof arm builds
  and runs it and demonstrates the issue by execution, so a finding is a
  reproducible fact, not a confidence score.
 ## What you control
 - **Advisory or blocking.** Advisory by default; `OUSAST_PUSH_MODE=blocking`
  turns it into a gate. Adopt in advisory mode, build trust, then block.
 - **Budget and deadline.** One budget covers the whole push; if it runs out you
  get an honest "incomplete coverage" notice, never a made-up verdict.
 - **Where proof runs.** Local sandbox, a container, or a shared cluster.
 - **Models and spend.** Keys and caps live in `.env`.
 ## Honest limits
 - **Coverage follows support.** It helps where the tool has framework facts and a
  language grammar; outside that it is weak, and third-party or vendor code is not
  analyzed.
 - **Large repositories can be slow.** On big codebases the deep analysis can
  exceed a comfortable push deadline today; that is an open engineering problem.
 - **Generalization is being measured, not asserted.** Whether it reliably catches
  real regressions and stays quiet on ordinary changes in repositories it has
  never seen is under active measurement. We consider the tool wrong if it misses
  real regressions or alarms on ordinary changes on unseen repositories, and that
  is exactly the catch-rate and false-alarm number the unseen-repo evaluation is
  producing now. Treat the advisory output accordingly until that number exists.
 ## Where this is going
 An MCP agent and skills so your editor or your coding agent gets the same check
 earlier, inline, before the push, so feedback arrives while you are still writing
 rather than at the gate. See the follow-up spec `mcp-shift-left-agent`.
@@ -0,0 +1,98 @@
 # Use case: catch, prove, fix, re-verify
 The tool closes the loop on a security regression. It finds the problem in your
 change, proves it with a reproducible check, and after the fix re-runs that same
 check to confirm the problem is gone. The proof becomes a regression test. It
 does not write the patch for you; it hands you a failing check and a repair
 direction, and your fix is confirmed when the check turns green.
 ## The loop
 1. **Catch.** On the changed code, the static arm flags a likely regression with
   a location and a repair direction.
 2. **Prove.** Where the app is runnable, the proof arm builds and runs it and
   demonstrates the issue: a check that triggers the effect on the current code.
 3. **Fix.** You, or a coding agent, write the fix against the repair direction
   and the failing check. The tool does not generate the patch.
 4. **Re-verify absence.** The same proof is re-run against the fixed code. It no
   longer triggers. That is the bug's absence demonstrated by execution, not a
   claim that it "looks fixed."
 5. **Keep it.** The proof is a regression test. Commit it and the fix stays fixed.
 ## What "re-verify absence" means, precisely
 A demonstrated finding is a differential: the proof triggers the effect on the
 vulnerable code and does not on the fixed code. Re-verifying a fix is the same
 operation run against your new revision. No effect means the specific issue the
 proof captured is gone. It does not claim the code is secure in general; it
 confirms that this proven issue no longer reproduces. That scoping is the point:
 it is honest about exactly what it checked.
 ## What it does and does not do
 - It produces a repair direction and a failing proof, not an auto-generated patch.
 - It re-verifies the fix by re-running the proof; the verifier already runs a
  demo against a given revision, so this is the existing mechanism, not a new one.
 - Families without a runnable proof (for example access control or configuration)
  get the catch and the repair direction but no execution proof, and are advisory
  only.
 ## In CI, with GitHub Actions
 `ousast pre-push . --base <rev> --head <rev> --deadline <seconds>` runs an
 explicit base-versus-head check, which is what an Action calls on a pull request.
 The example below is reference material, not an active workflow in this repo.
 ```yaml
 # .github/workflows/pre-push-security.yml  (example; adapt and enable in your repo)
 name: pre-push security
 on:
  pull_request:
 jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # base and head must both be present
      - name: Install OpenUltraSAST
        run: pipx install openultrasast   # or your pinned distribution
      - name: Check the diff
        env:
          # model keys and spend caps, if the proof arm is used, come from secrets
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          ousast pre-push . \
            --base "origin/${{ github.base_ref }}" \
            --head "${{ github.sha }}" \
            --deadline 300 \
            --mode advisory \
            --artifact "$GITHUB_WORKSPACE/pre-push.json"
      - name: Comment findings on the PR
        if: always()
        run: |
          # Placeholder: read pre-push.json and post the finding, its proof and the
          # repair direction as a PR comment. This formatter is not packaged yet
          # (see Honest status); wire your own, e.g. with gh pr comment.
          cat "$GITHUB_WORKSPACE/pre-push.json"
 ```
 The intended flow on a repository:
 - A pull request scans base to head. A demonstrated finding is posted as a PR
  comment with its proof and repair direction, the evidence a developer takes to
  a product owner to win capacity.
 - The fix pull request re-runs the check. The proof flips from failing to
  passing, which is the fix confirmed.
 - The proof is committed as a regression test so the issue cannot return
  unnoticed.
 ## Honest status
 Re-verify by execution and the `--base/--head` entry point exist today. The
 turnkey pieces around them are delivery work, not detection: the PR-comment
 formatter and the automatic landing of a proof as a committed regression test are
 not packaged yet, and the base-versus-head path inherits the open large-repo
 latency limit, so a long deadline or a cluster lane may be needed on big diffs.
 The full-repository CI scan (as opposed to a diff) is roadmap work
 (`plane-on-kubernetes`), not the pre-push diff path shown here.
@@ -228,3 +228,134 @@ pointing at your own bucket, a registry the workers can pull from, the runner im
 reachable as a Service, and the provider host allowed per task (which each task's EgressPolicy already does). The
 Model and Workspace manifests under `plane/` move unchanged; the Task templates get a new image reference; the kube
 context and `doctor`'s registry check are not configurable yet (the table above). Step by step: `docs/deployment.md`.
 ## Search executor and verifier task contract (operator verified 2026-10-05)
 There are two workers and no queue. `no free workers available` is capacity
 back-pressure: the dispatcher retries the same apply with 15–30 seconds of jitter,
 up to the workload deadline. It does not retry a sandbox execution or route to the VM
 because of this response. A shared reservation limits all AX workloads in one host
 process to two tasks; separate host processes coordinate through AX's rejection.
 Search executors build on the disk-backed `/workspace`, export a single archive, and
 are deleted before verifier repetitions start. The archive contains `checkout/`,
 `products/`, and `spec.json` with a `none` build recipe. A verifier receives only
 `VERIFY_INPUT_URL` and `RESULT_URL`; it never installs dependencies or fetches source.
 The executor's host-scoped `PREPARED_PUT_URL` carries the built output. The host checks
 its SHA-256 before passing it to fresh verifier tasks. Each side has three fresh runs.
 Verifier egress to `files.because-security.com:443` is requested but **pending**.
 Until the operator enables it, live verifier input/output is blocked. The first input
 download tolerates up to 60 seconds of delayed policy activation.
 `/` and `/tmp` consume the worker's 3 GiB RAM; `/workspace` has about 2 GiB usable disk.
 Entrypoints set `TMPDIR=/workspace/tmp`, `npm_config_cache=/workspace/.npm`,
 `MAVEN_OPTS=-Dmaven.repo.local=/workspace/.m2`, `COMPOSER_HOME=/workspace/.composer`,
 `PIP_CACHE_DIR=/workspace/.pip`, and `GRADLE_USER_HOME=/workspace/.gradle`.
 `OUSAST_SCRATCH_BYTES` overrides the default 2147483648-byte workspace guard. The guard
 includes caches and open output logs, checks running children and completed writes,
 and reports `could_not_build` / `scratch limit`. It is a monitored guard, not a hard
 filesystem quota; programs that hardcode `/tmp` still consume the worker's RAM.
 Repository clones must use HTTPS `git clone https://github.com/...git` or codeload
 archives, never `api.github.com`: tasks share one public IP. Search task inputs are
 presigned checkout archives, so these entrypoints do not clone repositories themselves.
 ## Image layers, publication and node cache budget
 The task family has one shared runtime base, `ousast-task-base`, built from the
 public AX runner v0.3.1. `base-browser` adds Chromium to that exact published base
 (by digest); engine and replay do not carry Chromium. The VM/kind `openultrasast`
 image uses the same base and Joern recipe. Replay inherits the published engine
 digest in CI, so even a cold build cannot accidentally duplicate its Joern layers.
 Java is **Temurin 21 JDK**, copied from `eclipse-temurin:21-jdk-jammy`.
 `ops/frontend-retention/install.py` explicitly requires Java 21 and invokes
 `java -cp ... dotty.tools.dotc.Main` using Joern's bundled Scala compiler.
 The shared JDK also provides `javac` for Maven/Gradle project builds.
 Curl/unzip and retention build scratch stay in a discarded Joern build stage.
 Joern stays above the base in the engine image (also used by replay and the VM
 lane); its compiler jars and retention provenance must not be blindly pruned.
 Runtime dependencies from `pyproject.toml` (core plus semantic/s3 for the VM lane)
 precede project code. Package installation uses `--no-deps --no-cache-dir`;
 its isolated packaging backend is temporary.
 The base retains upstream Python 3.12 with venv/pip. Its explicit apt package list
 is `nodejs npm node-typescript php-cli composer maven sqlite3 bubblewrap util-linux
 git ca-certificates libstdc++6 zlib1g`. Composer is the trixie apt package.
 Chromium is installed only in `base-browser`. Apt caches/lists and docs/man/info
 are cleaned; dpkg excludes new docs/man/info. Files already in inherited AX
 layers still occupy space even if deleted.
 Executor preparation supports pip, npm, Composer, Maven and Gradle builds.
 There is **no installed Gradle binary**: the executor invokes the selected project's
 `gradlew` through `/bin/sh`, including for wrappers without executable permissions.
 Gradle-wrapper distribution downloads and dependency downloads go through
 **public HTTPS from the executor**, subject to its egress policy and deadline.
 The verifier receives prepared products and performs no dependency downloads.
 Rebuild policy:
 - Dependency/toolchain changes: run **Task base image** (also triggered by changes
  to `plane/Dockerfile.base`, `pyproject.toml`, or `uv.lock`). It publishes
  `base-<short sha>` and `base-content-<input hash>` tags, plus their `-browser`
  variants, and prints immutable digest references. Content tags identify build
  inputs; they do not claim reproducible upstream apt/PyPI resolution. The lockfile
  triggers refreshes but pip installs the declared runtime constraints, not a uv
  frozen environment. Deliberate upstream refreshes use manual dispatch.
 - After both targets publish, ensure `ousast-task-base` is **public** in GHCR's
  package settings. Copy the workflow summary's JSON into `plane/task-base.digest`
  and submit that pin update for normal review. CI does not commit on your behalf.
  The initial null pins mean **unpublished**, not a usable bootstrap image.
 - A pin update or `plane/Dockerfile.*`/root Dockerfile change on main runs **Engine
  image**. For source, entrypoint or retention-installer changes, dispatch it once
  for the desired revision, or push a `v*` release tag. Source-only merges no longer
  publish images automatically. Never rebuild per task/run. All builds use scoped
  GHA caches; pin checks precede builds and require anonymous access plus identical
  base-layer ancestry for the browser variant.
 - Final package names must also be public in GHCR. Publication checks anonymous
  access after logout and fails if the package is private. Set visibility on first
  publication and rerun as needed. Deploy only the reported `image@sha256:...`
  references in the cluster profile/Task manifests, never `main` or a release tag.
  Publication does not automatically change deployed Task pins.
 For a local task build, pass `TASK_BASE_TAG` and `TASK_BASE_DIGEST` from the base
 pin; search instead takes `TASK_BROWSER_TAG` and `TASK_BROWSER_DIGEST`. Replay's
 `ENGINE_REF` defaults to its local engine stage; set it to the published engine
 reference to reuse exactly those layers. When building `base-browser` locally,
 pass `TASK_BASE_REF=<full base tag@digest>` for the same ancestry as CI.
 The operator's capacity rule is **all images in rotation, unpacked, together
 at most approximately 9 GiB**, including rollback revisions. Working builds take
 priority over minimizing an individual executor image; its previous 2.13 GB
 unpacked (~1.98 GiB) was acceptable. Retire unused Task templates and image
 revisions before rotating a large base/Joern generation. Shared layers occupy
 storage once where the runtime deduplicates them, but do not assume that turns
 a sum above 9 GiB into an acceptable rotation. Record both the sum of unpacked
 image sizes and actual unique-layer storage. Never prune images used by live tasks.
 Expected footprint (planning estimates only; no images built for this change):
 | Image | Expected unpacked size | Basis / uncertainty |
 | --- | --- | --- |
 | Shared base | about 1.3–1.9 GiB | ~454 MB inherited AX layers + ~281 MB JDK baseline + npm/Composer/Maven, language runtimes and venv/extras; apt dependency closure unmeasured |
 | Browser base | about 1.65–2.45 GiB | Shared base + roughly 350–550 MB Chromium/dependencies |
 | Search executor/verifier | about 1.7–2.5 GiB | Browser base + application; previous 2.13 GB unpacked is a baseline, not a ceiling |
 | Engine | roughly 3.5–6 GiB | Restored shared base + Joern; the supplied 2.16 GB compressed engine cannot establish its unpacked size |
 | Replay | engine + a few KiB | Same engine digest plus replay entrypoint |
 | VM/kind openultrasast | roughly 3.5–6 GiB plus benchmark assets | Same base/Joern, runtime extras shared, benchmark payload retained |
 An engine + search rotation therefore sums to about **5.2–8.5 GiB** before
 rollback images. Adding replay as another unpacked image brings the sum to about
 **8.7–14.5 GiB**; this rotation is not demonstrated to fit 9 GiB. Engine/replay
 share almost all layers, but the operator must confirm the accounting and measured
 footprint before selecting a rotation. Extra revisions and the VM image add to
 the budget if retained there.
 The previous search history included a 1.37 GB apt layer and 281 MB JDK; no
 per-package apt breakdown is available. Removing system Gradle and docs/caches
 may save space, while retained build tools and shared Python extras cost space.
 These ranges are not measured savings or a capacity guarantee. After publication,
 measure unpacked images and unique layers for the entire intended rotation, and
 verify build recipes, PHP/JavaScript retention, runner startup and Chromium before
 rollout. There is no separate <1.5 GiB executor gate.
@@ -0,0 +1,41 @@
 # syntax=docker/dockerfile:1
 # base-browser is built against the published base digest in CI; local builds
 # default to the base stage. Never independently rebuild its shared ancestry.
 ARG TASK_BASE_REF=base
 FROM eclipse-temurin:21-jdk-jammy AS jdk
 FROM ghcr.io/norandom/ax-task-runner:v0.3.1 AS base
 LABEL org.opencontainers.image.licenses="Apache-2.0" \
      org.opencontainers.image.source="https://github.com/norandom/OpenUltraSAST"
 USER root
 COPY --from=jdk /opt/java/openjdk /opt/java/openjdk
 ENV JAVA_HOME=/opt/java/openjdk
 ENV PATH="/venv/bin:/opt/java/openjdk/bin:${PATH}"
 # Use upstream /usr/local Python 3.12 (also required by frontend retention).
 # Its venv/pip and the toolchains below support every executor build recipe.
 # Gradle projects use their wrapper; no system Gradle is installed.
 RUN printf 'path-exclude=/usr/share/doc/*\npath-exclude=/usr/share/man/*\npath-exclude=/usr/share/info/*\n' \
      > /etc/dpkg/dpkg.cfg.d/01-no-docs \
 && apt-get update \
 && apt-get install -y --no-install-recommends \
      nodejs npm node-typescript php-cli composer maven sqlite3 bubblewrap util-linux git ca-certificates libstdc++6 zlib1g \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/* /usr/share/doc/* /usr/share/man/* /usr/share/info/* \
      /opt/java/openjdk/lib/src.zip /opt/java/openjdk/man /root/.cache
 # Metadata only: install runtime dependencies, including the VM lane's extras.
 # No project package or packaging backend enters this shared environment.
 COPY pyproject.toml /tmp/dependencies/pyproject.toml
 RUN python3 -c 'import pathlib,tomllib; p=tomllib.loads(pathlib.Path("/tmp/dependencies/pyproject.toml").read_text())["project"]; print("\n".join(p["dependencies"] + p["optional-dependencies"]["semantic"] + p["optional-dependencies"]["s3"]))' > /tmp/requirements.txt \
 && python3 -m venv /venv \
 && /venv/bin/pip install --no-cache-dir -r /tmp/requirements.txt \
 && rm -rf /tmp/dependencies /tmp/requirements.txt /root/.cache \
 && python3 --version && java -version && javac -version && node --version && npm --version && tsc --version \
 && php --version && composer --version && mvn --version && sqlite3 --version && bwrap --version \
 && setpriv --version && prlimit --version && nsenter --version
 FROM ${TASK_BASE_REF} AS base-browser
 RUN apt-get update \
 && apt-get install -y --no-install-recommends chromium \
 && apt-get clean \
 && rm -rf /var/lib/apt/lists/* /usr/share/doc/* /usr/share/man/* /usr/share/info/* /root/.cache \
 && chromium --version
@@ -1,23 +1,15 @@
-# Build from the repository root. AX v0.3.1 starts spec.command immediately;
+# syntax=docker/dockerfile:1
-# preserve its runner as PID 1 and put the engine command in the Task manifest.
+# Supply digests from plane/task-base.digest; deliberately no floating fallback.
-FROM eclipse-temurin:21-jre-jammy AS jre
+ARG TASK_BASE_TAG=base-unpublished
-
+ARG TASK_BASE_DIGEST
-FROM ghcr.io/norandom/ax-task-runner:v0.3.1
+ARG ENGINE_REF=engine
-LABEL org.opencontainers.image.licenses="Apache-2.0" \
+FROM ghcr.io/norandom/ousast-task-base:${TASK_BASE_TAG}@${TASK_BASE_DIGEST} AS joern-build
-      org.opencontainers.image.source="https://github.com/norandom/OpenUltraSAST"
+ENV PATH="/opt/joern-cli:${PATH}"
 USER root
 ARG JOERN_VERSION=v4.0.625
 ARG ARCHIVE=joern-cli-linux-x86_64.zip
 # The AX runner is Python 3.12 / Debian slim. Copy the Java 21 runtime from
 # Jammy (older glibc than Debian bookworm) instead of relying on distro JRE versions.
 COPY --from=jre /opt/java/openjdk /opt/java/openjdk
 ENV JAVA_HOME=/opt/java/openjdk
 ENV PATH="/venv/bin:/opt/java/openjdk/bin:/opt/joern-cli:${PATH}"
 RUN apt-get update \
- && apt-get install -y --no-install-recommends \
+ && apt-get install -y --no-install-recommends curl unzip \
      php-cli unzip curl ca-certificates libstdc++6 zlib1g \
 && rm -rf /var/lib/apt/lists/*
 RUN set -eux; \
@@ -37,16 +29,20 @@ COPY ops/frontend-retention/install.py /tmp/frontend-retention-install.py
 RUN python3 /tmp/frontend-retention-install.py /opt/joern-cli \
 && rm /tmp/frontend-retention-install.py
 FROM ghcr.io/norandom/ousast-task-base:${TASK_BASE_TAG}@${TASK_BASE_DIGEST} AS engine
 ENV PATH="/opt/joern-cli:${PATH}"
 COPY --from=joern-build /opt/joern-cli /opt/joern-cli
 WORKDIR /app
 COPY pyproject.toml README.md LICENSE ./
 COPY src ./src
 RUN --mount=type=cache,target=/root/.cache/pip \
    /venv/bin/pip install --no-deps --no-cache-dir .
 COPY benchmarks/learn/engine_task_entry.py \
     benchmarks/learn/engine_trace_worker.py \
     benchmarks/learn/engine_trace_parse.py ./benchmarks/learn/
-# Worker imports are standard-library plus engine modules. Isolate them from
+RUN /venv/bin/python -I -c 'import pathlib, runpy, sys; sys.modules.update(yaml=None, boto3=None); sys.path.insert(0, "/app/benchmarks/learn"); p = pathlib.Path("/app/benchmarks/learn/engine_trace_worker.py"); print("Worker import smoke bytes:", len(p.read_bytes())); runpy.run_path(str(p), run_name="engine_worker_import_smoke")'
-# the AX runner's Python environment and omit PyYAML, boto3 and all extras.
+# ENTRYPOINT and CMD belong to the upstream AX runner.
 RUN python3 -m venv /venv \
 && /venv/bin/pip install --no-cache-dir --no-deps . \
 && /venv/bin/python -I -c 'import pathlib, runpy, sys; sys.modules.update(yaml=None, boto3=None); sys.path.insert(0, "/app/benchmarks/learn"); p = pathlib.Path("/app/benchmarks/learn/engine_trace_worker.py"); print("Worker import smoke bytes:", len(p.read_bytes())); runpy.run_path(str(p), run_name="engine_worker_import_smoke")'
-# Do not set ENTRYPOINT or CMD: both belong to the upstream AX runner.
+FROM ${ENGINE_REF} AS replay
 COPY benchmarks/unseen/replay_entry.py ./benchmarks/unseen/replay_entry.py
 RUN /venv/bin/ousast pre-push --help > /dev/null
@@ -0,0 +1,19 @@
 # syntax=docker/dockerfile:1
 # Supply digests from plane/task-base.digest; deliberately no floating fallback.
 ARG TASK_BROWSER_TAG=base-unpublished-browser
 ARG TASK_BROWSER_DIGEST
 FROM ghcr.io/norandom/ousast-task-base:${TASK_BROWSER_TAG}@${TASK_BROWSER_DIGEST}
 USER root
 # Dedicated identity for artefacts, apps and Chromium; the verifier keeps root.
 RUN groupadd --gid 10001 search \
 && useradd --create-home --uid 10001 --gid 10001 search
 # Upstream's public CPython signing fingerprint trips the credential guard.
 ENV GPG_KEY=
 WORKDIR /app
 COPY pyproject.toml README.md LICENSE ./
 COPY src ./src
 RUN --mount=type=cache,target=/root/.cache/pip \
    /venv/bin/pip install --no-deps --no-cache-dir .
 # Entrypoints and verifier-owned recipes/oracles are included in src.
 USER root
 # Preserve the AX runner ENTRYPOINT and CMD.
@@ -0,0 +1,6 @@
 {
  "base": "ghcr.io/norandom/ousast-task-base:base-b696c08@sha256:0f374138fcb49fef41609d323cc80b6c2324b1e798d3a2aee5c8038b8c7ac3aa",
  "base-browser": "ghcr.io/norandom/ousast-task-base:base-b696c08-browser@sha256:09323d893d1b8a213dfa1aad6ba587566bba708713bc050d456466cf5a2421d8",
  "content": "bb23a92d2de9ff7e6e75d4b16752ec95a7d3962ee4fa06639a18a0514f639d2a",
  "note": "Built by task-base-image run 37358368253 from main b696c08; rebuild only when plane/Dockerfile.base, pyproject.toml or uv.lock change."
 }
@@ -13,7 +13,6 @@ requires-python = ">=3.11"
 dependencies = ["pyyaml>=6.0"]
 [project.optional-dependencies]
 train = ["numpy>=1.26,<3", "scikit-learn>=1.4,<2"]
 # The documentation site (mkdocs.yml, docs/). Mermaid renders client-side through Material's superfences fence.
 docs = [
    "mkdocs>=1.6,<2",
@@ -69,7 +68,7 @@ warn_return_any = true
 warn_unused_configs = true
 [[tool.mypy.overrides]]
-module = ["tree_sitter", "sklearn.*", "numpy"]
+module = "tree_sitter"
 ignore_missing_imports = true
 # boto3 is an optional extra without inline types, absent in the type-check environment (plane/memory.py imports
@@ -15,17 +15,6 @@ from typing import Any
 def add_commands(learn_sub: Any) -> None:
    train = learn_sub.add_parser("train", help="offline fitted classifiers using cached embeddings")
    train_sub = train.add_subparsers(dest="train_command", required=True)
    for command in ("fit-eval", "score"):
        parser = train_sub.add_parser(command)
        parser.add_argument("--memory", help="local memory store (or OUSAST_MEMORY)")
        parser.add_argument("--profile", choices=("static", "plane"), default="static")
        parser.add_argument("--units", type=Path, default=Path("plane/experiments/exp-005-graph-slice.units.jsonl"))
        parser.add_argument("--record", type=Path, default=Path("benchmarks/measurements/2026-10-04-trained-classifier/record.json"))
        parser.add_argument("--resamples", type=int, default=2000)
        if command == "score":
            parser.add_argument("--out", type=Path, required=True, help="per-example out-of-fold JSONL")
    memory = learn_sub.add_parser("memory", help="the decision engine's local memory of labelled examples")
    memory_sub = memory.add_subparsers(dest="memory_command", required=True)
    build = memory_sub.add_parser("build", help="label + feature record + excerpt -> example rows (no model)")
@@ -108,10 +97,6 @@ def add_commands(learn_sub: Any) -> None:
 def run(args: argparse.Namespace) -> int:
    if args.learn_command == "train":
        from .trained import run as run_train
        return run_train(args)
    if args.learn_command == "audit-leaks":
        return _audit_leaks(args)
    if args.learn_command == "memory" and args.memory_command == "build":
@@ -1,379 +0,0 @@
 """Offline, nested repository-held-out classifiers. No clients and no input profiles.
 The frozen experiment units define outer boundaries. Inner screens, encoders,
 scalers and hyperparameters see only inner training repositories. Scores are
 experimental development evidence, not permission to BLOCK a push.
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import math
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 from .embeddings import DEFAULT_DIMENSIONS, EmbeddingCache
 from .evaluate import Prediction, family_floor, pooled_block_gate, pooled_threshold, wilson_lower
 from .examples import Example, load_examples
 from .experiments import ArmUnit, Metric, Unit, arm_units, auc, load_outcomes, paired_bootstrap, read_units, within_pair_auc
 from .folds import outer_folds
 from .leaks import THRESHOLD, Pair, separation, signals
 from .schema import FEATURES, STATES
 MODELS = ("logistic", "hist_gradient_boosting")
 RECORD = Path("benchmarks/measurements/2026-10-04-trained-classifier/record.json")
@dataclass(frozen=True)
 class Scored:
    unit: Unit
    model: str
    s: float
    verdict: str = "scored"
    point: str | None = None
    def arm(self) -> ArmUnit:
        u = self.unit
        return ArmUnit(u.unit, u.group, u.family, u.label, u.pair, self.s, self.verdict, None, None)
    def prediction(self) -> Prediction:
        u = self.unit
        return Prediction(u.fold, u.family, u.group, u.label, self.s, self.verdict, p=self.s, pair=u.pair, point=self.point)
 def screen(examples: Sequence[Example], pairs: Mapping[str, str]) -> list[str]:
    """Reuse the audit's metric, including instrument states and family strata.
    No minimum pair floor: even a small training split must drop a perfect leak.
    Removing a feature also removes its missingness indicator.
    """
    sides: dict[tuple[str, str, str], dict[int, list[Example]]] = {}
    for e in examples:
        if pairs.get(e.id):
            sides.setdefault((e.group, e.family, pairs[e.id]), {}).setdefault(e.label, []).append(e)
    paired = []
    for (_, family, _), members in sides.items():
        if len(members.get(0, [])) == len(members.get(1, [])) == 1:
            records = [{"x": members[label][0].x, "instruments": members[label][0].instruments} for label in (1, 0)]
            paired.append(Pair(family, records[0], records[1]))
    scopes = [paired] + [[p for p in paired if p.family == f] for f in sorted({p.family for p in paired})]
    return sorted(s.name for s in signals("plane") if any(separation(s, scope)["separation"] >= THRESHOLD for scope in scopes if scope))
 def _deps() -> tuple[Any, Any, Any, Any]:
    try:
        import numpy as np
        from sklearn.ensemble import HistGradientBoostingClassifier
        from sklearn.linear_model import LogisticRegression
        from sklearn.preprocessing import StandardScaler
    except ImportError as exc:
        raise RuntimeError("learn train requires the optional train extra: uv sync --extra train") from exc
    return np, HistGradientBoostingClassifier, LogisticRegression, StandardScaler
 class Matrix:
    """Fixed schema vocabularies, training-only means/scales; null has its own bit."""
    def __init__(self, examples: Sequence[Example], vectors: Mapping[str, Sequence[float]], dropped: Sequence[str], pooled: bool):
        np, _, _, scaler = _deps()
        self.specs = [s for s in FEATURES if s.name not in dropped]
        self.states = sorted({s.instrument for s in FEATURES} - {n.removeprefix("state.") for n in dropped if n.startswith("state.")})
        self.families = sorted({e.family for e in examples}) if pooled else []
        self.scaler = scaler()
        raw = self.raw(examples, vectors)
        self.scaler.fit(np.asarray(raw, dtype=float))
    def raw(self, examples: Sequence[Example], vectors: Mapping[str, Sequence[float]]) -> list[list[float]]:
        rows = []
        for e in examples:
            vector = vectors.get(e.excerpt_sha)
            if vector is None or len(vector) != DEFAULT_DIMENSIONS or not all(math.isfinite(v) for v in vector):
                raise ValueError("missing, nonfinite or wrong-dimension stored embedding; no embedding calls are permitted")
            row = list(vector)
            for s in self.specs:
                value = e.x.get(s.name) if e.instruments.get(s.instrument, {}).get("state") == "ran" else None
                row.append(float(value is None))
                if s.type == "enum":
                    row.extend(float(value == v) for v in s.vocabulary)
                else:
                    row.append(float(value) if value is not None else 0.0)
            for instrument in self.states:
                state = e.instruments.get(instrument, {}).get("state")
                row.extend(float(state == v) for v in STATES)
                row.append(float(state is None))
            row.extend(float(e.family == f) for f in self.families)
            rows.append(row)
        return rows
    def transform(self, examples: Sequence[Example], vectors: Mapping[str, Sequence[float]]) -> Any:
        return self.scaler.transform(self.raw(examples, vectors))
 def _fit(
    train: Sequence[Example], vectors: Mapping[str, Sequence[float]], pairs: Mapping[str, str], model: str, parameter: float, pooled: bool
 ) -> tuple[Matrix, Any, list[str]]:
    np, tree, logistic, _ = _deps()
    dropped = screen(train, pairs)
    matrix = Matrix(train, vectors, dropped, pooled)
    x = matrix.transform(train, vectors)
    y = np.asarray([e.label for e in train])
    if len(set(y)) != 2:
        raise ValueError("training split needs both labels")
    if model == "logistic":
        estimator = logistic(C=parameter, class_weight="balanced", solver="liblinear", max_iter=2000, random_state=0)
        estimator.fit(x, y)
    elif model == "hist_gradient_boosting":
        # Disable sklearn's row-random early stopping: it would split repositories.
        estimator = tree(l2_regularization=parameter, max_iter=100, max_leaf_nodes=15, early_stopping=False, random_state=0)
        weights = np.asarray([len(y) / (2 * int(sum(y == label))) for label in y])
        estimator.fit(x, y, sample_weight=weights)
    else:
        raise ValueError("unknown trained model")
    return matrix, estimator, dropped
 def fit_fold(
    examples: Sequence[Example],
    units: Sequence[Unit],
    vectors: Mapping[str, Sequence[float]],
    fold: str,
    model: str,
    scope: str,
    *,
    pairs: Mapping[str, str] | None = None,
 ) -> tuple[list[Scored], dict[str, Any]]:
    """Fit one outer boundary, tuning on three fresh repository-grouped inner folds."""
    by_id = {e.id: e for e in examples}
    held_units = [u for u in units if u.fold == fold]
    held_groups = {u.group for u in held_units}
    train = [e for e in examples if e.group not in held_groups and (scope == "pooled" or e.family == scope)]
    held_units = [u for u in held_units if scope == "pooled" or u.family == scope]
    counts = [len({e.group for e in train if e.label == label}) for label in (0, 1)]
    if not held_units or min(counts, default=0) < (2 if scope == "pooled" else 20):
        return [], {"status": "insufficient data", "training_repositories_by_label": counts}
    pair_map = pairs if pairs is not None else {u.unit: u.pair for u in units}
    candidates = (0.01, 0.1, 1.0) if model == "logistic" else (0.0, 1.0, 10.0)
    inner = outer_folds(train, k=3, seed=0)
    trials = []
    inner_scores: dict[float, list[Scored]] = {}
    for parameter in candidates:
        scored: list[Scored] = []
        for boundary in inner:
            subtrain = [e for e in train if e.group not in boundary.eval_groups]
            valid = [e for e in train if e.group in boundary.eval_groups]
            if not valid or len({e.label for e in subtrain}) < 2:
                continue
            matrix, estimator, _ = _fit(subtrain, vectors, pair_map, model, parameter, scope == "pooled")
            ps = estimator.predict_proba(matrix.transform(valid, vectors))[:, 1]
            scored.extend(
                Scored(Unit(e.id, e.group, e.family, e.label, boundary.name, pair_map.get(e.id, "")), model, float(p))
                for e, p in zip(valid, ps, strict=True)
            )
        inner_scores[parameter] = scored
        value = auc([r.arm() for r in scored])
        trials.append({"parameter": parameter, "inner_pooled_auc": value})
    usable = [t for t in trials if t["inner_pooled_auc"] is not None]
    if not usable:
        raise ValueError("no evaluable inner repository folds")
    best = max(usable, key=lambda t: float(t["inner_pooled_auc"] or 0))
    parameter = float(best["parameter"] or 0)
    matrix, estimator, dropped = _fit(train, vectors, pair_map, model, parameter, scope == "pooled")
    scores = estimator.predict_proba(matrix.transform([by_id[u.unit] for u in held_units], vectors))[:, 1]
    # Digest is an isolation-test witness, never a serialization of population identities.
    witness = matrix.transform(train, vectors).tobytes() + matrix.scaler.mean_.tobytes() + matrix.scaler.scale_.tobytes()
    witness += estimator.predict_proba(matrix.transform(train, vectors)).tobytes()
    record = {
        "status": "ok",
        "training_examples": len(train),
        "training_repositories_by_label": counts,
        "dropped_signals": dropped,
        "parameter": parameter,
        "inner_trials": trials,
        "fit_digest": hashlib.sha256(witness).hexdigest(),
    }
    held_rows = [Scored(u, f"{model}:{scope}", float(s)) for u, s in zip(held_units, scores, strict=True)]
    # Inner predictions were fitted without any outer-held repository. Rename
    # their folds to avoid collision with the frozen outer fold name.
    inner_preds = [replace(r.prediction(), fold="inner:" + r.unit.fold) for r in inner_scores[parameter]]
    decided, gates = pooled_block_gate(inner_preds + [r.prediction() for r in held_rows], eligible=lambda r: bool(r.pair))
    record["pooled_gate"] = gates[fold]
    held_decisions = decided[len(inner_preds) :]
    return [replace(r, point=p.point) for r, p in zip(held_rows, held_decisions, strict=True)], record
 def metrics(rows: Sequence[Scored]) -> dict[str, Any]:
    arms = [r.arm() for r in rows]
    ranked = sorted(rows, key=lambda r: (-r.s, r.unit.unit))
    threshold = pooled_threshold([r.prediction() for r in rows])
    flagged = [r for r in rows if threshold is not None and r.s >= threshold and r.verdict != "unsure"]
    held_flags = [r for r in rows if r.point == "BLOCK"]
    return {
        "held_out_block_flags": len(held_flags),
        "held_out_block_wilson_lower": wilson_lower(sum(r.unit.label for r in held_flags), len(held_flags)),
        "family_floor": family_floor([r.prediction() for r in rows]),
        "examples": len(rows),
        "repositories": len({r.unit.group for r in rows}),
        "within_pair_auc": within_pair_auc(arms),
        "pooled_auc": auc(arms),
        "top_k_precision": {str(k): sum(r.unit.label for r in ranked[:k]) / k if len(rows) >= k else None for k in (10, 30, 73)},
        "wilson_threshold": threshold,
        "wilson_flagged": len(flagged),
        "wilson_lower": wilson_lower(sum(r.unit.label for r in flagged), len(flagged)),
        "threshold_check": "descriptive held-out capacity only; not an adopted operating point",
    }
 def write_scores(path: Path, rows: Sequence[Scored]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        "".join(
            json.dumps({**r.unit.as_dict(), "model": r.model, "s": r.s, "out_of_fold": True}, sort_keys=True, allow_nan=False) + "\n"
            for r in rows
        ),
        encoding="utf-8",
    )
 def fit_eval(
    examples: Sequence[Example],
    units: Sequence[Unit],
    vectors: Mapping[str, Sequence[float]],
    llm: Mapping[str, ArmUnit],
    *,
    pairs: Mapping[str, str] | None = None,
    resamples: int = 2000,
 ) -> tuple[dict[str, Any], list[Scored]]:
    if not examples or not units:
        raise ValueError("empty input: no evaluation is possible")
    ids = {e.id: e for e in examples}
    if len(ids) != len(examples) or len({u.unit for u in units}) != len(units):
        raise ValueError("duplicate example or unit IDs")
    groups: dict[str, str] = {}
    for u in units:
        e, a = ids.get(u.unit), llm.get(u.unit)
        if e is None or a is None or a.s is None or not math.isfinite(a.s):
            raise ValueError("every frozen unit needs an example and a finite exp-005 arm-A score")
        if (e.group, e.family, e.label) != (u.group, u.family, u.label) or (a.group, a.family, a.label, a.pair) != (
            u.group,
            u.family,
            u.label,
            u.pair,
        ):
            raise ValueError("unit/example/LLM metadata mismatch")
        if not u.fold or groups.setdefault(u.group, u.fold) != u.fold:
            raise ValueError("repository crosses outer folds")
    reference = [Scored(u, "exp-005:A", float(llm[u.unit].s or 0), llm[u.unit].verdict) for u in units]
    llm_decided, llm_gates = pooled_block_gate([r.prediction() for r in reference], eligible=lambda r: bool(r.pair))
    reference = [replace(r, point=p.point) for r, p in zip(reference, llm_decided, strict=True)]
    report: dict[str, Any] = {
        "status": "evaluated",
        "counts": {"memory": len(examples), "units": len(units)},
        "llm": {"overall": metrics(reference), "folds": {}, "pooled_gates": llm_gates},
        "models": {},
    }
    scores = []
    for fold in sorted({u.fold for u in units}):
        report["llm"]["folds"][fold] = metrics([r for r in reference if r.unit.fold == fold])
    for model in MODELS:
        for scope in ["pooled", *sorted({u.family for u in units})]:
            name = f"{model}:{scope}"
            rows: list[Scored] = []
            folds = {}
            for fold in sorted({u.fold for u in units}):
                held, info = fit_fold(examples, units, vectors, fold, model, scope, pairs=pairs)
                rows.extend(held)
                folds[fold] = {**info, "metrics": metrics(held)}
            matched = [(llm[r.unit.unit], r.arm()) for r in rows]
            baseline = [r for r in reference if r.unit.unit in {s.unit.unit for s in rows}]
            report["models"][name] = {
                "folds": folds,
                "overall": metrics(rows),
                "llm_same_units": metrics(baseline),
                "trained_minus_llm": paired_bootstrap(matched, Metric("within_pair_auc"), resamples=resamples, seed=0).as_dict(),
            }
            scores.extend(rows)
    return report, scores
 def run(args: argparse.Namespace) -> int:
    """Train from cached embeddings in the configured store; never call an embedding service."""
    import sys
    from ..config import load_dotenv
    from ..plane.memory import open_store
    try:
        load_dotenv()
        _deps()
        store = open_store(args.memory)
        examples = load_examples(store, args.profile)
        units = read_units(args.units)
        print(f"read units: {args.units.stat().st_size} bytes; {len(units)} units; {len(examples)} examples", file=sys.stderr)
        cache = EmbeddingCache(store)
        vectors = {}
        missing = set()
        exclusions = {
            family: {"excluded_missing_embedding": 0, "excluded_paired_units": 0, "excluded_missing_partner": 0}
            for family in sorted({e.family for e in examples} | {u.family for u in units})
        }
        for e in examples:
            vector = cache.get(e.excerpt_sha)
            if vector is None:
                missing.add(e.id)
                exclusions[e.family]["excluded_missing_embedding"] += 1
            else:
                vectors[e.excerpt_sha] = vector
        broken_pairs = {(u.group, u.family, u.pair) for u in units if u.unit in missing and u.pair}
        for u in units:
            if (u.group, u.family, u.pair) in broken_pairs:
                exclusions[u.family]["excluded_paired_units"] += 1
                if u.unit not in missing:
                    exclusions[u.family]["excluded_missing_partner"] += 1
        for family, counts in exclusions.items():
            print(f"{family}: " + "; ".join(f"{key}={value}" for key, value in counts.items()), file=sys.stderr)
        if len(missing) * 10 > len(examples):
            message = f"missing cached embeddings exclude {len(missing)}/{len(examples)} examples (>10%); training refused"
            args.record.parent.mkdir(parents=True, exist_ok=True)
            args.record.write_text(
                json.dumps({"status": "failed", "error": message, "exclusions": exclusions}, indent=2, sort_keys=True) + "\n",
                encoding="utf-8",
            )
            raise ValueError(message)
        examples = [e for e in examples if e.id not in missing]
        # Keep cached partners for pooled metrics, but remove their paired eligibility in both arms.
        units = [replace(u, pair="") if (u.group, u.family, u.pair) in broken_pairs else u for u in units if u.unit not in missing]
        # Same candidate identity used by experiments.freeze_units, without regenerating frozen outer folds.
        pairs = {}
        pair_labels: dict[str, list[int]] = {}
        for record in store.rows(kind="example", where={"profile": args.profile}):
            row = record.row
            candidate = str(row.get("candidate") or "")
            if candidate:
                identity = "\x00".join(str(row.get(k, "")) for k in ("repo", "candidate", "family"))
                pair = hashlib.sha256(identity.encode()).hexdigest()[:16]
                pairs[str(row["id"])] = pair
                pair_labels.setdefault(pair, []).append(int(row["label"]))
        pairs = {uid: pair for uid, pair in pairs.items() if sorted(pair_labels[pair]) == [0, 1]}
        pairs.update({u.unit: u.pair for u in units})
        llm = arm_units(load_outcomes(store, "exp-005-graph-slice"), "A")
        llm = {uid: replace(a, pair="") if (a.group, a.family, a.pair) in broken_pairs else a for uid, a in llm.items()}
        report, scores = fit_eval(examples, units, vectors, llm, pairs=pairs, resamples=args.resamples)
        report["exclusions"] = exclusions
        report["units_sha256"] = hashlib.sha256(args.units.read_bytes()).hexdigest()
        args.record.parent.mkdir(parents=True, exist_ok=True)
        args.record.write_text(json.dumps(report, indent=2, sort_keys=True, allow_nan=False) + "\n", encoding="utf-8")
        if args.train_command == "score":
            write_scores(args.out, scores)
        print("model\twithin-pair AUC\tpooled AUC\ttop-10\ttop-30\ttop-73")
        table = {"exp-005:A": report["llm"], **report["models"]}
        for name, result in table.items():
            m = result["overall"]
            print("\t".join(map(str, [name, m["within_pair_auc"], m["pooled_auc"], *m["top_k_precision"].values()])))
        return 0
    except (ValueError, RuntimeError, OSError) as exc:
        print(f"learn train: {exc}", file=sys.stderr)
        return 2
@@ -83,6 +83,10 @@ SPEC_OWNED = {
 # Reachable modules that stand alone: their own CLI subcommand or external protocol, off the scan path.
 STANDALONE = {
    "search.demo_replay": "benchmarks standalone: no-model stored demo replay; python -m benchmarks.search.demo_replay",
    "search.coordinator": (
        "search-with-proof Req 1/2/4: injected search executor and offline board checkpoint inspector; agent worker pending"
    ),
    "push_scoring": "pre-push-safety-net task 1.3: frozen-profile diagnostic outcome scorer; python -m openultrasast.push_scoring",
    "push_inputs": "pre-push-safety-net task 1.2: offline input provenance validator; python -m openultrasast.push_inputs",
    "mcp": "narrow MCP server over stdio; its own `ousast mcp` entry point and OpenCode integration",
@@ -341,19 +341,38 @@ def _scan_repository_impl(
            if limits.order_by_evidence
            else ordered_regions[: limits.max_regions]
        )
        changed_scope = _changed_files(change_context) if change_context is not None else None
        evidence_deadline: float | None = None
        evidence_portion = EVIDENCE_PORTION
        if changed_scope is not None and execution_budget is not None:
            # Change-scoped evidence pass (see EVIDENCE_BUDGET_FRACTION): tier the changed regions first and stop
            # once the pass has taken its share of the remaining budget, so the flow queries get the rest. A flow
            # into a changed region from unchanged code is still traced -- the CPG is whole-repo and every changed
            # region is tiered; only the unchanged tail, tiered while the sub-budget lasts, may be cut (recorded).
            changed_set = set(changed_scope)
            evidence_candidates = sorted(evidence_candidates, key=lambda region: region.path not in changed_set)
            now = time.monotonic()
            evidence_deadline = now + EVIDENCE_BUDGET_FRACTION * max(0.0, execution_budget.deadline_monotonic - now)
            evidence_portion = BOUNDED_EVIDENCE_PORTION
        tier_started = time.monotonic()
-        evidence_by_pair, failed = _evidence_pass(
+        evidence_by_pair, failed, bounded = _evidence_pass(
            cpg,
            _collect(evidence_candidates, execution_budget=execution_budget),
            hooks,
            degradations=degradations,
            context_rows=context_rows if change_context is not None else None,
-            context_files=_changed_files(change_context) if change_context is not None else None,
+            context_files=changed_scope,
            unit=unit,
            deadline=evidence_deadline,
            portion=evidence_portion,
        )
        per_kind["evidence"] = round(time.monotonic() - tier_started, 2)
        if failed:
            degradations.append({"stage": "model", "reason": "query_failed", "kind": "evidence", "requests": failed})
        if bounded:
            # The budget, not a failure, left these pairs untiered. Named so a change-scoped scan's silence over
            # the unchanged tail is legible rather than read as a clean bill of health for the whole repository.
            degradations.append({"stage": "model", "reason": "evidence_pass_bounded", "tiered_pairs": len(evidence_by_pair), "skipped_requests": bounded})
        tiers = [(path, function, family, evidence.tier) for (path, function, family), evidence in evidence_by_pair.items()]
        if limits.order_by_evidence and evidence_by_pair:
            ordered_regions = order_by_evidence(ordered_regions, evidence_by_pair)
@@ -1248,20 +1267,68 @@ def _collect(
 EVIDENCE_PORTION = 4000  # requests per evidence invocation; roughly ten seconds of work behind one JVM start
 # A push scan's whole cost is the evidence-tier pass -- measured 238 s of a 291 s run, 99.9 % of everything that
 # is not the CPG build or the flow queries -- because it tiers every region of the repository to rank them, and
 # a cold large CPG answers each pair far slower than the design's few milliseconds. When the push carries a change
 # context the pass is therefore spent CHANGE-FIRST (the regions the push touched are tiered before the rest) and
 # BOUNDED: it stops once it has taken this fraction of the remaining budget, leaving the rest for the flow queries
 # that actually find the defect. The CPG is still whole-repo, so a flow INTO a changed region from unchanged code is
 # traced as before; only the long tail of unchanged regions goes untiered, and that is recorded. A smaller portion
 # makes the stop granular -- 4000 is one atomic batch that could never stop before the deadline.
 EVIDENCE_BUDGET_FRACTION = 0.5
 # The deadline is only checked BETWEEN portions and a run_batch cannot be interrupted, so a portion's duration is
 # the overshoot. A cold large CPG answered a changed-region evidenceOnly pair in SECONDS (measured ~3-5 s under
 # load, 50-100x the warm few ms), so even a fixed 32-pair portion overshot a ~115 s sub-budget by a whole ~150 s
 # batch and left nothing for the flow queries. So the bounded pass sizes ADAPTIVELY: a small probe first, then each
 # next chunk sized from the measured per-pair rate to fit the budget left -- overshoot is one probe, at any rate.
 EVIDENCE_PROBE = 4  # the opening chunk, before the per-pair rate is known
 # The cap on any one chunk under bounding: the adaptive rate estimate assumes a uniform per-pair cost, so a cap
 # keeps a chunk from overshooting badly if the regions after the probe turn out slower than it did.
 BOUNDED_EVIDENCE_PORTION = 16
 def _portioned_evidence(cpg: Any, requests: Mapping[str, Mapping[str, object]]) -> dict[str, Any] | None:
    """The evidence pass in portions, merged. ``None`` only when no portion answered.
-    Typed as the batch returns it -- rows are the engine's mappings, and the caller reads them as such.
+def _portioned_evidence(
    cpg: Any, requests: Mapping[str, Mapping[str, object]], *, deadline: float | None = None, portion: int = EVIDENCE_PORTION
 ) -> tuple[dict[str, Any] | None, int]:
    """The evidence pass in portions, merged, with the number of requests ATTEMPTED.
    ``None`` only when no attempted portion answered. The attempted count lets the caller tell a bounded skip
    (budget ran out) from a query failure (the engine was asked and did not answer).
    Without a ``deadline`` the pass runs the whole population in fixed ``portion`` chunks, as before. WITH one (a
    monotonic time), it is bounded ADAPTIVELY: a small probe chunk first, then each next chunk sized from the
    measured per-pair rate to fit the budget that is left, capped at ``portion``. A run_batch cannot be
    interrupted, so sizing to the remaining budget -- rather than a fixed count -- keeps the overshoot to one probe
    whether a pair costs milliseconds or seconds. Typed as the batch returns it.
    """
    ids = list(requests)
-    if len(ids) <= EVIDENCE_PORTION:
+    if deadline is None and len(ids) <= portion:
        answered: dict[str, Any] | None = cpg.run_batch("taint", requests)
-        return answered
+        # Attempted counts what was SENT, not what came back: a None here is the engine failing on requests it
        # was asked, which is a failure to record -- never a budget skip (that is only the deadline-bounded tail).
        return answered, len(ids)
    merged: dict[str, Any] = {}
    answered_any = False
-    for start in range(0, len(ids), EVIDENCE_PORTION):
+    attempted = 0
-        part = cpg.run_batch("taint", {rid: requests[rid] for rid in ids[start : start + EVIDENCE_PORTION]})
+    start = 0
    per_pair = 0.0
    while start < len(ids):
        now = time.monotonic()
        if deadline is not None and start > 0 and now >= deadline:
            break
        if deadline is None:
            step = portion
        elif per_pair <= 0.0:
            step = min(EVIDENCE_PROBE, portion)  # probe first, before the rate is known
        else:
            step = max(1, min(portion, int((deadline - now) / per_pair)))  # fit the budget that is left
        chunk = ids[start : start + step]
        batch_started = time.monotonic()
        attempted += len(chunk)
        part = cpg.run_batch("taint", {rid: requests[rid] for rid in chunk})
        if deadline is not None and chunk:
            per_pair = (time.monotonic() - batch_started) / len(chunk)
        start += len(chunk)
        if part is None:
            continue
        answered_any = True
@@ -1269,7 +1336,7 @@ def _portioned_evidence(cpg: Any, requests: Mapping[str, Mapping[str, object]])
        if census is not None and "__census__" not in merged:
            merged["__census__"] = census
        merged.update(part)
-    return merged if answered_any else None
+    return (merged if answered_any else None), attempted
 def _evidence_pass(
@@ -1281,15 +1348,18 @@ def _evidence_pass(
    context_rows: dict[QuestionIdentity, list[Mapping[str, object]]] | None = None,
    context_files: tuple[str, ...] | None = None,
    unit: str = "repository",
-) -> tuple[dict[tuple[str, str, str], Evidence], int]:
+    deadline: float | None = None,
    portion: int = EVIDENCE_PORTION,
 ) -> tuple[dict[tuple[str, str, str], Evidence], int, int]:
    """The evidence vector of every taint pair in ``work``, keyed by (path, function, family).
-    Returns the vectors and the number of requests the engine did not answer (0 when it answered), so a
+    Returns the vectors, the number of ATTEMPTED requests the engine did not answer (a genuine failure), and
-    failed pass is recorded rather than read as "no evidence anywhere".
+    the number left untiered because ``deadline`` bounded the pass (a budget skip, not a failure) -- so each is
    recorded as what it is rather than both read as "no evidence anywhere".
    """
    grouped_taint = _grouped(list(work), hook_callbacks=hooks).get("taint", {})
    if not grouped_taint:
-        return {}, 0
+        return {}, 0, 0
    # With change context, the engine itemises locations only in the files the change touched and summarises
    # the rest, because those are the only locations `affected_context` can attach. `None` means the change's
    # files cannot be named safely, and then every location is itemised as before.
@@ -1302,9 +1372,9 @@ def _evidence_pass(
    # batch: a 22,125-request evidence pass on a plugin's push transaction exceeded its ceiling under load and
    # cost the whole scan. Streaming keeps what finished when a portion is killed; portioning keeps a single
    # kill from being the whole pass.
-    answered = _portioned_evidence(cpg, requests)
+    answered, attempted = _portioned_evidence(cpg, requests, deadline=deadline, portion=portion)
    if answered is None:
-        return {}, len(requests)
+        return {}, attempted, len(requests) - attempted
    census = answered.pop("__census__", None)
    if census and degradations is not None:
        entry = census[0] if isinstance(census[0], Mapping) else {}
@@ -1357,8 +1427,8 @@ def _evidence_pass(
        if len(languages) > 1:
            out.pop(key, None)
    if context_rows is not None:
-        _context_pass(cpg, work, context_rows, unit=unit)
+        _context_pass(cpg, work, context_rows, unit=unit, context_files=context_files)
-    return out, len(requests) - len(out)
+    return out, max(0, attempted - len(out)), len(requests) - attempted
 def _context_pass(
@@ -1367,6 +1437,7 @@ def _context_pass(
    context_rows: dict[QuestionIdentity, list[Mapping[str, object]]],
    *,
    unit: str,
    context_files: tuple[str, ...] | None = None,
 ) -> None:
    """Collect change context for the families the evidence pass does not ask.
@@ -1377,7 +1448,16 @@ def _context_pass(
    Each family's own query supplies its own scope. A failure here leaves the family's context
    absent, which the caller already treats as unresolved, so it degrades exactly as before.
    ``context_files`` scopes the pass to the regions a change TOUCHED. This pass is change context, so on a push
    only the changed regions need it -- and over a whole repository it is otherwise as costly as the tier pass
    (measured ~200 s on one push, every bit of it unchanged-region context nothing would consult). A changed
    region's own dominance/config context is what `affected_context` reads to establish what the change reaches;
    the unchanged tail is left to the same `context_projection_unavailable` it would hit under a spent budget.
    """
    if context_files is not None:
        allowed = set(context_files)
        work = [item for item in work if item[1].path in allowed]
    grouped = _grouped(list(work))
    by_rid = {rid: (region, spec) for rid, region, spec in work}
    for kind in ("dominance", "config"):
@@ -10,6 +10,7 @@ failure is `AccountError` (the task is `failed` and the run starts nothing furth
 from __future__ import annotations
 from collections.abc import Mapping
 from decimal import Decimal
 from typing import Any, Protocol
 from ..model.endpoint import Prices
@@ -22,8 +23,9 @@ _USAGE_FIELDS = ("prompt_tokens", "prompt_cache_hit_tokens", "completion_tokens"
 class BudgetExhausted(RuntimeError):
    """Raised before a call would start once the usd or calls ceiling is reached."""
-    def __init__(self, message: str, *, usd: float | None, calls: int) -> None:
+    def __init__(self, message: str, *, usd: float | None, calls: int, end_detail: str = "spend") -> None:
-        super().__init__(message)
+        super().__init__(f"{end_detail}: {message}")
        self.end_detail = end_detail
        self.usd = usd
        self.calls = calls
@@ -251,5 +253,70 @@ class MeteredEmbeddingClient:
 __all__ = [
    "AccountError", "BudgetExhausted", "EmbeddingClient", "MeteredClient", "MeteredEmbeddingClient", "UnmeteredUsage", "cost_of",
-    "is_account_error", "prices_from",
+    "is_account_error", "prices_from", "SpendBudget", "SpendReservation",
 ]  # fmt: skip
 class SpendBudget:
    """Thread-safe pre-call admission. Share one instance across concurrent callers.
    A caller must supply a genuine upper bound, including all tool-loop calls.
    Reservations remain charged until settled or explicitly released on failure.
    Existing MeteredClient callers retain their historical post-call metering.
    """
    def __init__(self, cap: float, *, spent: float = 0.0) -> None:
        from threading import Lock
        self._lock = Lock()
        self._cap = self._amount(cap)
        self._spent = self._amount(spent)
        if self._spent > self._cap:
            raise ValueError("spend exceeds cap")
        self._reserved = Decimal(0)
    @staticmethod
    def _amount(value: float) -> Decimal:
        amount = Decimal(str(value))
        if not amount.is_finite() or amount < 0:
            raise ValueError("cost must be finite and nonnegative")
        return amount
    @property
    def spent(self) -> float:
        with self._lock:
            return float(self._spent)
    @property
    def reserved(self) -> float:
        with self._lock:
            return float(self._reserved)
    def reserve(self, max_cost: float) -> SpendReservation:
        amount = self._amount(max_cost)
        with self._lock:
            if self._spent + self._reserved + amount > self._cap:
                raise BudgetExhausted("spend reservation exceeds cap", usd=float(self._spent), calls=0)
            self._reserved += amount
            return SpendReservation(self, amount)
 class SpendReservation:
    def __init__(self, budget: SpendBudget, amount: Decimal) -> None:
        self._budget, self._amount, self._active = budget, amount, True
    def settle(self, actual: float) -> None:
        amount = self._budget._amount(actual)
        with self._budget._lock:
            if not self._active:
                raise ValueError("reservation already closed")
            if amount > self._amount:
                # Retain the reservation: a broken upper bound must fail closed.
                raise ValueError("actual cost exceeds reservation")
            self._budget._reserved -= self._amount
            self._budget._spent += amount
            self._active = False
    def release(self) -> None:
        self.settle(0)
@@ -615,9 +615,12 @@ class S3Store(MemoryStore):
    presigned URLs. An admin configures the bucket once; opening a store verifies it (:meth:`verify_bucket`) and
    refuses a bucket without versioning, the ``runs/`` expiry rule or S3 Select. There is no local fallback."""
-    def __init__(self, client: ObjectClient, bucket: str, prefix: str = "") -> None:
+    read_only: bool = False
    def __init__(self, client: ObjectClient, bucket: str, prefix: str = "", *, read_only: bool = False) -> None:
        self.client, self.bucket, self.prefix = client, bucket, prefix.strip("/")
-        if self.describe() not in _VERIFIED:
+        self.read_only = read_only
        if not read_only and self.describe() not in _VERIFIED:
            self.verify_bucket()
            _VERIFIED.add(self.describe())
@@ -631,9 +634,11 @@ class S3Store(MemoryStore):
        return self.client.get(self._k(key))
    def _put(self, key: str, data: bytes, labels: Mapping[str, str] | None = None) -> None:
        self._writable()
        self.client.put(self._k(key), data, dict(labels or {}))
    def _delete(self, key: str) -> None:
        self._writable()
        self.client.delete(self._k(key))
    def _keys(self, prefix: str) -> list[str]:
@@ -647,11 +652,16 @@ class S3Store(MemoryStore):
        tagged = self.client.tags(self._k(key)).get("kind")
        return tagged is None or tagged == "*" or kind in tagged.split()
    def _writable(self) -> None:
        if self.read_only:
            raise MemoryStoreError("read-only store")
    def verify_bucket(self) -> None:
-        """Read-only check that the admin's one-time setup is in place: versioning ``Enabled``, an enabled
+        """Check the admin's one-time setup, writing only the capability probe: versioning ``Enabled``, an enabled
        lifecycle rule expiring ``<prefix>/runs/`` and none expiring the whole store, S3 Select answering a probe
        over JSON Lines, and the probe's object tags readable. Every missing piece is named with its admin action
        in one :class:`MemoryStoreError`."""
        self._writable()
        runs = self._k(RUNS_PREFIX)
        endpoint = '--endpoint-url "$S3_ENDPOINT"'
        missing: list[str] = []
@@ -739,6 +749,7 @@ class S3Store(MemoryStore):
            ) from exc
    def presign_put(self, key: str, expires: timedelta = timedelta(hours=1)) -> str:
        self._writable()
        return self.client.presign("PUT", self._k(key), expires)
    def presign_get(self, key: str, expires: timedelta = timedelta(hours=1)) -> str:
@@ -915,9 +926,10 @@ def s3_settings(environ: Mapping[str, str] | None = None) -> dict[str, Any]:
    return settings
-def open_store(spec: str | None = None, environ: Mapping[str, str] | None = None) -> MemoryStore:
+def open_store(spec: str | None = None, environ: Mapping[str, str] | None = None, *, read_only: bool = False) -> MemoryStore:
    """The store ``spec`` (else ``OUSAST_MEMORY``, else ``file://<results_root()>/memory``) names. ``s3://`` with no
-    bucket uses ``S3_BUCKET``."""
+    bucket uses ``S3_BUCKET``. ``read_only`` skips the S3 write/Select capability probe and refuses S3 mutations;
    it is intended for GET/list inventory readers, which do not need Select. Default opening is unchanged."""
    from .reconciler import results_root
    env = environ if environ is not None else os.environ
@@ -932,7 +944,7 @@ def open_store(spec: str | None = None, environ: Mapping[str, str] | None = None
        if not bucket:
            raise MemoryStoreError("OUSAST_MEMORY=s3:// names no bucket and S3_BUCKET is unset: set one of them")
        settings = s3_settings(environ)
-        return S3Store(S3Client(bucket=bucket, **settings), bucket, parts.path)
+        return S3Store(S3Client(bucket=bucket, **settings), bucket, parts.path, read_only=read_only)
    raise MemoryStoreError(f"OUSAST_MEMORY must be file:///<path> or s3://<bucket>[/<prefix>], got {text!r}")
@@ -404,12 +404,31 @@ class SnapshotAdapter:
                            spans.append(ChangedSpan(path_head.hex(), new_start, new_start + new_count - 1, "head"))
                        old_cursor, new_cursor = old_index + old_count, new_index + new_count
                    pairs.extend(_equal_line_pairs(old_lines, new_lines, old_cursor, len(old_lines), new_cursor, len(new_lines)))
-                    old_counts, new_counts = Counter(old_lines), Counter(new_lines)
+                    # Equal-region pairs are positionally 1:1 within a contiguous run
                    # (strictly +1/+1 from _equal_line_pairs). A line's content is a
                    # trustworthy positional anchor when it occupies exactly one old and
                    # one new run; content repeated across runs split by an edit is aligned
                    # arbitrarily by git and is withheld as ambiguous. Duplicates within one
                    # run stay forced and safe.
                    anchor_pairs = () if ambiguous_rename else pairs
                    anchor_runs: list[list[tuple[int, int]]] = []
                    for pair in anchor_pairs:
                        last = anchor_runs[-1][-1] if anchor_runs else None
                        if last is not None and pair[0] == last[0] + 1 and pair[1] == last[1] + 1:
                            anchor_runs[-1].append(pair)
                        else:
                            anchor_runs.append([pair])
                    old_runs: dict[bytes, set[int]] = {}
                    new_runs: dict[bytes, set[int]] = {}
                    for run_index, run in enumerate(anchor_runs):
                        for old_index, new_index in run:
                            old_runs.setdefault(old_lines[old_index], set()).add(run_index)
                            new_runs.setdefault(new_lines[new_index], set()).add(run_index)
                    ambiguous = False
-                    for old_index, new_index in () if ambiguous_rename else pairs:
+                    for old_index, new_index in anchor_pairs:
                        _check_budget(budget, cancelled)
                        content = old_lines[old_index]
-                        if old_counts[content] != 1 or new_counts[content] != 1:
+                        if len(old_runs.get(content, ())) != 1 or len(new_runs.get(content, ())) != 1:
                            ambiguous = True
                            continue
                        mappings.append(LineCorrespondence(path_base.hex(), path_head.hex(), old_index + 1, old_index + 1, new_index + 1))
@@ -0,0 +1 @@
 """Verifier-owned differential demonstrations (search-with-proof Req 3)."""
@@ -0,0 +1,222 @@
 """Local CLI lane using the existing sandbox job/result contract.
 Bubblewrap is required, never emulated with chmod. Each process sees only the
 immutable runtime, declared inputs, and its own scratch. No host /proc or home.
 The seccomp filter denies sockets for artefacts and builds, even on hosts where
 creating a network namespace is unavailable. SSRF apps join the oracle's private
 loopback namespace. This is a Linux lane; other hosts fail closed.
 """
 from __future__ import annotations
 import math
 import os
 import platform
 import resource
 import signal
 import struct
 import subprocess
 import sys
 import tempfile
 from contextlib import suppress
 from pathlib import Path
 from ..sandbox import SandboxJob, SandboxResult
 ARTEFACT_UID = 10001
 ARTEFACT_GID = 10001
 def isolation_mode() -> str:
    """Root containers need no user namespace; ordinary host callers retain it."""
    return "root-no-userns" if os.geteuid() == 0 else "userns"
 def drop_privileges() -> list[str]:
    return [
        "/usr/bin/setpriv",
        f"--reuid={ARTEFACT_UID}",
        f"--regid={ARTEFACT_GID}",
        "--clear-groups",
        "--no-new-privs",
        "--bounding-set=-all",
        "--inh-caps=-all",
        "--ambient-caps=-all",
        "--",
    ]
 def capability_args() -> list[str]:
    # Retain only what the trusted setpriv trampoline needs, then erase the
    # bounding/inheritable/ambient sets before executing any untrusted code.
    args = ["--cap-drop", "ALL"]
    if isolation_mode() == "root-no-userns":
        for capability in ("CAP_SETUID", "CAP_SETGID", "CAP_SETPCAP"):
            args += ["--cap-add", capability]
    return args
 def writable_directory(path: Path) -> None:
    if isolation_mode() == "root-no-userns":
        os.chown(path, ARTEFACT_UID, ARTEFACT_GID, follow_symlinks=False)
 class IsolationUnavailable(RuntimeError):
    """The isolation instrument failed, so no product outcome can be recorded."""
 def isolation_check(*, timeout_seconds: float = 5) -> None:
    """Prove a trivial job can read its input through the real sandbox path."""
    try:
        with tempfile.TemporaryDirectory(prefix="isolation-check-") as directory:
            root = Path(directory)
            if isolation_mode() == "root-no-userns":
                root.chmod(0o755)
            (root / "probe").write_text("isolation-ready\n")
            scratch = root / "scratch"
            scratch.mkdir()
            job = SandboxJob("", ("/bin/cat", "/workspace/probe"), root, {}, max(1, math.ceil(timeout_seconds)), 256, 128)
            result = run(job, scratch=scratch, wall_timeout_seconds=timeout_seconds)
    except (OSError, subprocess.SubprocessError) as exc:
        raise IsolationUnavailable(f"sandbox isolation preflight could not start: {exc}") from exc
    if result.exit_code or result.timed_out or result.stdout != "isolation-ready\n":
        raise IsolationUnavailable(
            f"sandbox isolation preflight failed (exit={result.exit_code}, timeout={result.timed_out}): {result.stderr}"
        )
 def _filter(network: bool) -> bytes:
    # Audit architecture check also excludes x32 syscall-number bypasses.
    if platform.machine() == "x86_64":
        arch, forbidden = 0xC000003E, [101, 165, 166, 272, 308, 321]
        sockets = [41, 42, 43, 49, 50, 53, 288]
    elif platform.machine() == "aarch64":
        arch, forbidden = 0xC00000B7, [39, 40, 97, 117, 268, 280]
        sockets = [198, 199, 200, 201, 202, 203, 242]
    else:
        raise OSError("unsupported seccomp architecture")
    ins = [(0x20, 0, 0, 4), (0x15, 1, 0, arch), (6, 0, 0, 0x80000000), (0x20, 0, 0, 0), (0x35, 0, 1, 0x40000000), (6, 0, 0, 0x80000000)]
    for number in forbidden + ([] if network else sockets):
        ins.extend([(0x15, 0, 1, number), (6, 0, 0, 0x50001)])
    ins.append((6, 0, 0, 0x7FFF0000))
    return b"".join(struct.pack("HBBI", *i) for i in ins)
 def run(
    job: SandboxJob,
    *,
    scratch: Path,
    mounts: dict[str, Path] | None = None,
    env: dict[str, str] | None = None,
    namespace_pid: int | None = None,
    scratch_bytes: int | None = None,
    wall_timeout_seconds: float | None = None,
    input_text: str = "",
    network: bool = False,
    writable_checkout: bool = False,
 ) -> SandboxResult:
    """Run with bounded files, memory, processes, and time; no inherited env."""
    def limits() -> None:
        resource.setrlimit(resource.RLIMIT_FSIZE, (1024 * 1024, 1024 * 1024))
        resource.setrlimit(resource.RLIMIT_AS, (job.memory_mb * 1024**2,) * 2)
        resource.setrlimit(resource.RLIMIT_CPU, (job.timeout_seconds + 1,) * 2)
    argv = ["bwrap", "--die-with-parent", "--new-session", "--unshare-pid", "--unshare-ipc", "--unshare-uts"]
    mode = isolation_mode()
    if namespace_pid is None:
        if mode == "userns":
            argv += ["--unshare-user"]
    else:
        argv = [
            "/usr/bin/nsenter",
            *(["--preserve-credentials", f"--user=/proc/{namespace_pid}/ns/user"] if mode == "userns" else []),
            f"--net=/proc/{namespace_pid}/ns/net",
            "--",
            *argv,
        ]
    if network and namespace_pid is None:
        argv += ["--unshare-net"]
    argv += [*capability_args(), "--clearenv", "--dev", "/dev"]
    for path in ("/usr", "/lib", "/lib64", "/bin"):
        if Path(path).exists():
            argv += ["--ro-bind", path, path]
    # The verifier's Python can live in /venv or a host venv backed by
    # an interpreter outside /usr. Keep that same ABI available in this lane.
    for path in dict.fromkeys((sys.base_prefix, sys.prefix)):
        if not any(Path(path).is_relative_to(base) for base in ("/usr", "/lib", "/lib64", "/bin")):
            argv += ["--ro-bind", path, path]
    argv += ["--bind" if writable_checkout else "--ro-bind", str(job.repo_root), "/workspace"]
    if scratch_bytes is None:
        writable_directory(scratch)
        argv += ["--bind", str(scratch), "/scratch"]
    else:
        if scratch_bytes < 1:
            raise ValueError("positive scratch limit required")
        argv += ["--size", str(scratch_bytes)]
        if mode == "root-no-userns":
            argv += ["--perms", "0777"]
        argv += ["--tmpfs", "/scratch"]
    for target, source in (mounts or {}).items():
        argv += ["--ro-bind", str(source), target]
    argv += [
        "--remount-ro",
        "/",
        "--chdir",
        "/scratch",
        "--setenv",
        "PATH",
        "/usr/bin:/bin",
        "--setenv",
        "HOME",
        "/scratch",
        "--setenv",
        "TMPDIR",
        "/scratch",
    ]
    for key, value in (env or {}).items():
        argv += ["--setenv", key, value]
    with tempfile.TemporaryFile() as policy, tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
        policy.write(_filter(namespace_pid is not None or network))
        policy.seek(0)
        # Apply NPROC after namespace setup and any uid drop. In root mode the
        # dedicated uid shares this process budget across concurrent sandboxes.
        argv += [
            "--seccomp",
            str(policy.fileno()),
            "--",
            *(drop_privileges() if mode == "root-no-userns" else []),
            "/usr/bin/prlimit",
            f"--nproc={job.pids_limit}:{job.pids_limit}",
            "--",
            *job.command,
        ]
        proc = subprocess.Popen(
            argv,
            stdin=subprocess.PIPE,
            stdout=out,
            stderr=err,
            pass_fds=(policy.fileno(),),
            start_new_session=True,
            preexec_fn=limits,
            env={"PATH": "/usr/bin:/bin"},
        )
        timed_out = False
        try:
            proc.communicate(
                input=input_text.encode(),
                timeout=min(job.timeout_seconds, wall_timeout_seconds) if wall_timeout_seconds is not None else job.timeout_seconds,
            )
        except subprocess.TimeoutExpired:
            timed_out = True
            os.killpg(proc.pid, signal.SIGKILL)
            proc.wait()
        finally:
            # Also terminate descendants left behind after a successful shell exit.
            with suppress(ProcessLookupError):
                os.killpg(proc.pid, signal.SIGKILL)
        out.seek(0)
        err.seek(0)
        return SandboxResult(
            proc.returncode, out.read(1024 * 1024).decode(errors="replace"), err.read(1024 * 1024).decode(errors="replace"), timed_out
        )
@@ -0,0 +1,147 @@
 """Coordinator-owned, content-addressed search checkpoints in the plane memory store.
 Workers receive snapshots and return proposals; they never receive this writer or
 store credentials. Persist the returned head in the host's run checkpoint.
 """
 from __future__ import annotations
 import copy
 import hashlib
 import json
 import re
 import threading
 from typing import Any
 import yaml
 from ..plane.memory import MemoryStore
 class Board:
    def __init__(self, store: MemoryStore, search_id: str, *, coordinator: str, max_bytes: int = 262144) -> None:
        if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", search_id) or not coordinator or max_bytes < 256:
            raise ValueError("invalid board configuration")
        self.store, self.coordinator, self.max_bytes = store, coordinator, max_bytes
        self.prefix = "boards/" + hashlib.sha256(search_id.encode()).hexdigest()
        self._lock = threading.RLock()
        self.head: str | None = None
        self._state: dict[str, Any] = dict(
            search_id=search_id, version=0, previous=None, facts=[], intents=[], hints=[], end_reason=None, end_detail=None, checkpoint={}
        )
    @property
    def state(self) -> dict[str, Any]:
        with self._lock:
            return copy.deepcopy(self._state)
    @classmethod
    def resume(cls, store: MemoryStore, search_id: str, head: str, *, coordinator: str, max_bytes: int = 262144) -> Board:
        board = cls(store, search_id, coordinator=coordinator, max_bytes=max_bytes)
        data = store.get_blob(board.prefix, head)
        if data is None or len(data) > max_bytes:
            raise ValueError("missing or oversized board checkpoint")
        state = json.loads(data)
        if state["search_id"] != search_id:
            raise ValueError("checkpoint belongs to another search")
        board._validate(state)
        board._state, board.head = state, head
        return board
    def commit(self, *, writer: str, **changes: Any) -> str:
        with self._lock:
            if writer != self.coordinator:
                raise PermissionError("only the coordinator may write the board")
            if self._state["end_reason"] is not None:
                raise ValueError("search already ended")
            if changes.keys() - {"facts", "intents", "hints", "end_reason", "end_detail", "checkpoint"}:
                raise ValueError("unknown board fields")
            state = {**self.state, **copy.deepcopy(changes), "version": self._state["version"] + 1, "previous": self.head}
            self._validate(state)
            data = json.dumps(state, sort_keys=True, allow_nan=False).encode()
            if len(data) > self.max_bytes:
                raise ValueError("board size cap exceeded")
            head = self.store.put_blob(self.prefix, data)
            self._state, self.head = state, head
            return head
    @staticmethod
    def _validate(state: dict[str, Any]) -> None:
        if state["end_reason"] not in (None, "goal_met", "budget_spent", "exhausted", "reason_refused"):
            raise ValueError("invalid end reason")
        ids: dict[str, set[str]] = {}
        for kind in ("facts", "intents", "hints"):
            ids[kind] = set()
            for row in state[kind]:
                required = ("id", "step", "task_id", "description" if kind == "intents" else "text")
                if any(not isinstance(row.get(key), str) or not row[key] for key in required):
                    raise ValueError("entry requires text and writer provenance")
                if row["id"] in ids[kind]:
                    raise ValueError("duplicate board id")
                ids[kind].add(row["id"])
        for fact in state["facts"]:
            if not isinstance(fact.get("evidence_refs"), list) or not fact["evidence_refs"]:
                raise ValueError("facts require evidence references")
            if any(not isinstance(ref, str) or not ref for ref in fact["evidence_refs"]):
                raise ValueError("invalid evidence reference")
            if not isinstance(fact.get("from_intents"), list) or set(fact["from_intents"]) - ids["intents"]:
                raise ValueError("unknown source intent")
        for intent in state["intents"]:
            if not isinstance(intent.get("from_facts"), list) or set(intent["from_facts"]) - ids["facts"]:
                raise ValueError("unknown source fact")
            if intent.get("status") not in ("open", "claimed", "concluded"):
                raise ValueError("invalid intent status")
            if intent["status"] == "claimed" and not intent.get("claimant"):
                raise ValueError("claimed intent requires claimant")
            if intent["status"] == "open" and intent.get("claimant") is not None:
                raise ValueError("open intent cannot have claimant")
    def candidate(self) -> dict[str, str]:
        """Manifest location is a hint, never confirmed evidence."""
        for hint in self.state["hints"]:
            if hint["id"] == "candidate":
                try:
                    value = json.loads(hint["text"])
                except ValueError:
                    continue
                if isinstance(value, dict):
                    return {k: v for k, v in value.items() if k in {"family", "file", "function", "oracle"} and isinstance(v, str)}
        return {}
    def snapshot(self, *, max_bytes: int = 32768, budget_left: dict[str, Any] | None = None) -> str:
        """Valid YAML even when truncated; explicit omission counts, never a cut string."""
        if max_bytes < 128:
            raise ValueError("snapshot cap must be at least 128 bytes")
        state = self.state
        view = {key: state[key] for key in ("version", "end_reason", "facts", "intents", "hints")}
        view["candidate"] = self.candidate()
        view["family"] = view["candidate"].get("family", "unknown")
        view["budget_left"] = budget_left or {}
        for intent in view["intents"]:
            if intent["status"] == "concluded":
                facts = [f["id"] for f in state["facts"] if intent["id"] in f["from_intents"]]
                intent["conclusion"] = {"facts": facts} if facts else {"failure": intent.get("failure", "no confirmed facts")}
        checkpoint = state.get("checkpoint", {})
        if checkpoint.get("duplicate_rejections"):
            view["rejections"] = checkpoint["duplicate_rejections"]
        if checkpoint.get("reason_completed", checkpoint.get("rounds", 0)) >= 2 and not any(f.get("demo") for f in state["facts"]):
            view["Priority"] = "construct the demo now with the facts available, or finish with the precise blocker."
        # Keep recent observations, with explicit truncation, without mutating the board.
        remaining = 12000
        for fact in reversed(view["facts"]):
            original = fact["text"]
            fact["text"] = original[: min(2000, remaining)]
            remaining -= len(fact["text"])
            if fact["text"] != original:
                fact["text_truncated"] = True
        view["omitted"] = dict.fromkeys(("facts", "intents", "hints"), 0)
        while True:
            text = str(yaml.safe_dump(view, sort_keys=False, allow_unicode=True))
            if len(text.encode()) <= max_bytes:
                return text
            kind = next((k for k in ("facts", "intents", "hints") if view[k]), None)
            if kind is None:
                raise ValueError("snapshot cap too small")
            view[kind].pop(0)
            view["omitted"][kind] += 1
@@ -0,0 +1,60 @@
 """Search ceilings carried to every executor; no model or transport dependencies."""
 import math
 from dataclasses import dataclass
@dataclass(frozen=True)
 class SearchBudget:
    # Recalibrated 2026-10-05 on the first three measured searches: settled cost was ~$0.003 per model call,
    # but worst-case reservations (~$0.027 per call) exhausted the old $0.05 task allowance after 2-4 calls.
    spend_usd: float = 2.00
    # Both ceilings bound each task: $0.40 and 40 model steps.
    max_call_usd: float = 0.40
    max_steps: int = 40
    http_start_seconds: int = 90
    cli_start_seconds: int = 30
    reason_rounds: int = 4
    intents_per_round: int = 3
    demonstrations: int = 3
    tasks: int = 32
    retries: int = 1
    memory_bytes: int = 5 * 1024**3
    disk_bytes: int = 2 * 1024**3
    task_wall_seconds: float = 900
    wall_seconds: float = 4 * 3600
    cleanup_seconds: float = 30
    def __post_init__(self) -> None:
        for name, value in vars(self).items():
            if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
                raise ValueError(f"invalid {name}")
            if value < 0 or (value == 0 and name not in ("retries", "spend_usd")):
                raise ValueError(f"invalid {name}")
            if name in (
                "max_steps",
                "http_start_seconds",
                "cli_start_seconds",
                "reason_rounds",
                "intents_per_round",
                "demonstrations",
                "tasks",
                "retries",
                "memory_bytes",
                "disk_bytes",
            ) and not isinstance(value, int):
                raise ValueError(f"{name} must be an integer")
 def verification_timeout(schema: dict, limits: dict | None = None) -> int:
    """Resolve the mode's start/command allowance from the search task budget."""
    key = "http_start_seconds" if schema["start"]["mode"] == "http" else "cli_start_seconds"
    value = (limits or {}).get(key, getattr(SearchBudget(), key))
    if type(value) is not int or not 1 <= value <= 300:
        raise ValueError("invalid verification timeout")
    return value
 def verification_run_seconds(schema: dict, timeout: int) -> int:
    # One readiness operation, all declared steps, and driver shutdown/handshake.
    return timeout * (1 + len(schema["steps"])) + 5
@@ -0,0 +1,499 @@
 """Host-only board driver. Executors own task isolation and enforce supplied limits.
 Reason/explore workers are group 5. They return proposals, never board writes.
 Only the trusted verify executor may return a demonstrated outcome. An interrupted
 call is conservatively charged its reservation on resume, never silently free.
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import json
 import re
 import time
 from collections import Counter
 from collections.abc import Callable
 from dataclasses import asdict, dataclass, replace
 from importlib import import_module
 from pathlib import Path
 from typing import Any, Protocol
 from ..plane.budget import BudgetExhausted, SpendBudget
 from ..plane.memory import open_store
 from .board import Board
 from .budget import SearchBudget
@dataclass(frozen=True)
 class SearchTask:
    id: str
    search_id: str
    step: str
    snapshot: str
    payload: dict[str, Any]
    limits: dict[str, Any]
    lane: str = "ax"
    def __post_init__(self) -> None:
        for value in (self.id, self.search_id):
            if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", value):
                raise ValueError("invalid search task identifier")
        if self.step not in ("reason", "explore", "verify") or self.lane not in ("ax", "kind", "docker"):
            raise ValueError("invalid search task step or lane")
 class Executor(Protocol):
    def __call__(self, task: SearchTask) -> dict[str, Any]:
        """Finish/clean up within limits; report actual cost, including failed calls.
        A missing cost on a model task charges its entire reservation. Model
        workers must reserve each call against limits.max_call_usd (the task's
        total allowance) using plane.budget.SpendBudget. Exceptions are untrusted
        diagnostics and must never be copied into the board.
        """
        ...
 class Coordinator:
    def __init__(
        self,
        board: Board,
        executor: Executor,
        *,
        budget: SearchBudget | None = None,
        clock: Callable[[], float] = time.time,
        push_budget: SpendBudget | None = None,
    ) -> None:
        self.board, self.executor = board, executor
        self.budget, self.clock, self.push_budget = budget or SearchBudget(), clock, push_budget
        self.state = board.state
        self.state.setdefault("end_detail", None)
        self.progress = self.state["checkpoint"] or dict(
            started_at=clock(),
            spent_usd=0.0,
            tasks=0,
            rounds=0,
            retries=0,
            demonstrations=0,
            pending=None,
            verified=[],
            failures=[],
        )
        self.meter = SpendBudget(self.budget.spend_usd, spent=self.progress["spent_usd"])
    def _save(self) -> None:
        self.progress["wall_seconds"] = max(0, self.clock() - self.progress["started_at"])
        self.state["checkpoint"] = self.progress
        self.board.commit(
            writer=self.board.coordinator,
            **{k: self.state[k] for k in ("facts", "intents", "hints", "end_reason", "end_detail", "checkpoint")},
        )
    def _end(self, reason: str, end_detail: str | None = None) -> dict[str, Any]:
        if reason == "budget_spent" and end_detail not in {
            "spend",
            "task_spend",
            "reason_rounds",
            "demonstrations",
            "tasks",
            "task_wall",
            "search_wall",
            "worker_steps",
            "worker_wall",
            "run_ceiling",
        }:
            raise ValueError("budget_spent requires an exhausted limit")
        self.state["end_detail"] = end_detail
        self.state["end_reason"] = reason
        self._save()
        return self.board.state
    def _remaining(self) -> float:
        return float(self.budget.wall_seconds - max(0, self.clock() - self.progress["started_at"]))
    def _snapshot(self) -> str:
        return self.board.snapshot(
            budget_left={
                "tasks": max(0, self.budget.tasks - self.progress["tasks"]),
                "reason_rounds": max(0, self.budget.reason_rounds - self.progress["rounds"]),
                "spend_usd": max(0, self.budget.spend_usd - self.meter.spent),
                "wall_seconds": max(0, self._remaining()),
            }
        )
    def _call(self, step: str, payload: dict[str, Any]) -> dict[str, Any]:
        lane = "ax"
        while True:
            remaining = self._remaining()
            if remaining <= self.budget.cleanup_seconds or self.progress["tasks"] >= self.budget.tasks:
                raise BudgetExhausted(
                    "task or wall budget exhausted",
                    usd=self.meter.spent,
                    calls=self.progress["tasks"],
                    end_detail="search_wall" if remaining <= self.budget.cleanup_seconds else "tasks",
                )
            maximum = self.budget.max_call_usd if step != "verify" else 0
            reservation = self.meter.reserve(maximum)
            push_reservation = None
            try:
                if self.push_budget is not None:
                    push_reservation = self.push_budget.reserve(maximum)
            except BudgetExhausted as exc:
                reservation.release()
                raise BudgetExhausted("push ceiling", usd=exc.usd, calls=exc.calls, end_detail="run_ceiling") from exc
            task_id = "task-" + str(self.progress["tasks"] + 1)
            limits = asdict(self.budget)
            limits["task_wall_seconds"] = min(self.budget.task_wall_seconds, remaining - self.budget.cleanup_seconds)
            task = SearchTask(task_id, self.state["search_id"], step, self._snapshot(), payload, limits, lane)
            self.progress["tasks"] += 1
            self.progress["pending"] = {"id": task_id, "step": step, "payload": payload}
            # A crash after this durable write may have spent the whole allowance.
            self.progress["spent_usd"] = self.meter.spent + maximum
            if step == "explore":
                intent = next(i for i in self.state["intents"] if i["id"] == payload["intent_id"])
                intent.update(status="claimed", claimant=task_id)
            self._save()
            task = replace(task, snapshot=self._snapshot())
            dispatched_at = self.clock()
            try:
                result = self.executor(task)
            except Exception:
                # Includes cleanup failures: never launch more work after a task
                # may have leaked. The persisted reservation remains conservative.
                reservation.settle(maximum)
                if push_reservation is not None:
                    push_reservation.settle(maximum)
                raise
            if not isinstance(result, dict):
                result = {"status": "invalid_result"}
            actual = result.get("cost_usd", maximum)
            try:
                reservation.settle(actual)
                if push_reservation is not None:
                    push_reservation.settle(actual)
            except (ValueError, TypeError, ArithmeticError):
                # Charge the maximum and stop on a violated executor contract.
                if reservation._active:
                    reservation.settle(maximum)
                if push_reservation is not None and push_reservation._active:
                    push_reservation.settle(maximum)
                result = {"status": "invalid_cost"}
            self.progress["spent_usd"] = self.meter.spent
            self.progress["pending"] = None
            if (
                result.get("status") == "invalid_cost"
                or self._remaining() <= 0
                or self.clock() - dispatched_at > limits["task_wall_seconds"]
            ):
                raise BudgetExhausted(
                    "executor exceeded cost or wall contract",
                    usd=self.meter.spent,
                    calls=self.progress["tasks"],
                    end_detail="task_spend"
                    if result.get("status") == "invalid_cost"
                    else "search_wall"
                    if self._remaining() <= 0
                    else "task_wall",
                )
            result = {**result, "task_id": task_id}
            # Persist results together with their effects in run(), not a "done"
            # checkpoint which could lose the result if the host then crashes.
            if result.get("status") in ("sandbox_failure", "oom", "instrument_failure") and self.progress["retries"] < self.budget.retries:
                self.progress["retries"] += 1
                lane = "docker"
                continue
            if step == "reason":
                self.progress["reason_completed"] = self.progress.get("reason_completed", 0) + 1
            return result
    def run(self) -> dict[str, Any]:
        if self.state["end_reason"]:
            return self.board.state
        candidate = self.board.candidate()
        if not self.progress["tasks"] and not self.state["intents"] and candidate.get("file") and candidate.get("function"):
            self.state["intents"].append(
                dict(
                    id="bootstrap",
                    description=(
                        f"Read the candidate function {candidate['function']} in {candidate['file']}, "
                        "the code that calls it, and how the application is started and reached from outside; "
                        "report the entry point, the route or CLI path to the candidate, and the inputs that reach it."
                    ),
                    from_facts=[],
                    status="open",
                    claimant=None,
                    step="bootstrap",
                    task_id="coordinator",
                )
            )
            self._save()
        pending = self.progress.get("pending")
        if pending:
            # Do not duplicate a possibly paid operation. Recover the claim as a
            # recorded failure; the next reason task can propose another direction.
            self.progress["failures"].append({"task_id": pending["id"], "reason": "interrupted"})
            for intent in self.state["intents"]:
                if intent.get("claimant") == pending["id"]:
                    intent.update(status="concluded", failure="interrupted")
            if pending["step"] == "verify":
                self.progress["verified"].append(pending["payload"]["fact_id"])
            self.progress["pending"] = None
            self._save()
        while True:
            if self._remaining() <= self.budget.cleanup_seconds:
                return self._end("budget_spent", "search_wall")
            try:
                intent = next((i for i in self.state["intents"] if i["status"] == "open"), None)
                demo = next((f for f in self.state["facts"] if f.get("demo") and f["id"] not in self.progress["verified"]), None)
                if demo is not None:
                    if self.progress["demonstrations"] >= self.budget.demonstrations:
                        return self._end("budget_spent", "demonstrations")
                    self.progress["demonstrations"] += 1
                    result = self._call(
                        "verify",
                        {
                            "fact_id": demo["id"],
                            "demo": demo["demo"],
                            "family": self.board.candidate().get("family"),
                            "oracle": demo.get("oracle"),
                        },
                    )
                    self.progress["verified"].append(demo["id"])
                    refs = result.get("evidence_refs")
                    if result.get("status") == "ok" and result.get("outcome") == "demonstrated" and self._refs(refs):
                        self.state["facts"].append(
                            dict(
                                id="verified-" + result["task_id"],
                                text="Differential demonstrated",
                                evidence_refs=refs,
                                from_intents=demo["from_intents"],
                                step="verify",
                                task_id=result["task_id"],
                            )
                        )
                        return self._end("goal_met")
                    self.progress["failures"].append({"task_id": result["task_id"], "reason": "not_demonstrated"})
                    if result.get("control_observed") is False and not any(h["id"] == "served-root" for h in self.state["hints"]):
                        self.state["hints"].append(
                            dict(
                                id="served-root",
                                step="verify",
                                task_id=result["task_id"],
                                text="The application did not serve the oracle root: its served-directory configuration "
                                "(argument, environment variable, or config file) must be set to the ${served_root} "
                                "placeholder itself, not a real path or an explore-time test directory.",
                            )
                        )
                elif intent is not None:
                    result = self._call("explore", {"intent_id": intent["id"], "description": intent["description"]})
                    intent["status"] = "concluded"
                    fact = result.get("fact")
                    if (
                        result.get("status") == "ok"
                        and isinstance(fact, dict)
                        and isinstance(fact.get("text"), str)
                        and fact["text"]
                        and self._refs(fact.get("evidence_refs"))
                    ):
                        entry = dict(
                            id="fact-" + result["task_id"],
                            text=fact["text"],
                            evidence_refs=fact["evidence_refs"],
                            from_intents=[intent["id"]],
                            step="explore",
                            task_id=result["task_id"],
                        )
                        if isinstance(fact.get("demo"), str) and fact["demo"]:
                            entry["demo"] = fact["demo"]
                            entry["oracle"] = fact.get("oracle")
                        self.state["facts"].append(entry)
                        intent["conclusion"] = {"facts": [entry["id"]]}
                    else:
                        intent["failure"] = result.get("failure") or (
                            "invalid_result" if result.get("status") == "ok" else result.get("status", "execution_failure")
                        )
                        intent["conclusion"] = {"failure": intent["failure"]}
                    if result.get("budget_exhaustion", {}).get("end_detail") == "task_spend":
                        intent["limit"] = "task_spend"
                        self.progress["failures"].append({"task_id": result["task_id"], "reason": "task_spend"})
                else:
                    if self.progress["rounds"] >= self.budget.reason_rounds:
                        return self._end("budget_spent", "reason_rounds")
                    self.progress["rounds"] += 1
                    result = self._call("reason", {})
                    if result.get("status") == "ok" and not result.get("intents") and "complete" not in result:
                        result = self._call(
                            "reason",
                            {
                                "reminder": (
                                    "No intents are open. You MUST propose 1-3 independent new intents, "
                                    "or cite facts containing a complete demo. An empty reply is a refusal."
                                )
                            },
                        )
                        if result.get("status") == "ok" and not result.get("intents") and "complete" not in result:
                            self.progress["failures"].append({"task_id": result["task_id"], "reason": "reason_refused"})
                            return self._end("reason_refused")
                    if result.get("budget_exhaustion", {}).get("end_detail") == "task_spend":
                        self.progress["failures"].append({"task_id": result["task_id"], "reason": "task_spend"})
                        self._save()
                        continue
                    if result.get("budget_exhaustion"):
                        return self._end("budget_spent", result["budget_exhaustion"]["end_detail"])
                    for attempt in range(2):
                        _, rejected = self._admit_intents(result)
                        if not rejected or attempt:
                            break
                        self._save()
                        result = self._call("reason", {"reminder": "duplicate_intent: choose a new direction; see snapshot rejections."})
                        if result.get("budget_exhaustion"):
                            if result["budget_exhaustion"]["end_detail"] == "task_spend":
                                break
                            return self._end("budget_spent", result["budget_exhaustion"]["end_detail"])
                    if result.get("budget_exhaustion", {}).get("end_detail") == "task_spend":
                        self.progress["failures"].append({"task_id": result["task_id"], "reason": "task_spend"})
                        self._save()
                        continue
                    if not any(i["status"] == "open" for i in self.state["intents"]):
                        return self._end("exhausted")
                if result.get("budget_exhaustion") and result["budget_exhaustion"]["end_detail"] != "task_spend":
                    return self._end("budget_spent", result["budget_exhaustion"]["end_detail"])
                self._save()
            except BudgetExhausted as exc:
                return self._end("budget_spent", exc.end_detail)
    def _admit_intents(self, result: dict[str, Any]) -> tuple[int, bool]:
        proposals = result.get("intents", [])
        if result.get("status") != "ok" or not isinstance(proposals, list) or len(proposals) > self.budget.intents_per_round:
            return 0, False
        known = {f["id"] for f in self.state["facts"]}
        descriptions = {i["description"] for i in self.state["intents"]}
        added = 0
        rejections = []
        for proposal in proposals:
            if not isinstance(proposal, dict):
                continue
            description, refs = proposal.get("description"), proposal.get("from_facts", [])
            if not isinstance(description, str) or not description.strip():
                continue
            if not isinstance(refs, list) or any(not isinstance(ref, str) or ref not in known for ref in refs):
                continue
            tokens = Counter(re.findall(r"\w+", description.casefold()))
            duplicate = next(
                (
                    i
                    for i in self.state["intents"]
                    if i["status"] == "concluded"
                    and tokens
                    and sum((tokens & Counter(re.findall(r"\w+", i["description"].casefold()))).values()) / sum(tokens.values()) > 0.6
                ),
                None,
            )
            if duplicate is not None:
                rejection = {
                    "task_id": result["task_id"],
                    "reason": "duplicate_intent",
                    "description": description,
                    "concluded_intent": duplicate["id"],
                }
                rejections.append(rejection)
                self.progress["failures"].append(rejection)
                continue
            if description in descriptions:
                continue
            added += 1
            descriptions.add(description)
            self.state["intents"].append(
                dict(
                    id=result["task_id"] + "-intent-" + str(added),
                    description=description,
                    from_facts=refs,
                    status="open",
                    claimant=None,
                    step="reason",
                    task_id=result["task_id"],
                )
            )
        self.progress["duplicate_rejections"] = rejections
        return added, bool(rejections)
    @staticmethod
    def _refs(refs: Any) -> bool:
        return isinstance(refs, list) and bool(refs) and all(isinstance(ref, str) and bool(ref) for ref in refs)
 class BatchExecutor:
    """Adapter to the existing AX/VM transfer and checkpoint protocol.
    Pass AXLane/DockerLane instances and a trusted worker command. No default
    worker is invented here: reason/explore entrypoints belong to group 5.
    The coordinator owns retries, so batch performs exactly one attempt.
    """
    def __init__(self, *, image: str, command: tuple[str, ...], output: Path, lanes: dict[str, Any]) -> None:
        batch = import_module("benchmarks.ax.batch")
        batch.validate_image(image)
        if not command:
            raise ValueError("worker command required")
        self.image, self.command, self.output, self.lanes = image, command, output, lanes
    def __call__(self, task: SearchTask) -> dict[str, Any]:
        import copy
        batch = import_module("benchmarks.ax.batch")
        if task.lane not in self.lanes:
            return {"status": "sandbox_failure", "cost_usd": 0}
        data = json.dumps(asdict(task), sort_keys=True, allow_nan=False).encode()
        digest = hashlib.sha256(data).hexdigest()
        identity = task.search_id + "-" + task.id
        item = batch.Item(
            identity,
            {"SPEC_URL": data},
            "result.dat",
            self.command,
            {"SEARCH_STEP": task.step, "SEARCH_ID": task.search_id, "SEARCH_TASK_ID": task.id},
            digest,
        )
        def validate(raw: bytes, output: Path) -> None:
            if len(raw) > 262144:
                raise ValueError("search result size exceeded")
            record = json.loads(raw)
            if not isinstance(record, dict) or record.get("status") not in (
                "ok",
                "sandbox_failure",
                "instrument_failure",
                "oom",
                "execution_failure",
            ):
                raise ValueError("invalid search result")
            (output / "result.json").write_text(json.dumps(record))
        workload = batch.Workload(self.image, frozenset({"SPEC_URL", "RESULT_URL"}), task.limits["task_wall_seconds"], validate)
        lane = copy.copy(self.lanes[task.lane])
        if hasattr(lane, "workload"):
            lane.workload = workload
        out = self.output / task.search_id / task.id
        batch.dispatch([item], workload, out, {task.lane: lane}, lanes=(task.lane,), max_attempts=1)
        record_path = out / (hashlib.sha256(identity.encode()).hexdigest() + ".json")
        if not record_path.exists():
            return {"status": "execution_failure", "cost_usd": 0}
        record: dict[str, Any] = json.loads(record_path.read_text())
        return record
 def main() -> None:
    """Offline checkpoint inspection, also useful before resuming with an executor."""
    parser = argparse.ArgumentParser(description="Inspect a search board checkpoint (no model calls)")
    parser.add_argument("--memory", required=True)
    parser.add_argument("--search-id", required=True)
    parser.add_argument("--head", required=True)
    args = parser.parse_args()
    board = Board.resume(open_store(args.memory), args.search_id, args.head, coordinator="inspect")
    print(board.snapshot(), end="")
 if __name__ == "__main__":
    main()
@@ -0,0 +1,499 @@
 """Bounded declarative demonstrations; no executable agent content or private variables.
 Start configuration accepts oracle-owned fixture placeholders; steps accept prior response captures. Runtime
 paths and build manifests are checkout relative; request payloads remain data (and
 may contain traversal or injection strings being tested at the public interface).
 """
 from __future__ import annotations
 import json
 import os
 import re
 import sys
 import tomllib
 from pathlib import Path, PurePosixPath
 from typing import Any, cast
 FAMILY_ORACLES = {
    "injection": ("sql", "command"),
    "path": ("path",),
    "output_encoding": ("xss",),
    "untrusted_destination": ("ssrf",),
    "deserialization": (),
    "access_control": (),
    "config_secrets": (),
 }
 def validate_oracle(family: str, oracle: str) -> None:
    if not isinstance(family, str) or family not in FAMILY_ORACLES:
        raise ValueError("unknown search family")
    if oracle not in FAMILY_ORACLES[family]:
        raise ValueError("demo oracle is not allowed for search family " + family)
 # JSON escaping can expand UTF-8 data sixfold and non-BMP environment characters
 # into twelve-byte surrogate pairs. Keep the ordinary demo payload at 64 KiB.
 MAX_DEMO_BYTES = 5 * 1024 * 1024
 MAX_DATA_BYTES = 64 * 1024
 ENV_DENYLIST = {
    "LD_PRELOAD",
    "LD_LIBRARY_PATH",
    "PYTHONPATH",
    "PYTHONSTARTUP",
    "NODE_OPTIONS",
    "NODE_PATH",
    "JAVA_TOOL_OPTIONS",
    "_JAVA_OPTIONS",
    "JDK_JAVA_OPTIONS",
    "PHP_INI_SCAN_DIR",
    "PHPRC",
    "PATH",
    "HOME",
    "TMPDIR",
 }
 DATA_EXTENSIONS = {".pem", ".key", ".json", ".yaml", ".yml", ".txt", ".env", ".ini", ".toml", ".db", ".sqlite", ".crt"}
 MAX_STEPS = 32
 MAX_VALUE_BYTES = 16384
 # Every executable and option is verifier-owned. Arguments below are manifests or
 # an enumerated build goal, never arbitrary package-manager flags or scripts.
 BUILD_RECIPES = {
    "none": (),
    "pip": (
        sys.executable,
        "-I",
        "-m",
        "pip",
        "install",
        "--no-index",
        "--ignore-installed",
        "--no-warn-script-location",
        "--target",
        "/scratch/packages",
        "-r",
    ),
    "npm": ("/usr/bin/npm", "ci", "--offline", "--ignore-scripts", "--prefix"),
    "composer": ("/usr/bin/composer", "install", "--no-plugins", "--no-scripts", "--no-interaction", "--working-dir"),
    "maven": ("/usr/bin/mvn", "--offline", "-f"),
    "gradle": ("/usr/bin/gradle", "--offline", "--no-daemon", "--project-dir"),
 }
 # Python apps run under the verifier's own interpreter: it is the one pip installed the products for
 # (the image carries a second, system Python with a different ABI tag; compiled extensions failed under it).
 RUNTIMES = {"python": (sys.executable, "-I"), "node": ("/usr/bin/node",), "php": ("/usr/bin/php",), "java": ("/usr/bin/java", "-jar")}
 ORACLE_PLACEHOLDERS = {
    "path": {"served_root"},
    "sql": {"database_path", "database_url"},
    "command": {"marker_dir"},
    "ssrf": {"callback_url"},
    "xss": set(),
 }
 _REFERENCE = re.compile(r"\$\{([a-z][a-z0-9_]{0,31})\}")
 _PRIVATE = re.compile(r"/(?:fixture|proc|sys|dev|deps|build)(?:/|\b)|(?:PROOF_MARKER|CALLBACK_URL|DATABASE|SERVED_ROOT)", re.I)
 # The model-facing schema is the same closed structure checked by validate_demo;
 # dynamic capture ordering and checkout containment are additional semantic checks.
 _TEXT_SCHEMA = {"type": "string", "maxLength": MAX_VALUE_BYTES}
 _ARG_SCHEMA = {"type": "array", "items": _TEXT_SCHEMA, "maxItems": 64}
 _CAPTURE_SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "required": ["name", "source"],
    "properties": {
        "name": {"type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$"},
        "source": {"enum": ["output", "json"]},
        "path": {"type": "array", "maxItems": 8, "items": {"type": ["string", "integer"]}},
    },
 }
 DEMO_SCHEMA = {
    "type": "object",
    "additionalProperties": False,
    "required": ["oracle", "build", "start", "steps"],
    "properties": {
        "oracle": {"enum": sorted({o for allowed in FAMILY_ORACLES.values() for o in allowed})},
        "build": {
            "type": "object",
            "additionalProperties": False,
            "required": ["recipe", "arguments"],
            "properties": {
                "recipe": {"enum": list(BUILD_RECIPES)},
                "arguments": {"type": "array", "items": {"type": "string", "maxLength": 512}, "maxItems": 1},
            },
            "description": "none takes no arguments; other recipes take one checkout-relative manifest or project path.",
        },
        "start": {
            "type": "object",
            "additionalProperties": False,
            "required": ["runtime", "path", "arguments", "mode"],
            "properties": {
                "runtime": {"enum": list(RUNTIMES)},
                "path": {"type": "string", "minLength": 1, "maxLength": 512},
                "arguments": _ARG_SCHEMA,
                "mode": {"enum": ["http", "cli"]},
                "port": {"type": "integer", "minimum": 1024, "maximum": 65535},
                "environment": {
                    "type": "object",
                    "maxProperties": 32,
                    "propertyNames": {
                        "pattern": "^[A-Z][A-Z0-9_]{0,63}$",
                        "not": {
                            "anyOf": [
                                {"enum": sorted(ENV_DENYLIST)},
                                {"pattern": "^OUSAST_|CANARY"},
                            ]
                        },
                    },
                    "additionalProperties": {"type": "string", "maxLength": 4096},
                },
                "files": {
                    "type": "object",
                    "maxProperties": 8,
                    "additionalProperties": {"type": "string", "maxLength": MAX_DATA_BYTES},
                    "description": "Relative data filenames under .demo/, no ..; allowed extensions: "
                    + " ".join(sorted(DATA_EXTENSIONS))
                    + "; contents at most 64 KiB UTF-8 each, written mode 0600. No scripts.",
                },
            },
            "description": "Tracked checkout entrypoint only. HTTP mode requires a port; CLI mode forbids it.",
        },
        "steps": {
            "type": "array",
            "minItems": 1,
            "maxItems": MAX_STEPS,
            "items": {
                "oneOf": [
                    {
                        "type": "object",
                        "additionalProperties": False,
                        "required": ["type", "arguments"],
                        "properties": {
                            "type": {"const": "cli"},
                            "arguments": _ARG_SCHEMA,
                            "stdin": _TEXT_SCHEMA,
                            "capture": _CAPTURE_SCHEMA,
                        },
                    },
                    {
                        "type": "object",
                        "additionalProperties": False,
                        "required": ["type", "method", "path"],
                        "properties": {
                            "type": {"const": "http"},
                            "method": {"enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]},
                            "path": {"type": "string", "pattern": "^/(?!/)", "maxLength": MAX_VALUE_BYTES},
                            "headers": {"type": "object", "maxProperties": 32, "additionalProperties": _TEXT_SCHEMA},
                            "body": _TEXT_SCHEMA,
                            "capture": _CAPTURE_SCHEMA,
                        },
                    },
                ]
            },
            "description": "Steps match the start mode. Only ${name} from a prior response capture may be substituted.",
        },
    },
 }
 def _keys(value: Any, required: set[str], optional: set[str] | frozenset[str] = frozenset()) -> None:
    if not isinstance(value, dict) or not required <= value.keys() or value.keys() - required - optional:
        raise ValueError("invalid or unknown schema fields")
 def checkout_path(value: Any) -> str:
    if not isinstance(value, str) or not value or len(value) > 512 or "\\" in value or "\0" in value:
        raise ValueError("invalid checkout path")
    path = PurePosixPath(value)
    if path.is_absolute() or any(p in ("", "..", ".") or p.startswith("-") for p in value.split("/")):
        raise ValueError("path must stay inside checkout")
    if not re.fullmatch(r"[a-zA-Z0-9_./ -]+", value):
        raise ValueError("invalid checkout path")
    return value
 _MANIFESTS = {
    "pip": ("pyproject.toml", "setup.py", "setup.cfg"),
    "npm": ("package.json", "package-lock.json"),
    "composer": ("composer.json", "composer.lock"),
    "maven": ("pom.xml",),
    "gradle": ("build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "gradlew"),
 }
 def build_project(recipe: str, path: Path, checkout: Path) -> Path:
    """Validate the recipe ecosystem against actual checkout files."""
    def manifest(candidate: Path) -> bool:
        return candidate.name in _MANIFESTS[recipe] or (recipe == "pip" and candidate.match("requirements*.txt"))
    def contained(candidate: Path) -> bool:
        return candidate.resolve().is_relative_to(checkout.resolve())
    if not contained(path):
        raise ValueError("recipe input outside checkout")
    if path.is_file():
        if not manifest(path):
            raise ValueError("recipe input is not an ecosystem manifest")
        return path.parent
    if path.is_dir() and any(p.is_file() and contained(p) and manifest(p) for p in path.iterdir()):
        return path
    raise ValueError("recipe input must be an ecosystem manifest or project directory")
 def preparation_command(recipe: str, path: Path, checkout: Path, products: Path) -> tuple[list[str], Path]:
    project = build_project(recipe, path, checkout)
    if recipe == "pip":
        requirements = path if path.is_file() and path.match("requirements*.txt") else None
        pyproject = project / "pyproject.toml"
        backend = False
        if requirements is None and pyproject.is_file():
            if not pyproject.resolve().is_relative_to(checkout.resolve()):
                raise ValueError("recipe input outside checkout")
            backend = bool(tomllib.loads(pyproject.read_text()).get("build-system", {}).get("build-backend"))
        if requirements is None and not backend and not (project / "setup.py").is_file():
            fallback = project / "requirements.txt"
            if fallback.is_file():
                requirements = fallback
        target = requirements or project
        if not target.resolve().is_relative_to(checkout.resolve()):
            raise ValueError("recipe input outside checkout")
        return [
            sys.executable,
            "-I",
            "-m",
            "pip",
            "install",
            "--ignore-installed",
            "--no-warn-script-location",
            "--target",
            str(products / "packages"),
            *(["-r", str(target)] if requirements else [str(target)]),
        ], project
    if recipe == "npm":
        locked = any((project / name).is_file() for name in ("package-lock.json", "npm-shrinkwrap.json"))
        return ["npm", "ci" if locked else "install", "--ignore-scripts"], project
    if recipe == "composer":
        return ["composer", "install", "--no-interaction", "--no-plugins", "--no-scripts"], project
    if recipe == "maven":
        return ["mvn", "-q", "-DskipTests", "package", "-f", str(project / "pom.xml")], project
    wrapper = project / "gradlew"
    if not wrapper.is_file() or not wrapper.resolve().is_relative_to(checkout.resolve()):
        raise ValueError("missing or external Gradle wrapper")
    return ["/bin/sh", str(wrapper), "--no-daemon", "--project-dir", str(project), "assemble"], project
 def _text(value: Any, names: set[str], *, maximum: int = MAX_VALUE_BYTES) -> str:
    if not isinstance(value, str) or "\0" in value or len(value.encode()) > maximum:
        raise ValueError("invalid or oversized value")
    if _PRIVATE.search(_REFERENCE.sub(lambda m: "" if m[1] in names else m[0], value)):
        raise ValueError("private verifier references are forbidden")
    references = _REFERENCE.findall(value)
    if any(name not in names for name in references) or "$" in _REFERENCE.sub("", value):
        raise ValueError("only allowed oracle placeholders or earlier response captures may be referenced")
    return value
 def _arguments(value: Any, names: set[str]) -> None:
    if not isinstance(value, list) or len(value) > 64:
        raise ValueError("invalid argument list")
    for arg in value:
        _text(arg, names)
 def validate_start_config(start: dict[str, Any], names: set[str] | None = None) -> None:
    names = names or set()
    environment = start.get("environment", {})
    if not isinstance(environment, dict) or len(environment) > 32:
        raise ValueError("invalid environment map")
    for name, value in environment.items():
        if (
            not isinstance(name, str)
            or not re.fullmatch(r"[A-Z][A-Z0-9_]{0,63}", name)
            or name in ENV_DENYLIST
            or name.startswith("OUSAST_")
            or "CANARY" in name
        ):
            raise ValueError("forbidden environment variable")
        if not isinstance(value, str) or len(value) > 4096:
            raise ValueError("invalid environment value")
        _text(value, names)
    files = start.get("files", {})
    if not isinstance(files, dict) or len(files) > 8:
        raise ValueError("invalid data file map")
    for name, content in files.items():
        checkout_path(name)
        if ".." in name or not any(name.endswith(ext) for ext in DATA_EXTENSIONS):
            raise ValueError("invalid data file extension or name")
        _text(content, names, maximum=MAX_DATA_BYTES)
 def write_start_files(checkout: Path, start: dict[str, Any], bindings: dict[str, str] | None = None) -> None:
    """Create only new private data files, before any app process is launched."""
    bindings = bindings or {}
    validate_start_config(start, set(bindings))
    for name, content in start.get("files", {}).items():
        content = substitute(content, bindings, maximum=MAX_DATA_BYTES)
        path = checkout / ".demo" / name
        directory = checkout
        for part in path.parent.relative_to(checkout).parts:
            directory /= part
            if directory.is_symlink():
                raise ValueError("data directory cannot be a symlink")
            directory.mkdir(exist_ok=True)
        # O_EXCL refuses existing files, links and hardlinks: never overwrite checkout data.
        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
        with os.fdopen(fd, "wb") as stream:
            os.fchmod(stream.fileno(), 0o600)
            stream.write(content.encode())
 def validate_demo(value: Any, *, checkout: Path | None = None) -> dict[str, Any]:
    try:
        encoded = json.dumps(value, allow_nan=False).encode()
    except (ValueError, TypeError, RecursionError) as exc:
        raise ValueError("demo must be JSON data") from exc
    if len(encoded) > MAX_DEMO_BYTES:
        raise ValueError("demo exceeds size limit")
    _keys(value, {"oracle", "build", "start", "steps"})
    if not isinstance(value["oracle"], str) or not any(value["oracle"] in allowed for allowed in FAMILY_ORACLES.values()):
        raise ValueError("unknown demo oracle")
    build, start = value["build"], value["start"]
    _keys(build, {"recipe", "arguments"})
    recipe = build["recipe"]
    if not isinstance(recipe, str) or recipe not in BUILD_RECIPES:
        raise ValueError("unknown build recipe")
    _arguments(build["arguments"], set())
    args = build["arguments"]
    if recipe == "none":
        if args:
            raise ValueError("none recipe accepts no arguments")
    else:
        if len(args) != 1:
            raise ValueError("recipe requires one checkout path")
        if args[0] != ".":
            checkout_path(args[0])
        if checkout is not None:
            build_project(recipe, checkout / args[0], checkout)
    _keys(start, {"runtime", "path", "arguments", "mode"}, {"port", "environment", "files"})
    placeholders = ORACLE_PLACEHOLDERS[value["oracle"]]
    validate_start_config(start, placeholders)
    ordinary = {**value, "start": {k: v for k, v in start.items() if k not in {"environment", "files"}}}
    if len(json.dumps(ordinary, allow_nan=False).encode()) > 65536:
        raise ValueError("demo excluding configuration exceeds size limit")
    if not isinstance(start["runtime"], str) or start["runtime"] not in RUNTIMES:
        raise ValueError("unknown runtime")
    checkout_path(start["path"])
    if start["path"].split("/")[0] == ".demo":
        raise ValueError("data files cannot be runtime entrypoints")
    _arguments(start["arguments"], placeholders)
    if any(
        arg.startswith("/") or ".." in arg.split("/") or re.search(r"(?:^|[= :])/(?:etc|home|root|tmp|workspace|scratch)/", arg)
        for arg in start["arguments"]
    ):
        raise ValueError("start arguments must not name external paths")
    if start["mode"] not in ("http", "cli"):
        raise ValueError("invalid start mode")
    if start["mode"] == "http":
        if type(start.get("port")) is not int or not 1024 <= start["port"] <= 65535:
            raise ValueError("http requires an unprivileged port")
    elif "port" in start:
        raise ValueError("cli does not accept a port")
    steps = value["steps"]
    if not isinstance(steps, list) or not 1 <= len(steps) <= MAX_STEPS:
        raise ValueError("invalid step count")
    names: set[str] = set()
    for step in steps:
        if not isinstance(step, dict) or step.get("type") != start["mode"]:
            raise ValueError("step must match runtime mode")
        if step["type"] == "cli":
            _keys(step, {"type", "arguments"}, {"stdin", "capture"})
            _arguments(step["arguments"], names)
            _text(step.get("stdin", ""), names)
        else:
            _keys(step, {"type", "method", "path"}, {"headers", "body", "capture"})
            if step["method"] not in ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"):
                raise ValueError("invalid HTTP method")
            path = _text(step["path"], names)
            if not path.startswith("/") or path.startswith("//") or any(c in path for c in "\r\n"):
                raise ValueError("HTTP path must be origin relative")
            headers = step.get("headers", {})
            if not isinstance(headers, dict) or len(headers) > 32:
                raise ValueError("invalid headers")
            for key, val in headers.items():
                if (
                    not isinstance(key, str)
                    or not re.fullmatch(r"[A-Za-z0-9-]+", key)
                    or key.lower() in ("host", "connection", "content-length", "transfer-encoding", "proxy-authorization")
                ):
                    raise ValueError("invalid HTTP header")
                if any(c in _text(val, names) for c in "\r\n"):
                    raise ValueError("invalid HTTP header value")
            _text(step.get("body", ""), names)
        if "capture" in step:
            capture = step["capture"]
            _keys(capture, {"name", "source"}, {"path"})
            name = capture["name"]
            if (
                not isinstance(name, str)
                or not re.fullmatch(r"[a-z][a-z0-9_]{0,31}", name)
                or name in names
                or name == "canary"
                or any(name in allowed for allowed in ORACLE_PLACEHOLDERS.values())
                or _PRIVATE.search(name)
            ):
                raise ValueError("invalid capture name")
            if capture["source"] not in ("output", "json"):
                raise ValueError("invalid capture source")
            path = capture.get("path", [])
            if not isinstance(path, list) or len(path) > 8 or any(type(p) not in (str, int) for p in path):
                raise ValueError("invalid JSON capture path")
            names.add(name)
    return cast(dict[str, Any], json.loads(encoded))
 def load_demo(path: Path) -> dict[str, Any]:
    if path.is_dir():
        # Legacy scripts cannot coexist with the schema and accidentally execute.
        if any(p.name != "demo.json" for p in path.iterdir()):
            raise ValueError("demo directory may contain only demo.json")
        path = path / "demo.json"
    if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_DEMO_BYTES:
        raise ValueError("invalid demo file")
    def pairs(items: list[tuple[str, Any]]) -> dict[str, Any]:
        result: dict[str, Any] = {}
        for key, value in items:
            if key in result:
                raise ValueError("duplicate JSON field")
            result[key] = value
        return result
    try:
        return validate_demo(json.loads(path.read_text(), object_pairs_hook=pairs))
    except RecursionError as exc:
        raise ValueError("demo nesting exceeds limit") from exc
 def substitute(value: str, captures: dict[str, str], *, maximum: int = MAX_VALUE_BYTES) -> str:
    result = _REFERENCE.sub(lambda m: captures[m.group(1)], value)
    if len(result.encode()) > maximum or "\0" in result:
        raise ValueError("expanded value exceeds limit")
    return result
 def capture_output(step: dict[str, Any], output: str, captures: dict[str, str], nonce: str) -> None:
    if "capture" not in step:
        return
    spec = step["capture"]
    value: Any = output
    if spec["source"] == "json":
        value = json.loads(output)
        for part in spec.get("path", []):
            value = value[part]
    if not isinstance(value, str):
        value = json.dumps(value, allow_nan=False)
    # Even a response revealing the canary cannot turn it into an input variable.
    if nonce in value:
        raise ValueError("canary values cannot be captured")
    _text(value, set())
    captures[spec["name"]] = value
@@ -0,0 +1,731 @@
 """Key-free repository executor and sequential presigned-object mailbox protocol.
 The in-process implementation is a test adapter. Production brains use
 ObjectStoreExecutor and an independently dispatched executor task.
 """
 from __future__ import annotations
 import argparse
 import copy
 import hashlib
 import io
 import json
 import math
 import os
 import resource
 import signal
 import stat
 import subprocess
 import tarfile
 import tempfile
 import time
 import urllib.error
 import urllib.request
 from collections.abc import Iterator, Mapping
 from contextlib import suppress
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
 from typing import Any, BinaryIO, Protocol
 from urllib.parse import urlsplit
 from ..sandbox import SandboxJob
 from . import _sandbox, task_storage
 from .budget import SearchBudget
 from .demo import MAX_DEMO_BYTES
 MAX_COMMAND_BYTES = MAX_DEMO_BYTES + 65536
 MAX_RESULT_BYTES = 65536
 SAFE_ENV = {"PATH": "/venv/bin:/opt/java/openjdk/bin:/usr/local/bin:/usr/bin:/bin", "LANG": "C.UTF-8", "JAVA_HOME": "/opt/java/openjdk"}
 def clean_environment(_source: Mapping[str, str] | None = None) -> dict[str, str]:
    """Explicit allowlist; even PATH is owned by the executor."""
    return {**SAFE_ENV, **task_storage.environment()}
@dataclass(frozen=True)
 class Command:
    seq: int
    name: str
    args: dict[str, Any]
    timeout_seconds: float = 30
    limits: dict[str, Any] = field(default_factory=dict)
    def validate(self) -> bytes:
        if type(self.seq) is not int or self.seq < 1 or self.seq > 100000:
            raise ValueError("invalid sequence")
        if self.name not in {"list_files", "read_file", "grep", "run", "stop", "prepare_verification"} or not isinstance(self.args, dict):
            raise ValueError("invalid command")
        if type(self.timeout_seconds) not in (float, int) or not math.isfinite(self.timeout_seconds) or not 0 < self.timeout_seconds <= 300:
            raise ValueError("invalid timeout")
        if not isinstance(self.limits, dict) or self.limits.keys() - {
            "result_bytes",
            "memory_bytes",
            "disk_bytes",
            "task_wall_seconds",
            "max_call_usd",
        }:
            raise ValueError("invalid limits")
        for name in ("result_bytes", "memory_bytes", "disk_bytes"):
            if name in self.limits and (type(self.limits[name]) is not int or self.limits[name] < 512):
                raise ValueError("invalid resource limit")
        data = json.dumps(asdict(self), sort_keys=True, allow_nan=False).encode()
        if len(data) > (MAX_COMMAND_BYTES if self.name == "prepare_verification" else 65536):
            raise ValueError("command too large")
        return data
 def _bounded(result: dict[str, Any], maximum: int) -> dict[str, Any]:
    result = copy.deepcopy(result)
    if len(json.dumps(result).encode()) <= maximum:
        return result
    result["truncated"] = True
    # Preserve structured evidence when possible; otherwise make loss explicit.
    while len(json.dumps(result).encode()) > maximum:
        fields = [(len(v), k) for k, v in result.items() if isinstance(v, (str, list)) and k not in {"status", "error", "isolation_mode"}]
        if not fields or max(fields)[0] == 0:
            return {"seq": result["seq"], "error": "result_limit", "truncated": True}
        _, key = max(fields)
        keep = len(result[key]) // 2
        result[key] = result[key][-keep:] if key == "stderr" and keep else result[key][:keep]
    return result
 class InProcessExecutor:
    """Test adapter; task_boundary is only enabled by the key-free task entrypoint."""
    def __init__(self, repo: Path, demo: Path | None = None, *, task_boundary: bool = False) -> None:
        self.repo = repo.resolve()
        if not self.repo.is_dir():
            raise ValueError("checkout unavailable")
        self.demo = demo
        self.task_boundary = task_boundary
        self.seq = 0
        self.stopped = False
        self.last_digest = ""
        self.last_result: dict[str, Any] = {}
        self.isolation_mode = "unprobed"
        self.prepared_put_url: str | None = None
        self.prepared_part_urls: list[str] = []
    def submit(
        self, name: str, args: dict[str, Any], *, timeout_seconds: float = 30, limits: dict[str, Any] | None = None
    ) -> dict[str, Any]:
        result = self.execute(Command(self.seq + 1, name, args, timeout_seconds, limits or {}))
        if result.get("error") in {"ValueError", "KeyError", "TypeError", "FileNotFoundError", "OSError"}:
            raise ValueError(result.get("reason", "repository command rejected"))
        return result
    def execute(self, command: Command) -> dict[str, Any]:
        digest = hashlib.sha256(command.validate()).hexdigest()
        if command.seq == self.seq:
            if digest != self.last_digest:
                raise ValueError("retry changed command")
            return copy.deepcopy(self.last_result)
        if self.stopped:
            raise ValueError("executor stopped")
        if command.seq != self.seq + 1:
            raise ValueError("out of order sequence")
        started = time.monotonic()
        self.deadline = started + command.timeout_seconds
        self.phase = "run"
        try:
            result = self._execute(command)
        except task_storage.ScratchLimit as exc:
            self.stopped = True
            result = {
                "status": "could_not_build",
                "reason": task_storage.exception_reason(exc, private=(str(self.repo), self.repo.name)),
                "phase": "scratch guard",
                "exit_code": None,
                "stderr": "",
                "stopped": True,
            }
        except (ValueError, OSError, KeyError, TypeError, TimeoutError, subprocess.SubprocessError) as exc:
            result = {
                "error": type(exc).__name__,
                "reason": task_storage.exception_reason(exc, private=(str(self.repo), self.repo.name)),
                "phase": self.phase,
                "exit_code": None,
                "stderr": "",
                "timed_out": isinstance(exc, TimeoutError),
            }
        result["wall_seconds"] = time.monotonic() - started
        result = _bounded({"seq": command.seq, **result}, min(MAX_RESULT_BYTES, command.limits.get("result_bytes", MAX_RESULT_BYTES)))
        self.seq, self.last_digest, self.last_result = command.seq, digest, copy.deepcopy(result)
        return result
    def _remaining(self) -> float:
        remaining = self.deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("executor deadline")
        return remaining
    def _path(self, value: str) -> Path:
        if not isinstance(value, str) or not value or "\0" in value:
            raise ValueError("invalid path")
        path = Path(value)
        if path.is_absolute() or ".." in path.parts or ".git" in path.parts:
            raise ValueError("path escapes checkout")
        result = self.repo / path
        if any(p.is_symlink() for p in [result, *result.parents] if p.is_relative_to(self.repo)):
            raise ValueError("symlink refused")
        if not result.resolve().is_relative_to(self.repo):
            raise ValueError("path escapes checkout")
        return result
    def _files(self) -> Iterator[Path]:
        for parent, directories, names in os.walk(self.repo, followlinks=False):
            self._remaining()
            directories[:] = sorted(d for d in directories if d != ".git" and not (Path(parent) / d).is_symlink())
            for name in sorted(names):
                self._remaining()
                path = Path(parent) / name
                if stat.S_ISREG(path.lstat().st_mode):
                    yield path
    def _read(self, path: Path) -> bytes:
        # O_NOFOLLOW closes the final-component symlink race; repository programs
        # are terminated before the next command so there are no concurrent writers.
        fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW)
        with os.fdopen(fd, "rb") as stream:
            if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
                raise ValueError("regular file required")
            return stream.read(1024 * 1024)
    def _execute(self, command: Command) -> dict[str, Any]:
        name, args = command.name, command.args
        if self.task_boundary:
            self.phase = "scratch guard"
            task_storage.check(task_storage.WORKSPACE if task_storage.WORKSPACE.is_dir() else self.repo)
            self.phase = "run"
        if name == "prepare_verification":
            return self._prepare_verification(args, command.limits)
        if name == "stop":
            self.stopped = True
            return {"stopped": True}
        if name == "list_files":
            files = []
            for path in self._files():
                files.append(str(path.relative_to(self.repo)))
                if len(files) == 1000:
                    break
            return {"files": files}
        if name == "read_file":
            path = self._path(args["path"])
            data = self._read(path)
            start = max(1, int(args.get("start", 1)))
            lines = min(400, max(1, int(args.get("lines", 400))))
            text = "\n".join(data.decode(errors="replace").splitlines()[start - 1 : start - 1 + lines])
            return {"text": text[:16384], "input_bytes": len(data), "truncated": len(text) > 16384 or path.stat().st_size > len(data)}
        if name == "grep":
            pattern = args["pattern"]
            if not isinstance(pattern, str) or not pattern:
                raise ValueError("nonempty pattern required")
            matches = []
            for index, path in enumerate(self._files()):
                if index >= 10000:
                    break
                for number, line in enumerate(self._read(path).decode(errors="replace").splitlines(), 1):
                    if pattern in line:
                        matches.append({"path": str(path.relative_to(self.repo)), "line": number, "text": line[:200]})
                        if len(matches) == 200:
                            return {"matches": matches}
            return {"matches": matches}
        argv = args["command"]
        if not isinstance(argv, list) or not argv or not all(isinstance(v, str) and "\0" not in v for v in argv):
            raise ValueError("command must be argv")
        timeout = min(self._remaining(), max(1, int(args.get("timeout_seconds", 30))))
        self.deadline = min(self.deadline, time.monotonic() + timeout)
        if self.task_boundary:
            self.isolation_mode = "task-boundary"
            return self._task_run(argv, timeout, command.limits)
        _sandbox.isolation_check(timeout_seconds=self._remaining())
        self.isolation_mode = _sandbox.isolation_mode()
        with tempfile.TemporaryDirectory(prefix="ousast-executor-") as directory:
            result = _sandbox.run(
                SandboxJob(
                    "",
                    tuple(argv),
                    self.repo,
                    {},
                    max(1, math.ceil(min(timeout, self._remaining()))),
                    max(1, command.limits.get("memory_bytes", SearchBudget().memory_bytes) // 1024**2),
                    128,
                ),
                scratch=Path(directory),
                mounts={"/demo": self.demo} if self.demo else {},
                scratch_bytes=command.limits.get("disk_bytes", task_storage.DEFAULT_SCRATCH_BYTES),
                wall_timeout_seconds=self._remaining(),
            )
        return {
            **(
                {
                    "phase": "timeout" if result.timed_out else "run",
                    "reason": "TimeoutError: command deadline" if result.timed_out else f"CommandFailure: exit code {result.exit_code}",
                }
                if result.timed_out or result.exit_code
                else {}
            ),
            "isolation_mode": self.isolation_mode,
            "exit_code": result.exit_code,
            "stdout": result.stdout[:16384],
            "stderr": task_storage.diagnostic(result.stderr, maximum=1500),
            "timed_out": result.timed_out,
            "truncated": len(result.stdout) > 16384 or len(result.stderr) > 16384,
        }
    def _task_run(self, argv: list[str], timeout: float, limits: dict[str, Any], *, cwd: Path | None = None) -> dict[str, Any]:
        process_limit = None
        try:
            uid = os.getuid()
            current = 0
            for entry in Path("/proc").iterdir():
                if not entry.name.isdecimal():
                    continue
                try:
                    status = (entry / "status").read_text()
                except FileNotFoundError:
                    continue
                fields = dict(line.split(":", 1) for line in status.splitlines() if ":" in line)
                # The kernel's NPROC counter counts threads, not processes: a single IDE or agent
                # process with 60 threads uses 60 of the allowance.
                if int(fields["Uid"].split()[0]) == uid:
                    current += int(fields.get("Threads", "1").strip() or 1)
            process_limit = current + 256
        except (OSError, ValueError, IndexError, StopIteration):
            pass
        def constrain() -> None:
            resource.setrlimit(resource.RLIMIT_FSIZE, (limits.get("disk_bytes", task_storage.DEFAULT_SCRATCH_BYTES),) * 2)
            # NPROC counts all processes of the real uid, so an absolute 128 blocks builds on busy hosts.
            if process_limit is not None:
                resource.setrlimit(resource.RLIMIT_NPROC, (process_limit,) * 2)
            if "memory_bytes" in limits:
                resource.setrlimit(resource.RLIMIT_AS, (limits["memory_bytes"],) * 2)
            resource.setrlimit(resource.RLIMIT_CPU, (math.ceil(timeout) + 1,) * 2)
        timeout = min(timeout, self._remaining())
        initial_bytes = self._tree_bytes()
        guard_root = task_storage.WORKSPACE if task_storage.WORKSPACE.is_dir() else self.repo
        peak_bytes = task_storage.check(guard_root)
        self.phase = "spawn"
        with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
            proc = subprocess.Popen(
                argv, cwd=cwd or self.repo, env=clean_environment(), stdout=out, stderr=err, start_new_session=True, preexec_fn=constrain
            )
            self.phase = "run"
            timed_out = False
            disk_exceeded = False
            failure: Exception | None = None
            # Monitor the full disk-backed workspace, including package caches.
            # An unnamespaced child can still hardcode RAM-backed paths: this
            # guard is not a replacement for the operator's memory limit.
            try:
                while True:
                    peak_bytes = max(
                        peak_bytes,
                        task_storage.check(guard_root, additional_bytes=os.fstat(out.fileno()).st_size + os.fstat(err.fileno()).st_size),
                    )
                    if self._tree_bytes() - initial_bytes > limits.get("disk_bytes", task_storage.DEFAULT_SCRATCH_BYTES):
                        disk_exceeded = True
                        break
                    try:
                        proc.wait(timeout=min(0.05, self._remaining()))
                        peak_bytes = max(
                            peak_bytes,
                            task_storage.check(
                                guard_root, additional_bytes=os.fstat(out.fileno()).st_size + os.fstat(err.fileno()).st_size
                            ),
                        )
                        if self._tree_bytes() - initial_bytes > limits.get("disk_bytes", task_storage.DEFAULT_SCRATCH_BYTES):
                            disk_exceeded = True
                        break
                    except subprocess.TimeoutExpired:
                        self._remaining()
            except task_storage.ScratchLimit as exc:
                disk_exceeded = True
                failure = exc
                self.stopped = True
            except TimeoutError as exc:
                timed_out = True
                failure = exc
            except OSError as exc:
                self.phase = "scratch guard"
                failure = exc
            finally:
                with suppress(ProcessLookupError):
                    os.killpg(proc.pid, signal.SIGKILL)
                proc.wait()
            out.seek(0)
            err.seek(max(0, os.fstat(err.fileno()).st_size - 16384))
            stderr = task_storage.diagnostic(err.read().decode(errors="replace"), maximum=1500)
            phase = "scratch guard" if disk_exceeded else "timeout" if timed_out else self.phase
            if disk_exceeded:
                self.stopped = True
            failed = failure or (task_storage.ScratchLimit("scratch limit") if disk_exceeded else None)
            reason = (
                task_storage.exception_reason(failed)
                if failed
                else (f"CommandFailure: exit code {proc.returncode}" if proc.returncode else "")
            )
            return {
                **({"status": "could_not_build", "stopped": self.stopped} if disk_exceeded else {}),
                **({"reason": reason, "phase": phase} if reason else {}),
                **({"error": type(failure).__name__} if failure and not (timed_out or disk_exceeded) else {}),
                "isolation_mode": "task-boundary",
                "exit_code": proc.returncode,
                "timed_out": timed_out,
                "disk_limit_exceeded": disk_exceeded,
                "aggregate_disk_isolation": "outer-task-quota-required",
                "scratch_peak_bytes": peak_bytes,
                "stdout_bytes": os.fstat(out.fileno()).st_size,
                "stderr_bytes": os.fstat(err.fileno()).st_size,
                "stdout": out.read(16384).decode(errors="replace"),
                "stderr": stderr,
                "truncated": os.fstat(out.fileno()).st_size > 16384 or os.fstat(err.fileno()).st_size > 16384,
            }
    def _prepare_verification(self, spec: dict[str, Any], limits: dict[str, Any]) -> dict[str, Any]:
        """Build and export through the host-scoped output URL, never a model URL."""
        import shutil
        from .demo import preparation_command, validate_demo
        from .verify import _tree
        from .verify_task import MAX_PART_BYTES, ArchiveLimit, bundle_ignore, pack_checkout, upload_parts, validate_spec
        if not self.task_boundary or not self.prepared_put_url:
            raise ValueError("preparation requires an executor task output")
        spec = copy.deepcopy(spec)
        validate_demo(spec["demo"], checkout=self.repo)
        recipe = spec["demo"]["build"]
        spec["demo"]["build"] = {"recipe": "none", "arguments": []}
        validate_spec(spec)
        with tempfile.TemporaryDirectory(prefix="ousast-built-") as directory:
            bundle = Path(directory)
            products = bundle / "products"
            products.mkdir()
            phases = {"build": 0.0, "bundle": 0.0, "upload": 0.0}
            built = {"exit_code": 0, "stderr": ""}
            before = time.monotonic()
            if recipe["recipe"] != "none":
                path = self._path(recipe["arguments"][0])
                argv, project = preparation_command(recipe["recipe"], path, self.repo, products)
                if argv[:2] == ["npm", "install"] and (self.repo / ".git").exists():
                    # Lockless old projects should resolve dependencies from their era.
                    # Metadata is optional; unavailable git must not prevent a build.
                    with suppress(OSError, subprocess.SubprocessError, UnicodeError):
                        commit_date = subprocess.run(
                            ["git", "-C", str(project), "show", "-s", "--format=%cI", "HEAD"],
                            check=True,
                            capture_output=True,
                            text=True,
                            env=clean_environment(),
                            timeout=min(5, self._remaining()),
                        ).stdout.strip()
                        if commit_date:
                            argv.extend(["--before", commit_date])
                self.phase = "build"
                built = self._task_run(argv, self._remaining(), {"disk_bytes": task_storage.DEFAULT_SCRATCH_BYTES, **limits}, cwd=project)
                phases["build"] = time.monotonic() - before
                if built.get("disk_limit_exceeded") or built["exit_code"] or built["timed_out"]:
                    return {
                        **built,
                        "status": "could_not_build",
                        "wall_seconds_by_phase": phases,
                        "phase": "build",
                        "stderr": task_storage.diagnostic(built.get("stderr", ""), maximum=1500),
                    }
            before = time.monotonic()
            # Validate internal generated links before materializing them as
            # regular archive members. No host/external files may be exported.
            _tree(self.repo, generated_links=True)
            _tree(products, generated_links=True)
            shutil.copytree(self.repo, bundle / "checkout", symlinks=False, ignore=bundle_ignore)
            materialized = bundle / "materialized"
            shutil.copytree(products, materialized, symlinks=False, ignore=bundle_ignore)
            shutil.rmtree(products)
            materialized.rename(products)
            (bundle / "spec.json").write_text(json.dumps(spec))
            task_storage.check(task_storage.WORKSPACE if task_storage.WORKSPACE.is_dir() else bundle)
            # The task entrypoint configures tempfile under disk-backed /workspace.
            spool_root = task_storage.WORKSPACE if task_storage.WORKSPACE.is_dir() else bundle.parent
            with tempfile.TemporaryFile(dir=spool_root) as archive:
                self.phase = "build export"
                try:
                    pack_checkout(bundle, archive)
                except ArchiveLimit as exc:
                    return {"status": "could_not_build", "phase": self.phase, "reason": str(exc), "archive_bytes": exc.archive_bytes}
                size = archive.tell()
                task_storage.check(spool_root, additional_bytes=size)
                archive.seek(0)
                digest = hashlib.file_digest(archive, "sha256").hexdigest()
                archive.seek(0)
                phases["bundle"] = time.monotonic() - before
                before = time.monotonic()
                self.phase = "result upload"
                if self.prepared_part_urls:
                    manifest = upload_parts(
                        archive, lambda url, block: URLTransport().put(url, block, self._remaining()), self.prepared_part_urls
                    )
                    URLTransport().put(self.prepared_put_url, manifest, self._remaining())
                    digest = hashlib.sha256(manifest).hexdigest()
                elif size <= MAX_PART_BYTES:
                    URLTransport().put(self.prepared_put_url, archive, self._remaining())
                else:
                    raise ValueError("multipart archive URLs required")
                phases["upload"] = time.monotonic() - before
                return {
                    "status": "ok",
                    "archive_bytes": size,
                    "sha256": digest,
                    "archive_parts": len(json.loads(manifest)["parts"]) if self.prepared_part_urls else 1,
                    "exit_code": built["exit_code"],
                    "stderr": task_storage.diagnostic(built.get("stderr", ""), maximum=1500),
                    "wall_seconds_by_phase": phases,
                }
    def _tree_bytes(self) -> int:
        total = 0
        for parent, directories, names in os.walk(self.repo, followlinks=False):
            self._remaining()
            directories[:] = [name for name in directories if not (Path(parent) / name).is_symlink()]
            for name in names:
                with suppress(OSError):
                    info = (Path(parent) / name).lstat()
                    if stat.S_ISREG(info.st_mode):
                        total += info.st_size
        return total
 class Transport(Protocol):
    def get(self, url: str, timeout: float) -> bytes | None: ...
    def put(self, url: str, data: bytes | BinaryIO, timeout: float) -> None: ...
 class URLTransport:
    """Only presigned object URLs; redirects are refused to preserve their scope."""
    def __init__(self) -> None:
        class NoRedirect(urllib.request.HTTPRedirectHandler):
            def redirect_request(self, *args: Any, **kwargs: Any) -> None:
                return None
        self.opener = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect())
    def get(self, url: str, timeout: float) -> bytes | None:
        try:
            with self.opener.open(url, timeout=timeout) as response:
                data = bytes(response.read(max(MAX_RESULT_BYTES, MAX_COMMAND_BYTES) + 1))
                if len(data) > max(MAX_RESULT_BYTES, MAX_COMMAND_BYTES):
                    raise ValueError("mailbox object too large")
                return data
        except urllib.error.HTTPError as exc:
            if exc.code == 404:
                return None
            raise
    def put(self, url: str, data: bytes | BinaryIO, timeout: float) -> None:
        headers = {"Content-Type": "application/json"}
        if not isinstance(data, bytes):
            headers["Content-Length"] = str(os.fstat(data.fileno()).st_size)
        with self.opener.open(urllib.request.Request(url, data=data, method="PUT", headers=headers), timeout=timeout):
            pass
 RETRY_SECONDS = 90.0
 def retry_mailbox(operation: Any, *, deadline: float | None = None) -> Any:
    """Retry transient store failures; each attempt has a bounded socket timeout."""
    end = min(time.monotonic() + RETRY_SECONDS, deadline if deadline is not None else float("inf"))
    delay = 0.2
    while True:
        try:
            return operation(max(0.001, min(10, end - time.monotonic())))
        except (OSError, TimeoutError) as exc:
            if isinstance(exc, urllib.error.HTTPError) and not 500 <= exc.code < 600:
                raise
            if time.monotonic() >= end:
                raise
            time.sleep(min(delay, max(0, end - time.monotonic())))
            delay = min(delay * 2, 5)
 class ObjectStoreExecutor:
    def __init__(self, command_put_url: str, result_get_url: str, *, transport: Transport | None = None, poll_seconds: float = 0.2) -> None:
        for url in (command_put_url, result_get_url):
            parts = urlsplit(url)
            if parts.scheme != "https" or not parts.hostname or parts.username or parts.password:
                raise ValueError("HTTPS presigned URLs required")
        self.command_url, self.result_url = command_put_url, result_get_url
        self.transport = transport or URLTransport()
        self.poll_seconds = poll_seconds
        self.seq = 0
        self.uncertain = False
        self.pending: Command | None = None
        self.isolation_mode = "remote-executor"
    def submit(
        self, name: str, args: dict[str, Any], *, timeout_seconds: float = 30, limits: dict[str, Any] | None = None
    ) -> dict[str, Any]:
        command = Command(self.seq + 1, name, args, timeout_seconds, limits or {})
        if self.pending is not None:
            if (name, args, limits or {}) != (self.pending.name, self.pending.args, self.pending.limits):
                raise RuntimeError("previous command outcome uncertain; retry the same command")
            command = self.pending
        payload = command.validate()
        end = time.monotonic() + timeout_seconds
        self.uncertain = True
        self.pending = copy.deepcopy(command)
        retry_end = end + RETRY_SECONDS
        last_error = ""
        phase = "result upload"
        uploaded = False
        while time.monotonic() < end:
            try:
                before = time.monotonic()
                try:
                    if not uploaded:
                        # Retry lost acknowledgements internally; successful delivery needs no further PUTs.
                        phase = "command upload"
                        retry_mailbox(lambda timeout: self.transport.put(self.command_url, payload, timeout), deadline=retry_end)
                        uploaded = True
                    phase = "result read"
                    raw = retry_mailbox(lambda timeout: self.transport.get(self.result_url, timeout), deadline=retry_end)
                finally:
                    end = min(retry_end, end + time.monotonic() - before)
                if raw is not None:
                    if len(raw) > MAX_RESULT_BYTES:
                        raise ValueError("result too large")
                    result = json.loads(raw)
                    if not isinstance(result, dict) or type(result.get("seq")) is not int:
                        raise ValueError("invalid result envelope")
                    if result["seq"] > command.seq:
                        raise ValueError("future result sequence")
                    if result["seq"] == command.seq:
                        self.seq, self.uncertain = command.seq, False
                        self.pending = None
                        self.isolation_mode = result.get("isolation_mode", self.isolation_mode)
                        return result
            except (OSError, TimeoutError) as exc:
                if isinstance(exc, urllib.error.HTTPError) and not 500 <= exc.code < 600:
                    raise
                last_error = task_storage.exception_reason(exc)
                break
            time.sleep(min(self.poll_seconds, max(0, end - time.monotonic())))
        raise TimeoutError(f"executor {phase} deadline; {last_error or 'no result received'}")
 def serve(
    executor: InProcessExecutor,
    command_get_url: str,
    result_put_url: str,
    *,
    transport: Transport | None = None,
    deadline_seconds: float = 900,
    poll_seconds: float = 0.2,
 ) -> None:
    transport = transport or URLTransport()
    end = time.monotonic() + deadline_seconds
    while time.monotonic() < end:
        try:
            raw = retry_mailbox(lambda timeout: transport.get(command_get_url, timeout), deadline=end)
            if raw is not None:
                if len(raw) > MAX_COMMAND_BYTES:
                    raise ValueError("command too large")
                command = Command(**json.loads(raw))
                if command.seq != executor.seq and command.timeout_seconds > end - time.monotonic():
                    raise TimeoutError("command exceeds task lifetime")
                result = executor.execute(command)
                retry_mailbox(
                    lambda timeout, result=result: transport.put(result_put_url, json.dumps(result).encode(), timeout), deadline=end
                )
                if result.get("stopped"):
                    return
        except (OSError, TimeoutError) as exc:
            if executor.last_result:
                executor.last_result["result_upload_reason"] = task_storage.exception_reason(exc)
                executor.last_result["result_upload_phase"] = "result upload"
            raise
        time.sleep(min(poll_seconds, max(0, end - time.monotonic())))
    raise TimeoutError("executor task deadline")
 def unpack_checkout(data: bytes, root: Path) -> None:
    """Bounded regular-file archive only; no links, special files, or metadata."""
    if len(data) > 128 * 1024**2:
        raise ValueError("checkout archive too large")
    root.mkdir(parents=True, exist_ok=False)
    with tarfile.open(fileobj=io.BytesIO(data), mode="r:*") as archive:
        total = 0
        for index, member in enumerate(archive):
            path = Path(member.name)
            total += member.size
            if (
                index >= 100000
                or total > 256 * 1024**2
                or path.is_absolute()
                or ".." in path.parts
                or ".git" in path.parts
                or not (member.isfile() or member.isdir())
            ):
                raise ValueError("unsafe checkout archive")
            destination = root / path
            if member.isdir():
                destination.mkdir(parents=True, exist_ok=True)
            else:
                destination.parent.mkdir(parents=True, exist_ok=True)
                source = archive.extractfile(member)
                if source is None:
                    raise ValueError("archive member is not a regular file")
                with source, destination.open("xb") as target:
                    while chunk := source.read(65536):
                        target.write(chunk)
                destination.chmod(0o755 if member.mode & 0o111 else 0o644)
 def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--repo", type=Path, required=True)
    parser.add_argument("--command-get-url")
    parser.add_argument("--result-put-url")
    parser.add_argument("--deadline", type=float, default=900)
    parser.add_argument("--task-boundary", action="store_true")
    args = parser.parse_args()
    command_url = args.command_get_url or os.environ.get("COMMAND_GET_URL")
    result_url = args.result_put_url or os.environ.get("EXECUTOR_RESULT_PUT_URL")
    repo_url = os.environ.get("REPO_URL")
    prepared_url = os.environ.get("PREPARED_PUT_URL")
    prepared_parts = json.loads(os.environ.get("PREPARED_PART_URLS", "[]"))
    # Clearing Python's environment cannot remove initial /proc/self/environ.
    # Refuse a misconfigured task before any repository input is opened.
    inherited = sorted(
        key
        for key, value in os.environ.items()
        if value and any(word in key.upper() for word in ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL"))
    )
    if inherited:
        # Names only, never values, so a misconfigured task can be diagnosed from the worker log.
        raise SystemExit("executor refuses inherited credentials: " + ", ".join(inherited))
    scratch_limit = task_storage.configure()
    os.environ.clear()
    os.environ.update(clean_environment())
    os.environ["OUSAST_SCRATCH_BYTES"] = str(scratch_limit)
    if not command_url or not result_url:
        raise SystemExit("executor requires presigned mailbox URLs")
    if repo_url:
        from .verify_task import download
        unpack_checkout(download(repo_url, 128 * 1024**2, readiness_budget=min(60, args.deadline)), args.repo)
    executor = InProcessExecutor(args.repo, task_boundary=args.task_boundary)
    executor.prepared_put_url = prepared_url
    executor.prepared_part_urls = prepared_parts
    serve(executor, command_url, result_url, deadline_seconds=args.deadline)
 if __name__ == "__main__":
    main()
@@ -0,0 +1,347 @@
 """Owned canaries. Only app captures enter these oracles, never attack output.
 The attacker may supply CLI arguments through TARGET. Fixtures and app config
 are mounted only in the app sandbox. Nonces are fresh per run and absent from
 artefact env. A browser executor is trusted verifier code, never a demo script.
 """
 from __future__ import annotations
 import json
 import os
 import secrets
 import selectors
 import shutil
 import sqlite3
 import subprocess
 import tempfile
 from collections.abc import Callable
 from dataclasses import dataclass
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import Protocol
 from urllib.parse import quote
 if __name__ != "__main__":
    from . import _sandbox
@dataclass(frozen=True)
 class Canary:
    root: Path
    nonce: str
    @classmethod
    def fresh(cls, root: Path) -> Canary:
        root.mkdir(mode=0o700)
        return cls(root, secrets.token_hex(24))
@dataclass(frozen=True)
 class ControlProbe:
    """A benign interaction a correctly functioning app must answer by returning
    ``token`` in its response body. It proves the demo's interface is wired and the
    app can serve before any absence of the secret effect is trusted as a negative."""
    method: str
    path: str
    token: str
    body: str = ""
 class Oracle(Protocol):
    namespace_pid: int | None
    placeholders: dict[str, str]
    def prepare(self, canary: Canary) -> dict[str, str]: ...
    def capture(self, output: str) -> None: ...
    def observe(self) -> tuple[bool, str]: ...
    def control(self) -> ControlProbe | None: ...
    def close(self) -> None: ...
 class OutputOracle:
    namespace_pid: int | None = None
    def prepare(self, canary: Canary) -> dict[str, str]:
        self.canary = canary
        self.seen = False
        self.placeholders: dict[str, str] = {}
        return {}
    def capture(self, output: str) -> None:
        self.seen |= self.canary.nonce in output
    def observe(self) -> tuple[bool, str]:
        return self.seen, "canary in verifier-captured app output" if self.seen else "no canary in app output"
    def control(self) -> ControlProbe | None:
        # No positive control by default. SQL/command/ssrf/xss controls are a
        # documented follow-up; only the path oracle plants one for now.
        return None
    def close(self) -> None:
        pass
 class PathOracle(OutputOracle):
    control_name = "control"
    def prepare(self, canary: Canary) -> dict[str, str]:
        super().prepare(canary)
        (canary.root / "public").mkdir()
        (canary.root / "canary").write_text(canary.nonce)
        (canary.root / "canary").chmod(0o600)
        # Parent canary covers classic traversal; this sibling covers prefix checks
        # using startswith without a separator.
        (canary.root / "public_leak").write_text(canary.nonce)
        (canary.root / "public_leak").chmod(0o600)
        # A benign in-root control file, distinct from the out-of-root secret, so a
        # correctly serving app returns it on BOTH revisions without any traversal.
        # Drawn from os.urandom, not secrets.token_hex, so it never perturbs callers
        # that monkeypatch the nonce source and count its draws.
        self.control_token = os.urandom(24).hex()
        control_file = canary.root / "public" / self.control_name
        control_file.write_text(self.control_token)
        control_file.chmod(0o600)
        self.placeholders = {"served_root": "/fixture/public"}
        return {"SERVED_ROOT": "/fixture/public"}
    def control(self) -> ControlProbe | None:
        return ControlProbe(method="GET", path="/" + self.control_name, token=self.control_token)
 class SQLOracle(OutputOracle):
    def prepare(self, canary: Canary) -> dict[str, str]:
        super().prepare(canary)
        with sqlite3.connect(canary.root / "fixture.db") as db:
            db.execute("CREATE TABLE records (name TEXT, value TEXT, public INTEGER)")
            db.executemany("INSERT INTO records VALUES (?, ?, ?)", [("ordinary", "public value", 1), ("secret", canary.nonce, 0)])
        (canary.root / "fixture.db").chmod(0o600)
        self.placeholders = {"database_path": "/fixture/fixture.db", "database_url": "sqlite:////fixture/fixture.db"}
        return {"DATABASE": "/fixture/fixture.db"}
 class CommandOracle(OutputOracle):
    def prepare(self, canary: Canary) -> dict[str, str]:
        super().prepare(canary)
        # Marker is in app-only writable scratch, inaccessible in artefact sandbox.
        self.marker = canary.root / "marker"
        self.placeholders = {"marker_dir": "/scratch"}
        return {}
    def observe(self) -> tuple[bool, str]:
        observed = self.marker.is_file() and not self.marker.is_symlink()
        return observed, "injected command marker exists" if observed else "no command marker"
 class SSRFOracle(OutputOracle):
    """Separate listener process and private loopback namespace; no external egress."""
    task_boundary = False
    process: subprocess.Popen[str] | None = None
    def prepare(self, canary: Canary) -> dict[str, str]:
        super().prepare(canary)
        self.process = subprocess.Popen(
            [
                *(
                    []
                    if self.task_boundary
                    else ["/usr/bin/unshare", *(["--user", "--map-root-user"] if _sandbox.isolation_mode() == "userns" else []), "--net"]
                ),
                "/usr/bin/python3",
                "-I",
                str(Path(__file__).resolve()),
                "--task-listener" if self.task_boundary else "--listener",
                canary.nonce,
            ],
            stdout=subprocess.PIPE,
            stderr=subprocess.DEVNULL,
            text=True,
            env={"PATH": "/usr/bin:/bin"},
        )
        assert self.process.stdout is not None
        with selectors.DefaultSelector() as selector:
            selector.register(self.process.stdout, selectors.EVENT_READ)
            if not selector.select(3):
                raise OSError("listener namespace readiness timed out")
            line = self.process.stdout.readline()
        if not line:
            raise OSError("private loopback listener unavailable")
        self.namespace_pid, port = json.loads(line)
        if self.task_boundary:
            self.namespace_pid = None
        self.placeholders = {"callback_url": f"http://127.0.0.1:{port}/{canary.nonce}"}  # loopback: private oracle listener
        return {"CALLBACK_URL": self.placeholders["callback_url"]}
    def observe(self) -> tuple[bool, str]:
        assert self.process is not None and self.process.stdout is not None
        with selectors.DefaultSelector() as selector:
            selector.register(self.process.stdout, selectors.EVENT_READ)
            observed = bool(selector.select(0.2)) and self.process.stdout.readline().strip() == "observed"
        return observed, "nonce request received" if observed else "no nonce request"
    def close(self) -> None:
        if self.process is not None:
            self.process.terminate()
            self.process.wait(timeout=3)
            if self.process.stdout:
                self.process.stdout.close()
 class BrowserExecutor:
    """Run captured HTML with a verifier-owned alert canary.
    Payloads call alert("ousast-xss"). Reflection/escaped HTML cannot set the fresh
    DOM marker. A restrictive CSP disables external resources and connections;
    Chromium's sandbox stays enabled for userns; root containers use the outer
    boundary and drop the browser uid. Each capture uses a fresh profile.
    Launch failures are unavailable execution, never a negative observation.
    """
    def __init__(self, binary: str | None = None, *, timeout_seconds: float = 15, task_boundary: bool = False) -> None:
        selected = binary or shutil.which("chromium") or shutil.which("chromium-browser")
        self.timeout_seconds = timeout_seconds
        if not selected:
            raise OSError("headless chromium unavailable")
        self.binary: str = selected
        self.task_boundary = task_boundary
        self.no_sandbox = task_boundary or _sandbox.isolation_mode() == "root-no-userns"
    def __call__(self, document: str, nonce: str) -> bool:
        marker = secrets.token_hex(24)
        # Neither the marker nor its attribute appears in app output. The bootstrap
        # source does appear in dump-dom, so inspect an actual DOM attribute only.
        attribute = "data-proof-" + secrets.token_hex(12)
        prelude = (
            '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; '
            "script-src 'unsafe-inline'; base-uri 'none'; form-action 'none'\">"
            '<script>window.alert=function(value){if(value==="ousast-xss"||value==='
            + json.dumps(nonce)
            + "){document.documentElement.setAttribute("
            + json.dumps(attribute)
            + ","
            + json.dumps(marker)
            + ");}};</script>"
        )
        with tempfile.TemporaryDirectory(prefix="ousast-browser-") as profile:
            # HTML can navigate even with CSP. A private network namespace, not
            # browser flags, is the no-egress boundary. Expose runtime only.
            if not self.task_boundary:
                _sandbox.writable_directory(Path(profile))
            namespaces = ["--unshare-pid", "--unshare-ipc", "--unshare-uts", "--unshare-net"] if self.no_sandbox else ["--unshare-all"]
            sandbox = ["bwrap", *namespaces, "--die-with-parent", "--new-session", *_sandbox.capability_args()]
            for path in ("/usr", "/bin", "/lib", "/lib64"):
                if Path(path).exists():
                    sandbox += ["--ro-bind", path, path]
            sandbox += [
                "--dev",
                "/dev",
                "--proc",
                "/proc",
                "--tmpfs",
                "/tmp",
                "--bind",
                profile,
                "/profile",
                "--setenv",
                "HOME",
                "/profile",
                "--",
            ]
            if self.task_boundary:
                sandbox = []
            try:
                done = subprocess.run(
                    [
                        *sandbox,
                        *(_sandbox.drop_privileges() if self.no_sandbox and not self.task_boundary else []),
                        self.binary,
                        *(["--no-sandbox"] if self.no_sandbox else []),
                        "--headless",
                        "--dump-dom",
                        "--disable-gpu",
                        "--disable-background-networking",
                        "--disable-extensions",
                        "--no-first-run",
                        "--no-default-browser-check",
                        "--disable-sync",
                        "--user-data-dir=" + (profile if self.task_boundary else "/profile"),
                        "--virtual-time-budget=1000",
                        "data:text/html;charset=utf-8," + quote(prelude + document),
                    ],
                    capture_output=True,
                    text=True,
                    timeout=self.timeout_seconds,
                    env={"PATH": "/usr/bin:/bin", "HOME": profile},
                )
            except subprocess.SubprocessError as exc:
                raise OSError("headless chromium failed") from exc
        if done.returncode or "<html" not in done.stdout.lower():
            raise OSError("headless chromium did not produce a document: " + done.stderr[-500:])
        class Marker(HTMLParser):
            seen = False
            def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
                if tag == "html" and (attribute, marker) in attrs:
                    self.seen = True
        parser = Marker()
        parser.feed(done.stdout)
        return parser.seen
 Browser = Callable[[str, str], bool]
 class XSSOracle(OutputOracle):
    def __init__(self, executor: Browser) -> None:
        self.executor = executor
    def capture(self, output: str) -> None:
        self.seen |= self.executor(output, self.canary.nonce)
 def oracle_for(family: str, browser: Browser | None = None) -> Oracle | None:
    factories = {"path": PathOracle, "sql": SQLOracle, "command": CommandOracle, "ssrf": SSRFOracle}
    if family == "xss":
        return XSSOracle(browser) if browser else None
    factory = factories.get(family)
    return factory() if factory else None
 def _listen(nonce: str, *, task_boundary: bool = False) -> None:
    import fcntl
    import socket
    import struct
    from http.server import BaseHTTPRequestHandler, HTTPServer
    # unshare created only loopback; bring it up without iproute2 or any egress.
    if not task_boundary:
        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
            fcntl.ioctl(sock, 0x8914, struct.pack("16sH14s", b"lo", 0x49, b""))
    class Handler(BaseHTTPRequestHandler):
        def do_GET(self) -> None:
            if self.path.split("?", 1)[0] == "/" + nonce:
                print("observed", flush=True)
            self.send_response(200)
            self.end_headers()
            self.wfile.write(b"ok")
        do_POST = do_PUT = do_PATCH = do_DELETE = do_HEAD = do_OPTIONS = do_TRACE = do_CONNECT = do_GET
        def log_message(self, format: str, *args: object) -> None:
            pass
    with HTTPServer(("127.0.0.1", 0), Handler) as server:
        print(json.dumps([os.getpid(), server.server_port]), flush=True)
        server.serve_forever()
 if __name__ == "__main__":
    import sys
    _listen(sys.argv[2], task_boundary=sys.argv[1] == "--task-listener")
@@ -0,0 +1,261 @@
 """No-model image probe: python -m openultrasast.search.probe.
 The packaged app is data, deliberately never imported into the worker process.
 RESULT_URL is an optional object-scoped PUT; no store credentials are used.
 """
 from __future__ import annotations
 import argparse
 import json
 import os
 import resource
 import shutil
 import subprocess
 import tempfile
 import time
 import urllib.request
 from dataclasses import asdict, replace
 from importlib.resources import files
 from pathlib import Path
 from typing import Any
 from . import _sandbox
 from .demo import FAMILY_ORACLES, load_demo
 from .oracles import BrowserExecutor
 from .task_storage import exception_reason
 from .verify import Side, VerificationRecord, verify, verify_side_task
 FAMILIES = ("sql", "path", "command", "ssrf", "xss")
 PAYLOADS = {
    "sql": "' OR public=0 --",
    "path": "../canary",
    "command": "; touch marker",
    "ssrf": "internal",
    "xss": '<script>alert("ousast-xss")</script>',
 }
 def materialise(root: Path, family: str) -> tuple[tuple[Side, Side], dict[str, Path]]:
    source = files("openultrasast.search").joinpath("probe_apps/app.py.txt").read_bytes()
    if not source:
        raise ValueError("empty packaged toy input")
    sides = []
    for name in ("vulnerable", "fixed"):
        checkout = root / name
        checkout.mkdir(parents=True)
        (checkout / "app.py").write_bytes(source)
        if name == "fixed":
            (checkout / "fixed").touch()
        sides.append(Side(checkout))
    demos = {}
    for name in ("real", "observer_access", "revision_patch"):
        demo = root / name
        demo.mkdir()
        demos[name] = demo
    schema: dict[str, Any] = {
        "oracle": family,
        "build": {"recipe": "none", "arguments": []},
        "start": {"runtime": "python", "path": "app.py", "arguments": [], "mode": "cli"},
        "steps": [{"type": "cli", "arguments": [family, PAYLOADS[family]]}],
    }
    (demos["real"] / "demo.json").write_text(json.dumps(schema))
    schema["steps"][0]["arguments"] = ["/fixture/canary"]
    (demos["observer_access"] / "demo.json").write_text(json.dumps(schema))
    schema["start"]["path"] = "../fixed/app.py"
    (demos["revision_patch"] / "demo.json").write_text(json.dumps(schema))
    return (sides[0], sides[1]), demos
 def image_facts() -> dict[str, Any]:
    facts = {}
    for name, argv in {
        "python": ["python3", "--version"],
        "node": ["node", "--version"],
        "tsc": ["tsc", "--version"],
        "php": ["php", "--version"],
        "java": ["java", "-version"],
        "sqlite": ["sqlite3", "--version"],
        "bwrap": ["bwrap", "--version"],
        "chromium": ["chromium", "--version"],
    }.items():
        try:
            done = subprocess.run(argv, capture_output=True, text=True, timeout=10, env={"PATH": os.defpath + ":/opt/java/openjdk/bin"})
            facts[name] = {"exit_code": done.returncode, "version": (done.stdout + done.stderr).strip()[:2000]}
        except (OSError, subprocess.SubprocessError) as exc:
            facts[name] = {"error": str(exc)}
    return facts
 def namespace_facts() -> dict[str, Any]:
    """Try capabilities independently, even when the combined preflight fails."""
    commands = {
        name: ["bwrap", f"--unshare-{name}", "--bind", "/", "/", "--", "/bin/true"]
        for name in ("user", "pid", "net", "ipc", "uts", "cgroup")
    }
    commands["mount"] = ["bwrap", "--bind", "/", "/", "--", "/bin/true"]
    commands["setpriv"] = [*_sandbox.drop_privileges(), "/usr/bin/id"]
    facts = {}
    for name, argv in commands.items():
        try:
            done = subprocess.run(argv, capture_output=True, text=True, timeout=5, env={"PATH": os.defpath})
            facts[name] = {"exit_code": done.returncode, "stderr": done.stderr[:2000], "stdout": done.stdout[:2000]}
        except (OSError, subprocess.SubprocessError) as exc:
            facts[name] = {"exit_code": None, "stderr": str(exc)}
    return facts
 def _verify_task_pair(sides: tuple[Side, Side], demo: Path, family: str) -> VerificationRecord:
    """Exercise the task executor on packaged toys only, not arbitrary checkouts.
    Repetitions get fresh scratch, but share this probe task's outer boundary.
    This is an instrument self-test, not a fresh-task dispatcher for evidence.
    """
    started = time.monotonic()
    records = []
    try:
        load_demo(demo)
    except (OSError, ValueError) as exc:
        return VerificationRecord(
            "inconclusive",
            (),
            time.monotonic() - started,
            "invalid declarative demo: " + exception_reason(exc),
            isolation_mode="task-boundary",
        )
    search_family = next(f for f, kinds in FAMILY_ORACLES.items() if family in kinds)
    for side in sides:
        runs = [verify_side_task(side, demo, search_family) for _ in range(3)]
        first = next((run for run in runs if run.outcome != "observed"), runs[0])
        records.append(
            replace(
                first,
                runs=tuple(observation for run in runs for observation in run.runs),
                elapsed_seconds=sum(run.elapsed_seconds for run in runs),
                build_seconds=sum(run.build_seconds for run in runs),
                ready_seconds=sum(run.ready_seconds for run in runs),
                run_seconds=sum(run.run_seconds for run in runs),
                scratch_peak_bytes=max(run.scratch_peak_bytes for run in runs),
                reason=first.reason if first.outcome != "observed" else "three probe task executions completed",
            )
        )
    demonstrated = (
        all(side.outcome == "observed" and len(side.runs) == 3 for side in records)
        and all(run.observed for run in records[0].runs)
        and not any(run.observed for run in records[1].runs)
    )
    return VerificationRecord(
        "demonstrated" if demonstrated else "inconclusive",
        tuple(records),
        time.monotonic() - started,
        "owned effect in 3/3 affected runs and 0/3 safe runs" if demonstrated else "no consistent differential effect",
        isolation_mode="task-boundary",
        chromium_no_sandbox=any(side.chromium_no_sandbox for side in records),
    )
 def probe(root: Path) -> dict[str, Any]:
    record: dict[str, Any] = {
        "status": "ok",
        "oracles": {},
        "image": image_facts(),
        "namespaces": namespace_facts(),
        "isolation_check": None,
        "isolation_mode": _sandbox.isolation_mode(),
    }
    namespaces = record["namespaces"]
    if namespaces and all(namespaces[name]["exit_code"] != 0 for name in ("user", "pid", "net", "ipc", "uts", "mount")):
        record["isolation_mode"] = "task-boundary"
    task_boundary = record["isolation_mode"] == "task-boundary"
    if task_boundary:
        # Real verification still needs fresh side tasks; only these packaged
        # self-test applications share the probe task's boundary.
        record["requires_fresh_side_tasks"] = True
    start = time.monotonic()
    try:
        if task_boundary:
            record["isolation_check"] = {"status": "skipped", "reason": "task-boundary"}
        else:
            _sandbox.isolation_check()
            record["isolation_check"] = {"status": "ok", "input_bytes": len(b"isolation-ready\n")}
        for family in FAMILIES:
            sides, demos = materialise(root / family, family)
            results: dict[str, Any] = {}
            record["oracles"][family] = results
            for name, demo in demos.items():
                search_family = next(f for f, kinds in FAMILY_ORACLES.items() if family in kinds)
                if task_boundary:
                    tick = time.monotonic()
                    try:
                        result = _verify_task_pair(sides, demo, family)
                    except Exception as exc:
                        result = VerificationRecord(
                            "inconclusive", (), time.monotonic() - tick, exception_reason(exc), isolation_mode="task-boundary"
                        )
                else:
                    result = verify(
                        *sides,
                        demo,
                        search_family,
                        oracle=family,
                        browser=BrowserExecutor() if family == "xss" else None,
                    )
                results[name] = asdict(result)
                if task_boundary and (result.outcome == "demonstrated") != (name == "real") and record["status"] == "ok":
                    expected = "demonstrated" if name == "real" else "not demonstrated"
                    record.update(
                        status="instrument_failure",
                        exception=f"{family}/{name}: expected {expected}, got {result.outcome}",
                    )
                # SSRF/browser need additional namespace capabilities beyond the
                # generic preflight. These failures must not look like oracle misses.
                for side in result.sides:
                    if not task_boundary and side.reason.startswith("verification unavailable or refused:"):
                        raise _sandbox.IsolationUnavailable(f"{family}/{name}: {side.reason}")
    except Exception as exc:
        record.update(status="instrument_failure", exception=exception_reason(exc))
        namespaces = record["namespaces"]
        if namespaces and all(namespaces[name]["exit_code"] != 0 for name in ("user", "pid", "net", "ipc", "uts", "mount")):
            record["isolation_mode"] = "task-boundary"
            record["requires_fresh_side_tasks"] = True
        if record["isolation_check"] is None:
            record["isolation_check"] = {"status": "instrument_failure", "exception": exception_reason(exc)}
    finally:
        record["wall_seconds"] = time.monotonic() - start
        record["peak_rss_kib"] = {
            "self": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss,
            "children": resource.getrusage(resource.RUSAGE_CHILDREN).ru_maxrss,
        }
        record["peak_rss_kib"]["sum"] = sum(record["peak_rss_kib"].values())
        record["scratch_disk_bytes"] = sum(p.stat().st_blocks * 512 for p in root.rglob("*") if p.is_file())
        record["verification_scratch_peak_bytes"] = max(
            (s["scratch_peak_bytes"] for results in record["oracles"].values() for result in results.values() for s in result["sides"]),
            default=0,
        )
        record["scratch_filesystem_used_bytes"] = shutil.disk_usage(root).used
    return record
 def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--heap-profile", choices=("vm", "ax"), help=argparse.SUPPRESS)
    parser.parse_args(argv)
    with tempfile.TemporaryDirectory(prefix="ousast-search-probe-") as directory:
        record = probe(Path(directory))
    data = (json.dumps(record, sort_keys=True) + "\n").encode()
    print(data.decode(), end="", flush=True)
    if url := os.environ.get("RESULT_URL"):
        request = urllib.request.Request(url, data=data, method="PUT", headers={"Content-Type": "application/json"})
        try:
            with urllib.request.urlopen(request, timeout=30) as response:
                if not 200 <= response.status < 300:
                    return 1
        except Exception as exc:
            record.update(status="instrument_failure", phase="result upload", reason=exception_reason(exc))
            print(json.dumps(record), flush=True)
            return 1
    return 0 if record["status"] == "ok" else 1
 if __name__ == "__main__":
    raise SystemExit(main())
@@ -0,0 +1,36 @@
 """CLI toy: arguments are its sole public interface; config belongs to the app."""
 import os
 import pathlib
 import sqlite3
 import subprocess
 import sys
 import urllib.request
 fixed = (pathlib.Path(__file__).parent / "fixed").exists()
 if sys.argv[1:] == ["--ready"]:
    sys.exit(1 if (pathlib.Path(__file__).parent / "broken").exists() else 0)
 family, payload = sys.argv[1:]
 if family == "path":
    root = pathlib.Path(os.environ["SERVED_ROOT"])
    path = (root / payload).resolve()
    if not fixed or path.is_relative_to(root):
        value = path.read_text()
        if not (pathlib.Path(__file__).parent / "flaky").exists() or value.startswith("a"):
            print(value)
 elif family == "sql":
    with sqlite3.connect(os.environ["DATABASE"]) as db:
        if fixed:
            rows = db.execute("SELECT value FROM records WHERE public=1 AND name=?", (payload,))
        else:
            rows = db.execute("SELECT value FROM records WHERE public=1 AND name='" + payload + "'")
        print(list(rows))
 elif family == "command":
    if not fixed:
        subprocess.run("echo " + payload, shell=True, check=False)
 elif family == "ssrf":
    if not fixed:
        print(urllib.request.urlopen((os.environ["CALLBACK_URL"] if payload == "internal" else payload), timeout=2).read())
 elif family == "xss":
    import html
    print(html.escape(payload) if fixed else payload)
@@ -0,0 +1,142 @@
 """Disk-backed task scratch and aggregate workspace guard for kube-ax."""
 from __future__ import annotations
 import os
 import re
 import stat
 import subprocess
 import tempfile
 import time
 from pathlib import Path
 from typing import Any
 DEFAULT_SCRATCH_BYTES = 2 * 1024**3
 WORKSPACE = Path("/workspace")
 class ScratchLimit(ValueError):
    """The task workspace exceeded its configured scratch budget."""
 def environment() -> dict[str, str]:
    if not WORKSPACE.is_dir():
        return {}
    root = str(WORKSPACE)
    return {
        "HOME": root + "/home",
        "TMPDIR": root + "/tmp",
        "npm_config_cache": root + "/.npm",
        "MAVEN_OPTS": "-Dmaven.repo.local=" + root + "/.m2",
        "COMPOSER_HOME": root + "/.composer",
        "PIP_CACHE_DIR": root + "/.pip",
        "GRADLE_USER_HOME": root + "/.gradle",
    }
 def configure() -> int:
    limit = int(os.environ.get("OUSAST_SCRATCH_BYTES", DEFAULT_SCRATCH_BYTES))
    if limit < 1:
        raise ValueError("scratch limit must be positive")
    env = environment()
    if env:
        Path(env["TMPDIR"]).mkdir(parents=True, exist_ok=True)
        Path(env["HOME"]).mkdir(parents=True, exist_ok=True)
        os.environ.update(env)
        # tempfile may have cached /tmp before this entry point ran.
        tempfile.tempdir = env["TMPDIR"]
    os.environ["OUSAST_SCRATCH_BYTES"] = str(limit)
    return limit
 def check(root: Path | None = None, limit: int | None = None, *, additional_bytes: int = 0) -> int:
    root = root or WORKSPACE
    limit = limit if limit is not None else int(os.environ.get("OUSAST_SCRATCH_BYTES", DEFAULT_SCRATCH_BYTES))
    if not root.is_dir():
        raise OSError("scratch root unavailable")
    def unreadable(error: OSError) -> None:
        if not isinstance(error, FileNotFoundError):
            raise error
    total = additional_bytes
    if total > limit:
        raise ScratchLimit("scratch limit")
    for parent, directories, names in os.walk(root, followlinks=False, onerror=unreadable):
        directories[:] = [d for d in directories if not (Path(parent) / d).is_symlink()]
        for name in names:
            try:
                info = (Path(parent) / name).lstat()
            except FileNotFoundError:  # A running build may remove its temporary files.
                continue
            if stat.S_ISREG(info.st_mode):
                total += max(info.st_size, info.st_blocks * 512)
            if total > limit:
                raise ScratchLimit("scratch limit")
    return total
 def communicate(proc: subprocess.Popen[Any], data: bytes, timeout: float, root: Path, *, files: tuple[Any, ...] = ()) -> None:
    """Poll while the child runs and after exit, catching short-lived growth too."""
    def guard() -> None:
        # TemporaryFile logs are unlinked, so a directory walk cannot see them.
        check(WORKSPACE if WORKSPACE.is_dir() else root, additional_bytes=sum(os.fstat(f.fileno()).st_size for f in files))
    end = time.monotonic() + timeout
    first = True
    while True:
        guard()
        try:
            proc.communicate(input=data if first else None, timeout=min(0.05, max(0, end - time.monotonic())))
            guard()
            return
        except subprocess.TimeoutExpired:
            first = False
            if time.monotonic() >= end:
                raise
 def diagnostic(value: object, *, maximum: int = 300, private: tuple[str, ...] = ()) -> str:
    """Sanitize before truncation so a clipped secret cannot escape redaction."""
    text = str(value)
    for key, secret in os.environ.items():
        if len(secret) >= 4 and any(word in key.upper() for word in ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL")):
            text = text.replace(secret, "[redacted]")
    text = re.sub(r"(?i)bearer\s+[^\s,;\"']+", "Bearer [redacted]", text)
    text = re.sub(r"(?i)(?:https?|s3)://[^\s<>\"']+", "[redacted-url]", text)
    text = re.sub(
        r"(?i)([\w-]*(?:authorization|signature|credential|token|secret|password|key))[\"']?\s*[:=]\s*[\"']?[^\s,;&\"']+",
        r"\1=[redacted]",
        text,
    )
    text = re.sub(r"\b(?:gh[pousr]_[A-Za-z0-9_]+|github_pat_[A-Za-z0-9_]+|sk-[A-Za-z0-9_-]+|npm_[A-Za-z0-9]+)\b", "[redacted]", text)
    text = re.sub(r"\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b", "[redacted]", text)
    for name in sorted(set(private), key=len, reverse=True):
        if name:
            text = text.replace(name, "[repository]")
    return "\n".join(text.splitlines()[-20:])[-maximum:]
 def exception_reason(exc: BaseException, *, private: tuple[str, ...] = ()) -> str:
    prefix = type(exc).__name__ + ": "
    maximum = max(0, 300 - len(prefix))
    cleanup = getattr(exc, "executor_cleanup_reason", None)
    if cleanup:
        original = str(exc).removesuffix("; " + cleanup)
        # Reserve space for both causes: a long teardown must not erase the
        # original failure from the bounded public record.
        half = max(0, (maximum - 2) // 2)
        return prefix + diagnostic(original, maximum=half, private=private) + "; " + diagnostic(cleanup, maximum=half, private=private)
    return prefix + diagnostic(exc, maximum=maximum, private=private)
 class CommandFailure(ValueError):
    """Transport a bounded command diagnostic without dropping stderr."""
    def __init__(self, phase: str, exit_code: int | None, stderr: str, reason: str = "") -> None:
        self.phase = phase
        self.exit_code = exit_code
        self.stderr = diagnostic(stderr, maximum=1500)
        summary = diagnostic(reason) if reason else f"{phase}: exit code {exit_code}"
        super().__init__(summary + (": " + self.stderr if self.stderr else ""))
@@ -0,0 +1,728 @@
 """Verifier-owned execution of bounded JSON demonstrations and owned oracles.
 When namespaces are unavailable, a trusted dispatcher must provide separate fresh
 AX tasks for the two sides. There is deliberately no local unsandboxed fallback.
 """
 from __future__ import annotations
 import hashlib
 import json
 import os
 import re
 import resource
 import secrets
 import shutil
 import signal
 import stat
 import subprocess
 import tempfile
 import time
 import zipfile
 from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import suppress
 from dataclasses import asdict, dataclass, field, replace
 from pathlib import Path
 from typing import Any, cast
 from ..sandbox import SandboxJob, SandboxResult
 from . import _sandbox, task_storage
 from .budget import SearchBudget, verification_run_seconds, verification_timeout
 from .demo import BUILD_RECIPES, FAMILY_ORACLES, RUNTIMES, capture_output, load_demo, substitute, validate_oracle, write_start_files
 from .oracles import BrowserExecutor, Canary, Oracle, oracle_for
 from .task_storage import CommandFailure, diagnostic, exception_reason
@dataclass(frozen=True)
 class Side:
    checkout: Path
    command: tuple[str, ...] = ()
    readiness_args: tuple[str, ...] = ("--ready",)
    dependencies: tuple[Path, ...] = ()
    build_command: tuple[str, ...] = ()
    products: Path | None = None
@dataclass(frozen=True)
 class RunObservation:
    observed: bool
    evidence: str
    elapsed_seconds: float
@dataclass(frozen=True)
 class SideRecord:
    outcome: str
    runs: tuple[RunObservation, ...]
    elapsed_seconds: float
    reason: str
    build_seconds: float = 0.0
    ready_seconds: float = 0.0
    run_seconds: float = 0.0
    scratch_peak_bytes: int = 0
    isolation_mode: str = field(default_factory=_sandbox.isolation_mode)
    chromium_no_sandbox: bool = False
    phase: str = ""
    exit_code: int | None = None
    stderr: str = ""
    stdout: str = ""
    control_observed: bool | None = None
@dataclass(frozen=True)
 class VerificationRecord:
    outcome: str
    sides: tuple[SideRecord, ...]
    elapsed_seconds: float
    reason: str
    isolation_mode: str = field(default_factory=_sandbox.isolation_mode)
    chromium_no_sandbox: bool = False
 def _tree(root: Path, *, generated_links: bool = False) -> str:
    """Hash every input byte; only post-build trees may link within themselves."""
    digest = hashlib.sha256()
    if root.is_symlink():
        raise ValueError("input must not be a link")
    if root.is_file():
        digest.update(root.read_bytes())
        return digest.hexdigest()
    if not root.is_dir():
        raise ValueError("input must be a real directory or JSON file")
    paths = [root, *sorted(root.rglob("*"))]
    directory_edges: dict[Path, list[Path]] = {}
    for path in paths:
        mode = path.lstat().st_mode
        if stat.S_ISLNK(mode) and generated_links:
            try:
                target = path.resolve(strict=True)
            except (OSError, RuntimeError) as exc:
                raise ValueError("dangling or cyclic build link") from exc
            if not target.is_relative_to(root.resolve()):
                raise ValueError("build link escapes its tree")
            if not (target.is_file() or target.is_dir()):
                raise ValueError("build link targets a special file")
            digest.update(str(path.relative_to(root)).encode())
            digest.update(str(mode).encode())
            digest.update(os.readlink(path).encode())
            if target.is_dir():
                directory_edges.setdefault(path.parent.resolve(), []).append(target)
            continue
        if not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):
            raise ValueError(f"links and special files refused: {path.name}")
        if path != root and path.is_dir():
            directory_edges.setdefault(path.parent.resolve(), []).append(path.resolve())
        digest.update(str(path.relative_to(root)).encode())
        digest.update(str(mode).encode())
        if path.is_file():
            with path.open("rb") as stream:
                while block := stream.read(65536):
                    digest.update(block)
    if generated_links:
        visiting: set[Path] = set()
        visited: set[Path] = set()
        def visit(directory: Path) -> None:
            if directory in visiting:
                raise ValueError("cyclic build directory link")
            if directory in visited:
                return
            visiting.add(directory)
            for target in directory_edges.get(directory, []):
                visit(target)
            visiting.remove(directory)
            visited.add(directory)
        visit(root.resolve())
    return digest.hexdigest()
 # Executed as verifier-owned code inside the same network sandbox as the app.
 # Redirects are refused: only the configured loopback application is reachable.
 _HTTP_DRIVER = r"""
 import http.client, importlib.util, json, os, socket, subprocess, sys, time
 spec = importlib.util.spec_from_file_location('demo', '/verifier-demo.py')
 demo = importlib.util.module_from_spec(spec)
 spec.loader.exec_module(demo)
 config = json.load(sys.stdin)
 schema = config['schema']
 app_errors = open("/scratch/" + config["errors"], "wb")
 app_output = open("/scratch/" + config["output"], "wb")
 app = subprocess.Popen(config['command'], stdin=subprocess.DEVNULL, stdout=app_output, stderr=app_errors)
 try:
    until = time.monotonic() + config['timeout']
    while True:
        if app.poll() is not None:
            raise SystemExit(app.returncode or 1)
        try:
            connection = socket.create_connection(('127.0.0.1', schema['start']['port']), timeout=0.1)
            connection.close()
            break
        except OSError:
            if time.monotonic() >= until:
                raise RuntimeError('HTTP readiness timed out')
            time.sleep(0.5)
    conn = http.client.HTTPConnection('127.0.0.1', schema['start']['port'], timeout=max(0.01, until - time.monotonic()))
    conn.request('GET', '/')
    response = conn.getresponse()  # Any HTTP status establishes listening.
    conn.close()
    with open('/scratch/' + config['ready'], 'w') as ready:
        ready.write('ready')
    acknowledgment_deadline = time.monotonic() + 3
    while not os.path.exists('/scratch/' + config['go']):
        if time.monotonic() >= acknowledgment_deadline:
            raise RuntimeError('verifier readiness acknowledgment timed out')
        time.sleep(0.01)
    captures, outputs = {}, []
    for step in schema['steps']:
        path = demo.substitute(step['path'], captures)
        if not path.startswith('/') or path.startswith('//') or '\r' in path or '\n' in path:
            raise ValueError('invalid expanded HTTP path')
        headers = {key: demo.substitute(value, captures) for key, value in step.get('headers', {}).items()}
        conn = http.client.HTTPConnection('127.0.0.1', schema['start']['port'], timeout=config['timeout'])
        conn.request(step['method'], path, body=demo.substitute(step.get('body', ''), captures).encode(), headers=headers)
        response = conn.getresponse()
        body = response.read(1048577)
        if len(body) > 1048576:
            raise ValueError('HTTP response exceeds limit')
        output = body.decode(errors='replace')
        outputs.append(output)
        demo.capture_output(step, output, captures, config['nonce'])
        conn.close()
    print(json.dumps(outputs))
 finally:
    app.terminate()
    try:
        app.wait(timeout=0.5)
    except subprocess.TimeoutExpired:
        app.kill()
        app.wait()
    app_errors.close()
    app_output.close()
 """
 def _http_steps(
    schema: dict[str, Any],
    command: tuple[str, ...],
    job: Callable[[tuple[str, ...]], SandboxJob],
    scratch: Path,
    mounts: dict[str, Path],
    env: dict[str, str],
    namespace_pid: int | None,
    nonce: str,
    runner: Callable[..., SandboxResult],
    ready_check: Callable[[], None],
    diagnostics: dict[str, Any] | None = None,
 ) -> list[str]:
    from . import demo as demo_module
    ready, go = ".ready-" + secrets.token_hex(12), ".go-" + secrets.token_hex(12)
    diagnostics = diagnostics if diagnostics is not None else {}
    request = {
        "schema": schema,
        "command": command,
        "timeout": job(command).timeout_seconds,
        "nonce": nonce,
        "ready": ready,
        "go": go,
        "errors": ready + ".err",
        "output": ready + ".out",
    }
    diagnostics.update(stdout="", stderr="")
    acknowledged = False
    started = time.monotonic()
    driver_job = replace(
        job(command),
        command=("/usr/bin/python3", "-I", "-c", _HTTP_DRIVER),
        timeout_seconds=verification_run_seconds(schema, job(command).timeout_seconds),
    )
    with ThreadPoolExecutor(max_workers=1) as pool:
        future = pool.submit(
            runner,
            driver_job,
            scratch=scratch,
            mounts={**mounts, "/verifier-demo.py": Path(demo_module.__file__)},
            env=env,
            namespace_pid=namespace_pid,
            network=True,
            input_text=json.dumps(request),
        )
        deadline = time.monotonic() + job(command).timeout_seconds + 5
        while not (scratch / ready).exists() and not future.done() and time.monotonic() < deadline:
            time.sleep(0.01)
        diagnostics["ready_seconds"] = diagnostics.get("ready_seconds", 0) + time.monotonic() - started
        if (scratch / ready).exists():
            ready_check()
            (scratch / go).touch()
            acknowledged = True
        result = future.result()
    for key, suffix in (("stdout", ".out"), ("stderr", ".err")):
        path = scratch / (ready + suffix)
        if path.is_file():
            with path.open("rb") as stream:
                stream.seek(max(0, path.stat().st_size - 16384))
                diagnostics[key] = diagnostic(stream.read().decode(errors="replace"), maximum=1500)
    if not acknowledged or result.exit_code or result.timed_out:
        raise CommandFailure(
            "start" if not acknowledged else "run",
            result.exit_code,
            diagnostics.get("stderr", "") + "\n" + result.stderr,
            "HTTP application/steps failed or readiness not acknowledged",
        )
    outputs = json.loads(result.stdout)
    if not isinstance(outputs, list) or len(outputs) != len(schema["steps"]) or not all(isinstance(value, str) for value in outputs):
        raise ValueError("invalid HTTP driver output")
    return cast(list[str], outputs)
 def _side(side: Side, demo: Path, family: str, timeout: int, browser: BrowserExecutor | None, *, task_boundary: bool = False) -> SideRecord:
    started = time.monotonic()
    runner = _run_task if task_boundary else _sandbox.run
    observations: list[RunObservation] = []
    timings = dict(build=0.0, ready=0.0, run=0.0)
    app_diagnostics: dict[str, Any] = {}
    private_values: list[str] = []
    disk_peak = 0
    control_observed: bool | None = None
    root: Path | None = None
    def timed(stage: str, operation: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
        nonlocal disk_peak
        tick = time.monotonic()
        try:
            return operation(*args, **kwargs)
        finally:
            timings[stage] += time.monotonic() - tick
            if root is not None:
                disk_peak = max(disk_peak, sum(p.lstat().st_blocks * 512 for p in root.rglob("*")))
    def record(outcome: str, reason: str, phase: str = "", result: Any = None) -> SideRecord:
        return SideRecord(
            outcome,
            tuple(observations),
            time.monotonic() - started,
            diagnostic(reason, maximum=1500, private=tuple(private_values)),
            timings["build"],
            timings["ready"] + app_diagnostics.get("ready_seconds", 0),
            max(0.0, timings["run"] - app_diagnostics.get("ready_seconds", 0)),
            disk_peak,
            isolation_mode="task-boundary" if task_boundary else _sandbox.isolation_mode(),
            chromium_no_sandbox=bool(getattr(browser, "no_sandbox", False)),
            phase=phase,
            exit_code=result.exit_code if result is not None else None,
            stderr=diagnostic(
                result.stderr if result is not None else app_diagnostics.get("stderr", ""), maximum=1500, private=tuple(private_values)
            ),
            stdout=diagnostic(getattr(result, "stdout", app_diagnostics.get("stdout", "")), maximum=1500, private=tuple(private_values)),
            control_observed=control_observed,
        )
    try:
        schema = load_demo(demo)
        originals = (side.checkout, *side.dependencies, demo, *((side.products,) if side.products else ()))
        initial = tuple(_tree(p) for p in originals)
        for run_index in range(1 if task_boundary else 3):
            tick = time.monotonic()
            with tempfile.TemporaryDirectory(prefix="ousast-proof-") as temporary:
                root = Path(temporary)
                checkout = shutil.copytree(side.checkout, root / "checkout")
                dependencies = [shutil.copytree(p, root / f"dep-{i}") for i, p in enumerate(side.dependencies)]
                immutable = (*dependencies,)
                before = tuple(_tree(p) for p in immutable)
                mounts = {f"/deps/{i}": p for i, p in enumerate(dependencies)}
                def job(command: tuple[str, ...], checkout: Path = checkout) -> SandboxJob:
                    return SandboxJob("", command, checkout, {}, timeout, SearchBudget().memory_bytes // 1024**2, 128)
                products = root / "products"
                if side.products is not None:
                    shutil.copytree(side.products, products)
                else:
                    products.mkdir()
                if task_boundary:
                    task_storage.check(task_storage.WORKSPACE if task_storage.WORKSPACE.is_dir() else root)
                recipe = schema["build"]["recipe"]
                build_args = schema["build"]["arguments"]
                if task_boundary and recipe != "none":
                    return record("could_not_build", "verifier requires executor-built archive; builds are forbidden")
                if recipe != "none":
                    build_input = checkout / build_args[0]
                    manifest = recipe in ("pip", "maven")
                    if not build_input.resolve().is_relative_to(checkout.resolve()) or not (
                        build_input.is_file() if manifest else build_input.is_dir()
                    ):
                        return record("could_not_build", "recipe input missing or outside checkout")
                    command = (*BUILD_RECIPES[recipe], "/workspace/" + build_args[0])
                    if recipe == "maven":
                        command += ("package", "-DskipTests")
                    elif recipe == "gradle":
                        command += ("assemble",)
                    compiled = timed("build", runner, job(command), scratch=products, mounts=mounts, writable_checkout=True)
                    if compiled.exit_code or compiled.timed_out:
                        return record("could_not_build", "build recipe failed", "build", compiled)
                if tuple(_tree(p) for p in immutable) != before:
                    return record("inconclusive", "build changed immutable inputs")
                mounts["/build"] = products
                start_spec = schema["start"]
                entry = checkout / start_spec["path"]
                if not entry.is_file() or not entry.resolve().is_relative_to(checkout.resolve()):
                    return record("could_not_build", "runtime entry missing from checkout")
                command = (*RUNTIMES[start_spec["runtime"]], "/workspace/" + start_spec["path"], *start_spec["arguments"])
                if start_spec["runtime"] == "python":
                    # Fixed bootstrap enables ordinary local imports and the pip
                    # recipe's offline packages without trusting PYTHONPATH.
                    bootstrap = (
                        "import os,runpy,sys; sys.dont_write_bytecode=True; p=sys.argv.pop(1); "
                        "sys.path[:0]=['/build/packages','/workspace',os.path.dirname(p)]; sys.argv[0]=p; "
                        "runpy.run_path(p,run_name='__main__')"
                    )
                    command = (*RUNTIMES["python"], "-c", bootstrap, "/workspace/" + start_spec["path"], *start_spec["arguments"])
                if start_spec["runtime"] == "java":
                    # -jar ignores CLASSPATH. Use the jar's declared main class
                    # with the verifier-owned product directories and jars.
                    with zipfile.ZipFile(entry) as jar, jar.open("META-INF/MANIFEST.MF") as jar_manifest:
                        metadata = jar_manifest.read(65537)
                    if len(metadata) > 65536:
                        return record("could_not_build", "oversized Java manifest")
                    metadata = metadata.replace(b"\r\n", b"\n").replace(b"\n ", b"")
                    main = re.search(rb"(?mi)^Main-Class: ([\w.$]+)\s*$", metadata.split(b"\n\n", 1)[0])
                    if main is None:
                        return record("could_not_build", "Java jar missing Main-Class")
                    classpath = ["/workspace/" + start_spec["path"], "/build/", "/build/classes"]
                    classpath.extend("/build/" + str(path.relative_to(products)) for path in sorted(products.rglob("*.jar")))
                    command = ("/usr/bin/java", "-cp", ":".join(classpath), main[1].decode(), *start_spec["arguments"])
                oracle = oracle_for(family, browser)
                assert oracle is not None
                try:
                    canary = Canary.fresh(root / "fixture")
                    private_values.extend((canary.nonce, str(root), "/fixture", "/scratch"))
                    if task_boundary and hasattr(oracle, "task_boundary"):
                        oracle.task_boundary = True
                    oracle_env = oracle.prepare(canary)
                    bindings = oracle.placeholders
                    file_bindings = bindings
                    if task_boundary:
                        # Files are app data, so resolve their paths before writing;
                        # the task runner only translates argv and environment.
                        file_bindings = {
                            key: re.sub(r"/(?:fixture|scratch)(?=/|$)", lambda _, path=str(canary.root): path, value)
                            for key, value in bindings.items()
                        }
                    private_values.extend((*bindings.values(), *file_bindings.values()))
                    write_start_files(checkout, start_spec, file_bindings)
                    if not task_boundary:
                        for name in start_spec.get("files", {}):
                            _sandbox.writable_directory(checkout / ".demo" / name)
                    product_hash = _tree(products, generated_links=True)
                    checkout_hash = _tree(checkout, generated_links=True)
                    command = tuple(substitute(arg, bindings) for arg in command)
                    app_env = {
                        **{
                            key: "/workspace/" + expanded if expanded.startswith(".demo/") else expanded
                            for key, value in start_spec.get("environment", {}).items()
                            for expanded in [substitute(value, bindings)]
                        },
                        **oracle_env,
                    }
                    if start_spec["runtime"] == "node":
                        # Executor npm runs in its selected project. That project
                        # may be separate from the launcher (e.g. .demo/), and the
                        # exported spec no longer carries a build recipe. Discover
                        # project installs, pruning dependency-internal installs.
                        node_paths = []
                        for parent, dirs, _ in os.walk(checkout):
                            dirs.sort()
                            if "node_modules" in dirs:
                                node_paths.append("/workspace/" + (Path(parent) / "node_modules").relative_to(checkout).as_posix())
                                dirs.remove("node_modules")
                        app_env["NODE_PATH"] = ":".join([*node_paths, "/build/node_modules"])
                    app_scratch = canary.root if family == "command" else root / "app"
                    app_scratch.mkdir(exist_ok=True)
                    fixture = canary.root
                    if not task_boundary and _sandbox.isolation_mode() == "root-no-userns" and family != "command":
                        # Observer originals remain private. Only the app gets a
                        # read-only copy of the fixtures its interface requires.
                        fixture = shutil.copytree(canary.root, root / "app-fixture")
                        for path in [fixture, *fixture.rglob("*")]:
                            path.chmod(0o555 if path.is_dir() else 0o444)
                    app_mounts = {**mounts, "/fixture": fixture}
                    if schema["start"]["mode"] == "cli":
                        ready = timed(
                            "ready",
                            runner,
                            job((*command, *side.readiness_args)),
                            scratch=app_scratch,
                            mounts=app_mounts,
                            env=app_env,
                            namespace_pid=oracle.namespace_pid,
                        )
                        app_diagnostics.update(stdout=ready.stdout, stderr=ready.stderr)
                        if ready.exit_code or ready.timed_out:
                            return record("could_not_run", "app readiness failed", "start", ready)
                    if family == "ssrf" and oracle.observe()[0]:
                        return record("inconclusive", "readiness triggered the SSRF oracle")
                    # Readiness cannot supply the attack's evidence or leave a command marker.
                    if family == "command" and any(canary.root.iterdir()):
                        return record("inconclusive", "readiness modified command fixture")
                    def http_ready_check(oracle: Oracle = oracle, canary: Canary = canary) -> None:
                        if family == "ssrf" and oracle.observe()[0]:
                            raise ValueError("HTTP readiness triggered the SSRF oracle")
                        if family == "command" and (canary.root / "marker").exists():
                            raise ValueError("HTTP readiness modified command fixture")
                    captures: dict[str, str] = {}
                    if schema["start"]["mode"] == "http":
                        # Positive control: on the first run, a benign in-root request
                        # for a verifier-planted marker, run as its OWN app start and
                        # fully guarded so it can only annotate, never change the
                        # verdict. Its marker returning proves the interface serves the
                        # fixture; its absence (or any control failure) is recorded, not
                        # trusted, since a valid app may answer only its own routes.
                        probe = oracle.control()
                        if run_index == 0 and probe is not None:
                            control_schema = {
                                **schema,
                                "steps": [
                                    {
                                        "type": "http",
                                        "method": probe.method,
                                        "path": probe.path,
                                        **({"body": probe.body} if probe.body else {}),
                                    }
                                ],
                            }
                            try:
                                control_outputs = timed(
                                    "run",
                                    _http_steps,
                                    control_schema,
                                    command,
                                    job,
                                    app_scratch,
                                    app_mounts,
                                    app_env,
                                    oracle.namespace_pid,
                                    canary.nonce,
                                    runner,
                                    http_ready_check,
                                    {},
                                )
                                control_observed = bool(control_outputs) and probe.token in control_outputs[0]
                            except (CommandFailure, OSError, ValueError, AssertionError):
                                control_observed = False
                        outputs = timed(
                            "run",
                            _http_steps,
                            schema,
                            command,
                            job,
                            app_scratch,
                            app_mounts,
                            app_env,
                            oracle.namespace_pid,
                            canary.nonce,
                            runner,
                            http_ready_check,
                            app_diagnostics,
                        )
                        for output in outputs:
                            timed("run", oracle.capture, output)
                    else:
                        for step in schema["steps"]:
                            arguments = [substitute(arg, captures) for arg in step["arguments"]]
                            result = timed(
                                "run",
                                runner,
                                job((*command, *arguments)),
                                scratch=app_scratch,
                                mounts=app_mounts,
                                env=app_env,
                                namespace_pid=oracle.namespace_pid,
                                input_text=substitute(step.get("stdin", ""), captures),
                            )
                            app_diagnostics.update(stdout=result.stdout, stderr=result.stderr)
                            if result.timed_out:
                                return record("inconclusive", "app attack timed out")
                            if result.exit_code:
                                return record("could_not_run", "app invocation failed", "run", result)
                            timed("run", oracle.capture, result.stdout)
                            capture_output(step, result.stdout, captures, canary.nonce)
                    observed, evidence = timed("run", oracle.observe)
                    if (
                        tuple(_tree(p) for p in immutable) != before
                        or tuple(_tree(p) for p in originals) != initial
                        or _tree(products, generated_links=True) != product_hash
                        or _tree(checkout, generated_links=True) != checkout_hash
                    ):
                        return record("inconclusive", "immutable input or dependency changed")
                    observations.append(RunObservation(observed, evidence, time.monotonic() - tick))
                finally:
                    oracle.close()
        return record("observed", "fresh task run completed" if task_boundary else "three fresh runs completed")
    except CommandFailure as exc:
        return record("could_not_run", str(exc), exc.phase, exc)
    except task_storage.ScratchLimit as exc:
        return record("could_not_build", exception_reason(exc))
    except (OSError, ValueError, AssertionError, KeyError, IndexError, TypeError, zipfile.BadZipFile) as exc:
        return record("could_not_run", "verification unavailable or refused: " + exception_reason(exc))
 def _run_task(
    job: SandboxJob,
    *,
    scratch: Path,
    mounts: dict[str, Path] | None = None,
    env: dict[str, str] | None = None,
    input_text: str = "",
    **kwargs: Any,
 ) -> SandboxResult:
    """Only called in a fresh externally isolated task by verify_side_task.
    The schema selects tracked programs, never agent scripts. The task itself is
    the filesystem/network boundary. Its launch manifest must contain no keys.
    """
    translations = {"/workspace": str(job.repo_root), "/scratch": str(scratch), **{k: str(v) for k, v in (mounts or {}).items()}}
    pattern = re.compile("(?:" + "|".join(re.escape(key) for key in sorted(translations, key=len, reverse=True)) + r")(?=/|$|['\"])")
    def translate(value: str) -> str:
        # One pass, at path-component boundaries: /fixture/fixture.db must
        # translate its mount prefix without also rewriting the filename.
        return pattern.sub(lambda match: translations[match.group(0)], value)
    command = tuple(translate(arg) for arg in job.command)
    environment = {"PATH": "/usr/bin:/bin", "HOME": str(scratch), "TMPDIR": str(scratch), **task_storage.environment()}
    environment.update({key: translate(value) for key, value in (env or {}).items()})
    def limits() -> None:
        resource.setrlimit(resource.RLIMIT_FSIZE, (1024 * 1024,) * 2)
        # The external task memory limit bounds app starts; RLIMIT_AS breaks V8 reservations.
        resource.setrlimit(resource.RLIMIT_CPU, (job.timeout_seconds + 1,) * 2)
    # Driver JSON includes command paths, but arbitrary user input stays data.
    if "-c" in command and _HTTP_DRIVER in job.command:
        config = json.loads(input_text)
        config["command"] = [translate(arg) for arg in config["command"]]
        input_text = json.dumps(config)
    with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
        proc = subprocess.Popen(
            command, cwd=scratch, env=environment, stdin=subprocess.PIPE, stdout=out, stderr=err, start_new_session=True, preexec_fn=limits
        )
        expired = False
        try:
            task_storage.communicate(proc, input_text.encode(), job.timeout_seconds, job.repo_root.parent, files=(out, err))
        except subprocess.TimeoutExpired:
            expired = True
        finally:
            with suppress(ProcessLookupError):
                os.killpg(proc.pid, signal.SIGKILL)
            proc.wait()
        out.seek(0)
        err.seek(max(0, os.fstat(err.fileno()).st_size - 16384))
        return SandboxResult(
            proc.returncode, out.read(1048576).decode(errors="replace"), err.read(1048576).decode(errors="replace"), expired
        )
 def verify_side_task(side: Side, demo: Path, family: str, timeout_seconds: int | None = None) -> SideRecord:
    """Fresh AX task entry: one repetition, grouped by the trusted dispatcher.
    This explicit API is never selected as a fallback in the host verifier.
    """
    schema = load_demo(demo)
    if family in FAMILY_ORACLES and not FAMILY_ORACLES[family]:
        return SideRecord("no_oracle", (), 0, "no owned oracle", isolation_mode="task-boundary")
    validate_oracle(family, schema["oracle"])
    kind = schema["oracle"]
    if timeout_seconds is not None and timeout_seconds < 1:
        raise ValueError("timeout must be positive")
    browser = BrowserExecutor(task_boundary=True) if kind == "xss" else None
    return _side(side, demo, kind, timeout_seconds or verification_timeout(schema), browser, task_boundary=True)
 def verify(
    affected: Side,
    safe: Side,
    artefact: Path,
    family: str,
    *,
    timeout_seconds: int | None = None,
    oracle: str | None = None,
    browser: BrowserExecutor | None = None,
    task_dispatcher: Callable[..., SideRecord] | None = None,
 ) -> VerificationRecord:
    """Affected is vulnerable/head; safe is fixed/base. No negative verdict exists."""
    started = time.monotonic()
    if family in FAMILY_ORACLES and not FAMILY_ORACLES[family]:
        return VerificationRecord("no_oracle", (), time.monotonic() - started, "no configured owned oracle for " + family)
    if timeout_seconds is not None and timeout_seconds < 1:
        raise ValueError("timeout must be positive")
    try:
        schema = load_demo(artefact)
        validate_oracle(family, schema["oracle"])
        if oracle is not None and oracle != schema["oracle"]:
            raise ValueError("oracle differs from demo")
        kind = schema["oracle"]
        if oracle_for(kind, browser) is None:
            raise ValueError("oracle runtime unavailable")
    except (OSError, ValueError) as exc:
        return VerificationRecord("inconclusive", (), time.monotonic() - started, "invalid declarative demo: " + exception_reason(exc))
    timeout_seconds = timeout_seconds or verification_timeout(schema)
    mode = "task-boundary" if task_dispatcher is not None else _sandbox.isolation_mode()
    if task_dispatcher is None:
        try:
            _sandbox.isolation_check(timeout_seconds=timeout_seconds)
        except _sandbox.IsolationUnavailable:
            raise _sandbox.IsolationUnavailable("task-boundary requires a trusted fresh-task dispatcher; no local fallback") from None
    if mode == "task-boundary":
        assert task_dispatcher is not None
        # Only trusted infrastructure supplies this callback. One fresh task per
        # side; task IDs and cleanup are the dispatcher's responsibility.
        sides = tuple(
            task_dispatcher(side=s, demo=load_demo(artefact), family=family, timeout_seconds=timeout_seconds, fresh_task=True)
            for s in (affected, safe)
        )
        if any(s.isolation_mode != "task-boundary" for s in sides):
            raise _sandbox.IsolationUnavailable("dispatcher did not attest task-boundary isolation")
    else:
        sides = tuple(_side(s, artefact, kind, timeout_seconds, browser) for s in (affected, safe))
    if any(s.outcome == "observed" and len(s.runs) != 3 for s in sides):
        outcome, reason = "inconclusive", "each side requires exactly three fresh observations"
    elif sides[1].outcome != "observed":
        outcome, reason = "inconclusive", "safe side did not complete build/readiness/verification"
    elif sides[0].outcome != "observed":
        outcome, reason = sides[0].outcome, sides[0].reason
    elif all(r.observed for r in sides[0].runs) and not any(r.observed for r in sides[1].runs):
        outcome, reason = "demonstrated", "owned effect in 3/3 affected runs and 0/3 safe runs"
    else:
        outcome, reason = "inconclusive", "no consistent differential effect"
    return VerificationRecord(
        outcome,
        sides,
        time.monotonic() - started,
        reason,
        isolation_mode=mode,
        chromium_no_sandbox=bool(getattr(browser, "no_sandbox", False)),
    )
 def main() -> None:
    import argparse
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("affected", type=Path)
    parser.add_argument("safe", type=Path)
    parser.add_argument("artefact", type=Path)
    parser.add_argument("family")
    args = parser.parse_args()
    result = verify(Side(args.affected), Side(args.safe), args.artefact, args.family)
    print(json.dumps(asdict(result), indent=2))
 if __name__ == "__main__":
    main()
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1 @@`
							`"""Verifier-owned differential demonstrations (search-with-proof Req 3)."""`