@descryy/runtime-orchestrator 0.0.0

package/dist/polling-output-source.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A live `ProcessOutputSource` over a polled buffer — the "future poll
+ * adapter" `process-output.ts`'s own header anticipated and left unbuilt.
+ *
+ * `ManagedProcess.readOutput()` returns the whole accumulated
+ * stdout+stderr, not a delta. **Reading it repeatedly and re-emitting
+ * everything would duplicate every line on every tick**, which is the
+ * mistake that made a correlation test read the wrong request id when a
+ * lane hit the same API from the other side. This source keeps the length
+ * it has already consumed and slices forward from it, so each line is
+ * yielded exactly once.
+ *
+ * It ends when `isFinished()` returns true **and** the buffer has stopped
+ * growing — checked in that order, because a process can exit with output
+ * still unread, and stopping at the exit event alone silently drops
+ * whatever it printed on the way out.
+ */
+import { type ProcessOutputSource } from "@descryy/runtime-backend-observation";
+export interface PollingProcessOutputSourceOptions {
+    readonly processId: string;
+    /** The whole accumulated buffer so far — `ManagedProcess.readOutput` has exactly this shape. */
+    readonly readOutput: () => string;
+    /** True once the process has exited. Output already buffered is still drained afterwards. */
+    readonly isFinished: () => boolean;
+    readonly pollIntervalMs?: number;
+}
+export declare function createPollingProcessOutputSource(options: PollingProcessOutputSourceOptions): ProcessOutputSource;
+//# sourceMappingURL=polling-output-source.d.ts.map

package/dist/polling-output-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling-output-source.d.ts","sourceRoot":"","sources":["../src/polling-output-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAwC,KAAK,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEtH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gGAAgG;IAChG,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC;IAClC,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,iCAAiC,GAAG,mBAAmB,CA4DhH"}

package/dist/polling-output-source.js

@@ -0,0 +1,73 @@
+/**
+ * A live `ProcessOutputSource` over a polled buffer — the "future poll
+ * adapter" `process-output.ts`'s own header anticipated and left unbuilt.
+ *
+ * `ManagedProcess.readOutput()` returns the whole accumulated
+ * stdout+stderr, not a delta. **Reading it repeatedly and re-emitting
+ * everything would duplicate every line on every tick**, which is the
+ * mistake that made a correlation test read the wrong request id when a
+ * lane hit the same API from the other side. This source keeps the length
+ * it has already consumed and slices forward from it, so each line is
+ * yielded exactly once.
+ *
+ * It ends when `isFinished()` returns true **and** the buffer has stopped
+ * growing — checked in that order, because a process can exit with output
+ * still unread, and stopping at the exit event alone silently drops
+ * whatever it printed on the way out.
+ */
+import { LineSplitter } from "@descryy/runtime-backend-observation";
+const DEFAULT_POLL_INTERVAL_MS = 50;
+export function createPollingProcessOutputSource(options) {
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    return {
+        processId: options.processId,
+        lines: (async function* () {
+            const splitter = new LineSplitter();
+            let consumed = 0;
+            for (;;) {
+                const whole = options.readOutput();
+                // The forward-slice above rests on one assumption about a
+                // collaborator: that the buffer only ever grows. `ManagedProcess`
+                // satisfies it today (`outputBuffer += chunk`, uncapped), but that
+                // is an implementation detail of another package and an uncapped
+                // buffer is exactly the thing someone eventually caps. On the day a
+                // cap or a rotation lands, `consumed` would sit past the end of the
+                // new buffer and this source would silently emit nothing, forever,
+                // while reporting healthy -- a collector that has stopped working
+                // and does not say so.
+                //
+                // Throwing is the honest response and it already has a destination:
+                // `LogCollector`'s consume loop catches it, emits COLLECTOR_ERROR
+                // and flips `backendLogAccess` to unavailable (RT-036). Silence is
+                // the one option not available.
+                if (whole.length < consumed) {
+                    throw new Error(`process output buffer shrank from ${consumed} to ${whole.length} characters — this source ` +
+                        "slices forward from a consumed offset and cannot reconstruct a truncated or rotated buffer " +
+                        "without either duplicating or dropping lines. Reported rather than guessed.");
+                }
+                if (whole.length > consumed) {
+                    const chunk = whole.slice(consumed);
+                    consumed = whole.length;
+                    const observedAt = new Date().toISOString();
+                    for (const text of splitter.push(chunk)) {
+                        yield { text, stream: "combined", observedAt };
+                    }
+                    // Deliberately loops again without sleeping: a burst of output
+                    // should drain at memory speed, not at the poll interval.
+                    continue;
+                }
+                if (options.isFinished()) {
+                    const observedAt = new Date().toISOString();
+                    // A final unterminated line is real output and is the one most
+                    // likely to matter -- a process that dies mid-write.
+                    for (const text of splitter.flush()) {
+                        yield { text, stream: "combined", observedAt };
+                    }
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            }
+        })(),
+    };
+}
+//# sourceMappingURL=polling-output-source.js.map

package/dist/polling-output-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling-output-source.js","sourceRoot":"","sources":["../src/polling-output-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAoD,MAAM,sCAAsC,CAAC;AAWtH,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAEpC,MAAM,UAAU,gCAAgC,CAAC,OAA0C;IACzF,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAE1E,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC;YACrB,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAE,CAAC;YACpC,IAAI,QAAQ,GAAG,CAAC,CAAC;YAEjB,SAAS,CAAC;gBACR,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;gBAEnC,0DAA0D;gBAC1D,kEAAkE;gBAClE,mEAAmE;gBACnE,iEAAiE;gBACjE,oEAAoE;gBACpE,oEAAoE;gBACpE,mEAAmE;gBACnE,kEAAkE;gBAClE,uBAAuB;gBACvB,EAAE;gBACF,oEAAoE;gBACpE,kEAAkE;gBAClE,mEAAmE;gBACnE,gCAAgC;gBAChC,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;oBAC5B,MAAM,IAAI,KAAK,CACb,qCAAqC,QAAQ,OAAO,KAAK,CAAC,MAAM,4BAA4B;wBAC1F,6FAA6F;wBAC7F,6EAA6E,CAChF,CAAC;gBACJ,CAAC;gBAED,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;oBAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;oBACpC,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC;oBACxB,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;oBAC5C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;wBACxC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;oBACjD,CAAC;oBACD,+DAA+D;oBAC/D,0DAA0D;oBAC1D,SAAS;gBACX,CAAC;gBAED,IAAI,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;oBACzB,MAAM,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;oBAC5C,+DAA+D;oBAC/D,qDAAqD;oBACrD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;wBACpC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;oBACjD,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;YACtE,CAAC;QACH,CAAC,CAAC,EAAE;KACL,CAAC;AACJ,CAAC"}

package/dist/profile-backend-observation.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Profile-driven backend traffic observation (RT-197, DEC-271).
+ *
+ * `InboundProxy` (RT-192) is wired into `runInstrumentedExecution` via
+ * `frontWithInboundProxy` — the **local, Descry-booted** half of DEC-271.
+ * The other half, `@descryhq-wq/runtime-remote-log-ingestion`, existed with real
+ * tests (`correlator.test.ts`, `file-log-adapter.test.ts`) and **zero
+ * callers outside its own package** — the same "built, never wired" shape
+ * DEC-270 found for `safety-gate.ts`'s `evaluateAction`. This module is
+ * that missing wiring, and the decision point DEC-271's own table
+ * describes: given an `EnvironmentProfile`, decide which of the two
+ * mechanisms applies, and never both.
+ *
+ * **The mutual-exclusivity guarantee is structural, not asserted.** This
+ * file does not import `createInboundProxy` — nothing in it, in any branch,
+ * is capable of constructing a proxy. A profile whose `mode` is `"remote"`
+ * or `"production"` can only ever reach `ingestFileLog`; a profile whose
+ * mode is `"localBooted"` is refused here with a `validationError` before
+ * any ingestion is attempted, on the grounds that DEC-271 names no
+ * ingestion mechanism for a profile Descry itself booted (that profile's
+ * proxy path is `runInstrumentedExecution`'s `frontWithInboundProxy`,
+ * driven by `ExecutionConfiguration`, not by this function).
+ *
+ * `"localAttached"` is refused the same way, for a different reason,
+ * disclosed rather than guessed at: DEC-271's own table names exactly two
+ * rows — "local, booted" and "remote (staging/preview) and production" —
+ * and says nothing about the third and fourth of DEC-266's four kinds.
+ * Local-attached is not remote infra (a proxy is not structurally
+ * forbidden the way it is for a target Descry does not own), but it is
+ * also not a process Descry started (so `runInstrumentedExecution`'s
+ * readiness-then-front sequencing, which RT-024 depends on, does not
+ * apply). Inventing an answer for a case the decision text does not cover
+ * would be exactly the guess DEC-266/DEC-271 both reject; this function
+ * says so and refuses instead.
+ */
+import type { Evidence } from "@descryy/runtime-contracts";
+import type { EnvironmentProfile } from "@descryy/runtime-environment-profile";
+import { EvidenceStore } from "@descryy/runtime-evidence-store";
+import { type RemoteLogSourceConfig } from "@descryhq-wq/runtime-remote-log-ingestion";
+/**
+ * The mechanism decision itself, exposed as data rather than only as a
+ * side effect — so a caller (or a test) can inspect *which* mechanism a
+ * profile resolves to without having to run it, and so the "never both"
+ * property is checkable structurally: exactly one of `"inboundProxy"` /
+ * `"remoteLogIngestion"` / `"none"` is ever returned, never two.
+ */
+export type BackendObservationMechanism = {
+    readonly kind: "inboundProxy";
+} | {
+    readonly kind: "remoteLogIngestion";
+    readonly config: RemoteLogSourceConfig;
+} | {
+    readonly kind: "none";
+    readonly reason: string;
+};
+/**
+ * Pure decision function — DEC-271's table read directly off
+ * `EnvironmentProfile.mode`. Never reaches the network or the filesystem;
+ * see `runRemoteLogObservation` below for the mechanism that actually
+ * performs ingestion.
+ */
+export declare function backendObservationMechanismFor(profile: EnvironmentProfile): BackendObservationMechanism;
+export interface RunRemoteLogObservationInput {
+    readonly profile: EnvironmentProfile;
+    readonly executionId: string;
+    /** Where ingested lines are written. Provided rather than constructed, same discipline as `InstrumentedExecutionInput.store`. */
+    readonly store: EvidenceStore;
+}
+export interface RunRemoteLogObservationResult {
+    readonly evidence: readonly Evidence[];
+    /** Set when this function refused to ingest anything -- a profile mode this function does not handle, or a declared source this pass has no adapter for. Evidence is empty and that is a refusal, not an absence of logs. */
+    readonly validationError: string | null;
+}
+/**
+ * The remote/production half of DEC-271, run against one profile's
+ * declared `remoteLogSource`. Reads the source **once** (today's only
+ * concrete adapter, `ingestFileLog`, is one-shot per its own doc — see
+ * `file-log-adapter.ts`) and writes every line through `EvidenceStore` as
+ * `BACKEND_LOG` evidence, so redaction runs (plan §28) exactly the same
+ * way it does for `LogCollector`'s local-process output.
+ *
+ * **Refuses rather than guesses** in three cases, each reported as a
+ * `validationError` rather than a silently empty result:
+ * 1. `profile.mode` is not `"remote"`/`"production"` (see this file's own
+ *    header for the disclosed local-attached gap).
+ * 2. no `remoteLogSource` is declared (DEC-271's "not observable here").
+ * 3. `remoteLogSource.location.kind` is not `"file"` — the only concrete
+ *    adapter this pass has; `"command"`/`"url"` are named-and-typed but
+ *    unbuilt, per `log-source-config.ts`'s own doc.
+ *
+ * **Never constructs `InboundProxy`.** This file does not import it.
+ */
+export declare function runRemoteLogObservation(input: RunRemoteLogObservationInput): Promise<RunRemoteLogObservationResult>;
+//# sourceMappingURL=profile-backend-observation.d.ts.map

package/dist/profile-backend-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-backend-observation.d.ts","sourceRoot":"","sources":["../src/profile-backend-observation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAA2C,KAAK,qBAAqB,EAAE,MAAM,2CAA2C,CAAC;AAIhI;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,kBAAkB,GAAG,2BAA2B,CAmBvG;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iIAAiI;IACjI,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;IACvC,6NAA6N;IAC7N,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,6BAA6B,CAAC,CA2DzH"}

package/dist/profile-backend-observation.js

@@ -0,0 +1,136 @@
+/**
+ * Profile-driven backend traffic observation (RT-197, DEC-271).
+ *
+ * `InboundProxy` (RT-192) is wired into `runInstrumentedExecution` via
+ * `frontWithInboundProxy` — the **local, Descry-booted** half of DEC-271.
+ * The other half, `@descryhq-wq/runtime-remote-log-ingestion`, existed with real
+ * tests (`correlator.test.ts`, `file-log-adapter.test.ts`) and **zero
+ * callers outside its own package** — the same "built, never wired" shape
+ * DEC-270 found for `safety-gate.ts`'s `evaluateAction`. This module is
+ * that missing wiring, and the decision point DEC-271's own table
+ * describes: given an `EnvironmentProfile`, decide which of the two
+ * mechanisms applies, and never both.
+ *
+ * **The mutual-exclusivity guarantee is structural, not asserted.** This
+ * file does not import `createInboundProxy` — nothing in it, in any branch,
+ * is capable of constructing a proxy. A profile whose `mode` is `"remote"`
+ * or `"production"` can only ever reach `ingestFileLog`; a profile whose
+ * mode is `"localBooted"` is refused here with a `validationError` before
+ * any ingestion is attempted, on the grounds that DEC-271 names no
+ * ingestion mechanism for a profile Descry itself booted (that profile's
+ * proxy path is `runInstrumentedExecution`'s `frontWithInboundProxy`,
+ * driven by `ExecutionConfiguration`, not by this function).
+ *
+ * `"localAttached"` is refused the same way, for a different reason,
+ * disclosed rather than guessed at: DEC-271's own table names exactly two
+ * rows — "local, booted" and "remote (staging/preview) and production" —
+ * and says nothing about the third and fourth of DEC-266's four kinds.
+ * Local-attached is not remote infra (a proxy is not structurally
+ * forbidden the way it is for a target Descry does not own), but it is
+ * also not a process Descry started (so `runInstrumentedExecution`'s
+ * readiness-then-front sequencing, which RT-024 depends on, does not
+ * apply). Inventing an answer for a case the decision text does not cover
+ * would be exactly the guess DEC-266/DEC-271 both reject; this function
+ * says so and refuses instead.
+ */
+import { EvidenceStore } from "@descryy/runtime-evidence-store";
+import { ingestFileLog } from "@descryhq-wq/runtime-remote-log-ingestion";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/**
+ * Pure decision function — DEC-271's table read directly off
+ * `EnvironmentProfile.mode`. Never reaches the network or the filesystem;
+ * see `runRemoteLogObservation` below for the mechanism that actually
+ * performs ingestion.
+ */
+export function backendObservationMechanismFor(profile) {
+    if (profile.mode === "localBooted") {
+        return { kind: "inboundProxy" };
+    }
+    if (profile.mode === "remote" || profile.mode === "production") {
+        if (profile.remoteLogSource == null) {
+            return {
+                kind: "none",
+                reason: `profile "${profile.name}" is mode "${profile.mode}" but declares no remoteLogSource -- DEC-271's honest "not observable here", not an error.`,
+            };
+        }
+        return { kind: "remoteLogIngestion", config: profile.remoteLogSource };
+    }
+    // mode === "localAttached" -- see this file's header for why this is a
+    // disclosed gap rather than a guessed answer.
+    return {
+        kind: "none",
+        reason: `profile "${profile.name}" is mode "localAttached" -- DEC-271 names a mechanism for neither local-attached nor any third case; not guessed at here.`,
+    };
+}
+/**
+ * The remote/production half of DEC-271, run against one profile's
+ * declared `remoteLogSource`. Reads the source **once** (today's only
+ * concrete adapter, `ingestFileLog`, is one-shot per its own doc — see
+ * `file-log-adapter.ts`) and writes every line through `EvidenceStore` as
+ * `BACKEND_LOG` evidence, so redaction runs (plan §28) exactly the same
+ * way it does for `LogCollector`'s local-process output.
+ *
+ * **Refuses rather than guesses** in three cases, each reported as a
+ * `validationError` rather than a silently empty result:
+ * 1. `profile.mode` is not `"remote"`/`"production"` (see this file's own
+ *    header for the disclosed local-attached gap).
+ * 2. no `remoteLogSource` is declared (DEC-271's "not observable here").
+ * 3. `remoteLogSource.location.kind` is not `"file"` — the only concrete
+ *    adapter this pass has; `"command"`/`"url"` are named-and-typed but
+ *    unbuilt, per `log-source-config.ts`'s own doc.
+ *
+ * **Never constructs `InboundProxy`.** This file does not import it.
+ */
+export async function runRemoteLogObservation(input) {
+    const { profile, executionId, store } = input;
+    const mechanism = backendObservationMechanismFor(profile);
+    if (mechanism.kind !== "remoteLogIngestion") {
+        const reason = mechanism.kind === "none"
+            ? mechanism.reason
+            : `profile "${profile.name}" resolves to mechanism "${mechanism.kind}", not remote log ingestion -- runRemoteLogObservation never constructs an InboundProxy, so it refuses rather than silently doing nothing.`;
+        return { evidence: [], validationError: reason };
+    }
+    const { config } = mechanism;
+    if (config.location.kind !== "file") {
+        return {
+            evidence: [],
+            validationError: `remoteLogSource.location.kind "${config.location.kind}" has no ingestion adapter yet -- only "file" is built (see file-log-adapter.ts's own doc); not observable here.`,
+        };
+    }
+    const fileConfig = { ...config, location: config.location };
+    let lines;
+    try {
+        lines = await ingestFileLog({ config: fileConfig });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { evidence: [], validationError: `remote log ingestion failed for profile "${profile.name}": ${detail}` };
+    }
+    const evidence = [];
+    for (const line of lines) {
+        evidence.push(store.write({
+            executionId,
+            timestamp: line.timestamp ?? new Date().toISOString(),
+            source: "backend-process",
+            service: null,
+            process: null,
+            eventType: "BACKEND_LOG",
+            payload: { raw: line.raw, ingestedVia: "remote-log-ingestion", profile: profile.name },
+            traceId: line.traceId,
+            requestId: line.requestId,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            // The observation itself (a line the target already logged) is not
+            // probabilistic -- same reasoning LogCollector's own emit gives
+            // for confidence: 1. Whether a LATER correlation to a captured
+            // request holds is a separate, lower-confidence question
+            // (`correlateLogLine`'s own confidence tiers), not this field's.
+            confidence: 1,
+            collectorVersion: COLLECTOR_VERSION,
+        }));
+    }
+    return { evidence, validationError: null };
+}
+//# sourceMappingURL=profile-backend-observation.js.map

package/dist/profile-backend-observation.js.map

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

package/dist/respawn-and-supervise.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Respawn-and-supervise: a real, separate execution mode next to attach
+ * mode, not a change to attach mode itself.
+ *
+ * **The tradeoff this makes, stated up front, because it must never be
+ * applied silently.** Attach mode (`attach-to-running-process.ts` and its
+ * siblings) reaches a process that was already running, unconfined, before
+ * Descry touched it -- `sandbox.ts`'s own module doc (`@descryhq-wq/runtime-
+ * controller`) says plainly there is no honest way to retroactively contain
+ * that process. This module does not try. It kills the attached target and
+ * spawns a fresh, equivalent process through the EXISTING `spawnProcess()`
+ * (`@descryy/runtime-controller`), which already gets full sandboxing
+ * (`applySandbox`, `applyResourceLimits`) for anything it spawns -- the same
+ * mechanism `ExecutionController.run()` uses, not a parallel one. The price
+ * is real: in-memory state, open connections, anything the old process held
+ * that was never persisted is gone the moment it is killed. A caller must
+ * choose this explicitly; nothing in this repo switches a running attach
+ * into a respawn on its own.
+ *
+ * **How this module learns what to respawn -- the design question this
+ * lane was told not to guess past.** This repo has a standing, named
+ * precedent for exactly this shape of question: RT-032 ("declared, never
+ * inferred" -- `ServiceConfiguration.dependsOn`, `substitutePortPlaceholders`,
+ * `discoverRunner`'s refusal to sniff a test framework from `package.json`).
+ * The caller-declared path (`RespawnCommand` with `source: "caller-declared"`)
+ * is the one this module recommends and the only one its own convenience
+ * default reaches for. A `/proc/<pid>/cmdline` readback (Linux-only, and
+ * genuinely insufficient on its own -- it cannot recover env vars set
+ * programmatically before `exec`, file descriptors already open and handed
+ * off, or a cwd that changed after launch) is real, but explicitly a
+ * best-effort convenience, never the default: `inferRespawnCommandFromProc`
+ * exists, is opt-in, and labels its own output `source: "proc-cmdline-
+ * inferred"` so nothing downstream can mistake an inference for a
+ * declaration. The two are never blurred into one shape.
+ *
+ * **Killing the old process.** `respawnAndSupervise` does not assume it owns
+ * the target's process group -- an attached-to process was not spawned by
+ * this runtime and may not even be its own group leader, so this signals
+ * the individual pid only (SIGTERM, then SIGKILL after `gracePeriodMs` if
+ * still alive), mirroring `process-manager.ts`'s own two-stage `kill()`
+ * without reusing its group-kill (`signalGroup`), which is `spawnProcess`'s
+ * own escape hatch for a group *it* created.
+ */
+import { type ManagedProcess, type SpawnProcessOptions } from "@descryy/runtime-controller";
+export type RespawnCommandSource = "caller-declared" | "proc-cmdline-inferred";
+/**
+ * Everything `spawnProcess` needs to relaunch an equivalent of the killed
+ * target, plus `source` -- the one field that is never optional, so a
+ * caller (and anything logging or auditing this decision later) can always
+ * tell a real declaration from a best-effort guess at a glance, never by
+ * inspecting provenance out of band.
+ */
+export interface RespawnCommand {
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly source: RespawnCommandSource;
+}
+export interface RespawnAndSuperviseOptions {
+    readonly processId: string;
+    /** The pid of the already-running, attached-to target. Verified alive before anything is killed. */
+    readonly targetPid: number;
+    /** How the replacement process is launched. See this module's own doc for why `source: "caller-declared"` is the recommended, default-reachable path. */
+    readonly respawn: RespawnCommand;
+    /** How long to wait for the old target to exit after SIGTERM before escalating to SIGKILL. Same default as `ManagedProcess.kill()`. */
+    readonly gracePeriodMs?: number;
+    readonly serviceName?: string;
+    readonly port?: number;
+    readonly resourceLimits?: SpawnProcessOptions["resourceLimits"];
+    readonly filesystemPolicy?: SpawnProcessOptions["filesystemPolicy"];
+    readonly networkPolicy?: SpawnProcessOptions["networkPolicy"];
+}
+export interface RespawnAndSuperviseResult {
+    /** The freshly spawned, fully-supervised (and, if declared, sandboxed) replacement -- everything `spawnProcess()` itself returns, unwrapped. */
+    readonly managedProcess: ManagedProcess;
+    readonly killedPid: number;
+    /** Whether the old target was observed to exit within `gracePeriodMs` of SIGTERM, or needed SIGKILL. Either way this does not return until the old pid is confirmed dead. */
+    readonly killedViaSigkill: boolean;
+    readonly respawnSource: RespawnCommandSource;
+}
+/**
+ * Kills the process at `options.targetPid` and spawns a fresh, supervised,
+ * (optionally) sandboxed replacement via `spawnProcess()`.
+ *
+ * **Not a silent behavior change to attach mode.** A caller reaches this
+ * function by name, explicitly, instead of one of the `attachToRunning*`
+ * functions -- there is no code path in this repo that upgrades an attach
+ * into a respawn on its own. `ATTACH_MODE_SCOPE_DISCLOSURE`
+ * (`@descryy/runtime-controller`) still governs attach mode itself,
+ * unconditionally, whether or not a caller ever reaches for this
+ * alternative.
+ *
+ * Throws (does not silently proceed) if `targetPid` is not alive at call
+ * time, matching `attachToRunningProcess`'s own "refuse rather than operate
+ * on a target that does not exist" contract.
+ */
+export declare function respawnAndSupervise(options: RespawnAndSuperviseOptions): Promise<RespawnAndSuperviseResult>;
+/**
+ * The opt-in, disclosed, BEST-EFFORT convenience this module's own doc
+ * names -- never the default `respawnAndSupervise` reaches for on its own.
+ * Reads `/proc/<pid>/cmdline`, `/proc/<pid>/cwd` and `/proc/<pid>/environ`
+ * to reconstruct a `RespawnCommand`, labelling it `source:
+ * "proc-cmdline-inferred"` so it can never be mistaken for a caller
+ * declaration downstream.
+ *
+ * **Real, disclosed limitations, not hypothetical ones:** Linux-only (no
+ * `/proc` on macOS/Windows); env vars a process set on itself
+ * programmatically after `exec` (as opposed to what it was launched with)
+ * are invisible here, because `/proc/<pid>/environ` only ever reflects the
+ * environment at `execve()` time; already-open file descriptors handed to
+ * the original process (an inherited socket, a pipe from its own parent)
+ * have no representation in a command line at all and cannot be recovered
+ * by any means this function has. Returns `null` -- never throws, never
+ * guesses a partial answer -- when `/proc/<pid>/cmdline` cannot be read
+ * (platform mismatch, pid gone, permission denied) or is empty.
+ */
+export declare function inferRespawnCommandFromProc(pid: number, platform?: NodeJS.Platform): RespawnCommand | null;
+//# sourceMappingURL=respawn-and-supervise.d.ts.map

package/dist/respawn-and-supervise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respawn-and-supervise.d.ts","sourceRoot":"","sources":["../src/respawn-and-supervise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAI1G,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,uBAAuB,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yJAAyJ;IACzJ,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,uIAAuI;IACvI,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,mBAAmB,CAAC,eAAe,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,yBAAyB;IACxC,gJAAgJ;IAChJ,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6KAA6K;IAC7K,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;CAC9C;AAyDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA6BjH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,cAAc,GAAG,IAAI,CAgD5H"}