@camstack/types 1.2.235 → 1.2.237

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-CsgPITp-.js");
+const require_sleep = require("./sleep-Cqxm5OIN.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
 const require_canonical_hash = require("./canonical-hash-CSE4ioRi.js");
 const require_enums = require("./enums.js");
@@ -146,6 +146,20 @@ var EVENT_OWNER_TYPES = [
 * nothing failing until a caller asked.
 */
 var EventOwnerTypeSchema = zod.z.enum(EVENT_OWNER_TYPES);
+/**
+* The owner kinds a media-PRESENCE probe may ask about: the three event tables
+* plus `track`.
+*
+* `videoclips` resolves a clip's still the way `resolveDefaultEventMedia` does
+* — the event's OWN media when it has any, else its owning TRACK's — so the
+* probe needs exactly this union and no more of {@link MediaOwnerType}. Built
+* FROM {@link EVENT_OWNER_TYPES} so a fourth event table reaches the probe the
+* day it is declared, rather than being accepted by one side and refused by the
+* other.
+*/
+var MEDIA_PRESENCE_OWNER_KINDS = [...EVENT_OWNER_TYPES, "track"];
+/** The same list as a Zod enum, for the cap input that carries it. */
+var MediaPresenceOwnerKindSchema = zod.z.enum(MEDIA_PRESENCE_OWNER_KINDS);
 var EVENT_OWNER_TYPE_SET = new Set(EVENT_OWNER_TYPES);
 /** True when this key's owner is one of the three event tables. */
 function isEventOwnerType(ownerType) {
@@ -12939,30 +12953,30 @@ var deviceManagerCapability = {
 		*/
 		getAllBindings: require_sleep.method(zod.z.object({}), zod.z.array(DeviceBindingsForDeviceSchema)),
 		/**
-		* Activate (or deactivate) a wrapper addon — or ONE of its sources — for a
-		* (device, cap) pair.
-		*
-		* Persists the binding via ctx.settings; `active: false` on a SINGLETON cap
-		* clears the wrapper (falling back to native if one is registered). On a
-		* COLLECTION cap it adds to the per-device DENY set instead, and the
-		* wrapper binding is left exactly as it was — a cap with several sources
-		* has no "which one" for `getBindings` to answer (D556).
-		*
-		* `sourceId` is what makes the switch match its label. One addon can serve
-		* several of a device's sources (`addon-provider-reolink` answers a hub
-		* child with `native:reolink:onboard` AND `native:reolink:hub`), so a
-		* toggle keyed by addon would turn off both while saying it turned off one
-		* — the D62 defect with the polarity reversed (D557). Naming the source
-		* denies exactly that source. OMITTING it keeps the cap-wide meaning
-		* D556 shipped: every source this addon serves for this device, which is
-		* also how a deny entry persisted before the re-key is still read.
+		* Activate (or deactivate) a wrapper addon for a (device, cap) pair — the
+		* per-camera function switch's ONE authority (D62).
+		*
+		* SINGLETON capabilities only. Persists the binding via ctx.settings;
+		* `active: false` clears the wrapper (falling back to native if one is
+		* registered) by persisting the explicit `{ wrapperAddonId: null }` marker,
+		* which is what stops `getBindings` re-binding a `defaultActive` wrapper.
+		*
+		* **A COLLECTION capability is REFUSED by name.** It briefly took a
+		* `sourceId` and wrote a per-device DENY set, so one of an addon's several
+		* sources could be switched off without switching off the rest (D556, then
+		* D555's re-key by source). The operator removed the whole idea the same
+		* day: *"tutti i providers funzionano sempre, non serve
+		* disattivarli/attivarli … loro vivono lì"* (D557 amended, third). A
+		* collection cap's providers are a DERIVED set — every addon that provides
+		* the cap for this device type, computed on every read and persisted
+		* nowhere — so there is nothing here to activate, and a verb that accepted
+		* the call could only write a field the enumeration does not read. That is
+		* the D62 shape, and this repo has shipped it four times.
 		*/
 		setWrapperActive: require_sleep.method(zod.z.object({
 			deviceId: zod.z.number(),
 			capName: zod.z.string(),
 			wrapperAddonId: zod.z.string(),
-			/** The `ClipSource.source` id to toggle. Absent = all of the addon's. */
-			sourceId: zod.z.string().optional(),
 			active: zod.z.boolean()
 		}), zod.z.void(), {
 			kind: "mutation",
@@ -22683,6 +22697,35 @@ var pipelineAnalyticsCapability = {
 			deviceId: zod.z.number()
 		}), zod.z.array(MediaFileInfoSchema).readonly()),
 		/**
+		* Which of `ownerIds` hold at least ONE media row — an INDEX read, never a
+		* blob read, and the LICENCE `videoclips` needs to publish a `thumbnail`.
+		*
+		* The event-media URL is stamped from a template for every event in the
+		* system, so "the plane is up" was being served as "there are bytes": 64 of
+		* one camera's 179 clips pointed at a 404 (device 3836, 2026-08-17). This
+		* is the question that turns the stamp into a claim.
+		*
+		* It is on the WIRE because the clip source is registered by the addon that
+		* owns the FOOTAGE, not by this one (D560) — the probe used to be an
+		* in-process `MediaStore` read. One call per OWNER KIND, never one per
+		* owner: that N+1 is what `MediaStore.ownersWithMedia` was written to
+		* prevent, and crossing a process boundary makes it worse, not better.
+		* `ownerIds` is bounded at the same 5 000 the annotation fetch is bounded
+		* at, so one pathological camera-day cannot mint an unbounded request.
+		*
+		* THROWS rather than answering partially. A probe that quietly
+		* under-reports reads as "these owners have nothing" and the caller drops
+		* thumbnails that exist — the opposite failure to the one above, and
+		* equally invisible.
+		*
+		* `deviceId` is the authorization subject, exactly as on `getEventMedia`.
+		*/
+		ownersWithMedia: require_sleep.method(zod.z.object({
+			deviceId: zod.z.number(),
+			ownerKind: MediaPresenceOwnerKindSchema,
+			ownerIds: zod.z.array(zod.z.string()).max(5e3)
+		}), zod.z.array(zod.z.string()).readonly()),
+		/**
 		* Search object events by text query using CLIP cosine similarity.
 		* Encodes `text` via the `embedding-encoder` cap, queries the
 		* `ObjectEmbeddingStore` with optional prefilters, ranks all matching
@@ -27121,25 +27164,34 @@ var vectorStoreCapability = {
 *
 * A device-scoped wrapper COLLECTION (D549 decision 2, D554): every provider a
 * camera has is a SOURCE, and they are listed beside each other — never one
-* substituted for another. The DEFAULT provider (registered by
-* `addon-post-analysis`, `defaultActive: true`) composes the analytics event
-* log (markers + thumbnails) with the recorder's `getPlaybackManifest` — a clip
+* substituted for another, and none of them privileged by name. One source,
+* `analytics`, is registered by the RECORDER — the addon that owns the
+* footage, D560 — and composes the analytics event log (markers + thumbnails,
+* read over `ctx.api`) with the recorder's own `getPlaybackManifest`: a clip
 * is a time-WINDOW over existing footage, never a separate file. A camera that
 * exposes NATIVE onboard clips (Reolink SD card, a hub's storage, HKSV) adds
-* its own catalog ALONGSIDE that one.
+* its own catalog ALONGSIDE that one. (`defaultActive` above is the CAP's
+* auto-bind to cameras, not a ranking among these sources — there is none.)
 *
 * The mount stays per-device (`resolveCapMount` → `device-scoped`), and a
 * device's SOURCES are its BINDINGS: `deviceManager.getBindings(deviceId)` is
 * what says a provider serves this camera, never the set of addons that
 * happen to have registered the capability somewhere in the cluster. That is
 * what stopped one addon appearing three times on 592 — as the device's
-* native provider, as the hub-local registration and as
-* `pipeline-analytics@little-unraid` (D554 amended 2026-09-20).
-*
-* `listClips` is asked of ONE provider at a time
-* ({@link videoclipsCapability.methods.listClips} `provider`), defaulting to
-* the bound one, which is CamStack on every camera today. It is NOT a union
-* over everything a camera has: *"l'utilizzatore è uno solo"*.
+* native provider, as the hub-local registration and as an
+* `<addonId>@<nodeId>` one (D554 amended 2026-09-20).
+*
+* `listClips` is asked of ONE provider at a time, and NAMING it is REQUIRED
+* ({@link videoclipsCapability.methods.listClips} `provider`, D554 amended). It is not
+* a union over everything a camera has: *"l'utilizzatore è uno solo"*. There
+* is no default, because a collection cap's binding set is DERIVED and PLURAL
+* (D554 amended, `getBindings` step 0) — "the bound one" does not exist to
+* resolve to, and the one thing that could take its place is a second
+* authority naming a provider per camera, which D554 decision 3 rejected.
+* The pick is a SURFACE's to make, from the {@link ClipSourceSchema} rows it
+* already holds, and it says which one it made (D569 § 1–3).
+* {@link videoclipsCapability.methods.listSources} is the method that fans out
+* — one row per source, by construction.
 * {@link videoclipsCapability.methods.getClipPlayback} dispatches by the
 * source namespace inside the clip id, which is why ids are self-contained.
 *
@@ -27155,6 +27207,47 @@ var vectorStoreCapability = {
 var MAX_CLIP_EVENT_IDS = 24;
 /** Cap on {@link ClipSchema.labels} — the ribbon row has space for ~3 words. */
 var MAX_CLIP_LABELS = 3;
+/**
+* Every reason a still-mint route may refuse, as a TOKEN — never prose.
+*
+* The route also sends the prose (`x-camstack-reason`), because a firmware's
+* own words are the only thing that explains a `camera-refused`. But the token
+* is what a surface may key a table on, and the code and the prose are
+* separate headers precisely because they had been the same one: the route
+* sent `queue-full: 16 thumbnail mints already waiting for host …` and the
+* surface's table was keyed by `queue-full`, so every refusal on this fleet
+* rendered as `Refused: <prose>`.
+*/
+var ClipStillRefusalCodeSchema = zod.z.enum([
+	"queue-full",
+	"camera-backoff",
+	"sleeping",
+	"camera-refused",
+	"no-keyframe",
+	"no-catalog-row",
+	"unsupported",
+	"unknown-device",
+	"uid-missing"
+]);
+/**
+* Whether a refusal is "not yet" or "never" — decided by the BRANCH that
+* refused and carried on the wire, never inferred by the client from the code.
+*
+* `deferred` means the work is queued or the host is resting: the surface
+* shows LOADING and comes back, under a bound. `final` means no retry can
+* change the answer: the surface shows the reason and stops.
+*
+* A response that carries no disposition is read as `final`, which is exactly
+* how every build before this one behaved — an old provider under a new
+* surface keeps the old, safe behaviour rather than gaining a retry loop.
+*/
+var ClipStillDispositionSchema = zod.z.enum(["deferred", "final"]);
+/** The camera's / provider's own words. Kept verbatim, never parsed. */
+var CLIP_STILL_REASON_HEADER = "x-camstack-reason";
+/** One {@link ClipStillRefusalCodeSchema} token, alone. */
+var CLIP_STILL_REASON_CODE_HEADER = "x-camstack-reason-code";
+/** One {@link ClipStillDispositionSchema} token, alone. */
+var CLIP_STILL_DISPOSITION_HEADER = "x-camstack-disposition";
 var ClipSchema = zod.z.object({
 	/** Opaque, provider-namespaced id. The default provider encodes the time
 	*  window so `getClipPlayback` is self-contained (no event re-query). */
@@ -27305,7 +27398,25 @@ var ClipSchema = zod.z.object({
 	*/
 	playable: zod.z.boolean().optional(),
 	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
-	unplayableReason: zod.z.string().optional()
+	unplayableReason: zod.z.string().optional(),
+	/**
+	* This clip is STILL BEING WRITTEN, so {@link ClipSchema.timeRange}`.endMs`
+	* is not its end.
+	*
+	* Absent — the common case — means the row is closed and its `endMs` is the
+	* end of the recording. Present and `true` means the source told us the file
+	* has no end yet, and the `endMs` we carry is whatever the camera's index
+	* entry happened to hold: on a Reolink E1 Outdoor PoE (592, measured
+	* 2026-09-20) the newest file `…_192927_000000_…_0.mp4` reported an `endTime`
+	* of 19:29:56 and STILL reported it eight minutes later, while the file went
+	* on growing. A surface that drew 29 s there was lying about a clip that
+	* plays for minutes, on the one row the operator looks at first.
+	*
+	* `endMs` is deliberately still a number: it is the best bound anything has
+	* for a mint window or a byte fetch, and every consumer already requires it.
+	* This flag says what it is WORTH, and a duration is not drawn from it.
+	*/
+	inProgress: zod.z.boolean().optional()
 });
 var ClipPlaybackSchema = zod.z.object({
 	/**
@@ -27388,59 +27499,17 @@ var ClipSourceSchema = zod.z.object({
 	* alternative — a `native:reolink:* → provider-reolink` table inside the
 	* widget — is a second authority on provider identity living in the one
 	* package with no business knowing it, wrong the day a third source appears
-	* (D557). One addon may serve SEVERAL sources: `addon-provider-reolink`
-	* answers a hub child with both `native:reolink:onboard` and
-	* `native:reolink:hub`, which is why the per-device switch is keyed by
-	* SOURCE and not by this (D555).
+	* (D557). One addon may serve SEVERAL sources, which is why the per-device
+	* switch is keyed by SOURCE and not by this (D555) — `addon-provider-reolink`
+	* served a hub child two of them until the two views were measured to be one
+	* store read twice (D555) and then read ONE way (D565).
 	*
 	* Optional for version skew only. The collection dispatcher stamps it from
 	* the registry, so a row that travelled through the fan-out carries the
 	* authoritative id whatever the provider filled in.
 	*/
 	addonId: zod.z.string().optional(),
-	/**
-	* Which API this source resolved to FOR THIS CAMERA, when it has a choice.
-	*
-	* A source may cover one store through more than one surface — the Reolink
-	* provider reads a hub child through the parent's event log and a standalone
-	* through its own file list, because that is what each camera answers. The
-	* CHOICE is the provider's, made from what the camera is, and is never a row
-	* the operator has to understand; but it is REPORTED, because a source that
-	* silently reads a different API on two cameras and then behaves differently
-	* is the thing nobody can debug later. Absent when the source has only one
-	* way to read its store.
-	*/
-	via: zod.z.string().optional(),
-	availability: ClipSourceAvailabilitySchema,
-	/**
-	* The operator switched this source OFF for this camera.
-	*
-	* Deliberately NOT a member of {@link ClipSourceAvailabilitySchema}'s
-	* vocabulary. That enum models what the source CAN do — a sleeping camera, an
-	* unmounted card, an index that disagrees with its own calendar — and a
-	* switched-off source could answer perfectly well; the operator decided it
-	* should not. Folding the choice in is how `disabled` and `broken` stop being
-	* distinguishable, which is the D62 rule this repo has already paid for twice:
-	* an off switch is REPORTED off (`CameraStatus.switchedOff`, the same word),
-	* and disabled must never look like broken. It is also what lets every
-	* exhaustive consumer of the availability enum keep compiling.
-	*
-	* A switched-off source contributes NO clips (`listClips` never calls it) and
-	* its row carries no `catalogAsOf`: nothing confirms a catalog it is not
-	* allowed to serve, and a frozen age that can only grow draws a stalling
-	* source rather than an off switch.
-	*
-	* The row survives BECAUSE it is the control the operator switches the source
-	* back on from — D554 decision 4's rule ("a source that cannot answer
-	* produces a ROW, not an absence") applied to the one case D556 carved out of
-	* it, and D557's own kept property ("a source is never hidden, only its
-	* rows"). Absent means on.
-	*
-	* A provider never sets this — like {@link ClipSourceSchema.addonId} it is
-	* stamped by the collection dispatcher, which holds the registry's projection
-	* of the persisted authority (D556) and is the only place that knows it.
-	*/
-	switchedOff: zod.z.boolean().optional()
+	availability: ClipSourceAvailabilitySchema
 });
 var videoclipsCapability = {
 	name: "videoclips",
@@ -27494,22 +27563,40 @@ var videoclipsCapability = {
 			limit: zod.z.number().int().positive().optional(),
 			/**
 			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-			* carries, never a source id and never a list.
+			* carries, never a source id and never a list. **Required** (D554 amended).
+			*
+			* A provider the device is not bound to is refused by name rather than
+			* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+			*
+			* It was optional, documented as "absent means the device's BOUND
+			* provider, which is CamStack on every camera". No code implemented
+			* that. Measured on the live hub 2026-09-20 — device 592, bound to
+			* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+			* answered SIX rows, three from each source, merged newest-first:
+			* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+			* so absence bought the union this method exists not to be, and
+			* `limit` meant `limit × sources`.
 			*
-			* Absent means the device's BOUND provider, which is CamStack on every
-			* camera today because that is what `deviceManager.getBindings`
-			* answers with. A provider the device is not bound to is refused by
-			* name rather than answered by another one (D552's
-			* `rejectUnresolvedAddonPin` rule).
+			* There is nothing to restore the default to. `getBindings` answers a
+			* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+			* `setWrapperActive` — the singleton authority that could name one —
+			* throws for a collection cap by design. Naming CamStack here instead
+			* would privilege one addon by id inside a surface whose premise is
+			* that sources are peers, and would be wrong on the first camera with
+			* no recorder binding. So absence is REFUSED, in the schema, where the
+			* generated types make it unomittable rather than merely discouraged.
+			*
+			* The default belongs to the SURFACE, which has the `listSources` rows
+			* and can say which one it picked (D569 § 1–3; the viewer already
+			* always sends this).
 			*
 			* It replaced `sources?: string[]`, a VIEW filter over source ids that
 			* assumed the answer was a fan-out over everything a camera has. The
-			* operator settled otherwise on 2026-09-20 — *"il get videoclips
-			* prendere un provider opzionale, di default va su camstack"*,
-			* *"l'utilizzatore è uno solo"* — so the list is asked of one provider
-			* at a time and there is nothing to filter out of it.
+			* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+			* solo"* — so the list is asked of one provider at a time and there is
+			* nothing to filter out of it.
 			*/
-			provider: zod.z.string().optional()
+			provider: zod.z.string().min(1)
 		}), zod.z.array(ClipSchema).readonly(), {
 			kind: "query",
 			auth: "protected"
@@ -48432,6 +48519,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.ownersWithMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.pauseForStorageMigration": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -52605,6 +52698,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.ownersWithMedia": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.proposeRetrainAnnotations": [{
 		name: "deviceId",
 		form: "single",
@@ -58927,6 +59025,9 @@ exports.CAP_NAMES_WITH_STATUS = CAP_NAMES_WITH_STATUS;
 exports.CAP_NODE_PIN_CONTEXT_KEY = require_sleep.CAP_NODE_PIN_CONTEXT_KEY;
 exports.CAP_PROVIDER_KIND_MAP = CAP_PROVIDER_KIND_MAP;
 exports.CLASS_MAP_MACRO_TARGETS = CLASS_MAP_MACRO_TARGETS;
+exports.CLIP_STILL_DISPOSITION_HEADER = CLIP_STILL_DISPOSITION_HEADER;
+exports.CLIP_STILL_REASON_CODE_HEADER = CLIP_STILL_REASON_CODE_HEADER;
+exports.CLIP_STILL_REASON_HEADER = CLIP_STILL_REASON_HEADER;
 exports.CLUSTER_MODEL_SCOPED_STEPS = CLUSTER_MODEL_SCOPED_STEPS;
 exports.CLUSTER_MODEL_SECTION_ID = CLUSTER_MODEL_SECTION_ID;
 exports.CLUSTER_STEP_SETTING_FIELDS = CLUSTER_STEP_SETTING_FIELDS;
@@ -58981,6 +59082,8 @@ exports.ClipPlaybackSchema = ClipPlaybackSchema;
 exports.ClipSchema = ClipSchema;
 exports.ClipSourceAvailabilitySchema = ClipSourceAvailabilitySchema;
 exports.ClipSourceSchema = ClipSourceSchema;
+exports.ClipStillDispositionSchema = ClipStillDispositionSchema;
+exports.ClipStillRefusalCodeSchema = ClipStillRefusalCodeSchema;
 exports.ClusterAddonNodeDeploymentSchema = ClusterAddonNodeDeploymentSchema;
 exports.ClusterAddonStatusEntrySchema = ClusterAddonStatusEntrySchema;
 exports.CollectionColumnSchema = CollectionColumnSchema;
@@ -59304,6 +59407,7 @@ exports.MAX_REASONS_PER_KEY = MAX_REASONS_PER_KEY;
 exports.MAX_SENSOR_TRIGGER_DEVICES = MAX_SENSOR_TRIGGER_DEVICES;
 exports.MAX_TRACK_DEBUG_NOTE_LEN = MAX_TRACK_DEBUG_NOTE_LEN;
 exports.MEDIA_OWNER_TYPES = MEDIA_OWNER_TYPES;
+exports.MEDIA_PRESENCE_OWNER_KINDS = MEDIA_PRESENCE_OWNER_KINDS;
 exports.METHOD_ACCESS_MAP = METHOD_ACCESS_MAP;
 exports.METHOD_DEVICE_SELECTORS = METHOD_DEVICE_SELECTORS;
 exports.MODEL_FORMATS = MODEL_FORMATS;
@@ -59330,6 +59434,7 @@ exports.MediaFileSchema = MediaFileSchema;
 exports.MediaPlayerRepeatSchema = MediaPlayerRepeatSchema;
 exports.MediaPlayerStateSchema = MediaPlayerStateSchema;
 exports.MediaPlayerStatusSchema = MediaPlayerStatusSchema;
+exports.MediaPresenceOwnerKindSchema = MediaPresenceOwnerKindSchema;
 exports.MediaRelocateModeSchema = MediaRelocateModeSchema;
 exports.MeshPeerSchema = MeshPeerSchema;
 exports.MeshStatusSchema = MeshStatusSchema;