CAP-2030 Change Ledger

What the change does

Three ideas, and everything else follows from them.

The registry table

Eighteen columns. These five carry the design; the rest are ownership, flags and timestamps.

Where an upload lands, in all four combinations the table to validate against

Which bucket is live, and whether the upload is itself the save, decide everything.

Five owner scopes, not four

The scope decides the shape of the path, and it is also what owner_scope groups by, which is why a fifth was worth adding rather than borrowing one.

QR codes are the case that needed it. They are minted as an unassigned pool, so there is no account when the object is written; their name is derived from the qr id alone on both the read and the write side; and they are printed on physical labels, so the object can never move. Folding them under library would give the same path but count them alongside the catalogue, which is the one question owner_scope exists to answer.

While the old bucket is live, uploads keep its flat layout — rows one and two are identical in file_path. They have to be: today’s reads build categories/<name> from a folder constant, so an object written anywhere else is an object nothing can find. What skipping staging buys before the cutover is the destination, not the location.

dbMigrations

Branch: CAP-2030-new-bucket-migration. Committed, with one comment change pending a re-run.

The table 1 file

One migration, applied and re-runnable.

backendApi

Branch: CAP-2030-new-bucket-migration. Two commits plus five files of follow-on work. Of the 5136 added lines, 4,157 are the runbook and 195 the migration copy inside it — the code itself is about 700 lines.

The mechanism 5 files

Where an upload is decided, recorded and filed. Read these four first.

Configuration and registration 4 files

The bucket becomes a setting, and the model is registered.

Save paths 11 files

Each of these puts a file where it belongs once the record referencing it exists.

Module registration 5 files

StorageModule added wherever a consumer is declared. Nest resolves a provider in its declaring module, so every declaring module needs it.

Documentation 1 file

Not part of this feature 3 files

Present on the branch but unrelated to the storage work. Worth deciding whether they belong in this PR.

capExpertApp

Branch: CAP-2030-new-bucket-migration. Not committed. Most of the 98 files are one or two lines: the two shared uploaders now require folder and uploadModule, so every parent had to name both.

Shared uploaders and the path map 4 files

The two shared components, the module map, and the new path builder.

Retargets and fixes 5 files

Uploads pointed at the right destination, plus two save bugs.

Parent bindings 82 files

Every parent of the two shared uploaders now passes folder and uploadModule, and where the account is known it passes accountId and skipTemp. Mechanical, one to two lines each.

Incidental 3 files

Import reflow and small model additions the sweep touched.

Removed 4 files

Dead module, confirmed unreachable before deleting.

How this was verified

What was actually run, so you know what the gates do and do not cover.

• ✓
  npm run typecheck clean in backendApi. In capExpertApp, clean in every changed file; the pre-existing ShipmentTrackingInputDto errors come from the gitignored swagger client.
• ✓
  check-layering, check-worker-paths clean. shared/ imports no role bucket.
• ✓
  eslint Every error in the changed API files was diffed against HEAD and is identical — no new findings. Ten pre-existing ones remain.
• ✓
  DI reachability A script parses every class for a StorageService dependency, resolves each module’s providers by import path, and confirms the declaring module can resolve it. Zero gaps. This is what the boot failure taught: typecheck passes on a DI graph that cannot be constructed.
• ✓
  Required inputs A quote-aware scan of all 87 uploader usages confirms every one binds both folder and uploadModule.
• ✓
  Path builder Probed against the compiled build for each scope, with and without an account, confirming {SCOPE} survives a null, an undefined and an empty string.
• ✓
  Front-end map parity The generator that built upload-targets.ts asserted the API map and the generated client agree on all 46 modules, in both directions.
• ×
  Not run: swagger diff per role The primary acceptance gate in backendApi/CLAUDE.md, since capExpertApp generates its clients from it. The presign DTO changed, so this needs capturing before merge.

Open items

Known and deliberate. None of it blocks the old-bucket path, which is what is live today.