Implement Perl-compatible restricted-hash semantics

[fglock]

Summary

Implement Perl-compatible restricted-hash semantics for Hash::Util on both the JVM and interpreter backends.

Current behavior

The bundled Hash::Util exposes several restricted-hash APIs, but key-locking is a no-op and the remaining operations are only partially implemented:

• lock_keys and unlock_keys are registered but do not change hash behavior.
• lock_value and unlock_value are compatibility no-ops.
• lock_keys_plus is a no-op.
• lock_hash prevents some writes, but does not reject reads of missing keys and does not consistently reproduce Perl's restricted-hash diagnostics.
• Inspection helpers such as hash_locked and hash_unlocked return placeholder values.

The feature matrix currently marks restricted hashes unsupported. docs/reference/bundled-modules.md should also be reconciled because it currently lists Hash::Util as providing lock_keys and lock_hash without describing the partial semantics.

Reproduction

use Hash::Util qw(lock_keys lock_hash);

my %keys = (a => 1);
lock_keys(%keys, 'a');
my $added = eval { $keys{b} = 2; 1 };
my $read  = eval { my $value = $keys{b}; 1 };

my %hash = (a => 1);
lock_hash(%hash);
my $missing = eval { my $value = $hash{b}; 1 };

Native Perl rejects the disallowed-key operations. PerlOnJava currently allows the lock_keys add/read operations and the lock_hash missing-key read on both backends.

Compatibility evidence

CPAN distribution MooX::Params::CompiledValidators v0.05 failed 3 of 17 tests under PerlOnJava in run 20260922-180448-60378:

• t/010-basic.t: restricted-hash access was not rejected.
• t/020-moose.t: restricted-hash access was not rejected.

Under system Perl, those two test files pass. The third file has an unrelated warning-sensitive Type::Tiny serialization failure.

The smallest direct probe also reproduces the backend gap: native Perl reports Attempt to access disallowed key, while both JVM and interpreter return without an error.

Proposed scope

• Implement key restrictions and enforcement for read, write, delete, and key creation.
• Implement whole-hash and value locking/unlocking with Perl-compatible state transitions.
• Implement lock_keys_plus and inspection helpers with correct results.
• Match Perl's relevant error behavior where practical.
• Add project-owned unit tests covering both backends and validate expected behavior with standard Perl.
• Update the bundled-modules documentation to distinguish implemented APIs from partial/no-op compatibility shims.

References

• dev/tools/feature-audit/remaining_semantics.t already records restricted-hash enforcement as failing on both backends.
• dev/design/feature-audit-plan.md records this as a known unsupported gap.