Expose hard-link identities for untransformed resources

[wilx]

What does this change?

Provides an optional HardLinkIdentitySupplier capability for resources whose contents can share one hard-link payload. A resource backed by a file can supply replacement or transformed contents; using the backing inode alone to combine archive entries can discard distinct output bytes.

getHardLinkIdentity() returns an opaque, source-scoped identity for equality comparisons, or null when the relationship cannot be guaranteed.

• PlexusIoFileResource supplies an identity for direct, untransformed regular-file contents. It reads attributes without following symbolic links and includes filesystem scope, file key, size, and modification time. Missing file keys, custom suppliers, transformations, and subclasses without an explicit guarantee yield null.
• Deferred preserves source identity when its contents are untransformed.
• Resource proxies preserve identity through name-only changes. An alternate content or size supplier invalidates the inherited identity unless it explicitly supplies its own HardLinkIdentitySupplier guarantee.

Related issue

Provides the resource API used by Plexus Archiver PR #493 for TAR hard-link preservation, addressing the resource integration question in PR #286. TAR creation, extraction, and configuration reside in the archiver PR.

The companion archiver uses this artifact as plexus-io:3.7.1-SNAPSHOT. Install this branch with mvn install before building the archiver locally.

Anything reviewers should look at closely?

The capability is optional for resource implementations. PlexusIoFileResource implements it, and proxies expose it when their target or alternate supplier does.

Equal identities identify the same content within a stable source. Consumers may cache them for one archive operation and must also compare the output metadata they intend to write. The contract assumes the source remains stable while it is read; matching bytes from unrelated files do not establish hard-link identity.

Validation

• Three tests cover real hard links, transformed and custom contents, transparent renaming, replacement-content proxies, and deferred-resource identity propagation.
• mvn install javadoc:javadoc: 61 tests, 0 failures, 0 errors, 0 skips on Linux/JDK 17.
• mvn spotless:check and git diff --check passed.
• The interface and methods have Javadoc; identity checks and proxy propagation have explanatory comments.
• Companion archiver suite: 651 tests, 0 failures, 0 errors, 4 skips. A Maven Assembly Plugin 3.8.0 reproducer emits a TAR whose contents and shared inode are verified by GNU tar and bsdtar extraction.

Validation covers Linux; Windows and macOS have not been validated.