@smonn/ids 0.13.0 → 0.14.0

package/README.md

@@ -8,10 +8,7 @@ Public-facing branded IDs for TypeScript apps. Type-safe, sortable, and codec-pl
 pnpm add @smonn/ids
 ```
 
-Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkw`: a three-letter brand, an
-underscore, then 26 Crockford base32 characters of payload. The default
-Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80
-random bits — the same byte layout as a [ULID](https://github.com/ulid/spec).
+Each ID looks like `usr_06f80z92d2dbsqqg28t5cy4tqg`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The default Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — the same byte layout as a [ULID](https://github.com/ulid/spec).
 
 ## Quickstart
 
@@ -21,7 +18,7 @@ import { type Id, createTimestampId } from "@smonn/ids";
 const users = createTimestampId("usr");
 
 // Generate — sortable by creation time via ORDER BY id
-const id = users.generate(); // "usr_01h7b3k9rqxn4cw3p9r8t2sgkw"
+const id = users.generate(); // "usr_06f80z92d2dbsqqg28t5cy4tqg"
 
 // Branded: Id<"usr"> and Id<"org"> are not interchangeable
 function loadUser(id: Id<"usr">) {
@@ -29,35 +26,28 @@ function loadUser(id: Id<"usr">) {
 }
 
 // Validate untrusted input — lenient in, canonical out
-const r = users.safeParse("USR_01H7B3K9RQXN1CW3P9R8T2SGKW");
+const r = users.safeParse("USR_06F80Z92D2DBSQQG28T5CY4TQG");
 if (r.ok) {
-  r.id; // "usr_01h7b3k9rqxn1cw3p9r8t2sgkw" as Id<"usr">
+  r.id; // "usr_06f80z92d2dbsqqg28t5cy4tqg" as Id<"usr">
 }
 ```
 
-`safeParse` accepts mixed case and the Crockford visual aliases (`o → 0`,
-`i → 1`, `l → 1`) and always returns the canonical lowercase form. See the
-[Timestamp codec guide](https://ids.smonn.se/codecs/timestamp/) for sorting,
-backfills (`generateAt`), range queries, structured errors, Standard Schema, and
-JSON Schema.
+`safeParse` accepts mixed case and the Crockford visual aliases (`o → 0`, `i → 1`, `l → 1`) and always returns the canonical lowercase form. See the [Timestamp codec guide](https://ids.smonn.se/codecs/timestamp/) for sorting, backfills (`generateAt`), range queries, structured errors, Standard Schema, and JSON Schema.
 
 ## Choosing a codec
 
-All six codecs share the same `<brand>_<26 chars>` wire shape but make different
-trade-offs. They are wire-indistinguishable — `safeParse`, `is`, and `parse`
-cannot distinguish an Opaque Timestamp ID from a Timestamp ID at runtime.
-Cross-codec confusion is undetectable by the library; the consumer is
-responsible for routing a given ID to the correct codec for the brand. Codec
-choice is therefore a per-brand commitment.
-
-| Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      |
-| ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- |
-| Timestamp         | `@smonn/ids`         | Ascending (oldest-first)  | No                 | Always (plaintext)         |
-| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No                 | Always (plaintext)         |
-| Signed Timestamp  | `@smonn/ids/signed`  | Ascending (oldest-first)  | Yes (signing key)  | Always (plaintext)         |
-| Opaque Timestamp  | `@smonn/ids/opaque`  | None (encrypted)          | Yes (AES key)      | With key only              |
-| Wrapped key       | `@smonn/ids/wrapped` | None                      | Yes (wrapping key) | N/A — not timestamp-family |
-| Digest            | `@smonn/ids/digest`  | None                      | Yes (digest key)   | N/A — not timestamp-family |
+All six codecs share the same `<brand>_<26 chars>` wire shape but make different trade-offs. They are wire-indistinguishable — `safeParse`, `is`, and `parse` cannot distinguish an Opaque Timestamp ID from a Timestamp ID at runtime. Cross-codec confusion is undetectable by the library; the consumer is responsible for routing a given ID to the correct codec for the brand. Codec choice is therefore a per-brand commitment.
+
+| Codec | Import | Sort direction | Key required | Timestamp extractable |
+| --- | --- | --- | --- | --- |
+| Timestamp | `@smonn/ids` | Ascending (oldest-first) | No | Always (plaintext) |
+| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No | Always (plaintext) |
+| Signed Timestamp | `@smonn/ids/signed` | Ascending (oldest-first) | Yes (signing key) | Always (plaintext) |
+| Opaque Timestamp | `@smonn/ids/opaque` | None (encrypted) | Yes (AES key) | With key only |
+| Wrapped key | `@smonn/ids/wrapped` | None | Yes (wrapping key) | N/A — not timestamp-family |
+| Digest | `@smonn/ids/digest` | None | Yes (digest key) | N/A — not timestamp-family |
+
+The Timestamp codec is the default and ships from the root `@smonn/ids` entry — it has no `/timestamp` subpath by design. If you try `import ... from "@smonn/ids/timestamp"` you will get a module-resolution error; use `@smonn/ids` directly. Every other codec uses a named subpath (`/reverse`, `/signed`, `/opaque`, `/wrapped`, `/digest`); this asymmetry is intentional and permanent.
 
 - **Newest-first scans** on forward-only KV stores → [Reverse Timestamp](https://ids.smonn.se/codecs/reverse/)
 - **Tamper-evident share links** verified without a DB lookup → [Signed Timestamp](https://ids.smonn.se/codecs/signed/) (integrity)
@@ -69,40 +59,33 @@ Try them all live in the [playground](https://ids.smonn.se/playground/).
 
 ## Integrations
 
-Framework and ORM adapters ship as optional subpath exports (each requires its
-own peer dependency):
+Framework and ORM adapters ship as optional subpath exports (each requires its own peer dependency):
 
 - **HTTP route params:** [Hono](https://ids.smonn.se/adapters/hono/), [Express](https://ids.smonn.se/adapters/express/), [Fastify](https://ids.smonn.se/adapters/fastify/) — `idParam` middleware; [NestJS](https://ids.smonn.se/adapters/nestjs/) — `ParseIdPipe`
 - **ORM columns:** [Drizzle](https://ids.smonn.se/adapters/drizzle/) — `idColumn`, [Kysely](https://ids.smonn.se/adapters/kysely/) — `idColumn`, [MikroORM](https://ids.smonn.se/adapters/mikro-orm/) — `idType`, [Prisma](https://ids.smonn.se/adapters/prisma/) — `idField`, [TypeORM](https://ids.smonn.se/adapters/typeorm/) — `idTransformer`
 - **GraphQL:** [GraphQL](https://ids.smonn.se/adapters/graphql/) — `idScalar` custom scalar
 - **CLI:** brand-agnostic `inspect` / `generate` / `keygen` — `npx @smonn/ids --help` ([docs](https://ids.smonn.se/cli/))
 
-Every codec also implements [Standard Schema v1](https://standardschema.dev/), so
-it slots into Zod, Valibot, ArkType, tRPC, and any validator-aware library.
+Every codec also implements [Standard Schema v1](https://standardschema.dev/), so it slots into Zod, Valibot, ArkType, tRPC, and any validator-aware library.
+
+**Native `uuid` column storage:** an `Id<Brand>` can be persisted into a native `uuid` column via `codec.toUUID(id)` and read back as a branded ID via `codec.fromUUID(value)` or `codec.safeFromUUID(value)` — a lossless round-trip useful when migrating off UUID primary keys while keeping existing column types and indexes.
 
 ## What this is **not** for
 
-- **Internal surrogate primary keys.** If nobody outside your service sees the
-  ID, the brand prefix and lenient parsing are dead weight. Use a `bigint`
-  sequence.
-- **Wire-compatible ULIDs.** The byte layout is ULID-shaped, but the encoding is
-  lowercase and brand-wrapped. Stock ULID parsers will reject these.
+- **Internal surrogate primary keys.** If nobody outside your service sees the ID, the brand prefix and lenient parsing are dead weight. Use a `bigint` sequence.
+- **Wire-compatible ULIDs.** The byte layout is ULID-shaped, but the encoding is lowercase and brand-wrapped. Stock ULID parsers will reject these.
+- **Spec-valid UUIDv7 output.** `toUUID` produces a **raw, unversioned** UUID — all 128 payload bits are preserved verbatim (lossless round-trip), which means the version/variant nibble positions hold real data, not `0x7`/`0b10`. It is **not** a spec-valid UUIDv7. Only the Timestamp codec happens to produce a UUID whose leading 48 bits are a real millisecond timestamp; only Timestamp and Reverse Timestamp produce time-sortable UUIDs. Importing a non-time-ordered UUID (e.g. a UUIDv4) into a timestamp-family codec via `fromUUID` yields a structurally valid `Id<Brand>` with a meaningless timestamp and random sort order — the same wire-indistinguishable contract that already governs codec variants.
 - **Distributed-trace / request-correlation IDs.** Use OpenTelemetry-format IDs.
-- **Hiding creation time with the Timestamp codec.** Anyone with one ID at a
-  known creation time can compute the epoch offset. Use the Opaque Timestamp
-  codec to hide creation time per-ID.
+- **Hiding creation time with the Timestamp codec.** Anyone with one ID at a known creation time can compute the epoch offset. Use the Opaque Timestamp codec to hide creation time per-ID.
 
 ## API surface
 
-Exports from the main `@smonn/ids` entry point only. Codec-specific subpath
-exports (`@smonn/ids/reverse`, `@smonn/ids/opaque`, `@smonn/ids/signed`,
-`@smonn/ids/wrapped`, `@smonn/ids/digest`) and adapter subpaths are not listed
-here.
+Exports from the main `@smonn/ids` entry point only. Codec-specific subpath exports (`@smonn/ids/reverse`, `@smonn/ids/opaque`, `@smonn/ids/signed`, `@smonn/ids/wrapped`, `@smonn/ids/digest`) and adapter subpaths are not listed here.
 
 ### Types
 
 - `Id<Brand>` — Canonical branded ID string for `Brand`; produced by `generate()` and `safeParse()`.
-- `ParseError` — Parse failure reason string (`"not_string"`, `"invalid_prefix"`, or `"invalid_base32"`) returned by `safeParse()`.
+- `ParseError` — Parse failure reason string returned by `safeParse()` (`"not_string"`, `"invalid_prefix"`, or `"invalid_base32"`) and by `safeFromUUID()` (`"not_string"` or `"invalid_uuid"`).
 - `ParseResult<Brand>` — Discriminated union returned by `safeParse()`: `{ ok: true; id: Id<Brand> }` or `{ ok: false; error: ParseError }`.
 - `JsonSchema` — Shape of the object returned by a codec's `toJsonSchema()`.
 - `IdsErrorCode` — String-literal union of the eleven stable error codes carried by `IdsError`.
@@ -119,9 +102,18 @@ here.
 - `isIdsError(value)` — Type guard for `IdsError`; uses an internal brand to survive ESM/CJS dual-package duplication where bare `instanceof` fails.
 - `createTimestampId(brand, options?)` — Creates a Timestamp codec for `brand` (three lowercase `a–z` characters).
 
+### Shared codec methods (all variants)
+
+Every codec instance exposes the following UUID interop methods in addition to the codec-specific ones documented on the [full docs site](https://ids.smonn.se):
+
+- `toUUID(id)` — Takes a trusted `Id<Brand>`, returns the 16-byte payload reinterpreted as a canonical lowercase-hyphenated UUID `string`. Total — cannot fail. The brand is shed; the output is a plain `string`, not a branded type.
+- `fromUUID(value)` — Takes an untrusted `string`, returns `Id<Brand>`. Throws `IdsError` (`code: "invalid_id"`) with a `ParseError` on `cause` (`"invalid_uuid"`, or `"not_string"` for untyped JavaScript callers) on malformed input.
+- `safeFromUUID(value)` — Takes `unknown`, returns `ParseResult<Brand>` (`{ ok: true; id }` or `{ ok: false; error: ParseError }`). Never throws.
+
 ## Links
 
 - **[Documentation](https://ids.smonn.se)** — full guides, API reference, and playground
+- **[SPEC.md](./SPEC.md)** — descriptive wire-format specification
 - **[Design decisions](./docs/adr/)** — recorded ADRs
 - **[CONTEXT.md](./CONTEXT.md)** — glossary of the project's vocabulary
 - **[Contributing](./CONTRIBUTING.md)** · **[Security](./SECURITY.md)**

package/dist/{adapter-types-CIc-4O-P.d.mts → adapter-types-Bia_w9sg.d.mts}

@@ -1,4 +1,4 @@
-import { i as ParseResult } from "./types-wplmOgOK.mjs";
+import { i as ParseResult } from "./types-hGBnCpJj.mjs";
 
 //#region src/adapters/adapter-types.d.ts
 /** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
@@ -17,4 +17,4 @@ type IdCodec<Brand extends string> = {
 type IdColumnCodec<Brand extends string> = IdCodec<Brand>;
 //#endregion
 export { IdColumnCodec as n, IdParamFailure as r, IdCodec as t };
-//# sourceMappingURL=adapter-types-CIc-4O-P.d.mts.map
+//# sourceMappingURL=adapter-types-Bia_w9sg.d.mts.map

package/dist/{adapter-types-CIc-4O-P.d.mts.map → adapter-types-Bia_w9sg.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"adapter-types-CIc-4O-P.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}
+{"version":3,"file":"adapter-types-Bia_w9sg.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}

package/dist/cli.mjs

@@ -1,11 +1,81 @@
 #!/usr/bin/env node
 import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
-import { t as createTimestampId } from "./timestamp-YPd58344.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-D7y5cgzT.mjs";
-import { t as createReverseTimestampId } from "./reverse-DrAofYWV.mjs";
-import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-B2Aa3zMg.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-BjmVzuYc.mjs";
-import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-Drnof-l_.mjs";
+import { t as createTimestampId } from "./timestamp-RXXwHfHO.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-COAcIIY4.mjs";
+import { t as createReverseTimestampId } from "./reverse-CT-El3hi.mjs";
+import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-Dkdteu1y.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-Oj2hC1vB.mjs";
+import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-CLJEGBxo.mjs";
+//#region src/cli/format.ts
+const invalidIdPrefix = "invalid_id: ";
+function formatCliError(err) {
+	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+}
+function formatWrappedInspectOutput(result) {
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:      ${result.brand}`,
+		`lookup-key: ${result.lookupKey.toString()}`,
+		`canonical:  ${result.canonical}`,
+		`uuid:       ${result.uuid}`,
+		`input:      ${inputLine}`,
+		""
+	].join("\n");
+}
+function formatSignedInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
+	lines.push(`verification: ${result.verification}`);
+	lines.push(`canonical: ${result.canonical}`, `uuid:      ${result.uuid}`, `input:     ${inputLine}`, "");
+	return lines.join("\n");
+}
+function formatInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:     ${result.brand}`,
+		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
+		`canonical: ${result.canonical}`,
+		`uuid:      ${result.uuid}`,
+		`input:     ${inputLine}`,
+		""
+	].join("\n");
+}
+function describeInputForm(input, canonical) {
+	if (input === canonical) return "canonical";
+	const notes = [];
+	if (input !== input.toLowerCase()) notes.push("was uppercase");
+	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
+	return `not canonical (${notes.join(" + ")})`;
+}
+const msPerMinute = 60 * 1e3;
+const msPerHour = 60 * msPerMinute;
+const msPerDay = 24 * msPerHour;
+const daysPerMonth = 30.44;
+const monthsPerYear = 12;
+function formatRelative(thenMs, nowMs) {
+	const diff = nowMs - thenMs;
+	const abs = Math.abs(diff);
+	const suffix = diff < 0 ? "from now" : "ago";
+	const head = headUnits(abs);
+	return head === "" ? "just now" : `${head} ${suffix}`;
+}
+function headUnits(abs) {
+	if (abs < 6e4) return "";
+	if (abs < 36e5) return unit(Math.round(abs / msPerMinute), "minute");
+	if (abs < 864e5) return unit(Math.round(abs / msPerHour), "hour");
+	if (abs < 864e5 * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
+	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
+	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
+	const years = Math.floor(totalMonths / monthsPerYear);
+	const months = totalMonths % monthsPerYear;
+	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
+}
+function unit(n, name) {
+	return `${n} ${n === 1 ? name : `${name}s`}`;
+}
+//#endregion
 //#region src/cli/key-io.ts
 function isLoadKeyError(value) {
 	if (typeof value !== "object" || value === null) return false;
@@ -46,7 +116,7 @@ async function loadKey(opts, format, facet) {
 	} catch (err) {
 		return {
 			kind: "import-failure",
-			message: err.message
+			message: formatCliError(err)
 		};
 	}
 }
@@ -135,7 +205,10 @@ const knownFlags = /* @__PURE__ */ new Set([
 	"--key-format",
 	"--count",
 	"-c",
-	"--bits"
+	"--bits",
+	"--uuid",
+	"--from-uuid",
+	"--brand"
 ]);
 function unsupportedFlagForCommand(command, flags, allowed) {
 	for (const flag of flags) if (!allowed.has(flag)) return knownFlags.has(flag) ? `unsupported flag for ${command}: ${flag}` : `unsupported flag: ${flag}`;
@@ -178,77 +251,10 @@ function isNsError(result) {
 	return result === "--ns requires a value";
 }
 //#endregion
-//#region src/cli/format.ts
-function formatCliError(err) {
-	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
-}
-function formatWrappedInspectOutput(result) {
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:      ${result.brand}`,
-		`lookup-key: ${result.lookupKey.toString()}`,
-		`canonical:  ${result.canonical}`,
-		`input:      ${inputLine}`,
-		""
-	].join("\n");
-}
-function formatSignedInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
-	lines.push(`verification: ${result.verification}`);
-	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
-	return lines.join("\n");
-}
-function formatInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:     ${result.brand}`,
-		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
-		`canonical: ${result.canonical}`,
-		`input:     ${inputLine}`,
-		""
-	].join("\n");
-}
-function describeInputForm(input, canonical) {
-	if (input === canonical) return "canonical";
-	const notes = [];
-	if (input !== input.toLowerCase()) notes.push("was uppercase");
-	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
-	return `not canonical (${notes.join(" + ")})`;
-}
-const msPerMinute = 60 * 1e3;
-const msPerHour = 60 * msPerMinute;
-const msPerDay = 24 * msPerHour;
-const daysPerMonth = 30.44;
-const monthsPerYear = 12;
-function formatRelative(thenMs, nowMs) {
-	const diff = nowMs - thenMs;
-	const abs = Math.abs(diff);
-	const suffix = diff < 0 ? "from now" : "ago";
-	const head = headUnits(abs);
-	return head === "" ? "just now" : `${head} ${suffix}`;
-}
-function headUnits(abs) {
-	if (abs < 6e4) return "";
-	if (abs < 36e5) return unit(Math.round(abs / msPerMinute), "minute");
-	if (abs < 864e5) return unit(Math.round(abs / msPerHour), "hour");
-	if (abs < 864e5 * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
-	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
-	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
-	const years = Math.floor(totalMonths / monthsPerYear);
-	const months = totalMonths % monthsPerYear;
-	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
-}
-function unit(n, name) {
-	return `${n} ${n === 1 ? name : `${name}s`}`;
-}
-//#endregion
 //#region src/cli/variants.ts
 function standardValidate(codec, input) {
 	const result = codec["~standard"].validate(input);
-	if (result.issues) return { issue: result.issues[0].message };
+	if (result.issues) return { issue: invalidIdPrefix + result.issues[0].message };
 	return { value: result.value };
 }
 const timestampVariant = {
@@ -395,6 +401,7 @@ const digestVariant = {
 			});
 			return {
 				safeParse: (v) => codec.safeParse(v),
+				toUUID: (id) => codec.toUUID(id),
 				async generate() {
 					const material = await (opts.readStdin ?? (() => Promise.resolve("")))();
 					return codec.digest(material);
@@ -420,7 +427,11 @@ const generatePolicy = {
 		signedVariant,
 		digestVariant
 	],
-	intrinsicFlags: ["--count", "-c"]
+	intrinsicFlags: [
+		"--count",
+		"-c",
+		"--uuid"
+	]
 };
 const inspectPolicy = {
 	default: timestampVariant,
@@ -430,7 +441,7 @@ const inspectPolicy = {
 		opaqueVariant,
 		signedVariant
 	],
-	intrinsicFlags: []
+	intrinsicFlags: ["--from-uuid", "--brand"]
 };
 const keygenPolicy = {
 	default: opaqueVariant,
@@ -492,8 +503,9 @@ async function buildCodec(variant, brand, values, opts) {
 function usageInspect() {
 	return [
 		"Usage: ids inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
+		"       ids inspect --from-uuid <uuid> --brand <brand>",
 		"",
-		"  Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"  Decode an ID and print brand, timestamp (or lookup key), canonical form, and UUID.",
 		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"  --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
 		"  --kind is required with --wrapped: u32, i32, u64, or i64.",
@@ -501,12 +513,14 @@ function usageInspect() {
 		"  --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
 		"  Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
 		"  Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
+		"  --from-uuid <uuid> converts a UUID back to a canonical Id<Brand>. Requires --brand <brand>.",
+		"  --brand <brand> specifies the entity type brand for --from-uuid (e.g. usr).",
 		""
 	].join("\n");
 }
 function usageGenerate() {
 	return [
-		`Usage: ids generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]`,
+		`Usage: ids generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--uuid] [--key-format hex|base64url]`,
 		"",
 		`  Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
 		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
@@ -517,6 +531,7 @@ function usageGenerate() {
 		"    Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
 		"    Same material + ns + key always produces the same ID. Digest IDs are one-way.",
 		"    --count N > 1 is rejected: same material always produces the same ID.",
+		"  --uuid emits the raw UUID form of each generated ID instead of the canonical ID.",
 		""
 	].join("\n");
 }
@@ -537,7 +552,8 @@ function usage() {
 		"",
 		"Subcommands:",
 		"  inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
-		"    Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"  inspect, i --from-uuid <uuid> --brand <brand>",
+		"    Decode an ID and print brand, timestamp (or lookup key), canonical form, and UUID.",
 		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"    --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
 		"    --kind is required with --wrapped: u32, i32, u64, or i64.",
@@ -545,7 +561,9 @@ function usage() {
 		"    --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
 		"    Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
 		"    Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
-		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]",
+		"    --from-uuid <uuid> converts a UUID back to a canonical Id<Brand>. Requires --brand <brand>.",
+		"    --brand <brand> specifies the entity type brand for --from-uuid (e.g. usr).",
+		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--uuid] [--key-format hex|base64url]",
 		`    Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
 		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"    --reverse mints Reverse Timestamp IDs (newest-first sort order).",
@@ -555,6 +573,7 @@ function usage() {
 		"      Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
 		"      Same material + ns + key always produces the same ID. Digest IDs are one-way.",
 		"      --count N > 1 is rejected: same material always produces the same ID.",
+		"    --uuid emits the raw UUID form of each generated ID instead of the canonical ID.",
 		"  keygen, k [--wrapped] [--signed] [--digest] [--bits 128|192|256] [--key-format hex|base64url]",
 		"    Emit a random key for importOpaqueKey, importWrappingKey, importSigningKey, or importDigestKey (key on stdout; warning on stderr).",
 		"    Safe handling: redirect stdout to a 0600 file (e.g. ids keygen > key.hex && chmod 0600 key.hex);",
@@ -634,7 +653,14 @@ async function runGenerate(args, opts) {
 		opts.stderr(codec.message + "\n");
 		return codec.kind === "usage" ? 2 : 1;
 	}
-	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
+	const emitUuid = flags.has("--uuid");
+	for (let i = 0; i < count; i++) {
+		const id = await codec.generate();
+		if (emitUuid) {
+			const uuid = codec.toUUID(id);
+			opts.stdout(uuid + "\n");
+		} else opts.stdout(id + "\n");
+	}
 	return 0;
 }
 //#endregion
@@ -656,6 +682,32 @@ async function runInspect(args, opts) {
 		opts.stderr(errors[0] + "\n");
 		return 2;
 	}
+	const fromUuidValue = values.get("--from-uuid");
+	if (fromUuidValue !== void 0) {
+		if (fromUuidValue === "") {
+			opts.stderr("--from-uuid requires a value\n");
+			return 2;
+		}
+		const brandValue = values.get("--brand");
+		if (brandValue === void 0 || brandValue === "") {
+			opts.stderr("--from-uuid requires --brand\n");
+			return 2;
+		}
+		let tsCodec;
+		try {
+			tsCodec = createTimestampId(brandValue, codecOpts(opts));
+		} catch (err) {
+			opts.stderr(formatCliError(err) + "\n");
+			return 1;
+		}
+		const result = tsCodec.safeFromUUID(fromUuidValue);
+		if (!result.ok) {
+			opts.stderr("invalid_uuid: not a valid RFC 9562 UUID\n");
+			return 1;
+		}
+		opts.stdout(result.id + "\n");
+		return 0;
+	}
 	const [input] = positionals;
 	if (input === void 0) {
 		opts.stderr(usageInspect());
@@ -680,6 +732,7 @@ async function runInspect(args, opts) {
 	let verifyTimestamp;
 	let verifyCanonical;
 	let verifyNowMs;
+	let verifyTsCodec;
 	if (cap.mode === "verify") {
 		const fmtCheck = parseKeyFormat(values, opts, variant.key);
 		if (isKeyFormatError(fmtCheck)) {
@@ -695,9 +748,10 @@ async function runInspect(args, opts) {
 		}
 		const structValidation = tsCodec["~standard"].validate(input);
 		if (structValidation.issues) {
-			opts.stderr(structValidation.issues[0].message + "\n");
+			opts.stderr(invalidIdPrefix + structValidation.issues[0].message + "\n");
 			return 1;
 		}
+		verifyTsCodec = tsCodec;
 		verifyCanonical = structValidation.value;
 		verifyTimestamp = tsCodec.extractTimestamp(verifyCanonical);
 		verifyNowMs = (opts.now ?? Date.now)();
@@ -705,10 +759,12 @@ async function runInspect(args, opts) {
 	const codecOrError = await buildCodec(variant, brand, values, opts);
 	if (isCodecError(codecOrError)) {
 		if (cap.mode === "verify") {
+			const uuid = verifyTsCodec.toUUID(verifyCanonical);
 			opts.stdout(formatSignedInspectOutput({
 				brand,
 				timestamp: verifyTimestamp,
 				canonical: verifyCanonical,
+				uuid,
 				input,
 				nowMs: verifyNowMs,
 				verification: "unavailable"
@@ -728,15 +784,20 @@ async function runInspect(args, opts) {
 		}
 		canonical = parsed.value;
 	}
+	function codecToUUID(id) {
+		return codecOrError.toUUID(id);
+	}
 	switch (cap.mode) {
 		case "readable": {
 			const timestamp = cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
+			const uuid = codecToUUID(canonical);
 			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
 				canonical,
+				uuid,
 				input,
 				nowMs
 			}));
@@ -745,11 +806,13 @@ async function runInspect(args, opts) {
 		case "keyed-readable": {
 			const timestamp = await cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
+			const uuid = codecToUUID(canonical);
 			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
 				canonical,
+				uuid,
 				input,
 				nowMs
 			}));
@@ -763,15 +826,18 @@ async function runInspect(args, opts) {
 				opts.stderr(formatCliError(err) + "\n");
 				return 1;
 			}
+			const uuid = codecToUUID(canonical);
 			opts.stdout(formatWrappedInspectOutput({
 				brand,
 				lookupKey,
 				canonical,
+				uuid,
 				input
 			}));
 			return 0;
 		}
 		case "verify": {
+			const uuid = verifyTsCodec.toUUID(verifyCanonical);
 			const verifyResult = await cap.safeVerify(codecOrError, input);
 			if (!verifyResult.ok) {
 				/* v8 ignore next 4 -- defensive: both codecs share the same wire parse so ParseError
@@ -784,6 +850,7 @@ async function runInspect(args, opts) {
 					brand,
 					timestamp: verifyTimestamp,
 					canonical: verifyCanonical,
+					uuid,
 					input,
 					nowMs: verifyNowMs,
 					verification: "failed"
@@ -795,6 +862,7 @@ async function runInspect(args, opts) {
 				brand,
 				timestamp: verifyTimestamp,
 				canonical: verifyResult.id,
+				uuid,
 				input,
 				nowMs: verifyNowMs,
 				verification: "ok"
@@ -876,15 +944,20 @@ const commands = [
 	}
 ];
 async function run(opts) {
-	const [subcommand, ...rest] = opts.argv;
-	const command = commands.find((candidate) => candidate.names.includes(subcommand ?? ""));
-	if (command !== void 0) return command.run(rest, opts);
-	if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
-		opts.stdout(usage());
-		return 0;
+	try {
+		const [subcommand, ...rest] = opts.argv;
+		const command = commands.find((candidate) => candidate.names.includes(subcommand ?? ""));
+		if (command !== void 0) return await command.run(rest, opts);
+		if (subcommand === void 0 || subcommand === "--help" || subcommand === "-h") {
+			opts.stdout(usage());
+			return 0;
+		}
+		opts.stderr(usage());
+		return 2;
+	} catch (err) {
+		opts.stderr(formatCliError(err) + "\n");
+		return 1;
 	}
-	opts.stderr(usage());
-	return 2;
 }
 //#endregion
 //#region bin/cli.ts