ADR-0039: Referenced Artifacts Become Immutable Once Fact-Addressed

Context

BSFG already stores large artifacts out-of-band and references them from facts. NATS Object Store supports put, get, and del, and client APIs also describe create/update behavior for objects. :contentReference[oaicite:0]{index=0}

That leaves a boundary-integrity question:

• can an artifact be overwritten after a fact references it?
• can a referenced artifact be deleted while the referencing fact remains retained?
• or does fact-addressed content need immutable identity semantics?

Because BSFG treats fact history as authoritative, artifact references must not silently drift underneath retained facts.

Options Considered

• simple operational patching
• fewer object keys over time

|

• fact meaning can drift silently
• audit reproducibility weakens
• digest checks become inconsistent with history

| | Delete-and-replace semantics | Allow referenced objects to be deleted and re-uploaded under the same logical key. |

• operationally convenient
• storage cleanup is simple

|

• historical references become unstable
• replay may not reproduce original evidence
• compliance posture degrades

| | Immutable once referenced (Selected) | Once a fact references an artifact, that artifact content is treated as immutable. Any correction or replacement uses a new object key and a new fact. |

• fact meaning remains stable over time
• digest-based integrity remains trustworthy
• replay and audit reconstruction stay reproducible
• matches append-only fact history

|

• replacement creates additional objects
• corrections require new facts and lifecycle cleanup later

| | Immutable by convention only | Recommend immutability but rely on operators and clients not to overwrite referenced objects. |

• minimal implementation burden
• flexibility for emergencies

|

• weak guarantee
• easy accidental violations
• hard to audit confidently

|

Decision

BSFG treats any artifact that has been referenced by a retained fact as immutable.

referenced object
  -> immutable content
replacement
  -> new object key + new fact

Therefore:

• artifact keys referenced by facts must not be overwritten in place
• a corrected or superseding artifact is stored under a new key
• the new artifact is linked by appending a new fact
• object digests remain part of the stable evidence chain

Deletion and garbage collection remain lifecycle concerns, but they must respect retention and evidence policy. A referenced artifact is not treated as casually mutable storage.

Consequences

Benefits:

• referenced evidence stays reproducible
• fact history and artifact content cannot silently diverge
• digest verification remains meaningful over time
• corrections are explicit and append-only, not hidden overwrites

Tradeoffs:

• object count grows when artifacts are corrected or superseded
• lifecycle and cleanup tooling must distinguish referenced vs unreferenced objects
• operators lose the convenience of in-place fixes for evidence-bearing content