Changing a document, end to end
You name a file and say what should be different. Connect reads that exact version, prepares what will differ, and shows you the result before anything exists. On confirmation modify_file writes the next version in the chain with provenance naming the request, the previous version stays byte for byte as it was, and the decision log records who allowed the change.
The chain#
- Trigger — you ask for something in an existing document to be different.
- User event — the request is posted with the route and any file or record the tab is working on.
- Authentication and workspace resolution — the workspace is fixed first, so the file being changed can only ever be one of yours.
- Ingest — the request joins the conversation; the file is not re-uploaded.
- Canonical record — the file is resolved, and so is the version. Where you did not name one, that is the latest, and the proposal says which it read.
- Reasoning — the contents are read and the difference is worked out; the model selects
modify_file. - Knowledge, memory and rules — the same authority applies as when a document is created: a value Connect cannot source stays a gap rather than becoming a guess.
- Autonomy and approval — a writing tool, so a proposal first. Nothing has changed at this point and discarding costs nothing.
- Action through the owning service — the file service appends a version. There is no in-place write and no mode that enables one.
- Result — the new version exists with provenance; the version you started from is unchanged and still readable.
- Relationship and timeline — records linked to the file see the new version through the link, because the link is to the file rather than to a version.
- Audit, usage and Needs You — the decision log records the request, the tool and the person who confirmed; a refused change leaves an entry and no version at all.
Stage five decides more than it looks. A request made while an older version was open is applied to that version, which is usually right and occasionally a surprise — so the proposal says which version it read before you confirm anything.
Stage by stage#
| Stage | What you see | What changes | What can fail |
|---|---|---|---|
| Name the file | The file in the proposal | Nothing | Two files with similar names; Connect asks which |
| Resolve the version | Which version will be read | Nothing | You meant a different one — discard and say so |
| Read | A working line | Nothing | The stored file cannot be parsed; it is refused rather than approximated |
| Propose | What will change | Nothing | The edit is not expressible in that format |
| Confirm | The proposal runs | A new version, and an audit entry | A refusal from the file service, reported as itself |
| Read the result | The new version in preview | Nothing further | The result went further than intended — the earlier version is still there |
What was touched, and what was not#
- A new version exists, with provenance naming the request and the tool.
- The earlier version is unchanged, including every audit entry that ever referred to it.
- Linked records need nothing. The link is to the file, so the new version arrives without relinking.
- No record was edited. Changing an attached document does not move a deal, update a company or close a case.
- Nothing was sent. As with creating a document, delivery is a separate action under its own rule.
When two people change the same file#
Both changes exist, in the order they were applied, and neither overwrote the other. What the second person changed, though, was applied to the first person's result rather than to the document they last read — which is worth checking before assuming the two intentions were combined.
Open the version list and read the provenance on the last two entries.
Result You can see both requests and who confirmed each, without guessing from the contents.
Open both versions.
Result You are comparing documents rather than reconstructing what somebody meant.
If the result is wrong, ask for one more revision that states the combined intention.
Result The chain gains a version whose provenance says exactly why, which is a better record than a silent correction.
Questions#
How do I know which version an answer was based on?
The answer names the file, and the version chain plus the decision log say what existed when. Between them the question of what the document said on a given day always has an answer, which is the entire reason for refusing to overwrite.
Can a change be undone in one step?
Not as an erasure, and deliberately so. You can produce a version whose contents match an earlier one, and the chain will show that you did. Designing undo for agent actions covers why reversal is modelled as a new action rather than a deletion.
What happens if a revision is refused?
No version is written and the file is exactly as it was. The refusal itself is recorded, so a chain with three versions may sit behind five requests — and the log, not the file, is where you see the other two.