@kernhq/module-inventory 0.2.0 → 0.4.0

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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"}