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
| Option | Description | Benefits | Drawbacks |
|---|---|---|---|
| Mutable referenced artifacts | Allow objects to be overwritten in place even after facts reference them. | 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