@camstack/addon-matter-broker 0.2.41 → 0.2.44

package/dist/addon.js

@@ -8053,18 +8053,61 @@ var RelocateFootageInputSchema = object({
 * `RecordingConfig.enabled` or camera wrapper bindings. */
 var StorageMigrationLeaseInputSchema = object({ leaseId: string$2().min(1) });
 var StorageMigrationFootageMoveInputSchema = RelocateFootageInputSchema.extend({ leaseId: string$2().min(1) });
+/**
+* What a `relocateMedia` pass DOES. One engine, three passes — never a second
+* mover (the engine already walks both collections with a timestamp cursor and
+* already has a stamp-without-copy path).
+*
+*  - `move`    — the default and the historical behaviour: event-media and
+*                retrain blobs move to `toLocationId` and their rows are
+*                stamped. The enrolled gallery is skipped (D197).
+*  - `seal`    — ROWS ONLY, no bytes. Every row whose `locationId` is NULL is
+*                stamped with `toLocationId`. `toLocationId` here is the id the
+*                bytes ALREADY sit on — today's `eventMedia` default — because
+*                a NULL row means "wherever `eventMedia` points *now*", and the
+*                instant a repoint moves that pointer the row reads from the
+*                new disk while its bytes are on the old one.
+*  - `gallery` — the inverse selection of `move`: ONLY the retention-exempt
+*                (enrolled-gallery) rows, which `move` deliberately skips.
+*                `galleryMedia` is `cardinality: 'single'`, so this pass can
+*                never run beside a live second location: it is stop-the-world
+*                by construction, which is acceptable only because the gallery
+*                is a few KB per enrolled sample.
+*/
+var MediaRelocateModeSchema = _enum([
+	"move",
+	"seal",
+	"gallery"
+]);
 var RelocateMediaInputSchema = object({
 	toLocationId: string$2(),
-	throttleMbps: number().min(1).max(1e3).optional()
+	throttleMbps: number().min(1).max(1e3).optional(),
+	/** Omitted = `move`, the pre-existing behaviour. */
+	mode: MediaRelocateModeSchema.optional()
+});
+/** How many rows still carry NO `locationId` — the population a repoint would
+*  silently re-aim at a disk that does not hold their bytes. Zero is the only
+*  value that permits a non-blocking `eventMedia` cutover. */
+var UnstampedEventMediaCountSchema = object({
+	media: number().int().nonnegative(),
+	retrainFrames: number().int().nonnegative(),
+	total: number().int().nonnegative()
 });
 var StorageMigrationMediaMoveInputSchema = RelocateMediaInputSchema.extend({ leaseId: string$2().min(1) });
-/** The independently selectable logical storage classes. `recordings`
-* encompasses the high and mid segment profiles; `recordingsLow` is low
-* segments; `eventMedia` is post-analysis blobs. */
+/** The independently selectable logical storage classes — every class
+* `storage.listLocationDeclarations` reports, so an operator never meets a
+* Zod enum error where they should meet an explanation.
+*
+* `recordings` encompasses the high and mid segment profiles; `recordingsLow`
+* is low segments; `eventMedia` is post-analysis blobs; `galleryMedia` is the
+* enrolled gallery; `backups` is the system backup archive. The last two have
+* their own rules — see {@link StorageMigrationFindingCodeSchema}. */
 var StorageMigrationClassSchema = _enum([
 	"recordings",
 	"recordingsLow",
-	"eventMedia"
+	"eventMedia",
+	"backups",
+	"galleryMedia"
 ]);
 /** A destination is always an existing, fully-qualified location id. The
 * migration API intentionally never changes a source location's `basePath`:
@@ -8072,20 +8115,56 @@ var StorageMigrationClassSchema = _enum([
 var StorageMigrationDestinationsSchema = object({
 	recordings: string$2().min(1).optional(),
 	recordingsLow: string$2().min(1).optional(),
-	eventMedia: string$2().min(1).optional()
+	eventMedia: string$2().min(1).optional(),
+	backups: string$2().min(1).optional(),
+	galleryMedia: string$2().min(1).optional()
 }).refine((value) => Object.keys(value).length > 0, { message: "select at least one storage class" });
+/**
+* How a migration sequences the cutover against the byte move.
+*
+*  - `blocking`     — the historical order: pause, move every byte, repoint,
+*                     resume. Recording is stopped for the whole move. Right
+*                     for a small or a cold class, and the only legal mode for
+*                     a `cardinality: 'single'` class.
+*  - `nonBlocking`  — repoint FIRST, drain behind: seal, pause, repoint,
+*                     refresh, resume, then move the past with everything
+*                     running. The pause is three bounded instants (a detach +
+*                     attach round, a write-gate drain, a lease) instead of one
+*                     bounded by bytes. 1.09 TB at 7–14 MB/s is thirty hours of
+*                     stopped recording under `blocking`; the same move is
+*                     seconds of stopped recording under `nonBlocking`.
+*
+* The mode is on the JOB, not only on the input, because `status` is where an
+* operator finds out which one is running.
+*/
+var StorageMigrationModeSchema = _enum(["blocking", "nonBlocking"]);
 /** Shared input for planning and starting an orchestrated storage migration. */
 var StorageMigrationInputSchema = object({
 	destinations: StorageMigrationDestinationsSchema,
-	throttleMbps: number().min(1).max(1e3).optional()
+	throttleMbps: number().min(1).max(1e3).optional(),
+	/** Omitted = `blocking`, which stays the default. */
+	mode: StorageMigrationModeSchema.optional()
 });
-/** The durable coordinator state machine. The only phase that changes default
-* locations is `repointing`, after every selected mover has completed and been
-* verified. */
+/**
+* The durable coordinator state machine.
+*
+* `blocking`:
+*   planning → pausing → moving → verifying → repointing → refreshing → resuming → done
+*
+* `nonBlocking`:
+*   planning → sealing → pausing → repointing → refreshing → resuming → draining → verifying → done
+*
+* Same phases, different order plus two new ones — not a second mover.
+* `sealing` closes the `eventMedia` NULL-row hole BEFORE anything is paused;
+* `draining` runs the same movers UNLEASED, after every writer is back up.
+* `repointing` is still the only phase that changes a default location.
+*/
 var StorageMigrationPhaseSchema = _enum([
 	"planning",
+	"sealing",
 	"pausing",
 	"moving",
+	"draining",
 	"verifying",
 	"repointing",
 	"refreshing",
@@ -8099,17 +8178,56 @@ var StorageMigrationParticipantSchema = _enum([
 	"recorder",
 	"analytics"
 ]);
+/**
+* The mover's own numbers, folded onto the coordinator's durable move record.
+*
+* The long half of a non-blocking migration is `draining`, and it is measured
+* in hours: 136 885 files at ~4 MB/s is about five of them. Before this shape
+* existed the only place those numbers appeared was a Loki line, so an operator
+* watching the Admin UI saw `phase: draining` and nothing else for a whole
+* afternoon.
+*
+* It is POLLED, never pushed. Events are telemetry and may be dropped
+* (D8/D11), and a dropped progress event is indistinguishable from a stalled
+* mover — which is the exact failure this is meant to end. The coordinator's
+* `waitForMoves` already fetches the whole {@link RelocateJob} on every tick to
+* read `state`; folding the counters costs no extra read and makes the durable
+* record say afterwards how far a move actually got.
+*
+* `filesTotal` is `null` for "no honest denominator" and is never zero-filled:
+* a windowed footage job (`sinceMs`) and a node with no ledger both genuinely
+* cannot say M, and a 0 there would render as "100 % done".
+*/
+var StorageMigrationMoveProgressSchema = object({
+	filesMoved: number().int().nonnegative(),
+	/** The archive census — the **M** of "N of M" (D295). `null` = unknowable. */
+	filesTotal: number().int().nonnegative().nullable(),
+	bytesMoved: number().int().nonnegative(),
+	/** The MOVER's start, not the migration's: a drain restarted after an addon
+	*  crash gets a new mover, and a rate computed from the migration's start
+	*  would silently average in the time nothing was running. */
+	startedAt: number(),
+	/** When the coordinator last read these numbers. Paired with `startedAt` it
+	*  is the only honest rate: both clocks are the hub's, so a UI never has to
+	*  subtract its own. */
+	observedAt: number()
+});
 var StorageMigrationMoveSchema = object({
 	storageClass: StorageMigrationClassSchema,
 	fromLocationId: string$2(),
 	toLocationId: string$2(),
 	moverJobId: string$2().nullable(),
 	state: RelocateJobStateSchema.nullable(),
-	error: string$2().nullable()
+	error: string$2().nullable(),
+	/** Last observed mover counters; `null` until the mover has been polled once. */
+	progress: StorageMigrationMoveProgressSchema.nullable()
 });
 var StorageMigrationJobSchema = object({
 	jobId: string$2(),
 	phase: StorageMigrationPhaseSchema,
+	/** Which order this job is running. `status` is the only place an operator
+	*  can tell a seconds-long cutover from a thirty-hour one. */
+	mode: StorageMigrationModeSchema,
 	destinations: StorageMigrationDestinationsSchema,
 	throttleMbps: number(),
 	moves: array(StorageMigrationMoveSchema),
@@ -8122,13 +8240,122 @@ var StorageMigrationJobSchema = object({
 	finishedAt: number().nullable(),
 	error: string$2().nullable()
 });
+var StorageMigrationFindingSchema = object({
+	code: _enum([
+		"sharesDeviceWithSource",
+		"deviceIdentityUnknown",
+		"unstampedEventMediaRows",
+		"blockingOnly",
+		"noMover"
+	]),
+	storageClass: StorageMigrationClassSchema,
+	/** Human-readable, already carrying the ids and counts. */
+	message: string$2()
+});
 var StorageMigrationPlanSchema = object({
 	destinations: StorageMigrationDestinationsSchema,
+	/** The mode this plan was built for. A plan is only valid for its mode: the
+	*  `eventMedia` seal gate and the single-cardinality refusal both depend on
+	*  it. */
+	mode: StorageMigrationModeSchema,
 	moves: array(object({
 		storageClass: StorageMigrationClassSchema,
 		fromLocationId: string$2(),
 		toLocationId: string$2()
-	}))
+	})),
+	findings: array(StorageMigrationFindingSchema)
+});
+/**
+* A mover as it exists RIGHT NOW, whether or not a migration job owns it.
+*
+* The coordinator's job record is the state of record for a migration, and its
+* moves carry {@link StorageMigrationMoveProgress}. But the movers are usable
+* standalone — `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
+* are both operator-callable, and on 2026-08-29 a five-hour drain was armed that
+* way because no supported UI path existed. A mover armed like that has no job
+* to fold progress into, so it has to be readable on its own or it is invisible.
+*
+* `migrationJobId` is what tells the two apart: `null` means nothing here
+* orchestrated it.
+*/
+var StorageMigrationMoverSchema = object({
+	lane: _enum(["footage", "media"]),
+	job: RelocateJobSchema,
+	/** The coordinator job that armed this mover, or `null` for a mover armed
+	*  directly against the owning addon. */
+	migrationJobId: string$2().nullable(),
+	/** When the hub read these counters. Stamped here so a rate is `bytesMoved`
+	*  over (`observedAt` − `job.startedAt`) with BOTH ends on the hub's clock —
+	*  a browser subtracting its own `Date.now()` from a server `startedAt` is a
+	*  rate made of two different clocks. */
+	observedAt: number()
+});
+/**
+* What a SOURCE still holds for one storage class — the number that makes a
+* "drain remaining" action honest rather than hopeful.
+*
+* It comes from the archive (`SegmentHourLedger.census` for footage, the media
+* engine's own selection count for media), never from the resident index: a
+* drain sized off `RecordingIndex` is what reported `done` over 80.3 GB it had
+* never been told about (D295).
+*
+* `items`/`bytes` are `null` for "the archive could not be asked", which is
+* deliberately NOT zero: a drain is still offered for an unknown residue,
+* because refusing on an unanswerable read would hide exactly the case an
+* operator needs to act on.
+*/
+var StorageMigrationResidueSchema = object({
+	storageClass: StorageMigrationClassSchema,
+	/** The location still holding the data. `'*'` for the media lane, whose rows
+	*  move from wherever they are rather than from one named source. */
+	fromLocationId: string$2(),
+	/** Where a drain would move it — the class's CURRENT default. */
+	toLocationId: string$2(),
+	/** Segments (footage lane) or rows (media lane) still on the source. */
+	items: number().int().nonnegative().nullable(),
+	/** Bytes on the source; `null` when the lane counts rows rather than bytes. */
+	bytes: number().int().nonnegative().nullable()
+});
+/**
+* Run the DRAIN half and nothing else.
+*
+* A migration that reached `done` has already repointed, so `start` correctly
+* refuses its destination ("already the default") — there is nothing left to
+* repoint. But the drain can fail, be cancelled, be interrupted by a restart,
+* or finish against a work list that was a tenth of the archive (D295), and
+* before this there was no supported way to run only that half: the only way
+* through was calling `recording.relocateFootage` by hand over admin tRPC.
+*
+* `drain` NEVER calls `setDefaultLocations`. That is what keeps `start`'s
+* refusal meaningful: the two verbs are disjoint, so nothing here can silently
+* re-repoint a class that is already migrated.
+*/
+var StorageMigrationDrainInputSchema = object({
+	/** The classes to drain. Each must appear in `storageMigration.residue`, so
+	*  a class whose source is already empty is refused rather than started. */
+	classes: array(StorageMigrationClassSchema).min(1),
+	throttleMbps: number().min(1).max(1e3).optional()
+});
+/** What a footage source still holds, asked of the durable hour ledger. */
+var RelocateResidueInputSchema = object({
+	fromLocationId: string$2().min(1),
+	/** Narrow to one logical class; omit for every profile on the location. */
+	footageClass: RelocateFootageClassSchema.optional()
+});
+/** `null` = the archive could not answer (no ledger on this node, or the
+*  aggregate failed). Never conflated with an empty source. */
+var RelocateResidueSchema = object({
+	segments: number().int().nonnegative(),
+	bytes: number().int().nonnegative()
+}).nullable();
+/** How many rows a media pass would still act on against a given target — the
+*  media lane's denominator AND its residue, from ONE derivation so the two can
+*  never disagree. `null` = the count could not be taken. */
+var RelocatableMediaCountSchema = object({ rows: number().int().nonnegative() }).nullable();
+var RelocatableMediaCountInputSchema = object({
+	toLocationId: string$2().min(1),
+	/** Omitted = `move`. */
+	mode: MediaRelocateModeSchema.optional()
 });
 /**
 * `StorageLocationType` — an addon-declared id that identifies the *kind* of
@@ -8234,6 +8461,32 @@ var StorageLocationRefSchema = union([StorageLocationTypeSchema, string$2().rege
 *   two addons declaring the same `id` must agree on `cardinality` (validated
 *   at kernel aggregation time, not here).
 */
+/**
+* `StorageAccess` — how the service that DECLARED a storage-location kind
+* actually reaches the bytes. It is the constraint that decides which
+* `storage-provider`s may back a location of that kind.
+*
+* - `'local-path'` — the service asks `storage.resolve` for a path string and
+*   then does its own `node:fs` I/O on it (the recorder's segment writer, the
+*   post-analysis media roots). Only a provider that serves a genuine local
+*   filesystem (`getProviderInfo().nodeLocal === true`) can satisfy that: a
+*   remote provider's `resolve` returns a path on the REMOTE host, and
+*   `fs.readdir` of it on this node either fails or — far worse — succeeds
+*   against a same-named local directory that is something else entirely.
+*
+* - `'cap-mediated'` — every byte travels through the `storage` cap
+*   (`read`/`write`, or `beginUpload`/`writeChunk`/`finalizeUpload`). The
+*   service never sees a path, so any provider can back it. `backups` is the
+*   one kind that qualifies today.
+*
+* Before this existed, `recordings` was unreachable by SFTP/S3/WebDAV only as
+* an EMERGENT property of how the recorder happened to be written. Nothing
+* refused the configuration; the first write simply went somewhere wrong, and
+* a recording write that goes wrong surfaces as a silent black window rather
+* than an error (the read path does not `stat`). This turns that accident into
+* a declared, enforced, testable refusal.
+*/
+var StorageAccessSchema = _enum(["local-path", "cap-mediated"]);
 var StorageLocationDeclarationSchema = object({
 	/**
 	* Global location identifier, e.g. `recordings` or `recordingsLow`.
@@ -8253,6 +8506,19 @@ var StorageLocationDeclarationSchema = object({
 	*/
 	cardinality: _enum(["single", "multi"]),
 	/**
+	* HOW the declaring service reaches the bytes — and therefore WHICH
+	* providers may back a location of this kind. See {@link StorageAccessSchema}
+	* and {@link STORAGE_ACCESS_FALLBACK}.
+	*
+	* Absent means `'local-path'`. That default is FAIL-CLOSED on purpose: it
+	* can only over-restrict (refuse a remote provider for a kind that might
+	* have coped) and never under-restrict. Declaring `'cap-mediated'` is the
+	* permissive direction and is therefore never inferred — a repo guard
+	* (`scripts/check-storage-access-declarations.ts`) refuses to let it be
+	* reached by omission.
+	*/
+	access: StorageAccessSchema.optional(),
+	/**
 	* When set, the default instance for this location inherits its resolved
 	* root from the named location's default instance. Useful for derivative
 	* slots (e.g. `recordingsLow` → `recordings`) so operators only need to
@@ -18186,8 +18452,10 @@ var TrackSchema = object({
 	lastSeen: number(),
 	/** Frame-rate position history (subject to maxPositionHistory cap). */
 	positions: array(TrackPositionSchema).readonly(),
-	/** Periodic snapshots at snapshotIntervalMs cadence (subject to
-	*  saveThumbnails policy). */
+	/** Periodic snapshots at snapshotIntervalMs cadence — DEBUG media, produced
+	*  only while `MediaSettings.debugMediaEnabled` is on for the camera (D299;
+	*  the retired `saveThumbnails` used to gate this and the rolling
+	*  `lastFrame` together). Empty is the healthy default, not a capture gap. */
 	snapshots: array(TrackSnapshotSchema).readonly(),
 	/** Deduplicated zones the track has entered at least once. Zone IDS. */
 	zonesVisited: array(string$2()).readonly(),
@@ -19047,6 +19315,9 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), method(RelocateMediaInputSchema, object({ jobId: string$2() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(RelocatableMediaCountInputSchema, RelocatableMediaCountSchema, {
+	kind: "query",
+	auth: "admin"
 }), method(object({}), array(RelocateJobSchema).readonly(), {
 	kind: "query",
 	auth: "admin"
@@ -20954,7 +21225,10 @@ method(object({
 }), StorageLocationSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({ id: string$2() }), _void(), {
+}), method(object({
+	id: string$2(),
+	force: boolean().optional()
+}), _void(), {
 	kind: "mutation",
 	auth: "admin"
 }), method(object({ id: string$2() }), object({
@@ -21003,6 +21277,9 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
 }), method(object({ jobId: string$2().optional() }), StorageMigrationJobSchema.nullable(), { auth: "admin" }), method(object({ jobId: string$2() }), object({ cancelled: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), array(StorageMigrationMoverSchema).readonly(), { auth: "admin" }), method(object({}), array(StorageMigrationResidueSchema).readonly(), { auth: "admin" }), method(StorageMigrationDrainInputSchema, object({ jobId: string$2() }), {
+	kind: "mutation",
+	auth: "admin"
 });
 var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string$2().min(1),
@@ -21401,12 +21678,38 @@ response: record(string$2(), unknown()) }), object({
 *
 * ## Why this is a capability and not a helper
 *
-* Six stores in `addon-post-analysis` already hold vectors — object CLIP, face,
-* plate, vehicle, identity, and the event store's derivatives — and every one of
-* them keeps its vectors in a `JSON` settings-store column and ranks them by
-* brute-force cosine in JS. Measured on the live hub that costs ~11.7 KB per row
-* (512 floats as TEXT, `JSON.parse`d on every search) and made semantic search
-* load 5,000 rows before ranking anything.
+* This capability was introduced with the claim that SIX stores in
+* `addon-post-analysis` held vectors in a `JSON` settings-store column — object
+* CLIP, face, plate, vehicle, identity, and the event store's derivatives. That
+* claim was never true, and leaving it here made five stores look like pending
+* work when three of them have no vector at all. Counted column by column on
+* 2026-08-30, exactly THREE ever held one:
+*
+*  - `object-clip`      — 512-dim CLIP image embedding, migrated 2026-08-06.
+*  - `faces.embedding`  — 512-dim ArcFace face embedding, migrated 2026-08-30.
+*  - `identity-samples.embedding` — the same ArcFace vector for an ENROLLED
+*    face, migrated 2026-08-30 into its OWN index (see below).
+*
+* `plates` and `vehicle-samples` store a plate STRING and a score; `vehicles`
+* and `identities` store a name; the event store stores no derivative vector.
+* They are not migration candidates and never were.
+*
+* Measured on the live hub the JSON encoding cost ~11.7 KB per row (512 floats
+* as TEXT, `JSON.parse`d on every search) and made semantic search load 5,000
+* rows before ranking anything.
+*
+* ## One index per COMPARISON, never per encoder
+*
+* `faces` and `identity-samples` hold the same 512 ArcFace dims from the same
+* model, and they still get two indexes. An index is a set of things that are
+* ranked against each other and that live and die together, and these two are
+* neither: a `faces` row is TRACK-OWNED and cascades away with its track under
+* a per-camera capacity cap, an `identity-samples` row is retention-EXEMPT
+* forever and is the gallery every recognition ranks against. One index would
+* mean every gallery load and every reconcile carried a filter whose failure
+* mode is either ranking a candidate against itself or reclaiming an enrolled
+* person's only sample. The dimension they share is not a reason to share an
+* index; the question they answer is, and it differs.
 *
 * The fix is not a faster loop, it is a different backend — and the backend
 * should be replaceable without touching six callers. So: a singleton
@@ -21511,7 +21814,20 @@ var VectorQueryResultSchema = object({
 	*/
 	scanned: number(),
 	/** True when the backend could not consider every row that passed the filter. */
-	truncated: boolean()
+	truncated: boolean(),
+	/**
+	* The `topK` the backend actually ran with.
+	*
+	* Every backend has a ceiling — sqlite-vec's is 4,096 — and a caller asking
+	* past it used to learn nothing but a boolean, from a WARN in the provider's
+	* own log rather than in its answer. That is how an audit asking for 20,000
+	* consumed 4,096 and reported `examined: 4096` as if it had walked the index,
+	* for weeks. `truncated` says THAT the answer was short; this says BY HOW
+	* MUCH, in the return value, where the caller cannot fail to see it.
+	*
+	* Equals the requested `topK` whenever nothing was lowered.
+	*/
+	effectiveTopK: number().int().positive()
 });
 var VectorDeleteInputSchema = object({
 	index: string$2(),
@@ -21540,6 +21856,68 @@ var VectorGetResultSchema = object({ items: array(object({
 	id: string$2(),
 	metadata: VectorMetadataSchema
 })) });
+/**
+* Ids to read back WITH their vectors.
+*
+* The sibling of {@link VectorGetResultSchema}, and deliberately a separate
+* method rather than a flag on it: `getByIds` promises no vectors and its one
+* caller depends on that promise. This one promises the opposite.
+*
+* It exists because a store cannot put its vectors here otherwise. An ArcFace
+* gallery is ranked IN PROCESS, per detection, against every enrolled sample —
+* a per-face cross-process KNN would be a network round trip inside the
+* recognition loop. So the gallery is loaded once and held in RAM, and loading
+* it requires the index to hand the floats back. Without this method the only
+* way to keep a readable vector is a JSON column, which is the thing this
+* capability exists to delete.
+*
+* BOUNDED BY THE CALLER: ids are named, never "everything". Enumerating an
+* index is {@link VectorScanInputSchema}'s job, and it returns no vectors.
+*/
+var VectorFetchInputSchema = object({
+	index: string$2(),
+	ids: array(string$2())
+});
+var VectorFetchResultSchema = object({ items: array(object({
+	id: string$2(),
+	/** base64 Float32LE — the same wire form `upsert` accepts. */
+	vector: string$2(),
+	metadata: VectorMetadataSchema
+})) });
+/**
+* ENUMERATE an index: one page of rows in a stable order, no ranking.
+*
+* A reconcile does not want the nearest rows, it wants ALL of them, and asking
+* a KNN for "all" is the wrong question twice over. It hits the backend's `k`
+* ceiling — 4,096 on sqlite-vec against a 22,128-row index — and it needs a
+* probe vector it does not have, so the audit passed a ZERO vector whose cosine
+* distance to every row is degenerate. `examined: 4096` then read as "we
+* looked" for as long as anyone cared to read it.
+*
+* This is the primitive that question actually needs: a bounded page, ordered
+* by the backend's own row order, costing no distance computation at all.
+* Vectors are NOT returned — an enumeration that shipped 2 KB per row would be
+* the full-table read this capability was built to stop.
+*/
+var VectorScanInputSchema = object({
+	index: string$2(),
+	/** Opaque resume point. `0` starts at the top; pass back `nextCursor`. */
+	cursor: number().int().nonnegative().default(0),
+	limit: number().int().positive()
+});
+var VectorScanResultSchema = object({
+	items: array(object({
+		id: string$2(),
+		metadata: VectorMetadataSchema
+	})),
+	/**
+	* Where the next page starts, or `null` when the walk reached the end.
+	*
+	* `null` is the ONLY end-of-index signal. A caller must not infer the end
+	* from a short page: a backend is free to return fewer rows than asked.
+	*/
+	nextCursor: number().int().nonnegative().nullable()
+});
 var VectorStatsInputSchema = object({ index: string$2() });
 var VectorStatsResultSchema = object({
 	/** Provider id, so an operator can tell brute force from an ANN index. */
@@ -21558,7 +21936,7 @@ method(VectorDeclareIndexInputSchema, _void(), {
 }), method(VectorUpsertInputSchema, VectorUpsertResultSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
+}), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorFetchInputSchema, VectorFetchResultSchema, { auth: "admin" }), method(VectorScanInputSchema, VectorScanResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(VectorDeleteByFilterInputSchema, VectorDeleteResultSchema, {
@@ -28194,6 +28572,9 @@ method(object({
 }), method(object({}), array(RelocateJobSchema).readonly(), {
 	kind: "query",
 	auth: "admin"
+}), method(RelocateResidueInputSchema, RelocateResidueSchema, {
+	kind: "query",
+	auth: "admin"
 }), method(object({ jobId: string$2() }), object({ cancelled: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
@@ -34828,6 +35209,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.countRelocatableMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.countUnstampedEventMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.deleteDeviceEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -35986,6 +36379,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recording.getRelocateResidue": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"recording.getStorageMigrationMoveStatus": {
 		capName: "recording",
 		capScope: "system",
@@ -36532,12 +36931,30 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"storageMigration.drain": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"storageMigration.movers": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"storageMigration.plan": {
 		capName: "storage-migration",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
+	"storageMigration.residue": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"storageMigration.start": {
 		capName: "storage-migration",
 		capScope: "system",
@@ -37372,6 +37789,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"vectorStore.fetchByIds": {
+		capName: "vector-store",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"vectorStore.getByIds": {
 		capName: "vector-store",
 		capScope: "system",
@@ -37384,6 +37807,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"vectorStore.scan": {
+		capName: "vector-store",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"vectorStore.stats": {
 		capName: "vector-store",
 		capScope: "system",

package/dist/addon.mjs

@@ -8051,18 +8051,61 @@ var RelocateFootageInputSchema = object({
 * `RecordingConfig.enabled` or camera wrapper bindings. */
 var StorageMigrationLeaseInputSchema = object({ leaseId: string$2().min(1) });
 var StorageMigrationFootageMoveInputSchema = RelocateFootageInputSchema.extend({ leaseId: string$2().min(1) });
+/**
+* What a `relocateMedia` pass DOES. One engine, three passes — never a second
+* mover (the engine already walks both collections with a timestamp cursor and
+* already has a stamp-without-copy path).
+*
+*  - `move`    — the default and the historical behaviour: event-media and
+*                retrain blobs move to `toLocationId` and their rows are
+*                stamped. The enrolled gallery is skipped (D197).
+*  - `seal`    — ROWS ONLY, no bytes. Every row whose `locationId` is NULL is
+*                stamped with `toLocationId`. `toLocationId` here is the id the
+*                bytes ALREADY sit on — today's `eventMedia` default — because
+*                a NULL row means "wherever `eventMedia` points *now*", and the
+*                instant a repoint moves that pointer the row reads from the
+*                new disk while its bytes are on the old one.
+*  - `gallery` — the inverse selection of `move`: ONLY the retention-exempt
+*                (enrolled-gallery) rows, which `move` deliberately skips.
+*                `galleryMedia` is `cardinality: 'single'`, so this pass can
+*                never run beside a live second location: it is stop-the-world
+*                by construction, which is acceptable only because the gallery
+*                is a few KB per enrolled sample.
+*/
+var MediaRelocateModeSchema = _enum([
+	"move",
+	"seal",
+	"gallery"
+]);
 var RelocateMediaInputSchema = object({
 	toLocationId: string$2(),
-	throttleMbps: number().min(1).max(1e3).optional()
+	throttleMbps: number().min(1).max(1e3).optional(),
+	/** Omitted = `move`, the pre-existing behaviour. */
+	mode: MediaRelocateModeSchema.optional()
+});
+/** How many rows still carry NO `locationId` — the population a repoint would
+*  silently re-aim at a disk that does not hold their bytes. Zero is the only
+*  value that permits a non-blocking `eventMedia` cutover. */
+var UnstampedEventMediaCountSchema = object({
+	media: number().int().nonnegative(),
+	retrainFrames: number().int().nonnegative(),
+	total: number().int().nonnegative()
 });
 var StorageMigrationMediaMoveInputSchema = RelocateMediaInputSchema.extend({ leaseId: string$2().min(1) });
-/** The independently selectable logical storage classes. `recordings`
-* encompasses the high and mid segment profiles; `recordingsLow` is low
-* segments; `eventMedia` is post-analysis blobs. */
+/** The independently selectable logical storage classes — every class
+* `storage.listLocationDeclarations` reports, so an operator never meets a
+* Zod enum error where they should meet an explanation.
+*
+* `recordings` encompasses the high and mid segment profiles; `recordingsLow`
+* is low segments; `eventMedia` is post-analysis blobs; `galleryMedia` is the
+* enrolled gallery; `backups` is the system backup archive. The last two have
+* their own rules — see {@link StorageMigrationFindingCodeSchema}. */
 var StorageMigrationClassSchema = _enum([
 	"recordings",
 	"recordingsLow",
-	"eventMedia"
+	"eventMedia",
+	"backups",
+	"galleryMedia"
 ]);
 /** A destination is always an existing, fully-qualified location id. The
 * migration API intentionally never changes a source location's `basePath`:
@@ -8070,20 +8113,56 @@ var StorageMigrationClassSchema = _enum([
 var StorageMigrationDestinationsSchema = object({
 	recordings: string$2().min(1).optional(),
 	recordingsLow: string$2().min(1).optional(),
-	eventMedia: string$2().min(1).optional()
+	eventMedia: string$2().min(1).optional(),
+	backups: string$2().min(1).optional(),
+	galleryMedia: string$2().min(1).optional()
 }).refine((value) => Object.keys(value).length > 0, { message: "select at least one storage class" });
+/**
+* How a migration sequences the cutover against the byte move.
+*
+*  - `blocking`     — the historical order: pause, move every byte, repoint,
+*                     resume. Recording is stopped for the whole move. Right
+*                     for a small or a cold class, and the only legal mode for
+*                     a `cardinality: 'single'` class.
+*  - `nonBlocking`  — repoint FIRST, drain behind: seal, pause, repoint,
+*                     refresh, resume, then move the past with everything
+*                     running. The pause is three bounded instants (a detach +
+*                     attach round, a write-gate drain, a lease) instead of one
+*                     bounded by bytes. 1.09 TB at 7–14 MB/s is thirty hours of
+*                     stopped recording under `blocking`; the same move is
+*                     seconds of stopped recording under `nonBlocking`.
+*
+* The mode is on the JOB, not only on the input, because `status` is where an
+* operator finds out which one is running.
+*/
+var StorageMigrationModeSchema = _enum(["blocking", "nonBlocking"]);
 /** Shared input for planning and starting an orchestrated storage migration. */
 var StorageMigrationInputSchema = object({
 	destinations: StorageMigrationDestinationsSchema,
-	throttleMbps: number().min(1).max(1e3).optional()
+	throttleMbps: number().min(1).max(1e3).optional(),
+	/** Omitted = `blocking`, which stays the default. */
+	mode: StorageMigrationModeSchema.optional()
 });
-/** The durable coordinator state machine. The only phase that changes default
-* locations is `repointing`, after every selected mover has completed and been
-* verified. */
+/**
+* The durable coordinator state machine.
+*
+* `blocking`:
+*   planning → pausing → moving → verifying → repointing → refreshing → resuming → done
+*
+* `nonBlocking`:
+*   planning → sealing → pausing → repointing → refreshing → resuming → draining → verifying → done
+*
+* Same phases, different order plus two new ones — not a second mover.
+* `sealing` closes the `eventMedia` NULL-row hole BEFORE anything is paused;
+* `draining` runs the same movers UNLEASED, after every writer is back up.
+* `repointing` is still the only phase that changes a default location.
+*/
 var StorageMigrationPhaseSchema = _enum([
 	"planning",
+	"sealing",
 	"pausing",
 	"moving",
+	"draining",
 	"verifying",
 	"repointing",
 	"refreshing",
@@ -8097,17 +8176,56 @@ var StorageMigrationParticipantSchema = _enum([
 	"recorder",
 	"analytics"
 ]);
+/**
+* The mover's own numbers, folded onto the coordinator's durable move record.
+*
+* The long half of a non-blocking migration is `draining`, and it is measured
+* in hours: 136 885 files at ~4 MB/s is about five of them. Before this shape
+* existed the only place those numbers appeared was a Loki line, so an operator
+* watching the Admin UI saw `phase: draining` and nothing else for a whole
+* afternoon.
+*
+* It is POLLED, never pushed. Events are telemetry and may be dropped
+* (D8/D11), and a dropped progress event is indistinguishable from a stalled
+* mover — which is the exact failure this is meant to end. The coordinator's
+* `waitForMoves` already fetches the whole {@link RelocateJob} on every tick to
+* read `state`; folding the counters costs no extra read and makes the durable
+* record say afterwards how far a move actually got.
+*
+* `filesTotal` is `null` for "no honest denominator" and is never zero-filled:
+* a windowed footage job (`sinceMs`) and a node with no ledger both genuinely
+* cannot say M, and a 0 there would render as "100 % done".
+*/
+var StorageMigrationMoveProgressSchema = object({
+	filesMoved: number().int().nonnegative(),
+	/** The archive census — the **M** of "N of M" (D295). `null` = unknowable. */
+	filesTotal: number().int().nonnegative().nullable(),
+	bytesMoved: number().int().nonnegative(),
+	/** The MOVER's start, not the migration's: a drain restarted after an addon
+	*  crash gets a new mover, and a rate computed from the migration's start
+	*  would silently average in the time nothing was running. */
+	startedAt: number(),
+	/** When the coordinator last read these numbers. Paired with `startedAt` it
+	*  is the only honest rate: both clocks are the hub's, so a UI never has to
+	*  subtract its own. */
+	observedAt: number()
+});
 var StorageMigrationMoveSchema = object({
 	storageClass: StorageMigrationClassSchema,
 	fromLocationId: string$2(),
 	toLocationId: string$2(),
 	moverJobId: string$2().nullable(),
 	state: RelocateJobStateSchema.nullable(),
-	error: string$2().nullable()
+	error: string$2().nullable(),
+	/** Last observed mover counters; `null` until the mover has been polled once. */
+	progress: StorageMigrationMoveProgressSchema.nullable()
 });
 var StorageMigrationJobSchema = object({
 	jobId: string$2(),
 	phase: StorageMigrationPhaseSchema,
+	/** Which order this job is running. `status` is the only place an operator
+	*  can tell a seconds-long cutover from a thirty-hour one. */
+	mode: StorageMigrationModeSchema,
 	destinations: StorageMigrationDestinationsSchema,
 	throttleMbps: number(),
 	moves: array(StorageMigrationMoveSchema),
@@ -8120,13 +8238,122 @@ var StorageMigrationJobSchema = object({
 	finishedAt: number().nullable(),
 	error: string$2().nullable()
 });
+var StorageMigrationFindingSchema = object({
+	code: _enum([
+		"sharesDeviceWithSource",
+		"deviceIdentityUnknown",
+		"unstampedEventMediaRows",
+		"blockingOnly",
+		"noMover"
+	]),
+	storageClass: StorageMigrationClassSchema,
+	/** Human-readable, already carrying the ids and counts. */
+	message: string$2()
+});
 var StorageMigrationPlanSchema = object({
 	destinations: StorageMigrationDestinationsSchema,
+	/** The mode this plan was built for. A plan is only valid for its mode: the
+	*  `eventMedia` seal gate and the single-cardinality refusal both depend on
+	*  it. */
+	mode: StorageMigrationModeSchema,
 	moves: array(object({
 		storageClass: StorageMigrationClassSchema,
 		fromLocationId: string$2(),
 		toLocationId: string$2()
-	}))
+	})),
+	findings: array(StorageMigrationFindingSchema)
+});
+/**
+* A mover as it exists RIGHT NOW, whether or not a migration job owns it.
+*
+* The coordinator's job record is the state of record for a migration, and its
+* moves carry {@link StorageMigrationMoveProgress}. But the movers are usable
+* standalone — `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
+* are both operator-callable, and on 2026-08-29 a five-hour drain was armed that
+* way because no supported UI path existed. A mover armed like that has no job
+* to fold progress into, so it has to be readable on its own or it is invisible.
+*
+* `migrationJobId` is what tells the two apart: `null` means nothing here
+* orchestrated it.
+*/
+var StorageMigrationMoverSchema = object({
+	lane: _enum(["footage", "media"]),
+	job: RelocateJobSchema,
+	/** The coordinator job that armed this mover, or `null` for a mover armed
+	*  directly against the owning addon. */
+	migrationJobId: string$2().nullable(),
+	/** When the hub read these counters. Stamped here so a rate is `bytesMoved`
+	*  over (`observedAt` − `job.startedAt`) with BOTH ends on the hub's clock —
+	*  a browser subtracting its own `Date.now()` from a server `startedAt` is a
+	*  rate made of two different clocks. */
+	observedAt: number()
+});
+/**
+* What a SOURCE still holds for one storage class — the number that makes a
+* "drain remaining" action honest rather than hopeful.
+*
+* It comes from the archive (`SegmentHourLedger.census` for footage, the media
+* engine's own selection count for media), never from the resident index: a
+* drain sized off `RecordingIndex` is what reported `done` over 80.3 GB it had
+* never been told about (D295).
+*
+* `items`/`bytes` are `null` for "the archive could not be asked", which is
+* deliberately NOT zero: a drain is still offered for an unknown residue,
+* because refusing on an unanswerable read would hide exactly the case an
+* operator needs to act on.
+*/
+var StorageMigrationResidueSchema = object({
+	storageClass: StorageMigrationClassSchema,
+	/** The location still holding the data. `'*'` for the media lane, whose rows
+	*  move from wherever they are rather than from one named source. */
+	fromLocationId: string$2(),
+	/** Where a drain would move it — the class's CURRENT default. */
+	toLocationId: string$2(),
+	/** Segments (footage lane) or rows (media lane) still on the source. */
+	items: number().int().nonnegative().nullable(),
+	/** Bytes on the source; `null` when the lane counts rows rather than bytes. */
+	bytes: number().int().nonnegative().nullable()
+});
+/**
+* Run the DRAIN half and nothing else.
+*
+* A migration that reached `done` has already repointed, so `start` correctly
+* refuses its destination ("already the default") — there is nothing left to
+* repoint. But the drain can fail, be cancelled, be interrupted by a restart,
+* or finish against a work list that was a tenth of the archive (D295), and
+* before this there was no supported way to run only that half: the only way
+* through was calling `recording.relocateFootage` by hand over admin tRPC.
+*
+* `drain` NEVER calls `setDefaultLocations`. That is what keeps `start`'s
+* refusal meaningful: the two verbs are disjoint, so nothing here can silently
+* re-repoint a class that is already migrated.
+*/
+var StorageMigrationDrainInputSchema = object({
+	/** The classes to drain. Each must appear in `storageMigration.residue`, so
+	*  a class whose source is already empty is refused rather than started. */
+	classes: array(StorageMigrationClassSchema).min(1),
+	throttleMbps: number().min(1).max(1e3).optional()
+});
+/** What a footage source still holds, asked of the durable hour ledger. */
+var RelocateResidueInputSchema = object({
+	fromLocationId: string$2().min(1),
+	/** Narrow to one logical class; omit for every profile on the location. */
+	footageClass: RelocateFootageClassSchema.optional()
+});
+/** `null` = the archive could not answer (no ledger on this node, or the
+*  aggregate failed). Never conflated with an empty source. */
+var RelocateResidueSchema = object({
+	segments: number().int().nonnegative(),
+	bytes: number().int().nonnegative()
+}).nullable();
+/** How many rows a media pass would still act on against a given target — the
+*  media lane's denominator AND its residue, from ONE derivation so the two can
+*  never disagree. `null` = the count could not be taken. */
+var RelocatableMediaCountSchema = object({ rows: number().int().nonnegative() }).nullable();
+var RelocatableMediaCountInputSchema = object({
+	toLocationId: string$2().min(1),
+	/** Omitted = `move`. */
+	mode: MediaRelocateModeSchema.optional()
 });
 /**
 * `StorageLocationType` — an addon-declared id that identifies the *kind* of
@@ -8232,6 +8459,32 @@ var StorageLocationRefSchema = union([StorageLocationTypeSchema, string$2().rege
 *   two addons declaring the same `id` must agree on `cardinality` (validated
 *   at kernel aggregation time, not here).
 */
+/**
+* `StorageAccess` — how the service that DECLARED a storage-location kind
+* actually reaches the bytes. It is the constraint that decides which
+* `storage-provider`s may back a location of that kind.
+*
+* - `'local-path'` — the service asks `storage.resolve` for a path string and
+*   then does its own `node:fs` I/O on it (the recorder's segment writer, the
+*   post-analysis media roots). Only a provider that serves a genuine local
+*   filesystem (`getProviderInfo().nodeLocal === true`) can satisfy that: a
+*   remote provider's `resolve` returns a path on the REMOTE host, and
+*   `fs.readdir` of it on this node either fails or — far worse — succeeds
+*   against a same-named local directory that is something else entirely.
+*
+* - `'cap-mediated'` — every byte travels through the `storage` cap
+*   (`read`/`write`, or `beginUpload`/`writeChunk`/`finalizeUpload`). The
+*   service never sees a path, so any provider can back it. `backups` is the
+*   one kind that qualifies today.
+*
+* Before this existed, `recordings` was unreachable by SFTP/S3/WebDAV only as
+* an EMERGENT property of how the recorder happened to be written. Nothing
+* refused the configuration; the first write simply went somewhere wrong, and
+* a recording write that goes wrong surfaces as a silent black window rather
+* than an error (the read path does not `stat`). This turns that accident into
+* a declared, enforced, testable refusal.
+*/
+var StorageAccessSchema = _enum(["local-path", "cap-mediated"]);
 var StorageLocationDeclarationSchema = object({
 	/**
 	* Global location identifier, e.g. `recordings` or `recordingsLow`.
@@ -8251,6 +8504,19 @@ var StorageLocationDeclarationSchema = object({
 	*/
 	cardinality: _enum(["single", "multi"]),
 	/**
+	* HOW the declaring service reaches the bytes — and therefore WHICH
+	* providers may back a location of this kind. See {@link StorageAccessSchema}
+	* and {@link STORAGE_ACCESS_FALLBACK}.
+	*
+	* Absent means `'local-path'`. That default is FAIL-CLOSED on purpose: it
+	* can only over-restrict (refuse a remote provider for a kind that might
+	* have coped) and never under-restrict. Declaring `'cap-mediated'` is the
+	* permissive direction and is therefore never inferred — a repo guard
+	* (`scripts/check-storage-access-declarations.ts`) refuses to let it be
+	* reached by omission.
+	*/
+	access: StorageAccessSchema.optional(),
+	/**
 	* When set, the default instance for this location inherits its resolved
 	* root from the named location's default instance. Useful for derivative
 	* slots (e.g. `recordingsLow` → `recordings`) so operators only need to
@@ -18184,8 +18450,10 @@ var TrackSchema = object({
 	lastSeen: number(),
 	/** Frame-rate position history (subject to maxPositionHistory cap). */
 	positions: array(TrackPositionSchema).readonly(),
-	/** Periodic snapshots at snapshotIntervalMs cadence (subject to
-	*  saveThumbnails policy). */
+	/** Periodic snapshots at snapshotIntervalMs cadence — DEBUG media, produced
+	*  only while `MediaSettings.debugMediaEnabled` is on for the camera (D299;
+	*  the retired `saveThumbnails` used to gate this and the rolling
+	*  `lastFrame` together). Empty is the healthy default, not a capture gap. */
 	snapshots: array(TrackSnapshotSchema).readonly(),
 	/** Deduplicated zones the track has entered at least once. Zone IDS. */
 	zonesVisited: array(string$2()).readonly(),
@@ -19045,6 +19313,9 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), method(RelocateMediaInputSchema, object({ jobId: string$2() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(RelocatableMediaCountInputSchema, RelocatableMediaCountSchema, {
+	kind: "query",
+	auth: "admin"
 }), method(object({}), array(RelocateJobSchema).readonly(), {
 	kind: "query",
 	auth: "admin"
@@ -20952,7 +21223,10 @@ method(object({
 }), StorageLocationSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({ id: string$2() }), _void(), {
+}), method(object({
+	id: string$2(),
+	force: boolean().optional()
+}), _void(), {
 	kind: "mutation",
 	auth: "admin"
 }), method(object({ id: string$2() }), object({
@@ -21001,6 +21275,9 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
 }), method(object({ jobId: string$2().optional() }), StorageMigrationJobSchema.nullable(), { auth: "admin" }), method(object({ jobId: string$2() }), object({ cancelled: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({}), array(StorageMigrationMoverSchema).readonly(), { auth: "admin" }), method(object({}), array(StorageMigrationResidueSchema).readonly(), { auth: "admin" }), method(StorageMigrationDrainInputSchema, object({ jobId: string$2() }), {
+	kind: "mutation",
+	auth: "admin"
 });
 var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string$2().min(1),
@@ -21399,12 +21676,38 @@ response: record(string$2(), unknown()) }), object({
 *
 * ## Why this is a capability and not a helper
 *
-* Six stores in `addon-post-analysis` already hold vectors — object CLIP, face,
-* plate, vehicle, identity, and the event store's derivatives — and every one of
-* them keeps its vectors in a `JSON` settings-store column and ranks them by
-* brute-force cosine in JS. Measured on the live hub that costs ~11.7 KB per row
-* (512 floats as TEXT, `JSON.parse`d on every search) and made semantic search
-* load 5,000 rows before ranking anything.
+* This capability was introduced with the claim that SIX stores in
+* `addon-post-analysis` held vectors in a `JSON` settings-store column — object
+* CLIP, face, plate, vehicle, identity, and the event store's derivatives. That
+* claim was never true, and leaving it here made five stores look like pending
+* work when three of them have no vector at all. Counted column by column on
+* 2026-08-30, exactly THREE ever held one:
+*
+*  - `object-clip`      — 512-dim CLIP image embedding, migrated 2026-08-06.
+*  - `faces.embedding`  — 512-dim ArcFace face embedding, migrated 2026-08-30.
+*  - `identity-samples.embedding` — the same ArcFace vector for an ENROLLED
+*    face, migrated 2026-08-30 into its OWN index (see below).
+*
+* `plates` and `vehicle-samples` store a plate STRING and a score; `vehicles`
+* and `identities` store a name; the event store stores no derivative vector.
+* They are not migration candidates and never were.
+*
+* Measured on the live hub the JSON encoding cost ~11.7 KB per row (512 floats
+* as TEXT, `JSON.parse`d on every search) and made semantic search load 5,000
+* rows before ranking anything.
+*
+* ## One index per COMPARISON, never per encoder
+*
+* `faces` and `identity-samples` hold the same 512 ArcFace dims from the same
+* model, and they still get two indexes. An index is a set of things that are
+* ranked against each other and that live and die together, and these two are
+* neither: a `faces` row is TRACK-OWNED and cascades away with its track under
+* a per-camera capacity cap, an `identity-samples` row is retention-EXEMPT
+* forever and is the gallery every recognition ranks against. One index would
+* mean every gallery load and every reconcile carried a filter whose failure
+* mode is either ranking a candidate against itself or reclaiming an enrolled
+* person's only sample. The dimension they share is not a reason to share an
+* index; the question they answer is, and it differs.
 *
 * The fix is not a faster loop, it is a different backend — and the backend
 * should be replaceable without touching six callers. So: a singleton
@@ -21509,7 +21812,20 @@ var VectorQueryResultSchema = object({
 	*/
 	scanned: number(),
 	/** True when the backend could not consider every row that passed the filter. */
-	truncated: boolean()
+	truncated: boolean(),
+	/**
+	* The `topK` the backend actually ran with.
+	*
+	* Every backend has a ceiling — sqlite-vec's is 4,096 — and a caller asking
+	* past it used to learn nothing but a boolean, from a WARN in the provider's
+	* own log rather than in its answer. That is how an audit asking for 20,000
+	* consumed 4,096 and reported `examined: 4096` as if it had walked the index,
+	* for weeks. `truncated` says THAT the answer was short; this says BY HOW
+	* MUCH, in the return value, where the caller cannot fail to see it.
+	*
+	* Equals the requested `topK` whenever nothing was lowered.
+	*/
+	effectiveTopK: number().int().positive()
 });
 var VectorDeleteInputSchema = object({
 	index: string$2(),
@@ -21538,6 +21854,68 @@ var VectorGetResultSchema = object({ items: array(object({
 	id: string$2(),
 	metadata: VectorMetadataSchema
 })) });
+/**
+* Ids to read back WITH their vectors.
+*
+* The sibling of {@link VectorGetResultSchema}, and deliberately a separate
+* method rather than a flag on it: `getByIds` promises no vectors and its one
+* caller depends on that promise. This one promises the opposite.
+*
+* It exists because a store cannot put its vectors here otherwise. An ArcFace
+* gallery is ranked IN PROCESS, per detection, against every enrolled sample —
+* a per-face cross-process KNN would be a network round trip inside the
+* recognition loop. So the gallery is loaded once and held in RAM, and loading
+* it requires the index to hand the floats back. Without this method the only
+* way to keep a readable vector is a JSON column, which is the thing this
+* capability exists to delete.
+*
+* BOUNDED BY THE CALLER: ids are named, never "everything". Enumerating an
+* index is {@link VectorScanInputSchema}'s job, and it returns no vectors.
+*/
+var VectorFetchInputSchema = object({
+	index: string$2(),
+	ids: array(string$2())
+});
+var VectorFetchResultSchema = object({ items: array(object({
+	id: string$2(),
+	/** base64 Float32LE — the same wire form `upsert` accepts. */
+	vector: string$2(),
+	metadata: VectorMetadataSchema
+})) });
+/**
+* ENUMERATE an index: one page of rows in a stable order, no ranking.
+*
+* A reconcile does not want the nearest rows, it wants ALL of them, and asking
+* a KNN for "all" is the wrong question twice over. It hits the backend's `k`
+* ceiling — 4,096 on sqlite-vec against a 22,128-row index — and it needs a
+* probe vector it does not have, so the audit passed a ZERO vector whose cosine
+* distance to every row is degenerate. `examined: 4096` then read as "we
+* looked" for as long as anyone cared to read it.
+*
+* This is the primitive that question actually needs: a bounded page, ordered
+* by the backend's own row order, costing no distance computation at all.
+* Vectors are NOT returned — an enumeration that shipped 2 KB per row would be
+* the full-table read this capability was built to stop.
+*/
+var VectorScanInputSchema = object({
+	index: string$2(),
+	/** Opaque resume point. `0` starts at the top; pass back `nextCursor`. */
+	cursor: number().int().nonnegative().default(0),
+	limit: number().int().positive()
+});
+var VectorScanResultSchema = object({
+	items: array(object({
+		id: string$2(),
+		metadata: VectorMetadataSchema
+	})),
+	/**
+	* Where the next page starts, or `null` when the walk reached the end.
+	*
+	* `null` is the ONLY end-of-index signal. A caller must not infer the end
+	* from a short page: a backend is free to return fewer rows than asked.
+	*/
+	nextCursor: number().int().nonnegative().nullable()
+});
 var VectorStatsInputSchema = object({ index: string$2() });
 var VectorStatsResultSchema = object({
 	/** Provider id, so an operator can tell brute force from an ANN index. */
@@ -21556,7 +21934,7 @@ method(VectorDeclareIndexInputSchema, _void(), {
 }), method(VectorUpsertInputSchema, VectorUpsertResultSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
+}), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorFetchInputSchema, VectorFetchResultSchema, { auth: "admin" }), method(VectorScanInputSchema, VectorScanResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(VectorDeleteByFilterInputSchema, VectorDeleteResultSchema, {
@@ -28192,6 +28570,9 @@ method(object({
 }), method(object({}), array(RelocateJobSchema).readonly(), {
 	kind: "query",
 	auth: "admin"
+}), method(RelocateResidueInputSchema, RelocateResidueSchema, {
+	kind: "query",
+	auth: "admin"
 }), method(object({ jobId: string$2() }), object({ cancelled: boolean() }), {
 	kind: "mutation",
 	auth: "admin"
@@ -34826,6 +35207,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.countRelocatableMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.countUnstampedEventMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.deleteDeviceEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -35984,6 +36377,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"recording.getRelocateResidue": {
+		capName: "recording",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"recording.getStorageMigrationMoveStatus": {
 		capName: "recording",
 		capScope: "system",
@@ -36530,12 +36929,30 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"storageMigration.drain": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"storageMigration.movers": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"storageMigration.plan": {
 		capName: "storage-migration",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
+	"storageMigration.residue": {
+		capName: "storage-migration",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"storageMigration.start": {
 		capName: "storage-migration",
 		capScope: "system",
@@ -37370,6 +37787,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"vectorStore.fetchByIds": {
+		capName: "vector-store",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"vectorStore.getByIds": {
 		capName: "vector-store",
 		capScope: "system",
@@ -37382,6 +37805,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"vectorStore.scan": {
+		capName: "vector-store",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"vectorStore.stats": {
 		capName: "vector-store",
 		capScope: "system",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-matter-broker",
-  "version": "0.2.41",
+  "version": "0.2.44",
   "description": "Matter broker addon for CamStack — owns a Matter fabric (commissioning + the long-lived controller) via the matter.js controller and brokers commissioned Matter nodes into CamStack",
   "keywords": [
     "camstack",