@camstack/system 1.2.160 → 1.2.161

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 (56) hide show
  1. package/dist/addon-runner.js +1 -1
  2. package/dist/addon-runner.mjs +1 -1
  3. package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.js +1 -1
  4. package/dist/builtins/addon-pages-aggregator/addon-pages-aggregator.addon.mjs +1 -1
  5. package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.js +1 -1
  6. package/dist/builtins/addon-widgets-aggregator/addon-widgets-aggregator.addon.mjs +1 -1
  7. package/dist/builtins/alerts/alerts.addon.js +1 -1
  8. package/dist/builtins/alerts/alerts.addon.mjs +1 -1
  9. package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.js +1 -1
  10. package/dist/builtins/backup-orchestrator/backup-orchestrator.addon.mjs +1 -1
  11. package/dist/builtins/console-logging/index.js +1 -1
  12. package/dist/builtins/console-logging/index.mjs +1 -1
  13. package/dist/builtins/core-blocks/core-blocks.addon.js +1 -1
  14. package/dist/builtins/core-blocks/core-blocks.addon.mjs +1 -1
  15. package/dist/builtins/device-manager/device-manager.addon.js +2 -2
  16. package/dist/builtins/device-manager/device-manager.addon.mjs +2 -2
  17. package/dist/builtins/doorbell/virtual-doorbell.addon.js +1 -1
  18. package/dist/builtins/doorbell/virtual-doorbell.addon.mjs +1 -1
  19. package/dist/builtins/hub-forwarder/index.js +1 -1
  20. package/dist/builtins/hub-forwarder/index.mjs +1 -1
  21. package/dist/builtins/liveness-monitor/liveness-monitor.addon.js +1 -1
  22. package/dist/builtins/liveness-monitor/liveness-monitor.addon.mjs +1 -1
  23. package/dist/builtins/local-auth/local-auth.addon.js +1 -1
  24. package/dist/builtins/local-auth/local-auth.addon.mjs +1 -1
  25. package/dist/builtins/local-network/local-network.addon.js +1 -1
  26. package/dist/builtins/local-network/local-network.addon.mjs +1 -1
  27. package/dist/builtins/loki-logging/index.js +1 -1
  28. package/dist/builtins/loki-logging/index.mjs +1 -1
  29. package/dist/builtins/native-metrics/native-metrics.addon.js +1 -1
  30. package/dist/builtins/native-metrics/native-metrics.addon.mjs +1 -1
  31. package/dist/builtins/platform-probe/index.js +1 -1
  32. package/dist/builtins/platform-probe/index.mjs +1 -1
  33. package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js +1 -1
  34. package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs +1 -1
  35. package/dist/builtins/snapshot/index.js +1 -1
  36. package/dist/builtins/snapshot/index.mjs +1 -1
  37. package/dist/builtins/sqlite-storage/filesystem-storage.addon.js +1 -1
  38. package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs +1 -1
  39. package/dist/builtins/sqlite-storage/sqlite-settings.addon.js +0 -0
  40. package/dist/builtins/sqlite-storage/sqlite-settings.addon.mjs +0 -0
  41. package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js +1 -1
  42. package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs +1 -1
  43. package/dist/builtins/system-config/system-config.addon.js +1 -1
  44. package/dist/builtins/system-config/system-config.addon.mjs +1 -1
  45. package/dist/builtins/winston-logging/index.js +1 -1
  46. package/dist/builtins/winston-logging/index.mjs +1 -1
  47. package/dist/{dist-DKs---Vx.mjs → dist-D4xNBlJM.mjs} +309 -207
  48. package/dist/{dist-CcvXUhHK.js → dist-Keu5TDO7.js} +309 -207
  49. package/dist/index.js +28 -7
  50. package/dist/index.mjs +28 -7
  51. package/dist/kernel/lifecycle/lifecycle-job-engine.d.ts +13 -0
  52. package/dist/{manifest-system-deps-DnoPpLGp.mjs → manifest-system-deps-CiCuev2R.mjs} +1 -1
  53. package/dist/{manifest-system-deps-oJMkWSX-.js → manifest-system-deps-DYv4ZPo2.js} +1 -1
  54. package/dist/{retired-settings-keys-DXZ2xe7C.js → retired-settings-keys-BBohF-eC.js} +1 -1
  55. package/dist/{retired-settings-keys-C3eONTvV.mjs → retired-settings-keys-COQMNlOJ.mjs} +1 -1
  56. package/package.json +1 -1
@@ -11295,6 +11295,133 @@ var embeddingEncoderCapability = {
11295
11295
  }
11296
11296
  };
11297
11297
  /**
11298
+ * `failure-contribution` — the capability an addon reports its OWN losses
11299
+ * through, per camera, with the denominator attached. It stores nothing.
11300
+ *
11301
+ * ## The twin of `load-contribution`, and why it is a twin and not a field
11302
+ *
11303
+ * `load-contribution` answers *what did this camera COST*. This answers *what
11304
+ * did this camera LOSE*. The reporting discipline is identical and deliberately
11305
+ * copied: the contributor reports what it already knows, hub-main adds only
11306
+ * `addonId`, nothing needs global knowledge, and there is no central list for
11307
+ * somebody to forget to edit.
11308
+ *
11309
+ * They are not merged, because their invariants are opposites:
11310
+ *
11311
+ * - a `load-contribution` measurement is **absent, never zero** — a zero would
11312
+ * claim a camera cost nothing, which is a measurement nobody made;
11313
+ * - a `failure-contribution` zero is the **most valuable value on the
11314
+ * surface** — `attempts: 400, succeeded: 400` is the proof a fix landed,
11315
+ * and it is exactly what an absent entry cannot say.
11316
+ *
11317
+ * Putting a loss counter on a cost entry would also break the reconciliation
11318
+ * that gives `load-contribution` its point: contributions are subtracted from
11319
+ * `metrics.node-processes-snapshot` to find processes nobody claims. A failure
11320
+ * has no process.
11321
+ *
11322
+ * ## Why not a log line, since the counters already exist
11323
+ *
11324
+ * Several of these paths already counted themselves — `CaptureScheduler`'s
11325
+ * per-device window, `KeyFrameCaptureLog`, `bumpCropMetric`. Every one of them
11326
+ * ends in a log line, and a log line is the thing the operator asked to stop
11327
+ * needing: *"possiamo armare questi errori intanto? Così al prossimo giro
11328
+ * ricontrolliamo tutti questi punti"*. Reading them meant grepping Loki and
11329
+ * hand-correlating timestamps, which is how a 22% thumbnail gap and a 3-hour
11330
+ * media blackout were both diagnosed. The counters stay; this is where they can
11331
+ * be READ.
11332
+ *
11333
+ * ## The rate is served with its denominator or not at all
11334
+ *
11335
+ * Every entry carries `attempts` and `succeeded`. A miss count alone is
11336
+ * unreadable: on 2026-08-28 the enrichment-crop miss count read as "35x worse
11337
+ * than yesterday" and was **flat across twelve hours** once divided by the
11338
+ * successes on the same path. A surface that publishes only the numerator
11339
+ * reproduces that mistake on every read.
11340
+ *
11341
+ * ## Shape
11342
+ *
11343
+ * Copied from `load-contribution.cap.ts` (`mode: 'collection'`,
11344
+ * `internal: true`, `mount: { kind: 'skip' }`): no tRPC route of its own and no
11345
+ * generated hooks, while `addons.listCapabilityProviders` still enumerates it
11346
+ * and the hub's `CapabilityRegistry` still holds an RPC proxy per provider — so
11347
+ * a forked runner's entries reach hub-main over transport that already exists.
11348
+ * No new UDS message, no second registry (D3). The operator reads the assembled
11349
+ * result through `system.getFailureContributions`.
11350
+ */
11351
+ var FailureReasonCountSchema = z.object({
11352
+ /**
11353
+ * Why the attempt did not land, in the contributor's own vocabulary —
11354
+ * `worker-lease-gone`, `queue-overflow`, `timeout`, `empty-read`. The same
11355
+ * strings that already appear in this repo's logs and, where one exists, the
11356
+ * same string the per-track `previewMissReason` records (D276): a second
11357
+ * vocabulary for the same loss would make the row and the counter
11358
+ * un-joinable.
11359
+ */
11360
+ reason: z.string(),
11361
+ count: z.number().int().nonnegative()
11362
+ });
11363
+ var FailureContributionSchema = z.object({
11364
+ /**
11365
+ * The failing path — `enrichment-crop`, `inference`, `plate-ocr`,
11366
+ * `person-over-vehicle`. Free text, for the reason `load-contribution` keeps
11367
+ * `unit` free: the families are owned by different addons and a shared enum
11368
+ * is a central list that rots invisibly.
11369
+ */
11370
+ family: z.string(),
11371
+ /**
11372
+ * The NUMERIC device id — the same value every log line carries as
11373
+ * `tags.deviceId`. Never nullable and never absent: a contributor that
11374
+ * cannot name the camera must not emit the entry, because a fleet total
11375
+ * cannot answer the only question anybody asks of this surface.
11376
+ */
11377
+ deviceId: z.number().int().positive(),
11378
+ /**
11379
+ * A second dimension inside the family: the model / step id for an inference
11380
+ * timeout, so "which camera AND which model" is one read. Absent when the
11381
+ * family has a single variant.
11382
+ */
11383
+ variant: z.string().optional(),
11384
+ /**
11385
+ * Epoch ms this counter started — the INCARNATION MARKER. A consumer
11386
+ * differencing two reads must drop the interval when it changes, because the
11387
+ * counter restarted from zero in a respawned runner. Same discipline as
11388
+ * `LoadContribution.startedAtMs`.
11389
+ */
11390
+ sinceMs: z.number(),
11391
+ /** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
11392
+ atMs: z.number(),
11393
+ /**
11394
+ * THE DENOMINATOR — every attempt on this path for this camera in the
11395
+ * window. A failure count published without it is the mistake this schema
11396
+ * exists to make impossible.
11397
+ */
11398
+ attempts: z.number().int().nonnegative(),
11399
+ /** Attempts that landed. `attempts - succeeded` is the loss. */
11400
+ succeeded: z.number().int().nonnegative(),
11401
+ /** The loss, partitioned. Sums to `attempts - succeeded`. */
11402
+ reasons: z.array(FailureReasonCountSchema).readonly()
11403
+ });
11404
+ var failureContributionCapability = {
11405
+ name: "failure-contribution",
11406
+ scope: "system",
11407
+ mode: "collection",
11408
+ internal: true,
11409
+ methods: {
11410
+ /**
11411
+ * This addon's per-camera failure counters, read live from bounded in-RAM
11412
+ * state it already keeps. Inert: no persistence, no sampling, no timer.
11413
+ *
11414
+ * READING NEVER RESETS. The counters are CUMULATIVE since `sinceMs`, and a
11415
+ * consumer that wants a rate differences two reads. A draining read would
11416
+ * make two operators with the page open each destroy half of the other's
11417
+ * numbers, and `load-contribution` already settled the same question the
11418
+ * same way for `cpuSeconds`.
11419
+ */
11420
+ list: method(z.void(), z.array(FailureContributionSchema).readonly()) },
11421
+ /** In-process only — enumerated through `addons.listCapabilityProviders`. */
11422
+ mount: { kind: "skip" }
11423
+ };
11424
+ /**
11298
11425
  * filesystem-browse — per-node capability for browsing the node's local
11299
11426
  * filesystem. Reads are unconfined (whole filesystem, from `/` down); WRITES
11300
11427
  * are sandboxed to operator-configured allowed roots (D115). Used by the
@@ -11907,6 +12034,82 @@ var llmCapability = {
11907
12034
  })
11908
12035
  }
11909
12036
  };
12037
+ var LoadContributionSchema = z.object({
12038
+ role: z.enum([
12039
+ "decode",
12040
+ "transcode",
12041
+ "recording",
12042
+ "streaming",
12043
+ "detection"
12044
+ ]),
12045
+ /**
12046
+ * The NUMERIC device id — the same value every log line carries as
12047
+ * `tags.deviceId`. `null` means this cost genuinely belongs to no single
12048
+ * camera (a shared pool), NOT that the contributor forgot to look it up: a
12049
+ * contributor that cannot name its camera must not emit the entry at all,
12050
+ * because an unnamed per-camera entry is indistinguishable from a shared one
12051
+ * and would quietly turn one camera's cost into everybody's.
12052
+ */
12053
+ deviceId: z.number().int().positive().nullable(),
12054
+ attribution: z.enum([
12055
+ "measured",
12056
+ "accounted",
12057
+ "unattributable"
12058
+ ]),
12059
+ /**
12060
+ * What ONE entry is, in the contributor's own words — `615/high`,
12061
+ * `617/native`, `cuda:0 shared pool`. Free text because the unit differs per
12062
+ * family and inventing a common one would lose the only information that
12063
+ * makes two entries for the same camera distinguishable.
12064
+ */
12065
+ unit: z.string(),
12066
+ /**
12067
+ * The OS process this cost lives in, when there is one. Present so a
12068
+ * consumer can (a) tell two generations of the same unit apart across a
12069
+ * restart, and (b) subtract claimed processes from the node's process
12070
+ * snapshot to see what NOBODY claimed. Absent for an entry that owns no
12071
+ * process of its own.
12072
+ */
12073
+ pid: z.number().int().positive().optional(),
12074
+ /**
12075
+ * When this generation started. The pid's incarnation marker: a consumer
12076
+ * differencing {@link LoadContributionSchema.shape.cpuSeconds} must drop the
12077
+ * window when this changes, because the counter restarted from zero in a new
12078
+ * process.
12079
+ */
12080
+ startedAtMs: z.number().optional(),
12081
+ /**
12082
+ * CUMULATIVE CPU seconds this unit has consumed since it started — user +
12083
+ * system, read from the child's own `/proc/<pid>/stat` at the moment the
12084
+ * contribution is asked for.
12085
+ *
12086
+ * Cumulative and not a rate on purpose: a rate needs a window, a window
12087
+ * needs a sampler, and a new per-node sampler is the defect half of
12088
+ * `docs/architecture/load-ledger.md` documents. A counter can be differenced
12089
+ * by whoever already keeps a history; a rate cannot be un-averaged.
12090
+ *
12091
+ * Absent — never zero — on a node with no `/proc`, on a read failure, and on
12092
+ * an entry with no process.
12093
+ */
12094
+ cpuSeconds: z.number().optional(),
12095
+ /** Resident bytes of this unit's process, same source and same rules. */
12096
+ rssBytes: z.number().optional()
12097
+ });
12098
+ var loadContributionCapability = {
12099
+ name: "load-contribution",
12100
+ scope: "system",
12101
+ mode: "collection",
12102
+ internal: true,
12103
+ methods: {
12104
+ /**
12105
+ * This addon's own cost entries, computed live from state it already
12106
+ * holds. Inert: no persistence, no sampling, no timer. It is answered on
12107
+ * whatever beat the caller already has.
12108
+ */
12109
+ list: method(z.void(), z.array(LoadContributionSchema).readonly()) },
12110
+ /** In-process only — enumerated through `addons.listCapabilityProviders`. */
12111
+ mount: { kind: "skip" }
12112
+ };
11910
12113
  /**
11911
12114
  * `log-channels` — the capability an addon DECLARES its diagnostic channels
11912
12115
  * through. It stores nothing.
@@ -12015,209 +12218,6 @@ var logDestinationCapability = {
12015
12218
  mount: { kind: "skip" }
12016
12219
  };
12017
12220
  /**
12018
- * `failure-contribution` — the capability an addon reports its OWN losses
12019
- * through, per camera, with the denominator attached. It stores nothing.
12020
- *
12021
- * ## The twin of `load-contribution`, and why it is a twin and not a field
12022
- *
12023
- * `load-contribution` answers *what did this camera COST*. This answers *what
12024
- * did this camera LOSE*. The reporting discipline is identical and deliberately
12025
- * copied: the contributor reports what it already knows, hub-main adds only
12026
- * `addonId`, nothing needs global knowledge, and there is no central list for
12027
- * somebody to forget to edit.
12028
- *
12029
- * They are not merged, because their invariants are opposites:
12030
- *
12031
- * - a `load-contribution` measurement is **absent, never zero** — a zero would
12032
- * claim a camera cost nothing, which is a measurement nobody made;
12033
- * - a `failure-contribution` zero is the **most valuable value on the
12034
- * surface** — `attempts: 400, succeeded: 400` is the proof a fix landed,
12035
- * and it is exactly what an absent entry cannot say.
12036
- *
12037
- * Putting a loss counter on a cost entry would also break the reconciliation
12038
- * that gives `load-contribution` its point: contributions are subtracted from
12039
- * `metrics.node-processes-snapshot` to find processes nobody claims. A failure
12040
- * has no process.
12041
- *
12042
- * ## Why not a log line, since the counters already exist
12043
- *
12044
- * Several of these paths already counted themselves — `CaptureScheduler`'s
12045
- * per-device window, `KeyFrameCaptureLog`, `bumpCropMetric`. Every one of them
12046
- * ends in a log line, and a log line is the thing the operator asked to stop
12047
- * needing: *"possiamo armare questi errori intanto? Così al prossimo giro
12048
- * ricontrolliamo tutti questi punti"*. Reading them meant grepping Loki and
12049
- * hand-correlating timestamps, which is how a 22% thumbnail gap and a 3-hour
12050
- * media blackout were both diagnosed. The counters stay; this is where they can
12051
- * be READ.
12052
- *
12053
- * ## The rate is served with its denominator or not at all
12054
- *
12055
- * Every entry carries `attempts` and `succeeded`. A miss count alone is
12056
- * unreadable: on 2026-08-28 the enrichment-crop miss count read as "35x worse
12057
- * than yesterday" and was **flat across twelve hours** once divided by the
12058
- * successes on the same path. A surface that publishes only the numerator
12059
- * reproduces that mistake on every read.
12060
- *
12061
- * ## Shape
12062
- *
12063
- * Copied from `load-contribution.cap.ts` (`mode: 'collection'`,
12064
- * `internal: true`, `mount: { kind: 'skip' }`): no tRPC route of its own and no
12065
- * generated hooks, while `addons.listCapabilityProviders` still enumerates it
12066
- * and the hub's `CapabilityRegistry` still holds an RPC proxy per provider — so
12067
- * a forked runner's entries reach hub-main over transport that already exists.
12068
- * No new UDS message, no second registry (D3). The operator reads the assembled
12069
- * result through `system.getFailureContributions`.
12070
- */
12071
- var FailureReasonCountSchema = z.object({
12072
- /**
12073
- * Why the attempt did not land, in the contributor's own vocabulary —
12074
- * `worker-lease-gone`, `queue-overflow`, `timeout`, `empty-read`. The same
12075
- * strings that already appear in this repo's logs and, where one exists, the
12076
- * same string the per-track `previewMissReason` records (D276): a second
12077
- * vocabulary for the same loss would make the row and the counter
12078
- * un-joinable.
12079
- */
12080
- reason: z.string(),
12081
- count: z.number().int().nonnegative()
12082
- });
12083
- var FailureContributionSchema = z.object({
12084
- /**
12085
- * The failing path — `enrichment-crop`, `inference`, `plate-ocr`,
12086
- * `person-over-vehicle`. Free text, for the reason `load-contribution` keeps
12087
- * `unit` free: the families are owned by different addons and a shared enum
12088
- * is a central list that rots invisibly.
12089
- */
12090
- family: z.string(),
12091
- /**
12092
- * The NUMERIC device id — the same value every log line carries as
12093
- * `tags.deviceId`. Never nullable and never absent: a contributor that
12094
- * cannot name the camera must not emit the entry, because a fleet total
12095
- * cannot answer the only question anybody asks of this surface.
12096
- */
12097
- deviceId: z.number().int().positive(),
12098
- /**
12099
- * A second dimension inside the family: the model / step id for an inference
12100
- * timeout, so "which camera AND which model" is one read. Absent when the
12101
- * family has a single variant.
12102
- */
12103
- variant: z.string().optional(),
12104
- /**
12105
- * Epoch ms this counter started — the INCARNATION MARKER. A consumer
12106
- * differencing two reads must drop the interval when it changes, because the
12107
- * counter restarted from zero in a respawned runner. Same discipline as
12108
- * `LoadContribution.startedAtMs`.
12109
- */
12110
- sinceMs: z.number(),
12111
- /** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
12112
- atMs: z.number(),
12113
- /**
12114
- * THE DENOMINATOR — every attempt on this path for this camera in the
12115
- * window. A failure count published without it is the mistake this schema
12116
- * exists to make impossible.
12117
- */
12118
- attempts: z.number().int().nonnegative(),
12119
- /** Attempts that landed. `attempts - succeeded` is the loss. */
12120
- succeeded: z.number().int().nonnegative(),
12121
- /** The loss, partitioned. Sums to `attempts - succeeded`. */
12122
- reasons: z.array(FailureReasonCountSchema).readonly()
12123
- });
12124
- var failureContributionCapability = {
12125
- name: "failure-contribution",
12126
- scope: "system",
12127
- mode: "collection",
12128
- internal: true,
12129
- methods: {
12130
- /**
12131
- * This addon's per-camera failure counters, read live from bounded in-RAM
12132
- * state it already keeps. Inert: no persistence, no sampling, no timer.
12133
- *
12134
- * READING NEVER RESETS. The counters are CUMULATIVE since `sinceMs`, and a
12135
- * consumer that wants a rate differences two reads. A draining read would
12136
- * make two operators with the page open each destroy half of the other's
12137
- * numbers, and `load-contribution` already settled the same question the
12138
- * same way for `cpuSeconds`.
12139
- */
12140
- list: method(z.void(), z.array(FailureContributionSchema).readonly()) },
12141
- /** In-process only — enumerated through `addons.listCapabilityProviders`. */
12142
- mount: { kind: "skip" }
12143
- };
12144
- var LoadContributionSchema = z.object({
12145
- role: z.enum([
12146
- "decode",
12147
- "transcode",
12148
- "recording",
12149
- "streaming",
12150
- "detection"
12151
- ]),
12152
- /**
12153
- * The NUMERIC device id — the same value every log line carries as
12154
- * `tags.deviceId`. `null` means this cost genuinely belongs to no single
12155
- * camera (a shared pool), NOT that the contributor forgot to look it up: a
12156
- * contributor that cannot name its camera must not emit the entry at all,
12157
- * because an unnamed per-camera entry is indistinguishable from a shared one
12158
- * and would quietly turn one camera's cost into everybody's.
12159
- */
12160
- deviceId: z.number().int().positive().nullable(),
12161
- attribution: z.enum([
12162
- "measured",
12163
- "accounted",
12164
- "unattributable"
12165
- ]),
12166
- /**
12167
- * What ONE entry is, in the contributor's own words — `615/high`,
12168
- * `617/native`, `cuda:0 shared pool`. Free text because the unit differs per
12169
- * family and inventing a common one would lose the only information that
12170
- * makes two entries for the same camera distinguishable.
12171
- */
12172
- unit: z.string(),
12173
- /**
12174
- * The OS process this cost lives in, when there is one. Present so a
12175
- * consumer can (a) tell two generations of the same unit apart across a
12176
- * restart, and (b) subtract claimed processes from the node's process
12177
- * snapshot to see what NOBODY claimed. Absent for an entry that owns no
12178
- * process of its own.
12179
- */
12180
- pid: z.number().int().positive().optional(),
12181
- /**
12182
- * When this generation started. The pid's incarnation marker: a consumer
12183
- * differencing {@link LoadContributionSchema.shape.cpuSeconds} must drop the
12184
- * window when this changes, because the counter restarted from zero in a new
12185
- * process.
12186
- */
12187
- startedAtMs: z.number().optional(),
12188
- /**
12189
- * CUMULATIVE CPU seconds this unit has consumed since it started — user +
12190
- * system, read from the child's own `/proc/<pid>/stat` at the moment the
12191
- * contribution is asked for.
12192
- *
12193
- * Cumulative and not a rate on purpose: a rate needs a window, a window
12194
- * needs a sampler, and a new per-node sampler is the defect half of
12195
- * `docs/architecture/load-ledger.md` documents. A counter can be differenced
12196
- * by whoever already keeps a history; a rate cannot be un-averaged.
12197
- *
12198
- * Absent — never zero — on a node with no `/proc`, on a read failure, and on
12199
- * an entry with no process.
12200
- */
12201
- cpuSeconds: z.number().optional(),
12202
- /** Resident bytes of this unit's process, same source and same rules. */
12203
- rssBytes: z.number().optional()
12204
- });
12205
- var loadContributionCapability = {
12206
- name: "load-contribution",
12207
- scope: "system",
12208
- mode: "collection",
12209
- internal: true,
12210
- methods: {
12211
- /**
12212
- * This addon's own cost entries, computed live from state it already
12213
- * holds. Inert: no persistence, no sampling, no timer. It is answered on
12214
- * whatever beat the caller already has.
12215
- */
12216
- list: method(z.void(), z.array(LoadContributionSchema).readonly()) },
12217
- /** In-process only — enumerated through `addons.listCapabilityProviders`. */
12218
- mount: { kind: "skip" }
12219
- };
12220
- /**
12221
12221
  * `login-method` — collection cap through which auth addons contribute
12222
12222
  * their pre-auth login surfaces to the login page. This is the SINGLE,
12223
12223
  * generic mechanism that supersedes the dead `auth.listProviders` reader:
@@ -17469,12 +17469,53 @@ var MediaFileKindEnum = z.enum([
17469
17469
  "keyFrameSmall",
17470
17470
  "thumbnailSmall"
17471
17471
  ]);
17472
+ /**
17473
+ * One media row ON THE WIRE: what it is, how big it is, and WHERE ITS BYTES
17474
+ * ARE — never the bytes themselves.
17475
+ *
17476
+ * ## Why `url` and not `base64`
17477
+ *
17478
+ * Measured on the live hub 2026-08-30: `getTrackMedia {trackId, deviceId}`
17479
+ * with no `kinds` returned 6 rows / **3 597 219 B**, of which `keyFrame` alone
17480
+ * was **2 824 077 B** — one full-resolution frame, base64, so +33 % on the
17481
+ * wire. Forty events is ~144 MB. Every byte of it was read off disk,
17482
+ * base64-encoded, held whole in a unary tRPC envelope, and materialised in
17483
+ * hub-main's heap on the way past — for an `<img>` that would have cached it.
17484
+ *
17485
+ * `url` points at the `event-media` data plane
17486
+ * (`/addon/<addonId>/event-media/<storedKey>`), which serves the same blob
17487
+ * with an ETag and `Cache-Control: immutable`, honours conditional GETs, can
17488
+ * render a `?variant=thumb`, and streams. The hub gate in front of it requires
17489
+ * a bearer or the session cookie (`access: 'authenticated'`), so the bytes are
17490
+ * no less protected than they were inside a `view`-level cap response — see
17491
+ * `data-plane-access.ts` for the rule and the one gap it does not close
17492
+ * (per-device scoping).
17493
+ *
17494
+ * The URL is built from the row's **stored** key, which is not always its
17495
+ * published `kind`: a track's face/plate crop is stored as `crop` under
17496
+ * `('face'|'plate', '<prefix>-<trackId>')` and published as
17497
+ * `faceCrop`/`plateCrop`. `MediaStore.getByKey` knows only the stored key.
17498
+ *
17499
+ * ## `base64` is TRANSITIONAL and is going away
17500
+ *
17501
+ * It is still populated for one reason: the deployed viewer's track-detail
17502
+ * HERO tile reads it (`use-track-media-entry.ts` → `parseMediaFiles`, which
17503
+ * REQUIRES the field), and a row without it parses as a FAILED read — the red
17504
+ * triangle — not as absence. Removing the field before that viewer ships is an
17505
+ * outage, not a cleanup. Once the viewer takes its hero bytes from `url`,
17506
+ * delete this line and the `withBytes` pass-through in
17507
+ * `analytics-query-facade.ts`; nothing else reads it.
17508
+ */
17472
17509
  var MediaFileSchema = z.object({
17473
17510
  key: z.string(),
17474
17511
  kind: MediaFileKindEnum,
17475
- base64: z.string(),
17476
17512
  sizeBytes: z.number(),
17477
17513
  timestamp: z.number()
17514
+ }).extend({
17515
+ /** `/addon/<addonId>/event-media/<encoded stored key>`. Always present. */
17516
+ url: z.string(),
17517
+ /** @deprecated Transitional — see the schema docblock. Use {@link url}. */
17518
+ base64: z.string()
17478
17519
  });
17479
17520
  /**
17480
17521
  * One media row WITHOUT its bytes.
@@ -17486,7 +17527,9 @@ var MediaFileSchema = z.object({
17486
17527
  * blocks the whole view.
17487
17528
  *
17488
17529
  * `sizeBytes` is carried because it is what lets a client decide between the
17489
- * stored blob and a `?variant=thumb` rendering without fetching either.
17530
+ * stored blob and a `?variant=thumb` rendering without fetching either, and
17531
+ * `url` because a client that had to build the plane path itself is a second
17532
+ * copy of a route — the embed, the viewer and the admin UI each grew one.
17490
17533
  */
17491
17534
  var MediaFileInfoSchema = MediaFileSchema.omit({ base64: true });
17492
17535
  /**
@@ -18619,6 +18662,26 @@ var pipelineAnalyticsCapability = {
18619
18662
  deviceId: z.number()
18620
18663
  }), z.array(MediaFileInfoSchema).readonly()),
18621
18664
  /**
18665
+ * What media an EVENT has, without any of it — the twin `getEventMedia`
18666
+ * never had.
18667
+ *
18668
+ * `listTrackMedia` above got this treatment because a track's media is
18669
+ * 5-8 MB. An event's is worse per row, not better: an old-style event owns
18670
+ * a `crop` AND a native-resolution `fullFrameBoxed`, and the track DETAIL
18671
+ * modal — the one surface that legitimately shows the big kinds — unions
18672
+ * both listings to build its filmstrip. It then renders every tile from
18673
+ * the `event-media` plane by key and throws the bytes away. Measured on
18674
+ * the live hub: one event's `fullFrameBoxed` is 2 824 077 B, base64'd to
18675
+ * ~3.8 MB, allocated whole in hub-main's heap, for a list of keys.
18676
+ *
18677
+ * Same `deviceId` authorization subject as `getEventMedia`, and the same
18678
+ * rows — this is a projection of that method, never a different question.
18679
+ */
18680
+ listEventMedia: method(z.object({
18681
+ eventId: z.string(),
18682
+ deviceId: z.number()
18683
+ }), z.array(MediaFileInfoSchema).readonly()),
18684
+ /**
18622
18685
  * Search object events by text query using CLIP cosine similarity.
18623
18686
  * Encodes `text` via the `embedding-encoder` cap, queries the
18624
18687
  * `ObjectEmbeddingStore` with optional prefilters, ranks all matching
@@ -25072,10 +25135,24 @@ var FaceClusterSchema = z.object({
25072
25135
  size: z.number().int(),
25073
25136
  cohesion: z.number()
25074
25137
  });
25138
+ /**
25139
+ * One gallery media row: what the crop is, how big it is, and WHERE its bytes
25140
+ * are — never the bytes.
25141
+ *
25142
+ * `base64` was deleted here rather than deprecated. `MediaFile.base64` (the
25143
+ * track/event contract) is still populated because a deployed viewer requires
25144
+ * the field to parse a row at all; this method has no such reader. Its ONE
25145
+ * caller is the admin UI's detail modal, which was building
25146
+ * `data:image/jpeg;base64,…` from a row whose `key` sat right beside it, in a
25147
+ * dialog already rendering its key FRAME from the `event-media` plane.
25148
+ *
25149
+ * `url` is `/addon/<addonId>/event-media/<encoded key>`. The plane resolves a
25150
+ * media key directly, so this needed no new plane and no new access decision.
25151
+ */
25075
25152
  var MediaFileLiteSchema$1 = z.object({
25076
25153
  key: z.string(),
25077
25154
  kind: z.string(),
25078
- base64: z.string(),
25155
+ url: z.string(),
25079
25156
  sizeBytes: z.number(),
25080
25157
  timestamp: z.number()
25081
25158
  });
@@ -28487,10 +28564,24 @@ var PlateInfoSchema = z.object({
28487
28564
  */
28488
28565
  cropUrl: z.string().optional()
28489
28566
  });
28567
+ /**
28568
+ * One gallery media row: what the crop is, how big it is, and WHERE its bytes
28569
+ * are — never the bytes.
28570
+ *
28571
+ * `base64` was deleted here rather than deprecated. `MediaFile.base64` (the
28572
+ * track/event contract) is still populated because a deployed viewer requires
28573
+ * the field to parse a row at all; this method has no such reader. Its ONE
28574
+ * caller is the admin UI's detail modal, which was building
28575
+ * `data:image/jpeg;base64,…` from a row whose `key` sat right beside it, in a
28576
+ * dialog already rendering its key FRAME from the `event-media` plane.
28577
+ *
28578
+ * `url` is `/addon/<addonId>/event-media/<encoded key>`. The plane resolves a
28579
+ * media key directly, so this needed no new plane and no new access decision.
28580
+ */
28490
28581
  var MediaFileLiteSchema = z.object({
28491
28582
  key: z.string(),
28492
28583
  kind: z.string(),
28493
- base64: z.string(),
28584
+ url: z.string(),
28494
28585
  sizeBytes: z.number(),
28495
28586
  timestamp: z.number()
28496
28587
  });
@@ -36832,6 +36923,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
36832
36923
  addonId: null,
36833
36924
  access: "view"
36834
36925
  },
36926
+ "pipelineAnalytics.listEventMedia": {
36927
+ capName: "pipeline-analytics",
36928
+ capScope: "device",
36929
+ addonId: null,
36930
+ access: "view"
36931
+ },
36835
36932
  "pipelineAnalytics.listGroups": {
36836
36933
  capName: "pipeline-analytics",
36837
36934
  capScope: "device",
@@ -40455,6 +40552,11 @@ Object.freeze({
40455
40552
  form: "array",
40456
40553
  optional: false
40457
40554
  }],
40555
+ "pipelineAnalytics.listEventMedia": [{
40556
+ name: "deviceId",
40557
+ form: "single",
40558
+ optional: false
40559
+ }],
40458
40560
  "pipelineAnalytics.listGroups": [{
40459
40561
  name: "deviceIds",
40460
40562
  form: "array",