References, retention and version erasure

Each retained reference records the file and its version: a record’s source, an XLSX format’s template and an export’s output file. record_read and record_history return sourceFileId with sourceVersion; format_get returns templateVersion. Read the source with file_read({fileId: sourceFileId, version: sourceVersion}). Export receipts keep pointing to the version that export wrote. An output reference protects its version from retention and individual version purge, but allows the whole output file to be trashed and purged. Replaying that export with the same requestId then fails not_found. Source and template files remain protected from whole-file erasure while referenced.

By default, the company keeps all versions. An owner or admin can change versionRetention through organization_update: {keep: "all"}, {keepLast: N} to keep the latest N existing versions, or {keepDays: N} to keep those created in the last N days. N must be a positive integer. principal_get returns the policy in organization.versionRetention. Maintenance applies it every five minutes and always preserves the current version and every version pinned by a retained reference.

purge({fileId, version, confirm: true}) erases one version of an active file. It requires the file’s creator, an owner or an admin, plus write access. A pinned version or the file’s only version fails with conflict. Erasing the current version promotes the latest earlier surviving version, with its content and indexes. Content leaves storage only when no version uses it.

Version numbers are never reused. Retention, version erasure and export rollback can leave gaps in history; file_history lists the surviving versions. Always pass the current version as baseVersion when writing, without calculating the next version number.