Editing while fields change
What happens to an edit you have open when someone renames or retypes a field on its Type, and how a capsule's age is measured.
A Type's fields can change while you have one of its capsules open: someone renames isbn to isbn13, or turns a text field into a list. Symbol moves every capsule's value to the new field when that happens. Your open editor still shows the old field, so saving from it could put the old field back and clear the value that was just moved.
Saving after the fields changed
When the fields of a capsule's Type changed after you opened it, your save is refused with a message that the capsule changed since you opened it. Nothing you send is written, so the moved value stays where it is.
- Your draft stays in the editor, so you can copy anything you typed.
- Reload the capsule to see it with its new fields and their values, then make your change again.
- A save from an editor opened after the change works as usual.
This is the same refusal you get when another person saved the capsule while you had it open. It never includes the capsule's current content: you read that again through the capsule itself, with the same access you had to open it.
How a capsule's age is measured
Renaming or retyping a field does not count as an edit of the capsules it touches. Their age stays the same, so a capsule that was going to show as stale, or be archived automatically, still does so on its usual schedule. See Archiving. The exception is a capsule whose own text uses the field as a {{token}}: that text is rewritten to the new name, and a rewritten text counts as an edit.
Editing a capsule yourself, or adding an entry to a log, still counts as an edit and restarts its age, as before.
For developers
Every capsule carries two times:
updated_atis the capsule's edit token. Send it back asclient_updated_atonPUT /api/preview/capsules/{id}. It moves whenever the stored capsule changes, including when a Type field rename or retype moves its values.lifecycle_updated_atis when the capsule's content was last edited. Staleness and automatic archiving are measured from it. A field rename or retype leaves it unchanged.
A save whose client_updated_at is not the stored updated_at answers 409 with code: "VERSION_CONFLICT" and a fixed message. The body carries no current row, no replacement token and no schema. Check the token before validating field values: a stale save answers this 409, not a field error, even when its fields no longer exist on the Type. Re-read the capsule and build the retry from what that read returns, never by swapping in a new token alone.
GET /api/preview/capsules/{id}?editor_snapshot=1 adds editor_snapshot to the read: { capsule_id, type_id, schema_revision, field_schema, field_values, updated_at }, all read at one moment, so the token always belongs to the schema beside it. Send that updated_at as client_updated_at on the next save. When the caller cannot edit the capsule, it is archived or deleted, its Type cannot be read, or a protected capsule is delivered as its approved version, the read has editor_snapshot: null and editor_snapshot_unavailable names the reason: not_editable, archived, not_found, type_unavailable or approved_delivery. A read that asks for the snapshot is never cached.
Through MCP, update_capsule and edit_capsule answer a stale write with error: "stale_updated_at" and current_updated_at: null, and the message asks the assistant to call get_capsule and retry from what it returns.