@kernhq/module-inventory 0.2.0 → 0.4.0

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,31 @@
 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,
+  MAX_LIVE_CATEGORIES,
+  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 +63,267 @@ 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),
+    /**
+     * The whole sequence, in the order somebody put it in — the only thing that writes `order`.
+     *
+     * **The ids, not positions.** A position number is a database column with a form around it: two
+     * categories can hold the same one, nobody thinks about their filing as integers, and the screen
+     * that asked for one had to explain how ties break. A list of ids says exactly what the person
+     * did, whatever they did it with — a drag, or the move-up and move-down buttons beside it.
+     *
+     * **It must name every live category the workspace has, exactly once.** A partial list is not
+     * treated as "leave the rest alone": somebody added a category in another tab while this page
+     * was open, and the ordering in hand no longer describes the workspace. Renumbering what it does
+     * name would drop the new one somewhere nobody chose, silently — so the whole call is refused
+     * with `inventory.category.order_stale` and the page reloads and asks again. Naming an archived
+     * category is the same mistake from the other side and gets the same answer; an id from another
+     * workspace is `NOT_FOUND`, exactly as `update` and `archive` answer for one.
+     *
+     * Answers the live sequence as it now stands, so a caller needs no second read.
+     *
+     * **The bound is `MAX_LIVE_CATEGORIES`, and it is the same number `create` refuses at.** A bound
+     * on this array with nothing enforcing it elsewhere is a silent ceiling: a workspace could grow
+     * past it one category at a time and then find that the only procedure that can order them is
+     * the one it can no longer call. Held to the same number at the point of creation, the array can
+     * always name every live category a workspace is allowed to have.
+     */
+    reorder: baseContract
+      .route({ method: 'POST', path: '/categories/reorder', tags: t })
+      .input(ws.extend({ categoryIds: z.array(z.uuid()).min(1).max(MAX_LIVE_CATEGORIES) }))
+      .output(z.array(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

package/src/contract/settings.ts

@@ -22,9 +22,29 @@ export const InventorySettings = z.object({
    */
   assetCodePrefix: z.string().max(8).default('INV-'),
   assetCodePad: z.number().int().min(1).max(10).default(4),
-  // `warrantyNoticeDays` used to sit here, describing a warranty sweep that has never existed —
-  // no job, no subscription, nothing reading the number. A setting nothing enforces is the same
-  // lie as a capability nothing checks: it teaches an administrator that the settings page does
-  // not mean anything. It comes back with the sweep.
+  /**
+   * How far ahead of a warranty running out somebody is told.
+   *
+   * This spent a release describing a sweep that did not exist — no job, no subscription, nothing
+   * reading the number — and was taken out for it. It is back because `warranty-sweep` reads it
+   * every morning: a live asset whose `warranty_until` falls inside this many days earns exactly
+   * one notice, marked on the row so the next morning does not send it again.
+   *
+   * A month by default, which is about how long it takes to decide whether to extend a warranty or
+   * budget for a replacement. Capped at a year: further out than that is not a notice, it is a
+   * report.
+   */
+  warrantyNoticeDays: z.number().int().min(1).max(365).default(30),
+  /**
+   * How long an item may be at a repairer before somebody is asked to chase it.
+   *
+   * Read by `repair-overdue`, which tells the person who logged the repair — and whoever is still
+   * holding the item — once, and then leaves them alone. Two weeks by default: long enough that an
+   * ordinary screen replacement never trips it, short enough that a laptop nobody chased does.
+   *
+   * A workspace with the `repairs` capability off never meets this: the sweep asks first, and a
+   * setting whose feature is switched off changes nothing rather than firing quietly.
+   */
+  repairOverdueDays: z.number().int().min(1).max(365).default(14),
 })
 export type InventorySettings = z.infer<typeof InventorySettings>

package/src/module.test.ts

@@ -11,6 +11,9 @@
  *
  * Add your module's real tests next to it; this one keeps working as the contract grows.
  */
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import type { Kernel } from '@kernhq/kernel'
 import { describe, expect, it } from 'vitest'
 import {
@@ -122,6 +125,40 @@ async function reachedFor(middleware: unknown): Promise<Reached> {
 
 const chainOf = (name: string): unknown[] => implemented[name]?.['~orpc'].middlewares ?? []
 
+/** What every implemented procedure's middleware chain reached for, resolved once. */
+async function resolveChains(): Promise<Record<string, Reached[]>> {
+  const entries = await Promise.all(
+    Object.keys(implemented).map(
+      async (name) => [name, await Promise.all(chainOf(name).map(reachedFor))] as const,
+    ),
+  )
+  return Object.fromEntries(entries)
+}
+
+/**
+ * Which of `names` the router does **not** put behind `capability`, in the right place.
+ *
+ * A pure function of the chains rather than an assertion inside a loop, so the check can be aimed at
+ * a chain this file builds by hand — which is the only way to show that it rejects what it claims
+ * to. An assertion that has never been seen to fail is a comment with a green tick beside it.
+ *
+ * Two ways to fail, and both matter: no capability gate at all, and a gate that sits *after* the
+ * permission check. The order is the whole point of `workspaceScoped` → `requiresCapability` →
+ * `requires`: a workspace with the module off must be refused before anything reveals which
+ * capabilities it would have had, and a workspace with the capability off must get 404 rather than
+ * the 403 a permission check would produce first.
+ */
+function ungated(capability: string, names: readonly string[], chains: Record<string, Reached[]>): string[] {
+  return names.filter((name) => {
+    const chain = chains[name] ?? []
+    const gate = chain.findIndex((r) => r.capability === `${MODULE_ID}.${capability}`)
+    const permission = chain.findIndex((r) => r.permission !== undefined)
+    // Index 0 is `workspaceScoped`'s place, so a gate there is a gate that displaced it.
+    if (gate < 1) return true
+    return permission !== -1 && gate > permission
+  })
+}
+
 describe('every procedure is authorised', () => {
   const declaredKeys = new Set(inventoryPermissions.map((p) => p.key))
 
@@ -168,15 +205,89 @@ describe('the module declares what it uses', () => {
  * Capabilities, which are the one thing here that cannot be seen by reading a handler.
  *
  * A missing `requiresCapability` is invisible: the procedure compiles, every other test passes, and
- * the only symptom is a workspace successfully calling a feature it switched off. So the map is
- * declared as data in the contract and checked against the router here.
+ * the only symptom is a workspace successfully calling a feature it switched off.
+ *
+ * **The expectation is derived from the contract, not opted into.** This used to check only the
+ * procedures named in `inventoryCapabilityProcedures` — so the map was both the claim and the
+ * evidence for it, and the regression it exists to catch walked straight past: add
+ * `repairs.cancel` to the contract, forget the middleware, forget the map, and every test here is
+ * green while a workspace with repairs switched off can call it. A list that has to be updated by
+ * the same person who forgot the thing it is guarding is not a guard.
  *
- * The map is empty while `core` is the only capability — `core` is `required`, so nothing sits
- * behind a switch anyone can flip. These tests are what keep that true as the map fills up.
+ * So the rule is read off the module's own declarations instead: **a switchable capability owns the
+ * router group named after it**, and every procedure in that group is gated on it. `repairs.*`
+ * belongs to `repairs`; `attachments.*` belongs to `attachments`. Adding a procedure to either group
+ * fails this file until it carries the middleware, whatever the map says. The map is still checked —
+ * it is what the client reads — but now against the group rather than against itself.
  */
 describe('capabilities are enforced where they are declared', () => {
   const gated = new Set(Object.values(inventoryCapabilityProcedures).flat())
 
+  /** The capabilities a workspace can actually switch: `core` is `required` and owns nothing. */
+  const switchable = inventoryCapabilities.filter((c) => !c.required).map((c) => c.id)
+
+  /** The contract's procedures under a capability's own name — the derived expectation. */
+  const groupOf = (capability: string) =>
+    Object.keys(declared)
+      .filter((name) => name.startsWith(`${capability}.`))
+      .sort()
+
+  it('gates every procedure in a switchable capability’s own group, named in the map or not', async () => {
+    const chains = await resolveChains()
+    for (const capability of switchable) {
+      expect(
+        groupOf(capability).length,
+        `${capability}: declared as a switch with no procedures behind it — a switch that changes nothing teaches an administrator that the switchboard does not mean anything`,
+      ).toBeGreaterThan(0)
+      expect(
+        ungated(capability, groupOf(capability), chains),
+        `these need requiresCapability('${MODULE_ID}', '${capability}') between the workspace gate and the permission check`,
+      ).toEqual([])
+    }
+  })
+
+  it('names that whole group in the map, so the client and the router cannot drift', () => {
+    // The client reads this map to decide what to hide; the router decides what to answer. A
+    // procedure gated in one and not the other is a tab that is there and 404s, or hidden and works.
+    for (const capability of switchable)
+      expect([...(inventoryCapabilityProcedures[capability] ?? [])].sort()).toEqual(groupOf(capability))
+  })
+
+  it('rejects an ungated procedure, and one gated in the wrong place', () => {
+    /**
+     * The assertion aimed at chains built here, because a check nobody has watched fail is a check
+     * nobody knows the shape of. Four procedures, one correct and three not, and `ungated` has to
+     * name exactly the three.
+     */
+    const chains: Record<string, Reached[]> = {
+      'repairs.list': [
+        { module: MODULE_ID },
+        { capability: `${MODULE_ID}.repairs` },
+        { permission: 'inventory.asset.view' },
+      ],
+      // The regression this file exists for: somebody added a procedure and no middleware.
+      'repairs.create': [{ module: MODULE_ID }, { permission: 'inventory.repair.manage' }],
+      // Gated, but after the permission — so a workspace with the capability off gets 403 from the
+      // permission check before the 404 that is the honest answer.
+      'repairs.update': [
+        { module: MODULE_ID },
+        { permission: 'inventory.repair.manage' },
+        { capability: `${MODULE_ID}.repairs` },
+      ],
+      // Gated on a different capability, which the identity check is what catches.
+      'repairs.complete': [
+        { module: MODULE_ID },
+        { capability: `${MODULE_ID}.attachments` },
+        { permission: 'inventory.repair.manage' },
+      ],
+    }
+    expect(ungated('repairs', Object.keys(chains), chains)).toEqual([
+      'repairs.create',
+      'repairs.update',
+      'repairs.complete',
+    ])
+  })
+
   it('names only capabilities the module actually declares', () => {
     const declaredIds = new Set(inventoryCapabilities.map((c) => c.id))
     for (const id of Object.keys(inventoryCapabilityProcedures))
@@ -210,3 +321,105 @@ describe('capabilities are enforced where they are declared', () => {
     expect(inventoryCapabilities.find((c) => c.id === 'core')?.required).toBe(true)
   })
 })
+
+/**
+ * The manifest's other declarations — the ones that are handlers rather than middleware.
+ *
+ * Every entry here is a promise to the rest of the product, and each has exactly one shape of lie
+ * available to it: an object type with no resolver renders a link to nothing, a search indexer for a
+ * type nobody declared indexes documents nothing can open, a notification type nothing sends is a
+ * row in everybody's preferences that changes nothing, and a job with no cron never runs. All four
+ * compile. `objectTypes` was removed from this module in 0.2.0 for precisely the first of them.
+ */
+describe('the platform surfaces the module declares', () => {
+  const objectTypes = inventoryModule.definition.objectTypes ?? []
+
+  it('backs every object type with a resolver and an indexer', () => {
+    const resolved = new Set((inventoryModule.resolvers ?? []).map((r) => r.type))
+    const indexed = new Set((inventoryModule.search ?? []).flatMap((s) => s.types))
+    for (const { type } of objectTypes)
+      expect({ type, resolved: resolved.has(type), indexed: indexed.has(type) }).toEqual({
+        type,
+        resolved: true,
+        indexed: true,
+      })
+  })
+
+  it('declares every type it resolves or indexes, so nothing points at an undeclared noun', () => {
+    const declared = new Set(objectTypes.map((o) => o.type))
+    for (const resolver of inventoryModule.resolvers ?? [])
+      expect({ type: resolver.type, declared: declared.has(resolver.type) }).toEqual({
+        type: resolver.type,
+        declared: true,
+      })
+    for (const type of (inventoryModule.search ?? []).flatMap((s) => s.types))
+      expect({ type, declared: declared.has(type) }).toEqual({ type, declared: true })
+  })
+
+  it('offers a full reindex as well as a single load', () => {
+    // Without `scan`, `core.search.reindex` walks this module and finds nothing to do — silently,
+    // which is the worst way for a repair mechanism to be missing.
+    for (const indexer of inventoryModule.search ?? [])
+      expect({ types: indexer.types, scan: typeof indexer.scan }).toEqual({
+        types: indexer.types,
+        scan: 'function',
+      })
+  })
+
+  it('gives every scheduled job a name of its own and a schedule', () => {
+    const jobs = inventoryModule.jobs ?? []
+    expect(jobs.length, 'a module with sweeps declares them').toBeGreaterThan(0)
+    expect(new Set(jobs.map((j) => j.name)).size, 'two jobs sharing a name share a queue').toBe(jobs.length)
+    // Every job this module has is a sweep; one without a cron would be a queue nothing enqueues.
+    for (const job of jobs)
+      expect({ job: job.name, cron: typeof job.cron }).toEqual({ job: job.name, cron: 'string' })
+  })
+
+  it('names every notification type under its own module id', () => {
+    for (const type of inventoryModule.definition.notificationTypes ?? [])
+      expect(type.type.startsWith(`${MODULE_ID}.`), type.type).toBe(true)
+  })
+
+  /**
+   * A notification type nothing sends is the same lie as a permission nothing checks — and unlike a
+   * permission there is no middleware to inspect, so this reads the server for the string.
+   *
+   * Crude on purpose, and honest about it: it proves the *literal* appears in a file that sends
+   * notifications, not that the branch is reachable. A type whose key was built by concatenation
+   * would slip past it. Every one of this module's four is a literal at its call site, and keeping
+   * them that way is the point — a notification type assembled at runtime is one nobody can grep
+   * for either.
+   */
+  it('has a sender in the server for every notification type it declares', () => {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const sources = readdirSync(join(here, 'server'), { recursive: true, encoding: 'utf8' })
+      .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+      .map((f) => readFileSync(join(here, 'server', f), 'utf8'))
+      .join('\n')
+    for (const { type } of inventoryModule.definition.notificationTypes ?? [])
+      expect({ type, sent: sources.includes(`'${type}'`) }).toEqual({ type, sent: true })
+  })
+
+  /**
+   * The client manifest's `name` is read on screen, so it has to be a getter over `t`.
+   *
+   * The dashboard's widget picker heads this module's group with `mod.name` directly, and the shell's
+   * settings rail falls back to it for a module whose navigation it cannot read — so an English
+   * literal there is a Latin word sitting in an otherwise Persian panel. `name` is typed as a plain
+   * `string` on `ClientModule`, which is exactly why nothing else catches this: a literal and a
+   * getter are the same type.
+   *
+   * Read as text rather than imported, and honest about being crude. `src/client/module.ts` reaches
+   * `@kernhq/ui`, which drags a Svelte compiler into whatever imports it, and this package's vitest
+   * runs plain Node — the same reason `errors.ts` and `messages.ts` are kept importable and the
+   * components are not. It proves the shape, not the rendering.
+   */
+  it('gives the client manifest a translated name rather than an English literal', () => {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const source = readFileSync(join(here, 'client', 'module.ts'), 'utf8')
+    expect(source, 'a getter, so the language is the one on screen at read time').toMatch(
+      /get name\(\)\s*\{\s*return t\('nav'\)/,
+    )
+    expect(source, 'and no literal left beside it').not.toMatch(/^\s*name: '/m)
+  })
+})