@legionworks/facet 1.9.0

package/src/service/export.ts

@@ -0,0 +1,218 @@
+import { readFileSync, realpathSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+
+import {
+  ExportResultSchema,
+  type ExportRequest,
+  type ExportResult,
+} from "../shared/contracts/commands";
+import type { Artifact, Revision } from "../shared/contracts/artifact";
+import {
+  mediaTypeForEvidenceImage,
+  sniffEvidenceImageFormat,
+  type EvidenceImageFormat,
+} from "../shared/evidence-image";
+import { buildExportSidecar } from "../shared/export";
+import { FacetError } from "../shared/errors/facet-error";
+import { now } from "../shared/util/time";
+import { latestStoredVerdict, verdictFromStoredRun } from "./stored-verdict";
+import type { ArtifactRepository } from "./store/repository";
+
+export { buildExportSidecar } from "../shared/export";
+
+function resolveExportTarget(
+  repository: ArtifactRepository,
+  command: ExportRequest,
+): { artifact: Artifact; revision: Revision } {
+  const artifact = repository.getArtifactById(command.artifactId);
+  if (artifact === null) {
+    throw new FacetError("artifact_not_found", "Artifact not found", {
+      retryable: false,
+      details: { artifactId: command.artifactId },
+    });
+  }
+
+  const revision =
+    command.revisionSha === undefined
+      ? repository.getLatestRevision(command.artifactId)
+      : repository.getRevisionBySha(command.artifactId, command.revisionSha);
+  if (revision === null) {
+    throw new FacetError("revision_not_found", "Revision not found", {
+      retryable: false,
+      details: {
+        artifactId: command.artifactId,
+        ...(command.revisionSha === undefined ? {} : { revisionSha: command.revisionSha }),
+      },
+    });
+  }
+  return { artifact, revision };
+}
+
+function evidenceUnavailable(artifact: Artifact, revision: Revision, cause?: unknown): FacetError {
+  return new FacetError("evidence_unavailable", "Screenshot evidence unavailable", {
+    retryable: false,
+    ...(cause === undefined ? {} : { cause }),
+    details: { artifactId: artifact.id, revisionSha: revision.sha256 },
+  });
+}
+
+// Legacy evidence roots whose tolerant read has already been reported.
+// The service is long-lived, so the migration warning fires at most once
+// per process per legacy root.
+const loggedLegacyEvidenceRoots = new Set<string>();
+
+function resolveEvidencePath(
+  repository: ArtifactRepository,
+  screenshotPath: string,
+  artifact: Artifact,
+  revision: Revision,
+): string {
+  const evidenceRoot = repository.getEvidenceRoot();
+  if (evidenceRoot === undefined) throw evidenceUnavailable(artifact, revision);
+  // The stored screenshot path is absolute, so the read root is decided per
+  // path, not by "is the canonical root empty": try the canonical root first,
+  // then the legacy child-derived root (pre explicit-threading installs wrote
+  // evidence there). The legacy root is read-only — never written.
+  const roots: Array<{ root: string; legacy: boolean }> = [{ root: evidenceRoot, legacy: false }];
+  const legacyRoot = repository.getLegacyEvidenceRoot();
+  if (legacyRoot !== undefined && legacyRoot !== evidenceRoot) {
+    roots.push({ root: legacyRoot, legacy: true });
+  }
+  for (const { root, legacy } of roots) {
+    try {
+      const resolvedRoot = realpathSync(root);
+      const resolvedCandidate = realpathSync(screenshotPath);
+      const relativeCandidate = relative(resolvedRoot, resolvedCandidate);
+      if (
+        relativeCandidate.length === 0 ||
+        isAbsolute(relativeCandidate) ||
+        relativeCandidate === ".." ||
+        relativeCandidate.startsWith("../")
+      ) {
+        // Not under this root — try the next (legacy) root.
+        continue;
+      }
+      if (legacy && !loggedLegacyEvidenceRoots.has(root)) {
+        loggedLegacyEvidenceRoots.add(root);
+        console.warn(
+          `facet: reading legacy evidence root ${root} (tolerant read; new evidence is written to ${evidenceRoot})`,
+        );
+      }
+      return resolvedCandidate;
+    } catch {
+      // root missing or candidate unresolvable — try the next root
+    }
+  }
+  throw evidenceUnavailable(artifact, revision);
+}
+
+export function readStoredRenderEvidence(input: {
+  readonly repository: ArtifactRepository;
+  readonly artifact: Artifact;
+  readonly revision: Revision;
+}): {
+  bytes: Uint8Array;
+  format: EvidenceImageFormat;
+  mediaType: ReturnType<typeof mediaTypeForEvidenceImage>;
+  verdict: ReturnType<typeof verdictFromStoredRun>;
+} {
+  const run = input.repository.listRenderRuns({ revisionId: input.revision.id, tier: 1 })[0];
+  if (run === undefined || run.screenshotPath === null) {
+    throw evidenceUnavailable(input.artifact, input.revision);
+  }
+
+  try {
+    const screenshotPath = resolveEvidencePath(
+      input.repository,
+      run.screenshotPath,
+      input.artifact,
+      input.revision,
+    );
+    const bytes = new Uint8Array(readFileSync(screenshotPath));
+    // File bytes are authoritative; an unknown signature is unavailable evidence, not PNG.
+    const format = sniffEvidenceImageFormat(bytes);
+    if (format === null) throw evidenceUnavailable(input.artifact, input.revision);
+    return {
+      bytes,
+      format,
+      mediaType: mediaTypeForEvidenceImage(format),
+      verdict: verdictFromStoredRun(input.revision, run),
+    };
+  } catch (cause) {
+    if (cause instanceof FacetError) throw cause;
+    throw evidenceUnavailable(input.artifact, input.revision, cause);
+  }
+}
+
+export function exportStoredSource(input: {
+  readonly repository: ArtifactRepository;
+  readonly command: ExportRequest;
+  readonly requestId: string;
+  readonly exportedAt?: string;
+}): ExportResult {
+  if (input.command.format === "render") {
+    throw new FacetError("evidence_unavailable", "Render export is not implemented", {
+      retryable: false,
+      details: { format: input.command.format },
+    });
+  }
+
+  const { artifact, revision } = resolveExportTarget(input.repository, input.command);
+
+  const verdict = latestStoredVerdict(input.repository, revision);
+  if (verdict === null) {
+    throw new FacetError("revision_not_found", "No stored verdict for revision", {
+      retryable: false,
+      details: { revisionId: revision.id },
+    });
+  }
+
+  const format = input.command.format;
+  return ExportResultSchema.parse({
+    command: "export",
+    requestId: input.requestId,
+    format,
+    bytes: Buffer.from(revision.source).toString("base64"),
+    sidecar: buildExportSidecar({
+      artifactId: artifact.id,
+      slug: artifact.slug,
+      revisionSha: revision.sha256,
+      artifactType: revision.artifactType,
+      renderer: revision.renderer,
+      verdict,
+      format,
+      exportedAt: input.exportedAt ?? now(),
+    }),
+  });
+}
+
+export function exportStoredRender(input: {
+  readonly repository: ArtifactRepository;
+  readonly command: ExportRequest;
+  readonly requestId: string;
+  readonly exportedAt?: string;
+}): ExportResult {
+  const { artifact, revision } = resolveExportTarget(input.repository, input.command);
+  const evidence = readStoredRenderEvidence({
+    repository: input.repository,
+    artifact,
+    revision,
+  });
+  return ExportResultSchema.parse({
+    command: "export",
+    requestId: input.requestId,
+    format: "render",
+    bytes: Buffer.from(evidence.bytes).toString("base64"),
+    sidecar: buildExportSidecar({
+      artifactId: artifact.id,
+      slug: artifact.slug,
+      revisionSha: revision.sha256,
+      artifactType: revision.artifactType,
+      renderer: revision.renderer,
+      verdict: evidence.verdict,
+      format: "render",
+      renderFormat: evidence.format,
+      exportedAt: input.exportedAt ?? now(),
+    }),
+  });
+}

package/src/service/http-utils.ts

@@ -0,0 +1,55 @@
+/**
+ * HTTP utilities shared by the router and the SSE stream.
+ *
+ * `envelopeResponse` is the single Response builder for every Facet
+ * route. The `cache-control: no-store` header is universal — no Facet
+ * response is cacheable, and a divergent cache header between routes
+ * would let a proxy pin a stale error envelope for a future caller.
+ *
+ * `generateRequestId` lives in `src/shared/util/time.ts` and is
+ * re-exported here so the existing import sites (router.ts, stream.ts)
+ * keep working without churn.
+ */
+
+import { type FacetEnvelope } from "../shared/contracts/envelope";
+import { generateRequestId } from "../shared/util/time";
+
+export { generateRequestId };
+
+const NO_STORE = "no-store";
+const TIER1_TRACE = process.env.FACET_TIER1_TRACE === "1";
+
+function traceTier1Transport(stage: string): void {
+  if (!TIER1_TRACE) return;
+  process.stderr.write(`[tier1-transport] ${stage}\n`);
+}
+
+export function envelopeResponse(envelope: FacetEnvelope<unknown>, status: number): Response {
+  traceTier1Transport(
+    `envelope-response:serialize:start status=${status} requestId=${envelope.requestId}`,
+  );
+  const body = JSON.stringify(envelope);
+  traceTier1Transport(
+    `envelope-response:serialize:complete bytes=${body.length} status=${status} requestId=${envelope.requestId}`,
+  );
+  const response = new Response(body, {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": NO_STORE,
+    },
+  });
+  traceTier1Transport(`envelope-response:return status=${status} requestId=${envelope.requestId}`);
+  return response;
+}
+
+/**
+ * Prefer a caller-supplied request id (when present and non-empty),
+ * otherwise mint one. The router uses the `null` form to always mint;
+ * a future caller can forward an upstream correlation id unchanged.
+ */
+export function pickRequestId(header: string | null | undefined): string {
+  if (header === null || header === undefined) return generateRequestId();
+  const trimmed = header.trim();
+  return trimmed.length > 0 ? trimmed : generateRequestId();
+}

package/src/service/lexical/expectations.ts

@@ -0,0 +1,210 @@
+/**
+ * Lexical expectations — the ONLY type-adjacent service module. It
+ * scans source bytes as TEXT to count fenced blocks (total + per-language
+ * for `mermaid`) and to estimate the renderer root count, WITHOUT
+ * importing any markdown, mermaid, svg, or dom-shim library.
+ *
+ * The boundary checker (scripts/check-boundaries.ts) tolerates this
+ * single file under src/service/ because the whole point of the
+ * service is to remain byte-dumb while still being able to compute
+ * lexical expectations the verifier compares against its own observed
+ * counts.
+ */
+
+import { MAX_MERMAID_BLOCKS, MAX_MERMAID_NODES } from "../../shared/config/limits";
+import type { ArtifactType } from "../../shared/contracts/artifact";
+import type { Renderer } from "../../shared/contracts/renderers";
+import { countMermaidNodeDeclarations } from "../../shared/util/mermaid-nodes";
+
+export interface FencedBlockCounts {
+  /** Total number of fenced blocks (any language) in the source. */
+  readonly total: number;
+  /** Number of fenced blocks whose info string equals "mermaid" (trimmed, case-sensitive). */
+  readonly mermaid: number;
+  /**
+   * Per-language counts. Key is the trimmed info string of the fence
+   * (e.g. "mermaid", "typescript"); fenced blocks with no info string
+   * collapse into the empty-string key.
+   */
+  readonly byLanguage: ReadonlyMap<string, number>;
+}
+
+export interface LexicalExpectations {
+  readonly totalFencedBlocks: number;
+  readonly mermaidBlocks: number;
+  readonly fencedBlocksByLanguage: ReadonlyMap<string, number>;
+  /**
+   * Expected number of renderer-root SVGs. For markdown sources this
+   * is the mermaid block count (each fenced mermaid block produces one
+   * renderer root); for mermaid/svg and SVG-rendered chart sources it is 1
+   * (the whole document renders as one renderer-owned root). Canvas charts
+   * have no SVG root. The verifier counts
+   * the actual SVGs and the verdict fails closed on any divergence.
+   */
+  readonly expectedRendererRoots: number;
+  /** Expected opaque regions produced by renderer modes without SVG roots. */
+  readonly expectedOpaqueRegions: number;
+  /**
+   * Lexical node expectation across all Mermaid blocks. `null` is a typed
+   * no-expectation marker for a diagram type without a maintained `g.node`
+   * grammar, so Tier 1 skips this one comparison rather than treating zero
+   * as a vacuous match.
+   */
+  readonly mermaidNodeCount: number | null;
+  /** True iff the source exceeds MAX_MERMAID_BLOCKS or MAX_MERMAID_NODES. */
+  readonly exceedsComplexityBudget: boolean;
+}
+
+/**
+ * Fence opener: a line that begins with three-or-more backticks OR
+ * three-or-more tildes, optionally followed by an info string. Closing
+ * fence: a line of the same character whose run length is at least the
+ * opener's run length. Info strings are trimmed; an empty info string
+ * is allowed and maps to the "" key.
+ */
+const FENCE_OPENER_RE = /^[ ]{0,3}(`{3,}|~{3,})([^\n]*)$/gm;
+
+interface FenceSpan {
+  readonly start: number;
+  readonly end: number;
+  readonly info: string;
+  readonly char: "`" | "~";
+}
+
+interface FenceCandidate {
+  readonly index: number;
+  readonly length: number;
+  readonly char: "`" | "~";
+  /** Trimmed info string after the fence chars; "" when only whitespace. */
+  readonly info: string;
+}
+
+/**
+ * A closing code fence must use the same character as the opening
+ * fence, be at least as long, and carry NO info string (only whitespace
+ * after the fence chars). Without the info-string check, an inner fence
+ * with a language tag (e.g. ```mermaid inside a ```mermaid body)
+ * would silently close its enclosing fence and split one block into two.
+ */
+function isValidCloser(candidate: FenceCandidate, open: FenceCandidate): boolean {
+  return candidate.char === open.char && candidate.length >= open.length && candidate.info === "";
+}
+
+function findFenceSpans(text: string): FenceSpan[] {
+  const spans: FenceSpan[] = [];
+  const candidates: FenceCandidate[] = [];
+  for (const match of text.matchAll(FENCE_OPENER_RE)) {
+    const index = match.index ?? 0;
+    const fence = match[1] ?? "";
+    const info = (match[2] ?? "").trim();
+    const char: "`" | "~" = fence.startsWith("`") ? "`" : "~";
+    candidates.push({ index, length: fence.length, char, info });
+  }
+  let open: FenceCandidate | null = null;
+  for (const candidate of candidates) {
+    if (open === null) {
+      open = candidate;
+      continue;
+    }
+    if (isValidCloser(candidate, open)) {
+      spans.push({
+        start: open.index,
+        end: candidate.index + candidate.length,
+        info: open.info,
+        char: open.char,
+      });
+      open = null;
+      continue;
+    }
+    // Not a valid closer (different char, shorter run, or carries an
+    // info string). The candidate is body content of the open fence;
+    // keep looking for the real closer.
+  }
+  return spans;
+}
+
+function countMermaidNodes(text: string, spans: readonly FenceSpan[]): number | null {
+  let count = 0;
+  for (const span of spans) {
+    if (span.info !== "mermaid") continue;
+    const body = text.slice(span.start, span.end);
+    const nodes = countMermaidNodeDeclarations(body);
+    if (nodes === null) return null;
+    count += nodes;
+  }
+  return count;
+}
+
+/**
+ * Count fenced code blocks. Returns total + per-language + the
+ * special-cased mermaid count. The byte input is decoded as UTF-8;
+ * the caller is expected to pass artifact source bytes, not arbitrary
+ * binary blobs.
+ */
+export function countFencedBlocks(bytes: Uint8Array): {
+  total: number;
+  mermaid: number;
+  byLanguage: Map<string, number>;
+} {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  const spans = findFenceSpans(text);
+  const byLanguage = new Map<string, number>();
+  let mermaid = 0;
+  for (const span of spans) {
+    const key = span.info;
+    byLanguage.set(key, (byLanguage.get(key) ?? 0) + 1);
+    if (key === "mermaid") mermaid += 1;
+  }
+  return { total: spans.length, mermaid, byLanguage };
+}
+
+/** Convenience wrapper that returns only the mermaid block count. */
+export function countMermaidBlocks(bytes: Uint8Array): number {
+  return countFencedBlocks(bytes).mermaid;
+}
+
+/**
+ * Compute the full lexical expectation surface for a source. The
+ * shape is the one consumed later by Tier 0 / Tier 1 verifiers to
+ * compare lexical expectations against observed counters.
+ *
+ * The expectations are artifact-type aware because the renderers are:
+ * markdown produces one renderer root per mermaid fence; mermaid,
+ * svg, and chart each render the whole document as ONE renderer-owned
+ * root. Node declarations are predicted only for the diagram-bearing
+ * types (markdown fences, mermaid documents).
+ */
+export function computeLexicalExpectations(
+  bytes: Uint8Array,
+  artifactType: ArtifactType,
+  renderer: Renderer = "svg",
+): LexicalExpectations {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  const spans = findFenceSpans(text);
+  const byLanguage = new Map<string, number>();
+  let mermaid = 0;
+  for (const span of spans) {
+    byLanguage.set(span.info, (byLanguage.get(span.info) ?? 0) + 1);
+    if (span.info === "mermaid") mermaid += 1;
+  }
+  const mermaidNodeCount =
+    artifactType === "markdown"
+      ? countMermaidNodes(text, spans)
+      : artifactType === "mermaid"
+        ? countMermaidNodeDeclarations(text)
+        : 0;
+  const exceedsComplexityBudget =
+    mermaid > MAX_MERMAID_BLOCKS ||
+    (mermaidNodeCount !== null && mermaidNodeCount > MAX_MERMAID_NODES);
+  const canvasChart = artifactType === "chart" && renderer === "canvas";
+  const expectedRendererRoots = canvasChart ? 0 : artifactType === "markdown" ? mermaid : 1;
+  return {
+    totalFencedBlocks: spans.length,
+    mermaidBlocks: mermaid,
+    fencedBlocksByLanguage: byLanguage,
+    expectedRendererRoots,
+    expectedOpaqueRegions: canvasChart ? 1 : 0,
+    mermaidNodeCount,
+    exceedsComplexityBudget,
+  };
+}

package/src/service/lifecycle/idle-controller.ts

@@ -0,0 +1,125 @@
+/**
+ * Idle controller — the service's single reason-counted state machine.
+ *
+ * Three reason kinds exist today (in-flight HTTP request, active SSE
+ * gallery lease, running validation job) and the rule is the same for
+ * all three: count > 0 keeps the service alive, count == 0 starts a
+ * short timer, count still 0 at expiry triggers graceful shutdown.
+ *
+ * No DB polling, no filesystem watcher, no periodic sweep — the timer
+ * is scheduled only when the count transitions to 0. This keeps the
+ * dormant cost literally zero: a service that never receives a request
+ * never wakes up to check.
+ *
+ * Lease expiry is handled in the lease manager itself (per-lease
+ * unrefed timer) and notifies the controller via its own acquire/release
+ * API — there is no separate lease-expiry polling loop here.
+ */
+
+export interface IdleControllerOptions {
+  readonly idleTimeoutMs: number;
+  readonly onIdle?: () => void | Promise<void>;
+  readonly now?: () => number;
+  readonly setTimer?: (handler: () => void, ms: number) => () => void;
+}
+
+export interface IdleController {
+  acquire(tag: string): void;
+  release(tag: string): void;
+  count(): number;
+  waitUntilIdle(): Promise<void>;
+  stop(): void;
+}
+
+function defaultClear(handle: ReturnType<typeof setTimeout>): void {
+  clearTimeout(handle);
+}
+
+export function createIdleController(options: IdleControllerOptions): IdleController {
+  const counts = new Map<string, number>();
+  const setTimer =
+    options.setTimer ??
+    ((handler: () => void, ms: number) => {
+      const handle = setTimeout(handler, ms);
+      if (typeof handle.unref === "function") handle.unref();
+      return () => defaultClear(handle);
+    });
+  let timer: (() => void) | null = null;
+  let fired = false;
+  let idlePromise: Promise<void> | null = null;
+
+  function ensureIdlePromise(): Promise<void> {
+    if (idlePromise === null) {
+      idlePromise = new Promise<void>((resolve) => {
+        if (fired) {
+          resolve();
+        } else {
+          // Stash the resolver on a private field via closure.
+          idleResolvers.push(resolve);
+        }
+      });
+    }
+    return idlePromise;
+  }
+
+  const idleResolvers: Array<() => void> = [];
+
+  function fire(): void {
+    if (fired) return;
+    fired = true;
+    try {
+      options.onIdle?.();
+    } catch {
+      // The handler is allowed to throw; we deliberately swallow so
+      // the idle path always reaches its terminal state.
+    }
+    for (const resolve of idleResolvers.splice(0)) resolve();
+  }
+
+  function cancelTimer(): void {
+    if (timer !== null) {
+      timer();
+      timer = null;
+    }
+  }
+
+  function scheduleIdle(): void {
+    cancelTimer();
+    timer = setTimer(() => {
+      timer = null;
+      // Only fire if we are STILL idle when the timer expires.
+      if (counts.size === 0) fire();
+    }, options.idleTimeoutMs);
+  }
+
+  return {
+    acquire(tag) {
+      counts.set(tag, (counts.get(tag) ?? 0) + 1);
+      if (counts.size === 1) cancelTimer();
+    },
+    release(tag) {
+      const current = counts.get(tag);
+      if (current === undefined) return;
+      if (current <= 1) counts.delete(tag);
+      else counts.set(tag, current - 1);
+      if (counts.size === 0 && !fired) scheduleIdle();
+    },
+    count() {
+      let total = 0;
+      for (const v of counts.values()) total += v;
+      return total;
+    },
+    waitUntilIdle() {
+      if (fired) return Promise.resolve();
+      // If count is currently 0 and no timer is scheduled, schedule one
+      // now so waitUntilIdle() actually fires — the count-starting-at-zero
+      // case has no release() to schedule the timer on.
+      if (counts.size === 0 && timer === null) scheduleIdle();
+      return ensureIdlePromise();
+    },
+    stop() {
+      cancelTimer();
+      fire();
+    },
+  };
+}