@legionworks/facet 1.9.0

package/src/service/store/schema.ts

@@ -0,0 +1,218 @@
+import { TSX_EXECUTION_MODES } from "../../shared/tsx/execution";
+
+/**
+ * The canonical DDL applied to a fresh database. Every column the
+ * schema holds today lives here; the v1 migration runs this block
+ * verbatim. Subsequent migrations extend this table set via additive
+ * ALTER TABLE statements (never a destructive rewrite — the schema
+ * migrations ledger records each version).
+ *
+ * Fresh v8 databases apply this block first (v1), then the v2-v8
+ * fragments in order. The v8 fragment widens the CHECK to include
+ * `tsx`, adds `revisions.execution`, and adds `render_runs.compiled_path`.
+ * Migrations are tracked, so a re-run on an already-migrated DB skips
+ * already-applied versions.
+ */
+export const INITIAL_SCHEMA = `
+CREATE TABLE projects(
+  id TEXT PRIMARY KEY,
+  project_root TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE artifacts(
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id),
+  slug TEXT NOT NULL,
+  title TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(project_id, slug)
+);
+CREATE TABLE revisions(
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL REFERENCES artifacts(id),
+  revision_number INTEGER NOT NULL,
+  parent_revision_id TEXT REFERENCES revisions(id),
+  artifact_type TEXT NOT NULL CHECK(artifact_type IN ('markdown','mermaid','svg','chart','html')),
+  source BLOB NOT NULL,
+  sha256 TEXT NOT NULL,
+  note TEXT,
+  pinned INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  UNIQUE(artifact_id, revision_number),
+  UNIQUE(artifact_id, sha256)
+);
+CREATE TABLE render_runs(
+  id TEXT PRIMARY KEY,
+  revision_id TEXT NOT NULL REFERENCES revisions(id),
+  tier INTEGER NOT NULL CHECK(tier IN (0,1)),
+  status TEXT NOT NULL,
+  expected_json TEXT NOT NULL,
+  observed_json TEXT NOT NULL,
+  screenshot_path TEXT,
+  console_path TEXT,
+  started_at TEXT NOT NULL,
+  finished_at TEXT NOT NULL
+);
+CREATE TABLE templates(
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL REFERENCES artifacts(id),
+  revision_id TEXT NOT NULL REFERENCES revisions(id),
+  name TEXT NOT NULL UNIQUE,
+  description TEXT,
+  promoted_by TEXT NOT NULL,
+  promoted_at TEXT NOT NULL
+);
+`;
+
+/**
+ * The v2 DDL fragment — appended after `INITIAL_SCHEMA` for fresh
+ * databases that land on v2 directly. Existing v1 databases pick up
+ * the v2 column via the migration step in `migrations.ts`. Keeping
+ * the fragment here (and not duplicated in the migration) means the
+ * canonical DDL and the migration body cannot drift apart.
+ */
+export const V2_SCHEMA_FRAGMENT = `
+ALTER TABLE render_runs ADD COLUMN retained INTEGER NOT NULL DEFAULT 0;
+`;
+
+/** The v3 DDL fragment adds renderer persistence; its literal CHECK mirrors RENDERERS deliberately and is parity-tested. */
+export const V3_SCHEMA_FRAGMENT = `
+ALTER TABLE revisions ADD COLUMN renderer TEXT NOT NULL DEFAULT 'svg' CHECK(renderer IN ('svg','canvas'));
+`;
+
+/** The v4 fragment preserves typed screenshot-capture failures across read-back. */
+export const V4_SCHEMA_FRAGMENT = `
+ALTER TABLE render_runs ADD COLUMN screenshot_error_json TEXT;
+`;
+
+/** The v5 fragment persists the insecure execution marker with each run. */
+export const V5_SCHEMA_FRAGMENT = `
+ALTER TABLE render_runs ADD COLUMN insecure_json TEXT;
+`;
+
+/**
+ * The v6 rebuild widens revisions.artifact_type. SQLite cannot alter a CHECK
+ * in place, so the official create-copy-drop-rename procedure preserves child
+ * foreign-key clauses by never renaming the original table.
+ */
+export const V6_SCHEMA_FRAGMENT = `
+CREATE TABLE revisions_v6(
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL REFERENCES artifacts(id),
+  revision_number INTEGER NOT NULL,
+  parent_revision_id TEXT REFERENCES revisions(id),
+  artifact_type TEXT NOT NULL CHECK(artifact_type IN ('markdown','mermaid','svg','chart','html')),
+  source BLOB NOT NULL,
+  sha256 TEXT NOT NULL,
+  note TEXT,
+  pinned INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  renderer TEXT NOT NULL DEFAULT 'svg' CHECK(renderer IN ('svg','canvas')),
+  UNIQUE(artifact_id, revision_number),
+  UNIQUE(artifact_id, sha256)
+);
+INSERT INTO revisions_v6(
+  id, artifact_id, revision_number, parent_revision_id, artifact_type, source, sha256,
+  note, pinned, created_at, renderer
+)
+SELECT
+  id, artifact_id, revision_number, parent_revision_id, artifact_type, source, sha256,
+  note, pinned, created_at, renderer
+FROM revisions;
+DROP TABLE revisions;
+ALTER TABLE revisions_v6 RENAME TO revisions;
+`;
+
+/**
+ * The v7 backfill repairs render_runs.observed_json rows written by
+ * prior releases that did NOT include the `opaqueRegionCount` and
+ * `externalImageCount` counters. A strict `VerdictObservedSchema.parse`
+ * would 400 read-back / export / gallery-source on every pre-arc
+ * artifact; the schema-level repair writes a 0 for every missing
+ * counter so future reads don't have to.
+ *
+ * The migration is idempotent: `json_extract(observed_json, '$.x')` is
+ * null when the field is absent, and `COALESCE` replaces that null with
+ * 0. Re-running the migration against an already-migrated row is a
+ * no-op because `COALESCE(null, 0)` and `COALESCE(0, 0)` both yield 0
+ * and the rebuilt JSON is identical to the existing one.
+ *
+ * This is the schema-side companion to the runtime tolerant read in
+ * `src/service/stored-verdict.ts` `withTolerantObserved`. The tolerant
+ * read defends the boundary against a row that was written before
+ * this migration ran; the migration moves the on-disk JSON to the
+ * current shape so future readers can be strict again if they want.
+ */
+export const V7_SCHEMA_FRAGMENT = `
+UPDATE render_runs
+SET observed_json = json_set(
+  json_set(
+    observed_json,
+    '$.opaqueRegionCount',
+    COALESCE(json_extract(observed_json, '$.opaqueRegionCount'), 0)
+  ),
+  '$.externalImageCount',
+  COALESCE(json_extract(observed_json, '$.externalImageCount'), 0)
+)
+WHERE
+  json_type(observed_json, '$.opaqueRegionCount') IS NULL
+  OR json_type(observed_json, '$.externalImageCount') IS NULL
+`;
+
+/**
+ * The v8 rebuild widens `revisions.artifact_type` to include `tsx`,
+ * adds `revisions.execution` (D2 of the TSX design — declared mode,
+ * default `static`, backfilled for every prior row), and adds
+ * `render_runs.compiled_path` (D7 — derived bundle stored alongside
+ * the run, NULLABLE so non-TSX runs and pre-arc rows stay NULL).
+ *
+ * SQLite cannot alter a CHECK in place, so the create-copy-drop-rename
+ * pattern from v6 is reused here. Every column is copied explicitly,
+ * and `execution` is set to `'static'` for every v7 row so the
+ * NOT NULL DEFAULT on the new column is satisfied without a separate
+ * UPDATE.
+ *
+ * Trap that shipped twice in this project (opaque-content v6 and
+ * HTML v7): adding a REQUIRED column to a stored shape breaks
+ * read-back of every row written by earlier releases. The fix is
+ * BOTH halves: a tolerant read in `src/service/stored-verdict.ts`
+ * for the runtime boundary AND a backfill migration on disk. The
+ * v8 backfill below is the schema-side half; the existing
+ * `withTolerantObserved` defends the runtime half for `observed_json`
+ * while this fragment backfills `execution` and widens the CHECK.
+ */
+export const V8_SCHEMA_FRAGMENT = `
+CREATE TABLE revisions_v8(
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL REFERENCES artifacts(id),
+  revision_number INTEGER NOT NULL,
+  parent_revision_id TEXT REFERENCES revisions(id),
+  artifact_type TEXT NOT NULL CHECK(artifact_type IN ('markdown','mermaid','svg','chart','html','tsx')),
+  source BLOB NOT NULL,
+  sha256 TEXT NOT NULL,
+  note TEXT,
+  pinned INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  renderer TEXT NOT NULL DEFAULT 'svg' CHECK(renderer IN ('svg','canvas')),
+  execution TEXT NOT NULL DEFAULT 'static' CHECK(execution IN (${TSX_EXECUTION_MODES.map((mode) => `'${mode}'`).join(",")})),
+  UNIQUE(artifact_id, revision_number),
+  UNIQUE(artifact_id, sha256)
+);
+INSERT INTO revisions_v8(
+  id, artifact_id, revision_number, parent_revision_id, artifact_type, source, sha256,
+  note, pinned, created_at, renderer, execution
+)
+SELECT
+  id, artifact_id, revision_number, parent_revision_id, artifact_type, source, sha256,
+  note, pinned, created_at, renderer, 'static'
+FROM revisions;
+DROP TABLE revisions;
+ALTER TABLE revisions_v8 RENAME TO revisions;
+ALTER TABLE render_runs ADD COLUMN compiled_path TEXT;
+`;
+
+export const V9_SCHEMA_FRAGMENT = `
+ALTER TABLE render_runs ADD COLUMN screenshot_format TEXT
+  CHECK(screenshot_format IN ('png','webp'));
+`;

package/src/service/stored-verdict.ts

@@ -0,0 +1,97 @@
+import type { Revision, RenderRun } from "../shared/contracts/artifact";
+import { VerdictSchema, type Verdict, type VerdictObserved } from "../shared/contracts/validation";
+import type { ArtifactRepository } from "./store/repository";
+
+/**
+ * Tolerate counters the pre-arc stored-observation schema did not
+ * include. Every prior release pre-dates both `externalImageCount`
+ * (added by this arc) and `opaqueRegionCount` (added by the prior
+ * opaque-content arc); a strict `VerdictObservedSchema.parse` would
+ * 400 the read-back / export / gallery-source routes on every
+ * pre-arc artifact. Default missing counters to 0 — the verdict's
+ * downstream behavior for a zero counter is what the verifier
+ * would have computed in the absence of the field (no partial,
+ * no opaque, no external_resources), and that is the conservative
+ * answer for a verifier that never observed the field at all.
+ *
+ * The companion migration (`src/service/store/migrations.ts`)
+ * backfills the missing counters to 0 in the on-disk JSON so the
+ * tolerant read is a defensive belt-and-braces against a row that
+ * was written before the migration ran. Treating the instance
+ * (`.optional()` on the schema) would fix this specific break but
+ * leave the same defect class to recur on the next counter
+ * addition; treating the boundary is what makes it durable.
+ */
+export function withTolerantObserved(parsed: unknown): VerdictObserved {
+  const observed = (parsed ?? {}) as Record<string, unknown>;
+  // Per-counter fallback: each field defaults to 0 when the stored
+  // JSON omits it (the pre-arc shape) and preserves the on-disk value
+  // when present. This is the durable treatment — every counter ever
+  // added can be extended the same way without re-breaking old rows.
+  const num = (key: string, fallback: number): number => {
+    const value = observed[key];
+    return typeof value === "number" ? value : fallback;
+  };
+  return {
+    rendererRootSvgCount: num("rendererRootSvgCount", 0),
+    graphCount: num("graphCount", 0),
+    mermaidNodeCount: num("mermaidNodeCount", 0),
+    visibleSvgCount: num("visibleSvgCount", 0),
+    opaqueRegionCount: num("opaqueRegionCount", 0),
+    externalImageCount: num("externalImageCount", 0),
+    // errorCount is required on the schema; pre-arc rows that never
+    // recorded it default to 0.
+    errorCount: num("errorCount", 0),
+    // Preserve optional fields the on-disk JSON may carry.
+    ...(observed.html !== undefined ? { html: observed.html as VerdictObserved["html"] } : {}),
+    ...(Array.isArray(observed.viewBoxes) ? { viewBoxes: observed.viewBoxes as string[] } : {}),
+    ...(Array.isArray(observed.discriminativeErrors)
+      ? {
+          discriminativeErrors:
+            observed.discriminativeErrors as VerdictObserved["discriminativeErrors"],
+        }
+      : {}),
+  };
+}
+
+export function verdictFromStoredRun(revision: Revision, run: RenderRun): Verdict {
+  return VerdictSchema.parse({
+    status: run.status,
+    tier: run.tier,
+    artifactId: revision.artifactId,
+    revisionSha: revision.sha256,
+    observed: withTolerantObserved(JSON.parse(run.observedJson)),
+    ...(run.screenshotErrorJson !== null
+      ? { screenshotError: JSON.parse(run.screenshotErrorJson) }
+      : {}),
+    ...(run.insecureJson !== null ? { insecure: JSON.parse(run.insecureJson) } : {}),
+    // Reconstruct execution from the revision row rather than the stored
+    // verdict. The render_run row carries no
+    // execution column (the marker is a verdict-level property, not a
+    // run-level one), and the marker is only emitted for TSX
+    // revisions — every other artifact type reads back with the
+    // field absent, so the wire form for non-TSX stays byte-identical.
+    //
+    // Execution-null policy (deliberate): when a TSX row's column
+    // is undefined on disk (purely defensive — the schema CHECK
+    // prevents NULL inserts and the v8 migration backfills pre-arc
+    // rows to 'static'), default to 'static' on the wire. 'static'
+    // is the canonical D2 default; emitting nothing was the prior
+    // silent behavior and an unpinned accident. Operators reading
+    // the wire form always see a marker on TSX rows.
+    ...(revision.artifactType === "tsx" ? { execution: revision.execution ?? "static" } : {}),
+  });
+}
+
+export function latestStoredVerdict(
+  repository: ArtifactRepository,
+  revision: Revision,
+): Verdict | null {
+  const runs = ([0, 1] as const)
+    .flatMap((tier) => repository.listRenderRuns({ revisionId: revision.id, tier }))
+    .toSorted(
+      (left, right) => right.finishedAt.localeCompare(left.finishedAt) || right.tier - left.tier,
+    );
+  const run = runs[0];
+  return run === undefined ? null : verdictFromStoredRun(revision, run);
+}

package/src/service/stream.ts

@@ -0,0 +1,301 @@
+/**
+ * SSE stream handler.
+ *
+ * The /api/v1/stream route emits revision-committed events to clients
+ * that hold a valid gallery lease. Auth happens BEFORE the lease check
+ * (a request without Bearer never reaches the lease logic), and the
+ * lease capability is carried via the authed fetch header — the
+ * `leaseId` is never embedded in a URL query parameter.
+ *
+ * Stream lifetime is bound to the lease: when the lease expires, the
+ * per-lease timer fires the manager's expiry-listener, which closes
+ * the controller and releases the stream's idle reason. Without this
+ * binding, the SSE connection would outlast its lease and the
+ * stream:<id> idle reason would pin the service alive forever.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { z } from "zod";
+
+import { errEnvelope } from "../shared/contracts/envelope";
+import type { RevisionCommittedEventSchema } from "../shared/contracts/events";
+
+import { requireBearer } from "./security/auth";
+import { checkHostOrigin, resolveHost } from "./security/host-origin";
+import type { GalleryLease, GalleryLeaseManager } from "./security/leases";
+import type { FacetLogger } from "../shared/logging/logger";
+import type { IdleController } from "./lifecycle/idle-controller";
+import { envelopeResponse, generateRequestId } from "./http-utils";
+
+const NO_STORE = "no-store";
+export const STREAM_HEARTBEAT_INTERVAL_MS = 15_000;
+
+export function assertHeartbeatBeforeLeaseTtl(
+  heartbeatIntervalMs: number,
+  leaseTtlMs: number,
+): void {
+  if (heartbeatIntervalMs >= leaseTtlMs) {
+    throw new RangeError("SSE heartbeat interval must be shorter than the lease TTL");
+  }
+}
+
+export type RevisionCommittedEvent = z.infer<typeof RevisionCommittedEventSchema>;
+
+/**
+ * Per-artifact fan-out for `revision:committed`. The write path
+ * (dispatcher, after commit + verdict runs) calls `emit`; every live
+ * SSE stream registered for that artifact receives the event. Sinks
+ * are isolated — one dead stream cannot wedge the others.
+ */
+export interface RevisionBroadcaster {
+  register(artifactId: string, send: (event: RevisionCommittedEvent) => void): () => void;
+  emit(event: RevisionCommittedEvent): void;
+  readonly size: number;
+}
+
+export function createRevisionBroadcaster(): RevisionBroadcaster {
+  const sinks = new Map<string, Set<(event: RevisionCommittedEvent) => void>>();
+  let size = 0;
+  return {
+    register(artifactId, send) {
+      let set = sinks.get(artifactId);
+      if (set === undefined) {
+        set = new Set();
+        sinks.set(artifactId, set);
+      }
+      set.add(send);
+      size += 1;
+      return () => {
+        const current = sinks.get(artifactId);
+        if (current === undefined) return;
+        if (current.delete(send)) size -= 1;
+        if (current.size === 0) sinks.delete(artifactId);
+      };
+    },
+    emit(event) {
+      const set = sinks.get(event.artifactId);
+      if (set === undefined) return;
+      // Spread snapshots the sinks so a callback that unregisters
+      // itself mid-fan-out does not skip the remaining peers.
+      // oxlint-disable-next-line unicorn/no-useless-spread
+      for (const send of [...set]) {
+        try {
+          send(event);
+        } catch {
+          // one dead stream must not wedge the fan-out
+        }
+      }
+    },
+    get size() {
+      return size;
+    },
+  };
+}
+
+export interface StreamHandlerDeps {
+  readonly installToken: string;
+  readonly leases: GalleryLeaseManager;
+  readonly idle: IdleController;
+  readonly logger: FacetLogger;
+  readonly expectedHost: string | (() => string);
+  readonly ownOrigin: string | (() => string);
+  readonly broadcaster: RevisionBroadcaster;
+  readonly heartbeatIntervalMs?: number;
+}
+
+interface StreamParsedRequest {
+  readonly url: string;
+  readonly method: string;
+  readonly host: string | null;
+  readonly origin: string | null;
+  readonly secFetchSite: string | null;
+  readonly authorization: string | null;
+  readonly headers: { get(name: string): string | null };
+}
+
+export function handleStream(deps: StreamHandlerDeps, req: StreamParsedRequest): Response {
+  const requestId = generateRequestId();
+
+  const hostCheck = checkHostOrigin({
+    method: req.method,
+    host: req.host,
+    origin: req.origin,
+    secFetchSite: req.secFetchSite,
+    expectedHost: resolveHost(deps.expectedHost),
+    ownOrigin: resolveHost(deps.ownOrigin),
+  });
+  if (!hostCheck.ok) {
+    let status = 400;
+    if (hostCheck.error.code === "invalid_request") {
+      const reason = (hostCheck.error.details as { reason?: string } | undefined)?.reason;
+      if (reason === "cross_site_mutation") status = 403;
+      else if (reason === "missing_host") status = 421;
+    }
+    return envelopeResponse(errEnvelope(requestId, hostCheck.error.toBody()), status);
+  }
+
+  const authResult = requireBearer(req.authorization, deps.installToken);
+  if (!authResult.ok) {
+    return envelopeResponse(errEnvelope(requestId, authResult.error.toBody()), 401);
+  }
+
+  // Lease capability travels in the `X-Gallery-Lease` header, never in
+  // a URL query parameter. URL tokens leak via server logs, the
+  // `Referer` header on outbound navigations, and the browser history
+  // — any of those would expose the lease id to processes the bearer
+  // holder did not authorise. A query-string `?lease=` is REJECTED (not
+  // silently accepted) so a misconfigured client sees a typed 401
+  // instead of an unguarded stream.
+  const leaseId = req.headers.get("x-gallery-lease");
+  const artifactId = req.headers.get("x-gallery-artifact");
+  if (leaseId === null || artifactId === null) {
+    return envelopeResponse(
+      errEnvelope(requestId, {
+        code: "invalid_envelope",
+        message:
+          "SSE requires X-Gallery-Lease + X-Gallery-Artifact headers (no query-string fallback)",
+        retryable: false,
+        details: { reason: "lease_header_missing" },
+      }),
+      401,
+    );
+  }
+
+  const lease: GalleryLease = {
+    leaseId,
+    artifactId,
+    pid: process.pid,
+    expiresAt: Date.now() + 1_000,
+  };
+  if (!deps.leases.validate(lease)) {
+    return envelopeResponse(
+      errEnvelope(requestId, {
+        code: "invalid_envelope",
+        message: "Lease is invalid or expired",
+        retryable: false,
+        details: { reason: "lease_invalid" },
+      }),
+      401,
+    );
+  }
+
+  const streamId = randomUUID();
+  deps.idle.acquire(`stream:${streamId}`);
+  const encoder = new TextEncoder();
+
+  // Per-stream teardown. Every teardown path (cancel, lease-gone,
+  // renew-failure) funnels through `releaseStreamOnly`; calling any of
+  // them twice is a no-op (the inner `closed` guard short-circuits).
+  let closed = false;
+  let unregister: (() => void) | null = null;
+  let heartbeat: ReturnType<typeof setInterval> | null = null;
+
+  // Shared stream-only teardown: clear the heartbeat interval, drop the
+  // broadcaster registration, and release the stream's idle reason. The
+  // lease is deliberately NOT touched here — the cancel path keeps the
+  // lease alive for the F5 refresh (the lease has its own TTL on the
+  // manager and is the credential the shell persists).
+  const releaseStreamOnly = (): void => {
+    if (closed) return;
+    closed = true;
+    if (heartbeat !== null) clearInterval(heartbeat);
+    unregister?.();
+    deps.idle.release(`stream:${streamId}`);
+  };
+
+  // Full teardown: shared stream cleanup plus lease release. Runs when
+  // the lease is gone (expired or explicitly released).
+  const releaseLease = (): void => {
+    if (closed) return;
+    releaseStreamOnly();
+    deps.leases.release(leaseId);
+  };
+
+  const readable = new ReadableStream({
+    start(controller) {
+      const send = (event: unknown): void => {
+        try {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+        } catch {
+          // controller already closed (lease expired mid-send)
+        }
+      };
+      send({ type: "stream:open", streamId, artifactId, at: new Date().toISOString() });
+
+      // Write-path fan-out: committed revisions for THIS artifact land
+      // on this stream. Unregistered on lease expiry / disconnect.
+      unregister = deps.broadcaster.register(artifactId, (event) => send(event));
+
+      // Bind stream lifetime to lease lifetime. When the per-lease
+      // timer fires, we close the stream + release the idle reason.
+      deps.leases.onExpireNotify(leaseId, () => {
+        try {
+          controller.enqueue(
+            encoder.encode(
+              `data: ${JSON.stringify({
+                type: "stream:close",
+                streamId,
+                at: new Date().toISOString(),
+                reason: "lease_expired",
+              })}\n\n`,
+            ),
+          );
+        } catch {
+          // already closed
+        }
+        try {
+          controller.close();
+        } catch {
+          // already closed
+        }
+        releaseLease();
+      });
+
+      heartbeat = setInterval(() => {
+        // Re-check liveness — if the lease was removed by the expiry
+        // hook or an explicit release in the meantime, the controller
+        // is closed and the teardown already ran, so `closed` is set
+        // and we return without re-enqueueing.
+        if (closed) return;
+        try {
+          controller.enqueue(encoder.encode(`: heartbeat\n\n`));
+          if (!deps.leases.renew(leaseId)) {
+            // Lease is gone (released or expired). The notification path
+            // normally fires first, but converge on the shared cleanup so
+            // the interval and idle reason are always released.
+            releaseStreamOnly();
+            return;
+          }
+          send({ type: "stream:heartbeat", streamId, at: new Date().toISOString() });
+        } catch {
+          // stream torn down between check and send
+          releaseStreamOnly();
+        }
+      }, deps.heartbeatIntervalMs ?? STREAM_HEARTBEAT_INTERVAL_MS);
+      if (typeof heartbeat.unref === "function") heartbeat.unref();
+    },
+    cancel() {
+      // Client-initiated disconnect: tear down the stream and the
+      // idle reason, but leave the lease alone. The lease has its own
+      // per-lease TTL on the lease manager and is the authoritative
+      // credential the shell persists to sessionStorage. Releasing it
+      // here would defeat the F5 refresh path: the cancel fires when
+      // the navigation tears down the SSE stream, the new shell would
+      // retry the lease it just released, and the typed "session
+      // expired" state would mask a perfectly valid credential.
+      // `stream:${streamId}` is the per-stream idle reason; the lease
+      // remains governed by GalleryLeaseManager.schedule.
+      releaseStreamOnly();
+    },
+  });
+
+  return new Response(readable, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream",
+      "cache-control": NO_STORE,
+      "x-accel-buffering": "no",
+    },
+  });
+}

package/src/service/verdict-enrichment.ts

@@ -0,0 +1,45 @@
+import type {
+  InsecureLevel,
+  InsecureMarker,
+  TsxExecutionMode,
+} from "../shared/contracts/validation";
+
+export const defaultInsecureReason = (level: InsecureLevel): string =>
+  `manual insecure level ${level}`;
+
+export function insecureMarker(
+  level: InsecureLevel,
+  reason: string | null | undefined,
+): InsecureMarker | undefined {
+  if (level === 0) return undefined;
+  return { level, reason: reason ?? defaultInsecureReason(level) };
+}
+
+/**
+ * Bind the verdict to its (artifactId, revisionSha) pair and attach
+ * the insecure marker and the TSX execution marker when set.
+ * The execution marker is conditional spread so non-TSX verdicts
+ * stay BYTE-IDENTICAL to the pre-arc wire shape — the field is
+ * absent, not null. The Tier 0/1 result schema extends VerdictSchema,
+ * so the marker flows through TSX publish and read-back uniformly.
+ */
+export function enrichVerdict<T extends object>(
+  result: T,
+  artifactId: string,
+  revisionSha: string,
+  insecure?: InsecureMarker,
+  execution?: TsxExecutionMode,
+): T & {
+  artifactId: string;
+  revisionSha: string;
+  insecure?: InsecureMarker;
+  execution?: TsxExecutionMode;
+} {
+  return {
+    ...result,
+    ...(insecure !== undefined ? { insecure } : {}),
+    ...(execution !== undefined ? { execution } : {}),
+    artifactId,
+    revisionSha,
+  };
+}