@kernhq/module-inventory 0.2.0 → 0.3.0

package/dist/server/services/notify.d.ts

@@ -38,6 +38,15 @@ export declare class NotifyService {
     private readonly kernel;
     constructor(kernel: Kernel);
     private best;
+    /**
+     * `best`, asked the other question: **did the call actually happen**, rather than what it returned.
+     *
+     * `best` cannot answer that — a procedure that legitimately answers `null` or `undefined` is
+     * indistinguishable from one that threw and was swallowed, and a caller writing "I have told
+     * them" into a database on the strength of that is writing a lie. So the value is thrown away
+     * here and the boolean is the whole answer.
+     */
+    private attempted;
     /**
      * Append to the asset's own history, inside the caller's transaction.
      *
@@ -51,12 +60,45 @@ export declare class NotifyService {
     history(tx: Tx, input: HistoryInput): Promise<void>;
     /** The workspace-wide activity feed's copy. Best-effort, and only ever after the commit. */
     activity(input: HistoryInput): Promise<void>;
-    notify(input: NotifyInput): Promise<void>;
+    /**
+     * Tell these people, and answer **who it was meant for and how many of them were actually
+     * written** — both numbers, because one of them cannot be checked without the other.
+     *
+     * Everything this class does is best-effort, so a failed `core.notifications.create` is swallowed
+     * and logged; a caller that then records "this one has been notified" has recorded something that
+     * never happened. The two nightly sweeps write exactly such a marker, once per row for ever, so a
+     * swallowed failure there is not a delayed notice but a notice nobody will ever receive.
+     *
+     * This used to answer a single count, and the sweeps marked the row whenever it was above zero —
+     * so a notice that reached one of three recipients was stamped *told*, and the two who missed it
+     * never heard. **A partial delivery is a failure for the people it did not reach**, and the row
+     * cannot record two answers, so the honest one is the pessimistic one: the sweeps mark nothing
+     * unless `delivered === targeted`, and say it again in the morning. The cost is that whoever did
+     * hear it hears it twice; `groupKey` collapses that in the notification centre, and it is a
+     * strictly smaller price than one person never being told at all.
+     *
+     * `targeted` is what is left after the de-duplication and the exclusions, which is why the caller
+     * cannot work it out from the list it passed in. `targeted: 0` means there was nobody to tell,
+     * which is also not "told".
+     */
+    notify(input: NotifyInput): Promise<{
+        targeted: number;
+        delivered: number;
+    }>;
     /** Realtime cache invalidation for connected clients. */
     change(workspaceId: string, entity: string, id: string, op: EntityChange['op'], opts?: {
         patch?: Record<string, unknown>;
         scope?: Record<string, string>;
     }): Promise<void>;
+    /**
+     * The workspace-wide search index, written to by `SearchService` and by nothing else.
+     *
+     * These two spent a release with no caller: `objectTypes` had been taken off the module
+     * definition, because a declared type with no indexer and no resolver renders a link to nothing.
+     * Both halves exist now — `src/server/services/search.ts` builds the documents, `src/server/
+     * index.ts` declares the indexer and the resolver — and every asset mutation reindexes after it
+     * has committed.
+     */
     index(documents: core.SearchDocument[]): Promise<void>;
     unindex(workspaceId: string, type: string, ids: string[]): Promise<void>;
 }

package/dist/server/services/notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../../src/server/services/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,EAAE,EAAU,MAAM,gBAAgB,CAAA;AAI7D,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,oDAAoD;IACpD,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;CAC9C;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;YAE7B,IAAI;IAYlB;;;;;;;;;OASG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzD,4FAA4F;IACtF,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5C,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB/C,yDAAyD;IACnD,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,EACtB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAO,GAC7E,OAAO,CAAC,IAAI,CAAC;IAgBV,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ/E"}
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../../src/server/services/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,EAAE,EAAU,MAAM,gBAAgB,CAAA;AAI7D,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,oDAAoD;IACpD,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;CAC9C;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;YAE7B,IAAI;IAYlB;;;;;;;OAOG;YACW,SAAS;IASvB;;;;;;;;;OASG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzD,4FAA4F;IACtF,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAclD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA0BlF,yDAAyD;IACnD,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,EACtB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAO,GAC7E,OAAO,CAAC,IAAI,CAAC;IAahB;;;;;;;;OAQG;IACG,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtD,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ/E"}

package/dist/server/services/notify.js

@@ -23,6 +23,20 @@ export class NotifyService {
             return null;
         }
     }
+    /**
+     * `best`, asked the other question: **did the call actually happen**, rather than what it returned.
+     *
+     * `best` cannot answer that — a procedure that legitimately answers `null` or `undefined` is
+     * indistinguishable from one that threw and was swallowed, and a caller writing "I have told
+     * them" into a database on the strength of that is writing a lie. So the value is thrown away
+     * here and the boolean is the whole answer.
+     */
+    async attempted(what, fn) {
+        return ((await this.best(what, async () => {
+            await fn();
+            return true;
+        })) === true);
+    }
     /**
      * Append to the asset's own history, inside the caller's transaction.
      *
@@ -56,12 +70,33 @@ export class NotifyService {
             data: input.data ?? {},
         }));
     }
+    /**
+     * Tell these people, and answer **who it was meant for and how many of them were actually
+     * written** — both numbers, because one of them cannot be checked without the other.
+     *
+     * Everything this class does is best-effort, so a failed `core.notifications.create` is swallowed
+     * and logged; a caller that then records "this one has been notified" has recorded something that
+     * never happened. The two nightly sweeps write exactly such a marker, once per row for ever, so a
+     * swallowed failure there is not a delayed notice but a notice nobody will ever receive.
+     *
+     * This used to answer a single count, and the sweeps marked the row whenever it was above zero —
+     * so a notice that reached one of three recipients was stamped *told*, and the two who missed it
+     * never heard. **A partial delivery is a failure for the people it did not reach**, and the row
+     * cannot record two answers, so the honest one is the pessimistic one: the sweeps mark nothing
+     * unless `delivered === targeted`, and say it again in the morning. The cost is that whoever did
+     * hear it hears it twice; `groupKey` collapses that in the notification centre, and it is a
+     * strictly smaller price than one person never being told at all.
+     *
+     * `targeted` is what is left after the de-duplication and the exclusions, which is why the caller
+     * cannot work it out from the list it passed in. `targeted: 0` means there was nobody to tell,
+     * which is also not "told".
+     */
     async notify(input) {
         const excluded = new Set([...(input.exclude ?? [])].filter(Boolean));
         const targets = [...new Set(input.userIds)].filter((id) => id && !excluded.has(id));
         if (!targets.length)
-            return;
-        await Promise.all(targets.map((userId) => this.best('notifications.create', () => this.kernel.call('core.notifications.create', {
+            return { targeted: 0, delivered: 0 };
+        const written = await Promise.all(targets.map((userId) => this.attempted('notifications.create', () => this.kernel.call('core.notifications.create', {
             userId,
             workspaceId: input.workspaceId,
             module: MODULE_ID,
@@ -74,6 +109,7 @@ export class NotifyService {
             groupKey: input.groupKey ?? null,
             actorId: input.actorId ?? null,
         }))));
+        return { targeted: targets.length, delivered: written.filter(Boolean).length };
     }
     /** Realtime cache invalidation for connected clients. */
     async change(workspaceId, entity, id, op, opts = {}) {
@@ -86,9 +122,15 @@ export class NotifyService {
             ...(opts.scope ? { scope: opts.scope } : {}),
         }));
     }
-    // Nothing calls `index`/`unindex` yet: `objectTypes` came off the module definition until there
-    // is a resolver and an indexer to stand behind it. They are kept as they are, copied from
-    // tracker, and are wired up by the change that declares the object type again.
+    /**
+     * The workspace-wide search index, written to by `SearchService` and by nothing else.
+     *
+     * These two spent a release with no caller: `objectTypes` had been taken off the module
+     * definition, because a declared type with no indexer and no resolver renders a link to nothing.
+     * Both halves exist now — `src/server/services/search.ts` builds the documents, `src/server/
+     * index.ts` declares the indexer and the resolver — and every asset mutation reindexes after it
+     * has committed.
+     */
     async index(documents) {
         if (!documents.length)
             return;

package/dist/server/services/notify.js.map

@@ -1 +1 @@
-{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../../src/server/services/notify.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../../../src/server/services/notify.ts"],"names":[],"mappings":"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"}

package/dist/server/services/offboarding.d.ts

@@ -0,0 +1,70 @@
+import type { Kernel } from '@kernhq/kernel';
+import type { NotifyService } from './notify.js';
+/** Why the checklist is being raised, which is the only difference between the two callers. */
+export type Departure = 
+/** `core.member.removed` — the account is out of the workspace already. */
+'removed'
+/** `hr.person.status_changed` to a status that ends employment — they may still be at their desk. */
+ | 'leaving';
+export interface ReturnList {
+    items: Array<{
+        id: string;
+        code: string;
+        name: string;
+    }>;
+    /** Who was told. Empty when there was nothing to return, or nobody who could act on it. */
+    recipients: string[];
+}
+/**
+ * Somebody is leaving, and the register still says things are theirs.
+ *
+ * **This raises a checklist and notifies. It never moves anything.** Custody changes because a
+ * person did something — handed an item over, handed it on, took it back — and every one of those
+ * writes a period row and a line of history saying who did it. A hook that quietly returned an
+ * item on somebody's last day would write a handover nobody performed, into the one record the
+ * company later argues from; and the laptop would still be in their bag. So the answer is a message
+ * to the people who can take it back, and the register stays exactly as true as it was.
+ *
+ * **It is inert without HR.** Nothing here imports HR, depends on it, or assumes it is installed:
+ * `hr.person.status_changed` simply never arrives in a workspace that has no HR, and the second
+ * caller — `core.member.removed` — is core's own event and needs nothing at all. Both paths check
+ * the *inventory* module is switched on for the workspace before doing anything, because an event
+ * bus is instance-wide and a workspace that has never enabled this module must not be sent its
+ * notifications.
+ */
+export declare class OffboardingService {
+    private readonly kernel;
+    private readonly notify;
+    constructor(kernel: Kernel, notify: NotifyService);
+    /**
+     * What one person is still recorded as holding.
+     *
+     * Read from `assets.custodian_user_id` — denormalised inside the transaction that writes the
+     * custody period, and indexed — rather than from an open-period join, which is the same choice
+     * `custody.byUser` makes and for the same reason. Archived rows cannot appear: an item somebody
+     * holds cannot be archived at all, because `assets.archive` refuses it.
+     */
+    held(workspaceId: string, userId: string): Promise<ReturnList['items']>;
+    /**
+     * Raise the return list, if there is one.
+     *
+     * Answers with what it found and who it told, so a test can assert both and a caller can log the
+     * count. Doing nothing is the ordinary case — most people leave holding nothing — and it is not
+     * an error.
+     *
+     * Redelivery sends the same message again: an event handler is retried, and `core.notifications
+     * .create` has no idempotency key. The two events behind this are rare enough that the cost is a
+     * duplicate row rather than a stream, and `groupKey` collapses them where a client groups. That
+     * is the same trade `module-tracker`'s `due-soon` makes, written down rather than assumed.
+     */
+    raise(workspaceId: string, userId: string, departure: Departure): Promise<ReturnList>;
+    /**
+     * What to call the person in the sentence.
+     *
+     * Core is asked, and a failure falls back to "a former member" rather than to the uuid: a
+     * notification with a uuid in the middle of it is the product admitting it does not know who it
+     * is talking about, and this module already refuses to print one on a screen for the same reason.
+     */
+    private nameOf;
+}
+//# sourceMappingURL=offboarding.d.ts.map

package/dist/server/services/offboarding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offboarding.d.ts","sourceRoot":"","sources":["../../../src/server/services/offboarding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAK5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAYhD,+FAA+F;AAC/F,MAAM,MAAM,SAAS;AACnB,2EAA2E;AACzE,SAAS;AACX,qGAAqG;GACnG,SAAS,CAAA;AAEb,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxD,2FAA2F;IAC3F,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,aAAa;IAGxC;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAiB7E;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IA8C3F;;;;;;OAMG;YACW,MAAM;CAMrB"}

package/dist/server/services/offboarding.js

@@ -0,0 +1,116 @@
+import { and, asc, eq, isNull } from 'drizzle-orm';
+import { MODULE_ID } from '../../contract/models.js';
+import { assets } from '../schema.js';
+import { membersWithPermission } from './audience.js';
+import { assetUrl } from './search.js';
+/** How many tags fit in one sentence before it stops being readable. */
+const TAGS_IN_BODY = 5;
+/**
+ * More than anybody is plausibly holding, and a bound all the same: this reads every live asset of
+ * one person, and an unbounded query in an event handler is an unbounded query.
+ */
+const MAX_HELD = 200;
+/**
+ * Somebody is leaving, and the register still says things are theirs.
+ *
+ * **This raises a checklist and notifies. It never moves anything.** Custody changes because a
+ * person did something — handed an item over, handed it on, took it back — and every one of those
+ * writes a period row and a line of history saying who did it. A hook that quietly returned an
+ * item on somebody's last day would write a handover nobody performed, into the one record the
+ * company later argues from; and the laptop would still be in their bag. So the answer is a message
+ * to the people who can take it back, and the register stays exactly as true as it was.
+ *
+ * **It is inert without HR.** Nothing here imports HR, depends on it, or assumes it is installed:
+ * `hr.person.status_changed` simply never arrives in a workspace that has no HR, and the second
+ * caller — `core.member.removed` — is core's own event and needs nothing at all. Both paths check
+ * the *inventory* module is switched on for the workspace before doing anything, because an event
+ * bus is instance-wide and a workspace that has never enabled this module must not be sent its
+ * notifications.
+ */
+export class OffboardingService {
+    kernel;
+    notify;
+    constructor(kernel, notify) {
+        this.kernel = kernel;
+        this.notify = notify;
+    }
+    /**
+     * What one person is still recorded as holding.
+     *
+     * Read from `assets.custodian_user_id` — denormalised inside the transaction that writes the
+     * custody period, and indexed — rather than from an open-period join, which is the same choice
+     * `custody.byUser` makes and for the same reason. Archived rows cannot appear: an item somebody
+     * holds cannot be archived at all, because `assets.archive` refuses it.
+     */
+    async held(workspaceId, userId) {
+        return this.kernel.database.withWorkspace(workspaceId, (tx) => tx
+            .select({ id: assets.id, code: assets.code, name: assets.name })
+            .from(assets)
+            .where(and(eq(assets.workspaceId, workspaceId), eq(assets.custodianUserId, userId), isNull(assets.archivedAt)))
+            .orderBy(asc(assets.code))
+            .limit(MAX_HELD));
+    }
+    /**
+     * Raise the return list, if there is one.
+     *
+     * Answers with what it found and who it told, so a test can assert both and a caller can log the
+     * count. Doing nothing is the ordinary case — most people leave holding nothing — and it is not
+     * an error.
+     *
+     * Redelivery sends the same message again: an event handler is retried, and `core.notifications
+     * .create` has no idempotency key. The two events behind this are rare enough that the cost is a
+     * duplicate row rather than a stream, and `groupKey` collapses them where a client groups. That
+     * is the same trade `module-tracker`'s `due-soon` makes, written down rather than assumed.
+     */
+    async raise(workspaceId, userId, departure) {
+        if (!(await this.kernel.isModuleEnabled(workspaceId, MODULE_ID).catch(() => false)))
+            return { items: [], recipients: [] };
+        const items = await this.held(workspaceId, userId);
+        if (!items.length)
+            return { items: [], recipients: [] };
+        // Whoever may take an item back, which is the thing this message is asking for. Not "the
+        // admins": a workspace that gave its office manager a custom role did that on purpose.
+        const recipients = await membersWithPermission(this.kernel, workspaceId, 'inventory.custody.manage');
+        if (!recipients.length) {
+            this.kernel.log.warn({ module: MODULE_ID, workspaceId, held: items.length }, 'inventory: somebody left holding items and nobody in the workspace may take them back');
+            return { items, recipients: [] };
+        }
+        const who = await this.nameOf(userId);
+        const tags = items.slice(0, TAGS_IN_BODY).map((item) => `${item.code} ${item.name}`);
+        const rest = items.length - tags.length;
+        await this.notify.notify({
+            workspaceId,
+            userIds: recipients,
+            type: 'inventory.custody.return_due',
+            title: departure === 'removed'
+                ? `${who} has left the workspace still holding ${items.length === 1 ? 'an item' : `${items.length} items`}`
+                : `${who} is leaving and still holds ${items.length === 1 ? 'an item' : `${items.length} items`}`,
+            body: rest > 0 ? `${tags.join(', ')} and ${rest} more` : tags.join(', '),
+            // One item has an object worth pointing at; several do not, and naming the first would send
+            // everybody to one laptop out of five. The URL below is the list either way.
+            object: items.length === 1 ? { module: MODULE_ID, type: 'asset', id: items[0].id } : null,
+            url: items.length === 1 ? assetUrl(items[0].id) : `/inventory?custodian=${userId}`,
+            data: { userId, departure, assetIds: items.map((item) => item.id) },
+            // One group per person, so the two events cannot stack two separate piles about one leaver.
+            groupKey: `inventory.return_due.${userId}`,
+            // Never to the person leaving: they are being *chased*, and on the `removed` path they are no
+            // longer a member of this workspace at all.
+            exclude: [userId],
+        });
+        return { items, recipients };
+    }
+    /**
+     * What to call the person in the sentence.
+     *
+     * Core is asked, and a failure falls back to "a former member" rather than to the uuid: a
+     * notification with a uuid in the middle of it is the product admitting it does not know who it
+     * is talking about, and this module already refuses to print one on a screen for the same reason.
+     */
+    async nameOf(userId) {
+        const user = await this.kernel
+            .call('core.users.get', { id: userId })
+            .catch(() => null);
+        return user?.name?.trim() || user?.email?.trim() || 'A former member';
+    }
+}
+//# sourceMappingURL=offboarding.js.map

package/dist/server/services/offboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offboarding.js","sourceRoot":"","sources":["../../../src/server/services/offboarding.ts"],"names":[],"mappings":"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"}

package/dist/server/services/repairs.d.ts

@@ -0,0 +1,204 @@
+import { type Tx } from '@kernhq/kernel';
+import type { RepairInput, RepairListItem, Repair as RepairModel, RepairPatchInput } from '../../contract/models.js';
+import { assets, repairs } from '../schema.js';
+import type { HistoryInput, NotifyService } from './notify.js';
+type Row = typeof repairs.$inferSelect;
+type AssetRow = typeof assets.$inferSelect;
+/** The wire shape: drizzle gives Date objects for timestamps, the contract promises ISO strings. */
+export declare function toRepair(row: Row): RepairModel;
+/**
+ * What one repair mutation wrote, and what may only leave the module once it has committed.
+ *
+ * The asset comes back beside the repair because sending an item away moves `assets.status`, and a
+ * caller that fetched the asset again afterwards would be reading a row somebody else may have
+ * changed in between — the panel would then show a repair that has already been completed.
+ */
+export interface RepairWritten {
+    repair: Row;
+    asset: AssetRow;
+    /** `null` when nothing happened worth recording, which is what an edit that changed nothing is. */
+    activity: HistoryInput | null;
+}
+export interface RepairListInput {
+    limit: number;
+    cursor?: string;
+    assetId?: string;
+    /** `true` for still away, `false` for finished, absent for both. */
+    open?: boolean;
+}
+/**
+ * What went away to be fixed, and what came back.
+ *
+ * Three things happen in one transaction on every change here, and the point of the class is that
+ * they cannot come apart: the repair row moves, `assets.status` is brought into step with it through
+ * `deriveStatus`, and an `asset_history` entry records it.
+ *
+ * **The database is the arbiter of "already away", not this file.** There is deliberately no
+ * `select … for update` on the asset *before* the repair row is written:
+ * `inventory_repairs_one_open_uq` — a unique index on `(asset_id) where returned_on is null` — is
+ * what makes two open repairs impossible, so two people pressing *Send for repair* on the same
+ * laptop in the same instant both read "it is here", both insert, and Postgres refuses exactly one
+ * of them. Checking first and inserting after is the race, not the fix. What this file owes the
+ * loser is a sentence they can act on rather than drizzle's "Failed query: insert into
+ * mod_inventory.repairs …".
+ *
+ * **`restamp` does lock it, afterwards, and that is a different job.** `assets.status` is derived
+ * from this module's repair rows *and* from custody, which another service writes, so the winner
+ * still has to compute an answer nobody can overwrite from a stale snapshot. See `lockAsset` in
+ * `status.ts`: the index decides the contest, the lock orders the bookkeeping that follows it.
+ *
+ * **Repairs do not touch custody.** An item at the repairer is still somebody's responsibility; see
+ * `status.ts`, where that rule is argued in full.
+ */
+export declare class RepairService {
+    private readonly notify;
+    constructor(notify: NotifyService);
+    /**
+     * Today, as this module means it: the UTC date.
+     *
+     * Not the browser's date, and not a workspace time zone — a repair is dated to the day, and the
+     * two hours a workspace in Istanbul is ahead of UTC would put an evening repair on tomorrow for
+     * one reader and today for another. One clock, the server's, the same reasoning that keeps asset
+     * tags server-side. A workspace that needs the exact day sends `sentOn` itself.
+     */
+    private static today;
+    /** The one error a lost race produces, in every place a race can be lost. */
+    private static alreadyAway;
+    /**
+     * A repair cannot come back before it was sent — checked on every path that writes either date.
+     *
+     * `complete` has always refused a return date before the send date, and `update` did not: it took
+     * `sentOn` from the patch and wrote it whatever the row already said, so correcting the send date
+     * of a *finished* repair could move it past the day the item came back. What that stores is a
+     * repair that ended before it started — every "how long was it away" answer negative, the overdue
+     * sweep measuring from a date in the future, and nothing anywhere to say which of the two dates is
+     * the wrong one.
+     *
+     * Both are `date` columns, so they read back as `YYYY-MM-DD` and compare correctly as text.
+     *
+     * The database holds the same rule (`inventory_repairs_returned_after_sent`), because two
+     * transactions can each pass this check and still write a pair that fails it: one moving `sent_on`
+     * while the other logs the item back. This runs first so the ordinary case gets a sentence rather
+     * than a constraint violation; `outOfOrder` is what the loser of that race gets.
+     */
+    private static requireInOrder;
+    private static outOfOrder;
+    /**
+     * One day past today, which is the whole tolerance a date typed by a person needs.
+     *
+     * `today()` is UTC — one clock, the server's, for the reason it documents — and a workspace in
+     * Auckland is up to fourteen hours ahead of it, so *their* today is UTC's tomorrow for a large
+     * part of their working day. Refusing at exactly UTC-today would refuse the ordinary case in half
+     * the world's offices. A day is enough for every real time zone and is nowhere near enough to be
+     * the defect below.
+     */
+    private static readonly FUTURE_GRACE_DAYS;
+    /**
+     * A repair cannot be sent from the future — checked on every path that writes `sent_on`.
+     *
+     * `sentOn` is a date a person types, and nothing bounded it. A repair dated 2030 is one the
+     * overdue sweep can never find: it looks for `sent_on <= today - repairOverdueDays`, so a send
+     * date years ahead is permanently outside the window and the chase never fires. Not for a while —
+     * **ever**, for the life of that row, and silently, because a sweep that finds nothing looks
+     * exactly like a sweep with nothing to do. It also makes every "how long has it been away" answer
+     * negative and puts the item at the top of a list ordered by when it left.
+     *
+     * A typo is the likely cause and a deliberate one is the dangerous case: this is the one field
+     * that decides whether anybody is ever reminded that a vendor still has the company's laptop.
+     *
+     * Bounded on the *server*, not in the contract, and both halves of that are deliberate. The
+     * contract is shared with the browser, so a `refine` there would compare against the reader's own
+     * clock — and a client whose date is a day ahead would refuse a date the server accepts, or the
+     * other way round. And it is a sentence rather than a bare `invalid_string`, because "a repair
+     * cannot be sent in the future" is something a person can act on.
+     *
+     * **A `BAD_REQUEST` with no `reason`, like `checkPhoto`'s refusal and the category check in
+     * `AssetService`.** The date is malformed rather than contested — nothing raced, no state
+     * changed underneath anybody, the value simply cannot be true — and `CONFLICT` is this module's
+     * word for losing a race. The cost is that the sentence reaches a Persian or Turkish reader in
+     * English: a translated refusal needs a stable `reason` **and** its five bundles in
+     * `src/client/errors.ts`, and the two have to arrive together or `errors.test.ts` fails from
+     * whichever side is ahead.
+     */
+    private static requireNotFuture;
+    private asset;
+    get(tx: Tx, workspaceId: string, repairId: string): Promise<Row>;
+    /**
+     * One asset's repairs, or the whole workspace's — one query with one filter, because they are one
+     * question asked at two scopes and a second query answering it would be a second one to keep in
+     * step.
+     *
+     * **Paged by id, newest logged first.** An id is uuidv7, so it already carries the clock, and it
+     * is unique where `sent_on` is a date two repairs logged on the same day share — a page boundary
+     * between two rows that share a sort key repeats one and drops the other. The same reasoning
+     * `assets.list` gives for `sort: 'recent'` and `assets.history` gives for ordering on the row id.
+     */
+    list(tx: Tx, workspaceId: string, input: RepairListInput): Promise<{
+        items: RepairListItem[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * The currency to store, given what the caller said and what is already there.
+     *
+     * A cost with no unit is not a cost, so an amount recorded with no currency inherits the asset's.
+     * **Inheritance fires in exactly one case** — an amount is being recorded and the repair has no
+     * currency at all — and getting that wrong is silent in both directions:
+     *
+     * - inheriting whenever a cost *exists* rather than whenever one *arrives* means an unrelated
+     *   edit (correcting a vendor) silently gives the asset's currency back to a repair whose
+     *   currency somebody deliberately cleared;
+     * - inheriting over a currency the repair already has means recording an amount in dollars on an
+     *   asset priced in euros quietly relabels it as euros.
+     *
+     * `undefined` means "not mentioned" and an explicit `null` means "no currency", which a workspace
+     * that records amounts and not currencies genuinely means. Collapsing the two is the mistake
+     * `assets.update` documents one file over.
+     */
+    private static currencyFor;
+    /** Send it away. Refuses when it is already at a repairer — that is what `complete` is for. */
+    create(tx: Tx, workspaceId: string, actorId: string | null, assetId: string, input: RepairInput): Promise<RepairWritten>;
+    /**
+     * Correct what was recorded — a vendor, or a cost that arrived with the invoice a week later.
+     *
+     * **`returnedOn` is deliberately not patchable.** 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. Editing a finished repair is allowed all the same: the invoice usually arrives after
+     * the item does.
+     *
+     * **No `actorId`, because nothing here records one.** This writes no timeline entry — see the
+     * bottom of the method — and a parameter kept for symmetry with `create` and `complete` would be
+     * a parameter every caller has to supply and nothing reads.
+     */
+    update(tx: Tx, workspaceId: string, repairId: string, patch: RepairPatchInput): Promise<RepairWritten>;
+    /**
+     * It came back.
+     *
+     * `and returned_on is null` in the predicate is the optimistic guard, exactly as
+     * `CustodyService.close` uses: under READ COMMITTED a concurrent complete blocks this statement,
+     * and when it resumes the row no longer matches, so zero rows come back rather than a second
+     * completion silently overwriting the first one's date.
+     */
+    complete(tx: Tx, workspaceId: string, actorId: string | null, repairId: string, input: {
+        returnedOn?: string;
+        costMinor?: number | null;
+        currency?: string | null;
+    }): Promise<RepairWritten>;
+    /**
+     * Bring `assets.status` back into step with the facts, inside the same transaction.
+     *
+     * Both facts are **read** rather than assumed — the open repair as it now stands, and the
+     * custodian as the asset row carries it — and `deriveStatus` decides. Assuming `under_repair`
+     * after an insert and `in_stock` after a completion is the version of this that silently released
+     * whoever was still holding the item.
+     *
+     * **The asset is locked and re-read here, rather than passed in.** It used to take the row the
+     * caller had already fetched, which is a snapshot from before the repair was written and before
+     * anything else that touched the asset in between: a handover committing in that window was
+     * invisible, so this derived a status from a custodian that had stopped being current and wrote it
+     * over the handover's answer. Taking the row under the lock is what makes "read both facts, then
+     * derive" true rather than merely intended. `lockAsset` argues it in full.
+     */
+    private restamp;
+}
+export {};
+//# sourceMappingURL=repairs.d.ts.map

package/dist/server/services/repairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repairs.d.ts","sourceRoot":"","sources":["../../../src/server/services/repairs.ts"],"names":[],"mappings":"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"}