stitchkit 0.103.9 → 0.103.10

package/llms-full.txt

@@ -8031,12 +8031,16 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-01 21:31 +07:00
+updated: 2026-10-02 00:37 +07:00
 participants:
   - role: authored
     harness: Codex
     model: GPT-6
     at: 2026-10-01 20:44 +07:00
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-02 00:08 +07:00
 ---
 
 # Native IO
@@ -8152,6 +8156,10 @@ callbacks owner не запускает. Normal completion ждёт всех byt
 
 Cleanup: POSIX process group, TERM, `killGraceMs` (default 100, maximum 10 000), затем KILL;
 `cleanupTimeoutMs` (default 2000, maximum 30 000) ограничивает ожидание close после сигналов.
+На Darwin временный `EPERM` при сигнале группе может означать zombies, ещё не убранные
+OS reaper. Повтор ограничен `cleanupTimeoutMs`; успех требует доставленного сигнала или
+`ESRCH`, постоянный отказ сохраняется в cause. Закрытие каждого owned pipe и выход leader
+наблюдаются отдельно, включая отсутствие общего `child.close` при teardown.
 Сохраняется caller/sink причина; failure cleanup — `NativeCommandError` с `COMMAND_CLEANUP` и
 AggregateError cause. Даже вышедший parent не исключает helper, удерживающий pipe. Windows
 отказывает с `COMMAND_UNAVAILABLE`; потомок, самостоятельно покинувший группу через setsid,
@@ -8166,6 +8174,68 @@ shell policy, command admission, логирование, redaction, bytes→text
 Длительные signal-only команды остаются streaming; bounded tar/capture получают свои явные limits.
 Импорт leaf не делает установку всего npm package маленькой; выбирайте dependency после измерения
 packed размера и dependency closure.
+## Resource-scoped launchers and shared owners
+
+`onLeaderSettled(event, signal)` observes leader exit before inherited stdout/stderr pipes
+close. A resource owner can stop its external scope there, allowing pipe drain to complete.
+The callback runs once: `event.kind === 'exit'` carries observed `exitCode`/`signal`; a terminal
+failure uses `kind: 'error'` and preserves its cause. Unavailable executables, output sink
+failure and caller cancellation settle through the same owner. `cleanupTimeoutMs` bounds
+the callback after settlement starts; it never becomes a deadline for signal-only execution.
+Honor the settlement signal; arbitrary user promises cannot be forcibly cancelled.
+
+```ts
+await runNativeCommand({
+  executable: launcher,
+  args,
+  signal: scope.signal,
+  onOutput: (bytes, channel, signal) => scope.write(bytes, channel, signal),
+  onLeaderSettled: (event, signal) => scope.settle(event, signal),
+});
+```
+
+`observeProcessInstance(pid)` returns `observed` with a `ProcessInstance`, or `unavailable`
+with its cause. `probeProcessOwner(pid, recorded)` compares that evidence on the machine the
+caller established: `matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy` or
+`unavailable`. Missing/partial/denied evidence is not death. Supervisor tree fencing remains
+the caller's job; a PID lifetime is not proof that its whole workload stopped.
+
+An exclusive lock applies exact requested permissions through its creating descriptor,
+independent of umask. Default `0600` stays private. Shared `0640` requires a common group and
+traversable directories; another UID also needs directory write permission to reclaim a
+proven-dead owner's file. Set `ownerlessGraceMs: null` to refuse every age-only reclaim,
+including ownerless reclaim guards. The default remains 5000 ms for existing clients.
+Восстановление stale reclaim guard использует тот же lock owner и следующий guard:
+проверка inode и удаление выполняются под ним. Конкурирующий writer не обходит guard,
+пока прежнее удаление приостановлено; live и unknown lifetime evidence остаются отказом.
+
+## Libraries with a Zod-only runtime
+
+Public leaves keep optional peers out of their import closure. Installing `stitchkit` still
+installs the complete package and ky; selective imports alone do not avoid that installation.
+A library can use Stitchkit as a build dependency, bundle its selected public native imports,
+keep Zod external, and publish the resulting implementation with its library artifact.
+
+```ts
+// The library's build entry; all mechanisms remain owned by Stitchkit.
+export { canonicalJson } from 'stitchkit/primitives';
+export { writeFileAtomic, withExclusiveLock } from 'stitchkit/files';
+export { observeProcessInstance, probeProcessOwner, runNativeCommand } from 'stitchkit/process';
+```
+
+Bundle for Node-compatible execution with Zod external. Publish declarations from the same
+version: carry their reachable relative `.d.ts` closure, rather than emitting references to
+`stitchkit` that force clients to install it for types. A library exposing its own DTOs may
+instead emit declarations for only that DTO contract. Keep the library's manifest at runtime
+`dependencies: {}` and `peerDependencies: { zod: ... }` when that is its declared promise.
+
+Darwin consumers need the published native binaries at the bundled loader's relative native
+directory. A JS-only bundle is not portable evidence. Qualify the packed library outside its
+build tree in Bun and Node, test its declarations, and check that importing an unbundled
+Stitchkit leaf fails there. A separate schema-only entry must not import the native entry.
+
+This delivery removes a runtime kernel installation; it does not remove the build-time
+Stitchkit installation or create an independent lightweight npm package.
 
 
 ==============================================================================
@@ -20568,7 +20638,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` (default 5000 ms, `null` disables age-based reclaim including guards); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
 | `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |
@@ -21122,3 +21192,8 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
 | `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
 | `NativeCommandError` | class | COMMAND_LIMIT, COMMAND_UNAVAILABLE or COMMAND_CLEANUP with internal cause |
+
+| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal |
+| `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
+| `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
+| `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |

package/llms.txt

@@ -39,7 +39,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
-- **stitchkit/files**: [llms/files.txt](llms/files.txt) 4.4 KB
+- **stitchkit/files**: [llms/files.txt](llms/files.txt) 4.5 KB
 - **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 26.9 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
@@ -55,7 +55,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 1.8 KB
 - **stitchkit/agent-runtime/harness-tools**: [llms/agent-runtime-harness-tools.txt](llms/agent-runtime-harness-tools.txt) 1.3 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 10.7 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 15.9 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.103.9",
+  "version": "0.103.10",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-7kxw1awn.js

@@ -1,328 +0,0 @@
-import {
-  loadDarwinBinding
-} from "./index-d4pa2bgs.js";
-import {
-  isRecord
-} from "./index-9jfdm5tg.js";
-
-// src/internal/exclusive-lock.ts
-import { constants } from "node:fs";
-import { lstat, open, unlink } from "node:fs/promises";
-import { hostname } from "node:os";
-import { z as z2 } from "zod";
-
-// src/internal/process-identity.ts
-import { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { platform } from "node:os";
-import { promisify } from "node:util";
-var detectedIdentity;
-async function firstReadableLine(paths) {
-  for (const path of paths) {
-    try {
-      const text = (await readFile(path, "utf8")).trim();
-      if (text.length > 0)
-        return text;
-    } catch {}
-  }
-  return null;
-}
-var run = promisify(execFile);
-function parsePlatformUuid(dump) {
-  return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(dump)?.[1] ?? null;
-}
-async function readDarwinPlatformUuid(command = "ioreg") {
-  try {
-    const { stdout } = await run(command, ["-rd1", "-c", "IOPlatformExpertDevice"], {
-      timeout: 2000,
-      maxBuffer: 1 << 20,
-      encoding: "utf8"
-    });
-    return parsePlatformUuid(stdout);
-  } catch {
-    return null;
-  }
-}
-async function machineIdentity(declared) {
-  if (declared !== undefined)
-    return declared;
-  if (detectedIdentity !== undefined)
-    return detectedIdentity;
-  detectedIdentity = platform() === "darwin" ? await readDarwinPlatformUuid() : await firstReadableLine(["/etc/machine-id", "/var/lib/dbus/machine-id"]);
-  return detectedIdentity;
-}
-async function probeLiveness(pid, reach = (target) => process.kill(target, 0)) {
-  try {
-    reach(pid);
-  } catch (error) {
-    return isRecord(error) && error.code === "ESRCH" ? "gone" : "alive";
-  }
-  return await isZombieProcess(pid) ? "gone" : "alive";
-}
-async function isZombieProcess(pid, seam = {}) {
-  const { procRoot = "/proc", psCommand = "ps" } = seam;
-  try {
-    const stat = await readFile(`${procRoot}/${pid}/stat`, "utf8");
-    return stat.slice(stat.lastIndexOf(")") + 1).trimStart().startsWith("Z");
-  } catch {}
-  try {
-    const { stdout } = await run(psCommand, ["-o", "state=", "-p", String(pid)], {
-      timeout: 2000,
-      maxBuffer: 1 << 16,
-      encoding: "utf8"
-    });
-    return stdout.trim().startsWith("Z");
-  } catch {
-    return false;
-  }
-}
-
-// src/internal/process-instance.ts
-import { readFile as readFile2, readlink } from "node:fs/promises";
-import { platform as platform2 } from "node:os";
-import { z } from "zod";
-var ProcessInstanceSchema = z.object({
-  platform: z.enum(["linux", "darwin"]),
-  bootId: z.string().min(1),
-  namespace: z.string().min(1),
-  startId: z.string().regex(/^\d+$/)
-}).strict();
-function linuxProcessStart(stat, pid) {
-  if (!stat.startsWith(`${pid} (`))
-    return null;
-  const end = stat.lastIndexOf(")");
-  if (end < 0)
-    return null;
-  const start = stat.slice(end + 1).trim().split(/\s+/)[19];
-  return start !== undefined && /^\d+$/.test(start) ? start : null;
-}
-async function readProcessInstance(pid, procRoot = "/proc") {
-  try {
-    if (platform2() === "darwin") {
-      const result = ProcessInstanceSchema.safeParse(loadDarwinBinding().processIdentity(pid));
-      return result.success ? result.data : null;
-    }
-    if (platform2() !== "linux")
-      return null;
-    const [bootId, namespace, ownStatus, timeNamespace, ownStat, stat] = await Promise.all([
-      readFile2(`${procRoot}/sys/kernel/random/boot_id`, "utf8"),
-      readlink(`${procRoot}/self/ns/pid`),
-      readFile2(`${procRoot}/self/status`, "utf8"),
-      readlink(`${procRoot}/self/ns/time`).catch((error) => {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-          return "";
-        throw error;
-      }),
-      readFile2(`${procRoot}/self/stat`, "utf8"),
-      readFile2(`${procRoot}/${pid}/stat`, "utf8")
-    ]);
-    const namespacePids = ownStatus.match(/^NStgid:[ \t]*(.*)$/m)?.[1]?.trim().split(/\s+/);
-    if (namespacePids?.length !== 1 || namespacePids[0] !== String(process.pid) || linuxProcessStart(ownStat, process.pid) === null)
-      return null;
-    const startId = linuxProcessStart(stat, pid);
-    if (startId === null || !bootId.trim())
-      return null;
-    return {
-      platform: "linux",
-      bootId: bootId.trim(),
-      namespace: `${namespace};${timeNamespace}`,
-      startId
-    };
-  } catch {
-    return null;
-  }
-}
-async function probeProcessOwner(pid, recorded, probes = { read: readProcessInstance, liveness: probeLiveness }) {
-  if (recorded === undefined)
-    return { liveness: await probes.liveness(pid), identity: "legacy" };
-  const unavailable = {
-    liveness: "not-probed",
-    identity: "unavailable"
-  };
-  if (recorded === null)
-    return unavailable;
-  const current = await probes.read(process.pid);
-  if (!current || recorded.platform !== current.platform)
-    return unavailable;
-  if (recorded.bootId !== current.bootId)
-    return { liveness: "gone", identity: "different-boot" };
-  if (recorded.namespace !== current.namespace)
-    return unavailable;
-  const liveness = await probes.liveness(pid);
-  if (liveness === "gone")
-    return { liveness, identity: "pid-gone" };
-  const observed = await probes.read(pid);
-  if (!observed || observed.bootId !== current.bootId || observed.namespace !== current.namespace)
-    return unavailable;
-  if (recorded.startId !== observed.startId)
-    return { liveness: "gone", identity: "reused-pid" };
-  return { liveness: "alive", identity: "matched" };
-}
-
-// src/internal/exclusive-lock.ts
-var ExclusiveLockOwnerSchema = z2.object({
-  pid: z2.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  host: z2.string().min(1),
-  acquiredAt: z2.string(),
-  machine: z2.string().min(1).optional().catch(undefined),
-  process: ProcessInstanceSchema.nullable().optional().catch(null)
-});
-function isCode(error, code) {
-  return isRecord(error) && error.code === code;
-}
-function readOwner(text) {
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return;
-  }
-  const owner = ExclusiveLockOwnerSchema.safeParse(parsed);
-  return owner.success ? owner.data : undefined;
-}
-function attribute(owner, identity) {
-  if (identity !== null && owner.machine !== undefined) {
-    return owner.machine === identity ? "this-machine" : "another-machine";
-  }
-  return owner.host === hostname() ? "this-machine" : "unattributable";
-}
-async function diagnose(owner, declaredIdentity) {
-  if (!owner)
-    return { attribution: "unattributable", liveness: "not-probed", owner: null };
-  const attribution = attribute(owner, await machineIdentity(declaredIdentity));
-  if (attribution !== "this-machine")
-    return { attribution, liveness: "not-probed", owner };
-  return { attribution, ...await probeProcessOwner(owner.pid, owner.process), owner };
-}
-async function readLockFile(path) {
-  let handle;
-  try {
-    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-    const info = await handle.stat();
-    return {
-      owner: readOwner(await handle.readFile("utf8")),
-      ino: info.ino,
-      mtimeMs: info.mtimeMs
-    };
-  } catch {
-    return;
-  } finally {
-    await handle?.close().catch(() => {
-      return;
-    });
-  }
-}
-async function unlinkIfSame(path, ino) {
-  try {
-    if ((await lstat(path)).ino !== ino)
-      return;
-    await unlink(path);
-  } catch (error) {
-    if (!isCode(error, "ENOENT"))
-      throw error;
-  }
-}
-async function createOwned(path, options, reclaimed) {
-  const identity = await machineIdentity(options.machineIdentity);
-  const instance = await readProcessInstance(process.pid);
-  const handle = await open(path, "wx", options.mode);
-  const owner = {
-    pid: process.pid,
-    process: instance,
-    host: hostname(),
-    acquiredAt: new Date().toISOString(),
-    ...identity !== null && { machine: identity }
-  };
-  let ino;
-  try {
-    await handle.writeFile(`${JSON.stringify(owner)}
-`, "utf8");
-    ino = (await handle.stat()).ino;
-  } catch (error) {
-    await handle.close().catch(() => {
-      return;
-    });
-    await unlink(path).catch(() => {
-      return;
-    });
-    throw error;
-  }
-  let released = false;
-  return {
-    path,
-    owner,
-    reclaimed,
-    async release() {
-      if (released)
-        return;
-      released = true;
-      try {
-        await handle.close();
-      } finally {
-        await unlinkIfSame(path, ino);
-      }
-    }
-  };
-}
-function reclaimable(state, diagnosis, graceMs) {
-  if (state.owner)
-    return diagnosis.liveness === "gone";
-  return graceMs !== undefined && Date.now() - state.mtimeMs >= graceMs;
-}
-async function reclaimUnderGuard(path, options) {
-  const guardPath = `${path}.reclaim`;
-  let guard;
-  try {
-    guard = await createOwned(guardPath, options, false);
-  } catch (error) {
-    if (!isCode(error, "EEXIST"))
-      throw error;
-    const stale = await readLockFile(guardPath);
-    if (stale) {
-      const verdict = await diagnose(stale.owner, options.machineIdentity);
-      if (reclaimable(stale, verdict, options.ownerlessGraceMs ?? 5000)) {
-        await unlinkIfSame(guardPath, stale.ino);
-      }
-    }
-    return;
-  }
-  try {
-    const state = await readLockFile(path);
-    if (state) {
-      const diagnosis = await diagnose(state.owner, options.machineIdentity);
-      if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
-        return "refused";
-      await unlinkIfSame(path, state.ino);
-    }
-    return await createOwned(path, options, state !== undefined).catch((error) => {
-      if (isCode(error, "EEXIST"))
-        return "refused";
-      throw error;
-    });
-  } finally {
-    await guard.release().catch(() => {
-      return;
-    });
-  }
-}
-async function attemptExclusiveLock(path, options) {
-  try {
-    return { held: await createOwned(path, options, false) };
-  } catch (error) {
-    if (!isCode(error, "EEXIST"))
-      throw error;
-    if (!options.reclaim)
-      return { error };
-    const state = await readLockFile(path);
-    const diagnosis = await diagnose(state?.owner, options.machineIdentity);
-    if (!state || !reclaimable(state, diagnosis, options.ownerlessGraceMs)) {
-      return { error, diagnosis };
-    }
-    const reclaimed = await reclaimUnderGuard(path, options);
-    if (reclaimed !== undefined && reclaimed !== "refused")
-      return { held: reclaimed };
-    return { error, diagnosis };
-  }
-}
-
-export { attemptExclusiveLock };