qbit-record-files/docs/TRACKED-DOWNLOADS.md

Tracked retained-file delivery

Status: Record Files full verification/install passed155 tests with zero failures/errors/skips and Checkstyle at23:34:41 on2026-10-30. The owner seam passed204 tests and installed earlier. This is not a production deployment or physical-device qualification claim.

Configure the installed Record Files QBit with new DownloadConfiguration(trustedAbsoluteApiBase, 20 * 1024 * 1024, maximumConcurrent) and a qualified independently durable audit port. The base includes /qqq/v1 and is operator configuration, never an incoming Host header. HTTPS is required except loopback fixture HTTP. Concurrency is explicit, 1–16; use a heap budget that covers several bounded copies per admitted 20 MiB original. The 20 MiB bound equals the existing retained owner intake/read ceiling and cannot be lowered to strand admitted files. No additional blob store is created. The producer registers the native routes only when this configuration exists. Legacy installations without it retain signed-link issuance semantics and cannot claim observed delivery.

The generic Collaboration attachment delivery descriptor adds delivery=AUTHENTICATED_FETCH for governed files. Download and preview URL issuance both use this configured route; neither falls back to a signed original. The retained reader's additive RetainedDownloadGrant.authenticated field preserves this distinction, while the existing three-argument constructor continues to describe signed links. Consumers must honor the mode. Generation foundation now preserves the mode in its DTO and native process result (full63-test install passed). The optional Record Files bridge mapping and tests are staged; its owner is verifying the rebuilt artifact integration.

A client makes a native authenticated full GET to /qbit/record-files/files/{immutableFileId}/downloads/{attemptUUID}, with X-Record-Files-Download: 1. The UUID is a correlation identity, not a credential or a link-issuance authorization. Current actor, source/retained archive authority, exact immutable version and release status are rechecked for every transfer. Each attempt is single-use; a repeated body request fails the unique durable event constraint before opening bytes. After validating the descriptor's configured origin and canonical immutable-file route, the standard client creates a fresh UUID for each preview, download or retry, preserving that exact origin/file route. Each body and its receipt use the same fresh UUID. No old completed receipt can certify a new transfer. Range, HEAD, query modifiers and ambient transactions are unsupported.

Before opening canonical bytes, DOWNLOAD_ATTEMPT commits independently. The bounded owner reader then verifies length and SHA-256 with its own current authorization and content-read audit. A per-configuration admission permit covers byte allocation and output. Responses have octet-stream content type, attachment disposition, no-store, nosniff, referrer-policy and a restrictive sandbox CSP. No uploaded HTML or SVG is served as active same-origin content.

DOWNLOAD_BODY_WRITE_COMPLETED records only successful synchronous server writes and flush. It does not prove browser persistence, receipt at a remote device, viewing, or printing. An observed I/O failure records DOWNLOAD_INTERRUPTED; the byte count is a confirmed lower bound when a write fails midway. A crash or unavailable terminal audit leaves the durable attempt UNKNOWN. Bytes already accepted by a server output stream cannot be retracted if final persistence fails.

GET the same path plus /receipt with native authentication and the same explicit header. The route rechecks current exact-file rights and requires the initiating actor; opaque UUIDs do not enumerate another actor's evidence. It returns only state, expected byte length and SHA-256. The standard desktop fetch validates the exact configured API origin and canonical route before attaching credentials, derives the receipt path locally, and verifies completed evidence and hash before offering local save. It never follows a response-supplied receipt URL with credentials.

The FilesTab preview hook uses the same verified bytes and component-scoped blob URLs. Only byte-identified PNG, JPEG, GIF and WebP enter the image element; URLs are revoked and requests aborted on cleanup, with stale state cleared before reopening. HTML/SVG are refused inline. The PDF consumer uses a pinned PDF.js worker and canvas without an iframe/action layer, bounded streamed text, cancellation and page-resource cleanup. Ordinary ungoverned signed previews preserve existing behavior. PDF.js parsing is not a hostile-code containment boundary.

Transfer checks enforce a 120-second deadline between writes. A blocking servlet output operation also requires the deployment's connector/proxy write-idle timeout; the Java check alone cannot interrupt a blocked native write. Admission is per configured QInstance; multiple instances/processes need an aggregate host allocation. Browser save, network failure timing, proxy behavior and physical devices remain deployment qualification work.

Verification: owner204 tracked-delivery full install; Record Files18 focused native/JDBC tests then155 full tests/install; subsequent native HTTP/service5 passed, including fresh-attempt repeat transfers, old-attempt refusal and current-rights revocation. Frontend178 combined focused tests, lint/typecheck, then24 focused cleanup tests passed. The final production build and four existing Chromium PDF/order checks passed; an additional Chromium flow saved exact bytes after preview under distinct attempts, and refused a browser download for an UNKNOWN receipt. Browser routes use fixtures; native HTTP tests use real middleware authentication and file-backed JDBC audit with synthetic canonical storage. These are complementary checks, not a deployed-host end-to-end or provider retention qualification.