diff --git a/.zed/rules b/.zed/rules index 55f080ee8..66993d81f 100644 --- a/.zed/rules +++ b/.zed/rules @@ -249,6 +249,30 @@ commands (pytest on Python 3.11, 3.12 and 3.13; the others on 3.11): - The Graphviz `dot` binary is optional. The tests that render a graph to an image skip when `dot` is not on `PATH` and run when it is. +## Logical type identifiers + +A logical type's identifier is its Arrow extension name plus its Arrow extension metadata +(developer, November 11, 2026, ITL-935/ITL-938); see `docs/concepts/logical-type-identifiers.md`. + +- The identifier is declared in one place, the extension type returned by + `get_arrow_extension_type()`, and read through `logical_types/identifier.py` + (`logical_type_identifier`, `LogicalTypeIdentifier.text`). Never put a logical type's bare + name into a hash input: use the identifier text. +- Change a type's identifier when, and only when, an existing value would be stored or hashed + differently. It is not a package version. Built-in types use `version_metadata(N)` + (`{"version":N}`); a new built-in type must write one, never empty metadata. +- A changed identifier is a schema change: it moves stored paths and golden values of that + type. Treat it like any other hash change (developer approval, migration assessment). +- The native containers `list[T]` / `set[T]` of a logical type (`ListLogicalType`) have no + version of their own, by design: never add a `"version"` key to their metadata. Their + identifier is the container kind plus the element's identifier; the type hash treats them + like any generic alias (origin and arguments). A change to how they are stored or hashed is + a data context (global hash version) change, not a logical type change. +- On read, stored metadata must be one of the type's `readable_extension_metadata()`; + otherwise raise `LogicalTypeIdentifierError`. Never wrap a stored column by name alone and + never fall back to the storage type. List an older value in `also_reads` only when the + current code decodes that layout. + ## Golden hash values Hash values must stay identical across releases (developer, November 10, 2026). Every hash @@ -263,6 +287,34 @@ checked by `tests/test_hashing/golden/test_golden_hashes.py`. - Never move or rename the fixtures in `tests/test_hashing/golden/cases.py`: function pods, dataclasses and pydantic models hash with their module path. +## Hash labels + +One rule holds for every hash label (developer, November 11, 2026; ITL-945; stated with +examples in `docs/reference/hashing.md`, "The hash label rule"). + +- A label names the algorithm that produced a digest (the whole procedure: canonical form, + preparation, encoding, digest function) and nothing else. Format `_v`, + integer `N`: `semantic_v1`, `arrow_v1`, `directory_v1`, `ndarray_v1`, `polars_expr_v1`. The + file content hash keeps `sha256`, the only exception. A logical type's implementer picks + its label. +- Change a label only when its algorithm would give an existing input a different digest. +- Define each label in exactly one place, as a constant beside its algorithm. Never write a + label literal anywhere else in code, and never in a data context file. +- Never feed a label into a hash computation. Feed a nested hash's digest only: never put + `to_string()`, `str(hash)` or `to_prefixed_digest()` into an identity structure, a preimage + table or a digest input. Inside a structure, return the `ContentHash` object and let the + structure hasher embed it. +- A hash inside a name (path component, column name, `uri`) is the bare hex digest: + `to_hex()`. Exception (developer, November 11, 2026): a source id is the source's name. A + default source id built from a hash keeps a source-kind prefix and the hash's label + (`derived: