@needle-tools/addressing 0.3.2 → 0.3.3

package/src/resolve.ts

@@ -1,172 +1,315 @@
-import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType, type GraphNode, type NeedleAddress } from "./address.js";
-import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS, type GltfJson } from "./gltf.js";
-
-export type GltfResolveResult = {
-    type: string;
-    index: number;
-    element: Record<string, unknown>;
-};
-
-/**
- * Resolve an address inside glTF JSON. Tries id → anchor → namePath (nodes), in that
- * order; returns null when nothing matches exactly (reconciliation is a separate,
- * explicit step — resolution never guesses).
- */
-export function resolveInGltf(address: NeedleAddress, json: GltfJson): GltfResolveResult | null {
-    const searched: Array<readonly [string, string]> = address.type
-        ? [[address.type, collectionKeyForType(address.type)]]
-        : [...STAMPED_COLLECTIONS];
-
-    if (address.id) {
-        for (const [type, key] of searched) {
-            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
-            if (found) return { type, index: found.index, element: found.element };
-        }
-    }
-    if (address.anchor) {
-        for (const [type, key] of searched) {
-            const found = findInCollection(json, key, el => parseAnchorValue(el.name as string | undefined) === address.anchor);
-            if (found) return { type, index: found.index, element: found.element };
-        }
-    }
-    if (address.namePath?.length && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, address.namePath);
-        if (index !== null) {
-            const nodes = json["nodes"] as Array<Record<string, unknown>>;
-            return { type: "node", index, element: nodes[index] };
-        }
-    }
-    return null;
-}
-
-/**
- * Resolve an address inside a live scene graph (duck-typed — any three.js).
- * Same order as glTF resolution: id → anchor → namePath.
- */
-export function resolveInGraph(address: NeedleAddress, root: GraphNode): GraphNode | null {
-    if (address.id) {
-        const byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
-        if (byId) return byId;
-    }
-    if (address.anchor) {
-        const byAnchor = findInGraph(root, n => parseAnchorValue(n.name) === address.anchor);
-        if (byAnchor) return byAnchor;
-    }
-    if (address.namePath?.length) {
-        let current: GraphNode | null = root;
-        for (const segment of address.namePath) {
-            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
-            if (!current) break;
-        }
-        if (current && current !== root) return current;
-    }
-    return null;
-}
-
-export type ReconcileCandidate = {
-    object: GraphNode;
-    /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */
-    confidence: number;
-    reasons: string[];
-};
-
-/**
- * When exact resolution fails (the asset changed), propose candidates instead of
- * guessing: nodes matching the address's name, ranked by how much of the recorded
- * namePath still matches. Callers decide thresholds and whether to re-anchor.
- */
-export function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[] {
-    if (!address.name && !address.namePath?.length) return [];
-    const targetName = address.name ?? address.namePath![address.namePath!.length - 1];
-
-    const candidates: ReconcileCandidate[] = [];
-    collectDescendants(root, (node, namePath) => {
-        if ((node.name ?? "") !== targetName) return;
-        const reasons = [`name matches "${targetName}"`];
-        let confidence = 0.5;
-        if (address.namePath?.length) {
-            const similarity = pathSuffixSimilarity(address.namePath, namePath);
-            confidence += 0.4 * similarity;
-            if (similarity > 0) reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
-        }
-        candidates.push({ object: node, confidence, reasons });
-    });
-    if (candidates.length === 1) {
-        candidates[0].confidence = Math.min(0.95, candidates[0].confidence + 0.1);
-        candidates[0].reasons.push("only candidate with this name");
-    }
-    return candidates.sort((a, b) => b.confidence - a.confidence);
-}
-
-function findInCollection(json: GltfJson, key: string, predicate: (el: Record<string, any>) => boolean): { index: number; element: Record<string, unknown> } | null {
-    const collection = json[key];
-    if (!Array.isArray(collection)) return null;
-    for (let i = 0; i < collection.length; i++) {
-        const element = collection[i];
-        if (element != null && typeof element === "object" && predicate(element)) {
-            return { index: i, element };
-        }
-    }
-    return null;
-}
-
-function walkGltfNamePath(json: GltfJson, namePath: string[]): number | null {
-    const nodes = json["nodes"];
-    const scenes = json["scenes"];
-    if (!Array.isArray(nodes) || !Array.isArray(scenes)) return null;
-    // roots: the union of all scenes' root nodes
-    let candidates: number[] = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
-    let match: number | null = null;
-    for (const segment of namePath) {
-        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
-        if (match === null) return null;
-        const children = nodes[match]?.children;
-        candidates = Array.isArray(children) ? children : [];
-    }
-    return match;
-}
-
-function findInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, visited = new Set<GraphNode>()): GraphNode | null {
-    if (visited.has(root)) return null;
-    visited.add(root);
-    if (predicate(root)) return root;
-    if (!root.children) return null;
-    for (let i = 0; i < root.children.length; i++) {
-        const child = root.children[i];
-        if (child == null) continue;
-        const found = findInGraph(child, predicate, visited);
-        if (found) return found;
-    }
-    return null;
-}
-
-/** visit every descendant of root with its root-exclusive name path (including own name) */
-function collectDescendants(root: GraphNode, visit: (node: GraphNode, namePath: string[]) => void): void {
-    const visited = new Set<GraphNode>();
-    const walk = (node: GraphNode, namePath: string[]) => {
-        if (visited.has(node)) return;
-        visited.add(node);
-        if (node !== root) visit(node, namePath);
-        if (!node.children) return;
-        for (let i = 0; i < node.children.length; i++) {
-            const child = node.children[i];
-            if (child == null) continue;
-            walk(child, [...namePath, child.name ?? ""]);
-        }
-    };
-    walk(root, []);
-}
-
-/** how much of the expected path's tail matches the actual path's tail (0..1) */
-function pathSuffixSimilarity(expected: string[], actual: string[]): number {
-    let shared = 0;
-    while (
-        shared < expected.length &&
-        shared < actual.length &&
-        expected[expected.length - 1 - shared] === actual[actual.length - 1 - shared]
-    ) {
-        shared++;
-    }
-    return shared / Math.max(expected.length, actual.length);
-}
+import { parseAnchorValue } from "./anchor.js";
+import { collectionKeyForType, type GraphNode, type NeedleAddress } from "./address.js";
+import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS, type GltfJson } from "./gltf.js";
+
+export type GltfResolveResult = {
+    type: string;
+    index: number;
+    element: Record<string, unknown>;
+};
+
+/**
+ * Resolve an address inside glTF JSON. Same ladder as the live graph —
+ * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * exactly one element. Returns null when nothing matches exactly (reconciliation is a
+ * separate, explicit step — resolution never guesses).
+ */
+export function resolveInGltf(address: NeedleAddress, json: GltfJson, options?: ResolveOptions): GltfResolveResult | null {
+    const report = options?.report;
+    const searched: Array<readonly [string, string]> = address.type
+        ? [[address.type, collectionKeyForType(address.type)]]
+        : [...STAMPED_COLLECTIONS];
+
+    let byAnchor: GltfResolveResult | null = null;
+    if (address.anchor) {
+        const matches: GltfResolveResult[] = [];
+        for (const [type, key] of searched) {
+            for (const found of collectInJsonCollection(json, key, el => parseAnchorValue(el.name as string | undefined) === address.anchor)) {
+                matches.push({ type, index: found.index, element: found.element });
+                if (matches.length > 1 && !report) break;
+            }
+            if (matches.length > 1 && !report) break;
+        }
+        if (matches.length === 1) byAnchor = matches[0];
+        else if (matches.length > 1) report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    if (byAnchor && !report) return byAnchor;
+
+    let byId: GltfResolveResult | null = null;
+    if (address.id) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
+            if (found) { byId = { type, index: found.index, element: found.element }; break; }
+        }
+    }
+
+    if (byAnchor) {
+        if (byId && (byId.type !== byAnchor.type || byId.index !== byAnchor.index)) {
+            report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        }
+        return byAnchor;
+    }
+    if (byId) return byId;
+
+    if (address.namePath?.length && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, address.namePath);
+        if (index !== null) {
+            const nodes = json["nodes"] as Array<Record<string, unknown>>;
+            return { type: "node", index, element: nodes[index] };
+        }
+    }
+    return null;
+}
+
+/** which rung of the ladder produced (or could have produced) a match */
+export type ResolutionRung = "id" | "anchor" | "namePath" | "name";
+
+/**
+ * Something a caller may want to show a human. Never an error — resolution still returns
+ * its best answer; these say the answer was not the only defensible one.
+ */
+export type ResolutionIssue =
+    /** an anchor matched several elements, so it could not outrank an exact key */
+    | { kind: "ambiguous-anchor"; anchor: string; count: number }
+    /** a name matched several elements in a flat collection */
+    | { kind: "ambiguous-name"; name: string; count: number }
+    /** two rungs resolved to DIFFERENT elements — the content changed underneath */
+    | { kind: "conflict"; preferred: ResolutionRung; other: ResolutionRung };
+
+export type ResolveOptions = {
+    /**
+     * Collect ambiguity/conflict evidence. OPT-IN because it costs extra traversals:
+     * detecting that two rungs disagree means evaluating both instead of stopping at the
+     * first hit, and resolution already walks from the root per address. The runtime
+     * short-circuits and pays nothing; the editor asks for evidence so it can surface
+     * drift to the user.
+     */
+    report?: (issue: ResolutionIssue) => void;
+};
+
+/**
+ * Resolve an address inside a live scene graph (duck-typed — any three.js).
+ *
+ * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * human-authored declaration, while an id may be a derived value whose basis shifted when
+ * the content changed. It only wins when it resolves UNIQUELY: anchors are labels and may
+ * legally repeat, and an ambiguous label must never outrank an exact key.
+ */
+export function resolveInGraph(address: NeedleAddress, root: GraphNode, options?: ResolveOptions): GraphNode | null {
+    const report = options?.report;
+
+    let byAnchor: GraphNode | null = null;
+    if (address.anchor) {
+        // without a reporter, stop at two — "exactly one" vs "more than one" is all the
+        // ladder needs, and the count only matters for the message
+        const matches = collectInGraph(root, n => parseAnchorValue(n.name) === address.anchor, report ? Infinity : 2);
+        if (matches.length === 1) byAnchor = matches[0];
+        else if (matches.length > 1) report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    // fast path: nothing left to learn unless the caller wants the disagreement reported
+    if (byAnchor && !report) return byAnchor;
+
+    let byId: GraphNode | null = null;
+    if (address.id) byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
+
+    if (byAnchor) {
+        if (byId && byId !== byAnchor) report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        return byAnchor;
+    }
+    if (byId) return byId;
+
+    if (address.namePath?.length) {
+        let current: GraphNode | null = root;
+        for (const segment of address.namePath) {
+            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
+            if (!current) break;
+        }
+        if (current && current !== root) return current;
+    }
+    return null;
+}
+
+/** duck-typed view of an element that is not a graph node (a material, texture, …) */
+export type AddressableElement = {
+    name?: string;
+    userData?: Record<string, unknown>;
+};
+
+/**
+ * Resolve an address against a FLAT collection of live elements — materials, textures and
+ * anything else that carries a name and `userData` but is not part of the scene graph.
+ *
+ * Same ladder as the graph, minus `namePath` (there is no hierarchy to walk) plus `name`
+ * as the final rung, since a flat collection has no positional fallback. This exists so
+ * every element type resolves through ONE implementation: materials previously had their
+ * own ladders, could not be anchored at all, and disagreed with each other about whether a
+ * name match had to be unique.
+ */
+export function resolveInCollection<T extends AddressableElement>(address: NeedleAddress, elements: readonly T[], options?: ResolveOptions): T | null {
+    const report = options?.report;
+
+    let byAnchor: T | null = null;
+    if (address.anchor) {
+        const matches = elements.filter(e => parseAnchorValue(e.name) === address.anchor);
+        if (matches.length === 1) byAnchor = matches[0];
+        else if (matches.length > 1) report?.({ kind: "ambiguous-anchor", anchor: address.anchor, count: matches.length });
+    }
+    if (byAnchor && !report) return byAnchor;
+
+    const byId = address.id ? elements.find(e => e.userData?.[NEEDLE_ID_KEY] === address.id) ?? null : null;
+
+    if (byAnchor) {
+        if (byId && byId !== byAnchor) report?.({ kind: "conflict", preferred: "anchor", other: "id" });
+        return byAnchor;
+    }
+    if (byId) return byId;
+
+    if (address.name) {
+        const named = elements.filter(e => e.name === address.name);
+        if (named.length === 1) return named[0];
+        if (named.length > 1) report?.({ kind: "ambiguous-name", name: address.name, count: named.length });
+    }
+    return null;
+}
+
+export type ReconcileCandidate = {
+    object: GraphNode;
+    /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */
+    confidence: number;
+    reasons: string[];
+};
+
+/**
+ * When exact resolution fails (the asset changed), propose candidates instead of
+ * guessing: nodes matching the address's name, ranked by how much of the recorded
+ * namePath still matches. Callers decide thresholds and whether to re-anchor.
+ */
+export function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[] {
+    if (!address.name && !address.namePath?.length) return [];
+    const targetName = address.name ?? address.namePath![address.namePath!.length - 1];
+
+    const candidates: ReconcileCandidate[] = [];
+    collectDescendants(root, (node, namePath) => {
+        if ((node.name ?? "") !== targetName) return;
+        const reasons = [`name matches "${targetName}"`];
+        let confidence = 0.5;
+        if (address.namePath?.length) {
+            const similarity = pathSuffixSimilarity(address.namePath, namePath);
+            confidence += 0.4 * similarity;
+            if (similarity > 0) reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
+        }
+        candidates.push({ object: node, confidence, reasons });
+    });
+    if (candidates.length === 1) {
+        candidates[0].confidence = Math.min(0.95, candidates[0].confidence + 0.1);
+        candidates[0].reasons.push("only candidate with this name");
+    }
+    return candidates.sort((a, b) => b.confidence - a.confidence);
+}
+
+/** every element of one glTF collection matching `predicate` */
+function collectInJsonCollection(json: GltfJson, key: string, predicate: (el: Record<string, any>) => boolean): Array<{ index: number; element: Record<string, unknown> }> {
+    const collection = json[key];
+    if (!Array.isArray(collection)) return [];
+    const found: Array<{ index: number; element: Record<string, unknown> }> = [];
+    for (let i = 0; i < collection.length; i++) {
+        const element = collection[i];
+        if (element != null && typeof element === "object" && predicate(element)) {
+            found.push({ index: i, element });
+        }
+    }
+    return found;
+}
+
+function findInCollection(json: GltfJson, key: string, predicate: (el: Record<string, any>) => boolean): { index: number; element: Record<string, unknown> } | null {
+    const collection = json[key];
+    if (!Array.isArray(collection)) return null;
+    for (let i = 0; i < collection.length; i++) {
+        const element = collection[i];
+        if (element != null && typeof element === "object" && predicate(element)) {
+            return { index: i, element };
+        }
+    }
+    return null;
+}
+
+function walkGltfNamePath(json: GltfJson, namePath: string[]): number | null {
+    const nodes = json["nodes"];
+    const scenes = json["scenes"];
+    if (!Array.isArray(nodes) || !Array.isArray(scenes)) return null;
+    // roots: the union of all scenes' root nodes
+    let candidates: number[] = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
+    let match: number | null = null;
+    for (const segment of namePath) {
+        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
+        if (match === null) return null;
+        const children = nodes[match]?.children;
+        candidates = Array.isArray(children) ? children : [];
+    }
+    return match;
+}
+
+/** every node matching `predicate`, stopping once `limit` are found (cycle-safe) */
+function collectInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, limit: number): GraphNode[] {
+    const found: GraphNode[] = [];
+    const visited = new Set<GraphNode>();
+    const walk = (node: GraphNode) => {
+        if (found.length >= limit || visited.has(node)) return;
+        visited.add(node);
+        if (predicate(node)) {
+            found.push(node);
+            if (found.length >= limit) return;
+        }
+        if (!node.children) return;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (child != null) walk(child);
+        }
+    };
+    walk(root);
+    return found;
+}
+
+function findInGraph(root: GraphNode, predicate: (node: GraphNode) => boolean, visited = new Set<GraphNode>()): GraphNode | null {
+    if (visited.has(root)) return null;
+    visited.add(root);
+    if (predicate(root)) return root;
+    if (!root.children) return null;
+    for (let i = 0; i < root.children.length; i++) {
+        const child = root.children[i];
+        if (child == null) continue;
+        const found = findInGraph(child, predicate, visited);
+        if (found) return found;
+    }
+    return null;
+}
+
+/** visit every descendant of root with its root-exclusive name path (including own name) */
+function collectDescendants(root: GraphNode, visit: (node: GraphNode, namePath: string[]) => void): void {
+    const visited = new Set<GraphNode>();
+    const walk = (node: GraphNode, namePath: string[]) => {
+        if (visited.has(node)) return;
+        visited.add(node);
+        if (node !== root) visit(node, namePath);
+        if (!node.children) return;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (child == null) continue;
+            walk(child, [...namePath, child.name ?? ""]);
+        }
+    };
+    walk(root, []);
+}
+
+/** how much of the expected path's tail matches the actual path's tail (0..1) */
+function pathSuffixSimilarity(expected: string[], actual: string[]): number {
+    let shared = 0;
+    while (
+        shared < expected.length &&
+        shared < actual.length &&
+        expected[expected.length - 1 - shared] === actual[actual.length - 1 - shared]
+    ) {
+        shared++;
+    }
+    return shared / Math.max(expected.length, actual.length);
+}

package/src/uuid.ts

@@ -1,48 +1,48 @@
-import { sha1, toHex } from "./hash.js";
-
-/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
-export const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
-
-/**
- * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
- * package's `v5(name, namespace)`.
- */
-export function uuidv5(name: string, namespace: string = UUID_NAMESPACE_URL): string {
-    const ns = parseUuidBytes(namespace);
-    const nameBytes = new TextEncoder().encode(name);
-    const input = new Uint8Array(ns.length + nameBytes.length);
-    input.set(ns);
-    input.set(nameBytes, ns.length);
-    const hash = sha1(input).slice(0, 16);
-    hash[6] = (hash[6] & 0x0f) | 0x50; // version 5
-    hash[8] = (hash[8] & 0x3f) | 0x80; // RFC 4122 variant
-    return formatUuid(hash);
-}
-
-/**
- * Random UUID for content that has no source file to be deterministic against
- * (scratch content created in an editor). Uses the platform's crypto when available.
- */
-export function randomUuid(): string {
-    const cryptoObj = globalThis.crypto;
-    if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
-    const bytes = new Uint8Array(16);
-    if (cryptoObj?.getRandomValues) cryptoObj.getRandomValues(bytes);
-    else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
-    bytes[6] = (bytes[6] & 0x0f) | 0x40;
-    bytes[8] = (bytes[8] & 0x3f) | 0x80;
-    return formatUuid(bytes);
-}
-
-function parseUuidBytes(uuid: string): Uint8Array {
-    const hex = uuid.replace(/-/g, "");
-    if (hex.length !== 32) throw new Error(`Invalid UUID: ${uuid}`);
-    const bytes = new Uint8Array(16);
-    for (let i = 0; i < 16; i++) bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
-    return bytes;
-}
-
-function formatUuid(bytes: Uint8Array): string {
-    const hex = toHex(bytes);
-    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
-}
+import { sha1, toHex } from "./hash.js";
+
+/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
+export const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+
+/**
+ * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
+ * package's `v5(name, namespace)`.
+ */
+export function uuidv5(name: string, namespace: string = UUID_NAMESPACE_URL): string {
+    const ns = parseUuidBytes(namespace);
+    const nameBytes = new TextEncoder().encode(name);
+    const input = new Uint8Array(ns.length + nameBytes.length);
+    input.set(ns);
+    input.set(nameBytes, ns.length);
+    const hash = sha1(input).slice(0, 16);
+    hash[6] = (hash[6] & 0x0f) | 0x50; // version 5
+    hash[8] = (hash[8] & 0x3f) | 0x80; // RFC 4122 variant
+    return formatUuid(hash);
+}
+
+/**
+ * Random UUID for content that has no source file to be deterministic against
+ * (scratch content created in an editor). Uses the platform's crypto when available.
+ */
+export function randomUuid(): string {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (cryptoObj?.getRandomValues) cryptoObj.getRandomValues(bytes);
+    else for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return formatUuid(bytes);
+}
+
+function parseUuidBytes(uuid: string): Uint8Array {
+    const hex = uuid.replace(/-/g, "");
+    if (hex.length !== 32) throw new Error(`Invalid UUID: ${uuid}`);
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+
+function formatUuid(bytes: Uint8Array): string {
+    const hex = toHex(bytes);
+    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+}