{
  "news_items": [
    {
      "ref": "n1",
      "category": "SCIENCE-&-TECHNOLOGY",
      "headline": "India Launches Its Most Powerful AI Supercomputer",
      "brief_text": "Flattened plain-text walk of the Brief Lexical tree. Image nodes omitted. Inline links preserved as their visible text only."
    },
    {
      "ref": "n2",
      "category": "GEOPOLITICS",
      "headline": "...",
      "brief_text": "..."
    }
  ],
  "document_date": "2026-03-01",
  "audience_hint": "competitive-exam aspirants reading current-affairs newsletters"
}

ROLE: You generate single-sentence factual Q&A items for current-affairs assessment.

TASK: For each item in the `news_items` payload selected for question generation, produce ONE question and ONE answer.

QUESTIONNAIRE LEVEL: Challenging enough to confirm careful reading. Students should not be able to answer correctly from the headline alone — the answer must require attention to the Brief text.

INTERROGATIVE STYLE (pick the one that fits best per item):
  - Who…? / When…? / What…? / Which…? / Where…?
  - According to {source named in the Brief}, {who/what/when/which/where}…?
  - Under which {Section/Regulation/Act/Initiative} … , {who/what/when/which/where}…?
  - Which {initiative/program/policy} was launched to address …?

STRICT RULES:
  1. Each question is a single sentence. No multi-sentence stems.
  2. Each answer is a direct factual phrase: a name, a date, a place, a number, or a specific term.
  3. No preambles in the answer ("According to the newsletter…", "As mentioned…").
  4. If the natural answer exceeds 12 words, return only the most essential portion.
  5. Integrity Always Verified - Each generated item must reference back to the source news_item via `source_refs` (an array of `ref` values copied **verbatim** from the input payload's `news_items[].ref`). NEVER fabricate, modify, or invent a `ref` value.
  6. No two items may share the same `source_refs` set unless explicitly requested.

OUTPUT SHAPE: Conform exactly to the attached JSON Schema for `subjective.straightforward`. See §11.1.

ROLE: You generate four-option multiple-choice questions for current-affairs assessment.

TASK: For each selected news_item, produce ONE MCQ with exactly four options keyed A–D and exactly one correct option.

QUESTIONNAIRE LEVEL: Distractors (the three wrong options) must be plausible domain-adjacent values, not absurd. The correct option must be directly verifiable from the Brief text.

INTERROGATIVE STYLE: Use the same style guide as Template T1 for the question stem.

STRICT RULES:
  1. The stem is a single sentence ending in a question mark.
  2. Exactly four options. Keys MUST be the literal strings "A", "B", "C", "D".
  3. Option values are short phrases — never full sentences, never explanations.
  4. Exactly one option is correct. `correct_option` is one of "A" | "B" | "C" | "D".
  5. Do not include "All of the above" or "None of the above" as values in this template (those belong to Template T3).
  6. Do not reveal the correct answer in the stem.
  7. Reference the source news_item via `source_refs` (an array of `ref` values copied verbatim from the input payload). NEVER fabricate a `ref`.

OUTPUT SHAPE: Conform exactly to the attached JSON Schema for `objective.direct`. See §11.1.

ROLE: You generate statement-analysis questions for current-affairs assessment.

TASK: For each selected news_item, produce ONE item containing:
  - `topic`: a short noun phrase identifying what the statements are about.
  - `statements`: exactly three short, declarative statements derived from the Brief. A mix of true and false (at least one of each) is required.
  - `options`: exactly four entries keyed A–D. Each VALUE must be drawn (without repetition) from the allowed set:
       { "1", "2", "3", "1+2", "2+3", "1+3", "All of the above", "None" }
  - `correct_option`: one of "A" | "B" | "C" | "D".

DISPLAY FORM (assembled by backend, not by the model):
  "Consider the following statements about {topic}:
    1. {statements[0]}
    2. {statements[1]}
    3. {statements[2]}
   Which of the above statements is/are true?"

STRICT RULES:
  1. Exactly three statements. Each a single declarative sentence, ≤ 20 words.
  2. Exactly four options. No duplicate values.
  3. The truth set encoded by `correct_option`'s value must match the actual truth of the statements you wrote (the validator will not check semantic truth, but a clearly inconsistent pairing reduces quality; produce internally consistent items).
  4. Reference the source news_item via `source_refs` (an array of `ref` values copied verbatim from the input payload). NEVER fabricate a `ref`.

OUTPUT SHAPE: Conform exactly to the attached JSON Schema for `objective.statement_analysis`. See §11.1.

{
  "items": [
    {
      "source_refs": ["n1"],
      "statement": "What is the peak performance of India's new AI supercomputer?",
      "answer": "210 petaflops"
    }
  ]
}

{
  "items": [
    {
      "source_refs": ["n2"],
      "statement": "Which planet's moon is NASA's Europa Clipper mission designed to study?",
      "options": { "A": "Mars", "B": "Jupiter", "C": "Saturn", "D": "Neptune" },
      "correct_option": "B"
    }
  ]
}

{
  "items": [
    {
      "source_refs": ["n3"],
      "topic": "the IEEE Global Quantum Internet Standards",
      "statements": [
        "The IEEE standards define a uniform protocol stack for quantum key distribution.",
        "The standards are binding on all member states of the United Nations.",
        "The standards include interoperability requirements for entanglement-based networks."
      ],
      "options": { "A": "1", "B": "1+3", "C": "2+3", "D": "All of the above" },
      "correct_option": "B"
    }
  ]
}

1. Refusal check       → model returned a structured refusal (Structured Outputs surfaces this).
                          If yes  → terminate retry chain; return refusal error to wizard.
                          If no   → continue.

2. Parse JSON          → safe parse. Failure (extremely rare with Structured Outputs)
                          counts as a validation failure, triggers retry (see below).

3. Schema validate     → JSON Schema validation against the requested type
                          (Pydantic model on backend, mirrored Zod on frontend).
                          Hard reject on any schema failure.

4. Business validate   → per-type rules:
   T1: nothing extra beyond schema.
   T2: correct_option ∈ keys(options); options has exactly four keys A/B/C/D;
       no option value repeats; no "All of the above" / "None" in any value.
   T3: statements.length === 3; options has exactly four keys A/B/C/D;
       every options value ∈ allowed_set; no duplicate values; correct_option
       references an existing key.

5. Source linkage     → source_refs (model response field) must be a non-empty
                          subset of the `ref` values supplied in the request
                          payload's news_items[]. Any unknown ref = hard reject
                          (model fabrication); retry. The model NEVER returns
                          atomic_uid values — those are backend-only (see
                          §22B.3.A Identity Boundary).

6. Per-request shape   → number of items returned === number of items requested.
                          Over/under-count is a validation failure.

attempt 0 (primary model)
  ├─ fail → attempt 1 (same model, same prompt unchanged)
  │   ├─ fail → attempt 2 (same model, prompt augmented with
  │   │                   a SYSTEM-level "Your prior response failed
  │   │                   validation: <terse error summary>. Regenerate
  │   │                   strictly per the schema." note)
  │   │   ├─ fail → advance to fallback model 1 (attempt 3)
  │   │   │   └─ … same 3-attempt cycle …
  │   │   │       └─ … advance through fallback 2, 3, 4 …
  │   │   │           └─ all 15 attempts exhausted → terminal error

{
  "attempt_index": 2,
  "model_used": "openai/gpt-4o-mini",
  "success": false,
  "validation_errors": [
    "T3 business rule: options.B value '1+4' not in allowed_set",
    "T3 business rule: statements.length === 4 (expected 3)"
  ],
  "prompt_tokens": 812,
  "completion_tokens": 240,
  "total_tokens": 1052
}

1. swap_refs_to_atomic_uids(response.items, ref_to_uid_map):
     For each item:
       item.source_atomic_uids = [ ref_to_uid_map[r] for r in item.source_refs ]
       del item.source_refs
     (The ref map is discarded after this step — refs do not persist.)

2. assign_qa_ids(items, document_id):
     Read the current max `qa_items.qa_id` sequence for this document_id.
     For each item in wizard order:
       seq += 1
       item.qa_id = f"QA-{document_id}-{seq:03d}"
     qa_id is assigned ONLY here, ONLY by the backend, ONLY post-validation.

3. attach_provenance(items, model_used_per_group, accepted_by, role):
     For each item, attach a private `_provenance` attribute (NOT part of
     content_json — destined for the qa_items row only):
       item._provenance = {
         model_used: <OpenRouter slug of the model that succeeded for this item's group>,
         generated_by_role: <"teacher" | "editor" | "sub-member">,
         generated_by_id:   <user-id of the actor>,
         accepted_at:       <ISO8601 now>   (set on Accept, not on Generate),
         is_late_added:     <bool>,
         slot_index:        <wizard slot index>,
       }
     Per-item provenance is persisted on qa_items rows for relational audit.
     It is NEVER written into content_json.qa.items[] — see §22B.3.E step 7
     for the split between content_json fields and qa_items row fields.

4. return items to the wizard for Teacher review/edit.

5. on "Accept Q&A": run the §22B.3.E step 7 transactional write
   (per-item rows into qa_items + top-level qa node into content_json).

slots = [
  Slot(slot_index=1, type="subjective.straightforward", news_item_uids=[uid_A]),
  Slot(slot_index=2, type="objective.direct",           news_item_uids=[uid_B]),
  Slot(slot_index=3, type="subjective.straightforward", news_item_uids=[uid_C]),
  Slot(slot_index=4, type="objective.statement_analysis", news_item_uids=[uid_D]),
  Slot(slot_index=5, type="objective.direct",           news_item_uids=[uid_B, uid_E]),
]

groups = {
  "subjective.straightforward":   [slots[0], slots[2]],
  "objective.direct":             [slots[1], slots[4]],
  "objective.statement_analysis": [slots[3]],
}

# group "objective.direct" — 2 slots, slots[1] and slots[4]
# slot[1] has 1 news_item (uid_B); slot[4] has 2 news_items (uid_B, uid_E)
ref_to_uid_T2  = { "n1": uid_B, "n2": uid_B, "n3": uid_E }
ref_to_slot_T2 = { "n1": 2,     "n2": 5,     "n3": 5     }  # slot_index values

dispatch_order = [T1_group, T2_group, T3_group]  # only non-empty groups
for group in dispatch_order:
    response = openrouter_call(group, retry_chain=15)
    if response.terminal_error:
        ABORT_ENTIRE_WIZARD_RUN(reason=response.error)   # see §22B.3.E step 6
    group.response = response

for group in dispatch_order:
    for response_item in group.response.items:
        # The model copied source_refs verbatim from the input payload.
        # Find the slot_index by looking up any one of the source_refs in the
        # per-group ref→slot map. (All refs in a single item's source_refs
        # belong to the same slot, by construction at step 2.)
        slot_index = ref_to_slot_for(group)[response_item.source_refs[0]]
        response_item._slot_index = slot_index   # private attribute, not persisted

merged = [item for group in dispatch_order for item in group.response.items]
merged.sort(key=lambda it: it._slot_index)

# Step 1 of §22B.3.D (per-item ref swap, using each item's own group map)
for item in merged:
    item.source_atomic_uids = [ ref_to_uid_for(item._group)[r] for r in item.source_refs ]
    del item.source_refs
    del item._slot_index    # discard ephemeral wizard ordering
    del item._group

# Step 2 of §22B.3.D (qa_id assignment in wizard order)
seq = read_max_qa_seq(document_id)   # 0 on first wizard run; N on late-add
for item in merged:
    seq += 1
    item.qa_id = f"QA-{document_id}-{seq:03d}"

BEGIN;

-- 7.1 Concurrency lock (see step 10 for race semantics).
SELECT MAX(qa_id_seq) AS current_max FROM qa_items
  WHERE document_id = :doc_id
  FOR UPDATE;

-- 7.2 If current_max differs from the seq window assigned at step 5,
--     re-assign qa_ids starting from current_max + 1, in slot_index order.

-- 7.3 Insert one row per item into qa_items WITH per-item provenance.
INSERT INTO qa_items
  (qa_id, qa_id_seq, slot_index, document_id, org_id,
   source_atomic_uids, type, payload,
   generated_by_role, generated_by_id, model_used,
   is_late_added, accepted_at, edited_after_accept)
VALUES
  (...), (...), (...);   -- N rows, one per merged item

-- 7.4 Build the content_json.qa node as a LEAN render-only structure.
--     Pseudocode for the JSONB value `merged_qa_node`:
--       merged_qa_node = {
--         "generated_by_role": <preserved if qa already exists; else from this run's actor>,
--         "generated_at":      <preserved if qa already exists; else now()>,
--         "model_used":        <preserved if qa already exists; else first group's successful model>,
--         "items": [
--           {  // for each row inserted at 7.3, in qa_id_seq ascending order:
--              "qa_id": <row.qa_id>,
--              "source_atomic_uids": <row.source_atomic_uids>,
--              "type": <row.type>,
--              ...<expand row.payload — type-specific render fields ONLY>
--           },
--           ...
--         ]
--       }
--     Note: provenance fields (model_used, generated_by_role, generated_by_id,
--           accepted_at, is_late_added, slot_index) are NEVER copied into the
--           items[] entries. They live exclusively on qa_items rows.

-- 7.5 If first acceptance: write the whole qa node.
--     If late-add (qa node already exists): preserve top-level fields, replace items[].
UPDATE documents
SET content_json = CASE
      WHEN content_json ? 'qa' THEN
        -- Late-add: preserve top-level metadata, replace items[] only.
        jsonb_set(
          content_json,
          '{qa,items}',
          :merged_qa_items_jsonb,
          true
        )
      ELSE
        -- First acceptance: write the whole qa node.
        jsonb_set(
          content_json,
          '{qa}',
          :merged_qa_node_jsonb,
          true
        )
    END,
    has_qa = true,
    qa_item_count = (SELECT COUNT(*) FROM qa_items WHERE document_id = :doc_id),
    qa_late_added = (content_json ? 'qa')   -- true iff qa node existed before this txn
WHERE id = :doc_id;

-- 7.6 Pipeline event for late-add (§13.6) to trigger PDF regen.
INSERT INTO pipeline_events (document_id, event_type, triggered_by, triggered_at, ...)
VALUES (:doc_id, 'qa_late_added', :actor, now(), ...)
  WHERE :is_late_add = true;

COMMIT;

{
  "qa": {
    "generated_by_role": "teacher",
    "generated_at": "2026-03-01T15:45:00.000Z",
    "model_used": "openai/gpt-4o-mini",
    "items": [
      {
        "qa_id": "QA-NL-20260301-0001-001",
        "source_atomic_uids": ["010326-News-IndiaLaunc-Cat-SCIENCE_AND_TECHNOLOGY-NL-20260301-0001-e5f6g7h8"],
        "type": "subjective.straightforward",
        "statement": "What is the peak performance of India's new AI supercomputer?",
        "answer": "210 petaflops"
      },
      {
        "qa_id": "QA-NL-20260301-0001-002",
        "source_atomic_uids": ["010326-News-NASAEuropa-Cat-SCIENCE_AND_TECHNOLOGY-NL-20260301-0001-u1v2w3x4"],
        "type": "objective.direct",
        "statement": "Which planet's moon is NASA's Europa Clipper mission designed to study?",
        "options": { "A": "Mars", "B": "Jupiter", "C": "Saturn", "D": "Neptune" },
        "correct_option": "B"
      },
      {
        "qa_id": "QA-NL-20260301-0001-003",
        "source_atomic_uids": ["010326-News-Reserve3rd-Cat-ECONOMY-NL-20260301-0001-p1q2r3s4"],
        "type": "subjective.straightforward",
        "statement": "By how many basis points did the RBI hike the repo rate?",
        "answer": "25 basis points"
      },
      {
        "qa_id": "QA-NL-20260301-0001-004",
        "source_atomic_uids": ["010326-News-GlobalQuan-Cat-SCIENCE_AND_TECHNOLOGY-NL-20260301-0001-c9d0e1f2"],
        "type": "objective.statement_analysis",
        "topic": "the IEEE Global Quantum Internet Standards",
        "statements": [
          "The IEEE standards define a uniform protocol stack for quantum key distribution.",
          "The standards are binding on all member states of the United Nations.",
          "The standards include interoperability requirements for entanglement-based networks."
        ],
        "options": { "A": "1", "B": "1+3", "C": "2+3", "D": "All of the above" },
        "correct_option": "B"
      },
      {
        "qa_id": "QA-NL-20260301-0001-005",
        "source_atomic_uids": [
          "010326-News-NASAEuropa-Cat-SCIENCE_AND_TECHNOLOGY-NL-20260301-0001-u1v2w3x4",
          "010326-News-ESAJupiter-Cat-SCIENCE_AND_TECHNOLOGY-NL-20260301-0001-t8u9v0w1"
        ],
        "type": "objective.direct",
        "statement": "Which two missions are jointly studying Jupiter's icy moons in 2026?",
        "options": { "A": "Europa Clipper & JUICE", "B": "Cassini & Galileo", "C": "Juno & Voyager-2", "D": "MESSENGER & New Horizons" },
        "correct_option": "A"
      }
    ]
  }
}