zarr-metadata 0.2.0 → 0.4.0

package/README.md

@@ -76,9 +76,13 @@ package's flat problem lists; `flattenTree`/`treeOf` convert between the
 two, and the flat path+kind form remains the cross-language interchange
 format the conformance corpus asserts on.
 
-Validation is structural (key presence, value shapes, fixed literals), not
-domain-level: extension points (codecs, chunk grids, data types) are never
-interpreted, matching the Python package's layering.
+The structural validators check key presence, value shapes, and fixed
+literals without interpreting extension points, matching the Python
+package's layering. `validateArraySemanticsV3` is a separate,
+TS-only semantic layer on top: it interprets the well-known core extension
+points to enforce the specs' cross-field prose rules (regular chunk grid
+arity, transpose permutations, sharding divisibility, fill_value vs data
+type), skipping unrecognized names — the extension name space is open.
 
 Consumers include the
 [Zarr Metadata VS Code extension](https://github.com/d-v-b/vscode-zarr).

package/dist/index.d.ts

@@ -8,6 +8,7 @@
 export type { JSONValue, ZarrV3MetadataFieldJSON, ZarrV3NamedConfigJSON } from "./common.js";
 export { flattenTree, formatTree, isEmptyTree, MetadataValidationError, treeOf, type ErrorTree, type Issue, type IssueKind, type IssuePath, type ParseResult, type PathedIssue, } from "./errors.js";
 export * from "./schemas.js";
+export * from "./semantics.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";
 export * from "./v2.js";
 export * from "./v3.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,SAAS,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,MAAM,EACN,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,SAAS,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC7F,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,MAAM,EACN,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@
  */
 export { flattenTree, formatTree, isEmptyTree, MetadataValidationError, treeOf, } from "./errors.js";
 export * from "./schemas.js";
+export * from "./semantics.js";
 export * from "./v2.js";
 export * from "./v3.js";
 export * from "./validation.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,MAAM,GAOP,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC;AAE7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,EACvB,MAAM,GAOP,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAE/B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC"}

package/dist/semantics.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Semantic (cross-field) validation for v3 array metadata.
+ *
+ * The structural validators never interpret what an extension point names;
+ * this module deliberately interprets a small set of WELL-KNOWN core
+ * extension points to enforce the cross-field rules the specs state in
+ * prose:
+ *
+ * - the `regular` chunk grid's `chunk_shape` has one length per dimension
+ *   of `shape`;
+ * - the `rectilinear` chunk grid's `chunk_shapes` has one entry per
+ *   dimension, and each explicit chunk list (integers and `[size, count]`
+ *   run-length pairs) sums exactly to that dimension's length (the
+ *   bare-integer uniform shorthand carries no sum constraint, like the
+ *   regular grid);
+ * - a `transpose` codec's `order` is a permutation of `0..n-1`, with one
+ *   entry per array dimension;
+ * - a `sharding_indexed` codec's inner `chunk_shape` matches the array's
+ *   dimensionality and evenly divides every chunk it shards — the grid's
+ *   chunk at the top level (each distinct per-dimension size, for
+ *   rectilinear grids), the parent shard's inner chunk when sharding
+ *   nests;
+ * - `fill_value` has a JSON shape permitted for the named core data type
+ *   (booleans for `bool`, ranged integers for the int types, numbers /
+ *   the "NaN"-family sentinels / width-checked "0x…" strings for the
+ *   float types, two-element arrays for the complex types).
+ *
+ * Unrecognized names are skipped everywhere — the extension name space is
+ * open, and a rule that guessed would lie. This layer has no counterpart
+ * in the Python reference implementation (which stops at structure), so it
+ * is covered by this package's own tests rather than the conformance
+ * corpus.
+ */
+import { type ErrorTree } from "./errors.js";
+/**
+ * Every semantic (cross-field) problem in a v3 array metadata document, as
+ * an error tree; an empty tree means no rule found a violation. Values that
+ * are not v3 array documents yield an empty tree; run the structural
+ * validators for structure.
+ */
+export declare function validateArraySemanticsV3(value: unknown): ErrorTree;
+//# sourceMappingURL=semantics.d.ts.map

package/dist/semantics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.d.ts","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAoB,MAAM,aAAa,CAAC;AAuMvE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAqFlE"}

package/dist/semantics.js

@@ -0,0 +1,303 @@
+/**
+ * Semantic (cross-field) validation for v3 array metadata.
+ *
+ * The structural validators never interpret what an extension point names;
+ * this module deliberately interprets a small set of WELL-KNOWN core
+ * extension points to enforce the cross-field rules the specs state in
+ * prose:
+ *
+ * - the `regular` chunk grid's `chunk_shape` has one length per dimension
+ *   of `shape`;
+ * - the `rectilinear` chunk grid's `chunk_shapes` has one entry per
+ *   dimension, and each explicit chunk list (integers and `[size, count]`
+ *   run-length pairs) sums exactly to that dimension's length (the
+ *   bare-integer uniform shorthand carries no sum constraint, like the
+ *   regular grid);
+ * - a `transpose` codec's `order` is a permutation of `0..n-1`, with one
+ *   entry per array dimension;
+ * - a `sharding_indexed` codec's inner `chunk_shape` matches the array's
+ *   dimensionality and evenly divides every chunk it shards — the grid's
+ *   chunk at the top level (each distinct per-dimension size, for
+ *   rectilinear grids), the parent shard's inner chunk when sharding
+ *   nests;
+ * - `fill_value` has a JSON shape permitted for the named core data type
+ *   (booleans for `bool`, ranged integers for the int types, numbers /
+ *   the "NaN"-family sentinels / width-checked "0x…" strings for the
+ *   float types, two-element arrays for the complex types).
+ *
+ * Unrecognized names are skipped everywhere — the extension name space is
+ * open, and a rule that guessed would lie. This layer has no counterpart
+ * in the Python reference implementation (which stops at structure), so it
+ * is covered by this package's own tests rather than the conformance
+ * corpus.
+ */
+import { treeOf } from "./errors.js";
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+function isIntArray(value) {
+    return (Array.isArray(value) &&
+        Object.keys(value).length === value.length &&
+        value.every((item) => Number.isInteger(item)));
+}
+/** The `{name, configuration}` of a metadata field, when extractable. */
+function fieldParts(field) {
+    if (typeof field === "string")
+        return { name: field, configuration: undefined };
+    if (isPlainObject(field) && typeof field["name"] === "string") {
+        const configuration = field["configuration"];
+        return {
+            name: field["name"],
+            configuration: isPlainObject(configuration) ? configuration : undefined,
+        };
+    }
+    return undefined;
+}
+// --- fill_value vs data_type ----------------------------------------------
+const INT_RANGES = {
+    int8: [-128, 127],
+    int16: [-32768, 32767],
+    int32: [-2147483648, 2147483647],
+    int64: [-9223372036854775808, 9223372036854775807],
+    uint8: [0, 255],
+    uint16: [0, 65535],
+    uint32: [0, 4294967295],
+    uint64: [0, 18446744073709551615],
+};
+const FLOAT_HEX_DIGITS = {
+    float16: 4,
+    float32: 8,
+    float64: 16,
+};
+/** Hex digit width of each complex type's component floats. */
+const COMPLEX_COMPONENT_HEX_DIGITS = {
+    complex64: 8,
+    complex128: 16,
+};
+function isFloatFill(value, hexDigits) {
+    if (typeof value === "number")
+        return true;
+    if (typeof value !== "string")
+        return false;
+    if (value === "NaN" || value === "Infinity" || value === "-Infinity")
+        return true;
+    return new RegExp(`^0x[0-9a-fA-F]{${hexDigits}}$`).test(value);
+}
+function floatFillMessage(name, hexDigits) {
+    return (`expected a number, "NaN", "Infinity", "-Infinity", or a ` +
+        `${hexDigits}-hex-digit "0x..." string for data type ${JSON.stringify(name)}`);
+}
+/** The fill_value issue for a KNOWN core data type, if any; undefined otherwise. */
+function fillValueIssue(dataTypeName, fill) {
+    if (dataTypeName === "bool") {
+        return typeof fill === "boolean"
+            ? undefined
+            : 'expected a boolean fill value for data type "bool"';
+    }
+    const intRange = INT_RANGES[dataTypeName];
+    if (intRange !== undefined) {
+        const [low, high] = intRange;
+        return Number.isInteger(fill) && fill >= low && fill <= high
+            ? undefined
+            : `expected an integer in [${low}, ${high}] for data type ${JSON.stringify(dataTypeName)}`;
+    }
+    const floatDigits = FLOAT_HEX_DIGITS[dataTypeName];
+    if (floatDigits !== undefined) {
+        return isFloatFill(fill, floatDigits)
+            ? undefined
+            : floatFillMessage(dataTypeName, floatDigits);
+    }
+    const complexDigits = COMPLEX_COMPONENT_HEX_DIGITS[dataTypeName];
+    if (complexDigits !== undefined) {
+        const ok = Array.isArray(fill) &&
+            fill.length === 2 &&
+            fill.every((part) => isFloatFill(part, complexDigits));
+        return ok
+            ? undefined
+            : `expected a two-element [real, imaginary] array for data type ${JSON.stringify(dataTypeName)}`;
+    }
+    return undefined; // unrecognized data type: no verdict
+}
+// --- codec pipelines (transpose / sharding) --------------------------------
+function isPermutation(order) {
+    const seen = new Set(order);
+    return seen.size === order.length && order.every((entry) => entry >= 0 && entry < order.length);
+}
+/**
+ * Walk one codec pipeline. `dims` is the array dimensionality at this point
+ * (undefined when unknowable); `outerChunkSizes` holds the distinct chunk
+ * lengths per dimension this pipeline may encode — what a sharding codec's
+ * inner chunks must divide. A regular grid contributes one size per
+ * dimension; a rectilinear grid may contribute several.
+ */
+function pipelineIssues(pipeline, path, dims, outerChunkSizes) {
+    const issues = [];
+    pipeline.forEach((entry, index) => {
+        const parts = fieldParts(entry);
+        if (parts === undefined)
+            return;
+        const { name, configuration } = parts;
+        if (name === "transpose") {
+            const order = configuration?.["order"];
+            if (!isIntArray(order))
+                return; // shape errors are the schema layer's
+            const orderPath = [...path, index, "configuration", "order"];
+            if (!isPermutation(order)) {
+                issues.push({
+                    path: orderPath,
+                    message: `expected a permutation of the integers 0..${order.length - 1}`,
+                    kind: "invalid_value",
+                });
+            }
+            if (dims !== undefined && order.length !== dims) {
+                issues.push({
+                    path: orderPath,
+                    message: `expected one entry per array dimension (${dims})`,
+                    kind: "invalid_value",
+                });
+            }
+        }
+        else if (name === "sharding_indexed") {
+            const chunkShape = configuration?.["chunk_shape"];
+            if (!isIntArray(chunkShape))
+                return;
+            const chunkShapePath = [...path, index, "configuration", "chunk_shape"];
+            if (dims !== undefined && chunkShape.length !== dims) {
+                issues.push({
+                    path: chunkShapePath,
+                    message: `expected one length per array dimension (${dims})`,
+                    kind: "invalid_value",
+                });
+            }
+            else if (outerChunkSizes !== undefined &&
+                chunkShape.length === outerChunkSizes.length &&
+                chunkShape.every((length) => length > 0)) {
+                let violation;
+                outerChunkSizes.forEach((sizes, axis) => {
+                    if (violation !== undefined)
+                        return;
+                    const bad = sizes.find((size) => size % chunkShape[axis] !== 0);
+                    if (bad !== undefined)
+                        violation = { axis, size: bad };
+                });
+                if (violation !== undefined) {
+                    const { axis, size } = violation;
+                    const uniform = outerChunkSizes.every((sizes) => sizes.length === 1);
+                    issues.push({
+                        path: chunkShapePath,
+                        message: uniform
+                            ? `expected ${JSON.stringify(chunkShape)} to evenly divide the outer chunk shape ${JSON.stringify(outerChunkSizes.map((sizes) => sizes[0]))}`
+                            : `expected ${JSON.stringify(chunkShape)} to evenly divide every chunk size of the grid (dimension ${axis} has chunk size ${size})`,
+                        kind: "invalid_value",
+                    });
+                }
+            }
+            const inner = configuration?.["codecs"];
+            if (Array.isArray(inner)) {
+                issues.push(...pipelineIssues(inner, [...path, index, "configuration", "codecs"], dims, chunkShape.map((length) => [length])));
+            }
+            // index_codecs encode the shard index, whose shape differs from the
+            // array's — no dimensional context applies there.
+        }
+    });
+    return issues;
+}
+/**
+ * Every semantic (cross-field) problem in a v3 array metadata document, as
+ * an error tree; an empty tree means no rule found a violation. Values that
+ * are not v3 array documents yield an empty tree; run the structural
+ * validators for structure.
+ */
+export function validateArraySemanticsV3(value) {
+    if (!isPlainObject(value) || value["node_type"] !== "array")
+        return treeOf([]);
+    const issues = [];
+    const shape = isIntArray(value["shape"]) ? value["shape"] : undefined;
+    const dims = shape?.length;
+    const grid = fieldParts(value["chunk_grid"]);
+    let chunkSizes;
+    if (grid?.name === "regular") {
+        const configured = grid.configuration?.["chunk_shape"];
+        if (isIntArray(configured)) {
+            if (dims !== undefined && configured.length !== dims) {
+                issues.push({
+                    path: ["chunk_grid", "configuration", "chunk_shape"],
+                    message: `expected one length per dimension of shape (${dims})`,
+                    kind: "invalid_value",
+                });
+                // wrong arity: unusable as division context
+            }
+            else {
+                chunkSizes = configured.map((length) => [length]);
+            }
+        }
+    }
+    else if (grid?.name === "rectilinear") {
+        const specs = grid.configuration?.["chunk_shapes"];
+        if (Array.isArray(specs)) {
+            if (dims !== undefined && specs.length !== dims) {
+                issues.push({
+                    path: ["chunk_grid", "configuration", "chunk_shapes"],
+                    message: `expected one entry per dimension of shape (${dims})`,
+                    kind: "invalid_value",
+                });
+            }
+            else {
+                const perDim = specs.map((spec, dim) => {
+                    // Bare integer: uniform shorthand, no sum constraint (edge chunks
+                    // are permitted, as with the regular grid).
+                    if (Number.isInteger(spec))
+                        return spec > 0 ? [spec] : undefined;
+                    if (!Array.isArray(spec))
+                        return undefined; // registry schema's problem
+                    const sizes = new Set();
+                    let total = 0;
+                    for (const entry of spec) {
+                        if (Number.isInteger(entry)) {
+                            sizes.add(entry);
+                            total += entry;
+                        }
+                        else if (Array.isArray(entry) &&
+                            entry.length === 2 &&
+                            Number.isInteger(entry[0]) &&
+                            Number.isInteger(entry[1])) {
+                            sizes.add(entry[0]);
+                            total += entry[0] * entry[1];
+                        }
+                        else {
+                            return undefined; // malformed entry: registry schema's problem
+                        }
+                    }
+                    const extent = shape?.[dim];
+                    if (extent !== undefined && total !== extent) {
+                        issues.push({
+                            path: ["chunk_grid", "configuration", "chunk_shapes", dim],
+                            message: `expected chunk sizes summing to ${extent} along dimension ${dim}, got ${total}`,
+                            kind: "invalid_value",
+                        });
+                    }
+                    return [...sizes];
+                });
+                if (perDim.every((sizes) => sizes !== undefined)) {
+                    chunkSizes = perDim;
+                }
+            }
+        }
+    }
+    const dataType = fieldParts(value["data_type"]);
+    if (dataType !== undefined && "fill_value" in value) {
+        const message = fillValueIssue(dataType.name, value["fill_value"]);
+        if (message !== undefined) {
+            issues.push({ path: ["fill_value"], message, kind: "invalid_value" });
+        }
+    }
+    const codecs = value["codecs"];
+    if (Array.isArray(codecs)) {
+        issues.push(...pipelineIssues(codecs, ["codecs"], dims, chunkSizes));
+    }
+    return treeOf(issues);
+}
+//# sourceMappingURL=semantics.js.map

package/dist/semantics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.js","sourceRoot":"","sources":["../src/semantics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zarr-metadata",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Spec-defined metadata types and validators for Zarr v2 and v3.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -21,6 +21,7 @@ export {
   type PathedIssue,
 } from "./errors.js";
 export * from "./schemas.js";
+export * from "./semantics.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";
 export * from "./v2.js";
 export * from "./v3.js";

package/src/semantics.ts

@@ -0,0 +1,325 @@
+/**
+ * Semantic (cross-field) validation for v3 array metadata.
+ *
+ * The structural validators never interpret what an extension point names;
+ * this module deliberately interprets a small set of WELL-KNOWN core
+ * extension points to enforce the cross-field rules the specs state in
+ * prose:
+ *
+ * - the `regular` chunk grid's `chunk_shape` has one length per dimension
+ *   of `shape`;
+ * - the `rectilinear` chunk grid's `chunk_shapes` has one entry per
+ *   dimension, and each explicit chunk list (integers and `[size, count]`
+ *   run-length pairs) sums exactly to that dimension's length (the
+ *   bare-integer uniform shorthand carries no sum constraint, like the
+ *   regular grid);
+ * - a `transpose` codec's `order` is a permutation of `0..n-1`, with one
+ *   entry per array dimension;
+ * - a `sharding_indexed` codec's inner `chunk_shape` matches the array's
+ *   dimensionality and evenly divides every chunk it shards — the grid's
+ *   chunk at the top level (each distinct per-dimension size, for
+ *   rectilinear grids), the parent shard's inner chunk when sharding
+ *   nests;
+ * - `fill_value` has a JSON shape permitted for the named core data type
+ *   (booleans for `bool`, ranged integers for the int types, numbers /
+ *   the "NaN"-family sentinels / width-checked "0x…" strings for the
+ *   float types, two-element arrays for the complex types).
+ *
+ * Unrecognized names are skipped everywhere — the extension name space is
+ * open, and a rule that guessed would lie. This layer has no counterpart
+ * in the Python reference implementation (which stops at structure), so it
+ * is covered by this package's own tests rather than the conformance
+ * corpus.
+ */
+
+import { treeOf, type ErrorTree, type PathedIssue } from "./errors.js";
+
+type Path = ReadonlyArray<string | number>;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+function isIntArray(value: unknown): value is number[] {
+  return (
+    Array.isArray(value) &&
+    Object.keys(value).length === value.length &&
+    value.every((item) => Number.isInteger(item))
+  );
+}
+
+/** The `{name, configuration}` of a metadata field, when extractable. */
+function fieldParts(
+  field: unknown,
+): { name: string; configuration: Record<string, unknown> | undefined } | undefined {
+  if (typeof field === "string") return { name: field, configuration: undefined };
+  if (isPlainObject(field) && typeof field["name"] === "string") {
+    const configuration = field["configuration"];
+    return {
+      name: field["name"],
+      configuration: isPlainObject(configuration) ? configuration : undefined,
+    };
+  }
+  return undefined;
+}
+
+// --- fill_value vs data_type ----------------------------------------------
+
+const INT_RANGES: Record<string, readonly [number, number]> = {
+  int8: [-128, 127],
+  int16: [-32768, 32767],
+  int32: [-2147483648, 2147483647],
+  int64: [-9223372036854775808, 9223372036854775807],
+  uint8: [0, 255],
+  uint16: [0, 65535],
+  uint32: [0, 4294967295],
+  uint64: [0, 18446744073709551615],
+};
+
+const FLOAT_HEX_DIGITS: Record<string, number> = {
+  float16: 4,
+  float32: 8,
+  float64: 16,
+};
+
+/** Hex digit width of each complex type's component floats. */
+const COMPLEX_COMPONENT_HEX_DIGITS: Record<string, number> = {
+  complex64: 8,
+  complex128: 16,
+};
+
+function isFloatFill(value: unknown, hexDigits: number): boolean {
+  if (typeof value === "number") return true;
+  if (typeof value !== "string") return false;
+  if (value === "NaN" || value === "Infinity" || value === "-Infinity") return true;
+  return new RegExp(`^0x[0-9a-fA-F]{${hexDigits}}$`).test(value);
+}
+
+function floatFillMessage(name: string, hexDigits: number): string {
+  return (
+    `expected a number, "NaN", "Infinity", "-Infinity", or a ` +
+    `${hexDigits}-hex-digit "0x..." string for data type ${JSON.stringify(name)}`
+  );
+}
+
+/** The fill_value issue for a KNOWN core data type, if any; undefined otherwise. */
+function fillValueIssue(dataTypeName: string, fill: unknown): string | undefined {
+  if (dataTypeName === "bool") {
+    return typeof fill === "boolean"
+      ? undefined
+      : 'expected a boolean fill value for data type "bool"';
+  }
+  const intRange = INT_RANGES[dataTypeName];
+  if (intRange !== undefined) {
+    const [low, high] = intRange;
+    return Number.isInteger(fill) && (fill as number) >= low && (fill as number) <= high
+      ? undefined
+      : `expected an integer in [${low}, ${high}] for data type ${JSON.stringify(dataTypeName)}`;
+  }
+  const floatDigits = FLOAT_HEX_DIGITS[dataTypeName];
+  if (floatDigits !== undefined) {
+    return isFloatFill(fill, floatDigits)
+      ? undefined
+      : floatFillMessage(dataTypeName, floatDigits);
+  }
+  const complexDigits = COMPLEX_COMPONENT_HEX_DIGITS[dataTypeName];
+  if (complexDigits !== undefined) {
+    const ok =
+      Array.isArray(fill) &&
+      fill.length === 2 &&
+      fill.every((part) => isFloatFill(part, complexDigits));
+    return ok
+      ? undefined
+      : `expected a two-element [real, imaginary] array for data type ${JSON.stringify(dataTypeName)}`;
+  }
+  return undefined; // unrecognized data type: no verdict
+}
+
+// --- codec pipelines (transpose / sharding) --------------------------------
+
+function isPermutation(order: number[]): boolean {
+  const seen = new Set(order);
+  return seen.size === order.length && order.every((entry) => entry >= 0 && entry < order.length);
+}
+
+/**
+ * Walk one codec pipeline. `dims` is the array dimensionality at this point
+ * (undefined when unknowable); `outerChunkSizes` holds the distinct chunk
+ * lengths per dimension this pipeline may encode — what a sharding codec's
+ * inner chunks must divide. A regular grid contributes one size per
+ * dimension; a rectilinear grid may contribute several.
+ */
+function pipelineIssues(
+  pipeline: unknown[],
+  path: Path,
+  dims: number | undefined,
+  outerChunkSizes: number[][] | undefined,
+): PathedIssue[] {
+  const issues: PathedIssue[] = [];
+  pipeline.forEach((entry, index) => {
+    const parts = fieldParts(entry);
+    if (parts === undefined) return;
+    const { name, configuration } = parts;
+    if (name === "transpose") {
+      const order = configuration?.["order"];
+      if (!isIntArray(order)) return; // shape errors are the schema layer's
+      const orderPath = [...path, index, "configuration", "order"];
+      if (!isPermutation(order)) {
+        issues.push({
+          path: orderPath,
+          message: `expected a permutation of the integers 0..${order.length - 1}`,
+          kind: "invalid_value",
+        });
+      }
+      if (dims !== undefined && order.length !== dims) {
+        issues.push({
+          path: orderPath,
+          message: `expected one entry per array dimension (${dims})`,
+          kind: "invalid_value",
+        });
+      }
+    } else if (name === "sharding_indexed") {
+      const chunkShape = configuration?.["chunk_shape"];
+      if (!isIntArray(chunkShape)) return;
+      const chunkShapePath = [...path, index, "configuration", "chunk_shape"];
+      if (dims !== undefined && chunkShape.length !== dims) {
+        issues.push({
+          path: chunkShapePath,
+          message: `expected one length per array dimension (${dims})`,
+          kind: "invalid_value",
+        });
+      } else if (
+        outerChunkSizes !== undefined &&
+        chunkShape.length === outerChunkSizes.length &&
+        chunkShape.every((length) => length > 0)
+      ) {
+        let violation: { axis: number; size: number } | undefined;
+        outerChunkSizes.forEach((sizes, axis) => {
+          if (violation !== undefined) return;
+          const bad = sizes.find((size) => size % (chunkShape[axis] as number) !== 0);
+          if (bad !== undefined) violation = { axis, size: bad };
+        });
+        if (violation !== undefined) {
+          const { axis, size } = violation;
+          const uniform = outerChunkSizes.every((sizes) => sizes.length === 1);
+          issues.push({
+            path: chunkShapePath,
+            message: uniform
+              ? `expected ${JSON.stringify(chunkShape)} to evenly divide the outer chunk shape ${JSON.stringify(outerChunkSizes.map((sizes) => sizes[0]))}`
+              : `expected ${JSON.stringify(chunkShape)} to evenly divide every chunk size of the grid (dimension ${axis} has chunk size ${size})`,
+            kind: "invalid_value",
+          });
+        }
+      }
+      const inner = configuration?.["codecs"];
+      if (Array.isArray(inner)) {
+        issues.push(
+          ...pipelineIssues(
+            inner,
+            [...path, index, "configuration", "codecs"],
+            dims,
+            chunkShape.map((length) => [length]),
+          ),
+        );
+      }
+      // index_codecs encode the shard index, whose shape differs from the
+      // array's — no dimensional context applies there.
+    }
+  });
+  return issues;
+}
+
+/**
+ * Every semantic (cross-field) problem in a v3 array metadata document, as
+ * an error tree; an empty tree means no rule found a violation. Values that
+ * are not v3 array documents yield an empty tree; run the structural
+ * validators for structure.
+ */
+export function validateArraySemanticsV3(value: unknown): ErrorTree {
+  if (!isPlainObject(value) || value["node_type"] !== "array") return treeOf([]);
+  const issues: PathedIssue[] = [];
+  const shape = isIntArray(value["shape"]) ? value["shape"] : undefined;
+  const dims = shape?.length;
+
+  const grid = fieldParts(value["chunk_grid"]);
+  let chunkSizes: number[][] | undefined;
+  if (grid?.name === "regular") {
+    const configured = grid.configuration?.["chunk_shape"];
+    if (isIntArray(configured)) {
+      if (dims !== undefined && configured.length !== dims) {
+        issues.push({
+          path: ["chunk_grid", "configuration", "chunk_shape"],
+          message: `expected one length per dimension of shape (${dims})`,
+          kind: "invalid_value",
+        });
+        // wrong arity: unusable as division context
+      } else {
+        chunkSizes = configured.map((length) => [length]);
+      }
+    }
+  } else if (grid?.name === "rectilinear") {
+    const specs = grid.configuration?.["chunk_shapes"];
+    if (Array.isArray(specs)) {
+      if (dims !== undefined && specs.length !== dims) {
+        issues.push({
+          path: ["chunk_grid", "configuration", "chunk_shapes"],
+          message: `expected one entry per dimension of shape (${dims})`,
+          kind: "invalid_value",
+        });
+      } else {
+        const perDim: (number[] | undefined)[] = specs.map((spec, dim) => {
+          // Bare integer: uniform shorthand, no sum constraint (edge chunks
+          // are permitted, as with the regular grid).
+          if (Number.isInteger(spec)) return spec as number > 0 ? [spec as number] : undefined;
+          if (!Array.isArray(spec)) return undefined; // registry schema's problem
+          const sizes = new Set<number>();
+          let total = 0;
+          for (const entry of spec) {
+            if (Number.isInteger(entry)) {
+              sizes.add(entry as number);
+              total += entry as number;
+            } else if (
+              Array.isArray(entry) &&
+              entry.length === 2 &&
+              Number.isInteger(entry[0]) &&
+              Number.isInteger(entry[1])
+            ) {
+              sizes.add(entry[0] as number);
+              total += (entry[0] as number) * (entry[1] as number);
+            } else {
+              return undefined; // malformed entry: registry schema's problem
+            }
+          }
+          const extent = shape?.[dim];
+          if (extent !== undefined && total !== extent) {
+            issues.push({
+              path: ["chunk_grid", "configuration", "chunk_shapes", dim],
+              message: `expected chunk sizes summing to ${extent} along dimension ${dim}, got ${total}`,
+              kind: "invalid_value",
+            });
+          }
+          return [...sizes];
+        });
+        if (perDim.every((sizes) => sizes !== undefined)) {
+          chunkSizes = perDim as number[][];
+        }
+      }
+    }
+  }
+
+  const dataType = fieldParts(value["data_type"]);
+  if (dataType !== undefined && "fill_value" in value) {
+    const message = fillValueIssue(dataType.name, value["fill_value"]);
+    if (message !== undefined) {
+      issues.push({ path: ["fill_value"], message, kind: "invalid_value" });
+    }
+  }
+
+  const codecs = value["codecs"];
+  if (Array.isArray(codecs)) {
+    issues.push(...pipelineIssues(codecs, ["codecs"], dims, chunkSizes));
+  }
+  return treeOf(issues);
+}