# V16.12 — Execution Acceleration Runtime

> Release focus: cut **wall-clock work** by reusing what is provably already
> true, overlapping what is safely independent, and verifying the **smallest
> sufficient** set — while the **release path stays fresh and sacred**.

## Why this release exists

V16.10 gave the runtime honest *economy* primitives (Tool Output Budgeter,
Context Kernel V2, Repo Intelligence, Semantic Tool Router, Verification
Ladder). V16.11 gave the advisor a single lifecycle owner and an event-first
answer channel. What was still missing was an **execution** layer: the runtime
kept re-reading identical files, re-running gates whose inputs had not changed,
re-running the full suite for a one-line docs change, and had no honest account
of where wall time went.

V16.12 adds that layer as **six single-question capabilities** plus **one
composition owner**. None of them re-implements a cache, a scheduler, a ladder or
a ledger that already exists.

## The six capabilities

| Module | The one question it answers |
|---|---|
| `lib/verification-receipt-cache-v16-12.mjs` | *May this exact gate result stand in for a fresh run?* |
| `lib/task-dag-scheduler-v16-12.mjs` | *Which independent work may safely overlap?* |
| `lib/tool-result-reuse-v16-12.mjs` | *Is this deterministic read/search result still valid?* |
| `lib/incremental-verification-v16-12.mjs` | *What is the smallest sufficient verification for this task?* |
| `lib/warm-service-reuse-v16-12.mjs` | *May a warm service be reused, and is it still healthy?* |
| `lib/waste-detector-v16-12.mjs` | *Where did wall time go, and what was wasted?* |

`lib/execution-acceleration-v16-12.mjs` is the **composition owner**: it picks a
fast path and wires the capabilities into one bounded execution. It holds no
cache, no ladder and no ledger.

## 1. Verification Receipt Cache — "already proven"

A receipt is reusable as a **PASS only** when the workspace content fingerprint
**and** the full gate identity match: gate name, command, args, cwd, env policy
digest, Node runtime identity and the verification policy version. Any change to
source, test, `package-lock.json`, config, runtime identity or the policy turns
the lookup into a **MISS**.

- `FAIL` / `ABORT` / `TIMEOUT` / `PARTIAL` / `UNVERIFIED` are **never** reusable
  as a PASS. `receiptProvesPass()` is the single gate.
- A **corrupt** entry is treated as a MISS and removed.
- **Final release mode disables reuse entirely** (`finalReleaseMode`), so
  `npm test` and `release:verify` always run fresh.
- Windows-safe atomic write (`atomicWriteJson`) retries `EBUSY` / `EPERM` /
  `EACCES` / `EEXIST`, is bounded, and **degrades to a miss on failure — never to
  a wrong answer**.

## 2. Task DAG Scheduler — safe overlap only

Nodes declare an effect: `PURE`, `READ_ONLY`, `CACHE_WRITE_SAFE`, `SOURCE_WRITE`,
`PROCESS_MUTATION`. **A `SOURCE_WRITE` never overlaps anything**; writes are
serialized. Every node settles to exactly one terminal status —
`DONE / FAILED / CANCELLED / STALE / SKIPPED` — and a stale-generation result is
discarded and settles rather than spinning. A critical failure **cancels its
dependents** (a failed syntax gate must not still launch the suite). A deadlock
guard reports `DAG_DEADLOCK` instead of hanging.

## 3. Tool Result Reuse — deterministic, invalidated by change

A repeated identical read/search (same path, root, range, query, content hash)
is a `CACHE_HIT`; a changed content hash, range, query, path or root is a MISS. A
caller can force a fresh reread. **Large values spill to the Evidence Store**
(`spillBytes`) so a giant raw evidence blob is not duplicated in memory; an
unresolvable spilled row is treated as a MISS, never a fabricated hit.

## 4. Incremental Verification — composes the V16.10 ladder

This module **composes and evolves** the V16.10 Verification Ladder; the ladder
remains the **escalation authority**. It classifies the task shape
(`TINY / NORMAL / DEEP / RELEASE`) and asks the ladder for the cheapest
sufficient rung:

| Shape | Target rung |
|---|---|
| TINY | static |
| NORMAL | affected tests |
| DEEP | affected → integration (full suite permitted) |
| RELEASE | full suite + release verify (always) |

Uncertainty **escalates**, never de-escalates. A failure delta is compacted
through the V16.10 **Tool Output Budgeter**, so a failure never resends thousands
of passing lines.

## 5. Warm Service Reuse — lazy, bounded, health-checked

Services (LSP, browser, …) are **lazy** — a registry with no use starts
**nothing**. Reuse is bounded by a per-kind and total capacity with LRU eviction,
a warm handle that fails its health check is **evicted**, idle handles are
cleaned up, and concurrent cold starts for the same key are **single-flight**.
There is **no always-on LSP** and **no browser pool owner** here: browser
ownership stays with V16.11 (`acquireManagedBrowserWorkerLease`).

## 6. Waste Detector + Wall-Time Attribution — honest provenance

Tracks repeated reads, repeated gate executions, repo-index rebuilds,
unnecessary browser starts and full-suite counts. Every figure carries a
provenance: **MEASURED** (a real count), **DERIVED**, **ESTIMATED**, or
**NOT_MEASURED** (never observed). An overlap saving is **ESTIMATED** and never
promoted to measured. The detector **feeds Metrics V2** via
`wallAttributionToEfficiencyEvents()`; it is **not a second metrics authority** —
`efficiency-metrics-v16-10.mjs` remains the single aggregator (its
`CAPABILITY_EVENT_KINDS` gains one `executionAcceleration` entry).

## Fast paths and the release law

`planExecutionAcceleration()` selects a deterministic fast path:

- `TINY_FAST_PATH` — docs/single-file low-risk: static verification, result reuse
  on, no full suite.
- `NORMAL_PATH` — a few files: affected tests, safe overlap on.
- `DEEP_PATH` — shared surface/high risk: affected → suite, advisor/browser
  permitted.
- `RELEASE_PATH` — **THE RELEASE PATH IS SACRED.** Receipt reuse is **disabled**,
  `freshGatesRequired` is true, and `requiredFreshGates` names `npm test` and
  `release:verify`. The runtime may **attribute** this work but must never
  **skip** it. `assertFreshGateAllowed()` refuses any release gate backed by a
  cached receipt.

## Non-goals / explicit limits

- **No second owner.** V16.12 does not create a second `WorkspaceStateOwner`,
  Metrics V2, Verification Ladder, EvidenceBroker or AdvisorSessionManager. It
  composes the existing owners.
- **No competing model turns.** The composition layer describes *what* should
  happen; it never runs a model turn or the suite on its own.
- **No write parallelism.** Source writes are serialized behind the Pre-write
  Fence.
- `npm run bench:v16.12` reports `SIMULATED_ONLY` / `synthetic: true`; per-scenario
  timings are **not** summed into a task-level speedup, and
  `PROVIDER_TOKENS = "NOT_MEASURED"`.

## Production wiring

`pi/extensions/ues.ts` hydrates the acceleration stack lazily
(`EXECUTION_ACCELERATION` and the capability entries in `lib/lazy-runtime.mjs`),
so boot pays for none of it and **PI_ONLY spawns zero browser**. The read-only
`ues_code` `verification-plan` action prefers the V16.12 incremental plan and
**falls back to the raw V16.10 ladder** if the module cannot hydrate, so the
action never regresses. `/ues-status` reports the plan for a NORMAL task and the
receipt-cache stats; a null module reads as `unavailable`, never as a fake plan.
The V16.11 lifecycle, epochs, recovery, poll fallback and submit guard are
preserved unchanged.

## Verification

- `npm run integrity` — V16.8/V16.9/V16.10/V16.11/**V16.12** source contracts all
  enforced; every prior release stays byte-stable.
- `npm run eval:v16.12` — the V16.12 capability + source-integrity suites.
- `npm run bench:v16.12` — the deterministic acceleration benchmark.
- `npm run release:verify` — the full gate (ci + every prior eval + V16.12).