feat(authoring): support quiescent writable APFS package reads

[777genius]

Problem and behavior

The standard-first package reader needs writable ordinary local APFS support under the accepted quiescent-source contract. This change adds bounded ordered path resolution, thread-scoped materialization policy and explicit ownership/cleanup for the Darwin reader. The source and ancestor bindings must remain unchanged from Open through Close, including the Open/Capture gap. Hostile concurrent writers are outside this contract.

Stacked on #183 (test/authoring-physical-fixture-delivery); do not retarget to main without rebasing the dependency stack. This is the reader/contracts checkpoint. Command integration, producer qualification and release activation remain later gates in the implementation plan.

The shared post-open guard also preserves Windows native metadata registration: ordinary reads use the existing verified lease observation, while unknown metadata and hardlinks remain rejected.

Validation

• Linux packageview and 29 regression package groups passed on the implementation checkpoints; Darwin no-cgo and Windows cross-compilation passed. Cross-compilation is not native qualification.
• Native Darwin arm64, macOS 15.6.1 / ordinary APFS, Go 1.25.13: focused reader/policy/shared tests and no-cgo rejection/zero-value Close tests passed on afc579c.
• Exact final test-only patch in b9f98ac: all five native focused tests passed, including ten traversal cancellation/cause cases, distinct Capture context handoff, panic/FD cleanup, scratch aliases and observed-change precedence.
• Independent reviews accepted the production corrections and the final C1 test correction. Deadline fixture cases explicitly prove synthetic cause propagation, not wall-clock timer expiry.
• Exact head 178dfd823bb3cc083b2abc75bbc0752529a6826b: all GitHub checks passed, including native Linux/Windows amd64 and arm64, packed Linux, source acquisition and both polyglot smoke jobs. Windows artifacts were inspected: zero failure or skip records, with both new ordinary-read tests and the unchanged hardlink test passing on each architecture.
• The same head passed focused native Darwin arm64 regression tests for ordinary capture, legacy/hardlink rejection, cleanup and writable APFS cancellation/context handoff/panic/FD behavior. Independent static review found no actionable defect in the four-file Windows correction. This remains a draft reader checkpoint; later release qualification is separate.

Scope and remaining gates

Useful legacy YAML code, dependencies, tests and assets remain preserved. No YAML fallback or second engine is introduced. No public release or Pages activation is included.

The existing Windows parent-sharing gate remains unresolved. Device/dataless behavior, advertised macOS floor, ambient policy interaction, producer and CLI release qualification are not established by the focused native results. These limits must remain explicit before release.

Review size is 2,366 changed lines across 26 files, slightly above the 2,000-line target. The reader contract, resolver, scoped I/O policy and causal cleanup tests form one coherent acquisition invariant; splitting them would leave intermediate behavior unsupported. Most additions are focused tests and contract documentation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}