zarr-metadata 0.2.0 → 0.3.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,36 @@
+/**
+ * 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`;
+ * - 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 the shape of the chunk it shards
+ *   (the regular grid's chunk at the top level, 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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAoB,MAAM,aAAa,CAAC;AAqLvE;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAoClE"}

package/dist/semantics.js

@@ -0,0 +1,228 @@
+/**
+ * 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`;
+ * - 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 the shape of the chunk it shards
+ *   (the regular grid's chunk at the top level, 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); `outerChunkShape` is the shape of the chunk
+ * this pipeline encodes — what a sharding codec's inner chunks must divide.
+ */
+function pipelineIssues(pipeline, path, dims, outerChunkShape) {
+    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 (outerChunkShape !== undefined &&
+                chunkShape.length === outerChunkShape.length &&
+                chunkShape.every((length) => length > 0) &&
+                outerChunkShape.some((outer, axis) => outer % chunkShape[axis] !== 0)) {
+                issues.push({
+                    path: chunkShapePath,
+                    message: `expected ${JSON.stringify(chunkShape)} to evenly divide the outer chunk shape ${JSON.stringify(outerChunkShape)}`,
+                    kind: "invalid_value",
+                });
+            }
+            const inner = configuration?.["codecs"];
+            if (Array.isArray(inner)) {
+                issues.push(...pipelineIssues(inner, [...path, index, "configuration", "codecs"], dims, chunkShape));
+            }
+            // 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 chunkShape;
+    if (grid?.name === "regular") {
+        const configured = grid.configuration?.["chunk_shape"];
+        if (isIntArray(configured)) {
+            chunkShape = 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",
+                });
+                chunkShape = undefined; // wrong arity: unusable as division context
+            }
+        }
+    }
+    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, chunkShape));
+    }
+    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.3.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,252 @@
+/**
+ * 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`;
+ * - 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 the shape of the chunk it shards
+ *   (the regular grid's chunk at the top level, 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); `outerChunkShape` is the shape of the chunk
+ * this pipeline encodes — what a sharding codec's inner chunks must divide.
+ */
+function pipelineIssues(
+  pipeline: unknown[],
+  path: Path,
+  dims: number | undefined,
+  outerChunkShape: 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 (
+        outerChunkShape !== undefined &&
+        chunkShape.length === outerChunkShape.length &&
+        chunkShape.every((length) => length > 0) &&
+        outerChunkShape.some((outer, axis) => outer % (chunkShape[axis] as number) !== 0)
+      ) {
+        issues.push({
+          path: chunkShapePath,
+          message: `expected ${JSON.stringify(chunkShape)} to evenly divide the outer chunk shape ${JSON.stringify(outerChunkShape)}`,
+          kind: "invalid_value",
+        });
+      }
+      const inner = configuration?.["codecs"];
+      if (Array.isArray(inner)) {
+        issues.push(
+          ...pipelineIssues(inner, [...path, index, "configuration", "codecs"], dims, chunkShape),
+        );
+      }
+      // 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 chunkShape: number[] | undefined;
+  if (grid?.name === "regular") {
+    const configured = grid.configuration?.["chunk_shape"];
+    if (isIntArray(configured)) {
+      chunkShape = 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",
+        });
+        chunkShape = undefined; // wrong arity: unusable as division context
+      }
+    }
+  }
+
+  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, chunkShape));
+  }
+  return treeOf(issues);
+}