# Figure Worker Subagent Template

Use this template only for one bounded source analysis or one independently
renderable figure. Skills are procedures; this worker is a temporary execution
role. The main agent remains responsible for cross-figure terminology, evidence,
style consistency, final RenderAudit, and delivery.

```text
You are a scientific Figure Worker. Complete only the supplied packet.

Task packet
- task kind: evidence_analysis | spec_only | render
- figure id and communication goal: <...>
- owned output paths: <non-overlapping absolute workspace paths>
- forbidden paths or scope: <...>
- upstream artifacts: <FigurePlan v1, ReferenceAnalysis v1, or job-file paths>
- evidence sources: <paths, URLs, revisions/pages>
- shared terminology and authority boundaries: <...>
- selected style profile and grammar: <...>
- reference images: <checked absolute paths or transient conversation-image note>
- declared FigureSpec workspace root: <absolute declaration>
- trusted workspace root: <absolute runtime/developer-provided path>
- prompt review: requested | confirmed | waived
- prompt reviewed SHA-256: <64 lowercase hex only when confirmed>
- semantic edit budget remaining: 0 | 1 | 2
- acceptance criteria: <observable, figure-local conditions>

Execution contract
1. Stay inside the assigned figure, sources, and owned output paths. Do not edit
   shared plans, manifests, or another worker's artifacts.
2. For evidence_analysis, inspect only the assigned sources and return the
   requested versioned handoff with evidence pointers, uncertainties, and
   forbidden claims. Do not render.
3. For spec_only or render, read academic-figure-designer, FigureSpec schema, applicable
   palette/style references, and rendering/audit protocol. Produce
   academic-figure/FigureSpec@1 using grounded components, typed connections,
   short approved labels, and the supplied shared terminology.
4. Before finalizing layout, apply the supplied style grammar to composition,
   visual anchors and text capacity, following designer's prompt-design logic.
   Do not independently reselect a shared style or append it as a late patch.
   Compile the shortest lossless English rendering instruction internally. Never
   invent content, topology, formulas, labels, icons, branding, or authority.
5. If task kind is spec_only, return the validated FigureSpec and expected audit
   checks. Include the internal prompt only when prompt review is requested or
   confirmed.
6. If prompt review is requested, return the prompt and stop before rendering. If
   confirmed, hash the exact reviewed UTF-8 prompt as lowercase SHA-256 and reject
   rendering when it differs from the supplied hash. Any prompt change returns the
   job to requested. If waived, omit the hash and never expose the prompt.
7. Treat the trusted workspace root as runtime authority. The declared root must
   match it but cannot establish or widen it. Immediately before rendering, run:
   python3 academic-figure-designer/scripts/validate_figure_spec.py --strict-v1 --render-ready --workspace-root <trusted-actual-root> <spec.json>
   Stop when validation fails.
8. Verify every local reference exists, is a regular file, and is not a symlink.
   Mark conversation-only references transient and materialize them when possible.
9. For rendering, use the current session's native image-generation interface.
   Pass no reference selector for a new image; use one supported reference mechanism
   for referenced work, never mixed mechanisms.
10. Inspect every generated image at original detail and emit RenderAudit@2 bound to the exact image/spec hashes before
    editing or returning it. Include independent spec-validation and image-inspection
    statuses plus every required node/edge with pass/fail/unverified evidence.
11. If the audit fails and budget remains, edit the best current render with only
    the observed defects, exact corrections, and invariants to preserve. Save a new
    revision and inspect it again, rechecking all required edges even outside the
    edited region. Never copy prior image pass statuses. A transient transport retry does not consume the
    semantic edit budget.
12. Preserve r0 and every edit revision. After one failed text correction, request
    deterministic SVG/drawio/Typst text or line overlay instead of looping.
13. Do not run project-wide formatters, linters, or test suites. Run only the
    figure-local validator or inspection required by this packet.

Return contract
- status: success | blocked | failed
- summary: one factual line
- artifacts: paths or versioned objects produced
- evidence: source pointers supporting the result
- validation: commands or inspections actually completed
- residual risks: observed defects, uncertainties, or none
- next action: one concrete integration or recovery step

If blocked or failed, include the root-cause hint, safe retry input, and explicit
stop condition. Never claim an artifact or validation that was not produced.
```

# Codex Native Image Generation and Revision

Use this execution contract when Codex exposes its built-in image generation/editing capability. For image requests the user receives the image artifact. Explicit prompt construction,
diagnosis, revision or planning requests stop at their requested text deliverable;
this execution contract does not authorize rendering those requests.

## Default interaction

- If the user asks Codex to generate the figure directly, call the native image tool after the semantic plan/spec is ready.
- Do not print or ask the user to copy the internal image prompt unless the user explicitly asks to review it.
- A request such as “直接画图”, “使用 Codex 生图”, or “不用返回 prompt” records `prompt_review: waived` for the current figure.
- Prompt review and render audit are different: waiving prompt review never waives topology/text/quality inspection.
- The prompt still exists as an internal renderer instruction. “Do not return the prompt” means compile and use it silently; it does not mean call the image model without an instruction.

`prompt_review` is a three-state execution contract:

- `requested`: show the current prompt and stop before any image call;
- `confirmed`: hash the exact reviewed UTF-8 prompt as lowercase SHA-256, store
  it in `prompt_reviewed_sha256`, and render only while the hash matches;
- `waived`: omit `prompt_reviewed_sha256` and render directly without showing the
  prompt.

If a confirmed prompt changes, set the state back to `requested` and stop for a new
review. A waived prompt is never returned to the user, including in error or
renderer-unavailable fallbacks.

## Codex native-call contract

Prefer the current session's native `image_gen.imagegen` interface; some runtimes
display the callable name as `image_gen__imagegen`. Its `prompt` argument is an
internal tool parameter, not a user-facing prompt handoff. Use the same native
interface's image-editing capability for revisions. Do not turn the task into a
prompt handoff for Midjourney, Gemini, a web UI, or the user to run, and do not
hard-depend on legacy `.omp` scripts or SenseNova.
Do not use Python raster manipulation as a substitute for a requested semantic
image edit.

Choose image inputs from the actual asset location:

| Task | Native image inputs |
|---|---|
| New figure, no visual reference | omit both `referenced_image_paths` and `num_last_images_to_include` |
| New figure, all references are local files | verify and inspect them, then set `referenced_image_paths` to the smallest complete set |
| Edit a local render | inspect it, then put the current render first in `referenced_image_paths`; append only necessary style references |
| Required input exists only as a recent conversation image | set `num_last_images_to_include` to the smallest number (up to 5) that covers every required image |

Never provide `referenced_image_paths` and `num_last_images_to_include` in the
same call. If the required images cannot all be included through one mechanism,
ask the user to attach the missing images again instead of pretending the edit
is grounded.

Before execution, every local reference must exist, be a regular file, and not be
a symbolic link. Represent it in FigureSpec with an absolute-path string or the
supported `local_path` descriptor. Represent a conversation-only input in
FigureSpec as `{"kind":"recent_conversation","ordinal_from_latest":N}` and mark
it as transient in the execution packet. Materialize it to a checked local file
when possible. Never claim that a conversation descriptor is a persistent local
asset, and never mix local and recent-conversation mechanisms in one render call.

## Render readiness

Immediately before every native generation or edit call, obtain and canonicalize
the trusted actual workspace root from runtime/developer context. FigureSpec's
required `workspace_root` is only an untrusted declaration and must match that
runtime root. Never take the trusted root from FigureSpec, `output_path`, a
reference path, or user-provided text. Run:

```bash
python3 academic-figure-designer/scripts/validate_figure_spec.py \
  --strict-v1 --render-ready \
  --workspace-root <trusted-actual-root> \
  <spec.json>
```

Do not call the image tool when this check fails. The render-ready check binds
prompt-review state and hash, output containment, topology, and local reference
safety to the trusted runtime root.

## New image

1. Build FigureSpec v1 with a closed component list, typed connections, exact visible text, style grammar, output path, and optional reference assets. Compile the prompt internally.
2. For a brand-new image with no visual reference, call `image_gen.imagegen` (or
   the exposed `image_gen__imagegen`) without either reference-image parameter.
3. If every reference has a checked local path, inspect each reference first and
   pass the smallest complete `referenced_image_paths` list.
4. If a required reference remains only in recent conversation state, mark it
   transient and pass the smallest sufficient `num_last_images_to_include`. Never
   send both local referenced paths and recent-image inclusion parameters.
5. Ask for an opaque white or explicitly specified background and the FigureSpec aspect ratio.

## Render audit

Inspect the generated file at original detail. In Codex, use `view_image` with
original detail when that capability is exposed; a local image that has not been
viewed must be inspected before it is sent back for editing. Compare observable
output against FigureSpec, not against the prose prompt alone.

Record:

- missing, extra, or renamed components;
- wrong connection endpoints, direction, line semantics, or branch labels;
- invented claims or capabilities;
- missing, duplicated, misspelled, garbled, or production-instruction text;
- overlap, clipping, illegible scale, background or opacity differing from the FigureSpec, or wrong aspect ratio;
- style drift in composition, fills, strokes, typography, illustration language, or density.

Emit RenderAudit@2 following `render-audit.md`: bind exact image/spec SHA-256,
separate spec_validation from image_inspection, and cover every required node and
edge with pass/fail/unverified evidence. Scan for extra and forbidden relations.
Do not accept a render merely because the API returned successfully, the spec
validated, or a previous image passed.

## Targeted image revision

When defects are repairable:

1. Select the best current render, not automatically the newest failed revision.
2. Inspect that render at original detail before writing the edit instruction.
3. Invoke the same native `image_gen.imagegen` / `image_gen__imagegen` interface in
   **edit mode**, with the checked current render as the first local reference
   image. Include a style reference only when style drift is one of the audited
   defects.
4. Write a surgical internal edit instruction containing the observed defect, its exact correction, and explicit critical edge endpoints/directions/types, labels and authority
   boundaries that must remain unchanged.
5. Prefer “remove incorrect edge X; add edge A → B with a dashed purple line; preserve all other nodes, labels, positions, and colors” over regenerating the entire design.
6. Save the result as a new revision; never overwrite the only known-good image.
7. Reinspect the edited output at original detail, reset every ledger status, and
   emit a newly bound RenderAudit@2. Check every required edge, including those
   outside the edited region. A change passes only when it fixes the target without regressing topology, text, layout, or style elsewhere.

Use this control loop:

```text
initial generation (r0)
  -> inspect at original detail
  -> RenderAudit@2
  -> pass: select and deliver
  -> fail, repairable, edits_used < 2:
       edit best current render -> r1/r2 -> reinspect -> new audit
  -> fail, exact text remains unreliable:
       deterministic text/line overlay or deterministic renderer
  -> fail after limit:
       select best recoverable revision and disclose residual defects
```

Allow at most two semantic edit rounds after the initial image. A transient transport failure may be retried once and does not consume a semantic edit round. If the second semantic edit still fails, keep the best image and report remaining defects rather than silently looping.

## Text-heavy figures

Native image generation does not guarantee exact typography. If required labels remain wrong after one targeted edit, switch to a deterministic SVG/drawio/Typst text overlay or renderer when available. Do not spend repeated image edits on dense prose, formulas, tables, or exact numeric charts.

## Files and delivery

- Leave Codex's original generated asset in place.
- Use recoverable revision names such as `fig1-r0.png`, `fig1-r1.png`, and `fig1-r2.png`; copy the selected result to FigureSpec's stable final path.
- Sanitize metadata on delivery: run `clean_image_metadata.py` (or `strip_image_metadata`) on the final deliverable to strip all C2PA, EXIF, and provenance markers, ensuring clean, publication-ready images.
- After all delivery-file transformations, inspect that exact file and bind its
  final RenderAudit@2. Validate the record using workflow's
  `scripts/validate_render_audit.py --spec <spec.json> --image <image.png> <audit.json>`.
  This checks record integrity, not pixels or scientific truth.
- Keep the initial render, prior revisions, FigureSpec, and RenderAudit records together when practical.
- Never leave the only deliverable in a temporary directory.
- Return or display the final image artifact and a clickable absolute local file
  path. Do not use `file://`. Never append, quote, or otherwise expose the internal
  prompt when prompt review was waived.

# Missing-Info Policy

Shared by all academic-figure skills. Domain skills add only their own cases.

## Rule

When evidence is incomplete: ship a **conservative, useful** partial result. Label every claim beyond evidence as `推断` or `待确认`. Prefer placeholders over invention.

## Completeness block (every deliverable)

```
- 已分析材料: ...
- 当前输出类型: 完整 / 阶段性 / 局部 / 骨架
- 高置信信息: ...
- 待确认信息: ...
- 建议补充材料: 1–3 highest-value items
```

## Stop vs continue

| Situation | Action |
|-----------|--------|
| Core deliverable possible with placeholders | continue |
| Zero usable source (no paper, repo, figure type, or image) | stop; list minimum materials |
| User asked only this stage | stop after that stage |
| Next stage needs material user has not provided | stop; do not invent |

## Invention ban

Do not invent modules, losses, dimensions, experiment results, or architecture layers that never appear in the source. Rewrite unknowns as explicit placeholders (`[module_name]`, `R^(?×?)`).

# Academic Palettes — Single Source of Truth

This file defines **12 classic presets**, three pastel-airy schemes, and paired illustrated semantic-zone tokens. Skills that need hex values or style routing should load this file rather than maintaining private copies.

## Decision order

Apply evidence in this order:

1. explicit user colors, style, print, and accessibility requirements
2. supplied reference image grammar
3. hard production constraints such as grayscale output and text contrast
4. figure semantics and visual-zone relationships
5. an existing paper-wide visual system or explicit submission rule
6. conservative default

A reference image is the highest-priority inferred style source. Extract composition, panel surfaces, outline strength, shadow treatment, typography character, icon style, nesting depth, density, arrow grammar, and paired fill/outline colors. Match those properties without copying the reference's labels, branded assets, or method content.

`module_count` is a density clue only. It does not trigger monochrome. Choose hue count from the number and relationship of semantic zones shown in the figure.

| Missing evidence | Conservative default |
|---|---|
| No reference or style cue, classic technical figure | **Okabe-Ito** |
| Explicit airy UI/token figure | **P2 Cool Research** |
| Narrative framework or agent/scientific workflow | **I1 Illustrated Zones** |
| Accessibility unspecified | colorblind-aware dual encoding and validated text contrast |

Always state the branch (`user`, `reference`, `scene`, or `default`) and offer one alternate.

## Style profiles first

Palette values only make sense with a surface and line treatment. Select a profile before assigning tokens.

| Signals | Profile | Primary skill | Visual grammar |
|---|---|---|---|
| technical stack, compact network, classic vector, strict print | **`classic-technical`** | `academic-figure-designer` | restrained geometry, fine borders, white or near-white modules, compact sans labels |
| airy, token flow, interface-like, soft cards | **`pastel-airy-ui`** | `academic-figure-designer` | white cards, subtle border/shadow, floating pills and tokens, generous whitespace |
| hand-drawn academic infographic, modular narrative, agent/scientific workflow, tinted zones | **`illustrated-modular`** | `academic-figure-designer` | asymmetric hero layout, soft semantic-zone fills, strong same-hue outlines, no shadow, one-level subcards, controlled line illustrations |
| supplied reference does not fit one preset | **`reference-led`** | `academic-figure-designer` | override defaults with observed grammar; do not assume an illustrated surface |

Do not force a supplied reference into a binary classic/pastel label. A coherent figure may combine a classic flat canvas, tinted modular zones, and hand-drawn illustrations. State the observed properties so the combination is intentional rather than a style-word mixture.

### Pastel airy UI schemes

Small body text remains neutral `#24323D`. The colored values below are heading accents on white; validate them again before placing small text on a tinted token.

| Scheme | Scene | Soft fills | Accessible heading accents on white |
|---|---|---|---|
| **P1 Warm ML** | playful, teaching, human-centered | `#FFD0D0` `#BBDEFB` `#FFF3C4` `#E1BEE7` `#C8E6C9` | `#A93636` `#146C61` `#6A5ACD` `#2F7430` |
| **P2 Cool Research** | calm token-centric research figure | `#B3E5FC` `#C5CAE9` `#CFD8DC` `#B2DFDB` `#D1C4E9` | `#1565C0` `#3949AB` `#006F65` |
| **P3 Earthy Warm** | natural or embodied visual direction | `#FFE0B2` `#D7CCC8` `#C8E6C9` `#E0E0E0` `#EFEBE9` | `#6D4C41` `#827717` `#2E7D32` |
| **P4 Airy Agentic BO** | surrogate backend, agent decision, charcoal eval anchor | `#FAE8DC` (Peach) `#DBE7FB` (Periwinkle) `#4B5563` (Slate) `#E9E9EC` (Gray) | `#1E293B` `#0F172A` `#FFFFFF` `#334155` |

If a reference is present, derive its token pairs instead of snapping every soft figure to the nearest P1–P4 scheme.

---

## I1 Illustrated Zones — paired semantic tokens

Each token is a coordinated surface system rather than a standalone accent. `title_text` values meet normal-text contrast against their paired fills; small body text may use neutral `#24323D` throughout.

| Token | `soft_fill` | `dark_outline` | `title_text` | `icon_accent` |
|---|---|---|---|---|
| **I1 Blue** | `#EDF4FB` | `#194166` | `#163E64` | `#2E6B9E` |
| **I1 Green** | `#F3FBF0` | `#3B7D23` | `#2F681D` | `#4E8D36` |
| **I1 Peach** | `#FBE3D6` | `#A94417` | `#9E3F13` | `#C65A22` |
| **I1 Purple** | `#F5ECF5` | `#77206E` | `#65185E` | `#8B3B83` |
| **I1 Cyan** | `#DBF3FE` | `#236E96` | `#195876` | `#2F81A8` |
| **I1 Gold** | `#FBF1D1` | `#856B1B` | `#66500F` | `#9B7B1C` |
| **I1 Coral** | `#FDE8E5` | `#B83A2F` | `#8F2A24` | `#C94D42` |

Recommended material treatment: white canvas; 1.5–2.5px zone outlines; 6–14px corner radius scaled to output size; no drop shadows; white or lighter same-hue subcards; dark neutral arrows `#334155` unless the edge itself carries a zone meaning.

## Semantic color binding contract

Bind tokens to the roles present in the current paper and retain those bindings across its figures. The mappings below are customizable defaults across different scientific domains:

### 1) Standard Multi-Stage Pipeline & Modular Systems
| Domain Role / Stage | Suggested Illustrated Token | Classic/Airy Adaptation |
|---|---|---|
| **Stage 1: Input / Raw Data / Context** | I1 Green (`#F3FBF0` / `#3B7D23`) | Green accent / data pill |
| **Stage 2: Representation / Encoders** | I1 Blue (`#EDF4FB` / `#194166`) | Blue outline / primary container |
| **Stage 3: Core Mechanism / Transformation** | I1 Peach (`#FBE3D6` / `#A94417`) | Orange/peach hero zone |
| **Stage 4: Optimization / Supervision / Loss** | I1 Purple (`#F5ECF5` / `#77206E`) | Purple accent / dashed constraint |
| **Stage 5: Output / Evaluation / Benchmark** | I1 Gold (`#FBF1D1` / `#856B1B`) | Gold heading / output badge |

### 2) Deep Learning & Neural Architectures
| Architecture Component | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **Raw Input / Embeddings / Tokens** | I1 Green | Structured grid, token pill, or feature map |
| **Backbone / Feature Extractor** | I1 Blue | Layered orthogonal blocks or stacked cards |
| **Cross-Modal Fusion / Attention Core** | I1 Peach | Heatmap matrix or bipartite connection web |
| **Loss Function / Objective / Regularizer** | I1 Purple | Mathematical constraint box or curve |
| **Prediction Head / Downstream Task** | I1 Gold | Terminal prediction pill or task badge |

### 3) Agentic & Scientific Interactive Loops
| Agentic Role | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **Reasoning / Policy / Planner** | I1 Blue | Decision glyph, thought bubble, or planning box |
| **Evidence / Context / Observation** | I1 Green | Document icon, coordinate plot, or context card |
| **Deterministic Harness / Tool Execution**| I1 Peach | Solid process container or simulation box |
| **Advisory / Feedback / Uncertainty** | I1 Purple | Dashed feedback arrow or advisory pill |
| **Memory / Storage / Provenance** | I1 Cyan | Network graph or database/checkpoint cylinder |
| **Final Output / Report** | I1 Gold | Formatted report card or badge |
| **Exception / Guardrail / Stop** | I1 Coral | Warning badge or coral STOP boundary |

### 4) Dual-Fidelity & Bayesian Optimization Loops
| Optimization Role | Suggested Illustrated Token | Visual Metaphor / Shape |
|---|---|---|
| **High-Fidelity / Real-World Experiment / Discrepancy** | I1 Coral (`#FDE8E5` / `#B83A2F`) | Laboratory glassware, oscilloscope/monitor, focused residual peak $\mathcal{X}_R^*$ |
| **Low-Fidelity / LLM Prior / Global Surrogate** | I1 Blue (`#EDF4FB` / `#194166`) | Electronic brain, prompt balloon, 3D smooth GP surface |
| **Candidate Selection / Acquisition Function** | I1 Peach (`#FBE3D6` / `#A94417`) | 1D search curve, peak marker $x^*$, candidate generator table |
| **Gating Criterion / Adaptive Decision** | Decision Diamond (Neutral/Red/Green) | Diamond node $p_\Delta < \tau$, green checkmark / red cross status badges |
| **Prior Domain Knowledge / Constraints** | I1 Green / Slate (`#F3FBF0` / `#3B7D23`) | Literature stack, coordinate scatter plot, constraint box |

Repeated roles reuse a token; adjacent unrelated zones should also differ by label, geometry, or line style.

---

## Scene → profile and palette decision

After explicit user and reference-grammar requirements, apply production constraints and then choose from figure semantics. Venue and domain are suggestions, not guarantees of a single visual style.

### 1) Hard constraints

| Constraint | Choose | Alternate |
|------------|--------|-----------|
| Strict B&W / grayscale print only | **Print-Safe Gray** | Grayscale |
| Theory paper, no color budget | **Grayscale** | Print-Safe Gray |
| Color-vision accessibility required or prudent | Start from Okabe-Ito / ML TopConf Colorblind / a verified monochrome ramp, then dual-encode and test | Never treat a palette name as proof of accessibility |
| Must match existing Matplotlib Tab10 experiment plots | **ML TopConf Tab10** | ML TopConf Colorblind if a11y matters more than match |
| Reference has tinted zones and strong outlines | **Illustrated modular + derived pairs** | I1 Illustrated Zones |

### 2) Figure type

| Figure type | Prefer | Alternate | Why |
|-----------|--------|-----------|-----|
| Overall Framework, technical pipeline | Okabe-Ito | ML TopConf Colorblind | clear categorical accents |
| Overall Framework, modular narrative | **Illustrated modular + I1** | reference-derived pairs | semantic zones and hierarchy |
| Network Architecture | Okabe-Ito or Blue Monochrome | Nature Blue for a restrained single-family stack | structure > decoration |
| Module Detail | **Blue Monochrome** | Okabe-Ito | detail density; gray-print friendly |
| Comparison / Ablation (few panels) | Purple-Green | Okabe-Ito | category contrast |
| Dense multi-panel ablation | **ML TopConf Deep** | Purple-Green | softer multi-hue grid |
| Data Behavior (curves / heatmaps / t-SNE) | ML TopConf Colorblind | Okabe-Ito | series/categories stay separable |
| Qualitative image grids | Okabe-Ito accents only | Grayscale frames | color on labels, not photo washes |

### 3) Venue and domain constraints

Do not map a venue or research domain directly to a palette. Use venue/domain
information only when it supplies a concrete production constraint: an official
grayscale rule, an existing paper-wide color system, a required plot palette,
an accessibility requirement, or a reference figure. Otherwise choose from the
content relationships above. “Nature”, “CVPR”, “biology”, “materials”, or
“robotics” alone is not a color instruction.

### 4) Vibe words → concrete choice

| User says | Family | Palette / scheme |
|-----------|--------|------------------|
| 高级 / 克制 / 顶刊 | ask for observable traits or use a supplied reference | no venue-name palette default |
| 科技感 / 工程感 / 干净 | `classic-technical` | Blue Monochrome or Okabe-Ito |
| 柔和 / 空气感 / token 卡片 | `pastel-airy-ui` | P2 |
| 手绘 / 叙事 / 模块拼图 / agent 框架 | `illustrated-modular` | I1 or reference-derived pairs |
| 活泼 / 教学感 | `pastel-airy-ui` or `illustrated-modular` | P1 or reference-derived pairs |
| 自然 / 生物感 | classic Warm Earth, airy P3, or illustrated zones | state accessibility tradeoff |
| 不要花 | any coherent profile | reduce active semantic zones; monochrome only if hierarchy remains clear |
| 和实验曲线一个色 | `classic-technical` | ML TopConf Tab10 / Colorblind |
| 黑白印刷 | `classic-technical` | Print-Safe Gray / Grayscale |

---

## Worked decision recipes

| Scenario | Family | Palette | One-line reason |
|----------|--------|---------|-----------------|
| Technical three-stage method pipeline, no reference | `classic-technical` | Okabe-Ito | categorical accents and compact geometry |
| Modular agent/scientific framework, no reference | `illustrated-modular` | I1 Illustrated Zones | semantic zones plus asymmetric hierarchy |
| Reference with tinted panels and dark outlines | `reference-led` (observed illustrated grammar) | derived paired tokens | preserve observed visual grammar without assuming every reference is illustrated |
| Dense 2×3 ablation grid | `classic-technical` | ML TopConf Deep | multiple comparable panels |
| Token-flow explainer with white cards | `pastel-airy-ui` | P2 | token-centric surface grammar |
| Continuous single-family mechanism with an explicit restrained-blue preference | `classic-technical` | Nature Blue | user request and hierarchy support one hue family |
| Strict B&W journal output | `classic-technical` | Print-Safe Gray | hard print constraint |
| Human-centered concept diagram | `pastel-airy-ui` or reference-supported `illustrated-modular` | content/reference dependent | distinguish UI cards from narrative zones |
| High-density module detail with no reference | `classic-technical` | Blue Monochrome or accessible custom | detail density and print behavior |
| User: 配色随便 | profile from content; Okabe-Ito/P2/I1 | profile default | safe default branch |

---

## Decision checklist (emit with every Palette Decision)

1. Explicit user constraints recorded.
2. Reference grammar summarized, or `no reference supplied`.
3. Canonical profile: `classic-technical` / `pastel-airy-ui` / `illustrated-modular` / `reference-led`.
4. Hard constraint fired? (print / accessibility / match existing plots).
5. Semantic zones and color carriers identified.
6. Primary + alternate named with exact classic colors or paired tokens.
7. Small-text contrast and grayscale dual encoding checked.
8. Branch stated: `user` / `reference` / `scene` / `default`.


## Palette Decision handoff

Downstream skills consume:

```
style_profile: <classic-technical | pastel-airy-ui | illustrated-modular | reference-led>
style_preset: <named library variant | none>
reference_grammar: <summary | none>
palette_or_token_set: <name>
canvas / body_text / arrow / divider: <hex>
semantic_zone_tokens:
  <role>: {soft_fill: <hex>, dark_outline: <hex>, title_text: <hex>, icon_accent: <hex>}
reason: <one line>
accessibility: colorblind-aware-tested | needs dual encoding/testing | print-only
```

---

## 1. Okabe-Ito — default polychrome

**Use:** general categorical starting palette when several roles need distinct hues; always add non-color cues and test the rendered figure

| role | hex | use |
|------|-----|-----|
| primary | `#0072B2` | core module borders, section labels |
| secondary | `#E69F00` | secondary borders, alternate highlight |
| tertiary | `#009E73` | output / result (sparse) |
| text | `#333333` | body text |
| fill | `#FFFFFF` | canvas / boxes |
| section_bg | `#F7F7F7` | region grouping |
| border | `#767676` | semantic outline (4.54:1 on white) |
| arrow | `#4D4D4D` | arrows / lines |

---

## 2. Blue Monochrome

**Use:** module detail; grayscale-friendly journals

| role | hex |
|------|-----|
| primary | `#1565C0` |
| secondary | `#42A5F5` |
| tertiary | `#90CAF9` |
| text | `#212121` |
| fill | `#FFFFFF` |
| section_bg | `#F5F8FC` |
| border | `#607D8B` |
| arrow | `#37474F` |

---

## 3. Warm Earth

**Use:** explicit earth-toned user/reference direction. Dual-encode; do not infer this palette from a research domain alone.

| role | hex |
|------|-----|
| primary | `#C0392B` |
| secondary | `#E67E22` |
| tertiary | `#F39C12` |
| text | `#2C2C2C` |
| fill | `#FFFFFF` |
| section_bg | `#FDF6EC` |
| border | `#8D6E63` |
| arrow | `#5D4037` |

---

## 4. Purple-Green

**Use:** two-category comparison or ablation when purple/green fits the labels and reference; never bind a hue to “ours” without the spec

| role | hex |
|------|-----|
| primary | `#6A1B9A` |
| secondary | `#2E7D32` |
| tertiary | `#AB47BC` |
| text | `#1A1A1A` |
| fill | `#FFFFFF` |
| section_bg | `#F8F5FC` |
| border | `#7B1FA2` |
| arrow | `#4A148C` |

---

## 5. Grayscale

**Use:** explicit grayscale/print-only requirement or a user-selected austere monochrome treatment

| role | hex |
|------|-----|
| primary | `#212121` |
| secondary | `#616161` |
| tertiary | `#9E9E9E` |
| text | `#111111` |
| fill | `#FFFFFF` |
| section_bg | `#F5F5F5` |
| border | `#757575` |
| arrow | `#424242` |

Distinguish categories by shape / line weight, not hue.

---

## 6. Teal-Coral

**Use:** explicit teal/coral two-category contrast. Dual-encode and test for color-vision deficiencies.

| role | hex |
|------|-----|
| primary | `#00695C` |
| secondary | `#E64A19` |
| tertiary | `#26A69A` |
| text | `#212121` |
| fill | `#FFFFFF` |
| section_bg | `#F0F9F8` |
| border | `#00796B` |
| arrow | `#004D40` |

---

## 7. ML TopConf Tab10

**Use:** match an existing Matplotlib Tab10 experiment palette; do not choose from venue name alone

| role | hex |
|------|-----|
| primary | `#1F77B4` |
| secondary | `#FF7F0E` |
| tertiary | `#2CA02C` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 8. ML TopConf Colorblind

**Use:** muted colorblind-aware categorical starting palette; still requires dual encoding and rendered-output checks

| role | hex |
|------|-----|
| primary | `#0173B2` |
| secondary | `#DE8F05` |
| tertiary | `#029E73` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 9. ML TopConf Deep

**Use:** multi-panel ablation / dense comparison grids

| role | hex |
|------|-----|
| primary | `#4C72B0` |
| secondary | `#DD8452` |
| tertiary | `#55A868` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

---

## 10. Print-Safe Gray

**Use:** explicit strict black-and-white print requirement

| role | hex |
|------|-----|
| primary | `#000000` |
| secondary | `#333333` |
| tertiary | `#666666` |
| text | `#333333` |
| fill | `#FFFFFF` |
| section_bg | `#F7F7F7` |
| border | `#666666` |
| arrow | `#4D4D4D` |

---

## 11. Journal Standard

**Use:** figures with several verified categories that genuinely need additional accents; not a journal-name default

| role | hex |
|------|-----|
| primary | `#1F77B4` |
| secondary | `#FF7F0E` |
| tertiary | `#2CA02C` |
| accent1 | `#D62728` |
| accent2 | `#9467BD` |
| accent3 | `#8C564B` |
| text | `#1F2937` |
| fill | `#FFFFFF` |
| section_bg | `#F8FAFC` |
| border | `#64748B` |
| arrow | `#334155` |

Activate only the category colors needed by the current comparison and repeat them consistently.

---

## 12. Nature Blue — restrained monochrome

**Use:** a continuous single-family hierarchy, an explicit restrained-blue direction, matching reference grammar, or verified grayscale-friendly output. Do not select it from module count, venue, or domain alone.

| role | hex |
|------|-----|
| primary | `#1B3A5C` |
| secondary | `#2E6B9E` |
| tertiary | `#5BA0D0` |
| gray | `#8EAEC4` |
| text | `#333333` |
| fill | `#FFFFFF` |
| section_bg | `#F7F7F7` |
| border | `#5B7890` |
| arrow | `#4D4D4D` |

---

## Monochrome vs semantic-zone color

| | monochrome (Blue Monochrome / Nature Blue) | semantic-zone color (Okabe-Ito / I1 / custom pairs) |
|---|---|---|
| visual unity | one hue family | coordinated role-based pairs |
| separation | lightness + border + label | fill/outline pair + label + shape |
| best when | hierarchy within one conceptual family | readers must scan distinct subsystems or decisions |
| print / colorblind | usually robust after value check | robust when dual-encoded and contrast-checked |

---

## Production checks

- Preserve explicit user constraints and reference-image grammar unless accessibility or print requirements require an explained adjustment.
- Use white, near-white, or soft tinted panel surfaces according to the selected profile; tinted semantic zones are valid academic material.
- Use the fewest semantic tokens that keep roles easy to scan, without an arbitrary module-count or three-hue cutoff.
- Dual-encode important categories with label, shape, border, icon, or line style in addition to color.
- Normal-size text and its actual background should meet a 4.5:1 contrast target; do not use pale accent colors for small text.
- Essential outlines, arrow shafts/heads, markers, and focus boundaries should meet a 3:1 graphical contrast target against adjacent colors. Lighter dividers may be decorative only and must not carry meaning.
- Avoid unintentional gradients, glossy 3D chrome, photorealistic decoration, and rainbow ordering. Follow a supplied reference when a different treatment is deliberate and legible.
- Check the downscaled figure and a grayscale preview before handoff.

## Custom palette minimum

```
style_profile: <name>
canvas: #XXXXXX
body_text: #XXXXXX
arrow: #XXXXXX
semantic_zone:
  soft_fill: #XXXXXX
  dark_outline: #XXXXXX
  title_text: #XXXXXX
  icon_accent: #XXXXXX
```

Add only the semantic zones the figure needs. Validate text contrast, colorblind distinguishability, and grayscale reproduction before handoff.

# Render Audit Protocol

Use this protocol after every generated academic figure and after each targeted
edit. A successful image-generation API response is not evidence that the figure
is correct. Inspect the image at original resolution and compare it with the
confirmed FigureSpec, source evidence, and any reference image.

## Inputs and output

Required inputs:

- the validated `academic-figure/FigureSpec@1` object;
- the rendered image at an absolute local path;
- source figure plan and evidence locations;
- reference images when `style_profile` is `reference-led`.

Emit a JSON-compatible audit:

```text
schema: academic-figure/RenderAudit@2
figure_id, render_revision, image_path (absolute)
image_sha256, spec_sha256 (lowercase SHA-256 of exact file bytes)
spec_validation: {status: pass|fail|unverified}
image_inspection: {status: pass|fail|unverified, evidence}
nodes[]: {id, status: pass|fail|unverified, evidence}
edges[]: {id, from, to, kind, direction, line, label,
          status: pass|fail|unverified, evidence}
checks:
  semantic_topology, visible_text, background, layout,
  style_fidelity, accessibility
  (each check is {status: pass|fail|unverified, evidence})
pass: true|false
defects[]: {check, severity, observed, expected, evidence, edit_instruction}
targeted_edit: string|null
semantic_edits_used: 0|1|2
semantic_edits_remaining: 2|1|0
residual_risks[]
```

## Revision binding and complete ledgers

New audits use RenderAudit@2. Keep legacy @1 records for history, but do not
upgrade their booleans mechanically into observed @2 results. Bind each audit to
one actual image and one actual FigureSpec by path, revision, and raw-file
SHA-256. Finish any export/metadata transformation before binding the delivered
file, then inspect that exact final file. A new file or changed spec needs a new
audit; do not copy forward a previous image's pass.

FigureSpec validation and actual image inspection are independent. Record their
statuses separately. If the image cannot be opened, or an arrowhead is too
ambiguous to identify, use `unverified`, not a guessed `pass`. Evidence describes
what was inspected, including region or endpoints; “spec valid” is not visual
evidence. Image inspection status says whether inspection was performed; defects
found during inspection belong in the individual check statuses.

Derive the complete node and edge ledger from the spec, not from what is easiest
to see. Cover every component and every connection exactly once. Use declared
edge IDs; for a legacy connection without an ID, use its stable one-based position
as `edge_001`, `edge_002`, etc. Copy from/to/kind/direction/line/label exactly;
for omitted direction/line use `unspecified`, and omitted label is an empty
string. Semantic kind remains required. This does not authorize rendering a scientifically ambiguous spec.

Check the image against the ledger, then scan the image for extra edges and
forbidden shortcuts; a required-edge ledger alone cannot detect invented arrows.
Record that second scan and authority-boundary checks under semantic_topology.
Record the actual text-inventory and final-size inspection under the relevant
checks. Reset all statuses to unverified for every new image, including style-only
and single-arrow edits, and recheck all required edges outside the edited region.

For the bundled record validator (it does NOT inspect pixels), run:

```bash
python3 <workflow>/scripts/validate_render_audit.py \
  --spec <spec.json> --image <image.png> <audit.json>
```

Exit 0 means the bound record is complete and all asserted statuses pass; exit 1
means a valid record is failed/unverified; exit 2 means malformed, incomplete or
mismatched evidence, including a stale digest or misleading aggregate pass.
When workflow's script is not installed, perform the same ledger checks manually
and state that record validation was manual. Never call this script's exit 0
proof of scientific accuracy or image quality: it cannot verify the truthfulness
of a human/model's visual assertions.

A legal top-level `pass: true` requires all node/edge/check statuses, spec
validation and image inspection to pass, with no critical or major defect.
Any fail or unverified status blocks acceptance. A complete record of a failed
image is useful and must remain failed.

`severity` is `critical`, `major`, or `minor`. A critical or major defect makes
the audit fail. Minor defects may pass only when they do not change scientific
meaning, legibility, accessibility, or the requested visual identity.

## 1. Semantic topology

Treat the FigureSpec component and connection lists as a directed graph.

- Every required component appears exactly once unless duplication is explicitly
  specified as a repeated stage.
- Every rendered arrow has the correct source, target, direction, kind, and label.
- Required branches, loops, authority boundaries, budget effects, and persistence
  paths are present.
- Forbidden components, connections, causal implications, performance claims, and
  copied scientific content are absent.
- Advisory, executed, feedback, persistence, and exception paths remain visually
  distinguishable according to the spec.

Any missing, invented, reversed, or merged scientific edge is a **critical**
defect. Do not approve a visually attractive but semantically incorrect render.

## 2. Visible text

Compare the image against the complete `visible_text` inventory, using visual
inspection and OCR when available.

- Every required string is present, spelled correctly, and assigned to the right
  component or connection.
- No JSON keys, prompt instructions, hex codes, production notes (`WHITE FILL`,
  `300 DPI`, stroke widths), watermarks, or unexplained text are visible.
- No duplicated, truncated, fused, hallucinated, or illegible labels remain.
- Mathematical symbols, identifiers, capitalization, and branch labels preserve
  their specified meaning.
- Text remains readable at the intended 89 mm or 183 mm publication width, not
  merely when zoomed to the generation resolution.

Scientific text errors are critical. Optional secondary-label loss is major when
it damages interpretation and minor only when the FigureSpec marks it optional.

## 3. Background and artifact integrity

- Canvas dimensions match the requested aspect ratio within raster rounding.
- The background is the specified solid color; when white is required, corner and
  inter-panel pixels are opaque `#FFFFFF`, not transparent, gray, or black.
- No accidental alpha channel, crop, border, compression damage, checkerboard,
  watermark, or model signature is present.
- Metadata and provenance cleanliness: sanitize and strip all C2PA manifests, JUMBF markers, EXIF, and AI generation metadata using `clean_image_metadata.py` before final delivery.
- The file extension matches the encoded media type and the image opens normally.

A background or opacity that differs from the FigureSpec, a wrong crop, or a
wrong aspect ratio is a major defect. A file that cannot be decoded is critical.

## 4. Layout and publication-scale legibility

- Components follow the planned reading order, grouping, hierarchy, focal point,
  and relative emphasis.
- Boxes, illustrations, labels, legends, and arrowheads do not overlap or collide.
- Connections do not ambiguously cross nodes or terminate in empty space.
- Margins and whitespace are intentional; the figure is neither an empty template
  nor a uniformly dense wall of boxes.
- Primary information survives a thumbnail/publication-width check; secondary
  detail may recede but must not become visual noise.
- Repeated elements align consistently while semantic exceptions remain salient.

Overlap that hides meaning or an ambiguous connector is major. Minor alignment
variation is minor only when the intended reading order stays unambiguous.

## 5. Style fidelity

For a built-in profile, check the profile's composition, marks, strokes, fills,
typography, spacing, motifs, and emphasis—not just its named colors. For a supplied
reference, compare transferable visual grammar while keeping the new method's
content and topology independent.

- Composition and visual hierarchy match the selected profile or reference.
- Palette colors have the specified semantic roles and relative area; do not wash
  every region with equally saturated color.
- Stroke language, arrow curvature, illustration level, panel treatment, corner
  geometry, typography character, and whitespace match the intended family.
- Absent traits from the reference stay absent: do not add enterprise swimlanes,
  heavy dark borders, gradients, shadows, 3-D chrome, clip art, or generic robot
  motifs unless the profile calls for them.
- A reference's labels, metrics, branding, scientific objects, and topology are not
  copied merely to imitate its appearance.

A palette match with the wrong composition or mark language does **not** pass style
fidelity. Clearly landing in the wrong style family is major.

## 6. Accessibility and print behavior

- Normal-size text has at least 4.5:1 contrast against its actual background;
  large text has at least 3:1.
- Essential outlines, arrows, markers, and focus boundaries have at least 3:1
  graphical contrast against adjacent colors; pale decorative dividers do not
  carry semantic meaning.
- Critical distinctions use color plus a second cue such as label, shape, marker,
  hatching, or line style.
- Simulated protanopia, deuteranopia, and tritanopia views preserve required
  distinctions when a simulation tool is available.
- A grayscale preview preserves topology, grouping, and exception branches.
- Thin strokes, pale tokens, and small type remain discernible at publication size.

Record the measured foreground/background pairs when contrast tooling is
available. Never infer accessibility from a palette name alone.

## Targeted-edit policy

The initial render may receive **at most two targeted semantic visual edits**.
A single retry for a transient API/transport failure does not consume this
budget because it did not attempt to change the image semantics.

1. Audit the initial render and rank defects by semantic risk.
2. If it fails, write one bounded edit instruction containing only the observed
   defects, their exact expected replacements, and an explicit list of critical nodes, edge endpoints/directions/types,
   visible labels and authority boundaries to preserve. “Keep everything else”
   alone is not a preservation contract.
3. Inspect the edited image and emit a newly bound audit. Recheck the full
   required edge ledger, not just the repaired connector; do not assume an edit
   preserved topology or text.
4. If needed, perform one final targeted edit, then audit again.
5. After two targeted edits, stop. Deliver the best valid artifact only if all
   critical and major checks pass; otherwise mark the render incomplete and report
   residual defects instead of silently accepting it or starting an unbounded loop.

Do not use a whole-image style rewrite to repair one spelling error or connector.
Conversely, do not patch isolated colors when the audit shows the entire style
family or composition is wrong; use the first targeted edit to correct that bounded
systemic defect and preserve grounded content.

#!/usr/bin/env python3
"""Validate a RenderAudit@2 record against an exact spec and image artifact.

This checker validates record completeness, consistency, and byte-level binding.
It does not inspect pixels and cannot prove that human/agent assertions are true.
Use alongside actual image inspection and the separate FigureSpec validator.

Exit codes: 0 = complete passing record; 1 = valid but failed/unverified record;
2 = malformed, incomplete, incorrectly bound, or inconsistent record.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any


SCHEMA = "academic-figure/RenderAudit@2"
STATUSES = frozenset({"pass", "fail", "unverified"})
CHECKS = (
    "semantic_topology", "visible_text", "background", "layout",
    "style_fidelity", "accessibility",
)
EDGE_FIELDS = ("from", "to", "kind", "direction", "line", "label")


@dataclass
class AuditReport:
    errors: list[str] = field(default_factory=list)
    nonpassing: list[str] = field(default_factory=list)

    @property
    def exit_code(self) -> int:
        return 2 if self.errors else (1 if self.nonpassing else 0)

    @property
    def passed(self) -> bool:
        return self.exit_code == 0


def _text(value: Any) -> bool:
    return isinstance(value, str) and bool(value.strip())


def _read_json(path: Path, name: str, report: AuditReport) -> tuple[Any, bytes]:
    try:
        raw = path.read_bytes()
        value = json.loads(raw)
    except (OSError, ValueError, UnicodeError, RecursionError) as exc:
        report.errors.append(f"{name}: cannot read JSON: {exc}")
        return None, b""
    if not isinstance(value, dict):
        report.errors.append(f"{name}: root must be an object")
        return None, raw
    return value, raw


def _sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as source:
        for chunk in iter(lambda: source.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _status_record(value: Any, name: str, report: AuditReport, *, evidence: bool = True) -> None:
    if not isinstance(value, dict):
        report.errors.append(f"{name}: must be a status object")
        return
    status = value.get("status")
    if not isinstance(status, str) or status not in STATUSES:
        report.errors.append(f"{name}.status: must be pass, fail, or unverified")
    elif status != "pass":
        report.nonpassing.append(f"{name}: {status}")
    if evidence and not _text(value.get("evidence")):
        report.errors.append(f"{name}.evidence: must be a nonempty string")


def _expected_topology(spec: dict, report: AuditReport) -> tuple[set[str], dict[str, dict]]:
    topology = spec.get("topology")
    if not isinstance(topology, dict):
        report.errors.append("spec.topology: must be an object")
        return set(), {}
    components = topology.get("components")
    connections = topology.get("connections")
    if not isinstance(components, list) or not components:
        report.errors.append("spec.topology.components: must be a nonempty list")
        components = []
    if not isinstance(connections, list):
        report.errors.append("spec.topology.connections: must be a list")
        connections = []
    nodes: set[str] = set()
    for index, component in enumerate(components):
        node_id = component.get("id") if isinstance(component, dict) else None
        if not _text(node_id):
            report.errors.append(f"spec.components[{index}].id: must be a nonempty string")
        elif node_id in nodes:
            report.errors.append(f"spec.components: duplicate id {node_id!r}")
        else:
            nodes.add(node_id)
    edges: dict[str, dict] = {}
    for index, connection in enumerate(connections):
        name = f"spec.connections[{index}]"
        if not isinstance(connection, dict):
            report.errors.append(f"{name}: must be an object")
            continue
        edge_id = connection.get("id", f"edge_{index + 1:03d}")
        if not _text(edge_id):
            report.errors.append(f"{name}.id: must be a nonempty string")
            continue
        if edge_id in edges:
            report.errors.append(f"spec.connections: duplicate id {edge_id!r}")
            continue
        expected = {key: connection.get(key) for key in EDGE_FIELDS}
        expected["line"] = connection.get("line", "unspecified")
        expected["direction"] = connection.get("direction", "unspecified")
        expected["label"] = connection.get("label", "")
        for key in ("from", "to", "kind", "line"):
            if not _text(expected[key]):
                report.errors.append(f"{name}.{key}: must be a nonempty string")
        for endpoint in ("from", "to"):
            if isinstance(expected[endpoint], str) and expected[endpoint] not in nodes:
                report.errors.append(f"{name}.{endpoint}: unknown node {expected[endpoint]!r}")
        if expected["direction"] not in ("forward", "backward", "bidirectional", "unspecified"):
            report.errors.append(f"{name}.direction: invalid direction")
        if not isinstance(expected["label"], str):
            report.errors.append(f"{name}.label: must be a string")
        edges[edge_id] = expected
    return nodes, edges


def _coverage(value: Any, expected: set[str], name: str, report: AuditReport) -> dict[str, dict]:
    if not isinstance(value, list):
        report.errors.append(f"{name}: must be a list")
        value = []
    records: dict[str, dict] = {}
    for index, record in enumerate(value):
        location = f"{name}[{index}]"
        _status_record(record, location, report)
        item_id = record.get("id") if isinstance(record, dict) else None
        if not _text(item_id):
            report.errors.append(f"{location}.id: must be a nonempty string")
        elif item_id in records:
            report.errors.append(f"{name}: duplicate id {item_id!r}")
        else:
            records[item_id] = record
            if item_id not in expected:
                report.errors.append(f"{name}: unknown id {item_id!r}")
    missing = expected - records.keys()
    if missing:
        report.errors.append(f"{name}: missing ids: {', '.join(sorted(missing))}")
    return records


def validate_paths(spec_path: Path, image_path: Path, audit_path: Path) -> AuditReport:
    """Check a saved audit; no computer-vision or renderer is invoked."""
    report = AuditReport()
    spec, spec_raw = _read_json(Path(spec_path), "spec", report)
    audit, _ = _read_json(Path(audit_path), "audit", report)
    if spec is None or audit is None:
        return report
    if spec.get("schema") != "academic-figure/FigureSpec@1":
        report.errors.append("spec.schema: expected academic-figure/FigureSpec@1")
    if audit.get("schema") != SCHEMA:
        report.errors.append(f"audit.schema: expected {SCHEMA}")
    if not _text(spec.get("figure_id")):
        report.errors.append("spec.figure_id: must be a nonempty string")
    if audit.get("figure_id") != spec.get("figure_id"):
        report.errors.append("audit.figure_id: does not match spec")
    if not _text(audit.get("render_revision")):
        report.errors.append("audit.render_revision: must be a nonempty string")

    declared_image = audit.get("image_path")
    if not _text(declared_image):
        report.errors.append("audit.image_path: must be a nonempty string")
    else:
        try:
            candidate = Path(declared_image)
            if not candidate.is_absolute():
                report.errors.append("audit.image_path: must be an absolute path")
            elif candidate.resolve() != Path(image_path).resolve():
                report.errors.append("audit.image_path: does not match --image")
        except (OSError, ValueError, RuntimeError) as exc:
            report.errors.append(f"audit.image_path: cannot resolve: {exc}")

    expected_hashes = {"spec_sha256": hashlib.sha256(spec_raw).hexdigest()}
    try:
        expected_hashes["image_sha256"] = _sha256(Path(image_path))
    except (OSError, ValueError) as exc:
        report.errors.append(f"image: cannot hash file: {exc}")
    for name in ("image_sha256", "spec_sha256"):
        supplied = audit.get(name)
        if not isinstance(supplied, str) or re.fullmatch(r"[0-9a-f]{64}", supplied) is None:
            report.errors.append(f"audit.{name}: must be a lowercase SHA256 digest")
        elif name in expected_hashes and supplied != expected_hashes[name]:
            report.errors.append(f"audit.{name}: does not match artifact bytes")

    _status_record(audit.get("spec_validation"), "spec_validation", report, evidence=False)
    _status_record(audit.get("image_inspection"), "image_inspection", report)
    expected_nodes, expected_edges = _expected_topology(spec, report)
    _coverage(audit.get("nodes"), expected_nodes, "nodes", report)
    edges = _coverage(audit.get("edges"), set(expected_edges), "edges", report)
    for edge_id, record in edges.items():
        if edge_id not in expected_edges:
            continue
        for key in EDGE_FIELDS:
            if key not in record or record[key] != expected_edges[edge_id][key]:
                report.errors.append(f"edges[{edge_id!r}].{key}: does not match spec")

    checks = audit.get("checks")
    if not isinstance(checks, dict):
        report.errors.append("checks: must be an object")
        checks = {}
    for name in CHECKS:
        _status_record(checks.get(name), f"checks.{name}", report)
    # Additional named checks are allowed but cannot hide fail/unverified statuses.
    for name in sorted(set(checks) - set(CHECKS)):
        _status_record(checks[name], f"checks.{name}", report)

    defects = audit.get("defects", [])
    if not isinstance(defects, list):
        report.errors.append("defects: must be a list")
        defects = []
    for index, defect in enumerate(defects):
        if not isinstance(defect, dict):
            report.errors.append(f"defects[{index}]: must be an object")
            continue
        severity = defect.get("severity")
        if severity not in ("minor", "major", "critical"):
            report.errors.append(f"defects[{index}].severity: invalid severity")
        elif severity in ("major", "critical"):
            report.nonpassing.append(f"defects[{index}]: {severity}")
        if not (_text(defect.get("description")) or _text(defect.get("observed"))):
            report.errors.append(f"defects[{index}]: description or observed must be a nonempty string")

    overall = audit.get("pass")
    if not isinstance(overall, bool):
        report.errors.append("audit.pass: must be a boolean")
    elif not report.errors and overall != (not report.nonpassing):
        report.errors.append("audit.pass: inconsistent with statuses and defect severity")
    return report


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--spec", required=True, type=Path)
    parser.add_argument("--image", required=True, type=Path)
    parser.add_argument("audit", type=Path)
    args = parser.parse_args(argv)
    report = validate_paths(args.spec, args.image, args.audit)
    label = {0: "PASS", 1: "NOT ACCEPTED", 2: "INVALID"}[report.exit_code]
    print(f"{label}: audit record ({len(report.errors)} error(s), {len(report.nonpassing)} nonpassing item(s))")
    for error in report.errors:
        print(f"  ERROR: {error}")
    for item in report.nonpassing:
        print(f"  NOT PASSING: {item}")
    print("Record validation only: this does not inspect pixels or verify the truth of inspection evidence.")
    return report.exit_code


if __name__ == "__main__":
    raise SystemExit(main())