# Producing a new version of a file

Connect never edits a file in place. A change reads the current version, produces a new one, links it to whatever the old version was linked to, and records who asked and why. The previous version stays exactly as it was. That is what makes a document Connect touched safe to send: you can always show what it looked like before, and what instruction produced the difference.

- **Status:** Available
- **Audience:** both
- **In the app:** #/home
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/file-version-chain/

## The path a change takes

1. Trigger — you ask for a change to a file, in the Assistant or from the file itself.
2. User event — your instruction, plus the file you mean. Ambiguity about which file is resolved before anything is read.
3. Authentication and workspace resolution — the file service resolves your workspace first; `media_assets` is scoped and under row-level security like every other table.
4. Ingest — the current version is read through the same file service every attachment uses, in the format it was stored in.
5. Canonical record — the file record, not a copy on disk, is the thing being versioned. The chain belongs to the record.
6. Reasoning — the model produces the new content from the old content and your instruction. It works from what is in the file, not from a memory of it.
7. Knowledge, memory and rules — grounding applies here as anywhere: a rewrite that must match how the business describes itself draws on Knowledge rather than on invention.
8. Autonomy and approval — writing a version is work inside the workspace and needs no approval. Sending the file to somebody is a different action, with its own rule.
9. Action — a new version is written. The previous version is untouched; nothing is overwritten and nothing is deleted.
10. Result — the new version becomes the current one, and you can open either.
11. Relationship and timeline — links follow the file record, so a document attached to a company or a deal stays attached across versions.
12. Audit and usage — provenance is stored with the version: who asked, when, and which version it came from. Storage is consumed by each version, because each one exists.

The stage that does the real work for you is the last one. A file that changed and cannot say why is a liability in a business record; a version that names its parent and its instruction is evidence.

## What one version carries

| Held | Why it matters |
|---|---|
| The content itself | The version is a real file you can open, not a description of a change |
| Its parent version | The chain is walkable backwards, so *what changed* is answerable by comparison |
| Who asked for it | A person, in every case — the Assistant acts on an instruction, it does not decide to revise documents on its own |
| When it was produced | Ordering a chain by claim rather than by clock is how histories go wrong |
| The links the file had | A version does not detach a document from the record it belongs to |

There is no in-place edit anywhere in that list, and no version that quietly replaces another. If you have sent version three to a customer and version four now exists, version three is still there to be looked at — which is the only way to answer *what did they actually receive* honestly.

## Why overwriting was not an option

1. **A model's output is a draft until a person has looked at it.** Overwriting makes the review destructive: rejecting the change would mean reconstructing the original.
2. **Documents leave the business.** A quotation, a summary, a letter — once one has been sent, the version that was sent has to remain readable.
3. **Provenance is not reconstructible.** You cannot work out afterwards which instruction produced a paragraph. It has to be stored at the moment it happens.
4. **Two people can act on the same file.** Separate versions make a collision visible instead of silently letting the last writer win.

> **Careful** The cost is storage, and it is real: every version of every changed file is kept. A workspace that regenerates large documents repeatedly accumulates them. That is a deliberate trade — the alternative is a history with holes in exactly the places somebody will later ask about.

## Where the chain breaks, and what to do

**The source could not be read** — A PDF with no text layer is the usual cause; the change never starts. See [the PDF has no readable text](/docs/troubleshooting/pdf-no-text/).
**The new version is worse than the old one** — Nothing is lost — the previous version is current again as soon as you say so. Rewriting from a clearer instruction is usually better than editing the model's output by hand.
**Two changes were asked for at once** — Both produce versions. The chain shows the order; decide which is current rather than trying to merge them in your head.
**The output format is not one Connect writes** — Connect reads more formats than it produces. Ask for a format it can write, then convert once, outside.
**The file was refused before any of this** — That is a different problem entirely — [the file was refused](/docs/troubleshooting/file-rejected/) covers it.

A practical habit: when a document matters, ask for the change, read the new version against the old one in preview, and only then link or send it. The chain makes that check cheap, which is the point of having it.

## Questions

### Can I delete an old version?

Versions exist so that a history is complete, and the sources this page is written from do not record a way to remove one selectively. Treat the chain as append-only when you plan how you work — regenerating a large document twenty times leaves twenty versions.

### Does a new version break the links to a record?

No. Links belong to the file record rather than to one version of it, so a document attached to a company, a deal or a case stays attached when it changes. That is what stops a revision quietly disappearing from the place somebody will look for it.

### Can the Assistant change a file without being asked?

No. A version is produced from an instruction, and the instruction has a person behind it. The Assistant does not revise documents on its own initiative, and its rights are narrower than yours in the same way everywhere else — no pricing authority, and no clearing a do-not-contact entry.

## Related

- [File versions](https://connectbyjbrh.com/docs/files-data/file-versions/)
- [Changing a file](https://connectbyjbrh.com/docs/files-data/modify-file/)
- [Creating a file](https://connectbyjbrh.com/docs/files-data/create-file/)
- [Linking a file to a record](https://connectbyjbrh.com/docs/files-data/linking-files/)
- [The record of a file](https://connectbyjbrh.com/docs/files-data/file-audit/)
- [Changing a document, end to end](https://connectbyjbrh.com/docs/workflows/modify-document/)

## What this page is based on

- docs-source/sources/GENERAL.md §9 — files and the Data grid
- docs-source/sources/GENERAL.md §8 — the Assistant
- `backend/app/file_workspace.py`, `file_formats.py`
- `backend/app/audit.py` — the decision log