docs: add include_metadata docstrings and README section (PLT-1734)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kurodo3[bot]

README.md

@@ -36,6 +36,31 @@ for batch in batches:
 digest = digester.finalize()
 ```
 
+## Metadata hashing
+
+By default, Arrow schema- and field-level metadata are excluded from the hash,
+preserving hash format 0.0.1 stability. Pass `include_metadata=True` to any
+entry point to include them:
+
+```python
+# One-shot
+digest = ArrowDigester.hash_table(table, include_metadata=True)
+
+# Streaming
+digester = ArrowDigester(schema, include_metadata=True)
+for batch in batches:
+    digester.update(batch)
+digest = digester.finalize()
+```
+
+When `include_metadata=True`, adding or changing any metadata key or value on
+any field (including nested struct children and list element fields) produces a
+different hash. Metadata key ordering is deterministic — the hash is stable
+regardless of insertion order.
+
+A schema with no metadata produces the same hash regardless of `include_metadata`
+(empty-metadata invariant).
+
 ## License
 
 MIT OR Apache-2.0

src/starfix/arrow_digester.py

@@ -743,7 +743,14 @@ def _finalize_digest(final_digest, entry: tuple) -> None:
 class ArrowDigester:
     """Pure-Python equivalent of the Rust ``ArrowDigester``.
 
-    Produces identical SHA-256 hashes with a 3-byte version prefix.
+    Produces identical SHA-256 hashes with a 3-byte version prefix
+    (hash format version 0.0.1, independent of the package version).
+
+    By default, Arrow schema- and field-level metadata are excluded from
+    the hash. Pass ``include_metadata=True`` to any entry point to include
+    them — see the ``include_metadata`` parameter on each method.
+    A schema with no metadata produces the same hash regardless of that
+    flag (empty-metadata invariant).
     """
 
     def __init__(self, schema: pa.Schema, *, include_metadata: bool = False) -> None:
@@ -816,7 +823,9 @@ def hash_record_batch(record_batch: pa.RecordBatch, *, include_metadata: bool =
             record_batch: The record batch to hash.
             include_metadata: When True, schema-level and per-field Arrow
                 metadata are included in the hash. Default is False,
-                preserving hash format 0.0.1 stability.
+                preserving hash format 0.0.1 stability. A schema with no
+                metadata produces the same hash regardless of this flag
+                (empty-metadata invariant).
         """
         d = ArrowDigester(record_batch.schema, include_metadata=include_metadata)
         d.update(record_batch)
@@ -830,7 +839,9 @@ def hash_table(table: pa.Table, *, include_metadata: bool = False) -> bytes:
             table: The table to hash.
             include_metadata: When True, schema-level and per-field Arrow
                 metadata are included in the hash. Default is False,
-                preserving hash format 0.0.1 stability.
+                preserving hash format 0.0.1 stability. A schema with no
+                metadata produces the same hash regardless of this flag
+                (empty-metadata invariant).
         """
         d = ArrowDigester(table.schema, include_metadata=include_metadata)
         for batch in table.to_batches():
@@ -842,6 +853,10 @@ def hash_array(array: pa.Array) -> bytes:
         """Hash a single array (spec Section 6).
 
         Uses the same recursive BTreeMap decomposition as the record-batch path.
+
+        Note:
+            ``include_metadata`` is intentionally absent here — standalone arrays
+            carry no schema or field metadata. This matches the Rust ``starfix`` API.
         """
         import pyarrow as pa