Provenance

Purpose and authority boundary

Provenance describes accepted activity; it does not authorize scientific decisions and it is not the Workflow state machine. A human, automation, plugin, system, or import agent can be truthfully recorded without inheriting human authority. Domain owners decide whether the referenced activity and outputs are valid.

A cache, wiki page, embedding index, generated narrative, local path, bundle, or container cannot be submitted as a canonical provenance entity. Projection state may be useful, but it does not replace the scientific records it summarizes.

Key types and event shape

• ProvenanceActivity declares an activity id/label and whether actor, digested inputs, and digested outputs are required.
• ProvenanceAgent supports human, automation, plugin, system, and import.
• ProvenanceEntityRef carries canonical kind/id and optional content digest.
• ProvenanceProtocolBinding and ProvenanceWorkflowBinding bind accepted identifiers and digests without making Provenance depend outward on those packages.
• ResearchEvent is the immutable event with actor, activity, UTC timestamp, subject, inputs, outputs, optional bindings, and event digest.
• ResearchEventFactory constructs and validates records. IProvenanceStore exposes append/read semantics; InMemoryProvenanceStore is the local reference store.

Source: NexusScholar.Provenance. Contract: ADR 0008.

Canonical identity and append authority

event id + agent + activity + occurred_at + subject
        + ordered inputs/outputs + optional protocol/workflow bindings
        ↓ DigestEnvelope
scope: provenance-event
schema: nexus.provenance-event / 1.0.0
        ↓
event digest

The store validates the event and reproduces its digest before append, rejects duplicate event ids, preserves order, and clones records on write/read. Later hardening adds resolver-backed append authority so callers cannot substitute partial actor, binding, or digest dictionaries for the referenced records. Stored collections remain immutable snapshots.

Typical developer flow

1. Select a declared activity whose required actor/input/output shape matches the domain action.
2. Use stable kind/id/digest entity references; never pass a path as the evidence identity.
3. Add exact Protocol and Workflow bindings when the activity occurred under them.
4. Create the event with injected clock/ID sources and append through the accepted store/authority boundary.
5. Project events outward for audit views; retain the canonical event as the source.

Failure and refusal behavior

Stable categories reject duplicate/default IDs, missing actor, unsupported agent kinds, missing required digested inputs or outputs, noncanonical projection kinds, non-UTC timestamps, invalid Protocol/Workflow bindings, and stale event digests. Rehydration/append authority rejects actor or binding claims that do not resolve to the exact expected record.

Tests, bridges, and nonclaims

ProvenanceTests, FE-01 Provenance tests, and ProvenanceFixtureTests cover creation, immutable append, authority binding, duplicates, and canonical exclusions. Fixtures live under fixtures/conformance/provenance.

Outward bridge packages may deterministically project accepted domain events—such as Workflow Execution transitions—into Provenance. Provenance itself remains Kernel-only. It provides no database, distributed ledger, signature, cryptographic non-repudiation, workflow state, decision authorization, bundle completeness, or guarantee that an external action actually occurred beyond the accepted record.