Finish the match key rename in the 51Did payload constants

[jwrosewell]

The problem

The stable, comparable part of a 51Did is called the match key. That
rename reached the accessor, where getMatchKey() is the real method and
getHash() is kept as a deprecated alias, but it never reached the payload
constants in
FodId.java.

Two constants still carried the old hash name even though their own
documentation already described the field as the match key, so the comment
and the name disagreed on the same line.

/** Byte offset of the match key field within the payload. */
public static final int HASH_OFFSET = 5;

/** Byte length of the match key field (SHA-256). */
public static final int HASH_LENGTH = 32;

Anyone reading the class had to work out for themselves that the two names
meant the same thing as getMatchKey().

What changed

MATCH_KEY_OFFSET and MATCH_KEY_LENGTH are now the real constants. They
keep the values they had, 5 and 32, and they keep the documentation they
had, which already used the right words.

HEADER_LENGTH and PAYLOAD_LENGTH keep their own names, which were never
wrong, and are now worked out from the new constants.

public static final int HEADER_LENGTH = MATCH_KEY_OFFSET;

public static final int PAYLOAD_LENGTH =
    MATCH_KEY_OFFSET + MATCH_KEY_LENGTH;

Every use of the old names moves to the new ones, which is 23 references
across six files.

File	References moved
pipeline.did/.../FodId.java	6
pipeline.did/.../DidClient.java	1
pipeline.did/.../FodIdTestFactory.java	4
pipeline.did/.../FodIdTests.java	8
pipeline.developer-examples/.../fodid/Main.java	2
pipeline.developer-examples/.../fodid/ExampleTests.java	2

The 51Did package README
gains a short paragraph next to the existing getHash() note, so the
constant naming is described in the same place as the accessor naming.

Nothing to do with SHA-256 hashing itself is renamed, and the unrelated
Device Detection Hash classes are untouched.

Why the old names are kept

HASH_OFFSET and HASH_LENGTH stay as deprecated aliases of the new
constants, so code already written against the earlier names keeps
compiling and reads the same values.

/**
 * Deprecated alias for {@link #MATCH_KEY_OFFSET}. The stable, comparable
 * part of a 51Did is now called the match key, mirroring the Model Terms
 * for Marketing vocabulary. This alias will be removed in a future
 * release.
 *
 * @deprecated renamed to {@link #MATCH_KEY_OFFSET}
 */
@Deprecated
public static final int HASH_OFFSET = MATCH_KEY_OFFSET;

The wording follows the getHash() deprecation already in the same file,
so a reader meets one explanation of the rename rather than two, and the
two aliases will be removed together in a future release.

How it was verified

A new test asserts the aliases still read the same values as the constants
they point at, because a deprecated alias nothing exercises is an alias
nobody notices breaking.

@Test
@SuppressWarnings("deprecation")
public void hashConstants_DeprecatedAliases_MatchNewNames() {
    assertEquals(FodId.MATCH_KEY_OFFSET, FodId.HASH_OFFSET);
    assertEquals(FodId.MATCH_KEY_LENGTH, FodId.HASH_LENGTH);
}

Built and tested with Apache Maven 3.9.16 on Java 21.0.11.

mvn -B -pl pipeline.did test

[INFO] --- animal-sniffer:1.24:check (check-java8-api) @ pipeline.did ---
[INFO] Checking unresolved references to org.codehaus.mojo.signature:java18:1.0
...
[INFO] Running fiftyone.pipeline.did.DidClientLiveTests
[WARNING] Tests run: 2, Failures: 0, Errors: 0, Skipped: 2, Time elapsed: 0.089 s
[INFO] Running fiftyone.pipeline.did.DidClientTests
[INFO] Tests run: 63, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.826 s
[INFO] Running fiftyone.pipeline.did.FodIdParseTests
[INFO] Tests run: 20, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.036 s
[INFO] Running fiftyone.pipeline.did.FodIdTests
[INFO] Tests run: 42, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.052 s
[INFO] Results:
[WARNING] Tests run: 127, Failures: 0, Errors: 0, Skipped: 2
[INFO] BUILD SUCCESS

The two skipped tests are DidClientLiveTests, which are skipped by design
because they call the live cloud service and no resource key was supplied.

mvn -B -pl pipeline.did,pipeline.developer-examples,pipeline.developer-examples/pipeline.developer-examples.fodid test

[INFO] Running pipeline.developerexamples.fodid.ExampleTests
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.042 s
[INFO] Reactor Summary for 51Degrees :: Pipeline :: 51Did 4.5.7-SNAPSHOT:
[INFO] 51Degrees :: Pipeline :: 51Did ..................... SUCCESS [ 22.300 s]
[INFO] 51Degrees :: Pipeline :: Developer Examples ........ SUCCESS [  0.002 s]
[INFO] 51Degrees :: Pipeline :: Developer Examples :: 51Did SUCCESS [  8.442 s]
[INFO] BUILD SUCCESS

The Java 8 signature check that this module runs over its compiled classes
also passed, so the change stays inside the API floor the module holds
itself to.

A repository-wide search for the two old names now returns six lines only,
being the two deprecated alias declarations in FodId.java, the two
assertions and the comment in the new test, and the sentence in the README
that describes the aliases. No working code reads the old names any more.

Outstanding

Nothing in this repository. The same pair of constants may carry the old
name in the other language ports of the 51Did reader, which is worth a
check before the aliases are removed.

The pull request is left open and is not merged.

Produced with AI assistance under James Rosewell's direction and needs human review.