feat: implement project verification goals and proof runs (#187)

[Joncallim]

Source Issue

Issue: #187

Agent Run

Runtime: manual
Run ID: n/a
Delivery mode: combined

Summary

Architecture evidence: docs/architecture/issue-187-verification-goal-run-policy.md plus the checked-in orthogonal review / normative amendment trail through Round 14.

Implementation evidence: this is a combined delivery PR. It now ships the complete manual-execution vertical slice for project verification goals, end to end:

• Strict executable goal schema v2 with shared v1/v2 registry parsing; v1 manifests remain byte/meaning compatible.
• Code-owned operation eligibility and execution-profile boundary: only exact Operation Catalog references on the reviewed allowlist are executable.
• Manifest v2 with execution bindings; immutable v2 snapshot persistence; protected registry execution bindings (migration 0034).
• First-class goal-run persistence: execution schema (migration 0035) and protected runtime routines (migration 0036) covering admission, lease claim/renewal, child operations, evidence snapshots, terminalization, and recovery fencing.
• Project verification policy with a default-disabled head, seeded on first use and revalidated live at admission.
• The safe manual runner itself: the route admits through forge_admit_verification_goal_run_v1 (the application login has no direct INSERT on run tables, so no bypassing write exists), then executes synchronously. The runner claims and renews the business lease, re-verifies the pinned executable identities, records the repository and environment evidence snapshots, runs the exact bound operations in canonical ordinal order through the root-anchored launcher, and terminalizes to a deterministic pass/fail/inconclusive outcome through forge_terminalize_verification_goal_run_v2, which requires the evidence set for a passed result.
• Queue-delivery and scheduler database authority: schedule-binding reconcile and per-goal slot-claim routines, with the privilege reconcile script and installer migration proof updated to match.

Remaining delivery scope: the ticking scheduler worker that drives the schedule-slot routines; goal history (last known-good / first observed failing) and the #185/#186 outcome/reliability integration; and closure E2E evidence. The PR remains draft while these are incomplete.

Acceptance Criteria Validation

• A project can define and validate at least one repository-backed verification goal. — existing v1 remains byte/meaning compatible; executable schema v2 validates, imports, snapshots, and activates through manifest-v2 protected registry bindings in migration 0034.
• A goal can run on demand and persist structured pass/fail/inconclusive evidence. — the manual runner admits through the protected routine, executes the bound operations under the root-anchored launcher, records repository/environment evidence snapshots, and terminalizes atomically; a passed outcome is impossible without the required evidence set.
• Unsafe or unsupported command definitions fail closed before execution. — v1 rejects commands/inputs; executable v2 accepts only reviewed allowlist references with matching capability. Admission throws before any DB write for non-allowlisted or capability-mismatched operations, the runner re-resolves the binding and refuses stored-policy digest drift, and the launcher re-verifies the pinned executable immediately before exec and never classifies a spawn-level failure as a successful exit.
• Scheduled runs do not overlap or create duplicate evidence for the same goal/ref. — migration 0036 ships the protected slot-claim and binding-reconcile authority that enforces one active slot per goal/ref at the database level; the scheduler worker that invokes it remains in the follow-up scope above.
• Forge records the last known-good state and the first observed failing state when determinable. — history implementation remains in the follow-up scope above.
• Goal runs emit canonical outcomes compatible with [FEATURE] Normalize execution outcomes and stop reasons #185 and reliability evidence compatible with [FEATURE] Add capability reliability ledger #186. — the run contracts define the canonical outcome vocabulary; subject/reliability integration remains in the follow-up scope above.
• Goal failure does not trigger an unreviewed code repair. — the architecture and executable contracts expose no repair/autonomy action and accept no arbitrary command/model field.
• Disabled goals do not run. — the route rejects disabled and non-manual goals, and the admission routine revalidates the live policy head, registry head, and entry/snapshot identity under the canonical lock order before any run row exists.
• Tests cover schema validation, command policy, deduplication, pass/fail history, and redaction. — schema, command policy, admission idempotent replay, launcher classification, runner lease/evidence handling, and route SQLSTATE mapping are covered by 49 new focused tests; history and redaction coverage lands with those remaining slices.

Tests / Verification

• verification-goal-launcher.test.ts (14 tests): exit-code classification; spawn-level failures (ENOENT, STDIO_MAXBUFFER) surface as spawnError and never as exit 0; killed children classify as timeout; executable replacement before launch fails closed as executable_changed; root dev/ino mismatch fails as root_changed; abort classifies as cancelled; the safe launch environment strips NODE_OPTIONS/NODE_PATH and every GIT_* redirection even when passed through overrides. Writing these tests exposed a real defect: an abort landing in the handle-close window briefly left the launch rejection unobserved (a process-level unhandledRejection under strict policy). The launcher now pins a marker handler at promise creation so the rejection is always adopted while callers still receive it normally.
• verification-goal-runner.test.ts (7 tests): happy path with evidence snapshots and lease-token-fenced child finalize; legacy operations policy key rejected as operation_contract_changed; spawn error → operation_infrastructure_failed; digest drift → operation_contract_changed; lease loss → lease_lost with no terminalize attempt; launcher error → root_changed; dirty repository → repository_dirty.
• verification-goal-admission.test.ts (5 tests): the protected routine call shape with no direct INSERT; the live policy head id and sequence passed as real parameters (bigint never crosses the JSON boundary); canonicalOperationOrdinals in the resolved policy; idempotent replay; non-allowlisted or capability-mismatched operations throw before any DB call.
• verification-goal-runtime-migration.test.ts (3 tests): migration 0036's hardened routine signatures (9-arg finalize with lease token, 6-arg slot claim), the queued-only claim guard, the lease-token fence, the passed-evidence guard, and the child_begun event, all mirrored in the privilege reconcile script.
• verification-goal-runs-route.test.ts (20 tests): POST/GET happy paths; 401/503/400/404/409 guards; disabled and non-manual goal rejection; closed SQLSTATE mapping (P1871/P1872/P1873/P1876 → 409, P1874 → 429); generic 500 carries a correlation id and leaks no secret material.
• Full suite: 2165 passed / 64 skipped across 162 files; tsc --noEmit clean; ESLint clean on all changed files.

Risks / Follow-up

This is intentionally a large combined delivery PR because #187's architecture and implementation share one security/evidence contract. Internal commits remain small and reviewable: architecture rounds first, then schema/registry slices, then the runtime slices, then the hardening and test slices. Architect first is an ordering/evidence rule, not a phase-specific PR rule.

The PR head branch was aligned to the delivery branch tip (codex/issue-187-goal-definition-v2). No content was lost: the three fix commits unique to the old head are contained in, or strictly superseded by, the delivery branch.

V1 proof execution remains read-only and does not enable arbitrary shell/test/build commands, host repository writes, auto-repair, autonomy changes, Sentinel actions, branch/commit/PR/merge automation, or live MCP grant issuance. Stronger same-UID/host confinement remains a separately stated residual boundary and is not silently claimed by this PR.