@legionworks/facet 1.9.0

package/src/validation/tier0/worker-input.ts

@@ -0,0 +1,75 @@
+import { ARTIFACT_TYPES, type ArtifactType } from "../../shared/contracts/artifact-types";
+import type { Renderer } from "../../shared/contracts/artifact";
+import type { LexicalCounters, TsxExecutionMode } from "../../shared/contracts/validation";
+
+export interface WorkerInput {
+  readonly schemaVersion: "facet.tier0.v2";
+  readonly requestId: string;
+  readonly revisionSha: string;
+  readonly artifactType: ArtifactType;
+  readonly renderer: Renderer;
+  readonly source: Uint8Array;
+  readonly lexical: LexicalCounters;
+  readonly execution?: TsxExecutionMode;
+}
+
+interface WorkerInputJson {
+  readonly schemaVersion?: unknown;
+  readonly requestId?: unknown;
+  readonly revisionSha?: unknown;
+  readonly artifactType?: unknown;
+  readonly renderer?: unknown;
+  readonly sourceBase64?: unknown;
+  readonly lexical?: unknown;
+  readonly execution?: unknown;
+}
+
+export function parseWorkerInput(text: string): WorkerInput {
+  const raw = JSON.parse(text) as WorkerInputJson;
+  if (raw.schemaVersion !== "facet.tier0.v2") {
+    throw new Error(`unknown schemaVersion: ${String(raw.schemaVersion)}`);
+  }
+  if (typeof raw.requestId !== "string" || raw.requestId.length === 0)
+    throw new Error("invalid requestId");
+  if (typeof raw.revisionSha !== "string" || !/^[a-f0-9]{64}$/.test(raw.revisionSha)) {
+    throw new Error("invalid revisionSha");
+  }
+  if (
+    typeof raw.artifactType !== "string" ||
+    !ARTIFACT_TYPES.includes(raw.artifactType as ArtifactType)
+  ) {
+    throw new Error(`invalid artifactType: ${String(raw.artifactType)}`);
+  }
+  if (raw.renderer !== "svg" && raw.renderer !== "canvas") {
+    throw new Error(`invalid renderer: ${String(raw.renderer)}`);
+  }
+  if (typeof raw.sourceBase64 !== "string") throw new Error("missing sourceBase64");
+  const lexical = raw.lexical as LexicalCounters | undefined;
+  if (
+    lexical === undefined ||
+    typeof lexical.rendererRootSvgCount !== "number" ||
+    (typeof lexical.mermaidNodeCount !== "number" && lexical.mermaidNodeCount !== null) ||
+    typeof lexical.visibleSvgCount !== "number"
+  ) {
+    throw new Error("invalid lexical counters");
+  }
+  const source = Uint8Array.from(Buffer.from(raw.sourceBase64, "base64"));
+  const execution =
+    raw.execution === "static" || raw.execution === "interactive" ? raw.execution : undefined;
+  if (raw.artifactType === "tsx" && execution !== "static" && execution !== "interactive") {
+    throw new Error("TSX input requires execution mode");
+  }
+  if (raw.artifactType !== "tsx" && raw.execution !== undefined) {
+    throw new Error("execution is only valid for TSX input");
+  }
+  return {
+    schemaVersion: "facet.tier0.v2",
+    requestId: raw.requestId,
+    revisionSha: raw.revisionSha,
+    artifactType: raw.artifactType as ArtifactType,
+    renderer: raw.renderer,
+    source,
+    lexical,
+    ...(execution === undefined ? {} : { execution }),
+  };
+}

package/src/validation/tier1/browser-process.ts

@@ -0,0 +1,147 @@
+/**
+ * Browser-process lifecycle for the Tier 1 verifier.
+ *
+ * The interface intentionally exposes only what the verifier needs
+ * (open a target, drive CDP, close) so a future raw-CDP impl can
+ * replace the puppeteer-core adapter without changing any caller.
+ *
+ * The ephemeral user-data-dir (mode 0700, removed in `finally`)
+ * makes the on-disk footprint zero between runs. The orphan
+ * cleanup helper registers the (pid, startTime) so a parent that
+ * crashes before the finally block can still reap the tmpdir.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { FacetError } from "../../shared/errors/facet-error";
+
+import { TIER1_USER_DATA_DIR_MODE } from "./limits";
+import { resolveLauncher, type ResolvedLauncher } from "./launcher";
+
+const TIER1_TRACE = process.env.FACET_TIER1_TRACE === "1";
+
+/**
+ * Minimal CDP session surface the verifier uses. Puppeteer-core's
+ * `CDPSession` satisfies this shape; a raw-CDP impl can too.
+ */
+export interface VerifierCdpSession {
+  send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  on(event: string, listener: (params: unknown) => void): void;
+  off(event: string, listener: (params: unknown) => void): void;
+  detach(): Promise<void>;
+}
+
+export interface VerifierTarget {
+  /** The browser-level CDP session (page-level for puppeteer-core). */
+  readonly session: VerifierCdpSession;
+  /**
+   * Frame-tree snapshot — every CDP `Page` call that depends on the
+   * frame tree reads from here so the verifier's "resolve child
+   * frame" step has a stable input.
+   */
+  getFrameTree(): Promise<unknown>;
+  /**
+   * Tear down the browser. The implementation MUST close the CDP
+   * session, signal the browser, reap the tmpdir, and remove any
+   * orphan-cleanup registration.
+   */
+  close(): Promise<void>;
+  /** Browser pid — the orphan cleanup key. */
+  readonly pid: number;
+  readonly startTime: number;
+}
+
+/**
+ * Build a fresh ephemeral user-data directory under `os.tmpdir()`. The
+ * returned path is mode 0700 (matches `TIER1_USER_DATA_DIR_MODE`); the
+ * caller MUST `rm -rf` it (via the verifier's `finally` block).
+ */
+export function createEphemeralProfileDir(): string {
+  const base = tmpdir();
+  const dir = mkdtempSync(join(base, "facet-tier1-"));
+  try {
+    chmodSync(dir, TIER1_USER_DATA_DIR_MODE);
+  } catch {
+    // best-effort; chmod may fail under restrictive umask
+  }
+  return dir;
+}
+
+/** Remove the ephemeral profile directory; best-effort. */
+export function removeEphemeralProfileDir(path: string): void {
+  const startedAt = performance.now();
+  if (TIER1_TRACE) process.stderr.write(`[tier1] browser-profile-remove:start path=${path}\n`);
+  try {
+    rmSync(path, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  } finally {
+    if (TIER1_TRACE) {
+      process.stderr.write(
+        `[tier1] browser-profile-remove:complete durationMs=${Math.round(performance.now() - startedAt)} path=${path}\n`,
+      );
+    }
+  }
+}
+
+export async function closeAndRemoveEphemeralProfile(
+  close: () => Promise<void>,
+  profileDir: string,
+  timeoutMs = 2_000,
+): Promise<void> {
+  try {
+    await Promise.race([close(), new Promise<void>((resolve) => setTimeout(resolve, timeoutMs))]);
+  } finally {
+    removeEphemeralProfileDir(profileDir);
+  }
+}
+
+/**
+ * Detect whether the launcher wrapper + pinned shell are reachable.
+ * Bounded by a 2s timeout so a hung unshare does not freeze the
+ * verifier; the verdict path runs this once per cold-start.
+ */
+export async function probeLauncherAvailability(
+  overrides: { readonly version?: string } = {},
+): Promise<{ available: boolean; reason: string | null }> {
+  let launcher: ResolvedLauncher;
+  try {
+    launcher = resolveLauncher(
+      overrides.version !== undefined ? { version: overrides.version } : {},
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { available: false, reason: message };
+  }
+  return new Promise((resolve) => {
+    const child: ChildProcess = spawn(launcher.executablePath, ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // already dead
+      }
+      resolve({ available: false, reason: "launcher probe timed out" });
+    }, 2_000);
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) {
+        resolve({ available: true, reason: null });
+        return;
+      }
+      resolve({ available: false, reason: `launcher exited with code ${code ?? "null"}` });
+    });
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      resolve({ available: false, reason: `launcher spawn failed: ${error.message}` });
+    });
+  });
+}
+
+void FacetError;

package/src/validation/tier1/cdp-pipe.ts

@@ -0,0 +1,281 @@
+/**
+ * Puppeteer-core adapter for the Tier 1 verifier.
+ *
+ * The verifier never imports puppeteer-core directly — it goes
+ * through `Tier1Browser` (declared in `browser-process.ts`) so a
+ * future raw-CDP impl can replace this module without changing the
+ * runner. This file is the ONLY place puppeteer-core appears.
+ *
+ * CDP transport: `--remote-debugging-pipe`. Puppeteer-core with
+ * `pipe: true` spawns the browser with the pipe inherited from
+ * the parent and exchanges a single JSON-encoded handshake on
+ * stdin/stdout to discover the page target. The verifier then
+ * opens a per-page CDPSession and uses it for the protocol probes.
+ *
+ * The pipe transport is REQUIRED inside the netns: loopback is
+ * DOWN so a TCP CDP port cannot accept connections. The
+ * `scripts/launch-netns.sh` wrapper execs unshare + the pinned
+ * shell, inheriting the pipe through the chain.
+ */
+
+import puppeteer, { type Browser, type CDPSession, type Page } from "puppeteer-core";
+
+import { buildBrowserArgs, resolveLauncher, type ResolvedLauncher } from "./launcher";
+import { TIER1_CDP_CALL_WATCHDOG_MS } from "./limits";
+import {
+  closeAndRemoveEphemeralProfile,
+  createEphemeralProfileDir,
+  removeEphemeralProfileDir,
+  type VerifierCdpSession,
+  type VerifierTarget,
+} from "./browser-process";
+import { readPidStartTimeTicks } from "../../shared/util/process";
+
+/**
+ * Typed signal for a dead CDP pipe transport: the browser process is
+ * alive but every protocol call pends forever (observed when a browser
+ * is spawned immediately after another browser's teardown — the new
+ * child's devtools pipe is torn down out from under it). The runner
+ * retries once with a fresh browser; anything else would hang the
+ * verification past every barrier deadline.
+ */
+export class Tier1TransportWedgeError extends Error {
+  constructor(where: string) {
+    super(`tier1: CDP transport wedged at ${where}`);
+    this.name = "Tier1TransportWedgeError";
+  }
+}
+
+const TIER1_TRACE = process.env.FACET_TIER1_TRACE === "1";
+
+function traceLaunch(stage: string, startedAt: number): void {
+  if (!TIER1_TRACE) return;
+  process.stderr.write(`[tier1] +${Date.now() - startedAt}ms browser:${stage}\n`);
+}
+
+class PuppeteerCdpSessionAdapter implements VerifierCdpSession {
+  constructor(private readonly inner: CDPSession) {}
+
+  async send<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    // Watchdog every call: a wedged pipe transport leaves the browser
+    // alive but every send pending forever — the run would hang past
+    // every barrier deadline because the deadline loops only advance
+    // when a send resolves. A typed rejection lets the runner retry
+    // with a fresh browser instead of hanging the verification.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race([
+        this.inner.send(method as never, params as never) as Promise<T>,
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(
+            () => reject(new Tier1TransportWedgeError(method)),
+            TIER1_CDP_CALL_WATCHDOG_MS,
+          );
+        }),
+      ]);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
+  on(event: string, listener: (params: unknown) => void): void {
+    this.inner.on(event as never, listener as never);
+  }
+
+  off(event: string, listener: (params: unknown) => void): void {
+    this.inner.off(event as never, listener as never);
+  }
+
+  async detach(): Promise<void> {
+    try {
+      await this.inner.detach();
+    } catch {
+      // session already torn down
+    }
+  }
+}
+
+class PuppeteerVerifierTarget implements VerifierTarget {
+  private readonly browser: Browser;
+  private readonly page: Page;
+  readonly session: VerifierCdpSession;
+  private readonly profileDir: string;
+  private closed = false;
+
+  constructor(browser: Browser, page: Page, session: CDPSession, profileDir: string) {
+    this.browser = browser;
+    this.page = page;
+    this.session = new PuppeteerCdpSessionAdapter(session);
+    this.profileDir = profileDir;
+  }
+
+  get pid(): number {
+    const proc = this.browser.process();
+    return proc?.pid ?? -1;
+  }
+
+  get startTime(): number {
+    // Read the OS-recorded monotonic start time (field 22 of
+    // /proc/<pid>/stat) so this record is byte-identical with the
+    // canonical lock-metadata start time in
+    // `service/lifecycle/process-lock.ts`. A future orphan-cleanup
+    // hook that cross-references the two with `isPidAlive` and
+    // start-time ticks will see the same value here as the lock
+    // metadata recorded at the parent's startup. Falls back to
+    // `Date.now()` only when the browser process is unreachable
+    // (e.g. closed before probe); the runner treats the
+    // (pid, startTime) pair as a best-effort identity key.
+    const proc = this.browser.process();
+    const pid = proc?.pid;
+    if (pid === undefined || !Number.isInteger(pid) || pid <= 0) return Date.now();
+    return readPidStartTimeTicks(pid) ?? Date.now();
+  }
+
+  async getFrameTree(): Promise<unknown> {
+    return this.session.send("Page.getFrameTree");
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    await closeAndRemoveEphemeralProfile(async () => {
+      await this.session.detach().catch(() => {});
+      await this.page.close().catch(() => {});
+      await this.browser.close().catch(() => {});
+    }, this.profileDir);
+  }
+}
+
+export interface PuppeteerTier1BrowserOptions {
+  readonly launcher?: ResolvedLauncher;
+  readonly logger?: (message: string) => void;
+}
+
+/**
+ * Production Tier1Browser impl backed by puppeteer-core. Constructs
+ * a fresh ephemeral profile under `os.tmpdir()` per launch, opens
+ * the launcher's executable as the netns wrapper, and returns a
+ * `VerifierTarget` the runner can drive.
+ */
+export class PuppeteerTier1Browser {
+  constructor(private readonly options: PuppeteerTier1BrowserOptions = {}) {}
+
+  async launch(): Promise<VerifierTarget> {
+    const startedAt = Date.now();
+    const launcher = this.options.launcher ?? resolveLauncher();
+    traceLaunch("launcher-resolved", startedAt);
+    const profileDir = createEphemeralProfileDir();
+    traceLaunch("profile-created", startedAt);
+    let browser: Browser | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let gaveUp = false;
+    try {
+      const launchPromise = puppeteer.launch({
+        executablePath: launcher.executablePath,
+        pipe: true,
+        headless: true,
+        userDataDir: profileDir,
+        // Bound the phases puppeteer's own timeout covers (spawn,
+        // endpoint wait, initial page target).
+        timeout: TIER1_CDP_CALL_WATCHDOG_MS,
+        args: buildBrowserArgs(profileDir) as string[],
+      });
+      // A launch that outlives the watchdog is abandoned; should the
+      // handshake settle late anyway, close the orphan immediately AND
+      // remove its profile dir. The watchdog's catch block already
+      // removed `profileDir` on the abandon path, but a Chromium
+      // process that only resolves afterward can recreate/write into
+      // that same directory on its way up — closing without a second
+      // (idempotent) removal would strand it again.
+      void launchPromise.then(
+        (late) => {
+          if (gaveUp) {
+            void late
+              .close()
+              .catch(() => {})
+              .finally(() => removeEphemeralProfileDir(profileDir));
+          }
+        },
+        () => {},
+      );
+      // Separate watchdog around the WHOLE launch: with pipe transport
+      // puppeteer's own timeout does not cover the spawn/handshake
+      // phase, which can pend forever (observed: spawn after another
+      // browser's teardown never produces a child process).
+      browser = await Promise.race([
+        launchPromise,
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(() => {
+            gaveUp = true;
+            reject(new Tier1TransportWedgeError("launch handshake"));
+          }, TIER1_CDP_CALL_WATCHDOG_MS);
+        }),
+      ]);
+      traceLaunch("puppeteer-launch-complete", startedAt);
+    } catch (error) {
+      removeEphemeralProfileDir(profileDir);
+      if (error instanceof Tier1TransportWedgeError) throw error;
+      const message = error instanceof Error ? error.message : String(error);
+      if (error instanceof Error && error.name === "TimeoutError") {
+        throw new Tier1TransportWedgeError(`launch: ${message}`);
+      }
+      throw new Error(`tier1: puppeteer launch failed: ${message}`, { cause: error });
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+    let page: Page;
+    try {
+      page = await browser.newPage();
+      traceLaunch("page-created", startedAt);
+    } catch (error) {
+      await browser.close().catch(() => {});
+      removeEphemeralProfileDir(profileDir);
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`tier1: failed to open page: ${message}`, { cause: error });
+    }
+    let session: CDPSession;
+    try {
+      session = await page.createCDPSession();
+      traceLaunch("cdp-session-created", startedAt);
+    } catch (error) {
+      await page.close().catch(() => {});
+      await browser.close().catch(() => {});
+      removeEphemeralProfileDir(profileDir);
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`tier1: failed to open CDP session: ${message}`, { cause: error });
+    }
+    traceLaunch("ready", startedAt);
+    return new PuppeteerVerifierTarget(browser, page, session, profileDir);
+  }
+
+  async probeAvailability(): Promise<{ available: boolean; reason: string | null }> {
+    const launcher = this.options.launcher ?? resolveLauncher();
+    let browser: Browser | undefined;
+    const profileDir = createEphemeralProfileDir();
+    try {
+      browser = await puppeteer.launch({
+        executablePath: launcher.executablePath,
+        pipe: true,
+        headless: true,
+        userDataDir: profileDir,
+        args: buildBrowserArgs(profileDir) as string[],
+      });
+      const page = await browser.newPage();
+      await page.close();
+      await browser.close();
+      return { available: true, reason: null };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { available: false, reason: message };
+    } finally {
+      if (browser !== undefined) {
+        try {
+          await browser.close();
+        } catch {
+          // already closed
+        }
+      }
+      removeEphemeralProfileDir(profileDir);
+    }
+  }
+}

package/src/validation/tier1/entries/chart.ts

@@ -0,0 +1,5 @@
+import { renderChart } from "../../../gallery-web/frame/renderers/chart";
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["chart", renderChart]]));

package/src/validation/tier1/entries/html.ts

@@ -0,0 +1,6 @@
+import "../../../gallery-web/frame/styles/artifact.css";
+import { renderHtml } from "../../../gallery-web/frame/renderers/html";
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["html", renderHtml]]));

package/src/validation/tier1/entries/markdown.ts

@@ -0,0 +1,5 @@
+import { renderMarkdown } from "../../../gallery-web/frame/renderers/markdown";
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["markdown", renderMarkdown]]));

package/src/validation/tier1/entries/mermaid.ts

@@ -0,0 +1,5 @@
+import { renderMermaidDocument } from "../../../gallery-web/frame/renderers/mermaid";
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["mermaid", renderMermaidDocument]]));

package/src/validation/tier1/entries/svg.ts

@@ -0,0 +1,5 @@
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { renderSvgDocument } from "../../../gallery-web/frame/renderers/svg";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["svg", renderSvgDocument]]));

package/src/validation/tier1/entries/tsx.ts

@@ -0,0 +1,5 @@
+import { renderTsx } from "../../../gallery-web/frame/renderers/tsx";
+import { createRendererRegistry } from "../../../gallery-web/frame/renderers/registry";
+import { startTier1Harness } from "../harness-entry";
+
+startTier1Harness(createRendererRegistry([["tsx", renderTsx]]));