@legionworks/facet 1.9.0

package/src/shared/contracts/envelope.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+
+/**
+ * The single protocol version this build speaks. Any envelope carrying a
+ * different value is rejected with `unknown_schema_version` so future
+ * schema bumps can fail loud rather than silently mis-parse.
+ */
+export const FACET_SCHEMA_VERSION = "facet.v1" as const;
+export type FacetSchemaVersion = typeof FACET_SCHEMA_VERSION;
+
+export const SchemaVersionSchema = z.literal(FACET_SCHEMA_VERSION);
+
+const PrimitiveDetailsSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+/**
+ * Wire body of every error response. `details` only accepts JSON-safe
+ * primitives so the envelope round-trips through `JSON.parse(JSON.stringify(...))`
+ * without losing type information — and without leaking functions, errors,
+ * or undefined into the wire format.
+ */
+export const FacetErrorBodySchema = z.object({
+  code: z.string().min(1),
+  message: z.string().min(1),
+  retryable: z.boolean(),
+  details: z.record(z.string(), PrimitiveDetailsSchema).optional(),
+});
+export type FacetErrorBody = z.infer<typeof FacetErrorBodySchema>;
+
+/**
+ * Both arms use `.strict()` so an envelope can carry ONLY the fields
+ * its discriminator allows. `ok:true` may not smuggle an `error` key
+ * (and vice versa), and no arm accepts extra top-level keys. Without
+ * this, a forged envelope with `ok:true` plus an `error` body would
+ * parse cleanly and confuse every downstream consumer that branches on
+ * the discriminator.
+ */
+const EnvelopeOkSchema = z
+  .object({
+    schemaVersion: SchemaVersionSchema,
+    requestId: z.string().min(1),
+    ok: z.literal(true),
+    data: z.unknown(),
+  })
+  .strict();
+
+const EnvelopeErrSchema = z
+  .object({
+    schemaVersion: SchemaVersionSchema,
+    requestId: z.string().min(1),
+    ok: z.literal(false),
+    error: FacetErrorBodySchema,
+  })
+  .strict();
+
+export const FacetEnvelopeSchema = z.discriminatedUnion("ok", [
+  EnvelopeOkSchema,
+  EnvelopeErrSchema,
+]);
+
+export type FacetEnvelope<T> =
+  | {
+      schemaVersion: FacetSchemaVersion;
+      requestId: string;
+      ok: true;
+      data: T;
+    }
+  | {
+      schemaVersion: FacetSchemaVersion;
+      requestId: string;
+      ok: false;
+      error: FacetErrorBody;
+    };
+
+/** Build a typed ok envelope carrying `data`. */
+export function okEnvelope<T>(requestId: string, data: T): FacetEnvelope<T> {
+  return {
+    schemaVersion: FACET_SCHEMA_VERSION,
+    requestId,
+    ok: true,
+    data,
+  };
+}
+
+/** Build a typed error envelope carrying `error`. */
+export function errEnvelope(requestId: string, error: FacetErrorBody): FacetEnvelope<never> {
+  return {
+    schemaVersion: FACET_SCHEMA_VERSION,
+    requestId,
+    ok: false,
+    error,
+  };
+}
+
+export type ParseEnvelopeResult =
+  | { ok: true; envelope: FacetEnvelope<unknown> }
+  | { ok: false; body: FacetErrorBody };
+
+/**
+ * Parse an arbitrary value as a Facet envelope. Returns a typed
+ * `unknown_schema_version` body when the value carries a future schema
+ * version, a typed `invalid_envelope` body for every other parse failure,
+ * and a typed `ok: true` result for well-formed inputs.
+ */
+export function parseEnvelope(input: unknown): ParseEnvelopeResult {
+  if (typeof input !== "object" || input === null) {
+    return {
+      ok: false,
+      body: {
+        code: "invalid_envelope",
+        message: "Envelope must be a JSON object",
+        retryable: false,
+      },
+    };
+  }
+  const candidate = input as Record<string, unknown>;
+  if (candidate.schemaVersion !== FACET_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      body: {
+        code: "unknown_schema_version",
+        message: `Unknown schema version: ${String(candidate.schemaVersion)}`,
+        retryable: false,
+        details: { received: String(candidate.schemaVersion ?? "undefined") },
+      },
+    };
+  }
+  const parsed = FacetEnvelopeSchema.safeParse(input);
+  if (parsed.success) {
+    return { ok: true, envelope: parsed.data as FacetEnvelope<unknown> };
+  }
+  return {
+    ok: false,
+    body: {
+      code: "invalid_envelope",
+      message: parsed.error.issues[0]?.message ?? "Envelope failed validation",
+      retryable: false,
+      details: { issueCount: parsed.error.issues.length },
+    },
+  };
+}

package/src/shared/contracts/events.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+import { ArtifactTypeSchema } from "./artifact";
+
+/**
+ * Stream lifecycle events emitted on the SSE channel. The wire is
+ * `type`-discriminated so clients can pattern-match without parsing a
+ * string union.
+ */
+export const StreamEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("stream:open"),
+    streamId: z.string().min(1),
+    artifactId: z.string().min(1).nullable(),
+    at: z.string().datetime({ offset: true }),
+  }),
+  z.object({
+    type: z.literal("stream:heartbeat"),
+    streamId: z.string().min(1),
+    at: z.string().datetime({ offset: true }),
+  }),
+  z.object({
+    type: z.literal("stream:close"),
+    streamId: z.string().min(1),
+    at: z.string().datetime({ offset: true }),
+    reason: z.string().min(1),
+  }),
+]);
+/**
+ * Emitted whenever a revision commits to the store. The sha is the
+ * authoritative identifier clients use to address the revision; the
+ * number is the human-readable position in the artifact's history.
+ */
+export const RevisionCommittedEventSchema = z.object({
+  type: z.literal("revision:committed"),
+  artifactId: z.string().min(1),
+  revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+  revisionNumber: z.number().int().positive(),
+  artifactType: ArtifactTypeSchema,
+  at: z.string().datetime({ offset: true }),
+});

package/src/shared/contracts/observed-counts.ts

@@ -0,0 +1,19 @@
+export const OBSERVED_COUNT_KEYS = [
+  "rendererRootSvgCount",
+  "graphCount",
+  "mermaidNodeCount",
+  "visibleSvgCount",
+  "opaqueRegionCount",
+  "externalImageCount",
+] as const;
+export type ObservedCountKey = (typeof OBSERVED_COUNT_KEYS)[number];
+
+export const HTML_OBSERVED_COUNT_KEYS = [
+  "rendererRootCount",
+  "headingCount",
+  "tableCount",
+  "listCount",
+  "imageCount",
+  "canvasCount",
+  "externalImageCount",
+] as const;

package/src/shared/contracts/renderers.ts

@@ -0,0 +1,6 @@
+export const RENDERERS = ["svg", "canvas"] as const;
+export type Renderer = (typeof RENDERERS)[number];
+
+export function isRenderer(value: unknown): value is Renderer {
+  return typeof value === "string" && (RENDERERS as readonly string[]).includes(value);
+}

package/src/shared/contracts/validation.ts

@@ -0,0 +1,296 @@
+import { z } from "zod";
+import { EvidenceImageFormatSchema } from "../evidence-image";
+
+import { ArtifactTypeSchema, RendererSchema } from "./artifact";
+import { HTML_OBSERVED_COUNT_KEYS, OBSERVED_COUNT_KEYS } from "./observed-counts";
+import { TSX_EXECUTION_MODES } from "../tsx/execution";
+
+/**
+ * Validation tier. Tier 0 is the always-on parser worker (no browser);
+ * Tier 1 is the explicit, ephemeral, headless-shell-backed verifier.
+ * Tier 2 (the user's browser) is display-only and never produces a
+ * `RenderRun`.
+ */
+export const ValidationTierSchema = z.union([z.literal(0), z.literal(1)]);
+
+/**
+ * Closed set of render status codes the verifier can produce. The
+ * `partial:` prefix is reserved for results that completed some checks
+ * but could not finalize the layout pass (e.g., due to viewport
+ * unavailability); `tampered` is reserved for hostile pages that
+ * attempted to forge the verdict.
+ *
+ * `partial:unstable` (D11) is the TSX interactive mode verdict for a
+ * structure that legitimately changed between the render barrier and
+ * the stability window. It is deliberately NOT `tampered` — a
+ * legitimately animated or async-loading component also changes
+ * structure between observations, and branding it a forgery would
+ * manufacture the exact false-verdict class this project has spent
+ * three arcs eliminating. `tampered` stays reserved for channel
+ * divergence — the page contradicting protocol authority.
+ */
+export const RenderStatusSchema = z.enum([
+  "ok",
+  "error",
+  "partial:layout_unverified",
+  "partial:opaque_content",
+  "partial:external_resources",
+  "partial:unstable",
+  "tampered",
+  "timeout",
+  "shim_only",
+  "probe_only",
+  "insecure:unvalidated",
+]);
+export type RenderStatus = z.infer<typeof RenderStatusSchema>;
+
+/**
+ * TSX execution mode marker. Carried on TSX static and
+ * interactive verdicts; ABSENT for every other artifact type. The
+ * shape mirrors the existing top-level marker precedents
+ * (`insecure`, `screenshotError`) — a discriminated literal, not a
+ * nullable object.
+ */
+export const TsxExecutionModeSchema = z.enum(TSX_EXECUTION_MODES);
+export type TsxExecutionMode = z.infer<typeof TsxExecutionModeSchema>;
+
+/** Discriminative errors the verifier chooses to surface beyond the count. */
+export const DiscriminativeErrorSchema = z.object({
+  code: z.string().min(1),
+  message: z.string().min(1),
+  location: z.string().optional(),
+});
+export type DiscriminativeError = z.infer<typeof DiscriminativeErrorSchema>;
+
+/**
+ * Evidence capture failed after the render verdict was derived. This stays
+ * outside `observed.discriminativeErrors`, which the verdict ladder consumes.
+ */
+export const ScreenshotErrorSchema = z.object({
+  code: z.literal("screenshot_unavailable"),
+  message: z.string().min(1),
+});
+export type ScreenshotError = z.infer<typeof ScreenshotErrorSchema>;
+
+export const InsecureLevelSchema = z.union([
+  z.literal(0),
+  z.literal(1),
+  z.literal(2),
+  z.literal(3),
+]);
+export type InsecureLevel = z.infer<typeof InsecureLevelSchema>;
+
+export const InsecureMarkerSchema = z.object({
+  level: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+  reason: z.string().min(1),
+});
+export type InsecureMarker = z.infer<typeof InsecureMarkerSchema>;
+
+const HtmlObservedCountShape = Object.fromEntries(
+  HTML_OBSERVED_COUNT_KEYS.map((key) => [key, z.number().int().nonnegative()]),
+) as Record<(typeof HTML_OBSERVED_COUNT_KEYS)[number], z.ZodNumber>;
+
+export const HtmlStructureCountsSchema = z.object(HtmlObservedCountShape);
+export type HtmlStructureCounts = z.infer<typeof HtmlStructureCountsSchema>;
+
+/**
+ * Lexical counters computed from the source bytes WITHOUT parsing or
+ * rendering. The verifier compares these against its own observations
+ * so an attacker cannot make a forged page's `svgCount` agree with
+ * the verifier's observation without also matching the lexical
+ * expectation.
+ *
+ * `externalImageCount` is the TYPE-AGNOSTIC count of references to
+ * resources the no-egress validation run cannot observe (HTTPS
+ * images). It applies to every artifact type that may reference an
+ * external resource (markdown native image syntax, raw HTML, html),
+ * so the verdict reads it from the top level rather than from the
+ * HTML-only `html` subfield.
+ */
+export const LexicalCountersSchema = z.object({
+  rendererRootSvgCount: z.number().int().nonnegative(),
+  // `null` is an explicit no-expectation marker for Mermaid diagram types
+  // whose renderer-owned `g.node` output lacks a maintained lexical grammar.
+  mermaidNodeCount: z.number().int().nonnegative().nullable(),
+  visibleSvgCount: z.number().int().nonnegative(),
+  opaqueRegionCount: z.number().int().nonnegative(),
+  externalImageCount: z.number().int().nonnegative(),
+  html: HtmlStructureCountsSchema.optional(),
+});
+export type LexicalCounters = z.infer<typeof LexicalCountersSchema>;
+
+/**
+ * The ONE canonical verdict-observed shape. Every read-back result and
+ * every Tier 0/1 result derives from this. The optional fields
+ * (`viewBoxes`, `discriminativeErrors`) are filled by Tier 1 when the
+ * layout pass succeeds.
+ *
+ * `graphCount` is included alongside `mermaidNodeCount` for parity with
+ * the acceptance-gate verdict contract — the acceptance tests assert
+ * `observed.graphCount` for nested-SVG forgery probes, so a verifier
+ * that does not surface it would fail those gates regardless of the
+ * status.
+ */
+const ObservedCountShape = Object.fromEntries(
+  OBSERVED_COUNT_KEYS.map((key) => [key, z.number().int().nonnegative()]),
+) as Record<(typeof OBSERVED_COUNT_KEYS)[number], z.ZodNumber>;
+
+export const VerdictObservedSchema = z.object({
+  ...ObservedCountShape,
+  html: HtmlStructureCountsSchema.optional(),
+  viewBoxes: z.array(z.string()).optional(),
+  errorCount: z.number().int().nonnegative(),
+  discriminativeErrors: z.array(DiscriminativeErrorSchema).optional(),
+});
+export type VerdictObserved = z.infer<typeof VerdictObservedSchema>;
+
+/**
+ * Canonical verdict: every read-back response, every Tier 0/1 result,
+ * and the acceptance-gate verdict are all structurally compatible with
+ * this shape. Tier results extend it (with `expected` for the
+ * expected-vs-observed comparison); read-back uses it directly.
+ *
+ * `execution` is the top-level marker for TSX static and
+ * interactive verdicts. It is ABSENT — not null — for every other
+ * artifact type, so the wire form for non-TSX stays byte-identical
+ * to the pre-arc shape. The runtime read-back reconstructs this field
+ * from the revision's stored execution mode rather than carrying it
+ * on the observed counters.
+ */
+export const VerdictSchema = z.object({
+  status: RenderStatusSchema,
+  tier: ValidationTierSchema,
+  artifactId: z.string().min(1),
+  revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+  observed: VerdictObservedSchema,
+  screenshotError: ScreenshotErrorSchema.optional(),
+  insecure: InsecureMarkerSchema.optional(),
+  execution: TsxExecutionModeSchema.optional(),
+});
+export type Verdict = z.infer<typeof VerdictSchema>;
+
+/** Tier 0 input: pure-parse verifier, no browser, no egress. */
+export const Tier0InputSchema = z.object({
+  revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+  artifactType: ArtifactTypeSchema,
+  renderer: RendererSchema,
+  source: z.instanceof(Uint8Array<ArrayBuffer>),
+  lexical: LexicalCountersSchema,
+  execution: TsxExecutionModeSchema.optional(),
+});
+export type Tier0Input = z.infer<typeof Tier0InputSchema>;
+
+/**
+ * The parent-side Tier 0 runner contract. The default implementation
+ * lives in `src/validation/tier0/runner.ts` (out-of-process Bun
+ * subprocess under `unshare --map-current-user --net`). The service
+ * imports THIS TYPE only — the runner implementation is constructed
+ * by callers (`src/cli/`, tests) and injected into the dispatcher so
+ * `src/service/**` stays byte-dumb and the boundary checker remains
+ * clean.
+ */
+export type Tier0Runner = ((input: Tier0Input) => Promise<Tier0WorkerResult>) & {
+  readonly close?: () => void;
+};
+export type Tier0RunnerFactory = (level: InsecureLevel) => Tier0Runner;
+
+export interface IsolationProbeResult {
+  readonly available: boolean;
+  readonly reason: string | null;
+}
+
+export type Tier0IsolationProbe = () => IsolationProbeResult | Promise<IsolationProbeResult>;
+
+/** Tier 0 result: extends the canonical verdict with the expected counters. */
+export const Tier0ResultSchema = VerdictSchema.extend({
+  tier: z.literal(0),
+  expected: LexicalCountersSchema,
+});
+export type Tier0Result = z.infer<typeof Tier0ResultSchema>;
+
+export const CompiledArtifactSchema = z.object({
+  mediaType: z.enum(["text/html", "text/javascript"]),
+  bytesBase64: z.string(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export type CompiledArtifact = z.infer<typeof CompiledArtifactSchema>;
+
+/** Identity-blind worker stdout; the parent adds artifactId before persistence. */
+export const Tier0WorkerResultSchema = Tier0ResultSchema.omit({ artifactId: true }).extend({
+  compiled: CompiledArtifactSchema.optional(),
+});
+export type Tier0WorkerResult = z.infer<typeof Tier0WorkerResultSchema>;
+
+/** Tier 1 input: headless-shell-backed verifier on top of Tier 0. */
+export const Tier1InputSchema = Tier0InputSchema.extend({
+  /**
+   * Bytes Tier 1 renders. This is the published source for every type except
+   * static TSX, which supplies the retained compiled HTML derived from it.
+   */
+  source: z.instanceof(Uint8Array<ArrayBuffer>),
+  /** Pinned chrome-headless-shell version that must run this verification. */
+  launcherVersion: z.string().min(1),
+  /** Network namespace name the verifier must be confined to. */
+  networkNamespace: z.string().min(1),
+  /**
+   * Per-run evidence directory (mode 0700). The runner writes the
+   * screenshot, the bounded console summary, and the protocol
+   * observation JSON under this directory. When omitted, the runner
+   * falls back to `computeFacetPaths().evidence` so production
+   * callers never have to specify it.
+   */
+  evidenceDir: z.string().optional(),
+});
+export type Tier1Input = z.infer<typeof Tier1InputSchema>;
+
+/**
+ * The parent-side Tier 1 runner contract. The default implementation
+ * lives in `src/validation/tier1/runner.ts` (an ephemeral netns'd
+ * `chrome-headless-shell` driven via CDP pipe). Like `Tier0Runner`,
+ * only THIS TYPE is imported by the service — the implementation is
+ * constructed by callers (`src/cli/`, tests) and injected so
+ * `src/service/**` stays byte-dumb.
+ */
+export type Tier1Runner = (input: Tier1Input) => Promise<Tier1Result>;
+export type Tier1RunnerFactory = (level: InsecureLevel) => Tier1Runner;
+export type Tier1AvailabilityProbe = () => IsolationProbeResult | Promise<IsolationProbeResult>;
+
+/**
+ * Tier 1 result: extends Tier 0 with screenshot/console paths.
+ *
+ * Partial verdicts require screenshot evidence or a typed explanation for
+ * why capture failed after the render verdict was already derived.
+ */
+export const Tier1ResultSchema = Tier0ResultSchema.extend({
+  tier: z.literal(1),
+  screenshotPath: z.string().nullable(),
+  screenshotFormat: EvidenceImageFormatSchema.optional(),
+  consolePath: z.string().nullable(),
+  screenshotError: ScreenshotErrorSchema.optional(),
+}).refine(
+  (value) =>
+    !value.status.startsWith("partial:") ||
+    value.screenshotPath !== null ||
+    value.screenshotError !== undefined,
+  {
+    message: "partial verdict requires screenshot evidence or a screenshot-unavailable marker",
+    path: ["screenshotPath"],
+  },
+);
+export type Tier1Result = z.infer<typeof Tier1ResultSchema>;
+
+/**
+ * The renderer-OWNED root count the verifier expects from one Tier 1
+ * run. Counts ONE top-level renderer-owned root per expected
+ * (revision, fence) pair — NOT every descendant `<svg>`. A nested
+ * `<svg id="forged">` inside a Mermaid label does NOT inflate this
+ * count; that probe is the gate-forgery acceptance contract.
+ */
+export const ProtocolObservationSchema = z.object({
+  ...ObservedCountShape,
+  html: HtmlStructureCountsSchema.optional(),
+  viewBoxes: z.array(z.string()),
+  errorCount: z.number().int().nonnegative(),
+  discriminativeErrors: z.array(DiscriminativeErrorSchema),
+});
+export type ProtocolObservation = z.infer<typeof ProtocolObservationSchema>;

package/src/shared/errors/facet-error.ts

@@ -0,0 +1,127 @@
+import type { FacetErrorBody } from "../contracts/envelope";
+
+/**
+ * Closed set of error codes the service can return on the wire. The store
+ * layer mirrors the same names for parity (database_corrupt, etc.); the
+ * protocol layer adds reserved/implemented-style codes that exist purely
+ * in the envelope path.
+ */
+export const FacetErrorCodes = {
+  // Store-derived codes (mirrored from src/service/store/database.ts).
+  database_corrupt: true,
+  database_busy: true,
+  disk_full: true,
+  duplicate_revision: true,
+  foreign_key: true,
+  immutable_revision: true,
+  migration_failed: true,
+  invalid_artifact_type: true,
+  constraint: true,
+  // Protocol-derived codes.
+  reserved_not_implemented: true,
+  unsupported_reserved_type: true,
+  unknown_schema_version: true,
+  payload_too_large: true,
+  invalid_envelope: true,
+  invalid_request: true,
+  artifact_not_found: true,
+  revision_not_found: true,
+  template_not_found: true,
+  evidence_unavailable: true,
+  output_unwritable: true,
+  revision_capacity_pinned: true,
+  // Tier 0 worker-level failures. These surface when the parent cannot
+  // even obtain a Tier0Result (worker died, bad stdout, wall-clock cap,
+  // output cap, unshare/unshare wrapper unavailable). Parser-level
+  // failures (mermaid syntax error, hostile svg, etc.) are recorded as
+  // a Tier0Result with status="error" and do NOT throw.
+  tier0_timeout: true,
+  tier0_protocol_error: true,
+  tier0_worker_died: true,
+  tier0_output_cap: true,
+  tier0_unavailable: true,
+  tsx_ast_denied: true,
+  tsx_compile_error: true,
+  tsx_compile_output_cap: true,
+  // Tier 1 verifier-level failures. Mirrors the Tier 0 worker set:
+  // the parent cannot obtain a Tier1Result at all (the netns wrapper
+  // is missing, the pinned shell binary is missing, the CDP pipe
+  // died, the probe timed out, or the verifier could not parse the
+  // browser protocol payload). Verdict-level divergences — page-shim
+  // lying, missing frame, missing render-complete — surface as
+  // `tampered` / `shim_only` / `timeout` / `probe_only` inside a
+  // Tier1Result, NOT as a throw.
+  tier1_unavailable: true,
+  tier1_browser_died: true,
+  tier1_protocol_error: true,
+  tier1_timeout: true,
+  tier1_launcher_missing: true,
+  // Generic catch-alls.
+  internal: true,
+} as const;
+
+export type FacetErrorCode = keyof typeof FacetErrorCodes;
+
+export type FacetErrorDetails = Record<string, string | number | boolean | null>;
+
+export interface FacetErrorOptions {
+  readonly retryable?: boolean;
+  readonly details?: FacetErrorDetails;
+  readonly cause?: unknown;
+}
+
+/**
+ * Typed error class for everything that flows out through the protocol
+ * envelope. Carries the wire-friendly `code`, the `retryable` flag, and
+ * primitive-only `details` so a `FacetErrorBody` derived from this object
+ * is always JSON-round-trippable.
+ *
+ * `FacetStoreError` extends this class — see `./store-error.ts`. The
+ * `from()` bridge relies on that inheritance so a thrown store fault
+ * surfaces on the wire with its typed code instead of collapsing to
+ * `invalid_envelope`.
+ */
+export class FacetError extends Error {
+  override readonly name: string = "FacetError";
+
+  constructor(
+    readonly code: FacetErrorCode,
+    message: string,
+    readonly options: FacetErrorOptions = {},
+  ) {
+    super(message, { cause: options.cause });
+  }
+
+  get retryable(): boolean {
+    return this.options.retryable ?? false;
+  }
+
+  get details(): FacetErrorDetails | undefined {
+    return this.options.details;
+  }
+
+  toBody(): FacetErrorBody {
+    const body: FacetErrorBody = {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+    };
+    if (this.options.details !== undefined) {
+      return { ...body, details: this.options.details };
+    }
+    return body;
+  }
+
+  /**
+   * Coerce any thrown value into a FacetError. Pre-existing FacetErrors pass
+   * through; everything else is wrapped as `invalid_envelope` (the safest
+   * generic code for an untyped boundary failure).
+   */
+  static from(error: unknown): FacetError {
+    if (error instanceof FacetError) return error;
+    if (error instanceof Error) {
+      return new FacetError("invalid_envelope", error.message, { cause: error });
+    }
+    return new FacetError("invalid_envelope", String(error));
+  }
+}