@camstack/system 1.2.289 → 1.2.290

package/dist/{dist-DKFb2936.mjs → dist-BkjMEa2F.mjs}

@@ -691,7 +691,7 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	return EventCategory;
 }({});
 //#endregion
-//#region ../types/dist/sleep-i3eUVc-d.mjs
+//#region ../types/dist/sleep-COWaSCAi.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -4050,6 +4050,46 @@ z.object({
 	})
 });
 /**
+* How long a minted ticket stays takeable.
+*
+* The consumer's dial is the next thing that happens after the cap call that
+* minted it returns — measured well under 100 ms on the same host for the clip
+* dial this is generalised from. Thirty seconds covers a busy hub and is short
+* enough that a ticket which leaked into a log is worth nothing by the time
+* anybody reads it.
+*/
+var PEER_BYTES_TICKET_TTL_MS = 3e4;
+/**
+* How long the producer waits on a consumer that has stopped reading before it
+* cuts the body.
+*
+* D447: a raw HTTP stream reads no chunk the socket has not taken. The producer
+* honours `write()`'s return and awaits `drain`; a peer that never drains is
+* a peer that is gone, and holding the body for it is the unbounded buffer this
+* whole facility exists to avoid.
+*/
+var PEER_BYTES_STALL_MS = 15e3;
+/** Bytes handed to the socket per `write()` when the producer holds a buffer. */
+var PEER_BYTES_CHUNK_BYTES = 256 * 1024;
+/** The wire shape of {@link PeerBytesTicket} — see the type for what it is. */
+var PeerBytesTicketSchema = z.object({
+	/** `http://127.0.0.1:<port>/<token>`. One `GET` takes it. */
+	url: z.string().min(1),
+	/**
+	* The HOST node this URL means something on — the hub or a named agent,
+	* never a runner. {@link AddonPeerBytes.open} compares it to its own and
+	* refuses `cross-node` by name when they differ, without dialling.
+	*/
+	hostNodeId: z.string().min(1),
+	expiresAtMs: z.number().int().nonnegative(),
+	/**
+	* What the producer DECLARED the body to be, when it knows — `null` when it
+	* does not. Never `0` for unknown (D393): a consumer sizing a bound off this
+	* must be able to tell "the producer did not say" from "the body is empty".
+	*/
+	declaredBytes: z.number().int().nonnegative().nullable()
+});
+/**
 * Adoption job — the background form of `device-adoption.adopt`.
 *
 * ## Why this exists
@@ -26133,6 +26173,7 @@ z.enum([
 	"sleeping",
 	"camera-refused",
 	"no-keyframe",
+	"decode-failed",
 	"no-catalog-row",
 	"unsupported",
 	"unknown-device",
@@ -26407,6 +26448,32 @@ var ClipBytesSchema = z.object({
 	durationMs: z.number().positive().optional()
 });
 /**
+* Where a clip's finished bytes can be TAKEN (D613) — the answer to
+* {@link videoclipsCapability.methods.offerClipBytes}.
+*
+* Everything {@link ClipBytesSchema} carries except the bytes themselves, plus
+* the one-shot ticket that leads to them. The metadata is answered BEFORE the
+* transfer on purpose: a consumer learns which twin it got, what to call the
+* file and how long the clip runs without having to read a byte, so a decision
+* it would make on that metadata (a wrong twin, an implausible duration) costs
+* no transfer at all.
+*/
+var ClipBytesOfferSchema = z.object({
+	/**
+	* One shot, seconds-long, loopback, on the PROVIDER's own host. Open it with
+	* `ctx.peerBytes.open(...)`, which refuses a ticket from another node by
+	* name rather than dialling a port that means something else here.
+	*/
+	ticket: PeerBytesTicketSchema,
+	contentType: z.string(),
+	/** Suggested filename, extension included. */
+	name: z.string(),
+	/** Which twin was actually served — see {@link ClipBytesSchema.served}. */
+	served: CamProfileSchema,
+	/** See {@link ClipBytesSchema.durationMs}. Absent when nothing measured it. */
+	durationMs: z.number().positive().optional()
+});
+/**
 * Where a clip's STREAM can be dialled (D597) — the answer to
 * {@link videoclipsCapability.methods.dialClipStream}.
 *
@@ -26482,6 +26549,44 @@ var ClipStreamDialSchema = z.object({
 	/** Why `servedAudio` is `none` although sound was asked for. */
 	audioReason: ClipStreamAudioReasonSchema.optional()
 });
+/**
+* What a surface may DRAW for this provider's clips — the answer to
+* {@link videoclipsCapability.methods.getPlaybackOptions} (D612).
+*
+* The envelope is a PROVIDER fact, not a clip fact, and that is measured, not
+* assumed: the broker's `chooseClipPath` reads exactly two inputs — whether
+* `dialClipStream` and `readClipBytes` are wired — and both are constants of
+* the broker's own closure over the provider's methods. The `profile` it is
+* handed is explicitly not read. So every clip of a provider is served the
+* same way, and a per-clip channel carried a value that could not vary. The
+* per-clip `clipTransport` server message was removed for exactly that reason.
+*
+* Queried per camera, before a clip is picked, so a control is rendered or
+* DISABLED rather than offered and refused at play time (D62: a disabled
+* control reads as unavailable, one that undoes the gesture reads as broken).
+*/
+var ClipPlaybackOptionsSchema = z.object({
+	/**
+	* How this provider's clips reach the player. `stream` is the provider's
+	* forward-only fMP4 (D597); `file` is one bounded by-handle fetch of the
+	* whole clip, `stbl` indexed (D575).
+	*/
+	transport: z.enum(["stream", "file"]),
+	/** `forward` = only ahead of the playhead. `free` = anywhere. */
+	seek: z.enum(["forward", "free"]),
+	/** Frame-step BACKWARD is meaningful. Forward always is. */
+	stepBack: z.boolean(),
+	/** Whether the scrub gesture is served, as opposed to refused by name. */
+	scrub: z.boolean(),
+	/**
+	* The rates that can be delivered, ascending, always containing `1`. The
+	* viewer draws its picker from this and from nothing else — a constant it
+	* keeps instead is the second authority that produced the defect: `8` and
+	* `16` were offered, the broker clamped them to `4`, and no line anywhere
+	* said so. `0` is not a member: pause is the absence of a rate.
+	*/
+	rates: z.array(z.number().positive()).min(1).readonly()
+});
 var ClipSourceAvailabilitySchema = z.object({
 	state: z.enum([
 		"ok",
@@ -26660,14 +26765,18 @@ var videoclipsCapability = {
 		*
 		* `getClipPlayback` is the right answer for a player: it hands back a URL
 		* on a plane the hub serves `access:'authenticated'`, which a browser and a
-		* viewer session satisfy. It is the wrong answer for another ADDON. There
-		* is no addon→addon byte transport in this framework — `AddonDataPlane`
-		* only lets an addon SERVE, on `127.0.0.1` behind a per-listener secret
-		* only the hub may present — so a recorder that wants a camera's clip
-		* cannot fetch that URL. This method is the one seam that exists for it,
-		* and it is deliberately the same shape (and the same bound) as
-		* `recordingExport.readExportBytes`, which exists for the mirror-image
-		* reason.
+		* viewer session satisfy. It is the wrong answer for another ADDON: the
+		* hub's proxy in front of that plane takes only a user credential, which
+		* an addon does not hold, so a recorder that wants a camera's clip cannot
+		* fetch that URL. This method is the shape that answer forced — the same
+		* one (and the same bound) as `recordingExport.readExportBytes`.
+		*
+		* **It is no longer the only seam.** Until D613 there was no addon→addon
+		* byte transport at all; there is now
+		* ({@link offerClipBytes}, over `ctx.peerBytes`), it holds nothing on
+		* either side, and it is what a clip EXPORT uses. This method remains for
+		* a consumer that genuinely wants the bytes in hand, and as the named
+		* fallback for a provider not yet redeployed.
 		*
 		* Routing needs no `provider` pin: the id is source-prefixed and
 		* self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
@@ -26734,6 +26843,65 @@ var videoclipsCapability = {
 			auth: "protected"
 		}),
 		/**
+		* Where this clip's finished bytes can be TAKEN — the by-handle read a
+		* clip EXPORT pulls, over the addon→addon byte transport (D613).
+		*
+		* This is {@link readClipBytes} with the envelope removed. Same gates,
+		* same vocabulary, same completion rules, same `served` contract — the
+		* only difference is that the bytes travel over a one-shot loopback
+		* socket instead of inside a base64 field, so neither side holds the
+		* payload whole and the 50 MiB refusal on a long `high` twin stops
+		* existing. The bound that remains is
+		* {@link VIDEOCLIPS_MAX_OFFER_BYTES}, and it bounds the PRODUCER's own
+		* copy rather than the transport.
+		*
+		* **The ticket is loopback and same-host.** A provider on an agent mints a
+		* URL that means nothing on the hub, and `ctx.peerBytes.open` refuses it
+		* `cross-node` by name rather than dialling whatever else holds that port
+		* here. A consumer that can be on the other side of a node boundary from
+		* its provider must be able to read that refusal and say so; it must not
+		* treat it as "no bytes".
+		*
+		* **A ticket is a one-shot bearer credential with a seconds-long life.**
+		* Take it immediately, never persist it, never log its `url`. An untaken
+		* ticket costs the provider one map entry until its TTL, and outstanding
+		* tickets are bounded — which is also what makes a per-frame misuse of
+		* this method refuse by name rather than work slowly (D9/D18: this is a
+		* by-handle fetch of finished media, not a frame pipe).
+		*
+		* Optional on the provider for the same reason `readClipBytes` is: a
+		* source with no camera socket behind it has no bytes. A provider that
+		* predates this method answers `NOT_IMPLEMENTED`, and a consumer may fall
+		* back to `readClipBytes` — but it says so in the log, with the deploy
+		* hint, because that fallback re-imposes the 50 MiB refusal and an
+		* operator who sees `too-large-to-transfer` after this shipped is looking
+		* at a stale addon, not at a clip that cannot be exported.
+		*/
+		offerClipBytes: optionalMethod(z.object({
+			deviceId: z.number(),
+			clipId: z.string().min(1),
+			/** WHICH provider holds the bytes — see `readClipBytes.provider`. */
+			provider: z.string().min(1),
+			/** Which twin — `low | mid` → the sub file, `high` → the main twin. */
+			profile: CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before the
+			* camera is touched rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_OFFER_BYTES} whatever is passed; absent means
+			* that ceiling.
+			*/
+			maxBytes: z.number().int().positive().optional(),
+			/**
+			* The operator's authorisation to wake a sleeping camera for this
+			* read. Absent — the default — means a sleeping standalone battery
+			* camera is REFUSED by name, before any session is opened.
+			*/
+			wake: ClipWakeSchema.optional()
+		}), ClipBytesOfferSchema, {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
 		* Where this clip's STREAM can be dialled (D597) — the forward-only
 		* fMP4 the provider writes from the first muxed byte, for the broker to
 		* play through the same WebRTC session as recorded footage, with the
@@ -26770,6 +26938,36 @@ var videoclipsCapability = {
 		}), ClipStreamDialSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* What a surface may DRAW for this provider's clips: the rates it can be
+		* played at, whether scrub is served, how far a position may be moved,
+		* and whether a backward frame-step means anything (D612).
+		*
+		* **The only authority.** The per-clip `clipTransport` server message
+		* that used to carry the same answer was removed: the broker's transport
+		* choice reads nothing that varies per clip, so the clip level had no
+		* information the provider does not already have, and two channels that
+		* can disagree are worse than one (D62).
+		*
+		* Asked per camera and per provider, so it must stay CHEAP — it is a
+		* statement about wiring, answered from a constant, never a call to the
+		* camera. A provider answers with one of {@link CLIP_PLAYBACK_OPTIONS}
+		* and never composes an envelope of its own.
+		*
+		* Optional, and absence is load-bearing: a provider that has not answered
+		* has not restricted anything, and a viewer reads it as the freedom it
+		* always had. See D612 on the rollout order that absence implies.
+		*/
+		getPlaybackOptions: optionalMethod(z.object({
+			deviceId: z.number(),
+			/** WHICH provider to ask — the `addonId` a {@link ClipSourceSchema}
+			*  row carries. Required for the same reason `listClips` requires it:
+			*  a collection cap has no "the bound one" to resolve to (D554). */
+			provider: z.string().min(1)
+		}), ClipPlaybackOptionsSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
@@ -49334,6 +49532,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.getPlaybackOptions": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.listClips": {
 		capName: "videoclips",
 		capScope: "device",
@@ -49346,6 +49550,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.offerClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.readClipBytes": {
 		capName: "videoclips",
 		capScope: "device",
@@ -51392,6 +51602,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.getPlaybackOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.listClips": [{
 		name: "deviceId",
 		form: "single",
@@ -51402,6 +51617,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.offerClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.readClipBytes": [{
 		name: "deviceId",
 		form: "single",
@@ -52533,4 +52753,4 @@ function enumerateInferenceDevices(hw) {
 	return out;
 }
 //#endregion
-export { deriveBatteryPresence as $, storageCapability as $t, ScopedTokenSchema as A, isEvent as An, mayWriteToLocation as At, authProviderCapability as B, ptzAutotrackCapability as Bt, REDACTED_SECRET as C, asString as Cn, lifecycleJobSchema as Ct, SOURCE_DEVICE_TYPES as D, expandCapMethods as Dn, logLevelAtMost as Dt, SOURCE_CAPS as E, emitReadiness as En, logDestinationCapability as Et, UserRecordSchema as F, resolveCapMount as Fn, objectInputDeclaresAddonId as Ft, cameraGridLayoutCapability as G, resolveMethodAuth as Gt, bareAddonId as H, resolveBucketMs as Ht, addonPagesCapability as I, scopeKey as In, objectInputDeclaresRequiredDeviceId as It, coreBlockIdFromAddonId as J, scopesAllowDeviceCap as Jt, collectSecretConfigKeys as K, runtimeStatePolicyFor as Kt, addonSettingsCapability as L, sleep as Ln, parseStreamParamsFormPatch as Lt, StorageLocationModeSchema as M, parseJsonObject as Mn, modeMayWrite as Mt, StorageLocationTypeSchema as N, parseJsonUnknown as Nn, motionCapability as Nt, STORAGE_ACCESS_FALLBACK as O, hydrateSchema as On, looseSchema as Ot, StorageMigrationJobSchema as P, readinessKey as Pn, normalizeUnit as Pt, decodeVectorBase64 as Q, snapshotCapability as Qt, addonWidgetsCapability as R, EventCategory as Rn, platformProbeCapability as Rt, MOTION_CLOSE_AFTER_MS as S, asNumber as Sn, legacyModeOf as St, RecordingStatusSchema as T, emitDownForOwnedCaps as Tn, locationIconKey as Tt, batteryCapability as U, resolveContainerPrimaryChild as Ut, backupCapability as V, reducePoints as Vt, buildStreamParamsConfigSchema as W, resolveLocationMode as Wt, dataStoreProviderCapability as X, settingsStoreCapability as Xt, coreBlocksCapability as Y, scoreRuntimes as Yt, declarationOwnerNodeId as Z, siteZoneKey as Zt, LOG_LEVEL_RANK as _, DeviceType as _n, isObjectInput as _t, BatteryStatusSchema as a, userManagementCapability as an, enumerateItemArrayFields as at, METHOD_ACCESS_MAP as b, WELL_KNOWN_TAB_MAP as bn, isVoidInput as bt, CORE_BLOCKS_ADDON_ID as c, withLocationMode as cn, evictionPolicyOfLocation as ct, DAY_NAMES as d, BaseAddon as dn, foldSnapshotByFunction as dt, storageMigrationCapability as en, deviceManagerCapability as et, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as f, DATAPLANE_SECRET_HEADER as fn, formatMinutes as ft, FIRST_LEVEL_MACRO_CLASSES as g, DeviceRole as gn, isLocationEnabled as gt, DeviceStatusSchema as h, DeviceFeature as hn, isCollectionArrayMethod as ht, BaseDevice as i, streamQualityLabel as in, enumerateInferenceDevices as it, StorageCleanupJobSchema as j, nodePin as jn, metricsProviderCapability as jt, STREAM_PROFILE_META as k, isDeviceConfigCap as kn, mayReadLocation as kt, CORE_BLOCK_ADDON_PREFIX as l, errMsg as ln, extractNestedAddonId as lt, DeclaredDevices as m, DEVICE_STATUS_METHOD as mn, isArrayOutputSchema as mt, AlertSchema as n, storageProviderCapability as nn, deviceStatusCapability as nt, CAMERA_SWITCH_ORDER as o, vectorDimFromBase64 as on, enumerateSchemaFields as ot, DERIVED_CAMERA_SILENCED_CAP_NAMES as p, DEVICE_SETTINGS_CONTRIBUTION_METHODS as pn, gbToBytes as pt, coreBlockAddonId as q, scopesAllowAddon as qt, ApiKeyRecordSchema as r, streamCatalogCapability as rn, doorbellCapability as rt, CAP_NAMES_WITH_STATUS as s, vectorStoreCapability as sn, evaluateSensorEdge as st, ALL_CAPABILITY_DEFINITIONS as t, storageOccupancyCapability as tn, deviceStateCapability as tt, CoreBlockSchema as u, buildFfmpegArgs as un, filesystemBrowseCapability as ut, LegacyStorageLocationDefaultSchema as v, ReadinessRegistry as vn, isSameAddonId as vt, RUNTIME_DEFAULTS as w, createEvent as wn, localNetworkCapability as wt, MINUTES_PER_DAY as x, asJsonObject as xn, kebabToCamel as xt, LocationIconIdSchema as y, ReadinessTimeoutError as yn, isSourceCap as yt, alertsCapability as z, procedureAuthKey as zt };
+export { dataStoreProviderCapability as $, settingsStoreCapability as $t, SOURCE_DEVICE_TYPES as A, expandCapMethods as An, logLevelAtMost as At, addonSettingsCapability as B, sleep as Bn, parseStreamParamsFormPatch as Bt, PEER_BYTES_CHUNK_BYTES as C, WELL_KNOWN_TAB_MAP as Cn, isVoidInput as Ct, RUNTIME_DEFAULTS as D, createEvent as Dn, localNetworkCapability as Dt, REDACTED_SECRET as E, asString as En, lifecycleJobSchema as Et, StorageLocationModeSchema as F, parseJsonObject as Fn, modeMayWrite as Ft, bareAddonId as G, resolveBucketMs as Gt, alertsCapability as H, procedureAuthKey as Ht, StorageLocationTypeSchema as I, parseJsonUnknown as In, motionCapability as It, cameraGridLayoutCapability as J, resolveMethodAuth as Jt, batteryCapability as K, resolveContainerPrimaryChild as Kt, StorageMigrationJobSchema as L, readinessKey as Ln, normalizeUnit as Lt, STREAM_PROFILE_META as M, isDeviceConfigCap as Mn, mayReadLocation as Mt, ScopedTokenSchema as N, isEvent as Nn, mayWriteToLocation as Nt, RecordingStatusSchema as O, emitDownForOwnedCaps as On, locationIconKey as Ot, StorageCleanupJobSchema as P, nodePin as Pn, metricsProviderCapability as Pt, coreBlocksCapability as Q, scoreRuntimes as Qt, UserRecordSchema as R, resolveCapMount as Rn, objectInputDeclaresAddonId as Rt, MOTION_CLOSE_AFTER_MS as S, ReadinessTimeoutError as Sn, isSourceCap as St, PEER_BYTES_TICKET_TTL_MS as T, asNumber as Tn, legacyModeOf as Tt, authProviderCapability as U, ptzAutotrackCapability as Ut, addonWidgetsCapability as V, EventCategory as Vn, platformProbeCapability as Vt, backupCapability as W, reducePoints as Wt, coreBlockAddonId as X, scopesAllowAddon as Xt, collectSecretConfigKeys as Y, runtimeStatePolicyFor as Yt, coreBlockIdFromAddonId as Z, scopesAllowDeviceCap as Zt, LOG_LEVEL_RANK as _, DEVICE_STATUS_METHOD as _n, isArrayOutputSchema as _t, BatteryStatusSchema as a, storageProviderCapability as an, deviceStatusCapability as at, METHOD_ACCESS_MAP as b, DeviceType as bn, isObjectInput as bt, CORE_BLOCKS_ADDON_ID as c, userManagementCapability as cn, enumerateItemArrayFields as ct, DAY_NAMES as d, withLocationMode as dn, evictionPolicyOfLocation as dt, siteZoneKey as en, declarationOwnerNodeId as et, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as f, errMsg as fn, extractNestedAddonId as ft, FIRST_LEVEL_MACRO_CLASSES as g, DEVICE_SETTINGS_CONTRIBUTION_METHODS as gn, gbToBytes as gt, DeviceStatusSchema as h, DATAPLANE_SECRET_HEADER as hn, formatMinutes as ht, BaseDevice as i, storageOccupancyCapability as in, deviceStateCapability as it, STORAGE_ACCESS_FALLBACK as j, hydrateSchema as jn, looseSchema as jt, SOURCE_CAPS as k, emitReadiness as kn, logDestinationCapability as kt, CORE_BLOCK_ADDON_PREFIX as l, vectorDimFromBase64 as ln, enumerateSchemaFields as lt, DeclaredDevices as m, BaseAddon as mn, foldSnapshotByFunction as mt, AlertSchema as n, storageCapability as nn, deriveBatteryPresence as nt, CAMERA_SWITCH_ORDER as o, streamCatalogCapability as on, doorbellCapability as ot, DERIVED_CAMERA_SILENCED_CAP_NAMES as p, buildFfmpegArgs as pn, filesystemBrowseCapability as pt, buildStreamParamsConfigSchema as q, resolveLocationMode as qt, ApiKeyRecordSchema as r, storageMigrationCapability as rn, deviceManagerCapability as rt, CAP_NAMES_WITH_STATUS as s, streamQualityLabel as sn, enumerateInferenceDevices as st, ALL_CAPABILITY_DEFINITIONS as t, snapshotCapability as tn, decodeVectorBase64 as tt, CoreBlockSchema as u, vectorStoreCapability as un, evaluateSensorEdge as ut, LegacyStorageLocationDefaultSchema as v, DeviceFeature as vn, isCollectionArrayMethod as vt, PEER_BYTES_STALL_MS as w, asJsonObject as wn, kebabToCamel as wt, MINUTES_PER_DAY as x, ReadinessRegistry as xn, isSameAddonId as xt, LocationIconIdSchema as y, DeviceRole as yn, isLocationEnabled as yt, addonPagesCapability as z, scopeKey as zn, objectInputDeclaresRequiredDeviceId as zt };