@descryy/runtime-orchestrator 0.2.1 → 0.4.0

package/dist/instrumented-execution.js

@@ -1,30 +1,14 @@
 /**
- * **The assembly nothing else performed.**
+ * The assembly wiring the runtime's pieces together in production code (previously
+ * only connected ad hoc by tests). Runs an `ExecutionController` over a `services`
+ * configuration; wraps each spawned process in a live `ProcessOutputSource`
+ * (polls the buffer, yields each line once); builds a `CollectorContext` with a
+ * real `resolveSourceRoot` closed over the execution's own processes; starts,
+ * drains and stops the adapter's collectors; writes every emitted item through
+ * `EvidenceStore` so redaction runs (plan §28).
  *
- * Every piece of the runtime existed and none of them were wired together
- * in production code: the controller spawned services, `RuntimeAdapter`
- * could build collectors, `resolveServiceRootForOrigin` could map an origin
- * to a source root, and `EvidenceStore` could persist. Only tests ever
- * connected them, each in its own way, which meant the thing the product
- * actually does had no single implementation to be right or wrong.
- *
- * This module is that implementation. It:
- *
- * 1. runs an `ExecutionController` over a `services` configuration;
- * 2. wraps each spawned process in a **live** `ProcessOutputSource` that
- *    polls the accumulated buffer and yields each line exactly once;
- * 3. builds a `CollectorContext` carrying a real `resolveSourceRoot`,
- *    closed over the execution's own processes — the channel RT-033 added
- *    and RT-029 built the lookup for, which until now nothing populated;
- * 4. starts the adapter's collectors, drains them, stops them;
- * 5. writes every emitted item through `EvidenceStore`, so redaction runs
- *    rather than being assumed (plan §28).
- *
- * **What it deliberately does not do.** It does not decide whether a
- * finding exists, does not correlate to graph nodes, and does not drive a
- * browser. Those are separate stages with separate contracts, and folding
- * them in here would make the one place that assembles the runtime also the
- * place that judges it.
+ * Deliberately does not decide whether a finding exists, correlate to graph
+ * nodes, or drive a browser — separate stages, separate contracts.
  */
 import { delimiter } from "node:path";
 import { resolveServiceRootForOrigin } from "@descryy/runtime-contracts";
@@ -36,13 +20,9 @@ import { createPollingProcessOutputSource } from "./polling-output-source.js";
 import { COLLECTOR_VERSION } from "./collector-version.js";
 /**
  * Builds the origin → source-root lookup a collector reads through
- * `CollectorContext.resolveSourceRoot`.
- *
- * This is the piece that had been missing at both ends: RT-029 wrote the
- * lookup and nothing called it; RT-033 added the channel and nothing filled
- * it. It closes over the execution's *own* processes, which is what makes
- * the port→service join possible at all — under ephemeral ports the
- * configuration cannot know the port, so only the running process can say.
+ * `CollectorContext.resolveSourceRoot`. Closes over the execution's own
+ * processes, which is what makes the port→service join possible at all — under
+ * ephemeral ports only the running process knows its own port.
  */
 export function createSourceRootResolver(processes, configuration) {
     return (origin) => resolveServiceRootForOrigin(origin, { processes, configuration });
@@ -66,9 +46,8 @@ export function applyOutboundLaunch(execution, launch) {
         const prepend = new Set(launch.prependToExisting ?? []);
         const env = { ...service.env };
         for (const [key, value] of Object.entries(launch.env ?? {})) {
-            // A variable the target already relies on is extended, not replaced --
-            // `PYTHONPATH` is the live case, and replacing it stops the application
-            // finding its own modules, which is breaking it in order to watch it.
+            // extend, don't replace, a variable the target relies on (PYTHONPATH is the
+            // live case) -- replacing it breaks the app's own module resolution
             const existing = prepend.has(key) ? (service.env?.[key] ?? process.env[key] ?? "") : "";
             env[key] = existing === "" ? value : `${value}${delimiter}${existing}`;
         }
@@ -83,35 +62,19 @@ export function applyOutboundLaunch(execution, launch) {
     return { ...execution, configuration: { ...execution.configuration, services } };
 }
 export async function runInstrumentedExecution(input) {
-    // **The outbound half, which nothing assembled before this.** The mechanism
-    // -- an outbound call captured at its own call site, joined to the route it
-    // reached in another process -- existed and was proven, but only a test
-    // ever wired it: `runInstrumentedExecution` started
-    // `createBackendCollectors` and nothing else, so no production path
-    // observed an outbound call at all.
+    // outbound observation needs two things: a collector to read the marker lines,
+    // and a launch that installs client instrumentation before app code can capture
+    // an unpatched client. The launch is adapter-declared and language-specific; an
+    // adapter that declares nothing gets neither.
     //
-    // It takes two things, not one. A collector to read the marker lines, and a
-    // *launch* that puts the client instrumentation inside the target process
-    // before any application code can capture an unpatched client. The second
-    // is language-specific, so it is declared on the adapter and merely applied
-    // here. An adapter that declares nothing gets neither -- the run proceeds,
-    // no outbound collector is started, and nothing claims one was.
-    // The budget clock starts here, not at `controller.run()`. The controller
-    // arms its own timer for the same number a few statements later, so this
-    // deadline is the marginally earlier — and therefore the conservative — of
-    // the two; a caller who declared a bound never waits past it because this
-    // function took some of it before the controller was even created.
+    // budget clock starts here, not at controller.run() -- marginally earlier than
+    // the controller's own timer, so a caller never waits past its declared bound
     const budgetStartedAt = Date.now();
     const outboundLaunch = input.adapter.outboundHttpLaunch?.() ?? null;
     const launchedExecution = outboundLaunch === null ? input.execution : applyOutboundLaunch(input.execution, outboundLaunch);
     const configuration = launchedExecution.configuration;
-    /**
-     * Every exit from this function reports the same struct, built from the one
-     * clock. Written as a closure rather than repeated at each `return` because
-     * there are four of them and the failure mode of the alternative — one
-     * return that quietly reports a different number — is exactly the class of
-     * bug this whole field exists to make visible.
-     */
+    // closure, not repeated per-return: there are four returns, and one quietly
+    // reporting a different number is the bug this field exists to catch
     const budgetOutcome = (observedForMs) => {
         const elapsedMs = Date.now() - budgetStartedAt;
         return {
@@ -123,20 +86,30 @@ export async function runInstrumentedExecution(input) {
         };
     };
     const controller = ExecutionController.create(launchedExecution);
-    // Closes §34's remaining "runtime self-observability" gap after RT-219:
-    // `controller.run()` has exactly one throw path (`controller.ts`'s own
-    // `spawnProcess` catch/rethrow, after it has already recorded the
-    // failure in `serviceStartResults` and transitioned to `FAILED_START`) --
-    // left unguarded here, that throw used to reject this whole function,
-    // uncaught, the identical "harness machinery breaks, zero evidence
-    // trail" shape RT-219 already fixed one layer up for `collector.start()`.
-    // Caught the same way: written through the same `EvidenceStore`, tagged
-    // `source: "harness"`. `controller.execution` and
-    // `controller.serviceStartResults` are both real at this point (`run()`
-    // mutates its private state, including a call to its own `#finish()`,
-    // before it ever throws) so the run resolves with what actually happened
-    // rather than rejecting the caller's own promise -- the same "resolves
-    // normally" contract RT-219 already established.
+    // B7: the execution row, minted here and nowhere else in production.
+    // `EvidenceStore.recordExecution` was complete and tested since the
+    // `executions` table was added -- schema, redaction, environment capture,
+    // upsert -- but this repo's and descry-core's own sources together held
+    // exactly two callers of it outside its own tests, both in
+    // evidence-store's test suite. Every evidence row this run is about to
+    // write carries `controller.execution.executionId`, so the parent row
+    // must exist before the first of them does; `controller.execution` is
+    // real the moment `create()` returns (it mints the id synchronously),
+    // which is before `controller.run()` -- and therefore before this
+    // function's own first `store.write()`, in the catch block just below.
+    input.store.recordExecution({
+        executionId: controller.execution.executionId,
+        application: controller.execution.application,
+        repository: controller.execution.repository,
+        commit: controller.execution.commit,
+        configuration: controller.execution.configuration,
+    });
+    // RT-219: controller.run()'s one throw path (spawnProcess catch/rethrow, after
+    // recording the failure in serviceStartResults) used to reject this whole
+    // function uncaught -- zero evidence trail. Caught here and written through
+    // EvidenceStore tagged "harness", same "resolves normally" contract RT-219
+    // established for collector.start(). controller.execution/serviceStartResults
+    // are both already real at this point (run() mutates state before it throws).
     let execution;
     try {
         execution = await controller.run(input.runOptions);
@@ -180,34 +153,23 @@ export async function runInstrumentedExecution(input) {
             budget: budgetOutcome(0),
         };
     }
-    // One source per spawned service. `serviceName` is what joins a handle
-    // back to its configuration entry, and a handle without one cannot be
-    // attributed -- skipped rather than guessed at.
-    // Declared before the sources close over it: each generator polls until
-    // this flips, and the flip is what lets `stop()` finish rather than wait
-    // forever on a source still watching a live buffer.
+    // a handle with no serviceName can't be attributed to a config entry -- skipped
+    // declared before the sources close over it: the flip lets stop() finish rather
+    // than wait forever on a source still watching a live buffer
     let finished = false;
     const sources = [];
-    // A **second, independent** source per process, kept with the service name
-    // that produced it.
-    //
-    // Not the same source object as the backend collector's, and this is the
-    // whole subtlety: `createPollingProcessOutputSource` yields each line
-    // exactly once, so two collectors sharing one source do not both see the
-    // output -- they race for it, and the first consumer wins. Sharing it made
-    // the backend log collector eat every `DESCRY_EXTERNAL_REQUEST` line and
-    // the outbound collector report nothing, which reads exactly like a service
-    // that made no outbound calls.
+    // second, independent source per process -- NOT shared with the backend
+    // collector's: createPollingProcessOutputSource yields each line exactly once,
+    // so sharing means two collectors race for it. Measured: sharing made the
+    // backend log collector eat every DESCRY_EXTERNAL_REQUEST line and the outbound
+    // collector report nothing, reading as "no outbound calls".
     const namedSources = [];
     for (const handle of execution.processes) {
         if (handle.serviceName === null)
             continue;
         const serviceName = handle.serviceName;
-        // `serviceName` is stamped here, at construction, and this is the only
-        // place it can be. The handle knows which declared service this process is;
-        // by the time a collector's evidence reaches `correlateExecution` that
-        // association is gone — a row in a store and no handle in scope — which is
-        // what made the gap permanent rather than recoverable.
+        // stamped here, at construction -- by the time evidence reaches
+        // correlateExecution the handle is out of scope and this association is gone
         sources.push(createPollingProcessOutputSource({
             processId: handle.processId,
             serviceName,
@@ -225,14 +187,10 @@ export async function runInstrumentedExecution(input) {
         });
     }
     const backendCollectors = input.adapter.createBackendCollectors(sources);
-    // Started only when the launch above actually installed instrumentation.
-    // A collector reading a process that was never instrumented would report
-    // "no outbound calls" for a service making them, which is the one answer
-    // worse than declining to look.
-    //
-    // `createExternalRequestCollector` itself names no language; the only
-    // language-specific value it needs is the adapter's own stack parser, which
-    // is what turns a captured call site into a file and a line.
+    // only started when the launch above actually installed instrumentation --
+    // otherwise it would report "no outbound calls" for a service making them,
+    // worse than declining to look. createExternalRequestCollector names no
+    // language itself; the adapter's stack parser is the only language-specific bit.
     const outboundCollectors = outboundLaunch === null
         ? []
         : namedSources.map(({ source, serviceName }) => createExternalRequestCollector({
@@ -241,26 +199,14 @@ export async function runInstrumentedExecution(input) {
             stackTraceParser: input.adapter.stackTraceParser,
         }));
     const emitted = [];
-    // `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency`/
-    // `environment` mechanisms -- the producer side of the same shape RT-219
-    // established for `automation` above: a structural fact the runtime
-    // establishes about its own execution environment, tagged
-    // `source: "dependency-check"` / `"environment-check"` rather than the
-    // service's own domain source, so a reader can tell "the project's
-    // declared versions don't match what actually ran" from an observation of
-    // the application itself without inspecting payload text. Run once per
-    // spawned service (each has its own `cwd`, and therefore potentially its
-    // own lockfile/`engines.node`), unconditionally -- "cheap, always
-    // available, no rerun needed" per the ruling -- but only ever emitted as
-    // evidence when an actual mismatch is found, the same "silence must not
-    // manufacture evidence" discipline `"harness"` already observes.
+    // dependency/environment version-mismatch checks (DEC-NEXT-fault-layer-empirical-
+    // confirmation.md): tagged "dependency-check"/"environment-check" rather than the
+    // service's own source, so a reader can tell version drift from an app
+    // observation. Run once per service (own cwd/lockfile/engines.node),
+    // unconditionally, but only emitted as evidence on an actual mismatch.
     //
-    // The observed Node version is `execution.environmentMetadata`'s own
-    // `nodeVersion` -- `process.version` of the controller process, captured
-    // once by `captureEnvironmentMetadata` during `controller.run()` above,
-    // never re-probed here. It is non-null whenever `validationError` is
-    // null (the early return above already excluded the one case where it
-    // would not be).
+    // observedNodeVersion is process.version captured once during controller.run();
+    // never re-probed here.
     const observedNodeVersion = execution.environmentMetadata?.nodeVersion ?? process.version;
     for (const handle of execution.processes) {
         if (handle.serviceName === null)
@@ -319,12 +265,9 @@ export async function runInstrumentedExecution(input) {
             }));
         }
     }
-    // Opt-in InboundProxy wiring (RT-192, DEC-271) -- see `frontWithInboundProxy`'s
-    // own doc for what this does and, just as important, what it does not
-    // close. Built AFTER `controller.run()` has already returned, so every
-    // service's own readiness answer already exists in
-    // `controller.serviceStartResults` -- this loop reads that answer, it
-    // never re-derives or re-checks it itself.
+    // opt-in InboundProxy wiring (RT-192, DEC-271), see frontWithInboundProxy's doc.
+    // Built after controller.run() returns, so readiness already exists in
+    // serviceStartResults -- this loop reads that answer, never re-derives it.
     const proxies = [];
     if (input.frontWithInboundProxy !== undefined) {
         for (const handle of execution.processes) {
@@ -335,11 +278,8 @@ export async function runInstrumentedExecution(input) {
                 continue;
             const readinessOutcome = controller.serviceStartResults.find((result) => result.serviceName === serviceName && result.stage === "readiness");
             if (readinessOutcome?.succeeded !== true || handle.port === null) {
-                // Requested but never proven live -- reported as a real
-                // COLLECTOR_ERROR, the same shape every other unavailable collector
-                // in this function gets, rather than a silent no-proxy fallback
-                // ("we did not observe this" vs "there was nothing to observe",
-                // plan §17, applies here too).
+                // requested but never proven live -- reported as COLLECTOR_ERROR, not a
+                // silent no-proxy fallback (plan §17: "not observed" vs "nothing there")
                 emitted.push(input.store.write({
                     executionId: execution.executionId,
                     timestamp: new Date().toISOString(),
@@ -377,28 +317,19 @@ export async function runInstrumentedExecution(input) {
     const context = {
         executionId: execution.executionId,
         configuration,
-        // Redaction runs here, on the way in -- EvidenceStore.write() is the
-        // only path that sets redactionStatus, so nothing reaches the returned
-        // array without having been through it (plan §28).
+        // redaction runs here, on the way in -- EvidenceStore.write() is the only
+        // path that sets redactionStatus (plan §28)
         emit: (evidenceInput) => {
             emitted.push(input.store.write({ ...evidenceInput, executionId: execution.executionId }));
         },
         resolveSourceRoot: createSourceRootResolver(execution.processes, configuration),
     };
-    // RT-219 (runtime self-observability). `collector.start()`'s documented
-    // failure path resolves `{available: false, reason}` -- the loop below
-    // already reports that one, tagged with the domain source the collector
-    // was going to observe. A collector that instead THROWS out of start()
-    // is a different claim: not "I looked and could not," but the harness's
-    // own machinery breaking before it ever got that far. Left unguarded,
-    // that throw rejects this Promise.all and `runInstrumentedExecution`
-    // aborts uncaught -- zero evidence trail for why, the exact "collector
-    // failure mistaken for absence of failure" shape plan §17 forbids,
-    // applied to the harness's own code instead of the application's.
-    // Caught here and written through the same EvidenceStore, tagged
-    // `source: "harness"` rather than the collector's domain source, so a
-    // reader can tell "our own observer broke" from "the observed system
-    // did" without inspecting payload text.
+    // RT-219: collector.start()'s documented failure path resolves {available:
+    // false, reason}, handled below. A collector that instead THROWS out of
+    // start() is a different claim -- the harness's own machinery breaking, not
+    // "I looked and could not" -- so it's caught here and tagged "harness" rather
+    // than the collector's domain source, instead of aborting this Promise.all
+    // uncaught with zero evidence trail.
     const startOutcomes = await Promise.all(collectors.map(async (collector) => {
         try {
             return { collector, result: await collector.start(context), threw: false };
@@ -429,14 +360,10 @@ export async function runInstrumentedExecution(input) {
             return { collector, result: { available: false, reason: `start() threw: ${detail}` }, threw: true };
         }
     }));
-    // A thrown start() was already reported above, under `source: "harness"`
-    // -- excluded here so it is not reported a second time under
-    // `source: "backend-process"` by the loop below, which would collide
-    // the two tags on what is really one failure.
+    // a thrown start() was already reported above under "harness" -- excluded here
+    // to avoid double-reporting the same failure under "backend-process"
     const unavailable = startOutcomes.filter((entry) => !entry.threw && !entry.result.available);
-    // A collector that could not start is reported, never silently absent:
-    // "we did not observe this" and "there was nothing to observe" are
-    // different claims (plan §17).
+    // reported, never silently absent (plan §17: "not observed" vs "nothing there")
     for (const entry of unavailable) {
         emitted.push(input.store.write({
             executionId: execution.executionId,
@@ -459,78 +386,44 @@ export async function runInstrumentedExecution(input) {
             collectorVersion: COLLECTOR_VERSION,
         }));
     }
-    // Every fronted proxy that actually started (a collector reported
-    // `available: false` above never reaches here -- its port stayed null on
-    // that codepath, matching `InboundProxy.port()`'s own contract).
+    // proxies with available:false above never reach here -- port stayed null
     const proxyPorts = {};
     for (const entry of proxies) {
         const port = entry.proxy.port();
         if (port !== null)
             proxyPorts[entry.serviceName] = port;
     }
-    // **Everything from here to the teardown is wrapped, because a throw above
-    // the teardown used to leak the whole execution.**
-    //
-    // `onReady` is caller code and is documented not to be caught — correctly,
-    // since turning a caller's failed setup into a clean run would be the
-    // silent-degradation failure this repo rules against. But "not caught" and
-    // "not cleaned up" are two different promises and only the first was ever
-    // made: when `onReady` threw, `finished = true`, the collector `stop()` loop
-    // and `controller.stop()` were all skipped, so the polling output sources
-    // kept polling a live buffer, the spawned child was never killed, and the
-    // controller's timer held the event loop open. Measured: the call rejects in
-    // 270ms with the caller's own error, and the process then never exits.
-    //
-    // The exception still propagates, uncaught by any handler that changes it,
-    // to the same caller with the same stack — the documented contract is
-    // untouched. Only the leak goes away.
+    // Wrapped because a throw above teardown used to leak the whole execution.
+    // onReady is caller code, documented not to be caught -- but "not caught" and
+    // "not cleaned up" are different promises: when onReady threw, finished stayed
+    // false, so collector.stop()/controller.stop() were skipped, sources kept
+    // polling, the spawned child was never killed, and the timer held the event
+    // loop open. Measured: rejects in 270ms, process then never exits. Exception
+    // still propagates unchanged to the caller; only the leak goes away.
     //
-    // Found the expensive way: a worktree missing the fixture app's
-    // `node_modules` made a test's `onReady` throw after a correctly bounded
-    // ten-second readiness wait, and the suite then hung for twenty minutes.
-    // `scripts/preflight.mjs` predicts that dependency gap and calls its worst
-    // case "a readiness timeout that looks like a slow boot" — milder than what
-    // actually happened, which is what makes this a defect rather than an
-    // inconvenience: a guard whose stated worst case is better than reality
-    // teaches people to trust it less than they should.
+    // Found the hard way: a worktree missing node_modules made a test's onReady
+    // throw after a correctly bounded readiness wait, then the suite hung for
+    // twenty minutes.
     let observationMs = 0;
     let bodyFailure = null;
     let teardownFailure = null;
     try {
         await input.onReady?.({ execution, proxyPorts });
-        // **The observation window is bounded by the declared budget, not just by
-        // `observeForMs`.** This line used to be an unconditional sleep for the
-        // full requested window, which made `timeoutMs` an upper bound on how long
-        // a service was allowed to live and no bound at all on how long the caller
-        // was made to wait. The two numbers then diverged silently, and in the
-        // worst direction: `ExecutionController`'s own timer had already killed
-        // every process at the deadline, so the remainder of the window watched
-        // dead processes and produced nothing. Measured — a 1500ms budget with a
-        // 12000ms window returned after 12288ms with zero evidence.
-        //
-        // Clamped rather than aborted. There is real work left after this point
-        // (draining collectors, reaping children) that owns OS resources and must
-        // still run; cancelling it to hit the number exactly would leak the
-        // processes the budget exists to bound. So the deadline decides how long we
-        // *watch*, and the overshoot from teardown is reported rather than hidden —
-        // `budget.exceeded` is what says the run finished past its own bound.
+        // observation window is bounded by the declared budget, not just observeForMs
+        // -- unconditionally sleeping the full window used to leave timeoutMs bounding
+        // only the service, not the wait; measured, a 1500ms budget with a 12000ms
+        // window returned after 12288ms with zero evidence (services dead the whole
+        // remainder). Clamped rather than aborted: teardown still owns OS resources
+        // and must run; the overshoot is reported via budget.exceeded, not hidden.
         const remainingMs = budgetStartedAt + configuration.timeoutMs - Date.now();
         observationMs = Math.max(0, Math.min(input.observeForMs, remainingMs));
         if (observationMs > 0) {
             await new Promise((resolve) => setTimeout(resolve, observationMs));
         }
-        // A window that was cut short is a degradation, and rule 7 says every
-        // fallback is labelled. `execution.state` already carries `TIMED_OUT` when
-        // the controller's own timer fired, but that says the *services* were
-        // stopped early — it does not say the observation was, and a run whose
-        // budget expired before the controller ever armed (or after it had already
-        // completed) leaves no trace in the state at all.
-        //
-        // Tagged `source: "harness"` with `COLLECTOR_ERROR`: this is the runtime
-        // observing itself rather than any watched domain, and the event type's own
-        // documented purpose is to keep "found nothing" apart from "stopped
-        // looking". A truncated window is precisely the second one, so it needs no
-        // new event type of its own.
+        // rule 7: cut-short window is a labelled degradation. execution.state's
+        // TIMED_OUT says the services stopped early, not that observation did --
+        // tagged "harness"/COLLECTOR_ERROR to keep "found nothing" apart from
+        // "stopped looking".
         if (observationMs < input.observeForMs) {
             emitted.push(input.store.write({
                 executionId: execution.executionId,
@@ -558,35 +451,22 @@ export async function runInstrumentedExecution(input) {
         }
     }
     catch (error) {
-        // Held, not handled. Rethrown below, unchanged, once the teardown in the
-        // `finally` has run.
+        // held, not handled -- rethrown below, unchanged, once teardown has run
         bodyFailure = { error };
     }
     finally {
-        // Order matters: the sources must be told the process is done before
-        // stop() awaits their drain, or stop() waits forever on a generator
-        // still polling a live buffer.
+        // order matters: sources must be told the process is done before stop()
+        // awaits their drain, or it waits forever on a generator polling a live buffer
         finished = true;
         try {
             await Promise.all(collectors.map((collector) => collector.stop()));
-            // **`timeout()` when this function cut the window short, `stop()` when it
-            // did not — and the distinction is not left to whichever timer fires
-            // first.**
-            //
-            // The clamp above ends the observation window at the deadline;
-            // `ExecutionController`'s own timer fires a moment later. Whichever of the
-            // two reached the controller first used to decide what the run *said* had
-            // happened, and teardown regularly won: measured `TIMED_OUT` at 1534ms and
-            // `COMPLETED` at 1515ms for the same case, with the second surfacing only
-            // under a loaded full-suite run.
-            //
-            // That is the one field `descry-core`'s `observe_runtime` reads to choose
-            // between `ok` and `timed_out`, so losing the race turned a disclosed
-            // degradation into a silent one — a run that returns on time and reports
-            // nothing was cut short. This function already knows: `observationMs <
-            // input.observeForMs` is exactly the condition it wrote the truncation
-            // evidence under. It says so directly rather than hoping to lose a race
-            // it set up itself.
+            // timeout() vs stop() is decided here, not left to whichever of this
+            // function's clamp or the controller's own timer fires first -- measured
+            // TIMED_OUT at 1534ms and COMPLETED at 1515ms for the same case under load.
+            // descry-core's observe_runtime reads this to choose ok vs timed_out, so
+            // losing that race silently hid a real truncation; this function already
+            // knows the answer (observationMs < input.observeForMs) and states it
+            // directly instead.
             if (observationMs < input.observeForMs) {
                 await controller.timeout();
             }
@@ -595,24 +475,16 @@ export async function runInstrumentedExecution(input) {
             }
         }
         catch (teardownError) {
-            // On the ordinary path a teardown failure is the only failure there is,
-            // so it propagates exactly as it always did — held here and rethrown
-            // below rather than thrown from inside the `finally`, which is the one
-            // place a throw really can discard an in-flight exception.
+            // held and rethrown below rather than thrown inside finally, which can
+            // discard an in-flight exception
             if (bodyFailure === null) {
                 teardownFailure = { error: teardownError };
             }
             else {
-                // When something already failed above, the caller's own error is the
-                // actionable one and a teardown failure must not replace it — a plain
-                // `finally` would silently substitute the second for the first, which
-                // is the same class of mistake as the leak this block exists to fix.
-                // So it is written to the evidence store instead of thrown, tagged
-                // `harness` (RT-219) because it is the runtime's own machinery
-                // breaking rather than anything about the observed application. It is
-                // not in the returned array — there is no return on this path — but
-                // the store is durable and is what `evidencePath` points at, so the
-                // record survives the throw.
+                // caller's error is the actionable one; a teardown failure must not
+                // silently replace it -- written to the evidence store instead (tagged
+                // "harness", RT-219) rather than thrown. Not in the returned array, but
+                // the store is durable so the record survives the throw.
                 input.store.write({
                     executionId: execution.executionId,
                     timestamp: new Date().toISOString(),
@@ -637,9 +509,7 @@ export async function runInstrumentedExecution(input) {
             }
         }
     }
-    // Rethrown untouched — the same error object, the same stack, to the same
-    // caller. The caller's own failure wins over a teardown failure when both
-    // happened, because it is the one they can act on.
+    // rethrown untouched, same object/stack; caller's failure wins over teardown's
     if (bodyFailure !== null)
         throw bodyFailure.error;
     if (teardownFailure !== null)