Replicated File Provider: supported download representation for a directory-backed package

The isolated test described above has now completed on macOS 27.0.1 (26A434), with a normally signed replicated extension.

We used a synthetic RTFD directory package with known text, a nested directory, a zero-byte file and an empty directory, plus a regular-file control. Both uploaded successfully. We then evicted only those fixtures through NSFileProviderManager and verified that both were dataless before selecting Finder's Download Now.

The system initiated a fetch for the package root. The represented item type was com.apple.package, and the actual requestedVersion was nil. Our extension reconstructed the authenticated members in the manager-provided, same-volume temporary location and passed the directory URL to the fetch completion. The returned item's content version represented those same members.

The native fetch completed without error. Both items were materialized before verification read their contents. Every file's SHA-256 matched its retained source; nested structure, the zero-byte file and the empty directory were preserved. The regular-file control also matched. No archive representation or special testing entitlement was used.

This establishes the observed behavior for that synthetic current-version request on this OS. It does not establish an API guarantee or explain the SDK's regular-file wording. Is returning this directory URL a supported package handoff? If so, which contract governs it, including content type, version and ownership requirements? We would like to distinguish supported behavior from an implementation detail before relying on it more broadly.

We have narrowed a second failure associated with this package representation. The following separates native observations from provider-only reproduction.

On the same macOS build, the isolated RTFD and Numbers package tests materialized successfully. Their retained native trees contain a package root but no independently registered member items. Other existing packages instead have both the package root and six immediate children registered as separate File Provider items. The native dump explicitly reports “Item parented to non-directory” at that relationship. Native remote-to-local child creation repeatedly fails with NSPOSIXErrorDomain 22 and cannotOpenByHandle. These are system application failures, not upload createItem errors. Root identity and its materialized directory agree; the log does not identify the exact rejected handle.

Using our existing production callbacks and enumerators with a synthetic directory package, we reproduced the projection difference without a registered native domain:

• The root has one stable itemIdentifier and parentItemIdentifier. contentType is exactly com.apple.package. At runtime it conforms to public.directory and com.apple.package, but not public.folder. Lookup, parent-folder enumeration, mutation completion and whole-package fetch agree on that type and the represented content version. Capabilities agree across those paths. We implement contentType; the selected macOS SDK marks typeIdentifier unavailable.

• Explicit enumeration of the package ID returns its six direct members with their own stable IDs and the package ID as parent. Whole-package fetch also returns those members inside the reconstructed directory, with the version describing that content.

• Initial working-set enumeration of a root-only materialized roster emits only the package root.

• A member-create change processed while the package root is materialized emits the root update first and then the independent member. A reported-but-not-materialized root does not make the new child eligible. Once a child has been reported, a subsequent member update remains eligible after reopening the persisted provider state, even without materialized membership.

This reproduces our callback output, not Apple's rejection in an isolated framework test. We do not have the historical membership timing needed to claim exactly how the affected native records were introduced. Retained creation receipts support whole-package create/retry; their early backend root receipt does not prove early completion to the system.

For a root represented and fetched as a package, should internal members ever be independently presented as native File Provider items? If this projection is invalid, which documented operation reconciles already retained child records while preserving stable remote identities and any uncommitted local package/member edits? Is there a supported metadata correction for this case?

Simply omitting future members does not establish recovery of already pending child operations. We have not sent deletion events for still-existing members, reported them missing, changed the root to public.folder, cleared state, replaced identities or recreated a domain. The reimportItems documentation concerns invalid identifiers, may reimport beyond the requested subtree, and schedules createItem with mayAlreadyExist; these identifiers are still valid. Its applicability and preservation behavior for this specific transition remain unclear.

The original directory-URL handoff contract question also remains open. We are seeking the supported package/child projection and existing-state transition, without introducing an archive storage format or a separate synchronization mechanism.

First off, sorry for the delay replying to this but I wanted to confirm a few details with the engineering team.

Getting into the details:

Is returning this directory URL a supported package handoff?

Yes. In that context, the header doc basically means "file" in the user experience sense, not at the file system level. The real difference here is between directory browsing (where it's expected that not all files will be available) and interacting with a document (where missing data could be considered file corruption).

For a root represented and fetched as a package, should internal members ever be independently presented as native File Provider items?

Ideally, no, but in practice it will probably happen. Having said that, a package presented as individual items should still work fine, as it simply changes exactly when any given object is downloaded.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware