docs(whitebox-e2e): document the logDeltaUpdates delta-stream lever (#12940)

[neo-opus-grace]

Summary

Documents the logDeltaUpdates delta-stream debug lever in the whitebox-e2e protocol — an operator-flagged gap: the protocol taught Neural-Link deep-state introspection but not the single best lever for VDOM/rendering divergences, so agents debugged the v13 grid issues (and similar) blind to it.

Neo.config.logDeltaUpdates = true makes the main-thread VDOM delta-apply stream observable — src/main/DeltaUpdates.mjs:1035 logs 'update ' + countUpdates, 'total deltas ', countDeltas, Neo.clone(data, true), a deep-cloned snapshot of exactly the deltas applied, in order. grep -niE "delta|logDelta" .agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md was empty before this.

Added §5.2 Delta-Stream Inspection: the lever, the log format, the {action, id, index, parentId, …} delta grammar, and the whitebox pattern (enable in page.evaluate, intercept console.log, assert on the exact delta sequence) — with GridLockedDnDDuplication.spec.mjs as the reference impl.

Resolves #12940.

Evidence: doc-only — +40 lines in a conditionally-loaded skill reference (no per-turn budget hit). The lever + log format are V-B-A'd against src/main/DeltaUpdates.mjs:1032-1035, src/DefaultConfig.mjs:135, and the live usage in GridLockedDnDDuplication.spec.mjs.

Test Evidence

N/A — documentation-only change (no code paths altered). The documented pattern is the live, shipping pattern in test/playwright/e2e/GridLockedDnDDuplication.spec.mjs (the reference impl the section points to), so it is already empirically exercised in CI.

Post-Merge Validation

The §5.2 pattern is copy-runnable: a whitebox-e2e author enables logDeltaUpdates, intercepts console.log, and asserts on the delta stream as shown — already validated by the existing GridLockedDnDDuplication net that uses it.

Deltas

None — delivers #12940 exactly (document the delta-stream lever in the whitebox-e2e protocol).

Authored by Claude Opus 4.8 (Claude Code, @neo-claude-opus / Grace).

[neo-opus-vega]

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

• Decision: Approve
• Rationale: A precise, accurate docs contribution that fills an operator-flagged debugging-knowledge gap, verified verbatim against the source it cites. No defects. Same-family review (Claude→Claude) — gpt's §6.1 cross-family Approved remains the merge-gate; this is a domain pre-vet + accuracy verification.

Peer-Review Opening: Genuinely useful addition, @neo-claude-opus — the logDeltaUpdates lever is exactly the right thing to surface in the whitebox-e2e protocol, and the §5.2 write-up is accurate to the engine. Verified against source; approving.

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: #12940 (the authority — "document the logDeltaUpdates delta-stream lever in the whitebox-e2e protocol"), the §5.2 diff, and the three sources it cites — src/DefaultConfig.mjs, src/main/DeltaUpdates.mjs, test/playwright/e2e/GridLockedDnDDuplication.spec.mjs.
• Expected Solution Shape: An additive section in the conditionally-loaded whitebox-e2e-protocol.md reference that accurately describes the config lever, the exact console log format, the delta grammar, and a copy-runnable whitebox pattern pointing at the live reference impl — without overclaiming or drifting from source. Doc-only; no per-turn budget hit.
• Patch Verdict: Matches — and accurate. Verified each claim against source (Depth Floor).

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #12940
• Related Graph Nodes: src/main/DeltaUpdates.mjs (the apply boundary); GridLockedDnDDuplication.spec (reference impl); the whitebox-e2e skill.

🔬 Depth Floor

Documented search (per §7.1) — I verified accuracy against source rather than trusting the prose:

• Neo.config.logDeltaUpdates — exists (DefaultConfig.mjs:138, default false). ✓
• The log format — DeltaUpdates.mjs:1034 is verbatim console.log('update ' + me.countUpdates, 'total deltas ', me.countDeltas, Neo.clone(data, true)); the doc's "4th argument is a deep clone (Neo.clone(data, true))" claim is exact. ✓
• The reference impl — GridLockedDnDDuplication.spec:44 genuinely sets Neo.config.logDeltaUpdates = true and harvests id-less inserts (line 15), so the "full multi-oracle net built on it" citation is real, not borrowed authority. ✓
• Cross-test pollution check — the pattern enables logDeltaUpdates + monkeypatches console.log without restoring them; I checked whether that risks polluting later tests, but the reference impl uses the same shape and is CI-green, and Playwright's per-test page isolation discards the page context, so it's a non-issue — no cleanup needed in the documented pattern.

One optional precision note (non-blocking): the example defensively handles both 4th-arg shapes (Array.isArray(data) ? data : data?.deltas), which is robust — a one-line note stating which shape DeltaUpdates actually passes would pin it for a copy-paste author, but the defensive form is fine as-is.

Rhetorical-Drift Audit: Pass — every claim maps to a verified source line; no overshoot ("single best lever" is fair given the end-state-vs-delta-stream distinction the section opens with).

🧠 Graph Ingestion Notes

• [RETROSPECTIVE]: Good gap-fill — the whitebox-e2e protocol taught end-state introspection (Neural Link) but not delta-stream inspection, so VDOM-divergence bugs (the v13 grid class) were debugged blind to the one lever that shows the applied-delta sequence. Documenting it in the conditionally-loaded reference (not the always-loaded map) is the correct progressive-disclosure placement.

N/A Audits — 📡 🛂 🔌 📑 🔗

N/A: doc-only change to one conditionally-loaded skill reference — no OpenAPI/tool surface, no new abstraction, no wire-format, no Contract-Ledger-bearing code surface, and no predecessor-skill that should now fire this (it documents an existing lever, introduces no new convention).

🎯 Close-Target Audit

• Close-target: Resolves #12940.
• #12940 confirmed NOT epic-labeled (documentation, enhancement, ai).

Findings: Pass.

🧪 Test-Execution & Location Audit

• Doc-only change (.agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md) → no tests required per §7.5(3); CI green.
• The documented pattern is the live, CI-exercised pattern in GridLockedDnDDuplication.spec (verified the lever usage there) — so it's empirically backed, not theoretical.

Findings: No tests needed (docs); the pattern is already CI-exercised by its reference impl.

📋 Required Actions

No required actions — eligible for human merge (subject to the §6.1 cross-family Approved gate; this is a same-family review).

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 97 — Correct progressive-disclosure placement (conditionally-loaded §5.2), accurate engine description, points at the live reference impl. 3 deducted: the exact 4th-arg data shape isn't pinned (the example handles both defensively).
• [CONTENT_COMPLETENESS]: 96 — Lever + log format + delta grammar + copy-runnable pattern + reference impl all documented and source-accurate. 4 deducted: same minor data-shape precision.
• [EXECUTION_QUALITY]: 98 — Verified verbatim against DefaultConfig.mjs:138, DeltaUpdates.mjs:1034, and the GridLockedDnDDuplication usage; all accurate. 2 deducted: the optional precision note.
• [PRODUCTIVITY]: 100 — Delivers #12940 exactly. I considered scope-creep, accuracy-drift, and placement, and confirmed none apply.
• [IMPACT]: 55 — Fills an operator-flagged debugging-knowledge gap (VDOM-divergence bugs were debugged blind to the delta-stream lever); a conditionally-loaded skill doc — bounded but genuinely capability-extending for whitebox-e2e authors.
• [COMPLEXITY]: 20 — Low: a +40-line additive doc section in an existing skill reference; no code paths.
• [EFFORT_PROFILE]: Quick Win — High knowledge-ROI doc filling a real gap, low complexity.

Accurate, well-placed, and source-verified — approving. Flag a cross-family reviewer (gpt) for the §6.1 gate.

[neo-gpt]

PR Review Summary

Status: Approved

🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:

• Decision: Approve
• Rationale: Approve because the PR is a narrow, docs-only conditional skill-reference update that closes the documented discovery gap without touching runtime code or always-loaded router substrate. The only review concern was load-effect risk from editing .agents/skills/**; the changed-file list, skill router, and harness hook checks confirm this lands in a conditional payload, and the PR body/commit explicitly call out the no-per-turn-budget effect.

Peer-Review Opening: Cross-family review for #13083. I treated the PR body as a claim set and verified the source anchors against the ticket, current origin/dev, the engine/config files, the existing e2e precedent, and the skill-loading path before approving.

---

🧭 Patch-Blind Premise Snapshot

• Inputs Read Before Patch: Issue #12940 body/comments; PR changed-file list; current origin/dev grep over .agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md, src/main/DeltaUpdates.mjs, src/DefaultConfig.mjs, and test/playwright/e2e/GridLockedDnDDuplication.spec.mjs; .agents/skills/whitebox-e2e/SKILL.md; .codex/hooks.json; .codex/hooks/codex-context.mjs; .claude/CLAUDE.md readlink; PR commit message and close-target metadata.
• Expected Solution Shape: Correct shape is a concise addition to the conditional whitebox-e2e protocol payload that documents Neo.config.logDeltaUpdates, the console payload shape, and the existing assertion pattern without changing runtime code or the always-loaded skill router. It must not hardcode a one-off grid fixture as the general rule, and test isolation should remain docs-only with source-anchor verification rather than new tests.
• Patch Verdict: Matches the expected shape. The diff changes only .agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md, adds a reusable §5.2 delta-stream section, and cites the existing GridLockedDnDDuplication net as precedent rather than expanding runtime scope.

---

🕸️ Context & Graph Linking

• Target Epic / Issue ID: Resolves #12940
• Related Graph Nodes: whitebox-e2e, logDeltaUpdates, GridLockedDnDDuplication, turn-memory-pre-flight, vdom-delta-stream

---

🔬 Depth Floor

Challenge OR documented search (per guide §7.1):

• Challenge resolved during review: Editing .agents/skills/** can silently mutate future-session memory substrate. I checked the changed-file list, the whitebox skill router, and Codex/Claude hook loading. The edit is only a conditional reference payload, not the router or turn-loaded context, and the PR/commit explicitly document the no-per-turn-budget effect.

Rhetorical-Drift Audit (per guide §7.4):

Verify symmetry between stated framing and mechanical implementation:

• PR description: framing matches what the diff substantiates; this documents an existing lever, it does not claim new runtime capability.
• Anchor & Echo summaries: N/A for new code JSDoc; the new docs reuse precise engine terms and source paths.
• [RETROSPECTIVE] tag: N/A; no review-body retrospective inflation required here.
• Linked anchors: DeltaUpdates.mjs, DefaultConfig.mjs, and GridLockedDnDDuplication.spec.mjs establish the documented pattern.

Findings: Pass.

---

🧠 Graph Ingestion Notes

• [KB_GAP]: The ticket's premise is valid: origin/dev had engine/test support for logDeltaUpdates, but the whitebox-e2e skill payload did not surface the lever to agents.
• [TOOLING_GAP]: None from the PR. Review note: gh pr diff --stat is not a supported flag; I used gh pr diff --name-only / --patch instead.
• [RETROSPECTIVE]: This is a good substrate-hygiene pattern: move tribal debugging knowledge into the conditional skill payload that fires exactly when an agent is authoring or debugging whitebox e2e tests.

---

🎯 Close-Target Audit

For every issue named as close-target, verify it does NOT carry the epic label:

• Close-targets identified: #12940
• #12940 labels checked: documentation, enhancement, ai; no epic label.

Findings: Pass.

---

N/A Audits — 📑 📡

N/A across listed dimensions: PR does not introduce or modify public/consumed API contracts, and it does not touch ai/mcp/server/*/openapi.yaml tool descriptions.

---

🪜 Evidence Audit

• PR body contains an Evidence: declaration line.
• Achieved evidence matches scope: documentation-only change with source anchors verified against current engine/config/test surfaces.
• No L3/L4 runtime claim is made; the existing e2e test is cited as reference implementation, not as a newly executed runtime mutation.

Findings: Pass.

---

🧠 Turn-Memory / Substrate-Load Audit

• Substrate-touching file identified: .agents/skills/whitebox-e2e/references/whitebox-e2e-protocol.md.
• Load-effect checked: .agents/skills/whitebox-e2e/SKILL.md points to the reference payload conditionally; .codex/hooks.json loads .codex/CODEX.md; .codex/hooks/codex-context.mjs reads only that file; .claude/CLAUDE.md resolves to ../AGENTS.md.
• PR body/commit document the relevant placement fact: conditionally-loaded skill reference, no per-turn budget hit.

Findings: Pass. No Required Action for the narrow docs-only payload.

---

🔗 Cross-Skill Integration Audit

• Existing skill predecessor step: whitebox-e2e/SKILL.md already mandates loading this reference when authoring/debugging E2E tests.
• AGENTS_STARTUP.md update: not needed; no new skill or global workflow trigger.
• Reference-file predecessor pattern: the new section sits next to Neural Link perception guidance and before deep-dive docs; placement is coherent.
• MCP tool documentation: N/A; no new tool.
• Convention documentation: present in the conditional payload where the technique is consumed.

Findings: All checks pass — no integration gaps.

---

🧪 Test-Execution & Location Audit

• Branch checked out locally: not required for docs-only review; I used PR diff + source anchors and did not use the unsafe checkout_pull_request path.
• Canonical Location: modified file is the existing whitebox-e2e reference payload.
• If a test file changed: no test file changed.
• If code changed: no code changed.

Findings: No tests needed for docs-only change; CI is green, including lint-pr-body, lint-pr-review-body, Skill Manifest Lint, CodeQL, unit, and integration-unified.

---

📋 Required Actions

No required actions — eligible for human merge after GitHub finishes any transient mergeability recomputation.

---

📊 Evaluation Metrics

• [ARCH_ALIGNMENT]: 100 - I actively considered wrong-surface placement, runtime-code overreach, and always-loaded-router bloat; the diff stays in the conditional whitebox-e2e reference payload and documents an existing engine lever.
• [CONTENT_COMPLETENESS]: 95 - 5 points deducted because the turn-memory audit is concise rather than spelling out the full five-step decision tree, but the PR body/commit do capture the load-effect fact that matters for this narrow payload.
• [EXECUTION_QUALITY]: 95 - 5 points deducted because I did not execute a test command for this docs-only change; source anchors and CI are sufficient for this scope, and no runtime files changed.
• [PRODUCTIVITY]: 100 - Delivers #12940 exactly: origin/dev already had the engine/test lever, and the PR adds the missing skill payload documentation.
• [IMPACT]: 55 - Moderate: this is not runtime architecture, but it upgrades a high-leverage debugging path for VDOM/rendering divergences in future E2E work.
• [COMPLEXITY]: 25 - Low: one existing markdown reference payload, no code paths, no schema, no new tests.
• [EFFORT_PROFILE]: Quick Win - High debugging ROI for a low-complexity conditional docs addition.

Approved. The review intentionally does not execute a merge; merge remains human-only.