@kernhq/module-inventory 0.2.0 → 0.3.0

package/src/contract/index.ts

@@ -10,6 +10,7 @@
 export * from './capabilities.js'
 export * from './events.js'
 export * from './models.js'
+export * from './notifications.js'
 export * from './permissions.js'
 export * from './router.js'
 export * from './settings.js'

package/src/contract/models.ts

@@ -18,6 +18,12 @@ export const MODULE_ID = 'inventory'
  *
  * 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.
+ *
+ * **`under_repair` belongs to the `repairs` capability**, so a workspace with that switch off never
+ * has an asset in it: the procedure that ends a repair answers 404 there, and a status nothing can
+ * move an item out of is a register the workspace cannot correct. The one thing a job does here is
+ * bring the rows *nobody touches* back into step after that switch moves, in both directions —
+ * `deriveStatus` in `src/server/services/status.ts` argues it, and nothing is destroyed either way.
  */
 export const AssetStatus = z.enum(['in_stock', 'assigned', 'reserved', 'under_repair', 'lost', 'retired'])
 export type AssetStatus = z.infer<typeof AssetStatus>
@@ -32,6 +38,86 @@ export type AssetStatus = z.infer<typeof AssetStatus>
 export const CustomValues = z.record(z.string(), z.unknown())
 export type CustomValues = z.infer<typeof CustomValues>
 
+/**
+ * A workspace's own grouping of what it owns — Laptops, Furniture, Cameras.
+ *
+ * Archived rather than deleted, and `archivedAt` is the whole reason: `assets.category_id` is a
+ * plain uuid with no foreign key, so a deleted category leaves every asset filed under it pointing
+ * at a row that is not there. The list column goes blank and the timeline entry that recorded the
+ * move loses the name it recorded. Archiving takes it out of every picker and every filter and
+ * leaves each asset able to say what it is.
+ */
+export const Category = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  name: z.string().min(1).max(120),
+  /** Where it sits in a picker. Equal orders fall back to the name, so a workspace that never
+   *  reorders anything still gets an alphabetical list rather than an arbitrary one. */
+  order: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  archivedAt: z.string().nullable(),
+})
+export type Category = z.infer<typeof Category>
+
+export const CategoryInput = z.object({
+  name: z.string().trim().min(1).max(120),
+  order: z.number().int().min(0).max(9999).optional(),
+})
+export type CategoryInput = z.infer<typeof CategoryInput>
+
+/**
+ * One stretch of time during which one person held one asset.
+ *
+ * Effective-dated, exactly as HR keeps employments: nothing is ever updated in place, a change
+ * closes the open row and inserts a new one. `effectiveTo === null` means "still holding it", and
+ * `inventory_custody_no_overlap` — a GiST exclusion constraint on
+ * `(asset_id =, tstzrange(effective_from, effective_to, '[)') &&)` — makes two of those for one
+ * asset impossible in the database rather than merely unlikely in the service.
+ */
+export const CustodyPeriod = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  /**
+   * The member who held it. A plain uuid — a cross-schema foreign key is what the module boundary
+   * exists to prevent — resolved against core membership at read time, which is also why a person
+   * who has since left the workspace still has readable history.
+   */
+  userId: z.uuid(),
+  note: z.string().max(500).nullable(),
+  effectiveFrom: z.string(),
+  effectiveTo: z.string().nullable(),
+  /** Who did the handing over, which is not always who received it. */
+  createdBy: z.uuid().nullable(),
+  createdAt: z.string(),
+})
+export type CustodyPeriod = z.infer<typeof CustodyPeriod>
+
+/**
+ * One entry in an asset's timeline.
+ *
+ * `action` is a **plain string, deliberately not an enum**. The rows are append-only and outlive
+ * the image that wrote them: an instance rolled back to a previous release would fail to parse its
+ * own history the moment a newer image had written an action the older enum does not list — a
+ * timeline that 500s rather than one that says a little less. The client renders a sentence per
+ * action it knows and a neutral one for anything else. What is written today is `created`,
+ * `updated`, `assigned`, `transferred`, `returned`, `retired`, `restored`, `repair_logged`,
+ * `repair_completed`, `attachment_added` and `attachment_removed`.
+ */
+export const AssetHistoryEntry = z.object({
+  id: z.uuid(),
+  assetId: z.uuid(),
+  /** Null for anything the platform did rather than a person. */
+  actorId: z.uuid().nullable(),
+  action: z.string().max(40),
+  changes: z.array(z.object({ field: z.string(), from: z.unknown(), to: z.unknown() })),
+  /** Action-specific ids — who received an item, who handed it over. Never a row. */
+  data: z.record(z.string(), z.unknown()),
+  occurredAt: z.string(),
+})
+export type AssetHistoryEntry = z.infer<typeof AssetHistoryEntry>
+
 export const Asset = z.object({
   id: z.uuid(),
   workspaceId: WorkspaceId,
@@ -63,6 +149,157 @@ export const Asset = z.object({
 })
 export type Asset = z.infer<typeof Asset>
 
+/**
+ * What a custody procedure answers with: the asset as it now stands, and the period this call
+ * opened.
+ *
+ * Both, because a screen needs both and fetching the asset again afterwards is a second round trip
+ * that can read a row somebody else has changed in between — the panel would then show a handover
+ * that has already been undone. `period` is null on a return: something closed, nothing opened.
+ */
+export const CustodyResult = z.object({
+  asset: Asset,
+  period: CustodyPeriod.nullable(),
+})
+export type CustodyResult = z.infer<typeof CustodyResult>
+
+/**
+ * One trip an item made to a repairer.
+ *
+ * `returnedOn === null` means it is still away, and that single fact is what puts the asset in
+ * `under_repair` — see `deriveStatus` in `src/server/services/status.ts`, which is the only place
+ * the three columns that drive a status are read together.
+ *
+ * **A repair is not custody, and neither one cancels the other.** A laptop assigned to Dan that goes
+ * to the repairer is still Dan's responsibility: the custody period stays open, `custodianUserId`
+ * stays set, and only `status` moves. That is why a repair does not touch custody and custody does
+ * not refuse a repaired item — the two answer different questions ("who is answerable for it" and
+ * "where is it"), and collapsing them would mean an item could not come back to the person who sent
+ * it.
+ */
+export const Repair = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  summary: z.string().min(1).max(200),
+  detail: z.string().max(4000).nullable(),
+  vendor: z.string().max(200).nullable(),
+  /** Minor units, like `Asset.priceMinor` — one convention for money across the module. */
+  costMinor: z.number().int().nullable(),
+  currency: z.string().length(3).nullable(),
+  sentOn: z.string(),
+  /** Null while it is still away. Set by `repairs.complete` and by nothing else. */
+  returnedOn: z.string().nullable(),
+  createdBy: z.uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+})
+export type Repair = z.infer<typeof Repair>
+
+/**
+ * A repair in a list, with the two things a reader needs to know *which item* it is about.
+ *
+ * **Joined at read time, never stored here.** `mod_inventory.repairs` holds no asset name, so
+ * renaming an asset renames it everywhere at once — a copied label is a label that goes stale, and
+ * this module already refuses to copy a person's name for the same reason. The join is inside one
+ * schema, which is the kind a module is allowed to make; the kind it is not is a join across the
+ * boundary into another module's tables.
+ *
+ * It extends `Repair` rather than replacing it, so a component that renders a repair renders one of
+ * these without knowing the difference. `create`, `update` and `complete` answer with a plain
+ * `Repair`: the caller of those already knows which asset it asked about.
+ */
+export const RepairListItem = Repair.extend({
+  assetCode: z.string().min(1).max(40),
+  assetName: z.string().min(1).max(200),
+})
+export type RepairListItem = z.infer<typeof RepairListItem>
+
+/**
+ * Everything a person can say about a repair.
+ *
+ * **No field here carries `.default()`, for the reason `AssetInput` spells out**: `update` is built
+ * from `.partial()`, and `.partial()` does not strip a default — zod still substitutes it for a key
+ * the request never sent, so a patch that renames a repair would silently re-date it. `sentOn` is
+ * optional rather than defaulted for the same reason; `repairs.create` fills today's date on the
+ * server, which is the only clock this module trusts.
+ */
+export const RepairInput = z.object({
+  summary: z.string().trim().min(1).max(200),
+  detail: z.string().max(4000).nullish(),
+  vendor: z.string().max(200).nullish(),
+  costMinor: z.number().int().min(0).nullish(),
+  currency: z.string().length(3).nullish(),
+  /** `sent_on` is `not null` in the database, so this is optional but never nullable. */
+  sentOn: z.iso.date().optional(),
+})
+export type RepairInput = z.infer<typeof RepairInput>
+
+export const RepairPatchInput = RepairInput.partial()
+export type RepairPatchInput = z.infer<typeof RepairPatchInput>
+
+/**
+ * What a repair mutation answers with: the repair, and the asset as it now stands.
+ *
+ * Both, for the reason `CustodyResult` carries both — sending an item away moves `assets.status`,
+ * and a screen that had to fetch the asset again afterwards would be reading a row somebody else
+ * may have changed in between.
+ */
+export const RepairResult = z.object({
+  repair: Repair,
+  asset: Asset,
+})
+export type RepairResult = z.infer<typeof RepairResult>
+
+/**
+ * A file recorded against an asset — a receipt, a warranty card, a manual.
+ *
+ * **The bytes are core's, not this module's.** A module does not upload: the browser uploads through
+ * core's file service and hands this module the id it was given, and reading one back is a download
+ * URL core signs. All that lives here is the fact that this asset has that file, plus the name and
+ * size copied at attach time so a list can be drawn without asking core once per row.
+ *
+ * `repairId` is what separates "the invoice for the screen replacement" from "the purchase receipt":
+ * null means it belongs to the asset itself.
+ */
+export const Attachment = z.object({
+  id: z.uuid(),
+  workspaceId: WorkspaceId,
+  assetId: z.uuid(),
+  repairId: z.uuid().nullable(),
+  fileId: z.uuid(),
+  name: z.string().max(300),
+  mimeType: z.string().max(200).nullable(),
+  /** Bytes, as core reported them when the file was attached. */
+  size: z.number().int().nullable(),
+  uploadedBy: z.uuid().nullable(),
+  createdAt: z.string(),
+})
+export type Attachment = z.infer<typeof Attachment>
+
+/**
+ * The register in numbers: what a page's count line and a dashboard card need in one request.
+ *
+ * `total` counts what the list shows by default — live rows — and `archived` is beside it rather
+ * than inside it, because a count line that silently included archived rows would disagree with the
+ * list under it.
+ *
+ * **`outForRepair` is null when the workspace does not track repairs.** Zero would be a claim
+ * ("nothing is away"), and a workspace with the `repairs` capability off has not made that claim —
+ * it has no opinion at all. The screens show the tile only when a number arrives, which is the same
+ * rule as hiding the Repairs tab, expressed in the data instead of in a second capability lookup.
+ */
+export const InventoryStats = z.object({
+  total: z.number().int().nonnegative(),
+  archived: z.number().int().nonnegative(),
+  /** Every status, zero-filled, so a screen can render the set without knowing which exist. */
+  byStatus: z.record(AssetStatus, z.number().int().nonnegative()),
+  outForRepair: z.number().int().nonnegative().nullable(),
+  /** Live assets nobody is holding — what is actually available to hand out. */
+  unassigned: z.number().int().nonnegative(),
+})
+export type InventoryStats = z.infer<typeof InventoryStats>
+
 /**
  * How a list is ordered, and therefore what a page cursor is a bookmark *into*.
  *

package/src/contract/notifications.ts

@@ -0,0 +1,73 @@
+import type { core } from '@kernhq/contracts'
+
+/**
+ * What Inventory will interrupt somebody about.
+ *
+ * Four things, and each of them changes what somebody has to *do*. That is the test: a rename, a new
+ * category, an item coming back — those are facts a screen shows when somebody looks, and a
+ * notification type nobody wants is a notification type everybody switches off along with the one
+ * that mattered.
+ *
+ * A type declared here and never sent is the same lie as a permission nothing checks. Each of these
+ * names its sender, and every one of them exists:
+ *
+ * - `custody.assigned` — `CustodyService`, on `assign` and `transfer`.
+ * - `warranty.expiring` — the `warranty-sweep` job, once per asset.
+ * - `repair.overdue` — the `repair-overdue` job, once per repair.
+ * - `custody.return_due` — the offboarding subscription, when HR says somebody has left or core says
+ *   they have been removed from the workspace.
+ *
+ * The keys keep their `inventory.custody.*` spelling rather than being renamed to
+ * `inventory.asset.*`: a notification type is the key a person's own preferences are stored under,
+ * so renaming one silently resets everybody who had switched it off.
+ */
+export const inventoryNotificationTypes: core.NotificationTypeDef[] = [
+  {
+    /**
+     * Everybody who has ever found a laptop on their desk with no idea it was now theirs is the
+     * reason this is `urgent` and reaches email — an asset register that records a handover the
+     * recipient never learns about has recorded an argument for later.
+     */
+    type: 'inventory.custody.assigned',
+    label: 'An item was handed to you',
+    description: 'Somebody made you the holder of an asset in the register.',
+    defaults: { inapp: true, push: true, email: true },
+    urgent: true,
+  },
+  {
+    /**
+     * Not urgent, and email is off by default. A warranty running out in a month is a thing to plan
+     * for, not a thing to stop for — and it arrives on a schedule rather than because somebody did
+     * something, which is exactly the kind of message that trains people to ignore the rest.
+     */
+    type: 'inventory.warranty.expiring',
+    label: 'A warranty is about to run out',
+    description: "An item's warranty expires soon. Sent once per item, to whoever is holding it.",
+    defaults: { inapp: true, push: false, email: false },
+    urgent: false,
+  },
+  {
+    /**
+     * Push, because this one is an action somebody has to take — ring the repairer — and nobody
+     * goes looking for it. Still not urgent: a laptop that has been away a fortnight can wait until
+     * the phone is picked up.
+     */
+    type: 'inventory.repair.overdue',
+    label: 'A repair has been away too long',
+    description: 'An item sent for repair has not been logged as returned. Sent once per repair.',
+    defaults: { inapp: true, push: true, email: false },
+    urgent: false,
+  },
+  {
+    /**
+     * Somebody is leaving and still has company property. Email, because it is a list of things to
+     * collect from a person who may not be at their desk much longer, and an in-app badge nobody
+     * opens until Monday is how a laptop leaves the building.
+     */
+    type: 'inventory.custody.return_due',
+    label: 'Somebody leaving still holds company property',
+    description: 'A member has left, or is leaving, and items are still recorded as theirs.',
+    defaults: { inapp: true, push: true, email: true },
+    urgent: true,
+  },
+]

package/src/contract/permissions.ts

@@ -5,8 +5,19 @@ import { definePermissions } from '@kernhq/contracts'
  * 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.
+ * with the procedures that enforce them — `field.manage` and the stock and purchasing keys with
+ * their own phases.
+ *
+ * **Reading custody is `asset.view`, and that is a decision rather than an omission.** Who holds an
+ * item looks like a privacy question, and it is not one here: `custodianUserId` and `custodySince`
+ * are fields of `Asset`, returned by `assets.list` and `assets.get` under `asset.view` since the
+ * module existed, and `assets.list` has always taken a `custodianUserId` filter. A separate
+ * `custody.view` would be a lock on a door beside an open window — it would refuse the timeline
+ * while the row above it named the same person. "Who has the projector" is also the question an
+ * asset register exists to answer; a company where a member cannot find that out asks in chat
+ * instead, which is worse for whoever is holding it. A workspace that disagrees takes
+ * `inventory.asset.view` off `guest`, which is one switch and already there. Writing custody is
+ * `custody.manage`, because handing an item over makes somebody answerable for it.
  */
 export const inventoryPermissions = definePermissions([
   {
@@ -23,4 +34,46 @@ export const inventoryPermissions = definePermissions([
     defaultRoles: ['owner', 'admin', 'member'],
     dangerous: false,
   },
+  {
+    /**
+     * Not `asset.manage`: correcting a serial number and making a colleague answerable for a
+     * £2,000 laptop are different acts, and plenty of workspaces want the first from everybody and
+     * the second from the office manager. Held by `member` by default all the same — an office
+     * where only an admin may hand over a charger keeps its register by not using it.
+     */
+    key: 'inventory.custody.manage',
+    label: 'Hand assets over and take them back',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    /**
+     * Sending an item away and recording what it cost, held by `member` for the same reason
+     * `custody.manage` is: the person who notices a broken screen is the person who should be able
+     * to log it, and an office where only an admin may do that keeps its repair record by not
+     * keeping one. Reading repairs rides `asset.view` — "where is the projector" is the question
+     * the register exists to answer, and a repair is one of the two answers.
+     *
+     * Not folded into `asset.manage`: correcting a serial number and committing the company to a
+     * £400 screen replacement are different acts, and the money is why.
+     */
+    key: 'inventory.repair.manage',
+    label: 'Log repairs',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  {
+    /**
+     * Categories are workspace configuration — one list everybody's assets are filed against — so
+     * this sits with the people who set the workspace up rather than with everybody who may edit an
+     * asset. Reading them rides `asset.view`, because the picker on the asset form needs them.
+     */
+    key: 'inventory.category.manage',
+    label: 'Manage asset categories',
+    scope: 'workspace',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: false,
+  },
 ])

package/src/contract/router.ts

@@ -1,9 +1,30 @@
 import { baseContract, PageInput, page } from '@kernhq/contracts'
 import { z } from 'zod'
-import { Asset, AssetCreateInput, AssetPatchInput, AssetSort, AssetStatus, ws } from './models.js'
+import {
+  Asset,
+  AssetCreateInput,
+  AssetHistoryEntry,
+  AssetPatchInput,
+  AssetSort,
+  AssetStatus,
+  Attachment,
+  Category,
+  CategoryInput,
+  CustodyPeriod,
+  CustodyResult,
+  InventoryStats,
+  RepairInput,
+  RepairListItem,
+  RepairPatchInput,
+  RepairResult,
+  ws,
+} from './models.js'
 
 const t = ['inventory'] as const
 
+/** A handover note is optional everywhere and shaped the same everywhere. */
+const custodyNote = z.string().max(500).nullish()
+
 export const inventoryContract = {
   assets: {
     list: baseContract
@@ -41,6 +62,239 @@ export const inventoryContract = {
       .route({ method: 'POST', path: '/assets/{assetId}/archive', tags: t })
       .input(ws.extend({ assetId: z.uuid(), archived: z.boolean().default(true) }))
       .output(Asset),
+    /**
+     * The asset's own timeline, newest first.
+     *
+     * Paged with the same keyset discipline `assets.list` uses and the same cursor codec, because a
+     * second bookmark format is a second set of the three bugs the first one had. The bookmark is a
+     * row id; the ordering is by id, which for a uuidv7 is the clock and, unlike `created_at`, is
+     * unique — two entries written in one transaction (a create and its first custody row) share a
+     * timestamp and a page boundary between them would repeat or drop one.
+     *
+     * Reads on `inventory.asset.view`. See `permissions.ts` for why custody is not gated separately.
+     */
+    history: baseContract
+      .route({ method: 'GET', path: '/assets/{assetId}/history', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), ...PageInput.shape }))
+      .output(page(AssetHistoryEntry)),
+  },
+
+  /**
+   * Who is holding what.
+   *
+   * Four verbs rather than one, because "hand it to somebody" and "hand it on to somebody else" are
+   * different questions with different failure modes: assigning something already out is a mistake
+   * worth refusing, and transferring something nobody holds is a different mistake. One procedure
+   * taking `userId | null` would answer both by silently doing whatever the row happened to allow.
+   */
+  custody: {
+    /** Hand a free item to a member. Refuses if somebody already has it — that is `transfer`. */
+    assign: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/custody', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), userId: z.uuid(), note: custodyNote }))
+      .output(CustodyResult),
+    /** Take it back. Closes the open period and puts the asset back in stock. */
+    return: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/custody/return', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), note: custodyNote }))
+      .output(CustodyResult),
+    /**
+     * Hand it straight on: one transaction, not a return followed by an assign.
+     *
+     * Two calls would leave the asset `in_stock` with no custodian in between — visible to anybody
+     * reading the list at that moment, and permanently visible in the timeline as a return that
+     * nobody performed.
+     */
+    transfer: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/custody/transfer', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), userId: z.uuid(), note: custodyNote }))
+      .output(CustodyResult),
+    /**
+     * Every period for one asset, newest first — "who had this laptop before me".
+     *
+     * An array rather than a page, like HR's `employment.history`: the rows are bounded by how many
+     * times one item changed hands, which is tens over its life. `limit` caps it rather than
+     * paging, so the answer is never unbounded and the caller never has a cursor to keep.
+     */
+    history: baseContract
+      .route({ method: 'GET', path: '/assets/{assetId}/custody', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), limit: z.number().int().min(1).max(200).default(100) }))
+      .output(z.array(CustodyPeriod)),
+    /**
+     * What one person is holding right now.
+     *
+     * Answered from `assets.custodian_user_id` — denormalised inside the same transaction that
+     * writes the period, and indexed — rather than from an open-period join, so the offboarding
+     * question ("what does Ada still have?") is one indexed read.
+     */
+    byUser: baseContract
+      .route({ method: 'GET', path: '/custody/by-user/{userId}', tags: t })
+      .input(ws.extend({ userId: z.uuid(), ...PageInput.shape }))
+      .output(page(Asset)),
+  },
+
+  /**
+   * How a workspace groups what it owns.
+   *
+   * Not paged: a workspace has tens of categories, and every one of them has to be in the picker
+   * anyway. A cursor here would be a page boundary in a dropdown.
+   */
+  categories: {
+    list: baseContract
+      .route({ method: 'GET', path: '/categories', tags: t })
+      .input(ws.extend({ archived: z.boolean().default(false) }))
+      .output(z.array(Category)),
+    create: baseContract
+      .route({ method: 'POST', path: '/categories', tags: t })
+      .input(ws.extend(CategoryInput.shape))
+      .output(Category),
+    update: baseContract
+      .route({ method: 'PATCH', path: '/categories/{categoryId}', tags: t })
+      .input(ws.extend({ categoryId: z.uuid(), ...CategoryInput.partial().shape }))
+      .output(Category),
+    /**
+     * Archive, not delete — and the same procedure restores.
+     *
+     * `assets.category_id` carries no foreign key, so a delete would leave every asset filed under
+     * it pointing at nothing: a blank column, and a timeline entry that recorded the move losing
+     * the name it recorded. Archiving is reversible and destroys nothing.
+     */
+    archive: baseContract
+      .route({ method: 'POST', path: '/categories/{categoryId}/archive', tags: t })
+      .input(ws.extend({ categoryId: z.uuid(), archived: z.boolean().default(true) }))
+      .output(Category),
+  },
+
+  /**
+   * What went away to be fixed.
+   *
+   * **Behind the `repairs` capability**, which is this module's first switchable one — so every
+   * procedure here answers **404** rather than 403 in a workspace that has it off. 403 would say
+   * "this exists and you may not have it", which is false for a company that does not record
+   * repairs, and it would contradict a panel that has already hidden the tab.
+   *
+   * Writing takes `inventory.repair.manage`; reading rides `inventory.asset.view`, for the reason
+   * custody does — "where is the projector" is the question the register exists to answer.
+   */
+  repairs: {
+    /**
+     * One asset's repairs, or the whole workspace's — the same procedure, because they are the same
+     * query with one filter and a second one would be a second thing to keep in step.
+     *
+     * `open: true` is the "what is away right now" question a dashboard card asks, and it is a
+     * filter rather than a procedure of its own for the same reason.
+     *
+     * Paged, unlike `custody.history`: one asset's repairs are bounded by how often it breaks, but
+     * a workspace's are not. Ordered newest-logged first, by row id — a uuidv7 already carries the
+     * clock and is unique, where `sent_on` is a date two repairs logged the same day share.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/repairs', tags: t })
+      .input(
+        ws.extend({
+          ...PageInput.shape,
+          assetId: z.uuid().optional(),
+          /** `true` for still away, `false` for finished, absent for both. */
+          open: z.boolean().optional(),
+        }),
+      )
+      .output(page(RepairListItem)),
+    /**
+     * Send it away. Refuses when the item is already at a repairer — one open repair per asset, and
+     * `inventory_repairs_one_open_uq` is what makes that true in the database rather than merely
+     * likely in the service.
+     *
+     * `sentOn` is optional and defaults to today **on the server**: a browser clock is not a fact
+     * this module is willing to record, and the same reasoning already keeps asset tags server-side.
+     */
+    create: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/repairs', tags: t })
+      .input(ws.extend({ assetId: z.uuid(), ...RepairInput.shape }))
+      .output(RepairResult),
+    /**
+     * Correct what was recorded — a vendor, a cost that arrived with the invoice a week later.
+     *
+     * Deliberately cannot set `returnedOn`: that one column decides whether the asset reads as
+     * `under_repair`, so exactly one procedure moves it and the derived status has one door rather
+     * than two.
+     */
+    update: baseContract
+      .route({ method: 'PATCH', path: '/repairs/{repairId}', tags: t })
+      .input(ws.extend({ repairId: z.uuid(), ...RepairPatchInput.shape }))
+      .output(RepairResult),
+    /**
+     * It came back. Closes the repair and puts the asset back to `assigned` if somebody still holds
+     * it, or `in_stock` if nobody does — never blindly to `in_stock`, which would quietly release
+     * whoever is answerable for it.
+     *
+     * Takes the cost, because that is when the invoice usually arrives.
+     */
+    complete: baseContract
+      .route({ method: 'POST', path: '/repairs/{repairId}/complete', tags: t })
+      .input(
+        ws.extend({
+          repairId: z.uuid(),
+          returnedOn: z.iso.date().optional(),
+          costMinor: z.number().int().min(0).nullish(),
+          currency: z.string().length(3).nullish(),
+        }),
+      )
+      .output(RepairResult),
+  },
+
+  /**
+   * Receipts, warranties, manuals — and the asset's photo, which is an `Asset` field rather than one
+   * of these.
+   *
+   * **Behind the `attachments` capability**, so these answer 404 in a workspace that has it off.
+   *
+   * **A module does not upload.** The browser sends the bytes to core's file service and hands this
+   * module the id core gave it; `add` records that this asset has that file. Nothing here streams,
+   * signs or stores anything, and `remove` detaches rather than deleting core's file — the same
+   * bytes may be attached elsewhere, and a module has no standing to destroy another module's row.
+   */
+  attachments: {
+    /**
+     * Every file on one asset, its repairs' included, each carrying its own `repairId`.
+     *
+     * Not paged and not filtered by repair: one asset's files are bounded and entirely loaded, so
+     * the panel groups them in the browser. That is the one case where filtering client-side is
+     * right, and it is the opposite of what `assets.list` may do.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/assets/{assetId}/attachments', tags: t })
+      .input(ws.extend({ assetId: z.uuid() }))
+      .output(z.array(Attachment)),
+    /** Attach files core already holds. `repairId` files them under one repair instead of the asset. */
+    add: baseContract
+      .route({ method: 'POST', path: '/assets/{assetId}/attachments', tags: t })
+      .input(
+        ws.extend({
+          assetId: z.uuid(),
+          fileIds: z.array(z.uuid()).min(1).max(20),
+          repairId: z.uuid().nullish(),
+        }),
+      )
+      .output(z.array(Attachment)),
+    /** Answers with the id it detached, so a client can drop exactly that row without re-reading. */
+    remove: baseContract
+      .route({ method: 'DELETE', path: '/attachments/{attachmentId}', tags: t })
+      .input(ws.extend({ attachmentId: z.uuid() }))
+      .output(z.object({ id: z.uuid() })),
+  },
+
+  /**
+   * The register in numbers.
+   *
+   * One procedure rather than a `total` on `assets.list`, because they answer different questions:
+   * a list's total describes the filter you asked for, and this describes the workspace. The assets
+   * page needs both — "showing 50 of 214" is two numbers from two places.
+   *
+   * Not behind a capability: it counts assets, which is `core`. `outForRepair` comes back null
+   * rather than 0 where `repairs` is off — see `InventoryStats`.
+   */
+  stats: {
+    summary: baseContract.route({ method: 'GET', path: '/stats', tags: t }).input(ws).output(InventoryStats),
   },
 }
 export type InventoryContract = typeof inventoryContract