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

package/dist/cjs/internal/ProcessCleanup.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Prepared process ownership and bounded release for Node and Bun hosts.
+ * @since 1.0.0
+ */
+import { type Lifecycle } from "@smthrs/kernel/ContainedSpawner";
+import * as Effect from "effect/Effect";
+import type * as PlatformError from "effect/PlatformError";
+import type * as ChildProcess from "effect/unstable/process/ChildProcess";
+/**
+ * An operating-system identity observed in a group.
+ * @private
+ * @since 1.0.0
+ */
+export interface Member {
+    readonly pid: number;
+    readonly startedAtMs: number;
+    readonly zombie: boolean;
+}
+/**
+ * One bounded observation, including the host group.
+ * @private
+ * @since 1.0.0
+ */
+export interface Snapshot {
+    readonly ownGroup: number;
+    readonly members: ReadonlyArray<Member>;
+}
+/**
+ * Observations can shorten or verify cleanup, but never authorize signals.
+ * @private
+ * @since 1.0.0
+ */
+export interface System {
+    readonly platform: string;
+    readonly snapshot: (pgid: number) => Snapshot | undefined;
+    /**
+     * True only when the kernel proves the group has no process at all. False
+     * means occupied or unknown; `snapshot` still decides those.
+     */
+    readonly vacant: (pgid: number) => boolean;
+}
+/**
+ * A finite termination deadline understood by the private owner.
+ * @private
+ * @since 1.0.0
+ */
+export interface Policy {
+    readonly killSignal: ChildProcess.Signal;
+    readonly graceMs: number;
+}
+/**
+ * Normalize and validate the deadline before it enters a native timer.
+ * @private
+ * @since 1.0.0
+ */
+export declare const policy: (options: ChildProcess.KillOptions, defaults?: ChildProcess.KillOptions) => Effect.Effect<Policy, PlatformError.PlatformError>;
+/**
+ * Prepare a live owner before target activation. Windows attaches that owner
+ * to a native job; POSIX uses its independently bounded process supervisor.
+ * @private
+ * @since 1.0.0
+ */
+export declare const lifecycle: (system: System) => Lifecycle;
+//# sourceMappingURL=ProcessCleanup.d.ts.map

package/dist/cjs/internal/ProcessCleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessCleanup.d.ts","sourceRoot":"","sources":["../../../src/internal/ProcessCleanup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,iCAAiC,CAAA;AAEhF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,KAAK,YAAY,MAAM,sCAAsC,CAAA;AAKzE;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC,MAAM,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,GACjB,SAAS,YAAY,CAAC,WAAW,EACjC,WAAU,YAAY,CAAC,WAAgB,KACtC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAsBhD,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,KAAG,SAA+C,CAAA"}

package/dist/cjs/internal/ProcessCleanup.js

@@ -0,0 +1,62 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ProcessCleanup_exports = {};
+__export(ProcessCleanup_exports, {
+  lifecycle: () => lifecycle,
+  policy: () => policy
+});
+module.exports = __toCommonJS(ProcessCleanup_exports);
+var import_ContainedSpawner = require("@smthrs/kernel/ContainedSpawner");
+var Duration = __toESM(require("effect/Duration"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var import_node_os = require("node:os");
+var import_ProcessCleanupPolicyError = require("./ProcessCleanupPolicyError.js");
+var Supervisor = __toESM(require("./ProcessSupervisor.js"), 1);
+const policy = (options, defaults = {}) => Effect.try({
+  try: () => {
+    const killSignal = options.killSignal ?? defaults.killSignal ?? "SIGTERM";
+    if (killSignal === "SIGSTOP" || import_node_os.constants.signals[killSignal] === void 0) {
+      throw new import_ProcessCleanupPolicyError.ProcessCleanupPolicyError({
+        code: "kill_signal_unsupported",
+        message: `Unsupported process termination signal ${killSignal}`
+      });
+    }
+    const graceMs = Duration.toMillis(options.forceKillAfter ?? defaults.forceKillAfter ?? import_ContainedSpawner.defaultGraceMs);
+    if (!Number.isFinite(graceMs) || graceMs < 0 || graceMs > 2147483647) {
+      throw new import_ProcessCleanupPolicyError.ProcessCleanupPolicyError({
+        code: "grace_out_of_range",
+        message: "Process cleanup grace must fit a finite nonnegative native timer"
+      });
+    }
+    return { killSignal, graceMs };
+  },
+  catch: (cause) => Supervisor.failure("kill", "process cleanup policy", cause)
+});
+const lifecycle = (system) => Supervisor.prepare(system, policy);
+//# sourceMappingURL=ProcessCleanup.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/ProcessCleanup.ts"],
+  "sourcesContent": ["/**\n * Prepared process ownership and bounded release for Node and Bun hosts.\n * @since 1.0.0\n */\n\nimport { defaultGraceMs, type Lifecycle } from \"@smthrs/kernel/ContainedSpawner\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport type * as PlatformError from \"effect/PlatformError\"\nimport type * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport { constants } from \"node:os\"\nimport { ProcessCleanupPolicyError } from \"./ProcessCleanupPolicyError.ts\"\nimport * as Supervisor from \"./ProcessSupervisor.ts\"\n\n/**\n * An operating-system identity observed in a group.\n * @private\n * @since 1.0.0\n */\nexport interface Member {\n  readonly pid: number\n  readonly startedAtMs: number\n  readonly zombie: boolean\n}\n\n/**\n * One bounded observation, including the host group.\n * @private\n * @since 1.0.0\n */\nexport interface Snapshot {\n  readonly ownGroup: number\n  readonly members: ReadonlyArray<Member>\n}\n\n/**\n * Observations can shorten or verify cleanup, but never authorize signals.\n * @private\n * @since 1.0.0\n */\nexport interface System {\n  readonly platform: string\n  readonly snapshot: (pgid: number) => Snapshot | undefined\n  /**\n   * True only when the kernel proves the group has no process at all. False\n   * means occupied or unknown; `snapshot` still decides those.\n   */\n  readonly vacant: (pgid: number) => boolean\n}\n\n/**\n * A finite termination deadline understood by the private owner.\n * @private\n * @since 1.0.0\n */\nexport interface Policy {\n  readonly killSignal: ChildProcess.Signal\n  readonly graceMs: number\n}\n\n/**\n * Normalize and validate the deadline before it enters a native timer.\n * @private\n * @since 1.0.0\n */\nexport const policy = (\n  options: ChildProcess.KillOptions,\n  defaults: ChildProcess.KillOptions = {}\n): Effect.Effect<Policy, PlatformError.PlatformError> =>\n  Effect.try({\n    try: () => {\n      const killSignal = options.killSignal ?? defaults.killSignal ?? \"SIGTERM\"\n      if (killSignal === \"SIGSTOP\" || constants.signals[killSignal] === undefined) {\n        throw new ProcessCleanupPolicyError({\n          code: \"kill_signal_unsupported\",\n          message: `Unsupported process termination signal ${killSignal}`\n        })\n      }\n      const graceMs = Duration.toMillis(options.forceKillAfter ?? defaults.forceKillAfter ?? defaultGraceMs)\n      // Node/Bun clamp an overflowing timeout to 1 ms. Refuse that policy rather\n      // than silently replacing a caller's grace with immediate termination.\n      if (!Number.isFinite(graceMs) || graceMs < 0 || graceMs > 2_147_483_647) {\n        throw new ProcessCleanupPolicyError({\n          code: \"grace_out_of_range\",\n          message: \"Process cleanup grace must fit a finite nonnegative native timer\"\n        })\n      }\n      return { killSignal, graceMs }\n    },\n    catch: (cause) => Supervisor.failure(\"kill\", \"process cleanup policy\", cause)\n  })\n\n/**\n * Prepare a live owner before target activation. Windows attaches that owner\n * to a native job; POSIX uses its independently bounded process supervisor.\n * @private\n * @since 1.0.0\n */\nexport const lifecycle = (system: System): Lifecycle => Supervisor.prepare(system, policy)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,8BAA+C;AAC/C,eAA0B;AAC1B,aAAwB;AAGxB,qBAA0B;AAC1B,uCAA0C;AAC1C,iBAA4B;AAqDrB,MAAM,SAAS,CACpB,SACA,WAAqC,CAAC,MAEtC,OAAO,IAAI;AAAA,EACT,KAAK,MAAM;AACT,UAAM,aAAa,QAAQ,cAAc,SAAS,cAAc;AAChE,QAAI,eAAe,aAAa,yBAAU,QAAQ,UAAU,MAAM,QAAW;AAC3E,YAAM,IAAI,2DAA0B;AAAA,QAClC,MAAM;AAAA,QACN,SAAS,0CAA0C,UAAU;AAAA,MAC/D,CAAC;AAAA,IACH;AACA,UAAM,UAAU,SAAS,SAAS,QAAQ,kBAAkB,SAAS,kBAAkB,sCAAc;AAGrG,QAAI,CAAC,OAAO,SAAS,OAAO,KAAK,UAAU,KAAK,UAAU,YAAe;AACvE,YAAM,IAAI,2DAA0B;AAAA,QAClC,MAAM;AAAA,QACN,SAAS;AAAA,MACX,CAAC;AAAA,IACH;AACA,WAAO,EAAE,YAAY,QAAQ;AAAA,EAC/B;AAAA,EACA,OAAO,CAAC,UAAU,WAAW,QAAQ,QAAQ,0BAA0B,KAAK;AAC9E,CAAC;AAQI,MAAM,YAAY,CAAC,WAA8B,WAAW,QAAQ,QAAQ,MAAM;",
+  "names": []
+}

package/dist/cjs/internal/ProcessCleanupPolicyError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A process cleanup policy that cannot be honoured: a termination signal the
+ * platform does not define or cannot deliver, or a grace that overflows a
+ * native timer. `policy` reports one as the `cause` of a `PlatformError`.
+ *
+ * @since 1.0.0
+ */
+import { Schema } from "effect";
+/**
+ * Which part of the policy was refused.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const ProcessCleanupPolicyErrorCode: Schema.Literals<readonly ["kill_signal_unsupported", "grace_out_of_range"]>;
+declare const ProcessCleanupPolicyError_base: Schema.Class<ProcessCleanupPolicyError, Schema.TaggedStruct<"@smthrs/platform-node/ProcessCleanupPolicyError", {
+    readonly code: Schema.Literals<readonly ["kill_signal_unsupported", "grace_out_of_range"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A cleanup policy outside what a native timer and the platform allow.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ProcessCleanupPolicyError extends ProcessCleanupPolicyError_base {
+    readonly name = "ProcessCleanupPolicyError";
+}
+export {};
+//# sourceMappingURL=ProcessCleanupPolicyError.d.ts.map

package/dist/cjs/internal/ProcessCleanupPolicyError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessCleanupPolicyError.d.ts","sourceRoot":"","sources":["../../../src/internal/ProcessCleanupPolicyError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,6EAAqE,CAAA;;;;;AAE/G;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,8BAG9C;IACC,SAAkB,IAAI,+BAA8B;CACrD"}

package/dist/cjs/internal/ProcessCleanupPolicyError.js

@@ -0,0 +1,33 @@
+"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 ProcessCleanupPolicyError_exports = {};
+__export(ProcessCleanupPolicyError_exports, {
+  ProcessCleanupPolicyError: () => ProcessCleanupPolicyError,
+  ProcessCleanupPolicyErrorCode: () => ProcessCleanupPolicyErrorCode
+});
+module.exports = __toCommonJS(ProcessCleanupPolicyError_exports);
+var import_effect = require("effect");
+const ProcessCleanupPolicyErrorCode = import_effect.Schema.Literals(["kill_signal_unsupported", "grace_out_of_range"]);
+class ProcessCleanupPolicyError extends import_effect.Schema.TaggedError()(
+  "@smthrs/platform-node/ProcessCleanupPolicyError",
+  { code: ProcessCleanupPolicyErrorCode, message: import_effect.Schema.String }
+) {
+  name = "ProcessCleanupPolicyError";
+}
+//# sourceMappingURL=ProcessCleanupPolicyError.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/ProcessCleanupPolicyError.ts"],
+  "sourcesContent": ["/**\n * A process cleanup policy that cannot be honoured: a termination signal the\n * platform does not define or cannot deliver, or a grace that overflows a\n * native timer. `policy` reports one as the `cause` of a `PlatformError`.\n *\n * @since 1.0.0\n */\n\nimport { Schema } from \"effect\"\n\n/**\n * Which part of the policy was refused.\n *\n * @category models\n * @since 1.0.0\n */\nexport const ProcessCleanupPolicyErrorCode = Schema.Literals([\"kill_signal_unsupported\", \"grace_out_of_range\"])\n\n/**\n * A cleanup policy outside what a native timer and the platform allow.\n *\n * @category errors\n * @since 1.0.0\n */\nexport class ProcessCleanupPolicyError extends Schema.TaggedError<ProcessCleanupPolicyError>()(\n  \"@smthrs/platform-node/ProcessCleanupPolicyError\",\n  { code: ProcessCleanupPolicyErrorCode, message: Schema.String }\n) {\n  override readonly name = \"ProcessCleanupPolicyError\"\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,oBAAuB;AAQhB,MAAM,gCAAgC,qBAAO,SAAS,CAAC,2BAA2B,oBAAoB,CAAC;AAQvG,MAAM,kCAAkC,qBAAO,YAAuC;AAAA,EAC3F;AAAA,EACA,EAAE,MAAM,+BAA+B,SAAS,qBAAO,OAAO;AAChE,EAAE;AAAA,EACkB,OAAO;AAC3B;",
+  "names": []
+}

package/dist/cjs/internal/ProcessFault.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A process supervision failure that is not a native errno: a supervisor that
+ * broke its status protocol, a bound that was exceeded, or a cleanup that could
+ * not be verified. `ProcessSupervisor` and `WindowsProcessJob` report one as the
+ * `cause` of a `PlatformError`, so a caller classifies it by `_tag` and `code`.
+ * @since 1.0.0
+ */
+import { Schema } from "effect";
+/**
+ * Which supervision rule failed.
+ * @category models
+ * @since 1.0.0
+ */
+export declare const ProcessFaultCode: Schema.Literals<readonly ["supervisor_timeout", "runtime_unsupported", "identity_mismatch", "control_channel_closed", "configuration_too_large", "outcome_missing", "status_too_large", "status_invalid", "status_unknown", "cleanup_unverified", "owner_identity_missing"]>;
+/**
+ * The stable code of a {@link ProcessFault}.
+ * @category models
+ * @since 1.0.0
+ */
+export type ProcessFaultCode = typeof ProcessFaultCode.Type;
+declare const ProcessFault_base: Schema.Class<ProcessFault, Schema.TaggedStruct<"@smthrs/platform-node/ProcessFault", {
+    readonly code: Schema.Literals<readonly ["supervisor_timeout", "runtime_unsupported", "identity_mismatch", "control_channel_closed", "configuration_too_large", "outcome_missing", "status_too_large", "status_invalid", "status_unknown", "cleanup_unverified", "owner_identity_missing"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A supervision failure with a stable code.
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class ProcessFault extends ProcessFault_base {
+    readonly name = "ProcessFault";
+}
+/**
+ * A process fault with a stable code.
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const processFault: (code: ProcessFaultCode, message: string, detail?: {
+    readonly cause?: unknown;
+}) => ProcessFault;
+declare const NativeProcessError_base: Schema.Class<NativeProcessError, Schema.TaggedStruct<"@smthrs/platform-node/NativeProcessError", {
+    readonly message: Schema.String;
+    readonly code: Schema.optional<Schema.String>;
+    readonly errno: Schema.optional<Schema.Number>;
+    readonly reason: Schema.optional<Schema.String>;
+    readonly syscall: Schema.optional<Schema.String>;
+    readonly path: Schema.optional<Schema.String>;
+    readonly signal: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A native process failure as data: the errno (`code`), `syscall`, `path` or
+ * `signal` the platform or the isolated owner reported, kept as fields of the
+ * `PlatformError` cause so callers read the platform's own vocabulary.
+ * `reason` is the stable code the owner program gave its own fault.
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class NativeProcessError extends NativeProcessError_base {
+    readonly name = "NativeProcessError";
+}
+export {};
+//# sourceMappingURL=ProcessFault.d.ts.map

package/dist/cjs/internal/ProcessFault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessFault.d.ts","sourceRoot":"","sources":["../../../src/internal/ProcessFault.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,8QAY3B,CAAA;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;;;;;;AAE3D;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,iBAIhC;IACA,SAAkB,IAAI,kBAAiB;CACxC;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,gBAAgB,EACtB,SAAS,MAAM,EACf,SAAQ;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,KACxC,YAA8D,CAAA;;;;;;;;;;AAEjE;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,uBAWvC;IACC,SAAkB,IAAI,wBAAuB;CAC9C"}

package/dist/cjs/internal/ProcessFault.js

@@ -0,0 +1,63 @@
+"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 ProcessFault_exports = {};
+__export(ProcessFault_exports, {
+  NativeProcessError: () => NativeProcessError,
+  ProcessFault: () => ProcessFault,
+  ProcessFaultCode: () => ProcessFaultCode,
+  processFault: () => processFault
+});
+module.exports = __toCommonJS(ProcessFault_exports);
+var import_effect = require("effect");
+const ProcessFaultCode = import_effect.Schema.Literals([
+  "supervisor_timeout",
+  "runtime_unsupported",
+  "identity_mismatch",
+  "control_channel_closed",
+  "configuration_too_large",
+  "outcome_missing",
+  "status_too_large",
+  "status_invalid",
+  "status_unknown",
+  "cleanup_unverified",
+  "owner_identity_missing"
+]);
+class ProcessFault extends import_effect.Schema.TaggedError()("@smthrs/platform-node/ProcessFault", {
+  code: ProcessFaultCode,
+  message: import_effect.Schema.String,
+  cause: import_effect.Schema.optional(import_effect.Schema.Unknown)
+}) {
+  name = "ProcessFault";
+}
+const processFault = (code, message, detail = {}) => new ProcessFault({ ...detail, code, message });
+class NativeProcessError extends import_effect.Schema.TaggedError()(
+  "@smthrs/platform-node/NativeProcessError",
+  {
+    message: import_effect.Schema.String,
+    code: import_effect.Schema.optional(import_effect.Schema.String),
+    errno: import_effect.Schema.optional(import_effect.Schema.Number),
+    reason: import_effect.Schema.optional(import_effect.Schema.String),
+    syscall: import_effect.Schema.optional(import_effect.Schema.String),
+    path: import_effect.Schema.optional(import_effect.Schema.String),
+    signal: import_effect.Schema.optional(import_effect.Schema.String)
+  }
+) {
+  name = "NativeProcessError";
+}
+//# sourceMappingURL=ProcessFault.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/ProcessFault.ts"],
+  "sourcesContent": ["/**\n * A process supervision failure that is not a native errno: a supervisor that\n * broke its status protocol, a bound that was exceeded, or a cleanup that could\n * not be verified. `ProcessSupervisor` and `WindowsProcessJob` report one as the\n * `cause` of a `PlatformError`, so a caller classifies it by `_tag` and `code`.\n * @since 1.0.0\n */\n\nimport { Schema } from \"effect\"\n\n/**\n * Which supervision rule failed.\n * @category models\n * @since 1.0.0\n */\nexport const ProcessFaultCode = Schema.Literals([\n  \"supervisor_timeout\",\n  \"runtime_unsupported\",\n  \"identity_mismatch\",\n  \"control_channel_closed\",\n  \"configuration_too_large\",\n  \"outcome_missing\",\n  \"status_too_large\",\n  \"status_invalid\",\n  \"status_unknown\",\n  \"cleanup_unverified\",\n  \"owner_identity_missing\"\n])\n\n/**\n * The stable code of a {@link ProcessFault}.\n * @category models\n * @since 1.0.0\n */\nexport type ProcessFaultCode = typeof ProcessFaultCode.Type\n\n/**\n * A supervision failure with a stable code.\n * @category errors\n * @since 1.0.0\n */\nexport class ProcessFault extends Schema.TaggedError<ProcessFault>()(\"@smthrs/platform-node/ProcessFault\", {\n  code: ProcessFaultCode,\n  message: Schema.String,\n  cause: Schema.optional(Schema.Unknown)\n}) {\n  override readonly name = \"ProcessFault\"\n}\n\n/**\n * A process fault with a stable code.\n * @category constructors\n * @since 1.0.0\n */\nexport const processFault = (\n  code: ProcessFaultCode,\n  message: string,\n  detail: { readonly cause?: unknown } = {}\n): ProcessFault => new ProcessFault({ ...detail, code, message })\n\n/**\n * A native process failure as data: the errno (`code`), `syscall`, `path` or\n * `signal` the platform or the isolated owner reported, kept as fields of the\n * `PlatformError` cause so callers read the platform's own vocabulary.\n * `reason` is the stable code the owner program gave its own fault.\n * @category errors\n * @since 1.0.0\n */\nexport class NativeProcessError extends Schema.TaggedError<NativeProcessError>()(\n  \"@smthrs/platform-node/NativeProcessError\",\n  {\n    message: Schema.String,\n    code: Schema.optional(Schema.String),\n    errno: Schema.optional(Schema.Number),\n    reason: Schema.optional(Schema.String),\n    syscall: Schema.optional(Schema.String),\n    path: Schema.optional(Schema.String),\n    signal: Schema.optional(Schema.String)\n  }\n) {\n  override readonly name = \"NativeProcessError\"\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,oBAAuB;AAOhB,MAAM,mBAAmB,qBAAO,SAAS;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAcM,MAAM,qBAAqB,qBAAO,YAA0B,EAAE,sCAAsC;AAAA,EACzG,MAAM;AAAA,EACN,SAAS,qBAAO;AAAA,EAChB,OAAO,qBAAO,SAAS,qBAAO,OAAO;AACvC,CAAC,EAAE;AAAA,EACiB,OAAO;AAC3B;AAOO,MAAM,eAAe,CAC1B,MACA,SACA,SAAuC,CAAC,MACvB,IAAI,aAAa,EAAE,GAAG,QAAQ,MAAM,QAAQ,CAAC;AAUzD,MAAM,2BAA2B,qBAAO,YAAgC;AAAA,EAC7E;AAAA,EACA;AAAA,IACE,SAAS,qBAAO;AAAA,IAChB,MAAM,qBAAO,SAAS,qBAAO,MAAM;AAAA,IACnC,OAAO,qBAAO,SAAS,qBAAO,MAAM;AAAA,IACpC,QAAQ,qBAAO,SAAS,qBAAO,MAAM;AAAA,IACrC,SAAS,qBAAO,SAAS,qBAAO,MAAM;AAAA,IACtC,MAAM,qBAAO,SAAS,qBAAO,MAAM;AAAA,IACnC,QAAQ,qBAAO,SAAS,qBAAO,MAAM;AAAA,EACvC;AACF,EAAE;AAAA,EACkB,OAAO;AAC3B;",
+  "names": []
+}

package/dist/cjs/internal/ProcessSupervisor.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Private parent connection for a POSIX process owner. Effect retains ownership
+ * of the caller's streams; separate sockets carry requests and lifetime status.
+ * @since 1.0.0
+ */
+import type { Lifecycle } from "@smthrs/kernel/ContainedSpawner";
+import * as Effect from "effect/Effect";
+import * as PlatformError from "effect/PlatformError";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import { type ChildProcessHandle, ExitCode } from "effect/unstable/process/ChildProcessSpawner";
+import { type Socket } from "node:net";
+import type { Policy, Snapshot, System } from "./ProcessCleanup.ts";
+/**
+ * Actual service pid, distinct from the owner recorded by the host.
+ * @private
+ * @since 1.0.0
+ */
+export declare const targetPidOf: (handle: ChildProcessHandle) => number | undefined;
+/**
+ * Preserve the platform's errno and signal vocabulary across the private wire.
+ * @private
+ * @since 1.0.0
+ */
+export declare const failure: (method: string, command: string, cause: unknown) => PlatformError.PlatformError;
+/**
+ * The observation behind an unverified cleanup, in the message itself: a
+ * failure report usually shows only the message, and whether the receipt, the
+ * kernel or the snapshot was missing decides host load versus a live survivor.
+ * @private
+ * @since 1.0.0
+ */
+export declare const unverifiedCleanup: (control: {
+    readonly fault: unknown;
+    readonly cleanupFailed: boolean;
+    readonly cleanupAcknowledged: boolean;
+    readonly targetDone: boolean;
+}, cleanupRequired: boolean, vacant: boolean, observed: Snapshot | undefined) => string;
+/**
+ * Standalone application executables do not implement the runtime's eval CLI.
+ * Refuse them before spawning rather than recursively launching the application.
+ * @private
+ * @since 1.0.0
+ */
+export declare const bootstrapArguments: (runtime: {
+    readonly bun: boolean;
+    readonly main: string;
+    readonly sea: boolean;
+}) => Effect.Effect<never, PlatformError.PlatformError, never> | Effect.Effect<string[], never, never>;
+/**
+ * Connect an owner to its authenticated private channel.
+ * @private
+ * @since 1.0.0
+ */
+export declare const connectOwner: (path: string, environment: Readonly<Record<string, string | undefined>>) => Socket;
+/**
+ * Kept separate from Effect scopes so native socket callbacks only settle
+ * promises; none can start an unowned fiber or signal an observed process id.
+ * @private
+ * @since 1.0.0
+ */
+export declare class Control {
+    readonly ready: {
+        promise: Promise<number>;
+        resolve: (value: number) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly started: {
+        promise: Promise<void>;
+        resolve: (value: void) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly exited: {
+        promise: Promise<ExitCode>;
+        resolve: (value: ExitCode) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly lost: {
+        promise: Promise<never>;
+        resolve: (value: never) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly ended: {
+        promise: Promise<void>;
+        resolve: (value: void) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly requestsReady: {
+        promise: Promise<void>;
+        resolve: (value: void) => void;
+        reject: (cause: unknown) => void;
+    };
+    readonly directory: string;
+    readonly path: string;
+    readonly requestPath: string;
+    readonly server: import("node:net").Server;
+    readonly requestServer: import("node:net").Server;
+    readonly listening: Promise<void>;
+    private readonly key;
+    private readonly connections;
+    socket: Socket | undefined;
+    requestSocket: Socket | undefined;
+    targetDone: boolean;
+    ownerCreation: unknown;
+    targetPid: number | undefined;
+    /** The owner's group guardian: a member that is neither target nor owner. */
+    guardianPid: number | undefined;
+    ownerDone: boolean;
+    spawnFailed: boolean;
+    cleanupFailed: boolean;
+    cleanupAcknowledged: boolean;
+    activationSent: boolean;
+    closeSent: boolean;
+    fault: unknown;
+    onTargetExit: () => void;
+    onCleanup: () => void;
+    private receivedReady;
+    private receivedStarted;
+    private withdrawn;
+    constructor(transport?: "native" | "tls");
+    private makeServer;
+    /** Only the trusted owner receives this environment; target configuration replaces it. */
+    environment(): Readonly<Record<string, string>>;
+    /** The test peer uses the same authenticated transport as the isolated owner. */
+    connect(requests?: boolean): Socket;
+    /** Validate the stored READY after the raw spawn effect has returned its pid. */
+    withdraw(pid: number, actual: number): void;
+    /** Request EOF asks for cleanup; leave its independent status reader intact. */
+    disconnect(): void;
+    dispose(): void;
+    rawEnded(): void;
+    write(message: unknown): Promise<void>;
+    private closed;
+    private acceptRequests;
+    private accept;
+    private receive;
+}
+/**
+ * Prepare a private, independently bounded process owner before target launch.
+ * @private
+ * @since 1.0.0
+ */
+export declare const prepare: (system: System, policy: (options: ChildProcess.KillOptions, defaults?: ChildProcess.KillOptions) => Effect.Effect<Policy, PlatformError.PlatformError>, transport?: "native" | "tls") => Lifecycle;
+//# sourceMappingURL=ProcessSupervisor.d.ts.map

package/dist/cjs/internal/ProcessSupervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessSupervisor.d.ts","sourceRoot":"","sources":["../../../src/internal/ProcessSupervisor.ts"],"names":[],"mappings":"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"}