@devicerail/recorder 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 DeviceRail contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,111 @@
+# `@devicerail/recorder`
+
+`@devicerail/recorder` records the public DeviceRail Session event stream into
+a durable, resumable checkpoint. It orders exclusively by `TestEvent.sequence`,
+preserves event and Action correlation, and stores typed Evidence references
+rather than screenshot or video bytes.
+
+The package sits above `@devicerail/client` and `@devicerail/protocol`. It has
+no Driver, ADB, AI SDK, prompt, YAML, visualizer, or product UI dependency.
+
+## Completion boundary
+
+A checkpoint is an internal recovery artifact, not a second archive format and
+not proof that recording completed. Completion requires an ended Session, an
+exact `session.export` match, and successful export and independent validation
+through the local Rust `devicerail-bundle` CLI. The CLI remains the sole Session
+Bundle writer and validator; this package does not reimplement its manifest or
+Evidence integrity rules.
+
+The daemon must be stopped before Bundle export so the CLI can acquire the
+filesystem Evidence Store's exclusive lock. Until export atomically publishes
+the Bundle, callers must not clear the Session or its Evidence and must not
+restart the daemon: startup reconciliation may release the stopped process's
+orphaned Evidence pins. Once export succeeds, independent validation reads only
+the Bundle and may run after a daemon restart. Retain the checkpoint until that
+validation succeeds.
+
+The intended lifecycle is `ExecutionRecorder.open` → `captureOnce` or
+`captureUntilSealed` → `publishSource` → close the client/daemon → `finalize`.
+`ExecutionRecorder.openOffline` resumes a sealed or completed checkpoint after
+shutdown without pretending an active in-memory daemon Session can be restored.
+Finalization takes an explicit absolute path to the `devicerail-bundle` binary
+and invokes it with fixed arguments and `shell: false`; package import never
+probes for or starts that binary.
+
+## Recovery limits
+
+Duplicate delivery is idempotent only when the complete event value matches.
+Sequence gaps, out-of-order events, cross-Session events, lifecycle violations,
+and incomplete Action pairs fail explicitly. Cancellation may retain a durable
+checkpoint but never publishes a completed recording.
+
+Protocol 1.4 media start/frame/end events are checkpointed as typed Evidence
+references. Stream IDs remain lifetime-unique for the whole Session, including
+after a stream has ended; reuse fails before a checkpoint can advance.
+
+The current `events.list` and `session.export` RPC methods do not accept
+request-control options. Recorder cancellation is therefore observed before
+and after each call and during polling/checkpoint/CLI work; interrupting a
+stuck stdio call requires the host to close the client connection.
+
+The current stdio transport limits each `events.list` and `session.export`
+response to 1 MiB. Recorder starts at 1000 events per page and, on the typed
+`response_frame_too_large` failure, halves that limit until the page fits. The
+successful smaller limit is reused for later pages; if one event still cannot
+fit, recording fails explicitly as `event_too_large`. Recorder advances
+`afterSequence` and durably commits each accepted event page before requesting
+the next, so a missed suffix does not need to fit in one response.
+
+When `session.export.page.v1` was negotiated and the configured event source
+implements `exportSessionPage`, sealing applies the same bounded retry policy to
+the authoritative export. Every page must repeat one stable ended `SessionInfo`
+and must exactly match the corresponding durable checkpoint events. Reading
+pages never advances the checkpoint; only the fully verified export performs
+the single `recording` to `sealed` revision CAS. Without that negotiated
+capability Recorder retains the legacy complete `session.export` behavior.
+Concurrent seal callers share one in-flight verification and successful CAS,
+but keep independent cancellation: an aborted waiter returns immediately
+without cancelling the owner, while a non-cancelled waiter may retry after an
+owner cancellation leaves the checkpoint recording.
+Concurrent seal attempts on one Recorder share a successful verification and
+CAS, while each caller retains independent cancellation: aborting a waiter does
+not cancel the owner, and a non-cancelled waiter retries after a cancelled
+owner operation.
+
+Pagination removes the RPC single-frame bottleneck; it does not remove the
+local snapshot limit. The complete Bundle Source must still fit its explicit
+8 MiB bound, below the Session Bundle's default 16 MiB manifest budget. The
+checkpoint permits a separate fixed 64 KiB envelope/phase headroom so a valid
+near-limit Source can advance through sealed and completed without losing room
+for its checksum and receipt metadata. Sessions whose Source exceeds 8 MiB
+require a future segmented checkpoint and streaming Bundle Source contract. The
+current daemon also uses a process-local Event Store, so recovery of an active
+Session requires the same daemon and connection to remain alive. A sealed,
+terminal checkpoint can be finalized offline before restarting the daemon.
+
+Recording pages are persisted in an explicitly versioned, checksummed sidecar
+journal. Each commit appends only the accepted page and atomically advances a
+small journal head, so `P` fixed-size pages write `O(N + P)` bytes instead of
+rewriting `P` growing prefixes. A checksum chain binds every committed page;
+bytes written before a head publication are ignored and truncated on the next
+append. Recovery validates the complete chain once, and the `recording` to
+`sealed` transition compacts it into one canonical checkpoint snapshot. The
+8 MiB Source and checkpoint bounds, per-page fsync, revision CAS, owner-only
+metadata checks, and fail-closed corruption behavior remain unchanged.
+
+The in-memory `EventLog` follows the same boundary: batch preparation validates
+against overlay indexes without copying the confirmed prefix, and the prefix is
+materialized only when a snapshot is requested or sealing begins. Public
+speculative `fork()` calls still copy identity indexes to preserve independent
+branch mutation and are not used by Recorder page capture.
+
+On Unix, checkpoint and Source files must be owned by the current user with no
+group/world permission bits, and directory fsync closes the normal power-loss
+window. Node.js exposes neither portable Windows owner-only ACL verification
+nor directory fsync. Recorder therefore does not claim or enforce owner-only
+access on Windows; deployments must provide a suitably ACL-restricted parent
+directory. It still checks regular-file identity and retains file flush plus
+atomic replace/no-clobber semantics, with final directory durability left to
+the filesystem. Stale writer locks are reclaimed only when the OS confirms
+their PID no longer exists; ambiguous or reused PIDs fail closed.

package/dist/bundle-cli.d.ts

@@ -0,0 +1,13 @@
+import { type BundleSourceFile } from "./source-file.js";
+import type { RecorderBundleReceipt } from "./types.js";
+export type BundleSource = BundleSourceFile;
+export interface BundleFinalizeOptions {
+    readonly executable: string;
+    readonly sourcePath: string;
+    readonly evidenceDirectory: string;
+    readonly outputDirectory: string;
+    readonly source: BundleSource;
+    readonly signal?: AbortSignal;
+}
+/** Runs the existing Rust Bundle writer and validator without a shell. */
+export declare function exportAndValidateBundle(options: BundleFinalizeOptions): Promise<RecorderBundleReceipt>;

package/dist/bundle-cli.js

@@ -0,0 +1,311 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { dirname, isAbsolute, join } from "node:path";
+import { RecorderError } from "./errors.js";
+import { validateBundleSourceFile, } from "./source-file.js";
+const COMMAND_OUTPUT_MAX_BYTES = 64 * 1024;
+const MANIFEST_MAX_BYTES = 16 * 1024 * 1024;
+function cancelled() {
+    throw new RecorderError("operation_cancelled", "Recorder operation was cancelled");
+}
+function appendBounded(chunks, chunk, total) {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    total.value += bytes.length;
+    if (total.value > COMMAND_OUTPUT_MAX_BYTES) {
+        return false;
+    }
+    chunks.push(bytes);
+    return true;
+}
+async function runCommand(executable, arguments_, signal) {
+    if (signal?.aborted) {
+        cancelled();
+    }
+    if (typeof executable !== "string" || !isAbsolute(executable)) {
+        throw new RecorderError("bundle_cli_failed", "Bundle CLI executable must be an absolute path");
+    }
+    return await new Promise((resolve, reject) => {
+        const child = spawn(executable, [...arguments_], {
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        const stdoutBytes = { value: 0 };
+        const stderrBytes = { value: 0 };
+        let overflow = false;
+        let aborted = false;
+        let spawnError;
+        let forceKillTimer;
+        const terminate = () => {
+            child.kill(process.platform === "win32" ? undefined : "SIGINT");
+            forceKillTimer ??= setTimeout(() => child.kill("SIGKILL"), 2_000);
+            forceKillTimer.unref();
+        };
+        const abortListener = () => {
+            aborted = true;
+            terminate();
+        };
+        signal?.addEventListener("abort", abortListener, { once: true });
+        child.stdout.on("data", (chunk) => {
+            if (!appendBounded(stdout, chunk, stdoutBytes)) {
+                overflow = true;
+                terminate();
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (!appendBounded(stderr, chunk, stderrBytes)) {
+                overflow = true;
+                terminate();
+            }
+        });
+        child.once("error", (error) => {
+            spawnError = error;
+        });
+        child.once("close", (code) => {
+            if (forceKillTimer) {
+                clearTimeout(forceKillTimer);
+            }
+            signal?.removeEventListener("abort", abortListener);
+            if (aborted || signal?.aborted) {
+                reject(new RecorderError("operation_cancelled", "Bundle CLI operation was cancelled"));
+                return;
+            }
+            if (overflow) {
+                reject(new RecorderError("bundle_cli_failed", "Bundle CLI output exceeded the bounded diagnostic limit"));
+                return;
+            }
+            if (spawnError) {
+                reject(new RecorderError("bundle_cli_failed", "Bundle CLI could not be started", {
+                    cause: spawnError,
+                }));
+                return;
+            }
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdout),
+                stderr: Buffer.concat(stderr),
+            });
+        });
+    });
+}
+function parseSummary(bytes, operation) {
+    let value;
+    try {
+        const text = bytes.toString("utf8");
+        if (!text.endsWith("\n") || text.indexOf("\n") !== text.length - 1) {
+            throw new Error("summary must be exactly one newline-terminated JSON value");
+        }
+        value = JSON.parse(text.slice(0, -1));
+    }
+    catch (cause) {
+        throw new RecorderError("bundle_summary_invalid", "Bundle CLI returned invalid JSON", {
+            cause,
+        });
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new RecorderError("bundle_summary_invalid", "Bundle CLI summary must be an object");
+    }
+    const summary = value;
+    const keys = Object.keys(summary).sort();
+    const expectedKeys = [
+        "assetBytes",
+        "assetCount",
+        "eventCount",
+        "ok",
+        "operation",
+        "sessionId",
+    ];
+    if (!isDeepStrictEqual(keys, expectedKeys)) {
+        throw new RecorderError("bundle_summary_invalid", "Bundle CLI summary fields are invalid");
+    }
+    if (summary.ok !== true || summary.operation !== operation) {
+        throw new RecorderError("bundle_summary_invalid", "Bundle CLI summary operation is invalid");
+    }
+    if (typeof summary.sessionId !== "string" || summary.sessionId.length === 0) {
+        throw new RecorderError("bundle_summary_invalid", "Bundle CLI sessionId is invalid");
+    }
+    for (const field of ["eventCount", "assetCount", "assetBytes"]) {
+        if (!Number.isSafeInteger(summary[field]) ||
+            Object.is(summary[field], -0) ||
+            summary[field] < 0) {
+            throw new RecorderError("bundle_summary_invalid", `Bundle CLI ${field} must be a non-negative safe integer`);
+        }
+    }
+    return summary;
+}
+async function executeCli(executable, arguments_, operation, signal) {
+    const result = await runCommand(executable, arguments_, signal);
+    if (result.exitCode !== 0) {
+        const diagnostic = result.stderr.toString("utf8").trim();
+        throw new RecorderError("bundle_cli_failed", `Bundle CLI ${operation} failed`, {
+            details: {
+                exitCode: result.exitCode,
+                ...(diagnostic ? { diagnostic } : {}),
+            },
+        });
+    }
+    return parseSummary(result.stdout, operation);
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
+            return false;
+        }
+        throw new RecorderError("bundle_cli_failed", "Bundle output metadata is inaccessible", {
+            cause,
+        });
+    }
+}
+function expectedReceipt(source) {
+    return {
+        sessionId: source.sessionExport.session.id,
+        eventCount: source.sessionExport.events.length,
+    };
+}
+function verifySummary(summary, source) {
+    const expected = expectedReceipt(source);
+    if (summary.sessionId !== expected.sessionId || summary.eventCount !== expected.eventCount) {
+        throw new RecorderError("bundle_summary_mismatch", "Bundle CLI summary does not identify the sealed recording", { details: { expected, actual: summary } });
+    }
+}
+async function verifyManifestIdentity(outputDirectory, source) {
+    let bytes;
+    try {
+        const path = join(outputDirectory, "manifest.json");
+        const pathMetadata = await lstat(path);
+        if (!pathMetadata.isFile() ||
+            pathMetadata.isSymbolicLink() ||
+            pathMetadata.size > MANIFEST_MAX_BYTES) {
+            throw new Error("manifest is not a bounded regular file");
+        }
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const opened = await handle.stat();
+            if (!opened.isFile() ||
+                opened.dev !== pathMetadata.dev ||
+                opened.ino !== pathMetadata.ino) {
+                throw new Error("manifest changed while it was opened");
+            }
+            const buffer = Buffer.allocUnsafe(MANIFEST_MAX_BYTES + 1);
+            let offset = 0;
+            while (offset < buffer.length) {
+                const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+                if (bytesRead === 0) {
+                    break;
+                }
+                offset += bytesRead;
+            }
+            if (offset > MANIFEST_MAX_BYTES) {
+                throw new Error("manifest exceeds its bounded read limit");
+            }
+            bytes = buffer.subarray(0, offset);
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    catch (cause) {
+        throw new RecorderError("bundle_summary_mismatch", "Validated Bundle manifest is unreadable", {
+            cause,
+        });
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(bytes.toString("utf8"));
+    }
+    catch (cause) {
+        throw new RecorderError("bundle_summary_mismatch", "Validated Bundle manifest is invalid", {
+            cause,
+        });
+    }
+    if (manifest === null || typeof manifest !== "object" || Array.isArray(manifest)) {
+        throw new RecorderError("bundle_summary_mismatch", "Validated Bundle manifest is invalid");
+    }
+    const record = manifest;
+    if (!isDeepStrictEqual(record.eventProtocolVersion, source.eventProtocolVersion) ||
+        !isDeepStrictEqual(record.session, source.sessionExport.session) ||
+        !isDeepStrictEqual(record.events, source.sessionExport.events)) {
+        throw new RecorderError("bundle_summary_mismatch", "Validated Bundle content does not match the sealed recording");
+    }
+}
+async function syncOutputParent(outputDirectory) {
+    // Rust publication uses MoveFileExW(MOVEFILE_WRITE_THROUGH) on Windows.
+    // On Unix this closes the durability-unknown recovery case before the
+    // Recorder marks a previously published target complete.
+    if (process.platform === "win32") {
+        return;
+    }
+    try {
+        const handle = await open(dirname(outputDirectory), "r");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
+    catch (cause) {
+        throw new RecorderError("bundle_cli_failed", "validated Bundle parent-directory durability could not be confirmed", { cause });
+    }
+}
+/** Runs the existing Rust Bundle writer and validator without a shell. */
+export async function exportAndValidateBundle(options) {
+    // The generated DTO types contain serde-default optionals that are wider
+    // than the daemon's canonical output. Reject that lossy shape before the
+    // Rust CLI can publish a target that would compare differently afterward.
+    const source = validateBundleSourceFile(options.source);
+    let exportSummary;
+    if (!(await pathExists(options.outputDirectory))) {
+        try {
+            exportSummary = await executeCli(options.executable, [
+                "export",
+                "--source",
+                options.sourcePath,
+                "--evidence-dir",
+                options.evidenceDirectory,
+                "--output",
+                options.outputDirectory,
+            ], "export", options.signal);
+            verifySummary(exportSummary, source);
+        }
+        catch (error) {
+            // Publication is the Rust writer's linearization point. If it raced the
+            // process failure, converge through the independent validator below.
+            if (!(await pathExists(options.outputDirectory))) {
+                throw error;
+            }
+        }
+    }
+    const validateSummary = await executeCli(options.executable, ["validate", options.outputDirectory], "validate", options.signal);
+    verifySummary(validateSummary, source);
+    if (exportSummary &&
+        !isDeepStrictEqual({
+            sessionId: exportSummary.sessionId,
+            eventCount: exportSummary.eventCount,
+            assetCount: exportSummary.assetCount,
+            assetBytes: exportSummary.assetBytes,
+        }, {
+            sessionId: validateSummary.sessionId,
+            eventCount: validateSummary.eventCount,
+            assetCount: validateSummary.assetCount,
+            assetBytes: validateSummary.assetBytes,
+        })) {
+        throw new RecorderError("bundle_summary_mismatch", "Bundle export and validation summaries disagree");
+    }
+    await verifyManifestIdentity(options.outputDirectory, source);
+    await syncOutputParent(options.outputDirectory);
+    return {
+        sessionId: validateSummary.sessionId,
+        eventCount: validateSummary.eventCount,
+        assetCount: validateSummary.assetCount,
+        assetBytes: validateSummary.assetBytes,
+    };
+}

package/dist/canonical.d.ts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_CANONICAL_JSON_MAX_BYTES: number;
+export interface CanonicalJsonOptions {
+    readonly maxBytes?: number;
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+}
+export declare class CanonicalJsonError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Encode one value as compact recursively key-sorted UTF-8 JSON plus one LF. */
+export declare function toCanonicalJson(value: unknown, options?: CanonicalJsonOptions): Buffer;
+/**
+ * Encode `{ checkpoint, sha256 }` while visiting the checkpoint value once.
+ * The checksum covers the checkpoint's standalone canonical bytes, including
+ * its LF, while depth/node limits still apply to the complete envelope.
+ */
+export declare function toCanonicalJsonChecksumEnvelope(checkpoint: unknown, options?: CanonicalJsonOptions): Buffer;
+/** Parse JSON only when its bytes are already in the canonical representation. */
+export declare function fromCanonicalJson(bytes: Uint8Array, options?: CanonicalJsonOptions): unknown;
+export declare function sha256Hex(bytes: Uint8Array): string;
+export declare function canonicalSha256(value: unknown, options?: CanonicalJsonOptions): string;
+export declare function sha256Matches(actualBytes: Uint8Array, expectedHex: string): boolean;