Skip to content

fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Astro-Han merged 3 commits into from
Aug 8, 2026
Merged

fix(desktop): harden core barrel against node-only value exports #1734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e6b8aa1
fix(desktop): prevent startup white screen
sunheyi6 Aug 1, 2026
c8fa3af
fix(desktop): harden core barrel against node-only value exports
sunheyi6 Aug 3, 2026
03f8199
fix(desktop): rebase onto main, keep barrel browser-safe after #2258
sunheyi6 Aug 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
.then(() => {
console.log('barrel-ok');
})
.catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
15 changes: 15 additions & 0 deletions apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
specifier: string,
context: unknown,
nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
if (specifier.startsWith('node:')) {
throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
}
return nextResolve(specifier, context);
}
67 changes: 67 additions & 0 deletions apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
* Executable regression guard for the renderer-facing `@maka/core` barrel.
*
* This test intentionally enforces a stronger structural invariant than the
* current tree-shaking behavior: the renderer-facing root barrel must remain
* loadable without evaluating any Node built-ins. The Electron renderer runs
* in a browser-like environment where `node:*` modules cannot resolve (Vite
* externalizes them; today they happen to be tree-shaken out of the renderer
* graph, but nothing about that is guaranteed). This test spawns a child Node
* process whose loader throws on every `node:*` import and then imports the
* built barrel; the child exits non-zero the moment the barrel graph evaluates
* Node-only code.
*
* This is the executable form of the source-regex contract that #1727 pruned
* (the previous form asserted on `packages/core/src/index.ts` text; this one
* asserts on the built artifact the renderer actually consumes).
*/

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
args: string[],
timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
return new Promise((resolve, reject) => {
const child = spawn(process.execPath, args, {
cwd: DESKTOP_ROOT,
stdio: ['ignore', 'pipe', 'pipe'],
});
let stdout = '';
let stderr = '';
child.stdout?.on('data', (chunk: Buffer) => {
stdout += chunk.toString();
});
child.stderr?.on('data', (chunk: Buffer) => {
stderr += chunk.toString();
});
const timer = setTimeout(() => {
child.kill('SIGKILL');
reject(new Error(`child process timed out after ${timeoutMs}ms`));
}, timeoutMs);
child.once('error', (error) => {
clearTimeout(timer);
reject(error);
});
child.once('close', (code) => {
clearTimeout(timer);
resolve({ code, stdout, stderr });
});
});
}

describe('renderer core barrel node boundary contract', () => {
it('importing @maka/core evaluates no node:* module', async () => {
const childPath = fileURLToPath(
new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
);
const { code, stdout, stderr } = await runChild([childPath]);
assert.equal(code, 0, `child process failed:\n${stderr}`);
assert.match(stdout, /barrel-ok/);
});
});
43 changes: 10 additions & 33 deletions packages/core/src/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
ToolLedgerTransitionKind,
ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
ToolLedgerCorruptionError,
ToolLedgerRejectionError,
scanToolLedger,
validateGenericToolLedgerAppend,
validateToolLedgerEventLane,
validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
ToolReconcileObservation,
ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
ToolRecoveryEventBundle,
ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
ToolRecoveryBundleValidationError,
assertToolRecoveryEventBundle,
interpretScannedToolRecovery,
validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
canonicalToolArgsHash,
stableJsonStringify,
stripUndefinedDeep,
} from './tool-args-identity.js';
export {
encodeCanonicalRuntimeEvent,
type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
ContinuationClaimV1,
ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
RuntimePrefixSegmentV1,
RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
buildImmutableRuntimePrefix,
createRuntimeBoundaryCursor,
decodeContinuationClaim,
decodeRuntimeBoundaryCursor,
decodeRuntimePrefixSegment,
digestRuntimeBoundaryManifest,
digestRuntimePrefix,
runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down
40 changes: 37 additions & 3 deletions packages/core/src/shell-run.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
'starting',
'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
) {
throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
}
if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
if (shellRunRecordsEqual(candidate, current)) return current;
return normalizeShellRunRecord(
{ ...candidate, revision: current.revision + 1 },
sessionId,
shellRunId,
);
}

/**
* Structural equality for normalized ShellRun records. Records are plain
* JSON-safe data (string/number/boolean/null/arrays/objects), so a small
* recursive comparison is sufficient and keeps this module free of node:*
* imports so the renderer-facing `@maka/core` barrel stays browser-safe.
*/
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
if (left === right) return true;
if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
return false;
}
if (Array.isArray(left) !== Array.isArray(right)) return false;
if (Array.isArray(left)) {
if (left.length !== (right as unknown[]).length) return false;
for (let index = 0; index < left.length; index += 1) {
if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
}
return true;
}
const leftKeys = Object.keys(left as Record<string, unknown>);
const rightKeys = Object.keys(right as Record<string, unknown>);
if (leftKeys.length !== rightKeys.length) return false;
for (const key of leftKeys) {
if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
if (
!shellRunRecordsEqual(
(left as Record<string, unknown>)[key],
(right as Record<string, unknown>)[key],
)
) {
return false;
}
}
return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
if (value === undefined) return true;
if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down
8 changes: 2 additions & 6 deletions packages/runtime-host/src/__tests__/client-capability-recovery.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
canonicalToolArgsHash,
TOOL_BOUNDARY_PROTOCOL_V1,
type RuntimeEvent,
type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down
3 changes: 2 additions & 1 deletion packages/runtime-host/src/__tests__/execution-host-message.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down
3 changes: 2 additions & 1 deletion packages/runtime-host/src/__tests__/execution-host-queue.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down
3 changes: 2 additions & 1 deletion packages/runtime-host/src/__tests__/execution-host-recovery.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down
3 changes: 2 additions & 1 deletion packages/runtime-host/src/__tests__/execution-host.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down
3 changes: 2 additions & 1 deletion packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/ai-sdk-backend.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
SessionHeader,
StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/context-budget.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down
4 changes: 2 additions & 2 deletions packages/runtime/src/__tests__/continuation-replay.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
buildImmutableRuntimePrefix,
type RuntimeEvent,
type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
buildContinuationReplayPlan,
buildContinuationReplaySegment,
Expand Down
7 changes: 2 additions & 5 deletions packages/runtime/src/__tests__/conversation-copy.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
RuntimeEventStore,
StoredMessage,
} from '@maka/core';
import {
canonicalToolArgsHash,
decodeCanonicalToolResultContent,
isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
createSqliteAgentRunStore,
createSqliteRuntimeStore,
Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
scanToolLedger,
type LlmConnection,
type RuntimeEvent,
type SessionEvent,
type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down
3 changes: 2 additions & 1 deletion packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/recovery-resolver.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
buildInterruptedCodeModeOutcomeCommits,
Expand Down
2 changes: 1 addition & 1 deletion packages/runtime/src/__tests__/runtime-resume.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
buildImmutableRuntimePrefix,
type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down
6 changes: 2 additions & 4 deletions packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
deriveTurnRecords,
DurableStoreWriteError,
isTerminalRuntimeEvent,
ToolLedgerCorruptionError,
ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
AgentRunEvent,
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
fix(desktop): harden core barrel against node-only value exports by sunheyi6 · Pull Request #1734 · apache/maka · GitHub
Skip to content
fix(desktop): harden core barrel against node-only value exports#1734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

Astro-Han
merged 3 commits into

from

Aug 8, 2026
 Merged


fix(desktop): harden core barrel against node-only value exports
#1734
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


3 commits


Select commit
Hold shift + click to select a range
e6b8aa1

fix(desktop): prevent startup white screen


sunheyi6 Aug 1, 2026
c8fa3af

fix(desktop): harden core barrel against node-only value exports


sunheyi6 Aug 3, 2026
03f8199

fix(desktop): rebase onto main, keep barrel browser-safe after #2258


sunheyi6 Aug 8, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


16 changes: 16 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/renderer-barrel-node-boundary-child.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
// Child process for renderer-core-barrel-node-boundary.test.ts. Registers the
// throwing loader hook, then imports the built @maka/core barrel. Prints
// `barrel-ok` and exits 0 only if the barrel evaluates without touching any
// `node:*` module.
import { register } from 'node:module';

register(new URL('./throw-on-node-import-hook.js', import.meta.url));

import('@maka/core')
 .then(() => {
 console.log('barrel-ok');
 })
 .catch((error: unknown) => {
 console.error(error);
 process.exitCode = 1;
 });

15 changes: 15 additions & 0 deletions
apps/desktop/src/main/__tests__/fixtures/throw-on-node-import-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
// Loader hook used by renderer-core-barrel-node-boundary.test.ts. It enforces
// the structural invariant under test: a `node:*` import cannot resolve in the
// renderer's browser-like environment, so the moment the @maka/core barrel
// graph reaches Node-only code this hook throws and the child process fails.

export async function resolve(
 specifier: string,
 context: unknown,
 nextResolve: (specifier: string, context: unknown) => Promise<{ url: string }>,
): Promise<{ url: string }> {
 if (specifier.startsWith('node:')) {
 throw new Error(`renderer core barrel evaluated Node-only module: ${specifier}`);
 }
 return nextResolve(specifier, context);
}

67 changes: 67 additions & 0 deletions
apps/desktop/src/main/__tests__/renderer-core-barrel-node-boundary.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
/**
 * Executable regression guard for the renderer-facing `@maka/core` barrel.
 *
 * This test intentionally enforces a stronger structural invariant than the
 * current tree-shaking behavior: the renderer-facing root barrel must remain
 * loadable without evaluating any Node built-ins. The Electron renderer runs
 * in a browser-like environment where `node:*` modules cannot resolve (Vite
 * externalizes them; today they happen to be tree-shaken out of the renderer
 * graph, but nothing about that is guaranteed). This test spawns a child Node
 * process whose loader throws on every `node:*` import and then imports the
 * built barrel; the child exits non-zero the moment the barrel graph evaluates
 * Node-only code.
 *
 * This is the executable form of the source-regex contract that #1727 pruned
 * (the previous form asserted on `packages/core/src/index.ts` text; this one
 * asserts on the built artifact the renderer actually consumes).
 */

import { strict as assert } from 'node:assert';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { describe, it } from 'node:test';

const DESKTOP_ROOT = fileURLToPath(new URL('../../../', import.meta.url));

function runChild(
 args: string[],
 timeoutMs = 30_000,
): Promise<{ code: number | null; stdout: string; stderr: string }> {
 return new Promise((resolve, reject) => {
 const child = spawn(process.execPath, args, {
 cwd: DESKTOP_ROOT,
 stdio: ['ignore', 'pipe', 'pipe'],
 });
 let stdout = '';
 let stderr = '';
 child.stdout?.on('data', (chunk: Buffer) => {
 stdout += chunk.toString();
 });
 child.stderr?.on('data', (chunk: Buffer) => {
 stderr += chunk.toString();
 });
 const timer = setTimeout(() => {
 child.kill('SIGKILL');
 reject(new Error(`child process timed out after ${timeoutMs}ms`));
 }, timeoutMs);
 child.once('error', (error) => {
 clearTimeout(timer);
 reject(error);
 });
 child.once('close', (code) => {
 clearTimeout(timer);
 resolve({ code, stdout, stderr });
 });
 });
}

describe('renderer core barrel node boundary contract', () => {
 it('importing @maka/core evaluates no node:* module', async () => {
 const childPath = fileURLToPath(
 new URL('./fixtures/renderer-barrel-node-boundary-child.js', import.meta.url),
 );
 const { code, stdout, stderr } = await runChild([childPath]);
 assert.equal(code, 0, `child process failed:\n${stderr}`);
 assert.match(stdout, /barrel-ok/);
 });
});

43 changes: 10 additions & 33 deletions
packages/core/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -268,14 +268,6 @@ export type {
 ToolLedgerTransitionKind,
 ToolLedgerTransitionValidation,
} from './tool-ledger-scanner.js';
export {
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
 scanToolLedger,
 validateGenericToolLedgerAppend,
 validateToolLedgerEventLane,
 validateToolLedgerTransition,
} from './tool-ledger-scanner.js';
export type {
 ToolReconcileObservation,
 ToolReconcileResultFact,
Expand All@@ -300,21 +292,7 @@ export type {
 ToolRecoveryEventBundle,
 ToolRecoveryOperationIdentity,
} from './tool-recovery-bundle.js';
export {
 ToolRecoveryBundleValidationError,
 assertToolRecoveryEventBundle,
 interpretScannedToolRecovery,
 validateToolRecoveryEventBundle,
} from './tool-recovery-bundle.js';
export {
 canonicalToolArgsHash,
 stableJsonStringify,
 stripUndefinedDeep,
} from './tool-args-identity.js';
export {
 encodeCanonicalRuntimeEvent,
 type CanonicalRuntimeEventEncoding,
} from './canonical-runtime-event.js';
export type { CanonicalRuntimeEventEncoding } from './canonical-runtime-event.js';
export type {
 ContinuationClaimV1,
 ImmutableRuntimePrefixV1,
Expand All@@ -325,16 +303,15 @@ export type {
 RuntimePrefixSegmentV1,
 RuntimeBoundaryDigest,
} from './runtime-boundary.js';
export {
 buildImmutableRuntimePrefix,
 createRuntimeBoundaryCursor,
 decodeContinuationClaim,
 decodeRuntimeBoundaryCursor,
 decodeRuntimePrefixSegment,
 digestRuntimeBoundaryManifest,
 digestRuntimePrefix,
 runtimePrefixSegment,
} from './runtime-boundary.js';
// The following modules are intentionally type-only (or absent) in this
// browser-consumed barrel: their value implementations depend on node:* (e.g.
// runtime-boundary.ts and tool-args-identity.ts use node:crypto, tool-
// ledger-scanner.ts and canonical-runtime-event.ts use node:util), which the
// renderer cannot evaluate. Runtime code must import their values from the
// explicit subpaths (`@maka/core/runtime-boundary`, `@maka/core/tool-args-
// identity`, `@maka/core/tool-ledger-scanner`, `@maka/core/canonical-runtime-
// event`, `@maka/core/tool-recovery-bundle`) so renderer imports of `@maka/core`
// never evaluate Node-only modules before React can mount.

// session.ts
export type {
Expand Down

40 changes: 37 additions & 3 deletions
packages/core/src/shell-run.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
import * as nodeUtil from 'node:util';

export const SHELL_RUN_STATUSES = [
 'starting',
 'running',
Expand DownExpand Up@@ -410,14 +408,50 @@ export function nextShellRunRecord(current: ShellRunRecord, patch: ShellRunPatch
 ) {
 throw new Error(`ShellRun terminal outcome is immutable: ${current.status}`);
 }
 if (nodeUtil.isDeepStrictEqual(candidate, current)) return current;
 if (shellRunRecordsEqual(candidate, current)) return current;
 return normalizeShellRunRecord(
 { ...candidate, revision: current.revision + 1 },
 sessionId,
 shellRunId,
 );
}

/**
 * Structural equality for normalized ShellRun records. Records are plain
 * JSON-safe data (string/number/boolean/null/arrays/objects), so a small
 * recursive comparison is sufficient and keeps this module free of node:*
 * imports so the renderer-facing `@maka/core` barrel stays browser-safe.
 */
function shellRunRecordsEqual(left: unknown, right: unknown): boolean {
 if (left === right) return true;
 if (typeof left !== 'object' || typeof right !== 'object' || left === null || right === null) {
 return false;
 }
 if (Array.isArray(left) !== Array.isArray(right)) return false;
 if (Array.isArray(left)) {
 if (left.length !== (right as unknown[]).length) return false;
 for (let index = 0; index < left.length; index += 1) {
 if (!shellRunRecordsEqual(left[index], (right as unknown[])[index])) return false;
 }
 return true;
 }
 const leftKeys = Object.keys(left as Record<string, unknown>);
 const rightKeys = Object.keys(right as Record<string, unknown>);
 if (leftKeys.length !== rightKeys.length) return false;
 for (const key of leftKeys) {
 if (!Object.prototype.hasOwnProperty.call(right, key)) return false;
 if (
 !shellRunRecordsEqual(
 (left as Record<string, unknown>)[key],
 (right as Record<string, unknown>)[key],
 )
 ) {
 return false;
 }
 }
 return true;
}

function isShellRunSandboxExecution(value: unknown): boolean {
 if (value === undefined) return true;
 if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
Expand Down

8 changes: 2 additions & 6 deletions
packages/runtime-host/src/__tests__/client-capability-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import {
 canonicalToolArgsHash,
 TOOL_BOUNDARY_PROTOCOL_V1,
 type RuntimeEvent,
 type ToolRecoveryMode,
} from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1, type RuntimeEvent, type ToolRecoveryMode } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { recoverClientCapabilityOutcomes } from '../server/client-capability-recovery.js';

Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-message.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-queue.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host-recovery.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -7,7 +7,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/execution-host.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import type { MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime-host/src/__tests__/fixtures/execution-host-suite.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -16,7 +16,8 @@ import { connect, type Socket } from 'node:net';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { test } from 'node:test';
import { canonicalToolArgsHash, TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { TOOL_BOUNDARY_PROTOCOL_V1 } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { AgentRunHeader } from '@maka/core/agent-run';
import { normalizeMessageContent, type MessageContent } from '@maka/core/events';
import type { ConnectionCatalogEntry } from '@maka/core/runtime-policy';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/ai-sdk-backend.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ import type {
 SessionHeader,
 StorageRef,
} from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { SessionEvent } from '@maka/core/events';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/context-budget.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import { createHash } from 'node:crypto';
import { describe, test } from 'node:test';
import { encodeCanonicalRuntimeEvent } from '@maka/core';
import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 ARCHIVED_TOOL_RESULT_PLACEHOLDER_KIND,
Expand Down

4 changes: 2 additions & 2 deletions
packages/runtime/src/__tests__/continuation-replay.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { type RuntimeEvent } from '@maka/core';
import {
 buildImmutableRuntimePrefix,
 type RuntimeEvent,
 type RuntimePrefixIdentityV1,
} from '@maka/core';
} from '@maka/core/runtime-boundary';
import {
 buildContinuationReplayPlan,
 buildContinuationReplaySegment,
Expand Down

7 changes: 2 additions & 5 deletions
packages/runtime/src/__tests__/conversation-copy.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -11,11 +11,8 @@ import type {
 RuntimeEventStore,
 StoredMessage,
} from '@maka/core';
import {
 canonicalToolArgsHash,
 decodeCanonicalToolResultContent,
 isSessionInlineRun,
} from '@maka/core';
import { decodeCanonicalToolResultContent, isSessionInlineRun } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import {
 createSqliteAgentRunStore,
 createSqliteRuntimeStore,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/pre-dispatch-refusal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,12 @@ import assert from 'node:assert/strict';
import { test } from 'node:test';

import {
 scanToolLedger,
 type LlmConnection,
 type RuntimeEvent,
 type SessionEvent,
 type SessionHeader,
} from '@maka/core';
import { scanToolLedger } from '@maka/core/tool-ledger-scanner';
import { z } from 'zod';

import { createSessionEventMapMemory, mapSessionEventToRuntimeEvent } from '../ai-sdk-flow.js';
Expand Down

3 changes: 2 additions & 1 deletion
packages/runtime/src/__tests__/recovery-authority-equivalence.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,7 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash, type RuntimeEvent } from '@maka/core';
import type { RuntimeEvent } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import { createSqliteRuntimeStore } from '@maka/storage';
import { resolveRuntimeRecovery } from '../recovery-resolver.js';
import { buildResumePlanFromRuntimeEvents } from '../runtime-resume.js';
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/recovery-resolver.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import {
 buildInterruptedCodeModeOutcomeCommits,
Expand Down

2 changes: 1 addition & 1 deletion
packages/runtime/src/__tests__/runtime-resume.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -5,7 +5,7 @@ import {
 buildImmutableRuntimePrefix,
 type ImmutableRuntimePrefixV1,
} from '@maka/core/runtime-boundary';
import { canonicalToolArgsHash } from '@maka/core';
import { canonicalToolArgsHash } from '@maka/core/tool-args-identity';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

Expand Down

6 changes: 2 additions & 4 deletions
packages/runtime/src/__tests__/session-manager-terminal-ledger.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
import { describe, test } from 'node:test';
import assert from 'node:assert/strict';
import { setTimeout as timerDelay } from 'node:timers/promises';
import { deriveTurnRecords, DurableStoreWriteError, isTerminalRuntimeEvent } from '@maka/core';
import {
 deriveTurnRecords,
 DurableStoreWriteError,
 isTerminalRuntimeEvent,
 ToolLedgerCorruptionError,
 ToolLedgerRejectionError,
} from '@maka/core';
} from '@maka/core/tool-ledger-scanner';
import type { SandboxBoundaryResponse } from '@maka/core/sandbox-boundary';
import type {
 AgentRunEvent,
Expand Down
Loading
Loading