@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.4

package/dist/cjs/internal/WindowsProcessJob.js

@@ -0,0 +1,113 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var WindowsProcessJob_exports = {};
+__export(WindowsProcessJob_exports, {
+  WindowsProcessJob: () => WindowsProcessJob,
+  resolveJobExecutable: () => resolveJobExecutable
+});
+module.exports = __toCommonJS(WindowsProcessJob_exports);
+var import_node_child_process = require("node:child_process");
+var import_node_path = require("node:path");
+var import_AtomicFileSystemExecutable = require("./AtomicFileSystemExecutable.js");
+var import_ProcessFault = require("./ProcessFault.js");
+const deferred = () => {
+  let resolve;
+  let reject;
+  const promise = new Promise((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  void promise.catch(() => {
+  });
+  return { promise, resolve, reject };
+};
+const resolveJobExecutable = () => {
+  const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY;
+  return configured === void 0 ? (0, import_AtomicFileSystemExecutable.resolveDefaultExecutable)(import_AtomicFileSystemExecutable.packageRoot, void 0) : (0, import_AtomicFileSystemExecutable.resolveConfiguredExecutable)(configured, void 0);
+};
+class WindowsProcessJob {
+  ready = deferred();
+  settled = deferred();
+  child;
+  receivedReady = false;
+  receivedSettled = false;
+  failed = false;
+  constructor(ownerPid, created, executable) {
+    if (typeof created !== "string" || !/^[1-9][0-9]{0,19}$/.test(created)) {
+      throw (0, import_ProcessFault.processFault)("owner_identity_missing", "Windows process owner has no exact creation identity");
+    }
+    const options = { cwd: (0, import_node_path.parse)(process.execPath).root, env: {}, windowsHide: true };
+    this.child = (0, import_node_child_process.spawn)(executable, ["--process-job", String(ownerPid), created], {
+      ...options,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let buffer = "";
+    this.child.stdout.setEncoding("utf8");
+    this.child.stdout.on("data", (data) => {
+      if (this.failed) return;
+      try {
+        buffer += data;
+        if (Buffer.byteLength(buffer) > 4096) {
+          throw (0, import_ProcessFault.processFault)("status_too_large", "Windows job status exceeds its bound");
+        }
+        for (; ; ) {
+          const end = buffer.indexOf("\n");
+          if (end < 0) break;
+          const frame = JSON.parse(buffer.slice(0, end));
+          buffer = buffer.slice(end + 1);
+          if (frame?.status === "ready" && frame.ownerPid === ownerPid && !this.receivedReady) {
+            this.receivedReady = true;
+            this.ready.resolve();
+          } else if (frame?.status === "settled" && this.receivedReady && !this.receivedSettled) {
+            this.receivedSettled = true;
+          } else throw (0, import_ProcessFault.processFault)("status_invalid", "Invalid Windows job status");
+        }
+      } catch (cause) {
+        this.fail(cause);
+      }
+    });
+    this.child.stderr.resume();
+    this.child.once("error", (cause) => this.fail(cause));
+    this.child.stdin.on("error", (cause) => this.fail(cause));
+    this.child.stdout.on("error", (cause) => this.fail(cause));
+    this.child.stderr.on("error", (cause) => this.fail(cause));
+    this.child.once("close", (code, signal) => {
+      if (!this.failed && code === 0 && signal === null && this.receivedSettled && buffer === "") {
+        this.settled.resolve();
+      } else this.fail((0, import_ProcessFault.processFault)("cleanup_unverified", "Windows job cleanup could not be verified"));
+    });
+  }
+  fail(cause) {
+    this.failed = true;
+    this.ready.reject(cause);
+    this.settled.reject(cause);
+    this.stop();
+  }
+  /** Closing this pipe asks the native guardian to terminate its job. */
+  stop() {
+    this.child.stdin.destroy();
+  }
+  /** Keep the guardian and all three pipes consistent with the host handle. */
+  reference(referenced) {
+    const method = referenced ? "ref" : "unref";
+    this.child[method]();
+    for (const pipe of [this.child.stdin, this.child.stdout, this.child.stderr]) pipe[method]();
+  }
+}
+//# sourceMappingURL=WindowsProcessJob.js.map

package/dist/cjs/internal/WindowsProcessJob.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/WindowsProcessJob.ts"],
+  "sourcesContent": ["/**\n * A native Windows job guardian, attached before the owner can launch a target.\n * @since 1.0.0\n */\n\nimport { spawn } from \"node:child_process\"\nimport type { Socket } from \"node:net\"\nimport { parse } from \"node:path\"\nimport { packageRoot, resolveConfiguredExecutable, resolveDefaultExecutable } from \"./AtomicFileSystemExecutable.ts\"\nimport { processFault } from \"./ProcessFault.ts\"\n\nconst deferred = <A>() => {\n  let resolve!: (value: A) => void\n  let reject!: (cause: unknown) => void\n  const promise = new Promise<A>((yes, no) => {\n    resolve = yes\n    reject = no\n  })\n  void promise.catch(() => {})\n  return { promise, resolve, reject }\n}\n\n/**\n * Resolve the same trusted helper for the owner's self-observation and guardian.\n * @private\n * @since 1.0.0\n */\nexport const resolveJobExecutable = (): string => {\n  const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY\n  return configured === undefined\n    ? resolveDefaultExecutable(packageRoot, undefined)\n    : resolveConfiguredExecutable(configured, undefined)\n}\n\n/**\n * Retains the guardian's dedicated control pipe until cleanup. EOF, including\n * host death, terminates the job independently of the Node owner's event loop.\n * @private\n * @since 1.0.0\n */\nexport class WindowsProcessJob {\n  readonly ready = deferred<void>()\n  readonly settled = deferred<void>()\n  private readonly child\n  private receivedReady = false\n  private receivedSettled = false\n  private failed = false\n\n  constructor(ownerPid: number, created: unknown, executable: string) {\n    if (typeof created !== \"string\" || !/^[1-9][0-9]{0,19}$/.test(created)) {\n      throw processFault(\"owner_identity_missing\", \"Windows process owner has no exact creation identity\")\n    }\n    const options = { cwd: parse(process.execPath).root, env: {}, windowsHide: true }\n    this.child = spawn(executable, [\"--process-job\", String(ownerPid), created], {\n      ...options,\n      stdio: [\"pipe\", \"pipe\", \"pipe\"]\n    })\n    let buffer = \"\"\n    this.child.stdout.setEncoding(\"utf8\")\n    this.child.stdout.on(\"data\", (data: string) => {\n      if (this.failed) return\n      try {\n        buffer += data\n        if (Buffer.byteLength(buffer) > 4096) {\n          throw processFault(\"status_too_large\", \"Windows job status exceeds its bound\")\n        }\n        for (;;) {\n          const end = buffer.indexOf(\"\\n\")\n          if (end < 0) break\n          const frame = JSON.parse(buffer.slice(0, end)) as { status?: unknown; ownerPid?: unknown } | null\n          buffer = buffer.slice(end + 1)\n          if (frame?.status === \"ready\" && frame.ownerPid === ownerPid && !this.receivedReady) {\n            this.receivedReady = true\n            this.ready.resolve()\n          } else if (frame?.status === \"settled\" && this.receivedReady && !this.receivedSettled) {\n            this.receivedSettled = true\n          } else throw processFault(\"status_invalid\", \"Invalid Windows job status\")\n        }\n      } catch (cause) {\n        this.fail(cause)\n      }\n    })\n    // Drain diagnostics without retaining unbounded native output.\n    this.child.stderr.resume()\n    this.child.once(\"error\", (cause) => this.fail(cause))\n    this.child.stdin.on(\"error\", (cause) => this.fail(cause))\n    this.child.stdout.on(\"error\", (cause) => this.fail(cause))\n    this.child.stderr.on(\"error\", (cause) => this.fail(cause))\n    this.child.once(\"close\", (code, signal) => {\n      if (!this.failed && code === 0 && signal === null && this.receivedSettled && buffer === \"\") {\n        this.settled.resolve()\n      } else this.fail(processFault(\"cleanup_unverified\", \"Windows job cleanup could not be verified\"))\n    })\n  }\n\n  private fail(cause: unknown): void {\n    this.failed = true\n    this.ready.reject(cause)\n    this.settled.reject(cause)\n    this.stop()\n  }\n\n  /** Closing this pipe asks the native guardian to terminate its job. */\n  stop(): void {\n    this.child.stdin.destroy()\n  }\n\n  /** Keep the guardian and all three pipes consistent with the host handle. */\n  reference(referenced: boolean): void {\n    const method = referenced ? \"ref\" : \"unref\"\n    this.child[method]()\n    for (const pipe of [this.child.stdin, this.child.stdout, this.child.stderr]) (pipe as Socket)[method]()\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/AtomicFileSystem.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Descriptor-relative filesystem operations through the packaged Rust helper.
+ * The helper pins the workspace root and walks each component with O_NOFOLLOW.
+ * Requests and responses are length-framed, size-limited, and cancellable.
+ * @since 0.1.0
+ */
+import { FileSystem, Layer } from "effect";
+export { AtomicHelperError, AtomicHelperErrorCode } from "./internal/AtomicHelperError.ts";
+/**
+ * The legacy system installation path, used after package and checkout paths.
+ * Helper selection never consults `PATH` or the process working directory.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const defaultExecutable = "/usr/local/bin/smithers-jj-export";
+/**
+ * Byte ceilings for the helper protocol. Every one of them is a contract, not
+ * a tuning knob: without them a large file, a large directory tree, or a
+ * malfunctioning helper makes the host allocate until it dies.
+ *
+ * - `content` bounds the bytes a single `readFile`/`writeFile` may carry.
+ * - `request` bounds the framed request; an over-limit request is refused
+ *   before an helper is even started.
+ * - `response` bounds the framed response, and is what a directory listing is
+ *   charged against as it is built. It bounds the REJECTION envelope too, so a
+ *   ceiling small enough to cut one off degrades that operation's typed reason
+ *   to the fail-closed one.
+ * - `stderr` bounds the diagnostic text retained from a failing helper.
+ * - `batchEntry` bounds one batch member's encoded success or failure envelope.
+ * - `batchSize` bounds the number of operations in one batch, at most 128.
+ *
+ * All except `batchSize` count bytes. The two ceilings that decide whether the host
+ * survives a wide fan-out are {@link Options.concurrency}, which bounds how
+ * many helpers run at once, and {@link Options.timeoutMs}, which bounds
+ * how long any one of them may take.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Limits {
+    readonly content: number;
+    readonly request: number;
+    readonly response: number;
+    readonly stderr: number;
+    /** Maximum operations in one helper invocation, at most 128. */
+    readonly batchSize: number;
+    /** Maximum encoded result bytes for one batch member. */
+    readonly batchEntry: number;
+}
+/**
+ * 16 MiB of file content, 24 MiB of framed request and response (base64
+ * expands 16 MiB to 22369624 bytes, which has to fit), and 64 KiB of retained
+ * helper diagnostics.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const defaultLimits: Limits;
+/**
+ * The default number of helper processes that may run at once:
+ * `os.availableParallelism()`.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export declare const defaultConcurrency: number;
+/**
+ * How long one helper may run before it is killed and the operation fails
+ * closed: five minutes.
+ *
+ * It is a backstop, not a latency budget. A read at the content ceiling over a
+ * slow disk has to fit under it, so it is generous; what it bounds is a helper
+ * that will never answer at all.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export declare const defaultTimeoutMs = 300000;
+/**
+ * The deliberate seam for a POSIX host that installs the native helper somewhere other
+ * than {@link defaultExecutable}, or that needs different ceilings. It is
+ * configuration, never discovery: the executable is validated as an absolute,
+ * executable regular file outside the confined workspace on every request, and
+ * every other field is read ONCE, when the layer is built.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Options {
+    readonly executable?: string | undefined;
+    readonly limits?: Partial<Limits> | undefined;
+    /**
+     * How many helper processes may run at once. Default
+     * {@link defaultConcurrency}.
+     *
+     * Each ordinary operation or batch starts one helper, so an unbounded
+     * `Effect.forEach` over a directory would start
+     * one helper per entry. This ceiling is what keeps a wide fan-out from
+     * pinning every core; it is a contract, not a tuning knob.
+     */
+    readonly concurrency?: number | undefined;
+    /**
+     * How long one helper may run before it is killed and the operation fails
+     * closed, in milliseconds. Default {@link defaultTimeoutMs}.
+     */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Process-local helper starts, for cost counters and local measurements.
+ * Includes helpers later cancelled or refused; rejected preflight starts none.
+ *
+ * @since 1.0.0
+ * @category metrics
+ */
+export declare const helperSpawns: () => number;
+/**
+ * The helper this process would start for an atomic operation, resolved exactly
+ * as an operation resolves it: `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`, then the
+ * packaged and checkout locations. Nothing is spawned. Throws an {@link AtomicHelperError} whose
+ * message names what was searched and how to install the helper when none is
+ * usable, so a diagnostic can report it before any operation needs it.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const resolveHelper: () => string;
+/**
+ * A Node filesystem layer carrying the kernel's atomic host extension, built
+ * against an explicitly configured helper, byte limits, process ceiling,
+ * and helper timeout.
+ *
+ * Every field of {@link Options} except `executable` is read once, here. The
+ * concurrency ceiling is one semaphore for the whole layer rather than one per
+ * request, which is the only arrangement that bounds anything.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<FileSystem.FileSystem>;
+/** A Node filesystem layer carrying the kernel's atomic host extension.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: Layer.Layer<FileSystem.FileSystem>;
+//# sourceMappingURL=AtomicFileSystem.d.ts.map

package/dist/esm/AtomicFileSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtomicFileSystem.d.ts","sourceRoot":"","sources":["../../src/AtomicFileSystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAU,UAAU,EAAE,KAAK,EAAoC,MAAM,QAAQ,CAAA;AAapF,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,sCAAsC,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAO3B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAA+B,CAAA;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,SAAU,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAC7C;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAgBD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAA;AAqJ7D;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,QAAO,MAA0C,CAAA;AAuB3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAuD7E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAiB,CAAA"}

package/dist/esm/AtomicFileSystem.js

@@ -0,0 +1,290 @@
+/**
+ * Descriptor-relative filesystem operations through the packaged Rust helper.
+ * The helper pins the workspace root and walks each component with O_NOFOLLOW.
+ * Requests and responses are length-framed, size-limited, and cancellable.
+ * @since 0.1.0
+ */
+import * as NodeFileSystem from "../vendor/node/NodeFileSystem.js";
+import * as KernelFileSystem from "@smthrs/kernel/FileSystem";
+import { Effect, FileSystem, Layer, PlatformError, Semaphore, Stream } from "effect";
+import { realpath, stat } from "node:fs/promises";
+import { availableParallelism } from "node:os";
+import { packageRoot, resolveConfiguredExecutable, resolveDefaultExecutable, stagePackaged } from "./internal/AtomicFileSystemExecutable.js";
+import * as Protocol from "./internal/AtomicFileSystemProtocol.js";
+import * as Transport from "./internal/AtomicFileSystemTransport.js";
+import { AtomicHelperError } from "./internal/AtomicHelperError.js";
+export { AtomicHelperError, AtomicHelperErrorCode } from "./internal/AtomicHelperError.js";
+/**
+ * The legacy system installation path, used after package and checkout paths.
+ * Helper selection never consults `PATH` or the process working directory.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const defaultExecutable = "/usr/local/bin/smithers-jj-export";
+/**
+ * 16 MiB of file content, 24 MiB of framed request and response (base64
+ * expands 16 MiB to 22369624 bytes, which has to fit), and 64 KiB of retained
+ * helper diagnostics.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const defaultLimits = {
+    content: 16 * 1024 * 1024,
+    request: 24 * 1024 * 1024,
+    response: 24 * 1024 * 1024,
+    stderr: 64 * 1024,
+    batchSize: KernelFileSystem.maxBatchSize,
+    batchEntry: 24 * 1024 * 1024
+};
+/**
+ * The default number of helper processes that may run at once:
+ * `os.availableParallelism()`.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export const defaultConcurrency = availableParallelism();
+/**
+ * How long one helper may run before it is killed and the operation fails
+ * closed: five minutes.
+ *
+ * It is a backstop, not a latency budget. A read at the content ceiling over a
+ * slow disk has to fit under it, so it is generous; what it bounds is a helper
+ * that will never answer at all.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export const defaultTimeoutMs = 300_000;
+/**
+ * Process-local helper starts, for cost counters and local measurements.
+ * Includes helpers later cancelled or refused; rejected preflight starts none.
+ *
+ * @since 1.0.0
+ * @category metrics
+ */
+export const helperSpawns = () => Transport.started();
+/** The helper enforces the same ceiling before it trusts a declared limit. */
+const hardLimitBytes = 256 * 1024 * 1024;
+/** `setTimeout` clamps a longer delay to 1 ms, so a bigger backstop is none. */
+const maxTimeoutMs = 2_147_483_647;
+/** Resolves every optional byte ceiling and refuses values that could disable a bound. */
+const resolveLimits = (overrides) => {
+    const limits = {
+        content: overrides?.content ?? defaultLimits.content,
+        request: overrides?.request ?? defaultLimits.request,
+        response: overrides?.response ?? defaultLimits.response,
+        stderr: overrides?.stderr ?? defaultLimits.stderr,
+        batchSize: overrides?.batchSize ?? defaultLimits.batchSize,
+        batchEntry: overrides?.batchEntry ?? defaultLimits.batchEntry
+    };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0 || value > hardLimitBytes) {
+            throw new AtomicHelperError({
+                code: "limit_invalid",
+                message: `atomic helper ${name} limit must be a positive integer no greater than ${hardLimitBytes}`
+            });
+        }
+    }
+    if (limits.batchSize > KernelFileSystem.maxBatchSize) {
+        throw new AtomicHelperError({
+            code: "limit_invalid",
+            message: `atomic helper batchSize limit must be no greater than ${KernelFileSystem.maxBatchSize}`
+        });
+    }
+    return limits;
+};
+/**
+ * Reads the whole of {@link Options} once, at layer construction.
+ *
+ * A rejected value is carried rather than thrown, because the failure a caller
+ * sees for it is a typed `BadArgument` on the first operation and not an
+ * exception escaping a layer.
+ */
+const resolveSettings = (options) => {
+    try {
+        const limits = resolveLimits(options.limits);
+        const concurrency = options.concurrency ?? defaultConcurrency;
+        if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {
+            throw new AtomicHelperError({
+                code: "concurrency_invalid",
+                message: "atomic helper concurrency must be a positive integer"
+            });
+        }
+        const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > maxTimeoutMs) {
+            throw new AtomicHelperError({
+                code: "timeout_invalid",
+                message: "atomic helper timeoutMs must be a positive integer no greater than 2147483647"
+            });
+        }
+        return { limits, timeoutMs, semaphore: Semaphore.makeUnsafe(concurrency) };
+    }
+    catch (invalid) {
+        return { invalid };
+    }
+};
+/**
+ * The framed half, one concrete result type. Nothing on this side of the pipe
+ * can prove what the helper answered: the protocol pairs an operation with its
+ * result, and {@link execute} restates that pairing for the kernel's typed
+ * request. Keeping the decode `unknown` here confines that promise to one
+ * assertion instead of one per caller.
+ */
+const executeFramed = (options, resolved) => (request) => Effect.suspend(() => {
+    if ("invalid" in resolved) {
+        const cause = resolved.invalid;
+        return Effect.fail(PlatformError.badArgument({
+            module: Protocol.moduleName,
+            method: request.operation,
+            description: cause instanceof Error ? cause.message : "atomic helper limits are invalid",
+            cause
+        }));
+    }
+    const limits = resolved.limits;
+    if (request.operation === "batch" &&
+        (!Array.isArray(request.requests) || request.requests.length === 0 || request.requests.length > limits.batchSize)) {
+        return Effect.fail(PlatformError.badArgument({
+            module: Protocol.moduleName,
+            method: "batch",
+            description: `atomic batch must contain 1 to ${limits.batchSize} operations`
+        }));
+    }
+    // Admission bounds request serialization and framing as well as children.
+    // Queued callers retain their input, without another full payload copy.
+    return resolved.semaphore.withPermits(1)(Effect.suspend(() => {
+        let body;
+        try {
+            const serialized = JSON.stringify(request.operation === "batch"
+                ? { ...request, batchSize: limits.batchSize, batchEntry: limits.batchEntry }
+                : request);
+            if (serialized === undefined) {
+                throw new AtomicHelperError({
+                    code: "request_not_serializable",
+                    message: "atomic request is not serializable"
+                });
+            }
+            body = Buffer.from(serialized, "utf8");
+        }
+        catch (cause) {
+            return Effect.fail(PlatformError.badArgument({
+                module: Protocol.moduleName,
+                method: request.operation,
+                description: "atomic request is not serializable",
+                cause
+            }));
+        }
+        if (body.byteLength > limits.request) {
+            // Refused before an helper exists: an over-limit request is caller
+            // input, and nothing about it improves by being sent.
+            return Effect.fail(PlatformError.badArgument({
+                module: Protocol.moduleName,
+                method: request.operation,
+                description: `atomic request of ${body.byteLength} bytes exceeds the ${limits.request} byte limit`
+            }));
+        }
+        let executable;
+        try {
+            executable = resolveExecutable(options, request.boundaryRoot);
+        }
+        catch (cause) {
+            return Effect.fail(Protocol.failure(request, cause));
+        }
+        return Transport.spawnHelper(request, executable, Protocol.encode(body, limits), resolved);
+    }));
+});
+const resolveExecutable = (options, boundaryRoot) => {
+    const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY;
+    return options.executable !== undefined
+        ? Transport.usableExecutable(options.executable, boundaryRoot)
+        : configured === undefined
+            ? resolveDefaultExecutable(packageRoot, boundaryRoot, defaultExecutable)
+            : resolveConfiguredExecutable(configured, boundaryRoot);
+};
+/**
+ * The helper this process would start for an atomic operation, resolved exactly
+ * as an operation resolves it: `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`, then the
+ * packaged and checkout locations. Nothing is spawned. Throws an {@link AtomicHelperError} whose
+ * message names what was searched and how to install the helper when none is
+ * usable, so a diagnostic can report it before any operation needs it.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const resolveHelper = () => resolveExecutable({}, undefined);
+const execute = (options, resolved) => {
+    const framed = executeFramed(options, resolved);
+    return (request) => framed(request);
+};
+const nativeRealPath = (path) => Effect.tryPromise({
+    try: () => realpath(path),
+    catch: (cause) => Protocol.failure({ operation: "realPath", path }, cause, {
+        ok: false,
+        code: cause.code ?? null,
+        message: cause.message,
+        syscall: "realpath"
+    })
+});
+/**
+ * A Node filesystem layer carrying the kernel's atomic host extension, built
+ * against an explicitly configured helper, byte limits, process ceiling,
+ * and helper timeout.
+ *
+ * Every field of {@link Options} except `executable` is read once, here. The
+ * concurrency ceiling is one semaphore for the whole layer rather than one per
+ * request, which is the only arrangement that bounds anything.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layerWith = (options) => {
+    // Outside the layer body on purpose. Inside it the settings would be read
+    // again on every BUILD, so two compositions of the same layer value could
+    // enforce two different ceilings out of one mutated object, and each would
+    // get a process ceiling of its own instead of sharing one.
+    const settings = resolveSettings(options);
+    return Layer.effect(FileSystem.FileSystem, Effect.map(
+    // The packaged helper is pinned while the host is built, before any flow
+    // can rewrite a workspace-local install of this package.
+    Effect.andThen(Effect.sync(() => {
+        if (options.executable === undefined && process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY === undefined) {
+            stagePackaged(packageRoot);
+        }
+    }), FileSystem.FileSystem), (fileSystem) => KernelFileSystem.withAtomicFileSystem({
+        ...fileSystem,
+        // Expand DOS names before pinning roots or opening native watchers.
+        realPath: nativeRealPath,
+        watch: (path, options) => process.platform !== "win32"
+            ? fileSystem.watch(path, options)
+            : Stream.unwrap(nativeRealPath(path).pipe(Effect.map((canonical) => fileSystem.watch(canonical, options))))
+    }, {
+        noFollowAuthorization: true,
+        execute: execute(options, settings),
+        identifyRoot: (path) => Effect.tryPromise({
+            try: async () => {
+                const info = await stat(path, { bigint: true });
+                return `${info.dev}:${info.ino}`;
+            },
+            catch: (cause) => Protocol.failure({ operation: "stat", path }, cause, {
+                ok: false,
+                code: cause.code ?? null,
+                message: cause.message,
+                syscall: "stat"
+            })
+        }),
+        batchLimits: {
+            size: "invalid" in settings ? defaultLimits.batchSize : settings.limits.batchSize,
+            response: "invalid" in settings ? defaultLimits.response : settings.limits.response
+        },
+        contentLimit: "invalid" in settings ? defaultLimits.content : settings.limits.content
+    }))).pipe(Layer.provide(NodeFileSystem.layer));
+};
+/** A Node filesystem layer carrying the kernel's atomic host extension.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export const layer = layerWith({});
+//# sourceMappingURL=AtomicFileSystem.js.map

package/dist/esm/AtomicFileSystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtomicFileSystem.js","sourceRoot":"","sources":["../../src/AtomicFileSystem.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Descriptor-relative filesystem operations through the packaged Rust helper.\n * The helper pins the workspace root and walks each component with O_NOFOLLOW.\n * Requests and responses are length-framed, size-limited, and cancellable.\n * @since 0.1.0\n */\n\nimport * as NodeFileSystem from \"@effect/platform-node/NodeFileSystem\"\nimport * as KernelFileSystem from \"@smthrs/kernel/FileSystem\"\nimport { Effect, FileSystem, Layer, PlatformError, Semaphore, Stream } from \"effect\"\nimport { realpath, stat } from \"node:fs/promises\"\nimport { availableParallelism } from \"node:os\"\nimport {\n  packageRoot,\n  resolveConfiguredExecutable,\n  resolveDefaultExecutable,\n  stagePackaged\n} from \"./internal/AtomicFileSystemExecutable.ts\"\nimport * as Protocol from \"./internal/AtomicFileSystemProtocol.ts\"\nimport * as Transport from \"./internal/AtomicFileSystemTransport.ts\"\nimport { AtomicHelperError } from \"./internal/AtomicHelperError.ts\"\n\nexport { AtomicHelperError, AtomicHelperErrorCode } from \"./internal/AtomicHelperError.ts\"\n\n/**\n * The legacy system installation path, used after package and checkout paths.\n * Helper selection never consults `PATH` or the process working directory.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const defaultExecutable = \"/usr/local/bin/smithers-jj-export\"\n\n/**\n * Byte ceilings for the helper protocol. Every one of them is a contract, not\n * a tuning knob: without them a large file, a large directory tree, or a\n * malfunctioning helper makes the host allocate until it dies.\n *\n * - `content` bounds the bytes a single `readFile`/`writeFile` may carry.\n * - `request` bounds the framed request; an over-limit request is refused\n *   before an helper is even started.\n * - `response` bounds the framed response, and is what a directory listing is\n *   charged against as it is built. It bounds the REJECTION envelope too, so a\n *   ceiling small enough to cut one off degrades that operation's typed reason\n *   to the fail-closed one.\n * - `stderr` bounds the diagnostic text retained from a failing helper.\n * - `batchEntry` bounds one batch member's encoded success or failure envelope.\n * - `batchSize` bounds the number of operations in one batch, at most 128.\n *\n * All except `batchSize` count bytes. The two ceilings that decide whether the host\n * survives a wide fan-out are {@link Options.concurrency}, which bounds how\n * many helpers run at once, and {@link Options.timeoutMs}, which bounds\n * how long any one of them may take.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface Limits {\n  readonly content: number\n  readonly request: number\n  readonly response: number\n  readonly stderr: number\n  /** Maximum operations in one helper invocation, at most 128. */\n  readonly batchSize: number\n  /** Maximum encoded result bytes for one batch member. */\n  readonly batchEntry: number\n}\n\n/**\n * 16 MiB of file content, 24 MiB of framed request and response (base64\n * expands 16 MiB to 22369624 bytes, which has to fit), and 64 KiB of retained\n * helper diagnostics.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const defaultLimits: Limits = {\n  content: 16 * 1024 * 1024,\n  request: 24 * 1024 * 1024,\n  response: 24 * 1024 * 1024,\n  stderr: 64 * 1024,\n  batchSize: KernelFileSystem.maxBatchSize,\n  batchEntry: 24 * 1024 * 1024\n}\n\n/**\n * The default number of helper processes that may run at once:\n * `os.availableParallelism()`.\n *\n * @since 1.0.0-rc.0\n * @category constants\n */\nexport const defaultConcurrency: number = availableParallelism()\n\n/**\n * How long one helper may run before it is killed and the operation fails\n * closed: five minutes.\n *\n * It is a backstop, not a latency budget. A read at the content ceiling over a\n * slow disk has to fit under it, so it is generous; what it bounds is a helper\n * that will never answer at all.\n *\n * @since 1.0.0-rc.0\n * @category constants\n */\nexport const defaultTimeoutMs = 300_000\n\n/**\n * The deliberate seam for a POSIX host that installs the native helper somewhere other\n * than {@link defaultExecutable}, or that needs different ceilings. It is\n * configuration, never discovery: the executable is validated as an absolute,\n * executable regular file outside the confined workspace on every request, and\n * every other field is read ONCE, when the layer is built.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface Options {\n  readonly executable?: string | undefined\n  readonly limits?: Partial<Limits> | undefined\n  /**\n   * How many helper processes may run at once. Default\n   * {@link defaultConcurrency}.\n   *\n   * Each ordinary operation or batch starts one helper, so an unbounded\n   * `Effect.forEach` over a directory would start\n   * one helper per entry. This ceiling is what keeps a wide fan-out from\n   * pinning every core; it is a contract, not a tuning knob.\n   */\n  readonly concurrency?: number | undefined\n  /**\n   * How long one helper may run before it is killed and the operation fails\n   * closed, in milliseconds. Default {@link defaultTimeoutMs}.\n   */\n  readonly timeoutMs?: number | undefined\n}\n\n/**\n * Everything read out of {@link Options} once, when the layer is built.\n *\n * Snapshotted rather than re-read per request: `Options` is a plain object the\n * caller still holds, and a byte ceiling that changes under a running host is\n * not a ceiling. The executable is deliberately NOT here — it is re-validated\n * per request, because the file it names can be replaced while the host runs.\n */\ninterface Settings {\n  readonly limits: Limits\n  readonly timeoutMs: number\n  readonly semaphore: Semaphore.Semaphore\n}\n\n/**\n * Process-local helper starts, for cost counters and local measurements.\n * Includes helpers later cancelled or refused; rejected preflight starts none.\n *\n * @since 1.0.0\n * @category metrics\n */\nexport const helperSpawns = (): number => Transport.started()\n\n/** The helper enforces the same ceiling before it trusts a declared limit. */\nconst hardLimitBytes = 256 * 1024 * 1024\n/** `setTimeout` clamps a longer delay to 1 ms, so a bigger backstop is none. */\nconst maxTimeoutMs = 2_147_483_647\n\n/** Resolves every optional byte ceiling and refuses values that could disable a bound. */\nconst resolveLimits = (overrides: Partial<Limits> | undefined): Limits => {\n  const limits: Limits = {\n    content: overrides?.content ?? defaultLimits.content,\n    request: overrides?.request ?? defaultLimits.request,\n    response: overrides?.response ?? defaultLimits.response,\n    stderr: overrides?.stderr ?? defaultLimits.stderr,\n    batchSize: overrides?.batchSize ?? defaultLimits.batchSize,\n    batchEntry: overrides?.batchEntry ?? defaultLimits.batchEntry\n  }\n  for (const [name, value] of Object.entries(limits)) {\n    if (!Number.isSafeInteger(value) || value <= 0 || value > hardLimitBytes) {\n      throw new AtomicHelperError({\n        code: \"limit_invalid\",\n        message: `atomic helper ${name} limit must be a positive integer no greater than ${hardLimitBytes}`\n      })\n    }\n  }\n  if (limits.batchSize > KernelFileSystem.maxBatchSize) {\n    throw new AtomicHelperError({\n      code: \"limit_invalid\",\n      message: `atomic helper batchSize limit must be no greater than ${KernelFileSystem.maxBatchSize}`\n    })\n  }\n  return limits\n}\n\n/**\n * Reads the whole of {@link Options} once, at layer construction.\n *\n * A rejected value is carried rather than thrown, because the failure a caller\n * sees for it is a typed `BadArgument` on the first operation and not an\n * exception escaping a layer.\n */\nconst resolveSettings = (options: Options): Settings | { readonly invalid: unknown } => {\n  try {\n    const limits = resolveLimits(options.limits)\n    const concurrency = options.concurrency ?? defaultConcurrency\n    if (!Number.isSafeInteger(concurrency) || concurrency <= 0) {\n      throw new AtomicHelperError({\n        code: \"concurrency_invalid\",\n        message: \"atomic helper concurrency must be a positive integer\"\n      })\n    }\n    const timeoutMs = options.timeoutMs ?? defaultTimeoutMs\n    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > maxTimeoutMs) {\n      throw new AtomicHelperError({\n        code: \"timeout_invalid\",\n        message: \"atomic helper timeoutMs must be a positive integer no greater than 2147483647\"\n      })\n    }\n    return { limits, timeoutMs, semaphore: Semaphore.makeUnsafe(concurrency) }\n  } catch (invalid) {\n    return { invalid }\n  }\n}\n\n/**\n * The framed half, one concrete result type. Nothing on this side of the pipe\n * can prove what the helper answered: the protocol pairs an operation with its\n * result, and {@link execute} restates that pairing for the kernel's typed\n * request. Keeping the decode `unknown` here confines that promise to one\n * assertion instead of one per caller.\n */\nconst executeFramed = (options: Options, resolved: Settings | { readonly invalid: unknown }) =>\n(\n  request: KernelFileSystem.AtomicRequest\n): Effect.Effect<unknown, PlatformError.PlatformError> =>\n  Effect.suspend(() => {\n    if (\"invalid\" in resolved) {\n      const cause = resolved.invalid\n      return Effect.fail(PlatformError.badArgument({\n        module: Protocol.moduleName,\n        method: request.operation,\n        description: cause instanceof Error ? cause.message : \"atomic helper limits are invalid\",\n        cause\n      }))\n    }\n    const limits = resolved.limits\n    if (\n      request.operation === \"batch\" &&\n      (!Array.isArray(request.requests) || request.requests.length === 0 || request.requests.length > limits.batchSize)\n    ) {\n      return Effect.fail(PlatformError.badArgument({\n        module: Protocol.moduleName,\n        method: \"batch\",\n        description: `atomic batch must contain 1 to ${limits.batchSize} operations`\n      }))\n    }\n    // Admission bounds request serialization and framing as well as children.\n    // Queued callers retain their input, without another full payload copy.\n    return resolved.semaphore.withPermits(1)(Effect.suspend(() => {\n      let body: Buffer\n      try {\n        const serialized = JSON.stringify(\n          request.operation === \"batch\"\n            ? { ...request, batchSize: limits.batchSize, batchEntry: limits.batchEntry }\n            : request\n        )\n        if (serialized === undefined) {\n          throw new AtomicHelperError({\n            code: \"request_not_serializable\",\n            message: \"atomic request is not serializable\"\n          })\n        }\n        body = Buffer.from(serialized, \"utf8\")\n      } catch (cause) {\n        return Effect.fail(PlatformError.badArgument({\n          module: Protocol.moduleName,\n          method: request.operation,\n          description: \"atomic request is not serializable\",\n          cause\n        }))\n      }\n      if (body.byteLength > limits.request) {\n        // Refused before an helper exists: an over-limit request is caller\n        // input, and nothing about it improves by being sent.\n        return Effect.fail(PlatformError.badArgument({\n          module: Protocol.moduleName,\n          method: request.operation,\n          description: `atomic request of ${body.byteLength} bytes exceeds the ${limits.request} byte limit`\n        }))\n      }\n      let executable: string\n      try {\n        executable = resolveExecutable(options, request.boundaryRoot)\n      } catch (cause) {\n        return Effect.fail(Protocol.failure(request, cause))\n      }\n      return Transport.spawnHelper<unknown>(request, executable, Protocol.encode(body, limits), resolved)\n    }))\n  })\n\nconst resolveExecutable = (options: Pick<Options, \"executable\">, boundaryRoot: string | undefined): string => {\n  const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY\n  return options.executable !== undefined\n    ? Transport.usableExecutable(options.executable, boundaryRoot)\n    : configured === undefined\n    ? resolveDefaultExecutable(packageRoot, boundaryRoot, defaultExecutable)\n    : resolveConfiguredExecutable(configured, boundaryRoot)\n}\n\n/**\n * The helper this process would start for an atomic operation, resolved exactly\n * as an operation resolves it: `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`, then the\n * packaged and checkout locations. Nothing is spawned. Throws an {@link AtomicHelperError} whose\n * message names what was searched and how to install the helper when none is\n * usable, so a diagnostic can report it before any operation needs it.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const resolveHelper = (): string => resolveExecutable({}, undefined)\n\nconst execute = (\n  options: Options,\n  resolved: Settings | { readonly invalid: unknown }\n): KernelFileSystem.AtomicFileSystem[\"execute\"] => {\n  const framed = executeFramed(options, resolved)\n  return <R extends KernelFileSystem.AtomicRequest>(request: R) =>\n    framed(request) as Effect.Effect<KernelFileSystem.AtomicResult<R>, PlatformError.PlatformError>\n}\n\nconst nativeRealPath = (path: string) =>\n  Effect.tryPromise({\n    try: () => realpath(path),\n    catch: (cause) =>\n      Protocol.failure({ operation: \"realPath\", path }, cause, {\n        ok: false,\n        code: (cause as NodeJS.ErrnoException).code ?? null,\n        message: (cause as NodeJS.ErrnoException).message,\n        syscall: \"realpath\"\n      })\n  })\n\n/**\n * A Node filesystem layer carrying the kernel's atomic host extension, built\n * against an explicitly configured helper, byte limits, process ceiling,\n * and helper timeout.\n *\n * Every field of {@link Options} except `executable` is read once, here. The\n * concurrency ceiling is one semaphore for the whole layer rather than one per\n * request, which is the only arrangement that bounds anything.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layerWith = (options: Options): Layer.Layer<FileSystem.FileSystem> => {\n  // Outside the layer body on purpose. Inside it the settings would be read\n  // again on every BUILD, so two compositions of the same layer value could\n  // enforce two different ceilings out of one mutated object, and each would\n  // get a process ceiling of its own instead of sharing one.\n  const settings = resolveSettings(options)\n  return Layer.effect(\n    FileSystem.FileSystem,\n    Effect.map(\n      // The packaged helper is pinned while the host is built, before any flow\n      // can rewrite a workspace-local install of this package.\n      Effect.andThen(\n        Effect.sync(() => {\n          if (options.executable === undefined && process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY === undefined) {\n            stagePackaged(packageRoot)\n          }\n        }),\n        FileSystem.FileSystem\n      ),\n      (fileSystem) =>\n        KernelFileSystem.withAtomicFileSystem({\n          ...fileSystem,\n          // Expand DOS names before pinning roots or opening native watchers.\n          realPath: nativeRealPath,\n          watch: (path, options) =>\n            process.platform !== \"win32\"\n              ? fileSystem.watch(path, options)\n              : Stream.unwrap(\n                nativeRealPath(path).pipe(Effect.map((canonical) => fileSystem.watch(canonical, options)))\n              )\n        }, {\n          noFollowAuthorization: true,\n          execute: execute(options, settings),\n          identifyRoot: (path) =>\n            Effect.tryPromise({\n              try: async () => {\n                const info = await stat(path, { bigint: true })\n                return `${info.dev}:${info.ino}`\n              },\n              catch: (cause) =>\n                Protocol.failure({ operation: \"stat\", path }, cause, {\n                  ok: false,\n                  code: (cause as NodeJS.ErrnoException).code ?? null,\n                  message: (cause as NodeJS.ErrnoException).message,\n                  syscall: \"stat\"\n                })\n            }),\n          batchLimits: {\n            size: \"invalid\" in settings ? defaultLimits.batchSize : settings.limits.batchSize,\n            response: \"invalid\" in settings ? defaultLimits.response : settings.limits.response\n          },\n          contentLimit: \"invalid\" in settings ? defaultLimits.content : settings.limits.content\n        })\n    )\n  ).pipe(Layer.provide(NodeFileSystem.layer))\n}\n\n/** A Node filesystem layer carrying the kernel's atomic host extension.\n *\n * @since 0.1.0\n * @category layers\n */\nexport const layer: Layer.Layer<FileSystem.FileSystem> = layerWith({})\n"]}