-- 73-exam-marker-regions.sql
-- Extends the exam-marker physical model (72-exam-marker.sql) for the locked S4-9 shape taxonomy
-- (user discussion 2026-06-06; see ~/cc/ideas/2026-06-06-s4-9-design-answers-from-transcript.md).
--
-- Taxonomy: Boundary carves main Questions; a teacher draws a box around each Part; inside a Part
-- live bounded regions of several KINDS. "Band"/"span" are retired. Idempotent (IF NOT EXISTS /
-- drop-and-re-add the named CHECK). Additive on top of 72; safe to re-run.

--==========================================================================================
-- 1. exam_questions: geometry for the drawn Part box (and optional main-question region)
--==========================================================================================
-- Geometry previously lived only on response areas. A Part is now a drawn box, so the question
-- row carries its own bounds + page. Nullable: main questions are derived between their boundaries.
alter table public.exam_questions add column if not exists bounds jsonb;   -- {x,y,w,h}
alter table public.exam_questions add column if not exists page int;

comment on column public.exam_questions.bounds is 'Drawn box for a Part (leaf); null for a derived main question';
comment on column public.exam_questions.page is 'Page index the Part box sits on; null for derived main questions';

--==========================================================================================
-- 2. exam_response_areas: more region kinds + context differentiation
--==========================================================================================
-- v1 keeps one generic Context but plans subject-specific differentiation later
-- (graph, chart, data_table, diagram, code_block, passage, …). Nullable now.
alter table public.exam_response_areas add column if not exists context_type text;

comment on column public.exam_response_areas.context_type is
  'Optional Context differentiation (v1 generic); future: graph|chart|data_table|diagram|code_block|passage';

-- Extend the kind enum. Region kinds now:
--   response        - where the student writes (uses response_form)
--   context         - stimulus the question/part draws on (uses context_type)
--   question_number - bounds the printed label "01" / "2.1" (physical metadata for OCR/AI)
--   mark_area       - bounds the printed marks "[2]" / "Total for Question X is N marks"
--   reference       - formulae/data sheets, appendices the student uses (kept, NOT ignored)
--   furniture       - margins, page numbers, blank space, decoration (explicitly excluded)
alter table public.exam_response_areas drop constraint if exists exam_response_areas_kind_check;
alter table public.exam_response_areas add constraint exam_response_areas_kind_check
  check (kind in ('response','context','question_number','mark_area','reference','furniture'));

comment on column public.exam_response_areas.kind is
  'response|context|question_number|mark_area|reference|furniture (see 73-exam-marker-regions.sql)';