[PR #4179] [MERGED] fix(javascript): bind native handoffs to canonical byte identity #6113

Closed
opened 2026-10-31 01:11:57 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4179
Author: @N0zoM1z0
Created: 10/15/2026
Status: ✅ Merged
Merged: 10/15/2026
Merged by: @N0zoM1z0

Base: main ← Head: fix/javascript-native-handoff-identity


📝 Commits (1)

  • d86a9e3 fix(javascript): bind native handoffs to canonical byte identity

📊 Changes

7 files changed (+1820 additions, -13 deletions)

View changed files

📝 docs/javascript-application-workflows.md (+8 -0)
➕ docs/verification/javascript-native-handoff-identity-2026-10-15.json (+1052 -0)
➕ docs/verification/javascript-native-handoff-identity-2026-10-15.md (+179 -0)
📝 package.json (+1 -0)
➕ scripts/verify/javascript/native-handoffs.mjs (+348 -0)
📝 src/domain/javascript/javascriptNativeHandoff.ts (+9 -13)
➕ tests/boundary/mcp/javascriptNativeHandoffIdentity.test.ts (+223 -0)

📄 Description

Summary

Missing ASAR native companions could yield handoffs bearing the archive digest and link native Evidence for that archive. Use the native node's canonical byte identity, leaving unavailable components visible with their paths, provenance and partial coverage.

Fixes #3926. Part of #4027 and #4091.

Problem and expected behavior

A missing .node companion has no proven content digest. Container-backed observations establish where its declaration came from; they cannot identify its bytes. A known-byte add-on must still link only matching native-subject Evidence, even when unrelated application scopes are partial.

Change and scope

  • Consume content-digest identity directly; remove the fallback observation scan.
  • Keep unavailable native nodes inline and omit false actionable handoffs/links. An empty handoff list is not proof that no native components exist.
  • Allocate the node index once per query only after an eligible target exists; no persistent cache.
  • Reuse the shared CLI/MCP workflow, schemas and caller choices. Add a reusable real-ASAR verifier and compact measurements.

No public schema or target authority is added. This is a routine static-analysis correction; no separate maintainer scope decision is applicable. Expected existing workflow effects:

  • Read existing files/captured data.
  • Launch an owned REA analysis worker.
  • Write private staged sources and verification inputs.

Neither the target application nor a native provider executes in this verification. Dependencies are unchanged. Generated outputs are rebuilt/checked and excluded from commits.

Contract and boundary impact

The native node identity owns byte meaning; handoff derivation consumes it after normal graph validation. CLI and MCP retain their existing input adapters and share the same application/domain workflow. Public schemas/catalog and provider selection are unchanged. Unavailable graph facts remain inline, and complete parent Evidence remains retained. Verification child commands use shared owned-process supervision and private runtime cleanup.

Evidence and regression coverage

Public CLI/stdio MCP baseline: missing-companion case failed; available-byte control passed. Both adapters and both native-Evidence selections ran before semantic assertions. The first CLI-selector harness attempt and optional architecture type correction are recorded separately; the latter produced byte-identical normalized input Evidence.

Real Joplin v3.7.21 AppImage: 6,324 ASAR files, three unpacked native components, selected package.json. The available control preserves exact parent/trace Evidence, facts, native links, coverage and token projections; the missing control retains the original unavailable node/provenance/coverage and removes the wrong handoff/container link. Every case has exact CLI/MCP parity. Native-provider Evidence is explicitly simulated to test linkage, not real-provider behavior.

Final controls were repeated after integrating reviewed main 62bf098: all available-case contract/fact/token fields match baseline, and all non-timing fields in both cases match the earlier post-fix controls. Updated application workflow acceptance passed 34/34; the related version-comparison consumers already use canonical content identity.

Available-case static task cost is unchanged: 12,340 BPE with selected name/description/inputSchema contracts plus structured replies, or 202,292 with the full catalog projection. Complete-tool-reply alternatives and all validation overhead/limits are documented. Missing-case removal of unsupported claims earns no efficiency credit.

Reproduction, measurements, source hashes and limitations.

  • Observations, derivations and unknowns stay distinguishable.
  • Caller inputs, source identity/provenance and prior attempts are retained.
  • Partial/unavailable outcomes remain visible independently of target eligibility.

Validation performed

  • Four-file focused selection: 24 passed. Final public two-case file passed again after named-summary parsing and the optional-field correction (overlaps the 24).
  • Updated application workflow CLI acceptance: 34 passed; adds34 cases/a fifth file to initial24 (58 distinct focused cases).
  • npm run check && npm run docs:check passed on final integration base 62bf098 (five consistency tests; 128.732 s wall / 115.518920 s CPU / 4,301,684,736 B peak, no OOM and verified cleanup)
  • Real Joplin available/missing controls, three retained query rounds, CLI parity, cl100k_base/tiktoken 0.12.0: both passed with exact CLI/MCP parity. Final available/missing complete verifier receipts: 258.885/59.738 s wall, 106.221003/59.254776 s CPU, 2,678,456,320/2,571,235,328 B peak cgroup memory, cleanup verified/no OOM under one CPU/8 GiB.
  • git diff --check: passed.
  • Final published head d86a9e3: all 40 CI checks passed. Codex completed without findings; Greptile reviewed all seven files with zero comments. Zero unresolved review threads. Merged source pins and required co-author verified.

Local scope is Linux x64, pinned Node 24.18.0/npm 11.16.0. Live Electron, real Ghidra/Hopper/IDA, other-platform runtime and hosted-agent behavior remain unverified. No speedup or performance-equivalence claim. Final available-case wall/CPU times are substantially above baseline; prior post-fix controls and final missing-case timings are separately recorded. Variability remains unresolved; cgroup peaks include charged file cache and the whole verifier.

Author readiness

Human owner: @N0zoM1z0

The session authorized implementation, validation, ready PRs and merging, including waiving manual declarations. The agent reviewed the diff/evidence. A human final-diff review is not asserted; declarations remain unchecked.

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • Concrete problem, related issue, scope and authority identified.
  • Producing identity/consumer boundary audited; superseded fallback removed.
  • Tests retain unknowns, exact known-byte controls, caller choices and provenance.
  • Owning docs updated; generated artifacts checked and excluded.
  • Final diff checked for secrets, unrelated changes and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4179 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `fix/javascript-native-handoff-identity` --- ### 📝 Commits (1) - [`d86a9e3`](https://github.com/morluto/rea/commit/d86a9e3c8677b317b2a09f00f755ec4e43cf058e) fix(javascript): bind native handoffs to canonical byte identity ### 📊 Changes **7 files changed** (+1820 additions, -13 deletions) <details> <summary>View changed files</summary> 📝 `docs/javascript-application-workflows.md` (+8 -0) ➕ `docs/verification/javascript-native-handoff-identity-2026-10-15.json` (+1052 -0) ➕ `docs/verification/javascript-native-handoff-identity-2026-10-15.md` (+179 -0) 📝 `package.json` (+1 -0) ➕ `scripts/verify/javascript/native-handoffs.mjs` (+348 -0) 📝 `src/domain/javascript/javascriptNativeHandoff.ts` (+9 -13) ➕ `tests/boundary/mcp/javascriptNativeHandoffIdentity.test.ts` (+223 -0) </details> ### 📄 Description ## Summary Missing ASAR native companions could yield handoffs bearing the archive digest and link native Evidence for that archive. Use the native node's canonical byte identity, leaving unavailable components visible with their paths, provenance and partial coverage. Fixes #3926. Part of #4027 and #4091. ## Problem and expected behavior A missing `.node` companion has no proven content digest. Container-backed observations establish where its declaration came from; they cannot identify its bytes. A known-byte add-on must still link only matching native-subject Evidence, even when unrelated application scopes are partial. ## Change and scope - Consume `content-digest` identity directly; remove the fallback observation scan. - Keep unavailable native nodes inline and omit false actionable handoffs/links. An empty handoff list is not proof that no native components exist. - Allocate the node index once per query only after an eligible target exists; no persistent cache. - Reuse the shared CLI/MCP workflow, schemas and caller choices. Add a reusable real-ASAR verifier and compact measurements. No public schema or target authority is added. This is a routine static-analysis correction; no separate maintainer scope decision is applicable. Expected existing workflow effects: - [x] Read existing files/captured data. - [x] Launch an owned REA analysis worker. - [x] Write private staged sources and verification inputs. Neither the target application nor a native provider executes in this verification. Dependencies are unchanged. Generated outputs are rebuilt/checked and excluded from commits. ## Contract and boundary impact The native node identity owns byte meaning; handoff derivation consumes it after normal graph validation. CLI and MCP retain their existing input adapters and share the same application/domain workflow. Public schemas/catalog and provider selection are unchanged. Unavailable graph facts remain inline, and complete parent Evidence remains retained. Verification child commands use shared owned-process supervision and private runtime cleanup. ## Evidence and regression coverage Public CLI/stdio MCP baseline: missing-companion case failed; available-byte control passed. Both adapters and both native-Evidence selections ran before semantic assertions. The first CLI-selector harness attempt and optional architecture type correction are recorded separately; the latter produced byte-identical normalized input Evidence. Real Joplin v3.7.21 AppImage: 6,324 ASAR files, three unpacked native components, selected package.json. The available control preserves exact parent/trace Evidence, facts, native links, coverage and token projections; the missing control retains the original unavailable node/provenance/coverage and removes the wrong handoff/container link. Every case has exact CLI/MCP parity. Native-provider Evidence is explicitly simulated to test linkage, not real-provider behavior. Final controls were repeated after integrating reviewed main `62bf098`: all available-case contract/fact/token fields match baseline, and all non-timing fields in both cases match the earlier post-fix controls. Updated application workflow acceptance passed 34/34; the related version-comparison consumers already use canonical content identity. Available-case static task cost is unchanged: 12,340 BPE with selected name/description/inputSchema contracts plus structured replies, or 202,292 with the full catalog projection. Complete-tool-reply alternatives and all validation overhead/limits are documented. Missing-case removal of unsupported claims earns no efficiency credit. [Reproduction, measurements, source hashes and limitations](https://github.com/morluto/rea/blob/c7f6b8bad1a34d5efb30ff2a017672dea1fcdabb/docs/verification/javascript-native-handoff-identity-2026-10-15.md). - [x] Observations, derivations and unknowns stay distinguishable. - [x] Caller inputs, source identity/provenance and prior attempts are retained. - [x] Partial/unavailable outcomes remain visible independently of target eligibility. ## Validation performed - Four-file focused selection: 24 passed. Final public two-case file passed again after named-summary parsing and the optional-field correction (overlaps the 24). - Updated application workflow CLI acceptance: 34 passed; adds34 cases/a fifth file to initial24 (58 distinct focused cases). - `npm run check && npm run docs:check` passed on final integration base `62bf098` (five consistency tests; 128.732 s wall / 115.518920 s CPU / 4,301,684,736 B peak, no OOM and verified cleanup) - Real Joplin available/missing controls, three retained query rounds, CLI parity, cl100k_base/tiktoken 0.12.0: both passed with exact CLI/MCP parity. Final available/missing complete verifier receipts: 258.885/59.738 s wall, 106.221003/59.254776 s CPU, 2,678,456,320/2,571,235,328 B peak cgroup memory, cleanup verified/no OOM under one CPU/8 GiB. - `git diff --check`: passed. - Final published head `d86a9e3`: all 40 CI checks passed. Codex completed without findings; Greptile reviewed all seven files with zero comments. Zero unresolved review threads. Merged source pins and required co-author verified. Local scope is Linux x64, pinned Node 24.18.0/npm 11.16.0. Live Electron, real Ghidra/Hopper/IDA, other-platform runtime and hosted-agent behavior remain unverified. No speedup or performance-equivalence claim. Final available-case wall/CPU times are substantially above baseline; prior post-fix controls and final missing-case timings are separately recorded. Variability remains unresolved; cgroup peaks include charged file cache and the whole verifier. ## Author readiness Human owner: @N0zoM1z0 The session authorized implementation, validation, ready PRs and merging, including waiving manual declarations. The agent reviewed the diff/evidence. A human final-diff review is not asserted; declarations remain unchecked. - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [x] Concrete problem, related issue, scope and authority identified. - [x] Producing identity/consumer boundary audited; superseded fallback removed. - [x] Tests retain unknowns, exact known-byte controls, caller choices and provenance. - [x] Owning docs updated; generated artifacts checked and excluded. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:11:57 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6113
No description provided.