@descryy/runtime-controller 0.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa1F,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAG5F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,2BAA2B,EAC3B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,8BAA8B,EAC9B,0BAA0B,EAC1B,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,0BAA0B,EAC1B,sCAAsC,EACtC,mCAAmC,EACnC,uCAAuC,EACvC,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAGvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAajI,OAAO,EAAE,eAAe,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/orchestration.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Turns a declarative `services` map (plan §6, RT-028) into a concrete
+ * spawn order for `ExecutionController.run()` (RT-032). Everything here is
+ * pure and side-effect-free — validated and ordered before anything is
+ * spawned, so a bad reference is refused atomically rather than discovered
+ * mid-sequence with some services already running.
+ *
+ * Start order and port injection are **declared in configuration, never
+ * inferred** — the same "ask, don't guess" discipline RT-023 already
+ * applied to browser script-URL roots. A `${name.port}` reference alone
+ * does not create an ordering guarantee; `name` must also appear in the
+ * referencing service's own `dependsOn`, or validation refuses.
+ */
+import type { ServiceConfiguration } from "@descryy/runtime-contracts";
+export type ServicesValidation = {
+    readonly valid: true;
+    readonly order: readonly string[];
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Validates a `services` map and returns a valid topological spawn order.
+ * Three checks, all before anything is spawned:
+ * 1. every `dependsOn` entry names a real key in `services`;
+ * 2. the `dependsOn` graph has no cycle (a start order must exist);
+ * 3. every `${name}.port` placeholder referenced in a service's own `env`
+ *    has `name` in that same service's `dependsOn` — the placeholder does
+ *    not itself create the ordering guarantee it depends on.
+ */
+export declare function validateServicesConfiguration(services: Readonly<Record<string, ServiceConfiguration>>): ServicesValidation;
+/**
+ * Replaces every `${name}.port` in `env`'s values with the resolved port
+ * for `name`. Assumes `validateServicesConfiguration` already confirmed
+ * every referenced name is a declared dependency that the caller resolves
+ * earlier in the same spawn order — a reference this function can't
+ * resolve is left untouched rather than silently dropped, so a caller that
+ * skipped validation sees an obviously-wrong literal `${...}` instead of a
+ * silently empty substitution.
+ */
+export declare function substitutePortPlaceholders(env: Readonly<Record<string, string>> | undefined, resolvedPorts: ReadonlyMap<string, number>): Record<string, string>;
+export type CommandTokenization = {
+    readonly ok: true;
+    readonly command: string;
+    readonly args: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes
+ * (literal throughout), double quotes (with `\` escaping `"` and `\`), and
+ * backslash escapes outside quotes. `spawnProcess` takes `command`/`args`
+ * separately while configuration carries one string (plan §6's YAML shape),
+ * so something has to split it, and doing that by whitespace alone breaks
+ * every path with a space in it — `"C:\Program Files\node.exe"` and
+ * `python3 -c "import app; app.main()"` both tokenized wrong before.
+ *
+ * **Refuses rather than guesses** on an unterminated quote, a trailing
+ * backslash, or an unquoted shell operator. Each of those has no correct
+ * interpretation without a shell, and returning a plausible tokenization
+ * for input that cannot mean what it says is how a configuration error
+ * arrives disguised as an application failure.
+ *
+ * Globs and `~` are *not* refused: they pass through literally, which is
+ * exactly what happens with no shell, and unlike the operators above they
+ * are frequently intended literally.
+ */
+export declare function tokenizeCommand(raw: string): CommandTokenization;
+//# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration.d.ts","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAiBvE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,GACvD,kBAAkB,CA+DpB;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,EACjD,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CA8EhE"}

package/dist/orchestration.js

@@ -0,0 +1,255 @@
+/**
+ * Turns a declarative `services` map (plan §6, RT-028) into a concrete
+ * spawn order for `ExecutionController.run()` (RT-032). Everything here is
+ * pure and side-effect-free — validated and ordered before anything is
+ * spawned, so a bad reference is refused atomically rather than discovered
+ * mid-sequence with some services already running.
+ *
+ * Start order and port injection are **declared in configuration, never
+ * inferred** — the same "ask, don't guess" discipline RT-023 already
+ * applied to browser script-URL roots. A `${name.port}` reference alone
+ * does not create an ordering guarantee; `name` must also appear in the
+ * referencing service's own `dependsOn`, or validation refuses.
+ */
+/**
+ * Bounded at `{1,256}`, not `+`, since RT-070's own regex audit (prompted by
+ * RT-069's ReDoS finding in `evidence-store/redaction.ts`) named this exact
+ * shape: an unbounded character class immediately followed by a required
+ * literal (`.port}`) that can be absent from the input. On a long string
+ * with `${` but no closing `.port}`, an unbounded class here would
+ * backtrack once per starting position -- O(n^2). `service.env` values are
+ * developer-authored configuration, not runtime/adversarial data, which is
+ * why this was flagged low-risk rather than urgent -- but the shape is
+ * identical to the one that DID become a real denial-of-service on a
+ * different input source the same day, and 256 characters is far more than
+ * any real service or dependency name needs.
+ */
+const PORT_PLACEHOLDER = /\$\{([^}]{1,256})\.port\}/g;
+/**
+ * Validates a `services` map and returns a valid topological spawn order.
+ * Three checks, all before anything is spawned:
+ * 1. every `dependsOn` entry names a real key in `services`;
+ * 2. the `dependsOn` graph has no cycle (a start order must exist);
+ * 3. every `${name}.port` placeholder referenced in a service's own `env`
+ *    has `name` in that same service's `dependsOn` — the placeholder does
+ *    not itself create the ordering guarantee it depends on.
+ */
+export function validateServicesConfiguration(services) {
+    const names = Object.keys(services);
+    for (const name of names) {
+        for (const dep of services[name]?.dependsOn ?? []) {
+            if (!(dep in services)) {
+                return { valid: false, reason: `service "${name}" depends on "${dep}", which is not in services` };
+            }
+        }
+    }
+    const orderResult = topologicalOrder(services, names);
+    if (!orderResult.valid) {
+        return orderResult;
+    }
+    for (const name of names) {
+        const declared = new Set(services[name]?.dependsOn ?? []);
+        for (const value of Object.values(services[name]?.env ?? {})) {
+            for (const match of value.matchAll(PORT_PLACEHOLDER)) {
+                const referenced = match[1];
+                if (referenced !== undefined && !declared.has(referenced)) {
+                    return {
+                        valid: false,
+                        reason: `service "${name}" references "\${${referenced}.port}" in env but does not declare "${referenced}" in dependsOn`,
+                    };
+                }
+            }
+        }
+    }
+    // Fourth check, and like the other three it runs before anything is
+    // spawned: exactly one of `command`/`attach` per service (RT-attach-mode-
+    // service-configuration). Neither means nothing tells `run()` how to
+    // start this service; both means an ambiguous configuration nothing here
+    // should silently pick a side on.
+    for (const name of names) {
+        const service = services[name];
+        const hasCommand = service?.command !== undefined;
+        const hasAttach = service?.attach !== undefined;
+        if (hasCommand === hasAttach) {
+            return {
+                valid: false,
+                reason: `service "${name}" must declare exactly one of "command" (spawn) or "attach" (attach to an already-running process), not ${hasCommand ? "both" : "neither"}`,
+            };
+        }
+    }
+    // Fifth check, same atomic-refusal placement. A command that cannot be
+    // tokenized is a configuration error, and discovering it mid-sequence
+    // would mean refusing service 3 after services 1 and 2 are already
+    // running — recoverable via rollback, but needlessly: nothing about this
+    // check needs a process to exist.
+    for (const name of names) {
+        const command = services[name]?.command;
+        if (command === undefined)
+            continue;
+        const tokenized = tokenizeCommand(command);
+        if (!tokenized.ok) {
+            return { valid: false, reason: `service "${name}": ${tokenized.reason}` };
+        }
+    }
+    return orderResult;
+}
+function topologicalOrder(services, names) {
+    const order = [];
+    const visited = new Set();
+    const visiting = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return null;
+        if (visiting.has(name))
+            return `cycle detected in dependsOn involving "${name}"`;
+        visiting.add(name);
+        for (const dep of services[name]?.dependsOn ?? []) {
+            const err = visit(dep);
+            if (err !== null)
+                return err;
+        }
+        visiting.delete(name);
+        visited.add(name);
+        order.push(name);
+        return null;
+    }
+    for (const name of names) {
+        const err = visit(name);
+        if (err !== null) {
+            return { valid: false, reason: err };
+        }
+    }
+    return { valid: true, order };
+}
+/**
+ * Replaces every `${name}.port` in `env`'s values with the resolved port
+ * for `name`. Assumes `validateServicesConfiguration` already confirmed
+ * every referenced name is a declared dependency that the caller resolves
+ * earlier in the same spawn order — a reference this function can't
+ * resolve is left untouched rather than silently dropped, so a caller that
+ * skipped validation sees an obviously-wrong literal `${...}` instead of a
+ * silently empty substitution.
+ */
+export function substitutePortPlaceholders(env, resolvedPorts) {
+    const result = {};
+    for (const [key, value] of Object.entries(env ?? {})) {
+        result[key] = value.replace(PORT_PLACEHOLDER, (literal, name) => {
+            const port = resolvedPorts.get(name);
+            return port === undefined ? literal : String(port);
+        });
+    }
+    return result;
+}
+/**
+ * Shell operators that only mean anything to a shell. `spawnProcess` uses
+ * `child_process.spawn` **without** one, deliberately — no implicit shell
+ * means no injection surface and no expansion nobody asked for. So a
+ * command containing these was never going to behave as written: it would
+ * be handed to the program as a literal argument.
+ *
+ * Refusing is the honest answer. The previous whitespace split passed
+ * `node server.mjs > out.log` through as three arguments to `node`, which
+ * starts a process that fails in a way pointing at the application rather
+ * than at its own configuration. Someone who genuinely wants a shell can
+ * say so — `sh -c "..."` tokenizes fine, since the operators are then
+ * inside quotes where they belong.
+ */
+const SHELL_OPERATORS = new Set(["|", "&", ";", "<", ">", "`", "$"]);
+/**
+ * POSIX-style tokenizer for `ServiceConfiguration.command`: single quotes
+ * (literal throughout), double quotes (with `\` escaping `"` and `\`), and
+ * backslash escapes outside quotes. `spawnProcess` takes `command`/`args`
+ * separately while configuration carries one string (plan §6's YAML shape),
+ * so something has to split it, and doing that by whitespace alone breaks
+ * every path with a space in it — `"C:\Program Files\node.exe"` and
+ * `python3 -c "import app; app.main()"` both tokenized wrong before.
+ *
+ * **Refuses rather than guesses** on an unterminated quote, a trailing
+ * backslash, or an unquoted shell operator. Each of those has no correct
+ * interpretation without a shell, and returning a plausible tokenization
+ * for input that cannot mean what it says is how a configuration error
+ * arrives disguised as an application failure.
+ *
+ * Globs and `~` are *not* refused: they pass through literally, which is
+ * exactly what happens with no shell, and unlike the operators above they
+ * are frequently intended literally.
+ */
+export function tokenizeCommand(raw) {
+    const tokens = [];
+    let current = "";
+    let started = false; // distinguishes an empty quoted token ('') from no token
+    let quote = null;
+    for (let i = 0; i < raw.length; i++) {
+        const char = raw[i];
+        if (quote === "'") {
+            if (char === "'")
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (quote === '"') {
+            if (char === "\\") {
+                const next = raw[i + 1];
+                if (next === undefined)
+                    return { ok: false, reason: 'command ends with a trailing backslash inside a double-quoted string, which escapes nothing' };
+                // Only `"` and `\` are escapable inside double quotes; anything
+                // else keeps the backslash, as a shell would.
+                if (next === '"' || next === "\\") {
+                    current += next;
+                    i++;
+                }
+                else {
+                    current += char;
+                }
+                continue;
+            }
+            if (char === '"')
+                quote = null;
+            else
+                current += char;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (char === "\\") {
+            const next = raw[i + 1];
+            if (next === undefined)
+                return { ok: false, reason: "command ends with a trailing backslash, which escapes nothing" };
+            current += next;
+            started = true;
+            i++;
+            continue;
+        }
+        if (SHELL_OPERATORS.has(char)) {
+            return {
+                ok: false,
+                reason: `command contains the shell operator "${char}" outside quotes, but processes are spawned without a shell — ` +
+                    `it would be passed to the program as a literal argument rather than interpreted. ` +
+                    `Use an explicit shell (sh -c "...") if that is what you meant.`,
+            };
+        }
+        if (/\s/.test(char)) {
+            if (started) {
+                tokens.push(current);
+                current = "";
+                started = false;
+            }
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (quote !== null)
+        return { ok: false, reason: `command has an unterminated ${quote === '"' ? "double" : "single"} quote` };
+    if (started)
+        tokens.push(current);
+    const [head, ...rest] = tokens;
+    if (head === undefined || head === "")
+        return { ok: false, reason: "command is empty" };
+    return { ok: true, command: head, args: rest };
+}
+//# sourceMappingURL=orchestration.js.map

package/dist/orchestration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration.js","sourceRoot":"","sources":["../src/orchestration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAMtD;;;;;;;;GAQG;AACH,MAAM,UAAU,6BAA6B,CAC3C,QAAwD;IAExD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;YAClD,IAAI,CAAC,CAAC,GAAG,IAAI,QAAQ,CAAC,EAAE,CAAC;gBACvB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,IAAI,iBAAiB,GAAG,6BAA6B,EAAE,CAAC;YACrG,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;QAC1D,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;YAC7D,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;gBACrD,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBAC5B,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;oBAC1D,OAAO;wBACL,KAAK,EAAE,KAAK;wBACZ,MAAM,EAAE,YAAY,IAAI,oBAAoB,UAAU,wCAAwC,UAAU,gBAAgB;qBACzH,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,0EAA0E;IAC1E,qEAAqE;IACrE,yEAAyE;IACzE,kCAAkC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,UAAU,GAAG,OAAO,EAAE,OAAO,KAAK,SAAS,CAAC;QAClD,MAAM,SAAS,GAAG,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC;QAChD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,YAAY,IAAI,2GAA2G,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE;aACrK,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,sEAAsE;IACtE,mEAAmE;IACnE,yEAAyE;IACzE,kCAAkC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QACxC,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,IAAI,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,SAAS,gBAAgB,CACvB,QAAwD,EACxD,KAAwB;IAExB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAEnC,SAAS,KAAK,CAAC,IAAY;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,0CAA0C,IAAI,GAAG,CAAC;QACjF,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnB,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;YAClD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,GAAG,KAAK,IAAI;gBAAE,OAAO,GAAG,CAAC;QAC/B,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CACxC,GAAiD,EACjD,aAA0C;IAE1C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,IAAY,EAAE,EAAE;YACtE,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,OAAO,GAAG,KAAK,CAAC,CAAC,yDAAyD;IAC9E,IAAI,KAAK,GAAqB,IAAI,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;QAErB,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,IAAI,IAAI,KAAK,GAAG;gBAAE,KAAK,GAAG,IAAI,CAAC;;gBAC1B,OAAO,IAAI,IAAI,CAAC;YACrB,SAAS;QACX,CAAC;QAED,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACxB,IAAI,IAAI,KAAK,SAAS;oBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6FAA6F,EAAE,CAAC;gBACpJ,gEAAgE;gBAChE,8CAA8C;gBAC9C,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;oBAClC,OAAO,IAAI,IAAI,CAAC;oBAChB,CAAC,EAAE,CAAC;gBACN,CAAC;qBAAM,CAAC;oBACN,OAAO,IAAI,IAAI,CAAC;gBAClB,CAAC;gBACD,SAAS;YACX,CAAC;YACD,IAAI,IAAI,KAAK,GAAG;gBAAE,KAAK,GAAG,IAAI,CAAC;;gBAC1B,OAAO,IAAI,IAAI,CAAC;YACrB,SAAS;QACX,CAAC;QAED,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjC,KAAK,GAAG,IAAI,CAAC;YACb,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QAED,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxB,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+DAA+D,EAAE,CAAC;YACtH,OAAO,IAAI,IAAI,CAAC;YAChB,OAAO,GAAG,IAAI,CAAC;YACf,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QAED,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EACJ,wCAAwC,IAAI,gEAAgE;oBAC5G,mFAAmF;oBACnF,gEAAgE;aACnE,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACrB,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;YACD,SAAS;QACX,CAAC;QAED,OAAO,IAAI,IAAI,CAAC;QAChB,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,QAAQ,EAAE,CAAC;IAC7H,IAAI,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAElC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;IAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACxF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjD,CAAC"}

package/dist/process-collector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `ProcessCollector`: turns `ProcessLifecycleEvent` (`controller.ts`) into
+ * `PROCESS_STARTED` / `PROCESS_READY` / `PROCESS_EXITED` Evidence.
+ *
+ * `backend-observation/collector.ts` named this a non-goal of `LogCollector`
+ * — "whether it becomes Evidence at all is an orchestration-layer question"
+ * — and it stayed unbuilt long enough that all three event types were
+ * declared in `contracts/src/runtime-event.ts` and emitted by nothing
+ * (RUNTIME-CHECKLIST.md §3). This is that orchestration-layer answer: a
+ * plain translator with no lifecycle logic of its own. `ExecutionController`
+ * decides *when* each transition happens (spawn, readiness settling either
+ * way, reap) and calls `RunOptions.onProcessLifecycleEvent` at exactly
+ * those moments; this collector's only job is turning one of those calls
+ * into one `context.emit()` call. It does not spawn anything, does not
+ * decide readiness, and does not know why a process exited — only that it
+ * did, and what `ProcessHandle` says about it.
+ *
+ * **Wiring order is load-bearing.** `start(context)` must be called before
+ * `RunOptions.onProcessLifecycleEvent` can fire — i.e. before
+ * `ExecutionController.run()` is called with this collector's
+ * `handleLifecycleEvent` wired in. `handleLifecycleEvent` throws rather
+ * than silently dropping an event if that order is violated: a lost
+ * PROCESS_STARTED reads to everything downstream as "this process was
+ * never observed," which is a worse and quieter failure than a thrown
+ * error at the exact call site that got the order wrong.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+import type { ProcessLifecycleEvent } from "./controller.ts";
+export interface ProcessCollector extends Collector {
+    /** Wire as `RunOptions.onProcessLifecycleEvent` — see the module doc for the ordering this depends on. */
+    handleLifecycleEvent(event: ProcessLifecycleEvent): void;
+}
+export declare function createProcessCollector(): ProcessCollector;
+//# sourceMappingURL=process-collector.d.ts.map

package/dist/process-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-collector.d.ts","sourceRoot":"","sources":["../src/process-collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAmF,MAAM,4BAA4B,CAAC;AAC7I,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,MAAM,WAAW,gBAAiB,SAAQ,SAAS;IACjD,0GAA0G;IAC1G,oBAAoB,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC1D;AA4ED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAuDzD"}

package/dist/process-collector.js

@@ -0,0 +1,148 @@
+/**
+ * `ProcessCollector`: turns `ProcessLifecycleEvent` (`controller.ts`) into
+ * `PROCESS_STARTED` / `PROCESS_READY` / `PROCESS_EXITED` Evidence.
+ *
+ * `backend-observation/collector.ts` named this a non-goal of `LogCollector`
+ * — "whether it becomes Evidence at all is an orchestration-layer question"
+ * — and it stayed unbuilt long enough that all three event types were
+ * declared in `contracts/src/runtime-event.ts` and emitted by nothing
+ * (RUNTIME-CHECKLIST.md §3). This is that orchestration-layer answer: a
+ * plain translator with no lifecycle logic of its own. `ExecutionController`
+ * decides *when* each transition happens (spawn, readiness settling either
+ * way, reap) and calls `RunOptions.onProcessLifecycleEvent` at exactly
+ * those moments; this collector's only job is turning one of those calls
+ * into one `context.emit()` call. It does not spawn anything, does not
+ * decide readiness, and does not know why a process exited — only that it
+ * did, and what `ProcessHandle` says about it.
+ *
+ * **Wiring order is load-bearing.** `start(context)` must be called before
+ * `RunOptions.onProcessLifecycleEvent` can fire — i.e. before
+ * `ExecutionController.run()` is called with this collector's
+ * `handleLifecycleEvent` wired in. `handleLifecycleEvent` throws rather
+ * than silently dropping an event if that order is violated: a lost
+ * PROCESS_STARTED reads to everything downstream as "this process was
+ * never observed," which is a worse and quieter failure than a thrown
+ * error at the exact call site that got the order wrong.
+ */
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/**
+ * All seven `CollectorCapabilities` fields describe DOM/console/network/
+ * backend-log/trace/source-mapping/stack-capture observation — none of them
+ * is "process lifecycle observation," which is the one thing this collector
+ * actually does. There is no eighth field to report it as available in.
+ * Reported `unavailable` on all seven, each with its own honest reason,
+ * rather than inventing a field this package doesn't own (`contracts` is
+ * outside this lane's boundary this round — flagged to the peer rather than
+ * changed unilaterally). A collector that is doing its one real job while
+ * `capabilities()` shows nothing but `unavailable` is itself a disclosed
+ * gap in the capability model, not a bug in this file.
+ */
+function computeCapabilities() {
+    const reason = "ProcessCollector observes process lifecycle (started/ready/exited) only — the capability model has no field for that yet.";
+    const status = { availability: "unavailable", reason };
+    return {
+        domObservation: status,
+        consoleObservation: status,
+        networkObservation: status,
+        backendLogAccess: status,
+        distributedTrace: status,
+        sourceMapping: status,
+        stackCapture: status,
+        processLifecycle: { availability: "available", reason: null },
+        databaseObservation: status,
+        externalServiceObservation: status,
+    };
+}
+function eventTypeOf(kind) {
+    switch (kind) {
+        case "process-started":
+            return "PROCESS_STARTED";
+        case "process-ready":
+        case "process-ready-failed":
+            return "PROCESS_READY";
+        case "process-exited":
+            return "PROCESS_EXITED";
+    }
+}
+/**
+ * `process-ready-failed` still becomes a `PROCESS_READY`-typed Evidence
+ * item — the vocabulary has no separate "readiness failed" type, and
+ * inventing one here would be a runtime-event vocabulary change made
+ * unilaterally in a collector, the wrong layer for it. The failure is not
+ * lost: `payload.ready` is `false` and `payload.readiness` carries the full
+ * `ReadinessResult` (mechanism attempted, elapsed time, reason), so a
+ * reader distinguishes "became ready" from "readiness failed" from the
+ * payload, not the event type — the same shape `ServiceStartResult`
+ * already uses (`succeeded: boolean` alongside a `stage`), not a new one.
+ */
+function payloadOf(event) {
+    switch (event.kind) {
+        case "process-started":
+            return { processId: event.handle.processId, serviceName: event.serviceName, pid: event.handle.pid, command: event.handle.command, startedAt: event.handle.startedAt };
+        case "process-ready":
+        case "process-ready-failed":
+            return { processId: event.handle.processId, serviceName: event.serviceName, ready: event.readiness.ready, readiness: event.readiness };
+        case "process-exited":
+            // `phase` is what lets a reader tell "crashed on boot" from
+            // "finished/was stopped after running successfully" — see
+            // `ProcessLifecycleEvent`'s own doc comment in controller.ts.
+            return {
+                processId: event.handle.processId,
+                serviceName: event.serviceName,
+                exitCode: event.handle.exitCode,
+                signal: event.handle.signal,
+                exitedAt: event.handle.exitedAt,
+                phase: event.phase,
+            };
+    }
+}
+export function createProcessCollector() {
+    const capabilities = computeCapabilities();
+    let context = null;
+    return {
+        collectorId: "process-collector",
+        start(ctx) {
+            context = ctx;
+            return Promise.resolve({ available: true });
+        },
+        stop() {
+            // Idempotent per the Collector contract; nothing held to release —
+            // this collector owns no process, socket, or file handle of its own,
+            // only a reference to the context it emits through.
+            context = null;
+            return Promise.resolve();
+        },
+        capabilities() {
+            return capabilities;
+        },
+        handleLifecycleEvent(event) {
+            if (context === null) {
+                throw new Error(`ProcessCollector.handleLifecycleEvent("${event.kind}") called before start() — ` +
+                    `wire handleLifecycleEvent as RunOptions.onProcessLifecycleEvent only after start() has resolved, ` +
+                    `or this event (and everything downstream of it) is silently unobserved rather than loudly wrong.`);
+            }
+            context.emit({
+                timestamp: new Date().toISOString(),
+                source: event.kind === "process-exited" ? "process-exit" : "backend-process",
+                service: event.serviceName,
+                process: event.handle.processId,
+                eventType: eventTypeOf(event.kind),
+                payload: payloadOf(event),
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                // A direct observation of our own orchestration state (we spawned
+                // it, we polled its readiness, we reaped it) — never inferred or
+                // guessed, same basis LogCollector already uses for its own
+                // verbatim-capture confidence of 1.
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        },
+    };
+}
+//# sourceMappingURL=process-collector.js.map

package/dist/process-collector.js.map

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