fix(hashing): route Schema through SchemaHandler, not _expand_mapping (ITL-639)

[kurodo3]

Summary

• Fixes dispatch order in SemanticAwarePythonHasher.hash_object so registered handlers run before the _is_structure check. This makes SchemaHandler reachable for Schema objects (previously intercepted as a plain Mapping by _expand_mapping).
• Replaces the NotImplementedError stub in SchemaHandler with the canonical implementation: iterates fields in sorted order, hashes each Python type via TypeObjectHandler, validates Arrow-translatability when a type_converter is available.
• Wires type_converter into SchemaHandler at registration (both in register_builtin_python_type_handlers and in v0.1.json) so unregistered types are caught at hash time with a clear diagnostic error.
• Adds SchemaHandler to the v0.1.json context registry — it was previously absent, meaning the handler was never registered when loading from the JSON spec.
• Adds four regression tests (TestSchemaHashBehavior): dispatch routing, module-rename stability, Arrow-translatability guard, and optional_fields exclusion.
• No hash values change. All eight golden schema hashes in schema_hash_golden.json remain byte-identical.

Fixes ITL-639

Test plan

• uv run pytest tests/test_hashing/ -v — all 10 tests pass, including TestSchemaHashStability with unchanged golden hashes
• uv run pytest tests/ -x -q — full suite (4823 passed, 93 skipped, 2 xfailed)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

🟢 Approval recommended

The changes are narrowly scoped, align with the PR’s stated intent, and are backed by targeted regression tests plus context-registry wiring to ensure the handler is actually used in the default configuration.

Pull request overview

This PR fixes schema hashing dispatch so Schema objects are hashed via the explicit SchemaHandler (rather than being intercepted as a generic Mapping and expanded via _expand_mapping). It also implements the canonical SchemaHandler behavior (stable field hashing + optional Arrow-translatability validation), registers it in the v0.1 context spec, and adds regression tests to prevent the original routing bug and module-rename instability from recurring.

Changes:

• Reorders SemanticAwarePythonHasher.hash_object dispatch so registered handlers run before the generic “structure expansion” path.
• Implements SchemaHandler and wires type_converter into its registration (code + v0.1 JSON context registry).
• Adds regression tests covering SchemaHandler routing, module-rename stability, unregistered-type rejection, and optional_fields exclusion; adds supporting design/plan artifacts under superpowers/.

File summaries

File	Description
src/orcapod/hashing/semantic_hashing/semantic_hasher.py	Moves handler dispatch ahead of _is_structure to ensure SchemaHandler is reachable for Schema instances.
src/orcapod/hashing/semantic_hashing/builtin_handlers.py	Implements SchemaHandler with deterministic field hashing and optional Arrow-translatability validation; registers it with type_converter.
src/orcapod/contexts/data/v0.1.json	Registers SchemaHandler (with type_converter reference) in the default context’s Python handler registry.
tests/test_hashing/test_type_annotation_golden.py	Adds TestSchemaHashBehavior regression tests for dispatch routing and stability/validation rules.
superpowers/specs/2026-09-03-itl-639-schema-hashing-arrow-representation-design.md	Design write-up documenting the motivation and intended hashing/validation behavior for ITL-639.
superpowers/plans/2026-09-03-itl-639-schema-hashing.md	Implementation plan artifact capturing the step-by-step work and verification checklist for ITL-639.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.