Opt-in actual renderer glGetError stage timings

The existing bounded GL diagnostic ring now records stages inside actual renderer opcode 12. This adds evidence for a future authorized investigation of the preserved 12,034.885 ms boundary described in the offline diagnosis. It does not explain that earlier native stall retrospectively or repair it. Evidence: scratch/runs/20261109-gl-error-stage-timing-1850/ (exact Git base, small relevant patch, focused-test and locked-build logs).

Usage

Use the established control after the GL host module loads and before the ordinary app's host imports/GL bridge are constructed:

GLRenderHost.configureDiagnostics({enabled: true, maxRecords: 128});
// Construct the ordinary app through its existing route.
const partial = GLRenderHost.diagnosticSnapshot(); // synchronous, no RPC
GLRenderHost.configureDiagnostics({enabled: false}); // future bridges only

Direct constructors can use glBatchDiagnostics: {enabled:true,maxRecords:128} and bridge.diagnosticSnapshot(). Explicit enabled:false overrides the module default. Configuration does not retrofit an existing bridge. No new flag, endpoint, timeout or scheduling policy is introduced. Storage remains the same private v1 shared ring: 1–128 records, default 64, 64 bytes per record plus a 64-byte header. Stage events consume this existing capacity, so old history will overwrite sooner. The host's bounded records and latest-bridge retention policy remain unchanged.

Stage boundaries

Each prefix has -enter, -exit and -error kinds, appended to the existing kind table without changing older IDs or the ring ABI:

Prefix IDs Exact operation enclosed
get-error-context 17–19 _current(), including context lookup, drawable validation and any WebGL activation it performs
get-error-flush 20–22 Existing conditional frontend.flushPendingDraw()
get-error-frontend 23–25 Frontend error check, return-value read and clear
get-error-backend 26–28 Existing frontend.backend.getError() call

The backend stage includes the context error facade: it may return a retained error without reaching the device. Otherwise it includes device getError() and native WebGL getError(). No change to gpu-backend.js is necessary. Context activation and pending-draw submission may themselves invoke backend operations; a long enclosing stage identifies that JS operation, not a driver cause. There is no backend stage when a frontend error is returned and no flush/frontend/backend stage when there is no current context.

All stages carry the existing endpoint, owner, context, frame token, opcode (12), command offset/size and aux identity. Associate stage records with their enclosing opcode-enter/opcode-exit or opcode-error interval in ring sequence order. Every exit/error links to its own stage enter through beginSequence; durationMs is the difference between its two renderer-owner performance.now() readings. Host and renderer clocks must not be subtracted. The opcode's stats/hook/capture setup and small gaps between stages remain outside those stages; the outer opcode interval continues to cover them. An original thrown value is rethrown, with a stage error followed by existing opcode/stream/batch error markers. Boundary-error counts count markers, not distinct failed operations. Replay's existing final flush still occurs after the opcode and is covered by the stream boundary.

The enter marker commits before the observed operation. An independent host snapshot can read it without scheduling renderer JS. Missing exit, overwrite, observer-clock failure, unavailable slot or retirement remains UNKNOWN; none establishes completion or a native cause. Snapshots retain the existing status: 'UNKNOWN'. Renderer destruction still marks retirement.

Semantics and verification limits

Only an armed renderer installs the stage hook. The unarmed opcode path adds one opcode-specific hook check and retains the existing context/flush/error implementation; it makes no stage callback, clock read, closure allocation or diagnostic bookkeeping. The armed path preserves context activation, access order, pending flush, frontend error return/clear, retained backend error return/clear, backend query and thrown-value identity. Observer failures remain contained by the existing recorder.

Passed node tools/q3-gl-batch-diagnostics.test.cjs: actual renderer adapter, Stream and OpenGLHostBridge.call(12); real frontend pending-draw merging and consumption; actual GPU context error facade and device getError method with a controlled native GL stub; frontend and retained error clearing; flush-set errors; context/flush/frontend/backend thrown values; no current context; observer-clock failure; unarmed zero diagnostic clocks; partial enter reads; 200 additional calls in a four-record ring; existing Manager/Endpoint/Node Worker dispatch, ordering, error and off/on parity controls. Locked flock /tmp/wine-build.lock bash tools/build.sh also passed.

These offline controls establish instrumentation and semantic behavior only. Artificial clock increments and controlled backend operations do not reproduce or identify the cause of the native 12-second delay. No browser, local Chrome, leased box, heavy runtime or nested worker was launched. Box ID/state/expiry and stop receipt: NOT_CREATED / N/A; no runtime watchdog or stop was needed. The ReturnFire1822 then Nox1828 runtime queue is unchanged. Next is a separately authorized native observation using these stages under unchanged ownership, routing, debugger, capture, first-failure and timeout guards; screenshot and post-navigation transport completion remain separate unresolved evidence.