feat(data): add Guid type — 128-bit RFC 4122 v4, linear-memory ECS-compatible (#106)

* feat(data): add Guid type — 128-bit RFC 4122 v4, linear-memory ECS-compatible

Adds `Guid` to `@adobe/data` as a 4×u32 tuple schema (16 bytes / 128 bits),
following the namespace pattern alongside `Time` and `Boolean` in the schema
folder. The tuple representation slots directly into `createStructBuffer` /
the ECS column path without any infrastructure changes.

Helpers: `create` (RFC 4122 v4 via `crypto.getRandomValues`), `toString`,
`fromString`, `equals`, `nil`. Includes 30 vitest tests covering layout
validity, struct buffer round-trips, version/variant bit correctness, and
`toString`/`fromString` interop with `crypto.randomUUID()`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(guid): add toUnserializableKey, performance tests, and README

- Adds `Guid.toUnserializableKey`: 8-char WTF-16 Map key (minimum-length
  JS string for 128 bits, ~10× cheaper to produce than toString)
- Adds `guid.performance.test.ts`: storage write/read comparison across
  StructTypedBuffer, BigUint64Array, and Array<bigint> at N=1M; Map key
  comparison across UUID string, BigInt, and toUnserializableKey at N=100K
- Adds README with design rationale, full benchmark tables, and conclusions

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(guid): rename toString/fromString → toUUID/fromUUID

Clarifies that the canonical output format is a UUID string
("xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"), not an arbitrary string.
Renames source files, tests, exports, README, and performance test
references consistently.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(guid): surface toUUID vs toUnserializableKey performance inline

Adds ~950 ns / ~87 ns cost annotations to the README API table and to
to-uuid.ts, so the trade-off is visible at the call site without
needing to cross-reference the performance test.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: krisnye

packages/data/src/schema/guid/README.md

@@ -0,0 +1,133 @@
+# Guid
+
+A 128-bit RFC 4122 v4 globally-unique identifier, designed for linear-memory
+ECS storage and efficient in-process Map lookups.
+
+## Representation
+
+```ts
+type Guid = readonly [number, number, number, number]; // 4 × u32
+```
+
+128 bits stored as a tuple of four unsigned 32-bit integers. This is the only
+representation that slots into the ECS `StructTypedBuffer` column path without
+any infrastructure changes — the struct codegen layer (`DataView32`,
+`getStructLayout`, `createReadStruct`) is 32-bit-quad-indexed, so `F64`-based
+or `bigint`-based schemas are rejected at that layer.
+
+The schema is a fixed-length `U32` array (16 bytes, `std140`-aligned):
+
+```ts
+Guid.schema // → { type: 'array', items: U32.schema, minItems: 4, maxItems: 4 }
+Guid.layout // → StructLayout { size: 16, type: 'array', fields: { 0,1,2,3 } }
+```
+
+## API
+
+```ts
+Guid.create()                  // → Guid    RFC 4122 v4 via crypto.getRandomValues
+Guid.nil                       // → Guid    [0, 0, 0, 0]
+Guid.equals(a, b)              // → boolean
+Guid.toUUID(g)                 // → string  "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"  ~950 ns
+Guid.fromUUID(s)               // → Guid    throws TypeError on bad input
+Guid.toUnserializableKey(g)    // → string  8-char WTF-16 Map key, NOT serializable  ~87 ns
+```
+
+`toUUID` is for human-readable output and cross-system interop. Use
+`toUnserializableKey` on any hot path where the result stays in-process —
+it is **~11× faster** to produce and hashes faster as a Map key (~93 ns/set
+vs ~215 ns/set at N=100K).
+
+### `Guid.toUnserializableKey`
+
+Returns an 8-character JS string that encodes all 128 bits by splitting each
+`u32` into two UTF-16 code units via `String.fromCharCode`. This is the
+**minimum-length** JS string for 128 bits and the fastest Map key to produce.
+
+**Use only as a transient in-process Map/Set key.** Some code units may be
+lone surrogates (0xD800–0xDFFF), which are valid in WTF-16 JS strings but
+corrupt on serialization (JSON, TextEncoder, postMessage). Do not store,
+transmit, or serialize the result.
+
+```ts
+const key = Guid.toUnserializableKey(g); // fast — ~84–92 ns vs ~950 ns for toUUID
+const map = new Map<string, SomeValue>();
+map.set(key, value);
+map.get(key);
+```
+
+---
+
+## Performance
+
+Tests run at N = 1,000,000 (storage) and N = 100,000 (Map keys) in both the
+Node and browser vitest projects. Numbers are from Node; browser results were
+within 10–20% in most cases. Source: `guid.performance.test.ts`.
+
+### Storage: write (N = 1,000,000)
+
+| Strategy | ns/op | Memory |
+|---|---|---|
+| **StructTypedBuffer** (4×u32, current) | **~8–10** | **15.3 MB** |
+| `BigUint64Array` packed (2×u64, identical footprint) | ~185–250 | 15.3 MB |
+| `Array<bigint>` heap (1×128-bit BigInt per slot) | ~270–345 | ~30.5 MB est. |
+
+### Storage: read (N = 1,000,000)
+
+| Strategy | ns/op |
+|---|---|
+| **StructTypedBuffer** | **~6–7** |
+| `BigUint64Array` packed | ~150–205 |
+| `Array<bigint>` heap | ~36–37 |
+
+StructTypedBuffer is **20–30× faster** than any BigInt-based storage for both
+read and write, despite identical raw byte footprint for the two typed-array
+approaches. The cost is the `u32 ↔ BigInt` conversion required on every
+access — JavaScript's BigInt arithmetic is expensive relative to direct
+typed-array element reads.
+
+The `Array<bigint>` read is faster than `BigUint64Array` read because the
+128-bit value is pre-boxed (no re-packing step), but it doubles the memory
+footprint and its write is the slowest due to heap allocation and seven BigInt
+operations per entry.
+
+### Map key comparison (N = 100,000)
+
+Key encoding is measured separately from the Map operation so the two costs
+can be evaluated independently.
+
+#### Set
+
+| Key type | Map set | Encode cost | Est. total memory |
+|---|---|---|---|
+| 36-char UUID string | ~215–221 ns/op | ~950–1005 ns/op | ~10.7 MB |
+| 128-bit BigInt | ~94–100 ns/op | ~270–370 ns/op | ~8.4 MB |
+| **8-char min UTF-16 (`toUnserializableKey`)** | **~93–110 ns/op** | **~84–92 ns/op** | **~8.4 MB** |
+
+#### Get
+
+| Key type | Map get |
+|---|---|
+| 36-char UUID string | ~72–92 ns/op |
+| 128-bit BigInt | ~94–97 ns/op |
+| **8-char min UTF-16** | **~58–75 ns/op** |
+
+Memory estimates (V8, 64-bit, pointer compression off):
+- `SeqOneByteString` (UUID): ~64 bytes/key + ~48 bytes/entry = ~10.7 MB at N=100K
+- `BigInt` (128-bit, 2 digits): ~40 bytes/key + ~48 bytes/entry = ~8.4 MB at N=100K
+- `SeqTwoByteString` (min-string): ~40 bytes/key + ~48 bytes/entry = ~8.4 MB at N=100K
+
+### Conclusions
+
+**For dense ECS component storage**, use `StructTypedBuffer` via the schema
+(`createArchetype({ ..., guid: Guid.schema })`). It is 20–30× faster than
+any BigInt representation and has the same 16-byte linear memory footprint.
+
+**For Map/Set lookups keyed on GUIDs**, use `Guid.toUnserializableKey`. It
+matches BigInt on set speed, beats it on get, uses the same memory, and is
+**~10× faster to encode** than `Guid.toUUID`. The UUID string is the slowest
+option across all three dimensions.
+
+**Only use `Guid.toUUID` / `Guid.fromUUID` when human readability or
+cross-system interop is required** (logging, APIs, serialization). On a hot
+lookup path, the 36-char UUID string costs ~1 µs per key just to produce.

packages/data/src/schema/guid/create.test.ts

@@ -0,0 +1,44 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Guid } from "./index.js";
+
+describe("Guid.create", () => {
+    it("returns a 4-element tuple of numbers", () => {
+        const g = Guid.create();
+        expect(g).toHaveLength(4);
+        expect(typeof g[0]).toBe("number");
+        expect(typeof g[1]).toBe("number");
+        expect(typeof g[2]).toBe("number");
+        expect(typeof g[3]).toBe("number");
+    });
+
+    it("all elements are in u32 range [0, 4294967295]", () => {
+        const g = Guid.create();
+        for (const n of g) {
+            expect(n).toBeGreaterThanOrEqual(0);
+            expect(n).toBeLessThanOrEqual(0xFFFFFFFF);
+        }
+    });
+
+    it("sets RFC 4122 v4 version nibble (bits 48-51 = 0100)", () => {
+        const g = Guid.create();
+        // Version nibble is bits [15:12] of g[1]
+        const versionNibble = (g[1] >>> 12) & 0xF;
+        expect(versionNibble).toBe(4);
+    });
+
+    it("sets RFC 4122 variant (top 2 bits of g[2] = 10)", () => {
+        const g = Guid.create();
+        const variantBits = (g[2] >>> 30) & 0x3;
+        expect(variantBits).toBe(0b10);
+    });
+
+    it("generates unique values", () => {
+        const seen = new Set<string>();
+        for (let i = 0; i < 100; i++) {
+            seen.add(Guid.toUUID(Guid.create()));
+        }
+        expect(seen.size).toBe(100);
+    });
+});

packages/data/src/schema/guid/create.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Guid } from "./index.js";
+
+// RFC 4122 v4: version nibble (bits 48-51) = 4, variant (bits 64-65) = 10
+export const create = (): Guid => {
+    const arr = new Uint32Array(4);
+    crypto.getRandomValues(arr);
+    arr[1] = (arr[1] & 0xFFFF0FFF) | 0x00004000;
+    arr[2] = (arr[2] & 0x3FFFFFFF) | 0x80000000;
+    return [arr[0], arr[1], arr[2], arr[3]];
+};

packages/data/src/schema/guid/equals.test.ts

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Guid } from "./index.js";
+
+describe("Guid.equals", () => {
+    it("returns true for identical Guids", () => {
+        const g: Guid = [1, 2, 3, 4];
+        expect(Guid.equals(g, g)).toBe(true);
+    });
+
+    it("returns true for two nil Guids", () => {
+        expect(Guid.equals(Guid.nil, [0, 0, 0, 0])).toBe(true);
+    });
+
+    it("returns false when element 0 differs", () => {
+        expect(Guid.equals([1, 2, 3, 4], [9, 2, 3, 4])).toBe(false);
+    });
+
+    it("returns false when element 1 differs", () => {
+        expect(Guid.equals([1, 2, 3, 4], [1, 9, 3, 4])).toBe(false);
+    });
+
+    it("returns false when element 2 differs", () => {
+        expect(Guid.equals([1, 2, 3, 4], [1, 2, 9, 4])).toBe(false);
+    });
+
+    it("returns false when element 3 differs", () => {
+        expect(Guid.equals([1, 2, 3, 4], [1, 2, 3, 9])).toBe(false);
+    });
+
+    it("returns true for two created Guids that are copies", () => {
+        const g = Guid.create();
+        const copy: Guid = [g[0], g[1], g[2], g[3]];
+        expect(Guid.equals(g, copy)).toBe(true);
+    });
+});

packages/data/src/schema/guid/equals.ts

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Guid } from "./index.js";
+
+export const equals = (a: Guid, b: Guid): boolean =>
+    a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];

packages/data/src/schema/guid/from-uuid.test.ts

@@ -0,0 +1,48 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import { describe, it, expect } from "vitest";
+import { Guid } from "./index.js";
+
+describe("Guid.fromUUID", () => {
+    it("parses a canonical lowercase UUID string", () => {
+        const g = Guid.fromUUID("12345678-9abc-def0-1122-334455667788");
+        expect(g).toEqual([0x12345678, 0x9abcdef0, 0x11223344, 0x55667788]);
+    });
+
+    it("parses uppercase hex", () => {
+        const g = Guid.fromUUID("12345678-9ABC-DEF0-1122-334455667788");
+        expect(g).toEqual([0x12345678, 0x9abcdef0, 0x11223344, 0x55667788]);
+    });
+
+    it("round-trips with toUUID", () => {
+        const g: Guid = [0xdeadbeef, 0xcafebabe, 0x80004000, 0x01234567];
+        expect(Guid.equals(Guid.fromUUID(Guid.toUUID(g)), g)).toBe(true);
+    });
+
+    it("round-trips a created Guid through toUUID/fromUUID", () => {
+        const g = Guid.create();
+        expect(Guid.equals(Guid.fromUUID(Guid.toUUID(g)), g)).toBe(true);
+    });
+
+    it("round-trips with crypto.randomUUID() strings", () => {
+        const uuidStr = crypto.randomUUID();
+        const g = Guid.fromUUID(uuidStr);
+        expect(Guid.toUUID(g)).toBe(uuidStr.toLowerCase());
+    });
+
+    it("throws TypeError for wrong length", () => {
+        expect(() => Guid.fromUUID("12345678-9abc-def0-1122-33445566778")).toThrow(TypeError);
+    });
+
+    it("throws TypeError for missing dashes", () => {
+        expect(() => Guid.fromUUID("123456789abcdef011223344556677881")).toThrow(TypeError);
+    });
+
+    it("throws TypeError for non-hex characters", () => {
+        expect(() => Guid.fromUUID("12345678-9xyz-def0-1122-334455667788")).toThrow(TypeError);
+    });
+
+    it("throws TypeError for empty string", () => {
+        expect(() => Guid.fromUUID("")).toThrow(TypeError);
+    });
+});

packages/data/src/schema/guid/from-uuid.ts

@@ -0,0 +1,18 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+import type { Guid } from "./index.js";
+
+const PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export const fromUUID = (s: string): Guid => {
+    if (!PATTERN.test(s)) {
+        throw new TypeError(`Invalid GUID string: "${s}"`);
+    }
+    const h = s.replace(/-/g, "");
+    return [
+        parseInt(h.slice(0, 8), 16),
+        parseInt(h.slice(8, 16), 16),
+        parseInt(h.slice(16, 24), 16),
+        parseInt(h.slice(24, 32), 16),
+    ];
+};