@kernhq/module-inventory 0.2.0 → 0.3.0

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 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.
+ * **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.
+ *
+ * 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,82 @@ 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 })
+  })
+})

package/src/server/index.ts

@@ -1,15 +1,54 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import type { core, Principal } from '@kernhq/contracts'
+import { WorkspaceId } from '@kernhq/contracts'
+import { KernError, type Kernel } from '@kernhq/kernel'
+import { and, eq, inArray } from 'drizzle-orm'
+import { z } from 'zod'
 import {
+  Asset,
   InventorySettings,
   inventoryCapabilities,
   inventoryContract,
   inventoryEvents,
+  inventoryNotificationTypes,
   inventoryPermissions,
   MODULE_ID,
 } from '../contract/index.js'
+import { inventoryJobs } from './jobs.js'
 import { defineModule, defineServerModule, inventoryRouter, packageVersion } from './router.js'
-import { schema } from './schema.js'
+import { assets, categories, schema, workspaces } from './schema.js'
+import { toAsset } from './services/assets.js'
+import { inventoryServices } from './services/index.js'
+import { ASSET_ICON, assetUrl } from './services/search.js'
+
+/**
+ * The categories a workspace starts with.
+ *
+ * Five, because an empty picker on the asset form is a question a new workspace cannot answer yet —
+ * "what do you file a laptop under" has an obvious answer and asking it costs somebody a trip to a
+ * settings page before they can add their first asset. Ordered rather than alphabetical: this is the
+ * order somebody scanning a list expects, and every one of them is renamable, archivable and
+ * ignorable.
+ */
+const DEFAULT_CATEGORIES = ['Laptops', 'Phones', 'Monitors', 'Furniture', 'Vehicles'] as const
+
+/**
+ * The `procedures` below are this module's service-to-service surface, reachable only over
+ * `kernel.call`. They deliberately run with elevated access — no workspace membership is checked,
+ * because the caller is another service and has none — so they must never be callable by an end
+ * user: anything a person does goes through the oRPC router and its permission middleware.
+ *
+ * Copied deliberately from `module-tracker`, down to the shape of the check, so that the one line
+ * standing between "an internal read" and "a permission-free read of any workspace's register"
+ * looks the same in every module somebody audits.
+ */
+function requireService(principal: Principal): void {
+  if (principal.kind !== 'service' && !principal.instanceAdmin) throw KernError.forbidden()
+}
+
+/** HR's statuses that mean somebody is on their way out. Their own enum; read, never guessed. */
+const LEAVING_STATUSES = new Set(['offboarding', 'terminated'])
 
 export const inventoryModule = defineServerModule({
   definition: defineModule({
@@ -22,15 +61,283 @@ export const inventoryModule = defineServerModule({
     permissions: inventoryPermissions,
     capabilities: inventoryCapabilities,
     events: inventoryEvents,
+    notificationTypes: inventoryNotificationTypes,
     settings: InventorySettings,
-    // `objectTypes` returns with the resolver that turns a mention or a link into an asset and the
-    // indexer that puts one in search — declaring the type with neither made both resolve to
-    // nothing, which reads to a user as a broken link rather than as a feature not built yet.
+    /**
+     * `inventory:asset:<id>` is a thing the rest of the product may point at.
+     *
+     * This came *off* the manifest in 0.2.0 and is back now, and the difference is the two handlers
+     * under it: `resolvers` turns the reference into a title, a URL and an icon, and `search` puts
+     * the row where somebody can find it in the first place. A declared type with neither renders a
+     * link to nothing, which reads to a person as a broken product rather than as a feature that
+     * has not shipped — the same lie as a permission nothing checks.
+     *
+     * `channelable: false`, unlike a tracker issue: a channel per laptop is not a thing anybody
+     * wants, and the conversation about an asset belongs wherever the work does.
+     */
+    objectTypes: [{ type: 'asset', label: 'Asset', icon: ASSET_ICON, channelable: false }],
   }),
   /** Attached so the developer panel can check the router against what was promised. */
   contract: inventoryContract,
   schema,
   migrationsFolder: join(dirname(fileURLToPath(import.meta.url)), '../../migrations'),
   router: inventoryRouter,
+
+  jobs: inventoryJobs(),
+
+  /**
+   * `inventory:asset:<id>` rendered wherever it is mentioned — a chat message, a tracker issue, a
+   * notification.
+   *
+   * The permission is checked **once for the batch**, not per id: `inventory.asset.view` is a
+   * workspace permission and every asset in a workspace has the same audience, so there is nothing
+   * per-row to decide. Somebody without it gets nulls, which the caller renders as plain text
+   * rather than as a link to a title they were not entitled to read — a resolver is a read like any
+   * other, and the fact that it is called by another module does not make it exempt.
+   */
+  resolvers: [
+    {
+      type: 'asset',
+      resolve: async (workspaceId, ids, principal, kernel) => {
+        const may = await kernel.authz
+          .can(principal, 'inventory.asset.view', { kind: 'workspace', workspaceId })
+          .catch(() => false)
+        if (!may) return ids.map(() => null)
+        return kernel.database.withWorkspace(workspaceId, async (tx) => {
+          const rows = await tx
+            .select({
+              id: assets.id,
+              code: assets.code,
+              name: assets.name,
+              status: assets.status,
+              archivedAt: assets.archivedAt,
+            })
+            .from(assets)
+            .where(and(eq(assets.workspaceId, workspaceId), inArray(assets.id, ids)))
+          const byId = new Map(rows.map((row) => [row.id, row]))
+          return ids.map((id) => {
+            const row = byId.get(id)
+            if (!row) return null
+            return {
+              id,
+              // The tag first, because that is what is printed on the sticker somebody is holding.
+              title: `${row.code} ${row.name}`,
+              url: assetUrl(id),
+              icon: ASSET_ICON,
+              /**
+               * An archived asset still resolves — a link written last year must not turn into
+               * nothing — and says so, where the search index drops it. A reference is a fact about
+               * the past; a search hit is an offer to go somewhere now.
+               *
+               * The value is the module's own status vocabulary, not a translated label, and
+               * `archived` is lowercase for the same reason `in_stock` is: a resolver runs in a
+               * service with no locale to render into, so it hands over the machine value and the
+               * caller decides. Every module's resolver does this today — `module-tracker` returns
+               * a raw `statusId`. Translating it needs the platform to give a resolver the reader's
+               * locale, which it does not, and inventing an English sentence here would look
+               * finished while being wrong in four of the five languages this module ships.
+               */
+              subtitle: row.archivedAt ? 'archived' : row.status,
+            }
+          })
+        })
+      },
+    },
+  ],
+
+  /**
+   * The register in the workspace-wide search index, so an asset tag read off a sticker finds the
+   * item from the command palette.
+   *
+   * Both halves are `SearchService`'s, so the document a mutation writes and the document a full
+   * reindex writes cannot drift: `load` answers `null` for an archived or missing row, which is what
+   * takes it back out, and `scan` pages by keyset for `core.search.reindex`.
+   */
+  search: [
+    {
+      types: ['asset'],
+      load: (workspaceId, id, kernel): Promise<core.SearchDocument | null> =>
+        inventoryServices(kernel).search.load(workspaceId, id),
+      scan: (workspaceId, kernel) => inventoryServices(kernel).search.scan(workspaceId),
+    },
+  ],
+
+  /** Answers other modules and services may ask, without reaching into `mod_inventory`. */
+  procedures: {
+    /**
+     * One asset, for whatever holds an id and needs to say what it is — an automation, a report, a
+     * module that recorded an `ObjectRef` and now has to act on it.
+     */
+    'asset.byId': {
+      input: z.object({ workspaceId: WorkspaceId, assetId: z.uuid() }),
+      output: Asset,
+      handler: async (input, { kernel, principal }) => {
+        requireService(principal)
+        return kernel.database.withWorkspace(input.workspaceId, async (tx) =>
+          toAsset(await inventoryServices(kernel).assets.get(tx, input.workspaceId, input.assetId)),
+        )
+      },
+    },
+    /**
+     * What one person is holding — the offboarding question, asked from outside.
+     *
+     * This module answers it for itself in the subscription below; the procedure exists because it
+     * is the question *other* modules ask about a person, and the alternative is each of them
+     * learning the shape of `mod_inventory.assets`. Answered through `AssetService.list` with the
+     * custodian filter fixed, which is the same one query path `custody.byUser` uses rather than a
+     * second one to keep in step.
+     */
+    'assets.byCustodian': {
+      input: z.object({
+        workspaceId: WorkspaceId,
+        userId: z.uuid(),
+        limit: z.number().int().min(1).max(200).default(100),
+        cursor: z.string().max(500).optional(),
+      }),
+      output: z.object({ items: z.array(Asset), nextCursor: z.string().nullable() }),
+      handler: async (input, { kernel, principal }) => {
+        requireService(principal)
+        return kernel.database.withWorkspace(input.workspaceId, (tx) =>
+          inventoryServices(kernel).assets.list(tx, {
+            workspaceId: input.workspaceId,
+            limit: input.limit,
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+            custodianUserId: input.userId,
+            archived: false,
+            sort: 'recent',
+          }),
+        )
+      },
+    },
+  },
+
+  subscriptions: {
+    /**
+     * Register the workspace so the sweeps can find it.
+     *
+     * Both halves are needed and neither is redundant: `onWorkspaceEnabled` covers somebody
+     * switching the module on for an existing workspace, and this covers a workspace created while
+     * the module is already on by default. A workspace registered twice is one row either way.
+     */
+    'core.workspace.created': async (event, kernel) => {
+      const { workspaceId } = event.payload as { workspaceId: string }
+      await registerWorkspace(kernel, workspaceId)
+    },
+
+    /**
+     * A member removed from the workspace does **not** silently vanish from the register.
+     *
+     * The obvious implementation — clear `custodian_user_id` for everything they held — is the one
+     * this module refuses to write, and the reason is the same one `OffboardingService` gives:
+     * custody is an effective-dated record of who was answerable for what, and an item does not
+     * come back because an account was closed. Clearing the column would say the laptop is in stock
+     * while it is in somebody's bag, and it would do it *without a custody period closing*, so the
+     * timeline would show a handover that never ended and a return that never happened. `assets
+     * .archive` already refuses to archive a held item for exactly this reason.
+     *
+     * So: nothing moves, and the people who can take the item back are told there is something to
+     * collect. The custodian field keeps naming somebody who is no longer a member, and every
+     * screen in this module already renders an unresolvable id as "a former member" rather than as
+     * a uuid — which is the honest thing for it to say.
+     */
+    'core.member.removed': async (event, kernel) => {
+      const { workspaceId, userId } = event.payload as { workspaceId: string; userId: string }
+      await inventoryServices(kernel).offboarding.raise(workspaceId, userId, 'removed')
+    },
+
+    /**
+     * HR says somebody is on their way out.
+     *
+     * **Inert without HR, in three independent ways**, because this module installs, boots and works
+     * in a workspace that has never had HR and there is no `dependsOn: ['hr']` on the manifest:
+     *
+     * 1. the event only exists if HR is running — a subscription to a pattern nothing publishes is
+     *    a subscription that never fires;
+     * 2. `OffboardingService.raise` asks whether *Inventory* is switched on for that workspace
+     *    before it does anything, because an event bus is instance-wide and one workspace having HR
+     *    says nothing about another;
+     * 3. the one thing it needs from HR — the account behind a `personId` — is a `kernel.call`, and
+     *    a call to a procedure nothing hosts throws, which is caught here and logged as nothing to
+     *    do. A module never imports another module.
+     *
+     * `offboarding` matters more than `terminated`: somebody in their notice period is still at
+     * their desk, which is when a list of things to collect is worth having. `terminated` is the
+     * backstop for a workspace that never uses the intermediate status.
+     */
+    'hr.person.status_changed': async (event, kernel) => {
+      const payload = event.payload as { workspaceId: string; personId: string; to: string }
+      if (!LEAVING_STATUSES.has(payload.to)) return
+      const person = await kernel
+        .call<{ userId: string | null } | null>('hr.person.get', {
+          workspaceId: payload.workspaceId,
+          personId: payload.personId,
+        })
+        .catch((err: unknown) => {
+          /**
+           * `UNAVAILABLE` is what the broker answers for a procedure nothing hosts, which is the
+           * ordinary state of an instance without HR and not worth a line in a log. Anything else
+           * is HR being *present and failing*, and swallowing the two the same way would mean the
+           * one case somebody should fix looks exactly like the case they should ignore.
+           */
+          if ((err as { code?: string }).code !== 'UNAVAILABLE')
+            kernel.log.warn(
+              { err: err instanceof Error ? err.message : String(err), module: MODULE_ID },
+              'inventory: could not ask People who is behind a person leaving',
+            )
+          return null
+        })
+      // No account: `user_id` is legitimately null for somebody who never had a Kern account, and
+      // for somebody core has already removed — that path is the subscription above.
+      if (!person?.userId) return
+      await inventoryServices(kernel).offboarding.raise(payload.workspaceId, person.userId, 'leaving')
+    },
+  },
+
+  /**
+   * A workspace that switches Inventory on gets a filing system and a place in the scheduler.
+   *
+   * Idempotent, because it runs again every time somebody switches the module off and back on.
+   * Neither half may double up:
+   *
+   * - the registry row is an `on conflict do nothing` on its own primary key;
+   * - the categories are seeded **only into a workspace that has none at all**, archived ones
+   *   included. Keying on the names instead would re-create "Laptops" for a workspace that had
+   *   renamed it to "Notebooks" — the second toggle would quietly hand somebody a duplicate of
+   *   their own category under the name they had rejected.
+   */
+  onWorkspaceEnabled: async (workspaceId, kernel) => {
+    await registerWorkspace(kernel, workspaceId)
+    await kernel.database.withWorkspace(workspaceId, async (tx) => {
+      const [existing] = await tx
+        .select({ id: categories.id })
+        .from(categories)
+        .where(eq(categories.workspaceId, workspaceId))
+        .limit(1)
+      if (existing) return
+      await tx.insert(categories).values(
+        DEFAULT_CATEGORIES.map((name, index) => ({
+          workspaceId,
+          name,
+          order: index + 1,
+        })),
+      )
+    })
+  },
 })
+
+/**
+ * Remember that this workspace exists, so a job woken by a clock can find it.
+ *
+ * Written inside `withWorkspace` rather than through the unbound handle: the table carries a
+ * row-level security policy like every other tenant table, and a bound session satisfies it without
+ * needing the connection to be the schema's owner. The enumeration in `jobs.ts` is the one place
+ * that cannot do the same, and says so.
+ */
+async function registerWorkspace(kernel: Kernel, workspaceId: string): Promise<void> {
+  await kernel.database.withWorkspace(workspaceId, (tx) =>
+    tx.insert(workspaces).values({ workspaceId }).onConflictDoNothing({ target: workspaces.workspaceId }),
+  )
+}
+
 export default inventoryModule
+export type InventoryModule = typeof inventoryModule