exam-ingest

# exam-ingest — validated workspace initialization

## Purpose

Convert a confirmed materials folder into a validated cram workspace. Build and repair the knowledge base only; do not teach or grade. The normal path produces structured ingestion facts under `.ingest/`, compiled chapter wiki and bank files, progress state, visual evidence, and an explicit readiness verdict before handing control back to `exam-cram`.

This module is the explicit `processing_mode=full` route. A missing, legacy, or
`lightweight` processing choice must not activate it; route that learner through
`scripts/lightweight_session.py` instead.

## Activation

Activate when the confirmed workspace lacks its wiki, bank, or progress state; when the student supplies new/changed course materials; or when `validate_workspace.py` reports ingestion readiness `blocked`. Do not treat the mere existence of generated files as proof that the workspace is ready.

## Inputs

- A student-confirmed materials directory containing PDF, DOCX, PPTX, XLSX, common standalone raster images, txt, or Markdown. Scans/images without usable sidecar text, damaged/encrypted files, unsupported features/formats, and ambiguous problem/solution pairs may require evidence-backed AI/human review.
- A target workspace directory explicitly confirmed by the student. Never default to the repository, process current directory, or an inferred course folder. The workspace must be separate from the materials tree so reruns cannot ingest generated outputs. If no workspace is confirmed, use `update_progress.py workspace-list --json`, then ask the student to select or provide one before writing anything.

## Workflow

1. **Pass the executable start gate, then use the official ingestion entry.** The exact materials/workspace pair, all three learning choices, and explicit `processing_mode=full` must already have been persisted with `exam_start.py confirm` as specified by `exam-cram`; a bare registry row or `update_progress.py set` is insufficient. Verify read-only with `exam_start.py status --materials <dir> --workspace <ws> --json`; require `ready_to_ingest=true`, then run from the package root:

   ```text
   python scripts/ingest_course.py --materials <dir> --workspace <ws> --json [--course-name <name>] [--lang zh|en] [--artifact-mode chat|visual]
   ```

   The default `core` orchestrator performs dependency preflight, deterministic extraction, provenance-preserving structured compilation, state initialization, visual indexing/repair, and canonical workspace validation. It never installs a dependency. Pass `--artifact-mode` only for an explicit standing student choice; omit it to retain the existing preference (or the default `chat` on a new workspace). An ordinary `exam_start.py confirm` with no `--processing-mode` likewise preserves an existing canonical processing choice; nevertheless this subskill still requires the effective choice to be explicit/current `full`.
2. **Interpret process and readiness separately.** Exit `0` means the engineering process completed and the JSON readiness is `ready` or `usable_with_gaps`; preserve and report any warnings in the latter. Exit `10` means `process_success=true` but `readiness=blocked`: do not teach, quiz, or claim completion. Any other nonzero is a dependency, input, or operation failure. For a missing required capability, ask once with the active language pack's consent line, install only on yes, then rerun the same command. A business/data failure is never evidence that Python is absent.
3. **Require ingestion-v2 parser receipts.** The regular path writes `.ingest/parser_receipts.json` with one receipt for every discovered source. Each row binds canonical source path, exact source SHA-256/media type, adapter/module/distribution/version, requested and produced location anchors, config SHA-256, result status, and the exact policy `{network:false, upload:false, install:false}`. Missing/duplicate rows, source or page drift, a policy mismatch, or a receipt referring to an unknown source blocks validation. A legacy ingestion-v1 payload remains readable only as legacy and must not be described as having v2 receipts. Unit language comes only from its payload: `zxx` is formula/symbol-only, never inherited, and never zh/en Guide support; otherwise review.
   Automatic layout crops remain available as unreceipted legacy `crop_image` assets for ordinary tutoring/quiz ingestion; geometry alone must never mint a current Study Guide receipt. Every new strict crop requires receipt schema v2 plus semantic-review schema v2, exact crop-hash binding, `unrelated_content_present=false`, and `student_attempt_present=false`. Target-only is the default (`verdict=target_item_only`, `isolation=target_item_only`, empty `required_context_ids`, detected IDs exactly the target); a dependent prompt instead uses `verdict=target_with_required_context` plus the distinct `isolation=target_with_required_context`, declares sorted unique prerequisite item/theorem/example IDs, and detects the target followed by exactly those contexts. Historical receipt schema v1 and semantic-review v1 stay read-only; existing v2 single-region receipts remain readable without hash/ID migration. For a completed ingestion-v2 workspace, `scripts/backfill_crop_receipts.py validate|apply --workspace <ws> --annotations <jsonl> --json` supports `upgrade_existing`, `create_from_parent`, and prompt-only `create_composite_from_parent` without rerunning the PDF builder. The composite is an explicit compatible v2 receipt variant: 2–32 non-overlapping regions from one exact parent/source/page are stacked without scaling using fully specified order, gap, RGBA background, and horizontal alignment; every pixel/PDF bbox, content ID, parent/target/candidate hash/dimension, source/parser revision, and output hash is bound and rechecked. It performs no OCR or arbitrary editing. A tainted parent page alone may not reject a semantically reviewed clean prompt component, but the candidate/outp