@kernhq/module-inventory 0.1.2 → 0.3.0

package/src/client/timeline.ts

@@ -0,0 +1,206 @@
+/**
+ * Turning a stored history row into something a person reads.
+ *
+ * `asset_history` holds `{ action, changes: [{field, from, to}], data: {…ids} }`, which is a shape
+ * for a database and not a sentence. A panel that renders it raw shows somebody a JSON diff of
+ * their own laptop; the point of a timeline is that it reads as "Ada handed it to Bruno".
+ *
+ * **"it", not the asset tag** — and this note exists because the README claimed otherwise for a
+ * release. The timeline only ever appears inside that asset's own panel, under a header already
+ * showing `INV-0042`, so naming the tag in all fifty entries would repeat on every line the one
+ * thing that cannot change while somebody is reading it.
+ *
+ * The decisions live here rather than inside the component for the reason `price.ts` does: a
+ * `.svelte` file drags a compiler behind it and cannot be unit-tested, and every one of these is a
+ * fact with a right answer. The component supplies the words — this file only says which words and
+ * about whom.
+ *
+ * Nothing here imports `@kernhq/ui`. That entry point reaches the Svelte components, and a helper
+ * that pulls a compiler into whatever imports it is a helper nothing can test.
+ */
+
+/** Every action this client knows how to phrase. Anything else is honest about not knowing. */
+const KNOWN = new Set([
+  'created',
+  'updated',
+  'assigned',
+  'transferred',
+  'returned',
+  'retired',
+  'restored',
+  'repair_logged',
+  'repair_completed',
+  'attachment_added',
+  'attachment_removed',
+])
+
+/**
+ * The message key for one entry's headline.
+ *
+ * An unknown action is **not** silently rendered as "changed it". The rows outlive the client that
+ * reads them: repairs and attachments write their own actions, and a browser tab left open across
+ * a deploy will meet one. `history_unknown` says somebody changed it and names the action, which is
+ * honest about the gap; a generic "changed it" would quietly describe a repair as an edit for as
+ * long as the tab stayed open.
+ */
+export function actionKey(action: string): string {
+  return KNOWN.has(action) ? `history_${action}` : 'history_unknown'
+}
+
+export const isKnownAction = (action: string): boolean => KNOWN.has(action)
+
+/**
+ * Which sentence a single field change wants.
+ *
+ * "from nothing to Desk 4" is not a change a person recognises — they filled a field in. The three
+ * shapes are the three sentences: filled in, cleared, and moved from one value to another.
+ *
+ * An empty string counts as absent, because that is what the asset form writes for a field somebody
+ * emptied: `description` is `not null` in the database, so clearing it stores `''` and never
+ * `null`, and `'' → 'x'` reported as "changed from  to x" is a sentence with a hole in it.
+ */
+export type ChangeShape = 'set' | 'cleared' | 'changed'
+
+const absent = (value: unknown): boolean => value === null || value === undefined || value === ''
+
+export function changeShape(from: unknown, to: unknown): ChangeShape {
+  if (absent(to)) return 'cleared'
+  if (absent(from)) return 'set'
+  return 'changed'
+}
+
+/**
+ * Who did it is `resolveName` in `members.ts`, and deliberately not here.
+ *
+ * This file used to carry an `actorKind(actorId, known)` that answered `person`, `former` or
+ * `system` from a bare set of ids. It was a second implementation of a question `members.ts`
+ * already answers, and it made the same mistake `nameOf` did: a set that has not been fetched yet
+ * is indistinguishable from a set somebody has left, so an id absent from it came back as `former`
+ * while the request was still in flight. A set cannot say which — only the request's own state can
+ * — so the question belongs where the directory is, with the five answers `NameKind` names.
+ */
+
+/**
+ * The message key naming a field, for the one sentence per change.
+ *
+ * A stored diff names its column (`serialNumber`, `warrantyUntil`), which is a word for a database
+ * and not for a reader — «warrantyUntil از ۲۰۲۷ به ۲۰۲۸ تغییر کرد» is English leaking into a Persian
+ * sentence in exactly the place a translation was supposed to be. The map is the whole of
+ * `AssetInput`, and `timeline.test.ts` holds it to that: a field added to the contract with no key
+ * here shows up as a failing test rather than as a column name on somebody's screen.
+ *
+ * `null` for a field this client has never heard of. The rows outlive the image that wrote them, so
+ * a browser tab open across a deploy will meet one, and the component prints the raw name — which is
+ * ugly and true, where a guessed label would be neither.
+ */
+const FIELD_KEYS: Record<string, string> = {
+  name: 'name',
+  description: 'description',
+  categoryId: 'category',
+  serialNumber: 'serial_number',
+  location: 'location',
+  purchasedFrom: 'purchased_from',
+  purchasedOn: 'purchased_on',
+  warrantyUntil: 'warranty_until',
+  priceMinor: 'price',
+  currency: 'currency',
+  photoFileId: 'photo',
+}
+
+export function fieldKey(field: string): string | null {
+  return FIELD_KEYS[field] ?? null
+}
+
+/**
+ * Which fields hold prose rather than a value, and therefore cannot be read out in a sentence.
+ *
+ * `description` is `z.string().max(8000)` in the contract, and the timeline rendered a change to it
+ * as "Description changed from … to …" with both versions inline — up to sixteen kilobytes of
+ * somebody's prose in a single row of a 440px panel, and every row below it pushed off the screen.
+ * A diff line is a sentence about a value; eight thousand characters is not a value.
+ *
+ * So a long-text change says **that** it changed and offers the text behind a disclosure, which is
+ * `TimelineText.svelte` — the two versions are only put in the document when somebody asks for
+ * them. The list stays a list, and nothing is hidden: the text is one keystroke away, labelled
+ * before and after.
+ *
+ * A set rather than a length check on the value, because the decision is about the *field*: a short
+ * description is still prose, and rendering it inline on the days it happens to be short would make
+ * the timeline's shape depend on what somebody typed.
+ */
+const LONG_TEXT = new Set(['description'])
+
+export const isLongText = (field: string): boolean => LONG_TEXT.has(field)
+
+/**
+ * The sentence a change to one field wants, as a key name.
+ *
+ * One function rather than the component branching on `isLongText` and `changeShape` separately,
+ * because the combination is the decision: clearing a description is still just "Description
+ * cleared" — short, complete, and nothing to disclose — while setting or changing one is the case
+ * that must not read its own value out.
+ *
+ * `text_changed` covers both `set` and `changed` for prose. "Description set to …" and "Description
+ * changed from … to …" are the same sentence once the values are gone, and two keys saying the same
+ * thing are two translations to keep in step for no gain.
+ */
+export type ChangeLine = 'cleared' | 'replaced' | 'set' | 'changed' | 'text_changed'
+
+/**
+ * A field whose value is an opaque id is reported as a replacement rather than with a uuid in it.
+ *
+ * `photoFileId` is the only one: the value is a file id, and "Photo changed from 0192… to 0193…"
+ * says less than "Photo replaced" while being longer and uglier.
+ */
+const OPAQUE = new Set(['photoFileId'])
+
+export const isOpaque = (field: string): boolean => OPAQUE.has(field)
+
+export function changeLineKind(field: string, from: unknown, to: unknown): ChangeLine {
+  const shape = changeShape(from, to)
+  if (shape === 'cleared') return 'cleared'
+  if (isOpaque(field)) return 'replaced'
+  return isLongText(field) ? 'text_changed' : shape
+}
+
+/**
+ * The other person in a custody sentence, out of the entry's `data`.
+ *
+ * `assigned` and `transferred` name who received it; `returned` names who gave it back, and both are
+ * stored under different keys because they are different facts. Reading `userId` for all three would
+ * make a return read "took it back from nobody" — the key is simply absent there.
+ */
+export function personIdOf(action: string, data: Record<string, unknown>): string | null {
+  const value = action === 'returned' ? data.previousUserId : data.userId
+  return typeof value === 'string' && value ? value : null
+}
+
+/** The handover note, if whoever handed the item over left one. */
+export function noteOf(data: Record<string, unknown>): string | null {
+  const note = data.note
+  return typeof note === 'string' && note.trim() ? note.trim() : null
+}
+
+/**
+ * The thing an entry is *about*, when the sentence alone does not say it.
+ *
+ * "Ada sent it for repair" is a sentence; which repair is the summary somebody typed, and "Ada
+ * attached a file" is missing the only interesting word in it. Both are rendered as a second line
+ * under the headline rather than interpolated into it, and neither goes through the catalogue —
+ * this is text a person typed or a file they named, so translating around it would be translating
+ * a placeholder.
+ *
+ * Two keys rather than one because they are two facts: a repair's `summary` and a file's `name`.
+ * Reading one key for both would print a file id where a summary belongs the day a third action
+ * arrives. Null for anything else, and for a row written before this client knew the key — the rows
+ * outlive the image that wrote them.
+ */
+export function subjectOf(action: string, data: Record<string, unknown>): string | null {
+  const value =
+    action === 'repair_logged' || action === 'repair_completed'
+      ? data.summary
+      : action === 'attachment_added' || action === 'attachment_removed'
+        ? data.name
+        : null
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}

package/src/client/widgets/OverviewWidget.svelte

@@ -1,44 +1,89 @@
 <script lang="ts">
-import { Badge, type BadgeTone, WidgetState } from '@kernhq/ui'
+import { Badge, messageLocale, type WidgetProps, WidgetState } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getInventoryApi } from '../api-instance.js'
+import { isolated } from '../bidi.js'
 import { t } from '../i18n.js'
+import { assetHref } from '../links.js'
+import { inventoryKeys } from '../query.js'
+import { statusTone } from '../status.js'
 
 /**
  * A dashboard card.
  *
  * `WidgetState` draws loading, failed and empty so every card on the board reports those three the
  * same way — and so a module does not have to translate "Retry" to show a widget that failed.
+ *
+ * `WidgetProps` rather than a hand-written pair, and that is what makes the rows work: the shell
+ * passes `workspaceSlug`, which is the half a link to another screen cannot be built without.
+ * Declaring two of the eight props by hand is how a card ends up unable to act on anything.
+ *
+ * `kern-widget` §3 also says to hide row actions while `editing`, and there is nothing to hide
+ * here: the action *is* the row, and `WidgetFrame` drags from its grip button rather than from the
+ * card's body — so an anchor in the body is never what somebody is holding.
  */
-interface Props {
-  workspaceId: string
-  settings?: Record<string, string | number | boolean | null>
-}
-const { workspaceId, settings }: Props = $props()
+const { workspaceId, workspaceSlug, settings }: WidgetProps = $props()
 
 const limit = $derived(Number(settings?.limit ?? 5))
 const api = getInventoryApi()
 
+/**
+ * The card asks for exactly what it shows.
+ *
+ * It used to fetch the default page and then drop archived rows and slice — so a workspace whose
+ * last twenty assets were all archived rendered an empty card that was not empty. The server knows
+ * how to exclude them and how many to send.
+ */
+const filters = $derived({ archived: false, limit })
+
 const assets = createQuery(() => ({
-  queryKey: ['inventory', 'assets', workspaceId],
-  queryFn: () => api.assets.list({ workspaceId }),
+  queryKey: inventoryKeys.assets(workspaceId, filters),
+  queryFn: () => api.assets.list({ workspaceId, ...filters }),
   enabled: Boolean(workspaceId),
 }))
 
-const items = $derived((assets.data?.items ?? []).filter((a) => !a.archivedAt).slice(0, limit))
+const items = $derived(assets.data?.items ?? [])
 
-function statusTone(status: string): BadgeTone {
-  switch (status) {
-    case 'assigned':
-      return 'info'
-    case 'under_repair':
-      return 'warning'
-    case 'retired':
-      return 'grey'
-    default:
-      return 'success'
-  }
-}
+/**
+ * The three numbers that make this card worth a place on a dashboard.
+ *
+ * A list of five recent rows says what somebody added last week, which is rarely the question. How
+ * many things there are, how many are sitting unclaimed, and how many are away being fixed is the
+ * question — and one request answers all three, so the strip costs a query rather than a screen.
+ *
+ * It fails **soft**: the card is a list of recent assets first, and a numbers strip that could not
+ * be loaded simply is not drawn. A dashboard where one card reports an error because a secondary
+ * query failed is a worse dashboard than one where a strip is missing.
+ */
+const stats = createQuery(() => ({
+  queryKey: inventoryKeys.stats(workspaceId),
+  queryFn: () => api.stats.summary({ workspaceId }),
+  enabled: Boolean(workspaceId),
+}))
+
+/**
+ * `outForRepair` is null for a workspace that does not track repairs — not zero, which would be a
+ * claim it has not made. A null tile is simply absent.
+ */
+const tiles = $derived(
+  stats.data
+    ? [
+        { label: t('stats_total'), value: stats.data.total },
+        { label: t('stats_unassigned'), value: stats.data.unassigned },
+        ...(stats.data.outForRepair !== null
+          ? [{ label: t('stats_out_for_repair'), value: stats.data.outForRepair }]
+          : []),
+      ]
+    : [],
+)
+
+/**
+ * A count in the reader's own digits — «۱۲» in Persian, not "12".
+ *
+ * Not `formatCount`, which caps at "99+": that is a badge helper, and a workspace with 214 assets
+ * would be told it has 99+ of them on the line whose job is to be the number.
+ */
+const number = (n: number) => new Intl.NumberFormat(messageLocale()).format(n)
 </script>
 
 <WidgetState
@@ -49,37 +94,102 @@ function statusTone(status: string): BadgeTone {
   emptyIcon="briefcase"
   onRetry={() => assets.refetch()}
 >
+  {#if tiles.length}
+    <dl class="stats">
+      {#each tiles as tile (tile.label)}
+        <div class="stat">
+          <dt>{tile.label}</dt>
+          <dd>{number(tile.value)}</dd>
+        </div>
+      {/each}
+    </dl>
+  {/if}
   <ul>
     {#each items as asset (asset.id)}
       <li>
-        <span class="code">{asset.code}</span>
-        <span class="name">{asset.name}</span>
-        <Badge tone={statusTone(asset.status)}>{t(`status_${asset.status}`)}</Badge>
+        <!--
+          The row *is* the action. `kern-widget` §3: a card that only shows rows is a table of
+          contents, and this one showed five assets with nothing to do about any of them. An anchor
+          rather than a click handler, so the keyboard route is the same route — Tab reaches it,
+          Enter follows it, and the browser offers "open in a new tab" for free. It lands on the
+          list with the asset's own panel open, which is exactly where clicking the row on that
+          screen puts somebody.
+        -->
+        <a class="row" href={assetHref(workspaceSlug, asset.id)}
+          aria-label={t('open_asset', isolated({ name: asset.name }))}>
+          <span class="code">{asset.code}</span>
+          <span class="name">{asset.name}</span>
+          <Badge tone={statusTone(asset.status)}>{t(`status_${asset.status}`)}</Badge>
+        </a>
       </li>
     {/each}
   </ul>
 </WidgetState>
 
 <style>
+  .stats {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px 18px;
+    margin: 0 0 12px;
+    padding: 0 0 12px;
+    border-bottom: 1px solid var(--kern-border-hairline);
+  }
+  .stat {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+  dt {
+    font-size: 11px;
+    /* Muted with a colour rather than opacity, which fades the label against the card. */
+    color: var(--kern-ink-500);
+  }
+  dd {
+    margin: 0;
+    font-size: 18px;
+    font-weight: 600;
+    line-height: 1.15;
+    letter-spacing: -0.02em;
+    color: var(--kern-ink-900);
+    font-variant-numeric: tabular-nums;
+  }
   ul {
     list-style: none;
     margin: 0;
     padding: 0;
     display: flex;
     flex-direction: column;
-    gap: 8px;
+    gap: 2px;
   }
-  li {
+  .row {
     display: flex;
     align-items: center;
     gap: 10px;
     font-size: 13px;
+    color: inherit;
+    text-decoration: none;
+    /* Logical, so the row's breathing room is on the reading-start edge in Persian too. Six
+       vertical pixels take the row past the 24px WCAG 2.5.8 target height on its own. */
+    padding-block: 5px;
+    padding-inline: 6px;
+    margin-inline: -6px;
+    border-radius: var(--kern-r-sm);
+  }
+  .row:hover {
+    background: var(--kern-surface-hover);
   }
   .code {
     font-size: 11px;
     color: var(--kern-ink-500);
     font-variant-numeric: tabular-nums;
     min-width: 64px;
+    /* A tag is read character by character off a sticker, so it stays left-to-right inside a
+       Persian or Arabic card and the bidi algorithm does not reorder its digits — the same rule
+       the repairs card next to it already follows. */
+    direction: ltr;
+    unicode-bidi: isolate;
   }
   .name {
     flex: 1;
@@ -88,5 +198,9 @@ function statusTone(status: string): BadgeTone {
     text-overflow: ellipsis;
     white-space: nowrap;
     color: var(--kern-ink-900);
+    /* A value somebody typed decides its own direction: `plaintext` takes it from the value's
+       first strong character, so a Latin name inside a Persian screen reads left to right and
+       keeps its own trailing punctuation instead of donating it to the paragraph. */
+    unicode-bidi: plaintext;
   }
 </style>

package/src/client/widgets/RepairsWidget.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+import { formatDate, type WidgetProps, WidgetState } from '@kernhq/ui'
+import { createQuery } from '@tanstack/svelte-query'
+import type { RepairListItem } from '../../contract/index.js'
+import { getInventoryApi } from '../api-instance.js'
+import { isolated } from '../bidi.js'
+import { t } from '../i18n.js'
+import { assetHref } from '../links.js'
+import { inventoryKeys } from '../query.js'
+
+/**
+ * What is away being fixed, right now.
+ *
+ * A second card rather than a `view` setting on the first one, because this one is **behind a
+ * capability**: `capability: 'repairs'` in `module.ts` means the shell does not offer it at all to a
+ * workspace that does not record repairs, where an option inside a settings dropdown would offer
+ * the question and then answer it with an empty card. That is the whole difference between a switch
+ * that means something and a switch that does not.
+ *
+ * It asks `repairs.list` at workspace scope — the one question a per-asset list cannot answer — and
+ * the asset's tag and name arrive joined, so nothing here has to look an id up.
+ *
+ * A row opens the **asset**, not the repair: a repair has no screen of its own, and the panel's
+ * Repairs tab is where somebody logs it back in — which is the thing anybody reading "away since
+ * 3 March" actually wants to do next. `WidgetProps` is what carries the `workspaceSlug` that link
+ * needs; this file declared two props by hand and could therefore not build one.
+ */
+const { workspaceId, workspaceSlug, settings }: WidgetProps = $props()
+
+const limit = $derived(Number(settings?.limit ?? 5))
+const api = getInventoryApi()
+
+const filters = $derived({ open: true, limit })
+
+const repairs = createQuery(() => ({
+  queryKey: inventoryKeys.repairs(workspaceId, filters),
+  queryFn: () => api.repairs.list({ workspaceId, ...filters }),
+  enabled: Boolean(workspaceId),
+}))
+
+const items = $derived<readonly RepairListItem[]>(repairs.data?.items ?? [])
+</script>
+
+<WidgetState
+  pending={repairs.isPending}
+  error={repairs.error}
+  empty={!items.length}
+  emptyTitle={t('widget_repairs_empty')}
+  emptyIcon="wrench"
+  onRetry={() => repairs.refetch()}
+>
+  <ul>
+    {#each items as repair (repair.id)}
+      <li>
+        <!-- An anchor, so the keyboard route and the pointer route are one route. -->
+        <a class="row" href={assetHref(workspaceSlug, repair.assetId)}
+          aria-label={t('open_asset', isolated({ name: repair.assetName }))}>
+          <span class="code">{repair.assetCode}</span>
+          <span class="name">{repair.assetName}</span>
+          <span class="since">
+            {t('repair_away_since', isolated({ date: formatDate(repair.sentOn) }))}
+          </span>
+        </a>
+      </li>
+    {/each}
+  </ul>
+</WidgetState>
+
+<style>
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+  }
+  .row {
+    display: flex;
+    align-items: baseline;
+    gap: 10px;
+    font-size: 13px;
+    min-width: 0;
+    color: inherit;
+    text-decoration: none;
+    /* Ten vertical pixels take the row past the 24px WCAG 2.5.8 target height; the inline padding
+       is given back by an equal negative margin, so the card's own gutter is unchanged. */
+    padding-block: 5px;
+    padding-inline: 6px;
+    margin-inline: -6px;
+    border-radius: var(--kern-r-sm);
+  }
+  .row:hover {
+    background: var(--kern-surface-hover);
+  }
+  .code {
+    font-size: 11px;
+    color: var(--kern-ink-500);
+    font-variant-numeric: tabular-nums;
+    min-width: 64px;
+    /* A tag is read character by character off a sticker, so it stays left-to-right inside a
+       Persian or Arabic card and the bidi algorithm does not reorder its digits. */
+    direction: ltr;
+    unicode-bidi: isolate;
+  }
+  .name {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--kern-ink-900);
+    /* A value somebody typed decides its own direction: `plaintext` takes it from the value's
+       first strong character, so a Latin name inside a Persian screen reads left to right and
+       keeps its own trailing punctuation instead of donating it to the paragraph. */
+    unicode-bidi: plaintext;
+  }
+  .since {
+    flex: none;
+    font-size: 11px;
+    /* Muted with a colour, never opacity: a faded line is unreadable whatever its token says. */
+    color: var(--kern-ink-500);
+  }
+</style>

package/src/contract/capabilities.ts

@@ -0,0 +1,99 @@
+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: `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, which is the rule this line has been held to in both
+    // directions: custody and the change history were taken *out* of it while neither had a
+    // procedure, and put back in the change that gave them one.
+    description:
+      'The asset register: what the company owns item by item, who is holding each one, and how each one got there',
+    required: true,
+    level: 1,
+  },
+  {
+    /**
+     * The first capability anyone can actually switch, and the reason it is one is the shape of the
+     * customers: an office that hands out laptops wants a register and never records a repair,
+     * while a company with a workshop wants little else. One answer for the whole workspace, not
+     * per person — so a capability rather than a permission — and switching it off writes a boolean
+     * into module settings and leaves every repair row exactly where it was.
+     *
+     * `dependsOn: ['core']` says the obvious out loud: a repair is a trip *an asset* made, so there
+     * is nothing to record without the register. It also means the closure prunes this
+     * automatically if `core` could ever be off, rather than each screen remembering to check two
+     * switches.
+     */
+    id: 'repairs',
+    label: 'Repairs',
+    description:
+      'What went away to be fixed, to whom, what it cost and when it came back — and the `under repair` status that follows an open one',
+    dependsOn: ['core'],
+    defaultEnabled: true,
+    level: 1,
+  },
+  {
+    /**
+     * Files against an asset or a repair — a purchase receipt, a warranty card, a repair invoice.
+     *
+     * Separate from `repairs` because plenty of workspaces want one without the other: an office
+     * that keeps receipts and never records a repair, and a workshop that records repairs and keeps
+     * no paperwork. Switching it off hides the Files tab and answers 404; the rows and the files in
+     * core's storage are untouched, which is what makes it a capability rather than a migration.
+     */
+    id: 'attachments',
+    label: 'Files',
+    description: 'Receipts, warranties and manuals kept against an asset or one of its repairs',
+    dependsOn: ['core'],
+    defaultEnabled: true,
+    level: 1,
+  },
+])
+
+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 const inventoryCapabilityProcedures: Record<string, readonly string[]> = {
+  repairs: ['repairs.list', 'repairs.create', 'repairs.update', 'repairs.complete'],
+  attachments: ['attachments.list', 'attachments.add', 'attachments.remove'],
+  // `stats.summary` is deliberately absent. It counts assets, which is `core`, and it answers
+  // `outForRepair: null` rather than a number when the workspace has `repairs` off — a count line
+  // and a dashboard card must not disappear because a *different* feature is switched off.
+}