qbit-record-files/docs/EXISTING-ATTACHMENT-ADOPTION.md

Existing attachment adoption

Status: root gate95331 passed owner5/RF8 and the ordinary Script upload/release/preview/download native HTTP case. The legacy native adoption case returned process ERROR. The process confirmation used raw Boolean identity although native forms submit string values. Source now uses the existing core boolean converter; focused negative/current-authority assertions are expanded. Root rerun is pending. No running database, user attachment, stored object, installed artifact or existing evidence bundle has been changed.

The owner exposes AttachmentsService.adoptRetainedAttachment(Integer attachmentId) and the native attachment-table process collaborationAdoptRetainedAttachment (Retain existing original). All clients use the same ordinary QQQ process metadata. The only semantic input is an existing attachment ID; the form also requires confirmation. No locator, bytes, receipt, author or force flag is accepted.

The configured lifecycle must explicitly authorize adoption; the default policy refuses. The Record Files policy requires a managed parent, current parent visibility/attach capability, record-files.manage, and current credential/channel mutation ceilings. Owner author/admin checks remain mandatory. Internal/source-code/audit tables are not implicitly made upload targets.

The operation commits an independently durable ATTACHMENT_ADOPTION_ATTEMPT, establishes the existing source admission fence, locks and rereads the owner row, and streams the already stored original under the 20 MiB bound to verify exact stored length and SHA-256. It never calls storage put/delete or returns the bytes. A current-authority recheck follows external callbacks. The existing attachment ID, source, storage coordinates, name, description, author, creation time and digest/length remain unchanged; only retained=true and the native modification timestamp may change.

The retained flag and ATTACHMENT_RETENTION_ADOPTED event commit in the same owner transaction. Existing lifecycle registration then runs in its separately owned transaction, as with ordinary retained uploads. These commits are deliberately not described as atomic together. Registration failure leaves the original retained and inaccessible until an authorized idempotent retry completes the same registry row. The original was not retroactively journaled as a new upload. Existing coordinated intake keys must recover through their original intake workflow.

Registration continues to honor the host's quarantine policy. Adoption never automatically releases content. Review/release and subsequent authenticated preview/download remain the existing native operations; issued delivery descriptors are not evidence of byte transfer. The tracked route and its durable receipt establish the actual transfer observation.

The local development host now disables attachment defaults and explicitly enables the same retained allowlist: purchase orders and their lines, Script projects, document types, stock, templates and asset versions. RF metadata is produced after these tables exist. Script revision files and owner/audit internals remain disabled. The local storage provider still refuses untracked presigned URLs.

Pending selectors:

• Canonical collaboration owner: ExistingAttachmentAdoptionTest — 5 cases, native H2 owner transactions and explicit test-only policy.
• Record Files: ExistingAttachmentAdoptionTest — 8 cases, real owner/RF persistence, deterministic existing storage bytes, mandatory intent and registration failure/retry, corruption/current-authority refusal and native discovery.
• Acceptance: ManagedAttachmentHostTest — 2 real native HTTP cases for ordinary Script multipart upload and old unmanaged attachment adoption, explicit release, preview/download and exact-byte/hash receipts. No worker or renderer is required.

Actual user attachment 9 is not test data and has not been read, moved, changed or adopted by this work. Root-controlled qualification and migration/adoption must precede any change to that live original. The running host still uses its prior artifact cohort. Existing collection migration/provider transport failures remain separately recorded and unclassified.

Gate9254 follow-up: owner5/RF8 passed again; actual legacy native adoption, same ID/hash/bytes, replay, explicit release and both deliveries succeeded. The final negative assertion incorrectly assumed Script had the PO tenant lock. Both fixture actors have scripting.view; the test now explicitly establishes Bob's normal parent READ/delivery access, revokes his issued session, and requires 401 for parent, delivery issuance and the earlier tracked URL. No source permission or tenant model changed. Corrected two-case host gate pending.

Current qualification and local adoption — 2026-11-01

The final managed-attachment-host-authorization-verification.log passed both native HTTP cases with zero failures/errors/skips. Owner5 and RF8 passed in the preceding source-reactor gate. Script is a shared readable project in this fixture: Bob's parent READ and descriptor issuance are allowed before session revocation, then parent/descriptor/previous tracked URL refuse. No uploader-only download rule was introduced.

Root reports the separate controlled live adoption and explicit release of attachment 9 succeeded in runtime7 through public port18593: ID/name/size unchanged, exact516424-byte JPEG, and tracked preview/download receipts verified. That operation was performed by root after qualification, not by these tests. The original statements above describe the earlier source-staging checkpoint; no historic evidence bundle was amended.