@camstack/addon-decoder-nodeav 1.2.43 → 1.2.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.js +387 -19
  2. package/dist/index.mjs +387 -19
  3. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -8003,6 +8003,21 @@ var RelocateJobSchema = object({
8003
8003
  bytesMoved: number().int(),
8004
8004
  /** Total files discovered up front; null while (or when) unknown. */
8005
8005
  filesTotal: number().int().nullable(),
8006
+ /**
8007
+ * Rows this run CORRECTED while moving them — a durable mutation the move
8008
+ * made that nobody asked for, so it is reported where the operator reads the
8009
+ * job rather than only in a log line.
8010
+ *
8011
+ * A footage segment records its byte count in its own NAME, and the durable
8012
+ * hour row derives its aggregates from those names. A file that does not
8013
+ * match its name therefore makes the ledger's sums — and with them quota and
8014
+ * pressure eviction — wrong by the difference, and only a rename can fix it.
8015
+ * On 2026-08-30 one such row also stalled a 110 749-file drain permanently.
8016
+ *
8017
+ * Absent on lanes where the question has no meaning: a media blob's size is
8018
+ * in its row, not in its name, so `MediaRelocateEngine` never reconciles one.
8019
+ */
8020
+ rowsReconciled: number().int().nonnegative().optional(),
8006
8021
  startedAt: number(),
8007
8022
  finishedAt: number().nullable(),
8008
8023
  error: string().nullable()
@@ -8071,14 +8086,42 @@ var RelocateMediaInputSchema = object({
8071
8086
  /** Omitted = `move`, the pre-existing behaviour. */
8072
8087
  mode: MediaRelocateModeSchema.optional()
8073
8088
  });
8074
- /** How many rows still carry NO `locationId` — the population a repoint would
8075
- * silently re-aim at a disk that does not hold their bytes. Zero is the only
8076
- * value that permits a non-blocking `eventMedia` cutover. */
8077
- var UnstampedEventMediaCountSchema = object({
8078
- media: number().int().nonnegative(),
8079
- retrainFrames: number().int().nonnegative(),
8080
- total: number().int().nonnegative()
8089
+ /**
8090
+ * The unstamped population of ONE collection split, because the gate and the
8091
+ * operator ask two different questions and only one of them has to be cheap.
8092
+ *
8093
+ * `present` is the GATE: "is there at least one row that would be orphaned by a
8094
+ * repoint". It is a single indexed seek to the first matching row, so it stays
8095
+ * answerable on a saturated disk and answers in O(log n) precisely in the state
8096
+ * that matters — after a seal, when the population is empty.
8097
+ *
8098
+ * `rows` is the NUMBER, for the refusal message and the operator's sense of
8099
+ * scale. It is a second, indexed `COUNT(*)`, and `null` means **not
8100
+ * measurable** — never zero. `{ present: true, rows: null }` is a legitimate
8101
+ * and useful answer: "there are some, and this read could not say how many"
8102
+ * still refuses the cutover, which is the whole job.
8103
+ */
8104
+ var UnstampedRowsSchema = object({
8105
+ present: boolean(),
8106
+ rows: number().int().nonnegative().nullable()
8081
8107
  });
8108
+ /**
8109
+ * How many rows still carry NO `locationId` — the population a repoint would
8110
+ * silently re-aim at a disk that does not hold their bytes.
8111
+ *
8112
+ * **`null` = the count could not be taken**, and it is NOT permission to cut
8113
+ * over. The gate opens on a measured absence and on nothing else; an unread
8114
+ * collection and an empty one are different facts, and this repo has already
8115
+ * paid for conflating them (`RelocateResidueSchema`, D295).
8116
+ */
8117
+ var UnstampedEventMediaCountSchema = object({
8118
+ media: UnstampedRowsSchema,
8119
+ retrainFrames: UnstampedRowsSchema,
8120
+ /** True when EITHER collection holds one. The refusal reads this. */
8121
+ anyPresent: boolean(),
8122
+ /** Sum across both, or `null` when either lane could not be counted. */
8123
+ total: number().int().nonnegative().nullable()
8124
+ }).nullable();
8082
8125
  var StorageMigrationMediaMoveInputSchema = RelocateMediaInputSchema.extend({ leaseId: string().min(1) });
8083
8126
  /** The independently selectable logical storage classes — every class
8084
8127
  * `storage.listLocationDeclarations` reports, so an operator never meets a
@@ -8164,13 +8207,53 @@ var StorageMigrationParticipantSchema = _enum([
8164
8207
  "recorder",
8165
8208
  "analytics"
8166
8209
  ]);
8210
+ /**
8211
+ * The mover's own numbers, folded onto the coordinator's durable move record.
8212
+ *
8213
+ * The long half of a non-blocking migration is `draining`, and it is measured
8214
+ * in hours: 136 885 files at ~4 MB/s is about five of them. Before this shape
8215
+ * existed the only place those numbers appeared was a Loki line, so an operator
8216
+ * watching the Admin UI saw `phase: draining` and nothing else for a whole
8217
+ * afternoon.
8218
+ *
8219
+ * It is POLLED, never pushed. Events are telemetry and may be dropped
8220
+ * (D8/D11), and a dropped progress event is indistinguishable from a stalled
8221
+ * mover — which is the exact failure this is meant to end. The coordinator's
8222
+ * `waitForMoves` already fetches the whole {@link RelocateJob} on every tick to
8223
+ * read `state`; folding the counters costs no extra read and makes the durable
8224
+ * record say afterwards how far a move actually got.
8225
+ *
8226
+ * `filesTotal` is `null` for "no honest denominator" and is never zero-filled:
8227
+ * a windowed footage job (`sinceMs`) and a node with no ledger both genuinely
8228
+ * cannot say M, and a 0 there would render as "100 % done".
8229
+ */
8230
+ var StorageMigrationMoveProgressSchema = object({
8231
+ filesMoved: number().int().nonnegative(),
8232
+ /** The archive census — the **M** of "N of M" (D295). `null` = unknowable. */
8233
+ filesTotal: number().int().nonnegative().nullable(),
8234
+ bytesMoved: number().int().nonnegative(),
8235
+ /** Rows the mover corrected while moving them — see `RelocateJob`. Absent on
8236
+ * a lane that cannot reconcile. A migration that silently rewrote durable
8237
+ * rows would be the same failure as one that silently skipped them. */
8238
+ rowsReconciled: number().int().nonnegative().optional(),
8239
+ /** The MOVER's start, not the migration's: a drain restarted after an addon
8240
+ * crash gets a new mover, and a rate computed from the migration's start
8241
+ * would silently average in the time nothing was running. */
8242
+ startedAt: number(),
8243
+ /** When the coordinator last read these numbers. Paired with `startedAt` it
8244
+ * is the only honest rate: both clocks are the hub's, so a UI never has to
8245
+ * subtract its own. */
8246
+ observedAt: number()
8247
+ });
8167
8248
  var StorageMigrationMoveSchema = object({
8168
8249
  storageClass: StorageMigrationClassSchema,
8169
8250
  fromLocationId: string(),
8170
8251
  toLocationId: string(),
8171
8252
  moverJobId: string().nullable(),
8172
8253
  state: RelocateJobStateSchema.nullable(),
8173
- error: string().nullable()
8254
+ error: string().nullable(),
8255
+ /** Last observed mover counters; `null` until the mover has been polled once. */
8256
+ progress: StorageMigrationMoveProgressSchema.nullable()
8174
8257
  });
8175
8258
  var StorageMigrationJobSchema = object({
8176
8259
  jobId: string(),
@@ -8216,6 +8299,98 @@ var StorageMigrationPlanSchema = object({
8216
8299
  findings: array(StorageMigrationFindingSchema)
8217
8300
  });
8218
8301
  /**
8302
+ * A mover as it exists RIGHT NOW, whether or not a migration job owns it.
8303
+ *
8304
+ * The coordinator's job record is the state of record for a migration, and its
8305
+ * moves carry {@link StorageMigrationMoveProgress}. But the movers are usable
8306
+ * standalone — `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
8307
+ * are both operator-callable, and on 2026-08-29 a five-hour drain was armed that
8308
+ * way because no supported UI path existed. A mover armed like that has no job
8309
+ * to fold progress into, so it has to be readable on its own or it is invisible.
8310
+ *
8311
+ * `migrationJobId` is what tells the two apart: `null` means nothing here
8312
+ * orchestrated it.
8313
+ */
8314
+ var StorageMigrationMoverSchema = object({
8315
+ lane: _enum(["footage", "media"]),
8316
+ job: RelocateJobSchema,
8317
+ /** The coordinator job that armed this mover, or `null` for a mover armed
8318
+ * directly against the owning addon. */
8319
+ migrationJobId: string().nullable(),
8320
+ /** When the hub read these counters. Stamped here so a rate is `bytesMoved`
8321
+ * over (`observedAt` − `job.startedAt`) with BOTH ends on the hub's clock —
8322
+ * a browser subtracting its own `Date.now()` from a server `startedAt` is a
8323
+ * rate made of two different clocks. */
8324
+ observedAt: number()
8325
+ });
8326
+ /**
8327
+ * What a SOURCE still holds for one storage class — the number that makes a
8328
+ * "drain remaining" action honest rather than hopeful.
8329
+ *
8330
+ * It comes from the archive (`SegmentHourLedger.census` for footage, the media
8331
+ * engine's own selection count for media), never from the resident index: a
8332
+ * drain sized off `RecordingIndex` is what reported `done` over 80.3 GB it had
8333
+ * never been told about (D295).
8334
+ *
8335
+ * `items`/`bytes` are `null` for "the archive could not be asked", which is
8336
+ * deliberately NOT zero: a drain is still offered for an unknown residue,
8337
+ * because refusing on an unanswerable read would hide exactly the case an
8338
+ * operator needs to act on.
8339
+ */
8340
+ var StorageMigrationResidueSchema = object({
8341
+ storageClass: StorageMigrationClassSchema,
8342
+ /** The location still holding the data. `'*'` for the media lane, whose rows
8343
+ * move from wherever they are rather than from one named source. */
8344
+ fromLocationId: string(),
8345
+ /** Where a drain would move it — the class's CURRENT default. */
8346
+ toLocationId: string(),
8347
+ /** Segments (footage lane) or rows (media lane) still on the source. */
8348
+ items: number().int().nonnegative().nullable(),
8349
+ /** Bytes on the source; `null` when the lane counts rows rather than bytes. */
8350
+ bytes: number().int().nonnegative().nullable()
8351
+ });
8352
+ /**
8353
+ * Run the DRAIN half and nothing else.
8354
+ *
8355
+ * A migration that reached `done` has already repointed, so `start` correctly
8356
+ * refuses its destination ("already the default") — there is nothing left to
8357
+ * repoint. But the drain can fail, be cancelled, be interrupted by a restart,
8358
+ * or finish against a work list that was a tenth of the archive (D295), and
8359
+ * before this there was no supported way to run only that half: the only way
8360
+ * through was calling `recording.relocateFootage` by hand over admin tRPC.
8361
+ *
8362
+ * `drain` NEVER calls `setDefaultLocations`. That is what keeps `start`'s
8363
+ * refusal meaningful: the two verbs are disjoint, so nothing here can silently
8364
+ * re-repoint a class that is already migrated.
8365
+ */
8366
+ var StorageMigrationDrainInputSchema = object({
8367
+ /** The classes to drain. Each must appear in `storageMigration.residue`, so
8368
+ * a class whose source is already empty is refused rather than started. */
8369
+ classes: array(StorageMigrationClassSchema).min(1),
8370
+ throttleMbps: number().min(1).max(1e3).optional()
8371
+ });
8372
+ /** What a footage source still holds, asked of the durable hour ledger. */
8373
+ var RelocateResidueInputSchema = object({
8374
+ fromLocationId: string().min(1),
8375
+ /** Narrow to one logical class; omit for every profile on the location. */
8376
+ footageClass: RelocateFootageClassSchema.optional()
8377
+ });
8378
+ /** `null` = the archive could not answer (no ledger on this node, or the
8379
+ * aggregate failed). Never conflated with an empty source. */
8380
+ var RelocateResidueSchema = object({
8381
+ segments: number().int().nonnegative(),
8382
+ bytes: number().int().nonnegative()
8383
+ }).nullable();
8384
+ /** How many rows a media pass would still act on against a given target — the
8385
+ * media lane's denominator AND its residue, from ONE derivation so the two can
8386
+ * never disagree. `null` = the count could not be taken. */
8387
+ var RelocatableMediaCountSchema = object({ rows: number().int().nonnegative() }).nullable();
8388
+ var RelocatableMediaCountInputSchema = object({
8389
+ toLocationId: string().min(1),
8390
+ /** Omitted = `move`. */
8391
+ mode: MediaRelocateModeSchema.optional()
8392
+ });
8393
+ /**
8219
8394
  * `StorageLocationType` — an addon-declared id that identifies the *kind* of
8220
8395
  * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
8221
8396
  * so the persisted record schema and the consumer-facing cap can both consume it
@@ -8319,6 +8494,32 @@ var StorageLocationRefSchema = union([StorageLocationTypeSchema, string().regex(
8319
8494
  * two addons declaring the same `id` must agree on `cardinality` (validated
8320
8495
  * at kernel aggregation time, not here).
8321
8496
  */
8497
+ /**
8498
+ * `StorageAccess` — how the service that DECLARED a storage-location kind
8499
+ * actually reaches the bytes. It is the constraint that decides which
8500
+ * `storage-provider`s may back a location of that kind.
8501
+ *
8502
+ * - `'local-path'` — the service asks `storage.resolve` for a path string and
8503
+ * then does its own `node:fs` I/O on it (the recorder's segment writer, the
8504
+ * post-analysis media roots). Only a provider that serves a genuine local
8505
+ * filesystem (`getProviderInfo().nodeLocal === true`) can satisfy that: a
8506
+ * remote provider's `resolve` returns a path on the REMOTE host, and
8507
+ * `fs.readdir` of it on this node either fails or — far worse — succeeds
8508
+ * against a same-named local directory that is something else entirely.
8509
+ *
8510
+ * - `'cap-mediated'` — every byte travels through the `storage` cap
8511
+ * (`read`/`write`, or `beginUpload`/`writeChunk`/`finalizeUpload`). The
8512
+ * service never sees a path, so any provider can back it. `backups` is the
8513
+ * one kind that qualifies today.
8514
+ *
8515
+ * Before this existed, `recordings` was unreachable by SFTP/S3/WebDAV only as
8516
+ * an EMERGENT property of how the recorder happened to be written. Nothing
8517
+ * refused the configuration; the first write simply went somewhere wrong, and
8518
+ * a recording write that goes wrong surfaces as a silent black window rather
8519
+ * than an error (the read path does not `stat`). This turns that accident into
8520
+ * a declared, enforced, testable refusal.
8521
+ */
8522
+ var StorageAccessSchema = _enum(["local-path", "cap-mediated"]);
8322
8523
  var StorageLocationDeclarationSchema = object({
8323
8524
  /**
8324
8525
  * Global location identifier, e.g. `recordings` or `recordingsLow`.
@@ -8338,6 +8539,19 @@ var StorageLocationDeclarationSchema = object({
8338
8539
  */
8339
8540
  cardinality: _enum(["single", "multi"]),
8340
8541
  /**
8542
+ * HOW the declaring service reaches the bytes — and therefore WHICH
8543
+ * providers may back a location of this kind. See {@link StorageAccessSchema}
8544
+ * and {@link STORAGE_ACCESS_FALLBACK}.
8545
+ *
8546
+ * Absent means `'local-path'`. That default is FAIL-CLOSED on purpose: it
8547
+ * can only over-restrict (refuse a remote provider for a kind that might
8548
+ * have coped) and never under-restrict. Declaring `'cap-mediated'` is the
8549
+ * permissive direction and is therefore never inferred — a repo guard
8550
+ * (`scripts/check-storage-access-declarations.ts`) refuses to let it be
8551
+ * reached by omission.
8552
+ */
8553
+ access: StorageAccessSchema.optional(),
8554
+ /**
8341
8555
  * When set, the default instance for this location inherits its resolved
8342
8556
  * root from the named location's default instance. Useful for derivative
8343
8557
  * slots (e.g. `recordingsLow` → `recordings`) so operators only need to
@@ -17993,8 +18207,10 @@ var TrackSchema = object({
17993
18207
  lastSeen: number(),
17994
18208
  /** Frame-rate position history (subject to maxPositionHistory cap). */
17995
18209
  positions: array(TrackPositionSchema).readonly(),
17996
- /** Periodic snapshots at snapshotIntervalMs cadence (subject to
17997
- * saveThumbnails policy). */
18210
+ /** Periodic snapshots at snapshotIntervalMs cadence DEBUG media, produced
18211
+ * only while `MediaSettings.debugMediaEnabled` is on for the camera (D299;
18212
+ * the retired `saveThumbnails` used to gate this and the rolling
18213
+ * `lastFrame` together). Empty is the healthy default, not a capture gap. */
17998
18214
  snapshots: array(TrackSnapshotSchema).readonly(),
17999
18215
  /** Deduplicated zones the track has entered at least once. Zone IDS. */
18000
18216
  zonesVisited: array(string()).readonly(),
@@ -18854,7 +19070,10 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
18854
19070
  }), method(RelocateMediaInputSchema, object({ jobId: string() }), {
18855
19071
  kind: "mutation",
18856
19072
  auth: "admin"
18857
- }), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(object({}), array(RelocateJobSchema).readonly(), {
19073
+ }), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(RelocatableMediaCountInputSchema, RelocatableMediaCountSchema, {
19074
+ kind: "query",
19075
+ auth: "admin"
19076
+ }), method(object({}), array(RelocateJobSchema).readonly(), {
18858
19077
  kind: "query",
18859
19078
  auth: "admin"
18860
19079
  }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
@@ -20813,6 +21032,9 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
20813
21032
  }), method(object({ jobId: string().optional() }), StorageMigrationJobSchema.nullable(), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
20814
21033
  kind: "mutation",
20815
21034
  auth: "admin"
21035
+ }), method(object({}), array(StorageMigrationMoverSchema).readonly(), { auth: "admin" }), method(object({}), array(StorageMigrationResidueSchema).readonly(), { auth: "admin" }), method(StorageMigrationDrainInputSchema, object({ jobId: string() }), {
21036
+ kind: "mutation",
21037
+ auth: "admin"
20816
21038
  });
20817
21039
  var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
20818
21040
  providerId: string().min(1),
@@ -21211,12 +21433,38 @@ response: record(string(), unknown()) }), object({
21211
21433
  *
21212
21434
  * ## Why this is a capability and not a helper
21213
21435
  *
21214
- * Six stores in `addon-post-analysis` already hold vectors object CLIP, face,
21215
- * plate, vehicle, identity, and the event store's derivativesand every one of
21216
- * them keeps its vectors in a `JSON` settings-store column and ranks them by
21217
- * brute-force cosine in JS. Measured on the live hub that costs ~11.7 KB per row
21218
- * (512 floats as TEXT, `JSON.parse`d on every search) and made semantic search
21219
- * load 5,000 rows before ranking anything.
21436
+ * This capability was introduced with the claim that SIX stores in
21437
+ * `addon-post-analysis` held vectors in a `JSON` settings-store columnobject
21438
+ * CLIP, face, plate, vehicle, identity, and the event store's derivatives. That
21439
+ * claim was never true, and leaving it here made five stores look like pending
21440
+ * work when three of them have no vector at all. Counted column by column on
21441
+ * 2026-08-30, exactly THREE ever held one:
21442
+ *
21443
+ * - `object-clip` — 512-dim CLIP image embedding, migrated 2026-08-06.
21444
+ * - `faces.embedding` — 512-dim ArcFace face embedding, migrated 2026-08-30.
21445
+ * - `identity-samples.embedding` — the same ArcFace vector for an ENROLLED
21446
+ * face, migrated 2026-08-30 into its OWN index (see below).
21447
+ *
21448
+ * `plates` and `vehicle-samples` store a plate STRING and a score; `vehicles`
21449
+ * and `identities` store a name; the event store stores no derivative vector.
21450
+ * They are not migration candidates and never were.
21451
+ *
21452
+ * Measured on the live hub the JSON encoding cost ~11.7 KB per row (512 floats
21453
+ * as TEXT, `JSON.parse`d on every search) and made semantic search load 5,000
21454
+ * rows before ranking anything.
21455
+ *
21456
+ * ## One index per COMPARISON, never per encoder
21457
+ *
21458
+ * `faces` and `identity-samples` hold the same 512 ArcFace dims from the same
21459
+ * model, and they still get two indexes. An index is a set of things that are
21460
+ * ranked against each other and that live and die together, and these two are
21461
+ * neither: a `faces` row is TRACK-OWNED and cascades away with its track under
21462
+ * a per-camera capacity cap, an `identity-samples` row is retention-EXEMPT
21463
+ * forever and is the gallery every recognition ranks against. One index would
21464
+ * mean every gallery load and every reconcile carried a filter whose failure
21465
+ * mode is either ranking a candidate against itself or reclaiming an enrolled
21466
+ * person's only sample. The dimension they share is not a reason to share an
21467
+ * index; the question they answer is, and it differs.
21220
21468
  *
21221
21469
  * The fix is not a faster loop, it is a different backend — and the backend
21222
21470
  * should be replaceable without touching six callers. So: a singleton
@@ -21321,7 +21569,20 @@ var VectorQueryResultSchema = object({
21321
21569
  */
21322
21570
  scanned: number(),
21323
21571
  /** True when the backend could not consider every row that passed the filter. */
21324
- truncated: boolean()
21572
+ truncated: boolean(),
21573
+ /**
21574
+ * The `topK` the backend actually ran with.
21575
+ *
21576
+ * Every backend has a ceiling — sqlite-vec's is 4,096 — and a caller asking
21577
+ * past it used to learn nothing but a boolean, from a WARN in the provider's
21578
+ * own log rather than in its answer. That is how an audit asking for 20,000
21579
+ * consumed 4,096 and reported `examined: 4096` as if it had walked the index,
21580
+ * for weeks. `truncated` says THAT the answer was short; this says BY HOW
21581
+ * MUCH, in the return value, where the caller cannot fail to see it.
21582
+ *
21583
+ * Equals the requested `topK` whenever nothing was lowered.
21584
+ */
21585
+ effectiveTopK: number().int().positive()
21325
21586
  });
21326
21587
  var VectorDeleteInputSchema = object({
21327
21588
  index: string(),
@@ -21350,6 +21611,68 @@ var VectorGetResultSchema = object({ items: array(object({
21350
21611
  id: string(),
21351
21612
  metadata: VectorMetadataSchema
21352
21613
  })) });
21614
+ /**
21615
+ * Ids to read back WITH their vectors.
21616
+ *
21617
+ * The sibling of {@link VectorGetResultSchema}, and deliberately a separate
21618
+ * method rather than a flag on it: `getByIds` promises no vectors and its one
21619
+ * caller depends on that promise. This one promises the opposite.
21620
+ *
21621
+ * It exists because a store cannot put its vectors here otherwise. An ArcFace
21622
+ * gallery is ranked IN PROCESS, per detection, against every enrolled sample —
21623
+ * a per-face cross-process KNN would be a network round trip inside the
21624
+ * recognition loop. So the gallery is loaded once and held in RAM, and loading
21625
+ * it requires the index to hand the floats back. Without this method the only
21626
+ * way to keep a readable vector is a JSON column, which is the thing this
21627
+ * capability exists to delete.
21628
+ *
21629
+ * BOUNDED BY THE CALLER: ids are named, never "everything". Enumerating an
21630
+ * index is {@link VectorScanInputSchema}'s job, and it returns no vectors.
21631
+ */
21632
+ var VectorFetchInputSchema = object({
21633
+ index: string(),
21634
+ ids: array(string())
21635
+ });
21636
+ var VectorFetchResultSchema = object({ items: array(object({
21637
+ id: string(),
21638
+ /** base64 Float32LE — the same wire form `upsert` accepts. */
21639
+ vector: string(),
21640
+ metadata: VectorMetadataSchema
21641
+ })) });
21642
+ /**
21643
+ * ENUMERATE an index: one page of rows in a stable order, no ranking.
21644
+ *
21645
+ * A reconcile does not want the nearest rows, it wants ALL of them, and asking
21646
+ * a KNN for "all" is the wrong question twice over. It hits the backend's `k`
21647
+ * ceiling — 4,096 on sqlite-vec against a 22,128-row index — and it needs a
21648
+ * probe vector it does not have, so the audit passed a ZERO vector whose cosine
21649
+ * distance to every row is degenerate. `examined: 4096` then read as "we
21650
+ * looked" for as long as anyone cared to read it.
21651
+ *
21652
+ * This is the primitive that question actually needs: a bounded page, ordered
21653
+ * by the backend's own row order, costing no distance computation at all.
21654
+ * Vectors are NOT returned — an enumeration that shipped 2 KB per row would be
21655
+ * the full-table read this capability was built to stop.
21656
+ */
21657
+ var VectorScanInputSchema = object({
21658
+ index: string(),
21659
+ /** Opaque resume point. `0` starts at the top; pass back `nextCursor`. */
21660
+ cursor: number().int().nonnegative().default(0),
21661
+ limit: number().int().positive()
21662
+ });
21663
+ var VectorScanResultSchema = object({
21664
+ items: array(object({
21665
+ id: string(),
21666
+ metadata: VectorMetadataSchema
21667
+ })),
21668
+ /**
21669
+ * Where the next page starts, or `null` when the walk reached the end.
21670
+ *
21671
+ * `null` is the ONLY end-of-index signal. A caller must not infer the end
21672
+ * from a short page: a backend is free to return fewer rows than asked.
21673
+ */
21674
+ nextCursor: number().int().nonnegative().nullable()
21675
+ });
21353
21676
  var VectorStatsInputSchema = object({ index: string() });
21354
21677
  var VectorStatsResultSchema = object({
21355
21678
  /** Provider id, so an operator can tell brute force from an ANN index. */
@@ -21368,7 +21691,7 @@ method(VectorDeclareIndexInputSchema, _void(), {
21368
21691
  }), method(VectorUpsertInputSchema, VectorUpsertResultSchema, {
21369
21692
  kind: "mutation",
21370
21693
  auth: "admin"
21371
- }), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
21694
+ }), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorFetchInputSchema, VectorFetchResultSchema, { auth: "admin" }), method(VectorScanInputSchema, VectorScanResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
21372
21695
  kind: "mutation",
21373
21696
  auth: "admin"
21374
21697
  }), method(VectorDeleteByFilterInputSchema, VectorDeleteResultSchema, {
@@ -26272,6 +26595,9 @@ method(object({
26272
26595
  }), method(object({}), array(RelocateJobSchema).readonly(), {
26273
26596
  kind: "query",
26274
26597
  auth: "admin"
26598
+ }), method(RelocateResidueInputSchema, RelocateResidueSchema, {
26599
+ kind: "query",
26600
+ auth: "admin"
26275
26601
  }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
26276
26602
  kind: "mutation",
26277
26603
  auth: "admin"
@@ -31237,6 +31563,12 @@ Object.freeze({
31237
31563
  addonId: null,
31238
31564
  access: "create"
31239
31565
  },
31566
+ "pipelineAnalytics.countRelocatableMedia": {
31567
+ capName: "pipeline-analytics",
31568
+ capScope: "device",
31569
+ addonId: null,
31570
+ access: "view"
31571
+ },
31240
31572
  "pipelineAnalytics.countUnstampedEventMedia": {
31241
31573
  capName: "pipeline-analytics",
31242
31574
  capScope: "device",
@@ -32401,6 +32733,12 @@ Object.freeze({
32401
32733
  addonId: null,
32402
32734
  access: "view"
32403
32735
  },
32736
+ "recording.getRelocateResidue": {
32737
+ capName: "recording",
32738
+ capScope: "system",
32739
+ addonId: null,
32740
+ access: "view"
32741
+ },
32404
32742
  "recording.getStorageMigrationMoveStatus": {
32405
32743
  capName: "recording",
32406
32744
  capScope: "system",
@@ -32947,12 +33285,30 @@ Object.freeze({
32947
33285
  addonId: null,
32948
33286
  access: "create"
32949
33287
  },
33288
+ "storageMigration.drain": {
33289
+ capName: "storage-migration",
33290
+ capScope: "system",
33291
+ addonId: null,
33292
+ access: "create"
33293
+ },
33294
+ "storageMigration.movers": {
33295
+ capName: "storage-migration",
33296
+ capScope: "system",
33297
+ addonId: null,
33298
+ access: "view"
33299
+ },
32950
33300
  "storageMigration.plan": {
32951
33301
  capName: "storage-migration",
32952
33302
  capScope: "system",
32953
33303
  addonId: null,
32954
33304
  access: "view"
32955
33305
  },
33306
+ "storageMigration.residue": {
33307
+ capName: "storage-migration",
33308
+ capScope: "system",
33309
+ addonId: null,
33310
+ access: "view"
33311
+ },
32956
33312
  "storageMigration.start": {
32957
33313
  capName: "storage-migration",
32958
33314
  capScope: "system",
@@ -33787,6 +34143,12 @@ Object.freeze({
33787
34143
  addonId: null,
33788
34144
  access: "delete"
33789
34145
  },
34146
+ "vectorStore.fetchByIds": {
34147
+ capName: "vector-store",
34148
+ capScope: "system",
34149
+ addonId: null,
34150
+ access: "view"
34151
+ },
33790
34152
  "vectorStore.getByIds": {
33791
34153
  capName: "vector-store",
33792
34154
  capScope: "system",
@@ -33799,6 +34161,12 @@ Object.freeze({
33799
34161
  addonId: null,
33800
34162
  access: "view"
33801
34163
  },
34164
+ "vectorStore.scan": {
34165
+ capName: "vector-store",
34166
+ capScope: "system",
34167
+ addonId: null,
34168
+ access: "view"
34169
+ },
33802
34170
  "vectorStore.stats": {
33803
34171
  capName: "vector-store",
33804
34172
  capScope: "system",
package/dist/index.mjs CHANGED
@@ -7999,6 +7999,21 @@ var RelocateJobSchema = object({
7999
7999
  bytesMoved: number().int(),
8000
8000
  /** Total files discovered up front; null while (or when) unknown. */
8001
8001
  filesTotal: number().int().nullable(),
8002
+ /**
8003
+ * Rows this run CORRECTED while moving them — a durable mutation the move
8004
+ * made that nobody asked for, so it is reported where the operator reads the
8005
+ * job rather than only in a log line.
8006
+ *
8007
+ * A footage segment records its byte count in its own NAME, and the durable
8008
+ * hour row derives its aggregates from those names. A file that does not
8009
+ * match its name therefore makes the ledger's sums — and with them quota and
8010
+ * pressure eviction — wrong by the difference, and only a rename can fix it.
8011
+ * On 2026-08-30 one such row also stalled a 110 749-file drain permanently.
8012
+ *
8013
+ * Absent on lanes where the question has no meaning: a media blob's size is
8014
+ * in its row, not in its name, so `MediaRelocateEngine` never reconciles one.
8015
+ */
8016
+ rowsReconciled: number().int().nonnegative().optional(),
8002
8017
  startedAt: number(),
8003
8018
  finishedAt: number().nullable(),
8004
8019
  error: string().nullable()
@@ -8067,14 +8082,42 @@ var RelocateMediaInputSchema = object({
8067
8082
  /** Omitted = `move`, the pre-existing behaviour. */
8068
8083
  mode: MediaRelocateModeSchema.optional()
8069
8084
  });
8070
- /** How many rows still carry NO `locationId` — the population a repoint would
8071
- * silently re-aim at a disk that does not hold their bytes. Zero is the only
8072
- * value that permits a non-blocking `eventMedia` cutover. */
8073
- var UnstampedEventMediaCountSchema = object({
8074
- media: number().int().nonnegative(),
8075
- retrainFrames: number().int().nonnegative(),
8076
- total: number().int().nonnegative()
8085
+ /**
8086
+ * The unstamped population of ONE collection split, because the gate and the
8087
+ * operator ask two different questions and only one of them has to be cheap.
8088
+ *
8089
+ * `present` is the GATE: "is there at least one row that would be orphaned by a
8090
+ * repoint". It is a single indexed seek to the first matching row, so it stays
8091
+ * answerable on a saturated disk and answers in O(log n) precisely in the state
8092
+ * that matters — after a seal, when the population is empty.
8093
+ *
8094
+ * `rows` is the NUMBER, for the refusal message and the operator's sense of
8095
+ * scale. It is a second, indexed `COUNT(*)`, and `null` means **not
8096
+ * measurable** — never zero. `{ present: true, rows: null }` is a legitimate
8097
+ * and useful answer: "there are some, and this read could not say how many"
8098
+ * still refuses the cutover, which is the whole job.
8099
+ */
8100
+ var UnstampedRowsSchema = object({
8101
+ present: boolean(),
8102
+ rows: number().int().nonnegative().nullable()
8077
8103
  });
8104
+ /**
8105
+ * How many rows still carry NO `locationId` — the population a repoint would
8106
+ * silently re-aim at a disk that does not hold their bytes.
8107
+ *
8108
+ * **`null` = the count could not be taken**, and it is NOT permission to cut
8109
+ * over. The gate opens on a measured absence and on nothing else; an unread
8110
+ * collection and an empty one are different facts, and this repo has already
8111
+ * paid for conflating them (`RelocateResidueSchema`, D295).
8112
+ */
8113
+ var UnstampedEventMediaCountSchema = object({
8114
+ media: UnstampedRowsSchema,
8115
+ retrainFrames: UnstampedRowsSchema,
8116
+ /** True when EITHER collection holds one. The refusal reads this. */
8117
+ anyPresent: boolean(),
8118
+ /** Sum across both, or `null` when either lane could not be counted. */
8119
+ total: number().int().nonnegative().nullable()
8120
+ }).nullable();
8078
8121
  var StorageMigrationMediaMoveInputSchema = RelocateMediaInputSchema.extend({ leaseId: string().min(1) });
8079
8122
  /** The independently selectable logical storage classes — every class
8080
8123
  * `storage.listLocationDeclarations` reports, so an operator never meets a
@@ -8160,13 +8203,53 @@ var StorageMigrationParticipantSchema = _enum([
8160
8203
  "recorder",
8161
8204
  "analytics"
8162
8205
  ]);
8206
+ /**
8207
+ * The mover's own numbers, folded onto the coordinator's durable move record.
8208
+ *
8209
+ * The long half of a non-blocking migration is `draining`, and it is measured
8210
+ * in hours: 136 885 files at ~4 MB/s is about five of them. Before this shape
8211
+ * existed the only place those numbers appeared was a Loki line, so an operator
8212
+ * watching the Admin UI saw `phase: draining` and nothing else for a whole
8213
+ * afternoon.
8214
+ *
8215
+ * It is POLLED, never pushed. Events are telemetry and may be dropped
8216
+ * (D8/D11), and a dropped progress event is indistinguishable from a stalled
8217
+ * mover — which is the exact failure this is meant to end. The coordinator's
8218
+ * `waitForMoves` already fetches the whole {@link RelocateJob} on every tick to
8219
+ * read `state`; folding the counters costs no extra read and makes the durable
8220
+ * record say afterwards how far a move actually got.
8221
+ *
8222
+ * `filesTotal` is `null` for "no honest denominator" and is never zero-filled:
8223
+ * a windowed footage job (`sinceMs`) and a node with no ledger both genuinely
8224
+ * cannot say M, and a 0 there would render as "100 % done".
8225
+ */
8226
+ var StorageMigrationMoveProgressSchema = object({
8227
+ filesMoved: number().int().nonnegative(),
8228
+ /** The archive census — the **M** of "N of M" (D295). `null` = unknowable. */
8229
+ filesTotal: number().int().nonnegative().nullable(),
8230
+ bytesMoved: number().int().nonnegative(),
8231
+ /** Rows the mover corrected while moving them — see `RelocateJob`. Absent on
8232
+ * a lane that cannot reconcile. A migration that silently rewrote durable
8233
+ * rows would be the same failure as one that silently skipped them. */
8234
+ rowsReconciled: number().int().nonnegative().optional(),
8235
+ /** The MOVER's start, not the migration's: a drain restarted after an addon
8236
+ * crash gets a new mover, and a rate computed from the migration's start
8237
+ * would silently average in the time nothing was running. */
8238
+ startedAt: number(),
8239
+ /** When the coordinator last read these numbers. Paired with `startedAt` it
8240
+ * is the only honest rate: both clocks are the hub's, so a UI never has to
8241
+ * subtract its own. */
8242
+ observedAt: number()
8243
+ });
8163
8244
  var StorageMigrationMoveSchema = object({
8164
8245
  storageClass: StorageMigrationClassSchema,
8165
8246
  fromLocationId: string(),
8166
8247
  toLocationId: string(),
8167
8248
  moverJobId: string().nullable(),
8168
8249
  state: RelocateJobStateSchema.nullable(),
8169
- error: string().nullable()
8250
+ error: string().nullable(),
8251
+ /** Last observed mover counters; `null` until the mover has been polled once. */
8252
+ progress: StorageMigrationMoveProgressSchema.nullable()
8170
8253
  });
8171
8254
  var StorageMigrationJobSchema = object({
8172
8255
  jobId: string(),
@@ -8212,6 +8295,98 @@ var StorageMigrationPlanSchema = object({
8212
8295
  findings: array(StorageMigrationFindingSchema)
8213
8296
  });
8214
8297
  /**
8298
+ * A mover as it exists RIGHT NOW, whether or not a migration job owns it.
8299
+ *
8300
+ * The coordinator's job record is the state of record for a migration, and its
8301
+ * moves carry {@link StorageMigrationMoveProgress}. But the movers are usable
8302
+ * standalone — `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
8303
+ * are both operator-callable, and on 2026-08-29 a five-hour drain was armed that
8304
+ * way because no supported UI path existed. A mover armed like that has no job
8305
+ * to fold progress into, so it has to be readable on its own or it is invisible.
8306
+ *
8307
+ * `migrationJobId` is what tells the two apart: `null` means nothing here
8308
+ * orchestrated it.
8309
+ */
8310
+ var StorageMigrationMoverSchema = object({
8311
+ lane: _enum(["footage", "media"]),
8312
+ job: RelocateJobSchema,
8313
+ /** The coordinator job that armed this mover, or `null` for a mover armed
8314
+ * directly against the owning addon. */
8315
+ migrationJobId: string().nullable(),
8316
+ /** When the hub read these counters. Stamped here so a rate is `bytesMoved`
8317
+ * over (`observedAt` − `job.startedAt`) with BOTH ends on the hub's clock —
8318
+ * a browser subtracting its own `Date.now()` from a server `startedAt` is a
8319
+ * rate made of two different clocks. */
8320
+ observedAt: number()
8321
+ });
8322
+ /**
8323
+ * What a SOURCE still holds for one storage class — the number that makes a
8324
+ * "drain remaining" action honest rather than hopeful.
8325
+ *
8326
+ * It comes from the archive (`SegmentHourLedger.census` for footage, the media
8327
+ * engine's own selection count for media), never from the resident index: a
8328
+ * drain sized off `RecordingIndex` is what reported `done` over 80.3 GB it had
8329
+ * never been told about (D295).
8330
+ *
8331
+ * `items`/`bytes` are `null` for "the archive could not be asked", which is
8332
+ * deliberately NOT zero: a drain is still offered for an unknown residue,
8333
+ * because refusing on an unanswerable read would hide exactly the case an
8334
+ * operator needs to act on.
8335
+ */
8336
+ var StorageMigrationResidueSchema = object({
8337
+ storageClass: StorageMigrationClassSchema,
8338
+ /** The location still holding the data. `'*'` for the media lane, whose rows
8339
+ * move from wherever they are rather than from one named source. */
8340
+ fromLocationId: string(),
8341
+ /** Where a drain would move it — the class's CURRENT default. */
8342
+ toLocationId: string(),
8343
+ /** Segments (footage lane) or rows (media lane) still on the source. */
8344
+ items: number().int().nonnegative().nullable(),
8345
+ /** Bytes on the source; `null` when the lane counts rows rather than bytes. */
8346
+ bytes: number().int().nonnegative().nullable()
8347
+ });
8348
+ /**
8349
+ * Run the DRAIN half and nothing else.
8350
+ *
8351
+ * A migration that reached `done` has already repointed, so `start` correctly
8352
+ * refuses its destination ("already the default") — there is nothing left to
8353
+ * repoint. But the drain can fail, be cancelled, be interrupted by a restart,
8354
+ * or finish against a work list that was a tenth of the archive (D295), and
8355
+ * before this there was no supported way to run only that half: the only way
8356
+ * through was calling `recording.relocateFootage` by hand over admin tRPC.
8357
+ *
8358
+ * `drain` NEVER calls `setDefaultLocations`. That is what keeps `start`'s
8359
+ * refusal meaningful: the two verbs are disjoint, so nothing here can silently
8360
+ * re-repoint a class that is already migrated.
8361
+ */
8362
+ var StorageMigrationDrainInputSchema = object({
8363
+ /** The classes to drain. Each must appear in `storageMigration.residue`, so
8364
+ * a class whose source is already empty is refused rather than started. */
8365
+ classes: array(StorageMigrationClassSchema).min(1),
8366
+ throttleMbps: number().min(1).max(1e3).optional()
8367
+ });
8368
+ /** What a footage source still holds, asked of the durable hour ledger. */
8369
+ var RelocateResidueInputSchema = object({
8370
+ fromLocationId: string().min(1),
8371
+ /** Narrow to one logical class; omit for every profile on the location. */
8372
+ footageClass: RelocateFootageClassSchema.optional()
8373
+ });
8374
+ /** `null` = the archive could not answer (no ledger on this node, or the
8375
+ * aggregate failed). Never conflated with an empty source. */
8376
+ var RelocateResidueSchema = object({
8377
+ segments: number().int().nonnegative(),
8378
+ bytes: number().int().nonnegative()
8379
+ }).nullable();
8380
+ /** How many rows a media pass would still act on against a given target — the
8381
+ * media lane's denominator AND its residue, from ONE derivation so the two can
8382
+ * never disagree. `null` = the count could not be taken. */
8383
+ var RelocatableMediaCountSchema = object({ rows: number().int().nonnegative() }).nullable();
8384
+ var RelocatableMediaCountInputSchema = object({
8385
+ toLocationId: string().min(1),
8386
+ /** Omitted = `move`. */
8387
+ mode: MediaRelocateModeSchema.optional()
8388
+ });
8389
+ /**
8215
8390
  * `StorageLocationType` — an addon-declared id that identifies the *kind* of
8216
8391
  * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
8217
8392
  * so the persisted record schema and the consumer-facing cap can both consume it
@@ -8315,6 +8490,32 @@ var StorageLocationRefSchema = union([StorageLocationTypeSchema, string().regex(
8315
8490
  * two addons declaring the same `id` must agree on `cardinality` (validated
8316
8491
  * at kernel aggregation time, not here).
8317
8492
  */
8493
+ /**
8494
+ * `StorageAccess` — how the service that DECLARED a storage-location kind
8495
+ * actually reaches the bytes. It is the constraint that decides which
8496
+ * `storage-provider`s may back a location of that kind.
8497
+ *
8498
+ * - `'local-path'` — the service asks `storage.resolve` for a path string and
8499
+ * then does its own `node:fs` I/O on it (the recorder's segment writer, the
8500
+ * post-analysis media roots). Only a provider that serves a genuine local
8501
+ * filesystem (`getProviderInfo().nodeLocal === true`) can satisfy that: a
8502
+ * remote provider's `resolve` returns a path on the REMOTE host, and
8503
+ * `fs.readdir` of it on this node either fails or — far worse — succeeds
8504
+ * against a same-named local directory that is something else entirely.
8505
+ *
8506
+ * - `'cap-mediated'` — every byte travels through the `storage` cap
8507
+ * (`read`/`write`, or `beginUpload`/`writeChunk`/`finalizeUpload`). The
8508
+ * service never sees a path, so any provider can back it. `backups` is the
8509
+ * one kind that qualifies today.
8510
+ *
8511
+ * Before this existed, `recordings` was unreachable by SFTP/S3/WebDAV only as
8512
+ * an EMERGENT property of how the recorder happened to be written. Nothing
8513
+ * refused the configuration; the first write simply went somewhere wrong, and
8514
+ * a recording write that goes wrong surfaces as a silent black window rather
8515
+ * than an error (the read path does not `stat`). This turns that accident into
8516
+ * a declared, enforced, testable refusal.
8517
+ */
8518
+ var StorageAccessSchema = _enum(["local-path", "cap-mediated"]);
8318
8519
  var StorageLocationDeclarationSchema = object({
8319
8520
  /**
8320
8521
  * Global location identifier, e.g. `recordings` or `recordingsLow`.
@@ -8334,6 +8535,19 @@ var StorageLocationDeclarationSchema = object({
8334
8535
  */
8335
8536
  cardinality: _enum(["single", "multi"]),
8336
8537
  /**
8538
+ * HOW the declaring service reaches the bytes — and therefore WHICH
8539
+ * providers may back a location of this kind. See {@link StorageAccessSchema}
8540
+ * and {@link STORAGE_ACCESS_FALLBACK}.
8541
+ *
8542
+ * Absent means `'local-path'`. That default is FAIL-CLOSED on purpose: it
8543
+ * can only over-restrict (refuse a remote provider for a kind that might
8544
+ * have coped) and never under-restrict. Declaring `'cap-mediated'` is the
8545
+ * permissive direction and is therefore never inferred — a repo guard
8546
+ * (`scripts/check-storage-access-declarations.ts`) refuses to let it be
8547
+ * reached by omission.
8548
+ */
8549
+ access: StorageAccessSchema.optional(),
8550
+ /**
8337
8551
  * When set, the default instance for this location inherits its resolved
8338
8552
  * root from the named location's default instance. Useful for derivative
8339
8553
  * slots (e.g. `recordingsLow` → `recordings`) so operators only need to
@@ -17989,8 +18203,10 @@ var TrackSchema = object({
17989
18203
  lastSeen: number(),
17990
18204
  /** Frame-rate position history (subject to maxPositionHistory cap). */
17991
18205
  positions: array(TrackPositionSchema).readonly(),
17992
- /** Periodic snapshots at snapshotIntervalMs cadence (subject to
17993
- * saveThumbnails policy). */
18206
+ /** Periodic snapshots at snapshotIntervalMs cadence DEBUG media, produced
18207
+ * only while `MediaSettings.debugMediaEnabled` is on for the camera (D299;
18208
+ * the retired `saveThumbnails` used to gate this and the rolling
18209
+ * `lastFrame` together). Empty is the healthy default, not a capture gap. */
17994
18210
  snapshots: array(TrackSnapshotSchema).readonly(),
17995
18211
  /** Deduplicated zones the track has entered at least once. Zone IDS. */
17996
18212
  zonesVisited: array(string()).readonly(),
@@ -18850,7 +19066,10 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
18850
19066
  }), method(RelocateMediaInputSchema, object({ jobId: string() }), {
18851
19067
  kind: "mutation",
18852
19068
  auth: "admin"
18853
- }), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(object({}), array(RelocateJobSchema).readonly(), {
19069
+ }), method(object({}), UnstampedEventMediaCountSchema, { auth: "admin" }), method(RelocatableMediaCountInputSchema, RelocatableMediaCountSchema, {
19070
+ kind: "query",
19071
+ auth: "admin"
19072
+ }), method(object({}), array(RelocateJobSchema).readonly(), {
18854
19073
  kind: "query",
18855
19074
  auth: "admin"
18856
19075
  }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
@@ -20809,6 +21028,9 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
20809
21028
  }), method(object({ jobId: string().optional() }), StorageMigrationJobSchema.nullable(), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
20810
21029
  kind: "mutation",
20811
21030
  auth: "admin"
21031
+ }), method(object({}), array(StorageMigrationMoverSchema).readonly(), { auth: "admin" }), method(object({}), array(StorageMigrationResidueSchema).readonly(), { auth: "admin" }), method(StorageMigrationDrainInputSchema, object({ jobId: string() }), {
21032
+ kind: "mutation",
21033
+ auth: "admin"
20812
21034
  });
20813
21035
  var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
20814
21036
  providerId: string().min(1),
@@ -21207,12 +21429,38 @@ response: record(string(), unknown()) }), object({
21207
21429
  *
21208
21430
  * ## Why this is a capability and not a helper
21209
21431
  *
21210
- * Six stores in `addon-post-analysis` already hold vectors object CLIP, face,
21211
- * plate, vehicle, identity, and the event store's derivativesand every one of
21212
- * them keeps its vectors in a `JSON` settings-store column and ranks them by
21213
- * brute-force cosine in JS. Measured on the live hub that costs ~11.7 KB per row
21214
- * (512 floats as TEXT, `JSON.parse`d on every search) and made semantic search
21215
- * load 5,000 rows before ranking anything.
21432
+ * This capability was introduced with the claim that SIX stores in
21433
+ * `addon-post-analysis` held vectors in a `JSON` settings-store columnobject
21434
+ * CLIP, face, plate, vehicle, identity, and the event store's derivatives. That
21435
+ * claim was never true, and leaving it here made five stores look like pending
21436
+ * work when three of them have no vector at all. Counted column by column on
21437
+ * 2026-08-30, exactly THREE ever held one:
21438
+ *
21439
+ * - `object-clip` — 512-dim CLIP image embedding, migrated 2026-08-06.
21440
+ * - `faces.embedding` — 512-dim ArcFace face embedding, migrated 2026-08-30.
21441
+ * - `identity-samples.embedding` — the same ArcFace vector for an ENROLLED
21442
+ * face, migrated 2026-08-30 into its OWN index (see below).
21443
+ *
21444
+ * `plates` and `vehicle-samples` store a plate STRING and a score; `vehicles`
21445
+ * and `identities` store a name; the event store stores no derivative vector.
21446
+ * They are not migration candidates and never were.
21447
+ *
21448
+ * Measured on the live hub the JSON encoding cost ~11.7 KB per row (512 floats
21449
+ * as TEXT, `JSON.parse`d on every search) and made semantic search load 5,000
21450
+ * rows before ranking anything.
21451
+ *
21452
+ * ## One index per COMPARISON, never per encoder
21453
+ *
21454
+ * `faces` and `identity-samples` hold the same 512 ArcFace dims from the same
21455
+ * model, and they still get two indexes. An index is a set of things that are
21456
+ * ranked against each other and that live and die together, and these two are
21457
+ * neither: a `faces` row is TRACK-OWNED and cascades away with its track under
21458
+ * a per-camera capacity cap, an `identity-samples` row is retention-EXEMPT
21459
+ * forever and is the gallery every recognition ranks against. One index would
21460
+ * mean every gallery load and every reconcile carried a filter whose failure
21461
+ * mode is either ranking a candidate against itself or reclaiming an enrolled
21462
+ * person's only sample. The dimension they share is not a reason to share an
21463
+ * index; the question they answer is, and it differs.
21216
21464
  *
21217
21465
  * The fix is not a faster loop, it is a different backend — and the backend
21218
21466
  * should be replaceable without touching six callers. So: a singleton
@@ -21317,7 +21565,20 @@ var VectorQueryResultSchema = object({
21317
21565
  */
21318
21566
  scanned: number(),
21319
21567
  /** True when the backend could not consider every row that passed the filter. */
21320
- truncated: boolean()
21568
+ truncated: boolean(),
21569
+ /**
21570
+ * The `topK` the backend actually ran with.
21571
+ *
21572
+ * Every backend has a ceiling — sqlite-vec's is 4,096 — and a caller asking
21573
+ * past it used to learn nothing but a boolean, from a WARN in the provider's
21574
+ * own log rather than in its answer. That is how an audit asking for 20,000
21575
+ * consumed 4,096 and reported `examined: 4096` as if it had walked the index,
21576
+ * for weeks. `truncated` says THAT the answer was short; this says BY HOW
21577
+ * MUCH, in the return value, where the caller cannot fail to see it.
21578
+ *
21579
+ * Equals the requested `topK` whenever nothing was lowered.
21580
+ */
21581
+ effectiveTopK: number().int().positive()
21321
21582
  });
21322
21583
  var VectorDeleteInputSchema = object({
21323
21584
  index: string(),
@@ -21346,6 +21607,68 @@ var VectorGetResultSchema = object({ items: array(object({
21346
21607
  id: string(),
21347
21608
  metadata: VectorMetadataSchema
21348
21609
  })) });
21610
+ /**
21611
+ * Ids to read back WITH their vectors.
21612
+ *
21613
+ * The sibling of {@link VectorGetResultSchema}, and deliberately a separate
21614
+ * method rather than a flag on it: `getByIds` promises no vectors and its one
21615
+ * caller depends on that promise. This one promises the opposite.
21616
+ *
21617
+ * It exists because a store cannot put its vectors here otherwise. An ArcFace
21618
+ * gallery is ranked IN PROCESS, per detection, against every enrolled sample —
21619
+ * a per-face cross-process KNN would be a network round trip inside the
21620
+ * recognition loop. So the gallery is loaded once and held in RAM, and loading
21621
+ * it requires the index to hand the floats back. Without this method the only
21622
+ * way to keep a readable vector is a JSON column, which is the thing this
21623
+ * capability exists to delete.
21624
+ *
21625
+ * BOUNDED BY THE CALLER: ids are named, never "everything". Enumerating an
21626
+ * index is {@link VectorScanInputSchema}'s job, and it returns no vectors.
21627
+ */
21628
+ var VectorFetchInputSchema = object({
21629
+ index: string(),
21630
+ ids: array(string())
21631
+ });
21632
+ var VectorFetchResultSchema = object({ items: array(object({
21633
+ id: string(),
21634
+ /** base64 Float32LE — the same wire form `upsert` accepts. */
21635
+ vector: string(),
21636
+ metadata: VectorMetadataSchema
21637
+ })) });
21638
+ /**
21639
+ * ENUMERATE an index: one page of rows in a stable order, no ranking.
21640
+ *
21641
+ * A reconcile does not want the nearest rows, it wants ALL of them, and asking
21642
+ * a KNN for "all" is the wrong question twice over. It hits the backend's `k`
21643
+ * ceiling — 4,096 on sqlite-vec against a 22,128-row index — and it needs a
21644
+ * probe vector it does not have, so the audit passed a ZERO vector whose cosine
21645
+ * distance to every row is degenerate. `examined: 4096` then read as "we
21646
+ * looked" for as long as anyone cared to read it.
21647
+ *
21648
+ * This is the primitive that question actually needs: a bounded page, ordered
21649
+ * by the backend's own row order, costing no distance computation at all.
21650
+ * Vectors are NOT returned — an enumeration that shipped 2 KB per row would be
21651
+ * the full-table read this capability was built to stop.
21652
+ */
21653
+ var VectorScanInputSchema = object({
21654
+ index: string(),
21655
+ /** Opaque resume point. `0` starts at the top; pass back `nextCursor`. */
21656
+ cursor: number().int().nonnegative().default(0),
21657
+ limit: number().int().positive()
21658
+ });
21659
+ var VectorScanResultSchema = object({
21660
+ items: array(object({
21661
+ id: string(),
21662
+ metadata: VectorMetadataSchema
21663
+ })),
21664
+ /**
21665
+ * Where the next page starts, or `null` when the walk reached the end.
21666
+ *
21667
+ * `null` is the ONLY end-of-index signal. A caller must not infer the end
21668
+ * from a short page: a backend is free to return fewer rows than asked.
21669
+ */
21670
+ nextCursor: number().int().nonnegative().nullable()
21671
+ });
21349
21672
  var VectorStatsInputSchema = object({ index: string() });
21350
21673
  var VectorStatsResultSchema = object({
21351
21674
  /** Provider id, so an operator can tell brute force from an ANN index. */
@@ -21364,7 +21687,7 @@ method(VectorDeclareIndexInputSchema, _void(), {
21364
21687
  }), method(VectorUpsertInputSchema, VectorUpsertResultSchema, {
21365
21688
  kind: "mutation",
21366
21689
  auth: "admin"
21367
- }), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
21690
+ }), method(VectorQueryInputSchema, VectorQueryResultSchema, { auth: "admin" }), method(VectorGetInputSchema, VectorGetResultSchema, { auth: "admin" }), method(VectorFetchInputSchema, VectorFetchResultSchema, { auth: "admin" }), method(VectorScanInputSchema, VectorScanResultSchema, { auth: "admin" }), method(VectorDeleteInputSchema, VectorDeleteResultSchema, {
21368
21691
  kind: "mutation",
21369
21692
  auth: "admin"
21370
21693
  }), method(VectorDeleteByFilterInputSchema, VectorDeleteResultSchema, {
@@ -26268,6 +26591,9 @@ method(object({
26268
26591
  }), method(object({}), array(RelocateJobSchema).readonly(), {
26269
26592
  kind: "query",
26270
26593
  auth: "admin"
26594
+ }), method(RelocateResidueInputSchema, RelocateResidueSchema, {
26595
+ kind: "query",
26596
+ auth: "admin"
26271
26597
  }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
26272
26598
  kind: "mutation",
26273
26599
  auth: "admin"
@@ -31233,6 +31559,12 @@ Object.freeze({
31233
31559
  addonId: null,
31234
31560
  access: "create"
31235
31561
  },
31562
+ "pipelineAnalytics.countRelocatableMedia": {
31563
+ capName: "pipeline-analytics",
31564
+ capScope: "device",
31565
+ addonId: null,
31566
+ access: "view"
31567
+ },
31236
31568
  "pipelineAnalytics.countUnstampedEventMedia": {
31237
31569
  capName: "pipeline-analytics",
31238
31570
  capScope: "device",
@@ -32397,6 +32729,12 @@ Object.freeze({
32397
32729
  addonId: null,
32398
32730
  access: "view"
32399
32731
  },
32732
+ "recording.getRelocateResidue": {
32733
+ capName: "recording",
32734
+ capScope: "system",
32735
+ addonId: null,
32736
+ access: "view"
32737
+ },
32400
32738
  "recording.getStorageMigrationMoveStatus": {
32401
32739
  capName: "recording",
32402
32740
  capScope: "system",
@@ -32943,12 +33281,30 @@ Object.freeze({
32943
33281
  addonId: null,
32944
33282
  access: "create"
32945
33283
  },
33284
+ "storageMigration.drain": {
33285
+ capName: "storage-migration",
33286
+ capScope: "system",
33287
+ addonId: null,
33288
+ access: "create"
33289
+ },
33290
+ "storageMigration.movers": {
33291
+ capName: "storage-migration",
33292
+ capScope: "system",
33293
+ addonId: null,
33294
+ access: "view"
33295
+ },
32946
33296
  "storageMigration.plan": {
32947
33297
  capName: "storage-migration",
32948
33298
  capScope: "system",
32949
33299
  addonId: null,
32950
33300
  access: "view"
32951
33301
  },
33302
+ "storageMigration.residue": {
33303
+ capName: "storage-migration",
33304
+ capScope: "system",
33305
+ addonId: null,
33306
+ access: "view"
33307
+ },
32952
33308
  "storageMigration.start": {
32953
33309
  capName: "storage-migration",
32954
33310
  capScope: "system",
@@ -33783,6 +34139,12 @@ Object.freeze({
33783
34139
  addonId: null,
33784
34140
  access: "delete"
33785
34141
  },
34142
+ "vectorStore.fetchByIds": {
34143
+ capName: "vector-store",
34144
+ capScope: "system",
34145
+ addonId: null,
34146
+ access: "view"
34147
+ },
33786
34148
  "vectorStore.getByIds": {
33787
34149
  capName: "vector-store",
33788
34150
  capScope: "system",
@@ -33795,6 +34157,12 @@ Object.freeze({
33795
34157
  addonId: null,
33796
34158
  access: "view"
33797
34159
  },
34160
+ "vectorStore.scan": {
34161
+ capName: "vector-store",
34162
+ capScope: "system",
34163
+ addonId: null,
34164
+ access: "view"
34165
+ },
33798
34166
  "vectorStore.stats": {
33799
34167
  capName: "vector-store",
33800
34168
  capScope: "system",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@camstack/addon-decoder-nodeav",
3
- "version": "1.2.43",
3
+ "version": "1.2.46",
4
4
  "description": "Standalone in-process node-av decoder addon for CamStack",
5
5
  "keywords": [
6
6
  "camstack",