IAM.Agent: review an immutable document revision

Availability and access

This is an opt-in development workflow. It requires a verified generated artifact, access to its original Docs/Mind sources, permission to modify the target IAM.Docs family and a real backend advertising the versions operations. Source builds alone do not enable the service. The operator must qualify the backend before enabling its write flag and Core’s version tools. Community additionally requires IAM_DOCS_FILE_VERSIONS_ENABLED=1 and IAM_DOCS_ALLOW_WRITE=1.

Do not use this flow to replace an unrelated document. The review compares the current file’s binary SHA256, the generated artifact’s binary SHA256 and the exact target head. A canonical extracted-text hash is a separate identity: two different files can contain the same text. A new revision receives a different document identifier and retains earlier files and their access controls.

Prepare the artifact first

Follow Documents: from a request to verified output. Inspect the sources and outline, generate the artifact, complete the offered file/text/render checks and review its meaning. Automatic readback checks content and citation presence; a human must still check factual correctness, unsupported claims and formatting.

An upload receipt proves storage acceptance. It does not prove processing completion, complete extracted-text readback or factual approval.

Enterprise: review and append

1. In the document workflow, find Add an immutable IAM.Docs version. Enter Target Docs document ID and choose the verified export under Version file format.
2. Review Start processing after adding the version. This choice belongs to the version review; uploading and processing are separate operations.
3. Click Review current head. Compare the displayed current document/revision, filename, Binary SHA-256, separate canonical-text SHA256, generated filename, media type, size and Exact upload UUID.
4. Select I reviewed this exact head and generated artifact, then Append immutable version. Only this second action attempts the claimed upload.
5. Keep the resulting revision identifier. Use Check exact upload receipt to observe this UUID, the immutable file and subsequent processing/readback. Review binary verification and complete text/citation readback separately.

The native host retains the review before dispatch. Changing the file, source authorization, account, workspace or head invalidates the prior approval. If another writer advanced the head, read the current state and prepare a fresh review rather than forcing the stale upload.

A restored receipt does not establish the current file. Current-head binary recheck stays not confirmed after reopening until Check exact upload receipt reads a fresh authorized head and matches its exact binary SHA256 and revision metadata. A later head or an unavailable check leaves the receipt intact and the recheck unconfirmed.

Enlarge screenshot

1 2 3 4

1. Reviewed binary head
2. Reviewed generated artifact
3. Exact persisted UUID and revision24
4. Fresh binary check versus pending text readback

Community: review and append

1. In the generated document run, review its cited sources and actual file, then select I reviewed the cited sources and actual artifact. This also enables version review; leave Save new document and process unused when appending a revision. Open Or · Append an immutable file version and enter Existing Docs document ID and Reason for this version.
2. Check Request processing of the new revision after upload, then click Review current binary head. Inspect the family, current/new file hashes, saved request UUID and readable history. The view is bounded and shows at most ten returned history entries.
3. Select I approve these exact binary head and artifact hashes and the processing choice as one immutable revision. Click Append reviewed version once.
4. Use Read exact upload receipt to reconcile the saved UUID. Complete the separate saved-content verification in the document workflow. A known uploaded file remains uploaded even when its later processing or readback fails.

Both clients perform one upload for a saved claim. They do not retry an uncertain upload with a different UUID. Approval of the prepared artifact does not silently authorize later changes to its bytes or target.

Enlarge screenshot

1 2 3 4

1. Reviewed binary head and artifact
2. Exact persisted UUID
3. Read exact upload receipt
4. Separate processing/readback status

Lost responses and processing failures

After a timeout or restart, reopen the saved review and read its exact request receipt. A receipt that has not been observed is an unknown outcome; it is not proof that the upload failed. Do not remove the claim, repeat the upload or guess a newly created identifier.

If processing start is unconfirmed, retain the uploaded revision and use the IAM.Docs processing controls for that exact identifier when permitted. Reading the initial receipt does not restart processing and can still show its original uploaded status after later processing observations. The client keeps later verified observations separately.

For 401/403, restore the original authorized connection; a new token or server configuration may require a new source review. For 409, compare the live head and existing receipt. For an unavailable versions service, leave the operation pending and ask the operator to restore its qualified backend. Do not treat ordinary new-document upload as recovery of the same revision.

Retention

Versioned files are immutable in this workflow. Normal deletion of a registered revision is refused before file-storage side effects. Operators must keep the guarded API and schema after the first family is created, even when disabling new version writes. Forced database cleanup or rollback to an older API is not a customer recovery procedure.