@kernhq/module-inventory 0.2.0 → 0.4.0

package/src/server/services/attachments.ts

@@ -0,0 +1,215 @@
+import type { core } from '@kernhq/contracts'
+import { KernError, type Kernel, type Tx, uuidv7 } from '@kernhq/kernel'
+import { and, asc, eq } from 'drizzle-orm'
+import type { Attachment as AttachmentModel } from '../../contract/models.js'
+import { assets, attachments, repairs } from '../schema.js'
+import type { HistoryInput, NotifyService } from './notify.js'
+
+type Row = typeof attachments.$inferSelect
+
+/** What this module copies out of core's file record, and all it copies. */
+export interface FileFacts {
+  id: string
+  name: string
+  mimeType: string | null
+  size: number | null
+}
+
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toAttachment(row: Row): AttachmentModel {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId as AttachmentModel['workspaceId'],
+    assetId: row.assetId,
+    repairId: row.repairId,
+    fileId: row.fileId,
+    name: row.name,
+    mimeType: row.mimeType,
+    size: row.size,
+    uploadedBy: row.uploadedBy,
+    createdAt: row.createdAt.toISOString(),
+  }
+}
+
+/**
+ * Files kept against an asset — receipts, warranties, manuals, a repair invoice.
+ *
+ * **A module does not upload, and this class is what that sentence means in code.** The browser
+ * sends the bytes to core's file service and is handed an id; this records that the asset has that
+ * file, with the name and size copied at attach time so a list can be drawn without asking core once
+ * per row. Nothing here streams, signs, stores or deletes a byte — `remove` detaches, because the
+ * same file may be attached elsewhere and a module has no standing to destroy another module's row.
+ *
+ * The copied name is a snapshot on purpose: renaming a file in core does not rename it here, which
+ * is the same trade every module makes when it copies a label rather than joining across a schema
+ * boundary. What it buys is a files list that is one query rather than one query plus a call per row.
+ */
+export class AttachmentService {
+  constructor(
+    private readonly kernel: Kernel,
+    private readonly notify: NotifyService,
+  ) {}
+
+  /**
+   * What core knows about these files — **called before the transaction opens, never inside one.**
+   *
+   * `kernel.call` is a request to another service over the broker, and awaiting one while holding a
+   * pooled connection is the failure `AssetService.codeFormat` documents: the pool starves under
+   * concurrent writes, and an attach fails outright whenever core is briefly away. So the router
+   * gathers the facts first and hands them to `add`, which does nothing but write.
+   *
+   * Two checks, and the first one is the one that matters: **a file has to belong to this
+   * workspace.** The id arrives in the request, so without this a member of one workspace could
+   * attach another workspace's file and read its name and size back out of the list — the module
+   * boundary does not help here, because core answers this module as a service.
+   */
+  async describe(workspaceId: string, fileIds: readonly string[]): Promise<FileFacts[]> {
+    const unique = [...new Set(fileIds)]
+    const found = await Promise.all(
+      unique.map(async (id) => {
+        const file = await this.kernel.call<core.FileObject | null>('core.files.get', { id })
+        if (!file || file.workspaceId !== workspaceId)
+          throw KernError.badRequest('That file is not one this workspace can attach.')
+        if (file.status !== 'ready') throw KernError.badRequest('That file has not finished uploading yet.')
+        return {
+          id: file.id,
+          name: file.name,
+          mimeType: file.mimeType || null,
+          size: typeof file.size === 'number' ? file.size : null,
+        }
+      }),
+    )
+    return found
+  }
+
+  /**
+   * Every file on one asset, its repairs' included, oldest first.
+   *
+   * Not paged and not filtered by repair: one asset's files are bounded by how much paperwork one
+   * item collects, and the panel groups them in the browser. That is the one case where filtering
+   * client-side is right — the list is entirely loaded — and it is the opposite of what a paged
+   * asset list may do.
+   */
+  async list(tx: Tx, workspaceId: string, assetId: string): Promise<AttachmentModel[]> {
+    const rows = await tx
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.assetId, assetId)))
+      .orderBy(asc(attachments.createdAt), asc(attachments.id))
+    return rows.map(toAttachment)
+  }
+
+  /**
+   * Record that this asset has these files.
+   *
+   * `onConflictDoNothing` on `(asset_id, file_id)`: attaching the same file to the same asset twice
+   * is not an error worth refusing — somebody pressed the button twice, or dropped the same receipt
+   * in again — and the second attempt simply adds nothing. The rows that *were* inserted come back,
+   * so the caller announces exactly what changed.
+   *
+   * An archived asset is deliberately allowed: finding the receipt for something you retired last
+   * month is a reason to file it, not a reason to be refused.
+   */
+  async add(
+    tx: Tx,
+    workspaceId: string,
+    actorId: string | null,
+    assetId: string,
+    repairId: string | null,
+    files: readonly FileFacts[],
+  ): Promise<{ rows: Row[]; activities: HistoryInput[] }> {
+    await this.requireAsset(tx, workspaceId, assetId)
+    if (repairId) await this.requireRepair(tx, workspaceId, assetId, repairId)
+    if (!files.length) return { rows: [], activities: [] }
+
+    const inserted = await tx
+      .insert(attachments)
+      .values(
+        files.map((file) => ({
+          id: uuidv7(),
+          workspaceId,
+          assetId,
+          repairId,
+          fileId: file.id,
+          name: file.name,
+          mimeType: file.mimeType,
+          size: file.size,
+          uploadedBy: actorId,
+        })),
+      )
+      .onConflictDoNothing({ target: [attachments.assetId, attachments.fileId] })
+      .returning()
+
+    /**
+     * One timeline entry per file, rather than one saying "3 files".
+     *
+     * A timeline is read to find out what happened to a thing, and "attached the purchase receipt"
+     * answers that where "attached 3 files" sends the reader looking. Attaching several at once is
+     * rare enough that the extra rows cost nothing.
+     */
+    const activities: HistoryInput[] = inserted.map((row) => ({
+      workspaceId,
+      assetId,
+      actorId,
+      action: 'attachment_added',
+      data: {
+        attachmentId: row.id,
+        name: row.name,
+        ...(row.repairId ? { repairId: row.repairId } : {}),
+      },
+    }))
+    for (const activity of activities) await this.notify.history(tx, activity)
+    return { rows: inserted, activities }
+  }
+
+  /** Detach one file. Core's copy of it is untouched — see the class docblock. */
+  async remove(
+    tx: Tx,
+    workspaceId: string,
+    actorId: string | null,
+    attachmentId: string,
+  ): Promise<{ row: Row; activity: HistoryInput }> {
+    const [row] = await tx
+      .select()
+      .from(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.id, attachmentId)))
+    if (!row) throw KernError.notFound('Attachment')
+
+    // Filtered by workspace as well as by id, like every other write in this module: `core`
+    // connects as a superuser with RLS bypassed, so the predicate in the statement is the only
+    // barrier there is, and a barrier that holds only because of what an earlier statement happened
+    // to do is not one.
+    await tx
+      .delete(attachments)
+      .where(and(eq(attachments.workspaceId, workspaceId), eq(attachments.id, attachmentId)))
+
+    const activity: HistoryInput = {
+      workspaceId,
+      assetId: row.assetId,
+      actorId,
+      action: 'attachment_removed',
+      data: { attachmentId: row.id, name: row.name },
+    }
+    await this.notify.history(tx, activity)
+    return { row, activity }
+  }
+
+  private async requireAsset(tx: Tx, workspaceId: string, assetId: string): Promise<void> {
+    const [row] = await tx
+      .select({ id: assets.id })
+      .from(assets)
+      .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+    if (!row) throw KernError.notFound('Asset')
+  }
+
+  /** A repair the file is filed under has to be one of *this* asset's, not merely one that exists. */
+  private async requireRepair(tx: Tx, workspaceId: string, assetId: string, repairId: string): Promise<void> {
+    const [row] = await tx
+      .select({ id: repairs.id })
+      .from(repairs)
+      .where(
+        and(eq(repairs.workspaceId, workspaceId), eq(repairs.id, repairId), eq(repairs.assetId, assetId)),
+      )
+    if (!row) throw KernError.notFound('Repair')
+  }
+}

package/src/server/services/audience.ts

@@ -0,0 +1,77 @@
+import type { BuiltinRole, Principal } from '@kernhq/contracts'
+import type { Kernel } from '@kernhq/kernel'
+
+/**
+ * Who to tell when the thing that happened belongs to the workspace rather than to a person.
+ *
+ * Custody notifications have an obvious recipient — the person the item was handed to. A warranty
+ * running out on a spare in a cupboard, or a repair nobody has chased, does not: it belongs to
+ * whoever looks after the register. There is no "the office manager" field, and inventing one would
+ * be a setting somebody has to fill in before the feature works at all, so the question is asked of
+ * the permission system instead: **who may actually do the thing this message is asking for.**
+ *
+ * A warranty notice asks somebody to renew or replace, which is `inventory.asset.manage`. An overdue
+ * repair asks somebody to chase the vendor, which is `inventory.repair.manage`. Somebody leaving
+ * with a laptop asks somebody to take it back, which is `inventory.custody.manage`. Each message
+ * names the key it needs rather than settling for "the admins", because a workspace that gave its
+ * office manager a custom role did that on purpose.
+ */
+
+/** Most senior first, so the cap below keeps the people most likely to act. */
+const ROLE_RANK: Record<BuiltinRole, number> = { owner: 3, admin: 2, member: 1, guest: 0 }
+
+/**
+ * How many people one workspace-level notification may reach.
+ *
+ * A message sent to five thousand people is not a notification, it is a mailing list nobody reads —
+ * and on a large instance every member holds `inventory.asset.manage` by default, so an uncapped
+ * audience would be exactly that. Twenty is well past any real "who looks after the register" group
+ * and small enough that the check below stays a handful of calls rather than one per seat.
+ *
+ * The cap is applied **after** sorting by role, so the people it keeps are the senior ones rather
+ * than whichever rows the database happened to return first.
+ */
+const RECIPIENT_CAP = 20
+
+interface Member {
+  userId: string
+  role: BuiltinRole
+}
+
+/**
+ * The members of a workspace who genuinely hold a permission.
+ *
+ * Genuinely, not "hold the role it defaults to": `kernel.authz.can` reads custom roles and scope
+ * bindings as well as the built-in defaults, so a workspace that took `inventory.repair.manage` away
+ * from `member` and gave it to one custom role is answered correctly. Guessing from the role would
+ * have been one local call instead of a handful, and would have quietly told the wrong people.
+ *
+ * Every failure here is swallowed: this decides an audience for a best-effort notification, and a
+ * member whose principal core cannot produce right now is one fewer recipient, not a reason for a
+ * nightly sweep to stop half-way through a workspace.
+ */
+export async function membersWithPermission(
+  kernel: Kernel,
+  workspaceId: string,
+  permission: string,
+): Promise<string[]> {
+  const members = await kernel
+    .call<Member[]>('core.workspaces.members', { workspaceId })
+    .catch(() => [] as Member[])
+
+  const ordered = [...members].sort((a, b) => (ROLE_RANK[b.role] ?? 0) - (ROLE_RANK[a.role] ?? 0))
+
+  const allowed: string[] = []
+  for (const member of ordered) {
+    if (allowed.length >= RECIPIENT_CAP) break
+    const principal = await kernel
+      .call<Principal | null>('core.users.principal', { userId: member.userId })
+      .catch(() => null)
+    if (!principal) continue
+    const can = await kernel.authz
+      .can(principal, permission, { kind: 'workspace', workspaceId })
+      .catch(() => false)
+    if (can) allowed.push(member.userId)
+  }
+  return allowed
+}

package/src/server/services/categories.ts

@@ -0,0 +1,337 @@
+import { KernError, type Tx, uuidv7 } from '@kernhq/kernel'
+import { and, asc, count, eq, isNull, sql } from 'drizzle-orm'
+import { type Category as CategoryModel, MAX_LIVE_CATEGORIES } from '../../contract/models.js'
+import { categories } from '../schema.js'
+import { violated } from './db-errors.js'
+
+type Row = typeof categories.$inferSelect
+
+/** The unique index `0000_init.sql` put on (workspace_id, name). */
+const NAME_TAKEN = 'inventory_categories_ws_name_uq'
+
+/** What `reorder` returns: the live sequence as it now stands, and which rows actually moved. */
+export interface Reordered {
+  rows: Row[]
+  /** Only the ids whose `order` changed — a change event for a row that did not move is a lie. */
+  moved: string[]
+}
+
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toCategory(row: Row): CategoryModel {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId as CategoryModel['workspaceId'],
+    name: row.name,
+    order: row.order,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+    archivedAt: row.archivedAt?.toISOString() ?? null,
+  }
+}
+
+/**
+ * How a workspace groups what it owns.
+ *
+ * Small on purpose. A category is a name and a position in a list; everything interesting about an
+ * asset belongs to the asset. The one thing here worth reading twice is that nothing deletes — see
+ * `archive` below.
+ */
+export class CategoryService {
+  /**
+   * Ordered by `order` and then by name.
+   *
+   * `order` is the sequence somebody dragged their categories into, and no two **live** categories
+   * share a number: `inventory_categories_ws_order_live_uq` is what makes that true rather than
+   * intended. So for the live set the tiebreak never fires.
+   *
+   * It stays because `list` also reads the archived rows, and those are outside the index: an
+   * archived category keeps the number it had when it left, and the very next reorder renumbers a
+   * live row onto it. A duplicate must sort the same way twice, and a name is the only column a
+   * person could predict.
+   */
+  async list(tx: Tx, workspaceId: string, includeArchived: boolean): Promise<CategoryModel[]> {
+    const filters = [eq(categories.workspaceId, workspaceId)]
+    if (!includeArchived) filters.push(isNull(categories.archivedAt))
+    const rows = await tx
+      .select()
+      .from(categories)
+      .where(and(...filters))
+      .orderBy(asc(categories.order), asc(categories.name))
+    return rows.map(toCategory)
+  }
+
+  async get(tx: Tx, workspaceId: string, categoryId: string): Promise<Row> {
+    const [row] = await tx
+      .select()
+      .from(categories)
+      .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+    if (!row) throw KernError.notFound('Category')
+    return row
+  }
+
+  /**
+   * A new category joins the **end** of the sequence, and a duplicate name is a `CONFLICT` with the
+   * name in it, never a 500.
+   *
+   * The unique index is what actually decides the name — checking first and inserting after is a
+   * race that two people adding "Laptops" at once will find — so the check is the insert, and the
+   * driver's 23505 is translated into a sentence rather than shown as "Failed query: insert into
+   * mod_inventory.categories …".
+   *
+   * The position is decided the same way, in the statement rather than around it. It used to be an
+   * optional number the caller passed and defaulted to 0, so every category anybody added landed at
+   * the *front*, tied with whatever was already there, and the list resolved the tie by name — a
+   * new category appearing in the middle of a sequence somebody had arranged by hand.
+   *
+   * **The subquery is not what makes the number unique — the lock above it is.** This used to say
+   * that a subquery inside the insert stopped two creates in flight from taking the same maximum,
+   * and that is false: under READ COMMITTED each statement takes its own snapshot, so both read a
+   * list without the other's row in it and both appended to the same place. `lockAppends` is what
+   * serialises them, and `inventory_categories_ws_order_live_uq` is what refuses the pair if
+   * anything ever reaches the table around it.
+   */
+  async create(tx: Tx, workspaceId: string, name: string): Promise<Row> {
+    await CategoryService.lockAppends(tx, workspaceId)
+    await CategoryService.roomForOneMore(tx, workspaceId)
+    try {
+      const [row] = await tx
+        .insert(categories)
+        .values({ id: uuidv7(), workspaceId, name, order: CategoryService.appended(workspaceId) })
+        .returning()
+      return row!
+    } catch (err) {
+      throw CategoryService.nameTaken(err, name)
+    }
+  }
+
+  /** A rename, and nothing else — the sequence is `reorder`'s to write. */
+  async update(tx: Tx, workspaceId: string, categoryId: string, patch: { name?: string }): Promise<Row> {
+    const previous = await this.get(tx, workspaceId, categoryId)
+    // `undefined` means "not mentioned". The column is not nullable, so there is no "clear it" here
+    // and no reason for the `null`-versus-`undefined` care `assets.update` needs.
+    const values = {
+      name: patch.name ?? previous.name,
+      updatedAt: new Date(),
+    }
+    try {
+      const [row] = await tx
+        .update(categories)
+        .set(values)
+        .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+        .returning()
+      return row!
+    } catch (err) {
+      throw CategoryService.nameTaken(err, values.name)
+    }
+  }
+
+  /**
+   * Archive and restore, which are one procedure because they are one column.
+   *
+   * **Nothing here deletes, and that is the decision this file exists to record.**
+   * `assets.category_id` carries no foreign key — a module keeps its ids plain — so a delete would
+   * leave every asset filed under this category pointing at a row that is not there: a blank column
+   * on the row, a picker that cannot explain what the asset used to be, and an `asset_history`
+   * entry saying "category changed to <nothing>". None of it recoverable, all of it caused by a
+   * settings screen. An archived category disappears from every picker and every filter and leaves
+   * each asset able to say what it is.
+   *
+   * **A restore appends**, for the reason `create` appends. The row kept the position it had when
+   * it left, and every live category has been renumbered since — so putting it back where its old
+   * number points lands it in the middle of somebody's arrangement, tied with whatever is there
+   * now. The end of the list is the one place a person can find it again. Archiving leaves the
+   * number alone: it is out of every list that reads it, and it is about to be overwritten anyway.
+   *
+   * A restore appends, so it races exactly as `create` does and is serialised the same way — and it
+   * is the one place other than `create` where the live set grows, so it is the other place the
+   * limit is enforced. Archiving needs neither: it takes a row out of the live set, and out of the
+   * partial index with it.
+   */
+  async archive(tx: Tx, workspaceId: string, categoryId: string, archived: boolean): Promise<Row> {
+    if (!archived) {
+      await CategoryService.lockAppends(tx, workspaceId)
+      await CategoryService.roomForOneMore(tx, workspaceId)
+    }
+    const [row] = await tx
+      .update(categories)
+      .set({
+        archivedAt: archived ? new Date() : null,
+        ...(archived ? {} : { order: CategoryService.appended(workspaceId) }),
+        updatedAt: new Date(),
+      })
+      .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+      .returning()
+    if (!row) throw KernError.notFound('Category')
+    return row
+  }
+
+  /**
+   * The sequence, rewritten from the ids somebody put it in — the only thing that writes `order`.
+   *
+   * Three refusals before a single row is touched, and all three are the same idea: this call
+   * describes the whole live list, so a list that does not match the workspace is not a partial
+   * instruction to be completed, it is an ordering of something else.
+   *
+   *   - **an id twice** — arithmetic that cannot be carried out, `BAD_REQUEST`;
+   *   - **an id that is not this workspace's** — `NOT_FOUND`, the answer `update` and `archive`
+   *     already give for one, and the answer that does not confirm the row exists elsewhere;
+   *   - **a live category the list does not name, or an archived one it does** — somebody added,
+   *     archived or restored a category while this page was open. Renumbering what was named would
+   *     put the missing one wherever its stale number happened to land, silently. `CONFLICT` with
+   *     `inventory.category.order_stale`, which the client turns into "reload and try again".
+   *
+   * All of it inside one transaction, opened by the router, so a refusal writes nothing and a
+   * renumbering is never half-applied. The `for update` is what makes two reorders arriving at once
+   * queue rather than interleave — without it both read the same list, both pass the check, and the
+   * writes of one land between the writes of the other, which is how a sequence ends up being
+   * neither of the two orders anybody asked for. Locking in id order is what stops two of them
+   * taking the same rows in opposite orders and deadlocking.
+   */
+  async reorder(tx: Tx, workspaceId: string, categoryIds: string[]): Promise<Reordered> {
+    const named = new Set(categoryIds)
+    if (named.size !== categoryIds.length)
+      throw KernError.badRequest('That list of categories names the same one more than once.')
+
+    const current = await tx
+      .select()
+      .from(categories)
+      .where(eq(categories.workspaceId, workspaceId))
+      .orderBy(asc(categories.id))
+      .for('update')
+    const known = new Map(current.map((row) => [row.id, row]))
+
+    if (categoryIds.some((id) => !known.has(id))) throw KernError.notFound('Category')
+    const live = current.filter((row) => !row.archivedAt)
+    if (live.some((row) => !named.has(row.id)) || categoryIds.some((id) => known.get(id)?.archivedAt))
+      throw KernError.conflict(
+        'The categories changed while this list was open, so this order was not saved. Reload the list and arrange it again.',
+        'inventory.category.order_stale',
+      )
+
+    // Only the rows that actually move are touched — a workspace has tens of categories, they are
+    // already locked, and a change event for a row whose position did not change would tell every
+    // screen in the workspace about a write that did not happen. `moved` is settled here, before a
+    // single write, so it stays the honest list whatever the two passes below do.
+    const now = new Date()
+    const going = categoryIds
+      .map((id, index) => ({ id, index }))
+      .filter(({ id, index }) => known.get(id)?.order !== index)
+    const moved = going.map(({ id }) => id)
+
+    /**
+     * Parked out of the way first, and only then put down where they belong.
+     *
+     * `inventory_categories_ws_order_live_uq` is a plain unique index, and Postgres checks one of
+     * those row by row rather than at the end of the statement. There is no deferrable form to reach
+     * for either: a unique *constraint* can be deferred and cannot be partial, and this one has to be
+     * partial. So the single-pass loop writes a collision the moment two rows swap — putting the
+     * first on 1 while the second still holds 1 — and a swap is the commonest reorder there is.
+     *
+     * `park` sits above both the highest number any row in this workspace holds **and** the last
+     * place in the new sequence. That is what makes the two passes safe: the parked values are
+     * distinct from one another and from every row staying put, and the `0…n-1` the second pass
+     * writes into is empty, because every live row that could have been sitting there is either
+     * parked or already on the number it is being given.
+     *
+     * Only the rows that actually move are written, so a reorder that shifts one row does not stamp
+     * `updated_at` across the whole list — and `updated_at` is left off the parking pass, which is
+     * bookkeeping rather than a change anybody made.
+     */
+    if (going.length > 0) {
+      const park = Math.max(...current.map((row) => row.order), categoryIds.length - 1) + 1
+      for (const [offset, { id }] of going.entries()) {
+        await tx
+          .update(categories)
+          .set({ order: park + offset })
+          .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, id)))
+      }
+      for (const { id, index } of going) {
+        await tx
+          .update(categories)
+          .set({ order: index, updatedAt: now })
+          .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, id)))
+      }
+    }
+
+    const rows = await tx
+      .select()
+      .from(categories)
+      .where(and(eq(categories.workspaceId, workspaceId), isNull(categories.archivedAt)))
+      .orderBy(asc(categories.order), asc(categories.name))
+    return { rows, moved }
+  }
+
+  /**
+   * One past the highest position this workspace has used, archived rows counted.
+   *
+   * Archived rows count because one of them can be restored, and a restored category landing on a
+   * live one's number is the tie this whole change exists to remove.
+   *
+   * **Only correct under `lockAppends`.** A subquery inside the write saves a round trip and settles
+   * nothing about concurrency: under READ COMMITTED it is evaluated against the snapshot its own
+   * statement started with, so two transactions appending at the same instant read the same maximum
+   * and take the same number. That is the defect `0008` exists for.
+   */
+  private static appended(workspaceId: string) {
+    return sql<number>`(select coalesce(max(${categories.order}), -1) + 1 from ${categories} where ${categories.workspaceId} = ${workspaceId})`
+  }
+
+  /**
+   * Hold the right to append to this workspace's list until the transaction ends.
+   *
+   * An advisory lock rather than `select … for update`, because the thing being protected is the
+   * *next* number rather than any row that exists: a workspace with no categories at all has no row
+   * to lock, and two creates against it would still collide. Taken per workspace, so two workspaces
+   * adding a category at the same moment never wait for each other.
+   *
+   * The first key is a constant for this list, so another module taking an advisory lock on the same
+   * workspace does not queue behind this one by accident.
+   *
+   * It cannot deadlock against `reorder`, which takes row locks and never asks for this one — so
+   * there is no pair of waits pointing at each other.
+   */
+  private static async lockAppends(tx: Tx, workspaceId: string): Promise<void> {
+    await tx.execute(
+      sql`select pg_advisory_xact_lock(hashtext('mod_inventory.categories.order'), hashtext(${workspaceId}))`,
+    )
+  }
+
+  /**
+   * Refuse the one that would take a workspace past `MAX_LIVE_CATEGORIES`, and say so.
+   *
+   * The number exists because `categories.reorder` is handed every live category at once and that
+   * array needs a bound. Leaving the bound only on the array is a silent ceiling: a workspace could
+   * pass it one category at a time and then discover that the only procedure that can order them is
+   * the one it can no longer call. Enforced here, the array can always name every live category a
+   * workspace is allowed to have.
+   *
+   * **Live rows, not every row ever made**, so that archiving one frees a place — which is what the
+   * refusal tells the reader to do, and the advice has to be true.
+   */
+  private static async roomForOneMore(tx: Tx, workspaceId: string): Promise<void> {
+    const [row] = await tx
+      .select({ n: count() })
+      .from(categories)
+      .where(and(eq(categories.workspaceId, workspaceId), isNull(categories.archivedAt)))
+    if ((row?.n ?? 0) < MAX_LIVE_CATEGORIES) return
+    throw KernError.conflict(
+      `This workspace already has ${MAX_LIVE_CATEGORIES} categories, which is as many as Inventory keeps in one order. Archive one it no longer uses to make room.`,
+      'inventory.category.limit_reached',
+    )
+  }
+
+  /**
+   * The unique index refused it, or something else did and must not be disguised.
+   *
+   * Rethrowing the original for anything that is not this constraint matters: turning every failed
+   * insert into "that name is taken" would hide a real fault behind a sentence a person would act
+   * on by renaming something, for ever.
+   */
+  private static nameTaken(err: unknown, name: string): unknown {
+    if (!violated(err, NAME_TAKEN)) return err
+    return KernError.conflict(
+      `This workspace already has a category called “${name}”.`,
+      'inventory.category.name_taken',
+    )
+  }
+}