@legionworks/facet 1.9.0

package/src/validation/tier1/verdict.ts

@@ -0,0 +1,246 @@
+/**
+ * Tier 1 verdict taxonomy.
+ *
+ * `deriveVerdict` is the SOLE component that decides a `RenderStatus`
+ * from the raw probe surface. It is pure: no IO, no time, no random
+ * ids. Every other layer depends on this contract, so the decision
+ * tree is exhaustively unit-tested in `tests/unit/verdict.test.ts`.
+ *
+ * Trust ordering:
+ *   protocol observation (CDP DOMSnapshot / DOM.getDocument)
+ *   > isolated-world observation (Runtime.evaluate)
+ *   > page-shim self-report (UNTRUSTED — page JavaScript can lie)
+ *
+ * A divergence between any pair up-ranks to the higher-authority
+ * channel's view; when shim contradicts protocol, status is `tampered`.
+ * Lifecycle failures (`renderComplete: false`) win over content
+ * comparisons — a verifier that never observed the render-complete
+ * barrier cannot honestly report `ok`, so the answer is `timeout`.
+ *
+ * Layout observability is its own axis: a renderer that produced
+ * SVGs with zeroed viewBoxes (visible bounds of 0×0) cannot have its
+ * layout verified. That is `partial:layout_unverified`, NOT `ok`,
+ * even when the counts match the lexical expectation.
+ */
+
+import type {
+  LexicalCounters,
+  ProtocolObservation,
+  RenderStatus,
+} from "../../shared/contracts/validation";
+import {
+  HTML_OBSERVED_COUNT_KEYS,
+  OBSERVED_COUNT_KEYS,
+} from "../../shared/contracts/observed-counts";
+
+// Re-export the protocol observation shape so the verdict tests can
+// typecheck without re-importing the validation contract.
+export type { ProtocolObservation };
+
+/**
+ * The page shim's self-reported counts. UNTRUSTED — page JavaScript
+ * can monkey-patch `document.querySelectorAll` and report whatever it
+ * likes. The verifier treats shim counts as advisory only.
+ */
+export type PageShim = Pick<
+  ProtocolObservation,
+  (typeof COUNT_COMPARISON_KEYS)[number] | "html" | "errorCount"
+>;
+
+export type CountsLike = Pick<
+  ProtocolObservation,
+  (typeof COUNT_COMPARISON_KEYS)[number] | "html" | "errorCount"
+>;
+
+const COUNT_COMPARISON_KEYS = OBSERVED_COUNT_KEYS;
+
+/**
+ * Which optional probe channels produced a usable observation. The
+ * protocol channel is always populated (a missing protocol result is
+ * a system-level failure, not a verdict-level one); shim and isolated
+ * are best-effort and may legitimately be null.
+ */
+export interface ChannelSummary {
+  readonly shim: boolean;
+  readonly isolated: boolean;
+}
+
+/**
+ * Lifecycle events observed before / during the verifier barrier.
+ * `bootReady` is the bundle's own boot handshake (i.e. the bundle
+ * emitted "boot-ready" on its control port). `renderComplete` is
+ * the renderer's "render-complete" barrier — without it, the verdict
+ * cannot trust the renderer finished settling.
+ *
+ * `structureChanged` (D11) is the result of the second observation
+ * Tier 1 takes for interactive TSX runs: the structure observed at
+ * the render barrier compared against the structure observed after
+ * a bounded stability window. `true` means a structure mismatch was
+ * detected, which earns `partial:unstable`. Non-interactive TSX runs
+ * and every other artifact type omit the field; the verdict treats
+ * undefined as `false` so the legacy code path is unchanged.
+ */
+export interface LifecycleSummary {
+  readonly bootReady: boolean;
+  readonly renderComplete: boolean;
+  readonly structureChanged?: boolean;
+  /** A protocol or isolated-world authority channel diverged at either observation. */
+  readonly channelDivergence?: boolean;
+  /** Interactive TSX has no lexical HTML prediction and no trusted outer shim. */
+  readonly interactive?: boolean;
+}
+
+/**
+ * Compute the final `RenderStatus`. Order of precedence:
+ *
+ *   1. Lifecycle: `renderComplete === false` → `timeout`
+ *   2. Trust: shim disagrees with protocol → `tampered`
+ *   3. Trust: isolated disagrees with protocol → `tampered`
+ *   4. Channel availability: both shim AND isolated missing → `probe_only`
+ *   5. Channel availability: only shim missing → `probe_only`
+ *   6. Channel availability: only isolated missing → `shim_only`
+ *   7. Opaque content: expected > 0 but protocol observed 0 → `error`
+ *   8. Opaque content: protocol observed > 0 → `partial:opaque_content`
+ *   9. External resources: expected external images > 0 → `partial:external_resources`
+ *  10. Layout observability (non-HTML only): protocol visibleSvgCount === 0
+ *      AND every viewBox is zeroed → `partial:layout_unverified`. The
+ *      branch is gated on `expected.html === undefined` because HTML
+ *      artifacts carry no viewBox axis — they have no SVG layout to
+ *      verify against, so `partial:layout_unverified` is structurally
+ *      unreachable for HTML. A clean HTML artifact with zero
+ *      `visibleSvgCount` and zero `viewBoxes` returns `ok` when its
+ *      counts match.
+ *  11. Counts: protocol discriminativeErrors non-empty → `error`
+ *  12. Counts: protocol observed !== expected lexical → `error`
+ *  13. Otherwise → `ok`
+ *
+ * Tampered wins over partial: a forge attempt that hides layout
+ * observability (no viewBoxes) is still a forge attempt.
+ *
+ * D11 addition: `partial:unstable` slots between step 6 and step 7,
+ * i.e. AFTER the catastrophic statuses (timeout, tampered, channel
+ * availability) and the count-mismatch error, but BEFORE the
+ * single-snapshot partials (opaque_content, external_resources,
+ * layout_unverified). The reasoning: when structure is changing
+ * between the two observation snapshots, the verifier cannot
+ * honestly claim "this artifact has structure X" — every
+ * single-snapshot claim is moot. Unstable is a meta-claim about the
+ * page's runtime behavior that dominates the structural claims.
+ * Tampered stays above it because channel divergence (the page
+ * contradicting protocol authority) is the more catastrophic
+ * reading of the page's behavior.
+ */
+export function deriveVerdict(
+  expected: LexicalCounters,
+  protocolObservation: ProtocolObservation,
+  isolatedObservation: ProtocolObservation | null,
+  pageShim: PageShim | null,
+  lifecycle: LifecycleSummary,
+): RenderStatus {
+  if (!lifecycle.renderComplete) return "timeout";
+
+  if (
+    lifecycle.channelDivergence === true ||
+    protocolObservation.discriminativeErrors.some((error) => error.code === "protocol_divergence")
+  ) {
+    return "tampered";
+  }
+  if (!lifecycle.interactive && pageShim !== null && countsDiffer(pageShim, protocolObservation)) {
+    return "tampered";
+  }
+  if (isolatedObservation !== null && countsDiffer(isolatedObservation, protocolObservation)) {
+    return "tampered";
+  }
+
+  const shimAvailable = pageShim !== null;
+  const isolatedAvailable = isolatedObservation !== null;
+  if (lifecycle.interactive) {
+    if (!isolatedAvailable) return "probe_only";
+  } else {
+    if (!shimAvailable && !isolatedAvailable) return "probe_only";
+    if (!shimAvailable) return "probe_only";
+    if (!isolatedAvailable) return "shim_only";
+  }
+
+  if (protocolObservation.discriminativeErrors.length > 0) return "error";
+  if (!lifecycle.interactive && !matchesExpected(expected, protocolObservation)) return "error";
+  // D11: structure changed between the barrier and the stability
+  // window. This is the only path that does not also depend on a
+  // single observation — it depends on TWO observations, so it
+  // dominates the single-snapshot partial statuses below.
+  if (lifecycle.structureChanged === true) return "partial:unstable";
+  if (expected.opaqueRegionCount > 0 && protocolObservation.opaqueRegionCount === 0) {
+    return "error";
+  }
+  if (protocolObservation.opaqueRegionCount > 0) return "partial:opaque_content";
+  // `externalImageCount` is the type-agnostic counter — markdown surfaces
+  // it from native `![](https://…)` token walks, HTML surfaces it from
+  // image elements, every other type carries 0 because their Tier 0
+  // policies already reject external references. Reading it at the top
+  // level keeps the verdict from depending on the HTML-shaped subfield.
+  if (protocolObservation.externalImageCount > 0) {
+    return "partial:external_resources";
+  }
+  if (
+    !lifecycle.interactive &&
+    expected.html === undefined &&
+    !layoutObservable(protocolObservation)
+  ) {
+    return "partial:layout_unverified";
+  }
+  return "ok";
+}
+
+/** A renderer-owned root whose visible bounds are real, not degenerate. */
+function layoutObservable(protocol: ProtocolObservation): boolean {
+  if (protocol.visibleSvgCount > 0) return true;
+  if (protocol.viewBoxes.length === 0) return false;
+  return protocol.viewBoxes.some((vb) => !isDegenerateViewBox(vb));
+}
+
+function isDegenerateViewBox(viewBox: string): boolean {
+  const parts = viewBox
+    .trim()
+    .split(/[\s,]+/)
+    .map((segment) => Number.parseFloat(segment));
+  if (parts.length !== 4) return true;
+  const [, , width, height] = parts as [number, number, number, number];
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return true;
+  return width <= 0 || height <= 0;
+}
+
+// The top-level external-image count is compared with the other protocol
+// counts, preserving the existing single comparison for this duplicated value.
+const HTML_COUNT_KEYS = HTML_OBSERVED_COUNT_KEYS.filter((key) => key !== "externalImageCount");
+
+function htmlCountsDiffer(
+  left: ProtocolObservation["html"],
+  right: ProtocolObservation["html"],
+): boolean {
+  if (left === undefined || right === undefined) return left !== right;
+  return HTML_COUNT_KEYS.some((key) => left[key] !== right[key]);
+}
+
+export function countsDiffer(left: CountsLike, right: CountsLike): boolean {
+  return (
+    COUNT_COMPARISON_KEYS.some((key) => left[key] !== right[key]) ||
+    left.errorCount !== right.errorCount ||
+    htmlCountsDiffer(left.html, right.html)
+  );
+}
+
+function matchesExpected(expected: LexicalCounters, protocol: ProtocolObservation): boolean {
+  if (expected.rendererRootSvgCount !== protocol.rendererRootSvgCount) return false;
+  if (expected.mermaidNodeCount !== null && expected.mermaidNodeCount !== protocol.mermaidNodeCount)
+    return false;
+  if (expected.html !== undefined && htmlCountsDiffer(expected.html, protocol.html)) return false;
+  // opaqueRegionCount is not compared here: expected > 0 / observed 0 returns
+  // error above, observed > 0 returns partial:opaque_content above, and 0 / 0
+  // is the only reachable ordinary path.
+  // visibleSvgCount is a protocol-only observation; the lexical
+  // counter for markdown/mermaid sources is 0 (the dispatcher does
+  // not count it). The verdict cannot punish the renderer for
+  // surfacing a layout-observable SVG when the lexical expectation
+  // explicitly leaves the field unset.
+  return true;
+}

package/src/validation/tier1/webp.ts

@@ -0,0 +1,69 @@
+import sharp from "sharp";
+
+export interface AnimatedWebpOptions {
+  readonly delayMs: number;
+  readonly quality: number;
+}
+
+export interface AnimatedWebpCapOptions extends Omit<AnimatedWebpOptions, "quality"> {
+  readonly qualities: readonly number[];
+  readonly capBytes: number;
+}
+
+export async function encodeAnimatedWebp(
+  frames: readonly Buffer[],
+  options: AnimatedWebpOptions,
+): Promise<Buffer> {
+  if (frames.length === 0) throw new Error("animated WebP requires at least one frame");
+  const metadata = await Promise.all(
+    frames.map((frame) => sharp(frame, { limitInputPixels: true }).metadata()),
+  );
+  const width = metadata[0]?.width;
+  const height = metadata[0]?.height;
+  if (
+    width === undefined ||
+    height === undefined ||
+    metadata.some((frame) => frame.width !== width || frame.height !== height)
+  )
+    throw new Error("animated WebP frames do not share dimensions");
+  const decoded = await Promise.all(
+    frames.map(async (frame) => {
+      const result = await sharp(frame, { limitInputPixels: true })
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+      return { bytes: result.data, info: result.info };
+    }),
+  );
+  if (decoded.some(({ info }) => info.channels !== 4))
+    throw new Error("animated WebP frames must decode as RGBA");
+  if (!Number.isSafeInteger(height * frames.length))
+    throw new Error("animated WebP frame stack is too tall");
+
+  return sharp(Buffer.concat(decoded.map(({ bytes }) => bytes)), {
+    raw: {
+      width,
+      height: height * frames.length,
+      channels: 4,
+      pageHeight: height,
+    },
+  })
+    .webp({
+      quality: options.quality,
+      effort: 4,
+      loop: 0,
+      delay: Array.from({ length: frames.length }, () => options.delayMs),
+    })
+    .toBuffer();
+}
+
+export async function encodeAnimatedWebpWithinCap(
+  frames: readonly Buffer[],
+  options: AnimatedWebpCapOptions,
+): Promise<Buffer | null> {
+  for (const quality of options.qualities) {
+    const bytes = await encodeAnimatedWebp(frames, { ...options, quality });
+    if (bytes.byteLength <= options.capBytes) return bytes;
+  }
+  return null;
+}

package/templates/README.md

@@ -0,0 +1,88 @@
+# Artifact templates
+
+Styled starting points for every type Facet renders. Each is self-contained:
+inline data, fragment-only references, no remote fonts — a source that
+reaches outside the sandbox fails closed by design.
+
+| file                          | type       | publish                                                                                                            |
+| ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
+| `status-report.md`            | `markdown` | `facet publish --artifact-id <id> --type markdown --file templates/status-report.md`                               |
+| `legion-flow.mmd`             | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/legion-flow.mmd`                                 |
+| `legion-sequence.mmd`         | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/legion-sequence.mmd`                             |
+| `metric-card.svg`             | `svg`      | `facet publish --artifact-id <id> --type svg --file templates/metric-card.svg`                                     |
+| `system-map.svg`              | `svg`      | `facet publish --artifact-id <id> --type svg --file templates/system-map.svg`                                      |
+| `timeseries.vl.json`          | `chart`    | `facet publish --artifact-id <id> --type chart --file templates/timeseries.vl.json`                                |
+| `bar-compare.vl.json`         | `chart`    | `facet publish --artifact-id <id> --type chart --file templates/bar-compare.vl.json`                               |
+| `decision-record.md`          | `markdown` | `facet publish --artifact-id <id> --type markdown --file templates/decision-record.md`                             |
+| `legion-boundaries.mmd`       | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/legion-boundaries.mmd`                           |
+| `legion-state.mmd`            | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/legion-state.mmd`                                |
+| `exemplar.md`                 | `markdown` | `facet publish --artifact-id <id> --type markdown --file templates/exemplar.md`                                    |
+| `html-status-report.html`     | `html`     | `facet publish --artifact-id <id> --type html --file templates/html-status-report.html`                            |
+| `html-release-ledger.html`    | `html`     | `facet publish --artifact-id <id> --type html --file templates/html-release-ledger.html`                           |
+| `tsx-status-report.tsx`       | `tsx`      | `facet publish --artifact-id <id> --type tsx --file templates/tsx-status-report.tsx`                               |
+| `tsx-interactive-counter.tsx` | `tsx`      | `facet publish --artifact-id <id> --type tsx --execution interactive --file templates/tsx-interactive-counter.tsx` |
+
+`exemplar.md` is the reference artifact for the current surface: one publish
+carrying tables, checklists, a JSON fence, and three themed diagrams — and
+its three mermaid fences ARE the lexical expectation the verifier checks.
+Publish it, read it back at `--tier visual`, open the gallery.
+
+## Complex tier
+
+Stress-tier counterparts exercise the wider supported surface. Each remains
+self-contained and publishes through the same revision-bound proof path.
+
+| file                      | type       | publish                                                                                                     |
+| ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `pipeline-audit.md`       | `markdown` | `facet publish --artifact-id <id> --type markdown --file templates/pipeline-audit.md`                       |
+| `service-topology.mmd`    | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/service-topology.mmd`                     |
+| `deployment-state.mmd`    | `mermaid`  | `facet publish --artifact-id <id> --type mermaid --file templates/deployment-state.mmd`                     |
+| `observability-map.svg`   | `svg`      | `facet publish --artifact-id <id> --type svg --file templates/observability-map.svg`                        |
+| `release-metrics.vl.json` | `chart`    | `facet publish --artifact-id <id> --type chart --file templates/release-metrics.vl.json`                    |
+| `fleet-dashboard.html`    | `html`     | `facet publish --artifact-id <id> --type html --file templates/fleet-dashboard.html`                        |
+| `incident-console.tsx`    | `tsx`      | `facet publish --artifact-id <id> --type tsx --execution interactive --file templates/incident-console.tsx` |
+| `capacity-report.tsx`     | `tsx`      | `facet publish --artifact-id <id> --type tsx --file templates/capacity-report.tsx`                          |
+
+Read back what you published, then promote a good revision into a service
+template (operator token required, provisioned out of band):
+
+```sh
+facet read-back --artifact-id <id> --revision-sha <sha256>
+facet promote --revision-id <id> --name status-report --promoted-by <operator>
+facet instantiate --name status-report --new-slug q3-report
+```
+
+## The Legion diagram theme
+
+Every mermaid template opens with the same `%%{init}%%` block — the house
+diagram theme. Reuse it verbatim in docs and new diagrams:
+
+- transparent background; the gallery stage provides the ground
+- node fill `#1e2030`, border `#3b4261`, text `#c8d3f5`, edges `#545c7e`
+- labels in the mono stack — diagram text is machine truth
+- hue is semantic only: green `#c3e88d` ok · amber `#ffc777` warn ·
+  red `#ff757f` fail · cyan `#86e1fc` accent, via `classDef`, sparingly
+
+## Constraints worth knowing
+
+- Charts: inline `data.values` only. A `data.url` spec is rejected before
+  render; zero-mark specs are an error, not an ok.
+- SVG: `use`, `image`, scripts, SMIL, and non-fragment URLs are stripped.
+  Keep paint refs as `url(#id)`. Cap 1 MiB, 16 roots.
+- Markdown: GFM. Raw HTML renders as visible text, not elements — keep
+  templates structural. Base typography inside the frame is currently
+  browser-default; a vendored artifact stylesheet is a tracked follow-up.
+- Mermaid: at most 64 fenced blocks and 10,000 nodes per artifact.
+- HTML: static, script-free. No `<script>`, no `on*=` handlers, no
+  `<style>` block, no `style=` attribute, no `<meta>` / `<link>` /
+  `<form>` / `<iframe>`. Styling comes from the shipped class
+  vocabulary (`docs/reference/html.md`); a class outside that set
+  renders the element unstyled with no error and no trust
+  downgrade. `<img src="https://…">` is permitted and downgrades
+  the verdict to `partial:external_resources`; `http:`,
+  protocol-relative, and `javascript:` URLs fail closed.
+- TSX: `static` is the default and enters the HTML pipeline. `interactive`
+  observes client-rendered structure twice; it has no SSR or hydration claim.
+  Use only vendored React imports and the HTML class vocabulary. Facet mounts
+  the default export, so templates must not self-mount. See
+  [TSX reference](../docs/reference/tsx.md).

package/templates/bar-compare.vl.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "description": "Facet bar template — read-backs by status. Inline data only.",
+  "background": "transparent",
+  "width": 640,
+  "height": 300,
+  "title": {
+    "text": "Read-backs by status · 30 days",
+    "anchor": "start",
+    "color": "#c8d3f5",
+    "font": "system-ui, sans-serif",
+    "fontSize": 15,
+    "fontWeight": 600,
+    "offset": 18
+  },
+  "data": {
+    "values": [
+      { "status": "ok", "count": 412 },
+      { "status": "partial", "count": 34 },
+      { "status": "error", "count": 26 },
+      { "status": "timeout", "count": 11 },
+      { "status": "shim_only", "count": 7 },
+      { "status": "probe_only", "count": 5 },
+      { "status": "tampered", "count": 3 }
+    ]
+  },
+  "mark": { "type": "bar", "cornerRadiusEnd": 3 },
+  "encoding": {
+    "x": {
+      "field": "status",
+      "type": "nominal",
+      "title": null,
+      "sort": ["ok", "partial", "error", "timeout", "shim_only", "probe_only", "tampered"],
+      "axis": { "labelAngle": 0 }
+    },
+    "y": { "field": "count", "type": "quantitative", "title": "count" },
+    "color": {
+      "field": "status",
+      "type": "nominal",
+      "legend": null,
+      "scale": {
+        "domain": ["ok", "partial", "error", "timeout", "shim_only", "probe_only", "tampered"],
+        "range": ["#c3e88d", "#ffc777", "#ff757f", "#737aa2", "#737aa2", "#737aa2", "#ff757f"]
+      }
+    }
+  },
+  "config": {
+    "view": { "stroke": null },
+    "axis": {
+      "domainColor": "#3b4261",
+      "tickColor": "#3b4261",
+      "gridColor": "#232330",
+      "gridDash": [2, 3],
+      "labelColor": "#828bb8",
+      "titleColor": "#a9b1d6",
+      "labelFont": "ui-monospace, Menlo, monospace",
+      "titleFont": "ui-monospace, Menlo, monospace",
+      "labelFontSize": 11,
+      "titleFontSize": 11,
+      "titlePadding": 12
+    }
+  }
+}

package/templates/capacity-report.tsx

@@ -0,0 +1,102 @@
+import React from "react";
+
+const regions = [
+  { name: "north", ready: 18, total: 20, queue: 6, latency: 182 },
+  { name: "core", ready: 14, total: 16, queue: 4, latency: 196 },
+  { name: "edge", ready: 10, total: 12, queue: 8, latency: 218 },
+] as const;
+
+export default function CapacityReport() {
+  const readyWorkers = regions.reduce((total, region) => total + region.ready, 0);
+  const workerCapacity = regions.reduce((total, region) => total + region.total, 0);
+  const queuedRevisions = regions.reduce((total, region) => total + region.queue, 0);
+  const averageLatency = Math.round(
+    regions.reduce((total, region) => total + region.latency, 0) / regions.length,
+  );
+  const capacityPercent = Math.round((readyWorkers / workerCapacity) * 100);
+
+  return (
+    <main className="max-w-2xl p-6 gap-6 flex flex-col bg-legion-paper text-legion-ink">
+      <header className="flex flex-col gap-2">
+        <div className="flex flex-wrap gap-2">
+          <span className="badge">capacity report</span>
+          <span className="badge">static render</span>
+          <span className="badge">{capacityPercent}% ready</span>
+        </div>
+        <h1 className="text-2xl font-bold">Capacity report</h1>
+        <p className="text-sm text-legion-muted">
+          Worker readiness, queued revisions, and visual verification latency by operating region.
+        </p>
+      </header>
+
+      <section className="grid grid-cols-3 gap-4" aria-label="capacity summary">
+        <article className="stat card border border-legion-line rounded-box p-4 gap-2 flex flex-col">
+          <span className="text-xs text-legion-muted">ready workers</span>
+          <strong className="text-2xl font-bold">{readyWorkers}</strong>
+          <span className="text-xs text-legion-cyan">of {workerCapacity} scheduled</span>
+        </article>
+        <article className="stat card border border-legion-line rounded-box p-4 gap-2 flex flex-col">
+          <span className="text-xs text-legion-muted">queued revisions</span>
+          <strong className="text-2xl font-bold">{queuedRevisions}</strong>
+          <span className="text-xs text-legion-muted">across {regions.length} regions</span>
+        </article>
+        <article className="stat card border border-legion-line rounded-box p-4 gap-2 flex flex-col">
+          <span className="text-xs text-legion-muted">average visual latency</span>
+          <strong className="text-2xl font-bold">{averageLatency} ms</strong>
+          <span className="text-xs text-legion-cyan">within 250 ms target</span>
+        </article>
+      </section>
+
+      <section className="card border border-legion-line rounded-box p-4 gap-3 flex flex-col">
+        <div className="flex items-center justify-between gap-2">
+          <h2 className="text-lg font-semibold">Regional allocation</h2>
+          <span className="badge">revision-bound</span>
+        </div>
+        <div className="overflow-x-auto">
+          <table className="table table-zebra w-full">
+            <thead>
+              <tr>
+                <th className="text-left">region</th>
+                <th className="text-right">ready</th>
+                <th className="text-right">queue</th>
+                <th className="text-right">visual latency</th>
+              </tr>
+            </thead>
+            <tbody>
+              {regions.map((region) => (
+                <tr key={region.name}>
+                  <td>{region.name}</td>
+                  <td className="text-right">
+                    {region.ready} / {region.total}
+                  </td>
+                  <td className="text-right">{region.queue}</td>
+                  <td className="text-right">{region.latency} ms</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </section>
+
+      <section className="grid grid-cols-2 gap-4">
+        <article className="card border border-legion-line rounded-box p-4 gap-2 flex flex-col">
+          <h2 className="text-lg font-semibold">Readiness signal</h2>
+          <p className="text-sm text-legion-muted">
+            {readyWorkers} workers are ready. {workerCapacity - readyWorkers} remain reserved for
+            maintenance and recovery.
+          </p>
+          <span className="text-lg font-semibold text-legion-cyan">
+            ✓ {capacityPercent}% capacity online
+          </span>
+        </article>
+        <article className="card border border-legion-line rounded-box p-4 gap-2 flex flex-col">
+          <h2 className="text-lg font-semibold">Planning note</h2>
+          <p className="text-sm text-legion-muted">
+            Keep edge capacity fixed until its queue drops below the current 8-revision threshold.
+          </p>
+          <span className="text-sm">→ review after the next visual verification window</span>
+        </article>
+      </section>
+    </main>
+  );
+}

package/templates/decision-record.md

@@ -0,0 +1,24 @@
+# ADR NNNN — short decision title
+
+**Status.** proposed · accepted · superseded by NNNN
+**Date.** 2026-08-08
+
+## Context
+
+Two or three sentences. The forces at play, the constraint that makes this
+a decision rather than a preference. Link the evidence, not the vibes.
+
+## Decision
+
+One paragraph, present tense, active voice: what we do.
+
+| option     | cost | why not |
+| ---------- | ---- | ------- |
+| A (chosen) | —    | —       |
+| B          | —    | —       |
+
+## Consequences
+
+- what gets easier
+- what gets harder
+- what becomes impossible on purpose

package/templates/deployment-state.mmd

@@ -0,0 +1,40 @@
+%%{init: {"theme": "base", "themeVariables": {"background": "transparent", "primaryColor": "#1e2030", "primaryTextColor": "#c8d3f5", "primaryBorderColor": "#3b4261", "lineColor": "#545c7e", "textColor": "#a9b1d6", "fontFamily": "ui-monospace, Menlo, monospace", "fontSize": "13px"}}}%%
+stateDiagram-v2
+  [*] --> Admission
+
+  state "admission controls" as Admission {
+    [*] --> Intake
+    Intake --> PolicyCheck : revision received
+    PolicyCheck --> Accepted : policy passed
+    PolicyCheck --> Rejected : policy denied
+    Accepted --> [*]
+    Rejected --> [*]
+  }
+
+  Admission --> Staging : accepted revision
+  Admission --> [*] : rejected revision
+
+  state "staging rollout" as Staging {
+    [*] --> Provisioning
+    Provisioning --> Verifying : workers ready
+    Verifying --> Ready : tier 0 ok
+    Verifying --> Blocked : validation error
+    Ready --> [*]
+    Blocked --> [*]
+  }
+
+  Staging --> Canary : release requested
+  Staging --> [*] : staging blocked
+
+  state "canary release" as Canary {
+    [*] --> Routing
+    Routing --> Observing : traffic shifted
+    Observing --> Stable : checks pass
+    Observing --> RollingBack : error budget spent
+    RollingBack --> [*] : traffic restored
+    Stable --> [*]
+  }
+
+  Canary --> Complete : stable observation
+  Canary --> Staging : rollback complete
+  Complete --> [*]