@smonn/ids 0.5.0 → 0.7.0

package/README.md

@@ -70,6 +70,48 @@ const userId = r.id; // Id<"usr">, canonical
 
 `ParseError` is exported as a literal union so the switch is exhaustive at compile time.
 
+### "Handle structured errors from this library"
+
+`parse()`, `unwrap()`, the ORM adapter read paths, and the codec constructors all throw `IdsError` on failure — a single class with a stable `code` field for programmatic branching. Use `isIdsError()` to safely identify them without depending on `instanceof` across module copies:
+
+```ts
+import { isIdsError } from "@smonn/ids";
+
+try {
+  users.parse(rawInput);
+} catch (err) {
+  if (isIdsError(err)) {
+    switch (err.code) {
+      case "invalid_id": // parse failed; err.cause is the ParseError string
+        return 400;
+      case "invalid_brand": // bad codec construction — fix the brand string
+        throw err;
+      // ...
+    }
+  }
+  throw err;
+}
+```
+
+**Error codes** (`IdsErrorCode` — stable contract; `message` is non-contractual):
+
+| `code`                    | meaning                                         | thrown by                                                 | remedy                                     |
+| ------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------------ |
+| `invalid_brand`           | brand is not three lowercase `a–z` characters   | `create*Id(brand)` construction                           | Fix the brand string                       |
+| `invalid_key_format`      | format is not `hex` or `base64url`              | `decodeOpaqueKey`, `decodeWrappingKey`                    | Pass `"hex"` or `"base64url"`              |
+| `invalid_key_encoding`    | key string is malformed for its declared format | `decodeOpaqueKey`, `decodeWrappingKey`                    | Re-encode the key with the matching format |
+| `invalid_key_length`      | raw key is not 16, 24, or 32 bytes              | `importOpaqueKey`, `importWrappingKey`, decoder functions | Use a valid AES key size                   |
+| `invalid_kind`            | wrapped kind is not `u32`/`i32`/`u64`/`i64`     | `createWrappedKeyId({ kind })`                            | Use one of the four supported kinds        |
+| `empty_keyring`           | the wrapping keyring is empty                   | `createWrappedKeyId({ keys })`                            | Supply at least one `WrappingKey`          |
+| `duplicate_keyring_entry` | two keyring entries share the same raw secret   | `createWrappedKeyId({ keys })`                            | Deduplicate the key list                   |
+| `invalid_lookup_key`      | lookup key is out of range or the wrong JS type | `wrap(lookupKey)`                                         | Check the kind's range and JS type         |
+| `verification_failed`     | no keyring entry verifies the payload tag       | `unwrap(id)`                                              | Check keyring; tamper or wrong key         |
+| `invalid_id`              | string is not a valid ID for this brand         | `parse()`, ORM adapter read paths                         | Use `safeParse()` for untrusted input      |
+
+`invalid_id` carries the originating `ParseError` string on `cause` — check `err.cause` for `"not_string"`, `"invalid_prefix"`, or `"invalid_base32"` when you need to distinguish the failure mode.
+
+`isIdsError()` uses a non-enumerable brand symbol rather than bare `instanceof`, so it works correctly even when multiple copies of `@smonn/ids` are loaded in the same process (the ESM + CJS dual-package hazard).
+
 ### "Sort and date-stamp records using just the ID"
 
 The first 6 bytes of the payload are a big-endian millisecond Unix timestamp, so `ORDER BY id` sorts by creation time without a separate `created_at` column. To extract the timestamp from an existing ID:
@@ -164,6 +206,167 @@ The `pattern` describes the **canonical form only** — it matches `generate()`
 
 `example` is produced by calling `generate()` on each invocation, so it is fresh (non-deterministic) and always matches the returned `pattern`. One consequence: a codec wired with an injected `now` outside the 48-bit range — the same misconfiguration that breaks `generate()` — makes `toJsonSchema()` throw too.
 
+### "Validate a route param in Hono"
+
+`@smonn/ids/hono` provides `idParam` — a middleware factory that validates a named route param against a codec and exposes the canonical `Id<Brand>` to the handler. Hono is an **optional peer dependency**; install it separately alongside `@smonn/ids`.
+
+```bash
+pnpm add hono
+```
+
+```ts
+import { idParam } from "@smonn/ids/hono";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+
+// Default: throws HTTPException → app.onError handles rendering (HTML, JSON, problem+json, …)
+app.get("/users/:id", idParam("id", usr), (c) => {
+  const id = c.get("id"); // Id<"usr">, canonical
+  // …
+});
+
+// Override: consumer fully owns the error response
+app.get(
+  "/orgs/:id",
+  idParam("id", org, {
+    onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+  }),
+  handler,
+);
+
+// Or a lightweight status remap without a full handler
+app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+```
+
+**Default error-channel behavior:** on failure the adapter throws `HTTPException(status)` — it does **not** write a response body itself. This lets the app's existing `app.onError` handler control content negotiation (HTML, JSON, problem+json, redirect, etc.) exactly as it would for any other error.
+
+**`options.onError`:** when provided, the hook owns the response entirely — the adapter neither throws nor writes anything.
+
+**`options.status`:** remaps the default HTTP status for a failure reason without requiring a full handler.
+
+**400 vs 404 defaults:**
+
+- **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, status 404.** The resource cannot exist under this route — a `usr_` ID makes no sense on `/orders/:id`.
+- **Malformed or missing ID (`invalid_base32` or `not_string`) → `reason: "malformed"`, status 400.** The ID is absent or unreadable — a bad request, not a missing resource.
+
+`idParam` calls `safeParse` at the boundary (lenient: accepts mixed case and Crockford aliases), so the handler always receives a canonical, normalized `Id<Brand>` — never the raw URL string. Works with any codec variant's structural `safeParse`.
+
+### "Validate a route param in Express"
+
+`@smonn/ids/express` provides the same `idParam` factory for Express. Express is an **optional peer dependency**; install it separately alongside `@smonn/ids`.
+
+```bash
+pnpm add express
+```
+
+```ts
+import { idParam, IdParamError } from "@smonn/ids/express";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+
+// Default: calls next(err) with an IdParamError → app error-handling middleware renders it
+app.get("/users/:id", idParam("id", usr), (req, res) => {
+  const id = res.locals.id; // Id<"usr">, canonical
+  // …
+});
+
+// Error-handling middleware receives the typed error
+app.use((err, req, res, next) => {
+  if (err instanceof IdParamError) {
+    res.status(err.status).json({ error: err.reason });
+    return;
+  }
+  next(err);
+});
+
+// Override: consumer fully owns the error response
+app.get(
+  "/orgs/:id",
+  idParam("id", org, {
+    onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+  }),
+  handler,
+);
+
+// Or a lightweight status remap without a full handler
+app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+```
+
+**Default error-channel behavior:** on failure the adapter calls `next(err)` with an `IdParamError` carrying `status` and `reason` — it does **not** write a response body itself. This lets the app's existing error-handling middleware control rendering exactly as it would for any other error.
+
+**`options.onError`:** when provided, the hook owns the response entirely — the adapter does not call `next(err)`.
+
+**`options.status`:** remaps the default HTTP status for a failure reason without requiring a full handler.
+
+The 400 vs 404 defaults are identical to the Hono adapter: `reason: "brand_mismatch"` → 404, `reason: "malformed"` → 400. The canonical `Id<Brand>` is stored in `res.locals` under `paramName` and available to downstream handlers.
+
+### "Validate a route param in Fastify"
+
+`@smonn/ids/fastify` provides the same `idParam` factory for Fastify. Fastify is an **optional peer dependency**; install it separately alongside `@smonn/ids`.
+
+```bash
+pnpm add fastify
+```
+
+```ts
+import { idParam, IdParamError } from "@smonn/ids/fastify";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+
+// Default: throws IdParamError → setErrorHandler renders it
+fastify.get<{ Params: { id: string } }>(
+  "/users/:id",
+  {
+    preHandler: idParam("id", usr),
+  },
+  (request, reply) => {
+    const id = request.params.id; // string; use `as Id<"usr">` if the narrowed type is needed
+    // …
+  },
+);
+
+// Error handler receives the typed error
+fastify.setErrorHandler((err, request, reply) => {
+  if (err instanceof IdParamError) {
+    reply.status(err.statusCode).send({ error: err.reason });
+    return;
+  }
+  reply.send(err);
+});
+
+// Override: consumer fully owns the error response
+fastify.get(
+  "/orgs/:id",
+  {
+    preHandler: idParam("id", org, {
+      onError: (failure, request, reply) =>
+        reply.status(failure.status).send({ error: failure.reason }),
+    }),
+  },
+  handler,
+);
+
+// Or a lightweight status remap without a full handler
+fastify.get(
+  "/things/:id",
+  {
+    preHandler: idParam("id", thing, { status: { brand_mismatch: 400 } }),
+  },
+  handler,
+);
+```
+
+**Default error-channel behavior:** on failure the adapter throws `IdParamError` carrying `statusCode` and `reason` — it does **not** write a response body itself. Fastify's `setErrorHandler` receives the error and controls rendering exactly as it would for any other error.
+
+**`options.onError`:** when provided, the hook owns the response entirely — the adapter does not throw.
+
+**`options.status`:** remaps the default HTTP status for a failure reason without requiring a full handler.
+
+The 400 vs 404 defaults are identical to the Hono and Express adapters: `reason: "brand_mismatch"` → 404, `reason: "malformed"` → 400. The canonical `Id<Brand>` is stored in `request.params` under `paramName`. Works with any codec variant's structural `safeParse`.
+
 ### "Don't leak creation time in IDs that customers can see"
 
 The Timestamp codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the Opaque Timestamp codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
@@ -171,7 +374,7 @@ The Timestamp codec exposes the creation timestamp by design — that's what mak
 ```ts
 import { createOpaqueTimestampId, importOpaqueKey } from "@smonn/ids/opaque";
 
-const key = await importOpaqueKey(new Uint8Array(16)); // 128- or 256-bit raw key
+const key = await importOpaqueKey(new Uint8Array(16)); // returns an OpaqueKey handle
 const invoices = createOpaqueTimestampId("inv", { key });
 
 const id = await invoices.generate(); // "inv_…", timestamp not extractable without the key
@@ -188,6 +391,47 @@ Encryption is AES-CBC with a zero IV. That's deliberately safe here because the
 
 To store or transport key material outside the library, `encodeOpaqueKey` / `decodeOpaqueKey` round-trip raw bytes in `hex` or `base64url` — distinct from the Crockford base32 used in ID payloads. The CLI's `keygen` subcommand emits keys in this format (see [CLI](#cli)).
 
+### "Newest-first IDs for descending range scans"
+
+Most KV stores (DynamoDB, Cloud Datastore, range-scan KV) only support forward lexicographic scans natively — reading the most recent entries first would otherwise require a full reverse scan or a separate sort step. The Reverse Timestamp codec solves this by bitwise-inverting the 48-bit timestamp field before encoding, so newer IDs sort lexicographically before older ones.
+
+```ts
+import { createReverseTimestampId } from "@smonn/ids/reverse";
+
+const events = createReverseTimestampId("evt");
+
+const id = events.generate(); // "evt_…", sorts newest-first
+events.extractTimestamp(id); // Date — inversion is reversed to recover the original ms
+```
+
+**Range-bound direction is flipped.** Because a newer timestamp maps to a lexicographically smaller ID, a time-range scan over [t_old, t_new] passes the newer timestamp as the lower bound and the older timestamp as the upper bound:
+
+```ts
+const start = new Date("2026-01-01T00:00:00Z"); // older
+const end = new Date("2026-02-01T00:00:00Z"); // newer
+
+// Reverse Timestamp: lower bound = newer time, upper bound = older time
+sql`SELECT * FROM events WHERE id BETWEEN ${events.minIdForTime(end)} AND ${events.maxIdForTime(start)}`;
+
+// compare: Timestamp codec (ascending) passes start/end in the natural forward direction
+// sql`... WHERE id BETWEEN ${plainEvents.minIdForTime(start)} AND ${plainEvents.maxIdForTime(end)}`
+```
+
+`minIdForTime(t)` is always the lexicographically smallest ID at millisecond `t` (random portion all `0x00`) and `maxIdForTime(t)` is the largest (random portion all `0xff`). Under reversal, a newer `t` produces a smaller `minIdForTime` result, so the bounds are swapped relative to the Timestamp codec — see [ADR-0010](./docs/adr/0010-reverse-timestamp-inversion.md) for the detailed rationale.
+
+**Same-millisecond order remains non-deterministic.** The random 10-byte tail is not affected by the timestamp inversion. Two IDs generated in the same millisecond have independent random tails and do not sort deterministically relative to each other — the same caveat as the Timestamp codec (ADR-0002).
+
+No key material is required. The inversion is a deterministic byte transform; `generate`, `generateAt`, and `extractTimestamp` are fully synchronous.
+
+## Choosing a codec variant
+
+| Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      | Range query support                                            |
+| ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- | -------------------------------------------------------------- |
+| Timestamp         | `@smonn/ids`         | Ascending (oldest-first)  | No                 | Always                     | `minIdForTime(t_old)` → `maxIdForTime(t_new)`                  |
+| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No                 | Always                     | `minIdForTime(t_new)` → `maxIdForTime(t_old)` (bounds flipped) |
+| Opaque Timestamp  | `@smonn/ids/opaque`  | None (encrypted)          | Yes (AES key)      | With key only              | None — encrypted payloads do not sort by time                  |
+| Wrapped key       | `@smonn/ids/wrapped` | None                      | Yes (wrapping key) | N/A — not timestamp-family | None                                                           |
+
 ## What this is **not** for
 
 - **Internal surrogate primary keys.** If nobody outside your service ever sees the ID, the brand prefix and lenient parsing are dead weight. Use a `bigint` sequence.
@@ -199,6 +443,9 @@ To store or transport key material outside the library, `encodeOpaqueKey` / `dec
 
 ```ts
 import {
+  IdsError, // class — thrown by caller-reachable failures; carries a stable `code`
+  isIdsError, // (value: unknown) => value is IdsError — brand check, survives dual-package
+  type IdsErrorCode, // "invalid_brand" | "invalid_key_format" | ... (10 members)
   createTimestampId, // (brand: string, opts?: TimestampOptions) => TimestampCodec<Brand>
   type Id, // branded string type
   type TimestampCodec, // returned by createTimestampId
@@ -209,16 +456,43 @@ import {
 } from "@smonn/ids";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   createOpaqueTimestampId, // (brand: string, opts: OpaqueTimestampOptions) => OpaqueTimestampCodec<Brand>
-  importOpaqueKey, // (bytes: Uint8Array) => Promise<CryptoKey>
+  importOpaqueKey, // (bytes: Uint8Array) => Promise<OpaqueKey>
   encodeOpaqueKey, // (bytes: Uint8Array, format: OpaqueKeyFormat) => string
   decodeOpaqueKey, // (encoded: string, format: OpaqueKeyFormat) => Uint8Array
   type OpaqueTimestampCodec, // returned by createOpaqueTimestampId
-  type OpaqueTimestampOptions, // { key, now?, rng?, allowDuplicateBrand? } constructor options
+  type OpaqueTimestampOptions, // { key: OpaqueKey, now?, rng?, allowDuplicateBrand? } constructor options
+  type OpaqueKey, // opaque imported handle for AES key material
   type OpaqueKeyFormat, // "hex" | "base64url"
 } from "@smonn/ids/opaque";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  createReverseTimestampId, // (brand: string, opts?: ReverseTimestampOptions) => ReverseTimestampCodec<Brand>
+  type ReverseTimestampCodec, // returned by createReverseTimestampId
+  type ReverseTimestampOptions, // { now?, rng?, allowDuplicateBrand? } constructor options
+} from "@smonn/ids/reverse";
+
+import {
+  importSigningKey, // (bytes: Uint8Array) => Promise<SigningKey>
+  encodeSigningKey, // (bytes: Uint8Array, format: SigningKeyFormat) => string
+  decodeSigningKey, // (encoded: string, format: SigningKeyFormat) => Uint8Array
+  IdsError, // re-exported from @smonn/ids/signed for convenience
+  isIdsError, // re-exported from @smonn/ids/signed for convenience
+  type SigningKey, // opaque SigningKey handle (HKDF-derived)
+  type SigningKeyFormat, // "hex" | "base64url"
+  type IdsErrorCode, // re-exported from @smonn/ids/signed for convenience
+} from "@smonn/ids/signed";
+
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   createWrappedKeyId, // (brand: string, opts: { kind: "u32" | "i32" | "u64" | "i64", keys }) => WrappedKeyCodec<Brand, Kind>
   importWrappingKey, // (bytes: Uint8Array) => Promise<WrappingKey>
   encodeWrappingKey, // (bytes: Uint8Array, format: WrappingKeyFormat) => string
@@ -227,31 +501,294 @@ import {
   type WrappingKey, // opaque imported handle for wrapping key material
   type WrappingKeyFormat, // "hex" | "base64url"
 } from "@smonn/ids/wrapped";
+
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  idColumn, // (codec: IdColumnCodec<Brand>) => PgCustomColumnBuilder (Drizzle column)
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+} from "@smonn/ids/drizzle";
+
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  idField, // (codec: IdColumnCodec<Brand>) => IdTransform<Brand> — read/write transforms for Prisma $extends
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+  type IdTransform, // { read(value: unknown): Id<Brand>; write(value: Id<Brand>): string }
+} from "@smonn/ids/prisma";
+
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  idColumn, // (codec: IdColumnCodec<Brand>) => { toDriver, fromDriver }
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+  type IdColumnType, // ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>
+} from "@smonn/ids/kysely";
+
+import {
+  idParam, // (paramName: string, codec, options?) => Hono MiddlewareHandler — throws HTTPException by default; onError/status options override
+  type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
+  type IdParamOptions, // { onError?, status? }
+} from "@smonn/ids/hono";
+
+import {
+  idParam, // (paramName: string, codec, options?) => Express middleware — calls next(err) with IdParamError by default; onError/status options override
+  IdParamError, // Error subclass with .reason and .status — forwarded via next(err) by default
+  type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
+  type IdParamOptions, // { onError?, status? }
+} from "@smonn/ids/express";
+
+import {
+  idParam, // (paramName: string, codec, options?) => Fastify preHandler — throws IdParamError by default; onError/status options override
+  IdParamError, // Error subclass with .reason and .statusCode — thrown into setErrorHandler by default
+  type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
+  type IdParamOptions, // { onError?, status? }
+} from "@smonn/ids/fastify";
 ```
 
-`@smonn/ids/wrapped` ships the Wrapped key codec for `u32`, `i32`, `u64`, and `i64` lookup keys. `wrap(lookupKey)` emits a public ID, `unwrap(id)` verifies and recovers the lookup key, and `safeUnwrap(input)` structurally parses then reports parse or verification failure without throwing. The 32-bit kinds use `number`; the 64-bit kinds use `bigint`.
+`@smonn/ids/wrapped` ships the Wrapped key codec for `u32`, `i32`, `u64`, and `i64` lookup keys. `wrap(lookupKey)` returns a public ID; `unwrap(id)` verifies the payload and returns the lookup key; `safeUnwrap(input)` is the non-throwing path for untrusted input.
+
+**Integer kinds and value types.** The 32-bit kinds (`u32`, `i32`) use safe JavaScript `number` values in their fixed-width ranges. The 64-bit kinds (`u64`, `i64`) always use `bigint` — even when the magnitude would fit in a `number` — to prevent silent truncation or sign erasure.
 
 ```ts
+import { createWrappedKeyId, importWrappingKey } from "@smonn/ids/wrapped";
+
 const key = await importWrappingKey(new Uint8Array(32));
-const invoices = createWrappedKeyId("inv", { kind: "u64", keys: [key] });
 
-const id = await invoices.wrap(42n); // "inv_..."
-const lookupKey = await invoices.unwrap(id); // 42n
+// u32: number, range [0, 4294967295]
+const u32Ids = createWrappedKeyId("inv", { kind: "u32", keys: [key] });
+const u32Id = await u32Ids.wrap(42); // number → Id<"inv">
+const u32Key = await u32Ids.unwrap(u32Id); // → 42 (number)
+
+// i32: number, range [-2147483648, 2147483647]
+const i32Ids = createWrappedKeyId("rec", { kind: "i32", keys: [key] });
+const i32Id = await i32Ids.wrap(-7); // number → Id<"rec">
+const i32Key = await i32Ids.unwrap(i32Id); // → -7 (number)
+
+// u64: bigint, range [0n, 18446744073709551615n]
+const u64Ids = createWrappedKeyId("ord", { kind: "u64", keys: [key] });
+const u64Id = await u64Ids.wrap(42n); // bigint → Id<"ord">
+const u64Key = await u64Ids.unwrap(u64Id); // → 42n (bigint)
+
+// i64: bigint, range [-9223372036854775808n, 9223372036854775807n]
+const i64Ids = createWrappedKeyId("evt", { kind: "i64", keys: [key] });
+const i64Id = await i64Ids.wrap(-1n); // bigint → Id<"evt">
+const i64Key = await i64Ids.unwrap(i64Id); // → -1n (bigint)
+```
+
+**Keyring rotation.** Pass a non-empty ordered list of wrapping keys at construction. The first entry is the _current_ key — the only one `wrap` uses. `unwrap` trials every entry in order until the verification tag matches, so IDs wrapped under any listed key are still unwrappable. Removing an entry from the list revokes all IDs wrapped under it.
+
+```ts
+const oldKey = await importWrappingKey(rawOldSecret);
+const newKey = await importWrappingKey(rawNewSecret);
+
+// Before rotation: only oldKey in the ring
+const legacy = createWrappedKeyId("inv", { kind: "u32", keys: [oldKey] });
+const id = await legacy.wrap(7);
+
+// After rotation: newKey is current; oldKey is still accepted on unwrap
+const rotated = createWrappedKeyId("inv", { kind: "u32", keys: [newKey, oldKey] });
+await rotated.unwrap(id); // succeeds — tried oldKey and matched
+await rotated.wrap(7); // uses newKey → different public ID
+```
+
+**Equality leakage.** The Wrapped key codec is deterministic: the same lookup key wrapped under the same wrapping key always yields the same public ID. An observer without operator material can tell that two identical public IDs wrap the same lookup key, but cannot recover the lookup key or wrapping key from the ID alone. This is an accepted trade-off for fitting an 8-byte integer lane and an 8-byte verification tag into the 16-byte payload. UUID-sized values (128 bits) are out of scope for this compact branch — there is no room for them alongside the verification tag.
+
+**Fail-closed verification.** `is`, `parse`, and `safeParse` are structural — they check only the prefix and base32 payload shape, with no key material required. Cryptographic verification only happens in `unwrap` and `safeUnwrap`.
+
+- `unwrap(id)` takes a trusted `Id<Brand>` and **throws** if payload verification fails. Use it when the ID is already known to be structurally valid (e.g. freshly loaded from your database).
+- `safeUnwrap(input)` accepts untrusted input, structurally parses first, then verifies — without throwing. It returns one of:
+
+```ts
+// Success
+{
+  ok: true;
+  id: Id<Brand>;
+  lookupKey: number | bigint;
+}
+
+// Structural parse failure (wrong brand, invalid base32, etc.)
+{
+  ok: false;
+  error: "not_string" | "invalid_prefix" | "invalid_base32";
+}
+
+// Payload verified but tag mismatch (tampered, wrong keyring, or revoked key)
+{
+  ok: false;
+  error: "verification_failed";
+}
+```
+
+Use `safeUnwrap` at API boundaries where the input is untrusted:
+
+```ts
+const result = await invoices.safeUnwrap(req.body.invoiceId);
+
+if (!result.ok) {
+  if (result.error === "verification_failed") return 403; // tampered or wrong key
+  return 400; // malformed ID
+}
+
+const { id, lookupKey } = result; // Id<"inv">, number
 ```
 
 ### Codec methods
 
-| Method                 | `TimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | Description                                                                   |
-| ---------------------- | ----------------------- | ----------------------------- | ----------------------------------------------------------------------------- |
-| `generate()`           | sync                    | async                         | Produce a fresh ID                                                            |
-| `generateAt(date)`     | sync                    | async                         | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
-| `is(value)`            | sync                    | sync                          | Strict type guard: `true` only for already-canonical strings                  |
-| `parse(value)`         | sync                    | sync                          | Lenient: normalise to canonical, or throw                                     |
-| `safeParse(value)`     | sync                    | sync                          | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
-| `extractTimestamp(id)` | sync                    | async                         | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
-| `minIdForTime(date)`   | sync                    | —                             | Tight lower bound for any ID generated at `date` (for range queries)          |
-| `maxIdForTime(date)`   | sync                    | —                             | Tight upper bound for any ID generated at `date` (for range queries)          |
-| `toJsonSchema()`       | sync                    | sync                          | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
+| Method                 | `TimestampCodec<Brand>` | `ReverseTimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | `WrappedKeyCodec<Brand, Kind>` | Description                                                                   |
+| ---------------------- | ----------------------- | ------------------------------ | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `generate()`           | sync                    | sync                           | async                         | —                              | Produce a fresh ID                                                            |
+| `generateAt(date)`     | sync                    | sync                           | async                         | —                              | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
+| `wrap(lookupKey)`      | —                       | —                              | —                             | async                          | Wrap a lookup key into a public ID using the current wrapping key             |
+| `unwrap(id)`           | —                       | —                              | —                             | async                          | Verify and recover the lookup key; throws on verification failure             |
+| `safeUnwrap(input)`    | —                       | —                              | —                             | async                          | Non-throwing: structurally parse then verify; returns parse or verify error   |
+| `is(value)`            | sync                    | sync                           | sync                          | sync                           | Strict type guard: `true` only for already-canonical strings                  |
+| `parse(value)`         | sync                    | sync                           | sync                          | sync                           | Lenient: normalise to canonical, or throw                                     |
+| `safeParse(value)`     | sync                    | sync                           | sync                          | sync                           | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
+| `extractTimestamp(id)` | sync                    | sync                           | async                         | —                              | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
+| `minIdForTime(date)`   | sync                    | sync †                         | —                             | —                              | Tight lower bound for any ID generated at `date` (for range queries)          |
+| `maxIdForTime(date)`   | sync                    | sync †                         | —                             | —                              | Tight upper bound for any ID generated at `date` (for range queries)          |
+| `toJsonSchema()`       | sync                    | sync                           | sync                          | sync                           | JSON Schema (`type`/`pattern`/`description`/`example`) for the canonical form |
+
+† Under the Reverse Timestamp codec, a newer timestamp maps to a lexicographically smaller ID — pass `minIdForTime(t_new)` as the lower bound and `maxIdForTime(t_old)` as the upper bound for a [t_old, t_new] scan.
+
+## ORM adapters
+
+### Drizzle (`@smonn/ids/drizzle`)
+
+`@smonn/ids/drizzle` is a subpath export that provides a Drizzle custom column type bound to a codec. It requires `drizzle-orm` as a peer dependency — installing `@smonn/ids` alone does not require Drizzle.
+
+```bash
+pnpm add drizzle-orm
+```
+
+```ts
+import { pgTable } from "drizzle-orm/pg-core";
+import { idColumn } from "@smonn/ids/drizzle";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+
+export const users = pgTable("users", {
+  id: idColumn(usr).primaryKey(),
+});
+// users.id is typed as Id<"usr"> end-to-end
+```
+
+`idColumn(codec)` works with any codec variant — `TimestampCodec`, `OpaqueTimestampCodec`, and `WrappedKeyCodec` all satisfy the required interface.
+
+**Write path:** `Id<Brand>` is already canonical, so it is passed to the driver unchanged.
+
+**Read path:** values from the database are normalised via `codec.safeParse()` rather than the strict `is()` check. Data at rest should already be canonical per [ADR-0003](./docs/adr/0003-canonical-strict-is.md), but `safeParse` is a safe boundary in case stale non-canonical values exist. An unrecognised value throws at read time so corrupt data surfaces immediately rather than silently.
+
+```ts
+import {
+  idColumn, // (codec: IdColumnCodec<Brand>) => PgCustomColumnBuilder
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+} from "@smonn/ids/drizzle";
+```
+
+### Kysely (`@smonn/ids/kysely`)
+
+`@smonn/ids/kysely` is a subpath export that provides a Kysely column adapter bound to a codec. It requires `kysely` as a peer dependency — installing `@smonn/ids` alone does not require Kysely.
+
+```bash
+pnpm add kysely
+```
+
+```ts
+import { idColumn, type IdColumnType } from "@smonn/ids/kysely";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+const usrCol = idColumn(usr);
+
+// Use IdColumnType in your Database interface:
+interface Database {
+  users: { id: IdColumnType<"usr"> };
+}
+
+// Kysely has no runtime transformer — fromDriver/toDriver do NOT fire automatically.
+// You must call fromDriver() manually on every read result.
+// The `as unknown as string` cast is required because TypeScript already sees
+// row.id as Id<"usr"> (from the Database interface), even though the raw DB
+// value is a plain string at runtime.
+const row = await db.selectFrom("users").selectAll().executeTakeFirstOrThrow();
+const id = usrCol.fromDriver(row.id as unknown as string);
+```
+
+`idColumn(codec)` works with any codec variant — `TimestampCodec`, `OpaqueTimestampCodec`, and `WrappedKeyCodec` all satisfy the required interface.
+
+**Write path:** `Id<Brand>` is already canonical, so `toDriver` passes it to the driver unchanged.
+
+**Read path:** `fromDriver` normalises the raw DB string via `codec.safeParse()`. An unrecognised value throws at read time so corrupt data surfaces immediately rather than silently.
+
+```ts
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  idColumn, // (codec: IdColumnCodec<Brand>) => { toDriver, fromDriver }
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+  type IdColumnType, // ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>
+} from "@smonn/ids/kysely";
+```
+
+### Prisma (`@smonn/ids/prisma`)
+
+`@smonn/ids/prisma` is a subpath export that provides a read/write transform pair for integrating `Id<Brand>` with Prisma's `$extends` extension model. It requires `@prisma/client` as a peer dependency — installing `@smonn/ids` alone does not require Prisma.
+
+```bash
+pnpm add @prisma/client
+```
+
+```ts
+import { idField } from "@smonn/ids/prisma";
+import { createTimestampId } from "@smonn/ids";
+import type { Id } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+const userIdField = idField(usr);
+
+const xprisma = prisma.$extends({
+  result: {
+    user: {
+      id: {
+        needs: { id: true },
+        compute(user) {
+          // Cast required — see Prisma caveat below
+          return userIdField.read(user.id) as Id<"usr">;
+        },
+      },
+    },
+  },
+});
+
+// Write path: Id<Brand> is already canonical — pass it directly
+await xprisma.user.create({ data: { id: userIdField.write(usr.generate()), name: "Alice" } });
+
+// Read path: validated and typed as Id<"usr"> (with cast)
+const user = await xprisma.user.findFirstOrThrow();
+```
+
+`idField(codec)` works with any codec variant — `TimestampCodec`, `OpaqueTimestampCodec`, `ReverseTimestampCodec`, and `WrappedKeyCodec` all satisfy the required interface.
+
+**Write path:** `Id<Brand>` is already canonical, so `write` is an identity function — it returns the string unchanged.
+
+**Read path:** values from the database are normalised via `codec.safeParse()` rather than the strict `is()` check. Data at rest should already be canonical per [ADR-0003](./docs/adr/0003-canonical-strict-is.md), but `safeParse` is a safe boundary in case stale non-canonical values exist. An unrecognised value throws at read time so corrupt data surfaces immediately rather than silently.
+
+**Prisma casting caveat:** Prisma's `$extends` result component can add typed computed accessors to model instances, but cannot retroactively re-type an existing schema field at the Prisma Client level. The `read` function asserts `Id<Brand>` at the TypeScript level, but Prisma's generated types for the model field will not reflect this branding. Callers will need an explicit `as Id<"brand">` cast at consumption sites. This is a Prisma type-system constraint, not a library limitation — see the JSDoc on `idField` for the canonical example.
+
+```ts
+import {
+  idField, // (codec: IdColumnCodec<Brand>) => IdTransform<Brand>
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+  type IdTransform, // { read(value: unknown): Id<Brand>; write(value: Id<Brand>): string }
+} from "@smonn/ids/prisma";
+```
 
 ## CLI
 

package/dist/adapter-types-oHCCSgOO.d.mts

@@ -0,0 +1,12 @@
+//#region src/adapter-types.d.ts
+/** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
+type IdParamFailure = {
+  readonly reason: "brand_mismatch";
+  readonly status: number;
+} | {
+  readonly reason: "malformed";
+  readonly status: number;
+};
+//#endregion
+export { IdParamFailure as t };
+//# sourceMappingURL=adapter-types-oHCCSgOO.d.mts.map