@sema-agent/server 1.323.0 → 2.0.0

package/dist/bake-runner/runner.d.ts

@@ -1,3 +1,5 @@
+/** The claim image-api returns: the VETTED argv (operator free-text never reaches the runner) + the per-bake
+ *  ingest secret minted at claim (so a stale/rogue runner can't inject frames into another bake — §P2.4e). */
 export interface ClaimedBake {
     bakeId: string;
     argv: string[];
@@ -5,22 +7,34 @@ export interface ClaimedBake {
     dryRun: boolean;
     logs: boolean;
     ingestSecret: string;
+    /** Denormalized so the runner can pick the profile-aware deadline without a second fetch. */
     profile?: string | null;
     bands?: string[] | null;
 }
+/** The ingest/heartbeat response — image-api echoes whether a cancel was requested so the runner kills the group. */
 export interface IngestAck {
     accepted: boolean;
+    /** The durable cancel flag (§P2.11) — polled off EVERY ingest/heartbeat response (≤heartbeat-interval lag). */
     cancelRequested?: boolean;
+    /** False when the lease was lost/stolen (the runner aborts + kills the child — it no longer owns the build). */
     leaseValid?: boolean;
 }
+/** A spawned build.sh child — abstracted so a test can drive stdout/stderr/exit without a real process. The handle
+ *  exposes the process-GROUP id (negative pid) so a kill signals the WHOLE group (the setsid-detached tree). */
 export interface ChildHandle {
+    /** Negated pgid for `process.kill(-pgid, sig)` — the group kill that actually stops a detached build (§P2.11). */
     readonly pgid: number;
+    /** Resolves with the child's exit code (or 124-style on a signal) once it exits. */
     readonly exited: Promise<{
         code: number | null;
         signal: string | null;
     }>;
+    /** Send a signal to the process GROUP (SIGTERM then SIGKILL on the cancel/deadline path). */
     killGroup(signal: NodeJS.Signals): void;
 }
+/** Spawn `build.sh <argv> --json` detached in its own process group; stdout/stderr are delivered LINE-BY-LINE via
+ *  the callbacks (the impl splits on newlines). The runner feeds ONLY stdout lines through the JSON parser; stderr
+ *  is the failure tail (§P2.5) — buffered, surfaced on a non-zero exit, never JSON.parsed. */
 export interface ChildSpawner {
     spawn(opts: {
         argv: string[];
@@ -29,15 +43,27 @@ export interface ChildSpawner {
         onStderrLine(line: string): void;
     }): ChildHandle;
 }
+/** The image-api HTTP client (claim/ingest) — injected so a test drives the control plane without a server. */
 export interface ImageApiClient {
+    /** Long-poll for + claim the next queued bake; null when none is claimable right now. */
     claimNext(): Promise<ClaimedBake | null>;
+    /** POST one frame to `…/ingest` (carries the per-bake ingest secret header); returns the ack (cancel/lease). */
     ingest(bakeId: string, ingestSecret: string, frame: Record<string, unknown>): Promise<IngestAck>;
+    /** Heartbeat the lease forward (also surfaces cancel/lease state) — distinct from a frame ingest. */
     heartbeat(bakeId: string, ingestSecret: string): Promise<IngestAck>;
 }
+/** Host-side ops the runner needs that are NOT image-api calls (fs + a thin docker-push wrapper for the big-blob
+ *  retry — NOT a build.sh --replay). All injected so the orchestration is testable off build-host. */
 export interface HostOps {
+    /** Read the manifest BODY off the build-host FS (build.sh's done carries only a path — a cat/read is mandatory, §P2.10). */
     readManifest(path: string): Promise<unknown>;
+    /** `df -P -BG /data` output for the pre-flight disk guard (§P2.7); the runner parses free GiB out of it. */
     dfData(): Promise<string>;
+    /** Checkout the recipe at RECIPE_REF so build.sh's git rev-parse gitsha is REAL (§P2.12); returns the cwd. */
     checkoutRecipe(ref: string): Promise<string>;
+    /** The thin `docker push` big-blob retry wrapper (§P2.12) — retries a flaky registry layer push (born on SWR —
+     *  deprecated; pool now docker.io/claybobby) WITHOUT re-running the
+     *  whole build (build.sh has no push-only re-entry; --replay would re-bake + hit the dup-check). Best-effort. */
     dockerPushRetry?(tag: string, attempts: number): Promise<{
         ok: boolean;
         digest: string | null;
@@ -58,10 +84,17 @@ export interface BakeRunnerOpts {
     host: HostOps;
     clock: Clock;
     log: BakeRunnerLogger;
+    /** The git ref build.sh's recipe checkout is pinned to (RECIPE_REF) — replay-sufficient gitsha (§P2.12). */
     recipeRef: string;
+    /** The absolute path to build.sh inside the recipe checkout (e.g. e2b-template/dev-sandbox/build.sh). */
     buildShPath: string;
+    /** Lease heartbeat cadence (default 30s) — must stay well under image-api's BAKE_LEASE_MS (90s) so a healthy
+     *  build never has its lease reaped (§P2.7). The docker-build progress tick + cancel poll ride the same cadence. */
     heartbeatMs?: number;
+    /** Idle poll backoff when no bake is claimable (default 5s). */
     idlePollMs?: number;
+    /** Minimum free GiB on /data at claim; below this the bake fails fast (507-class) rather than dying mid-build and
+     *  leaving a half-layer (k3s + docker containerd both on /data — a fill triggers kubelet GC eviction — §P2.7). */
     minFreeGb?: number;
 }
 export declare class BakeRunner {
@@ -71,15 +104,36 @@ export declare class BakeRunner {
     private readonly minFreeGb;
     private stopped;
     constructor(opts: BakeRunnerOpts);
+    /** Cooperative shutdown — finishes the in-flight bake's current frame, then exits the claim loop. */
     stop(): void;
+    /** The long-poll loop: claim → run → release → poll next. Single-flight is enforced DB-side (the claim CAS), so a
+     *  second runner replica simply never wins a claim. Runs until `stop()`. */
     loop(): Promise<void>;
+    /** Run a single CLAIMED bake end-to-end. Owns the lineOrd counter, the heartbeat/cancel/deadline timers, the
+     *  child process group, the stdout→ingest pump, and the terminal done synthesis. */
     runOne(bake: ClaimedBake): Promise<void>;
+    /** Forward build.sh's own `done` line — but FIRST read the manifest BODY off disk and attach it so image-api can
+     *  auto-register (build.sh's done carries only a build-host path, NOT the body — §P2.10). A manifest read failure is
+     *  non-fatal: the done still forwards (the digest is on the line); image-api then registers indexId:null partial.
+     *
+     *  BIG-BLOB PUSH RETRY (§P2.12): build.sh dies exit 13 on a flaky `docker push`. The retry is a THIN `docker push`
+     *  wrapper on the host (NOT build.sh --replay — that re-bakes + hits the dup-check exit 10). On a push-fail done
+     *  for a `--push` bake with a known tag, the runner retries the push; on success it rewrites the done to COMPLETE
+     *  with the recovered post-push digest (no manifest on disk — build.sh dies before the manifest write — so image-
+     *  api registers the built-and-pushed-but-unregistered partial, which the P3 reconciliation tick finalizes). */
     private forwardDone;
+    /** Kill the process GROUP: SIGTERM, then SIGKILL shortly after (a SIGKILL mid-docker-build can leave dangling
+     *  layers; the dup-check + lockhash prevent a poisoned re-bake, and a startup workdir sweep reclaims them — §P2.11). */
     private killGroup;
     private stopSupervisor;
+    /** Pre-flight free-GiB read; null (fail-open) on a df parse/exec miss — a df hiccup must not block a bake (the
+     *  reaper + a mid-build fill guard still protect the host). */
     private freeGbOrNull;
+    /** Ingest one frame, swallowing transient errors (the buffered-retry of unsent lines is the real-runner's job;
+     *  image-api's uq_line makes a re-send a no-op, so a dropped frame is recoverable, never a crash). */
     private safeIngest;
 }
+/** Allocate the next per-bake lineOrd (monotonic from 1) — the at-least-once ingest dedupe key (§P2.10). */
 export declare function nextOrd(ord: {
     n: number;
 }): number;

package/dist/bake-runner/runner.js

@@ -1,8 +1,28 @@
+/**
+ * bake-runner core (IMAGE-API-DESIGN.md §P2.0/§P2.12) — the privileged build-host daemon that actually runs `build.sh`.
+ *
+ * image-api (the unprivileged controller) holds ZERO build credentials; this runner is the ONE privileged,
+ * non-customer-facing tier (node-pinned build-host, replicas=1, docker.sock + ctr + /root/.docker mounted). It:
+ *   1. long-polls image-api for a queued bake and CLAIMS it (single-flight via the DB lease — image-api's job);
+ *   2. checks out the recipe at the deployed RECIPE_REF (so build.sh's git rev-parse is REAL — §P2.12);
+ *   3. spawns `build.sh <VETTED argv> --json` as a CHILD IN ITS OWN PROCESS GROUP (setsid/detached) so a cancel
+ *      can SIGTERM/SIGKILL the whole group — channel-close does NOT kill a build (§P2.11);
+ *   4. forwards each STDOUT line to `…/ingest` with an incrementing lineOrd (at-least-once dedupe — §P2.10);
+ *   5. heartbeats the lease (+ polls cancel_requested off the ingest/heartbeat response) every ~30s;
+ *   6. on cancel/deadline kills the process GROUP and synthesizes the terminal `done` (build.sh emits none — §P2.11);
+ *   7. on the `done` line reads the manifest BODY off disk and forwards it so image-api can auto-register (§P2.10).
+ *
+ * This file is the I/O-injected core: the HTTP client, the child spawner, the fs reader, the clock and the logger
+ * are all dependencies, so the orchestration is structurally testable here while `main.ts` wires the real ones (the
+ * runner can only be exercised live on build-host). The line→frame mapping itself lives PURE in ./protocol.ts.
+ */
 import { resolve as resolvePath } from "node:path";
 import { lineToFrame, dockerBuildTickFrame, synthDoneFrame, exitDoneFrame, deadlineMsForProfile, parseDfFreeGb, parseBuildShLine, manifestPathFromLine, } from "./protocol.js";
 const DEFAULT_HEARTBEAT_MS = 30_000;
 const DEFAULT_IDLE_POLL_MS = 5_000;
 const DEFAULT_MIN_FREE_GB = 20;
+/** A high, fixed lineOrd for the loop-level catch terminal (runOne owns the per-bake counter, so its current value
+ *  is out of scope here) — far above any realistic in-bake line count so it never collides on uq_line. */
 const TERMINAL_FALLBACK_ORD = 2_000_000_000;
 export class BakeRunner {
     o;
@@ -16,9 +36,12 @@ export class BakeRunner {
         this.idlePollMs = opts.idlePollMs ?? DEFAULT_IDLE_POLL_MS;
         this.minFreeGb = opts.minFreeGb ?? DEFAULT_MIN_FREE_GB;
     }
+    /** Cooperative shutdown — finishes the in-flight bake's current frame, then exits the claim loop. */
     stop() {
         this.stopped = true;
     }
+    /** The long-poll loop: claim → run → release → poll next. Single-flight is enforced DB-side (the claim CAS), so a
+     *  second runner replica simply never wins a claim. Runs until `stop()`. */
     async loop() {
         while (!this.stopped) {
             let claimed = null;
@@ -36,18 +59,28 @@ export class BakeRunner {
                 await this.runOne(claimed);
             }
             catch (err) {
+                // A bake that threw out of runOne (an unexpected host/API failure) — best-effort terminal so readers settle.
+                // The lineOrd here is unknown (runOne owns the counter), so use a NULL-equivalent high ordinal that won't
+                // collide with an in-flight frame's uq_line (image-api still ++seq's it; the reaper backstops a true miss).
                 this.o.log.error("bake_run_error", { bakeId: claimed.bakeId, err: String(err) });
                 await this.safeIngest(claimed, exitDoneFrame(TERMINAL_FALLBACK_ORD, 1, String(err)));
             }
         }
     }
+    /** Run a single CLAIMED bake end-to-end. Owns the lineOrd counter, the heartbeat/cancel/deadline timers, the
+     *  child process group, the stdout→ingest pump, and the terminal done synthesis. */
     async runOne(bake) {
-        const ord = { n: 0 };
+        const ord = { n: 0 }; // the monotonic lineOrd allocator (at-least-once dedupe key — §P2.10)
         this.o.log.info("bake_claimed", { bakeId: bake.bakeId, push: bake.push, dryRun: bake.dryRun, logs: bake.logs });
+        // M2: serialize the stdout→ingest pump. A burst chunk (bufferLines calls onStdoutLine per newline synchronously)
+        // + the progress tick were fired as un-awaited `void safeIngest`, so N POSTs raced concurrently — image-api's
+        // non-atomic seq alloc then lost a frame on a (bake_id,seq) PK collision. Chain each non-terminal ingest so they
+        // POST one-at-a-time in lineOrd order, and AWAIT the chain before runOne returns (alongside the done forward).
         let pump = Promise.resolve();
         const enqueueIngest = (frame) => {
             pump = pump.then(() => this.safeIngest(bake, frame));
         };
+        // ── Pre-flight disk guard (§P2.7): below the floor, fail FAST rather than dying mid-build with a half-layer.
         if (!bake.dryRun) {
             const freeGb = await this.freeGbOrNull();
             if (freeGb !== null && freeGb < this.minFreeGb) {
@@ -63,6 +96,7 @@ export class BakeRunner {
                 return;
             }
         }
+        // ── Recipe checkout at the pinned ref so build.sh's git rev-parse gitsha is REAL (§P2.12).
         let cwd;
         try {
             cwd = await this.o.host.checkoutRecipe(this.o.recipeRef);
@@ -71,16 +105,24 @@ export class BakeRunner {
             await this.safeIngest(bake, exitDoneFrame(nextOrd(ord), 1, `recipe checkout failed: ${String(err)}`));
             return;
         }
+        // ── Spawn build.sh in its OWN PROCESS GROUP (so a cancel/deadline kill signals the whole detached tree).
         const stderrTail = [];
         let lastManifestPath = null;
-        let lastImageTag = null;
+        let lastImageTag = null; // the built tag — the push-retry target (§P2.12 big-blob retry)
         let sawDone = false;
+        // build.sh's `done` triggers an ASYNC tail (read the manifest body / the push retry, then ingest) — the child
+        // can exit the instant after printing it. It is chained ONTO `pump` (below), so `await pump` before runOne
+        // returns also awaits this pending forward (the lease isn't released before the auto-register input lands).
+        // 🔴 Resolve buildShPath against the recipe CHECKOUT cwd, NOT via PATH: node/bun's spawn resolves a BARE or
+        // RELATIVE argv[0] through $PATH (a bare `build.sh` silently ENOENT→exit-127 footgun — cost an hour live), so
+        // path.resolve(cwd, buildShPath) pins it to the checkout. An absolute buildShPath is returned unchanged.
         const buildShAbs = resolvePath(cwd, this.o.buildShPath);
         const buildArgv = [buildShAbs, ...bake.argv, "--json"];
         const child = this.o.spawner.spawn({
             argv: buildArgv,
             cwd,
             onStdoutLine: (raw) => {
+                // Forward EVERY stdout line through the pure mapper; remember the manifest path for the auto-register read.
                 const ev = parseBuildShLine(raw);
                 if (ev && ev.event === "manifest" && typeof ev.path === "string") {
                     lastManifestPath = ev.path;
@@ -90,39 +132,47 @@ export class BakeRunner {
                 }
                 if (ev && ev.event === "done") {
                     sawDone = true;
+                    // The done line needs the manifest BODY attached before ingest (auto-register reads it off disk — §P2.10).
+                    // M2: chain it ON the serialized pump so the terminal `done` is forwarded STRICTLY AFTER every queued
+                    // non-terminal frame (the SSE log's last event), in lineOrd order — never racing ahead of them.
                     pump = pump.then(() => this.forwardDone(bake, ord, ev, lastManifestPath, lastImageTag));
                     return;
                 }
                 enqueueIngest(lineToFrame(raw, nextOrd(ord)));
             },
+            // stderr is the failure tail (`tail -40 build.log >&2`), NOT JSON — buffer it, surface on a non-zero exit.
             onStderrLine: (raw) => {
                 if (stderrTail.length < 80)
                     stderrTail.push(raw);
             },
         });
+        // ── The heartbeat / cancel-poll / docker-build-progress / deadline supervisor, racing the child exit.
         const deadlineMs = deadlineMsForProfile(bake.profile ?? "custom", bake.bands ?? null);
         const startedAt = this.o.clock.now();
         let killedFor = null;
-        let childExited = false;
+        let childExited = false; // set when the child resolves so the supervisor's next tick stops (no leaked heartbeats)
         const supervisor = (async () => {
+            // eslint-disable-next-line no-constant-condition
             while (true) {
                 await this.o.clock.sleep(this.heartbeatMs);
                 if (childExited || killedFor)
-                    return;
+                    return; // the child finished, or we already killed — stop heartbeating
                 const elapsed = this.o.clock.now() - startedAt;
+                // Deadline first (a hung build past its profile budget — kill the group, synthesize FAILED 124).
                 if (elapsed >= deadlineMs) {
                     killedFor = "timeout";
                     this.o.log.warn("bake_deadline_kill", { bakeId: bake.bakeId, elapsedMs: elapsed, deadlineMs });
                     this.killGroup(child);
                     return;
                 }
+                // Heartbeat the lease + read back the cancel flag (the durable cross-replica cancel — §P2.11).
                 let ack;
                 try {
                     ack = await this.o.api.heartbeat(bake.bakeId, bake.ingestSecret);
                 }
                 catch (err) {
                     this.o.log.warn("bake_heartbeat_error", { bakeId: bake.bakeId, err: String(err) });
-                    continue;
+                    continue; // a transient heartbeat miss is not fatal; the reaper backstops a truly-lost runner.
                 }
                 if (ack.cancelRequested) {
                     killedFor = "cancelled";
@@ -131,30 +181,50 @@ export class BakeRunner {
                     return;
                 }
                 if (ack.leaseValid === false) {
+                    // The lease was stolen (image-api reaped us as stale) — abort; we no longer own this build.
                     killedFor = "timeout";
                     this.o.log.warn("bake_lease_lost", { bakeId: bake.bakeId });
                     this.killGroup(child);
                     return;
                 }
+                // No cancel, no deadline: emit the docker-build progress tick so a resuming reader sees motion (logs off).
                 enqueueIngest(dockerBuildTickFrame(nextOrd(ord), Math.floor(elapsed / 1000)));
             }
         })();
         const exit = await child.exited;
         childExited = true;
         this.stopSupervisor(supervisor);
+        // M2: drain the serialized pump BEFORE synthesizing a terminal. The pump carries every non-terminal frame AND
+        // (when build.sh printed its own done) the chained `forwardDone` — so by here the real `done` has already been
+        // forwarded LAST in lineOrd order. Draining first guarantees the lease isn't released before the auto-register
+        // input (manifest body) is in image-api's hands.
         await pump.catch(() => undefined);
+        // ── Terminal done synthesis. build.sh has NO SIGTERM trap, so a killed child emits no done — we synthesize it.
         if (killedFor) {
             await this.safeIngest(bake, synthDoneFrame(nextOrd(ord), killedFor));
             return;
         }
         if (sawDone) {
+            // build.sh printed its own done — already forwarded (manifest-body read / push retry) via the drained pump.
             return;
         }
+        // The child exited WITHOUT a done line (a crash/SIGKILL before build.sh's die() trap) — backstop a FAILED done
+        // carrying the exit code + the stderr failure tail (image-api redacts it on store).
         const code = exit.code ?? (exit.signal ? 137 : 1);
         await this.safeIngest(bake, exitDoneFrame(nextOrd(ord), code, stderrTail.join("\n")));
     }
+    /** Forward build.sh's own `done` line — but FIRST read the manifest BODY off disk and attach it so image-api can
+     *  auto-register (build.sh's done carries only a build-host path, NOT the body — §P2.10). A manifest read failure is
+     *  non-fatal: the done still forwards (the digest is on the line); image-api then registers indexId:null partial.
+     *
+     *  BIG-BLOB PUSH RETRY (§P2.12): build.sh dies exit 13 on a flaky `docker push`. The retry is a THIN `docker push`
+     *  wrapper on the host (NOT build.sh --replay — that re-bakes + hits the dup-check exit 10). On a push-fail done
+     *  for a `--push` bake with a known tag, the runner retries the push; on success it rewrites the done to COMPLETE
+     *  with the recovered post-push digest (no manifest on disk — build.sh dies before the manifest write — so image-
+     *  api registers the built-and-pushed-but-unregistered partial, which the P3 reconciliation tick finalizes). */
     async forwardDone(bake, ord, doneLine, lastManifestPath, lastImageTag) {
         let line = doneLine;
+        // Push-fail (exit 13) recovery: retry the big-blob push out-of-band before declaring the bake failed.
         if (line.status === "FAILED" &&
             line.exitCode === 13 &&
             bake.push &&
@@ -164,6 +234,7 @@ export class BakeRunner {
             try {
                 const r = await this.o.host.dockerPushRetry(lastImageTag, 3);
                 if (r.ok) {
+                    // Recovered: rewrite the terminal to COMPLETE with the post-push RepoDigest (design §6 runtime ref).
                     line = { ...line, status: "COMPLETE", exitCode: 0, error: null, digest: r.digest ?? line.digest, pushed: true };
                     this.o.log.info("bake_push_recovered", { bakeId: bake.bakeId, tag: lastImageTag });
                 }
@@ -181,28 +252,36 @@ export class BakeRunner {
                 }
                 catch (err) {
                     this.o.log.warn("bake_manifest_read_failed", { bakeId: bake.bakeId, path, err: String(err) });
+                    // leave manifestBody unset → image-api registers the built-but-unregistered partial (digest, indexId:null).
                 }
             }
         }
         await this.safeIngest(bake, frame);
     }
+    /** Kill the process GROUP: SIGTERM, then SIGKILL shortly after (a SIGKILL mid-docker-build can leave dangling
+     *  layers; the dup-check + lockhash prevent a poisoned re-bake, and a startup workdir sweep reclaims them — §P2.11). */
     killGroup(child) {
         try {
             child.killGroup("SIGTERM");
         }
         catch {
+            /* the group may already be gone */
         }
         void this.o.clock.sleep(5_000).then(() => {
             try {
                 child.killGroup("SIGKILL");
             }
             catch {
+                /* already dead */
             }
         });
     }
     stopSupervisor(p) {
+        // The supervisor loop exits on its own once killedFor is set or the child exits; this just swallows its result.
         void p.catch(() => undefined);
     }
+    /** Pre-flight free-GiB read; null (fail-open) on a df parse/exec miss — a df hiccup must not block a bake (the
+     *  reaper + a mid-build fill guard still protect the host). */
     async freeGbOrNull() {
         try {
             return parseDfFreeGb(await this.o.host.dfData());
@@ -211,6 +290,8 @@ export class BakeRunner {
             return null;
         }
     }
+    /** Ingest one frame, swallowing transient errors (the buffered-retry of unsent lines is the real-runner's job;
+     *  image-api's uq_line makes a re-send a no-op, so a dropped frame is recoverable, never a crash). */
     async safeIngest(bake, frame) {
         try {
             return await this.o.api.ingest(bake.bakeId, bake.ingestSecret, frame);
@@ -221,6 +302,7 @@ export class BakeRunner {
         }
     }
 }
+/** Allocate the next per-bake lineOrd (monotonic from 1) — the at-least-once ingest dedupe key (§P2.10). */
 export function nextOrd(ord) {
     ord.n += 1;
     return ord.n;

package/dist/bench/l8/artifact.d.ts

@@ -1,38 +1,70 @@
+/**
+ * L8 G-c artifact — the signed deploy-authenticity evidence the design/93 §5.2 G-c aggregator requires
+ * (SPEC-RSI-L7-L8 §A.3). The artifact is canonical-JSON serialized and ed25519-signed so the GO aggregator can
+ * verify it was produced by a real L8 run and link it to a commit + adapter build + boundary.
+ *
+ * 🔴 SIGNING IS PROVENANCE, NOT AUTHENTICITY-OF-RESULT (SPEC §A.3 RISK-4): a valid signature only proves "this
+ * run, with this key, produced these probe VALUES"; it does NOT prove the probes hit a real boundary — that is
+ * the P0 fail-loud + the external collector's job. The aggregator MUST check `gC.satisfied` AND
+ * `boundary.isolationClassVerified` AND `p1Mode !== "adapter-RO-seam-absent"`, never just "signature valid".
+ *
+ * 🔴 ED25519, NOT HMAC: a shared HMAC secret is forgeable by anyone who holds it; ed25519 is asymmetric
+ * — the private key signs (control-plane held, env L8_SIGNER_KEY_B64), the PUBLIC key (shipped to the aggregator)
+ * only verifies. node:crypto's ed25519 is built-in (no new dep).
+ *
+ * 🔴 TIMESTAMPS ARE INJECTED, NOT `Date.now()` (deterministic-test requirement): `buildArtifact` takes
+ * `producedAt` from the caller (the live runner passes a real ISO string; the unit test passes a fixed one), so
+ * the canonical JSON is byte-stable in tests.
+ */
 import { type KeyObject } from "node:crypto";
 import { type L8SchemaVersion, type L8Escape } from "./escape.js";
 import type { Backend, P1Mode } from "./probes.js";
 export interface L8Boundary {
     provisioned: boolean;
+    /** What the adapter SELF-DECLARES (capabilities.isolation) — recorded but never load-bearing. */
     isolationClassClaimed: "out_of_process" | "in_process_probe_only";
+    /** What L8 PROVED (P0+P2) — the load-bearing field. */
     isolationClassVerified: boolean;
+    /** kata only; null+reason on e2b (RISK-7). */
     guestKernel: string | null;
     hostKernel: string | null;
     runtimeClass: string;
+    /** P1 sanity: escalation failed because CAP_SYS_ADMIN is gone, not because we silently had it. */
     capSysAdminAbsent: boolean;
 }
 export interface ProbeRecord {
     id: string;
     name: string;
+    /** The verdict for this probe. `null` ⇒ the probe is in an honest PENDING state (blocked on a cross-team dep). */
     passed: boolean | null;
+    /** Honest pending flag — set when the probe could not run for real (the blocker is in `pendingReason`). */
     pending: boolean;
     pendingReason?: string;
+    /** P1-specific honest mode (only on the immutable-mount probe). */
     p1Mode?: P1Mode;
+    /** Per-probe structured observation fields (kept open so each probe records what it asserts). */
     observations?: Record<string, unknown>;
+    /** The command(s) the probe issued (for audit; the live runner fills these). */
     commands?: string[];
+    /** The INDEPENDENT observer's result for this probe (e.g. collector nonce log / inode check). */
     independentObserver?: Record<string, unknown>;
 }
 export interface L8GcResult {
+    /** G-c = no escapes ∧ isolationClassVerified ∧ every probe passed (none pending/failed) ∧ p1Mode present. */
     satisfied: boolean;
     reason: string;
 }
 export interface L8Signature {
     alg: "ed25519";
     keyId: string;
+    /** base64 detached signature over the canonical JSON of the artifact MINUS the `signature` field. */
     sig: string;
 }
+/** The l8.v1 artifact. `signature` is absent until {@link signArtifact}. */
 export interface L8DeployContractArtifact {
     schemaVersion: L8SchemaVersion;
     kind: "deploy-contract-authenticity";
+    /** Injected ISO timestamp — NOT Date.now() (deterministic-test requirement). */
     producedAt: string;
     serviceCommit: string;
     coreVersion: string;
@@ -41,6 +73,7 @@ export interface L8DeployContractArtifact {
     probes: ProbeRecord[];
     escapes: L8Escape[];
     gC: L8GcResult;
+    /** Content hash linking the artifact body (everything except `signature`) — the thing the signature covers. */
     contentHash: string;
     signature?: L8Signature;
 }
@@ -51,12 +84,42 @@ export interface BuildArtifactMeta {
     backend: Backend;
     boundary: L8Boundary;
 }
+/**
+ * Canonical JSON: object keys sorted recursively, no insignificant whitespace, arrays preserve order. Stable
+ * across re-serialization so the signature/contentHash are deterministic. Rejects non-finite numbers (NaN/Inf
+ * would serialize as `null` and silently corrupt the canonical form).
+ */
 export declare function canonicalJson(value: unknown): string;
+/** sha256 of the canonical body — links the signature to the exact body bytes. */
 export declare function computeContentHash(a: L8DeployContractArtifact): string;
+/**
+ * Fold G-c (SPEC §A.3): satisfied iff
+ *   - no escapes, AND
+ *   - boundary.provisioned AND boundary.isolationClassVerified, AND
+ *   - every probe passed (NONE pending, NONE failed), AND
+ *   - the immutable-mount probe's p1Mode is NOT "adapter-RO-seam-absent".
+ * G-c is necessary-non-sufficient: any pending/failed probe ⇒ NO-GO. This is what keeps tier-ON NO-GO honest.
+ */
 export declare function foldGc(boundary: L8Boundary, probes: ProbeRecord[], escapes: L8Escape[]): L8GcResult;
+/** Build the artifact body + contentHash. Pure: timestamps injected, gC folded. No signature yet. */
 export declare function buildArtifact(meta: BuildArtifactMeta, probes: ProbeRecord[], escapes: L8Escape[]): L8DeployContractArtifact;
+/** Load an ed25519 private key from a base64 PKCS8 DER (the L8_SIGNER_KEY_B64 control-plane secret). */
 export declare function loadPrivateKeyB64(b64: string): KeyObject;
+/** Load an ed25519 public key from a base64 SPKI DER (the key shipped to the aggregator). */
 export declare function loadPublicKeyB64(b64: string): KeyObject;
+/**
+ * Sign the artifact: recompute the contentHash (defends against a body mutated after build), sign the canonical
+ * body with ed25519 (`sign(null, msg, key)` — ed25519 takes no separate digest algorithm), attach the detached
+ * base64 signature. Returns a NEW artifact (does not mutate the input).
+ */
 export declare function signArtifact(artifact: L8DeployContractArtifact, privateKey: KeyObject, keyId: string): L8DeployContractArtifact;
+/**
+ * Verify an artifact: recompute the contentHash over the body and check it matches the stored one (tamper of any
+ * body field flips the hash), then ed25519-verify the detached signature over the canonical body. Returns false
+ * (never throws) on a missing/garbage signature, a content-hash mismatch, or a bad signature.
+ *
+ * 🔴 A `true` here means INTEGRITY/PROVENANCE only — the caller MUST still gate on gC.satisfied AND
+ * boundary.isolationClassVerified AND p1Mode (see file header). Verification alone is NOT a GO.
+ */
 export declare function verifyArtifact(artifact: L8DeployContractArtifact, publicKey: KeyObject): boolean;
 //# sourceMappingURL=artifact.d.ts.map

package/dist/bench/l8/artifact.js

@@ -1,5 +1,29 @@
+/**
+ * L8 G-c artifact — the signed deploy-authenticity evidence the design/93 §5.2 G-c aggregator requires
+ * (SPEC-RSI-L7-L8 §A.3). The artifact is canonical-JSON serialized and ed25519-signed so the GO aggregator can
+ * verify it was produced by a real L8 run and link it to a commit + adapter build + boundary.
+ *
+ * 🔴 SIGNING IS PROVENANCE, NOT AUTHENTICITY-OF-RESULT (SPEC §A.3 RISK-4): a valid signature only proves "this
+ * run, with this key, produced these probe VALUES"; it does NOT prove the probes hit a real boundary — that is
+ * the P0 fail-loud + the external collector's job. The aggregator MUST check `gC.satisfied` AND
+ * `boundary.isolationClassVerified` AND `p1Mode !== "adapter-RO-seam-absent"`, never just "signature valid".
+ *
+ * 🔴 ED25519, NOT HMAC: a shared HMAC secret is forgeable by anyone who holds it; ed25519 is asymmetric
+ * — the private key signs (control-plane held, env L8_SIGNER_KEY_B64), the PUBLIC key (shipped to the aggregator)
+ * only verifies. node:crypto's ed25519 is built-in (no new dep).
+ *
+ * 🔴 TIMESTAMPS ARE INJECTED, NOT `Date.now()` (deterministic-test requirement): `buildArtifact` takes
+ * `producedAt` from the caller (the live runner passes a real ISO string; the unit test passes a fixed one), so
+ * the canonical JSON is byte-stable in tests.
+ */
 import { createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify } from "node:crypto";
 import { L8_SCHEMA_VERSION } from "./escape.js";
+// ───────────────────────────── canonical JSON ─────────────────────────────
+/**
+ * Canonical JSON: object keys sorted recursively, no insignificant whitespace, arrays preserve order. Stable
+ * across re-serialization so the signature/contentHash are deterministic. Rejects non-finite numbers (NaN/Inf
+ * would serialize as `null` and silently corrupt the canonical form).
+ */
 export function canonicalJson(value) {
     return serialize(value);
 }
@@ -21,7 +45,7 @@ function serialize(v) {
     if (t === "object") {
         const obj = v;
         const keys = Object.keys(obj)
-            .filter((k) => obj[k] !== undefined)
+            .filter((k) => obj[k] !== undefined) // omit undefined fields (matches JSON.stringify object semantics)
             .sort();
         return `{${keys.map((k) => `${JSON.stringify(k)}:${serialize(obj[k])}`).join(",")}}`;
     }
@@ -29,14 +53,26 @@ function serialize(v) {
         throw new Error("canonicalJson: bigint is not serializable");
     throw new Error(`canonicalJson: unsupported type ${t}`);
 }
+// ───────────────────────────── content hash ─────────────────────────────
 import { createHash } from "node:crypto";
+/** The body that the signature + contentHash cover = the artifact WITHOUT `signature` and WITHOUT `contentHash`. */
 function signableBody(a) {
     const { signature: _sig, contentHash: _ch, ...rest } = a;
     return rest;
 }
+/** sha256 of the canonical body — links the signature to the exact body bytes. */
 export function computeContentHash(a) {
     return createHash("sha256").update(canonicalJson(signableBody(a)), "utf8").digest("hex");
 }
+// ───────────────────────────── gC fold (pure) ─────────────────────────────
+/**
+ * Fold G-c (SPEC §A.3): satisfied iff
+ *   - no escapes, AND
+ *   - boundary.provisioned AND boundary.isolationClassVerified, AND
+ *   - every probe passed (NONE pending, NONE failed), AND
+ *   - the immutable-mount probe's p1Mode is NOT "adapter-RO-seam-absent".
+ * G-c is necessary-non-sufficient: any pending/failed probe ⇒ NO-GO. This is what keeps tier-ON NO-GO honest.
+ */
 export function foldGc(boundary, probes, escapes) {
     const reasons = [];
     if (escapes.length > 0)
@@ -45,6 +81,9 @@ export function foldGc(boundary, probes, escapes) {
         reasons.push("boundary not provisioned");
     if (!boundary.isolationClassVerified)
         reasons.push("isolationClass not verified (P0/P2 — possible runc downgrade)");
+    // 🔴 (review HIGH) require the FULL canonical probe set PRESENT before satisfied can be true — else an empty or
+    // partial probe array silently satisfies G-c (a GO with NO evidence; foldGc(boundary,[],[]) used to return
+    // satisfied:true). Each required id must appear exactly once. Mirrors PROBE_MATRIX ids (P0..P4).
     const REQUIRED_PROBE_IDS = ["P0", "P1", "P2", "P3", "P4"];
     const idCounts = new Map();
     for (const p of probes)
@@ -61,6 +100,8 @@ export function foldGc(boundary, probes, escapes) {
     const failedProbes = probes.filter((p) => !p.pending && p.passed !== true);
     if (failedProbes.length > 0)
         reasons.push(`failed/unproven probe(s): ${failedProbes.map((p) => p.id).join(", ")}`);
+    // wq64gmm5e: key on the constrained `id` (every other gate above keys on id) — a free-form `name` drift must
+    // never fail this seam-absent guard OPEN into a fake-green GO.
     const p1 = probes.find((p) => p.id === "P1");
     if (p1 && p1.p1Mode === "adapter-RO-seam-absent") {
         reasons.push("P1 ran in adapter-RO-seam-absent mode (necessary-non-sufficient for the grader contract)");
@@ -73,6 +114,8 @@ export function foldGc(boundary, probes, escapes) {
             : `G-c NOT satisfied: ${reasons.join(" | ")}`,
     };
 }
+// ───────────────────────────── build (pure) ─────────────────────────────
+/** Build the artifact body + contentHash. Pure: timestamps injected, gC folded. No signature yet. */
 export function buildArtifact(meta, probes, escapes) {
     const gC = foldGc(meta.boundary, probes, escapes);
     const draft = {
@@ -86,17 +129,25 @@ export function buildArtifact(meta, probes, escapes) {
         probes,
         escapes,
         gC,
-        contentHash: "",
+        contentHash: "", // filled below
     };
     draft.contentHash = computeContentHash(draft);
     return draft;
 }
+// ───────────────────────────── ed25519 sign / verify ─────────────────────────────
+/** Load an ed25519 private key from a base64 PKCS8 DER (the L8_SIGNER_KEY_B64 control-plane secret). */
 export function loadPrivateKeyB64(b64) {
     return createPrivateKey({ key: Buffer.from(b64, "base64"), format: "der", type: "pkcs8" });
 }
+/** Load an ed25519 public key from a base64 SPKI DER (the key shipped to the aggregator). */
 export function loadPublicKeyB64(b64) {
     return createPublicKey({ key: Buffer.from(b64, "base64"), format: "der", type: "spki" });
 }
+/**
+ * Sign the artifact: recompute the contentHash (defends against a body mutated after build), sign the canonical
+ * body with ed25519 (`sign(null, msg, key)` — ed25519 takes no separate digest algorithm), attach the detached
+ * base64 signature. Returns a NEW artifact (does not mutate the input).
+ */
 export function signArtifact(artifact, privateKey, keyId) {
     const withHash = { ...artifact, signature: undefined, contentHash: "" };
     withHash.contentHash = computeContentHash(withHash);
@@ -104,6 +155,14 @@ export function signArtifact(artifact, privateKey, keyId) {
     const sig = cryptoSign(null, msg, privateKey);
     return { ...withHash, signature: { alg: "ed25519", keyId, sig: sig.toString("base64") } };
 }
+/**
+ * Verify an artifact: recompute the contentHash over the body and check it matches the stored one (tamper of any
+ * body field flips the hash), then ed25519-verify the detached signature over the canonical body. Returns false
+ * (never throws) on a missing/garbage signature, a content-hash mismatch, or a bad signature.
+ *
+ * 🔴 A `true` here means INTEGRITY/PROVENANCE only — the caller MUST still gate on gC.satisfied AND
+ * boundary.isolationClassVerified AND p1Mode (see file header). Verification alone is NOT a GO.
+ */
 export function verifyArtifact(artifact, publicKey) {
     const sig = artifact.signature;
     if (!sig || sig.alg !== "ed25519" || typeof sig.sig !== "string")