@smonn/ids 0.9.1 → 0.9.3

package/README.md

@@ -1,1041 +1,98 @@
 # @smonn/ids
 
-Public-facing branded IDs for TypeScript apps.
+Public-facing branded IDs for TypeScript apps. Type-safe, sortable, and codec-pluggable.
+
+📖 **Full documentation & interactive playground: [ids.smonn.se](https://ids.smonn.se)**
 
 ```bash
 pnpm add @smonn/ids
 ```
 
-Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — same byte layout as a [ULID](https://github.com/ulid/spec); see [ADR-0002](./docs/adr/0002-payload-layout.md) for the deliberate divergences. The Opaque Timestamp codec (`@smonn/ids/opaque`) keeps the same wire shape but encrypts the payload under a key, so the timestamp isn't readable from the ID.
-
-## What this is for
+Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: 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).
 
-### "Give my entities IDs that are safe to expose in URLs, dashboards, and support tickets"
-
-```ts
-import { createTimestampId } from "@smonn/ids";
-
-const users = createTimestampId("usr");
-const id = users.generate(); // "usr_01h7b3k9rqxn4cw3p9r8t2sgkz"
-```
-
-The three-letter brand tells you what kind of thing the ID refers to without an out-of-band lookup. No leaking row counts via sequential PKs, no slug collisions, no "is this a user or an org?" ambiguity in a stack trace.
-
-### "Catch me passing a `UserId` where I needed an `OrgId`"
+## Quickstart
 
 ```ts
 import { type Id, createTimestampId } from "@smonn/ids";
 
 const users = createTimestampId("usr");
-const orgs = createTimestampId("org");
 
+// Generate — sortable by creation time via ORDER BY id
+const id = users.generate(); // "usr_01h7b3k9rqxn4cw3p9r8t2sgkz"
+
+// Branded: Id<"usr"> and Id<"org"> are not interchangeable
 function loadUser(id: Id<"usr">) {
   /* ... */
 }
 
-loadUser(orgs.generate()); // ❌ Type 'Id<"org">' is not assignable to 'Id<"usr">'.
-```
-
-`Id<Brand>` is nominally tagged. `Id<"usr">` and `Id<"org">` are not interchangeable — even though both are strings at runtime, the type system treats them as distinct.
-
-### "A support agent emailed me an ID — accept it even if they typed it wrong"
-
-```ts
-users.safeParse("usr_01h7b3k9rqxn1cw3p9r8t2sgkz"); // canonical
-users.safeParse("USR_01H7B3K9RQXN1CW3P9R8T2SGKZ"); // uppercase
-users.safeParse("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz"); // o, I, l aliased
-// → { ok: true, id: "usr_01h7b3k9rqxn1cw3p9r8t2sgkz" } for all three
-```
-
-`safeParse` accepts mixed case and the Crockford-spec visual aliases (`o → 0`, `i → 1`, `l → 1`), and always returns the **canonical form** — lowercase, aliases resolved. Equality checks on canonical strings work as expected.
-
-### "Validate an ID arriving from a URL or request body"
-
-```ts
-const r = users.safeParse(input);
-
-if (!r.ok) {
-  switch (r.error) {
-    case "not_string":
-      return 400; // wasn't a string at all
-    case "invalid_prefix":
-      return 404; // wrong kind of ID (or not an ID)
-    case "invalid_base32":
-      return 400; // prefix matched but payload is malformed
-  }
-}
-
-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;
+// Validate untrusted input — lenient in, canonical out
+const r = users.safeParse("USR_01H7B3K9RQXN1CW3P9R8T2SGKZ");
+if (r.ok) {
+  r.id; // "usr_01h7b3k9rqxn1cw3p9r8t2sgkz" as Id<"usr">
 }
 ```
 
-**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)`, `verify(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:
-
-```ts
-users.extractTimestamp(id); // Date
-```
-
-For time-range queries, `minIdForTime(date)` and `maxIdForTime(date)` build synthetic IDs at the tight lower and upper bounds of a given millisecond — same timestamp bytes, random portion filled with all `0x00` (min) or all `0xFF` (max). No separate `created_at` column needed:
-
-```ts
-const start = new Date("2026-01-01T00:00:00Z");
-const end = new Date("2026-02-01T00:00:00Z");
-
-sql`SELECT * FROM users WHERE id BETWEEN ${users.minIdForTime(start)} AND ${users.maxIdForTime(end)}`;
-```
-
-Both validate the date the same way `generate()` does — pre-epoch or past the 48-bit ceiling throws.
-
-To mint a real ID (random tail and all) at a timestamp you choose rather than at `now`, use `generateAt(date)`. The timestamp bytes come from the supplied `Date`; the random portion is filled by the codec's `rng`, so the result round-trips through `extractTimestamp` exactly:
-
-```ts
-const id = users.generateAt(new Date("2024-03-15T12:00:00Z")); // Id<"usr">
-users.extractTimestamp(id); // → 2024-03-15T12:00:00.000Z
-```
-
-This is the one-liner for backfilling: migrating from UUIDv7 / ULID / Snowflake is `oldRows.map((r) => users.generateAt(extractTime(r)))`, with no need to spin up a throwaway codec per timestamp. It validates the date exactly like `generate()` — pre-epoch, past the 48-bit ceiling, or an `Invalid Date` throws.
-
-The timestamp layout (millisecond precision, big-endian, Unix epoch) is part of the public contract — see [ADR-0002](./docs/adr/0002-payload-layout.md).
-
-Caveat: two IDs generated in the same millisecond by the same process have independent random tails and do **not** sort deterministically relative to each other. If you need stable intra-millisecond ordering, this library isn't the right tool.
-
-### "Inject a fixed clock and RNG so my tests are deterministic"
-
-```ts
-const users = createTimestampId("usr", {
-  now: () => new Date("2026-01-01T00:00:00Z").getTime(),
-  rng: (target) => {}, // leave target as zero-filled
-});
-
-users.generate(); // deterministic snapshot-friendly output
-```
-
-Both injection fields (`now?` and `rng?`) are optional. Defaults are `Date.now` and an entropy harvester built on `crypto.randomUUID` (faster than `crypto.getRandomValues` for the 10-byte fills this library needs). `now` returns milliseconds since the Unix epoch. `rng` writes random bytes into the provided target (a 10-byte view into the codec's persistent buffer), so a custom RNG never has to allocate.
-
-### "Catch a double-registered brand before it bites in production"
-
-The intended pattern is one codec per brand per process, constructed at module init. Calling `createTimestampId(brand)` a second time for the same brand usually means a bundling or import bug (accidental re-export, a test re-importing without resetting). In development (`process.env.NODE_ENV !== "production"`), the second call emits a one-shot `console.warn`; the brand-tracking registry is skipped in production. The same registry covers cross-codec collisions: `createTimestampId("usr")` followed by `createOpaqueTimestampId("usr")` warns too, because codec choice is a per-brand commitment ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)). Tests that intentionally re-create codecs can opt out:
-
-```ts
-const users = createTimestampId("usr", { allowDuplicateBrand: true });
-```
-
-The check is a heuristic, not a guarantee. Two physical copies of `@smonn/ids` loaded into the same process (the worst-case bundling bug) each keep their own registry, so neither warns — it catches re-imports of a single module copy, not duplicate copies of the module itself.
-
-### "Use with any Standard Schema validator"
-
-Each codec implements [Standard Schema v1](https://standardschema.dev/), so it slots directly into any validator-aware library (Zod, Valibot, ArkType, tRPC inputs, Hono, etc.) without rewriting the same `z.string().refine(usr.is)` boilerplate:
-
-```ts
-import { type } from "arktype";
-
-const Body = type({ userId: users });
-
-const r = Body({ userId: "USR_01H7B3K9RQXN1CW3P9R8T2SGKZ" });
-// → { userId: "usr_01h7b3k9rqxn1cw3p9r8t2sgkz" } typed as Id<"usr">
-```
-
-`validate` is synchronous, wraps `safeParse`, and returns the canonical `Id<Brand>` on success. Each `ParseError` variant maps to a distinct `issues[].message`:
-
-| ParseError       | message                  |
-| ---------------- | ------------------------ |
-| `not_string`     | `expected string`        |
-| `invalid_prefix` | `expected prefix 'usr_'` |
-| `invalid_base32` | `invalid base32 payload` |
-
-### "Describe an ID field in an OpenAPI / JSON Schema spec"
-
-```ts
-users.toJsonSchema();
-// {
-//   type: "string",
-//   pattern: "^usr_[0-9a-hjkmnp-tv-z]{26}$",
-//   description: "Branded ID for 'usr'",
-//   example: "usr_01h7b3k9rqxn1cw3p9r8t2sgkz",
-// }
-```
-
-`toJsonSchema()` returns a plain object you can drop straight into an OpenAPI `components.schemas` entry, a JSON Schema document, or any tool that derives sample payloads from `example`. The character class `[0-9a-hjkmnp-tv-z]` is the lowercase Crockford base32 alphabet (excludes `i`, `l`, `o`, `u`).
-
-The `pattern` describes the **canonical form only** — it matches `generate()` output and what `is()` accepts, but rejects uppercase and the Crockford aliases (`o`, `i`, `l`) that `safeParse()` tolerates. Normalising lenient input is the codec's job at the boundary; an artefact that describes data at rest describes the canonical wire shape (see [ADR-0003](./docs/adr/0003-canonical-strict-is.md)).
-
-`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.
-
-```ts
-import { createOpaqueTimestampId, importOpaqueKey } from "@smonn/ids/opaque";
-
-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
-await invoices.extractTimestamp(id); // Date — same codec, same key required
-```
-
-Three differences from the Timestamp codec:
-
-- **Async key-dependent methods.** WebCrypto is async-only, so `generate`, `generateAt`, and `extractTimestamp` return `Promise`s. `is`, `parse`, `safeParse`, `toJsonSchema`, and the Standard Schema adapter stay sync — they work on the wire form only ([ADR-0006](./docs/adr/0006-async-keyed-codec-contract.md)).
-- **No `minIdForTime` / `maxIdForTime`.** Encrypted payloads don't sort by time. If you need time-range scans on entities using the Opaque Timestamp codec, store the timestamp in a separate column.
-- **Wire-indistinguishable from the Timestamp codec.** Codec choice is a per-brand commitment; the brand registry warns if you register the same brand against both in dev ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)).
-
-Encryption is AES-CBC with a zero IV. That's deliberately safe here because the plaintext already carries 80 bits of entropy per ID; see [ADR-0004](./docs/adr/0004-aes-cbc-strip-trick.md) for the full rationale.
-
-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)).
-
-**Rotating the Opaque key.** Rotation is **forward-only and caller-tracked** — the codec deliberately has no key ring. The key feeds only `generate` and `extractTimestamp`; `parse`, `safeParse`, `is`, and `toJsonSchema` work on the wire form and never touch it, so rotating forward is nearly free: point new writes at a new key and keep the old key only to read old IDs' timestamps. Because the payload is unauthenticated ([ADR-0004](./docs/adr/0004-aes-cbc-strip-trick.md)) and carries no key id ([ADR-0007](./docs/adr/0007-wire-indistinguishable-codec-variants.md)), the library **cannot** trial a ring to pick the right key for you — a wrong key yields a plausible but wrong timestamp, never an error. You hold one codec per _key epoch_ and select it from your own record of which epoch minted each ID:
-
-```ts
-// One codec instance per key epoch. You — not the library — track which epoch
-// minted each ID (a key-epoch column, tenant→key map, created-at cutover). The
-// epoch CANNOT be read from the ID itself. `allowDuplicateBrand` silences the
-// per-brand registry warning (ADR-0007): multiple instances of one brand is the
-// legitimate case that flag exists for.
-const codecs = new Map([
-  [1, createOpaqueTimestampId("inv", { key: keyV1, allowDuplicateBrand: true })],
-  [2, createOpaqueTimestampId("inv", { key: keyV2, allowDuplicateBrand: true })], // current epoch
-]);
-
-const id = await codecs.get(2)!.generate(); // new IDs use the current epoch's key
-
-// Reading an old ID: look up its epoch from your records, pick that codec.
-const epoch = await db.keyEpochFor(someOldId); // your bookkeeping, not the ID
-await codecs.get(epoch)!.extractTimestamp(someOldId);
-```
-
-If you need transparent, correctness-grade rotation where the library trials a key ring and a wrong key is _rejected_, that's the Signed Timestamp codec's job ([ADR-0012](./docs/adr/0012-signed-timestamp-construction.md)) — its HMAC tag gives a verifiable ring. The Opaque codec trades that away for confidentiality. See [ADR-0013](./docs/adr/0013-opaque-key-rotation.md).
-
-### "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
-```
+`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.
 
-**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:
+## Choosing a codec
 
-```ts
-const start = new Date("2026-01-01T00:00:00Z"); // older
-const end = new Date("2026-02-01T00:00:00Z"); // newer
+All five codecs share the same `<brand>_<26 chars>` wire shape but make different
+trade-offs. They are wire-indistinguishable, so codec choice is a per-brand
+commitment.
 
-// Reverse Timestamp: lower bound = newer time, upper bound = older time
-sql`SELECT * FROM events WHERE id BETWEEN ${events.minIdForTime(end)} AND ${events.maxIdForTime(start)}`;
+| 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 |
 
-// compare: Timestamp codec (ascending) passes start/end in the natural forward direction
-// sql`... WHERE id BETWEEN ${plainEvents.minIdForTime(start)} AND ${plainEvents.maxIdForTime(end)}`
-```
+- **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)
+- **IDs that must not leak creation time** → [Opaque Timestamp](https://ids.smonn.se/codecs/opaque/) (confidentiality)
+- **A public handle for an internal integer PK** → [Wrapped key](https://ids.smonn.se/codecs/wrapped/)
 
-`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.
+Try them all live in the [playground](https://ids.smonn.se/playground/).
 
-**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).
+## Integrations
 
-No key material is required. The inversion is a deterministic byte transform; `generate`, `generateAt`, and `extractTimestamp` are fully synchronous.
+Framework and ORM adapters ship as optional subpath exports (each requires its
+own peer dependency):
 
-## Choosing a codec variant
+- **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
+- **ORM columns:** [Drizzle](https://ids.smonn.se/adapters/drizzle/), [Kysely](https://ids.smonn.se/adapters/kysely/), [Prisma](https://ids.smonn.se/adapters/prisma/)
+- **CLI:** brand-agnostic `inspect` / `generate` / `keygen` — `npx @smonn/ids --help` ([docs](https://ids.smonn.se/cli/))
 
-| Codec             | Import               | Sort direction            | Key required       | Timestamp extractable      | Range query support                                                          |
-| ----------------- | -------------------- | ------------------------- | ------------------ | -------------------------- | ---------------------------------------------------------------------------- |
-| Timestamp         | `@smonn/ids`         | Ascending (oldest-first)  | No                 | Always (plaintext)         | `minIdForTime(t_old)` → `maxIdForTime(t_new)`                                |
-| Reverse Timestamp | `@smonn/ids/reverse` | Descending (newest-first) | No                 | Always (plaintext)         | `minIdForTime(t_new)` → `maxIdForTime(t_old)` (bounds flipped)               |
-| Signed Timestamp  | `@smonn/ids/signed`  | Ascending (oldest-first)  | Yes (signing key)  | Always (plaintext)         | `minIdForTime(t_old)` → `maxIdForTime(t_new)` (sentinels carry no valid tag) |
-| 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                                                                         |
+Every codec also implements [Standard Schema v1](https://standardschema.dev/), so
+it slots into Zod, Valibot, ArkType, tRPC, and any validator-aware library.
 
 ## 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.
-- **Wire-compatible ULIDs.** The byte layout is ULID-shaped but the encoding is lowercase and wrapped in a brand envelope. 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.
 - **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. A custom epoch wouldn't help and isn't supported. To hide creation time per-ID, use the Opaque Timestamp codec (above).
-
-## API surface
-
-```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
-  type TimestampOptions, // { now?, rng?, allowDuplicateBrand? } constructor options
-  type ParseError, // "not_string" | "invalid_prefix" | "invalid_base32"
-  type ParseResult, // safeParse return type
-  type JsonSchema, // toJsonSchema return type
-} 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<OpaqueKey>
-  encodeOpaqueKey, // (bytes: Uint8Array, format: OpaqueKeyFormat) => string
-  decodeOpaqueKey, // (encoded: string, format: OpaqueKeyFormat) => Uint8Array
-  type OpaqueTimestampCodec, // returned by createOpaqueTimestampId
-  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
-  createSignedTimestampId, // (brand: string, opts: SignedTimestampOptions) => SignedTimestampCodec<Brand>
-  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
-  type SignedTimestampCodec, // returned by createSignedTimestampId
-  type SignedTimestampOptions, // { keys: SigningKey[], now?, rng?, allowDuplicateBrand? } constructor options
-  type SafeVerifyResult, // { ok: true, id: Id<Brand> } | { ok: false, error: ParseError | "verification_failed" }
-} 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
-  decodeWrappingKey, // (encoded: string, format: WrappingKeyFormat) => Uint8Array
-  type WrappedKeyCodec, // returned by createWrappedKeyId
-  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/signed` ships the Signed Timestamp codec — it keeps the 48-bit timestamp **readable and sortable** like the Timestamp codec, but replaces half of the random tail with a truncated HMAC tag, making IDs **tamper-evident and verifiable without a database lookup**. This adds **integrity, not confidentiality** — the opposite security axis from the Opaque Timestamp codec, which hides the timestamp but has no auth tag.
-
-The canonical use case is **share links**: embed a Signed Timestamp ID in a share URL and verify it on receipt without a database roundtrip.
-
-```ts
-import { createSignedTimestampId, importSigningKey } from "@smonn/ids/signed";
-
-const key = await importSigningKey(new Uint8Array(32));
-const shares = createSignedTimestampId("shr", { keys: [key] });
-
-const id = await shares.generate(); // "shr_…", timestamp readable and sortable
-shares.extractTimestamp(id); // Date — sync, timestamp is plaintext
-
-await shares.verify(id); // passes; throws IdsError verification_failed on tamper
-```
-
-The non-throwing `safeVerify` path accepts untrusted input, structurally parses first, then verifies — without throwing:
-
-```ts
-const result = await shares.safeVerify(req.params.shareId);
-
-if (!result.ok) {
-  if (result.error === "verification_failed") return 403; // tampered or wrong key
-  return 400; // malformed ID
-}
-
-const { id } = result; // Id<"shr">, canonical
-```
-
-`safeVerify` returns one of:
-
-```ts
-// Success
-{
-  ok: true;
-  id: Id<Brand>;
-}
-
-// Structural parse failure (wrong brand, invalid base32, etc.)
-{
-  ok: false;
-  error: "not_string" | "invalid_prefix" | "invalid_base32";
-}
-
-// Structurally valid but tag mismatch (tampered, wrong keyring, or revoked key)
-{
-  ok: false;
-  error: "verification_failed";
-}
-```
-
-**False-accept bound.** With a signing keyring of `n` entries, an attacker's per-`verify` success probability is approximately `n / 2⁴⁰`. Verification is online-only — the signing key lives server-side, so offline guessing is not possible.
-
-**Key handling.** Import signing key material via `importSigningKey(bytes)` from raw bytes (16, 24, or 32 bytes). Signing-key material is a **separate secret domain** from Opaque keys and Wrapping keys — same `hex` / `base64url` encoded-format conventions, but a distinct `SigningKey` handle and HKDF label so one raw secret cannot silently serve multiple codecs.
-
-```ts
-import { encodeSigningKey, decodeSigningKey } from "@smonn/ids/signed";
-
-const encoded = encodeSigningKey(rawBytes, "base64url"); // string
-const decoded = decodeSigningKey(encoded, "base64url"); // Uint8Array
-```
-
-**Managing the signing keyring.** Pass a non-empty ordered list of signing keys at construction. The first entry is the _current_ key — the only one `generate` / `generateAt` sign with. `verify` / `safeVerify` trial every entry in order until the tag matches, so IDs signed under any listed key remain verifiable. Removing an entry from the list revokes all IDs signed under it.
-
-```ts
-const oldKey = await importSigningKey(rawOldSecret);
-const newKey = await importSigningKey(rawNewSecret);
-
-// Before rotation: only oldKey in the ring
-const legacy = createSignedTimestampId("shr", { keys: [oldKey] });
-const id = await legacy.generate();
-
-// After rotation: newKey is current; oldKey is still accepted on verify
-const rotated = createSignedTimestampId("shr", { keys: [newKey, oldKey] });
-await rotated.verify(id); // succeeds — tried oldKey and matched
-await rotated.generate(); // signs with newKey
-```
-
-`@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));
-
-// 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>` | `ReverseTimestampCodec<Brand>` | `OpaqueTimestampCodec<Brand>` | `SignedTimestampCodec<Brand>` | `WrappedKeyCodec<Brand, Kind>` | Description                                                                   |
-| ---------------------- | ----------------------- | ------------------------------ | ----------------------------- | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
-| `generate()`           | sync                    | sync                           | async                         | async                         | —                              | Produce a fresh ID                                                            |
-| `generateAt(date)`     | sync                    | sync                           | async                         | async                         | —                              | Produce a fresh ID with timestamp bytes from `date` (for backfills)           |
-| `verify(id)`           | —                       | —                              | —                             | async                         | —                              | Verify the HMAC tag; throws `IdsError` `verification_failed` on mismatch      |
-| `safeVerify(input)`    | —                       | —                              | —                             | async                         | —                              | Non-throwing: structurally parse then verify; returns parse or verify error   |
-| `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                          | sync                           | Strict type guard: `true` only for already-canonical strings                  |
-| `parse(value)`         | sync                    | sync                           | sync                          | sync                          | sync                           | Lenient: normalise to canonical, or throw                                     |
-| `safeParse(value)`     | sync                    | sync                           | sync                          | sync                          | sync                           | Lenient: normalise to canonical, or return `{ ok: false, error }`             |
-| `extractTimestamp(id)` | sync                    | sync                           | async                         | sync                          | —                              | Decode the creation `Date` from an `Id<Brand>` (trusts the type)              |
-| `minIdForTime(date)`   | sync                    | sync †                         | —                             | sync ‡                        | —                              | Tight lower bound for any ID generated at `date` (for range queries)          |
-| `maxIdForTime(date)`   | sync                    | sync †                         | —                             | sync ‡                        | —                              | Tight upper bound for any ID generated at `date` (for range queries)          |
-| `toJsonSchema()`       | sync                    | 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.
-
-‡ Signed Timestamp sentinels carry no valid HMAC tag and are not verifiable — they exist only for indexed range scans, not as real IDs.
-
-## 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
-
-Brand-agnostic subcommands, no install required. Run `npx @smonn/ids --help` for the full flag list.
-
-### `inspect` (`i`)
-
-Decode an ID and print brand, timestamp (or lookup key), canonical form, and whether the input was already canonical.
-
-```bash
-$ npx @smonn/ids inspect usr_01h7b3k9rqxn1cw3p9r8t2sgkz
-brand:     usr
-timestamp: 1983-05-27T10:24:22.469Z (43 years ago)
-canonical: usr_01h7b3k9rqxn1cw3p9r8t2sgkz
-input:     canonical
-```
-
-Accepts non-canonical input (uppercase, Crockford aliases). Pass the flag that matches the codec variant used at generation — without a flag, the **Timestamp codec** is assumed.
-
-| Flag                   | Codec variant           | Env var                      | Notes                                                                                           |
-| ---------------------- | ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
-| _(none)_               | Timestamp codec         | —                            | Timestamp readable directly                                                                     |
-| `--opaque`             | Opaque Timestamp codec  | `IDS_KEY`                    | Wrong key yields plausible-but-wrong timestamp, not an error (see [CONTEXT.md](./CONTEXT.md))   |
-| `--reverse`            | Reverse Timestamp codec | —                            | No key required; timestamp decoded from inverted bytes                                          |
-| `--wrapped --kind <k>` | Wrapped key codec       | `IDS_WRAPPING_KEY`           | `--kind` required: `u32`, `i32`, `u64`, `i64`; prints `lookup-key`                              |
-| `--signed`             | Signed Timestamp codec  | `IDS_SIGNING_KEY` (optional) | Without key: prints timestamp only. With key: adds `verification: ok` or `verification: failed` |
-
-Key format defaults to `hex` for all keyed modes; override with `--key-format hex|base64url` or the matching `_FORMAT` env var (see [Environment variables](#environment-variables) below).
-
-```bash
-# Opaque Timestamp (IDS_KEY required):
-IDS_KEY=<hex-or-base64url-key> npx @smonn/ids inspect inv_… --opaque
-
-# Wrapped key (IDS_WRAPPING_KEY and --kind required):
-IDS_WRAPPING_KEY=<hex-or-base64url-key> npx @smonn/ids inspect item_… --wrapped --kind u64
-
-# Reverse Timestamp (no key):
-npx @smonn/ids inspect feed_… --reverse
-
-# Signed Timestamp — timestamp only (no key):
-npx @smonn/ids inspect evt_… --signed
-
-# Signed Timestamp — with verification:
-IDS_SIGNING_KEY=<hex-or-base64url-key> npx @smonn/ids inspect evt_… --signed
-```
-
-### `generate` (`g`)
-
-Mint one or more canonical IDs for a brand. Output is one ID per line (pipeable).
-
-```bash
-$ npx @smonn/ids generate usr --count 3
-usr_…
-usr_…
-usr_…
-```
-
-Flags: `--count` / `-c N` (default 1, max 10000). Uses the Timestamp codec unless a mode flag is set.
-
-| Flag        | Codec variant           | Env var           |
-| ----------- | ----------------------- | ----------------- |
-| _(none)_    | Timestamp codec         | —                 |
-| `--opaque`  | Opaque Timestamp codec  | `IDS_KEY`         |
-| `--reverse` | Reverse Timestamp codec | —                 |
-| `--signed`  | Signed Timestamp codec  | `IDS_SIGNING_KEY` |
-
-```bash
-# Opaque Timestamp:
-IDS_KEY=<hex-or-base64url-key> npx @smonn/ids generate inv --opaque --count 2
-
-# Reverse Timestamp (newest-first sort order):
-npx @smonn/ids generate feed --reverse --count 5
-
-# Signed Timestamp:
-IDS_SIGNING_KEY=<hex-or-base64url-key> npx @smonn/ids generate evt --signed
-```
-
-### `keygen` (`k`)
-
-Emit a random key to stdout — for use with `importOpaqueKey`, `importWrappingKey`, or `importSigningKey` (a secret — do not log or commit). Default: 256-bit hex for the Opaque key domain.
-
-```bash
-$ npx @smonn/ids keygen
-a1b2c3…
-
-$ npx @smonn/ids keygen --bits 128 --key-format base64url
-AbCdEf…
-```
-
-| Flag        | Key domain | Intended for       | Import function     |
-| ----------- | ---------- | ------------------ | ------------------- |
-| _(none)_    | Opaque     | `IDS_KEY`          | `importOpaqueKey`   |
-| `--wrapped` | Wrapping   | `IDS_WRAPPING_KEY` | `importWrappingKey` |
-| `--signed`  | Signing    | `IDS_SIGNING_KEY`  | `importSigningKey`  |
-
-Flags: `--bits 128|192|256` (default 256), `--key-format hex|base64url` (default `hex`). Key-format env vars do not affect `keygen` — only `--key-format` on the command line.
-
-```bash
-# Wrapping key:
-npx @smonn/ids keygen --wrapped
-
-# Signing key (base64url):
-npx @smonn/ids keygen --signed --key-format base64url
-```
-
-### Environment variables
-
-All keyed modes read secrets from environment variables — not from argv (argv leaks via `ps` and shell history). Missing or malformed key env vars print a clear stderr message and exit non-zero. Invalid input prints the parse error to stderr and exits non-zero.
-
-| Env var                   | Used by                       | Default format |
-| ------------------------- | ----------------------------- | -------------- |
-| `IDS_KEY`                 | `--opaque`                    | `hex`          |
-| `IDS_KEY_FORMAT`          | `--opaque` (format override)  | —              |
-| `IDS_WRAPPING_KEY`        | `--wrapped`                   | `hex`          |
-| `IDS_WRAPPING_KEY_FORMAT` | `--wrapped` (format override) | —              |
-| `IDS_SIGNING_KEY`         | `--signed`                    | `hex`          |
-| `IDS_SIGNING_KEY_FORMAT`  | `--signed` (format override)  | —              |
-
-Key format defaults to `hex` for all modes; override per-invocation with `--key-format hex|base64url` or set the matching `_FORMAT` env var for a session default. `--key-format` on the command line wins over the env var. Key-format env vars do not affect `keygen` output — only `--key-format` applies there.
-
-### Signed mode (`--signed`)
-
-`generate --signed` and `inspect --signed` read the HMAC signing key from `IDS_SIGNING_KEY` — not from argv.
-
-`inspect --signed` always emits a full timestamp report on stdout and carries a `verification:` line with a three-value verdict:
-
-| Case          | stdout                               | stderr                                         | exit |
-| ------------- | ------------------------------------ | ---------------------------------------------- | ---- |
-| Correct key   | report + `verification: ok`          | —                                              | 0    |
-| Tag mismatch  | report + `verification: failed`      | `verification_failed: <message>`               | 1    |
-| Key missing   | report + `verification: unavailable` | `missing IDS_SIGNING_KEY environment variable` | 1    |
-| Key malformed | report + `verification: unavailable` | specific key diagnostic                        | 1    |
+- **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.
 
-The timestamp is always readable (Signed Timestamp IDs carry a plaintext timestamp), so `inspect` without `--signed` also decodes it — but without verification.
+## Links
 
-Key format defaults to `hex`; override with `--key-format` or `IDS_SIGNING_KEY_FORMAT`. `--key-format` wins over the environment variable.
+- **[Documentation](https://ids.smonn.se)** — full guides, API reference, and playground
+- **[Design decisions](./docs/adr/)** — recorded ADRs
+- **[CONTEXT.md](./CONTEXT.md)** — glossary of the project's vocabulary
+- **[Contributing](./CONTRIBUTING.md)** · **[Security](./SECURITY.md)**
 
-## Design
+## License
 
-- [`CONTEXT.md`](./CONTEXT.md) — glossary of the project's vocabulary
-- [`docs/adr/`](./docs/adr/) — recorded design decisions
+[MIT](./LICENSE)