/citation-integrity/source-mapping
Source Mapping Table
A source mapping table is the reviewable bridge between a messy source folder and a governed source registry. It records which citation label corresponds to which source file and which extracted text file, while preserving the operator decision that made the mapping usable, pending, or rejected.
The table is intentionally simple because its primary job is governance, not automation. It gives reviewers one place to inspect source paths, extracted-text paths, labels, notes, and review status before coverage or fragment verification is used as evidence of readiness.
CSV schema
| Field | Purpose |
|---|---|
| exhibit_label | The citation label, source label, or profile-defined reference used by the analytical draft. |
| source_filename | The path or filename for the original source file. Accepted and provisional rows need a real source path. |
| extracted_text_filename | The path or filename for extracted text used by verbatim fragment checks. Accepted and provisional rows need a real extracted-text path. |
| title | A human-readable title for operator review. |
| source_type | A profile-defined type such as filing, transcript, report, email, dataset, or attachment. |
| notes | Operator notes explaining review decisions, date mismatches, label ambiguity, or intentional exclusions. |
| review_status | The required governance field describing whether a row is usable for clean coverage. |
Review status
The required review_status field prevents a mechanical mapping from being mistaken for a reviewed mapping. Accepted rows and provisional rows may both be useful during system operation, but only accepted rows can enter clean reviewed coverage.
| Status | Clean eligible | Meaning |
|---|---|---|
| accepted | Yes | Confirmed by operator review. The row may enter clean coverage if its files exist and no hard validation errors remain. |
| provisional | No | Useful for mechanical testing or triage. It remains excluded from clean coverage until accepted. |
| needs_review | No | Known to require human disposition before it can support clean coverage. |
| rejected | No | Considered and declined. It remains visible so the same rejected mapping is not rediscovered later. |
| no_source_found | No | A valid unresolved disposition. Source and extracted-text paths may be blank because the row records that no matching source is available. |
Validation
Validation checks the table before it is used for bridge or coverage work. The validator does not decide what the correct mapping should be. It surfaces rows that are structurally unsafe, missing required evidence, or likely to inflate coverage if left unreviewed.
- Required fields are present, especially review_status.
- Review status is one of the documented values.
- Accepted and provisional rows do not have blank source or extracted-text paths.
- Referenced source files and extracted-text files exist.
- Paths do not contain double-prefix construction errors.
- Duplicate labels are surfaced for operator review.
- Generic labels are not treated as accepted unless a human explicitly reviewed them.
- Date mismatches between a label and a source filename are surfaced and require an accepted review decision with an explanatory note.
Date mismatches
Date-bearing labels and filenames can drift apart for legitimate reasons, but they are dangerous when handled silently. A row whose label suggests one date while the source filename suggests another is treated as unsafe until a reviewer accepts the row and explains the reason in notes.
This keeps the system from converting a plausible filename match into a governed source mapping without a human decision at the boundary.
Clean coverage
Raw coverage and clean coverage answer different questions. Raw coverage is useful during corpus assembly because it shows progress against the current mapping table. Clean coverage is the evaluator-facing number because it counts only reviewed, valid, source-backed rows.
| Output | Meaning |
|---|---|
| raw coverage | All mapped rows useful for internal progress tracking. |
| clean coverage | Only accepted rows that pass validation, point to existing files, and carry no unresolved hard warnings. |
| clean_coverage_eligible.csv | The filtered mapping artifact used when reporting clean reviewed coverage. |
Operator review
The mapping table is a human-edited governance artifact. Automated matching may suggest candidates, but acceptance remains a review act. Ambiguous labels, missing sources, path repairs, date mismatches, and generic filenames should leave notes that explain why the row is safe enough to count or why it remains excluded.
The goal is not to make source mapping effortless. The goal is to keep every mapping decision inspectable before it affects coverage, fragment verification, promotion, or export.