@kernhq/module-inventory 0.1.2 → 0.3.0

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

@@ -0,0 +1,80 @@
+import { type Kernel, type Tx } from '@kernhq/kernel';
+import type { Attachment as AttachmentModel } from '../../contract/models.js';
+import { attachments } 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 declare function toAttachment(row: Row): AttachmentModel;
+/**
+ * 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 declare class AttachmentService {
+    private readonly kernel;
+    private readonly notify;
+    constructor(kernel: Kernel, 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.
+     */
+    describe(workspaceId: string, fileIds: readonly string[]): Promise<FileFacts[]>;
+    /**
+     * 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.
+     */
+    list(tx: Tx, workspaceId: string, assetId: string): Promise<AttachmentModel[]>;
+    /**
+     * 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.
+     */
+    add(tx: Tx, workspaceId: string, actorId: string | null, assetId: string, repairId: string | null, files: readonly FileFacts[]): Promise<{
+        rows: Row[];
+        activities: HistoryInput[];
+    }>;
+    /** Detach one file. Core's copy of it is untouched — see the class docblock. */
+    remove(tx: Tx, workspaceId: string, actorId: string | null, attachmentId: string): Promise<{
+        row: Row;
+        activity: HistoryInput;
+    }>;
+    private requireAsset;
+    /** A repair the file is filed under has to be one of *this* asset's, not merely one that exists. */
+    private requireRepair;
+}
+export {};
+//# sourceMappingURL=attachments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../../src/server/services/attachments.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,MAAM,EAAE,KAAK,EAAE,EAAU,MAAM,gBAAgB,CAAA;AAExE,OAAO,KAAK,EAAE,UAAU,IAAI,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAAU,WAAW,EAAW,MAAM,cAAc,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE9D,KAAK,GAAG,GAAG,OAAO,WAAW,CAAC,YAAY,CAAA;AAE1C,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED,oGAAoG;AACpG,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,eAAe,CAatD;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa;IAGxC;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBrF;;;;;;;OAOG;IACG,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IASpF;;;;;;;;;;OAUG;IACG,GAAG,CACP,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,KAAK,EAAE,SAAS,SAAS,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,UAAU,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IA6CvD,gFAAgF;IAC1E,MAAM,CACV,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA0BlC,YAAY;IAQ1B,oGAAoG;YACtF,aAAa;CAS5B"}

package/dist/server/services/attachments.js

@@ -0,0 +1,182 @@
+import { KernError, uuidv7 } from '@kernhq/kernel';
+import { and, asc, eq } from 'drizzle-orm';
+import { assets, attachments, repairs } from '../schema.js';
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export function toAttachment(row) {
+    return {
+        id: row.id,
+        workspaceId: row.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 {
+    kernel;
+    notify;
+    constructor(kernel, notify) {
+        this.kernel = kernel;
+        this.notify = notify;
+    }
+    /**
+     * 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, fileIds) {
+        const unique = [...new Set(fileIds)];
+        const found = await Promise.all(unique.map(async (id) => {
+            const file = await this.kernel.call('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, workspaceId, assetId) {
+        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, workspaceId, actorId, assetId, repairId, files) {
+        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 = 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, workspaceId, actorId, attachmentId) {
+        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 = {
+            workspaceId,
+            assetId: row.assetId,
+            actorId,
+            action: 'attachment_removed',
+            data: { attachmentId: row.id, name: row.name },
+        };
+        await this.notify.history(tx, activity);
+        return { row, activity };
+    }
+    async requireAsset(tx, workspaceId, assetId) {
+        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. */
+    async requireRepair(tx, workspaceId, assetId, repairId) {
+        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');
+    }
+}
+//# sourceMappingURL=attachments.js.map

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

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

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

@@ -0,0 +1,15 @@
+import type { Kernel } from '@kernhq/kernel';
+/**
+ * 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 declare function membersWithPermission(kernel: Kernel, workspaceId: string, permission: string): Promise<string[]>;
+//# sourceMappingURL=audience.d.ts.map

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,57 @@
+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;
+/** 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, which is what makes a workspace that never touches the
+     * order field still get an alphabetical picker rather than an arbitrary one — every row has
+     * `order` 0, so the tiebreak is doing all the work and has to be a name rather than an id.
+     */
+    list(tx: Tx, workspaceId: string, includeArchived: boolean): Promise<CategoryModel[]>;
+    get(tx: Tx, workspaceId: string, categoryId: string): Promise<Row>;
+    /**
+     * A duplicate name is a `CONFLICT` with the name in it, never a 500.
+     *
+     * The unique index is what actually decides — 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 …".
+     */
+    create(tx: Tx, workspaceId: string, name: string, order: number): Promise<Row>;
+    update(tx: Tx, workspaceId: string, categoryId: string, patch: {
+        name?: string;
+        order?: number;
+    }): 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.
+     */
+    archive(tx: Tx, workspaceId: string, categoryId: string, archived: boolean): Promise<Row>;
+    /**
+     * 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,KAAK,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,0BAA0B,CAAA;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGzC,KAAK,GAAG,GAAG,OAAO,UAAU,CAAC,YAAY,CAAA;AAKzC,oGAAoG;AACpG,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,aAAa,CAUlD;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B;;;;OAIG;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;;;;;;;OAOG;IACG,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAS9E,MAAM,CACV,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACvC,OAAO,CAAC,GAAG,CAAC;IAqBf;;;;;;;;;;OAUG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAU/F;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;CAOzB"}

package/dist/server/services/categories.js

@@ -0,0 +1,124 @@
+import { KernError, uuidv7 } from '@kernhq/kernel';
+import { and, asc, eq, isNull } from 'drizzle-orm';
+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, which is what makes a workspace that never touches the
+     * order field still get an alphabetical picker rather than an arbitrary one — every row has
+     * `order` 0, so the tiebreak is doing all the work and has to be a name rather than an id.
+     */
+    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 duplicate name is a `CONFLICT` with the name in it, never a 500.
+     *
+     * The unique index is what actually decides — 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 …".
+     */
+    async create(tx, workspaceId, name, order) {
+        try {
+            const [row] = await tx.insert(categories).values({ id: uuidv7(), workspaceId, name, order }).returning();
+            return row;
+        }
+        catch (err) {
+            throw CategoryService.nameTaken(err, name);
+        }
+    }
+    async update(tx, workspaceId, categoryId, patch) {
+        const previous = await this.get(tx, workspaceId, categoryId);
+        // `undefined` means "not mentioned". Neither field is 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,
+            order: patch.order ?? previous.order,
+            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.
+     */
+    async archive(tx, workspaceId, categoryId, archived) {
+        const [row] = await tx
+            .update(categories)
+            .set({ archivedAt: archived ? new Date() : null, updatedAt: new Date() })
+            .where(and(eq(categories.workspaceId, workspaceId), eq(categories.id, categoryId)))
+            .returning();
+        if (!row)
+            throw KernError.notFound('Category');
+        return row;
+    }
+    /**
+     * 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"}