Document server-owned canonical authorization namespace hashes

[zcourts]

Contract gap

anvil-core/src/authz_realm_schema.rs canonicalizes an authorization schema and replaces each client-supplied namespace hash with a deterministic protobuf-domain hash. That appears intentional, but clients can reasonably interpret the request hash as round-trippable input and reject the correct returned schema.

Required contract

Document and test that:

• client-supplied namespace hashes are not preserved;
• Anvil canonicalizes schema semantics and the returned non-empty namespace hash is authoritative;
• clients should compare canonical semantics and/or an authoritative schema-reference digest, not a JSON-input-domain hash;
• the hash algorithm/domain/version has an explicit compatibility story.

Do not change canonical server hashing merely to preserve arbitrary client hashes.

Acceptance criteria

• Public schema API documentation states ownership and validation semantics.
• Proto/API field comments identify input versus authoritative output behavior.
• Round-trip test submits a differing non-empty client hash and proves the returned schema is semantically equivalent with Anvil’s canonical hash.
• Compatibility/versioning behavior is covered for future canonical encoding changes.

[zcourts]

Contract update written, not yet built (2026-07-29): all shipped client proto copies now state that input AuthzNamespaceSchema.schema_hash is ignored at publication and responses contain Anvil's authoritative deterministic-protobuf-domain hash. The public authorisation guide documents semantic validation, schema-reference digests, and hash-domain/version compatibility. A focused test proves a client JSON-domain hash is replaced while namespace JSON/relations remain semantically intact. Formatting/diff checks pass; generated-client and API tests remain for the consolidated build.