@camstack/types 1.2.93 → 1.2.95

package/dist/index.js

@@ -1530,12 +1530,25 @@ var RecordingBandSchema = zod.z.object({
 * segment is ever finalized and the camera records nothing anyway. At the 10 s
 * default segment length, 30 s leaves room for two full segments. `preBufferSec`
 * is retroactive only — it costs nothing at record time, it merely keeps
-* already-written segments — so it is set to one segment length.
+* already-written segments.
 *
-* An EXPLICIT `0` is left alone: that is an operator statement, not an omission.
+* ## Why `preBufferSec` is 15 and not one segment length
+*
+* It has to cover the broker's RECORDING pre-roll, which is media handed to the
+* writer from BEFORE the trigger (D192/D193). If this bound were narrower, the
+* keep gate would delete the very seconds the ring just supplied — two
+* authorities disagreeing about the same footage, which is the failure D191 was
+* written against. It is therefore set to `RECORDING_PRE_ROLL_MAX_MS` (15 s),
+* the widest window the broker can be configured to serve, so an operator
+* raising the cluster pre-roll can never walk past the gate silently. The
+* addon-side guard is
+* `packages/addon-pipeline/src/recorder/addon/__tests__/band-decision.spec.ts`.
+*
+* An EXPLICIT `0` is left alone: that is an operator statement, not an omission,
+* and it is excluded from that invariant by name.
 */
 var DEFAULT_EVENTS_BAND_BUFFER_SEC = {
-	preBufferSec: 10,
+	preBufferSec: 15,
 	postBufferSec: 30
 };
 /**
@@ -4223,11 +4236,15 @@ export default function block(ctx: AddonContext) {
   ): Promise<void> {
     const resolved: Record<string, unknown> = {}
     for (const [k, v] of Object.entries(args)) resolved[k] = substitute(v, vars)
-    const client = (ctx.api as unknown as Record<string, Record<string, { mutate: (i: unknown) => Promise<unknown> }>>)[capToRouterKey(cap)]
-    if (client === undefined || client[method] === undefined) {
+    const client: unknown = Reflect.get(ctx.api, capToRouterKey(cap))
+    const proc: unknown =
+      typeof client === 'object' && client !== null ? Reflect.get(client, method) : undefined
+    const mutate: unknown =
+      typeof proc === 'object' && proc !== null ? Reflect.get(proc, 'mutate') : undefined
+    if (typeof mutate !== 'function') {
       throw new Error('no such device method: ' + cap + '.' + method)
     }
-    await client[method]!.mutate({ ...resolved, deviceId })
+    await mutate({ ...resolved, deviceId })
   }
 
   async function evaluateConditions(): Promise<boolean> {
@@ -14688,7 +14705,7 @@ var TrackEnvelopeSchema = zod.z.object({
 * `snapshots[]` references — megabytes across a page of tracks. `slim`
 * keeps every scalar the list surfaces actually render (ids, class(es),
 * label / audioLabels / importance enrichment, firstSeen/lastSeen, state,
-* zonesVisited, bestEventId, envelope, hasFace, hasRider) and returns `positions` /
+* zonesVisited, bestEventId, envelope, hasFace, hasEmbeddedFace, hasRider) and returns `positions` /
 * `snapshots` as EMPTY arrays — detail views re-fetch the full row via
 * `getTrack`. Mirrors the event-store `projection` convention
 * (`getObjectEvents` et al.).
@@ -14999,6 +15016,35 @@ var TrackSchema = zod.z.object({
 	*/
 	hasFace: zod.z.boolean().optional(),
 	/**
+	* This track has a face row IN THE GALLERY: a crop **and** an embedding — a
+	* face an operator could ASSIGN to an identity.
+	*
+	* The STRICT twin of {@link hasFace}, and the pair only earns its keep
+	* because the two disagree. `hasFace` is stamped at the TOP of the face
+	* branch, before every gate, and means no more than "a face detector produced
+	* a face detail". This one is stamped at the single moment the gallery row
+	* LANDS — after `FaceRecognizer.onTrackEnd` successfully persists it, i.e.
+	* past the embedding-magnitude verdict, the `minFacePx` detection gate, the
+	* candidate gate, the imageless-track drop (no crop was ever captured) and
+	* the crop-store drop. Everything between the detector and that insert can
+	* legitimately refuse the face, so a flag written any earlier promises the
+	* operator something to assign and delivers nothing.
+	*
+	* **Independent of recognition.** A face collected but never auto-matched is
+	* still assignable — it is in fact the face an operator most wants to reach —
+	* so this is NOT gated on `recognizedIdentityId`. Recognition lands in
+	* `subLabel`; this says only that the raw material exists.
+	*
+	* **Set once, never cleared.** A track that produced a gallery row produced
+	* one; deleting the row later is the gallery's business, not this flag's.
+	*
+	* **Absent ≠ false**, the same rule as {@link hasFace}: every row written
+	* before the column omits it, and so does every server that predates the
+	* field. A consumer must test `=== true` and render nothing otherwise —
+	* never infer "no assignable face".
+	*/
+	hasEmbeddedFace: zod.z.boolean().optional(),
+	/**
 	* This subject CONTAINS a folded rider — a person the rider-pairing step
 	* ([D34](../decisions/adr-0034.md)) removed from the frame BEFORE the tracker,
 	* so the passage is tracked once and as a VEHICLE.
@@ -16965,6 +17011,26 @@ var DetailResultSchema = zod.z.object({
 	* the consuming gate treats as accept — never as reject.
 	*/
 	embeddingMagnitude: zod.z.number().optional(),
+	/**
+	* Model that produced `embedding` — the SAME contract `labelModelId` has for
+	* `label`, and for the same reason: the producing node is the only side that
+	* knows which model actually ran, and re-deriving it downstream is exactly
+	* the inference this model exists to forbid.
+	*
+	* Additive and optional, so a runner that predates it degrades to
+	* "unmeasurable" rather than to a wrong answer — the consumer falls back to
+	* its previous assumption instead of refusing.
+	*
+	* Its absence was not cosmetic. `FaceRecognizer` needs the probe's model id
+	* to use `face-matcher`'s same-model gate (`sample.modelId !== probe.modelId`);
+	* with nothing on the wire it took the id from the GALLERY, so the gate
+	* compared the gallery against itself and could never fire. That turned the
+	* one guard protecting the face feature space into a tautology, and it is
+	* why swapping `face-embedding`'s model would NOT have stranded the enrolled
+	* gallery as the catalog comment predicts — it would have scored the new
+	* model's vectors against the old model's samples in one cosine space.
+	*/
+	embeddingModelId: zod.z.string().optional(),
 	label: zod.z.string().optional(),
 	/**
 	* The tier `label` occupies, copied VERBATIM from the producing step's
@@ -18170,6 +18236,24 @@ var CameraStatusSchema = zod.z.object({
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: zod.z.number()
 });
+/**
+* Why the dispatcher does NOT consider a device the node HAS for the
+* camera-root election. The list is the CONTRACT between the orchestrator's
+* `resolveInferenceDeviceEligibility` (which computes it) and the admin UI
+* (which renders it) — the orchestrator's `InferenceDeviceExclusionReason`
+* derives from this tuple so the two can never drift.
+*
+* Every one of these drops used to be silent, and an accelerator that is
+* enabled, available, and never chosen is indistinguishable from one that was
+* never configured. The reason is the difference.
+*/
+var INFERENCE_DEVICE_EXCLUSION_REASONS = [
+	"disabled",
+	"unavailable",
+	"cannot-host-camera-root",
+	"accelerator-preferred"
+];
+var InferenceDeviceExclusionReasonSchema = zod.z.enum(INFERENCE_DEVICE_EXCLUSION_REASONS);
 var NodeInferenceDeviceSchema = zod.z.object({
 	/** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
 	key: zod.z.string(),
@@ -18200,7 +18284,17 @@ var NodeInferenceDeviceSchema = zod.z.object({
 	* available per format; this is the stored selection that becomes the
 	* default for EVERY camera landing on this accelerator.
 	*/
-	steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional()
+	steps: zod.z.record(zod.z.string(), DeviceStepConfigSchema).optional(),
+	/**
+	* `null` when the device IS a camera-root candidate on this node; otherwise
+	* the reason the dispatcher drops it. Computed by the SAME
+	* `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+	* never disagree with the election — deriving it in the UI from
+	* `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+	* the node's model catalog) and `accelerator-preferred` (needs the node-wide
+	* "an accelerator is serving" predicate).
+	*/
+	exclusion: InferenceDeviceExclusionReasonSchema.nullable()
 });
 var NodeInferenceDevicesSchema = zod.z.object({
 	nodeId: zod.z.string(),
@@ -24520,7 +24614,41 @@ var ConnectionEndpointSchema = zod.z.object({
 	*/
 	priority: zod.z.number()
 });
-var GetConnectionEndpointsResultSchema = zod.z.object({ endpoints: zod.z.array(ConnectionEndpointSchema).readonly() });
+/**
+* Where the advertised local port came from. Ordered most → least
+* authoritative, and the whole point of returning it: a client must be able to
+* tell a FACT about the hub's socket from an echo of its own guess.
+*/
+var LocalPortSourceEnum = zod.z.enum([
+	"server-config",
+	"server-env",
+	"caller-hint",
+	"default"
+]);
+/** The port every LAN/loopback `baseUrl` in the same result was built with. */
+var AdvertisedLocalPortSchema = zod.z.object({
+	port: zod.z.number().int().min(1).max(65535),
+	source: LocalPortSourceEnum
+});
+var GetConnectionEndpointsResultSchema = zod.z.object({
+	endpoints: zod.z.array(ConnectionEndpointSchema).readonly(),
+	/**
+	* The port the hub built the LAN/loopback URLs with, and where that number
+	* came from.
+	*
+	* Returned rather than merely applied, because "the URL is right" and "the
+	* client can KNOW the URL is right" are different properties. A client that
+	* only sees a corrected URL cannot distinguish a hub that fixed the port from
+	* a hub that echoed the port the client sent, so it cannot decide whether to
+	* race the candidate or discard it. With `source` it can: anything but
+	* `caller-hint` is the hub's own socket.
+	*
+	* Absent on hubs predating this field — a client that finds it missing is
+	* talking to an echoing hub and must degrade exactly as it does for
+	* `caller-hint`.
+	*/
+	localPort: AdvertisedLocalPortSchema
+});
 /**
 * The chosen outbound endpoint for notification artifacts. `baseUrl: null` =
 * AUTO (resolved from the candidate ranking at send time); `resolved` reports
@@ -24566,10 +24694,35 @@ var localNetworkCapability = {
 		* Honours `getAllowedAddresses()` when set — addresses outside
 		* the allowlist are dropped (the public tunnel + loopback are
 		* always included as escape hatches).
+		*
+		* **The port is the hub's, not the caller's** (D62 — a function's fact
+		* belongs to whoever already owns it). This method used to take a `port`
+		* and echo it onto every LAN and loopback URL it advertised, which made
+		* every client a second authority on a socket only the hub binds. A viewer
+		* configured with a port-less public URL (`https://camstack.example.top`)
+		* infers 443 from the scheme, asks with 443, and was handed
+		* `https://192.168.1.9:443` for a hub listening on 4443. That candidate
+		* cannot ever answer, and losing its race reads in the log exactly like
+		* "the LAN was tried and it was slower" — so an operator sitting on his own
+		* WiFi stayed on the public tunnel for weeks, with the LAN candidate born
+		* dead on every single connect.
+		*
+		* The hub now resolves its own listen port and reports it as `localPort`,
+		* with the SOURCE of the number, so a client can tell a fact from an echo.
+		*
+		* Out of scope on purpose: a LAN URL that is not the hub's own socket (a
+		* reverse proxy in front of it on another port) is not this method's to
+		* invent either — pin it with `setNotificationEndpoint` / a configured
+		* origin, which is an operator statement rather than a guess.
 		*/
 		getConnectionEndpoints: require_sleep.method(zod.z.object({
-			/** Local hub HTTP port to use in base URLs. */
-			port: zod.z.number().int().min(1).max(65535),
+			/**
+			* LEGACY HINT — do not send from new code. Kept optional so clients
+			* written against the echoing contract keep working; the hub uses it
+			* only when it cannot read its own port, and says so via
+			* `localPort.source === 'caller-hint'`.
+			*/
+			port: zod.z.number().int().min(1).max(65535).optional(),
 			/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
 			*  candidate. Default `true`. */
 			includeLoopback: zod.z.boolean().optional(),
@@ -32343,11 +32496,63 @@ function startReachabilityPoll(options) {
 //#endregion
 //#region src/device/runtime-state-helpers.ts
 var LAST_FETCHED_FIELD = "lastFetchedAt";
+/**
+* How long a bridge stops re-attempting a refresh that did not land.
+*
+* Sized against the failure it exists for: a camera whose control plane
+* is unreachable costs the FULL connect give-up (~3s on Linux when the
+* neighbour never answers, up to the client's own timeout otherwise) on
+* every attempt, and a failed refresh never advances `lastFetchedAt`, so
+* without a cooldown the slice is permanently stale and EVERY read pays
+* that price. One attempt per minute is enough to notice the camera
+* coming back; per-read is enough to stall the viewer's first paint.
+*/
+var RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = 6e4;
+/**
+* The freshness window for a cap whose value changes ONLY when WE write it.
+*
+* The usual `staleMs: 10_000` is tuned for a reading that moves on its own — a
+* battery level, a day/night state that flips at dusk. It is the wrong number
+* for a cap like `privacy-mask`, whose two facts (is the video mask on, is the
+* microphone on) change when an operator changes them, through a `setMask` /
+* `setAudioEnabled` that **re-reads the camera and rewrites this very slice**.
+* A write is therefore its own invalidation: the window never delays an
+* operator's own change, however long it is.
+*
+* What the window really bounds is the ONE case we do not write: somebody
+* changing the mask in the vendor app or the camera's web UI. Ten minutes is
+* the trade — that change is visible within ten minutes, and a fleet of 29
+* cameras behind a page that polls every 5s costs about 3 camera round trips a
+* minute instead of 696
+* ([D221](../../../../docs/decisions/adr-0221-a-polled-list-never-dials-a-camera.md)).
+*
+* Use it ONLY with {@link RuntimeStateStaleReadPolicy} `'serve-and-revalidate'`.
+* On the awaiting default a window this long does not remove the stall, it
+* merely makes it rarer and just as long.
+*/
+var OPERATOR_WRITTEN_STALE_MS = 10 * 6e4;
 function createRuntimeStateBridge(params) {
 	const { runtimeState, cap, ownDeviceId, refresh, staleMs, empty, logger } = params;
 	const missCooldownMs = params.refreshMissCooldownMs ?? 6e4;
+	const staleRead = params.staleRead ?? "await-refresh";
 	/** Epoch ms until which a refresh is not re-attempted. 0 = no cooldown. */
 	let missCooldownUntil = 0;
+	/**
+	* The refresh this bridge currently has in the air, if any.
+	*
+	* Providers single-flight their own camera client, so this is not what stops
+	* a second round trip. What it stops is a POLLED reader JOINING one: under
+	* `'serve-and-revalidate'` a read that finds a refresh already outstanding is
+	* answered from the slice at once — even a cold, empty slice, which reports
+	* UNKNOWN, which is the truth about a camera nobody has reached.
+	*
+	* That distinction is the whole cost of an unreachable camera. Measured on
+	* the live hub (device 3629, an offline battery Reolink): its refresh takes
+	* 23.1s to give up, so without this every 5s poll landing inside those 23s
+	* joined the wait and spent the caller's full 1.2s source budget — five
+	* stalled polls per cooldown cycle, for one camera, forever.
+	*/
+	let refreshInFlight = null;
 	const readFetchedAt = () => {
 		const value = runtimeState.getCapState(cap.name)?.[LAST_FETCHED_FIELD];
 		return typeof value === "number" ? value : 0;
@@ -32368,14 +32573,14 @@ function createRuntimeStateBridge(params) {
 			}
 		});
 	};
-	const ensureFresh = async () => {
-		const slice = runtimeState.getCapState(cap.name);
-		const fetchedAt = readFetchedAt();
-		if (slice && Date.now() - fetchedAt <= staleMs) {
-			missCooldownUntil = 0;
-			return;
-		}
-		if (Date.now() < missCooldownUntil) return;
+	/**
+	* One refresh attempt, plus the LANDED check that decides the cooldown.
+	*
+	* @param fetchedAt What `lastFetchedAt` was before the attempt — the only
+	*                  evidence the bridge has that the refresh persisted
+	*                  anything, since providers swallow their own camera errors.
+	*/
+	const runRefresh = async (fetchedAt) => {
 		try {
 			await refresh();
 		} catch (err) {
@@ -32391,6 +32596,41 @@ function createRuntimeStateBridge(params) {
 		}
 		openMissCooldown(void 0);
 	};
+	/**
+	* Start a refresh and remember it, at most one at a time.
+	*
+	* It never rejects: under `'serve-and-revalidate'` the caller is answered
+	* from the slice either way, so a floating rejection would take the process
+	* down for a fault the miss cooldown has already recorded and logged.
+	*/
+	const startRefresh = (fetchedAt) => {
+		const existing = refreshInFlight;
+		if (existing !== null) return existing;
+		const started = runRefresh(fetchedAt).catch(() => void 0).finally(() => {
+			refreshInFlight = null;
+		});
+		refreshInFlight = started;
+		return started;
+	};
+	const ensureFresh = async () => {
+		const slice = runtimeState.getCapState(cap.name);
+		const fetchedAt = readFetchedAt();
+		if (slice && Date.now() - fetchedAt <= staleMs) {
+			missCooldownUntil = 0;
+			return;
+		}
+		if (Date.now() < missCooldownUntil) return;
+		if (staleRead === "serve-and-revalidate") {
+			if (refreshInFlight !== null) return;
+			if (slice && fetchedAt > 0) {
+				startRefresh(fetchedAt);
+				return;
+			}
+			await startRefresh(fetchedAt);
+			return;
+		}
+		await runRefresh(fetchedAt);
+	};
 	const projectStatus = () => {
 		const slice = runtimeState.getCapState(cap.name);
 		if (!slice) return empty();
@@ -44334,6 +44574,166 @@ function readTimelapseGeneratedAt(rule, deviceId) {
 	return rule.lastGeneratedAt ?? 0;
 }
 //#endregion
+//#region src/pipeline/cluster-model-scope.ts
+/**
+* A model choice has a SCOPE, and a scope change has a workflow.
+*
+* ## The two scopes
+*
+* Almost every pipeline step's model is a **node** question: which build runs
+* fastest on THIS accelerator. Two nodes may legitimately answer differently —
+* a Coral runs the tflite SSD, a Mac runs the coreml YOLO — because the answers
+* are compared against nothing. They produce boxes, and a box is a box.
+*
+* Two steps are not like that. `face-embedding` and `clip-embedding` produce
+* **vectors that land in ONE shared index** (`identity_samples`,
+* `vec_object_clip`) and are ranked against each other by cosine similarity.
+* Cosine similarity between two encoders is not a weak signal, it is a
+* meaningless number — and nothing inside a vector can tell you it happened.
+* So for those two steps the model is a **cluster** question with exactly one
+* answer, stored in exactly one row.
+*
+* That is the same argument [D52](../../../../docs/decisions/adr-0052.md) makes
+* for the crop convention (`detail-crop.ts`), one level up: the crop decides
+* WHAT pixels the encoder sees, this decides WHICH encoder sees them. Both are
+* cluster-wide for the same reason and neither may become per-node.
+*
+* ## Why the registry lives here and not in the step catalog
+*
+* The scope itself is declared on the step, in
+* `detection-pipeline/registry/step-definitions.ts` (`StepDefinition.modelScope`)
+* — that is where a new step declares what kind of choice its model is. But the
+* catalog lives inside `addon-pipeline`, and three packages that must NOT
+* import an addon need to know the set: the orchestrator (which renders and
+* stores the row), post-analysis (which pins the row for a re-embed pass) and
+* admin-ui (which mirrors it). So the set is mirrored here, and
+* `scripts/check-cluster-model-scope.ts` fails the build when the two disagree.
+* A hand-copied key that stops matching is exactly how a setting silently stops
+* arriving while both sides still look correct.
+*
+* ## The defaults ARE today's behaviour
+*
+* {@link DEFAULT_CLUSTER_STEP_MODELS} reproduces the catalog `defaultModelId`
+* of both steps. Declaring the scope therefore changes nothing on the day it
+* ships: the cluster row starts out saying what every node was already doing.
+* Changing it is legitimate — that is what the knob is for — but it invalidates
+* the stored vectors of that surface, and must be followed by a re-embed pass
+* (`face-reembed-pass.ts`, `embedding-rebuild.ts`).
+*/
+/**
+* The cluster-scoped steps. Mirrored from the catalog's `modelScope: 'cluster'`
+* declarations and guarded by `scripts/check-cluster-model-scope.ts`.
+*/
+var CLUSTER_MODEL_SCOPED_STEPS = [{
+	stepId: "face-embedding",
+	label: "Face recognition model",
+	defaultModelId: "arcface-r100",
+	indexName: "the enrolled face gallery",
+	options: [
+		{
+			id: "arcface-r100",
+			label: "ArcFace (ResNet34)"
+		},
+		{
+			id: "auraface-r100",
+			label: "AuraFace R100"
+		},
+		{
+			id: "inception-resnet-v1",
+			label: "Inception ResNet V1"
+		}
+	]
+}, {
+	stepId: "clip-embedding",
+	label: "Semantic search model",
+	defaultModelId: "mobileclip-s1",
+	indexName: "the object semantic-search index",
+	options: [{
+		id: "mobileclip-s1",
+		label: "MobileCLIP S1"
+	}, {
+		id: "mobileclip-s2",
+		label: "MobileCLIP S2"
+	}]
+}];
+/**
+* Store identity of the cluster row inside `pipeline-orchestrator`'s GLOBAL
+* (cluster-wide) settings — the same owner, and for the same reason, as the
+* detail-crop convention: hub-resident and neutral between the addons that
+* read it.
+*/
+var CLUSTER_MODEL_SECTION_ID = "cluster-step-models";
+/**
+* The settings key holding one step's cluster model choice.
+*
+* Step-qualified so the keys stay unique across the addon's whole schema, which
+* is what lets {@link pickClusterStepModels} walk every section instead of
+* trusting the section id.
+*/
+function clusterModelSettingKey(stepId) {
+	return `clusterModel:${stepId}`;
+}
+/** True when this step's model is a cluster-wide choice rather than a per-node one. */
+function isClusterScopedStep(stepId) {
+	return CLUSTER_MODEL_SCOPED_STEPS.some((s) => s.stepId === stepId);
+}
+/** The cluster row when nobody has configured one — today's catalog defaults. */
+var DEFAULT_CLUSTER_STEP_MODELS = Object.freeze(Object.fromEntries(CLUSTER_MODEL_SCOPED_STEPS.map((s) => [s.stepId, s.defaultModelId])));
+/** A stored choice is a non-empty model id, or it is not a choice. */
+var ChosenModelIdSchema = zod.z.string().min(1);
+/**
+* Narrow a FLAT settings record to the cluster row.
+*
+* Per-FIELD fallback, deliberately (same rule as `readDetailCropConvention`): a
+* junk face model must not also discard a valid clip model. An absent, empty or
+* non-string value resolves to the step's catalog default — the historical
+* behaviour — never to a blank id, because a blank id downstream becomes
+* "substitute the format default", which is precisely the substitution this
+* scope exists to forbid.
+*/
+function readClusterStepModels(config) {
+	const out = {};
+	for (const step of CLUSTER_MODEL_SCOPED_STEPS) {
+		const parsed = ChosenModelIdSchema.safeParse(config[clusterModelSettingKey(step.stepId)]);
+		out[step.stepId] = parsed.success ? parsed.data : step.defaultModelId;
+	}
+	return out;
+}
+function isHydratedField$2(entry) {
+	return typeof entry === "object" && entry !== null && "key" in entry;
+}
+/**
+* Extract the cluster row from an `addon-settings.getGlobalSettings` payload.
+*
+* Walks EVERY section rather than looking inside {@link CLUSTER_MODEL_SECTION_ID}
+* alone: the keys are unique across the addon's schema, and a section rename
+* must not silently revert the whole cluster to the defaults. A `null` payload
+* (addon mid-boot) is the defaults.
+*/
+function pickClusterStepModels(view) {
+	if (view === null) return DEFAULT_CLUSTER_STEP_MODELS;
+	const flat = {};
+	const wanted = new Set(CLUSTER_MODEL_SCOPED_STEPS.map((s) => clusterModelSettingKey(s.stepId)));
+	for (const section of view.sections) for (const entry of section.fields) {
+		if (!isHydratedField$2(entry) || typeof entry.key !== "string") continue;
+		if (wanted.has(entry.key)) flat[entry.key] = entry.value;
+	}
+	return readClusterStepModels(flat);
+}
+/**
+* The cluster model for `stepId`, or `null` when the step is node-scoped.
+*
+* `null` is the signal to LEAVE THE CALLER'S RESOLUTION ALONE — it is not "no
+* model". Returning a default here for a node-scoped step would quietly
+* override every per-(node,device) selection in the fleet.
+*/
+function resolveClusterStepModelId(stepId, models) {
+	const step = CLUSTER_MODEL_SCOPED_STEPS.find((s) => s.stepId === stepId);
+	if (step === void 0) return null;
+	const chosen = models[stepId];
+	return chosen !== void 0 && chosen !== "" ? chosen : step.defaultModelId;
+}
+//#endregion
 //#region src/pipeline/detail-crop.ts
 /**
 * THE detail-crop convention — the single derivation of the rectangle a
@@ -44448,6 +44848,30 @@ function pickDetailCropConvention(view) {
 	}
 	return readDetailCropConvention(flat);
 }
+/**
+* The normalised box that means "the image IS the subject".
+*
+* Used when the stored pixels are ALREADY the model's input — the 112×112
+* aligned face template a gallery sample carries. There is no rectangle left to
+* choose, and the convention must not choose one: re-detecting and re-aligning
+* over a template applies a SECOND warp, passes every gate, and produces a
+* plausible useless vector (session 2026-08-20 §3).
+*
+* Sending it as the whole frame with this box is exact rather than merely
+* convenient, and the reason is a property of {@link deriveDetailCropRect}, not
+* a coincidence: padding a full-frame box can only push OUTSIDE the frame, and
+* both edge modes bring it straight back — unsquared truncates, squared cannot
+* exceed the frame's short side and then slides inside. So for a SQUARE image
+* the derivation is the identity under every convention value, and an operator
+* changing the crop margin cannot silently re-cut an enrolled template.
+* `face-reembed-pass.spec.ts` asserts that identity against the real function.
+*/
+var FULL_IMAGE_BBOX = Object.freeze({
+	x: 0,
+	y: 0,
+	w: 1,
+	h: 1
+});
 /** Slider bounds for the operator-facing padding knob (orchestrator settings UI). */
 var DETAIL_CROP_PADDING_FIELD = {
 	min: 0,
@@ -46782,6 +47206,8 @@ exports.CAPABILITY_ROUTER_KEYS = CAPABILITY_ROUTER_KEYS;
 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.CLUSTER_MODEL_SCOPED_STEPS = CLUSTER_MODEL_SCOPED_STEPS;
+exports.CLUSTER_MODEL_SECTION_ID = CLUSTER_MODEL_SECTION_ID;
 exports.COCO_80_LABELS = COCO_80_LABELS;
 exports.COCO_TO_MACRO = COCO_TO_MACRO;
 exports.CONNECTION_TEST_TIMEOUT_MS = CONNECTION_TEST_TIMEOUT_MS;
@@ -46869,6 +47295,7 @@ exports.DECLARED_DEVICE_SWEEP_LIMIT = DECLARED_DEVICE_SWEEP_LIMIT;
 exports.DECLARED_INTEGRATION_FIXED_KEY = DECLARED_INTEGRATION_FIXED_KEY;
 exports.DEFAULT_ADDON_PLACEMENT = DEFAULT_ADDON_PLACEMENT;
 exports.DEFAULT_AUDIO_ANALYZER_CONFIG = DEFAULT_AUDIO_ANALYZER_CONFIG;
+exports.DEFAULT_CLUSTER_STEP_MODELS = DEFAULT_CLUSTER_STEP_MODELS;
 exports.DEFAULT_DECODER_HWACCEL_CONFIG = DEFAULT_DECODER_HWACCEL_CONFIG;
 exports.DEFAULT_DETAIL_CROP_CONVENTION = DEFAULT_DETAIL_CROP_CONVENTION;
 exports.DEFAULT_EVENTS_BAND_BUFFER_SEC = DEFAULT_EVENTS_BAND_BUFFER_SEC;
@@ -46987,6 +47414,7 @@ exports.ExpressionGlobalBindingSchema = ExpressionGlobalBindingSchema;
 exports.ExpressionLiteralBindingSchema = ExpressionLiteralBindingSchema;
 exports.ExpressionParseError = ExpressionParseError;
 exports.ExpressionSourceSchema = ExpressionSourceSchema;
+exports.FULL_IMAGE_BBOX = FULL_IMAGE_BBOX;
 exports.FanControlStatusSchema = FanControlStatusSchema;
 exports.FanDirectionSchema = FanDirectionSchema;
 exports.FeatureManifestSchema = FeatureManifestSchema;
@@ -47013,6 +47441,7 @@ exports.HistoryResolutionEnum = HistoryResolutionEnum;
 exports.HumidifierStatusSchema = HumidifierStatusSchema;
 exports.HumiditySensorStatusSchema = HumiditySensorStatusSchema;
 exports.HvacModeSchema = HvacModeSchema;
+exports.INFERENCE_DEVICE_EXCLUSION_REASONS = INFERENCE_DEVICE_EXCLUSION_REASONS;
 exports.ImageContractSchema = ImageContractSchema;
 exports.ImageContractStateSchema = ImageContractStateSchema;
 exports.ImageRotateSchema = ImageRotateSchema;
@@ -47020,6 +47449,7 @@ exports.ImageSettingsOptionsSchema = ImageSettingsOptionsSchema;
 exports.ImageSettingsPatchSchema = ImageSettingsPatchSchema;
 exports.ImageSettingsStatusSchema = ImageSettingsStatusSchema;
 exports.ImageStatusSchema = ImageStatusSchema;
+exports.InferenceDeviceExclusionReasonSchema = InferenceDeviceExclusionReasonSchema;
 exports.IngestOwnerSchema = IngestOwnerSchema;
 exports.InstalledPackageSchema = InstalledPackageSchema;
 exports.IntegrationLiteSchema = IntegrationLiteSchema;
@@ -47232,6 +47662,7 @@ exports.NotificationFormatSchema = NotificationFormatSchema;
 exports.NotificationSchema = NotificationSchema;
 exports.NotifierStatusSchema = NotifierStatusSchema;
 exports.NumericSensorStatusSchema = NumericSensorStatusSchema;
+exports.OPERATOR_WRITTEN_STALE_MS = OPERATOR_WRITTEN_STALE_MS;
 exports.OPS_LOG_DEFAULT_LIMIT = OPS_LOG_DEFAULT_LIMIT;
 exports.OPS_LOG_RING_DEFAULT_MAX = OPS_LOG_RING_DEFAULT_MAX;
 exports.OauthIntegrationDescriptorSchema = OauthIntegrationDescriptorSchema;
@@ -47314,6 +47745,7 @@ exports.RESERVED_BINDING_NAMES = RESERVED_BINDING_NAMES;
 exports.RESTORED_CAP_NAMES = RESTORED_CAP_NAMES;
 exports.RUNTIME_DEFAULTS = RUNTIME_DEFAULTS;
 exports.RUNTIME_STATE_POLICY = RUNTIME_STATE_POLICY;
+exports.RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS = RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS;
 exports.RUNTIME_TO_FORMAT = RUNTIME_TO_FORMAT;
 exports.RawStateResultSchema = require_sleep.RawStateResultSchema;
 exports.ReadGopBytesResultSchema = ReadGopBytesResultSchema;
@@ -47645,6 +48077,7 @@ exports.classifyBearerPrincipal = classifyBearerPrincipal;
 exports.classifyStream = classifyStream;
 exports.classifyStreams = classifyStreams;
 exports.climateControlCapability = climateControlCapability;
+exports.clusterModelSettingKey = clusterModelSettingKey;
 exports.collectHydratedFieldEntries = require_sleep.collectHydratedFieldEntries;
 exports.collectHydratedFieldValues = require_sleep.collectHydratedFieldValues;
 exports.colorCapability = colorCapability;
@@ -47763,6 +48196,7 @@ exports.isAudioLabelSelected = isAudioLabelSelected;
 exports.isAudioRule = isAudioRule;
 exports.isBaseConditionKey = isBaseConditionKey;
 exports.isBatteryPresenceFault = isBatteryPresenceFault;
+exports.isClusterScopedStep = isClusterScopedStep;
 exports.isCollectionArrayMethod = isCollectionArrayMethod;
 exports.isDeployableToAgent = isDeployableToAgent;
 exports.isDetectionMacroClass = isDetectionMacroClass;
@@ -47846,6 +48280,7 @@ exports.parseStreamParamsFormPatch = parseStreamParamsFormPatch;
 exports.patchAudio = patchAudio;
 exports.petFeederCapability = petFeederCapability;
 exports.pickAccessoryControl = pickAccessoryControl;
+exports.pickClusterStepModels = pickClusterStepModels;
 exports.pickDetailCropConvention = pickDetailCropConvention;
 exports.pickNativeLeaseOverride = pickNativeLeaseOverride;
 exports.pickPreferredRtspEntry = pickPreferredRtspEntry;
@@ -47869,6 +48304,7 @@ exports.procedureAuthKey = procedureAuthKey;
 exports.ptzAutotrackCapability = ptzAutotrackCapability;
 exports.ptzCapability = ptzCapability;
 exports.pythonScriptForBackend = pythonScriptForBackend;
+exports.readClusterStepModels = readClusterStepModels;
 exports.readDetailCropConvention = readDetailCropConvention;
 exports.readDeviceStateFrom = readDeviceStateFrom;
 exports.readNativeLeaseOverride = readNativeLeaseOverride;
@@ -47886,6 +48322,7 @@ exports.resolveAddonGroup = resolveAddonGroup;
 exports.resolveAddonPlacement = resolveAddonPlacement;
 exports.resolveAddonRuntime = resolveAddonRuntime;
 exports.resolveCapMount = require_sleep.resolveCapMount;
+exports.resolveClusterStepModelId = resolveClusterStepModelId;
 exports.resolveDetectionRuntime = resolveDetectionRuntime;
 exports.resolveDeviceControlKind = resolveDeviceControlKind;
 exports.resolveDeviceProfile = resolveDeviceProfile;