@kernhq/module-inventory 0.1.2 → 0.3.0

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;

package/migrations/0006_workspace_registry_read.sql

@@ -0,0 +1,50 @@
+-- The one read in this module that has no workspace to be bound to.
+--
+-- Hand-written, because drizzle-kit does not generate policies — the same reason `0001_rls.sql` is
+-- hand-written, and it carries the same guard: `create policy` has no `if not exists`, so it is
+-- preceded by an explicit drop. `migrations.test.ts` applies this folder twice against a database
+-- created from nothing and is what proves the guard is real rather than intended.
+--
+-- **Append-only.** 0.2.0 is published and `core` depends on it. This adds a policy and changes no
+-- table, column or index, so the 0.2.0 image reads the schema afterwards exactly as it read it
+-- before and rolling back needs no dump.
+--
+-- ## What was wrong
+--
+-- `mod_inventory.workspaces` is the registry the two nightly sweeps enumerate: a cron handler is
+-- woken by a clock, so it has no workspace and `app.workspace_id` is unset for it by definition.
+-- The table is a tenant table like every other — it carries `workspace_id` — so `0004` gave it
+-- `enable`, `force` and the standard per-workspace policy, and the enumeration was left resting on
+-- "the application connects as the schema's owner, and an owner bypasses RLS".
+--
+-- That is false, and `force row level security` is exactly the clause that makes it false: forcing
+-- subjects the **table owner** to the policies as well. Only a superuser (or a role with BYPASSRLS)
+-- is exempt. So on every deployment whose application role is an ordinary login role — which is what
+-- the project's own RLS note asks for — `select workspace_id from mod_inventory.workspaces` with no
+-- workspace bound returned **zero rows**. Not an error, not a warning: both sweeps found nothing to
+-- do, every night, for ever. The development database runs as a superuser, which is precisely why
+-- nothing noticed.
+--
+-- ## Why this shape of fix
+--
+-- Permissive policies are OR-ed, so this adds a second `for select` policy rather than touching the
+-- first. It admits a session with **no workspace bound** — which is the scheduler, by construction,
+-- since every request-bound read in this module goes through `kernel.database.withWorkspace` and
+-- sets the GUC. A request-bound session therefore still matches only the original policy and still
+-- sees exactly its own row: this widens nothing for anybody holding a workspace.
+--
+-- It is keyed on the *absence of a binding* rather than on a role name because a role name is a
+-- deployment's choice — `kern`, `kern_app`, whatever an operator called it — and a migration that
+-- named one would be right on one instance and wrong on the next. `set_config(..., true)` is
+-- transaction-local, so an unbound read on a pooled connection sees the setting unset (NULL) or
+-- empty; both are covered.
+--
+-- The table holds nothing but workspace ids and a timestamp — it is this module's own bookkeeping,
+-- not tenant data anybody reads through the API. `assets`, `custody_periods`, `repairs` and the rest
+-- are untouched and keep answering nothing at all to a session with no workspace, which is what
+-- `inventory.int.test.ts` proves against a plain login role.
+
+drop policy if exists "workspaces_unbound_read" on "mod_inventory"."workspaces";--> statement-breakpoint
+create policy "workspaces_unbound_read" on "mod_inventory"."workspaces"
+  for select
+  using (coalesce(current_setting('app.workspace_id', true), '') = '');

package/migrations/0007_history_sequence.sql

@@ -0,0 +1,83 @@
+-- The timeline's own ordering key, because a uuidv7 is only ordered to the millisecond.
+--
+-- Hand-written, because drizzle-kit does not generate a sequence, a backfill or a `setval` — the
+-- same reason `0001_rls.sql` and `0006_workspace_registry_read.sql` are hand-written. Every
+-- statement carries its own guard, and `migrations.test.ts` applies this folder twice against a
+-- database created from nothing to prove the guards are real rather than intended.
+--
+-- ## What was wrong
+--
+-- `asset_history` is read newest-first ordered by its primary key, on the grounds that a uuidv7
+-- already carries the clock and is unique where `occurred_at` is not. Half of that is true. The
+-- kernel's `uuidv7()` puts the millisecond in bytes 0-5 and fills bytes 6-15 from `randomUUID()`
+-- with **no intra-millisecond counter**, so two entries written in the same millisecond sort in an
+-- order decided by ten random bytes. It is stable for a given set of rows, so keyset paging stayed
+-- correct — no gaps, no repeats — and the defect never showed up as a broken list. What it showed
+-- up as is a timeline that renders "Bruno removed the file" above "Bruno added the file", which is
+-- the one record a company later argues from.
+--
+-- `occurred_at` is no rescue: it defaults to `now()`, which is the *transaction* timestamp, so two
+-- entries written in one transaction share it exactly.
+--
+-- ## Why a sequence
+--
+-- A sequence is exact rather than probabilistic: `nextval` hands out strictly increasing values
+-- whatever the clock does, at whatever rate, and two entries written a microsecond apart are two
+-- values. It is also cheap — one `nextval` per history row, no extra round trip — and it is the one
+-- ordering key a module can own outright, where the clock belongs to the machine.
+--
+-- The unique index is on `(workspace_id, asset_id, seq)` because that is what the timeline reads:
+-- one asset's entries, newest first, paged on `seq`. `inventory_asset_history_ws_asset_row_idx` is
+-- left where it is — dropping an index is a schema change and this file only adds — and goes one
+-- release later.
+--
+-- ## Append-only, and readable by the image before this one
+--
+-- 0.2.0 is published and `core` depends on it, so this file only adds: a sequence, a column, an
+-- index. The column is `not null` **with a default**, which is what keeps the previous image
+-- writing: it never names `seq`, so the default fills it, and it never selects `seq`, so it reads
+-- the table exactly as it read it before. Rolling that image back needs no dump.
+--
+-- The backfill orders existing rows by `(occurred_at, id)` rather than leaving them to the physical
+-- order a rewrite would produce. Within one millisecond that is still the arbitrary uuid order this
+-- migration exists to replace — nothing can recover an order that was never recorded — but across
+-- milliseconds it is the order the timeline already showed, so an existing instance's history does
+-- not visibly reshuffle on upgrade.
+
+CREATE SEQUENCE IF NOT EXISTS "mod_inventory"."asset_history_seq" AS bigint;--> statement-breakpoint
+
+ALTER TABLE "mod_inventory"."asset_history" ADD COLUMN IF NOT EXISTS "seq" bigint;--> statement-breakpoint
+
+-- Only the rows that have none, so a replay matches nothing and changes nothing.
+--
+-- `created_at` rather than `occurred_at`: the drizzle field is `occurredAt` and the *column* it maps
+-- to is `created_at`, because `asset_history` reuses the module's `created()` factory. A migration
+-- talks to the column, and this file's first draft talked to the field — which fails at
+-- `column "occurred_at" does not exist`, during the module's own migration, which is a host service
+-- that never binds its port rather than a broken timeline.
+UPDATE "mod_inventory"."asset_history" AS h
+   SET "seq" = ordered.rn
+  FROM (SELECT "id", row_number() OVER (ORDER BY "created_at", "id") AS rn
+          FROM "mod_inventory"."asset_history"
+         WHERE "seq" IS NULL) AS ordered
+ WHERE h."id" = ordered."id";--> statement-breakpoint
+
+-- `GREATEST` so this only ever moves the sequence forward. A replay against a live database must
+-- not hand back a value some open transaction has already taken.
+SELECT setval('mod_inventory.asset_history_seq',
+              GREATEST((SELECT coalesce(max("seq"), 0) FROM "mod_inventory"."asset_history"),
+                       (SELECT last_value FROM "mod_inventory"."asset_history_seq")),
+              true);--> statement-breakpoint
+
+ALTER TABLE "mod_inventory"."asset_history"
+  ALTER COLUMN "seq" SET DEFAULT nextval('mod_inventory.asset_history_seq');--> statement-breakpoint
+
+ALTER TABLE "mod_inventory"."asset_history" ALTER COLUMN "seq" SET NOT NULL;--> statement-breakpoint
+
+-- So `drop schema mod_inventory cascade` takes the sequence with it, and so does dropping the
+-- column one release from now.
+ALTER SEQUENCE "mod_inventory"."asset_history_seq"
+  OWNED BY "mod_inventory"."asset_history"."seq";--> statement-breakpoint
+
+CREATE UNIQUE INDEX IF NOT EXISTS "inventory_asset_history_ws_asset_seq_uq"
+  ON "mod_inventory"."asset_history" USING btree ("workspace_id","asset_id","seq");

package/migrations/meta/0000_snapshot.json

@@ -1,5 +1,5 @@
 {
-  "id": "50998845-5c27-429f-ba8d-b7beda4579b4",
+  "id": "33173d81-879e-409b-a7c7-d8f9977b9e6c",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "version": "7",
   "dialect": "postgresql",
@@ -139,8 +139,7 @@
         },
         "status": {
           "name": "status",
-          "type": "asset_status",
-          "typeSchema": "public",
+          "type": "text",
           "primaryKey": false,
           "notNull": true,
           "default": "'in_stock'"
@@ -205,6 +204,13 @@
           "primaryKey": false,
           "notNull": false
         },
+        "custom": {
+          "name": "custom",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
         "created_at": {
           "name": "created_at",
           "type": "timestamp with time zone",
@@ -311,6 +317,28 @@
           "method": "btree",
           "with": {}
         },
+        "inventory_assets_ws_custodian_idx": {
+          "name": "inventory_assets_ws_custodian_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "custodian_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "custodian_user_id is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
         "inventory_assets_ws_warranty_idx": {
           "name": "inventory_assets_ws_warranty_idx",
           "columns": [
@@ -568,13 +596,13 @@
         "workspace_id": {
           "name": "workspace_id",
           "type": "uuid",
-          "primaryKey": true,
+          "primaryKey": false,
           "notNull": true
         },
         "key": {
           "name": "key",
           "type": "text",
-          "primaryKey": true,
+          "primaryKey": false,
           "notNull": true
         },
         "value": {
@@ -586,7 +614,12 @@
       },
       "indexes": {},
       "foreignKeys": {},
-      "compositePrimaryKeys": {},
+      "compositePrimaryKeys": {
+        "counters_workspace_id_key_pk": {
+          "name": "counters_workspace_id_key_pk",
+          "columns": ["workspace_id", "key"]
+        }
+      },
       "uniqueConstraints": {},
       "policies": {},
       "checkConstraints": {},
@@ -972,13 +1005,7 @@
       "isRLSEnabled": false
     }
   },
-  "enums": {
-    "public.asset_status": {
-      "name": "asset_status",
-      "schema": "public",
-      "values": ["in_stock", "assigned", "under_repair", "retired"]
-    }
-  },
+  "enums": {},
   "schemas": {
     "mod_inventory": "mod_inventory"
   },