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

package/dist/esm/internal/ProcSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcSnapshot.js","sourceRoot":"","sources":["../../../src/internal/ProcSnapshot.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Process-group observation read from Linux `/proc`, with no `ps` binary.\n * @since 1.0.0\n */\n\nimport { readdirSync, readFileSync } from \"node:fs\"\nimport type * as ProcessCleanup from \"./ProcessCleanup.ts\"\n\n/**\n * The kernel's own process table, which is the production root.\n * @private\n * @since 1.0.0\n */\nexport const defaultProcRoot = \"/proc\"\n\n/**\n * The `/proc` root a platform publishes its process table under, if any.\n * @private\n * @since 1.0.0-rc.1\n */\nexport const rootFor = (platform: string): string | undefined => platform === \"linux\" ? defaultProcRoot : undefined\n\n/**\n * `/proc` reports `starttime` in USER_HZ, which Linux fixes at 100 for this\n * interface however the running kernel is configured.\n */\nconst userHz = 100\n\n/** A pid, as both a directory name and the first field of a stat line. */\nconst pidName = /^[0-9]+$/\n\n/** `/proc/stat`'s boot instant, in seconds since the epoch. */\nconst bootLine = /^btime[ \\t]+([0-9]+)$/m\n\n/** Fields 3 through 22 inclusive: state, then pgrp third, then starttime. */\nconst statFieldsAfterComm = 20\n\n/** A read that failed because the file is no longer there. */\nconst missing = (cause: unknown): boolean => (cause as NodeJS.ErrnoException).code === \"ENOENT\"\n\n/**\n * One process's group, zombie state and start time, from a `/proc/<pid>/stat`\n * line.\n *\n * `comm` is the second field, it is wrapped in parentheses, and a process may\n * put both spaces and parentheses inside it, so the numeric fields after it are\n * taken from the LAST `)` rather than by splitting the whole line. The first\n * field after that paren is field 3, so field N is at index N - 3.\n *\n * Anything that is not a stat line in that shape answers `undefined` rather\n * than a record built out of whichever fields happened to parse.\n * @private\n * @since 1.0.0\n */\nexport const parseStat = (\n  text: string,\n  bootMs: number\n): { readonly pgid: number; readonly member: ProcessCleanup.Member } | undefined => {\n  const open = text.indexOf(\"(\")\n  const close = text.lastIndexOf(\")\")\n  if (open <= 0 || close < open) return undefined\n  const head = text.slice(0, open).trim()\n  if (!pidName.test(head)) return undefined\n  const after = text.slice(close + 1).trim().split(/[ \\t]+/)\n  if (after.length < statFieldsAfterComm) return undefined\n  const pid = Number(head)\n  const pgid = Number(after[2])\n  const startedTicks = Number(after[19])\n  if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(pgid) || !Number.isSafeInteger(startedTicks)) {\n    return undefined\n  }\n  return {\n    pgid,\n    // A zombie holds a slot without being a process the caller has to wait for,\n    // so the distinction has to survive the read.\n    member: { pid, startedAtMs: bootMs + Math.round((startedTicks / userHz) * 1000), zombie: after[0] === \"Z\" }\n  }\n}\n\n/**\n * Every member of `pgid`, plus this process's own group, read from `/proc`.\n *\n * Answering `undefined` means the question could not be asked here, which is\n * what a non-Linux host and a `hidepid` mount both produce; the caller keeps\n * its record rather than acting on a table it could not read. A pid that\n * disappears between listing the directory and reading its `stat` is not an\n * unreadable table: it is a process that ended, which is the same end state as\n * never having been in the group, so it is skipped.\n * @private\n * @since 1.0.0\n */\nexport const snapshot = (root: string) => (pgid: number): ProcessCleanup.Snapshot | undefined => {\n  let bootMs: number\n  let ownGroup: number\n  let names: ReadonlyArray<string>\n  try {\n    const boot = bootLine.exec(readFileSync(`${root}/stat`, \"utf8\"))\n    if (boot === null) return undefined\n    bootMs = Number(boot[1]) * 1000\n    if (!Number.isSafeInteger(bootMs)) return undefined\n    const self = parseStat(readFileSync(`${root}/self/stat`, \"utf8\"), bootMs)\n    if (self === undefined || self.pgid <= 0) return undefined\n    ownGroup = self.pgid\n    names = readdirSync(root)\n  } catch {\n    return undefined\n  }\n  const members: Array<ProcessCleanup.Member> = []\n  for (const name of names) {\n    if (!pidName.test(name)) continue\n    let text: string\n    try {\n      text = readFileSync(`${root}/${name}/stat`, \"utf8\")\n    } catch (cause) {\n      if (missing(cause)) continue\n      return undefined\n    }\n    const parsed = parseStat(text, bootMs)\n    if (parsed === undefined) return undefined\n    if (parsed.pgid !== pgid) continue\n    members.push(parsed.member)\n  }\n  return { ownGroup, members }\n}\n\n/**\n * This machine's boot instant from `${root}/stat`, in epoch milliseconds, or\n * `undefined` when the table cannot be read here.\n * @private\n * @since 1.0.0\n */\nexport const bootMs = (root: string): number | undefined => {\n  try {\n    const boot = bootLine.exec(readFileSync(`${root}/stat`, \"utf8\"))\n    if (boot === null) return undefined\n    const ms = Number(boot[1]) * 1000\n    return Number.isSafeInteger(ms) ? ms : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * This process's own process group, read from `/proc/self/stat`, or `null`\n * when the file cannot be read or parsed.\n *\n * The reaper's own-group guard needs this number before it may signal any\n * group. Reading it here instead of from `ps` keeps the guard working on a\n * Linux image that ships no `procps`.\n * @private\n * @since 1.0.0\n */\nexport const ownGroup = (root: string) => (): number | null => {\n  try {\n    const self = parseStat(readFileSync(`${root}/self/stat`, \"utf8\"), 0)\n    return self === undefined || self.pgid <= 0 ? null : self.pgid\n  } catch {\n    return null\n  }\n}\n\n/**\n * When `pid` started, in epoch milliseconds, read from `/proc/<pid>/stat` and\n * `/proc/stat`'s `btime`.\n *\n * `gone` is the table having no entry for the pid (`ENOENT`). Every other\n * failure is `unavailable`: the question could not be asked, so the caller\n * keeps its record instead of acting on it.\n * @private\n * @since 1.0.0\n */\nexport const startedAtMs = (root: string) =>\n(\n  pid: number\n):\n  | { readonly _tag: \"started\"; readonly startedAtMs: number }\n  | { readonly _tag: \"gone\" }\n  | { readonly _tag: \"unavailable\" } =>\n{\n  if (!Number.isSafeInteger(pid) || pid <= 0) return { _tag: \"unavailable\" }\n  const boot = bootMs(root)\n  if (boot === undefined) return { _tag: \"unavailable\" }\n  let text: string\n  try {\n    text = readFileSync(`${root}/${pid}/stat`, \"utf8\")\n  } catch (cause) {\n    return missing(cause) ? { _tag: \"gone\" } : { _tag: \"unavailable\" }\n  }\n  const parsed = parseStat(text, boot)\n  return parsed === undefined || parsed.member.pid !== pid\n    ? { _tag: \"unavailable\" }\n    : { _tag: \"started\", startedAtMs: parsed.member.startedAtMs }\n}\n"]}

package/dist/esm/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/esm/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/esm/internal/ProcessCleanup.js

@@ -0,0 +1,45 @@
+/**
+ * Prepared process ownership and bounded release for Node and Bun hosts.
+ * @since 1.0.0
+ */
+import { defaultGraceMs } from "@smthrs/kernel/ContainedSpawner";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { constants } from "node:os";
+import { ProcessCleanupPolicyError } from "./ProcessCleanupPolicyError.js";
+import * as Supervisor from "./ProcessSupervisor.js";
+/**
+ * Normalize and validate the deadline before it enters a native timer.
+ * @private
+ * @since 1.0.0
+ */
+export const policy = (options, defaults = {}) => Effect.try({
+    try: () => {
+        const killSignal = options.killSignal ?? defaults.killSignal ?? "SIGTERM";
+        if (killSignal === "SIGSTOP" || constants.signals[killSignal] === undefined) {
+            throw new ProcessCleanupPolicyError({
+                code: "kill_signal_unsupported",
+                message: `Unsupported process termination signal ${killSignal}`
+            });
+        }
+        const graceMs = Duration.toMillis(options.forceKillAfter ?? defaults.forceKillAfter ?? defaultGraceMs);
+        // Node/Bun clamp an overflowing timeout to 1 ms. Refuse that policy rather
+        // than silently replacing a caller's grace with immediate termination.
+        if (!Number.isFinite(graceMs) || graceMs < 0 || graceMs > 2_147_483_647) {
+            throw new 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)
+});
+/**
+ * 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 const lifecycle = (system) => Supervisor.prepare(system, policy);
+//# sourceMappingURL=ProcessCleanup.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessCleanup.js","sourceRoot":"","sources":["../../../src/internal/ProcessCleanup.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAkB,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAA;AAC1E,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AAgDpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,OAAiC,EACjC,WAAqC,EAAE,EACa,EAAE,CACtD,MAAM,CAAC,GAAG,CAAC;IACT,GAAG,EAAE,GAAG,EAAE;QACR,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,IAAI,SAAS,CAAA;QACzE,IAAI,UAAU,KAAK,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5E,MAAM,IAAI,yBAAyB,CAAC;gBAClC,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,0CAA0C,UAAU,EAAE;aAChE,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,cAAc,IAAI,QAAQ,CAAC,cAAc,IAAI,cAAc,CAAC,CAAA;QACtG,2EAA2E;QAC3E,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,aAAa,EAAE,CAAC;YACxE,MAAM,IAAI,yBAAyB,CAAC;gBAClC,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,kEAAkE;aAC5E,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;IAChC,CAAC;IACD,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,wBAAwB,EAAE,KAAK,CAAC;CAC9E,CAAC,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAa,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA","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"]}

package/dist/esm/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/esm/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/esm/internal/ProcessCleanupPolicyError.js

@@ -0,0 +1,25 @@
+/**
+ * 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 const ProcessCleanupPolicyErrorCode = Schema.Literals(["kill_signal_unsupported", "grace_out_of_range"]);
+/**
+ * A cleanup policy outside what a native timer and the platform allow.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export class ProcessCleanupPolicyError extends Schema.TaggedError()("@smthrs/platform-node/ProcessCleanupPolicyError", { code: ProcessCleanupPolicyErrorCode, message: Schema.String }) {
+    name = "ProcessCleanupPolicyError";
+}
+//# sourceMappingURL=ProcessCleanupPolicyError.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessCleanupPolicyError.js","sourceRoot":"","sources":["../../../src/internal/ProcessCleanupPolicyError.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,yBAAyB,EAAE,oBAAoB,CAAC,CAAC,CAAA;AAE/G;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,MAAM,CAAC,WAAW,EAA6B,CAC5F,iDAAiD,EACjD,EAAE,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,CAChE;IACmB,IAAI,GAAG,2BAA2B,CAAA;CACrD","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"]}

package/dist/esm/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/esm/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/esm/internal/ProcessFault.js

@@ -0,0 +1,64 @@
+/**
+ * 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 const ProcessFaultCode = 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"
+]);
+/**
+ * A supervision failure with a stable code.
+ * @category errors
+ * @since 1.0.0
+ */
+export class ProcessFault extends Schema.TaggedError()("@smthrs/platform-node/ProcessFault", {
+    code: ProcessFaultCode,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown)
+}) {
+    name = "ProcessFault";
+}
+/**
+ * A process fault with a stable code.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const processFault = (code, message, detail = {}) => new ProcessFault({ ...detail, code, message });
+/**
+ * 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 class NativeProcessError extends Schema.TaggedError()("@smthrs/platform-node/NativeProcessError", {
+    message: Schema.String,
+    code: Schema.optional(Schema.String),
+    errno: Schema.optional(Schema.Number),
+    reason: Schema.optional(Schema.String),
+    syscall: Schema.optional(Schema.String),
+    path: Schema.optional(Schema.String),
+    signal: Schema.optional(Schema.String)
+}) {
+    name = "NativeProcessError";
+}
+//# sourceMappingURL=ProcessFault.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessFault.js","sourceRoot":"","sources":["../../../src/internal/ProcessFault.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC9C,oBAAoB;IACpB,qBAAqB;IACrB,mBAAmB;IACnB,wBAAwB;IACxB,yBAAyB;IACzB,iBAAiB;IACjB,kBAAkB;IAClB,gBAAgB;IAChB,gBAAgB;IAChB,oBAAoB;IACpB,wBAAwB;CACzB,CAAC,CAAA;AASF;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,MAAM,CAAC,WAAW,EAAgB,CAAC,oCAAoC,EAAE;IACzG,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CACvC,CAAC;IACkB,IAAI,GAAG,cAAc,CAAA;CACxC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,IAAsB,EACtB,OAAe,EACf,SAAuC,EAAE,EAC3B,EAAE,CAAC,IAAI,YAAY,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAA;AAEjE;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,MAAM,CAAC,WAAW,EAAsB,CAC9E,0CAA0C,EAC1C;IACE,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CACvC,CACF;IACmB,IAAI,GAAG,oBAAoB,CAAA;CAC9C","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"]}

package/dist/esm/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/esm/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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"}