# File versions

Every file in Connect is a chain of versions rather than a single document. Version 1 is however it arrived — uploaded or produced — and each later version is one recorded change on top of the one before it. Each carries provenance: what produced it, from which request, and under whose confirmation. The chain is append-only and no version is ever rewritten.

- **Status:** Available
- **Audience:** both
- **In the app:** #/data
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/files-data/file-versions/

## What one version is

A version is the whole document at a moment, not a patch against the previous one. Opening version 2 gives you version 2, complete, with no reconstruction step that could go wrong. That makes the store larger and the reading simpler, which is the right trade for business documents that are read far more often than they are changed.

**Contents** — The full file as it stood, kept byte for byte.
**Provenance** — What made this version: an upload, `create_file`, or a `modify_file` change, and the request behind it.
**Position** — Its place in the chain. Positions are never renumbered when a new version is added.
**Audit link** — The entry in the [decision log](/docs/autonomy/) that records the action, including who confirmed it.

## Provenance versus audit

They answer different questions and both are kept. Provenance belongs to the version and says where this document came from. The audit trail belongs to the workspace and says what was decided, by what, under which rule, and what happened — including refusals, because a refusal is a decision too.

| Question | Answered by | Survives |
|---|---|---|
| Where did this document come from? | The version's provenance | As long as the version does |
| Who allowed this change, and under what rule? | The audit trail | Independently of the file |
| What did the document say on the day it was quoted? | The version itself | Both, together |
| Was a change proposed and refused? | The audit trail only — no version is written | The audit trail |

The last row is the one people are surprised by. A refused change leaves no version, so a chain with three entries may have had five requests against it. The file tells you what exists; [the record of a file](/docs/files-data/file-audit/) tells you what was attempted.

## Reading a chain

1. Open the file from the Files sheet in [the Data grid](/docs/files-data/data-grid/), or from the record it is linked to.
   - Result: You get the latest version, which is what almost every reader wants.
2. Open the version list.
   - Result: Every version is there in order, oldest first, with what produced each one.
3. Open an earlier version to read it.
   - Result: You are reading the document as it was, not a reconstruction of it. Nothing about opening it changes the chain.
4. To go back to older contents, ask for a change from that version.
   - Result: A new version is written whose contents match the old one. The chain still only grows forwards, and the detour is visible in it.

> **Note** Connect does not show a line-by-line difference between two versions. If you need to know precisely what moved, open both and compare, or ask a question naming the two versions and read the answer against them.

## What the chain is not

- **Not a backup.** It protects a document against being changed into something else, not against the workspace being lost. Those are different problems with different answers.
- **Not branching.** There is one line of versions per file. Two people changing the same file produce two versions in order, not two parallel drafts.
- **Not shared across files.** Producing the same content in another format makes a separate file with its own chain starting at version 1.
- **Not visible outside the workspace.** Versions live in `media_assets` with everything else, scoped and under row-level security — the same [three layers of isolation](/research/three-layers-of-isolation/) as any record.

## Questions

### Can a version be deleted?

The chain is append-only, so nothing is removed as part of normal use — that is what makes an old citation still checkable. Removing data on request is a deliberate administrative act rather than something a change to a document can do incidentally.

### Does uploading the same file again make a new version?

Uploading is how a file arrives, so it starts a chain at version 1. Adding a later version of an existing file is a change to that file rather than a fresh upload, which is what keeps one document's history in one place instead of scattered across near-identical entries.

### Why is there no diff view?

It is not part of the file service. Business documents are read rather than merged, and the question that actually gets asked is what the document said on a given day — which opening the version answers exactly, with none of the ambiguity a rendered difference introduces.

## Related

- [Changing a file](https://connectbyjbrh.com/docs/files-data/modify-file/)
- [The record of a file](https://connectbyjbrh.com/docs/files-data/file-audit/)
- [Creating a file](https://connectbyjbrh.com/docs/files-data/create-file/)
- [Producing a new version of a file](https://connectbyjbrh.com/docs/workflows/file-version-chain/)
- [The Data grid](https://connectbyjbrh.com/docs/files-data/data-grid/)
- [What Connect may do](https://connectbyjbrh.com/docs/autonomy/)

## What this page is based on

- docs-source/sources/GENERAL.md §9 — new versions, provenance and audit
- docs-source/sources/GENERAL.md §5 — the audit trail records refusals
- `backend/app/file_workspace.py`
- `backend/app/audit.py`