@kernhq/module-inventory 0.1.2 → 0.2.0

package/src/client/price.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import { formatPrice, parsePrice } from './price.js'
+
+/**
+ * The regression this file exists for.
+ *
+ * `raw.replace(',', '.')` replaced the first comma only, so `1.234,56` — how German, Turkish and
+ * Persian write twelve hundred — parsed as `1.23456` and was stored as €1.23. Three of the five
+ * languages this module ships, silently, with no error anywhere. `abc` and `-5` were worse: they
+ * came back `null` and the asset saved with no price at all.
+ */
+const minor = (raw: string, locale: string) => {
+  const result = parsePrice(raw, locale)
+  return result.ok ? result.minor : 'invalid'
+}
+
+describe('parsePrice', () => {
+  it('reads a grouped price in each locale the module ships', () => {
+    expect(minor('1,234.56', 'en')).toBe(123456)
+    expect(minor('1.234,56', 'de')).toBe(123456)
+    expect(minor('1.234,56', 'tr')).toBe(123456)
+    // Persian groups with ٬ and points with ٫, in Persian digits.
+    expect(minor('۱٬۲۳۴٫۵۶', 'fa')).toBe(123456)
+    expect(minor('1,234.56', 'ar')).toBe(123456)
+  })
+
+  it('reads an ungrouped price in each locale', () => {
+    expect(minor('1234.56', 'en')).toBe(123456)
+    expect(minor('1234,56', 'de')).toBe(123456)
+    expect(minor('1234,56', 'tr')).toBe(123456)
+    expect(minor('۱۲۳۴٫۵۶', 'fa')).toBe(123456)
+  })
+
+  it('folds Persian and Arabic digits, so a person may type their own numerals', () => {
+    expect(minor('۱۹٫۹۹', 'fa')).toBe(1999)
+    expect(minor('١٩.٩٩', 'ar')).toBe(1999)
+    expect(minor('۲۵', 'fa')).toBe(2500)
+  })
+
+  it('treats an empty field as no price rather than a bad one', () => {
+    expect(minor('', 'en')).toBe(null)
+    expect(minor('   ', 'de')).toBe(null)
+  })
+
+  it('rejects what it cannot read instead of saving nothing', () => {
+    // Both of these used to return null, and the asset was filed with no price.
+    expect(minor('abc', 'en')).toBe('invalid')
+    expect(minor('-5', 'en')).toBe('invalid')
+    expect(minor('1.2.3', 'en')).toBe('invalid')
+    expect(minor('12,34', 'en')).toBe('invalid')
+    expect(minor('$12.00', 'en')).toBe('invalid')
+  })
+
+  /**
+   * The 100× that has no visible symptom: `.` is German's *group* separator, so stripping it would
+   * store 123456 for somebody who meant 1234.56. There is no way to tell which they meant, so the
+   * field asks rather than guesses.
+   */
+  it('rejects a group separator that does not group three digits', () => {
+    expect(minor('1234.56', 'de')).toBe('invalid')
+    expect(minor('1234.56', 'tr')).toBe('invalid')
+    expect(minor('1.23.456', 'de')).toBe('invalid')
+    expect(minor('1,2345', 'en')).toBe('invalid')
+  })
+
+  it('keeps a bare decimal, with or without its leading zero', () => {
+    expect(minor('0.5', 'en')).toBe(50)
+    expect(minor('.5', 'en')).toBe(50)
+    expect(minor(',5', 'de')).toBe(50)
+  })
+
+  it('does not lose a cent to floating point', () => {
+    expect(minor('19.99', 'en')).toBe(1999)
+    expect(minor('0.07', 'en')).toBe(7)
+    expect(minor('8.29', 'en')).toBe(829)
+  })
+})
+
+describe('formatPrice', () => {
+  it('has no price to show for no price', () => {
+    expect(formatPrice(null, 'en')).toBe('')
+    expect(formatPrice(undefined, 'de')).toBe('')
+  })
+
+  /**
+   * What the edit form seeds itself with has to be something the same locale can parse back, or
+   * opening an asset and saving it unchanged would report the stored price as invalid.
+   */
+  it('round-trips through parsePrice in every locale', () => {
+    for (const locale of ['en', 'de', 'tr', 'fa', 'ar']) {
+      for (const value of [0, 7, 2500, 123456, 99999999]) {
+        expect({ locale, value, back: minor(formatPrice(value, locale), locale) }).toEqual({
+          locale,
+          value,
+          back: value,
+        })
+      }
+    }
+  })
+
+  it('writes the reader’s own digits', () => {
+    expect(formatPrice(123456, 'fa')).toContain('۴')
+    expect(formatPrice(123456, 'de')).toBe('1234,56')
+    expect(formatPrice(123456, 'en')).toBe('1234.56')
+  })
+})

package/src/client/price.ts

@@ -0,0 +1,135 @@
+/**
+ * Reading and writing a price the way the person in front of the form writes it.
+ *
+ * **This is the file that shipped a silent 100× data loss.** The dialog parsed a price with
+ * `Number.parseFloat(raw.replace(',', '.'))`, and `String.replace` with a string pattern replaces
+ * only the *first* match — so a German, Turkish or Persian reader typing `1.234,56`, which is how
+ * three of the five languages this module ships write twelve hundred, got `1.23456` parsed to
+ * `1.23` and stored as €1.23. `1,234.56` in English became the same. Neither said anything: the
+ * old parser returned `null` for garbage and the asset was simply saved with no price at all, so
+ * `abc` and `-5` both vanished without an error.
+ *
+ * So: no separator is assumed, the locale is asked what its own are, and anything that is not a
+ * plain non-negative number in *that* locale comes back as a rejection the form can show. There is
+ * no third outcome where a wrong number is stored quietly.
+ *
+ * Pure on purpose — the locale arrives as an argument rather than being read from `@kernhq/ui`.
+ * That entry point reaches Svelte components, and a parser that drags a compiler behind it is a
+ * parser nothing can unit-test. The dialog passes `messageLocale()`.
+ */
+
+/** `minor: null` is a real answer — an empty field means "no price", not a bad one. */
+export type PriceResult = { ok: true; minor: number | null } | { ok: false }
+
+interface Separators {
+  group: string
+  decimal: string
+}
+
+const SEPARATORS: Map<string, Separators> = new Map()
+
+/**
+ * What this locale's own numbers look like, asked of `Intl` rather than tabulated here.
+ *
+ * A table of separators per language is a table that is wrong for the sixth language somebody adds.
+ * Measured for the five shipped today: en and ar group with `,` and point with `.`, de and tr are
+ * the other way round, and fa uses `٬` and `٫`.
+ */
+function separatorsFor(locale: string): Separators {
+  const cached = SEPARATORS.get(locale)
+  if (cached) return cached
+  const found: Separators = { group: ',', decimal: '.' }
+  try {
+    const parts = new Intl.NumberFormat(locale).formatToParts(12345.6)
+    found.group = parts.find((part) => part.type === 'group')?.value ?? found.group
+    found.decimal = parts.find((part) => part.type === 'decimal')?.value ?? found.decimal
+  } catch {
+    // A runtime that cannot name this locale must not make the field unusable; English separators
+    // are the fallback, and a wrong guess shows an error rather than storing a wrong number.
+  }
+  SEPARATORS.set(locale, found)
+  return found
+}
+
+/**
+ * A Persian keyboard produces ۱۲۳ and an Arabic one ١٢٣, and `Number` reads neither.
+ *
+ * Same fold HR's employee counter does, and for the same reason: a person typing the digits of
+ * their own language into their own language's form must not be told their input is not a number.
+ */
+const toLatinDigits = (value: string) =>
+  value
+    .replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660))
+    .replace(/[۰-۹]/g, (d) => String(d.charCodeAt(0) - 0x06f0))
+
+/** Bidi controls ride along on anything copied out of an RTL document and are never separators. */
+const BIDI = /[‎‏؜⁦-⁩]/g
+
+/**
+ * A group separator always precedes exactly three digits.
+ *
+ * This is the rule that stops the quiet 100×: in German `.` groups, so `1234.56` is not "one
+ * thousand two hundred and thirty-four point five six" — it is not a well-formed German number at
+ * all. Stripping the dot would store €12,345.60 for a €1,234.56 laptop and nothing would say so.
+ * Rejecting it puts the question back to the person, which is the only honest answer available.
+ */
+function isGroupedInteger(text: string, group: string): boolean {
+  if (/^\d+$/.test(text)) return true
+  if (!group || !text.includes(group)) return false
+  const [first, ...rest] = text.split(group)
+  if (first === undefined || !/^\d{1,3}$/.test(first)) return false
+  return rest.every((chunk) => /^\d{3}$/.test(chunk))
+}
+
+/**
+ * Minor units are the wire format; the form takes what somebody reads off the receipt.
+ *
+ * Returns `{ ok: false }` for anything that is not a non-negative number in `locale` — including a
+ * negative one, which the contract has no way to mean and the old parser dropped in silence.
+ */
+export function parsePrice(raw: string, locale: string): PriceResult {
+  const text = toLatinDigits(raw).replace(BIDI, '').trim()
+  if (!text) return { ok: true, minor: null }
+
+  const { group, decimal } = separatorsFor(locale)
+  const pieces = text.split(decimal)
+  if (pieces.length > 2) return { ok: false }
+
+  let whole = pieces[0] ?? ''
+  const frac = pieces[1]
+  // "‚50" is how somebody writes half a unit; the leading zero is implied, not missing.
+  if (whole === '' && frac !== undefined) whole = '0'
+
+  if (!isGroupedInteger(whole, group)) return { ok: false }
+  if (frac !== undefined && !/^\d+$/.test(frac)) return { ok: false }
+
+  const digits = group ? whole.split(group).join('') : whole
+  const value = Number(`${digits}.${frac ?? '0'}`)
+  if (!Number.isFinite(value)) return { ok: false }
+
+  const minor = Math.round(value * 100)
+  // A price that cannot survive the round trip through a double is not a price anybody typed.
+  if (!Number.isSafeInteger(minor)) return { ok: false }
+  return { ok: true, minor }
+}
+
+/**
+ * The stored price, back in the field, in the reader's own numbers.
+ *
+ * The edit form has to seed itself from `priceMinor`, and seeding it with `1234.56` for a German
+ * reader would make them look at a number their own locale says is €123,456 — then `parsePrice`
+ * would reject it on the grouping rule and they would be told their own data is invalid. What comes
+ * out of here is exactly what goes back in.
+ */
+export function formatPrice(minor: number | null | undefined, locale: string): string {
+  if (minor === null || minor === undefined) return ''
+  try {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+      useGrouping: false,
+    }).format(minor / 100)
+  } catch {
+    return String(minor / 100)
+  }
+}

package/src/client/query.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { inventoryKeys } from './query.js'
+
+/**
+ * The realtime contract, held to by a test because nothing else can hold it.
+ *
+ * `realtime.svelte.ts` calls `invalidateQueries({ queryKey: [module, entity] })` with whatever the
+ * server put in the change event, and `src/server/router.ts` emits `entity: 'asset'`. A key whose
+ * second segment is anything else is simply never invalidated — no error, no warning, just a list
+ * that stops updating. That is what `['inventory', 'assets', …]` did: the detail panel refreshed
+ * and the list behind it did not, and the only way to see it was to write to the module from a
+ * second browser.
+ *
+ * Proven against `partialMatchKey` from `@tanstack/query-core`, which is what
+ * `invalidateQueries` filters with; asserted here on the segment itself, so the test does not need
+ * the query runtime to state the rule it is protecting.
+ */
+const WS = '01920000-0000-7000-8000-000000000001'
+
+/** Must equal the `entity` string in `src/server/router.ts`'s `notify.change` call. */
+const ENTITY = 'asset'
+
+describe('inventoryKeys', () => {
+  it('names the entity exactly as the server emits it, on every key', () => {
+    for (const [name, key] of [
+      ['assets', inventoryKeys.assets(WS)],
+      ['assets(filtered)', inventoryKeys.assets(WS, { archived: false })],
+      ['asset', inventoryKeys.asset(WS, 'some-id')],
+    ] as const)
+      expect({ name, module: key[0], entity: key[1] }).toEqual({
+        name,
+        module: 'inventory',
+        entity: ENTITY,
+      })
+  })
+
+  it('puts the list and the row under one prefix, so one change event reaches both', () => {
+    const list = inventoryKeys.assets(WS, { archived: false })
+    const row = inventoryKeys.asset(WS, 'some-id')
+    expect(list.slice(0, 2)).toEqual(row.slice(0, 2))
+  })
+
+  it('makes a filtered list a different question from an unfiltered one', () => {
+    expect(inventoryKeys.assets(WS, { archived: true })).not.toEqual(
+      inventoryKeys.assets(WS, { archived: false }),
+    )
+    expect(inventoryKeys.assets(WS, { archived: false })).not.toEqual(inventoryKeys.assets(WS))
+  })
+
+  it('does not let two workspaces share a cache entry', () => {
+    expect(inventoryKeys.assets('ws-a')).not.toEqual(inventoryKeys.assets('ws-b'))
+  })
+
+  it('starts every key with the module, so one invalidation can clear all of Inventory', () => {
+    for (const key of [inventoryKeys.all, inventoryKeys.assets(WS), inventoryKeys.asset(WS, 'id')])
+      expect(key[0]).toBe('inventory')
+  })
+})

package/src/client/query.ts

@@ -3,10 +3,23 @@
  *
  * `[module, entity, …scope]`, so a realtime `change` event invalidates precisely what it touched.
  * Filters are part of the key wherever a screen can ask the same question two ways — a cached list
- * for "all" must not be served when somebody asked for "assigned".
+ * for "all" must not be served when somebody asked for "assigned", and the archived list is a
+ * different question from the live one rather than the same answer filtered afterwards.
+ *
+ * **The entity segment is singular, and that is not a style choice.** `realtime.svelte.ts`
+ * invalidates `[module, entity]` with whatever the server put in the change event, and
+ * `src/server/router.ts` emits `entity: 'asset'` — so the prefix that arrives is
+ * `['inventory', 'asset']`. This file spelled the list key `['inventory', 'assets', …]`, which that
+ * prefix never matches: `partialMatchKey` compares segment by segment and `'assets' !== 'asset'`.
+ * The detail key was already singular, so a change refreshed the panel nobody was looking at while
+ * the list and the dashboard card behind it stayed stale until a reload. Every other module keys
+ * the list and the row off one singular entity name (`['tracker', 'issue', …]`); so does this one
+ * now.
  */
 export const inventoryKeys = {
+  /** Everything under this module, for the blunt invalidation after a write. */
+  all: ['inventory'] as const,
   assets: (ws: string, filters?: Record<string, unknown>) =>
-    filters ? (['inventory', 'assets', ws, filters] as const) : (['inventory', 'assets', ws] as const),
+    filters ? (['inventory', 'asset', ws, filters] as const) : (['inventory', 'asset', ws] as const),
   asset: (ws: string, id: string) => ['inventory', 'asset', ws, id] as const,
 }

package/src/client/settings/core-api.ts

@@ -0,0 +1,32 @@
+/**
+ * The slice of core's API this module reaches for, named by shape rather than imported.
+ *
+ * A module talks to another module through `kernel.call()` on the server; on the client the shell
+ * hands over its own configured core client, and typing the seam structurally keeps the dependency
+ * pointing one way — inventory does not import core's router type, and core does not know inventory
+ * exists.
+ *
+ * Keep it to what is actually called. A wide type here is a promise about core's surface that this
+ * module has no standing to make. Two procedures are all the settings page needs, and both are
+ * gated on `core.modules.manage` in `core/src/modules/core/router.ts`.
+ */
+export interface CoreApi {
+  workspaces: {
+    modules: {
+      list(input: { workspaceId: string }): Promise<
+        Array<{
+          manifest: { id: string }
+          state: {
+            enabled: boolean
+            settings?: Record<string, unknown>
+          }
+        }>
+      >
+      updateSettings(input: {
+        workspaceId: string
+        moduleId: string
+        settings: Record<string, unknown>
+      }): Promise<unknown>
+    }
+  }
+}

package/src/client/widgets/OverviewWidget.svelte

@@ -3,6 +3,7 @@ import { Badge, type BadgeTone, WidgetState } from '@kernhq/ui'
 import { createQuery } from '@tanstack/svelte-query'
 import { getInventoryApi } from '../api-instance.js'
 import { t } from '../i18n.js'
+import { inventoryKeys } from '../query.js'
 
 /**
  * A dashboard card.
@@ -19,18 +20,30 @@ const { workspaceId, settings }: Props = $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':
+    case 'reserved':
       return 'info'
+    case 'lost':
+      return 'danger'
     case 'under_repair':
       return 'warning'
     case 'retired':

package/src/contract/capabilities.ts

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

package/src/contract/events.ts

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

package/src/contract/index.ts

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

package/src/contract/models.ts

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

package/src/contract/permissions.ts

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