nebula-notebook 0.2.15 → 0.2.17

package/node-server/dist/kernel/kernel-service.d.ts

@@ -4,7 +4,7 @@
  * Manages Jupyter kernel sessions - spawning, execution, and lifecycle.
  * Uses ZeroMQ for kernel communication following the Jupyter messaging protocol.
  */
-import { KernelOutput, ExecutionResult, ExecutionQueueInfo, StartKernelOptions, SessionInfo, KernelServiceConfig } from './types';
+import { KernelOutput, ExecutionResult, ExecutionQueueInfo, InternalExecutionOptions, StartKernelOptions, SessionInfo, KernelServiceConfig } from './types';
 import { SessionStore } from './session-store';
 import { KernelSpec } from './kernelspec';
 /** Kernel-originated comm event surfaced to onComm listeners. */
@@ -256,7 +256,7 @@ export declare class KernelService {
     /**
      * Execute code in a kernel session
      */
-    executeCode(sessionId: string, code: string, onOutput: (output: KernelOutput, cellId?: string | null) => Promise<void>, onQueueInfo?: (info: ExecutionQueueInfo) => void, cellId?: string | null): Promise<ExecutionResult>;
+    executeCode(sessionId: string, code: string, onOutput: (output: KernelOutput, cellId?: string | null) => Promise<void>, onQueueInfo?: (info: ExecutionQueueInfo) => void, cellId?: string | null, internalOptions?: InternalExecutionOptions): Promise<ExecutionResult>;
     private enqueueExecution;
     /**
      * Serialize shell socket SENDS. Receives are owned by the unified shell

package/node-server/dist/kernel/kernel-service.js

@@ -635,6 +635,12 @@ class KernelService {
      */
     async startKernel(options = {}) {
         const kernelName = options.kernelName || 'python3';
+        if (options.internalEnv
+            && (Object.keys(options.internalEnv).some((key) => key !== 'PYTHONNOUSERSITE')
+                || (options.internalEnv.PYTHONNOUSERSITE !== undefined
+                    && options.internalEnv.PYTHONNOUSERSITE !== '1'))) {
+            throw new Error('Unsupported internal kernel environment override');
+        }
         // env:<pythonPath> kernels raw-launch a Python environment directly
         // (VSCode-style) — no kernelspec registration involved. Preflight here so
         // callers get a crisp, coded error instead of a spawn failure + ready
@@ -672,7 +678,7 @@ class KernelService {
         const cwd = options.cwd || (normalizedFilePath ? path.dirname(normalizedFilePath) : process.cwd());
         const proc = (0, child_process_1.spawn)(argv[0], argv.slice(1), {
             cwd,
-            env: { ...process.env, ...spec.env },
+            env: { ...process.env, ...spec.env, ...options.internalEnv },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         // Log kernel stdout/stderr for debugging
@@ -1408,7 +1414,7 @@ class KernelService {
     /**
      * Execute code in a kernel session
      */
-    async executeCode(sessionId, code, onOutput, onQueueInfo, cellId) {
+    async executeCode(sessionId, code, onOutput, onQueueInfo, cellId, internalOptions) {
         // Polyfill `!command` lines for kernels whose language lacks them (see
         // rewriteShellLines) — rewritten code still runs IN the kernel process,
         // so cwd/env/node are the kernel's, exactly like IPython's native `!`.
@@ -1433,7 +1439,7 @@ class KernelService {
                     for (const o of stored) {
                         await onOutput(o, cellId);
                     }
-                });
+                }, internalOptions?.storeHistory !== false);
                 return { ...result, ...queueInfo };
             }
             catch (err) {
@@ -1506,7 +1512,7 @@ class KernelService {
         }
         return message;
     }
-    async executeCodeInternal(sessionId, code, onOutput) {
+    async executeCodeInternal(sessionId, code, onOutput, storeHistory = true) {
         const session = this.sessions.get(sessionId);
         if (!session) {
             throw new Error(`Session ${sessionId} not found`);
@@ -1537,7 +1543,7 @@ class KernelService {
             const content = {
                 code,
                 silent: false,
-                store_history: true,
+                store_history: storeHistory,
                 user_expressions: {},
                 allow_stdin: false,
                 stop_on_error: true,
@@ -1571,6 +1577,10 @@ class KernelService {
                 else if (msgType === 'execute_result' || msgType === 'display_data') {
                     const output = this.formatDisplayData(msgContent.data || {}, msgContent.metadata || undefined);
                     if (output) {
+                        output.jupyterOutputType = msgType;
+                        if (msgType === 'execute_result' && Number.isSafeInteger(msgContent.execution_count)) {
+                            output.jupyterExecutionCount = msgContent.execution_count;
+                        }
                         await onOutput(output);
                     }
                 }

package/node-server/dist/kernel/types.d.ts

@@ -82,6 +82,14 @@ export interface KernelOutput {
     mimeBundle?: MimeBundle;
     metadata?: Record<string, JsonValue>;
     preferredMimeType?: string;
+    /** Exact protocol shape retained for immutable replay sealing. */
+    jupyterOutputType?: 'execute_result' | 'display_data';
+    /** Present for execute_result protocol messages. */
+    jupyterExecutionCount?: number;
+}
+export interface InternalExecutionOptions {
+    /** Server-authored probes use false so they cannot perturb notebook counts. */
+    storeHistory?: false;
 }
 export interface SequencedKernelOutput {
     seq: number;
@@ -114,6 +122,14 @@ export interface StartKernelOptions {
     kernelName?: string;
     cwd?: string;
     filePath?: string;
+    /**
+     * Server-only launch hardening. This is intentionally not accepted by the
+     * public kernel HTTP route; replay sealing uses it to exclude user-site
+     * packages before the Python process starts.
+     */
+    internalEnv?: {
+        PYTHONNOUSERSITE?: '1';
+    };
 }
 /**
  * Session info returned by API

package/node-server/dist/notebook/headless-handler.d.ts

@@ -138,6 +138,16 @@ export declare class HeadlessOperationHandler {
      * Used by startAgentSession to inform agent what changed between sessions.
      */
     getUpdatesSince(notebookPath: string, sinceTimestamp: number): UpdateSummary[];
+    /**
+     * Get-or-create the execution session for a notebook: on its bound cluster
+     * server when a binding exists (proxied session id), locally otherwise.
+     * A dead binding falls back to a fresh local kernel — allocations end
+     * routinely (walltime, cancel), and that fallback is the documented
+     * "falls back to a new kernel on next use" behavior.
+     */
+    private resolveKernelSession;
+    /** Start (get-or-create) a kernel on the bound server; null if it is gone. */
+    private startBoundKernel;
     private startKernelOp;
     private shutdownKernelOp;
     private restartKernelOp;

package/node-server/dist/notebook/headless-handler.js

@@ -49,6 +49,7 @@ const registry_1 = require("../fs/notebook-formats/registry");
 const cell_metadata_1 = require("./cell-metadata");
 const undoRedoManager_1 = require("./undoRedoManager");
 const kernelspec_1 = require("../kernel/kernelspec");
+const kernel_proxy_1 = require("../cluster/kernel-proxy");
 function copyCellOutput(output) {
     return {
         type: (output.type || 'stdout'),
@@ -1345,11 +1346,16 @@ class HeadlessOperationHandler {
                 error: 'Kernel service not available. Make sure the Node.js server is properly initialized.',
             };
         }
-        // Get or create a kernel session for this notebook
+        // Get or create a kernel session for this notebook. A kernel preference
+        // with a serverId means the notebook is bound to a cluster peer (compute
+        // allocation) — the kernel must live THERE, not on this server: resolving
+        // locally would run cells on the login node, and on a cross-arch
+        // allocation the local ipykernel probe can't even run the env's python.
         const requestedSessionId = operation.sessionId ?? operation.session_id;
-        const preferredKernelName = this.kernelService.getNotebookKernelPreference(notebookPath)?.kernelName || 'python3';
+        const kernelPref = this.kernelService.getNotebookKernelPreference(notebookPath);
+        const preferredKernelName = kernelPref?.kernelName || 'python3';
         let sessionId = null;
-        if (requestedSessionId && this.kernelService.hasSession(requestedSessionId)) {
+        if (requestedSessionId && (this.kernelService.hasSession(requestedSessionId) || (0, kernel_proxy_1.isProxiedSession)(requestedSessionId))) {
             sessionId = requestedSessionId;
         }
         else {
@@ -1357,8 +1363,7 @@ class HeadlessOperationHandler {
         }
         if (!sessionId) {
             try {
-                const result = await this.kernelService.getOrCreateKernel(notebookPath, preferredKernelName);
-                sessionId = result.sessionId;
+                sessionId = await this.resolveKernelSession(notebookPath, preferredKernelName, kernelPref?.serverId ?? null);
             }
             catch (err) {
                 const errMsg = err instanceof Error ? err.message : String(err);
@@ -1409,9 +1414,11 @@ class HeadlessOperationHandler {
             // Create execution promise
             const executeTask = async () => {
                 try {
-                    const result = await this.kernelService.executeCode(sessionId, code, outputCallback, (info) => {
-                        queueInfo = info;
-                    }, actualCellId);
+                    const result = (0, kernel_proxy_1.isProxiedSession)(sessionId)
+                        ? await (0, kernel_proxy_1.executeRemoteCode)(sessionId, code, outputCallback, actualCellId)
+                        : await this.kernelService.executeCode(sessionId, code, outputCallback, (info) => {
+                            queueInfo = info;
+                        }, actualCellId);
                     executionCount = result.executionCount;
                     if (!queueInfo && result.queuePosition !== undefined && result.queueLength !== undefined) {
                         queueInfo = { queuePosition: result.queuePosition, queueLength: result.queueLength };
@@ -1579,14 +1586,61 @@ class HeadlessOperationHandler {
     // -------------------------------------------------------------------------
     // Kernel Operations
     // -------------------------------------------------------------------------
+    /**
+     * Get-or-create the execution session for a notebook: on its bound cluster
+     * server when a binding exists (proxied session id), locally otherwise.
+     * A dead binding falls back to a fresh local kernel — allocations end
+     * routinely (walltime, cancel), and that fallback is the documented
+     * "falls back to a new kernel on next use" behavior.
+     */
+    async resolveKernelSession(notebookPath, kernelName, boundServerId) {
+        if (boundServerId) {
+            const remote = await this.startBoundKernel(notebookPath, kernelName, boundServerId);
+            if (remote)
+                return remote.sessionId;
+        }
+        const result = await this.kernelService.getOrCreateKernel(notebookPath, kernelName);
+        return result.sessionId;
+    }
+    /** Start (get-or-create) a kernel on the bound server; null if it is gone. */
+    async startBoundKernel(notebookPath, kernelName, serverId) {
+        try {
+            return await (0, kernel_proxy_1.startRemoteKernel)(serverId, kernelName, notebookPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`[Headless] Bound server ${serverId} unavailable (${msg}) — falling back to a local kernel`);
+            return null;
+        }
+    }
     async startKernelOp(operation, notebookPath) {
         if (!this.kernelService) {
             return { success: false, error: 'Kernel service not available' };
         }
         const kernelName = operation.kernelName || 'python3';
         try {
-            const { sessionId, created } = await this.kernelService.getOrCreateKernel(notebookPath, kernelName);
-            this.kernelService.saveNotebookKernelPreference(notebookPath, kernelName);
+            // Bound notebooks start their kernel on the bound server, and the
+            // binding must survive the preference re-save — dropping serverId here
+            // silently unbound notebooks from their allocations.
+            const boundServerId = this.kernelService.getNotebookKernelPreference(notebookPath)?.serverId ?? null;
+            let sessionId;
+            let created;
+            if (boundServerId) {
+                const remote = await this.startBoundKernel(notebookPath, kernelName, boundServerId);
+                if (remote) {
+                    sessionId = remote.sessionId;
+                    created = remote.created;
+                    this.kernelService.saveNotebookKernelPreference(notebookPath, kernelName, boundServerId);
+                }
+                else {
+                    ({ sessionId, created } = await this.kernelService.getOrCreateKernel(notebookPath, kernelName));
+                    this.kernelService.saveNotebookKernelPreference(notebookPath, kernelName);
+                }
+            }
+            else {
+                ({ sessionId, created } = await this.kernelService.getOrCreateKernel(notebookPath, kernelName));
+                this.kernelService.saveNotebookKernelPreference(notebookPath, kernelName);
+            }
             const spec = (0, kernelspec_1.getKernelSpec)(kernelName);
             const metadataResult = await this.fsService.updateNotebookMetadata(notebookPath, {
                 kernelspec: {

package/node-server/dist/notebook/operation-router.js

@@ -49,8 +49,10 @@ const os = __importStar(require("os"));
 const ws_1 = require("ws");
 const cell_hash_1 = require("./cell-hash");
 const registry_1 = require("../fs/notebook-formats/registry");
+const sealed_path_1 = require("../fs/sealed-path");
 const AGENT_LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
 const UI_STALE_TIMEOUT_MS = 45 * 1000; // 45 seconds
+const READ_ONLY_OPERATIONS = new Set(['readCell', 'readCellOutput', 'searchCells', 'readNotebook', 'getUpdatesSince']);
 function normalizeNotebookPath(notebookPath) {
     // IMPORTANT: This must match how the kernel service normalizes file paths.
     // If the UI registers `~/foo.ipynb` but the kernel associates the session
@@ -320,6 +322,16 @@ class OperationRouter {
         const normalizedPath = normalizeNotebookPath(notebookPath);
         const opType = operation.type;
         const agentId = operation.agentId;
+        const sealInfo = (0, sealed_path_1.classifySealedPath)(normalizedPath);
+        if (sealInfo.sealed && !READ_ONLY_OPERATIONS.has(opType)) {
+            return {
+                success: false,
+                error: `Cannot ${opType || 'modify notebook'}: sealed evidence ${sealInfo.sealId} is read-only`,
+                code: 'sealed_read_only',
+                seal_id: sealInfo.sealId,
+                path: sealInfo.canonicalPath,
+            };
+        }
         // For createNotebook, route to ANY connected UI (not path-specific)
         // This allows the UI to open the new notebook in a new tab.
         // EXCEPT text notebook formats (.py/.qmd): the UI's create handler only
@@ -375,10 +387,9 @@ class OperationRouter {
             return { ...result, backend };
         }
         // Enforce agent session for write operations
-        const readOnlyOps = new Set(['readCell', 'readCellOutput', 'searchCells', 'readNotebook', 'getUpdatesSince']);
         const sessionOps = new Set(['startAgentSession', 'endAgentSession']);
         const creationOps = new Set(['createNotebook']); // Operations that create files (don't require session)
-        const isWrite = !readOnlyOps.has(opType) && !sessionOps.has(opType) && !creationOps.has(opType);
+        const isWrite = !READ_ONLY_OPERATIONS.has(opType) && !sessionOps.has(opType) && !creationOps.has(opType);
         if (isWrite) {
             if (!isLocked) {
                 console.log(`  -> BLOCKED: Write requires active agent session`);

package/node-server/dist/provenance/canonical-json.d.ts

@@ -0,0 +1,36 @@
+export type CanonicalJsonValue = null | boolean | number | string | CanonicalJsonValue[] | {
+    [key: string]: CanonicalJsonValue;
+};
+/**
+ * Cross-runtime hash profile used by every structured Nebula provenance hash.
+ *
+ * This value is included in the encoded root, so future profiles cannot share
+ * a digest with this one even when their value encodings happen to match.
+ */
+export declare const CANONICAL_HASH_PROFILE: "nebula-canonical-hash-v1";
+/**
+ * Serialize a JSON value deterministically.
+ *
+ * Object keys are sorted recursively. Values that regular JSON.stringify
+ * silently drops or coerces are rejected: provenance hashes must never depend
+ * on an implicit lossy conversion.
+ */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(value: string | Buffer | Uint8Array): string;
+/**
+ * Convert a JSON-like value to an injective, language-neutral typed tree.
+ *
+ * - Object keys use Unicode scalar/code-point order rather than JavaScript's
+ *   UTF-16 code-unit order.
+ * - Safe integral numbers share one integer representation.
+ * - Every other finite Number, including -0 and unsafe integral Numbers, is
+ *   represented by its exact big-endian IEEE-754 binary64 bits.
+ * - Strings containing unpaired UTF-16 surrogates are rejected.
+ *
+ * The returned tree itself contains only JSON values, and contains no dynamic
+ * object keys, so regular JSON serialization is deterministic cross-runtime.
+ */
+export declare function canonicalizeForHash(value: unknown): CanonicalJsonValue;
+/** Serialize the typed cross-runtime representation used as SHA-256 input. */
+export declare function hashCanonicalJson(value: unknown): string;
+export declare function sha256Canonical(value: unknown): string;

package/node-server/dist/provenance/canonical-json.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_HASH_PROFILE = void 0;
+exports.canonicalJson = canonicalJson;
+exports.sha256Hex = sha256Hex;
+exports.canonicalizeForHash = canonicalizeForHash;
+exports.hashCanonicalJson = hashCanonicalJson;
+exports.sha256Canonical = sha256Canonical;
+const crypto_1 = require("crypto");
+/**
+ * Cross-runtime hash profile used by every structured Nebula provenance hash.
+ *
+ * This value is included in the encoded root, so future profiles cannot share
+ * a digest with this one even when their value encodings happen to match.
+ */
+exports.CANONICAL_HASH_PROFILE = 'nebula-canonical-hash-v1';
+/**
+ * Serialize a JSON value deterministically.
+ *
+ * Object keys are sorted recursively. Values that regular JSON.stringify
+ * silently drops or coerces are rejected: provenance hashes must never depend
+ * on an implicit lossy conversion.
+ */
+function canonicalJson(value) {
+    return serializeCanonical(value, new WeakSet(), '$');
+}
+function sha256Hex(value) {
+    return (0, crypto_1.createHash)('sha256').update(value).digest('hex');
+}
+/**
+ * Convert a JSON-like value to an injective, language-neutral typed tree.
+ *
+ * - Object keys use Unicode scalar/code-point order rather than JavaScript's
+ *   UTF-16 code-unit order.
+ * - Safe integral numbers share one integer representation.
+ * - Every other finite Number, including -0 and unsafe integral Numbers, is
+ *   represented by its exact big-endian IEEE-754 binary64 bits.
+ * - Strings containing unpaired UTF-16 surrogates are rejected.
+ *
+ * The returned tree itself contains only JSON values, and contains no dynamic
+ * object keys, so regular JSON serialization is deterministic cross-runtime.
+ */
+function canonicalizeForHash(value) {
+    return [
+        exports.CANONICAL_HASH_PROFILE,
+        encodeForHash(value, new WeakSet(), '$'),
+    ];
+}
+/** Serialize the typed cross-runtime representation used as SHA-256 input. */
+function hashCanonicalJson(value) {
+    return canonicalJson(canonicalizeForHash(value));
+}
+function sha256Canonical(value) {
+    return sha256Hex(hashCanonicalJson(value));
+}
+function encodeForHash(value, ancestors, location) {
+    if (value === null)
+        return ['null'];
+    switch (typeof value) {
+        case 'boolean':
+            return ['boolean', value];
+        case 'string':
+            assertUnicodeScalarString(value, location);
+            return ['string', value];
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`Canonical hash requires finite numbers at ${location}`);
+            }
+            if (Number.isSafeInteger(value) && !Object.is(value, -0)) {
+                return ['integer', value];
+            }
+            return ['float64', float64Hex(value)];
+        case 'undefined':
+            throw new TypeError(`Canonical hash cannot encode undefined at ${location}`);
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new TypeError(`Canonical hash cannot encode ${typeof value} at ${location}`);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Canonical hash cannot encode value at ${location}`);
+    }
+    const objectValue = value;
+    if (ancestors.has(objectValue)) {
+        throw new TypeError(`Canonical hash cannot encode a cyclic value at ${location}`);
+    }
+    ancestors.add(objectValue);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value)) {
+                    throw new TypeError(`Canonical hash cannot encode a sparse array at ${location}[${index}]`);
+                }
+                items.push(encodeForHash(value[index], ancestors, `${location}[${index}]`));
+            }
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                throw new TypeError(`Canonical hash cannot encode symbol keys at ${location}`);
+            }
+            return ['array', items];
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`Canonical hash requires a plain object at ${location}`);
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError(`Canonical hash cannot encode symbol keys at ${location}`);
+        }
+        const record = value;
+        const pairs = [];
+        const keys = Object.keys(record);
+        for (const key of keys)
+            assertUnicodeScalarString(key, `${location} object key`);
+        keys.sort(compareUnicodeCodePoints);
+        for (const key of keys) {
+            pairs.push([
+                key,
+                encodeForHash(record[key], ancestors, `${location}.${key}`),
+            ]);
+        }
+        return ['object', pairs];
+    }
+    finally {
+        ancestors.delete(objectValue);
+    }
+}
+function float64Hex(value) {
+    const bytes = Buffer.allocUnsafe(8);
+    bytes.writeDoubleBE(value, 0);
+    return bytes.toString('hex');
+}
+function assertUnicodeScalarString(value, location) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const following = value.charCodeAt(index + 1);
+            if (!(following >= 0xdc00 && following <= 0xdfff)) {
+                throw new TypeError(`Canonical hash requires Unicode scalar strings at ${location}`);
+            }
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            throw new TypeError(`Canonical hash requires Unicode scalar strings at ${location}`);
+        }
+    }
+}
+function compareUnicodeCodePoints(left, right) {
+    let leftIndex = 0;
+    let rightIndex = 0;
+    while (leftIndex < left.length && rightIndex < right.length) {
+        const leftPoint = left.codePointAt(leftIndex);
+        const rightPoint = right.codePointAt(rightIndex);
+        if (leftPoint !== rightPoint)
+            return leftPoint - rightPoint;
+        leftIndex += leftPoint > 0xffff ? 2 : 1;
+        rightIndex += rightPoint > 0xffff ? 2 : 1;
+    }
+    return (left.length - leftIndex) - (right.length - rightIndex);
+}
+function serializeCanonical(value, ancestors, location) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'string':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`Canonical JSON requires finite numbers at ${location}`);
+            }
+            // JSON.stringify canonicalizes -0 to 0, which is the desired JSON value.
+            return JSON.stringify(value);
+        case 'undefined':
+            throw new TypeError(`Canonical JSON cannot encode undefined at ${location}`);
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new TypeError(`Canonical JSON cannot encode ${typeof value} at ${location}`);
+        case 'object':
+            break;
+        default:
+            throw new TypeError(`Canonical JSON cannot encode value at ${location}`);
+    }
+    const objectValue = value;
+    if (ancestors.has(objectValue)) {
+        throw new TypeError(`Canonical JSON cannot encode a cyclic value at ${location}`);
+    }
+    ancestors.add(objectValue);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value)) {
+                    throw new TypeError(`Canonical JSON cannot encode a sparse array at ${location}[${index}]`);
+                }
+                items.push(serializeCanonical(value[index], ancestors, `${location}[${index}]`));
+            }
+            return `[${items.join(',')}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`Canonical JSON requires a plain object at ${location}`);
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError(`Canonical JSON cannot encode symbol keys at ${location}`);
+        }
+        const record = value;
+        const properties = Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${serializeCanonical(record[key], ancestors, `${location}.${key}`)}`);
+        return `{${properties.join(',')}}`;
+    }
+    finally {
+        ancestors.delete(objectValue);
+    }
+}

package/node-server/dist/provenance/provenance-store.d.ts

@@ -0,0 +1,63 @@
+import type { ProvenanceAppendResult, ProvenanceBlobReference, ProvenanceBlobVerification, ProvenanceEvent, ProvenanceEventInput, ProvenanceVerification } from './types';
+export declare class ProvenanceIntegrityError extends Error {
+    readonly code = "PROVENANCE_INTEGRITY_ERROR";
+    readonly failedLine?: number;
+    constructor(message: string, failedLine?: number);
+}
+export declare class IdempotencyConflictError extends Error {
+    readonly code = "IDEMPOTENCY_CONFLICT";
+    constructor(key: string);
+}
+export declare class BlobIntegrityError extends Error {
+    readonly code = "PROVENANCE_BLOB_INTEGRITY_ERROR";
+    constructor(message: string);
+}
+export interface ProvenanceStoreOptions {
+    /** fsync ledger/blob writes. Defaults to true. */
+    durable?: boolean;
+    /** Test seam; production events always use the server clock. */
+    clock?: () => Date;
+    /** Test seam; production events use cryptographically random UUIDs. */
+    idFactory?: () => string;
+}
+/**
+ * Server-owned append-only scientific provenance storage.
+ *
+ * Undo/redo history remains a separate, client-replaceable projection. This
+ * store writes one canonical event per JSONL line and binds every event to the
+ * previous event hash. All mutations for a notebook are serialized in-process.
+ */
+export declare class ProvenanceStore {
+    private static readonly writeQueues;
+    private readonly durable;
+    private readonly clock;
+    private readonly idFactory;
+    constructor(options?: ProvenanceStoreOptions);
+    getLedgerPath(notebookPath: string): string;
+    getBlobPath(notebookPath: string, sha256: string): string;
+    append(notebookPath: string, input: ProvenanceEventInput): Promise<ProvenanceAppendResult>;
+    read(notebookPath: string): Promise<ProvenanceEvent[]>;
+    verify(notebookPath: string): Promise<ProvenanceVerification>;
+    findByIdempotencyKey(notebookPath: string, idempotencyKey: string): Promise<ProvenanceEvent | null>;
+    putBlob(notebookPath: string, value: string | Buffer | Uint8Array): Promise<ProvenanceBlobReference>;
+    readBlob(notebookPath: string, sha256: string): Promise<Buffer>;
+    verifyBlob(notebookPath: string, sha256: string): Promise<ProvenanceBlobVerification>;
+    private normalizeNotebookPath;
+    private normalizeInput;
+    private canonicalClone;
+    private hashRequest;
+    private requestEnvelope;
+    private inputFromEvent;
+    private readVerified;
+    private validateEventShape;
+    private appendLine;
+    private ledgerNeedsNewline;
+    private syncDirectory;
+    private readIfExists;
+    private assertBlobBytes;
+    private toBuffer;
+    private assertSha256;
+    private runSerialized;
+    private isNodeError;
+}
+export type { ProvenanceActor, ProvenanceAppendResult, ProvenanceBlobReference, ProvenanceBlobVerification, ProvenanceEvent, ProvenanceEventInput, ProvenanceVerification, } from './types';