@kernhq/module-inventory 0.2.0 → 0.4.0

package/dist/server/services/audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.d.ts","sourceRoot":"","sources":["../../../src/server/services/audience.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAuC5C;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBnB"}

package/dist/server/services/audience.js

@@ -0,0 +1,64 @@
+/**
+ * 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 = { 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;
+/**
+ * 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, workspaceId, permission) {
+    const members = await kernel
+        .call('core.workspaces.members', { workspaceId })
+        .catch(() => []);
+    const ordered = [...members].sort((a, b) => (ROLE_RANK[b.role] ?? 0) - (ROLE_RANK[a.role] ?? 0));
+    const allowed = [];
+    for (const member of ordered) {
+        if (allowed.length >= RECIPIENT_CAP)
+            break;
+        const principal = await kernel
+            .call('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;
+}
+//# sourceMappingURL=audience.js.map

package/dist/server/services/audience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audience.js","sourceRoot":"","sources":["../../../src/server/services/audience.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,+EAA+E;AAC/E,MAAM,SAAS,GAAgC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;AAE1F;;;;;;;;;;GAUG;AACH,MAAM,aAAa,GAAG,EAAE,CAAA;AAOxB;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAc,EACd,WAAmB,EACnB,UAAkB;IAElB,MAAM,OAAO,GAAG,MAAM,MAAM;SACzB,IAAI,CAAW,yBAAyB,EAAE,EAAE,WAAW,EAAE,CAAC;SAC1D,KAAK,CAAC,GAAG,EAAE,CAAC,EAAc,CAAC,CAAA;IAE9B,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAEhG,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,MAAM,IAAI,aAAa;YAAE,MAAK;QAC1C,MAAM,SAAS,GAAG,MAAM,MAAM;aAC3B,IAAI,CAAmB,sBAAsB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;aACzE,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;QACpB,IAAI,CAAC,SAAS;YAAE,SAAQ;QACxB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK;aAC3B,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;aAC9D,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;QACrB,IAAI,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/server/services/categories.d.ts

@@ -0,0 +1,157 @@
+import { type Tx } from '@kernhq/kernel';
+import { type Category as CategoryModel } from '../../contract/models.js';
+import { categories } from '../schema.js';
+type Row = typeof categories.$inferSelect;
+/** 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 declare function toCategory(row: Row): CategoryModel;
+/**
+ * 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 declare 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.
+     */
+    list(tx: Tx, workspaceId: string, includeArchived: boolean): Promise<CategoryModel[]>;
+    get(tx: Tx, workspaceId: string, categoryId: string): Promise<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.
+     */
+    create(tx: Tx, workspaceId: string, name: string): Promise<Row>;
+    /** A rename, and nothing else — the sequence is `reorder`'s to write. */
+    update(tx: Tx, workspaceId: string, categoryId: string, patch: {
+        name?: string;
+    }): Promise<Row>;
+    /**
+     * 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.
+     */
+    archive(tx: Tx, workspaceId: string, categoryId: string, archived: boolean): Promise<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.
+     */
+    reorder(tx: Tx, workspaceId: string, categoryIds: string[]): Promise<Reordered>;
+    /**
+     * 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;
+    /**
+     * 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 lockAppends;
+    /**
+     * 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 roomForOneMore;
+    /**
+     * 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;
+}
+export {};
+//# sourceMappingURL=categories.d.ts.map

package/dist/server/services/categories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.d.ts","sourceRoot":"","sources":["../../../src/server/services/categories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,EAAE,EAAU,MAAM,gBAAgB,CAAA;AAE3D,OAAO,EAAE,KAAK,QAAQ,IAAI,aAAa,EAAuB,MAAM,0BAA0B,CAAA;AAC9F,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGzC,KAAK,GAAG,GAAG,OAAO,UAAU,CAAC,YAAY,CAAA;AAKzC,iGAAiG;AACjG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,gGAAgG;IAChG,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,CAUlD;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;OAWG;IACG,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAWrF,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IASxE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAcrE,yEAAyE;IACnE,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC;IAoBrG;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAkB/F;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IA0ErF;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;IAIvB;;;;;;;;;;;;;OAaG;mBACkB,WAAW;IAMhC;;;;;;;;;;;OAWG;mBACkB,cAAc;IAYnC;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;CAOzB"}

package/dist/server/services/categories.js

@@ -0,0 +1,309 @@
+import { KernError, uuidv7 } from '@kernhq/kernel';
+import { and, asc, count, eq, isNull, sql } from 'drizzle-orm';
+import { MAX_LIVE_CATEGORIES } from '../../contract/models.js';
+import { categories } from '../schema.js';
+import { violated } from './db-errors.js';
+/** The unique index `0000_init.sql` put on (workspace_id, name). */
+const NAME_TAKEN = 'inventory_categories_ws_name_uq';
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toCategory(row) {
+    return {
+        id: row.id,
+        workspaceId: row.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, workspaceId, includeArchived) {
+        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, workspaceId, categoryId) {
+        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, workspaceId, name) {
+        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, workspaceId, categoryId, patch) {
+        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, workspaceId, categoryId, archived) {
+        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, workspaceId, categoryIds) {
+        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.
+     */
+    static appended(workspaceId) {
+        return sql `(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.
+     */
+    static async lockAppends(tx, workspaceId) {
+        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.
+     */
+    static async roomForOneMore(tx, workspaceId) {
+        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.
+     */
+    static nameTaken(err, name) {
+        if (!violated(err, NAME_TAKEN))
+            return err;
+        return KernError.conflict(`This workspace already has a category called “${name}”.`, 'inventory.category.name_taken');
+    }
+}
+//# sourceMappingURL=categories.js.map

package/dist/server/services/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../../src/server/services/categories.ts"],"names":[],"mappings":"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"}

package/dist/server/services/cursor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one page boundary this module issues, for every list it pages.
+ *
+ * **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.
+ *
+ * It lives here rather than in `assets.ts` because the repair list pages too, and a second bookmark
+ * format would be a second set of those three bugs. `src/client/mock.ts` mirrors this byte for
+ * byte; read them as one pair and change them as one pair.
+ *
+ * The asset timeline is the one list that does **not** use this one: it is ordered by a sequence
+ * rather than by a row id, so its bookmark is `SeqBookmark` below.
+ */
+export interface Bookmark<S extends string> {
+    i: string;
+    s: S;
+}
+export declare const encodeMark: <S extends string>(mark: Bookmark<S>) => string;
+export declare function decodeMark<S extends string>(cursor: string, sort: S): Bookmark<S>;
+/**
+ * The other page boundary: a row's **sequence number**, and the sort it was issued under.
+ *
+ * The asset timeline is ordered by `asset_history.seq` rather than by the row id, because a uuidv7
+ * is only ordered to the millisecond and two entries written inside one — an attach and a detach, a
+ * create and its first entry — sort by ten random bytes. `schema.ts` argues that at the column. A
+ * bookmark into that ordering has to name the sequence value, so it is a number rather than a uuid
+ * and needs its own codec: handing `decodeMark` a number would have it refused as "not a uuid", and
+ * relaxing `decodeMark` to accept either is how one of the two shapes ends up unvalidated.
+ *
+ * It keeps all three properties the uuid bookmark has, and for the same reasons:
+ *
+ *   - **bounded** — a base64url of `{"n":<integer>,"s":"recent"}` is around forty characters
+ *     whatever the row, well inside `Cursor`'s `max(512)` in `@kernhq/contracts`;
+ *   - **checked before it reaches SQL** — anything that is not a safe positive integer is refused
+ *     here rather than interpolated into a `bigint` comparison for Postgres to reject as a 22P02;
+ *   - **bound to its sort** — a bookmark issued under one ordering is meaningless under another,
+ *     and reading it anyway is what made "Load more" loop for ever.
+ *
+ * `Number.isSafeInteger` is the upper bound as well as the type check: the column is a `bigint` and
+ * the sequence would have to hand out nine quadrillion history rows to reach it, but a cursor
+ * arrives from outside and `JSON.parse` will happily produce `1e400`.
+ */
+export interface SeqBookmark<S extends string> {
+    n: number;
+    s: S;
+}
+export declare const encodeSeqMark: <S extends string>(mark: SeqBookmark<S>) => string;
+export declare function decodeSeqMark<S extends string>(cursor: string, sort: S): SeqBookmark<S>;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/server/services/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/server/services/cursor.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM;IACxC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,CAAC,CAAA;CACL;AAED,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,MAAM,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC,KAAG,MACA,CAAA;AAKjE,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAcjF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM;IAC3C,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,CAAC,CAAA;CACL;AAED,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAAG,MACN,CAAA;AAEjE,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAWvF"}