@kernhq/module-inventory 0.1.2 → 0.2.0

package/README.md

@@ -1,16 +1,62 @@
 # @kernhq/module-inventory
 
-The asset register for [Kern](https://github.com/KernAIO/app): what the company owns, who holds each
-item, and everything that happened to it.
+The asset register for [Kern](https://github.com/KernAIO/app): a list of what the company owns, item
+by item.
 
-- **Assets** with an auto-assigned tag (`INV-0042`), serial number, purchase date and vendor, price,
-  warranty expiry, location, photo and description.
-- **Custody**: hand an item to a member and it stays theirs — with the full history of who held it
-  before — until somebody hands it on or takes it back.
-- **History**: every change to an asset is recorded as an append-only timeline entry: what moved,
-  from what, to what, by whom.
+This is a first-party Kern module. Contract, server, screens, strings and manifest ship in one
+package — `core` imports `inventoryModule`, the app shell registers `inventoryClientModule`, and
+deleting the package removes the feature completely. Enable it per workspace in
+**Settings → Modules**.
 
-Part of a Kern instance; enable it per workspace in **Settings → Modules**.
+## What it does today
+
+An **asset** carries an asset tag the server assigns (`INV-0042`), a name and description, a serial
+number, a purchase date and vendor, a price, a warranty expiry, a location, a photo and a status.
+
+The status column holds one of `in_stock`, `assigned`, `reserved`, `under_repair`, `lost` and
+`retired`, and the screen can filter by any of them — but until custody and repairs ship, nothing
+sets it, so every asset is `in_stock` and the other five filters correctly return nothing. The
+filter is not wrong; there is simply nothing else to find yet.
+
+- The **Assets** screen lists them in a table, searches by name, tag or serial number, filters by
+  status, hides archived rows until the switch asks for them, and pages a workspace with more
+  assets than one screen holds. All four are one server query; nothing is filtered in the browser.
+- Adding an asset opens a dialog, and editing one opens the same dialog seeded from the row. The tag
+  is the server's job — people read tags off stickers rather than inventing them.
+- Each row carries a menu: edit, archive, restore. Archiving asks first and names what it is about
+  to archive; restoring does not, because it takes nothing away.
+- A **dashboard card** shows the most recently added assets.
+- **Settings → Inventory → General** sets the shape of an asset tag — the prefix and how many digits
+  it is padded to, so a workspace that already labels its laptops `LT-` keeps doing that. The number
+  itself is a counter in the database rather than a setting: a number an administrator can edit is a
+  number that produces a duplicate tag.
+- Two permissions gate it: `inventory.asset.view` and `inventory.asset.manage`.
+- Its strings ship in the five languages the platform speaks — English, Arabic, German, Persian,
+  Turkish.
+
+The whole API is five procedures under `/api/inventory`: list, get, create, update and archive an
+asset. An asset's photo is settable through `create` and `update` and by nothing on the screen yet;
+its custom values are settable by neither, and wait on custom fields below.
+
+## Not built yet
+
+Nothing here has a screen. Most of it is a table in `mod_inventory` and nothing more; each bullet
+says how far it actually got. A register is worth designing whole, and a migration that adds a
+column later is cheaper than one that reshapes a table. A table is not a feature, and this section
+stays until each one ships.
+
+- **Custody** — who is holding an item now, who held it before, and handing it on.
+- **History** — an append-only timeline of every change to an asset. The writes exist: create,
+  update, archive and restore each append an `asset_history` row, and the integration suite holds
+  them to it. Nothing reads them back — there is no procedure and no screen.
+- **Repairs** — what went away for repair, to whom, what it cost and when it came back.
+- **Categories** — the column and the list filter exist; nothing can create a category.
+- **Custom fields** — a workspace's own fields on an asset. `assets.custom` holds the values;
+  nothing defines a field, so `create` and `update` refuse to write into it at all.
+- **Attachments** — receipts, warranties and manuals against an asset or a repair.
+
+Further off, and with nothing in the schema yet: locations and stock control (bins, counts, reorder
+points), purchasing, depreciation, and reservations.
 
 ## Developing
 

package/dist/contract/capabilities.d.ts

@@ -0,0 +1,49 @@
+/**
+ * How much Inventory this workspace has.
+ *
+ * The module answers two questions that look like one: *what do we own and who has it* (an office
+ * with forty laptops) and *how much of this do we have and where* (a warehouse with bins and
+ * reorder points). Both are "things the company has", both want the same categories, locations,
+ * suppliers, attachments and search — and almost nobody wants both halves at once. Capabilities are
+ * what keep the small case small: an office switches on nothing beyond the register and never meets
+ * the word "bin".
+ *
+ * **Declared here only once something is behind it.** A switch that changes nothing teaches an
+ * administrator that the switchboard does not mean anything, so this list grows with the module.
+ *
+ * Two rules decide whether something belongs here at all:
+ *
+ * - **Not a permission.** "May Ada write off a laptop" is a permission — true for her, false for
+ *   somebody else, in the same workspace. "Does this company track stock levels" is a capability:
+ *   one answer for everyone, the owner included, and the answer is 404 rather than 403.
+ * - **Reversible without a migration.** Switching one off writes a boolean into module settings and
+ *   the rows stay exactly where they are. Anything that would need data thrown away to reverse is
+ *   not a capability, however much it looks like one.
+ *
+ * The rest arrive with the work that makes them mean something: `repairs`, `attachments` and
+ * `labels` with the finished register; `custom_fields` and `locations` beside them; `stock` and
+ * `procurement` with stock control; `depreciation` and `reservations` last. Adding one here before
+ * its procedures exist is the mistake this comment is here to prevent.
+ */
+export declare const inventoryCapabilities: readonly {
+    id: string;
+    label: string;
+    dependsOn: string[];
+    defaultEnabled: boolean;
+    level: 3 | 1 | 2;
+    required: boolean;
+    description?: string | undefined;
+}[];
+export type InventoryCapabilityId = (typeof inventoryCapabilities)[number]['id'];
+/**
+ * Which procedures sit behind which capability.
+ *
+ * Declared as data because a missing `requiresCapability` is invisible: the procedure compiles,
+ * every other test passes, and the only symptom is a workspace calling a feature it switched off.
+ * `module.test.ts` reads this and fails when a procedure named here is not carrying the middleware.
+ *
+ * A procedure absent from this map belongs to the module as a whole and is reachable whenever
+ * Inventory is on — which for `core` is always, because it is `required`.
+ */
+export declare const inventoryCapabilityProcedures: Record<string, readonly string[]>;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/contract/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;GAWhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAA;AAEhF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAM,CAAA"}

package/dist/contract/capabilities.js

@@ -0,0 +1,52 @@
+import { defineCapabilities } from '@kernhq/contracts';
+/**
+ * How much Inventory this workspace has.
+ *
+ * The module answers two questions that look like one: *what do we own and who has it* (an office
+ * with forty laptops) and *how much of this do we have and where* (a warehouse with bins and
+ * reorder points). Both are "things the company has", both want the same categories, locations,
+ * suppliers, attachments and search — and almost nobody wants both halves at once. Capabilities are
+ * what keep the small case small: an office switches on nothing beyond the register and never meets
+ * the word "bin".
+ *
+ * **Declared here only once something is behind it.** A switch that changes nothing teaches an
+ * administrator that the switchboard does not mean anything, so this list grows with the module.
+ *
+ * Two rules decide whether something belongs here at all:
+ *
+ * - **Not a permission.** "May Ada write off a laptop" is a permission — true for her, false for
+ *   somebody else, in the same workspace. "Does this company track stock levels" is a capability:
+ *   one answer for everyone, the owner included, and the answer is 404 rather than 403.
+ * - **Reversible without a migration.** Switching one off writes a boolean into module settings and
+ *   the rows stay exactly where they are. Anything that would need data thrown away to reverse is
+ *   not a capability, however much it looks like one.
+ *
+ * The rest arrive with the work that makes them mean something: `repairs`, `attachments` and
+ * `labels` with the finished register; `custom_fields` and `locations` beside them; `stock` and
+ * `procurement` with stock control; `depreciation` and `reservations` last. Adding one here before
+ * its procedures exist is the mistake this comment is here to prevent.
+ */
+export const inventoryCapabilities = defineCapabilities([
+    {
+        id: 'core',
+        label: 'Assets',
+        // Says only what the module answers today. Custody and the change history are what the schema
+        // is shaped for and neither has a procedure yet, so naming them here promised a workspace two
+        // features it would then go looking for.
+        description: 'The asset register: what the company owns, item by item',
+        required: true,
+        level: 1,
+    },
+]);
+/**
+ * Which procedures sit behind which capability.
+ *
+ * Declared as data because a missing `requiresCapability` is invisible: the procedure compiles,
+ * every other test passes, and the only symptom is a workspace calling a feature it switched off.
+ * `module.test.ts` reads this and fails when a procedure named here is not carrying the middleware.
+ *
+ * A procedure absent from this map belongs to the module as a whole and is reachable whenever
+ * Inventory is on — which for `core` is always, because it is `required`.
+ */
+export const inventoryCapabilityProcedures = {};
+//# sourceMappingURL=capabilities.js.map

package/dist/contract/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/contract/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;IACtD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,QAAQ;QACf,8FAA8F;QAC9F,8FAA8F;QAC9F,yCAAyC;QACzC,WAAW,EAAE,yDAAyD;QACtE,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,CAAC;KACT;CACF,CAAC,CAAA;AAIF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsC,EAAE,CAAA"}

package/dist/contract/events.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+/**
+ * `<module>.<entity>.<action>`. Anything that emits one declares it here.
+ *
+ * Payloads carry **ids, never rows**. A subscriber that needs the record asks for it with its own
+ * principal, so an event cannot become a way to read data past a permission check.
+ */
+export declare const inventoryEvents: {
+    assetCreated: import("@kernhq/contracts").EventDef<"inventory.asset.created", z.ZodObject<{
+        assetId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    assetUpdated: import("@kernhq/contracts").EventDef<"inventory.asset.updated", z.ZodObject<{
+        assetId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    assetArchived: import("@kernhq/contracts").EventDef<"inventory.asset.archived", z.ZodObject<{
+        assetId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+    /**
+     * The other half of `archive`, which is also the restore path (`archived: false`).
+     *
+     * One procedure emitting `archived` whichever way the flag pointed told every subscriber that a
+     * restored item had just been retired — and the module's own `asset_history` row already knew
+     * better, recording `retired` and `restored` separately.
+     */
+    assetRestored: import("@kernhq/contracts").EventDef<"inventory.asset.restored", z.ZodObject<{
+        assetId: z.ZodUUID;
+        workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    }, z.core.$strip>>;
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/contract/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/contract/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;IAa1B;;;;;;OAMG;;;;;CAKJ,CAAA"}

package/dist/contract/events.js

@@ -0,0 +1,22 @@
+import { defineEvent, WorkspaceId } from '@kernhq/contracts';
+import { z } from 'zod';
+/**
+ * `<module>.<entity>.<action>`. Anything that emits one declares it here.
+ *
+ * Payloads carry **ids, never rows**. A subscriber that needs the record asks for it with its own
+ * principal, so an event cannot become a way to read data past a permission check.
+ */
+export const inventoryEvents = {
+    assetCreated: defineEvent('inventory.asset.created', z.object({ assetId: z.uuid(), workspaceId: WorkspaceId })),
+    assetUpdated: defineEvent('inventory.asset.updated', z.object({ assetId: z.uuid(), workspaceId: WorkspaceId })),
+    assetArchived: defineEvent('inventory.asset.archived', z.object({ assetId: z.uuid(), workspaceId: WorkspaceId })),
+    /**
+     * The other half of `archive`, which is also the restore path (`archived: false`).
+     *
+     * One procedure emitting `archived` whichever way the flag pointed told every subscriber that a
+     * restored item had just been retired — and the module's own `asset_history` row already knew
+     * better, recording `retired` and `restored` separately.
+     */
+    assetRestored: defineEvent('inventory.asset.restored', z.object({ assetId: z.uuid(), workspaceId: WorkspaceId })),
+};
+//# sourceMappingURL=events.js.map

package/dist/contract/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/contract/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY,EAAE,WAAW,CACvB,yBAAyB,EACzB,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAC1D;IACD,YAAY,EAAE,WAAW,CACvB,yBAAyB,EACzB,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAC1D;IACD,aAAa,EAAE,WAAW,CACxB,0BAA0B,EAC1B,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAC1D;IACD;;;;;;OAMG;IACH,aAAa,EAAE,WAAW,CACxB,0BAA0B,EAC1B,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAC1D;CACF,CAAA"}

package/dist/contract/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What this module offers, as data.
+ *
+ * A barrel and nothing else: every symbol is defined in the file beside it. Imported by **both**
+ * halves — the server implements the contract, the client calls it — so nothing reachable from here
+ * may touch Node. A procedure that exists here and not in the router is a lie that compiles, and
+ * `module.test.ts` checks exactly that.
+ */
+export * from './capabilities.js';
+export * from './events.js';
+export * from './models.js';
+export * from './permissions.js';
+export * from './router.js';
+export * from './settings.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/contract/index.js

@@ -0,0 +1,15 @@
+/**
+ * What this module offers, as data.
+ *
+ * A barrel and nothing else: every symbol is defined in the file beside it. Imported by **both**
+ * halves — the server implements the contract, the client calls it — so nothing reachable from here
+ * may touch Node. A procedure that exists here and not in the router is a lie that compiles, and
+ * `module.test.ts` checks exactly that.
+ */
+export * from './capabilities.js';
+export * from './events.js';
+export * from './models.js';
+export * from './permissions.js';
+export * from './router.js';
+export * from './settings.js';
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/contract/models.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+/**
+ * The nouns this module owns, and the shapes that cross the wire.
+ *
+ * Imported by **both** halves — the server implements against them, the client calls against them —
+ * so nothing here may touch Node. Types only; the procedures live in `router.ts`.
+ */
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_<id>` and every event. */
+export declare const MODULE_ID = "inventory";
+/**
+ * An asset's lifecycle. `in_stock` and `assigned` follow custody (an open row in `custody_periods`
+ * means assigned); `under_repair` follows an open repair; `reserved` follows a booking that has not
+ * been collected; `lost` and `retired` are set by hand when an item stops being usable.
+ *
+ * Stored rather than derived, because every list filter asks for it — and kept in step inside the
+ * same transaction that writes the row it derives from, never by a job afterwards.
+ */
+export declare const AssetStatus: z.ZodEnum<{
+    in_stock: "in_stock";
+    assigned: "assigned";
+    reserved: "reserved";
+    under_repair: "under_repair";
+    lost: "lost";
+    retired: "retired";
+}>;
+export type AssetStatus = z.infer<typeof AssetStatus>;
+/**
+ * A value a workspace defined for itself, stored under its `key` in `assets.custom`.
+ *
+ * `unknown` rather than a union: the field definition says what the type is, and validating a value
+ * against a definition the client may not have loaded yet would fail honest input. The server checks
+ * it against `field_defs` before writing.
+ */
+export declare const CustomValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type CustomValues = z.infer<typeof CustomValues>;
+export declare const Asset: z.ZodObject<{
+    id: z.ZodUUID;
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+    code: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    categoryId: z.ZodNullable<z.ZodUUID>;
+    status: z.ZodEnum<{
+        in_stock: "in_stock";
+        assigned: "assigned";
+        reserved: "reserved";
+        under_repair: "under_repair";
+        lost: "lost";
+        retired: "retired";
+    }>;
+    custodianUserId: z.ZodNullable<z.ZodUUID>;
+    custodySince: z.ZodNullable<z.ZodString>;
+    serialNumber: z.ZodNullable<z.ZodString>;
+    location: z.ZodNullable<z.ZodString>;
+    purchasedOn: z.ZodNullable<z.ZodString>;
+    purchasedFrom: z.ZodNullable<z.ZodString>;
+    priceMinor: z.ZodNullable<z.ZodNumber>;
+    currency: z.ZodNullable<z.ZodString>;
+    warrantyUntil: z.ZodNullable<z.ZodString>;
+    photoFileId: z.ZodNullable<z.ZodUUID>;
+    custom: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    archivedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Asset = z.infer<typeof Asset>;
+/**
+ * How a list is ordered, and therefore what a page cursor is a bookmark *into*.
+ *
+ * Exported rather than written inline in `router.ts` because the server validates a cursor against
+ * this same list: a bookmark issued under one sort is meaningless under another, and the only way
+ * to say so is for both halves to read one enum.
+ */
+export declare const AssetSort: z.ZodEnum<{
+    code: "code";
+    name: "name";
+    recent: "recent";
+}>;
+export type AssetSort = z.infer<typeof AssetSort>;
+/**
+ * Everything a person can say about an asset. `create` requires `name`; `update` takes any subset.
+ *
+ * **No field here carries `.default()`, and that is load-bearing.** `update` is built from
+ * `AssetInput.partial()`, and `.partial()` does not strip a default — it only wraps the field in
+ * `optional`, so zod still substitutes the default for a key the request never sent. `description`
+ * had `.default('')`, so `PATCH {assetId, name}` reached the handler as
+ * `{assetId, name, description: ''}`; the service correctly read a present value as "set it" and a
+ * rename destroyed the text, writing a bogus `description` diff into `asset_history` as it went.
+ * The care the service takes over `undefined` versus `null` is defeated one layer above it, here.
+ * A value `create` should fill in belongs on `AssetCreateInput` below, which is never partialled.
+ */
+export declare const AssetInput: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    categoryId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+    serialNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purchasedFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purchasedOn: z.ZodOptional<z.ZodNullable<z.ZodISODate>>;
+    warrantyUntil: z.ZodOptional<z.ZodNullable<z.ZodISODate>>;
+    priceMinor: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    photoFileId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+}, z.core.$strip>;
+export type AssetInput = z.infer<typeof AssetInput>;
+/**
+ * What `create` accepts: the same fields, with the one value a new row may not go without.
+ *
+ * `description` is `not null` in the database, so a create with no description needs *something*.
+ * Defaulting it here rather than in `AssetInput` is what keeps `update` able to tell "leave it
+ * alone" from "clear it" — see the note above.
+ */
+export declare const AssetCreateInput: z.ZodObject<{
+    name: z.ZodString;
+    categoryId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+    serialNumber: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    location: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purchasedFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    purchasedOn: z.ZodOptional<z.ZodNullable<z.ZodISODate>>;
+    warrantyUntil: z.ZodOptional<z.ZodNullable<z.ZodISODate>>;
+    priceMinor: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    photoFileId: z.ZodOptional<z.ZodNullable<z.ZodUUID>>;
+    description: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type AssetCreateInput = z.infer<typeof AssetCreateInput>;
+/** What `update` accepts: any subset, and nothing filled in for a key that never arrived. */
+export declare const AssetPatchInput: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    categoryId: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodUUID>>>;
+    serialNumber: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    location: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    purchasedFrom: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    purchasedOn: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodISODate>>>;
+    warrantyUntil: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodISODate>>>;
+    priceMinor: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+    currency: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
+    photoFileId: z.ZodOptional<z.ZodOptional<z.ZodNullable<z.ZodUUID>>>;
+}, z.core.$strip>;
+export type AssetPatchInput = z.infer<typeof AssetPatchInput>;
+/** Shared by every workspace-scoped procedure, which is all of them. */
+export declare const ws: z.ZodObject<{
+    workspaceId: z.core.$ZodBranded<z.ZodUUID, "WorkspaceId", "out">;
+}, z.core.$strip>;
+//# sourceMappingURL=models.d.ts.map

package/dist/contract/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/contract/models.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;GAKG;AAEH,wGAAwG;AACxG,eAAO,MAAM,SAAS,cAAc,CAAA;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;;;;;;EAAkF,CAAA;AAC1G,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,wCAAoC,CAAA;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEvD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4BhB,CAAA;AACF,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;EAAqC,CAAA;AAC3D,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;iBAerB,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;iBAE3B,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAE/D,6FAA6F;AAC7F,eAAO,MAAM,eAAe;;;;;;;;;;;;iBAAuB,CAAA;AACnD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAE7D,wEAAwE;AACxE,eAAO,MAAM,EAAE;;iBAAyC,CAAA"}

package/dist/contract/models.js

@@ -0,0 +1,107 @@
+import { WorkspaceId } from '@kernhq/contracts';
+import { z } from 'zod';
+/**
+ * The nouns this module owns, and the shapes that cross the wire.
+ *
+ * Imported by **both** halves — the server implements against them, the client calls against them —
+ * so nothing here may touch Node. Types only; the procedures live in `router.ts`.
+ */
+/** Lowercase, 2-32 characters. Names the API prefix, the Postgres schema `mod_<id>` and every event. */
+export const MODULE_ID = 'inventory';
+/**
+ * An asset's lifecycle. `in_stock` and `assigned` follow custody (an open row in `custody_periods`
+ * means assigned); `under_repair` follows an open repair; `reserved` follows a booking that has not
+ * been collected; `lost` and `retired` are set by hand when an item stops being usable.
+ *
+ * Stored rather than derived, because every list filter asks for it — and kept in step inside the
+ * same transaction that writes the row it derives from, never by a job afterwards.
+ */
+export const AssetStatus = z.enum(['in_stock', 'assigned', 'reserved', 'under_repair', 'lost', 'retired']);
+/**
+ * A value a workspace defined for itself, stored under its `key` in `assets.custom`.
+ *
+ * `unknown` rather than a union: the field definition says what the type is, and validating a value
+ * against a definition the client may not have loaded yet would fail honest input. The server checks
+ * it against `field_defs` before writing.
+ */
+export const CustomValues = z.record(z.string(), z.unknown());
+export const Asset = z.object({
+    id: z.uuid(),
+    workspaceId: WorkspaceId,
+    /** Human-facing asset tag (`INV-0001`), assigned by the server, unique per workspace. */
+    code: z.string().min(1).max(40),
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000),
+    categoryId: z.uuid().nullable(),
+    status: AssetStatus,
+    /**
+     * The member currently holding the item. A plain uuid — cross-schema foreign keys are what the
+     * module boundary exists to prevent — resolved against core membership at read time.
+     */
+    custodianUserId: z.uuid().nullable(),
+    custodySince: z.string().nullable(),
+    serialNumber: z.string().max(200).nullable(),
+    location: z.string().max(200).nullable(),
+    purchasedOn: z.string().nullable(),
+    purchasedFrom: z.string().max(200).nullable(),
+    /** Minor units (cents), the convention billing established; formatted on the client. */
+    priceMinor: z.number().int().nullable(),
+    currency: z.string().length(3).nullable(),
+    warrantyUntil: z.string().nullable(),
+    photoFileId: z.uuid().nullable(),
+    custom: CustomValues,
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    archivedAt: z.string().nullable(),
+});
+/**
+ * How a list is ordered, and therefore what a page cursor is a bookmark *into*.
+ *
+ * Exported rather than written inline in `router.ts` because the server validates a cursor against
+ * this same list: a bookmark issued under one sort is meaningless under another, and the only way
+ * to say so is for both halves to read one enum.
+ */
+export const AssetSort = z.enum(['recent', 'name', 'code']);
+/**
+ * Everything a person can say about an asset. `create` requires `name`; `update` takes any subset.
+ *
+ * **No field here carries `.default()`, and that is load-bearing.** `update` is built from
+ * `AssetInput.partial()`, and `.partial()` does not strip a default — it only wraps the field in
+ * `optional`, so zod still substitutes the default for a key the request never sent. `description`
+ * had `.default('')`, so `PATCH {assetId, name}` reached the handler as
+ * `{assetId, name, description: ''}`; the service correctly read a present value as "set it" and a
+ * rename destroyed the text, writing a bogus `description` diff into `asset_history` as it went.
+ * The care the service takes over `undefined` versus `null` is defeated one layer above it, here.
+ * A value `create` should fill in belongs on `AssetCreateInput` below, which is never partialled.
+ */
+export const AssetInput = z.object({
+    name: z.string().min(1).max(200),
+    description: z.string().max(4000).optional(),
+    categoryId: z.uuid().nullish(),
+    serialNumber: z.string().max(200).nullish(),
+    location: z.string().max(200).nullish(),
+    purchasedFrom: z.string().max(200).nullish(),
+    purchasedOn: z.iso.date().nullish(),
+    warrantyUntil: z.iso.date().nullish(),
+    priceMinor: z.number().int().min(0).nullish(),
+    currency: z.string().length(3).nullish(),
+    photoFileId: z.uuid().nullish(),
+    // `custom` is deliberately absent: there is nothing to validate a value against until
+    // `fields.*` exists, and accepting arbitrary JSON into a column a workspace has not defined
+    // is how a schemaless field bag becomes permanent. It arrives with the field definitions.
+});
+/**
+ * What `create` accepts: the same fields, with the one value a new row may not go without.
+ *
+ * `description` is `not null` in the database, so a create with no description needs *something*.
+ * Defaulting it here rather than in `AssetInput` is what keeps `update` able to tell "leave it
+ * alone" from "clear it" — see the note above.
+ */
+export const AssetCreateInput = AssetInput.extend({
+    description: z.string().max(4000).default(''),
+});
+/** What `update` accepts: any subset, and nothing filled in for a key that never arrived. */
+export const AssetPatchInput = AssetInput.partial();
+/** Shared by every workspace-scoped procedure, which is all of them. */
+export const ws = z.object({ workspaceId: WorkspaceId });
+//# sourceMappingURL=models.js.map

package/dist/contract/models.js.map

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

package/dist/contract/permissions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `<module>.<resource>.<action>`, each with the narrowest scope that works and the roles that hold
+ * it by default. A workspace can add or remove any of them afterwards with a custom role.
+ *
+ * A key with nothing checking it is a role editor full of switches that do nothing, so these arrive
+ * with the procedures that enforce them — `custody.manage`, `repair.manage`, `category.manage`,
+ * `field.manage`, `value.view` and the stock and purchasing keys with their own phases.
+ */
+export declare const inventoryPermissions: readonly [{
+    readonly key: "inventory.asset.view";
+    readonly label: "View assets";
+    readonly scope: "workspace";
+    readonly defaultRoles: ["owner", "admin", "member", "guest"];
+    readonly dangerous: false;
+}, {
+    readonly key: "inventory.asset.manage";
+    readonly label: "Create and edit assets";
+    readonly scope: "workspace";
+    readonly defaultRoles: ["owner", "admin", "member"];
+    readonly dangerous: false;
+}];
+//# sourceMappingURL=permissions.d.ts.map

package/dist/contract/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/contract/permissions.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAe/B,CAAA"}

package/dist/contract/permissions.js

@@ -0,0 +1,26 @@
+import { definePermissions } from '@kernhq/contracts';
+/**
+ * `<module>.<resource>.<action>`, each with the narrowest scope that works and the roles that hold
+ * it by default. A workspace can add or remove any of them afterwards with a custom role.
+ *
+ * A key with nothing checking it is a role editor full of switches that do nothing, so these arrive
+ * with the procedures that enforce them — `custody.manage`, `repair.manage`, `category.manage`,
+ * `field.manage`, `value.view` and the stock and purchasing keys with their own phases.
+ */
+export const inventoryPermissions = definePermissions([
+    {
+        key: 'inventory.asset.view',
+        label: 'View assets',
+        scope: 'workspace',
+        defaultRoles: ['owner', 'admin', 'member', 'guest'],
+        dangerous: false,
+    },
+    {
+        key: 'inventory.asset.manage',
+        label: 'Create and edit assets',
+        scope: 'workspace',
+        defaultRoles: ['owner', 'admin', 'member'],
+        dangerous: false,
+    },
+]);
+//# sourceMappingURL=permissions.js.map

package/dist/contract/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/contract/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;IACpD;QACE,GAAG,EAAE,sBAAsB;QAC3B,KAAK,EAAE,aAAa;QACpB,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;QACnD,SAAS,EAAE,KAAK;KACjB;IACD;QACE,GAAG,EAAE,wBAAwB;QAC7B,KAAK,EAAE,wBAAwB;QAC/B,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;QAC1C,SAAS,EAAE,KAAK;KACjB;CACF,CAAC,CAAA"}