macOS APFS: com.apple.macl and UF_TRACKED appear after creating a hard link — safe file replacement and rollback?

I'm investigating an unexpected metadata change during a controlled file deployment on macOS.

Environment and observed state

Two regular configuration files are used by a local service. Before replacement, the first file had:

  • SHA-256: verified.
  • File flags: 0.
  • Extended attributes: none.
  • Hard-link count: 1.
  • Owner/group: 501/20.
  • Permissions: 0644.
  • ACL: empty.

A backup procedure created a hard link to preserve the original inode before replacing the active pathname with an independently created file.

Immediately after creating and verifying the hard link, the original file was observed with:

  • The same SHA-256 and inode.
  • Flags: 64 (UF_TRACKED).
  • Extended attribute: com.apple.macl.
  • Hard-link count: 2.

No file content was replaced. The procedure stopped because the metadata no longer matched the original baseline.

Additional observations

  • Other backup methods also encountered unexpected metadata changes during destination creation.
  • Tests using renamex_np with RENAME_SWAP successfully exchanged and restored artificial files with flags 0 and empty extended attributes.
  • A test with artificial files already containing com.apple.provenance also succeeded.
  • We could not reproduce the specific UF_TRACKED + com.apple.macl + two-hard-link state in an isolated fixture using ordinary documented operations.
  • The operational original and its second hard link currently share the same inode. No attempt has been made to remove the protected attribute or change its flags.

Questions for Apple filesystem/security specialists

  1. Under what documented circumstances can creating a hard link or related Finder/TCC document-tracking behavior cause UF_TRACKED and com.apple.macl to appear on an existing file?
  2. Are these metadata changes expected for a file accessed through a user-authorized Documents location?
  3. What supported mechanism can preserve the current original inode and provide a verifiable rollback when replacing its active pathname?
  4. Is renamex_np(..., RENAME_SWAP) appropriate for this situation, and what special considerations apply to the existing second hard link and protected extended attributes?
  5. What verification criteria would you recommend before permitting a production replacement?

I am looking for a documented, reversible procedure that preserves macOS security protections. I do not want to disable SIP, forcibly remove com.apple.macl, or bypass TCC.

I can provide sanitized metadata comparisons and a minimal reproduction if needed.

Answered by DTS Engineer in 917595022

See my reply on this thread.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

See my reply on this thread.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"