nebula-notebook 0.2.15 → 0.2.17

package/node-server/dist/provenance/replay-seal-service.js

@@ -0,0 +1,1702 @@
+"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 });
+exports.ReplaySealService = exports.ReplaySealConflictError = exports.ReplaySealValidationError = void 0;
+exports.normalizeNotebookOutputsForComparison = normalizeNotebookOutputsForComparison;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const fsp = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const canonical_json_1 = require("./canonical-json");
+const provenance_store_1 = require("./provenance-store");
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const CELL_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const SEAL_ID_RE = /^seal-[a-f0-9]{32}$/;
+const PROBE_BEGIN = '__NEBULA_RUNTIME_ENV_BEGIN__';
+const PROBE_END = '__NEBULA_RUNTIME_ENV_END__';
+const OUTPUT_LIMIT_MARKER = 'Output limit reached';
+class ReplaySealValidationError extends Error {
+    code = 'REPLAY_SEAL_VALIDATION_ERROR';
+    constructor(message) {
+        super(message);
+        this.name = 'ReplaySealValidationError';
+    }
+}
+exports.ReplaySealValidationError = ReplaySealValidationError;
+class ReplaySealConflictError extends Error {
+    code = 'IDEMPOTENCY_CONFLICT';
+    constructor() {
+        super('Idempotency-Key was already used with a different replay-seal request');
+        this.name = 'ReplaySealConflictError';
+    }
+}
+exports.ReplaySealConflictError = ReplaySealConflictError;
+/**
+ * Normalize only nbformat's equivalent text encodings for replay comparison.
+ *
+ * - stream.text: an array of strings is joined, a string is unchanged;
+ * - data values for text/*, application/javascript, and image/svg+xml use the
+ *   same array-to-string join;
+ * - every other JSON value, including binary MIME arrays and traceback, is
+ *   preserved exactly.
+ *
+ * This is intentionally separate from outputs_sha256, which hashes the exact
+ * output JSON written to the immutable executed notebook.
+ */
+function normalizeNotebookOutputsForComparison(value) {
+    if (!Array.isArray(value)) {
+        throw new ReplaySealValidationError('Notebook outputs must be an array');
+    }
+    const cloned = JSON.parse((0, canonical_json_1.canonicalJson)(value));
+    for (const rawOutput of cloned) {
+        if (!rawOutput || typeof rawOutput !== 'object' || Array.isArray(rawOutput))
+            continue;
+        const output = rawOutput;
+        if (output.output_type === 'stream' && 'text' in output) {
+            output.text = joinTextArray(output.text, 'stream.text');
+        }
+        const data = output.data;
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+            for (const [mimeType, mimeValue] of Object.entries(data)) {
+                if (mimeType.startsWith('text/')
+                    || mimeType === 'application/javascript'
+                    || mimeType === 'image/svg+xml') {
+                    data[mimeType] = joinTextArray(mimeValue, `data.${mimeType}`);
+                }
+            }
+        }
+    }
+    return cloned;
+}
+function joinTextArray(value, field) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === 'string')) {
+        return value.join('');
+    }
+    throw new ReplaySealValidationError(`${field} must be a string or an array of strings`);
+}
+/**
+ * Fresh-kernel, top-to-bottom replay and immutable evidence sealing.
+ *
+ * The service deliberately makes no network/filesystem-isolation claim. A
+ * dedicated kernel prevents state inheritance from an exploratory session;
+ * the immutable copies, hashes, and server-authored event prefix bind what ran.
+ */
+class ReplaySealService {
+    static queues = new Map();
+    rootDirectory;
+    registryDirectory;
+    kernelService;
+    provenanceStore;
+    durable;
+    idFactory;
+    clock;
+    processInstanceId = (0, crypto_1.randomUUID)();
+    activeJobs = new Map();
+    attemptedJobs = new Set();
+    constructor(options) {
+        if (!options || typeof options !== 'object') {
+            throw new TypeError('ReplaySealService options are required');
+        }
+        this.rootDirectory = path.resolve(options.rootDirectory);
+        this.registryDirectory = path.join(this.rootDirectory, '.nebula', 'replay-seal-jobs');
+        this.kernelService = options.kernelService;
+        this.provenanceStore = options.provenanceStore ?? new provenance_store_1.ProvenanceStore();
+        this.durable = options.durable !== false;
+        this.idFactory = options.idFactory ?? crypto_1.randomUUID;
+        this.clock = options.clock ?? (() => new Date());
+    }
+    async submit(rawRequest, idempotencyKey) {
+        const request = this.normalizeRequest(rawRequest);
+        this.validateIdempotencyKey(idempotencyKey);
+        await this.ensureRegistryDirectory();
+        const sealId = `seal-${(0, canonical_json_1.sha256Hex)(idempotencyKey).slice(0, 32)}`;
+        const requestFingerprint = (0, canonical_json_1.sha256Canonical)(request);
+        const registryPath = this.registryPath(sealId);
+        const job = await this.runSerialized(`seal:${registryPath}`, async () => {
+            const existing = await this.readJob(registryPath);
+            if (existing) {
+                if (existing.requestFingerprint !== requestFingerprint) {
+                    throw new ReplaySealConflictError();
+                }
+                return existing;
+            }
+            const sourceBytes = await this.readNotebookSource(request.notebook_path);
+            const sourceSha256 = (0, canonical_json_1.sha256Hex)(sourceBytes);
+            if (sourceSha256 !== request.source_notebook_sha256) {
+                throw new ReplaySealValidationError(`source_notebook_sha256 mismatch: expected ${request.source_notebook_sha256}, got ${sourceSha256}`);
+            }
+            const frozen = this.parseFrozenNotebook(sourceBytes, request.kernel_name);
+            this.validateEnvironmentDeclaration(request.environment_manifest, path.dirname(request.notebook_path));
+            await this.preflightArtifacts(request);
+            const sealDirectory = await this.createSafeSealDirectory(path.dirname(request.notebook_path), sealId);
+            const frozenNotebookPath = path.join(sealDirectory, 'source.ipynb');
+            await this.writeImmutable(frozenNotebookPath, sourceBytes);
+            const now = this.clock().toISOString();
+            const created = {
+                schemaVersion: 1,
+                sealId,
+                status: 'pending',
+                requestFingerprint,
+                request,
+                sourceNotebookSha256: sourceSha256,
+                frozenNotebookPath,
+                sealDirectory,
+                processInstanceId: this.processInstanceId,
+                createdAt: now,
+                updatedAt: now,
+            };
+            await this.persistJob(created);
+            return created;
+        });
+        if (job.status === 'pending' || job.status === 'running') {
+            if (job.processInstanceId !== this.processInstanceId) {
+                await this.failJob(job, new Error('Nebula restarted during replay; automatic re-execution is refused because notebook code may have external side effects'));
+                const interrupted = await this.readJob(registryPath);
+                if (!interrupted)
+                    throw new Error(`Interrupted replay job disappeared: ${sealId}`);
+                return this.verifiedResponseFor(interrupted);
+            }
+            this.ensureRunning(job);
+        }
+        return this.verifiedResponseFor(job);
+    }
+    async getStatus(sealId) {
+        if (!SEAL_ID_RE.test(sealId))
+            return null;
+        await this.ensureRegistryDirectory();
+        const job = await this.readJob(this.registryPath(sealId));
+        if (!job)
+            return null;
+        if (job.status === 'pending' || job.status === 'running') {
+            if (job.processInstanceId !== this.processInstanceId) {
+                await this.failJob(job, new Error('Nebula restarted during replay; automatic re-execution is refused because notebook code may have external side effects'));
+                const interrupted = await this.readJob(this.registryPath(sealId));
+                return interrupted ? this.responseFor(interrupted) : null;
+            }
+            this.ensureRunning(job);
+        }
+        return this.verifiedResponseFor(job);
+    }
+    ensureRunning(job) {
+        if (this.activeJobs.has(job.sealId) || this.attemptedJobs.has(job.sealId))
+            return;
+        this.attemptedJobs.add(job.sealId);
+        const run = this.runJob(job).catch(async (error) => {
+            await this.failJob(job, error).catch(() => undefined);
+        }).finally(() => {
+            if (this.activeJobs.get(job.sealId) === run)
+                this.activeJobs.delete(job.sealId);
+        });
+        this.activeJobs.set(job.sealId, run);
+    }
+    async runJob(initialJob) {
+        let job = await this.updateJob(initialJob, { status: 'running', error: undefined });
+        const request = job.request;
+        const actor = { kind: 'agent', id: request.source_id, name: 'kosmos' };
+        const inputManifestSha256 = (0, canonical_json_1.sha256Canonical)(request.input_manifest);
+        const environmentManifestSha256 = (0, canonical_json_1.sha256Canonical)(request.environment_manifest);
+        await this.provenanceStore.putBlob(request.notebook_path, (0, canonical_json_1.hashCanonicalJson)(request.input_manifest));
+        await this.provenanceStore.putBlob(request.notebook_path, (0, canonical_json_1.hashCanonicalJson)(request.environment_manifest));
+        const frozenBytes = await fsp.readFile(job.frozenNotebookPath);
+        if ((0, canonical_json_1.sha256Hex)(frozenBytes) !== job.sourceNotebookSha256) {
+            throw new Error('Frozen source notebook failed hash verification');
+        }
+        const frozen = this.parseFrozenNotebook(frozenBytes, request.kernel_name);
+        const commonEvent = {
+            actor,
+            runId: request.run_id,
+            taskId: request.task_id,
+            sourceId: request.source_id,
+            inputManifestSha256,
+            environmentManifestSha256,
+        };
+        await this.provenanceStore.append(request.notebook_path, {
+            ...commonEvent,
+            type: 'seal.started',
+            idempotencyKey: this.sealRequestEventKey(job.sealId),
+            payload: {
+                schemaVersion: 1,
+                sealId: job.sealId,
+                sourceNotebook: {
+                    path: request.notebook_path,
+                    sha256: job.sourceNotebookSha256,
+                },
+                kernelName: frozen.kernelName,
+                artifacts: request.artifacts.map((artifact) => ({
+                    path: artifact.path,
+                    sha256: artifact.sha256,
+                    sizeBytes: artifact.size_bytes,
+                })),
+                isolation: {
+                    freshKernel: true,
+                    networkIsolated: false,
+                    filesystemIsolated: false,
+                },
+            },
+        });
+        let sessionId;
+        let executionError;
+        let stopError;
+        let runtimeEnvironment;
+        let bootstrapManifest;
+        const executedCells = [];
+        try {
+            sessionId = await this.kernelService.startKernel({
+                kernelName: frozen.kernelName,
+                cwd: path.dirname(request.notebook_path),
+                internalEnv: { PYTHONNOUSERSITE: '1' },
+            });
+            const baseProbe = await this.executeServerCode(sessionId, this.baseEnvironmentProbeSource());
+            const probed = this.parseBaseEnvironmentProbe(baseProbe.rawStdout);
+            this.compareBaseEnvironment(probed, request.environment_manifest);
+            await this.appendExecutionEvent(request.notebook_path, commonEvent, {
+                type: 'seal.environment.probed',
+                executionId: baseProbe.executionId,
+                payload: {
+                    schemaVersion: 1,
+                    sourceSha256: baseProbe.sourceSha256,
+                    outputsSha256: baseProbe.outputsSha256,
+                    executionCount: baseProbe.executionCount,
+                    basePackagesSha256: probed.base_packages_sha256,
+                    executableRealpath: probed.python.executable_realpath,
+                    pythonNoUserSite: true,
+                    status: 'completed',
+                },
+            });
+            const taskLocal = this.taskLocalDeclaration(request.environment_manifest, path.dirname(request.notebook_path));
+            let actualTaskLocal = null;
+            if (taskLocal) {
+                const bootstrap = await this.executeServerCode(sessionId, this.taskLocalBootstrapSource(taskLocal.packageDirectory, taskLocal.canonicalPackageDirectory));
+                const packages = this.parseTaskLocalProbe(bootstrap.rawStdout);
+                const packagesSha256 = (0, canonical_json_1.sha256Canonical)(packages);
+                this.compareTaskLocalEnvironment(packages, packagesSha256, taskLocal.declaration);
+                actualTaskLocal = {
+                    package_directory: taskLocal.packageDirectory,
+                    packages,
+                    packages_sha256: packagesSha256,
+                };
+                bootstrapManifest = {
+                    package_directory: taskLocal.packageDirectory,
+                    source_sha256: bootstrap.sourceSha256,
+                    outputs_sha256: bootstrap.outputsSha256,
+                    execution_id: bootstrap.executionId,
+                    execution_count: bootstrap.executionCount,
+                    status: 'completed',
+                };
+                await this.appendExecutionEvent(request.notebook_path, commonEvent, {
+                    type: 'seal.bootstrap.completed',
+                    executionId: bootstrap.executionId,
+                    payload: {
+                        schemaVersion: 1,
+                        packageDirectory: taskLocal.packageDirectory,
+                        packagesSha256,
+                        sourceSha256: bootstrap.sourceSha256,
+                        outputsSha256: bootstrap.outputsSha256,
+                        executionCount: bootstrap.executionCount,
+                        status: 'completed',
+                    },
+                });
+            }
+            runtimeEnvironment = { ...probed, task_local: actualTaskLocal };
+            for (const cell of frozen.codeCells) {
+                const execution = await this.executeNotebookCell(sessionId, cell);
+                const manifest = {
+                    cell_id: cell.id,
+                    source_sha256: execution.sourceSha256,
+                    exploratory_outputs_sha256: cell.exploratoryOutputsSha256,
+                    outputs_sha256: execution.outputsSha256,
+                    replay_comparison_outputs_sha256: execution.comparisonOutputsSha256,
+                    outputs_match_exploratory: cell.exploratoryOutputsSha256 === execution.comparisonOutputsSha256,
+                    exploratory_execution_count: cell.exploratoryExecutionCount,
+                    execution_id: execution.executionId,
+                    execution_count: execution.executionCount,
+                    status: 'completed',
+                };
+                executedCells.push({ index: cell.index, manifest, outputs: execution.outputs });
+                await this.appendExecutionEvent(request.notebook_path, commonEvent, {
+                    type: 'seal.cell.completed',
+                    executionId: execution.executionId,
+                    payload: {
+                        schemaVersion: 1,
+                        sealId: job.sealId,
+                        cellId: cell.id,
+                        sourceSha256: execution.sourceSha256,
+                        exploratoryOutputsSha256: cell.exploratoryOutputsSha256,
+                        outputsSha256: execution.outputsSha256,
+                        replayComparisonOutputsSha256: execution.comparisonOutputsSha256,
+                        outputsMatchExploratory: cell.exploratoryOutputsSha256 === execution.comparisonOutputsSha256,
+                        exploratoryExecutionCount: cell.exploratoryExecutionCount,
+                        executionCount: execution.executionCount,
+                        status: 'completed',
+                    },
+                });
+            }
+        }
+        catch (error) {
+            executionError = error;
+        }
+        finally {
+            if (sessionId !== undefined) {
+                try {
+                    const stopped = await this.kernelService.stopKernel(sessionId);
+                    if (!stopped)
+                        stopError = new Error('Fresh replay kernel could not be stopped');
+                }
+                catch (error) {
+                    stopError = error;
+                }
+            }
+        }
+        if (executionError)
+            throw executionError;
+        if (stopError)
+            throw stopError;
+        if (!runtimeEnvironment)
+            throw new Error('Fresh kernel produced no environment attestation');
+        const sealedNotebook = this.buildSealedNotebook(frozen.notebook, executedCells);
+        const sealedBytes = Buffer.from(`${(0, canonical_json_1.canonicalJson)(sealedNotebook)}\n`, 'utf8');
+        const sealedNotebookPath = path.join(job.sealDirectory, 'notebook.ipynb');
+        await this.writeImmutable(sealedNotebookPath, sealedBytes);
+        const notebookSha256 = (0, canonical_json_1.sha256Hex)(sealedBytes);
+        const artifacts = await this.sealArtifacts(request, job.sealDirectory, sealedNotebookPath, notebookSha256, sealedBytes.length);
+        const runtimeEnvironmentSha256 = (0, canonical_json_1.sha256Canonical)(runtimeEnvironment);
+        await this.provenanceStore.putBlob(request.notebook_path, (0, canonical_json_1.hashCanonicalJson)(runtimeEnvironment));
+        const completion = await this.provenanceStore.append(request.notebook_path, {
+            ...commonEvent,
+            type: 'seal.completed',
+            payload: {
+                schemaVersion: 1,
+                hashProfile: canonical_json_1.CANONICAL_HASH_PROFILE,
+                sealId: job.sealId,
+                sourceNotebook: {
+                    path: request.notebook_path,
+                    sha256: job.sourceNotebookSha256,
+                },
+                notebook: { path: sealedNotebookPath, sha256: notebookSha256 },
+                inputManifestSha256,
+                environmentManifestSha256,
+                runtimeEnvironmentSha256,
+                cells: executedCells.map(({ manifest }) => ({
+                    cellId: manifest.cell_id,
+                    sourceSha256: manifest.source_sha256,
+                    exploratoryOutputsSha256: manifest.exploratory_outputs_sha256,
+                    outputsSha256: manifest.outputs_sha256,
+                    replayComparisonOutputsSha256: manifest.replay_comparison_outputs_sha256,
+                    outputsMatchExploratory: manifest.outputs_match_exploratory,
+                    exploratoryExecutionCount: manifest.exploratory_execution_count,
+                    executionId: manifest.execution_id,
+                    executionCount: manifest.execution_count,
+                    status: manifest.status,
+                })),
+                artifacts: artifacts.map((artifact) => ({
+                    sourcePath: artifact.source_path,
+                    path: artifact.path,
+                    sha256: artifact.sha256,
+                    sizeBytes: artifact.size_bytes,
+                })),
+                isolation: {
+                    freshKernel: true,
+                    networkIsolated: false,
+                    filesystemIsolated: false,
+                },
+            },
+        });
+        const eventLedger = await this.captureLedgerPrefix(request.notebook_path, completion.event.eventHash, completion.event.seq);
+        const unsignedManifest = {
+            schema_version: 1,
+            hash_profile: canonical_json_1.CANONICAL_HASH_PROFILE,
+            seal_id: job.sealId,
+            source_notebook: {
+                path: request.notebook_path,
+                sha256: job.sourceNotebookSha256,
+            },
+            notebook: { path: sealedNotebookPath, sha256: notebookSha256 },
+            input_manifest_sha256: inputManifestSha256,
+            environment_manifest_sha256: environmentManifestSha256,
+            runtime_environment: runtimeEnvironment,
+            runtime_environment_sha256: runtimeEnvironmentSha256,
+            event_chain_head_sha256: completion.event.eventHash,
+            event_ledger: eventLedger,
+            cells: executedCells.map(({ manifest }) => manifest),
+            artifacts,
+            isolation: {
+                fresh_kernel: true,
+                network_isolated: false,
+                filesystem_isolated: false,
+            },
+            ...(bootstrapManifest ? { bootstrap: bootstrapManifest } : {}),
+        };
+        const manifest = {
+            ...unsignedManifest,
+            manifest_sha256: (0, canonical_json_1.sha256Canonical)(unsignedManifest),
+        };
+        await this.writeImmutable(path.join(job.sealDirectory, 'manifest.json'), Buffer.from(`${(0, canonical_json_1.canonicalJson)(manifest)}\n`, 'utf8'));
+        job = await this.updateJob(job, { status: 'completed', manifest, error: undefined });
+        await this.hardenSealDirectory(job.sealDirectory);
+    }
+    async failJob(job, error) {
+        const message = this.errorMessage(error);
+        const request = job.request;
+        const common = {
+            actor: { kind: 'agent', id: request.source_id, name: 'kosmos' },
+            runId: request.run_id,
+            taskId: request.task_id,
+            sourceId: request.source_id,
+            inputManifestSha256: (0, canonical_json_1.sha256Canonical)(request.input_manifest),
+            environmentManifestSha256: (0, canonical_json_1.sha256Canonical)(request.environment_manifest),
+        };
+        await this.provenanceStore.append(request.notebook_path, {
+            ...common,
+            type: 'seal.failed',
+            payload: {
+                schemaVersion: 1,
+                hashProfile: canonical_json_1.CANONICAL_HASH_PROFILE,
+                sealId: job.sealId,
+                error: message,
+            },
+        }).catch(() => undefined);
+        await this.updateJob(job, { status: 'failed', error: message, manifest: undefined });
+    }
+    async executeNotebookCell(sessionId, cell) {
+        return this.executeAndCapture(sessionId, cell.source, cell.id);
+    }
+    async executeServerCode(sessionId, source) {
+        return this.executeAndCapture(sessionId, source, null, { storeHistory: false });
+    }
+    async executeAndCapture(sessionId, source, cellId, internalOptions) {
+        const executionId = this.idFactory();
+        const kernelOutputs = [];
+        const result = await this.kernelService.executeCode(sessionId, source, async (output) => { kernelOutputs.push(this.cloneJson(output)); }, undefined, cellId, internalOptions);
+        const errorOutput = kernelOutputs.find((output) => output.type === 'error');
+        if (result.status !== 'ok' || errorOutput) {
+            throw new Error(result.error || errorOutput?.content || `Execution failed for ${cellId ?? 'server bootstrap'}`);
+        }
+        if (!Number.isSafeInteger(result.executionCount) || (result.executionCount ?? -1) < 0) {
+            throw new Error(`Kernel returned no valid execution count for ${cellId ?? 'server bootstrap'}`);
+        }
+        if (kernelOutputs.some((output) => output.content.includes(OUTPUT_LIMIT_MARKER))) {
+            throw new Error(`Kernel output was truncated for ${cellId ?? 'server bootstrap'}`);
+        }
+        const outputs = kernelOutputs.map((output) => this.toJupyterOutput(output));
+        return {
+            executionId,
+            executionCount: result.executionCount,
+            sourceSha256: (0, canonical_json_1.sha256Hex)(source),
+            outputsSha256: (0, canonical_json_1.sha256Canonical)(outputs),
+            comparisonOutputsSha256: (0, canonical_json_1.sha256Canonical)(normalizeNotebookOutputsForComparison(outputs)),
+            outputs,
+            rawStdout: kernelOutputs
+                .filter((output) => output.type === 'stdout')
+                .map((output) => output.content)
+                .join(''),
+        };
+    }
+    async appendExecutionEvent(notebookPath, common, details) {
+        await this.provenanceStore.append(notebookPath, { ...common, ...details });
+    }
+    buildSealedNotebook(notebook, executed) {
+        const sealed = this.cloneJson(notebook);
+        for (const item of executed) {
+            const cell = sealed.cells[item.index];
+            cell.outputs = item.outputs;
+            cell.execution_count = item.manifest.execution_count;
+        }
+        return sealed;
+    }
+    async preflightArtifacts(request) {
+        const workspace = path.dirname(request.notebook_path);
+        for (const descriptor of request.artifacts) {
+            try {
+                await this.assertNoSymlinkComponents(workspace, descriptor.path);
+                const actual = await this.hashRegularFile(descriptor.path);
+                if (actual.size_bytes !== descriptor.size_bytes) {
+                    throw new ReplaySealValidationError(`Requested artifact size mismatch: ${descriptor.path}; expected ${descriptor.size_bytes}, got ${actual.size_bytes}`);
+                }
+                if (actual.sha256 !== descriptor.sha256) {
+                    throw new ReplaySealValidationError(`Requested artifact sha256 mismatch: ${descriptor.path}; expected ${descriptor.sha256}, got ${actual.sha256}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof ReplaySealValidationError)
+                    throw error;
+                throw new ReplaySealValidationError(this.errorMessage(error));
+            }
+        }
+    }
+    async sealArtifacts(request, sealDirectory, sealedNotebookPath, notebookSha256, notebookSize) {
+        const artifacts = [{
+                source_path: request.notebook_path,
+                path: sealedNotebookPath,
+                sha256: notebookSha256,
+                size_bytes: notebookSize,
+            }];
+        const workspace = path.dirname(request.notebook_path);
+        for (const descriptor of request.artifacts) {
+            const sourcePath = descriptor.path;
+            const relative = this.relativeInside(workspace, sourcePath, 'artifact path');
+            if (relative.split(path.sep)[0] === '.nebula') {
+                throw new Error(`Requested artifact must not be inside .nebula: ${sourcePath}`);
+            }
+            await this.assertNoSymlinkComponents(workspace, sourcePath);
+            const components = relative.split(path.sep);
+            const filename = components.pop();
+            if (!filename)
+                throw new Error(`Requested artifact has no filename: ${sourcePath}`);
+            const destinationDirectory = await this.ensureSafeDirectoryChain(sealDirectory, ['artifacts', ...components]);
+            const destination = path.join(destinationDirectory, filename);
+            const copied = await this.copyRegularFileImmutable(sourcePath, destination, descriptor);
+            artifacts.push({ source_path: sourcePath, path: destination, ...copied });
+        }
+        return artifacts;
+    }
+    async copyRegularFileImmutable(sourcePath, destination, expected) {
+        let source;
+        try {
+            source = await fsp.open(sourcePath, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (this.isNodeError(error, 'ENOENT'))
+                throw new Error(`Requested artifact is missing: ${sourcePath}`);
+            if (this.isNodeError(error, 'ELOOP'))
+                throw new Error(`Requested artifact is a symbolic link: ${sourcePath}`);
+            throw error;
+        }
+        const directory = path.dirname(destination);
+        const temporary = `${destination}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`;
+        let destinationHandle;
+        try {
+            const before = await source.stat();
+            if (!before.isFile())
+                throw new Error(`Requested artifact is not a regular file: ${sourcePath}`);
+            destinationHandle = await fsp.open(temporary, 'wx', 0o400);
+            const hash = (0, crypto_1.createHash)('sha256');
+            const buffer = Buffer.allocUnsafe(1024 * 1024);
+            let sizeBytes = 0;
+            for (;;) {
+                const { bytesRead } = await source.read(buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    break;
+                const chunk = buffer.subarray(0, bytesRead);
+                hash.update(chunk);
+                await destinationHandle.write(chunk);
+                sizeBytes += bytesRead;
+            }
+            if (this.durable)
+                await destinationHandle.sync();
+            const after = await source.stat();
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+                || before.mtimeMs !== after.mtimeMs || after.size !== sizeBytes) {
+                throw new Error(`Requested artifact changed while it was sealed: ${sourcePath}`);
+            }
+            const sha256 = hash.digest('hex');
+            if (sizeBytes !== expected.size_bytes) {
+                throw new Error(`Requested artifact size mismatch after replay: ${sourcePath}; expected ${expected.size_bytes}, got ${sizeBytes}`);
+            }
+            if (sha256 !== expected.sha256) {
+                throw new Error(`Requested artifact sha256 mismatch after replay: ${sourcePath}; expected ${expected.sha256}, got ${sha256}`);
+            }
+            await destinationHandle.close();
+            destinationHandle = undefined;
+            try {
+                await fsp.link(temporary, destination);
+            }
+            catch (error) {
+                if (this.isNodeError(error, 'EEXIST')) {
+                    throw new Error(`Immutable artifact destination already exists: ${destination}`);
+                }
+                throw error;
+            }
+            await fsp.chmod(destination, 0o400);
+            if (this.durable)
+                await this.syncDirectory(directory);
+            return { sha256, size_bytes: sizeBytes };
+        }
+        finally {
+            await source.close().catch(() => undefined);
+            await destinationHandle?.close().catch(() => undefined);
+            await fsp.unlink(temporary).catch(() => undefined);
+        }
+    }
+    baseEnvironmentProbeSource() {
+        return [
+            'def __nebula_server_environment_probe__():',
+            '    import importlib.metadata as metadata',
+            '    import json',
+            '    import os',
+            '    import platform',
+            '    import sys',
+            '    packages = {}',
+            '    for distribution in metadata.distributions():',
+            '        name = distribution.metadata.get("Name")',
+            '        if name:',
+            '            packages[str(name).lower()] = str(distribution.version)',
+            '    value = {',
+            '        "executable": sys.executable,',
+            '        "executable_realpath": os.path.realpath(sys.executable),',
+            '        "implementation": platform.python_implementation(),',
+            '        "version": platform.python_version(),',
+            '        "platform": platform.platform(),',
+            '        "base_packages": dict(sorted(packages.items())),',
+            '    }',
+            `    print(${JSON.stringify(PROBE_BEGIN)} + json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + ${JSON.stringify(PROBE_END)})`,
+            '__nebula_server_environment_probe__()',
+            'del __nebula_server_environment_probe__',
+        ].join('\n');
+    }
+    taskLocalBootstrapSource(packageDirectory, canonicalPackageDirectory) {
+        return [
+            'def __nebula_server_task_local_bootstrap__():',
+            '    import importlib.metadata as metadata',
+            '    import json',
+            '    import os',
+            '    import sys',
+            `    package_directory = ${JSON.stringify(packageDirectory)}`,
+            `    expected_realpath = ${JSON.stringify(canonicalPackageDirectory)}`,
+            '    if os.path.realpath(package_directory) != expected_realpath or not os.path.isdir(package_directory):',
+            '        raise RuntimeError("task-local package directory changed after server validation")',
+            '    packages = {}',
+            '    for distribution in metadata.distributions(path=[package_directory]):',
+            '        name = distribution.metadata.get("Name")',
+            '        if name:',
+            '            packages[str(name).lower()] = str(distribution.version)',
+            '    if package_directory not in sys.path:',
+            '        sys.path.insert(0, package_directory)',
+            `    print(${JSON.stringify(PROBE_BEGIN)} + json.dumps(dict(sorted(packages.items())), ensure_ascii=False, sort_keys=True, separators=(",", ":")) + ${JSON.stringify(PROBE_END)})`,
+            '__nebula_server_task_local_bootstrap__()',
+            'del __nebula_server_task_local_bootstrap__',
+        ].join('\n');
+    }
+    parseBaseEnvironmentProbe(stdout) {
+        const raw = this.markerPayload(stdout, 'environment probe');
+        const value = this.parseObject(raw, 'environment probe');
+        const packages = this.stringMap(value.base_packages, 'environment probe base_packages');
+        const python = {
+            executable: this.nonempty(value.executable, 'environment probe executable'),
+            executable_realpath: this.nonempty(value.executable_realpath, 'environment probe executable_realpath'),
+            implementation: this.nonempty(value.implementation, 'environment probe implementation'),
+            version: this.nonempty(value.version, 'environment probe version'),
+            platform: this.nonempty(value.platform, 'environment probe platform'),
+        };
+        if (!path.isAbsolute(python.executable) || !path.isAbsolute(python.executable_realpath)) {
+            throw new Error('Fresh kernel environment probe returned a non-absolute executable');
+        }
+        return {
+            schema_version: 1,
+            python,
+            python_no_user_site: true,
+            base_packages: packages,
+            base_packages_sha256: (0, canonical_json_1.sha256Canonical)(packages),
+        };
+    }
+    parseTaskLocalProbe(stdout) {
+        return this.stringMap(this.parseObject(this.markerPayload(stdout, 'task-local bootstrap'), 'task-local bootstrap'), 'task-local packages');
+    }
+    compareBaseEnvironment(actual, declaration) {
+        const base = this.optionalRecord(declaration.base, 'environment_manifest.base');
+        if (!base || base.inspection === 'not_configured')
+            return;
+        const comparisons = [
+            ['python_binary_target', base.python_binary_target, actual.python.executable_realpath],
+            ['implementation', base.implementation, actual.python.implementation],
+            ['python_version', base.python_version, actual.python.version],
+            ['platform', base.platform, actual.python.platform],
+            ['base_packages_sha256', base.base_packages_sha256, actual.base_packages_sha256],
+        ];
+        for (const [name, expected, observed] of comparisons) {
+            if (expected !== undefined && expected !== null && expected !== observed) {
+                throw new Error(`Fresh kernel environment mismatch for ${name}: expected ${String(expected)}, got ${String(observed)}`);
+            }
+        }
+        if (base.base_packages !== undefined) {
+            const expectedPackages = this.stringMap(base.base_packages, 'environment_manifest.base.base_packages');
+            if ((0, canonical_json_1.sha256Canonical)(expectedPackages) !== actual.base_packages_sha256) {
+                throw new Error('Fresh kernel environment mismatch for base_packages');
+            }
+        }
+    }
+    compareTaskLocalEnvironment(packages, packagesSha256, declaration) {
+        if (declaration.packages_sha256 !== undefined && declaration.packages_sha256 !== packagesSha256) {
+            throw new Error(`Task-local package hash mismatch: expected ${String(declaration.packages_sha256)}, got ${packagesSha256}`);
+        }
+        if (declaration.packages !== undefined) {
+            const expected = this.stringMap(declaration.packages, 'environment_manifest.task_local.packages');
+            if ((0, canonical_json_1.sha256Canonical)(expected) !== (0, canonical_json_1.sha256Canonical)(packages)) {
+                throw new Error('Task-local package distribution map mismatch');
+            }
+        }
+    }
+    taskLocalDeclaration(environment, workspace) {
+        const taskLocal = this.optionalRecord(environment.task_local, 'environment_manifest.task_local');
+        if (!taskLocal || taskLocal.package_directory === null || taskLocal.package_directory === undefined)
+            return null;
+        const packageDirectory = this.nonempty(taskLocal.package_directory, 'environment_manifest.task_local.package_directory');
+        if (!path.isAbsolute(packageDirectory)) {
+            throw new ReplaySealValidationError('environment_manifest.task_local.package_directory must be absolute');
+        }
+        this.relativeInside(workspace, packageDirectory, 'task-local package_directory');
+        let stat;
+        try {
+            stat = (0, fs_1.lstatSync)(packageDirectory);
+        }
+        catch {
+            throw new ReplaySealValidationError('task-local package_directory must be an existing directory');
+        }
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new ReplaySealValidationError('task-local package_directory must be a real directory, not a symbolic link');
+        }
+        const realWorkspace = (0, fs_1.realpathSync)(workspace);
+        const realPackageDirectory = (0, fs_1.realpathSync)(packageDirectory);
+        this.relativeInside(realWorkspace, realPackageDirectory, 'task-local package_directory');
+        this.assertNoSymlinkComponentsSync(path.resolve(workspace), path.resolve(packageDirectory));
+        return {
+            packageDirectory,
+            canonicalPackageDirectory: realPackageDirectory,
+            declaration: taskLocal,
+        };
+    }
+    validateEnvironmentDeclaration(environment, workspace) {
+        this.taskLocalDeclaration(environment, workspace);
+    }
+    parseFrozenNotebook(bytes, requestedKernelName) {
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString('utf8'));
+        }
+        catch (error) {
+            throw new ReplaySealValidationError(`Notebook is not valid JSON: ${this.errorMessage(error)}`);
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new ReplaySealValidationError('Notebook must be a JSON object');
+        }
+        const notebook = parsed;
+        if (!Array.isArray(notebook.cells) || notebook.nbformat !== 4) {
+            throw new ReplaySealValidationError('Replay sealing requires a Jupyter nbformat 4 notebook');
+        }
+        if (!notebook.metadata || typeof notebook.metadata !== 'object' || Array.isArray(notebook.metadata)) {
+            throw new ReplaySealValidationError('Notebook metadata must be an object');
+        }
+        const seen = new Set();
+        const codeCells = [];
+        notebook.cells.forEach((cell, index) => {
+            if (!cell || typeof cell !== 'object' || Array.isArray(cell)) {
+                throw new ReplaySealValidationError(`Notebook cell ${index + 1} must be an object`);
+            }
+            if (typeof cell.id !== 'string' || !CELL_ID_RE.test(cell.id)) {
+                throw new ReplaySealValidationError(`Notebook cell ${index + 1} requires a canonical top-level Jupyter cell id`);
+            }
+            if (seen.has(cell.id)) {
+                throw new ReplaySealValidationError(`Notebook has duplicate cell id ${cell.id}`);
+            }
+            seen.add(cell.id);
+            if (cell.cell_type === 'code') {
+                const source = this.cellSource(cell.source, index);
+                const exploratoryOutputs = cell.outputs === undefined ? [] : cell.outputs;
+                if (!Array.isArray(exploratoryOutputs)) {
+                    throw new ReplaySealValidationError(`Notebook code cell ${index + 1} has invalid outputs`);
+                }
+                (0, canonical_json_1.canonicalJson)(exploratoryOutputs);
+                const exploratoryExecutionCount = cell.execution_count === null
+                    || cell.execution_count === undefined
+                    ? null
+                    : cell.execution_count;
+                if (exploratoryExecutionCount !== null
+                    && (!Number.isSafeInteger(exploratoryExecutionCount) || exploratoryExecutionCount < 0)) {
+                    throw new ReplaySealValidationError(`Notebook code cell ${index + 1} has invalid execution_count`);
+                }
+                codeCells.push({
+                    index,
+                    id: cell.id,
+                    source,
+                    exploratoryOutputsSha256: (0, canonical_json_1.sha256Canonical)(normalizeNotebookOutputsForComparison(exploratoryOutputs)),
+                    exploratoryExecutionCount: exploratoryExecutionCount,
+                });
+            }
+        });
+        if (codeCells.length === 0) {
+            throw new ReplaySealValidationError('Notebook must contain at least one code cell');
+        }
+        let kernelName = requestedKernelName;
+        if (!kernelName) {
+            const kernelspec = this.optionalRecord(notebook.metadata.kernelspec, 'notebook metadata.kernelspec');
+            kernelName = typeof kernelspec?.name === 'string' && kernelspec.name.trim()
+                ? kernelspec.name
+                : 'python3';
+        }
+        return { notebook: this.cloneJson(notebook), codeCells, kernelName };
+    }
+    normalizeRequest(raw) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new ReplaySealValidationError('Replay-seal request body must be an object');
+        }
+        const allowedKeys = new Set([
+            'notebook_path',
+            'run_id',
+            'task_id',
+            'source_id',
+            'source_notebook_sha256',
+            'artifacts',
+            'kernel_name',
+            'input_manifest',
+            'environment_manifest',
+        ]);
+        const unknownKeys = Object.keys(raw).filter((key) => !allowedKeys.has(key));
+        if (unknownKeys.length > 0) {
+            throw new ReplaySealValidationError(`Replay-seal request has unsupported field: ${unknownKeys[0]}`);
+        }
+        const notebookPath = this.nonempty(raw.notebook_path, 'notebook_path');
+        if (!path.isAbsolute(notebookPath) || path.extname(notebookPath).toLowerCase() !== '.ipynb') {
+            throw new ReplaySealValidationError('notebook_path must be an absolute .ipynb path');
+        }
+        if (path.normalize(notebookPath) !== notebookPath) {
+            throw new ReplaySealValidationError('notebook_path must be normalized without dot segments');
+        }
+        const sourceSha256 = this.nonempty(raw.source_notebook_sha256, 'source_notebook_sha256');
+        if (!SHA256_RE.test(sourceSha256)) {
+            throw new ReplaySealValidationError('source_notebook_sha256 must be a lowercase SHA-256 digest');
+        }
+        const artifactDescriptors = raw.artifacts;
+        if (!Array.isArray(artifactDescriptors)) {
+            throw new ReplaySealValidationError('artifacts must be an array');
+        }
+        const workspace = path.dirname(notebookPath);
+        const normalizedArtifacts = [];
+        for (const [index, value] of artifactDescriptors.entries()) {
+            if (!value || typeof value !== 'object' || Array.isArray(value)) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} must be an object`);
+            }
+            const descriptor = value;
+            const descriptorKeys = Object.keys(descriptor);
+            const unknownDescriptorKey = descriptorKeys.find((key) => key !== 'path' && key !== 'sha256' && key !== 'size_bytes');
+            if (unknownDescriptorKey) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} has unsupported field: ${unknownDescriptorKey}`);
+            }
+            const artifactPath = this.nonempty(descriptor.path, `artifacts item ${index + 1} path`);
+            if (!path.isAbsolute(artifactPath)) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} path must be absolute`);
+            }
+            if (path.normalize(artifactPath) !== artifactPath) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} path must be normalized without dot segments`);
+            }
+            const relative = this.relativeInside(workspace, artifactPath, `artifacts item ${index + 1} path`);
+            if (relative.split(path.sep)[0] === '.nebula') {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} must not be inside .nebula`);
+            }
+            if (artifactPath === notebookPath) {
+                throw new ReplaySealValidationError('artifacts must not repeat notebook_path');
+            }
+            if (normalizedArtifacts.some((artifact) => artifact.path === artifactPath)) {
+                throw new ReplaySealValidationError(`artifacts repeats ${artifactPath}`);
+            }
+            const sha256 = this.nonempty(descriptor.sha256, `artifacts item ${index + 1} sha256`);
+            if (!SHA256_RE.test(sha256)) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} sha256 must be a lowercase SHA-256 digest`);
+            }
+            const sizeBytes = descriptor.size_bytes;
+            if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 0) {
+                throw new ReplaySealValidationError(`artifacts item ${index + 1} size_bytes must be a non-negative safe integer`);
+            }
+            normalizedArtifacts.push({
+                path: path.normalize(artifactPath),
+                sha256,
+                size_bytes: sizeBytes,
+            });
+        }
+        let inputManifest;
+        let environmentManifest;
+        try {
+            inputManifest = this.plainRecord(raw.input_manifest, 'input_manifest');
+            environmentManifest = this.plainRecord(raw.environment_manifest, 'environment_manifest');
+        }
+        catch (error) {
+            if (error instanceof ReplaySealValidationError)
+                throw error;
+            throw new ReplaySealValidationError(this.errorMessage(error));
+        }
+        let kernelName;
+        if (raw.kernel_name !== undefined) {
+            kernelName = this.nonempty(raw.kernel_name, 'kernel_name');
+            if (kernelName.startsWith('env:') && !path.isAbsolute(kernelName.slice(4))) {
+                throw new ReplaySealValidationError('env: kernel_name must contain an absolute Python interpreter path');
+            }
+        }
+        const request = {
+            notebook_path: path.normalize(notebookPath),
+            run_id: this.nonempty(raw.run_id, 'run_id'),
+            task_id: this.nonempty(raw.task_id, 'task_id'),
+            source_id: this.nonempty(raw.source_id, 'source_id'),
+            source_notebook_sha256: sourceSha256,
+            artifacts: normalizedArtifacts,
+            input_manifest: inputManifest,
+            environment_manifest: environmentManifest,
+            ...(kernelName !== undefined ? { kernel_name: kernelName } : {}),
+        };
+        return this.cloneJson(request);
+    }
+    validateIdempotencyKey(value) {
+        if (typeof value !== 'string' || value.length === 0 || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value)) {
+            throw new ReplaySealValidationError('Idempotency-Key must be 1-512 characters without control characters');
+        }
+    }
+    responseFor(job) {
+        if (job.status === 'completed' && job.manifest) {
+            return { seal_id: job.sealId, status: 'completed', manifest: job.manifest };
+        }
+        if (job.status === 'failed') {
+            return { seal_id: job.sealId, status: 'failed', error: job.error || 'Replay seal failed' };
+        }
+        if (job.status === 'completed') {
+            throw new Error(`Completed replay seal ${job.sealId} has no manifest`);
+        }
+        return { seal_id: job.sealId, status: job.status };
+    }
+    async verifiedResponseFor(job) {
+        if (job.status !== 'completed')
+            return this.responseFor(job);
+        try {
+            const manifest = await this.verifyCompletedSeal(job);
+            return { seal_id: job.sealId, status: 'completed', manifest };
+        }
+        catch (error) {
+            return {
+                seal_id: job.sealId,
+                status: 'failed',
+                error: `Seal integrity verification failed: ${this.errorMessage(error)}`,
+            };
+        }
+    }
+    async verifyCompletedSeal(job) {
+        if (!job.manifest)
+            throw new Error('completed job has no manifest');
+        if (job.requestFingerprint !== (0, canonical_json_1.sha256Canonical)(job.request)) {
+            throw new Error('persisted request fingerprint mismatch');
+        }
+        const sealDirectory = await fsp.realpath(job.sealDirectory);
+        if (sealDirectory !== job.sealDirectory)
+            throw new Error('seal directory path is not canonical');
+        const expectedFrozenPath = path.join(sealDirectory, 'source.ipynb');
+        if (job.frozenNotebookPath !== expectedFrozenPath)
+            throw new Error('frozen notebook path mismatch');
+        const manifestPath = path.join(sealDirectory, 'manifest.json');
+        const manifestStat = await fsp.lstat(manifestPath);
+        if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) {
+            throw new Error('manifest is not a regular immutable file');
+        }
+        const manifestBytes = await fsp.readFile(manifestPath);
+        let parsed;
+        try {
+            parsed = JSON.parse(manifestBytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('manifest contains invalid JSON');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('manifest is not an object');
+        }
+        const manifest = parsed;
+        if (manifestBytes.toString('utf8') !== `${(0, canonical_json_1.canonicalJson)(manifest)}\n`) {
+            throw new Error('manifest is not canonical JSON');
+        }
+        const { manifest_sha256: claimedManifestSha256, ...unsignedManifest } = manifest;
+        if (!SHA256_RE.test(claimedManifestSha256) || (0, canonical_json_1.sha256Canonical)(unsignedManifest) !== claimedManifestSha256) {
+            throw new Error('manifest_sha256 mismatch');
+        }
+        if ((0, canonical_json_1.canonicalJson)(manifest) !== (0, canonical_json_1.canonicalJson)(job.manifest)) {
+            throw new Error('job state and immutable manifest disagree');
+        }
+        if (manifest.schema_version !== 1
+            || manifest.hash_profile !== canonical_json_1.CANONICAL_HASH_PROFILE
+            || manifest.seal_id !== job.sealId) {
+            throw new Error('manifest identity mismatch');
+        }
+        if (manifest.source_notebook.path !== job.request.notebook_path
+            || manifest.source_notebook.sha256 !== job.sourceNotebookSha256
+            || manifest.source_notebook.sha256 !== job.request.source_notebook_sha256) {
+            throw new Error('source notebook attestation mismatch');
+        }
+        const frozen = await this.hashRegularFile(expectedFrozenPath);
+        if (frozen.sha256 !== job.sourceNotebookSha256)
+            throw new Error('frozen source notebook hash mismatch');
+        const expectedNotebookPath = path.join(sealDirectory, 'notebook.ipynb');
+        if (manifest.notebook.path !== expectedNotebookPath)
+            throw new Error('sealed notebook path mismatch');
+        const notebook = await this.hashRegularFile(expectedNotebookPath);
+        if (notebook.sha256 !== manifest.notebook.sha256)
+            throw new Error('sealed notebook hash mismatch');
+        if (!Array.isArray(manifest.cells) || manifest.cells.length === 0) {
+            throw new Error('manifest contains no executed cells');
+        }
+        await this.verifyManifestCells(expectedFrozenPath, expectedNotebookPath, manifest.cells);
+        if ((0, canonical_json_1.sha256Canonical)(manifest.runtime_environment) !== manifest.runtime_environment_sha256) {
+            throw new Error('runtime environment hash mismatch');
+        }
+        if ((0, canonical_json_1.sha256Canonical)(job.request.input_manifest) !== manifest.input_manifest_sha256) {
+            throw new Error('input manifest hash mismatch');
+        }
+        if ((0, canonical_json_1.sha256Canonical)(job.request.environment_manifest) !== manifest.environment_manifest_sha256) {
+            throw new Error('environment manifest hash mismatch');
+        }
+        if (!(await this.provenanceStore.verifyBlob(job.request.notebook_path, manifest.input_manifest_sha256)).valid) {
+            throw new Error('input manifest blob verification failed');
+        }
+        if (!(await this.provenanceStore.verifyBlob(job.request.notebook_path, manifest.environment_manifest_sha256)).valid) {
+            throw new Error('environment manifest blob verification failed');
+        }
+        if (!(await this.provenanceStore.verifyBlob(job.request.notebook_path, manifest.runtime_environment_sha256)).valid) {
+            throw new Error('runtime environment blob verification failed');
+        }
+        const expectedArtifactSources = [
+            job.request.notebook_path,
+            ...job.request.artifacts.map((artifact) => artifact.path),
+        ];
+        if (!Array.isArray(manifest.artifacts) || manifest.artifacts.length !== expectedArtifactSources.length) {
+            throw new Error('artifact attestation count mismatch');
+        }
+        for (let index = 0; index < manifest.artifacts.length; index += 1) {
+            const artifact = manifest.artifacts[index];
+            if (artifact.source_path !== expectedArtifactSources[index]) {
+                throw new Error(`artifact ${index + 1} source path mismatch`);
+            }
+            const artifactRealPath = await fsp.realpath(artifact.path);
+            this.relativeInside(sealDirectory, artifactRealPath, `artifact ${index + 1} sealed path`);
+            const actual = await this.hashRegularFile(artifact.path);
+            if (actual.sha256 !== artifact.sha256 || actual.size_bytes !== artifact.size_bytes) {
+                throw new Error(`artifact ${index + 1} hash or size mismatch`);
+            }
+            const requested = job.request.artifacts[index - 1];
+            if (requested && (artifact.sha256 !== requested.sha256
+                || artifact.size_bytes !== requested.size_bytes)) {
+                throw new Error(`artifact ${index + 1} does not match its predeclared descriptor`);
+            }
+        }
+        if (manifest.artifacts[0].path !== manifest.notebook.path
+            || manifest.artifacts[0].sha256 !== manifest.notebook.sha256) {
+            throw new Error('notebook artifact does not match the sealed notebook');
+        }
+        const ledger = manifest.event_ledger;
+        if (ledger.path !== this.provenanceStore.getLedgerPath(job.request.notebook_path)
+            || ledger.head_sha256 !== manifest.event_chain_head_sha256
+            || ledger.prefix_size_bytes < 1
+            || !Number.isSafeInteger(ledger.head_seq)
+            || ledger.head_seq < 1) {
+            throw new Error('event ledger metadata mismatch');
+        }
+        const ledgerBytes = await fsp.readFile(ledger.path);
+        if (ledger.prefix_size_bytes > ledgerBytes.length)
+            throw new Error('event ledger prefix exceeds file');
+        const prefix = ledgerBytes.subarray(0, ledger.prefix_size_bytes);
+        if (prefix.at(-1) !== 0x0a || (0, canonical_json_1.sha256Hex)(prefix) !== ledger.prefix_sha256) {
+            throw new Error('event ledger prefix hash or boundary mismatch');
+        }
+        const head = this.verifyLedgerPrefix(prefix, job.request.notebook_path);
+        if (head.eventHash !== ledger.head_sha256
+            || head.seq !== ledger.head_seq
+            || head.type !== 'seal.completed') {
+            throw new Error('event ledger head mismatch');
+        }
+        const headPayload = this.plainRecord(head.payload, 'completed event payload');
+        if ((0, canonical_json_1.canonicalJson)(head.record.actor) !== (0, canonical_json_1.canonicalJson)({
+            kind: 'agent',
+            id: job.request.source_id,
+            name: 'kosmos',
+        })
+            || head.record.runId !== job.request.run_id
+            || head.record.taskId !== job.request.task_id
+            || head.record.sourceId !== job.request.source_id
+            || head.record.inputManifestSha256 !== manifest.input_manifest_sha256
+            || head.record.environmentManifestSha256 !== manifest.environment_manifest_sha256) {
+            throw new Error('completed event actor or request identity mismatch');
+        }
+        const expectedEventCells = manifest.cells.map((item) => ({
+            cellId: item.cell_id,
+            sourceSha256: item.source_sha256,
+            exploratoryOutputsSha256: item.exploratory_outputs_sha256,
+            outputsSha256: item.outputs_sha256,
+            replayComparisonOutputsSha256: item.replay_comparison_outputs_sha256,
+            outputsMatchExploratory: item.outputs_match_exploratory,
+            exploratoryExecutionCount: item.exploratory_execution_count,
+            executionId: item.execution_id,
+            executionCount: item.execution_count,
+            status: item.status,
+        }));
+        const expectedEventArtifacts = manifest.artifacts.map((item) => ({
+            sourcePath: item.source_path,
+            path: item.path,
+            sha256: item.sha256,
+            sizeBytes: item.size_bytes,
+        }));
+        if (headPayload.sealId !== job.sealId
+            || headPayload.hashProfile !== canonical_json_1.CANONICAL_HASH_PROFILE
+            || (0, canonical_json_1.canonicalJson)(headPayload.sourceNotebook) !== (0, canonical_json_1.canonicalJson)(manifest.source_notebook)
+            || (0, canonical_json_1.canonicalJson)(headPayload.notebook) !== (0, canonical_json_1.canonicalJson)(manifest.notebook)
+            || headPayload.inputManifestSha256 !== manifest.input_manifest_sha256
+            || headPayload.environmentManifestSha256 !== manifest.environment_manifest_sha256
+            || headPayload.runtimeEnvironmentSha256 !== manifest.runtime_environment_sha256
+            || (0, canonical_json_1.canonicalJson)(headPayload.cells) !== (0, canonical_json_1.canonicalJson)(expectedEventCells)
+            || (0, canonical_json_1.canonicalJson)(headPayload.artifacts) !== (0, canonical_json_1.canonicalJson)(expectedEventArtifacts)
+            || (0, canonical_json_1.canonicalJson)(headPayload.isolation) !== (0, canonical_json_1.canonicalJson)({
+                freshKernel: true,
+                networkIsolated: false,
+                filesystemIsolated: false,
+            })) {
+            throw new Error('completed event does not attest this seal');
+        }
+        return manifest;
+    }
+    verifyLedgerPrefix(prefix, notebookPath) {
+        const lines = prefix.toString('utf8').split('\n');
+        if (lines.at(-1) !== '')
+            throw new Error('ledger prefix lacks final newline');
+        lines.pop();
+        let previousHash = null;
+        let head;
+        for (let index = 0; index < lines.length; index += 1) {
+            const record = this.parseObject(lines[index], `ledger event ${index + 1}`);
+            const eventHash = record.eventHash;
+            if (typeof eventHash !== 'string' || !SHA256_RE.test(eventHash)) {
+                throw new Error(`ledger event ${index + 1} has an invalid hash`);
+            }
+            const { eventHash: _eventHash, ...unsigned } = record;
+            if ((0, canonical_json_1.sha256Canonical)(unsigned) !== eventHash
+                || record.seq !== index + 1
+                || record.prevHash !== previousHash
+                || record.notebookPath !== notebookPath) {
+                throw new Error(`ledger event ${index + 1} failed chain verification`);
+            }
+            if (typeof record.type !== 'string')
+                throw new Error(`ledger event ${index + 1} has no type`);
+            head = {
+                eventHash,
+                seq: index + 1,
+                type: record.type,
+                payload: record.payload,
+                record,
+            };
+            previousHash = eventHash;
+        }
+        if (!head)
+            throw new Error('ledger prefix contains no events');
+        return head;
+    }
+    async verifyManifestCells(sourceNotebookPath, sealedNotebookPath, cells) {
+        const readNotebook = async (filePath) => {
+            const raw = JSON.parse(await fsp.readFile(filePath, 'utf8'));
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Array.isArray(raw.cells)) {
+                throw new Error(`Invalid notebook JSON during seal verification: ${filePath}`);
+            }
+            return raw;
+        };
+        const source = await readNotebook(sourceNotebookPath);
+        const sealed = await readNotebook(sealedNotebookPath);
+        const sourceCodeCells = source.cells.filter((cell) => cell.cell_type === 'code');
+        const sealedCodeCells = sealed.cells.filter((cell) => cell.cell_type === 'code');
+        if (sourceCodeCells.length !== cells.length || sealedCodeCells.length !== cells.length) {
+            throw new Error('manifest executed-cell count does not match notebook code cells');
+        }
+        for (let index = 0; index < cells.length; index += 1) {
+            const record = cells[index];
+            const original = sourceCodeCells[index];
+            const replayed = sealedCodeCells[index];
+            const originalSource = this.cellSource(original.source, index);
+            const replayedSource = this.cellSource(replayed.source, index);
+            const originalOutputs = original.outputs ?? [];
+            const replayedOutputs = replayed.outputs ?? [];
+            if (!Array.isArray(originalOutputs) || !Array.isArray(replayedOutputs)) {
+                throw new Error(`Invalid notebook outputs for cell ${record.cell_id}`);
+            }
+            const exploratoryDigest = (0, canonical_json_1.sha256Canonical)(normalizeNotebookOutputsForComparison(originalOutputs));
+            const replayComparisonDigest = (0, canonical_json_1.sha256Canonical)(normalizeNotebookOutputsForComparison(replayedOutputs));
+            if (original.id !== record.cell_id
+                || replayed.id !== record.cell_id
+                || originalSource !== replayedSource
+                || (0, canonical_json_1.sha256Hex)(replayedSource) !== record.source_sha256
+                || (0, canonical_json_1.sha256Canonical)(replayedOutputs) !== record.outputs_sha256
+                || exploratoryDigest !== record.exploratory_outputs_sha256
+                || replayComparisonDigest !== record.replay_comparison_outputs_sha256
+                || record.outputs_match_exploratory !== (exploratoryDigest === replayComparisonDigest)
+                || (original.execution_count ?? null) !== record.exploratory_execution_count
+                || replayed.execution_count !== record.execution_count
+                || record.status !== 'completed') {
+                throw new Error(`manifest cell attestation mismatch for ${record.cell_id}`);
+            }
+        }
+    }
+    async hashRegularFile(filePath) {
+        let handle;
+        try {
+            handle = await fsp.open(filePath, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (this.isNodeError(error, 'ELOOP'))
+                throw new Error(`File is a symbolic link: ${filePath}`);
+            throw error;
+        }
+        try {
+            const before = await handle.stat();
+            if (!before.isFile())
+                throw new Error(`Not a regular file: ${filePath}`);
+            const hash = (0, crypto_1.createHash)('sha256');
+            const buffer = Buffer.allocUnsafe(1024 * 1024);
+            let sizeBytes = 0;
+            for (;;) {
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    break;
+                hash.update(buffer.subarray(0, bytesRead));
+                sizeBytes += bytesRead;
+            }
+            const after = await handle.stat();
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+                || before.mtimeMs !== after.mtimeMs || after.size !== sizeBytes) {
+                throw new Error(`File changed during verification: ${filePath}`);
+            }
+            return { sha256: hash.digest('hex'), size_bytes: sizeBytes };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    registryPath(sealId) {
+        return path.join(this.registryDirectory, `${sealId}.json`);
+    }
+    async ensureRegistryDirectory() {
+        await this.ensureSafeDirectoryChain(this.rootDirectory, ['.nebula', 'replay-seal-jobs']);
+    }
+    async createSafeSealDirectory(workspace, sealId) {
+        const sealsDirectory = await this.ensureSafeDirectoryChain(workspace, ['.nebula', 'seals']);
+        const sealDirectory = path.join(sealsDirectory, sealId);
+        try {
+            await fsp.mkdir(sealDirectory, { mode: 0o700 });
+            if (this.durable)
+                await this.syncDirectory(sealsDirectory);
+        }
+        catch (error) {
+            if (!this.isNodeError(error, 'EEXIST'))
+                throw error;
+            const stat = await fsp.lstat(sealDirectory);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new ReplaySealValidationError('Seal path is not a real directory');
+            }
+            // An indexed job is handled before this method. An unindexed directory
+            // is ambiguous crash/attacker state and must never be adopted silently.
+            throw new ReplaySealValidationError(`Seal directory already exists without authoritative job state: ${sealDirectory}`);
+        }
+        return await fsp.realpath(sealDirectory);
+    }
+    async ensureSafeDirectoryChain(base, components) {
+        let current = await fsp.realpath(base);
+        const baseStat = await fsp.lstat(current);
+        if (!baseStat.isDirectory())
+            throw new Error(`Directory root is not a directory: ${base}`);
+        for (const component of components) {
+            if (!component || component === '.' || component === '..' || component.includes(path.sep)) {
+                throw new Error(`Unsafe directory component: ${component}`);
+            }
+            const candidate = path.join(current, component);
+            try {
+                await fsp.mkdir(candidate, { mode: 0o700 });
+                if (this.durable)
+                    await this.syncDirectory(current);
+            }
+            catch (error) {
+                if (!this.isNodeError(error, 'EEXIST'))
+                    throw error;
+            }
+            const stat = await fsp.lstat(candidate);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new ReplaySealValidationError(`Refusing unsafe directory in seal path: ${candidate}`);
+            }
+            const realCandidate = await fsp.realpath(candidate);
+            if (path.dirname(realCandidate) !== current) {
+                throw new ReplaySealValidationError(`Seal directory escapes its parent: ${candidate}`);
+            }
+            current = realCandidate;
+        }
+        return current;
+    }
+    async hardenSealDirectory(directory) {
+        const visit = async (current) => {
+            const stat = await fsp.lstat(current);
+            if (stat.isSymbolicLink())
+                throw new Error(`Seal contains a symbolic link: ${current}`);
+            if (!stat.isDirectory()) {
+                if (!stat.isFile())
+                    throw new Error(`Seal contains a non-regular entry: ${current}`);
+                await fsp.chmod(current, 0o400);
+                return;
+            }
+            const entries = await fsp.readdir(current);
+            for (const entry of entries)
+                await visit(path.join(current, entry));
+            await fsp.chmod(current, 0o500);
+        };
+        await visit(directory);
+    }
+    sealRequestEventKey(sealId) {
+        return `replay-seal:${sealId}`;
+    }
+    async persistJob(job) {
+        await Promise.all([
+            this.writeJsonAtomic(this.registryPath(job.sealId), job),
+            this.writeJsonAtomic(path.join(job.sealDirectory, 'job.json'), job),
+        ]);
+    }
+    async updateJob(job, patch) {
+        const updated = {
+            ...job,
+            ...patch,
+            updatedAt: this.clock().toISOString(),
+        };
+        if (patch.manifest === undefined)
+            delete updated.manifest;
+        if (patch.error === undefined)
+            delete updated.error;
+        await this.persistJob(updated);
+        return updated;
+    }
+    async readJob(filePath) {
+        let raw;
+        try {
+            const stat = await fsp.lstat(filePath);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new Error(`Replay-seal job state must be a regular file: ${filePath}`);
+            }
+            raw = await fsp.readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            if (this.isNodeError(error, 'ENOENT'))
+                return null;
+            throw error;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || parsed.schemaVersion !== 1 || !SEAL_ID_RE.test(parsed.sealId)) {
+            throw new Error(`Invalid replay-seal job state: ${filePath}`);
+        }
+        return parsed;
+    }
+    async writeJsonAtomic(filePath, value) {
+        const directory = path.dirname(filePath);
+        const temporary = `${filePath}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`;
+        const handle = await fsp.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${(0, canonical_json_1.canonicalJson)(value)}\n`, 'utf8');
+            if (this.durable)
+                await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fsp.rename(temporary, filePath);
+    }
+    async writeImmutable(filePath, bytes) {
+        const directory = path.dirname(filePath);
+        const temporary = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${(0, crypto_1.randomUUID)()}.tmp`);
+        try {
+            const handle = await fsp.open(temporary, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_NOFOLLOW, 0o400);
+            try {
+                await handle.writeFile(bytes);
+                if (this.durable)
+                    await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            try {
+                await fsp.link(temporary, filePath);
+            }
+            catch (error) {
+                if (!this.isNodeError(error, 'EEXIST'))
+                    throw error;
+                const stat = await fsp.lstat(filePath);
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    throw new Error(`Immutable seal target is not a regular file: ${filePath}`);
+                }
+                const existing = await fsp.readFile(filePath);
+                if (!existing.equals(bytes)) {
+                    throw new Error(`Immutable seal file already exists with different content: ${filePath}`);
+                }
+            }
+            await fsp.chmod(filePath, 0o400);
+            if (this.durable)
+                await this.syncDirectory(directory);
+        }
+        finally {
+            await fsp.unlink(temporary).catch(() => undefined);
+        }
+    }
+    async readNotebookSource(notebookPath) {
+        let lexicalStat;
+        try {
+            lexicalStat = await fsp.lstat(notebookPath);
+        }
+        catch (error) {
+            if (this.isNodeError(error, 'ENOENT'))
+                throw new ReplaySealValidationError(`Notebook not found: ${notebookPath}`);
+            throw error;
+        }
+        if (lexicalStat.isSymbolicLink() || !lexicalStat.isFile()) {
+            throw new ReplaySealValidationError('notebook_path must be a regular file, not a symbolic link');
+        }
+        const rootRealPath = await fsp.realpath(this.rootDirectory);
+        const notebookRealPath = await fsp.realpath(notebookPath);
+        this.relativeInside(rootRealPath, notebookRealPath, 'notebook_path');
+        await this.assertNoSymlinkComponents(path.resolve(this.rootDirectory), path.resolve(notebookPath));
+        let handle;
+        try {
+            handle = await fsp.open(notebookPath, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+        }
+        catch (error) {
+            if (this.isNodeError(error, 'ELOOP')) {
+                throw new ReplaySealValidationError('notebook_path became a symbolic link during preflight');
+            }
+            throw error;
+        }
+        try {
+            const before = await handle.stat();
+            if (!before.isFile()
+                || before.dev !== lexicalStat.dev
+                || before.ino !== lexicalStat.ino) {
+                throw new ReplaySealValidationError('notebook_path changed during preflight');
+            }
+            const bytes = await handle.readFile();
+            const after = await handle.stat();
+            if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+                || before.mtimeMs !== after.mtimeMs || bytes.length !== after.size) {
+                throw new ReplaySealValidationError('notebook_path changed while it was frozen');
+            }
+            return bytes;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async captureLedgerPrefix(notebookPath, headHash, headSeq) {
+        const ledgerPath = this.provenanceStore.getLedgerPath(notebookPath);
+        const bytes = await fsp.readFile(ledgerPath);
+        let offset = 0;
+        let foundEnd = -1;
+        while (offset < bytes.length) {
+            const newline = bytes.indexOf(0x0a, offset);
+            if (newline < 0)
+                throw new Error('Provenance ledger does not end on an event boundary');
+            const line = bytes.subarray(offset, newline).toString('utf8');
+            const event = JSON.parse(line);
+            if (event.eventHash === headHash && event.seq === headSeq) {
+                foundEnd = newline + 1;
+                break;
+            }
+            offset = newline + 1;
+        }
+        if (foundEnd < 0)
+            throw new Error('Completed seal event is missing from provenance ledger');
+        const prefix = bytes.subarray(0, foundEnd);
+        return {
+            path: ledgerPath,
+            prefix_size_bytes: prefix.length,
+            prefix_sha256: (0, canonical_json_1.sha256Hex)(prefix),
+            head_sha256: headHash,
+            head_seq: headSeq,
+        };
+    }
+    toJupyterOutput(output) {
+        switch (output.type) {
+            case 'stdout':
+            case 'stderr':
+                return { output_type: 'stream', name: output.type, text: output.content };
+            case 'error':
+                return {
+                    output_type: 'error',
+                    ename: 'Error',
+                    evalue: output.content,
+                    traceback: output.content.split('\n'),
+                };
+            case 'image':
+                return { output_type: 'display_data', data: { 'image/png': output.content }, metadata: output.metadata ?? {} };
+            case 'html':
+                return { output_type: 'display_data', data: { 'text/html': output.content }, metadata: output.metadata ?? {} };
+            case 'display_data':
+                if (output.jupyterOutputType === 'execute_result') {
+                    return {
+                        output_type: 'execute_result',
+                        data: output.mimeBundle ?? { 'text/plain': output.content },
+                        metadata: output.metadata ?? {},
+                        execution_count: output.jupyterExecutionCount ?? null,
+                    };
+                }
+                return {
+                    output_type: 'display_data',
+                    data: output.mimeBundle ?? { 'text/plain': output.content },
+                    metadata: output.metadata ?? {},
+                };
+        }
+    }
+    markerPayload(stdout, context) {
+        const begin = stdout.lastIndexOf(PROBE_BEGIN);
+        const end = stdout.indexOf(PROBE_END, begin + PROBE_BEGIN.length);
+        if (begin < 0 || end < 0)
+            throw new Error(`Fresh kernel ${context} returned no attestation payload`);
+        return stdout.slice(begin + PROBE_BEGIN.length, end);
+    }
+    parseObject(raw, context) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Fresh kernel ${context} returned invalid JSON`);
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`Fresh kernel ${context} returned a non-object payload`);
+        }
+        return parsed;
+    }
+    stringMap(value, context) {
+        const record = this.plainRecord(value, context);
+        const result = {};
+        for (const key of Object.keys(record).sort()) {
+            if (typeof record[key] !== 'string')
+                throw new Error(`${context} values must be strings`);
+            result[key] = record[key];
+        }
+        return result;
+    }
+    plainRecord(value, name) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new ReplaySealValidationError(`${name} must be an object`);
+        }
+        (0, canonical_json_1.canonicalJson)(value);
+        return this.cloneJson(value);
+    }
+    optionalRecord(value, name) {
+        if (value === undefined || value === null)
+            return null;
+        return this.plainRecord(value, name);
+    }
+    nonempty(value, name) {
+        if (typeof value !== 'string' || value.trim().length === 0 || /\u0000/.test(value)) {
+            throw new ReplaySealValidationError(`${name} must be non-empty text`);
+        }
+        return value;
+    }
+    cellSource(value, index) {
+        if (typeof value === 'string')
+            return value;
+        if (Array.isArray(value) && value.every((item) => typeof item === 'string'))
+            return value.join('');
+        throw new ReplaySealValidationError(`Notebook code cell ${index + 1} has invalid source`);
+    }
+    relativeInside(root, target, name) {
+        const relative = path.relative(path.resolve(root), path.resolve(target));
+        if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new ReplaySealValidationError(`${name} must be a distinct path inside the notebook workspace`);
+        }
+        return relative;
+    }
+    async assertNoSymlinkComponents(root, target) {
+        const relative = this.relativeInside(root, target, 'artifact path');
+        let current = path.resolve(root);
+        for (const component of relative.split(path.sep)) {
+            current = path.join(current, component);
+            let stat;
+            try {
+                stat = await fsp.lstat(current);
+            }
+            catch (error) {
+                if (this.isNodeError(error, 'ENOENT'))
+                    throw new Error(`Requested artifact is missing: ${target}`);
+                throw error;
+            }
+            if (stat.isSymbolicLink())
+                throw new Error(`Requested artifact path contains a symbolic link: ${target}`);
+        }
+        const real = await fsp.realpath(target);
+        const realRoot = await fsp.realpath(root);
+        this.relativeInside(realRoot, real, 'resolved artifact path');
+    }
+    assertNoSymlinkComponentsSync(root, target) {
+        const relative = this.relativeInside(root, target, 'path');
+        let current = path.resolve(root);
+        for (const component of relative.split(path.sep)) {
+            current = path.join(current, component);
+            let stat;
+            try {
+                stat = (0, fs_1.lstatSync)(current);
+            }
+            catch {
+                throw new ReplaySealValidationError(`Path component does not exist: ${current}`);
+            }
+            if (stat.isSymbolicLink()) {
+                throw new ReplaySealValidationError(`Path contains a symbolic link: ${current}`);
+            }
+        }
+    }
+    async syncDirectory(directory) {
+        try {
+            const handle = await fsp.open(directory, 'r');
+            try {
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch {
+            // Some filesystems do not support directory fsync. File data remains
+            // fsynced and create/rename operations still retain atomicity.
+        }
+    }
+    cloneJson(value) {
+        return JSON.parse((0, canonical_json_1.canonicalJson)(value));
+    }
+    errorMessage(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    isNodeError(error, code) {
+        return !!error && typeof error === 'object' && error.code === code;
+    }
+    runSerialized(key, task) {
+        const previous = ReplaySealService.queues.get(key) ?? Promise.resolve();
+        const result = previous.catch(() => undefined).then(task);
+        const settled = result.then(() => undefined, () => undefined);
+        ReplaySealService.queues.set(key, settled);
+        settled.finally(() => {
+            if (ReplaySealService.queues.get(key) === settled)
+                ReplaySealService.queues.delete(key);
+        });
+        return result;
+    }
+}
+exports.ReplaySealService = ReplaySealService;