@kernhq/module-inventory 0.2.0 → 0.4.0

package/src/server/schema.ts

@@ -1,8 +1,10 @@
 import { moduleSchema } from '@kernhq/kernel'
 import { sql } from 'drizzle-orm'
 import {
+  bigint,
   boolean,
   char,
+  check,
   date,
   index,
   integer,
@@ -33,6 +35,35 @@ const ts = (name: string) => timestamp(name, { withTimezone: true, mode: 'date'
 const created = () => ts('created_at').notNull().defaultNow()
 const updated = () => ts('updated_at').notNull().defaultNow()
 
+/**
+ * Workspaces this module is switched on in, so scheduled work can find them.
+ *
+ * A cron handler starts with no workspace: it is woken by a clock, not by a request, so there is
+ * nothing to derive a tenant from and no `withWorkspace` it could already be inside. Core knows the
+ * answer and would give it (`core.workspaces.list`), but asking it every tick makes the sweeps fail
+ * whenever core is briefly away — for a job whose whole point is to run unattended overnight. So the
+ * module keeps the one fact it needs: an id, written when the module is switched on for a workspace
+ * and when a workspace is created. `module-tracker` keeps the same table for the same reason.
+ *
+ * **It carries `workspace_id`, so it is a tenant table and has a policy like every other** — and the
+ * one reader that cannot honour that policy is the enumeration itself, because `app.workspace_id` is
+ * unset in a job by definition. That was left resting on "the connection is the schema's owner, and
+ * an owner bypasses RLS", which is **false here**: every table in this schema carries `force row
+ * level security`, and forcing it subjects the owner to the policies too. So `select workspace_id
+ * from workspaces` with no workspace bound answered zero rows — not an error, not a warning, simply
+ * nothing to sweep, every night, for ever.
+ *
+ * `0006_workspace_registry_read.sql` is the fix and it is scoped as narrowly as the problem: one
+ * extra `for select` policy, on this table only, admitting a session that has **no** workspace bound.
+ * A request-bound session still sees exactly its own row, and this table holds nothing but workspace
+ * ids anyway — it is the module's own bookkeeping, not tenant data anybody reads. Added in `0004`,
+ * because 0.2.0 is published.
+ */
+export const workspaces = schema.table('workspaces', {
+  workspaceId: uuid('workspace_id').primaryKey(),
+  createdAt: created(),
+})
+
 export const counters = schema.table(
   'counters',
   /** Per-workspace sequence sources (`asset_code`). Narrow on purpose: one row per key. */
@@ -59,12 +90,38 @@ export const categories = schema.table(
     workspaceId: ws(),
     name: text('name').notNull(),
     order: integer('order').notNull().default(0),
+    /**
+     * Archived rather than deleted, and the reason is `assets.category_id`.
+     *
+     * There is no foreign key — a module keeps its joins inside its own schema and its ids plain —
+     * so deleting a row here would leave every asset filed under it pointing at nothing. The
+     * category column on the row would go blank and the timeline entry that says "category changed
+     * to Laptops" would lose the word "Laptops": data destroyed by a settings screen, silently, and
+     * with no way back. Archiving takes the category out of every picker and every filter and
+     * leaves each asset able to say what it is.
+     *
+     * Added in `0002`, because 0.2.0 is published.
+     */
+    archivedAt: ts('archived_at'),
     createdAt: created(),
     updatedAt: updated(),
   },
   (t) => [
+    // Unique across archived rows too: two categories called "Laptops", one of them archived, is
+    // two rows a picker cannot tell apart the moment somebody restores the second.
     uniqueIndex('inventory_categories_ws_name_uq').on(t.workspaceId, t.name),
     index('inventory_categories_ws_idx').on(t.workspaceId, t.order),
+    /**
+     * One live category per place, which the contract claims and nothing enforced until `0008`.
+     *
+     * **Partial, over the live rows only.** An archived category keeps the number it had when it was
+     * archived and the next reorder renumbers a live row onto it — a collision nobody can see, since
+     * an archived category is in no picker, no filter and no sequence. A total unique index would
+     * refuse that entirely correct pair.
+     */
+    uniqueIndex('inventory_categories_ws_order_live_uq')
+      .on(t.workspaceId, t.order)
+      .where(sql`${t.archivedAt} is null`),
   ],
 )
 
@@ -91,6 +148,18 @@ export const assets = schema.table(
     priceMinor: integer('price_minor'),
     currency: char('currency', { length: 3 }),
     warrantyUntil: date('warranty_until'),
+    /**
+     * When the warranty sweep last told somebody this one is about to run out.
+     *
+     * The idempotency row `kern-service` asks scheduled work for, as a column. A warranty falls
+     * inside the notice window for every one of the thirty days before it expires, so a sweep with
+     * no marker sends the same notice thirty times — and `groupKey` collapses that in the
+     * notification centre while still sending thirty emails. Cleared by `assets.update` whenever
+     * `warranty_until` itself moves, so extending a warranty earns a fresh notice at the new date.
+     *
+     * Nullable and added in `0004`, so the 0.2.0 image reads the table straight past it.
+     */
+    warrantyNotifiedAt: ts('warranty_notified_at'),
     photoFileId: uuid('photo_file_id'),
     /** Values for this workspace's own `field_defs`, keyed by their `key`. */
     custom: jsonb('custom').$type<Record<string, unknown>>().notNull().default({}),
@@ -178,12 +247,52 @@ export const assetHistory = schema.table(
     workspaceId: ws(),
     assetId: uuid('asset_id').notNull(),
     actorId: uuid('actor_id'),
-    action: text('action').notNull(), // created | updated | transferred | returned | repair_logged | repair_completed | attachment_added | retired | restored
+    action: text('action').notNull(), // created | updated | assigned | transferred | returned | repair_logged | repair_completed | attachment_added | retired | restored
     changes: jsonb('changes').$type<{ field: string; from: unknown; to: unknown }[]>(),
     data: jsonb('data'),
     occurredAt: created(),
+    /**
+     * The order these entries actually happened in — a sequence, not a clock and not the id.
+     *
+     * **A uuidv7 is only ordered to the millisecond.** The kernel's `uuidv7()` puts the clock in
+     * bytes 0-5 and fills bytes 6-15 from `randomUUID()` with no intra-millisecond counter, so two
+     * entries written in the same millisecond sort by ten random bytes. That is *stable* for a
+     * given set of rows, which is why keyset paging never dropped or repeated one and why the
+     * defect hid for so long — what it produced instead was a timeline rendering "Bruno removed the
+     * file" above "Bruno added the file". A register's whole value is that it says what happened in
+     * the order it happened.
+     *
+     * `occurred_at` cannot stand in for it either: it defaults to `now()`, which is the
+     * *transaction* timestamp, so a create and its first history row share it exactly.
+     *
+     * A sequence is exact rather than probabilistic — `nextval` is strictly increasing whatever the
+     * clock does — and it is the one ordering key a module owns outright. Filled by the column
+     * default, so nothing in the service has to remember it and the previous image's inserts get
+     * one too. Added in `0007`.
+     */
+    seq: bigint('seq', { mode: 'number' }).notNull().default(sql`nextval('mod_inventory.asset_history_seq')`),
   },
-  (t) => [index('inventory_asset_history_asset_idx').on(t.workspaceId, t.assetId, t.occurredAt)],
+  (t) => [
+    index('inventory_asset_history_asset_idx').on(t.workspaceId, t.assetId, t.occurredAt),
+    /**
+     * Superseded by the index below, and left here on purpose.
+     *
+     * The timeline used to be keyset-paged by **id**, on the reasoning `assets.list` still gives for
+     * `sort: 'recent'` — an id is uuidv7, so it carries the clock, and it is unique where
+     * `occurred_at` is not. Unique it is; ordered it is only to the millisecond. `seq` replaced it.
+     *
+     * Dropping this is a schema change and a migration here only adds, so it goes one release from
+     * now rather than in the one that stopped reading it. Added in `0002`.
+     */
+    index('inventory_asset_history_ws_asset_row_idx').on(t.workspaceId, t.assetId, t.id),
+    /**
+     * What `assets.history` pages on: one asset's entries, newest first, bounded by `seq`.
+     *
+     * Unique, because the sequence makes it so and saying so lets Postgres stop at the first match
+     * for a cursor. Added in `0007`.
+     */
+    uniqueIndex('inventory_asset_history_ws_asset_seq_uq').on(t.workspaceId, t.assetId, t.seq),
+  ],
 )
 
 export const repairs = schema.table(
@@ -200,11 +309,66 @@ export const repairs = schema.table(
     sentOn: date('sent_on').notNull(),
     /** Null while the item is still away — also how `under_repair` is derived. */
     returnedOn: date('returned_on'),
+    /**
+     * When the overdue sweep last said this one has been away too long.
+     *
+     * Same job as `assets.warranty_notified_at` and for the same reason: a repair that passed the
+     * threshold yesterday has passed it again today, so a sweep with no marker chases the same
+     * vendor every morning until the item comes back. Cleared by `repairs.update` when `sent_on`
+     * moves, because that is the date the threshold is measured from.
+     *
+     * Nullable and added in `0004`, so the 0.2.0 image reads the table straight past it.
+     */
+    overdueNotifiedAt: ts('overdue_notified_at'),
     createdBy: uuid('created_by'),
     createdAt: created(),
     updatedAt: updated(),
   },
-  (t) => [index('inventory_repairs_ws_asset_idx').on(t.workspaceId, t.assetId, t.sentOn)],
+  (t) => [
+    index('inventory_repairs_ws_asset_idx').on(t.workspaceId, t.assetId, t.sentOn),
+    /**
+     * What the overdue sweep reads: one workspace's still-open repairs, oldest first.
+     *
+     * The index above starts (workspace_id, asset_id, sent_on) and cannot answer "every open repair
+     * in this workspace sent before a date" without visiting every asset; `inventory_repairs_one_
+     * open_uq` is partial on the right predicate but keyed by `asset_id`, so it cannot be scoped to
+     * a workspace either. Added in `0004`.
+     */
+    index('inventory_repairs_ws_open_idx').on(t.workspaceId, t.sentOn).where(sql`returned_on is null`),
+    /**
+     * One open repair per asset, decided by the database rather than by the service.
+     *
+     * Custody leans on a GiST exclusion constraint for the same reason and this is the cheaper
+     * version of it: a repair has no range to overlap, only a flag, so a partial unique index says
+     * exactly the same thing. Two people pressing *Send for repair* on the same laptop in the same
+     * instant both read "it is here", both insert, and Postgres refuses one of them — where a
+     * `select … for update` would serialise them into two open repairs, which is a worse answer
+     * wearing the clothes of a safer one. `RepairService` turns the 23505 into a sentence.
+     *
+     * Not scoped by `workspace_id`: an asset id belongs to exactly one workspace, and adding the
+     * column would let the same asset be open in two of them if an id ever leaked across.
+     *
+     * Added in `0003`, because 0.2.0 is published.
+     */
+    uniqueIndex('inventory_repairs_one_open_uq').on(t.assetId).where(sql`returned_on is null`),
+    /**
+     * A repair cannot come back before it was sent.
+     *
+     * Two dates a person types, and nothing but arithmetic decides whether the pair means anything:
+     * stored the wrong way round, every "how long was it away" answer is negative and the overdue
+     * sweep measures from a date in the future. `repairs.complete` refused it from the start;
+     * `repairs.update` did not, and could move `sent_on` past the `returned_on` of a repair that had
+     * already come back. The service checks first so a person gets a sentence, and this is what
+     * makes the rule true of the table rather than of the code paths somebody remembered.
+     *
+     * Added in `0005` as `not valid`: the constraint is enforced on every insert and update from
+     * that moment, and existing rows are not scanned. That is deliberate — a module's migrations
+     * are the first thing the kernel runs, so a validating constraint that met one bad row left
+     * over from this defect would not degrade repairs, it would stop the whole host service
+     * booting. `RepairService` translates the resulting 23514 into a sentence.
+     */
+    check('inventory_repairs_returned_after_sent', sql`returned_on is null or returned_on >= sent_on`),
+  ],
 )
 
 /** Bytes live in core object storage via `uploadFile`; this only records that an asset has one. */
@@ -235,6 +399,10 @@ export const TENANT_TABLES = [
   // and therefore out of `0001_rls.sql` — because it holds no asset data, which is not the rule
   // the file states at the top. Tracker's structurally identical `issue_counters` is covered.
   'counters',
+  // Holds nothing but tenant ids, and is still a tenant table: the rule this list encodes is "has a
+  // `workspace_id` column", not "holds asset data". `module-tracker`'s equivalent is deliberately
+  // unpolicied and that is the one shape of exception this module does not make.
+  'workspaces',
   'categories',
   'assets',
   'field_defs',

package/src/server/services/assets.ts

@@ -1,15 +1,18 @@
 import { KernError, type Kernel, type Tx, uuidv7 } from '@kernhq/kernel'
-import { and, asc, desc, eq, ilike, isNull, or, sql } from 'drizzle-orm'
+import { and, asc, desc, eq, ilike, isNull, lt, or, sql } from 'drizzle-orm'
 import { alias, type PgColumn } from 'drizzle-orm/pg-core'
 import type {
   AssetCreateInput,
+  AssetHistoryEntry,
   Asset as AssetModel,
   AssetPatchInput,
   AssetSort,
 } from '../../contract/models.js'
 import { InventorySettings } from '../../contract/settings.js'
-import { assets, counters } from '../schema.js'
+import { assetHistory, assets, categories, counters } from '../schema.js'
+import { decodeMark, decodeSeqMark, encodeMark, encodeSeqMark } from './cursor.js'
 import type { HistoryInput, NotifyService } from './notify.js'
+import { openRepairId } from './status.js'
 
 type Row = typeof assets.$inferSelect
 
@@ -62,52 +65,20 @@ export function toAsset(row: Row): AssetModel {
 }
 
 /**
- * A page boundary, as the client sees it: **the bookmarked row's id, and the sort it was issued
- * under**. Nothing else — in particular not the sort key itself, which is what it used to carry.
- *
- * That earlier shape (`{k: <sort key>, i: <id>}`) was wrong three separate ways, each of them
- * reachable by anyone who could type into the address bar:
- *
- *   - **It could not be trusted.** `decode` checked only that `i` was a *string*, and `i` is
- *     interpolated into `(col, id) < ($1, $2::uuid)`. `{"k":"x","i":"not-a-uuid"}` therefore
- *     reached Postgres as a 22P02 nobody caught — an unhandled 500 and an error-level log line per
- *     request, at the 600-a-minute the rate limiter allows.
- *   - **It was not bound to its sort.** A cursor issued under `sort=recent` replayed under
- *     `sort=code` compared a uuid against a code, so page two came back equal to page one and
- *     "Load more" never ended.
- *   - **It was unbounded.** `sort=name` on a 200-character Persian name encoded to 602 characters,
- *     and `Cursor` in `@kernhq/contracts` is `max(512)` — so a long enough name broke "Load more"
- *     with a validation error, in exactly the locales least likely to be tested.
- *
- * Carrying the id alone and reading the sort key back from that row in SQL answers all three: the
- * cursor is a fixed ~60 characters whatever the name, a value that is not a uuid is refused before
- * it is anywhere near the database, and a cursor whose sort disagrees with the request is refused
- * rather than quietly misread. Base64 so nothing in the product is tempted to read it — it is a
- * bookmark, not an offset, and its shape is this file's business.
+ * The wire shape of one timeline entry. Drizzle's `jsonb` columns are nullable in the row and never
+ * null in the contract — `changes: []` and `data: {}` are what "nothing to say" looks like to a
+ * screen, where `null` is one more thing every caller has to remember to handle.
  */
-interface Bookmark {
-  i: string
-  s: AssetSort
-}
-const encode = (b: Bookmark) => Buffer.from(JSON.stringify(b), 'utf8').toString('base64url')
-
-/** Cheap and total, and it runs before the value can reach a `::uuid` cast. */
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-function decode(cursor: string, sort: AssetSort): Bookmark {
-  const refuse = () => KernError.badRequest('That page marker is not one this list issued')
-  let parsed: Partial<Bookmark> | null
-  try {
-    parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as Partial<Bookmark> | null
-  } catch {
-    throw refuse()
+export function toHistoryEntry(row: typeof assetHistory.$inferSelect): AssetHistoryEntry {
+  return {
+    id: row.id,
+    assetId: row.assetId,
+    actorId: row.actorId,
+    action: row.action,
+    changes: row.changes ?? [],
+    data: (row.data as Record<string, unknown> | null) ?? {},
+    occurredAt: row.occurredAt.toISOString(),
   }
-  if (typeof parsed?.i !== 'string' || !UUID.test(parsed.i)) throw refuse()
-  // One comparison covers both a sort this list never issues and a sort it issued under a
-  // *different* request. Either way the bookmark cannot be read against the ordering asked for,
-  // and pretending otherwise is what made "Load more" loop for ever.
-  if (parsed.s !== sort) throw refuse()
-  return { i: parsed.i, s: sort }
 }
 
 /**
@@ -119,6 +90,15 @@ function decode(cursor: string, sort: AssetSort): Bookmark {
  */
 const contains = (q: string) => `%${q.replace(/[\\%_]/g, '\\$&')}%`
 
+/**
+ * The one ordering a timeline has, named rather than left as a literal.
+ *
+ * The cursor codec binds a bookmark to the sort it was issued under and refuses it under any other,
+ * so a timeline needs a name for its sort even while there is only one — and the day a second one
+ * exists, every cursor already in a browser tab is refused rather than misread.
+ */
+const HISTORY_SORT = 'recent'
+
 /** Which column an ordering sorts on, for the list itself and for the bookmarked row alike. */
 const sortKey = <T extends { id: PgColumn; name: PgColumn; code: PgColumn }>(t: T, sort: AssetSort) =>
   sort === 'name' ? t.name : sort === 'code' ? t.code : t.id
@@ -194,17 +174,30 @@ export class AssetService {
     if (input.custodianUserId) filters.push(eq(assets.custodianUserId, input.custodianUserId))
     if (!input.archived) filters.push(isNull(assets.archivedAt))
 
-    // `recent` sorts by id rather than by `created_at`: ids are uuidv7, so they carry the clock,
-    // and one indexed unique column is a cheaper and unambiguous page boundary than a timestamp
-    // two rows can share. Ordered to the millisecond and no finer — the kernel's `uuidv7()` fills
-    // its last ten bytes from `randomUUID()` with no counter — so two assets created inside one
-    // millisecond come back in a stable but arbitrary order relative to each other. That is fine
-    // for a list and fatal for a test that expects creation order; see `inventory.int.test.ts`.
+    /**
+     * `recent` sorts by id rather than by `created_at`: ids are uuidv7, so they carry the clock, and
+     * one indexed unique column is a cheaper and unambiguous page boundary than a timestamp two rows
+     * can share. Ordered to the millisecond and no finer — the kernel's `uuidv7()` fills its last
+     * ten bytes from `randomUUID()` with no counter — so two assets created inside one millisecond
+     * come back in a stable but arbitrary order relative to each other.
+     *
+     * **The timeline deliberately stopped accepting that and this list has not**, so the difference
+     * is worth stating rather than leaving as an inconsistency. `asset_history` is a record somebody
+     * argues from, and a millisecond there holds a create and its own first entry, so an arbitrary
+     * order is a lie about causation — it has a sequence of its own now (`schema.ts`, `seq`). A list
+     * is an ordering of things a person is browsing: nothing hangs on which of two assets imported
+     * in the same millisecond is shown first, and paging stays gapless either way because the id is
+     * unique. If that ever stops being true — a bulk import whose order somebody relies on — the
+     * fix is the same sequence, not a timestamp: `created_at` defaults to the *transaction's*
+     * `now()`, so one import shares it exactly.
+     *
+     * It is fatal for a test that expects creation order; see `inventory.int.test.ts`.
+     */
     const column = sortKey(assets, input.sort)
     const descending = input.sort === 'recent'
 
     if (input.cursor) {
-      const mark = decode(input.cursor, input.sort)
+      const mark = decodeMark(input.cursor, input.sort)
       /**
        * The sort key comes back out of the bookmarked row rather than out of the cursor, which is
        * what keeps the cursor small and stops it disagreeing with the row it names. Scoped by
@@ -239,10 +232,91 @@ export class AssetService {
 
     const items = rows.slice(0, input.limit)
     const last = items.at(-1)
-    const nextCursor = rows.length > input.limit && last ? encode({ i: last.id, s: input.sort }) : null
+    const nextCursor = rows.length > input.limit && last ? encodeMark({ i: last.id, s: input.sort }) : null
     return { items: items.map(toAsset), nextCursor }
   }
 
+  /**
+   * The asset's own timeline, newest first, paged on the sequence the entries carry.
+   *
+   * **The ordering is `seq`, not `occurred_at` and not the id**, and the middle one of those three
+   * is the interesting correction.
+   *
+   * `occurred_at` was never a candidate: it defaults to `now()`, which is the *transaction*
+   * timestamp, so `create` writes the asset and its `created` entry with the same value and a page
+   * boundary between two entries that share a sort key repeats one and drops the other.
+   *
+   * The id looked like the answer and was only half of one. A uuidv7 is unique, so paging on it is
+   * gapless — but the kernel's `uuidv7()` carries the clock only to the millisecond and fills the
+   * rest from `randomUUID()` with no counter, so two entries written inside one millisecond sort by
+   * ten random bytes. Stable, so nothing was ever dropped or repeated; and arbitrary, so a timeline
+   * could show "Bruno removed the file" above "Bruno added the file". `seq` is a sequence: strictly
+   * increasing whatever the clock does, at whatever rate. `schema.ts` argues it at the column.
+   *
+   * The comparison is a single column because the sort key *is* the bookmark, so there is no
+   * bookmarked-row subquery here. The bookmark is still checked as a bounded positive integer and
+   * still bound to the sort it was issued under, because that is the codec's job and not this
+   * query's.
+   */
+  async history(
+    tx: Tx,
+    workspaceId: string,
+    assetId: string,
+    input: { limit: number; cursor?: string },
+  ): Promise<{ items: AssetHistoryEntry[]; nextCursor: string | null }> {
+    // 404 before paging: a timeline for an asset in another workspace must not answer with an
+    // empty list, which reads as "nothing has happened to it" rather than "it is not yours".
+    await this.get(tx, workspaceId, assetId)
+
+    const filters = [eq(assetHistory.workspaceId, workspaceId), eq(assetHistory.assetId, assetId)]
+    if (input.cursor) filters.push(lt(assetHistory.seq, decodeSeqMark(input.cursor, HISTORY_SORT).n))
+
+    const rows = await tx
+      .select()
+      .from(assetHistory)
+      .where(and(...filters))
+      .orderBy(desc(assetHistory.seq))
+      .limit(input.limit + 1)
+
+    const items = rows.slice(0, input.limit)
+    const last = items.at(-1)
+    const nextCursor =
+      rows.length > input.limit && last ? encodeSeqMark({ n: last.seq, s: HISTORY_SORT }) : null
+    return { items: items.map(toHistoryEntry), nextCursor }
+  }
+
+  /**
+   * A category id in a request is a claim about a row in this workspace, and it is checked before
+   * it is stored.
+   *
+   * The same defect `photoFileId` had, one field over: `assets.create` and `assets.update` took
+   * `categoryId` on trust, so any uuid at all went into the column. Two things follow from that,
+   * and neither is theoretical. An id belonging to **another workspace** files an asset under a
+   * category this one cannot see, name or unfile — the picker resolves names from its own
+   * `categories.list`, so the field renders blank and the filter it sits behind matches nothing
+   * anybody can select. An id belonging to **nobody** does the same thing with no other workspace
+   * involved. Either way the register holds a reference to a row that is not there, which is
+   * exactly the state `categories.archive` exists to prevent from the other end.
+   *
+   * **Checked inside the caller's transaction, unlike `checkPhoto`.** A file lives in core and has
+   * to be asked for over the broker, so that check happens before a connection is taken — the rule
+   * `codeFormat` documents. A category is this module's own table one join away, so the honest
+   * place for it is the transaction that writes the row: it costs one indexed read, and it cannot
+   * be raced by somebody deleting the category, because nothing deletes one.
+   *
+   * An **archived** category is deliberately allowed. Archiving takes it out of every picker and
+   * leaves every asset already filed under it still naming it; refusing it here would mean an edit
+   * to an asset's location failed because of a category somebody tidied away last year, and it
+   * would make re-filing a batch of assets under an old category impossible for no gain.
+   */
+  private async requireCategory(tx: Tx, workspaceId: string, categoryId: string): Promise<void> {
+    const [row] = await tx
+      .select({ id: categories.id })
+      .from(categories)
+      .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+    if (!row) throw KernError.badRequest('That category is not one this workspace has.')
+  }
+
   async get(tx: Tx, workspaceId: string, assetId: string): Promise<Row> {
     const [row] = await tx
       .select()
@@ -259,6 +333,7 @@ export class AssetService {
     input: AssetCreateInput,
     format: CodeFormat,
   ): Promise<Written> {
+    if (input.categoryId) await this.requireCategory(tx, workspaceId, input.categoryId)
     const [row] = await tx
       .insert(assets)
       .values({
@@ -305,6 +380,11 @@ export class AssetService {
     assetId: string,
     input: AssetPatchInput,
   ): Promise<Written> {
+    // Before the row is locked, because a refusal here has nothing to do with this asset and
+    // holding a row lock across a check that can throw is a lock held for no reason. `undefined`
+    // means the patch never mentioned a category and `null` means "unfile it"; neither is an id.
+    if (input.categoryId) await this.requireCategory(tx, workspaceId, input.categoryId)
+
     const [prev] = await tx
       .select()
       .from(assets)
@@ -320,6 +400,16 @@ export class AssetService {
       patch[field] = value !== undefined ? (value ?? null) : prev[field]
     }
 
+    /**
+     * A new warranty date earns a new notice.
+     *
+     * `warranty_notified_at` is the marker that stops the sweep saying the same thing every morning
+     * for a month; left alone here, extending a warranty by two years would mean nobody is ever told
+     * about the new date, because the row is already marked. Cleared only when the date itself
+     * moved — an edit to the name must not re-arm a notice somebody has already had.
+     */
+    if (patch.warrantyUntil !== prev.warrantyUntil) patch.warrantyNotifiedAt = null
+
     // Filtered by workspace as well as by id. The `select … for update` three statements up already
     // carries the predicate, so this is not reachable today — but `core` connects as a superuser
     // with RLS bypassed, which makes the predicate in the statement the only barrier there is. A
@@ -343,13 +433,83 @@ export class AssetService {
     return { row: row!, activity }
   }
 
+  /**
+   * @param repairsOn whether the workspace records repairs, read before the transaction opened.
+   * The "it is away for repair" refusal below tells somebody to go and use `repairs.complete`, and
+   * that procedure answers 404 in a workspace with the capability off — so the refusal would be an
+   * instruction to open a door that is not there, and the asset could never leave the register.
+   */
   async archive(
     tx: Tx,
     workspaceId: string,
     actorId: string | null,
     assetId: string,
     archived: boolean,
+    repairsOn: boolean,
   ): Promise<Written> {
+    /**
+     * **Locked before either refusal is decided, because both of them are about a race.**
+     *
+     * The two checks below used to read the facts with a plain select, so the state they call
+     * impossible was reachable by simply doing the two things at once: an archive and a handover
+     * each read "nobody is holding it", both were allowed, and the register was left with an
+     * archived asset and an open custody period — the timeline showing a handover that never ended,
+     * and "what is Ada still holding?" quietly not counting it, because that question excludes
+     * archived rows. A check whose answer another transaction may already have changed is not a
+     * check; it is a comment.
+     *
+     * The lock is the same one `CustodyService.stamp` and `RepairService.restamp` take before they
+     * write `status`, which is what makes the ordering complete rather than one-sided: whichever
+     * transaction gets it second re-reads what the first committed, so an archive that arrives
+     * first makes the handover refuse, and a handover that arrives first makes the archive refuse.
+     * `lockAsset` in `status.ts` argues it in full.
+     */
+    const [locked] = await tx
+      .select()
+      .from(assets)
+      .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+      .for('update')
+    if (!locked) throw KernError.notFound('Asset')
+
+    if (archived) {
+      /**
+       * An item somebody is holding cannot leave the register.
+       *
+       * Somebody is answerable for the thing; taking it out of the register does not make them not
+       * answerable, it only stops anybody being able to find out. Two steps instead of one, and
+       * both of them mean something.
+       */
+      if (locked.custodianUserId)
+        throw KernError.conflict(
+          'Somebody is still holding this item. Take it back before archiving it.',
+          'inventory.asset.still_held',
+        )
+
+      /**
+       * An item that is at a repairer cannot leave the register either, and for the same reason as
+       * custody: money is committed and the thing is out of the building, so taking it out of the
+       * register does not settle that — it only stops anybody being able to find out.
+       *
+       * It also keeps two counts that must agree from drifting. `stats.summary` reports
+       * `byStatus.under_repair` from the cached status column, over live rows only, and
+       * `outForRepair` from the repair rows themselves; an archived asset with an open repair
+       * would appear in one and not the other, and neither number would be wrong.
+       *
+       * **Only while the workspace records repairs.** With the `repairs` capability off, this
+       * refusal names a procedure that answers 404 — so it was not a two-step instruction, it was a
+       * dead end: the repair could not be completed, so the asset could not be archived, so the
+       * item was stuck in the register for as long as the capability stayed off. A refusal that
+       * points at a door has to be withdrawn when the door is taken away. `stats.away` counts only
+       * live assets for the same reason, so the two counts still cannot disagree.
+       */
+      const open = repairsOn ? await openRepairId(tx, workspaceId, assetId) : undefined
+      if (open)
+        throw KernError.conflict(
+          'This item is away for repair. Log the repair as returned before archiving it.',
+          'inventory.asset.under_repair',
+        )
+    }
+
     const [row] = await tx
       .update(assets)
       .set({ archivedAt: archived ? new Date() : null, updatedAt: new Date() })