@kernhq/module-inventory 0.2.0 → 0.4.0

package/dist/server/services/search.js

@@ -0,0 +1,142 @@
+import { and, eq, isNull, sql } from 'drizzle-orm';
+import { MODULE_ID } from '../../contract/models.js';
+import { assets, categories } from '../schema.js';
+/** One page of the full reindex. Big enough to be worth a round trip, small enough to hold. */
+const SCAN_BATCH = 500;
+/**
+ * How an asset is referred to from outside this module.
+ *
+ * One function, because a search hit and a resolved `inventory:asset:<id>` reference have to be the
+ * same thing — somebody who finds a laptop in the command palette and somebody who follows a link to
+ * it from a chat message are looking at the same row and must see the same words for it.
+ */
+export const assetUrl = (assetId) => `/inventory?asset=${assetId}`;
+export const ASSET_ICON = 'briefcase';
+/**
+ * What a person types into the command palette, and what an asset has to answer it with.
+ *
+ * An asset tag read off a sticker is the first of these — `INV-0042` is what somebody has in their
+ * hand — so it leads the title, exactly as tracker leads with an issue key. The rest is everything
+ * printed on or near the thing: its name, its serial number, where it is kept, and what the
+ * workspace files it under.
+ *
+ * **The category is indexed by name, not by id.** "chair" finds every chair filed under Furniture
+ * only if the word Furniture is in the document; an id in `attributes` is a filter, not a search
+ * term. The cost is that renaming a category leaves its assets' documents naming the old word until
+ * each one is next written, which is a staleness worth stating and not worth a workspace-wide
+ * rewrite on every rename — `core.search.reindex` is the thing that fixes it, and it exists.
+ *
+ * `acl` is null: an asset is visible to anybody with `inventory.asset.view`, which is a workspace
+ * permission and not a per-row one, so there is no narrower audience to name.
+ */
+export function assetSearchDocument(workspaceId, row) {
+    const body = [row.asset.description, row.asset.serialNumber, row.asset.location, row.categoryName]
+        .map((part) => part?.trim())
+        .filter((part) => Boolean(part))
+        .join('\n');
+    return {
+        workspaceId: workspaceId,
+        object: { module: MODULE_ID, type: 'asset', id: row.asset.id },
+        title: `${row.asset.code} ${row.asset.name}`,
+        body: body || null,
+        url: assetUrl(row.asset.id),
+        icon: ASSET_ICON,
+        acl: null,
+        updatedAt: row.asset.updatedAt.toISOString(),
+        attributes: {
+            code: row.asset.code,
+            status: row.asset.status,
+            categoryId: row.asset.categoryId,
+            custodianUserId: row.asset.custodianUserId,
+        },
+    };
+}
+/** The one select every read here makes: the asset, plus its category's current name. */
+const withCategoryName = (tx) => tx
+    .select({ asset: assets, categoryName: categories.name })
+    .from(assets)
+    .leftJoin(categories, and(eq(categories.id, assets.categoryId), eq(categories.workspaceId, assets.workspaceId)));
+/**
+ * Putting assets into the workspace-wide search index, and taking them out again.
+ *
+ * `NotifyService` has carried `index`/`unindex` since the module was written and nothing called
+ * either, because `objectTypes` had been taken off the manifest — a declared type with no indexer
+ * and no resolver renders a link to nothing, which reads to a person as a broken product rather
+ * than as a feature that has not shipped. Both halves arrive together here.
+ *
+ * Every method is best-effort by way of `NotifyService`: an asset must not fail to save because the
+ * core search service is briefly away. The register's own row is authoritative and a later
+ * `core.search.reindex` repairs whatever was missed, which is exactly what that job is for.
+ */
+export class SearchService {
+    kernel;
+    notify;
+    constructor(kernel, notify) {
+        this.kernel = kernel;
+        this.notify = notify;
+    }
+    /**
+     * One asset as a document, or `null` for one the index should not hold.
+     *
+     * `null` for a row that is gone **and** for one that is archived, because the indexer treats null
+     * as "remove this": an archived asset is one the workspace has said it no longer tracks, so
+     * finding it in the command palette would offer a door to something deliberately put away.
+     * Restoring it writes the row again, which reindexes it.
+     */
+    async load(workspaceId, assetId) {
+        return this.kernel.database.withWorkspace(workspaceId, async (tx) => {
+            const [row] = await withCategoryName(tx)
+                .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+                .limit(1);
+            if (!row || row.asset.archivedAt)
+                return null;
+            return assetSearchDocument(workspaceId, row);
+        });
+    }
+    /**
+     * Every live asset of a workspace, in pages, for a full reindex.
+     *
+     * Keyset by id rather than `offset`: a scan of a big workspace runs for a while, and an offset
+     * walk over a table somebody is writing to repeats and drops rows. Ids are uuidv7 and unique, so
+     * one column is a page boundary two rows cannot share — the same reasoning `assets.list` gives.
+     *
+     * One transaction per page rather than one for the whole scan: holding a pooled connection open
+     * across a reindex of ten thousand rows is how a service runs out of connections doing
+     * maintenance.
+     */
+    async *scan(workspaceId) {
+        let cursor = null;
+        for (;;) {
+            const rows = await this.kernel.database.withWorkspace(workspaceId, (tx) => withCategoryName(tx)
+                .where(and(eq(assets.workspaceId, workspaceId), isNull(assets.archivedAt), cursor ? sql `${assets.id} > ${cursor}` : sql `true`))
+                .orderBy(assets.id)
+                .limit(SCAN_BATCH));
+            if (!rows.length)
+                return;
+            for (const row of rows)
+                yield assetSearchDocument(workspaceId, row);
+            cursor = rows.at(-1)?.asset.id ?? null;
+        }
+    }
+    /**
+     * Bring the index into step with one asset, whichever direction that means.
+     *
+     * Called after the transaction has committed, never inside it — the index is another service's
+     * table, and telling it about a row a rollback then took away cannot be retracted. It is the
+     * reason `router.ts` announces from outside the transaction and this is announced beside the
+     * event and the realtime change.
+     */
+    async reindex(workspaceId, assetId) {
+        const document = await this.load(workspaceId, assetId).catch((err) => {
+            this.kernel.log.warn({ err: err instanceof Error ? err.message : err, workspaceId, assetId }, 'inventory: could not read an asset to reindex it');
+            return undefined;
+        });
+        if (document === undefined)
+            return;
+        if (document)
+            await this.notify.index([document]);
+        else
+            await this.notify.unindex(workspaceId, 'asset', [assetId]);
+    }
+}
+//# sourceMappingURL=search.js.map

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

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

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

@@ -0,0 +1,42 @@
+import type { Tx } from '@kernhq/kernel';
+import { type InventoryStats } from '../../contract/models.js';
+/**
+ * The register in numbers.
+ *
+ * It exists because the assets page had no honest number to print. `assets.list` is keyset-paged and
+ * never counts, so the count line said "50 assets" for a workspace with 214 of them and then "100
+ * assets" after *Load more* — a number that is simply wrong, on the line whose whole job is to be
+ * the number. A `count(*)` bolted onto every list page would be the expensive answer to that; one
+ * cheap procedure the page calls once is the right one, and it also gives the dashboard card
+ * something worth showing.
+ *
+ * **`total` counts what the list shows by default — live rows.** `archived` sits beside it rather
+ * than inside it, because a count line that silently included archived rows would disagree with the
+ * list underneath it.
+ */
+export declare class StatsService {
+    /**
+     * @param repairsOn whether this workspace has the `repairs` capability. Resolved by the caller
+     * *before* the transaction opens, because it is a settings read over the broker.
+     */
+    summary(tx: Tx, workspaceId: string, repairsOn: boolean): Promise<InventoryStats>;
+    /**
+     * How many live items are at a repairer, counted from the **repair rows** rather than from
+     * `assets.status`.
+     *
+     * `byStatus.under_repair` is the same number, and deliberately arrives a different way: that one
+     * reads the cached column every list filters on, this one reads the fact the column is derived
+     * from. `deriveStatus` is what keeps them equal, and `inventory.int.test.ts` asserts they are —
+     * which is a real check on the derivation rather than two ways of writing the same query.
+     *
+     * **Joined to `assets` for the live rows, which it did not used to be.** The old version leaned on
+     * `AssetService.archive` refusing to retire an item that is away, so every open repair was assumed
+     * to belong to a live asset. That refusal is now withdrawn while the workspace has the `repairs`
+     * capability off — it named a procedure answering 404, and leaving it in place is what stranded
+     * the asset — so an archived row with an open repair is reachable, and `byStatus.under_repair`
+     * (live rows only) would have disagreed with this number the moment the capability came back on.
+     * Two counts of one thing have to be counted over one set.
+     */
+    private away;
+}
+//# sourceMappingURL=stats.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../../src/server/services/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AAExC,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAG3E;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB;;;OAGG;IACG,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAsCvF;;;;;;;;;;;;;;;;OAgBG;YACW,IAAI;CAQnB"}

package/dist/server/services/stats.js

@@ -0,0 +1,80 @@
+import { and, eq, isNull, sql } from 'drizzle-orm';
+import { AssetStatus } from '../../contract/models.js';
+import { assets, repairs } from '../schema.js';
+/**
+ * The register in numbers.
+ *
+ * It exists because the assets page had no honest number to print. `assets.list` is keyset-paged and
+ * never counts, so the count line said "50 assets" for a workspace with 214 of them and then "100
+ * assets" after *Load more* — a number that is simply wrong, on the line whose whole job is to be
+ * the number. A `count(*)` bolted onto every list page would be the expensive answer to that; one
+ * cheap procedure the page calls once is the right one, and it also gives the dashboard card
+ * something worth showing.
+ *
+ * **`total` counts what the list shows by default — live rows.** `archived` sits beside it rather
+ * than inside it, because a count line that silently included archived rows would disagree with the
+ * list underneath it.
+ */
+export class StatsService {
+    /**
+     * @param repairsOn whether this workspace has the `repairs` capability. Resolved by the caller
+     * *before* the transaction opens, because it is a settings read over the broker.
+     */
+    async summary(tx, workspaceId, repairsOn) {
+        const [totals] = await tx
+            .select({
+            total: sql `count(*) filter (where ${assets.archivedAt} is null)`.mapWith(Number),
+            archived: sql `count(*) filter (where ${assets.archivedAt} is not null)`.mapWith(Number),
+            unassigned: sql `count(*) filter (where ${assets.archivedAt} is null and ${assets.custodianUserId} is null)`.mapWith(Number),
+        })
+            .from(assets)
+            .where(eq(assets.workspaceId, workspaceId));
+        const grouped = await tx
+            .select({ status: assets.status, n: sql `count(*)`.mapWith(Number) })
+            .from(assets)
+            .where(and(eq(assets.workspaceId, workspaceId), isNull(assets.archivedAt)))
+            .groupBy(assets.status);
+        /**
+         * Zero-filled over the whole enum, so a screen can render the set without asking which statuses
+         * happen to exist in this workspace. A missing key and a zero look the same on a card and are
+         * not the same thing to a `Record`.
+         */
+        const byStatus = Object.fromEntries(AssetStatus.options.map((status) => [status, 0]));
+        for (const row of grouped)
+            if (row.status in byStatus)
+                byStatus[row.status] = row.n;
+        return {
+            total: totals?.total ?? 0,
+            archived: totals?.archived ?? 0,
+            byStatus,
+            outForRepair: repairsOn ? await this.away(tx, workspaceId) : null,
+            unassigned: totals?.unassigned ?? 0,
+        };
+    }
+    /**
+     * How many live items are at a repairer, counted from the **repair rows** rather than from
+     * `assets.status`.
+     *
+     * `byStatus.under_repair` is the same number, and deliberately arrives a different way: that one
+     * reads the cached column every list filters on, this one reads the fact the column is derived
+     * from. `deriveStatus` is what keeps them equal, and `inventory.int.test.ts` asserts they are —
+     * which is a real check on the derivation rather than two ways of writing the same query.
+     *
+     * **Joined to `assets` for the live rows, which it did not used to be.** The old version leaned on
+     * `AssetService.archive` refusing to retire an item that is away, so every open repair was assumed
+     * to belong to a live asset. That refusal is now withdrawn while the workspace has the `repairs`
+     * capability off — it named a procedure answering 404, and leaving it in place is what stranded
+     * the asset — so an archived row with an open repair is reachable, and `byStatus.under_repair`
+     * (live rows only) would have disagreed with this number the moment the capability came back on.
+     * Two counts of one thing have to be counted over one set.
+     */
+    async away(tx, workspaceId) {
+        const [row] = await tx
+            .select({ n: sql `count(*)`.mapWith(Number) })
+            .from(repairs)
+            .innerJoin(assets, and(eq(assets.id, repairs.assetId), eq(assets.workspaceId, repairs.workspaceId)))
+            .where(and(eq(repairs.workspaceId, workspaceId), isNull(repairs.returnedOn), isNull(assets.archivedAt)));
+        return row?.n ?? 0;
+    }
+}
+//# sourceMappingURL=stats.js.map

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

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

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

@@ -0,0 +1,102 @@
+import { type Tx } from '@kernhq/kernel';
+import type { AssetStatus } from '../../contract/models.js';
+import { assets } from '../schema.js';
+/**
+ * What an asset's status is, decided in one place from the facts that decide it.
+ *
+ * `assets.status` is stored rather than computed, because every list filter asks for it — but it is
+ * **derived**, and the moment two services each wrote their own version of the derivation they
+ * disagreed. That is not hypothetical: `CustodyService.stamp` wrote `userId ? 'assigned' :
+ * 'in_stock'` unconditionally, so handing over a laptop that was sitting at the repairer would have
+ * announced it as back in the office. Both services now read this function, so there is one answer
+ * and a test can hold it.
+ *
+ * ## The rule, written down because it is a decision rather than an inevitability
+ *
+ * **Custody and repair are independent facts, and repair wins the status column.** An item can be
+ * out for repair *while still assigned to somebody*: Dan's laptop goes to the workshop, Dan is still
+ * answerable for it, the custody period stays open and `custodian_user_id` stays set. Only `status`
+ * moves, because `status` is the column that answers *where is it*, and "with a repairer" is the
+ * answer somebody looking for it needs. Custody is answered by `custodian_user_id`, which is a
+ * different column and is not touched.
+ *
+ * Two consequences follow, and both are deliberate:
+ *
+ * - **No custody procedure refuses an item that is away for repair.** Refusing `assign` would mean
+ *   refusing `return` too, and somebody leaving the company while their laptop is at the workshop
+ *   must still be able to hand it back. All three verbs recompute the status through this function
+ *   instead, so a return during a repair leaves the item `under_repair` with nobody holding it,
+ *   which is exactly true.
+ * - **Completing a repair does not blindly go to `in_stock`.** It goes back to whatever custody
+ *   says — `assigned` when somebody still holds it — because the repair never released them.
+ *
+ * `reserved`, `lost` and `retired` are not derivable from anything this module records: they are set
+ * by hand by the features that will own them, and nothing writes them today. When something does,
+ * it either belongs in this function with a fact of its own or it does not belong in this column.
+ *
+ * ## The third fact, which is not about the item at all
+ *
+ * **`under_repair` belongs to the `repairs` capability, so a workspace that has switched repairs
+ * off never has an asset in it.** That is not cosmetic tidying, it is the thing that stopped an
+ * asset being stranded: with the capability off, `repairs.complete` answers 404, so the row that
+ * decides `under_repair` can never be closed — and the item sat in a status nothing could move it
+ * out of, behind an archive that refused it for the same reason. Reading the switch here is what
+ * makes the capability reversible in both directions rather than one: switch repairs off and the
+ * next thing that touches the asset derives its status from custody alone; switch it back on and
+ * the open repair asserts itself again, because nothing was destroyed to get out of it.
+ *
+ * The switch is read *before* the transaction opens, like every other settings lookup in this
+ * module, and handed down as `repairsOn` — a `kernel.settings` call is a broker round trip and
+ * awaiting one while holding a pooled connection is the failure `AssetService.codeFormat`
+ * documents. `jobs.ts` reconciles the rows nobody happens to touch.
+ */
+export interface StatusFacts {
+    /** `assets.custodian_user_id` — who is answerable for it, which a repair does not change. */
+    custodianUserId: string | null;
+    /** An **open repair this workspace is recording** — see `awayForRepair` below. */
+    awayForRepair: boolean;
+}
+export declare function deriveStatus(facts: StatusFacts): AssetStatus;
+/**
+ * Is this item away for a repair the workspace still records?
+ *
+ * Two facts, and the capability is checked first so the query is skipped entirely for a workspace
+ * that does not record repairs. Every caller that decides a status goes through this rather than
+ * through `openRepairId` directly, so there is one answer to "is it away" and a test can hold it.
+ */
+export declare function awayForRepair(tx: Tx, workspaceId: string, assetId: string, repairsOn: boolean): Promise<boolean>;
+/**
+ * The open repair for one asset, if there is one — the query behind `awayForRepair`.
+ *
+ * At most one exists by construction: `inventory_repairs_one_open_uq` is a unique index on
+ * `(asset_id) where returned_on is null`. It lives here rather than in `RepairService` so that
+ * `CustodyService` can read the fact without depending on the whole repair service, and so that
+ * every caller decides a status the same way — read both facts, then call `deriveStatus`, never
+ * assume one of them.
+ */
+/**
+ * The asset row, locked for the rest of the transaction — the serialisation point for `status`.
+ *
+ * **`status` is derived from two facts written by two different services, so the derivation needs a
+ * lock even though neither fact does.** `CustodyService` decides it from custody *and* the open
+ * repair; `RepairService` decides it from the repair *and* the custodian. Each used to read the
+ * other's fact without a lock, so a handover and a repair completing at the same instant
+ * interleaved into a status that matched neither: the second writer had read the first one's fact
+ * before it was written, derived from a snapshot that no longer existed, and overwrote the answer.
+ * That is a lost update in the plain sense — two transactions, one column, one of them silently
+ * discarded.
+ *
+ * Both paths now take this lock **before** reading either fact, so the second one waits, re-reads
+ * what the first committed, and derives from the state that actually exists. `for('update')`
+ * re-evaluates the row at the latest committed version once the lock is granted, which is exactly
+ * what makes the re-read honest rather than a repeat of the stale snapshot.
+ *
+ * **It is not the arbiter of "already held" or "already away".** Those stay with the exclusion
+ * constraint and the partial unique index, for the reason both services' docblocks give: locking
+ * the asset first would serialise two handovers into two *successful* handovers. This lock is taken
+ * after the row that decides the race has been written, so it orders the bookkeeping without
+ * deciding the contest.
+ */
+export declare function lockAsset(tx: Tx, workspaceId: string, assetId: string): Promise<typeof assets.$inferSelect>;
+export declare function openRepairId(tx: Tx, workspaceId: string, assetId: string): Promise<string | undefined>;
+//# sourceMappingURL=status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/server/services/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,EAAE,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,MAAM,EAAW,MAAM,cAAc,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,WAAW,WAAW;IAC1B,6FAA6F;IAC7F,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,kFAAkF;IAClF,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAG5D;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,MAAM,CAAC,YAAY,CAAC,CAQrC;AAED,wBAAsB,YAAY,CAChC,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B"}

package/dist/server/services/status.js

@@ -0,0 +1,71 @@
+import { KernError } from '@kernhq/kernel';
+import { and, eq, isNull } from 'drizzle-orm';
+import { assets, repairs } from '../schema.js';
+export function deriveStatus(facts) {
+    if (facts.awayForRepair)
+        return 'under_repair';
+    return facts.custodianUserId ? 'assigned' : 'in_stock';
+}
+/**
+ * Is this item away for a repair the workspace still records?
+ *
+ * Two facts, and the capability is checked first so the query is skipped entirely for a workspace
+ * that does not record repairs. Every caller that decides a status goes through this rather than
+ * through `openRepairId` directly, so there is one answer to "is it away" and a test can hold it.
+ */
+export async function awayForRepair(tx, workspaceId, assetId, repairsOn) {
+    if (!repairsOn)
+        return false;
+    return (await openRepairId(tx, workspaceId, assetId)) !== undefined;
+}
+/**
+ * The open repair for one asset, if there is one — the query behind `awayForRepair`.
+ *
+ * At most one exists by construction: `inventory_repairs_one_open_uq` is a unique index on
+ * `(asset_id) where returned_on is null`. It lives here rather than in `RepairService` so that
+ * `CustodyService` can read the fact without depending on the whole repair service, and so that
+ * every caller decides a status the same way — read both facts, then call `deriveStatus`, never
+ * assume one of them.
+ */
+/**
+ * The asset row, locked for the rest of the transaction — the serialisation point for `status`.
+ *
+ * **`status` is derived from two facts written by two different services, so the derivation needs a
+ * lock even though neither fact does.** `CustodyService` decides it from custody *and* the open
+ * repair; `RepairService` decides it from the repair *and* the custodian. Each used to read the
+ * other's fact without a lock, so a handover and a repair completing at the same instant
+ * interleaved into a status that matched neither: the second writer had read the first one's fact
+ * before it was written, derived from a snapshot that no longer existed, and overwrote the answer.
+ * That is a lost update in the plain sense — two transactions, one column, one of them silently
+ * discarded.
+ *
+ * Both paths now take this lock **before** reading either fact, so the second one waits, re-reads
+ * what the first committed, and derives from the state that actually exists. `for('update')`
+ * re-evaluates the row at the latest committed version once the lock is granted, which is exactly
+ * what makes the re-read honest rather than a repeat of the stale snapshot.
+ *
+ * **It is not the arbiter of "already held" or "already away".** Those stay with the exclusion
+ * constraint and the partial unique index, for the reason both services' docblocks give: locking
+ * the asset first would serialise two handovers into two *successful* handovers. This lock is taken
+ * after the row that decides the race has been written, so it orders the bookkeeping without
+ * deciding the contest.
+ */
+export async function lockAsset(tx, workspaceId, assetId) {
+    const [row] = await tx
+        .select()
+        .from(assets)
+        .where(and(eq(assets.workspaceId, workspaceId), eq(assets.id, assetId)))
+        .for('update');
+    if (!row)
+        throw KernError.notFound('Asset');
+    return row;
+}
+export async function openRepairId(tx, workspaceId, assetId) {
+    const [row] = await tx
+        .select({ id: repairs.id })
+        .from(repairs)
+        .where(and(eq(repairs.workspaceId, workspaceId), eq(repairs.assetId, assetId), isNull(repairs.returnedOn)))
+        .limit(1);
+    return row?.id;
+}
+//# sourceMappingURL=status.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/server/services/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAW,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AA0D9C,MAAM,UAAU,YAAY,CAAC,KAAkB;IAC7C,IAAI,KAAK,CAAC,aAAa;QAAE,OAAO,cAAc,CAAA;IAC9C,OAAO,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAA;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAM,EACN,WAAmB,EACnB,OAAe,EACf,SAAkB;IAElB,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAA;IAC5B,OAAO,CAAC,MAAM,YAAY,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,KAAK,SAAS,CAAA;AACrE,CAAC;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAM,EACN,WAAmB,EACnB,OAAe;IAEf,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,EAAE;SACR,IAAI,CAAC,MAAM,CAAC;SACZ,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;SACvE,GAAG,CAAC,QAAQ,CAAC,CAAA;IAChB,IAAI,CAAC,GAAG;QAAE,MAAM,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC3C,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,EAAM,EACN,WAAmB,EACnB,OAAe;IAEf,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;SACnB,MAAM,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;SAC1B,IAAI,CAAC,OAAO,CAAC;SACb,KAAK,CACJ,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CACpG;SACA,KAAK,CAAC,CAAC,CAAC,CAAA;IACX,OAAO,GAAG,EAAE,EAAE,CAAA;AAChB,CAAC"}

package/migrations/0002_custody_and_categories.sql

@@ -0,0 +1,23 @@
+-- Custody, the history read side, and archivable categories.
+--
+-- Generated from `src/server/schema.ts` with `pnpm db:generate` and then guarded, in that order.
+-- Hand-writing the SQL is what puts an unguarded `ALTER TABLE … ADD PRIMARY KEY` in a file instead
+-- of an inline key inside a `CREATE TABLE IF NOT EXISTS`; generating first and adding the guards
+-- after keeps the file the schema's own output.
+--
+-- **Append-only from here.** 0.2.0 is published and `core` depends on it, so this file adds and
+-- never rewrites: a nullable column and an index, both of which the 0.2.0 image can read straight
+-- past. Nothing is dropped, renamed or narrowed, so rolling that image back needs no dump.
+--
+-- **Both statements are idempotent.** A module's migrations are the first thing the kernel runs, so
+-- one that throws does not break its own feature — it takes down the whole host service, and `core`
+-- hosts five modules. `migrations.test.ts` applies this folder twice against a database created
+-- from nothing and is what proves the guards are real rather than intended.
+
+ALTER TABLE "mod_inventory"."categories" ADD COLUMN IF NOT EXISTS "archived_at" timestamp with time zone;--> statement-breakpoint
+
+-- `assets.history` pages by id, not by `created_at`: an id is uuidv7 so it already carries the
+-- clock, and it is unique where a timestamp two rows written in one transaction share is not. The
+-- index `0000_init.sql` created starts (workspace_id, asset_id, created_at) and cannot serve
+-- `order by id desc`; this one can.
+CREATE INDEX IF NOT EXISTS "inventory_asset_history_ws_asset_row_idx" ON "mod_inventory"."asset_history" USING btree ("workspace_id","asset_id","id");

package/migrations/0003_repairs.sql

@@ -0,0 +1,23 @@
+-- One open repair per asset.
+--
+-- Generated from `src/server/schema.ts` with `pnpm db:generate` and then guarded, in that order —
+-- generating first is what keeps the file the schema's own output rather than a hand-written guess
+-- at it.
+--
+-- **Append-only.** 0.2.0 is published and `core` depends on it, so this file adds an index and
+-- nothing else: no table is created, dropped, renamed or narrowed, and the 0.2.0 image reads the
+-- schema afterwards exactly as it read it before. Rolling that image back needs no dump.
+--
+-- **The guard is not decoration.** A module's migrations are the first thing the kernel runs, so one
+-- that throws does not break its own feature — it takes down the whole host service, and `core`
+-- hosts five modules. drizzle emits a bare `CREATE UNIQUE INDEX` here; `if not exists` is added by
+-- hand, and `migrations.test.ts` applies this folder twice against a database created from nothing
+-- to prove the guard is real rather than intended.
+--
+-- Why an index and not a service check: two people pressing *Send for repair* on the same laptop in
+-- the same instant both read "it is here" and both insert. Checking first and inserting after is the
+-- race, not the fix. Custody settles the same problem with a GiST exclusion constraint; a repair has
+-- no range to overlap, only a flag, so a partial unique index says exactly the same thing more
+-- cheaply. `RepairService` translates the resulting 23505 into a sentence.
+
+CREATE UNIQUE INDEX IF NOT EXISTS "inventory_repairs_one_open_uq" ON "mod_inventory"."repairs" USING btree ("asset_id") WHERE returned_on is null;

package/migrations/0004_platform_surfaces.sql

@@ -0,0 +1,51 @@
+-- The platform surfaces: a workspace registry the scheduler can read, and the two "already told
+-- somebody" markers the two sweeps need.
+--
+-- Generated from `src/server/schema.ts` with `pnpm db:generate` and then guarded, in that order.
+-- Hand-writing the SQL is what puts an unguarded `ALTER TABLE … ADD PRIMARY KEY` in a file instead
+-- of an inline key inside a `CREATE TABLE IF NOT EXISTS`; generating first keeps the file the
+-- schema's own output. The `if not exists` on the table, the two columns and the index, and the
+-- `drop policy if exists` under them, are what was added afterwards.
+--
+-- **Append-only.** 0.2.0 is published and `core` depends on it, so this file only adds: a new table,
+-- two nullable columns and an index. Nothing is dropped, renamed or narrowed, so the 0.2.0 image
+-- reads the schema afterwards exactly as it read it before and rolling back needs no dump.
+--
+-- **Every statement is idempotent.** A module's migrations are the first thing the kernel runs, so
+-- one that throws does not break its own feature — it takes down the whole host service, and `core`
+-- hosts five modules. `migrations.test.ts` applies this folder twice against a database created from
+-- nothing and is what proves the guards are real rather than intended.
+--
+-- Why `workspaces` exists at all: a cron handler is woken by a clock, so it starts with no workspace
+-- and nothing to derive one from. Core would answer, and asking it every tick makes an overnight
+-- sweep fail whenever core is briefly away. `module-tracker` keeps the same table for the same
+-- reason. It gets a policy like every other table carrying `workspace_id`; the enumeration itself
+-- cannot honour that policy — `app.workspace_id` is unset there by definition — and reads as the
+-- owner, which is what every module's scheduler here already does.
+
+CREATE TABLE IF NOT EXISTS "mod_inventory"."workspaces" (
+	"workspace_id" uuid PRIMARY KEY NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+
+alter table "mod_inventory"."workspaces" enable row level security;--> statement-breakpoint
+alter table "mod_inventory"."workspaces" force row level security;--> statement-breakpoint
+drop policy if exists "workspaces_ws_isolation" on "mod_inventory"."workspaces";--> statement-breakpoint
+create policy "workspaces_ws_isolation" on "mod_inventory"."workspaces"
+  using (workspace_id::text = current_setting('app.workspace_id', true))
+  with check (workspace_id::text = current_setting('app.workspace_id', true));--> statement-breakpoint
+
+-- A warranty falls inside the notice window on every one of the days before it expires, so a sweep
+-- with no marker sends the same notice every morning for a month. Cleared when `warranty_until`
+-- itself moves.
+ALTER TABLE "mod_inventory"."assets" ADD COLUMN IF NOT EXISTS "warranty_notified_at" timestamp with time zone;--> statement-breakpoint
+
+-- The same, for a repair that has been away too long: it is still too long tomorrow.
+ALTER TABLE "mod_inventory"."repairs" ADD COLUMN IF NOT EXISTS "overdue_notified_at" timestamp with time zone;--> statement-breakpoint
+
+-- What the overdue sweep reads: one workspace's still-open repairs, oldest first.
+-- `inventory_repairs_ws_asset_idx` starts (workspace_id, asset_id, sent_on) and cannot answer this
+-- without visiting every asset, and `inventory_repairs_one_open_uq` is partial on the right
+-- predicate but keyed by `asset_id` alone, so it cannot be scoped to a workspace.
+CREATE INDEX IF NOT EXISTS "inventory_repairs_ws_open_idx" ON "mod_inventory"."repairs" USING btree ("workspace_id","sent_on") WHERE returned_on is null;

package/migrations/0005_repair_dates.sql

@@ -0,0 +1,35 @@
+-- A repair cannot come back before it was sent.
+--
+-- Generated from `src/server/schema.ts` with `pnpm db:generate` and then guarded, in that order —
+-- generating first is what keeps the file the schema's own output rather than a hand-written guess
+-- at it. The `drop constraint if exists` and the `not valid` are what was added afterwards.
+--
+-- **Append-only.** 0.2.0 is published and `core` depends on it, so this file adds a constraint and
+-- nothing else: no table is created, dropped, renamed or narrowed, and the 0.2.0 image reads the
+-- schema afterwards exactly as it read it before. Rolling that image back needs no dump.
+--
+-- **Idempotent.** `add constraint` has no `if not exists`, so it is preceded by an explicit drop —
+-- the same shape `0001_rls.sql` uses for the custody exclusion constraint, and for the same reason:
+-- a module's migrations are the first thing the kernel runs, so one that throws does not degrade its
+-- own feature, it stops the host service booting, and `core` hosts five modules. A regenerated
+-- `migrations/meta/_journal.json` is enough to cause a replay. `migrations.test.ts` applies this
+-- folder twice against a database created from nothing to prove the guard is real.
+--
+-- **`not valid`, and that is the whole difference between a safe upgrade and an outage.** The
+-- constraint is enforced on every insert and update from the moment it exists; what `not valid`
+-- skips is the scan of rows that are already there. Those rows are exactly the ones this defect may
+-- have written — `repairs.update` would move `sent_on` past a `returned_on` — and a validating
+-- constraint that met one of them would throw *during migration*, on somebody's instance, during an
+-- upgrade, taking core down with it. An instance that wants the scan can run
+-- `alter table … validate constraint …` by hand once it has corrected its data; nothing needs it to.
+--
+-- Why the database as well as the service: `repairs.update` and `repairs.complete` each check the
+-- pair before writing it, and two transactions can each pass that check and still commit a pair that
+-- fails it — one moving `sent_on` while the other logs the item back. The service check is what
+-- gives an ordinary mistake a sentence; this is what makes the rule true of the table.
+
+ALTER TABLE "mod_inventory"."repairs"
+  DROP CONSTRAINT IF EXISTS "inventory_repairs_returned_after_sent";--> statement-breakpoint
+ALTER TABLE "mod_inventory"."repairs"
+  ADD CONSTRAINT "inventory_repairs_returned_after_sent"
+  CHECK (returned_on is null or returned_on >= sent_on) NOT VALID;