noteconnection 1.8.0 → 1.9.0

package/dist/src/core/PathBridge.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PathBridge = exports.BRIDGE_INBOUND_SCHEMA_LIMITS = exports.BRIDGE_INBOUND_LIMITS = exports.BRIDGE_BACKPRESSURE_LIMITS = void 0;
+exports.PathBridge = exports.BRIDGE_INBOUND_SCHEMA_LIMITS = exports.BRIDGE_INBOUND_LIMITS = exports.BRIDGE_BACKPRESSURE_LIMITS = exports.PATH_BRIDGE_CAPABILITIES = exports.PATH_BRIDGE_PROTOCOL_VERSION = void 0;
 exports.resolveBridgeInboundSchemaPolicy = resolveBridgeInboundSchemaPolicy;
 exports.resolveBridgeInboundLimitConfig = resolveBridgeInboundLimitConfig;
 exports.parseBridgeInboundEnvelope = parseBridgeInboundEnvelope;
@@ -8,10 +8,21 @@ exports.computeBridgePathFingerprint = computeBridgePathFingerprint;
 exports.buildBridgePathTransportSummary = buildBridgePathTransportSummary;
 exports.validateBridgePathPayload = validateBridgePathPayload;
 const ws_1 = require("ws");
+/** Versioned, host-neutral contract shared by Web, Tauri, Capacitor, and Godot. */
+exports.PATH_BRIDGE_PROTOCOL_VERSION = '2.0';
+exports.PATH_BRIDGE_CAPABILITIES = Object.freeze([
+    'path.transport',
+    'knowledge.analyze',
+    'knowledge.query',
+    'knowledge.readEvidence',
+    'knowledge.exportBundle',
+    'request.cancel',
+]);
 const PATH_REQUEST_TIMEOUT_MS = 3000;
 const PATH_PRODUCER_GRACE_MS = 30000;
 const MERMAID_RENDER_TIMEOUT_MS = 12000;
 const UNAUTHORIZED_CLIENT_TIMEOUT_MS = 5000;
+const DEFAULT_HOST_OPERATION_TIMEOUT_MS = 15000;
 const BYTES_PER_MIB = 1024 * 1024;
 const DEFAULT_INBOUND_MESSAGE_LIMIT_MIB = 128;
 const LARGE_GRAPH_INBOUND_MESSAGE_LIMIT_MIB = 256;
@@ -131,6 +142,12 @@ const PATH_MUTATION_TYPES = new Set([
 const KNOWN_BRIDGE_MESSAGE_TYPES = new Set([
     'authenticate',
     'identify',
+    'capabilities',
+    'analyze',
+    'query',
+    'readEvidence',
+    'exportBundle',
+    'cancel',
     'requestPath',
     'pathResult',
     'pathStatus',
@@ -247,6 +264,74 @@ function validateRequestPathPayload(payload) {
     }
     return null;
 }
+const BRIDGE_CORRELATION_ID_MAX_LENGTH = 128;
+const BRIDGE_CAPABILITY_MAX_COUNT = 32;
+function validateCorrelationId(value, field) {
+    if (value === undefined) {
+        return null;
+    }
+    if (!isNonEmptyString(value)) {
+        return `${field} must be a non-empty string when provided.`;
+    }
+    if (value.trim().length > BRIDGE_CORRELATION_ID_MAX_LENGTH) {
+        return `${field} must be at most ${BRIDGE_CORRELATION_ID_MAX_LENGTH} characters.`;
+    }
+    if (/[\u0000-\u001f\u007f]/.test(value)) {
+        return `${field} must not contain control characters.`;
+    }
+    return null;
+}
+function validateCapabilitiesPayload(payload) {
+    if (payload.protocolVersion !== undefined && !isNonEmptyString(payload.protocolVersion)) {
+        return 'capabilities payload.protocolVersion must be a non-empty string when provided.';
+    }
+    if (payload.client !== undefined && !isNonEmptyString(payload.client)) {
+        return 'capabilities payload.client must be a non-empty string when provided.';
+    }
+    if (!Array.isArray(payload.capabilities)) {
+        return 'capabilities payload.capabilities must be an array.';
+    }
+    if (payload.capabilities.length > BRIDGE_CAPABILITY_MAX_COUNT) {
+        return `capabilities payload.capabilities must contain at most ${BRIDGE_CAPABILITY_MAX_COUNT} entries.`;
+    }
+    if (payload.capabilities.some((capability) => !isNonEmptyString(capability))) {
+        return 'capabilities payload.capabilities must contain only non-empty strings.';
+    }
+    if (payload.maxPayloadBytes !== undefined && !isFiniteNumberValue(payload.maxPayloadBytes)) {
+        return 'capabilities payload.maxPayloadBytes must be a finite number when provided.';
+    }
+    return null;
+}
+function validateAnalysisRequestPayload(type, payload) {
+    if (!isRecord(payload)) {
+        return `${type} payload must be an object.`;
+    }
+    const requestIdError = validateCorrelationId(payload.requestId, `${type} payload.requestId`);
+    if (requestIdError) {
+        return requestIdError;
+    }
+    if (type !== 'cancel' && !isNonEmptyString(payload.requestId)) {
+        return `${type} payload.requestId must be a non-empty string.`;
+    }
+    if (payload.workspaceId !== undefined && !isNonEmptyString(payload.workspaceId)) {
+        return `${type} payload.workspaceId must be a non-empty string when provided.`;
+    }
+    if (payload.sourceUri !== undefined && !isNonEmptyString(payload.sourceUri)) {
+        return `${type} payload.sourceUri must be a non-empty string when provided.`;
+    }
+    return null;
+}
+function identifyPayloadCapabilitiesInvalid(payload) {
+    if (payload.capabilities === undefined) {
+        return null;
+    }
+    return validateCapabilitiesPayload({
+        protocolVersion: payload.protocolVersion,
+        client: payload.client ?? payload.tag,
+        capabilities: payload.capabilities,
+        maxPayloadBytes: payload.maxPayloadBytes,
+    });
+}
 function validatePathStatusPayload(payload) {
     if (payload.level !== undefined && !isValidBridgeStatusLevel(payload.level)) {
         return 'pathStatus payload.level must be one of info/success/warning/error when provided.';
@@ -485,8 +570,22 @@ function validateKnownEnvelopePayload(type, payload, policy) {
                 if (client !== undefined && typeof client !== 'string') {
                     return `${type} client/tag must be a string when provided.`;
                 }
+                if (identifyPayloadCapabilitiesInvalid(payload)) {
+                    return identifyPayloadCapabilitiesInvalid(payload);
+                }
             }
             return null;
+        case 'capabilities':
+            if (!isRecord(payload)) {
+                return 'capabilities payload must be an object.';
+            }
+            return validateCapabilitiesPayload(payload);
+        case 'analyze':
+        case 'query':
+        case 'readEvidence':
+        case 'exportBundle':
+        case 'cancel':
+            return validateAnalysisRequestPayload(type, payload);
         case 'requestPath':
             if (payload !== undefined && !isRecord(payload)) {
                 return 'requestPath payload must be an object when provided.';
@@ -593,6 +692,9 @@ function parseBridgeInboundEnvelope(data, policy = BRIDGE_INBOUND_SCHEMA_POLICY)
         payload: data.payload,
         token: data.token,
         client: data.client,
+        version: data.version,
+        requestId: data.requestId,
+        correlationId: data.correlationId,
     };
     if (envelope.token !== undefined && typeof envelope.token !== 'string') {
         return {
@@ -606,6 +708,18 @@ function parseBridgeInboundEnvelope(data, policy = BRIDGE_INBOUND_SCHEMA_POLICY)
             reason: 'Bridge message client must be a string when provided.',
         };
     }
+    const versionError = validateCorrelationId(envelope.version, 'Bridge message version');
+    if (versionError) {
+        return { ok: false, reason: versionError };
+    }
+    const requestIdError = validateCorrelationId(envelope.requestId, 'Bridge message requestId');
+    if (requestIdError) {
+        return { ok: false, reason: requestIdError };
+    }
+    const correlationIdError = validateCorrelationId(envelope.correlationId, 'Bridge message correlationId');
+    if (correlationIdError) {
+        return { ok: false, reason: correlationIdError };
+    }
     const isKnownType = KNOWN_BRIDGE_MESSAGE_TYPES.has(type);
     if (!isKnownType && policy.rejectUnknownTypes) {
         return {
@@ -828,6 +942,7 @@ class PathBridge {
         this.currentPath = null;
         this.pendingPathRequests = new Map();
         this.pendingMermaidRenderRequests = new Map();
+        this.pendingHostOperations = new Map();
         this.unauthorizedClientTimers = new Map();
         this.outboundQueueState = new Map();
         this.nextMermaidRenderRequestId = 1;
@@ -840,6 +955,11 @@ class PathBridge {
             : 9876;
         this.host = resolvedOptions.host || '127.0.0.1';
         this.authToken = typeof resolvedOptions.authToken === 'string' ? resolvedOptions.authToken.trim() : '';
+        this.hostAdapter = resolvedOptions.hostAdapter || null;
+        this.hostOperationTimeoutMs = Number.isFinite(Number(resolvedOptions.hostOperationTimeoutMs)) &&
+            Number(resolvedOptions.hostOperationTimeoutMs) > 0
+            ? Math.floor(Number(resolvedOptions.hostOperationTimeoutMs))
+            : DEFAULT_HOST_OPERATION_TIMEOUT_MS;
         this.wss = new ws_1.WebSocketServer({
             port: this.port,
             host: this.host,
@@ -918,6 +1038,7 @@ class PathBridge {
                 const wasProducer = !!meta && this.isPathProducerTag(meta.tag);
                 this.clearUnauthorizedDisconnect(ws);
                 this.clearPendingPathRequest(ws);
+                this.cancelHostOperationsForClient(ws, 'client_disconnected');
                 this.clearOutboundQueueState(ws);
                 this.clients.delete(ws);
                 this.clientMeta.delete(ws);
@@ -1187,7 +1308,11 @@ class PathBridge {
         }
         let serialized = '';
         try {
-            serialized = JSON.stringify({ type, payload });
+            serialized = JSON.stringify({
+                type,
+                payload,
+                version: exports.PATH_BRIDGE_PROTOCOL_VERSION,
+            });
         }
         catch (error) {
             const meta = this.clientMeta.get(client);
@@ -1221,6 +1346,15 @@ class PathBridge {
     sendStatus(client, payload) {
         this.sendMessage(client, 'pathStatus', payload);
     }
+    sendCapabilities(client) {
+        this.sendMessage(client, 'capabilities', {
+            protocolVersion: exports.PATH_BRIDGE_PROTOCOL_VERSION,
+            capabilities: [...exports.PATH_BRIDGE_CAPABILITIES],
+            maxPayloadBytes: MAX_INBOUND_MESSAGE_BYTES,
+            hostAdapter: Boolean(this.hostAdapter),
+            hostOperationTimeoutMs: this.hostOperationTimeoutMs,
+        });
+    }
     notifyPendingPathRequests(payload) {
         const pendingClients = Array.from(this.pendingPathRequests.keys());
         pendingClients.forEach((client) => this.sendStatus(client, payload));
@@ -1239,6 +1373,17 @@ class PathBridge {
     clearAllPendingPathRequests() {
         Array.from(this.pendingPathRequests.keys()).forEach((client) => this.clearPendingPathRequest(client));
     }
+    cancelHostOperationsForClient(client, reason) {
+        Array.from(this.pendingHostOperations.entries()).forEach(([requestId, pending]) => {
+            if (pending.client !== client) {
+                return;
+            }
+            clearTimeout(pending.timer);
+            pending.controller.abort(reason);
+            this.pendingHostOperations.delete(requestId);
+            this.hostAdapter?.cancel?.(requestId);
+        });
+    }
     invalidateCurrentPath(reason) {
         if (!this.currentPath) {
             return;
@@ -1451,6 +1596,101 @@ class PathBridge {
         }
         this.broadcast('pathStatus', status);
     }
+    sendHostOperationResult(client, operationType, requestId, correlationId, result, error, cancelled = false) {
+        this.sendMessage(client, 'operationResult', {
+            type: operationType,
+            requestId,
+            correlationId,
+            ok: !error && !cancelled,
+            cancelled,
+            result: error || cancelled ? undefined : result,
+            error: error || (cancelled ? 'operation_cancelled' : undefined),
+        });
+    }
+    executeHostOperation(type, payloadLike, envelope, sender) {
+        if (!this.hostAdapter || !isRecord(payloadLike)) {
+            this.broadcast(type, payloadLike || {});
+            return;
+        }
+        const requestId = typeof payloadLike.requestId === 'string' ? payloadLike.requestId.trim() : '';
+        if (!requestId) {
+            this.sendHostOperationResult(sender, type, '', '', undefined, 'request_id_required');
+            return;
+        }
+        if (this.pendingHostOperations.has(requestId)) {
+            this.sendHostOperationResult(sender, type, requestId, requestId, undefined, 'request_in_flight');
+            return;
+        }
+        const controller = new AbortController();
+        const correlationId = typeof envelope.correlationId === 'string' && envelope.correlationId.trim()
+            ? envelope.correlationId.trim()
+            : requestId;
+        const timer = setTimeout(() => {
+            const pending = this.pendingHostOperations.get(requestId);
+            if (!pending) {
+                return;
+            }
+            this.pendingHostOperations.delete(requestId);
+            pending.controller.abort();
+            this.hostAdapter?.cancel?.(requestId);
+            this.sendHostOperationResult(sender, type, requestId, correlationId, undefined, 'operation_timeout');
+        }, this.hostOperationTimeoutMs);
+        const pending = { client: sender, controller, timer };
+        this.pendingHostOperations.set(requestId, pending);
+        const clientTag = this.clientMeta.get(sender)?.tag || 'unknown';
+        Promise.resolve()
+            .then(() => this.hostAdapter.execute({
+            type,
+            requestId,
+            correlationId,
+            payload: payloadLike,
+            clientTag,
+            signal: controller.signal,
+        }))
+            .then((result) => {
+            if (this.pendingHostOperations.get(requestId) !== pending) {
+                return;
+            }
+            this.pendingHostOperations.delete(requestId);
+            clearTimeout(timer);
+            this.sendHostOperationResult(sender, type, requestId, correlationId, result);
+        })
+            .catch((error) => {
+            if (this.pendingHostOperations.get(requestId) !== pending) {
+                return;
+            }
+            this.pendingHostOperations.delete(requestId);
+            clearTimeout(timer);
+            const message = controller.signal.aborted ? 'operation_cancelled' : String(error?.message || error);
+            this.sendHostOperationResult(sender, type, requestId, correlationId, undefined, message, controller.signal.aborted);
+        });
+    }
+    cancelHostOperation(payloadLike, sender) {
+        if (!this.hostAdapter) {
+            // Preserve the pre-adapter relay contract for legacy clients,
+            // including cancellation frames without a request ID.
+            this.broadcast('cancel', payloadLike || {});
+            return;
+        }
+        const payload = isRecord(payloadLike) ? payloadLike : {};
+        const requestId = typeof payload.requestId === 'string' ? payload.requestId.trim() : '';
+        if (!requestId) {
+            this.sendHostOperationResult(sender, 'cancel', '', '', undefined, 'request_id_required');
+            return;
+        }
+        const pending = this.pendingHostOperations.get(requestId);
+        if (pending) {
+            clearTimeout(pending.timer);
+            pending.controller.abort();
+            this.pendingHostOperations.delete(requestId);
+            this.hostAdapter?.cancel?.(requestId);
+            this.sendHostOperationResult(sender, 'cancel', requestId, requestId, undefined, undefined, true);
+        }
+        else {
+            this.sendHostOperationResult(sender, 'cancel', requestId, requestId, undefined, 'operation_not_found');
+        }
+        this.broadcast('cancel', payloadLike || {});
+    }
     handleMessage(envelope, sender) {
         const { type, payload, client } = envelope;
         console.log(`[PathBridge] Received: ${type}`);
@@ -1461,8 +1701,25 @@ class PathBridge {
                 const identifyPayload = isRecord(payload) ? payload : {};
                 const requestedTag = identifyPayload.client ?? identifyPayload.tag ?? client ?? 'unknown';
                 this.setClientTag(sender, String(requestedTag));
+                this.sendCapabilities(sender);
                 break;
             }
+            case 'capabilities':
+                // Capability advertisements are relayed so a Web/Tauri client
+                // can negotiate the same contract with Godot or a mobile peer.
+                this.broadcast('capabilities', payload || {});
+                break;
+            case 'analyze':
+            case 'query':
+            case 'readEvidence':
+            case 'exportBundle':
+                // The optional host adapter owns domain execution while the
+                // bridge retains correlation, timeout, and cancellation policy.
+                this.executeHostOperation(type, payload, envelope, sender);
+                break;
+            case 'cancel':
+                this.cancelHostOperation(payload, sender);
+                break;
             case 'requestPath':
                 this.handlePathRequest(sender);
                 break;
@@ -1599,6 +1856,12 @@ class PathBridge {
     }
     close() {
         this.clearAllPendingPathRequests();
+        Array.from(this.pendingHostOperations.entries()).forEach(([requestId, pending]) => {
+            clearTimeout(pending.timer);
+            pending.controller.abort();
+            this.hostAdapter?.cancel?.(requestId);
+        });
+        this.pendingHostOperations.clear();
         Array.from(this.pendingMermaidRenderRequests.values()).forEach((pendingRequest) => {
             clearTimeout(pendingRequest.timer);
             pendingRequest.reject(new Error('PathBridge is closing before Mermaid render completed.'));

package/dist/src/core/ResourceReference.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeResourceReference = normalizeResourceReference;
+/**
+ * Shared, host-neutral reference normalization used by Graph and backend
+ * identity generation. It intentionally has no Node or platform dependency so
+ * the path-core bundle can execute in a browser VM and in Godot WebView.
+ */
+function normalizeResourceReference(reference) {
+    if (typeof reference !== 'string') {
+        throw new Error('Resource reference must be a string');
+    }
+    if (reference.includes('\0')) {
+        throw new Error('Resource reference must not contain NUL characters');
+    }
+    return reference.normalize('NFC').replace(/\\/g, '/').toLowerCase();
+}

package/dist/src/desktop.godot.pack.test.js

@@ -0,0 +1,142 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+jest.mock('child_process', () => ({ ...jest.requireActual('child_process'), spawnSync: jest.fn() }));
+const { prepareDesktopGodotPack } = require('../scripts/prepare-desktop-godot-pack');
+const { resolveHostGodotBinaryName } = require('../scripts/tauri-sidecar-utils');
+const runtime = require('../config/godot-desktop-runtime.json');
+const spawn = child_process_1.spawnSync;
+describe('desktop Godot resource package', () => {
+    let directory;
+    const write = (relative, content) => {
+        const file = path.join(directory, relative);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, content);
+    };
+    beforeEach(() => {
+        directory = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'desktop-godot-pack-'));
+        write('path_mode/project.godot', `config_version=5\nconfig/features=PackedStringArray("${runtime.version}", "Forward+")\n`);
+        write('path_mode/export_presets.cfg', '[preset.0]\nname="Windows Desktop"\n');
+        write('path_mode/scenes/main.tscn', '[gd_scene format=3]\n');
+        write('path_mode/scripts/main.gd', 'extends Node\n');
+        write('path_mode/shaders/main.gdshader', 'shader_type spatial;\n');
+        write('path_mode/assets/background.exr', 'fixture');
+        write(`src-tauri/bin/${resolveHostGodotBinaryName()}`, 'engine fixture');
+        spawn.mockImplementation((_executable, args) => {
+            if (args.includes('--version'))
+                return { status: 0, stdout: `${runtime.version}.stable.official.fixture\n`, stderr: '' };
+            if (args.includes('--export-pack'))
+                fs.writeFileSync(args[args.length - 1], 'GDPC resource fixture');
+            return { status: 0, stdout: 'done\n', stderr: '' };
+        });
+    });
+    afterEach(() => {
+        jest.resetAllMocks();
+        fs.rmSync(directory, { recursive: true, force: true });
+    });
+    test('exports only runtime roots and binds the pack to source and engine bytes', () => {
+        write('path_mode/.godot/editor/state', 'private editor state');
+        write('path_mode/tmp/debug.gd', 'debug fixture');
+        const report = prepareDesktopGodotPack(directory);
+        expect(report.engineVersion).toBe(`${runtime.version}.stable.official.fixture`);
+        expect(report.pack.path).toBe('output/desktop/path_mode.pck');
+        expect(report.pack.sha256).toMatch(/^[a-f0-9]{64}$/);
+        expect(report.files.map((file) => file.path)).toEqual(expect.arrayContaining(['project.godot', 'scenes/main.tscn', 'assets/background.exr']));
+        expect(report.files.some((file) => /editor|tmp/.test(file.path))).toBe(false);
+        expect(fs.readdirSync(path.join(directory, 'output/desktop')).some(name => name.startsWith('.pathmode-'))).toBe(false);
+    });
+    test('rejects an engine version that cannot consume the declared project', () => {
+        spawn.mockReturnValue({ status: 0, stdout: '4.3.stable.official.fixture\n', stderr: '' });
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/requires Godot/);
+        expect(spawn).toHaveBeenCalledTimes(1);
+    });
+    test('rejects SVG before invoking Godot import', () => {
+        write('path_mode/assets/unsupported.svg', '<svg/>');
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/cannot import SVG/);
+        expect(spawn.mock.calls.every(([, args]) => args.includes('--version'))).toBe(true);
+    });
+    test('does not accept zero exit after a Godot script error or replace an earlier pack', () => {
+        write('output/desktop/path_mode.pck', 'GDPC previous pack');
+        spawn.mockImplementation((_executable, args) => args.includes('--version')
+            ? { status: 0, stdout: `${runtime.version}.stable.official.fixture`, stderr: '' }
+            : { status: 0, stdout: '', stderr: '\u001b[31mSCRIPT ERROR: invalid exported script\u001b[0m\n' });
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/invalid exported script/);
+        expect(fs.readFileSync(path.join(directory, 'output/desktop/path_mode.pck'), 'utf8')).toBe('GDPC previous pack');
+    });
+    test('rejects successful export without a resource pack', () => {
+        spawn.mockImplementation((_executable, args) => ({ status: 0, stdout: args.includes('--version') ? `${runtime.version}.stable.official.fixture` : '', stderr: '' }));
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/ENOENT/);
+    });
+    test('rejects an invalid pack header', () => {
+        spawn.mockImplementation((_executable, args) => {
+            if (args.includes('--export-pack'))
+                fs.writeFileSync(args[args.length - 1], 'not a pack');
+            return { status: 0, stdout: args.includes('--version') ? `${runtime.version}.stable.official.fixture` : '', stderr: '' };
+        });
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/PCK resource pack/);
+    });
+    test('rejects source changes between staging and publication', () => {
+        spawn.mockImplementation((_executable, args) => {
+            if (args.includes('--export-pack')) {
+                fs.writeFileSync(args[args.length - 1], 'GDPC resource fixture');
+                write('path_mode/scripts/main.gd', 'extends Node\n# changed during export\n');
+            }
+            return { status: 0, stdout: args.includes('--version') ? `${runtime.version}.stable.official.fixture` : '', stderr: '' };
+        });
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/inputs changed/);
+        expect(fs.existsSync(path.join(directory, 'output/desktop/path_mode.pck'))).toBe(false);
+    });
+    test('rejects files added between staging and publication', () => {
+        spawn.mockImplementation((_executable, args) => {
+            if (args.includes('--export-pack')) {
+                fs.writeFileSync(args[args.length - 1], 'GDPC resource fixture');
+                write('path_mode/scripts/added.gd', 'extends Node\n');
+            }
+            return { status: 0, stdout: args.includes('--version') ? `${runtime.version}.stable.official.fixture` : '', stderr: '' };
+        });
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/inputs changed/);
+        expect(fs.existsSync(path.join(directory, 'output/desktop/path_mode.pck'))).toBe(false);
+    });
+    test('rejects a symlinked runtime root before importing external files', () => {
+        fs.renameSync(path.join(directory, 'path_mode/assets'), path.join(directory, 'external-assets'));
+        fs.symlinkSync(path.join(directory, 'external-assets'), path.join(directory, 'path_mode/assets'), process.platform === 'win32' ? 'junction' : 'dir');
+        expect(() => prepareDesktopGodotPack(directory)).toThrow(/must not be a symlink/);
+        expect(spawn.mock.calls.every(([, args]) => args.includes('--version'))).toBe(true);
+    });
+});

package/dist/src/desktop.runtime.graph.test.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vm = __importStar(require("node:vm"));
+const { waitForAcceptanceGraph } = require('../scripts/verify-desktop-runtime');
+const graph = { nodes: [{ id: 'Alpha' }, { id: 'Beta' }], edges: [{ source: 'Alpha', target: 'Beta' }] };
+test('waits past the build reload and returns one snapshot from the ready document', async () => {
+    const pages = [
+        vm.createContext({ performance: { timeOrigin: 100 }, graphData: graph }),
+        vm.createContext({ performance: { timeOrigin: 200 } }),
+        vm.createContext({ performance: { timeOrigin: 200 }, graphData: graph }),
+    ];
+    const evaluate = jest.fn(async (expression) => {
+        const page = pages.shift();
+        if (!page)
+            throw new Error('Unexpected extra WebView read');
+        return vm.runInContext(expression, page);
+    });
+    await expect(waitForAcceptanceGraph({ evaluate }, 100)).resolves.toEqual({ nodes: ['Alpha', 'Beta'], edges: 1 });
+    expect(evaluate).toHaveBeenCalledTimes(3);
+});
+test('captures lexical graphData and its links before another CDP request can replace the document', async () => {
+    const page = vm.createContext({ performance: { timeOrigin: 200 } });
+    vm.runInContext(`const graphData = ${JSON.stringify({ nodes: graph.nodes, links: graph.edges })}`, page);
+    const evaluate = jest.fn(async (expression) => {
+        const snapshot = vm.runInContext(expression, page);
+        // Navigation destroys the document after this single serialized CDP response.
+        if (evaluate.mock.calls.length > 1)
+            throw new Error('Execution context was destroyed');
+        return snapshot;
+    });
+    await expect(waitForAcceptanceGraph({ evaluate }, 100)).resolves.toEqual({ nodes: ['Alpha', 'Beta'], edges: 1 });
+    expect(evaluate).toHaveBeenCalledTimes(1);
+});

package/dist/src/export/WorkspaceExportBundle.js

@@ -457,6 +457,16 @@ function buildKnowledgeRunReports(records) {
             ? knowledgeRun.scope
             : {};
         const answerReleaseReview = buildAnswerReleaseReviewSummary(knowledgeRun.answerReleaseReview ?? payload.answerReleaseReview);
+        const graphAnswerPlan = (knowledgeRun.graphAnswerPlan ?? payload.graphAnswerPlan);
+        const graphAnswerCoverage = (knowledgeRun.graphAnswerCoverage ?? payload.graphAnswerCoverage);
+        const answerTaskPlan = (knowledgeRun.answerTaskPlan
+            ?? graphAnswerPlan?.answerTaskPlan
+            ?? payload.answerTaskPlan);
+        const answerTaskCoverage = (knowledgeRun.answerTaskCoverage
+            ?? payload.answerTaskCoverage);
+        const graphAnswerClaims = Array.isArray(graphAnswerPlan?.claims)
+            ? graphAnswerPlan.claims.filter((claim) => Boolean(claim && typeof claim === 'object'))
+            : [];
         const graphContext = payload.graphContext && typeof payload.graphContext === 'object'
             ? payload.graphContext
             : {};
@@ -510,6 +520,40 @@ function buildKnowledgeRunReports(records) {
                     : null,
                 missingLookupCount,
             },
+            ...(graphAnswerPlan ? {
+                graphAnswerPlan: {
+                    intent: String(graphAnswerPlan.intent || '').trim(),
+                    depth: String(graphAnswerPlan.depth || '').trim(),
+                    anchorAtomId: String(graphAnswerPlan.anchorAtomId || '').trim(),
+                    claimCount: graphAnswerClaims.length,
+                    requiredClaimCount: graphAnswerClaims.filter((claim) => claim.required === true).length,
+                    requiredRoles: Array.isArray(graphAnswerPlan.requiredRoles)
+                        ? graphAnswerPlan.requiredRoles.map((role) => String(role || '').trim()).filter(Boolean)
+                        : [],
+                    coverageScore: normalizeOptionalScore(graphAnswerCoverage?.coverageScore),
+                    missingRequiredClaimIds: Array.isArray(graphAnswerCoverage?.missingRequiredClaimIds)
+                        ? graphAnswerCoverage.missingRequiredClaimIds.map((claimId) => String(claimId || '').trim()).filter(Boolean)
+                        : [],
+                },
+            } : {}),
+            ...(answerTaskPlan ? {
+                answerTask: {
+                    primarySubject: String(answerTaskPlan.primarySubject || '').trim(),
+                    subtaskCount: Array.isArray(answerTaskPlan.subtasks)
+                        ? answerTaskPlan.subtasks.length
+                        : 0,
+                    requiredSubtaskCount: Array.isArray(answerTaskPlan.subtasks)
+                        ? answerTaskPlan.subtasks.filter((subtask) => Boolean(subtask && typeof subtask === 'object' && subtask.required === true)).length
+                        : 0,
+                    missingRequiredSubtaskIds: Array.isArray(answerTaskCoverage?.missingRequiredSubtaskIds)
+                        ? answerTaskCoverage.missingRequiredSubtaskIds.map((id) => String(id || '').trim()).filter(Boolean)
+                        : [],
+                    learningRouteNodeCount: Array.isArray(answerTaskPlan.learningRoute)
+                        ? answerTaskPlan.learningRoute.length
+                        : 0,
+                    coverageScore: normalizeOptionalScore(answerTaskCoverage?.coverageScore),
+                },
+            } : {}),
             ...(answerReleaseReview ? { answerReleaseReview } : {}),
         };
     });