@smthrs/kernel 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/CommandLine.js

@@ -0,0 +1,195 @@
+/**
+ * @since 1.0.0-rc.0
+ *
+ * Rendering an `effect/unstable/process` `Command` back to a shell command
+ * line.
+ *
+ * Two callers need the same string and must agree on it exactly:
+ *
+ *  1. `@smthrs/kernel/ChildProcessSpawner` uses it as the `proc:spawn`
+ *     capability resource, so a grant reads the way an operator wrote it; and
+ *  2. `@smthrs/platform-browser/BrowserChildProcessSpawner` uses it as the line
+ *     it hands to the in-browser bash interpreter, which has no `argv` to spawn
+ *     with.
+ *
+ * A single renderer keeps a granted capability and the command a browser
+ * actually runs from drifting apart.
+ *
+ * The module is pure string handling — no host access — so it stays on the
+ * browser-safe side of the package.
+ */
+import { isInheritedName } from "./ChildProcessEnvironment.js";
+/** Tokens made only of these characters need no quoting in a POSIX shell. */
+const SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/**
+ * Quotes one token for a POSIX shell, leaving obviously safe tokens alone.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export const quote = (token) => token !== "" && SAFE.test(token) ? token : `'${token.replaceAll("'", `'\\''`)}'`;
+/**
+ * Renders a `Command` as a single shell command line.
+ *
+ * A standard command with `shell: true` renders its tokens verbatim, matching
+ * the line Node and the browser interpreter hand to the default shell. A
+ * custom shell renders as an explicit `<shell> -c <line>` invocation so the
+ * selected executable is part of the permission resource. Without `shell`,
+ * every token is POSIX-quoted to preserve literal argv semantics. These
+ * distinctions are security-sensitive: the rendered value is also the
+ * `proc:spawn` capability resource, so it must describe what will execute.
+ * The rendering is POSIX-only by contract: on Windows, Node invokes the shell
+ * with `/d /s /c` rather than `-c`, so the rendered line describes the POSIX
+ * invocation, not a cmd.exe one.
+ *
+ * The `proc:spawn` capability resource is {@link resource}, which starts from
+ * this line and adds what the line alone cannot show.
+ *
+ * A `PipedCommand` renders with `|` between its sides. That is a faithful
+ * rendering of what the pipeline does, and it is the only form an interpreter
+ * that takes a command line rather than an `argv` can be given. `from`/`to`
+ * pipe options are *not* expressible this way; rendering ignores them, so a
+ * pipeline that redirects `stderr` renders like one that pipes `stdout`.
+ * Capability checks therefore see the commands, never the plumbing.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export const render = (command) => command._tag === "StandardCommand"
+    ? command.options.shell === undefined || command.options.shell === false
+        ? [command.command, ...command.args].map(quote).join(" ")
+        : command.options.shell === true
+            ? [command.command, ...command.args].join(" ")
+            : `${quote(command.options.shell)} -c ${quote([command.command, ...command.args].join(" "))}`
+    : `${render(command.left)} | ${render(command.right)}`;
+/**
+ * Shell syntax that chains, substitutes, groups, or redirects: everything that
+ * lets one shell line run or write more than a single simple command.
+ */
+const shellControl = /[;&|`$<>()\n\r]/;
+/**
+ * Redirections that neither run nor write anything a grant should see: an fd
+ * duplication such as `2>&1` and a discard to `/dev/null`. They are removed
+ * before {@link shellControl} is tested, so `git status 2>&1` keeps its
+ * verbatim resource. Only a space or tab may sit between `>` and `/dev/null`:
+ * `>` followed by a line break is not a discard, so it stays control syntax.
+ */
+const harmlessRedirect = /(^|\s)(?:\d*>&\d+|\d*>[ \t]*\/dev\/null)(?=\s|$)/g;
+/**
+ * Names of the environment variables a stage sets that the child would not
+ * otherwise inherit: every name outside the bootstrap set, and a bootstrap
+ * name whose value differs from the ambient one.
+ */
+const overriddenNames = (command, ambient) => Object.entries(command.options.env ?? {})
+    .filter(([name, value]) => value !== undefined && (!isInheritedName(name) || ambient[name] !== value))
+    .map(([name]) => name)
+    .sort();
+/**
+ * The stages of a command in execution order: the command itself, or every
+ * `StandardCommand` of a pipeline from left to right. The spawner checks each
+ * stage as its own `proc:spawn` capability.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.1
+ */
+export const stages = (command) => command._tag === "StandardCommand" ? [command] : [...stages(command.left), ...stages(command.right)];
+/**
+ * The `proc:spawn` capability resource for one stage: {@link render}, with
+ * three additions that keep a prefix grant from authorizing code the stage
+ * never named.
+ *
+ *  - A `shell: true` stage whose line holds shell control syntax (`;`, `&`,
+ *    `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`, or a line break) is marked as the
+ *    explicit `sh -c '<line>'` it is. A grant such as `git status *` then
+ *    cannot match `git status; curl x | sh`, while a simple shell line such as
+ *    `git status --short` keeps its verbatim resource. An fd duplication such
+ *    as `2>&1` and a discard to `/dev/null` do not count as control syntax.
+ *  - A stage that sets an environment variable the child would not otherwise
+ *    inherit is prefixed with `env <NAME>… -- `, sorted names only. That is
+ *    every name outside the bootstrap set `ChildProcessEnvironment` inherits
+ *    (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`, `SHELL`, `LC_*`), and a
+ *    bootstrap name whose value differs from `context.ambient`. A grant for
+ *    `git status` covers neither `env GIT_SSH_COMMAND -- git status` nor
+ *    `env PATH -- git status`. Values never enter the resource because they
+ *    often carry credentials.
+ *  - A stage whose `cwd` `context.contains` rejects is prefixed with
+ *    `cwd <path> -- `, so a grant does not follow the command into a
+ *    directory whose configuration the flow does not govern. When
+ *    `context.resolvedCwd` is given, that real path is judged and named
+ *    instead of the lexical `cwd`.
+ *
+ * A pipeline has no single resource: the spawner checks every one of its
+ * {@link stages}, so `git status | sh` needs a grant for `sh` too.
+ *
+ * The `env` and `cwd` prefixes share their spelling with a literal command:
+ * `make("env", ["PATH", "--", "git", "status"])` renders as
+ * `env PATH -- git status`, the resource of `git status` with `PATH`
+ * overridden. The alias grants nothing extra. The literal command runs a
+ * program named `PATH` (or `cwd`) from the ambient `PATH`, not `git`. A grant
+ * with `*` inside the prefix, such as `env * -- git status`, also matches
+ * `env -C /x -- git status`, but it already admits any variable name,
+ * including `GIT_SSH_COMMAND` and `LD_PRELOAD`, which run arbitrary code.
+ * Grant a prefixed resource exactly as the request shows it.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.1
+ */
+export const resource = (command, context = {}) => {
+    const line = render(command);
+    const shown = command.options.shell === true && shellControl.test(line.replace(harmlessRedirect, "$1"))
+        ? `sh -c ${quote(line)}`
+        : line;
+    const names = overriddenNames(command, context.ambient ?? {});
+    const withEnv = names.length === 0 ? shown : `env ${names.map(quote).join(" ")} -- ${shown}`;
+    const directory = command.options.cwd === undefined ? undefined : context.resolvedCwd ?? command.options.cwd;
+    return directory === undefined || context.contains?.(directory) === true
+        ? withEnv
+        : `cwd ${quote(directory)} -- ${withEnv}`;
+};
+/** The leading token of a shell line, which is the program the line runs. */
+const program = (line) => {
+    const trimmed = line.trimStart();
+    const end = trimmed.search(/\s/);
+    return end === -1 ? trimmed : trimmed.slice(0, end);
+};
+/**
+ * The executable a command runs, without its arguments.
+ *
+ * A durable record of a spawned process names its program with this rather
+ * than with {@link render}: arguments carry credentials (`curl -u user:pass`,
+ * `mysql -phunter2`), and a journal that keeps them keeps them permanently.
+ * Nothing that reads such a record needs more than the program name; a reaper
+ * matches processes by pid and process group.
+ *
+ * Without `shell`, `command` is the executable itself, spaces and all. With a
+ * shell, the line is what runs, so the program is its first token: both
+ * `make("mysql -phunter2", [], { shell: true })` and
+ * `make("mysql", ["-phunter2"])` yield `mysql`. A pipeline names one
+ * executable per stage, joined the way {@link render} joins the stages.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export const executable = (command) => command._tag === "StandardCommand"
+    ? command.options.shell === undefined || command.options.shell === false
+        ? command.command
+        : program(command.command)
+    : `${executable(command.left)} | ${executable(command.right)}`;
+/**
+ * The working directory a command runs in, taking the leftmost stage of a
+ * pipeline, which is the stage `setCwd` and the spawners agree to treat as the
+ * pipeline's own directory.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export const cwd = (command) => command._tag === "StandardCommand" ? command.options.cwd : cwd(command.left);
+/**
+ * The environment overrides a command runs with, taking the leftmost stage of
+ * a pipeline for the same reason {@link cwd} does.
+ *
+ * @category rendering
+ * @since 1.0.0-rc.0
+ */
+export const env = (command) => command._tag === "StandardCommand" ? command.options.env : env(command.left);
+//# sourceMappingURL=CommandLine.js.map

package/dist/esm/CommandLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandLine.js","sourceRoot":"","sources":["../../src/CommandLine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @since 1.0.0-rc.0\n *\n * Rendering an `effect/unstable/process` `Command` back to a shell command\n * line.\n *\n * Two callers need the same string and must agree on it exactly:\n *\n *  1. `@smthrs/kernel/ChildProcessSpawner` uses it as the `proc:spawn`\n *     capability resource, so a grant reads the way an operator wrote it; and\n *  2. `@smthrs/platform-browser/BrowserChildProcessSpawner` uses it as the line\n *     it hands to the in-browser bash interpreter, which has no `argv` to spawn\n *     with.\n *\n * A single renderer keeps a granted capability and the command a browser\n * actually runs from drifting apart.\n *\n * The module is pure string handling — no host access — so it stays on the\n * browser-safe side of the package.\n */\n\nimport type * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport { isInheritedName } from \"./ChildProcessEnvironment.ts\"\n\n/** Tokens made only of these characters need no quoting in a POSIX shell. */\nconst SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/\n\n/**\n * Quotes one token for a POSIX shell, leaving obviously safe tokens alone.\n *\n * @category rendering\n * @since 1.0.0-rc.0\n */\nexport const quote = (token: string): string =>\n  token !== \"\" && SAFE.test(token) ? token : `'${token.replaceAll(\"'\", `'\\\\''`)}'`\n\n/**\n * Renders a `Command` as a single shell command line.\n *\n * A standard command with `shell: true` renders its tokens verbatim, matching\n * the line Node and the browser interpreter hand to the default shell. A\n * custom shell renders as an explicit `<shell> -c <line>` invocation so the\n * selected executable is part of the permission resource. Without `shell`,\n * every token is POSIX-quoted to preserve literal argv semantics. These\n * distinctions are security-sensitive: the rendered value is also the\n * `proc:spawn` capability resource, so it must describe what will execute.\n * The rendering is POSIX-only by contract: on Windows, Node invokes the shell\n * with `/d /s /c` rather than `-c`, so the rendered line describes the POSIX\n * invocation, not a cmd.exe one.\n *\n * The `proc:spawn` capability resource is {@link resource}, which starts from\n * this line and adds what the line alone cannot show.\n *\n * A `PipedCommand` renders with `|` between its sides. That is a faithful\n * rendering of what the pipeline does, and it is the only form an interpreter\n * that takes a command line rather than an `argv` can be given. `from`/`to`\n * pipe options are *not* expressible this way; rendering ignores them, so a\n * pipeline that redirects `stderr` renders like one that pipes `stdout`.\n * Capability checks therefore see the commands, never the plumbing.\n *\n * @category rendering\n * @since 1.0.0-rc.0\n */\nexport const render = (command: ChildProcess.Command): string =>\n  command._tag === \"StandardCommand\"\n    ? command.options.shell === undefined || command.options.shell === false\n      ? [command.command, ...command.args].map(quote).join(\" \")\n      : command.options.shell === true\n      ? [command.command, ...command.args].join(\" \")\n      : `${quote(command.options.shell)} -c ${quote([command.command, ...command.args].join(\" \"))}`\n    : `${render(command.left)} | ${render(command.right)}`\n\n/**\n * Shell syntax that chains, substitutes, groups, or redirects: everything that\n * lets one shell line run or write more than a single simple command.\n */\nconst shellControl = /[;&|`$<>()\\n\\r]/\n\n/**\n * Redirections that neither run nor write anything a grant should see: an fd\n * duplication such as `2>&1` and a discard to `/dev/null`. They are removed\n * before {@link shellControl} is tested, so `git status 2>&1` keeps its\n * verbatim resource. Only a space or tab may sit between `>` and `/dev/null`:\n * `>` followed by a line break is not a discard, so it stays control syntax.\n */\nconst harmlessRedirect = /(^|\\s)(?:\\d*>&\\d+|\\d*>[ \\t]*\\/dev\\/null)(?=\\s|$)/g\n\n/**\n * What {@link resource} compares a stage against, supplied by the spawner that\n * checks it.\n *\n * @category models\n * @since 1.0.0-rc.1\n */\nexport interface ResourceContext {\n  /**\n   * The environment the spawning process itself holds. A bootstrap name\n   * (`PATH`, `HOME`, ...) whose declared value equals the ambient value is the\n   * inherited default and stays out of the resource; one set to anything else\n   * is named. Omitted, every declared bootstrap name is named.\n   */\n  readonly ambient?: Readonly<Record<string, string | undefined>> | undefined\n  /**\n   * Whether a stage's working directory is inside the directory the flow\n   * already governs. A `cwd` it rejects is named in the resource. Omitted,\n   * every `cwd` a stage sets is named.\n   */\n  readonly contains?: ((directory: string) => boolean) | undefined\n  /**\n   * The stage `cwd` with every symlink resolved, when the host could resolve\n   * it. It replaces the lexical `cwd` both for `contains` and in the\n   * `cwd <path> -- ` prefix, so a symlink inside the governed directory that\n   * leads out of it is judged, and shown, by where the command really runs.\n   */\n  readonly resolvedCwd?: string | undefined\n}\n\n/**\n * Names of the environment variables a stage sets that the child would not\n * otherwise inherit: every name outside the bootstrap set, and a bootstrap\n * name whose value differs from the ambient one.\n */\nconst overriddenNames = (\n  command: ChildProcess.StandardCommand,\n  ambient: Readonly<Record<string, string | undefined>>\n): ReadonlyArray<string> =>\n  Object.entries(command.options.env ?? {})\n    .filter(([name, value]) => value !== undefined && (!isInheritedName(name) || ambient[name] !== value))\n    .map(([name]) => name)\n    .sort()\n\n/**\n * The stages of a command in execution order: the command itself, or every\n * `StandardCommand` of a pipeline from left to right. The spawner checks each\n * stage as its own `proc:spawn` capability.\n *\n * @category rendering\n * @since 1.0.0-rc.1\n */\nexport const stages = (command: ChildProcess.Command): ReadonlyArray<ChildProcess.StandardCommand> =>\n  command._tag === \"StandardCommand\" ? [command] : [...stages(command.left), ...stages(command.right)]\n\n/**\n * The `proc:spawn` capability resource for one stage: {@link render}, with\n * three additions that keep a prefix grant from authorizing code the stage\n * never named.\n *\n *  - A `shell: true` stage whose line holds shell control syntax (`;`, `&`,\n *    `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`, or a line break) is marked as the\n *    explicit `sh -c '<line>'` it is. A grant such as `git status *` then\n *    cannot match `git status; curl x | sh`, while a simple shell line such as\n *    `git status --short` keeps its verbatim resource. An fd duplication such\n *    as `2>&1` and a discard to `/dev/null` do not count as control syntax.\n *  - A stage that sets an environment variable the child would not otherwise\n *    inherit is prefixed with `env <NAME>… -- `, sorted names only. That is\n *    every name outside the bootstrap set `ChildProcessEnvironment` inherits\n *    (`PATH`, `HOME`, `USER`, `LANG`, `TERM`, `TMPDIR`, `SHELL`, `LC_*`), and a\n *    bootstrap name whose value differs from `context.ambient`. A grant for\n *    `git status` covers neither `env GIT_SSH_COMMAND -- git status` nor\n *    `env PATH -- git status`. Values never enter the resource because they\n *    often carry credentials.\n *  - A stage whose `cwd` `context.contains` rejects is prefixed with\n *    `cwd <path> -- `, so a grant does not follow the command into a\n *    directory whose configuration the flow does not govern. When\n *    `context.resolvedCwd` is given, that real path is judged and named\n *    instead of the lexical `cwd`.\n *\n * A pipeline has no single resource: the spawner checks every one of its\n * {@link stages}, so `git status | sh` needs a grant for `sh` too.\n *\n * The `env` and `cwd` prefixes share their spelling with a literal command:\n * `make(\"env\", [\"PATH\", \"--\", \"git\", \"status\"])` renders as\n * `env PATH -- git status`, the resource of `git status` with `PATH`\n * overridden. The alias grants nothing extra. The literal command runs a\n * program named `PATH` (or `cwd`) from the ambient `PATH`, not `git`. A grant\n * with `*` inside the prefix, such as `env * -- git status`, also matches\n * `env -C /x -- git status`, but it already admits any variable name,\n * including `GIT_SSH_COMMAND` and `LD_PRELOAD`, which run arbitrary code.\n * Grant a prefixed resource exactly as the request shows it.\n *\n * @category rendering\n * @since 1.0.0-rc.1\n */\nexport const resource = (command: ChildProcess.StandardCommand, context: ResourceContext = {}): string => {\n  const line = render(command)\n  const shown = command.options.shell === true && shellControl.test(line.replace(harmlessRedirect, \"$1\"))\n    ? `sh -c ${quote(line)}`\n    : line\n  const names = overriddenNames(command, context.ambient ?? {})\n  const withEnv = names.length === 0 ? shown : `env ${names.map(quote).join(\" \")} -- ${shown}`\n  const directory = command.options.cwd === undefined ? undefined : context.resolvedCwd ?? command.options.cwd\n  return directory === undefined || context.contains?.(directory) === true\n    ? withEnv\n    : `cwd ${quote(directory)} -- ${withEnv}`\n}\n\n/** The leading token of a shell line, which is the program the line runs. */\nconst program = (line: string): string => {\n  const trimmed = line.trimStart()\n  const end = trimmed.search(/\\s/)\n  return end === -1 ? trimmed : trimmed.slice(0, end)\n}\n\n/**\n * The executable a command runs, without its arguments.\n *\n * A durable record of a spawned process names its program with this rather\n * than with {@link render}: arguments carry credentials (`curl -u user:pass`,\n * `mysql -phunter2`), and a journal that keeps them keeps them permanently.\n * Nothing that reads such a record needs more than the program name; a reaper\n * matches processes by pid and process group.\n *\n * Without `shell`, `command` is the executable itself, spaces and all. With a\n * shell, the line is what runs, so the program is its first token: both\n * `make(\"mysql -phunter2\", [], { shell: true })` and\n * `make(\"mysql\", [\"-phunter2\"])` yield `mysql`. A pipeline names one\n * executable per stage, joined the way {@link render} joins the stages.\n *\n * @category rendering\n * @since 1.0.0-rc.0\n */\nexport const executable = (command: ChildProcess.Command): string =>\n  command._tag === \"StandardCommand\"\n    ? command.options.shell === undefined || command.options.shell === false\n      ? command.command\n      : program(command.command)\n    : `${executable(command.left)} | ${executable(command.right)}`\n\n/**\n * The working directory a command runs in, taking the leftmost stage of a\n * pipeline, which is the stage `setCwd` and the spawners agree to treat as the\n * pipeline's own directory.\n *\n * @category rendering\n * @since 1.0.0-rc.0\n */\nexport const cwd = (command: ChildProcess.Command): string | undefined =>\n  command._tag === \"StandardCommand\" ? command.options.cwd : cwd(command.left)\n\n/**\n * The environment overrides a command runs with, taking the leftmost stage of\n * a pipeline for the same reason {@link cwd} does.\n *\n * @category rendering\n * @since 1.0.0-rc.0\n */\nexport const env = (\n  command: ChildProcess.Command\n): Record<string, string | undefined> | undefined =>\n  command._tag === \"StandardCommand\" ? command.options.env : env(command.left)\n"]}

package/dist/esm/ContainedSpawner.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Process containment: prepared ownership, bounded cleanup and durable records.
+ *
+ * A host supplies a {@link Lifecycle} that owns launch and cleanup independently
+ * of the command's exit status. The lifecycle first prepares a process identity;
+ * this decorator commits that identity to {@link ProcessLedger.ProcessLedger}
+ * before activating the caller's command. Failed or interrupted startup closes
+ * its child scope immediately, including any earlier legs of a partial pipeline.
+ *
+ * Each command receives default termination and escalation options. The host
+ * lifecycle validates that policy and verifies cleanup before the decorator
+ * retires its record. Unverifiable cleanup retains the record for recovery;
+ * a host that dies also leaves its committed records discoverable by the next
+ * incarnation's reaper (`ProcessReaper` in `@smthrs/platform-node`).
+ *
+ * Every pipeline leg is prepared and recorded separately, including legs whose
+ * pid the aggregate handle does not expose. The module remains platform-neutral.
+ * A layer without a lifecycle provides only deadline defaults and bookkeeping;
+ * it does not declare the verified-cleanup contract read by {@link isContained}.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Host Adapters.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as PlatformError from "effect/PlatformError";
+import * as Scope from "effect/Scope";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import { type ChildProcessHandle, ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import * as ProcessLedger from "./ProcessLedger.ts";
+/**
+ * How long a contained child may take to honour `SIGTERM`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultGraceMs = 2000;
+/**
+ * Containment configuration.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    /**
+     * Milliseconds between the `SIGTERM` that asks a child to stop and the
+     * `SIGKILL` that makes it. Default {@link defaultGraceMs}.
+     */
+    readonly graceMs?: number | undefined;
+    /**
+     * The platform the host spawner runs on, as `process.platform` spells it.
+     * Windows records no POSIX process group, including for detached children.
+     * On POSIX, detachment determines whether the child leads its own group.
+     * Default `"linux"`; host bundles pass their actual platform.
+     */
+    readonly platform?: string | undefined;
+}
+/**
+ * A platform's preparation, activation, and cleanup of a contained process.
+ *
+ * Preparation receives the underlying spawner and must own cleanup before it
+ * can fail or be interrupted. It returns the process identity to record and an
+ * idempotent `activate` effect. The decorator runs activation only after that
+ * identity commits to the ledger. A platform can therefore prepare an owner
+ * without executing the caller's command before it is durably discoverable.
+ *
+ * Failed startup closes its own scope immediately. A successful startup keeps
+ * that scope attached to the caller's scope. `settled` must stay false on failed
+ * or unverifiable cleanup; only verified cleanup permits ledger retirement.
+ * The wrapped handle applies the same policy to an explicit `kill`.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Lifecycle = (command: ChildProcess.StandardCommand, spawn: (command: ChildProcess.StandardCommand) => Effect.Effect<ChildProcessHandle, PlatformError.PlatformError, Scope.Scope>) => Effect.Effect<{
+    readonly handle: ChildProcessHandle;
+    readonly activate: Effect.Effect<void, PlatformError.PlatformError, Scope.Scope>;
+    readonly settled: Effect.Effect<boolean>;
+}, PlatformError.PlatformError, Scope.Scope>;
+/**
+ * Whether a spawner declares the platform lifecycle required for containment.
+ *
+ * Only a layer with a {@link Lifecycle} declares this contract. A kill deadline
+ * alone does not verify cleanup. The permission decorator preserves the
+ * declaration when it wraps a contained service. The marker interoperates
+ * across the package's ESM and CommonJS projections.
+ *
+ * This is a trusted composition check: a caller-supplied lifecycle remains
+ * responsible for implementing its contract.
+ *
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const isContained: (spawner: ChildProcessSpawner["Service"]) => boolean;
+/**
+ * Supplies a command's default termination signal and escalation deadline.
+ *
+ * Both legs of a pipeline get the same policy — a pipeline is one action's
+ * process tree and a surviving leg is as much of a leak as a surviving
+ * child. Explicit `killSignal` and `forceKillAfter` values are preserved for
+ * the host lifecycle to validate.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const withContainment: (command: ChildProcess.Command, options?: Options) => ChildProcess.Command;
+/**
+ * The process group a started child leads, or `null` when it shares the
+ * host's or the platform has no POSIX process groups.
+ *
+ * A detached POSIX child leads a group whose id is its own pid. A child in
+ * the host's group must not record that group as its own cleanup target.
+ * Windows detachment creates an independent console, not a POSIX group;
+ * Windows records therefore always carry `null`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const groupOf: (command: ChildProcess.Command, pid: number, platform?: string) => number | null;
+/**
+ * Decorates the process spawner in place with containment and bookkeeping.
+ *
+ * Compose it over a host spawner layer with `Layer.provide`. It provides the
+ * tag it also requires. Compose the permission decorator over this layer to
+ * authorize the caller's whole pipeline before its per-process expansion. A
+ * lifecycle may use different commands during preparation; a decorator below
+ * containment sees those platform commands instead of the caller's command.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (options?: Options, lifecycle?: Lifecycle) => Layer.Layer<ChildProcessSpawner, never, ChildProcessSpawner | ProcessLedger.ProcessLedger>;
+//# sourceMappingURL=ContainedSpawner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ContainedSpawner.d.ts","sourceRoot":"","sources":["../../src/ContainedSpawner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAErD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,YAAY,MAAM,sCAAsC,CAAA;AACpE,OAAO,EACL,KAAK,kBAAkB,EACvB,mBAAmB,EAEpB,MAAM,6CAA6C,CAAA;AAIpD,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,OAAO,CAAA;AAElC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,YAAY,CAAC,eAAe,EACrC,KAAK,EAAE,CACL,OAAO,EAAE,YAAY,CAAC,eAAe,KAClC,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,KAC7E,MAAM,CAAC,MAAM,CAChB;IACE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;CACzC,EACD,aAAa,CAAC,aAAa,EAC3B,KAAK,CAAC,KAAK,CACZ,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,mBAAmB,CAAC,SAAS,CAAC,KAAG,OAA2C,CAAA;AAEjH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,YAAY,CAAC,OAAO,EAC7B,UAAU,OAAO,KAChB,YAAY,CAAC,OAcf,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAI,SAAS,YAAY,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,IAIhG,CAAA;AAKD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAChB,UAAU,OAAO,EACjB,YAAY,SAAS,KACpB,KAAK,CAAC,KAAK,CAAC,mBAAmB,EAAE,KAAK,EAAE,mBAAmB,GAAG,aAAa,CAAC,aAAa,CAmEzF,CAAA"}

package/dist/esm/ContainedSpawner.js

@@ -0,0 +1,180 @@
+/**
+ * Process containment: prepared ownership, bounded cleanup and durable records.
+ *
+ * A host supplies a {@link Lifecycle} that owns launch and cleanup independently
+ * of the command's exit status. The lifecycle first prepares a process identity;
+ * this decorator commits that identity to {@link ProcessLedger.ProcessLedger}
+ * before activating the caller's command. Failed or interrupted startup closes
+ * its child scope immediately, including any earlier legs of a partial pipeline.
+ *
+ * Each command receives default termination and escalation options. The host
+ * lifecycle validates that policy and verifies cleanup before the decorator
+ * retires its record. Unverifiable cleanup retains the record for recovery;
+ * a host that dies also leaves its committed records discoverable by the next
+ * incarnation's reaper (`ProcessReaper` in `@smthrs/platform-node`).
+ *
+ * Every pipeline leg is prepared and recorded separately, including legs whose
+ * pid the aggregate handle does not expose. The module remains platform-neutral.
+ * A layer without a lifecycle provides only deadline defaults and bookkeeping;
+ * it does not declare the verified-cleanup contract read by {@link isContained}.
+ *
+ * Governing design:
+ * `docs/specs/Concepts/Host Adapters.md`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as PlatformError from "effect/PlatformError";
+import * as Schedule from "effect/Schedule";
+import * as Scope from "effect/Scope";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import { ChildProcessSpawner, make as makeSpawner } from "effect/unstable/process/ChildProcessSpawner";
+import * as CommandLine from "./CommandLine.js";
+import * as Containment from "./internal/Containment.js";
+import * as Pipeline from "./internal/Pipeline.js";
+import * as ProcessLedger from "./ProcessLedger.js";
+/**
+ * How long a contained child may take to honour `SIGTERM`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const defaultGraceMs = 2000;
+/**
+ * Whether a spawner declares the platform lifecycle required for containment.
+ *
+ * Only a layer with a {@link Lifecycle} declares this contract. A kill deadline
+ * alone does not verify cleanup. The permission decorator preserves the
+ * declaration when it wraps a contained service. The marker interoperates
+ * across the package's ESM and CommonJS projections.
+ *
+ * This is a trusted composition check: a caller-supplied lifecycle remains
+ * responsible for implementing its contract.
+ *
+ * @category predicates
+ * @since 1.0.0
+ */
+export const isContained = (spawner) => Containment.isContained(spawner);
+/**
+ * Supplies a command's default termination signal and escalation deadline.
+ *
+ * Both legs of a pipeline get the same policy — a pipeline is one action's
+ * process tree and a surviving leg is as much of a leak as a surviving
+ * child. Explicit `killSignal` and `forceKillAfter` values are preserved for
+ * the host lifecycle to validate.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const withContainment = (command, options) => {
+    const graceMs = options?.graceMs ?? defaultGraceMs;
+    if (command._tag === "PipedCommand") {
+        return ChildProcess.pipeTo(withContainment(command.left, options), withContainment(command.right, options), command.options);
+    }
+    return ChildProcess.make(command.command, [...command.args], {
+        ...command.options,
+        killSignal: command.options.killSignal ?? "SIGTERM",
+        forceKillAfter: command.options.forceKillAfter ?? graceMs
+    });
+};
+/**
+ * The process group a started child leads, or `null` when it shares the
+ * host's or the platform has no POSIX process groups.
+ *
+ * A detached POSIX child leads a group whose id is its own pid. A child in
+ * the host's group must not record that group as its own cleanup target.
+ * Windows detachment creates an independent console, not a POSIX group;
+ * Windows records therefore always carry `null`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const groupOf = (command, pid, platform) => {
+    if (platform === "win32")
+        return null;
+    const options = command._tag === "PipedCommand" ? rightmost(command).options : command.options;
+    return (options.detached ?? true) ? pid : null;
+};
+const rightmost = (command) => command._tag === "StandardCommand" ? command : rightmost(command.right);
+/**
+ * Decorates the process spawner in place with containment and bookkeeping.
+ *
+ * Compose it over a host spawner layer with `Layer.provide`. It provides the
+ * tag it also requires. Compose the permission decorator over this layer to
+ * authorize the caller's whole pipeline before its per-process expansion. A
+ * lifecycle may use different commands during preparation; a decorator below
+ * containment sees those platform commands instead of the caller's command.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (options, lifecycle) => Layer.effect(ChildProcessSpawner, Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner;
+    const ledger = yield* ProcessLedger.ProcessLedger;
+    const service = makeSpawner((command) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        // A failed startup must clean up even when its caller catches the
+        // error and keeps the outer scope open. One child scope contains
+        // the entire pipeline, so failure of a later leg also closes all
+        // earlier legs. Successful spawns retain it until their caller closes.
+        const processScope = yield* Scope.fork(yield* Scope.Scope);
+        return yield* restore(Pipeline.spawn(command, Effect.fn("ContainedSpawner.spawn")(function* (command) {
+            // The release finalizer is registered BEFORE the spawn, so scope
+            // closure runs it AFTER the spawn's own kill finalizer: finalizers
+            // run last-registered-first, and a ledger that announced an exit
+            // while the process was still being signalled would be telling the
+            // next incarnation to stop looking for something still alive. The
+            // slot is empty until the record exists, which is also what makes a
+            // spawn that never got recorded a no-op to release.
+            const slot = {
+                settled: Effect.succeed(true)
+            };
+            yield* Effect.addFinalizer(() => Effect.gen(function* () {
+                if (slot.current === undefined)
+                    return;
+                if (yield* slot.settled)
+                    return yield* releaseQuietly(ledger, slot.current);
+                yield* Effect.logWarning(`process cleanup could not verify ${slot.current.pid}; retaining its ledger record`);
+            }));
+            const contained = withContainment(command, options);
+            const watched = lifecycle === undefined ? undefined : yield* lifecycle(contained, spawner.spawn);
+            const handle = watched?.handle ?? (yield* spawner.spawn(contained));
+            slot.settled = watched?.settled ?? slot.settled;
+            const pid = handle.pid;
+            slot.current = yield* ledger.record({
+                pid,
+                pgid: groupOf(command, pid, options?.platform),
+                commandDigest: CommandLine.executable(command)
+            }).pipe(
+            // A spawn whose record did not commit is precisely the child this
+            // module exists to make discoverable, so it is not started: the
+            // process is signalled and the caller is told, rather than left
+            // running with nothing durable naming it.
+            Effect.tapCause(() => Effect.ignore(handle.kill())), Effect.mapError(unrecorded));
+            if (watched !== undefined)
+                yield* watched.activate;
+            return handle;
+        })).pipe(Scope.provide(processScope))).pipe(Effect.onError((cause) => Scope.close(processScope, Exit.failCause(cause))));
+    })));
+    return lifecycle === undefined ? service : Containment.mark(service);
+}));
+/** The spawn failure a caller sees when the ledger could not record a child. */
+const unrecorded = (cause) => PlatformError.systemError({
+    _tag: "Unknown",
+    module: "ChildProcess",
+    method: "spawn",
+    description: "the process ledger could not record this spawn durably",
+    cause
+});
+/**
+ * Retires a record on scope close, retrying the durable write.
+ *
+ * A finalizer has nowhere to report a failure, so the retry is the report: an
+ * exit that never commits leaves the record inherited, and the next
+ * incarnation's reaper finds a pid that is already gone and retires it then.
+ * That is the safe direction, and the reason this is the ONE place a ledger
+ * failure is logged rather than propagated.
+ */
+const releaseQuietly = (ledger, record) => ledger.release(record).pipe(Effect.retry(Schedule.recurs(2)), Effect.catch((error) => Effect.logWarning(`process ledger could not retire ${record.pid}; leaving it for the reaper`, error)));
+//# sourceMappingURL=ContainedSpawner.js.map

package/dist/esm/ContainedSpawner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainedSpawner.js","sourceRoot":"","sources":["../../src/ContainedSpawner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,aAAa,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,YAAY,MAAM,sCAAsC,CAAA;AACpE,OAAO,EAEL,mBAAmB,EACnB,IAAI,IAAI,WAAW,EACpB,MAAM,6CAA6C,CAAA;AACpD,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,WAAW,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAA;AAClD,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAuDlC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAuC,EAAW,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAA;AAEjH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAA6B,EAC7B,OAAiB,EACK,EAAE;IACxB,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,cAAc,CAAA;IAClD,IAAI,OAAO,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACpC,OAAO,YAAY,CAAC,MAAM,CACxB,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EACtC,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,EACvC,OAAO,CAAC,OAAO,CAChB,CAAA;IACH,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE;QAC3D,GAAG,OAAO,CAAC,OAAO;QAClB,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,IAAI,SAAS;QACnD,cAAc,EAAE,OAAO,CAAC,OAAO,CAAC,cAAc,IAAI,OAAO;KAC1D,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,OAA6B,EAAE,GAAW,EAAE,QAAiB,EAAiB,EAAE;IACtG,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,IAAI,CAAA;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAA;IAC9F,OAAO,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;AAChD,CAAC,CAAA;AAED,MAAM,SAAS,GAAG,CAAC,OAA6B,EAAgC,EAAE,CAChF,OAAO,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAEzE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,OAAiB,EACjB,SAAqB,EACuE,EAAE,CAC9F,KAAK,CAAC,MAAM,CACV,mBAAmB,EACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,mBAAmB,CAAA;IAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,aAAa,CAAC,aAAa,CAAA;IACjD,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,OAAO,EAAE,EAAE,CACV,MAAM,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE,EAAE,CACrC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClB,kEAAkE;QAClE,iEAAiE;QACjE,iEAAiE;QACjE,uEAAuE;QACvE,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC1D,OAAO,KAAK,CAAC,CAAC,OAAO,CACnB,QAAQ,CAAC,KAAK,CACZ,OAAO,EACP,MAAM,CAAC,EAAE,CAAC,wBAAwB,CAAC,CAAC,QAAQ,CAAC,EAAC,OAAO;YACnD,iEAAiE;YACjE,mEAAmE;YACnE,iEAAiE;YACjE,mEAAmE;YACnE,kEAAkE;YAClE,oEAAoE;YACpE,oDAAoD;YACpD,MAAM,IAAI,GAA+E;gBACvF,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;aAC9B,CAAA;YACD,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAC9B,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAClB,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;oBAAE,OAAM;gBACtC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO;oBAAE,OAAO,KAAK,CAAC,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;gBAC3E,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CACtB,oCAAoC,IAAI,CAAC,OAAO,CAAC,GAAG,+BAA+B,CACpF,CAAA;YACH,CAAC,CAAC,CACH,CAAA;YACD,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,EAAE,OAAO,CAAiC,CAAA;YACnF,MAAM,OAAO,GAAG,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;YAChG,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;YACnE,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,OAAO,CAAA;YAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAa,CAAA;YAChC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;gBAClC,GAAG;gBACH,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC;gBAC9C,aAAa,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC;aAC/C,CAAC,CAAC,IAAI;YACL,kEAAkE;YAClE,gEAAgE;YAChE,gEAAgE;YAChE,0CAA0C;YAC1C,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,EACnD,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAC5B,CAAA;YACD,IAAI,OAAO,KAAK,SAAS;gBAAE,KAAK,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAA;YAClD,OAAO,MAAM,CAAA;QACf,CAAC,CAAC,CACH,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CACpC,CAAC,IAAI,CACJ,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAC5E,CAAA;IACH,CAAC,CAAC,CACH,CACJ,CAAA;IACD,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACtE,CAAC,CAAC,CACH,CAAA;AAEH,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,KAAc,EAA+B,EAAE,CACjE,aAAa,CAAC,WAAW,CAAC;IACxB,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,cAAc;IACtB,MAAM,EAAE,OAAO;IACf,WAAW,EAAE,wDAAwD;IACrE,KAAK;CACN,CAAC,CAAA;AAEJ;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,CACrB,MAA6B,EAC7B,MAAmC,EACd,EAAE,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CACzB,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAChC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CACrB,MAAM,CAAC,UAAU,CAAC,mCAAmC,MAAM,CAAC,GAAG,6BAA6B,EAAE,KAAK,CAAC,CACrG,CACF,CAAA","sourcesContent":["/**\n * Process containment: prepared ownership, bounded cleanup and durable records.\n *\n * A host supplies a {@link Lifecycle} that owns launch and cleanup independently\n * of the command's exit status. The lifecycle first prepares a process identity;\n * this decorator commits that identity to {@link ProcessLedger.ProcessLedger}\n * before activating the caller's command. Failed or interrupted startup closes\n * its child scope immediately, including any earlier legs of a partial pipeline.\n *\n * Each command receives default termination and escalation options. The host\n * lifecycle validates that policy and verifies cleanup before the decorator\n * retires its record. Unverifiable cleanup retains the record for recovery;\n * a host that dies also leaves its committed records discoverable by the next\n * incarnation's reaper (`ProcessReaper` in `@smthrs/platform-node`).\n *\n * Every pipeline leg is prepared and recorded separately, including legs whose\n * pid the aggregate handle does not expose. The module remains platform-neutral.\n * A layer without a lifecycle provides only deadline defaults and bookkeeping;\n * it does not declare the verified-cleanup contract read by {@link isContained}.\n *\n * Governing design:\n * `docs/specs/Concepts/Host Adapters.md`.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Exit from \"effect/Exit\"\nimport * as Layer from \"effect/Layer\"\nimport * as PlatformError from \"effect/PlatformError\"\nimport * as Schedule from \"effect/Schedule\"\nimport * as Scope from \"effect/Scope\"\nimport * as ChildProcess from \"effect/unstable/process/ChildProcess\"\nimport {\n  type ChildProcessHandle,\n  ChildProcessSpawner,\n  make as makeSpawner\n} from \"effect/unstable/process/ChildProcessSpawner\"\nimport * as CommandLine from \"./CommandLine.ts\"\nimport * as Containment from \"./internal/Containment.ts\"\nimport * as Pipeline from \"./internal/Pipeline.ts\"\nimport * as ProcessLedger from \"./ProcessLedger.ts\"\n\n/**\n * How long a contained child may take to honour `SIGTERM`.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const defaultGraceMs = 2000\n\n/**\n * Containment configuration.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Options {\n  /**\n   * Milliseconds between the `SIGTERM` that asks a child to stop and the\n   * `SIGKILL` that makes it. Default {@link defaultGraceMs}.\n   */\n  readonly graceMs?: number | undefined\n  /**\n   * The platform the host spawner runs on, as `process.platform` spells it.\n   * Windows records no POSIX process group, including for detached children.\n   * On POSIX, detachment determines whether the child leads its own group.\n   * Default `\"linux\"`; host bundles pass their actual platform.\n   */\n  readonly platform?: string | undefined\n}\n\n/**\n * A platform's preparation, activation, and cleanup of a contained process.\n *\n * Preparation receives the underlying spawner and must own cleanup before it\n * can fail or be interrupted. It returns the process identity to record and an\n * idempotent `activate` effect. The decorator runs activation only after that\n * identity commits to the ledger. A platform can therefore prepare an owner\n * without executing the caller's command before it is durably discoverable.\n *\n * Failed startup closes its own scope immediately. A successful startup keeps\n * that scope attached to the caller's scope. `settled` must stay false on failed\n * or unverifiable cleanup; only verified cleanup permits ledger retirement.\n * The wrapped handle applies the same policy to an explicit `kill`.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Lifecycle = (\n  command: ChildProcess.StandardCommand,\n  spawn: (\n    command: ChildProcess.StandardCommand\n  ) => Effect.Effect<ChildProcessHandle, PlatformError.PlatformError, Scope.Scope>\n) => Effect.Effect<\n  {\n    readonly handle: ChildProcessHandle\n    readonly activate: Effect.Effect<void, PlatformError.PlatformError, Scope.Scope>\n    readonly settled: Effect.Effect<boolean>\n  },\n  PlatformError.PlatformError,\n  Scope.Scope\n>\n\n/**\n * Whether a spawner declares the platform lifecycle required for containment.\n *\n * Only a layer with a {@link Lifecycle} declares this contract. A kill deadline\n * alone does not verify cleanup. The permission decorator preserves the\n * declaration when it wraps a contained service. The marker interoperates\n * across the package's ESM and CommonJS projections.\n *\n * This is a trusted composition check: a caller-supplied lifecycle remains\n * responsible for implementing its contract.\n *\n * @category predicates\n * @since 1.0.0\n */\nexport const isContained = (spawner: ChildProcessSpawner[\"Service\"]): boolean => Containment.isContained(spawner)\n\n/**\n * Supplies a command's default termination signal and escalation deadline.\n *\n * Both legs of a pipeline get the same policy — a pipeline is one action's\n * process tree and a surviving leg is as much of a leak as a surviving\n * child. Explicit `killSignal` and `forceKillAfter` values are preserved for\n * the host lifecycle to validate.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const withContainment = (\n  command: ChildProcess.Command,\n  options?: Options\n): ChildProcess.Command => {\n  const graceMs = options?.graceMs ?? defaultGraceMs\n  if (command._tag === \"PipedCommand\") {\n    return ChildProcess.pipeTo(\n      withContainment(command.left, options),\n      withContainment(command.right, options),\n      command.options\n    )\n  }\n  return ChildProcess.make(command.command, [...command.args], {\n    ...command.options,\n    killSignal: command.options.killSignal ?? \"SIGTERM\",\n    forceKillAfter: command.options.forceKillAfter ?? graceMs\n  })\n}\n\n/**\n * The process group a started child leads, or `null` when it shares the\n * host's or the platform has no POSIX process groups.\n *\n * A detached POSIX child leads a group whose id is its own pid. A child in\n * the host's group must not record that group as its own cleanup target.\n * Windows detachment creates an independent console, not a POSIX group;\n * Windows records therefore always carry `null`.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const groupOf = (command: ChildProcess.Command, pid: number, platform?: string): number | null => {\n  if (platform === \"win32\") return null\n  const options = command._tag === \"PipedCommand\" ? rightmost(command).options : command.options\n  return (options.detached ?? true) ? pid : null\n}\n\nconst rightmost = (command: ChildProcess.Command): ChildProcess.StandardCommand =>\n  command._tag === \"StandardCommand\" ? command : rightmost(command.right)\n\n/**\n * Decorates the process spawner in place with containment and bookkeeping.\n *\n * Compose it over a host spawner layer with `Layer.provide`. It provides the\n * tag it also requires. Compose the permission decorator over this layer to\n * authorize the caller's whole pipeline before its per-process expansion. A\n * lifecycle may use different commands during preparation; a decorator below\n * containment sees those platform commands instead of the caller's command.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layer = (\n  options?: Options,\n  lifecycle?: Lifecycle\n): Layer.Layer<ChildProcessSpawner, never, ChildProcessSpawner | ProcessLedger.ProcessLedger> =>\n  Layer.effect(\n    ChildProcessSpawner,\n    Effect.gen(function*() {\n      const spawner = yield* ChildProcessSpawner\n      const ledger = yield* ProcessLedger.ProcessLedger\n      const service = makeSpawner(\n        (command) =>\n          Effect.uninterruptibleMask((restore) =>\n            Effect.gen(function*() {\n              // A failed startup must clean up even when its caller catches the\n              // error and keeps the outer scope open. One child scope contains\n              // the entire pipeline, so failure of a later leg also closes all\n              // earlier legs. Successful spawns retain it until their caller closes.\n              const processScope = yield* Scope.fork(yield* Scope.Scope)\n              return yield* restore(\n                Pipeline.spawn(\n                  command,\n                  Effect.fn(\"ContainedSpawner.spawn\")(function*(command) {\n                    // The release finalizer is registered BEFORE the spawn, so scope\n                    // closure runs it AFTER the spawn's own kill finalizer: finalizers\n                    // run last-registered-first, and a ledger that announced an exit\n                    // while the process was still being signalled would be telling the\n                    // next incarnation to stop looking for something still alive. The\n                    // slot is empty until the record exists, which is also what makes a\n                    // spawn that never got recorded a no-op to release.\n                    const slot: { current?: ProcessLedger.ProcessRecord; settled: Effect.Effect<boolean> } = {\n                      settled: Effect.succeed(true)\n                    }\n                    yield* Effect.addFinalizer(() =>\n                      Effect.gen(function*() {\n                        if (slot.current === undefined) return\n                        if (yield* slot.settled) return yield* releaseQuietly(ledger, slot.current)\n                        yield* Effect.logWarning(\n                          `process cleanup could not verify ${slot.current.pid}; retaining its ledger record`\n                        )\n                      })\n                    )\n                    const contained = withContainment(command, options) as ChildProcess.StandardCommand\n                    const watched = lifecycle === undefined ? undefined : yield* lifecycle(contained, spawner.spawn)\n                    const handle = watched?.handle ?? (yield* spawner.spawn(contained))\n                    slot.settled = watched?.settled ?? slot.settled\n                    const pid = handle.pid as number\n                    slot.current = yield* ledger.record({\n                      pid,\n                      pgid: groupOf(command, pid, options?.platform),\n                      commandDigest: CommandLine.executable(command)\n                    }).pipe(\n                      // A spawn whose record did not commit is precisely the child this\n                      // module exists to make discoverable, so it is not started: the\n                      // process is signalled and the caller is told, rather than left\n                      // running with nothing durable naming it.\n                      Effect.tapCause(() => Effect.ignore(handle.kill())),\n                      Effect.mapError(unrecorded)\n                    )\n                    if (watched !== undefined) yield* watched.activate\n                    return handle\n                  })\n                ).pipe(Scope.provide(processScope))\n              ).pipe(\n                Effect.onError((cause) => Scope.close(processScope, Exit.failCause(cause)))\n              )\n            })\n          )\n      )\n      return lifecycle === undefined ? service : Containment.mark(service)\n    })\n  )\n\n/** The spawn failure a caller sees when the ledger could not record a child. */\nconst unrecorded = (cause: unknown): PlatformError.PlatformError =>\n  PlatformError.systemError({\n    _tag: \"Unknown\",\n    module: \"ChildProcess\",\n    method: \"spawn\",\n    description: \"the process ledger could not record this spawn durably\",\n    cause\n  })\n\n/**\n * Retires a record on scope close, retrying the durable write.\n *\n * A finalizer has nowhere to report a failure, so the retry is the report: an\n * exit that never commits leaves the record inherited, and the next\n * incarnation's reaper finds a pid that is already gone and retires it then.\n * That is the safe direction, and the reason this is the ONE place a ledger\n * failure is logged rather than propagated.\n */\nconst releaseQuietly = (\n  ledger: ProcessLedger.Service,\n  record: ProcessLedger.ProcessRecord\n): Effect.Effect<void> =>\n  ledger.release(record).pipe(\n    Effect.retry(Schedule.recurs(2)),\n    Effect.catch((error) =>\n      Effect.logWarning(`process ledger could not retire ${record.pid}; leaving it for the reaper`, error)\n    )\n  )\n"]}