Appraisal

Purpose and authority boundary

NexusScholar.Appraisal owns methodological appraisal authority. It represents the questions asked, the allowed answers, the judgment vocabulary, the evidence inspected, and the human judgment recorded for one candidate under an approved Protocol.

The module deliberately does not ship or endorse a named appraisal instrument. AppraisalInstrument is a versioned contract that callers populate for a method domain. Version 1.0.0 is the only currently admitted instrument schema version.

An appraisal is not a score generator. Automation may create a proposal, but final and corrective appraisal records require a human actor, complete answers, evidence for every answer, at least one record-level evidence location, an allowed judgment, and rationale.

Data and authority flow

approved Protocol + versioned instrument
                  |
                  v
        AppraisalRecord.CreateProposal
                  |       non-current
                  v
        AppraisalRecord.CreateFinal
                  |       human + evidence
                  v
           AppraisalJournal
                  |
        correction supersedes one exact
        current record; amendment appends
        an invalidation without deletion

AppraisalJournal.CurrentRecords is a replay projection. It excludes proposals, superseded records, and amendment-invalidated digests. Corrections are admitted only when id, digest, candidate, Protocol version, and instrument digest all match one current target.

Key API surface

• AppraisalInstrument.Create validates a stable id, supported version, method domain, ordered unique questions, allowed answers, and judgment vocabulary.
• AppraisalRecord.CreateProposal admits partial automation output without making it current authority.
• AppraisalRecord.CreateFinal requires every instrument question, exact per-answer evidence, record-level evidence, a vocabulary-approved judgment, rationale, approved Protocol, human actor, and UTC clock.
• AppraisalRecord.CreateCorrection additionally binds the exact superseded record id and digest.
• AppraisalJournal.Append enforces unique identities and current correction targets.
• AppraisalAmendmentInvalidation.Create binds exact current appraisal digests to one verified Protocol amendment.

The canonical schemas are nexus.appraisal.instrument, nexus.appraisal.record, and nexus.appraisal.invalidation, version 1.0.0.

Failure states and deterministic behavior

Canonical envelopes bind Protocol id and digest, instrument id/version/digest, candidate, answers, judgment, evidence, actor, time, proposal/correction flags, and supersession material. Evidence locations carry their own verified raw-artifact and derived-representation identities.

• Missing or unsupported instrument version fails closed.
• Duplicate, unknown, incomplete, or vocabulary-invalid answers are rejected.
• Final answers without exact Full Text evidence are rejected.
• Automation finalization is rejected even if the payload is otherwise complete.
• Corrections of stale, foreign-candidate, foreign-Protocol, or foreign-instrument records are rejected.
• Invalidation must target current records governed by the amended Protocol version.

Dependencies and extension points

Appraisal depends only on Kernel, Protocol, and FullText. Instruments are caller-defined within the admitted schema: developers can model different method domains by supplying explicit questions, allowed answers, and judgments. The package does not fetch instrument definitions, select an instrument automatically, or calculate aggregate quality scores.

Synthesis consumes appraisals only through SynthesisEligibleRecord.FromAppraisal, which verifies journal membership, final—not proposal—status, currentness, and invalidation state. Workflow invalidation uses the outward ScientificRecords bridge.

Tests and accepted evidence

AppraisalTests cover instrument validation, evidence requirements, proposals, final authority, corrections, and invalidation. Canonical and cross-package cases live in FE-07 fixture tests and authority replay tests.

See ADR 0034, the FE-07 gate, and FE-07 completion evidence.

Explicit nonclaims

The module does not endorse any appraisal instrument, certify risk of bias, grade certainty, produce clinical or causal conclusions, execute AI, provide persistence, or claim PHP, regulatory, or production compatibility. It verifies record authority and evidence binding, not methodological correctness of a caller-supplied instrument.