@maroonedog/luq 0.1.2-alpha → 2.1.0

package/dist/path/create-value-writer.mjs

@@ -0,0 +1,77 @@
+import { collectKeySegments, isIndexableObject, readOwnProperty, } from "./create-value-reader.mjs";
+import { isArray } from "../types/index.mjs";
+export function createValueWriter(template) {
+    const keys = collectKeySegments(template);
+    if (keys.length === 0)
+        return (_subject, value) => value;
+    return (subject, value) => writeInto(subject, keys, 0, value);
+}
+function writeInto(container, keys, depth, value) {
+    const key = keys[depth];
+    if (key === undefined)
+        return value;
+    if (container === null || container === undefined) {
+        return vivify(key, writeInto(undefined, keys, depth + 1, value));
+    }
+    if (!isIndexableObject(container))
+        return container;
+    const child = readOwnProperty(container, key);
+    const written = writeInto(child, keys, depth + 1, value);
+    if (written === child)
+        return container;
+    return copyWith(container, key, written);
+}
+/**
+ * Auto-vivification, restricted to the one case the legacy rule got wrong:
+ * only a missing or null intermediate is created. A present primitive is left
+ * exactly as it is (the `if (!isIndexableObject) return container` above), so
+ * writing `a.b` into `{a: 0}` destroys nothing and returns the original root
+ * by identity.
+ *
+ * The container created is always a plain object. A numeric segment does not
+ * conjure an array — the declaration grammar cannot express `items[0]`, so a
+ * numeric key here is a Record key.
+ */
+/**
+ * キーを own プロパティとして置く。**代入演算子を使わない。**
+ *
+ * `copy[key] = value` は key が "__proto__" のとき Object.prototype の
+ * アクセサ (setter) を呼び、own プロパティを作る代わりにプロトタイプを
+ * 差し替えてしまう。defineProperty はアクセサを見ずに own プロパティを
+ * 定義するので、"__proto__" という名前のプロパティを安全に持てる。
+ *
+ * "constructor" と "prototype" は Object.prototype 上でデータプロパティ
+ * なので代入でも own プロパティになるが、キーごとに分岐すると分岐のほうを
+ * 間違えるので一律にこちらを通す。
+ *
+ * これが「宣言パスに __proto__ を書けるようにする」の前提。書き込みが安全に
+ * なったので、パス文法の側で拒否する必要が無くなった (reserved-segment.ts)。
+ */
+function putOwnProperty(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+function vivify(key, written) {
+    const created = {};
+    putOwnProperty(created, key, written);
+    return created;
+}
+function copyWith(container, key, value) {
+    if (isArray(container)) {
+        const index = Number(key);
+        if (!Number.isInteger(index) || index < 0)
+            return container;
+        const copy = container.slice();
+        copy[index] = value;
+        return copy;
+    }
+    // スプレッドは own の列挙可能プロパティを CreateDataProperty で写すので、
+    // ここでは setter は動かない。危ないのは下の代入だけ。
+    const copy = { ...container };
+    putOwnProperty(copy, key, value);
+    return copy;
+}

package/dist/path/element-of.types.d.ts

@@ -0,0 +1 @@
+export type ElementOf<T> = unknown extends T ? unknown : NonNullable<T> extends infer U ? U extends readonly (infer E)[] ? E : never : never;

package/dist/path/element-of.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/element-of.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/field-path.types.d.ts

@@ -0,0 +1,13 @@
+import type { IsOpaqueObject } from "./opaque-object.types";
+import type { PathDepthBudget, PreviousDepth } from "./path-depth.types";
+import type { ElementOf } from "./element-of.types";
+/** The union of legal path literals for T. `[*]` is the only array wildcard and
+ *  array members are never enumerated, which removes `items.name`,
+ *  `items[0].name`, `tags.length` and `items.map` with ONE rule. */
+export type FieldPath<T, D extends number = PathDepthBudget> = RecordPaths<T, D>;
+type RecordPaths<T, D extends number> = NonNullable<T> extends infer U ? U extends readonly unknown[] ? never : IsOpaqueObject<U> extends true ? never : U extends object ? {
+    [K in Extract<keyof U, string>]-?: K | DescendantPaths<K, U[K], D>;
+}[Extract<keyof U, string>] : never : never;
+type DescendantPaths<Prefix extends string, V, D extends number> = D extends 0 ? never : NonNullable<V> extends infer U ? U extends readonly unknown[] ? `${Prefix}[*]` | DescendantPaths<`${Prefix}[*]`, ElementOf<U>, PreviousDepth[D]> : IsOpaqueObject<U> extends true ? never : U extends object ? JoinPath<Prefix, RecordPaths<U, PreviousDepth[D]>> : never : never;
+type JoinPath<Prefix extends string, Sub> = Sub extends string ? `${Prefix}.${Sub}` : never;
+export {};

package/dist/path/field-path.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/field-path.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/format-issue-path.d.ts

@@ -0,0 +1,15 @@
+import type { PathSegment } from "./path-segment.types";
+/**
+ * `[key items, each, key name]` with `[0]` renders `items[0].name`; a nested
+ * template with `[0, 2]` renders `matrix[0][2]`. An empty template renders
+ * `""`, which is the path a root-level failure carries.
+ *
+ * Wildcards consume `indices` left to right, outermost first — the order the
+ * index stack pushes them in.
+ *
+ * Too few indices is a bug in the caller, not a data condition, so it throws
+ * rather than rendering a `[*]` that would then look like a declaration path.
+ * Surplus indices are ignored: the stack may still hold entries belonging to
+ * array nodes above this template.
+ */
+export declare function formatIssuePath(template: readonly PathSegment[], indices: readonly number[]): string;

package/dist/path/format-issue-path.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatIssuePath = formatIssuePath;
+/**
+ * `[key items, each, key name]` with `[0]` renders `items[0].name`; a nested
+ * template with `[0, 2]` renders `matrix[0][2]`. An empty template renders
+ * `""`, which is the path a root-level failure carries.
+ *
+ * Wildcards consume `indices` left to right, outermost first — the order the
+ * index stack pushes them in.
+ *
+ * Too few indices is a bug in the caller, not a data condition, so it throws
+ * rather than rendering a `[*]` that would then look like a declaration path.
+ * Surplus indices are ignored: the stack may still hold entries belonging to
+ * array nodes above this template.
+ */
+function formatIssuePath(template, indices) {
+    let rendered = "";
+    let consumed = 0;
+    for (const segment of template) {
+        if (segment.kind === "key") {
+            rendered += rendered === "" ? segment.key : `.${segment.key}`;
+            continue;
+        }
+        const index = indices[consumed];
+        if (index === undefined) {
+            throw new RangeError(`formatIssuePath needs ${consumed + 1} index/indices for the template ` +
+                `but received ${indices.length}`);
+        }
+        consumed += 1;
+        rendered += `[${index}]`;
+    }
+    return rendered;
+}

package/dist/path/format-issue-path.mjs

@@ -0,0 +1,31 @@
+/**
+ * `[key items, each, key name]` with `[0]` renders `items[0].name`; a nested
+ * template with `[0, 2]` renders `matrix[0][2]`. An empty template renders
+ * `""`, which is the path a root-level failure carries.
+ *
+ * Wildcards consume `indices` left to right, outermost first — the order the
+ * index stack pushes them in.
+ *
+ * Too few indices is a bug in the caller, not a data condition, so it throws
+ * rather than rendering a `[*]` that would then look like a declaration path.
+ * Surplus indices are ignored: the stack may still hold entries belonging to
+ * array nodes above this template.
+ */
+export function formatIssuePath(template, indices) {
+    let rendered = "";
+    let consumed = 0;
+    for (const segment of template) {
+        if (segment.kind === "key") {
+            rendered += rendered === "" ? segment.key : `.${segment.key}`;
+            continue;
+        }
+        const index = indices[consumed];
+        if (index === undefined) {
+            throw new RangeError(`formatIssuePath needs ${consumed + 1} index/indices for the template ` +
+                `but received ${indices.length}`);
+        }
+        consumed += 1;
+        rendered += `[${index}]`;
+    }
+    return rendered;
+}

package/dist/path/index.d.ts

@@ -0,0 +1,18 @@
+export type { EachSegment, IsWellFormedPath, KeySegment, ParsePath, PathSegment, Segment, } from "./path-segment.types";
+export type { PathDepthBudget, PreviousDepth } from "./path-depth.types";
+export type { IsOpaqueObject, OpaqueObject } from "./opaque-object.types";
+export type { ElementOf } from "./element-of.types";
+export type { PropertyValueOf } from "./property-value-of.types";
+export type { FieldPath } from "./field-path.types";
+export type { LeafPath, MissingLeafPaths } from "./leaf-path.types";
+export type { PickPaths, ValueAtPath } from "./value-at-path.types";
+export { PathSyntaxError, RESERVED_SEGMENTS, assertDeclarableKey, isReservedSegment, } from "./reserved-segment";
+export { formatFieldPath, leafKeyOf, parentFieldPath, parseFieldPath, } from "./parse-field-path";
+export type { ValueReader } from "./create-value-reader";
+export { collectKeySegments, createValueReader, isIndexableObject, readOwnProperty, } from "./create-value-reader";
+export type { ArrayReader } from "./create-array-reader";
+export { createArrayReader } from "./create-array-reader";
+export type { ValueWriter } from "./create-value-writer";
+export { createValueWriter } from "./create-value-writer";
+export { formatIssuePath } from "./format-issue-path";
+export { matchPathPattern } from "./match-path-pattern";

package/dist/path/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPathPattern = exports.formatIssuePath = exports.createValueWriter = exports.createArrayReader = exports.readOwnProperty = exports.isIndexableObject = exports.createValueReader = exports.collectKeySegments = exports.parseFieldPath = exports.parentFieldPath = exports.leafKeyOf = exports.formatFieldPath = exports.isReservedSegment = exports.assertDeclarableKey = exports.RESERVED_SEGMENTS = exports.PathSyntaxError = void 0;
+var reserved_segment_1 = require("./reserved-segment");
+Object.defineProperty(exports, "PathSyntaxError", { enumerable: true, get: function () { return reserved_segment_1.PathSyntaxError; } });
+Object.defineProperty(exports, "RESERVED_SEGMENTS", { enumerable: true, get: function () { return reserved_segment_1.RESERVED_SEGMENTS; } });
+Object.defineProperty(exports, "assertDeclarableKey", { enumerable: true, get: function () { return reserved_segment_1.assertDeclarableKey; } });
+Object.defineProperty(exports, "isReservedSegment", { enumerable: true, get: function () { return reserved_segment_1.isReservedSegment; } });
+var parse_field_path_1 = require("./parse-field-path");
+Object.defineProperty(exports, "formatFieldPath", { enumerable: true, get: function () { return parse_field_path_1.formatFieldPath; } });
+Object.defineProperty(exports, "leafKeyOf", { enumerable: true, get: function () { return parse_field_path_1.leafKeyOf; } });
+Object.defineProperty(exports, "parentFieldPath", { enumerable: true, get: function () { return parse_field_path_1.parentFieldPath; } });
+Object.defineProperty(exports, "parseFieldPath", { enumerable: true, get: function () { return parse_field_path_1.parseFieldPath; } });
+var create_value_reader_1 = require("./create-value-reader");
+Object.defineProperty(exports, "collectKeySegments", { enumerable: true, get: function () { return create_value_reader_1.collectKeySegments; } });
+Object.defineProperty(exports, "createValueReader", { enumerable: true, get: function () { return create_value_reader_1.createValueReader; } });
+Object.defineProperty(exports, "isIndexableObject", { enumerable: true, get: function () { return create_value_reader_1.isIndexableObject; } });
+Object.defineProperty(exports, "readOwnProperty", { enumerable: true, get: function () { return create_value_reader_1.readOwnProperty; } });
+var create_array_reader_1 = require("./create-array-reader");
+Object.defineProperty(exports, "createArrayReader", { enumerable: true, get: function () { return create_array_reader_1.createArrayReader; } });
+var create_value_writer_1 = require("./create-value-writer");
+Object.defineProperty(exports, "createValueWriter", { enumerable: true, get: function () { return create_value_writer_1.createValueWriter; } });
+var format_issue_path_1 = require("./format-issue-path");
+Object.defineProperty(exports, "formatIssuePath", { enumerable: true, get: function () { return format_issue_path_1.formatIssuePath; } });
+var match_path_pattern_1 = require("./match-path-pattern");
+Object.defineProperty(exports, "matchPathPattern", { enumerable: true, get: function () { return match_path_pattern_1.matchPathPattern; } });

package/dist/path/index.mjs

@@ -0,0 +1,7 @@
+export { PathSyntaxError, RESERVED_SEGMENTS, assertDeclarableKey, isReservedSegment, } from "./reserved-segment.mjs";
+export { formatFieldPath, leafKeyOf, parentFieldPath, parseFieldPath, } from "./parse-field-path.mjs";
+export { collectKeySegments, createValueReader, isIndexableObject, readOwnProperty, } from "./create-value-reader.mjs";
+export { createArrayReader } from "./create-array-reader.mjs";
+export { createValueWriter } from "./create-value-writer.mjs";
+export { formatIssuePath } from "./format-issue-path.mjs";
+export { matchPathPattern } from "./match-path-pattern.mjs";

package/dist/path/leaf-path.types.d.ts

@@ -0,0 +1,16 @@
+import type { IsOpaqueObject } from "./opaque-object.types";
+import type { PathDepthBudget, PreviousDepth } from "./path-depth.types";
+import type { ElementOf } from "./element-of.types";
+/** The subset of FieldPath<T> that terminates at a value: the paths `.strict()`
+ *  demands a declaration for. */
+export type LeafPath<T, D extends number = PathDepthBudget> = RecordLeafPaths<T, D>;
+export type MissingLeafPaths<T, TDeclared extends string> = Exclude<LeafPath<T>, TDeclared>;
+/** False for `{}` and for anything with a string index signature. */
+type IsEnumerableRecord<U> = [Extract<keyof U, string>] extends [never] ? false : string extends Extract<keyof U, string> ? false : true;
+type RecordLeafPaths<T, D extends number> = NonNullable<T> extends infer U ? U extends readonly unknown[] ? never : IsOpaqueObject<U> extends true ? never : U extends object ? IsEnumerableRecord<U> extends true ? {
+    [K in Extract<keyof U, string>]-?: LeafPathsBelow<K, U[K], D>;
+}[Extract<keyof U, string>] : never : never : never;
+type LeafPathsBelow<Prefix extends string, V, D extends number> = D extends 0 ? Prefix : NonNullable<V> extends infer U ? U extends readonly unknown[] ? LeafPathsBelow<`${Prefix}[*]`, ElementOf<U>, PreviousDepth[D]> : IsOpaqueObject<U> extends true ? Prefix : U extends object ? IsEnumerableRecord<U> extends true ? {
+    [K in Extract<keyof U, string>]-?: LeafPathsBelow<`${Prefix}.${K}`, U[K], PreviousDepth[D]>;
+}[Extract<keyof U, string>] : never : Prefix : never;
+export {};

package/dist/path/leaf-path.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/leaf-path.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/match-path-pattern.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `pattern` is a declaration path and is PARSED, so a malformed pattern throws
+ * PathSyntaxError rather than quietly matching nothing.
+ *
+ * `concretePath` is untrusted text (it may come straight from a caller
+ * filtering issues) and is only scanned: a `[*]` in it fails the digit rule
+ * and returns false, which keeps the two grammars from meeting in the middle.
+ */
+export declare function matchPathPattern(pattern: string, concretePath: string): boolean;

package/dist/path/match-path-pattern.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPathPattern = matchPathPattern;
+// ===========================================================================
+// L1  src/path/match-path-pattern.ts
+// The round trip between the two grammars: does the issue path `items[0].name`
+// belong to the declaration `items[*].name`?
+//
+// The legacy version built a RegExp by string replacement on every call. This
+// scans the concrete path against the already-parsed template instead, so a
+// key containing a regex metacharacter cannot change the meaning of the match
+// and no pattern is ever compiled from user text.
+// ===========================================================================
+const parse_field_path_1 = require("./parse-field-path");
+/**
+ * `pattern` is a declaration path and is PARSED, so a malformed pattern throws
+ * PathSyntaxError rather than quietly matching nothing.
+ *
+ * `concretePath` is untrusted text (it may come straight from a caller
+ * filtering issues) and is only scanned: a `[*]` in it fails the digit rule
+ * and returns false, which keeps the two grammars from meeting in the middle.
+ */
+function matchPathPattern(pattern, concretePath) {
+    const template = (0, parse_field_path_1.parseFieldPath)(pattern);
+    let cursor = 0;
+    for (let i = 0; i < template.length; i += 1) {
+        const segment = template[i];
+        if (segment === undefined)
+            return false;
+        if (segment.kind === "key") {
+            if (i > 0) {
+                if (concretePath[cursor] !== ".")
+                    return false;
+                cursor += 1;
+            }
+            if (!concretePath.startsWith(segment.key, cursor))
+                return false;
+            cursor += segment.key.length;
+            continue;
+        }
+        const afterIndex = scanIndex(concretePath, cursor);
+        if (afterIndex === null)
+            return false;
+        cursor = afterIndex;
+    }
+    return cursor === concretePath.length;
+}
+/** Consumes `[<digits>]` at `from`, returning the position after it. */
+function scanIndex(concretePath, from) {
+    if (concretePath[from] !== "[")
+        return null;
+    let cursor = from + 1;
+    let digits = 0;
+    while (isDigit(concretePath[cursor])) {
+        cursor += 1;
+        digits += 1;
+    }
+    if (digits === 0)
+        return null;
+    if (concretePath[cursor] !== "]")
+        return null;
+    return cursor + 1;
+}
+function isDigit(character) {
+    return character !== undefined && character >= "0" && character <= "9";
+}

package/dist/path/match-path-pattern.mjs

@@ -0,0 +1,63 @@
+// ===========================================================================
+// L1  src/path/match-path-pattern.ts
+// The round trip between the two grammars: does the issue path `items[0].name`
+// belong to the declaration `items[*].name`?
+//
+// The legacy version built a RegExp by string replacement on every call. This
+// scans the concrete path against the already-parsed template instead, so a
+// key containing a regex metacharacter cannot change the meaning of the match
+// and no pattern is ever compiled from user text.
+// ===========================================================================
+import { parseFieldPath } from "./parse-field-path.mjs";
+/**
+ * `pattern` is a declaration path and is PARSED, so a malformed pattern throws
+ * PathSyntaxError rather than quietly matching nothing.
+ *
+ * `concretePath` is untrusted text (it may come straight from a caller
+ * filtering issues) and is only scanned: a `[*]` in it fails the digit rule
+ * and returns false, which keeps the two grammars from meeting in the middle.
+ */
+export function matchPathPattern(pattern, concretePath) {
+    const template = parseFieldPath(pattern);
+    let cursor = 0;
+    for (let i = 0; i < template.length; i += 1) {
+        const segment = template[i];
+        if (segment === undefined)
+            return false;
+        if (segment.kind === "key") {
+            if (i > 0) {
+                if (concretePath[cursor] !== ".")
+                    return false;
+                cursor += 1;
+            }
+            if (!concretePath.startsWith(segment.key, cursor))
+                return false;
+            cursor += segment.key.length;
+            continue;
+        }
+        const afterIndex = scanIndex(concretePath, cursor);
+        if (afterIndex === null)
+            return false;
+        cursor = afterIndex;
+    }
+    return cursor === concretePath.length;
+}
+/** Consumes `[<digits>]` at `from`, returning the position after it. */
+function scanIndex(concretePath, from) {
+    if (concretePath[from] !== "[")
+        return null;
+    let cursor = from + 1;
+    let digits = 0;
+    while (isDigit(concretePath[cursor])) {
+        cursor += 1;
+        digits += 1;
+    }
+    if (digits === 0)
+        return null;
+    if (concretePath[cursor] !== "]")
+        return null;
+    return cursor + 1;
+}
+function isDigit(character) {
+    return character !== undefined && character >= "0" && character <= "9";
+}

package/dist/path/opaque-object.types.d.ts

@@ -0,0 +1,5 @@
+/** Built-in and callable object types whose members are implementation, not
+ *  data. FieldPath (generator) and ValueAtPath (resolver) both read this, so
+ *  the two directions cannot disagree about where a path stops. */
+export type OpaqueObject = Date | RegExp | Error | Promise<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object> | ArrayBuffer | SharedArrayBuffer | ArrayBufferView | ((...args: never[]) => unknown) | (abstract new (...args: never[]) => unknown);
+export type IsOpaqueObject<T> = [T] extends [never] ? false : [NonNullable<T>] extends [OpaqueObject] ? true : false;

package/dist/path/opaque-object.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/opaque-object.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/parse-field-path.d.ts

@@ -0,0 +1,25 @@
+import type { PathSegment } from "./path-segment.types";
+/**
+ * Grammar: `head ("." head)*` where `head` is `key ("[*]")*`.
+ *
+ * `[*]` is the DECLARATION wildcard and the only bracket form; `[0]` belongs
+ * to the issue grammar (see formatIssuePath) and is rejected here, so a
+ * wildcard path can never be emitted as an issue path or vice versa.
+ */
+export declare function parseFieldPath(path: string): readonly PathSegment[];
+/** The inverse of parseFieldPath. Exported so the round trip is testable and
+ *  so parentFieldPath never rebuilds a path by string surgery. */
+export declare function formatFieldPath(segments: readonly PathSegment[]): string;
+/**
+ * The declared path one level up, or null at the top. Step 9 groups declared
+ * child keys by this, so it must drop exactly one segment: the parent of
+ * `items[*]` is `items`, and the parent of `matrix[*][*]` is `matrix[*]`.
+ */
+export declare function parentFieldPath(path: string): string | null;
+/**
+ * The final key of a path, or null when the path ends in a wildcard — an
+ * element has an index, not a key. Returning null rather than `""` is what
+ * lets step 9 tell "a declared child key of this object" from "the elements of
+ * this array" without re-inspecting the string.
+ */
+export declare function leafKeyOf(path: string): string | null;

package/dist/path/parse-field-path.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFieldPath = parseFieldPath;
+exports.formatFieldPath = formatFieldPath;
+exports.parentFieldPath = parentFieldPath;
+exports.leafKeyOf = leafKeyOf;
+const reserved_segment_1 = require("./reserved-segment");
+const EACH_SUFFIX = "[*]";
+const EACH_SEGMENT = Object.freeze({ kind: "each" });
+/**
+ * Grammar: `head ("." head)*` where `head` is `key ("[*]")*`.
+ *
+ * `[*]` is the DECLARATION wildcard and the only bracket form; `[0]` belongs
+ * to the issue grammar (see formatIssuePath) and is rejected here, so a
+ * wildcard path can never be emitted as an issue path or vice versa.
+ */
+function parseFieldPath(path) {
+    if (path === "") {
+        throw new reserved_segment_1.PathSyntaxError(path, "a field path must not be empty");
+    }
+    const segments = [];
+    for (const head of path.split(".")) {
+        appendHead(head, path, segments);
+    }
+    return Object.freeze(segments);
+}
+function appendHead(head, path, into) {
+    let key = head;
+    let eachCount = 0;
+    while (key.endsWith(EACH_SUFFIX)) {
+        key = key.slice(0, -EACH_SUFFIX.length);
+        eachCount += 1;
+    }
+    (0, reserved_segment_1.assertDeclarableKey)(key, path);
+    into.push(Object.freeze({ kind: "key", key }));
+    for (let i = 0; i < eachCount; i += 1)
+        into.push(EACH_SEGMENT);
+}
+/** The inverse of parseFieldPath. Exported so the round trip is testable and
+ *  so parentFieldPath never rebuilds a path by string surgery. */
+function formatFieldPath(segments) {
+    let rendered = "";
+    segments.forEach((segment, index) => {
+        if (segment.kind === "each") {
+            rendered += EACH_SUFFIX;
+            return;
+        }
+        rendered += index === 0 ? segment.key : `.${segment.key}`;
+    });
+    return rendered;
+}
+/**
+ * The declared path one level up, or null at the top. Step 9 groups declared
+ * child keys by this, so it must drop exactly one segment: the parent of
+ * `items[*]` is `items`, and the parent of `matrix[*][*]` is `matrix[*]`.
+ */
+function parentFieldPath(path) {
+    const segments = parseFieldPath(path);
+    if (segments.length <= 1)
+        return null;
+    return formatFieldPath(segments.slice(0, -1));
+}
+/**
+ * The final key of a path, or null when the path ends in a wildcard — an
+ * element has an index, not a key. Returning null rather than `""` is what
+ * lets step 9 tell "a declared child key of this object" from "the elements of
+ * this array" without re-inspecting the string.
+ */
+function leafKeyOf(path) {
+    const segments = parseFieldPath(path);
+    const last = segments[segments.length - 1];
+    if (last === undefined || last.kind === "each")
+        return null;
+    return last.key;
+}

package/dist/path/parse-field-path.mjs

@@ -0,0 +1,69 @@
+import { PathSyntaxError, assertDeclarableKey } from "./reserved-segment.mjs";
+const EACH_SUFFIX = "[*]";
+const EACH_SEGMENT = Object.freeze({ kind: "each" });
+/**
+ * Grammar: `head ("." head)*` where `head` is `key ("[*]")*`.
+ *
+ * `[*]` is the DECLARATION wildcard and the only bracket form; `[0]` belongs
+ * to the issue grammar (see formatIssuePath) and is rejected here, so a
+ * wildcard path can never be emitted as an issue path or vice versa.
+ */
+export function parseFieldPath(path) {
+    if (path === "") {
+        throw new PathSyntaxError(path, "a field path must not be empty");
+    }
+    const segments = [];
+    for (const head of path.split(".")) {
+        appendHead(head, path, segments);
+    }
+    return Object.freeze(segments);
+}
+function appendHead(head, path, into) {
+    let key = head;
+    let eachCount = 0;
+    while (key.endsWith(EACH_SUFFIX)) {
+        key = key.slice(0, -EACH_SUFFIX.length);
+        eachCount += 1;
+    }
+    assertDeclarableKey(key, path);
+    into.push(Object.freeze({ kind: "key", key }));
+    for (let i = 0; i < eachCount; i += 1)
+        into.push(EACH_SEGMENT);
+}
+/** The inverse of parseFieldPath. Exported so the round trip is testable and
+ *  so parentFieldPath never rebuilds a path by string surgery. */
+export function formatFieldPath(segments) {
+    let rendered = "";
+    segments.forEach((segment, index) => {
+        if (segment.kind === "each") {
+            rendered += EACH_SUFFIX;
+            return;
+        }
+        rendered += index === 0 ? segment.key : `.${segment.key}`;
+    });
+    return rendered;
+}
+/**
+ * The declared path one level up, or null at the top. Step 9 groups declared
+ * child keys by this, so it must drop exactly one segment: the parent of
+ * `items[*]` is `items`, and the parent of `matrix[*][*]` is `matrix[*]`.
+ */
+export function parentFieldPath(path) {
+    const segments = parseFieldPath(path);
+    if (segments.length <= 1)
+        return null;
+    return formatFieldPath(segments.slice(0, -1));
+}
+/**
+ * The final key of a path, or null when the path ends in a wildcard — an
+ * element has an index, not a key. Returning null rather than `""` is what
+ * lets step 9 tell "a declared child key of this object" from "the elements of
+ * this array" without re-inspecting the string.
+ */
+export function leafKeyOf(path) {
+    const segments = parseFieldPath(path);
+    const last = segments[segments.length - 1];
+    if (last === undefined || last.kind === "each")
+        return null;
+    return last.key;
+}

package/dist/path/path-depth.types.d.ts

@@ -0,0 +1,4 @@
+/** The ONE recursion budget every path type counts down, so a self-referential
+ *  model yields a finite path union instead of TS2589. */
+export type PathDepthBudget = 6;
+export type PreviousDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8];

package/dist/path/path-depth.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/path-depth.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/path-segment.types.d.ts

@@ -0,0 +1,27 @@
+export interface KeySegment {
+    readonly key: string;
+}
+export interface EachSegment {
+    readonly each: true;
+}
+export type Segment = KeySegment | EachSegment;
+/** Splits one dot-free head such as `items[*][*]` into its segments. */
+type ParseHead<H extends string> = H extends `${infer K}[*]` ? [...ParseHead<K>, EachSegment] : [{
+    readonly key: H;
+}];
+export type ParsePath<P extends string> = P extends `${infer H}.${infer R}` ? [...ParseHead<H>, ...ParsePath<R>] : ParseHead<P>;
+type HasEmptyKey<S extends readonly Segment[]> = S extends readonly [
+    infer H,
+    ...infer R extends readonly Segment[]
+] ? H extends {
+    readonly key: "";
+} ? true : HasEmptyKey<R> : false;
+export type IsWellFormedPath<P extends string> = ParsePath<P> extends readonly [Segment, ...Segment[]] ? HasEmptyKey<ParsePath<P>> extends true ? false : true : false;
+/** The runtime segment shape parseFieldPath produces (same vocabulary). */
+export type PathSegment = {
+    readonly kind: "key";
+    readonly key: string;
+} | {
+    readonly kind: "each";
+};
+export {};

package/dist/path/path-segment.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });