go-docs-promise-vs-reality-jit-scoping
Root cause (U-GAP-018): README.md promised "hot paths become native code" (a runtime-execution claim) while jitSandboxAdapter.Execute was — and is, by design — a hard NOT_IMPLEMENTED stub. The E2E battery (provision.sh) asserts jit echo → 501, so implementing execution to match the README would break the battery. The task offered implement-vs-document; checking the battery's design constraints first forces the DOCS route.
The fix: scope JIT as generation-only (Phase 1) with validation/deployment as planned Phase 2, and lock that scoping with a docs-contract regression test. No execution code changed — the 501 contract is preserved.
Before (the false promise):
Hot paths become native code at runtime: the JIT compiles and executes
hot paths as native code in the sandbox.
After (scoped, matches reality): ```markdown Scope (U-GAP-018): Phase 1 ships generation only. No hot path executes generated native code at runtime yet.
Project at `~/u-gap-018` (`go 1.26.0`, module `gap018`). Verified end-to-end: | Check | Result | |---|---| | `gofmt -l .` / `go vet ./...` | clean | | `go test ./... -count=1` | **5/5 PASS** (`TestExecuteReturnsNotImplemented`, `TestStatusNotImplementedIs501`, `TestDocsContract`, `TestGenerateAcceptsValidIR`, `TestGenerateRejectsEmptyIR`) | | `./provision.sh` (E2E battery) | **ALL BATTERY CHECKS PASSED** (exit 0): gen→OK, echo→501+non-zero, docs contract PASS | **Regression demo (the actual gap):** reverting README to the buggy claim produced `--- FAIL: TestDocsContract — README re-introduces promise-vs-reality claim "hot paths become native code"`; restoring the scoped README → PASS. Also failed when scoping markers were dropped (missing `Phase 1/Phase 2/generation-only/501/NOT_IMPLEMENTED`). **Edge cases tested:** - `jit` with no args, `jit gen` without `-expr`, unknown subcommand → all exit 2 (usage error), never touching the 501 contract. - `jit echo` exits non-zero while printing the `501` marker — the battery requires *both* (a naive implementer that returns 200 breaks check 2/3). - Battery negative path: if the `501` marker or non-zero exit is missing, `provision.sh` fails with a specific message — proving implementing execution would break the battery, i.e., why implement-vs-document resolves to DOCS. - Empty/whitespace IR rejected by `Generate`; valid IR produces a non-empty deterministic listing. - Build collision edge (`-o jit` vs the `jit/` package dir) fixed by building into `bin/`; final tree is clean of build artifacts. ---
{"model": "deepseek-v4-flash", "problem_class": "go-docs-promise-vs-reality-jit-scoping", "result": "passed", "tests": 5}