feat(gpu): slice 4 runtime graphics diagnostics evidence contract (refs OpenCoven/psyche-build#229)

[CompleteDotTech]

Outcome

Slice 4 core (#229, bead psyche-z7c.4): the runtime graphics diagnostics
evidence contract and its machine-checkable implementation — additive, no existing file touched.

• docs/gpu/SLICE4-DIAGNOSTICS-CONTRACT.md — merging native platform/process facts with strict
  browser graphics evidence; bounded rendering/transport metrics; the debug-authorized
  deterministic 1/6/12/24-terminal stress-harness boundary (the harness itself is [psyche-z7c.4.4] Add the debug-authorized rendering stress harness #230's
  deliverable); the diagnostics surface boundary ([psyche-z7c.4.5] Expose the in-app developer GPU diagnostics surface #231's deliverable); evidence policy quoted
  verbatim and enforced (accelerated/software/unknown/unavailable reported only from runtime
  evidence; unsupported version/backend/adapter fields omitted — never placeholder-filled; hosted
  compilation never proves physical GPU acceleration); metrics retention (20,000 rAF samples) and
  polling cadence (1 s minimum) bounds.
• src/gpu/slice4ReportMerge.ts — versioned schema-v1 pure TS module: mergeSlice4Reports()
  (deterministic native + browser merge; strict unknown-field rejection at every level; typed
  bounded rejections; deep-frozen outputs; canonical key order), classifyRenderer() (fail-closed
  accelerated/software/conflicting→unknown/unavailable), boundedMetricsWindow() (oversize input
  → typed oversize rejection, never silent truncation; sub-second polling cadences rejected).
• __tests__/gpuSlice4ReportMerge.test.ts — 37 focused tests: merge determinism (byte-identical
  JSON, canonical key order, input-order independence), classification table (ANGLE Metal /
  Direct3D / Vulkan / OpenGL hardware, SwiftShader / llvmpipe / Microsoft Basic Render Driver
  software, masked and non-strict unknown, no-API unavailable, conflicting → unknown),
  omission-not-placeholder, bounds enforcement, unknown-field rejection.

Refs #229 (bead psyche-z7c.4; parent epic #228; canonical outcome gh-199).

Scope and boundaries

Done here:

• Evidence contract document, the v1 merge/classification/metrics module, and its tests. Nothing
  else.

Deliberately NOT done (owned by sibling slices — no duplication, no collisions):

• Stress harness — [psyche-z7c.4.4] Add the debug-authorized rendering stress harness #230 (psyche-z7c.4.4) owns the process-spawning harness, native steady/
  burst/rewrite fixture commands, scenario execution, and the launcher. This slice fixes only the
  authorization boundary that harness must satisfy: debug build + startup environment
  authorization, fixed fixtures only, fixed 1/6/12/24 scenario set.
• In-app diagnostics surface — [psyche-z7c.4.5] Expose the in-app developer GPU diagnostics surface #231 (psyche-z7c.4.5, currently blocked by [psyche-z7c.4.4] Add the debug-authorized rendering stress harness #230). This slice
  fixes only what the surface may render: present fields only (omitted fields = hidden rows, no
  placeholders), prominent software fallback, controls gated on debugBuild && stressAuthorized.
• Verification matrix — [psyche-z7c.4.6] Document and execute the GPU verification matrix #232's charter (physical-collection procedure and manifest validator;
  not started by anyone yet as far as this slice observed). The acceleration vocabulary here is
  kept identical to the matrix's so evidence maps without translation.
• No native Rust code, no changes to frames/PTY/terminal rendering (slices 1–3), no CSP or
  capability changes, no package scripts or dependency changes, no workflow changes, no barrel
  edits, no generated outputs.

Blocked dependencies observed: #231 is blocked by #230 upstream; both are outside this slice. This
PR does not depend on either to land.

Risk class

• R1 — documentation or isolated tests (this change: additive docs + pure module + tests)
• R2 — product behavior
• R3 — authority, security, protocol, persistence, recovery, or consequential actions
• R4 — release, repository governance, credentials, generated-source ownership, or cross-repository identity

Validation and evidence

All commands run from the worktree on branch psyche/issue-229-gpu-slice4-evidence (based on
origin/main at f323879):

Command	Observed result
npx pnpm install --frozen-lockfile	exit 0; lockfile unchanged
npx pnpm exec vitest --run __tests__/gpuSlice4ReportMerge.test.ts	1 file passed; 37/37 tests passed
npx pnpm exec tsc --noEmit	exit 0
npx pnpm exec tsc -p tsconfig.test.json --noEmit	exit 0
git diff --check	exit 0, no output
npx pnpm test (full portable suite, with change)	10 files failed / 56 tests failed; 4824 passed
npx pnpm test baseline (same command after git stash -u)	same 10 files failed / same 56 tests failed; 4787 passed

Baseline comparison: the 56 full-suite failures are pre-existing and environmental (tmux/PTY- and
process-dependent suites on this host: daemon/spawnPromptTransport.test.ts, daemon/bridge.test.ts,
macosBuildChannels.test.ts, processIdentity.test.ts, runProcess.test.ts, …). My change adds
exactly +37 passing tests and zero failures vs baseline.

Explicit gaps (not run here / honest gaps):

• No physical GPU evidence on macOS/Windows/Linux — no accelerated claim is made anywhere in
  this PR; hosted CI on virtualized runners validates types/tests/fallback classification only.
• No Rust/cargo proof (host has no toolchain; native diagnostics are out of this slice's scope).
• scripts/agent-bootstrap / scripts/agent-check not run (require tmux; unavailable here).
• Stress scenarios were never executed — no terminal/process was spawned; the boundary is
  specified and unit-tested at contract level only.

Working record

docs/working-records/issue-229-gpu-slice4-evidence.md — outcome, boundaries, exact commands and
results, head SHAs (438da06 deliverables; PR head is authoritative), test counts, proof gaps,
rollback, and security notes.

Generated outputs

None touched: src/utils/generated-agents-doc.ts, desktop web bundles, Xcode project/Info.plist,
and dist/** are unchanged.

Security and privacy

• No credentials, tokens, private keys, raw prompts, unrestricted terminal output, private
  repository contents, environment dumps, private URLs, or unredacted personal paths are
  introduced by this change.
• Evidence and fixtures contain only synthetic, bounded renderer-identity format examples
  (public ANGLE/Mesa/SwiftShader formats); no host, machine, or personal data.

Review focus

• The classification table's fail-closed rows in
  docs/gpu/SLICE4-DIAGNOSTICS-CONTRACT.md vs classifyRenderer() — especially: strict context +
  masked renderer → unknown (never accelerated), software markers authoritative over strict
  contexts, conflicting evidence → unknown, no usable API → unavailable.
• Omission-not-placeholder discipline: masked/absent engineVersion/backend/adapter/
  supportingProbe/process keys are absent (no null/"unknown" placeholders), with
  unsupportedFields naming missing graphics identity fields.
• Bounds honesty: oversize metrics windows are typed rejections (never silent truncation);
  sub-second polling cadences are rejected; error lists are bounded with an explicit suppression
  marker.

Release and support impact

Additive documentation, one pure versioned module, and tests. No public command, schema,
persisted format, error, security boundary, package dependency, or workflow change. No support
matrix or roadmap change. Desktop GPU acceleration support claims remain governed by the
verification matrix (#232) and physical evidence; nothing here asserts acceleration for any
platform.

Pipeline note: upstream OpenCoven PR/issue writes are token-denied for this pipeline, so this PR
runs on the CompleteDotTech fork with real GitHub Actions CI; the branch is ready for a maintainer
one-click PR to upstream.

Refs #229

[vercel]

@CompleteDotTech is attempting to deploy a commit to the 0xBuns Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
psyche-build-docs	Ready	Preview	Aug 30, 2026 2:59pm

[BunsDev]

Closing as a non-executable duplicate contract slice. The canonical Slice 4 sequencing remains in the owning roadmap/issues; future work should start from current main with runtime integration and one acceptance gate.