@smonn/ids 0.0.0

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm lint
+
+      - run: pnpm fmt:check
+
+      - run: pnpm typecheck
+
+      - run: pnpm test
+
+      - run: pnpm build

package/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install -g npm@latest
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - name: Create release PR or publish
+        uses: changesets/action@v1
+        with:
+          publish: pnpm changeset publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"

package/.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "ignorePatterns": []
+}

package/.oxlintrc.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "oxc"],
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {},
+  "env": {
+    "builtin": true
+  }
+}

package/AGENTS.md

@@ -0,0 +1,15 @@
+# smonn-ids
+
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues on `smonn/ids`, accessed via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default canonical vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context repo: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

package/CONTEXT.md

@@ -0,0 +1,51 @@
+# IDs
+
+Library for generating, parsing, and validating public-facing entity IDs in TypeScript apps. IDs are k-sortable by creation time, type-safe at compile time, and tolerant of human transcription (case + visually-ambiguous characters).
+
+## Language
+
+**Brand**:
+The string that identifies an entity type (e.g. `"usr"`, `"org"`). Exists simultaneously at runtime (the literal characters embedded at the start of every ID) and at the type level (the nominal tag on `Id<Brand>` that prevents cross-type assignment). One concept, two materialisations — the runtime brand IS the type-level brand.
+_Avoid_: prefix, tag (overloaded with HTML/hashtag), type code, object prefix, resource prefix.
+
+**Prefix**:
+The brand plus the trailing separator — `"usr_"`. Distinct from the brand itself: the brand is `"usr"`, the prefix is what actually appears at the start of an encoded ID.
+_Avoid_: brand (use **Brand** for the unsuffixed form), header.
+
+**Codec**:
+The brand-scoped object returned by `createId(brand)`, exposing `generate`, `is`, `parse`, `safeParse`, and `extractTimestamp`. The brand is validated once at codec creation; the prefix is then captured by each method. One codec per entity type, typically constructed at module init.
+_Avoid_: factory, generator, encoder.
+
+**Canonical form**:
+The unique representation of an ID — lowercase, with Crockford base32 aliases (`o`, `i`, `l`) already resolved to `0`, `1`, `1`. Two strings denote the same ID iff their canonical forms are equal. `Id<Brand>` always holds a canonical string: `generate()` produces canonical, `parse()`/`safeParse()` normalise to canonical at the boundary, and `is()` is strict — see [ADR-0003](./docs/adr/0003-canonical-strict-is.md).
+_Avoid_: normalised form (use **Canonical form**), valid form.
+
+**Payload**:
+The 16 raw bytes that follow the prefix in an encoded ID: 6 bytes of millisecond-precision Unix timestamp (big-endian) followed by 10 bytes of randomness. ULID-shaped — same byte layout as a [ULID](https://github.com/ulid/spec), but encoded in lowercase Crockford base32 and wrapped in a brand envelope rather than emitted bare.
+_Avoid_: ULID (use **Payload** when talking about our bytes; reserve "ULID" for the spec itself), body, contents.
+
+## Example dialogue
+
+> **Dev:** I'm storing user IDs in a column. Do I store the string the user typed, or transform it first?
+>
+> **Domain expert:** Store the canonical form. Two strings that decode to the same ID are distinct as JS strings — `===` is wrong unless both are canonical. `safeParse()` returns canonical; that's what goes in the database.
+>
+> **Dev:** So `is()` is the wrong check at the boundary?
+>
+> **Domain expert:** Right. `is()` is strict — it only returns `true` for already-canonical strings. Use it to discriminate between brands on input you already trust. For untrusted external input, use `safeParse()`; it normalises and hands back an `Id<Brand>` you can rely on.
+>
+> **Dev:** What if I have a string I know is a user ID and just want the timestamp out of it?
+>
+> **Domain expert:** It has to be typed as an `Id<"usr">` first — `extractTimestamp` trusts the type. The honest way to get one is `usr.safeParse(...)`. If you cast a raw string to `Id<"usr">`, you own the consequences.
+>
+> **Dev:** Why does everything hang off `usr` instead of being top-level functions?
+>
+> **Domain expert:** `usr` is a codec. One codec per brand, built at module init. The brand is validated once at construction and the prefix is captured by each method. Standalone functions would either re-validate every call or let bad brands silently corrupt data.
+>
+> **Dev:** And the part after `usr_` is just random?
+>
+> **Domain expert:** No — it's the payload. First 6 bytes are a millisecond Unix timestamp, then 10 random bytes. ULID-shaped, but lowercase and wrapped in a brand envelope. That's why IDs sort by creation time.
+
+## Flagged ambiguities / known gaps
+
+**Same-millisecond sort order is non-deterministic.** Two IDs generated in the same ms by the same process have independent random tails; they sort randomly relative to each other rather than by generation order. This is deliberate — see ADR-0002. Adding ULID-style monotonic increment would require a stateful generator and a breaking change to `Options`, and is a separate design exercise if the need ever arises.

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+## Before you open a PR
+
+- **Open or comment on a [GitHub issue](https://github.com/smonn/ids/issues) first** if your change is more than a small bug fix or doc tweak. Especially for anything that touches the wire format, the public API, or the validation contract — these have been deliberated and "I built it, please merge" PRs may not be accepted.
+- **Read [`CONTEXT.md`](./CONTEXT.md).** Use its vocabulary in code, commit messages, and PR descriptions; avoid the synonyms listed under each `_Avoid_:` line.
+- **Skim the [ADRs](./docs/adr/).** They record the constraints your change has to live with.
+
+## Closed design questions
+
+These were considered and rejected for specific reasons. If you have a genuinely new argument, raise it as an issue with that argument explicit — don't ship a PR that silently reopens the decision.
+
+- **Brand width or charset.** Fixed at three lowercase a–z chars. Changing it invalidates every previously-issued ID. See [ADR-0001](./docs/adr/0001-brand-format.md).
+- **Payload byte split, byte order, precision, or epoch.** Fixed at 6 bytes big-endian ms Unix timestamp + 10 random bytes. Same wire-format constraint. See [ADR-0002](./docs/adr/0002-payload-layout.md).
+- **Lenient `is()`.** `is()` is canonical-only by design; the lenient path is `safeParse()`. Restoring lenient `is()` would re-open the footgun ADR-0003 closed. See [ADR-0003](./docs/adr/0003-canonical-strict-is.md).
+- **Monotonicity inside `generate()`.** A stable intra-ms sort would force a breaking change to `Options.rng`. If you need this, design it as a separate opt-in API (e.g. `createMonotonicId`) and propose it in an issue first.
+- **Custom epoch.** 48 bits of ms gives ~8919 years of headroom from 1970; there's no bit-budget motivation to rebase. A custom epoch would turn time into a magic number every downstream consumer would have to remember. See [ADR-0002](./docs/adr/0002-payload-layout.md).
+
+## Setup
+
+```bash
+pnpm install
+```
+
+Requires Node ≥ 24 and pnpm.
+
+## Dev loop
+
+```bash
+pnpm test              # vitest run
+pnpm test:watch        # vitest in watch mode
+pnpm test:coverage     # vitest with v8 coverage
+pnpm typecheck         # tsc --noEmit
+pnpm lint              # oxlint
+pnpm fmt:check         # oxfmt --check
+pnpm build             # tsdown
+```
+
+Run `pnpm test`, `pnpm typecheck`, `pnpm lint`, and `pnpm fmt:check` before opening a PR.
+
+## Style
+
+- **Don't mock the clock or RNG.** Inject them via `Options` (`now`, `rng`) — see the existing tests for how.
+- **New exports → update the API surface section in [`README.md`](./README.md).**
+- **New domain concept → add a glossary entry to [`CONTEXT.md`](./CONTEXT.md)**, including any synonyms you want future contributors to avoid.
+- **New design decision that's hard to reverse, surprising without context, and the result of a real trade-off → add a new ADR** under `docs/adr/`, numbered sequentially.
+- **Commit subjects:** `<scope>: <what changed>` (e.g. `id: tighten is() to canonical-only`).
+
+## Tests
+
+- Add a test for any new public behaviour.
+- Add boundary tests for any new numeric input (compare with `extracts ms at the 48-bit boundary` and friends in `id.test.ts`).
+- Use deterministic `rng` and `now` in tests that assert on the encoded form — never snapshot a fully-random ID.

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Simon Ingeson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @smonn/ids
+
+Public-facing branded IDs for TypeScript apps.
+
+```bash
+pnpm add @smonn/ids
+```
+
+Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkz`: a three-letter brand, an underscore, then 26 Crockford base32 characters encoding 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.
+
+## What this is for
+
+### "Give my entities IDs that are safe to expose in URLs, dashboards, and support tickets"
+
+```ts
+import { createId } from "@smonn/ids";
+
+const users = createId("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`"
+
+```ts
+import { type Id, createId } from "@smonn/ids";
+
+const users = createId("usr");
+const orgs = createId("org");
+
+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.
+
+### "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
+```
+
+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 = createId("usr", {
+  now: () => new Date("2026-01-01T00:00:00Z"),
+  rng: (bytes) => new Uint8Array(bytes),
+});
+
+users.generate(); // deterministic snapshot-friendly output
+```
+
+Both `Options` fields are optional. Defaults are `() => new Date()` and `crypto.getRandomValues`.
+
+## 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.
+- **Distributed-trace / request-correlation IDs.** Use OpenTelemetry-format IDs.
+- **Hiding when your system launched.** Anyone with one known-time ID can compute the epoch offset. A custom epoch isn't supported, and wouldn't help anyway.
+
+## API surface
+
+```ts
+import {
+  createId, // (brand: string, opts?: Partial<Options>) => Codec<Brand>
+  type Id, // branded string type
+  type Codec, // returned by createId
+  type Options, // { now, rng } injection points
+  type ParseError, // "not_string" | "invalid_prefix" | "invalid_base32"
+  type ParseResult, // safeParse return type
+} from "@smonn/ids";
+```
+
+### `Codec<Brand>`
+
+| Method                 | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| `generate()`           | Produce a fresh ID                                                |
+| `is(value)`            | Strict type guard: `true` only for already-canonical strings      |
+| `parse(value)`         | Lenient: normalise to canonical, or throw                         |
+| `safeParse(value)`     | Lenient: normalise to canonical, or return `{ ok: false, error }` |
+| `extractTimestamp(id)` | Decode the creation `Date` from an `Id<Brand>` (trusts the type)  |
+
+## Design
+
+- [`CONTEXT.md`](./CONTEXT.md) — glossary of the project's vocabulary
+- [`docs/adr/`](./docs/adr/) — recorded design decisions

package/docs/adr/0001-brand-format.md

@@ -0,0 +1,10 @@
+# Brand format: three lowercase a–z characters
+
+Public-facing IDs need a short, fixed-width type identifier that humans can scan, that doesn't collide with the Crockford base32 payload, and that survives in URLs. We use exactly three lowercase a–z characters, validated at runtime: three gives 17,576 brands (more than any single app needs), lowercase removes case-normalisation from the brand portion, and excluding digits keeps the brand visually distinct from the payload. The brand width is part of the wire format — changing it invalidates every previously-issued ID.
+
+## Considered Options
+
+- **Variable width** — rejected: forces `split("_")` and a brand registry; parsing ambiguity
+- **Alphanumeric brands** (e.g. `s3_…`) — rejected: visual collision with the payload
+- **2 chars** — rejected: too few combinations as an app grows
+- **4+ chars** — rejected: URL cost without scaling benefit

package/docs/adr/0002-payload-layout.md

@@ -0,0 +1,26 @@
+# Payload layout: ULID-shaped, with deliberate divergences
+
+The payload is laid out exactly like a ULID: 48-bit millisecond Unix timestamp (big-endian) followed by 80 random bits, encoded as 26 Crockford base32 characters. We adopt the ULID byte split because it's already k-sortable, fits cleanly into 26 base32 chars, and gives ~80 bits of randomness per millisecond (collision-safe for any plausible single-app throughput).
+
+Three deliberate divergences from the spec:
+
+- **Lowercase encoding.** The brand is lowercase a–z (see [ADR-0001](./0001-brand-format.md)) and lowercasing the payload keeps the whole ID visually uniform. Decoding remains case-insensitive.
+- **Brand envelope.** IDs are emitted with a `<brand>_` prefix rather than as bare 26-char strings. Off-the-shelf ULID parsers will not accept these and shouldn't be expected to.
+- **No monotonicity.** Two IDs generated in the same millisecond by the same process do not sort deterministically. The ULID spec's monotonic-increment recommendation would require a stateful generator and break the `Options.rng` shape. Sort stability within a single ms is a non-goal for public-facing entity IDs.
+
+## Timestamp contract
+
+`Codec.extractTimestamp(id)` is a public, supported method — its existence makes the timestamp layout part of the stability contract, not an implementation detail. Specifically:
+
+- **Position:** first 6 bytes of the payload (immediately after the prefix, before the random bytes)
+- **Encoding:** unsigned big-endian integer
+- **Precision:** milliseconds
+- **Epoch:** Unix (1970-01-01T00:00:00Z) — not a custom epoch
+
+Unix is non-negotiable. 48 bits of ms gives ~8919 years of headroom from 1970, so there is no bit-budget motivation to rebase (the Snowflake/Discord rationale). A custom epoch would burn the only remaining direct ULID compatibility (the timestamp bytes themselves) and turn epoch into a magic number every external consumer of the bytes would have to know.
+
+`extractTimestamp` does not validate its input — it trusts the `Id<Brand>` type. Callers holding raw external strings must pass them through `safeParse()` / `parse()` first (see [ADR-0003](./0003-canonical-strict-is.md)).
+
+## Consequences
+
+The 16-byte payload layout is part of the wire format. Changing the byte split (e.g. 8+8, 4+12), the timestamp precision, the byte order, or the epoch invalidates every previously-issued ID — the same constraint as the brand width.

package/docs/adr/0003-canonical-strict-is.md

@@ -0,0 +1,12 @@
+# Lenient at boundaries, strict everywhere else
+
+`Id<Brand>` denotes a **canonical** ID: lowercase, with Crockford base32 aliases (`o`, `i`, `l`) already resolved. The boundary between an untrusted external string and a typed `Id<Brand>` is `parse()` / `safeParse()`; these accept lenient input (mixed case, `o`/`i`/`l` aliases) and return the canonical form. `is()` is strict — it returns `true` only for strings that are already canonical. Once a value carries the `Id<Brand>` type, `===` reliably tests logical equality.
+
+## Considered Options
+
+- **Lenient `is()`** (rejected) — equivalent to `safeParse().success`. Leaves `Id<Brand>` semantically ambiguous: a value of that type might or might not be canonical, so consumers can't rely on `===` and non-canonical strings can leak into storage if a caller forgets to round-trip through `parse()`.
+
+## Consequences
+
+- Always call `safeParse()` / `parse()` at the boundary (incoming URL params, form fields, request bodies). Never assert that a raw external string is already an `Id<Brand>`.
+- `is()` is the right guard for trusting an already-typed string (e.g. discriminating across brands within already-validated input). It is the wrong guard for ingesting external input.

package/docs/agents/domain.md

@@ -0,0 +1,37 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+This repo is **single-context**:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-brand-format.md
+│   ├── 0002-payload-layout.md
+│   └── 0003-canonical-strict-is.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@smonn/ids",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@changesets/cli": "2.31.0",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.2",
+    "oxfmt": "0.52.0",
+    "oxlint": "1.67.0",
+    "tsdown": "0.22.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "knip": "knip"
+  }
+}

package/src/base32.ts

@@ -0,0 +1,54 @@
+/*
+  This is based on Crockford's Base32 spec: https://www.crockford.com/base32.html
+  One difference is that it uses lowercase instead of uppercase when encoding.
+*/
+
+import { invariant } from "./invariant.js";
+
+export const alphabet = "0123456789abcdefghjkmnpqrstvwxyz";
+
+const numberToCharLookup = alphabet.split("");
+
+const charToNumberLookup = new Map<string, number>([
+  ...numberToCharLookup.map((char, i) => [char, i] as const),
+  ["o", 0],
+  ["i", 1],
+  ["l", 1],
+]);
+
+export function encodeBase32(bytes: Uint8Array): string {
+  let result = "";
+  let bits = 0;
+  let value = 0;
+
+  for (const byte of bytes) {
+    value = (value << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      result += numberToCharLookup[(value >>> bits) & 0x1f];
+    }
+  }
+  invariant(bits === 3, "expected three leftover bits");
+  result += numberToCharLookup[(value << (5 - bits)) & 0x1f];
+  return result;
+}
+
+export function decodeBase32(str: string): Uint8Array {
+  const result = new Uint8Array(Math.floor((str.length * 5) / 8));
+  let bits = 0;
+  let value = 0;
+  let index = 0;
+
+  for (const char of str) {
+    const v = charToNumberLookup.get(char.toLowerCase());
+    invariant(v !== undefined, "invalid base32");
+    value = (value << 5) | v;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      result[index++] = (value >>> bits) & 0xff;
+    }
+  }
+  return result;
+}

package/src/id.test.ts

@@ -0,0 +1,124 @@
+import { expect, describe, it } from "vitest";
+import { createId } from "./id.js";
+
+describe("id", () => {
+  it("roundtrip", () => {
+    const fixed = new Date("2026-05-28T12:00:00Z");
+    const usr = createId("usr", { now: () => fixed });
+    const id = usr.generate();
+    expect(usr.extractTimestamp(id)).toEqual(fixed);
+  });
+
+  it("deterministic snapshot", () => {
+    const usr = createId("usr", {
+      now: () => new Date(0),
+      rng: (n) => new Uint8Array(n),
+    });
+    expect(usr.generate()).toBe("usr_" + "0".repeat(26)); // adjust to actual
+  });
+
+  it("extracts ms=0 (epoch boundary)", () => {
+    const usr = createId("usr", {
+      now: () => new Date(0),
+      rng: (n) => new Uint8Array(n),
+    });
+    expect(usr.extractTimestamp(usr.generate())).toEqual(new Date(0));
+  });
+
+  it("extracts ms at the 48-bit boundary", () => {
+    const maxMs = 2 ** 48 - 1;
+    const usr = createId("usr", {
+      now: () => new Date(maxMs),
+      rng: (n) => new Uint8Array(n),
+    });
+    expect(usr.extractTimestamp(usr.generate())).toEqual(new Date(maxMs));
+  });
+
+  it("rejects timestamps that overflow 48 bits", () => {
+    const usr = createId("usr", {
+      now: () => new Date(2 ** 48),
+      rng: (n) => new Uint8Array(n),
+    });
+    expect(() => usr.generate()).toThrow();
+  });
+
+  it("rejects pre-epoch timestamps", () => {
+    const usr = createId("usr", {
+      now: () => new Date(-1),
+      rng: (n) => new Uint8Array(n),
+    });
+    expect(() => usr.generate()).toThrow();
+  });
+
+  it("handles maximal random bytes", () => {
+    const usr = createId("usr", {
+      now: () => new Date(0),
+      rng: (n) => new Uint8Array(n).fill(0xff),
+    });
+    const id = usr.generate();
+    expect(usr.is(id)).toBe(true);
+    expect(usr.extractTimestamp(id)).toEqual(new Date(0));
+  });
+
+  it("is() accepts only canonical form", () => {
+    const usr = createId("usr");
+    expect(usr.is("usr_01h7b3k9rqxn1cw3p9r8t2sgkz")).toBe(true);
+    expect(usr.is("USR_01H7B3K9RQXN1CW3P9R8T2SGKZ")).toBe(false); // uppercase
+    expect(usr.is("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toBe(false); // contains o/i/l aliases
+  });
+
+  it("parse() normalises lenient input to canonical form", () => {
+    const usr = createId("usr");
+    expect(usr.parse("USR_01H7B3K9rqxn4cw3p9r8t2sgkz")).toEqual("usr_01h7b3k9rqxn4cw3p9r8t2sgkz");
+    expect(usr.parse("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual("usr_01h7b3k9rqxn1cw3p9r8t2sgkz");
+  });
+
+  it("safeParse() returns canonical form on success", () => {
+    const usr = createId("usr");
+    expect(usr.safeParse("usr_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual({
+      ok: true,
+      id: "usr_01h7b3k9rqxn1cw3p9r8t2sgkz",
+    });
+  });
+
+  it("safeParse() fails on bad input", () => {
+    const usr = createId("usr");
+    expect(usr.safeParse(null)).toEqual({ ok: false, error: "not_string" });
+    expect(usr.safeParse("org_Olh7b3k9rqxnIcw3p9r8t2sgkz")).toEqual({
+      ok: false,
+      error: "invalid_prefix",
+    });
+    expect(usr.safeParse("usr_01h7b3k9rqxn1cw3p9r8t2sgk!")).toEqual({
+      ok: false,
+      error: "invalid_base32",
+    });
+  });
+
+  it("cross-brand rejection", () => {
+    const org = createId("org");
+    const usr = createId("usr");
+    const orgId = org.generate();
+    expect(usr.is(orgId)).toBe(false);
+    expect(() => usr.parse(orgId)).toThrow();
+  });
+
+  it("brands containing o/i/l", () => {
+    const log = createId("log");
+    const logId = log.generate();
+    expect(log.is(logId)).toBe(true);
+  });
+
+  it("is() does not accept malformed inputs", () => {
+    const usr = createId("usr");
+    expect(usr.is(null)).toBe(false);
+    expect(usr.is("usr_")).toBe(false);
+    expect(usr.is("usr_!!!")).toBe(false);
+    expect(usr.is("usr_" + "a".repeat(25))).toBe(false); // wrong length
+  });
+
+  it("fails if brand is not exactly three a-z characters", () => {
+    expect(() => createId("a")).toThrow();
+    expect(() => createId("aaaa")).toThrow();
+    expect(() => createId("!@?")).toThrow();
+  });
+});

package/src/id.ts

@@ -0,0 +1,133 @@
+import { alphabet, decodeBase32, encodeBase32 } from "./base32.js";
+import { invariant } from "./invariant.js";
+
+export type Options = {
+  now: () => Date;
+  rng: (bytes: number) => Uint8Array;
+};
+
+const defaultOptions: Options = {
+  now: () => new Date(),
+  rng: (bytes: number) => crypto.getRandomValues(new Uint8Array(bytes)),
+};
+
+export type Prefix<Brand extends string> = `${Brand}_`;
+
+export type Id<Brand extends string> = `${Prefix<Brand>}${string}` & {
+  readonly __brand: Brand;
+};
+
+export type ParseError = "not_string" | "invalid_prefix" | "invalid_base32";
+
+export type ParseResult<Brand extends string> =
+  | { ok: true; id: Id<Brand> }
+  | { ok: false; error: ParseError };
+
+export type Codec<Brand extends string> = {
+  generate(): Id<Brand>;
+  is(value: unknown): value is Id<Brand>;
+  parse(value: unknown): Id<Brand>;
+  safeParse(value: unknown): ParseResult<Brand>;
+  extractTimestamp(id: Id<Brand>): Date;
+};
+
+const timestampByteLength = 6;
+const randomByteLength = 10;
+const totalByteLength = timestampByteLength + randomByteLength;
+const base32Length = Math.ceil((totalByteLength * 8) / 5);
+const replacePattern = /[ilo]/gi;
+const replaceMap = { o: "0", i: "1", l: "1" } as const;
+const replacer = (match: string) => {
+  invariant(match === "o" || match === "i" || match === "l", "invalid match");
+  return replaceMap[match];
+};
+
+const base32Pattern = new RegExp(`^[${alphabet}]{${base32Length}}$`);
+const brandPattern = /^[a-z]{3}$/;
+
+export function createId<Brand extends string>(
+  brand: Brand,
+  opts: Partial<Options> = {},
+): Codec<Brand> {
+  invariant(brandPattern.test(brand), "invalid brand, expected three lowercase a-z characters");
+
+  const options = {
+    ...defaultOptions,
+    ...opts,
+  } satisfies Options;
+
+  const prefix: Prefix<Brand> = `${brand}_`;
+
+  return {
+    generate: () => generate(prefix, options),
+    is: (value: unknown) => is(prefix, value),
+    parse: (value: unknown) => parse(prefix, value),
+    safeParse: (value: unknown) => safeParse(prefix, value),
+    extractTimestamp: (id: Id<Brand>) => extractTimestamp(prefix, id),
+  };
+}
+
+function safeParse<Brand extends string>(
+  prefix: Prefix<Brand>,
+  value: unknown,
+): ParseResult<Brand> {
+  if (typeof value !== "string") return { ok: false, error: "not_string" };
+  const lowercase = value.toLowerCase();
+  if (!lowercase.startsWith(prefix)) return { ok: false, error: "invalid_prefix" };
+
+  const base32 = lowercase.slice(prefix.length).replaceAll(replacePattern, replacer);
+
+  if (!base32Pattern.test(base32)) return { ok: false, error: "invalid_base32" };
+
+  const id = (prefix + base32) as Id<Brand>;
+  return { ok: true, id };
+}
+
+function parse<Brand extends string>(prefix: Prefix<Brand>, value: unknown): Id<Brand> {
+  const result = safeParse(prefix, value);
+  if (result.ok) return result.id;
+  throw new Error(`Invalid ID: ${result.error}`);
+}
+
+function is<Brand extends string>(prefix: Prefix<Brand>, value: unknown): value is Id<Brand> {
+  if (typeof value !== "string") return false;
+  if (!value.startsWith(prefix)) return false;
+  return base32Pattern.test(value.slice(prefix.length));
+}
+
+function encodeNumberToUint8Array(value: number, bytes: number): Uint8Array {
+  invariant(value >= 0, "value is negative");
+  invariant(value < 2 ** (bytes * 8), `value exceeds ${bytes * 8}-bit range`);
+  const result = new Uint8Array(bytes);
+  // iterate backwards to encode in big-endian
+  for (let i = bytes - 1; i >= 0; i--) {
+    // we encode via 256 as bitwise ops will coerce to 32-bit integers
+    result[i] = value % 256;
+    value = Math.floor(value / 256);
+  }
+  return result;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const result = new Uint8Array(a.length + b.length);
+  result.set(a, 0);
+  result.set(b, a.length);
+  return result;
+}
+
+function generate<Brand extends string>(prefix: Prefix<Brand>, options: Options): Id<Brand> {
+  const timestamp = encodeNumberToUint8Array(options.now().getTime(), timestampByteLength);
+  const rand = options.rng(randomByteLength);
+  return (prefix + encodeBase32(concat(timestamp, rand))) as Id<Brand>;
+}
+
+function extractTimestamp<Brand extends string>(prefix: Prefix<Brand>, id: Id<Brand>): Date {
+  const base32 = id.slice(prefix.length);
+  const bytes = decodeBase32(base32);
+  const timestampBytes = bytes.subarray(0, timestampByteLength);
+  let ms = 0;
+  for (const byte of timestampBytes) {
+    ms = ms * 256 + byte;
+  }
+  return new Date(ms);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  type Codec,
+  type Id,
+  type Options,
+  type ParseError,
+  type ParseResult,
+  createId,
+} from "./id.js";

package/src/invariant.ts

@@ -0,0 +1,3 @@
+export function invariant(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["es2024", "ESNext.Array", "ESNext.Collection", "ESNext.Iterator", "ESNext.Promise"],
+    "module": "preserve",
+    "target": "es2024",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "rewriteRelativeImportExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  dts: {
+    sourcemap: true,
+  },
+  sourcemap: true,
+  platform: "node",
+  exports: true,
+});

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: "v8",
+    },
+  },
+});