Extraction

Purpose and authority boundary

NexusScholar.Extraction owns the scientific record that says which structured values were extracted from one included candidate, under which approved Protocol, from which exact Full Text representation. It does not parse PDFs, retrieve papers, run AI models, store database rows, or execute synthesis.

An ExtractionForm is the human-approved schema for one candidate. Every form question reference must resolve to the approved Protocol decision set. Every ExtractionFieldDefinition declares a stable field id, a Protocol question reference, a supported JSON value type, and whether the field is required.

Automation can append an ExtractionRecordKind.Proposal. Only a human actor can create review, correction, or resolution authority. Proposals never appear in the journal’s current scientific projection.

Record and journal model

approved Protocol
      |
      v
ExtractionForm --digest--> ExtractionJournal
                              |
              +---------------+----------------+
              |               |                |
           proposal          review         correction
          non-current       current      supersedes current
                              |
                        disagreement?
                              |
                           resolution
                    binds exact current records

The journal is an append-only digest chain. Each entry receives a one-based ordinal and the previous head digest when appended. A correction must target exactly one current record. A resolution must bind an existing unresolved field disagreement, at least two current source-record digests, and exactly one disputed field value.

Current records are derived by replay: proposals are excluded, corrected or resolved sources are superseded, and amendment-invalidated records are removed from the current projection without deleting their history.

Key API surface

• ExtractionForm.Create verifies approved Protocol status, question references, field uniqueness, field types, human approval, and UTC time.
• ExtractionFieldValue couples a canonical JSON value to a FullTextEvidenceLocation; supported types are string, integer, number, boolean, object, and array.
• ExtractionRecord.Create creates proposal, review, correction, or resolution entries and validates kind-specific source bindings.
• ExtractionJournal.Append attaches the digest chain, validates current-state constraints, and recomputes current records and disagreements.
• ExtractionAmendmentInvalidation.Create binds a verified Protocol amendment to exact current record digests and requires a human actor.

The canonical schemas are nexus.extraction.form, nexus.extraction.record, and nexus.extraction.invalidation, all version 1.0.0.

Determinism, refusal states, and stale data

Forms sort question references and fields before digesting. Records sort field values and resolution source digests. Conflicts derive stable ids from candidate id, field id, value signatures, and exact evidence-location digests. Canonical JSON and digest envelopes make the same accepted content reproduce the same identity.

• Unknown or duplicate fields fail with stable extraction error categories.
• Final records missing required fields or exact evidence fail closed.
• Automation attempting final authority is rejected.
• A correction of a superseded, invalidated, or otherwise non-current record is rejected.
• A resolution that omits the actual current disagreement is rejected.
• An amendment invalidation targeting anything except current records is rejected.

Dependencies and extension points

The package depends inward on Kernel for canonical identity, Protocol for approved versions and amendments, and FullText for verified evidence locations. It has no Workflow, UI, persistence, provider, or model dependency. Workflow integration is intentionally moved to the ScientificRecords bridge.

Developers can introduce method-specific forms and field vocabularies through the existing typed form contract. New value kinds, automatic acceptance, database persistence semantics, or a different correction model require an accepted contract change rather than an adapter shortcut.

Tests and accepted evidence

ExtractionTests cover forms, typed values, proposals, corrections, disagreement resolution, evidence, and invalidation. FE-07 fixtures exercise canonical records and negative cases; authority replay tests cover downstream invalidation binding.

Scope and claims are accepted by ADR 0034, the FE-07 gate, and completion evidence.

Explicit nonclaims

Extraction does not claim PDF parsing, OCR, semantic correctness, independent double-entry by default, named methodology endorsement, statistical validity, database durability, AI execution, PHP compatibility, or production readiness. It preserves structured human authority and evidence identity; it does not certify that a scientific value is true.