@kernhq/module-inventory 0.2.0 → 0.4.0

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/0008_category_order_unique.sql

@@ -0,0 +1,71 @@
+-- No two live categories on the same place, enforced rather than intended.
+--
+-- Hand-written, because the repair below is not something drizzle-kit generates — the same reason
+-- `0001_rls.sql`, `0006_workspace_registry_read.sql` and `0007_history_sequence.sql` are. 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
+--
+-- The contract, the changeset and `CategoryService.list`'s own comment all said that `reorder` keeps
+-- the live categories on distinct numbers, so the `order by "order", "name"` tiebreak never fires for
+-- them. All three were describing an intention.
+--
+-- A category joins the end of the list by taking `(select coalesce(max("order"), -1) + 1)`, and a
+-- restore appends the same way. Putting that subquery *inside* the insert removes a round trip; it
+-- does not remove the race. Under READ COMMITTED every statement takes its own snapshot, so two
+-- transactions appending at the same instant each read a list without the other's row in it and both
+-- take the same number. `reorder`'s `select … for update` does not serialise them either: a row lock
+-- cannot cover a row that does not exist yet, and a restore's subquery is evaluated against the
+-- snapshot its statement started with rather than the one it would get after waiting.
+--
+-- Two live categories on one number is not a crash. It is a list whose order changes under somebody
+-- when a name changes, and a *move up* that appears to do nothing because the row it swapped with
+-- sorts back ahead of it by name.
+--
+-- ## Why an index
+--
+-- Because checking first and writing after is the race, not the fix — the same reason
+-- `inventory_repairs_one_open_uq` is an index in `0003`. `CategoryService` takes a per-workspace
+-- advisory lock so the ordinary append never meets this index at all; the index is what makes the
+-- claim true whatever else reaches the table.
+--
+-- **Partial, over the live rows only.** An archived category keeps the number it had when it left,
+-- and the next reorder renumbers a live row straight onto it. That collision is invisible — an
+-- archived category is in no picker, no filter and no sequence — so a total unique index would refuse
+-- an archive-and-reorder that is entirely correct.
+--
+-- ## The repair comes first, or the upgrade takes the host service down
+--
+-- A module's migrations are the first thing the kernel runs, so a `CREATE UNIQUE INDEX` that meets
+-- rows already sharing a number does not break categories: it throws during boot, and `core` hosts
+-- five modules and never binds its port. Every instance that has run 0.2.0 may hold such a pair, so
+-- the duplicates are renumbered before the index is built.
+--
+-- The renumbering is confined to the workspaces that actually have a duplicate, and it walks them in
+-- `("order", "name", "id")` — which is the order `list` already returns and therefore the order the
+-- screen already showed. Nobody's arrangement visibly changes. `"order" <> ordered.rn - 1` is what
+-- makes a replay match nothing rather than rewrite rows a second time.
+--
+-- ## Append-only, and readable by the image before this one
+--
+-- 0.2.0 is published and `core` depends on it. This changes no table and no column: it adds an index
+-- and moves some integers within the range they already occupied, so the previous image reads the
+-- table exactly as it read it before and rolling back needs no dump.
+
+UPDATE "mod_inventory"."categories" AS c
+   SET "order" = ordered.rn - 1
+  FROM (SELECT "id",
+               row_number() OVER (PARTITION BY "workspace_id" ORDER BY "order", "name", "id") AS rn
+          FROM "mod_inventory"."categories"
+         WHERE "archived_at" IS NULL
+           AND "workspace_id" IN (SELECT "workspace_id"
+                                    FROM "mod_inventory"."categories"
+                                   WHERE "archived_at" IS NULL
+                                   GROUP BY "workspace_id", "order"
+                                  HAVING count(*) > 1)) AS ordered
+ WHERE c."id" = ordered."id"
+   AND c."order" <> ordered.rn - 1;--> statement-breakpoint
+
+CREATE UNIQUE INDEX IF NOT EXISTS "inventory_categories_ws_order_live_uq"
+  ON "mod_inventory"."categories" USING btree ("workspace_id","order") WHERE "archived_at" IS NULL;