Protocol

Purpose and authority boundary

Protocol owns the difference between an editable plan and approved scientific authority. A ProtocolDraft collects intent, values, required decisions, human-authored decisions, unresolved questions, and allowed waivers. Approval creates an immutable ProtocolVersion whose content digest is separate from the approval records that authorize it.

Product law: a draft is not an approved protocol, a proposal is not a decision, and an approval ID is not proof. Only a VerifiedProtocolVersion with reproduced content, policy, target, actor, approval, and digest bindings may establish authority downstream.

Authority model and lifecycle

draft
  ├─ record human decisions
  ├─ preserve unresolved decisions
  └─ declare permitted waivers
        ↓ validation
ready-for-review candidate + protocol-content digest
        ↓ policy-satisfying human approvals
approved immutable version
        ├─ amendment → new version + supersession links
        ├─ waiver → separately approved supplemental authority
        └─ deviation → actual-conduct record; never rewrites the plan

Approval policy supports single researcher, dual independent, specialist/project roles, institutional signoff, and custom role expressions. The selected policy controls minimum approvals, distinct actors, and required roles. allowsAutomation must remain false for protocol authority.

Key types and services

• ProtocolDraft creates the mutable pre-approval aggregate and rejects overwrite-style decision changes.
• RequiredDecisionDefinition, ProtocolDecision, and UnresolvedDecision capture the decision vocabulary and approval blockers.
• ApprovalPolicy and ProtocolApproval define human authorization independently of protocol content.
• ProtocolVersion is the immutable content-bearing version; VerifiedProtocolVersion is the trusted wrapper.
• ProtocolRehydrator uses IProtocolAuthorityResolver to reproduce version, policy, approval set, and target bindings from untrusted records.
• ProtocolSupplementalApproval, VerifiedProtocolWaiver, and VerifiedProtocolAmendment close the former approval-ID-only gap for supplemental authority.
• VerifiedProtocolDeviation records actual conduct, cited evidence, invalidation effects, approvals, and disclosure mapping without mutating the approved version.
• ProtocolAuthorityPackageCanonicalCodec and deviation codecs provide canonical persistence boundaries.

Source: NexusScholar.Protocol. Decisions: ADR 0003, ADR 0004, and ADR 0019.

Digests, immutability, and lineage

ProtocolVersion.ContentDigest uses scope protocol-content, schema nexus.protocol-content/1.0.0, and includes protocol/version/project identity, version number, template, intent, values, required decisions, decisions, waivers, superseded version id, and amendment id where present. It excludes approvals, its own digest, persistence, UI state, and projections.

Every approval uses scope approval-record and binds the exact version and protocol-content digest. Supplemental approvals bind a target-specific waiver or amendment digest. Collections are normalized deterministically before hashing; approved versions are defensively copied and deeply immutable. A scientific change therefore produces a new version and explicit lineage, never a rewritten digest.

Typical developer flow

1. Create a draft with injected IDs, clock, template identity, intent, values, and required decisions.
2. Record identified-human decisions; represent still-open questions explicitly.
3. Create an approval candidate. Missing required decisions or blocking unresolved decisions stop here.
4. Create approval records against the candidate’s exact content digest and policy.
5. Approve and retain the returned immutable version plus approval records.
6. At a persistence/import boundary, rehydrate through an authority resolver and pass only VerifiedProtocolVersion.
7. For change, create and approve an amendment/successor; for divergence in actual conduct, create a verified deviation.

Failure and refusal behavior

Stable categories cover missing or duplicate decisions, blocking unresolved decisions, stale content, target mismatch, unauthorized or non-human approval, same-actor dual approval, insufficient policy, invalid waiver/deviation/amendment, and post-approval mutation. Rehydration rejects missing or extra approvals, wrong policy, altered digests, mismatched targets, policy downgrade, invalid lineage, foreign invalidation notices, and non-human supplemental authority.

Tests and evidence

ProtocolTests, ProtocolDeviationAuthorityTests, and ProtocolFixtureTests cover construction, approval, immutable rehydration, supplemental authority, and adversarial records. The Protocol fixture pack includes valid single/dual approval, amendment, waiver, deviation, stale digest, automation, duplicate approval, policy downgrade, and lineage cases.

Dependencies, extension points, and nonclaims

Protocol depends only on Kernel inside Nexus. Downstream modules consume verified wrappers; they do not reinterpret Protocol bytes. New method packs may define required decisions and stricter policies, while new supplemental target types require an explicit authority contract and tests. This module provides no institutional identity provider, signature/non-repudiation, persistence, UI, workflow execution, legal certification, or broad PHP/blueprint compatibility.