planr 1.3.0 → 1.4.0

package/website/alchemy-runtime.test.mjs

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  assertAlchemyRuntime,
+  MINIMUM_ALCHEMY_NODE_MAJOR,
+} from "../scripts/check-alchemy-runtime.mjs";
+
+test("accepts the minimum supported Alchemy deployment runtime", () => {
+  assert.equal(assertAlchemyRuntime("22.0.0"), MINIMUM_ALCHEMY_NODE_MAJOR);
+});
+
+test("rejects Node runtimes supported by the Planr CLI but not by Alchemy", () => {
+  assert.throws(
+    () => assertAlchemyRuntime("18.16.1"),
+    /Cloudflare deployment requires Node\.js 22 or newer; current runtime is 18\.16\.1/,
+  );
+  assert.throws(
+    () => assertAlchemyRuntime("20.19.5"),
+    /Cloudflare deployment requires Node\.js 22 or newer/,
+  );
+});

package/website/app.mjs

@@ -0,0 +1,216 @@
+import { formatBasisPoints, previewCommand, statusLabel, visibleCompositions } from "./catalog-model.mjs";
+
+const nodes = {
+  selectA: document.querySelector("#composition-a"),
+  selectB: document.querySelector("#composition-b"),
+  cardA: document.querySelector("#comparison-a"),
+  cardB: document.querySelector("#comparison-b"),
+  comparison: document.querySelector("#comparison"),
+  empty: document.querySelector("#empty-state"),
+  emptyMessage: document.querySelector("#empty-message"),
+  filter: document.querySelector("#recommended-only"),
+  published: document.querySelector("#stat-published"),
+  recommended: document.querySelector("#stat-recommended"),
+  trust: document.querySelector("#stat-trust"),
+  generated: document.querySelector("#generated-at"),
+  copyStatus: document.querySelector("#copy-status"),
+  fixtureBanner: document.querySelector("#fixture-banner"),
+};
+
+function catalogLocation() {
+  const local = ["127.0.0.1", "localhost"].includes(location.hostname);
+  const fixture = new URLSearchParams(location.search).get("fixture");
+  if (local && fixture === "recommended") {
+    nodes.fixtureBanner.hidden = false;
+    return "./test-fixtures/recommended.json";
+  }
+  return "./data/catalog.json";
+}
+
+function text(parent, element, value, className) {
+  const node = document.createElement(element);
+  if (className) node.className = className;
+  node.textContent = value;
+  parent.append(node);
+  return node;
+}
+
+function formatDate(unix) {
+  if (!Number.isFinite(unix)) return "Not published";
+  return new Intl.DateTimeFormat("en", { dateStyle: "medium", timeZone: "UTC" }).format(new Date(unix * 1000));
+}
+
+function formatNumber(value) {
+  return Number.isFinite(Number(value)) ? new Intl.NumberFormat("en").format(Number(value)) : "—";
+}
+
+function optionLabel(entry) {
+  return `${entry.policy.id} + ${entry.binding.id} · ${statusLabel(entry.status)}`;
+}
+
+function fillSelect(select, entries, preferredIndex) {
+  const previous = select.value;
+  select.replaceChildren();
+  for (const entry of entries) {
+    const option = document.createElement("option");
+    option.value = entry.id;
+    option.textContent = optionLabel(entry);
+    select.append(option);
+  }
+  select.value = entries.some((entry) => entry.id === previous) ? previous : entries[Math.min(preferredIndex, entries.length - 1)]?.id ?? "";
+}
+
+function metric(parent, label, value) {
+  const wrapper = document.createElement("div");
+  wrapper.className = "metric";
+  text(wrapper, "span", label);
+  text(wrapper, "strong", value);
+  parent.append(wrapper);
+}
+
+function section(parent, title) {
+  const wrapper = document.createElement("section");
+  wrapper.className = "card-section";
+  text(wrapper, "h4", title);
+  parent.append(wrapper);
+  return wrapper;
+}
+
+function definitionRow(list, termValue, detailValue) {
+  const row = document.createElement("div");
+  text(row, "dt", termValue);
+  text(row, "dd", detailValue);
+  list.append(row);
+}
+
+function renderCard(card, entry) {
+  card.replaceChildren();
+  if (!entry) return;
+  card.dataset.compositionId = entry.id;
+
+  const top = document.createElement("div");
+  top.className = "card-top";
+  const title = document.createElement("div");
+  text(title, "span", `${entry.binding.id} · ${entry.binding.host}`, "binding-name");
+  text(title, "h3", entry.policy.id);
+  const badge = text(top, "span", statusLabel(entry.status), `badge status-${entry.status}`);
+  badge.setAttribute("aria-label", `Status: ${statusLabel(entry.status)}`);
+  top.prepend(title);
+  card.append(top);
+  text(card, "p", `Policy ${entry.policy.version} · Binding ${entry.binding.version} · Entry ${entry.entryVersion}`, "meta-line");
+
+  const metrics = document.createElement("div");
+  metrics.className = "metric-grid";
+  metric(metrics, "Active agents", formatNumber(entry.policy.usage.max_active_agents));
+  metric(metrics, "Parallel writers", formatNumber(entry.policy.usage.max_parallel_writers));
+  metric(metrics, "Max depth", formatNumber(entry.policy.usage.max_depth));
+  metric(metrics, "Metering", entry.policy.usage.metering ?? "unavailable");
+  card.append(metrics);
+
+  const compatibility = section(card, "Compatibility");
+  const compatibilityList = document.createElement("dl");
+  compatibilityList.className = "compatibility-list";
+  definitionRow(
+    compatibilityList,
+    "Supported hosts",
+    entry.compatibility.hosts?.length ? entry.compatibility.hosts.join(", ") : "No compatible host declared",
+  );
+  definitionRow(
+    compatibilityList,
+    "Planr versions",
+    `${entry.compatibility.minPlanrVersion ?? "Any"} through ${entry.compatibility.maxPlanrVersion ?? "latest"}`,
+  );
+  definitionRow(
+    compatibilityList,
+    "Lifecycle",
+    entry.replacement
+      ? `${statusLabel(entry.status)}; replace with ${entry.replacement}`
+      : statusLabel(entry.status),
+  );
+  compatibility.append(compatibilityList);
+
+  const enforcement = section(card, "Enforcement matrix");
+  const list = document.createElement("dl");
+  list.className = "enforcement-list";
+  for (const item of entry.enforcement) {
+    const row = document.createElement("div");
+    const term = text(row, "dt", item.dimension);
+    text(term, "span", item.state.replaceAll("_", " "), "state");
+    text(row, "dd", item.detail);
+    list.append(row);
+  }
+  enforcement.append(list);
+
+  const evidence = section(card, "Evaluation & provenance");
+  text(evidence, "p", `${entry.evaluation.suiteId} ${entry.evaluation.suiteVersion} · evaluated ${formatDate(entry.evaluation.evaluatedAtUnix)} · review ${formatDate(entry.evaluation.reviewAtUnix)}`, "meta-line");
+  text(evidence, "p", `Quality ${formatBasisPoints(entry.evaluation.metrics?.average_quality_score_bps)} · runs ${formatNumber(entry.evaluation.metrics?.runs)} · oracle passes ${formatNumber(entry.evaluation.metrics?.oracle_passes)}`, "meta-line");
+  text(evidence, "p", `Manifest ${entry.registry.manifestSha256}`, "hash");
+  text(evidence, "p", `Signer ${entry.registry.signer} · signature verified · trusted maintainer`, "meta-line");
+
+  const commandSection = section(card, "Preview safely");
+  const commandBlock = document.createElement("div");
+  commandBlock.className = "command-block";
+  const command = previewCommand(entry.policy.id, entry.binding.id);
+  text(commandBlock, "code", command);
+  const button = text(commandBlock, "button", "Copy preview command", "copy-button");
+  button.type = "button";
+  button.dataset.command = command;
+  commandSection.append(commandBlock);
+}
+
+function wireCopy() {
+  document.addEventListener("click", async (event) => {
+    const button = event.target.closest("button[data-command]");
+    if (!button) return;
+    try {
+      await navigator.clipboard.writeText(button.dataset.command);
+      button.textContent = "Copied";
+      nodes.copyStatus.textContent = `Copied preview command for ${button.closest(".preset-card").dataset.compositionId}`;
+      setTimeout(() => { button.textContent = "Copy preview command"; }, 1400);
+    } catch {
+      nodes.copyStatus.textContent = "Clipboard access was unavailable; select the command text to copy it manually.";
+    }
+  });
+}
+
+function render(catalog) {
+  const entries = visibleCompositions(catalog, nodes.filter.checked);
+  nodes.published.textContent = formatNumber(catalog.compositions.length);
+  nodes.recommended.textContent = formatNumber(catalog.compositions.filter((entry) => entry.recommended).length);
+  nodes.trust.textContent = catalog.source?.state === "verified_registry_projection" ? "Signed registry" : "Publication gated";
+  nodes.generated.textContent = Number.isFinite(catalog.generatedAtUnix)
+    ? `Projection generated ${formatDate(catalog.generatedAtUnix)} · ${catalog.source.trust}`
+    : "No signed registry projection published.";
+  fillSelect(nodes.selectA, entries, 0);
+  fillSelect(nodes.selectB, entries, 1);
+  const empty = entries.length === 0;
+  nodes.empty.hidden = !empty;
+  nodes.comparison.hidden = empty;
+  if (empty) {
+    nodes.emptyMessage.textContent = catalog.source?.message ?? (nodes.filter.checked ? "No published composition currently carries an evaluation-backed recommendation." : "No trusted compositions are published.");
+    return;
+  }
+  const find = (id) => entries.find((entry) => entry.id === id);
+  renderCard(nodes.cardA, find(nodes.selectA.value));
+  renderCard(nodes.cardB, find(nodes.selectB.value));
+}
+
+async function start() {
+  wireCopy();
+  const response = await fetch(catalogLocation(), { cache: "no-store" });
+  if (!response.ok) throw new Error(`catalog request failed with HTTP ${response.status}`);
+  const catalog = await response.json();
+  if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.compositions)) throw new Error("unsupported catalog data");
+  const update = () => render(catalog);
+  nodes.filter.addEventListener("change", update);
+  nodes.selectA.addEventListener("change", update);
+  nodes.selectB.addEventListener("change", update);
+  update();
+}
+
+start().catch((error) => {
+  nodes.empty.hidden = false;
+  nodes.comparison.hidden = true;
+  nodes.emptyMessage.textContent = `Catalog unavailable: ${error.message}`;
+  nodes.trust.textContent = "Unavailable";
+});

package/website/build-catalog.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { projectComposition, safeIdentifier } from "./catalog-model.mjs";
+
+function usage(message) {
+  if (message) console.error(message);
+  console.error(
+    "usage: node website/build-catalog.mjs --manifest <registry.toml> --content-root <dir> --trust-store <trusted.toml> --entry <id=host> [--entry <id=host> ...] --at-unix <unix> --output <catalog.json> [--planr-bin <planr>]",
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const values = { entries: [], planrBin: "planr" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!value) usage(`missing value for ${flag}`);
+    index += 1;
+    if (flag === "--entry") values.entries.push(value);
+    else if (flag === "--manifest") values.manifest = value;
+    else if (flag === "--content-root") values.contentRoot = value;
+    else if (flag === "--trust-store") values.trustStore = value;
+    else if (flag === "--at-unix") values.atUnix = Number(value);
+    else if (flag === "--output") values.output = value;
+    else if (flag === "--planr-bin") values.planrBin = value;
+    else usage(`unknown argument ${flag}`);
+  }
+  if (
+    !values.manifest ||
+    !values.contentRoot ||
+    !values.trustStore ||
+    !values.output ||
+    !Number.isSafeInteger(values.atUnix) ||
+    values.entries.length === 0
+  ) {
+    usage("all required arguments must be provided");
+  }
+  return values;
+}
+
+function runJson(binary, args, cwd) {
+  const result = spawnSync(binary, args, { cwd, encoding: "utf8" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || result.stdout.trim() || `${binary} exited ${result.status}`);
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (error) {
+    throw new Error(`${binary} returned invalid JSON: ${error.message}`);
+  }
+}
+
+function entrySpec(raw) {
+  const separator = raw.lastIndexOf("=");
+  if (separator < 1 || separator === raw.length - 1) usage(`invalid --entry ${raw}; expected id=host`);
+  return { id: raw.slice(0, separator), host: raw.slice(separator + 1) };
+}
+
+function artifactPath(verified, kind, contentRoot) {
+  const matches = verified.entry.artifacts.filter((artifact) => artifact.kind === kind);
+  if (matches.length !== 1) throw new Error(`entry ${verified.entry.id} must contain one ${kind}`);
+  return resolve(contentRoot, matches[0].path);
+}
+
+const options = parseArgs(process.argv.slice(2));
+const invocationRoot = process.cwd();
+const planrBin =
+  isAbsolute(options.planrBin) || !options.planrBin.includes("/")
+    ? options.planrBin
+    : resolve(invocationRoot, options.planrBin);
+const manifest = resolve(invocationRoot, options.manifest);
+const contentRoot = resolve(invocationRoot, options.contentRoot);
+const trustStore = resolve(invocationRoot, options.trustStore);
+const scratch = mkdtempSync(join(tmpdir(), "planr-preset-site-"));
+
+try {
+  const compositions = options.entries.map((raw) => {
+    const { id, host } = entrySpec(raw);
+    const verified = runJson(
+      planrBin,
+      [
+        "--json",
+        "agents",
+        "preset",
+        "registry",
+        "verify",
+        manifest,
+        "--entry",
+        id,
+        "--content-root",
+        contentRoot,
+        "--trust-store",
+        trustStore,
+        "--at-unix",
+        String(options.atUnix),
+        "--host",
+        host,
+      ],
+      scratch,
+    );
+    const verificationPath = artifactPath(verified, "verification", contentRoot);
+    const policyId = safeIdentifier(verified.entry.evaluation?.policy_id, "policy id");
+    const bindingId = safeIdentifier(verified.entry.evaluation?.binding_id, "binding id");
+    const preview = runJson(
+      planrBin,
+      ["--json", "agents", "preset", "apply", policyId, "--binding", bindingId],
+      scratch,
+    );
+    const verificationEnvelope = JSON.parse(readFileSync(verificationPath, "utf8"));
+    return projectComposition({ verified, preview, verificationEnvelope });
+  });
+  const catalog = {
+    schemaVersion: 1,
+    generatedAtUnix: options.atUnix,
+    source: {
+      state: "verified_registry_projection",
+      manifest: options.manifest,
+      entryCount: compositions.length,
+      trust: "planr_registry_v1",
+    },
+    compositions,
+  };
+  const output = resolve(invocationRoot, options.output);
+  await mkdir(dirname(output), { recursive: true });
+  writeFileSync(output, `${JSON.stringify(catalog, null, 2)}\n`, { mode: 0o644 });
+  console.log(`wrote ${compositions.length} verified composition(s) to ${output}`);
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}

package/website/build-site.test.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  buildSite,
+  PUBLIC_SITE_FILES,
+  verifyPublication,
+} from "../scripts/build-site.mjs";
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "planr-site-build-"));
+  const sourceRoot = join(root, "website");
+  const outputRoot = join(root, "dist", "website");
+  for (const relativePath of PUBLIC_SITE_FILES) {
+    const path = join(sourceRoot, relativePath);
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, `public:${relativePath}\n`);
+  }
+  return { root, sourceRoot, outputRoot };
+}
+
+test("builds only the public runtime allowlist and preserves nested catalog bytes", async (t) => {
+  const paths = await fixture();
+  t.after(() => rm(paths.root, { recursive: true, force: true }));
+  await writeFile(join(paths.sourceRoot, "build-catalog.mjs"), "must not be public\n");
+  await mkdir(join(paths.sourceRoot, "registry"), { recursive: true });
+  await writeFile(join(paths.sourceRoot, "registry", "trusted-maintainers.toml"), "not public\n");
+
+  const files = await buildSite(paths);
+
+  assert.deepEqual(files, [...PUBLIC_SITE_FILES].sort());
+  assert.equal(
+    await readFile(join(paths.outputRoot, "data", "catalog.json"), "utf8"),
+    "public:data/catalog.json\n",
+  );
+});
+
+test("fails before replacing output when a required source artifact is missing", async (t) => {
+  const paths = await fixture();
+  t.after(() => rm(paths.root, { recursive: true, force: true }));
+  await mkdir(paths.outputRoot, { recursive: true });
+  await writeFile(join(paths.outputRoot, "sentinel"), "keep on validation failure\n");
+  await rm(join(paths.sourceRoot, "styles.css"));
+
+  await assert.rejects(() => buildSite(paths), /missing public website artifact: styles\.css/);
+  assert.equal(await readFile(join(paths.outputRoot, "sentinel"), "utf8"), "keep on validation failure\n");
+});
+
+test("publication verification rejects unexpected nested output", async (t) => {
+  const paths = await fixture();
+  t.after(() => rm(paths.root, { recursive: true, force: true }));
+  await buildSite(paths);
+  await mkdir(join(paths.outputRoot, "registry"), { recursive: true });
+  await writeFile(join(paths.outputRoot, "registry", "manifest.toml"), "unexpected\n");
+
+  await assert.rejects(() => verifyPublication(paths.outputRoot), /publish output mismatch/);
+});
+
+test("refuses an output directory inside the source tree", async (t) => {
+  const paths = await fixture();
+  t.after(() => rm(paths.root, { recursive: true, force: true }));
+
+  await assert.rejects(
+    () => buildSite({ sourceRoot: paths.sourceRoot, outputRoot: join(paths.sourceRoot, "dist") }),
+    /must not be inside/,
+  );
+});

package/website/catalog-model.mjs

@@ -0,0 +1,185 @@
+const IDENTIFIER = /^[A-Za-z0-9._-]+$/;
+
+export function safeIdentifier(value, label = "identifier") {
+  if (typeof value !== "string" || !IDENTIFIER.test(value)) {
+    throw new Error(`${label} is not a safe registry identifier`);
+  }
+  return value;
+}
+
+export function previewCommand(policyId, bindingId) {
+  return `planr agents preset apply ${safeIdentifier(policyId, "policy id")} --binding ${safeIdentifier(bindingId, "binding id")}`;
+}
+
+export function statusLabel(status) {
+  const labels = {
+    experimental: "Experimental",
+    verified: "Verified",
+    recommended: "Recommended",
+    stale: "Stale",
+    deprecated: "Deprecated",
+  };
+  return labels[status] ?? "Unverified";
+}
+
+export function formatBasisPoints(value) {
+  const basisPoints = Number(value);
+  return Number.isFinite(basisPoints) ? `${(basisPoints / 100).toFixed(2)}%` : "—";
+}
+
+function findArtifact(entry, kind) {
+  const artifacts = entry.artifacts.filter((artifact) => artifact.kind === kind);
+  if (artifacts.length !== 1) {
+    throw new Error(`registry entry must contain exactly one ${kind} artifact`);
+  }
+  return artifacts[0];
+}
+
+function proposedConfig(preview, kind) {
+  const artifact = preview.artifacts.find((candidate) => candidate.kind === kind);
+  const value = artifact?.config_diff?.proposed?.value;
+  if (!value || typeof value !== "object") {
+    throw new Error(`preset preview is missing proposed ${kind} configuration`);
+  }
+  return value;
+}
+
+function matchingCandidate(report, policyId, bindingId) {
+  const candidate = report.candidates?.find(
+    (value) => value.policy?.id === policyId && value.binding?.id === bindingId,
+  );
+  if (!candidate) {
+    throw new Error(`evaluation report has no candidate for ${policyId} + ${bindingId}`);
+  }
+  return candidate;
+}
+
+function recommendationMatches(report, policyId, bindingId) {
+  return Boolean(
+    report.recommended?.some(
+      (value) => value.policy === policyId && value.binding === bindingId && value.status === "recommended",
+    ),
+  );
+}
+
+export function projectComposition({ verified, preview, verificationEnvelope }) {
+  if (!verified?.integrity_verified || !verified?.signature_verified || !verified?.trusted_maintainer) {
+    throw new Error("website projection requires an integrity-verified entry signed by a trusted maintainer");
+  }
+  if (!verified.compatible) {
+    throw new Error("website projection requires a compatible registry entry");
+  }
+  if (!preview?.pack?.safe) {
+    throw new Error("website projection requires a canonical safe-pack preview");
+  }
+
+  const entry = verified.entry;
+  const evaluation = entry.evaluation;
+  if (!evaluation) {
+    throw new Error("website projection requires evaluation binding metadata");
+  }
+  const policyId = safeIdentifier(evaluation.policy_id, "policy id");
+  const bindingId = safeIdentifier(evaluation.binding_id, "binding id");
+  const report = verificationEnvelope.report ?? verificationEnvelope;
+  const candidate = matchingCandidate(report, policyId, bindingId);
+  const reportRecommended = recommendationMatches(report, policyId, bindingId);
+  if (verified.recommended && (!reportRecommended || candidate.status !== "recommended")) {
+    throw new Error("registry recommendation does not match canonical evaluation evidence");
+  }
+
+  const policy = proposedConfig(preview, "active_policy");
+  const agents = proposedConfig(preview, "agent_registry");
+  if (policy.id !== policyId || preview.composition?.binding?.id !== bindingId) {
+    throw new Error("preset preview provenance does not match registry evaluation binding");
+  }
+  const runs = Number(candidate.metrics?.runs ?? 0);
+  const verifiedRoutes = Number(candidate.metrics?.verified_route_runs ?? 0);
+  const policyArtifact = findArtifact(entry, "policy");
+  const bindingArtifact = findArtifact(entry, "host-binding");
+  const verificationArtifact = findArtifact(entry, "verification");
+
+  return {
+    id: `${safeIdentifier(entry.id, "entry id")}@${entry.version}`,
+    entryId: entry.id,
+    entryVersion: entry.version,
+    status: verified.effective_status,
+    statusLabel: statusLabel(verified.effective_status),
+    recommended: verified.recommended,
+    freshness: verified.freshness,
+    lifecycle: entry.lifecycle,
+    replacement: entry.replacement ?? null,
+    policy: {
+      id: policyId,
+      version: evaluation.policy_version,
+      usage: policy.usage,
+      transitions: policy.transitions,
+      materiality: policy.materiality,
+      execution: policy.execution,
+    },
+    binding: {
+      id: bindingId,
+      version: evaluation.binding_version,
+      host: preview.composition.host,
+      profiles: agents.profiles,
+      dispatch: preview.composition.dispatch,
+    },
+    compatibility: {
+      hosts: entry.compatible_hosts,
+      minPlanrVersion: entry.min_planr_version,
+      maxPlanrVersion: entry.max_planr_version,
+    },
+    enforcement: [
+      {
+        dimension: "Policy limits",
+        state: "verified",
+        detail: "Planr validates count, time, concurrency, transition, and safety-stop limits before dispatch.",
+      },
+      {
+        dimension: "Execution permissions",
+        state: "verified",
+        detail: "Registry-safe policy: no commands, hooks, network/MCP grants, secrets, or overwrite permission.",
+      },
+      {
+        dimension: "Model and effort",
+        state: "host_enforced",
+        detail: "The host binding requests concrete routes; the host retains final execution authority.",
+      },
+      {
+        dimension: "Effective route evidence",
+        state: runs > 0 && verifiedRoutes === runs ? "verified" : "unavailable",
+        detail: `${verifiedRoutes} of ${runs} evaluation runs carried verified effective-route evidence.`,
+      },
+    ],
+    evaluation: {
+      suiteId: report.suite?.id,
+      suiteVersion: report.suite?.version,
+      evaluatedAtUnix: report.suite?.evaluated_at_unix,
+      reviewAtUnix: entry.review_at_unix,
+      status: candidate.status,
+      metrics: candidate.metrics,
+      thresholds: candidate.threshold_results,
+      resultHashes: candidate.results?.map((result) => result.result_sha256) ?? [],
+      fixtureSha256: report.suite?.fixture_sha256,
+    },
+    registry: {
+      id: verified.registry_id,
+      version: verified.registry_version,
+      manifestSha256: verified.manifest_sha256,
+      signer: entry.signature?.signer,
+      signatureVerified: true,
+      trustedMaintainer: true,
+      artifacts: [policyArtifact, bindingArtifact, verificationArtifact].map((artifact) => ({
+        path: artifact.path,
+        kind: artifact.kind,
+        sha256: artifact.sha256,
+        sizeBytes: artifact.size_bytes,
+      })),
+    },
+    command: previewCommand(policyId, bindingId),
+  };
+}
+
+export function visibleCompositions(catalog, recommendedOnly = false) {
+  const compositions = Array.isArray(catalog?.compositions) ? catalog.compositions : [];
+  return recommendedOnly ? compositions.filter((entry) => entry.recommended) : compositions;
+}