@coldtea/pr-lens-schema 0.1.0

package/src/graph.ts

@@ -0,0 +1,331 @@
+import { z } from "zod";
+import { Delta, FileRef, Id, Label, Lens, SchemaVersionField, Sha, Summary } from "./primitives.js";
+
+/**
+ * Coarse on purpose: this drives the card icon and shape, never analysis.
+ * Anything that does not fit is `other`, which still renders.
+ */
+export const NodeKind = z.enum([
+  "service",
+  "app",
+  "module",
+  "function",
+  "route",
+  "job",
+  "queue",
+  "datastore",
+  "cache",
+  "external",
+  "ui",
+  "config",
+  "test",
+  "package",
+  "other",
+]);
+export type NodeKind = z.infer<typeof NodeKind>;
+
+export const Lane = z
+  .strictObject({
+    id: Id,
+    label: Label,
+    subtitle: Label.optional().describe("Secondary line in the lane header, e.g. the platform."),
+    order: z
+      .int()
+      .min(0)
+      .max(64)
+      .optional()
+      .describe("Left-to-right placement. Ties fall back to array order."),
+    delta: Delta.optional().describe("Set only when the lane itself is new or gone."),
+    summary: Summary.optional(),
+  })
+  .describe("A grouping band of the diagram. Every node belongs to exactly one lane.");
+export type Lane = z.infer<typeof Lane>;
+
+export const GraphNode = z
+  .strictObject({
+    id: Id,
+    label: Label,
+    kind: NodeKind,
+    delta: Delta,
+    lane: Id.describe("Id of the lane this node sits in."),
+    group: Id.optional().describe("Optional sub-cluster within the lane, e.g. a package."),
+    subtitle: Label.optional().describe("Secondary line on the card, e.g. a symbol signature."),
+    summary: Summary.optional().describe("Body text for this node's drill-down section."),
+    files: z
+      .array(FileRef)
+      .max(64)
+      .default([])
+      .describe("Backing source locations, used to build diff permalinks."),
+    badges: z
+      .array(Label)
+      .max(6)
+      .default([])
+      .describe("Extra chips on the card, beyond the delta badge the renderer adds."),
+  })
+  .describe("A node in the architecture graph.");
+export type GraphNode = z.infer<typeof GraphNode>;
+
+export const EdgeKind = z.enum([
+  "call",
+  "http",
+  "rpc",
+  "event",
+  "queue",
+  "data",
+  "dependency",
+  "render",
+  "other",
+]);
+export type EdgeKind = z.infer<typeof EdgeKind>;
+
+/**
+ * `hero` is the one connection the change is really about. More than a couple
+ * per diagram and the emphasis stops meaning anything.
+ */
+export const EdgeEmphasis = z.enum(["normal", "hero", "muted"]);
+export type EdgeEmphasis = z.infer<typeof EdgeEmphasis>;
+
+export const GraphEdge = z
+  .strictObject({
+    id: Id,
+    from: Id.describe("Source node id."),
+    to: Id.describe("Target node id."),
+    kind: EdgeKind,
+    delta: Delta,
+    label: Label.optional().describe("Text on the edge, e.g. a payload size or protocol."),
+    emphasis: EdgeEmphasis.default("normal"),
+    animated: z
+      .boolean()
+      .default(false)
+      .describe("Render a travelling pulse along this edge in the architecture lens."),
+    summary: Summary.optional(),
+    files: z.array(FileRef).max(32).default([]),
+  })
+  .describe("A directed connection between two nodes.");
+export type GraphEdge = z.infer<typeof GraphEdge>;
+
+/** `async` fires and forgets, `return` carries a result back, `self` never leaves the participant. */
+export const MessageKind = z.enum(["sync", "async", "return", "self"]);
+export type MessageKind = z.infer<typeof MessageKind>;
+
+/**
+ * Order is the array position. An explicit step number would let a producer
+ * emit a document whose animation order disagrees with its own message list.
+ */
+export const FlowMessage = z
+  .strictObject({
+    id: Id,
+    from: Id.describe("Participant node id the message originates from."),
+    to: Id.describe("Participant node id the message arrives at. Equals `from` when kind is self."),
+    label: Label,
+    kind: MessageKind.default("sync"),
+    delta: Delta,
+    animated: z.boolean().default(true).describe("Whether the data-flow lens pulses this step."),
+    repeat: z
+      .int()
+      .min(1)
+      .max(1_000_000)
+      .optional()
+      .describe("Times the step occurs per run, e.g. 4 batched requests."),
+    note: Summary.optional().describe("Aside rendered beside the step in the drill-down."),
+    files: z.array(FileRef).max(32).default([]),
+  })
+  .refine((message) => (message.kind === "self") === (message.from === message.to), {
+    message: "kind 'self' and from === to must agree",
+    path: ["kind"],
+  })
+  .describe("One ordered step in a flow.");
+export type FlowMessage = z.infer<typeof FlowMessage>;
+
+export const FlowParticipant = z
+  .strictObject({
+    node: Id.describe("Id of the graph node this column represents."),
+    label: Label.optional().describe("Shorter name for the column when the node label is long."),
+  })
+  .describe("A column in the sequence diagram, ordered by array position.");
+export type FlowParticipant = z.infer<typeof FlowParticipant>;
+
+export const Flow = z
+  .strictObject({
+    id: Id,
+    title: Label,
+    summary: Summary.optional(),
+    delta: Delta.default("modified"),
+    participants: z.array(FlowParticipant).min(2).max(12),
+    messages: z.array(FlowMessage).min(1).max(64).describe("Ordered by array position."),
+  })
+  .describe("An ordered message sequence for the data-flow lens.");
+export type Flow = z.infer<typeof Flow>;
+
+export const StatChip = z
+  .strictObject({
+    label: Label,
+    value: z.string().min(1).max(32),
+    tone: z.enum(["neutral", "added", "modified", "removed", "hero"]).default("neutral"),
+  })
+  .describe("A headline chip above the diagram.");
+export type StatChip = z.infer<typeof StatChip>;
+
+/**
+ * Counts that cannot be derived from the document, plus free-form chips.
+ * Per-delta element counts are deliberately absent: they are derivable, and a
+ * stored copy can only ever go stale against the node and edge lists.
+ */
+export const Stats = z
+  .strictObject({
+    filesChanged: z.int().min(0).optional(),
+    additions: z.int().min(0).optional().describe("Lines added across the diff."),
+    deletions: z.int().min(0).optional().describe("Lines removed across the diff."),
+    chips: z.array(StatChip).max(8).default([]),
+  })
+  .describe("Headline numbers for the comment header.");
+export type Stats = z.infer<typeof Stats>;
+
+/**
+ * A view either shows the whole document or a named selection. The two are
+ * distinct states rather than "a selection that happens to be empty", so
+ * removing the last element a view pointed at can never silently turn it into
+ * a view of everything.
+ */
+export const ViewScope = z
+  .discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("all") }),
+    z
+      .strictObject({
+        kind: z.literal("selection"),
+        lanes: z.array(Id).max(64).default([]),
+        nodes: z.array(Id).max(256).default([]),
+        edges: z.array(Id).max(512).default([]),
+        flows: z.array(Id).max(32).default([]),
+      })
+      .meta({
+        anyOf: [
+          { properties: { lanes: { minItems: 1 } }, required: ["lanes"] },
+          { properties: { nodes: { minItems: 1 } }, required: ["nodes"] },
+          { properties: { edges: { minItems: 1 } }, required: ["edges"] },
+          { properties: { flows: { minItems: 1 } }, required: ["flows"] },
+        ],
+      })
+      .refine(
+        (scope) =>
+          scope.lanes.length + scope.nodes.length + scope.edges.length + scope.flows.length > 0,
+        { message: "a selection must name at least one element" },
+      ),
+  ])
+  .describe("What a drill-down section shows.");
+export type ViewScope = z.infer<typeof ViewScope>;
+
+export type View = {
+  id: string;
+  title: string;
+  lens: Lens;
+  summary?: string;
+  scope: ViewScope;
+  defaultOpen: boolean;
+  children: View[];
+};
+
+/**
+ * One node of the nested `<details>` tree in the PR comment. The whole tree
+ * ships pre-rendered, so expanding a section costs no round trip.
+ */
+export type ViewInput = {
+  id: string;
+  title: string;
+  lens: Lens;
+  summary?: string;
+  scope?:
+    | { kind: "all" }
+    | { kind: "selection"; lanes?: string[]; nodes?: string[]; edges?: string[]; flows?: string[] };
+  defaultOpen?: boolean;
+  children?: ViewInput[];
+};
+
+export const View: z.ZodType<View, ViewInput> = z.lazy(() =>
+  z
+    .strictObject({
+      id: Id,
+      title: Label,
+      lens: Lens,
+      summary: Summary.optional(),
+      scope: ViewScope.default({ kind: "all" }),
+      defaultOpen: z.boolean().default(false),
+      children: z.array(View).max(32).default([]),
+    })
+    .describe("A drill-down section; children nest as further <details> blocks."),
+);
+
+/**
+ * Hints, not instructions: the renderer owns final placement so that layout
+ * stays deterministic for a given document. A hint is a floor rather than an
+ * answer — it can push a node further down the page, never above something
+ * that feeds it — so a stale hint can leave a gap but can never invert an
+ * edge. Absolute coordinates are intentionally not expressible.
+ */
+export const LayoutHints = z
+  .strictObject({
+    direction: z.enum(["right", "down"]).default("right").describe("Primary flow direction."),
+    laneOrder: z.array(Id).max(64).default([]).describe("Explicit left-to-right lane order."),
+    rank: z.record(Id, z.int().min(0).max(256)).optional().describe("Preferred layer index per node id."),
+  })
+  .describe("Optional, non-binding placement hints.");
+export type LayoutHints = z.infer<typeof LayoutHints>;
+
+/** Everything needed to rebuild a permalink to any file this document points at. */
+export const Provenance = z
+  .strictObject({
+    repo: z.strictObject({
+      owner: z.string().min(1).max(64),
+      name: z.string().min(1).max(128),
+      host: z.string().min(1).max(128).default("github.com"),
+    }),
+    base: z.strictObject({ sha: Sha, ref: z.string().min(1).max(255).optional() }),
+    head: z.strictObject({ sha: Sha, ref: z.string().min(1).max(255).optional() }),
+    pullRequest: z
+      .strictObject({
+        number: z.int().min(1),
+        title: z.string().min(1).max(512).optional(),
+        url: z.url().optional(),
+      })
+      .optional(),
+    generator: z
+      .strictObject({
+        name: z.string().min(1).max(64),
+        version: z.string().min(1).max(32).optional(),
+        model: z.string().min(1).max(128).optional().describe("Extraction model, when one was used."),
+      })
+      .optional(),
+  })
+  .describe("Where the document came from.");
+export type Provenance = z.infer<typeof Provenance>;
+
+/**
+ * The document every PR Lens component speaks: extraction emits it, the
+ * renderer consumes it, and a baseline map is one of these kept current by
+ * patch documents.
+ */
+export const GraphDoc = z
+  .strictObject({
+    schemaVersion: SchemaVersionField,
+    kind: z.literal("graph"),
+    id: Id.optional().describe("Stable id when the document is stored, e.g. a baseline map."),
+    generatedAt: z.iso.datetime().optional(),
+    title: Label,
+    summary: Summary.optional().describe("The one-paragraph answer to 'what does this change do?'"),
+    lenses: z
+      .array(Lens)
+      .min(1)
+      .max(8)
+      .describe("Lenses this document carries enough detail to render."),
+    provenance: Provenance,
+    lanes: z.array(Lane).min(1).max(16),
+    nodes: z.array(GraphNode).min(1).max(256),
+    edges: z.array(GraphEdge).max(512).default([]),
+    flows: z.array(Flow).max(16).default([]),
+    stats: Stats.optional(),
+    views: z.array(View).max(32).default([]),
+    layout: LayoutHints.optional(),
+  })
+  .describe("A PR Lens graph document.");
+export type GraphDoc = z.infer<typeof GraphDoc>;
+export type GraphDocInput = z.input<typeof GraphDoc>;

package/src/index.ts

@@ -0,0 +1,82 @@
+export { SCHEMA_VERSION, type SchemaVersion } from "./version.js";
+
+export {
+  Delta,
+  DELTAS,
+  FileRef,
+  FullSha,
+  Id,
+  Label,
+  Lens,
+  LENSES,
+  MAX_RENDER_ASSETS,
+  MAX_VIEWS,
+  Theme,
+  THEMES,
+  SchemaVersionField,
+  Sha,
+  Summary,
+} from "./primitives.js";
+
+export {
+  EdgeEmphasis,
+  EdgeKind,
+  Flow,
+  FlowMessage,
+  FlowParticipant,
+  GraphDoc,
+  GraphEdge,
+  GraphNode,
+  Lane,
+  LayoutHints,
+  MessageKind,
+  NodeKind,
+  Provenance,
+  StatChip,
+  Stats,
+  View,
+  ViewScope,
+  type GraphDocInput,
+  type ViewInput,
+} from "./graph.js";
+
+export {
+  EdgePatch,
+  FlowPatch,
+  LanePatch,
+  NodePatch,
+  PatchDoc,
+  PatchOp,
+  PATCH_OPS,
+  targetDescribesATransition,
+  type PatchDocInput,
+} from "./patch.js";
+
+export { Config, MapCorrections, Selector, type ConfigInput } from "./config.js";
+
+export { RenderAsset, RenderManifest, type RenderManifestInput } from "./manifest.js";
+
+export {
+  formatIssues,
+  PrLensSchemaError,
+  type Parsed,
+  type SchemaErrorCode,
+  type SchemaIssue,
+} from "./errors.js";
+
+export { graphIntegrityIssues, graphSnapshotIssues } from "./integrity.js";
+
+export {
+  parseConfig,
+  parseGraphDoc,
+  parsePatchDoc,
+  parseRenderManifest,
+  safeParseConfig,
+  safeParseGraphDoc,
+  safeParsePatchDoc,
+  safeParseRenderManifest,
+} from "./validate.js";
+
+export { applyPatch, applyPatchDoc } from "./apply.js";
+
+export { assertNever } from "./utils.js";

package/src/integrity.ts

@@ -0,0 +1,216 @@
+import type { SchemaIssue } from "./errors.js";
+import type { GraphDoc, View } from "./graph.js";
+import { FullSha, MAX_VIEWS, THEMES, type Delta } from "./primitives.js";
+import { assertNever } from "./utils.js";
+
+const duplicates = (ids: readonly string[]): string[] => {
+  const seen = new Set<string>();
+  const repeated = new Set<string>();
+  for (const id of ids) {
+    if (seen.has(id)) repeated.add(id);
+    seen.add(id);
+  }
+  return [...repeated];
+};
+
+const flattenViews = (views: readonly View[], prefix: string): { view: View; path: string }[] =>
+  views.flatMap((view, index) => {
+    const path = `${prefix}[${index}]`;
+    return [{ view, path }, ...flattenViews(view.children, `${path}.children`)];
+  });
+
+/**
+ * Structural validation says a field holds an id; these checks say the id
+ * points at something. Extraction models routinely emit an edge to a node
+ * they forgot to declare, and a renderer must never be handed that document.
+ */
+export const graphIntegrityIssues = (doc: GraphDoc): SchemaIssue[] => {
+  const issues: SchemaIssue[] = [];
+  const broken = (path: string, message: string) =>
+    issues.push({ code: "BROKEN_REFERENCE", path, message });
+  const duplicate = (path: string, message: string) =>
+    issues.push({ code: "DUPLICATE_ID", path, message });
+
+  const laneIds = new Set(doc.lanes.map((lane) => lane.id));
+  const nodeIds = new Set(doc.nodes.map((node) => node.id));
+  const flowIds = new Set(doc.flows.map((flow) => flow.id));
+  const edgeIds = new Set(doc.edges.map((edge) => edge.id));
+  const lenses = new Set(doc.lenses);
+
+  for (const id of duplicates(doc.lanes.map((lane) => lane.id)))
+    duplicate("lanes", `duplicate lane id '${id}'`);
+  for (const id of duplicates(doc.nodes.map((node) => node.id)))
+    duplicate("nodes", `duplicate node id '${id}'`);
+  for (const id of duplicates(doc.edges.map((edge) => edge.id)))
+    duplicate("edges", `duplicate edge id '${id}'`);
+  for (const id of duplicates(doc.flows.map((flow) => flow.id)))
+    duplicate("flows", `duplicate flow id '${id}'`);
+
+  doc.nodes.forEach((node, index) => {
+    if (!laneIds.has(node.lane))
+      broken(`nodes[${index}].lane`, `node '${node.id}' references unknown lane '${node.lane}'`);
+  });
+
+  doc.edges.forEach((edge, index) => {
+    if (!nodeIds.has(edge.from))
+      broken(`edges[${index}].from`, `edge '${edge.id}' references unknown node '${edge.from}'`);
+    if (!nodeIds.has(edge.to))
+      broken(`edges[${index}].to`, `edge '${edge.id}' references unknown node '${edge.to}'`);
+  });
+
+  doc.flows.forEach((flow, flowIndex) => {
+    const participantIds = new Set(flow.participants.map((participant) => participant.node));
+
+    for (const id of duplicates(flow.participants.map((participant) => participant.node)))
+      duplicate(`flows[${flowIndex}].participants`, `participant '${id}' listed twice`);
+    for (const id of duplicates(flow.messages.map((message) => message.id)))
+      duplicate(`flows[${flowIndex}].messages`, `duplicate message id '${id}'`);
+
+    flow.participants.forEach((participant, index) => {
+      if (!nodeIds.has(participant.node))
+        broken(
+          `flows[${flowIndex}].participants[${index}].node`,
+          `flow '${flow.id}' references unknown node '${participant.node}'`,
+        );
+    });
+
+    flow.messages.forEach((message, index) => {
+      if (!participantIds.has(message.from))
+        broken(
+          `flows[${flowIndex}].messages[${index}].from`,
+          `message '${message.id}' sends from '${message.from}', which is not a participant`,
+        );
+      if (!participantIds.has(message.to))
+        broken(
+          `flows[${flowIndex}].messages[${index}].to`,
+          `message '${message.id}' sends to '${message.to}', which is not a participant`,
+        );
+    });
+  });
+
+  if (doc.flows.length > 0 && !lenses.has("data-flow"))
+    broken("lenses", "document carries flows but does not declare the 'data-flow' lens");
+
+  const views = flattenViews(doc.views, "views");
+  for (const id of duplicates(views.map(({ view }) => view.id)))
+    duplicate("views", `duplicate view id '${id}'`);
+
+  // Each array in the tree is capped, but the tree's depth is not, so the
+  // total is only bounded here.
+  if (views.length > MAX_VIEWS)
+    issues.push({
+      code: "INVALID_DOCUMENT",
+      path: "views",
+      message: `drill-down tree carries ${views.length} views; a render is one asset per view per theme, and at ${THEMES.length} themes only ${MAX_VIEWS} fit a render manifest`,
+    });
+
+  for (const { view, path } of views) {
+    if (!lenses.has(view.lens))
+      broken(`${path}.lens`, `view '${view.id}' uses lens '${view.lens}', which the document does not declare`);
+
+    switch (view.scope.kind) {
+      case "all":
+        break;
+      case "selection": {
+        const selection = view.scope;
+        const scoped: [keyof Omit<typeof selection, "kind">, string, ReadonlySet<string>][] = [
+          ["lanes", "lane", laneIds],
+          ["nodes", "node", nodeIds],
+          ["edges", "edge", edgeIds],
+          ["flows", "flow", flowIds],
+        ];
+        for (const [collection, singular, known] of scoped) {
+          selection[collection].forEach((id, index) => {
+            if (!known.has(id))
+              broken(
+                `${path}.scope.${collection}[${index}]`,
+                `view '${view.id}' scopes unknown ${singular} '${id}'`,
+              );
+          });
+        }
+        break;
+      }
+      default:
+        assertNever(view.scope, "Unhandled view scope");
+    }
+  }
+
+  if (doc.layout) {
+    doc.layout.laneOrder.forEach((id, index) => {
+      if (!laneIds.has(id)) broken(`layout.laneOrder[${index}]`, `unknown lane '${id}'`);
+    });
+    for (const id of Object.keys(doc.layout.rank ?? {})) {
+      if (!nodeIds.has(id)) broken(`layout.rank.${id}`, `unknown node '${id}'`);
+    }
+  }
+
+  return issues;
+};
+
+/**
+ * Everything a document must satisfy to be stored as a map, and the check to
+ * run before storing one.
+ *
+ * A map describes a system, not a change to one: it is identified, it names
+ * the single commit it reflects in full, and nothing in it is annotated as a
+ * change. A map that fails this would hand the next pull request a baseline
+ * that already claims to be mid change, and every delta computed against it
+ * would inherit the mistake.
+ */
+export const graphSnapshotIssues = (doc: GraphDoc): SchemaIssue[] => {
+  const issues: SchemaIssue[] = [];
+
+  if (doc.id === undefined)
+    issues.push({
+      code: "NOT_A_SNAPSHOT",
+      path: "id",
+      message: "a stored map needs an id, so a patch can say which map it targets",
+    });
+
+  for (const side of ["base", "head"] as const) {
+    if (!FullSha.safeParse(doc.provenance[side].sha).success)
+      issues.push({
+        code: "NOT_A_SNAPSHOT",
+        path: `provenance.${side}.sha`,
+        message: `a stored map records the commit it reflects in full, but this one records '${doc.provenance[side].sha}'`,
+      });
+  }
+
+  const requireUnchanged = (delta: Delta | undefined, path: string, subject: string) => {
+    if (delta === undefined || delta === "unchanged") return;
+    issues.push({
+      code: "NOT_A_SNAPSHOT",
+      path,
+      message: `${subject} is marked '${delta}', but a stored map describes a system rather than a change`,
+    });
+  };
+
+  if (doc.provenance.base.sha !== doc.provenance.head.sha)
+    issues.push({
+      code: "NOT_A_SNAPSHOT",
+      path: "provenance",
+      message: `a stored map reflects one commit, but base is ${doc.provenance.base.sha} and head is ${doc.provenance.head.sha}`,
+    });
+
+  doc.lanes.forEach((lane, index) =>
+    requireUnchanged(lane.delta, `lanes[${index}].delta`, `lane '${lane.id}'`),
+  );
+  doc.nodes.forEach((node, index) =>
+    requireUnchanged(node.delta, `nodes[${index}].delta`, `node '${node.id}'`),
+  );
+  doc.edges.forEach((edge, index) =>
+    requireUnchanged(edge.delta, `edges[${index}].delta`, `edge '${edge.id}'`),
+  );
+  doc.flows.forEach((flow, flowIndex) => {
+    requireUnchanged(flow.delta, `flows[${flowIndex}].delta`, `flow '${flow.id}'`);
+    flow.messages.forEach((message, index) =>
+      requireUnchanged(
+        message.delta,
+        `flows[${flowIndex}].messages[${index}].delta`,
+        `step '${message.id}' of flow '${flow.id}'`,
+      ),
+    );
+  });
+
+  return issues;
+};

package/src/manifest.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { Id, Lens, MAX_RENDER_ASSETS, SchemaVersionField, Sha, Theme } from "./primitives.js";
+
+/**
+ * GitHub serves comment images through a proxy that caches aggressively, so
+ * every asset is addressed by the hash of its own bytes and a new render is a
+ * new URL rather than an updated one.
+ */
+export const RenderAsset = z
+  .strictObject({
+    id: Id,
+    lens: Lens,
+    theme: Theme.describe("Half of a <picture> pair."),
+    view: Id.optional().describe("Drill-down view this asset renders, when it is not the root."),
+    mediaType: z.literal("image/svg+xml"),
+    contentHash: z
+      .string()
+      .regex(/^[0-9a-f]{16,64}$/, "must be lowercase hex")
+      .describe("Hash of the asset bytes; the identity of this render."),
+    bytes: z.int().min(1),
+    width: z.int().min(1),
+    height: z.int().min(1),
+    animated: z.boolean().default(false).describe("Contains SMIL animation."),
+    url: z.url().optional().describe("Where the asset is published, once it has been uploaded."),
+    path: z
+      .string()
+      .min(1)
+      .max(1024)
+      .optional()
+      .describe("Local path, for surfaces that write files instead of uploading."),
+  })
+  .refine((asset) => asset.url !== undefined || asset.path !== undefined, {
+    message: "an asset needs a url or a path",
+    path: ["url"],
+  })
+  .meta({ anyOf: [{ required: ["url"] }, { required: ["path"] }] })
+  .describe("One rendered SVG.");
+export type RenderAsset = z.infer<typeof RenderAsset>;
+
+/** What a render produced: the inventory the comment composer builds from. */
+export const RenderManifest = z
+  .strictObject({
+    schemaVersion: SchemaVersionField,
+    kind: z.literal("render-manifest"),
+    generatedAt: z.iso.datetime().optional(),
+    graph: z
+      .strictObject({
+        id: Id.optional(),
+        headSha: Sha.optional(),
+        contentHash: z
+          .string()
+          .regex(/^[0-9a-f]{16,64}$/, "must be lowercase hex")
+          .describe("Hash of the graph document this render came from."),
+      })
+      .describe("The document that was rendered."),
+    renderer: z.strictObject({
+      name: z.string().min(1).max(64),
+      version: z.string().min(1).max(32),
+    }),
+    assets: z.array(RenderAsset).min(1).max(MAX_RENDER_ASSETS),
+  })
+  .describe("A PR Lens render manifest.");
+export type RenderManifest = z.infer<typeof RenderManifest>;
+export type RenderManifestInput = z.input<typeof RenderManifest>;