@kernhq/module-inventory 0.1.2 → 0.3.0

package/dist/server/services/db-errors.js

@@ -0,0 +1,32 @@
+/**
+ * Which constraint Postgres refused a write with, dug out of what drizzle hands back.
+ *
+ * A database constraint is only half a feature. `inventory_custody_no_overlap` makes two open
+ * custody periods for one asset impossible — but two people pressing *Hand over* on the same laptop
+ * at the same instant means the loser is shown drizzle's own text, "Failed query: insert into
+ * mod_inventory.custody_periods …", which tells a person nothing they can act on and looks like the
+ * product broke rather than like somebody else got there first.
+ *
+ * So the service catches, asks these two questions, and throws a `KernError.conflict` with a
+ * sentence. Reaching through `cause` rather than reading the top frame is the load-bearing part:
+ * drizzle wraps the driver's error, and the driver's error is the only object carrying `code` and
+ * `constraint`. `src/server/inventory.int.test.ts` walks the same chain for the same reason.
+ */
+const MAX_DEPTH = 5;
+function walk(err, read) {
+    let cursor = err;
+    for (let depth = 0; depth < MAX_DEPTH && cursor; depth++) {
+        const found = read(cursor);
+        if (found)
+            return found;
+        cursor = cursor.cause;
+    }
+    return undefined;
+}
+/** The constraint's name, if a named one refused the write. */
+export const constraintOf = (err) => walk(err, (e) => (typeof e.constraint === 'string' ? e.constraint : undefined));
+/** The SQLSTATE, if one reached us. `23P01` is an exclusion violation, `23505` a unique one. */
+export const sqlStateOf = (err) => walk(err, (e) => (typeof e.code === 'string' && /^[0-9A-Z]{5}$/.test(e.code) ? e.code : undefined));
+/** Did this write lose to `name`, whichever way Postgres reported it? */
+export const violated = (err, name) => constraintOf(err) === name;
+//# sourceMappingURL=db-errors.js.map

package/dist/server/services/db-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-errors.js","sourceRoot":"","sources":["../../../src/server/services/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,SAAS,GAAG,CAAC,CAAA;AAQnB,SAAS,IAAI,CAAC,GAAY,EAAE,IAA4C;IACtE,IAAI,MAAM,GAAY,GAAG,CAAA;IACzB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,IAAI,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAqB,CAAC,CAAA;QACzC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAA;QACvB,MAAM,GAAI,MAAsB,CAAC,KAAK,CAAA;IACxC,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAY,EAAsB,EAAE,CAC/D,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;AAEjF,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAY,EAAsB,EAAE,CAC7D,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;AAErG,yEAAyE;AACzE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAY,EAAE,IAAY,EAAW,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,IAAI,CAAA"}

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

@@ -0,0 +1,26 @@
+import type { Kernel } from '@kernhq/kernel';
+import { AssetService } from './assets.js';
+import { AttachmentService } from './attachments.js';
+import { CategoryService } from './categories.js';
+import { CustodyService } from './custody.js';
+import { NotifyService } from './notify.js';
+import { OffboardingService } from './offboarding.js';
+import { RepairService } from './repairs.js';
+import { SearchService } from './search.js';
+import { StatsService } from './stats.js';
+export interface InventoryServices {
+    notify: NotifyService;
+    assets: AssetService;
+    categories: CategoryService;
+    custody: CustodyService;
+    repairs: RepairService;
+    attachments: AttachmentService;
+    stats: StatsService;
+    /** The workspace-wide index, and the documents behind `inventory:asset:<id>`. */
+    search: SearchService;
+    /** Somebody left holding company property. Raises a checklist; never moves custody. */
+    offboarding: OffboardingService;
+}
+/** One service graph per kernel instance; the router, jobs and procedures all share it. */
+export declare function inventoryServices(kernel: Kernel): InventoryServices;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAA;IACrB,MAAM,EAAE,YAAY,CAAA;IACpB,UAAU,EAAE,eAAe,CAAA;IAC3B,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;IACtB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,KAAK,EAAE,YAAY,CAAA;IACnB,iFAAiF;IACjF,MAAM,EAAE,aAAa,CAAA;IACrB,uFAAuF;IACvF,WAAW,EAAE,kBAAkB,CAAA;CAChC;AAID,2FAA2F;AAC3F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CA2BnE"}

package/dist/server/services/index.js

@@ -0,0 +1,39 @@
+import { AssetService } from './assets.js';
+import { AttachmentService } from './attachments.js';
+import { CategoryService } from './categories.js';
+import { CustodyService } from './custody.js';
+import { NotifyService } from './notify.js';
+import { OffboardingService } from './offboarding.js';
+import { RepairService } from './repairs.js';
+import { SearchService } from './search.js';
+import { StatsService } from './stats.js';
+const cache = new WeakMap();
+/** One service graph per kernel instance; the router, jobs and procedures all share it. */
+export function inventoryServices(kernel) {
+    const existing = cache.get(kernel);
+    if (existing)
+        return existing;
+    const notify = new NotifyService(kernel);
+    const assets = new AssetService(kernel, notify);
+    const categories = new CategoryService();
+    const custody = new CustodyService(notify);
+    const repairs = new RepairService(notify);
+    const attachments = new AttachmentService(kernel, notify);
+    const stats = new StatsService();
+    const search = new SearchService(kernel, notify);
+    const offboarding = new OffboardingService(kernel, notify);
+    const services = {
+        notify,
+        assets,
+        categories,
+        custody,
+        repairs,
+        attachments,
+        stats,
+        search,
+        offboarding,
+    };
+    cache.set(kernel, services);
+    return services;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/server/services/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAgBzC,MAAM,KAAK,GAAG,IAAI,OAAO,EAA6B,CAAA;AAEtD,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAE7B,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IACxC,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;IACxC,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAA;IAC1C,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAA;IACzC,MAAM,WAAW,GAAG,IAAI,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAA;IAChC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChD,MAAM,WAAW,GAAG,IAAI,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE1D,MAAM,QAAQ,GAAsB;QAClC,MAAM;QACN,MAAM;QACN,UAAU;QACV,OAAO;QACP,OAAO;QACP,WAAW;QACX,KAAK;QACL,MAAM;QACN,WAAW;KACZ,CAAA;IACD,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IAC3B,OAAO,QAAQ,CAAA;AACjB,CAAC"}

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

@@ -0,0 +1,27 @@
+import { type Kernel } from '@kernhq/kernel';
+/**
+ * Is this person somebody this workspace can hand a laptop to?
+ *
+ * **`custody.assign` and `custody.transfer` took any uuid.** The id arrives in the request, nothing
+ * looked it up, and the module then wrote it into `custody_periods.user_id` and
+ * `assets.custodian_user_id` — the two columns that answer "who is answerable for this" for the rest
+ * of the item's life — and sent a notification to it. So a member of one workspace could record a
+ * *stranger* as holding company property, and the product would then chase that stranger about it.
+ * Every screen renders an id it cannot resolve as "a former member", which is the honest thing for a
+ * screen to say and exactly what hides this: the register looks plausible and names nobody real.
+ *
+ * The check is a question for core, because membership is core's fact and this module has no copy of
+ * it. `core.users.principal` answers with one person rather than the workspace's whole roll, which
+ * matters on an instance where a workspace has thousands of seats and this runs on every handover.
+ *
+ * **`active`, not merely present.** An invitation nobody has accepted is not somebody who can be
+ * handed a thing, and a suspended account is one the workspace has deliberately shut out.
+ *
+ * **A failure here refuses rather than waves through.** Every other cross-service call this module
+ * makes is best-effort, and this one deliberately is not: swallowing the failure would mean the
+ * check silently stops existing exactly while core is unwell, which is indistinguishable from not
+ * having written it. `UNAVAILABLE` is 503 and says the true thing — the answer is not knowable right
+ * now — where a 400 would tell somebody their colleague is not a member.
+ */
+export declare function requireWorkspaceMember(kernel: Kernel, workspaceId: string, userId: string): Promise<void>;
+//# sourceMappingURL=members.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../../../src/server/services/members.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/server/services/members.js

@@ -0,0 +1,39 @@
+import { KernError } from '@kernhq/kernel';
+/**
+ * Is this person somebody this workspace can hand a laptop to?
+ *
+ * **`custody.assign` and `custody.transfer` took any uuid.** The id arrives in the request, nothing
+ * looked it up, and the module then wrote it into `custody_periods.user_id` and
+ * `assets.custodian_user_id` — the two columns that answer "who is answerable for this" for the rest
+ * of the item's life — and sent a notification to it. So a member of one workspace could record a
+ * *stranger* as holding company property, and the product would then chase that stranger about it.
+ * Every screen renders an id it cannot resolve as "a former member", which is the honest thing for a
+ * screen to say and exactly what hides this: the register looks plausible and names nobody real.
+ *
+ * The check is a question for core, because membership is core's fact and this module has no copy of
+ * it. `core.users.principal` answers with one person rather than the workspace's whole roll, which
+ * matters on an instance where a workspace has thousands of seats and this runs on every handover.
+ *
+ * **`active`, not merely present.** An invitation nobody has accepted is not somebody who can be
+ * handed a thing, and a suspended account is one the workspace has deliberately shut out.
+ *
+ * **A failure here refuses rather than waves through.** Every other cross-service call this module
+ * makes is best-effort, and this one deliberately is not: swallowing the failure would mean the
+ * check silently stops existing exactly while core is unwell, which is indistinguishable from not
+ * having written it. `UNAVAILABLE` is 503 and says the true thing — the answer is not knowable right
+ * now — where a 400 would tell somebody their colleague is not a member.
+ */
+export async function requireWorkspaceMember(kernel, workspaceId, userId) {
+    let principal;
+    try {
+        principal = await kernel.call('core.users.principal', { userId });
+    }
+    catch (err) {
+        kernel.log.warn({ err: err instanceof Error ? err.message : String(err), workspaceId }, 'inventory: could not check whether the new custodian is a member');
+        throw new KernError('UNAVAILABLE', 'Who belongs to this workspace cannot be checked right now. Try again in a moment.');
+    }
+    const member = (principal?.memberships ?? []).some((m) => m.workspaceId === workspaceId && m.status === 'active');
+    if (!member)
+        throw KernError.badRequest('That person is not a member of this workspace, so nothing can be handed to them.');
+}
+//# sourceMappingURL=members.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"members.js","sourceRoot":"","sources":["../../../src/server/services/members.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAe,MAAM,gBAAgB,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAc,EACd,WAAmB,EACnB,MAAc;IAEd,IAAI,SAA2B,CAAA;IAC/B,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAmB,sBAAsB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAA;IACrF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,CAAC,IAAI,CACb,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,EACtE,kEAAkE,CACnE,CAAA;QACD,MAAM,IAAI,SAAS,CACjB,aAAa,EACb,mFAAmF,CACpF,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,CAC9D,CAAA;IACD,IAAI,CAAC,MAAM;QACT,MAAM,SAAS,CAAC,UAAU,CACxB,kFAAkF,CACnF,CAAA;AACL,CAAC"}

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

@@ -0,0 +1,105 @@
+import type { core, EntityChange, ObjectRef } from '@kernhq/contracts';
+import { type Kernel, type Tx } from '@kernhq/kernel';
+export interface HistoryInput {
+    workspaceId: string;
+    assetId: string;
+    actorId: string | null;
+    action: string;
+    changes?: Array<{
+        field: string;
+        from: unknown;
+        to: unknown;
+    }>;
+    data?: Record<string, unknown>;
+}
+export interface NotifyInput {
+    workspaceId: string;
+    userIds: Iterable<string>;
+    type: string;
+    title: string;
+    body?: string | null;
+    object?: ObjectRef | null;
+    url?: string | null;
+    data?: Record<string, unknown>;
+    groupKey?: string | null;
+    actorId?: string | null;
+    /** never notify the person who caused the change */
+    exclude?: Iterable<string | null | undefined>;
+}
+/**
+ * Side effects that leave the module: activity, notifications, realtime and the search index.
+ *
+ * All of them are best-effort. An inventory mutation must not fail because the core service is
+ * briefly unavailable, so every cross-module call is swallowed and logged — the local
+ * `asset_history` row is written inside the caller's transaction and remains the authoritative
+ * record of what happened.
+ */
+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.
+     *
+     * This row is the authoritative record and belongs in the transaction it describes — if the write
+     * rolls back, so does its history. The mirror of it in core's activity feed is `activity()`, and
+     * it deliberately does **not** happen here: it used to, fired off with `void` while the
+     * transaction was still open, so a rollback left the workspace's feed showing an event for an id
+     * that never existed. The caller flushes it after the commit, beside the event and the realtime
+     * change, which is what everything else in this module already does.
+     */
+    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>;
+    /**
+     * 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>;
+}
+//# sourceMappingURL=notify.d.ts.map

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

@@ -0,0 +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;;;;;;;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

@@ -0,0 +1,147 @@
+import { uuidv7 } from '@kernhq/kernel';
+import { MODULE_ID } from '../../contract/models.js';
+import { assetHistory } from '../schema.js';
+/**
+ * Side effects that leave the module: activity, notifications, realtime and the search index.
+ *
+ * All of them are best-effort. An inventory mutation must not fail because the core service is
+ * briefly unavailable, so every cross-module call is swallowed and logged — the local
+ * `asset_history` row is written inside the caller's transaction and remains the authoritative
+ * record of what happened.
+ */
+export class NotifyService {
+    kernel;
+    constructor(kernel) {
+        this.kernel = kernel;
+    }
+    async best(what, fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            this.kernel.log.warn({ err: err instanceof Error ? err.message : err, what }, 'inventory side effect failed');
+            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.
+     *
+     * This row is the authoritative record and belongs in the transaction it describes — if the write
+     * rolls back, so does its history. The mirror of it in core's activity feed is `activity()`, and
+     * it deliberately does **not** happen here: it used to, fired off with `void` while the
+     * transaction was still open, so a rollback left the workspace's feed showing an event for an id
+     * that never existed. The caller flushes it after the commit, beside the event and the realtime
+     * change, which is what everything else in this module already does.
+     */
+    async history(tx, input) {
+        await tx.insert(assetHistory).values({
+            id: uuidv7(),
+            workspaceId: input.workspaceId,
+            assetId: input.assetId,
+            actorId: input.actorId,
+            action: input.action,
+            changes: input.changes ?? [],
+            data: input.data ?? {},
+        });
+    }
+    /** The workspace-wide activity feed's copy. Best-effort, and only ever after the commit. */
+    async activity(input) {
+        await this.best('activity.record', () => this.kernel.call('core.activity.record', {
+            workspaceId: input.workspaceId,
+            module: MODULE_ID,
+            object: { module: MODULE_ID, type: 'asset', id: input.assetId },
+            action: input.action,
+            actorId: input.actorId,
+            changes: input.changes ?? [],
+            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 { 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,
+            type: input.type,
+            title: input.title,
+            body: input.body ?? null,
+            object: input.object ?? null,
+            url: input.url ?? null,
+            data: input.data ?? {},
+            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 = {}) {
+        await this.best('realtime.change', () => this.kernel.realtime.change(workspaceId, {
+            module: MODULE_ID,
+            entity,
+            id,
+            op,
+            ...(opts.patch ? { patch: opts.patch } : {}),
+            ...(opts.scope ? { scope: opts.scope } : {}),
+        }));
+    }
+    /**
+     * 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;
+        await this.best('search.index', () => this.kernel.call('core.search.index', { documents }));
+    }
+    async unindex(workspaceId, type, ids) {
+        if (!ids.length)
+            return;
+        await this.best('search.remove', () => this.kernel.call('core.search.remove', {
+            refs: ids.map((id) => ({ workspaceId, object: { module: MODULE_ID, type, id } })),
+        }));
+    }
+}
+//# sourceMappingURL=notify.js.map

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

@@ -0,0 +1 @@
+{"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"}