@primafuture/systemd-tasks 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.1.0 — 2026-09-17 (local candidate)
+
+- Add the `@primafuture/systemd-tasks/observed` entrypoint with immutable
+  JSON-safe intents, finite manager-owned stdin, live binary stdout/stderr, and
+  separate payload/guardian lifecycle evidence.
+- Create payload, retention, and `Type=notify` guardian services in one atomic
+  transaction. Both process services require successful retention initialization;
+  payload stop propagates to a drain-aware guardian even when exec was cancelled.
+  Fail closed when the guardian dies, while allowing it to drain output after
+  payload exit, stop, timeout, client detach, or client death.
+- Add a versioned bounded guardian protocol, sequential asynchronous callback
+  backpressure, explicit local detach, and stable `OBSERVATION_FAILED` errors.
+  Reconnect, replay, and stream adoption remain deliberately unsupported.
+- Generalize the existing D-Bus adapter to an ordered auxiliary-unit topology and
+  share transport ownership, mutation serialization, notification routing,
+  cleanup, diagnostics, and `TaskError` identity across root/observed APIs and
+  mixed ESM/CommonJS loading.
+- Upgrade the external native transport to the exact published
+  `@primafuture/socket-fdx@1.1.0` release and use its owned `socketPair()` and
+  `adoptSocket()` primitives.
+- Extend deterministic, real-systemd, installed ESM/CommonJS, and TypeScript
+  consumer tests, including the real 512 KiB stdin boundary, partial socket
+  allocation rollback, pre-readiness detach, cross-client pre-exec stop, final
+  output under slow-callback backpressure during explicit stop, 32 MiB per-channel draining, and guardian
+  fail-closed behavior. Detach also settles independently of an already-pending
+  application callback. No npm publish was performed.
+
 ## 1.0.0 — 2026-09-07
 
 - Add explicit preparation, single-attempt submission, lookup, inspection, waiting,

package/README.md

@@ -4,7 +4,7 @@ Run one-shot Linux processes owned by the **systemd user manager**, with literal
 arguments, binary file-descriptor I/O, manager-owned timeouts, and recoverable
 results after the Node client exits or crashes.
 
-Version 1.0.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
+Version 1.1.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
 and cgroup v2. The verified environment
 is Node 24.13.0, systemd 257.9-0ubuntu2.4, Linux 6.17.0-14-generic, x86-64.
 Other versions satisfying those minimums are not independently verified.
@@ -15,11 +15,12 @@ Other versions satisfying those minimums are not independently verified.
 npm install @primafuture/systemd-tasks
 ```
 
-The pinned native dependency `@primafuture/socket-fdx@1.0.0` is installed under
-the npm alias `usocket` and supplies its compatible `USocket` adapter. It ships a
-prebuilt native binary: ordinary installation needs no compiler, Python, or install
-scripts. Consumers do not need `overrides`. The dependency is pinned to its stable release;
-musl Linux and other architectures are outside its current support. The JavaScript D-Bus stack
+The native dependency `@primafuture/socket-fdx@1.1.0` is installed under the npm
+alias `usocket` and supplies both the D-Bus adapter and explicitly owned Unix
+socket-pair primitives. It is pinned to the exact published release and ships a
+prebuilt native binary, so ordinary installation needs no compiler, Python, install
+scripts, or consumer override. Musl Linux and other architectures remain unsupported.
+The JavaScript D-Bus stack
 (`dbus-next@0.10.2` and its dependencies) is bundled; licenses are recorded in
 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
@@ -29,6 +30,9 @@ that the retention executable resolves to a regular executable file before openi
 the bus, then verifies the manager environment. It fails explicitly; the library does not provision a manager,
 enable linger, request elevated privileges, or fall back to child_process.
 Importing either the ESM or CommonJS entrypoint does not connect or start a process.
+Observed tasks additionally require `/usr/bin/systemd-notify`, `/usr/bin/systemctl`,
+and the packaged guardian bundle; `connectObserved()` verifies them before opening
+the bus.
 
 ## Basic execution
 
@@ -70,6 +74,79 @@ environment that are absent from this map, using a snapshot immediately before
 submission. Systemd may add execution metadata such as `INVOCATION_ID`. Concurrent
 external changes to manager configuration are outside this guarantee.
 
+## Observed execution
+
+The separate `@primafuture/systemd-tasks/observed` entrypoint adds live binary
+stdout/stderr delivery without wrapping the payload process:
+
+```ts
+import * as observed from '@primafuture/systemd-tasks/observed';
+
+const intent = observed.prepareObserved({
+	executable: '/usr/bin/sort',
+	argv: [],
+	cwd: '/tmp',
+	env: {},
+	runtimeLimitMs: 5000,
+	stopGraceMs: 500,
+	stdin: 'second\nfirst\n',
+});
+
+const client = await observed.connectObserved();
+try {
+	const started = await client.startObserved(intent, {
+		async onOutput(event) {
+			// Awaiting here applies bounded backpressure to both output channels.
+			await consume(event.stream, event.data);
+		},
+	});
+	await started.observation.completion;
+	const completed = await client.wait(intent, { timeoutMs: 10000 });
+	await client.release(completed.reference);
+} finally {
+	await client.disconnect();
+}
+```
+
+`stdin` is mandatory. A string is snapshotted as UTF-8, a `Uint8Array` is copied,
+an empty value remains an explicit empty data input, and `null` selects `/dev/null`.
+The fixed limit is 512 KiB, chosen to remain below systemd's manager-state line
+serialization boundary after base64 expansion. The canonical base64 snapshot is
+part of the serialized intent and its fingerprint. Systemd owns `StandardInputData` after submission and
+may retain those bytes in manager state until release, so treat the intent and
+manager access as sensitive when stdin contains secrets.
+
+Each observed task consists of payload, retention, and `Type=notify` guardian
+services created by one `StartTransientUnit` transaction. The payload is ordered
+after and `BindsTo` the guardian; both process services require successful
+retention initialization. `startObserved()` returns only after manager
+acceptance and guardian readiness, with a fixed five-second readiness budget. A
+failure after manager acceptance reports `mutationOutcome: 'accepted'`; it is not
+permission to retry.
+
+Output callbacks are sequential and their returned promises provide real bounded
+backpressure. Callback failure rejects `observation.completion` with
+`OBSERVATION_FAILED` and detaches locally; it does not stop the payload. `detach()`
+and `disconnect()` likewise close only the local observer. The guardian continues
+to drain and discard both channels so the payload does not receive `EPIPE` merely
+because the client left. There is deliberately no reconnect, replay, or adoption
+of another client's live stream. Use ordinary durable file I/O instead when output
+must survive observation loss.
+
+An already-invoked callback is application code and cannot be cancelled. Explicit
+detach closes the socket and settles `completion` as `detached` without waiting for
+that callback promise; no later callback is invoked, and a later settlement of the
+detached callback cannot change the observation outcome or block `disconnect()`.
+
+The guardian emits a private versioned binary protocol with separate stdout and
+stderr frames. Payload bytes and callback causes are never included in diagnostics.
+`wait()` reports payload and guardian results independently and reaches `completed`
+only after both services are terminal with confirmed empty cgroups. `stop()` targets
+the payload; systemd propagates that stop to the guardian in reverse dependency
+order, so it drains bytes already written before completing. This also closes a
+guardian whose payload start was cancelled before exec. `release()` refuses until
+both process services are clean, then removes retention.
+
 ## Lifecycle and recovery
 
 | Operation | Contract |
@@ -206,7 +283,7 @@ service manipulation can invalidate evidence. The library does not enable linger
 recreate missing tasks, implement a daemon, or promise survival when the manager
 itself stops. Connection failure is distinct from missing units.
 
-The only advanced properties allowed in 1.0.0 are `CPUWeight` and `IOWeight`, each
+The only advanced properties allowed in 1.x are `CPUWeight` and `IOWeight`, each
 with signature `'t'` and an integer value from 1 to 10000. Duplicates, unknown
 properties, and lifecycle overrides are rejected before mutation. Kernel/controller
 configuration determines the practical scheduling effect of those weights.
@@ -228,7 +305,8 @@ npm run check
 `check` runs strict typechecking, unit tests, real systemd integration tests, dual
 ESM/CJS build, and tarball runtime/type smoke tests. `prepublishOnly` invokes the
 same chain. Integration tests fail explicitly when prerequisites are missing.
-Tests create unique identities and clean only their recorded task/retention pairs.
+Tests create unique identities and clean only their recorded task/retention pairs,
+plus the exact guardian identity for observed tests.
 They do not restart the user manager or change host configuration.
 
 Runnable repository examples after `npm run build`:

package/THIRD_PARTY_NOTICES.md

@@ -25,7 +25,7 @@ This file is generated by `scripts/licenses.ts` from the distributed source map.
 
 ## External native dependency
 
-`@primafuture/socket-fdx` 1.0.0 (ISC) is installed separately under the npm alias `usocket`. It ships its native binary, license, and third-party notices, has no runtime dependencies, and is not embedded in this JavaScript bundle. The direct pinned alias applies in consumer installations without root overrides.
+`@primafuture/socket-fdx` 1.1.0 (ISC) is installed separately under the npm alias `usocket`. It ships its native binary, license, and third-party notices, has no runtime dependencies, and is not embedded in this JavaScript bundle. The direct pinned alias applies in consumer installations without root overrides.
 
 ## @nornagon/put 0.0.8
 

package/dist/guardian.mjs

@@ -0,0 +1,212 @@
+// src/guardian.ts
+import * as childProcess from "child_process";
+import * as fs from "fs";
+import * as net from "net";
+
+// src/observed-framing.ts
+var magic = Buffer.from("SDTO", "ascii");
+var version = 1;
+var headerBytes = 10;
+var maximumPayloadBytes = 64 * 1024;
+var kind = Object.freeze({ ready: 1, stdout: 2, stderr: 3, complete: 4 });
+function encode(frameKind, payload = new Uint8Array()) {
+  if (!Object.values(kind).includes(frameKind) || payload.byteLength > maximumPayloadBytes) throw new Error("Invalid observed guardian frame.");
+  const frame = Buffer.allocUnsafe(headerBytes + payload.byteLength);
+  magic.copy(frame, 0);
+  frame[4] = version;
+  frame[5] = frameKind;
+  frame.writeUInt32BE(payload.byteLength, 6);
+  frame.set(payload, headerBytes);
+  return frame;
+}
+
+// src/guardian.ts
+function fail(message, cause) {
+  throw new Error(`Observed task guardian failed: ${message}`, cause === void 0 ? void 0 : { cause });
+}
+function validateDescriptors() {
+  if (process.env.LISTEN_PID !== String(process.pid)) fail("LISTEN_PID does not identify this process.");
+  if (process.env.LISTEN_FDS !== "3") fail("LISTEN_FDS is not exactly three.");
+  if (process.env.LISTEN_FDNAMES !== "task-stdout:task-stderr:observer") fail("LISTEN_FDNAMES has an unexpected order.");
+  for (const descriptor of [3, 4, 5]) if (!fs.fstatSync(descriptor).isSocket()) fail(`descriptor ${descriptor} is not a socket.`);
+  delete process.env.LISTEN_PID;
+  delete process.env.LISTEN_FDS;
+  delete process.env.LISTEN_FDNAMES;
+}
+function notifyReady() {
+  const result = childProcess.spawnSync("/usr/bin/systemd-notify", ["--ready", "--pid=parent"], {
+    env: process.env,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    timeout: 5e3
+  });
+  if (result.error) fail("systemd-notify could not execute.", result.error);
+  if (result.status !== 0) fail(`systemd-notify exited with status ${String(result.status)}.`);
+}
+function payloadWasInvoked(unitName) {
+  if (process.getuid === void 0) return null;
+  const runtimeDirectory = `/run/user/${String(process.getuid())}`;
+  const result = childProcess.spawnSync("/usr/bin/systemctl", ["--user", "show", unitName, "--property=InvocationID", "--value"], {
+    env: { XDG_RUNTIME_DIR: runtimeDirectory, DBUS_SESSION_BUS_ADDRESS: `unix:path=${runtimeDirectory}/bus` },
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
+    timeout: 5e3,
+    maxBuffer: 4096
+  });
+  if (result.error || result.status !== 0) return null;
+  const invocationId = result.stdout.trim();
+  if (invocationId === "") return false;
+  return /^[0-9a-f]{32}$/.test(invocationId) ? true : null;
+}
+async function writeReady(observer) {
+  return await new Promise(
+    /** Chyba client-facing socketu znamená detach, nikoliv selhání guardian infrastruktury. */
+    (resolve) => {
+      try {
+        observer.write(encode(kind.ready), (error) => {
+          resolve(error === void 0 || error === null);
+        });
+      } catch {
+        resolve(false);
+      }
+    }
+  );
+}
+async function run() {
+  validateDescriptors();
+  const payloadUnitName = process.argv[2];
+  if (!payloadUnitName || !/^pf-systemd-tasks-observed-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\.service$/.test(payloadUnitName)) fail("payload unit name is invalid.");
+  const stdout = new net.Socket({ fd: 3, readable: true, writable: false });
+  const stderr = new net.Socket({ fd: 4, readable: true, writable: false });
+  const observer = new net.Socket({ fd: 5, readable: true, writable: true, allowHalfOpen: true });
+  const sources = [
+    { stream: stdout, kind: kind.stdout, ended: false, pending: null },
+    { stream: stderr, kind: kind.stderr, ended: false, pending: null }
+  ];
+  let attached = true;
+  let blocked = false;
+  let pumping = false;
+  let finishing = false;
+  let nextSourceIndex = 0;
+  let readyFrameSettled = false;
+  function detach() {
+    if (!attached) return;
+    attached = false;
+    blocked = false;
+    observer.destroy();
+    for (const source of sources) {
+      source.pending = null;
+      source.stream.off("readable", pump);
+      source.stream.resume();
+    }
+  }
+  function finishIfComplete() {
+    if (!readyFrameSettled || finishing || !sources.every(
+      /** Oba payload descriptory musí potvrdit EOF. */
+      (source) => source.ended
+    )) return;
+    finishing = true;
+    if (!attached) process.exit(0);
+    observer.end(
+      encode(kind.complete),
+      /** Lokální shutdown callback potvrzuje odeslaný FIN bez čekání na vzdálený close. */
+      () => process.exit(0)
+    );
+  }
+  function pump() {
+    if (pumping || blocked || !readyFrameSettled) return;
+    pumping = true;
+    try {
+      let idleSources = 0;
+      while (!blocked && idleSources < sources.length) {
+        const source = sources[nextSourceIndex];
+        nextSourceIndex = (nextSourceIndex + 1) % sources.length;
+        const available = source.pending ?? source.stream.read();
+        if (available === null) {
+          idleSources++;
+          continue;
+        }
+        idleSources = 0;
+        const chunk = available.subarray(0, maximumPayloadBytes);
+        source.pending = available.byteLength > chunk.byteLength ? available.subarray(chunk.byteLength) : null;
+        if (attached) {
+          const writable = observer.write(encode(source.kind, chunk));
+          if (attached && !writable) blocked = true;
+        }
+      }
+    } finally {
+      pumping = false;
+    }
+    finishIfComplete();
+  }
+  function sourceFailure(error) {
+    stdout.destroy();
+    stderr.destroy();
+    observer.destroy();
+    process.nextTick(
+      /** Throw mimo EventEmitter callback zachová nenulový process exit. */
+      () => {
+        throw error;
+      }
+    );
+  }
+  for (const source of sources) {
+    source.stream.on("readable", pump);
+    source.stream.once(
+      "end",
+      /** Drain zbytku před terminal EOF. */
+      () => {
+        source.ended = true;
+        pump();
+        finishIfComplete();
+      }
+    );
+    source.stream.once("error", sourceFailure);
+  }
+  observer.on(
+    "drain",
+    /** Pokračuje až po skutečném poklesu Node write fronty. */
+    () => {
+      blocked = false;
+      pump();
+    }
+  );
+  observer.on(
+    "data",
+    /** Protokol je jednosměrný; neočekávaný klientský payload znamená detach. */
+    detach
+  );
+  observer.once("end", detach);
+  observer.once("close", detach);
+  observer.once("error", detach);
+  process.on(
+    "SIGTERM",
+    /** Jen pre-exec cancellation postrádá skutečné EOF, protože manager dál vlastní write endpointy. */
+    () => {
+      if (payloadWasInvoked(payloadUnitName) !== false) {
+        pump();
+        return;
+      }
+      for (const source of sources) {
+        source.ended = true;
+        source.pending = null;
+        source.stream.destroy();
+      }
+      finishIfComplete();
+    }
+  );
+  notifyReady();
+  if (!await writeReady(observer)) detach();
+  readyFrameSettled = true;
+  if (attached) observer.resume();
+  pump();
+}
+void run().catch(
+  /** Top-level startup failure musí zachovat nenulový guardian exit. */
+  (error) => {
+    process.nextTick(() => {
+      throw error;
+    });
+  }
+);
+//# sourceMappingURL=guardian.mjs.map

package/dist/guardian.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/guardian.ts","../src/observed-framing.ts"],"sourcesContent":["import * as childProcess from 'node:child_process';\nimport * as fs from 'node:fs';\nimport * as net from 'node:net';\nimport * as framing from './observed-framing';\n\n/** Jeden guardian input drží svůj framing kind a případný zbytek velkého stream readu. */\ninterface Source {\n\t/** Raw task stream vlastněný tímto guardian procesem. */\n\treadonly stream: net.Socket;\n\t/** Output kind zachovávající oddělení stdout a stderr. */\n\treadonly kind: typeof framing.kind.stdout | typeof framing.kind.stderr;\n\t/** EOF je autoritativní až po vyčerpání kernel bufferu. */\n\tended: boolean;\n\t/** Zbytek většího readu čekající na další bounded frame. */\n\tpending: Buffer | null;\n}\n\n/** Ukončí guardian fail-closed bez zápisu citlivých output dat na jeho stdio. */\nfunction fail(message: string, cause?: unknown): never {\n\tthrow new Error(`Observed task guardian failed: ${message}`, cause === undefined ? undefined : { cause });\n}\n\n/** Ověří přesný systemd fd-store kontrakt dřív, než guardian oznámí readiness. */\nfunction validateDescriptors(): void {\n\tif (process.env.LISTEN_PID !== String(process.pid)) fail('LISTEN_PID does not identify this process.');\n\tif (process.env.LISTEN_FDS !== '3') fail('LISTEN_FDS is not exactly three.');\n\tif (process.env.LISTEN_FDNAMES !== 'task-stdout:task-stderr:observer') fail('LISTEN_FDNAMES has an unexpected order.');\n\tfor (const descriptor of [3, 4, 5]) if (!fs.fstatSync(descriptor).isSocket()) fail(`descriptor ${descriptor} is not a socket.`);\n\tdelete process.env.LISTEN_PID;\n\tdelete process.env.LISTEN_FDS;\n\tdelete process.env.LISTEN_FDNAMES;\n}\n\n/** Potvrdí systemd readiness synchronně, aby ready frame nikdy nepředběhl selhání notify. */\nfunction notifyReady(): void {\n\tconst result = childProcess.spawnSync('/usr/bin/systemd-notify', ['--ready', '--pid=parent'], {\n\t\tenv: process.env,\n\t\tstdio: ['ignore', 'pipe', 'pipe'],\n\t\tencoding: 'utf8',\n\t\ttimeout: 5000,\n\t});\n\tif (result.error) fail('systemd-notify could not execute.', result.error);\n\tif (result.status !== 0) fail(`systemd-notify exited with status ${String(result.status)}.`);\n}\n\n/** Přečte payload InvocationID až po ordered stopu; prázdná hodnota spolehlivě značí zrušení před exec. */\nfunction payloadWasInvoked(unitName: string): boolean | null {\n\tif (process.getuid === undefined) return null;\n\tconst runtimeDirectory = `/run/user/${String(process.getuid())}`;\n\tconst result = childProcess.spawnSync('/usr/bin/systemctl', ['--user', 'show', unitName, '--property=InvocationID', '--value'], {\n\t\tenv: { XDG_RUNTIME_DIR: runtimeDirectory, DBUS_SESSION_BUS_ADDRESS: `unix:path=${runtimeDirectory}/bus` },\n\t\tstdio: ['ignore', 'pipe', 'pipe'],\n\t\tencoding: 'utf8',\n\t\ttimeout: 5000,\n\t\tmaxBuffer: 4096,\n\t});\n\tif (result.error || result.status !== 0) return null;\n\tconst invocationId = result.stdout.trim();\n\tif (invocationId === '') return false;\n\treturn /^[0-9a-f]{32}$/.test(invocationId) ? true : null;\n}\n\n/** Rozliší lokální acceptance ready frame od observeru odpojeného během startupu. */\nasync function writeReady(observer: net.Socket): Promise<boolean> {\n\treturn await new Promise<boolean>(/** Chyba client-facing socketu znamená detach, nikoliv selhání guardian infrastruktury. */ resolve => {\n\t\ttry { observer.write(framing.encode(framing.kind.ready), error => { resolve(error === undefined || error === null); }); }\n\t\tcatch { resolve(false); }\n\t});\n}\n\n/** Drží output pipes průchozí po detach a končí až po EOF obou payload kanálů. */\nasync function run(): Promise<void> {\n\tvalidateDescriptors();\n\tconst payloadUnitName = process.argv[2];\n\tif (!payloadUnitName || !/^pf-systemd-tasks-observed-[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}\\.service$/.test(payloadUnitName)) fail('payload unit name is invalid.');\n\tconst stdout = new net.Socket({ fd: 3, readable: true, writable: false });\n\tconst stderr = new net.Socket({ fd: 4, readable: true, writable: false });\n\tconst observer = new net.Socket({ fd: 5, readable: true, writable: true, allowHalfOpen: true });\n\tconst sources: Source[] = [\n\t\t{ stream: stdout, kind: framing.kind.stdout, ended: false, pending: null },\n\t\t{ stream: stderr, kind: framing.kind.stderr, ended: false, pending: null },\n\t];\n\tlet attached = true;\n\tlet blocked = false;\n\tlet pumping = false;\n\tlet finishing = false;\n\tlet nextSourceIndex = 0;\n\tlet readyFrameSettled = false;\n\n\t/** Přepne nevratně do drain/discard a uvolní output backpressure payloadu. */\n\tfunction detach(): void {\n\t\tif (!attached) return;\n\t\tattached = false;\n\t\tblocked = false;\n\t\tobserver.destroy();\n\t\tfor (const source of sources) {\n\t\t\tsource.pending = null;\n\t\t\tsource.stream.off('readable', pump);\n\t\t\tsource.stream.resume();\n\t\t}\n\t}\n\n\t/** Po obou EOF odešle jediný complete frame, nebo po detach prostě dovolí exit. */\n\tfunction finishIfComplete(): void {\n\t\tif (!readyFrameSettled || finishing || !sources.every(/** Oba payload descriptory musí potvrdit EOF. */ source => source.ended)) return;\n\t\tfinishing = true;\n\t\tif (!attached) process.exit(0);\n\t\tobserver.end(framing.encode(framing.kind.complete), /** Lokální shutdown callback potvrzuje odeslaný FIN bez čekání na vzdálený close. */ () => process.exit(0));\n\t}\n\n\t/** Fair round-robin čte nejvýše bounded framy a respektuje skutečné EOF i observer write backpressure. */\n\tfunction pump(): void {\n\t\tif (pumping || blocked || !readyFrameSettled) return;\n\t\tpumping = true;\n\t\ttry {\n\t\t\tlet idleSources = 0;\n\t\t\twhile (!blocked && idleSources < sources.length) {\n\t\t\t\tconst source = sources[nextSourceIndex]!;\n\t\t\t\tnextSourceIndex = (nextSourceIndex + 1) % sources.length;\n\t\t\t\tconst available = source.pending ?? source.stream.read();\n\t\t\t\tif (available === null) { idleSources++; continue; }\n\t\t\t\tidleSources = 0;\n\t\t\t\tconst chunk = available.subarray(0, framing.maximumPayloadBytes);\n\t\t\t\tsource.pending = available.byteLength > chunk.byteLength ? available.subarray(chunk.byteLength) : null;\n\t\t\t\tif (attached) {\n\t\t\t\t\tconst writable = observer.write(framing.encode(source.kind, chunk));\n\t\t\t\t\tif (attached && !writable) blocked = true;\n\t\t\t\t}\n\t\t\t}\n\t\t} finally { pumping = false; }\n\t\tfinishIfComplete();\n\t}\n\n\t/** Zdrojová chyba musí shodit guardian a přes BindsTo fail-closed zastavit payload. */\n\tfunction sourceFailure(error: Error): void {\n\t\tstdout.destroy();\n\t\tstderr.destroy();\n\t\tobserver.destroy();\n\t\tprocess.nextTick(/** Throw mimo EventEmitter callback zachová nenulový process exit. */ () => { throw error; });\n\t}\n\n\tfor (const source of sources) {\n\t\tsource.stream.on('readable', pump);\n\t\tsource.stream.once('end', /** Drain zbytku před terminal EOF. */ () => { source.ended = true; pump(); finishIfComplete(); });\n\t\tsource.stream.once('error', sourceFailure);\n\t}\n\tobserver.on('drain', /** Pokračuje až po skutečném poklesu Node write fronty. */ () => { blocked = false; pump(); });\n\tobserver.on('data', /** Protokol je jednosměrný; neočekávaný klientský payload znamená detach. */ detach);\n\tobserver.once('end', detach);\n\tobserver.once('close', detach);\n\tobserver.once('error', detach);\n\tprocess.on('SIGTERM', /** Jen pre-exec cancellation postrádá skutečné EOF, protože manager dál vlastní write endpointy. */ () => {\n\t\tif (payloadWasInvoked(payloadUnitName) !== false) { pump(); return; }\n\t\tfor (const source of sources) {\n\t\t\tsource.ended = true;\n\t\t\tsource.pending = null;\n\t\t\tsource.stream.destroy();\n\t\t}\n\t\tfinishIfComplete();\n\t});\n\n\tnotifyReady();\n\tif (!await writeReady(observer)) detach();\n\treadyFrameSettled = true;\n\tif (attached) observer.resume();\n\tpump();\n}\n\nvoid run().catch(/** Top-level startup failure musí zachovat nenulový guardian exit. */ error => { process.nextTick(() => { throw error; }); });\n","/** Čtyřbytový magic odděluje guardian stream od náhodného nebo staršího protokolu. */\nexport const magic = Buffer.from('SDTO', 'ascii');\n/** První veřejně implementovaná verze interního guardian protokolu. */\nexport const version = 1;\n/** Fixní hlavička obsahuje magic, verzi, kind a uint32be délku. */\nexport const headerBytes = 10;\n/** Jeden payload frame je bounded nezávisle na Node stream high-water marku. */\nexport const maximumPayloadBytes = 64 * 1024;\n\n/** Wire hodnoty jsou stabilní a nesmějí záviset na pořadí TypeScript enumu. */\nexport const kind = Object.freeze({ ready: 1, stdout: 2, stderr: 3, complete: 4 } as const);\n\n/** Zakóduje jeden již bounded frame pro guardian write frontu. */\nexport function encode(frameKind: number, payload: Uint8Array = new Uint8Array()): Buffer {\n\tif (!Object.values(kind).includes(frameKind as 1 | 2 | 3 | 4) || payload.byteLength > maximumPayloadBytes) throw new Error('Invalid observed guardian frame.');\n\tconst frame = Buffer.allocUnsafe(headerBytes + payload.byteLength);\n\tmagic.copy(frame, 0);\n\tframe[4] = version;\n\tframe[5] = frameKind;\n\tframe.writeUInt32BE(payload.byteLength, 6);\n\tframe.set(payload, headerBytes);\n\treturn frame;\n}\n"],"mappings":"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","names":[]}