@smonn/ids 0.14.0 → 0.15.0

package/dist/graphql.d.mts

@@ -1,5 +1,6 @@
 import { t as Id } from "./types-hGBnCpJj.mjs";
 import { t as IdCodec } from "./adapter-types-Bia_w9sg.mjs";
+import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcKKOG.mjs";
 import { GraphQLScalarType } from "graphql";
 
 //#region src/adapters/graphql.d.ts
@@ -27,5 +28,5 @@ declare function idScalar<Brand extends string>(codec: IdCodec<Brand>, config: {
   description?: string;
 }): GraphQLScalarType<Id<Brand>, string>;
 //#endregion
-export { idScalar };
+export { IdsError, type IdsErrorCode, idScalar, isIdsError };
 //# sourceMappingURL=graphql.d.mts.map

package/dist/graphql.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.d.mts","names":[],"sources":["../src/adapters/graphql.ts"],"mappings":";;;;;;;AAwBA;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,MAAA;EAAU,IAAA;EAAc,WAAA;AAAA,IACvB,iBAAA,CAAkB,EAAA,CAAG,KAAA"}
+{"version":3,"file":"graphql.d.mts","names":[],"sources":["../src/adapters/graphql.ts"],"mappings":";;;;;;;AA2BA;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,MAAA;EAAU,IAAA;EAAc,WAAA;AAAA,IACvB,iBAAA,CAAkB,EAAA,CAAG,KAAA"}

package/dist/graphql.mjs

@@ -1,3 +1,4 @@
+import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
 import { GraphQLError, GraphQLScalarType, Kind } from "graphql";
 //#region src/adapters/graphql.ts
 /**
@@ -37,6 +38,6 @@ function idScalar(codec, config) {
 	});
 }
 //#endregion
-export { idScalar };
+export { IdsError, idScalar, isIdsError };
 
 //# sourceMappingURL=graphql.mjs.map

package/dist/graphql.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.mjs","names":[],"sources":["../src/adapters/graphql.ts"],"sourcesContent":["import { GraphQLError, GraphQLScalarType, Kind } from \"graphql\";\nimport type { ValueNode } from \"graphql\";\nimport type { IdCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/**\n * Builds a `GraphQLScalarType` for the given codec and brand.\n *\n * - `serialize` — validates via `codec.safeParse`; throws `GraphQLError` on a non-conforming value.\n * - `parseValue` — validates variables via `codec.safeParse`; throws `GraphQLError` on failure.\n * - `parseLiteral` — validates inline `Kind.STRING` literals; throws `GraphQLError` for any\n *   other AST kind or on a failed `safeParse`.\n *\n * `graphql` must be installed as a peer dependency.\n *\n * @example\n * ```ts\n * import { idScalar } from \"@smonn/ids/graphql\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const UserIdScalar = idScalar(usr, { name: \"UserId\", description: \"A branded user ID.\" });\n * ```\n */\nexport function idScalar<Brand extends string>(\n  codec: IdCodec<Brand>,\n  config: { name: string; description?: string },\n): GraphQLScalarType<Id<Brand>, string> {\n  const parse = (value: unknown): Id<Brand> => {\n    const result = codec.safeParse(value);\n    if (!result.ok) {\n      throw new GraphQLError(`invalid ${config.name}: ${result.error}`);\n    }\n    return result.id;\n  };\n  return new GraphQLScalarType<Id<Brand>, string>({\n    name: config.name,\n    description: config.description,\n    serialize: parse,\n    parseValue: parse,\n    parseLiteral: (ast: ValueNode) => {\n      if (ast.kind !== Kind.STRING) {\n        throw new GraphQLError(`${config.name} must be a string literal, got ${ast.kind}`);\n      }\n      return parse(ast.value);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,SACd,OACA,QACsC;CACtC,MAAM,SAAS,UAA8B;EAC3C,MAAM,SAAS,MAAM,UAAU,KAAK;EACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,aAAa,WAAW,OAAO,KAAK,IAAI,OAAO,OAAO;EAElE,OAAO,OAAO;CAChB;CACA,OAAO,IAAI,kBAAqC;EAC9C,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,WAAW;EACX,YAAY;EACZ,eAAe,QAAmB;GAChC,IAAI,IAAI,SAAS,KAAK,QACpB,MAAM,IAAI,aAAa,GAAG,OAAO,KAAK,iCAAiC,IAAI,MAAM;GAEnF,OAAO,MAAM,IAAI,KAAK;EACxB;CACF,CAAC;AACH"}
+{"version":3,"file":"graphql.mjs","names":[],"sources":["../src/adapters/graphql.ts"],"sourcesContent":["import { GraphQLError, GraphQLScalarType, Kind } from \"graphql\";\nimport type { ValueNode } from \"graphql\";\nimport type { IdCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\n/**\n * Builds a `GraphQLScalarType` for the given codec and brand.\n *\n * - `serialize` — validates via `codec.safeParse`; throws `GraphQLError` on a non-conforming value.\n * - `parseValue` — validates variables via `codec.safeParse`; throws `GraphQLError` on failure.\n * - `parseLiteral` — validates inline `Kind.STRING` literals; throws `GraphQLError` for any\n *   other AST kind or on a failed `safeParse`.\n *\n * `graphql` must be installed as a peer dependency.\n *\n * @example\n * ```ts\n * import { idScalar } from \"@smonn/ids/graphql\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const UserIdScalar = idScalar(usr, { name: \"UserId\", description: \"A branded user ID.\" });\n * ```\n */\nexport function idScalar<Brand extends string>(\n  codec: IdCodec<Brand>,\n  config: { name: string; description?: string },\n): GraphQLScalarType<Id<Brand>, string> {\n  const parse = (value: unknown): Id<Brand> => {\n    const result = codec.safeParse(value);\n    if (!result.ok) {\n      throw new GraphQLError(`invalid ${config.name}: ${result.error}`);\n    }\n    return result.id;\n  };\n  return new GraphQLScalarType<Id<Brand>, string>({\n    name: config.name,\n    description: config.description,\n    serialize: parse,\n    parseValue: parse,\n    parseLiteral: (ast: ValueNode) => {\n      if (ast.kind !== Kind.STRING) {\n        throw new GraphQLError(`${config.name} must be a string literal, got ${ast.kind}`);\n      }\n      return parse(ast.value);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,SACd,OACA,QACsC;CACtC,MAAM,SAAS,UAA8B;EAC3C,MAAM,SAAS,MAAM,UAAU,KAAK;EACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,aAAa,WAAW,OAAO,KAAK,IAAI,OAAO,OAAO;EAElE,OAAO,OAAO;CAChB;CACA,OAAO,IAAI,kBAAqC;EAC9C,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,WAAW;EACX,YAAY;EACZ,eAAe,QAAmB;GAChC,IAAI,IAAI,SAAS,KAAK,QACpB,MAAM,IAAI,aAAa,GAAG,OAAO,KAAK,iCAAiC,IAAI,MAAM;GAEnF,OAAO,MAAM,IAAI,KAAK;EACxB;CACF,CAAC;AACH"}

package/dist/prisma.d.mts

@@ -4,6 +4,16 @@ import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcK
 
 //#region src/adapters/prisma.d.ts
 /**
+* Typed `$extends` result-component field definition produced by
+* {@link IdTransform.computeField} — a `{ needs, compute }` pair whose `compute`
+* return type is statically `Id<Brand>`, so the extended-client model field is
+* typed correctly without a per-call-site cast.
+*/
+type IdComputeField<Brand extends string> = {
+  needs: Record<string, boolean>;
+  compute: (model: Record<string, unknown>) => Id<Brand>;
+};
+/**
 * Read/write transform pair and `$extends` result-component factory for
 * integrating `Id<Brand>` with Prisma extensions.
 */
@@ -27,8 +37,8 @@ type IdTransform<Brand extends string> = {
   * `Id<Brand>` through Prisma's type machinery without a per-call-site cast.
   *
   * @param fieldName - The model field to read from (e.g. `"id"`).
-  * @returns A `{ needs, compute }` object whose `compute` return type is
-  * statically `Id<Brand>`, so the extended-client model field is typed correctly.
+  * @returns An {@link IdComputeField} whose `compute` return type is statically
+  * `Id<Brand>`, so the extended-client model field is typed correctly.
   *
   * @example
   * ```ts
@@ -40,10 +50,7 @@ type IdTransform<Brand extends string> = {
   * // xprisma.user.findUnique(…).id is typed as Id<"usr"> — no cast required
   * ```
   */
-  computeField(fieldName: string): {
-    needs: Record<string, boolean>;
-    compute: (model: Record<string, unknown>) => Id<Brand>;
-  };
+  computeField(fieldName: string): IdComputeField<Brand>;
 };
 /**
 * Creates a read/write transform pair for use with Prisma's `$extends` extension model.
@@ -72,5 +79,5 @@ type IdTransform<Brand extends string> = {
 */
 declare function idField<Brand extends string>(codec: IdColumnCodec<Brand>): IdTransform<Brand>;
 //#endregion
-export { type IdColumnCodec, IdTransform, IdsError, type IdsErrorCode, idField, isIdsError };
+export { type IdColumnCodec, IdComputeField, IdTransform, IdsError, type IdsErrorCode, idField, isIdsError };
 //# sourceMappingURL=prisma.d.mts.map

package/dist/prisma.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.d.mts","names":[],"sources":["../src/adapters/prisma.ts"],"mappings":";;;;;AAYA;;;;AAAA,KAAY,WAAA;;;;;;EAMV,IAAA,CAAK,KAAA,YAAiB,EAAA,CAAG,KAAA;EA6BsB;;;;;;;EArB/C,KAAA,CAAM,KAAA,EAAO,EAAA,CAAG,KAAA;;;;;;;;;;;;;;AAqBkC;AA6BpD;;;;EA/BE,YAAA,CAAa,SAAA;IACX,KAAA,EAAO,MAAA;IACP,OAAA,GAAU,KAAA,EAAO,MAAA,sBAA4B,EAAA,CAAG,KAAA;EAAA;AAAA;;;;;;;;AA6BoC;;;;;;;;;;;;;;;;;;iBAAxE,OAAA,uBAA8B,KAAA,EAAO,aAAA,CAAc,KAAA,IAAS,WAAA,CAAY,KAAA"}
+{"version":3,"file":"prisma.d.mts","names":[],"sources":["../src/adapters/prisma.ts"],"mappings":";;;;;AAcA;;;;;;AAAA,KAAY,cAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA,GAAU,KAAA,EAAO,MAAA,sBAA4B,EAAA,CAAG,KAAA;AAAA;;;;;KAOtC,WAAA;;;;AAPsC;AAOlD;EAME,IAAA,CAAK,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;;;;;EAQzB,KAAA,CAAM,KAAA,EAAO,EAAA,CAAG,KAAA;EAmBiB;;;;;;;;;;;;;;;AAAe;AA4BlD;;EA5BE,YAAA,CAAa,SAAA,WAAoB,cAAA,CAAe,KAAA;AAAA;;;;;;;;;;;;;AA4BsC;;;;;;;;;;;;;iBAAxE,OAAA,uBAA8B,KAAA,EAAO,aAAA,CAAc,KAAA,IAAS,WAAA,CAAY,KAAA"}

package/dist/prisma.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.mjs","names":[],"sources":["../src/adapters/prisma.ts"],"sourcesContent":["import { readIdColumn, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * Read/write transform pair and `$extends` result-component factory for\n * integrating `Id<Brand>` with Prisma extensions.\n */\nexport type IdTransform<Brand extends string> = {\n  /**\n   * Read transform: validates the raw database value via `safeParse` and returns\n   * `Id<Brand>`. Throws if the value is missing, malformed, or belongs to a\n   * different brand.\n   */\n  read(value: unknown): Id<Brand>;\n  /**\n   * Write transform: passes `Id<Brand>` through as its canonical string form.\n   * `Id<Brand>` is already the canonical string, so this is an identity function\n   * at runtime.\n   *\n   * Use in a Prisma `$extends` query component or explicit `data` mapping.\n   */\n  write(value: Id<Brand>): string;\n  /**\n   * Creates a typed `$extends` result-component field definition that carries\n   * `Id<Brand>` through Prisma's type machinery without a per-call-site cast.\n   *\n   * @param fieldName - The model field to read from (e.g. `\"id\"`).\n   * @returns A `{ needs, compute }` object whose `compute` return type is\n   * statically `Id<Brand>`, so the extended-client model field is typed correctly.\n   *\n   * @example\n   * ```ts\n   * const xprisma = prisma.$extends({\n   *   result: {\n   *     user: { id: userIdField.computeField(\"id\") },\n   *   },\n   * });\n   * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n   * ```\n   */\n  computeField(fieldName: string): {\n    needs: Record<string, boolean>;\n    compute: (model: Record<string, unknown>) => Id<Brand>;\n  };\n};\n\n/**\n * Creates a read/write transform pair for use with Prisma's `$extends` extension model.\n *\n * Works with any codec variant exposing `safeParse`.\n *\n * Use `computeField(fieldName)` to produce a typed `$extends` result-component\n * field definition — the brand is carried through Prisma's type machinery\n * automatically and no per-call-site cast is required.\n *\n * @example\n * ```ts\n * import { idField } from \"@smonn/ids/prisma\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const userIdField = idField(usr);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     user: { id: userIdField.computeField(\"id\") },\n *   },\n * });\n * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n * ```\n */\nexport function idField<Brand extends string>(codec: IdColumnCodec<Brand>): IdTransform<Brand> {\n  return {\n    read(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        // Prisma's $extends types `compute` as returning `any` in its constraint\n        // type (DynamicResultExtensionArgs). Returning a pre-built object with an\n        // explicit Id<Brand> return type on `compute` causes TypeScript to infer\n        // the brand through the `& R` intersection in $extends — encapsulating\n        // the single necessary cast here rather than pushing it to every call site.\n        compute: (model: Record<string, unknown>): Id<Brand> =>\n          readIdColumn(codec, model[fieldName]),\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,SAAgB,QAA8B,OAAiD;CAC7F,OAAO;EACL,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,aAAa,WAAmB;GAC9B,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAM3B,UAAU,UACR,aAAa,OAAO,MAAM,UAAU;GACxC;EACF;CACF;AACF"}
+{"version":3,"file":"prisma.mjs","names":[],"sources":["../src/adapters/prisma.ts"],"sourcesContent":["import { readIdColumn, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * Typed `$extends` result-component field definition produced by\n * {@link IdTransform.computeField} — a `{ needs, compute }` pair whose `compute`\n * return type is statically `Id<Brand>`, so the extended-client model field is\n * typed correctly without a per-call-site cast.\n */\nexport type IdComputeField<Brand extends string> = {\n  needs: Record<string, boolean>;\n  compute: (model: Record<string, unknown>) => Id<Brand>;\n};\n\n/**\n * Read/write transform pair and `$extends` result-component factory for\n * integrating `Id<Brand>` with Prisma extensions.\n */\nexport type IdTransform<Brand extends string> = {\n  /**\n   * Read transform: validates the raw database value via `safeParse` and returns\n   * `Id<Brand>`. Throws if the value is missing, malformed, or belongs to a\n   * different brand.\n   */\n  read(value: unknown): Id<Brand>;\n  /**\n   * Write transform: passes `Id<Brand>` through as its canonical string form.\n   * `Id<Brand>` is already the canonical string, so this is an identity function\n   * at runtime.\n   *\n   * Use in a Prisma `$extends` query component or explicit `data` mapping.\n   */\n  write(value: Id<Brand>): string;\n  /**\n   * Creates a typed `$extends` result-component field definition that carries\n   * `Id<Brand>` through Prisma's type machinery without a per-call-site cast.\n   *\n   * @param fieldName - The model field to read from (e.g. `\"id\"`).\n   * @returns An {@link IdComputeField} whose `compute` return type is statically\n   * `Id<Brand>`, so the extended-client model field is typed correctly.\n   *\n   * @example\n   * ```ts\n   * const xprisma = prisma.$extends({\n   *   result: {\n   *     user: { id: userIdField.computeField(\"id\") },\n   *   },\n   * });\n   * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n   * ```\n   */\n  computeField(fieldName: string): IdComputeField<Brand>;\n};\n\n/**\n * Creates a read/write transform pair for use with Prisma's `$extends` extension model.\n *\n * Works with any codec variant exposing `safeParse`.\n *\n * Use `computeField(fieldName)` to produce a typed `$extends` result-component\n * field definition — the brand is carried through Prisma's type machinery\n * automatically and no per-call-site cast is required.\n *\n * @example\n * ```ts\n * import { idField } from \"@smonn/ids/prisma\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const userIdField = idField(usr);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     user: { id: userIdField.computeField(\"id\") },\n *   },\n * });\n * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n * ```\n */\nexport function idField<Brand extends string>(codec: IdColumnCodec<Brand>): IdTransform<Brand> {\n  return {\n    read(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        // Prisma's $extends types `compute` as returning `any` in its constraint\n        // type (DynamicResultExtensionArgs). Returning a pre-built object with an\n        // explicit Id<Brand> return type on `compute` causes TypeScript to infer\n        // the brand through the `& R` intersection in $extends — encapsulating\n        // the single necessary cast here rather than pushing it to every call site.\n        compute: (model: Record<string, unknown>): Id<Brand> =>\n          readIdColumn(codec, model[fieldName]),\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoFA,SAAgB,QAA8B,OAAiD;CAC7F,OAAO;EACL,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,aAAa,WAAmB;GAC9B,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAM3B,UAAU,UACR,aAAa,OAAO,MAAM,UAAU;GACxC;EACF;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smonn/ids",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "license": "MIT",
   "author": "Simon Ingeson (https://github.com/smonn)",
   "repository": {
@@ -11,7 +11,8 @@
     "ids": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "spec/vectors.json"
   ],
   "type": "module",
   "types": "./dist/index.d.mts",

package/spec/vectors.json

@@ -0,0 +1,97 @@
+{
+  "version": 1,
+  "vectors": [
+    {
+      "name": "timestamp_extract_running_example",
+      "category": "codec:timestamp",
+      "operation": "extract",
+      "input": "usr_06f80z92d2dbsqqg28t5cy4tqg",
+      "expected": 1780272145000
+    },
+    {
+      "name": "timestamp_generate_running_example",
+      "category": "codec:timestamp",
+      "operation": "generate",
+      "input": { "timestamp": 1780272145000, "rng": "9abcdef0123456789abc" },
+      "expected": "usr_06f80z92d2dbsqqg28t5cy4tqg"
+    },
+    {
+      "name": "reverse_extract_running_example",
+      "description": "the 6 timestamp bytes are bitwise-inverted before encoding; extract re-inverts them",
+      "category": "codec:reverse",
+      "operation": "extract",
+      "input": "usr_zsgqz0pxjydbsqqg28t5cy4tqg",
+      "expected": 1780272145000
+    },
+    {
+      "name": "reverse_generate_running_example",
+      "category": "codec:reverse",
+      "operation": "generate",
+      "input": { "timestamp": 1780272145000, "rng": "9abcdef0123456789abc" },
+      "expected": "usr_zsgqz0pxjydbsqqg28t5cy4tqg"
+    },
+    {
+      "name": "to_uuid_running_example",
+      "description": "the 16 payload bytes written verbatim as an RFC 9562 lowercase hyphenated UUID",
+      "category": "wire",
+      "operation": "to_uuid",
+      "input": "usr_06f80z92d2dbsqqg28t5cy4tqg",
+      "expected": "019e807d-2268-9abc-def0-123456789abc"
+    },
+    {
+      "name": "from_uuid_running_example",
+      "category": "wire",
+      "operation": "from_uuid",
+      "input": "019e807d-2268-9abc-def0-123456789abc",
+      "expected": { "ok": true, "id": "usr_06f80z92d2dbsqqg28t5cy4tqg" }
+    },
+    {
+      "name": "from_uuid_uppercase_accept",
+      "description": "RFC 9562 parsers accept uppercase hex; output is the same canonical id",
+      "category": "wire",
+      "operation": "from_uuid",
+      "input": "019E807D-2268-9ABC-DEF0-123456789ABC",
+      "expected": { "ok": true, "id": "usr_06f80z92d2dbsqqg28t5cy4tqg" }
+    },
+    {
+      "name": "from_uuid_reject_braces",
+      "description": "braced {…} form is rejected; only the hyphenated 8-4-4-4-12 form is accepted",
+      "category": "wire",
+      "operation": "from_uuid",
+      "input": "{019e807d-2268-9abc-def0-123456789abc}",
+      "expected": { "ok": false, "layer": "uuid" }
+    },
+    {
+      "name": "canonicalize_uppercase",
+      "description": "ASCII A-Z folds to lowercase",
+      "category": "wire",
+      "operation": "canonicalize",
+      "input": "USR_06F80Z92D2DBSQQG28T5CY4TQG",
+      "expected": { "ok": true, "id": "usr_06f80z92d2dbsqqg28t5cy4tqg" }
+    },
+    {
+      "name": "canonicalize_alias_o_to_zero",
+      "description": "Crockford visual alias o/O resolves to 0 before validation",
+      "category": "wire",
+      "operation": "canonicalize",
+      "input": "usr_o6f8oz92d2dbsqqg28t5cy4tqg",
+      "expected": { "ok": true, "id": "usr_06f80z92d2dbsqqg28t5cy4tqg" }
+    },
+    {
+      "name": "canonicalize_reject_padding_bit",
+      "description": "final base32 char '1' has non-zero low 2 bits (not in [048cgmrw])",
+      "category": "wire",
+      "operation": "canonicalize",
+      "input": "usr_00000000000000000000000001",
+      "expected": { "ok": false, "layer": "base32" }
+    },
+    {
+      "name": "canonicalize_reject_wrong_prefix",
+      "description": "a well-formed id of a different brand is rejected at the prefix layer (vectors are authored against brand usr)",
+      "category": "wire",
+      "operation": "canonicalize",
+      "input": "org_06f80z92d2dbsqqg28t5cy4tqg",
+      "expected": { "ok": false, "layer": "prefix" }
+    }
+  ]
+}