logicsrc/docs/opencontext/provenance.md

Provenance

Provenance answers "who says so, and when did we last check".

That is a different question from "is it true" (authority) and from "may you read it" (permissions). An object can be canonical and unattributable, or perfectly attributed and merely observed.

Provenance survives resolution. Summarising or reformatting content may not erase its origin, because an agent that cannot cite its sources cannot be audited or corrected.

Declaring it

Two ways, and the difference matters.

# This object *is* the origin. A mission statement written here has no upstream.
canonical_source: true

# This object mirrors a fact that lives somewhere else.
sources:
  - uri: git://github.com/acme/context/policies/refunds.md
    type: document
    retrieved_at: 2026-08-09T15:00:00Z
    digest: sha256:9f2c1ab…
    trust: trusted
    author: support

Field	Notes
uri	Where it came from. The scheme tells a reader which system to go argue with when the fact is wrong.
type	canonical-record, document, conversation, observation, api, inference.
retrieved_at	When these bytes were last read.
digest	sha256:<64 hex> over the retrieved bytes.
trust	Trust of this specific origin, when it differs from the object's.

More than one source is normal — the same fact may be mirrored from a CRM and confirmed in a policy document.

Requiring it

provenance:
  required: true
  digest: sha256
  require_digest: false

Every resolved object must then declare a source or canonical_source: true:

✗ missing-provenance: policies.refunds declares no source, and provenance.required is true.
    → Add sources: [...], or canonical_source: true if this object is itself the origin.

Judged against what the author wrote

The loader attaches a file:// source with a digest to every file-backed object, so a bundle is attributable even when the author declared nothing. That is added provenance, and it is deliberately not what the requirement is checked against.

If it were, provenance.required would always pass and mean nothing. The check runs against the authored document, so "this pricing came from the CRM" is something a human has to say.

Integrity digests

sources:
  - uri: https://example.com/handbook.md
    digest: sha256:9f2c1ab…

A digest lets a consumer detect that a remote source changed under them — the difference between stale context and silently wrong context.

provenance:
  require_digest: true    # every remote source must carry one

✗ missing-digest: policies.handbook: remote source https://example.com/h.md has no
  integrity digest.
    → Add digest: sha256:<hex>, so a change at the source is detectable.

In the bundle

Provenance is flattened into its own top-level list, so it stands on its own even when content was summarised:

{
  "objects": [ { "id": "policies.refunds", "content": "Refunds within 30 days." } ],
  "provenance": [
    {
      "id": "policies.refunds",
      "canonical_source": true,
      "sources": [
        { "uri": "file://context/policies/refunds.md",
          "type": "document",
          "retrieved_at": "2026-08-09T14:00:00Z",
          "digest": "sha256:4c6959f2…",
          "trust": "trusted" }
      ]
    }
  ]
}

Query it:

opencontext bundle --role support | jq '.provenance[] | {id, sources: [.sources[].uri]}'

Provenance and trust

Attribution is not endorsement. Naming a source makes a claim checkable; it does not make it true.

id: operations.ticket-4821
authority: observed        # we saw it
trust: untrusted           # a stranger wrote it
sources:
  - uri: https://support.example.com/tickets/4821
    type: conversation
    trust: untrusted

An origin of type conversation or observation is a reason to keep the object's authority low. See security.

Provenance and decisions

The two together are what make an agent's decision reconstructable a year later:

id: decisions.2026-08-09-refund-4821
type: decision
decision: Credited against the next invoice.
bundle:
  bundle_id: ocb_37c04d801d013b07
  digest: sha256:37c04d80…

The bundle digest proves which context was in front of the decider; the provenance inside that bundle proves where each piece came from. Neither is enough alone.

Checklist

• provenance.required: true in production repositories.
• Objects mirroring another system name it in sources, with the right scheme.
• Objects authored here declare canonical_source: true rather than a fake source.
• Remote sources carry digests; require_digest: true where it matters.
• type reflects the real origin — conversation and observation are not canonical-record.
• Decision records cite the bundle they were made from.