78: exam_questions.command_word + preamble (analyse contract v2, WS-2)

Additive/idempotent columns carrying the two fields analyse.py v2 now emits but
v1 dropped: command_word (primary command verb per part) and preamble (stem
prose jsonb sidecar). Applied to dev .94.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GruxHXxfdp4kZCgAMVFgvV

volumes/db/cc/75-exam-marker-region-meta.sql

@@ -0,0 +1,12 @@
+--==========================================================================================
+-- 75. exam_response_areas.meta — rich recognition payload from the extraction service (P2)
+--==========================================================================================
+-- The extraction service (docling-exam-spike analyse contract) returns richer per-region detail than
+-- the thin first-pass could: per-option OMR box geometry + fill (boxes[]), select_n ("tick 2 of 5"),
+-- n_options, the expected unit/quantity for single-line answers, and the data_table an MC question reads.
+-- These have no dedicated columns; keep them in a jsonb sidecar so the canvas can render tick boxes /
+-- units / MC option counts without a column per attribute. Nullable, defaults to {}.
+alter table public.exam_response_areas add column if not exists meta jsonb not null default '{}'::jsonb;
+
+comment on column public.exam_response_areas.meta is
+  'Extraction-service recognition detail: {n_lines, unit, quantity, n_boxes, n_options, select_n, box_form, boxes:[{x0,y0,x1,y1,fill}], table:{grid,n_cells}}. Rendered by the canvas; not authoritative for marking.';

volumes/db/cc/76-exam-marker-extraction-meta.sql

@@ -0,0 +1,11 @@
+--==========================================================================================
+-- 76. exam_templates.extraction_meta — trust signal + provenance from the extraction service (P3)
+--==========================================================================================
+-- Records, per template, how the recognition was produced and whether it reconciled: the audit
+-- cover-total gate (cover_total vs detected_total, status, anomaly), the engine + slug used, and
+-- region counts. Lets the setup UI show "extraction: cover 100 = detected 100 ✓" (or flag an under-read),
+-- and lets the digital-text view resolve the paper's replica by slug. Nullable, defaults to {}.
+alter table public.exam_templates add column if not exists extraction_meta jsonb not null default '{}'::jsonb;
+
+comment on column public.exam_templates.extraction_meta is
+  'Extraction-service provenance + trust gate: {engine, slug, audit:{cover_total,detected_total,status,anomaly}, counts}.';

volumes/db/cc/78-exam-marker-command-preamble.sql

@@ -0,0 +1,20 @@
+--==========================================================================================
+-- 78. exam_questions.command_word + preamble — richer recognition carried by the analyse contract v2 (WS-2)
+--==========================================================================================
+-- The extraction service (docling-exam-spike analyse.py v2, scripts/ANALYSE-CONTRACT.md) now carries two
+-- fields the thin v1 bridge dropped:
+--   * command_word — the primary command verb per part (calculate / explain / suggest / describe …), from
+--     structure.command_words / part_info.primary. Drives the question-tree command pill + future filtering.
+--   * preamble    — the stem prose that introduces a question/part (structure.preamble_by_label), as a
+--     jsonb sidecar {n, text:[…lines], nontext:[{kind,cls,page}], bands:[{page,y0,y1}]}. Kept as jsonb (not
+--     a column per line) so the tree/doc view can show the stem and the canvas can locate its band. The
+--     preamble band is ALSO emitted as a drawable context region (context_type='preamble'); this column is
+--     the authoritative text for the outline view.
+-- Both nullable; containers/parts without a detected command/preamble stay null. Additive + idempotent.
+alter table public.exam_questions add column if not exists command_word text;
+alter table public.exam_questions add column if not exists preamble jsonb;
+
+comment on column public.exam_questions.command_word is
+  'Primary command verb for a leaf part (calculate/explain/suggest/describe/…), from the analyse contract v2 (structure command_words / part_info). Null for container questions or when none detected.';
+comment on column public.exam_questions.preamble is
+  'Stem prose introducing this question/part, from the analyse contract v2 (structure.preamble_by_label): {n, text:[lines], nontext:[{kind,cls,page}], bands:[{page,y0,y1}]}. Authoritative text for the outline view; the band is also drawn as a context_type=preamble region.';