@camstack/addon-pipeline 1.2.102 → 1.2.104

package/dist/{dist-Ccmt3fGJ.mjs → dist-D9sltFoR.mjs}

@@ -8545,12 +8545,25 @@ var RecordingBandSchema = 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
 };
 DEFAULT_EVENTS_BAND_BUFFER_SEC.postBufferSec * 1e3;
@@ -17883,7 +17896,7 @@ var TrackEnvelopeSchema = 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.).
@@ -18178,6 +18191,35 @@ var TrackSchema = object({
 	*/
 	hasFace: 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: 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.
@@ -19685,6 +19727,26 @@ var DetailResultSchema = object({
 	* the consuming gate treats as accept — never as reject.
 	*/
 	embeddingMagnitude: 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: string().optional(),
 	label: string().optional(),
 	/**
 	* The tier `label` occupies, copied VERBATIM from the producing step's
@@ -21237,6 +21299,7 @@ DeviceType.Camera, method(object({
 		isBattery: boolean(),
 		reason: _enum([
 			"disabled",
+			"offline",
 			"sleeping",
 			"unreachable",
 			"waking"
@@ -21282,9 +21345,17 @@ targets: array(object({
 	sleeping: boolean(),
 	/** Current device state rendered over the cached frame. State images
 	*  remain authoritative even when their photographic background is
-	*  old; null means the link must carry a current camera frame. */
+	*  old; null means the link must carry a current camera frame.
+	*
+	*  **This is the ONLY source a surface may derive an inactive tile
+	*  from.** A client that reads a device's `online`/`disabled` flags and
+	*  draws its own verdict will disagree with the pixels it is painting
+	*  — the frame comes from here, and so must the sentence over it
+	*  (D190). Pair with `ageMs` for the age of the photograph behind the
+	*  state. */
 	stateReason: _enum([
 		"disabled",
+		"offline",
 		"sleeping",
 		"unreachable",
 		"waking"
@@ -36087,6 +36158,153 @@ TimelapseRuleInputSchema.extend({
 	createdAt: number(),
 	updatedAt: number()
 });
+/**
+* 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"
+	}]
+}];
+/**
+* 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}`;
+}
+/** 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 = 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;
+}
 var DETAIL_CROP_PADDING_KEY = "detailCropPaddingRatio";
 var DETAIL_CROP_SQUARE_KEY = "detailCropSquare";
 /**
@@ -36158,6 +36376,12 @@ function pickDetailCropConvention(view) {
 	}
 	return readDetailCropConvention(flat);
 }
+Object.freeze({
+	x: 0,
+	y: 0,
+	w: 1,
+	h: 1
+});
 DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio;
 /**
 * Derive the crop rectangle for one parent detection.
@@ -37140,4 +37364,4 @@ function enumerateInferenceDevices(hw) {
 	return out;
 }
 //#endregion
-export { recordingCapability as $, batteryCapability as A, array as At, egressTranscodeSharingKey as B, EventCategory as Bt, RecordingConfigSchema as C, makeSourceBrokerId as Ct, audioAnalysisCapability as D, selectAssignedProfileSlots as Dt, addonWidgetsSourceCapability as E, parseProfileBrokerId as Et, defineCustomActions as F, number as Ft, mapAudioLabelToMacro as G, enumerateInferenceDevices as H, deriveBatteryPresence as I, object as It, parseProcStatus as J, maskUrlCredentials as K, deriveDetailCropRect as L, record as Lt, createHwAccelCache as M, discriminatedUnion as Mt, customAction as N, lazy as Nt, audioAnalyzerCapability as O, sleep as Ot, defaultDeviceFor as P, literal as Pt, pipelineRunnerCapability as Q, deriveRecordingMode as R, string as Rt, RECORDING_EXPORT_MAX_READ_BYTES as S, makeProfileBrokerId as St, YAMNET_TO_MACRO as T, parseJsonUnknown as Tt, evaluateZoneRules as U, egressTransportFromRequest as V, hfModelUrl as W, pickNativeLeaseOverride as X, pickDetailCropConvention as Y, pipelineExecutorCapability as Z, NativeLeaseSettingsSchema as _, DeviceFeature as _t, COCO_80_LABELS as a, storageEvictableCapability as at, RATE_CONTROL_RELAXED as b, hydrateSchema as bt, DEFAULT_DETAIL_CROP_CONVENTION as c, webrtcSessionCapability as ct, DEVICE_BACKEND_TO_FORMAT as d, Fmp4BoxSplitter as dt, recordingExportCapability as et, EVENT_PAD_MS as f, buildFfmpegArgs as ft, NativeLeaseAdmissionSchema as g, CAM_PROFILE_ORDER as gt, HF_BASE_URL as h, BaseAddon as ht, BatteryStatusSchema as i, runtimeDevices as it, cameraStreamsCapability as j, boolean as jt, audioKindId as k, _enum as kt, DEFAULT_EVENTS_BAND_BUFFER_SEC as l, errMsg as lt, ExportRecordSchema as m, isSoftwareDecode as mt, AUDIO_BACKEND_CHOICES as n, resolvePoolMemoryPolicy as nt, COCO_TO_MACRO as o, streamBrokerCapability as ot, EncodeProfileSchema as p, invocationFromEncodeProfile as pt, motionDetectionCapability as q, AUDIO_MACRO_LABELS as r, resolveRecordingProfiles as rt, DEFAULT_AUDIO_ANALYZER_CONFIG as s, supportedRuntimes as st, APPLE_SA_TO_MACRO as t, resolveEgressDecodeHwAccel as tt, DEFAULT_NATIVE_LEASE_SETTINGS as u, AUDIO_PRESETS as ut, OpsLogEntrySchema as v, DeviceType as vt, RingBuffer as w, nodePin as wt, RATE_CONTROL_TIGHT as x, isEvent as xt, PoolMemoryWatchdog as y, createEvent as yt, detectionPipelineCapability as z, union as zt };
+export { pipelineExecutorCapability as $, audioKindId as A, selectAssignedProfileSlots as At, detectionPipelineCapability as B, record as Bt, RECORDING_EXPORT_MAX_READ_BYTES as C, hydrateSchema as Ct, addonWidgetsSourceCapability as D, nodePin as Dt, YAMNET_TO_MACRO as E, makeSourceBrokerId as Et, defaultDeviceFor as F, discriminatedUnion as Ft, hfModelUrl as G, egressTransportFromRequest as H, union as Ht, defineCustomActions as I, lazy as It, motionDetectionCapability as J, mapAudioLabelToMacro as K, deriveBatteryPresence as L, literal as Lt, cameraStreamsCapability as M, _enum as Mt, createHwAccelCache as N, array as Nt, audioAnalysisCapability as O, parseJsonUnknown as Ot, customAction as P, boolean as Pt, pickNativeLeaseOverride as Q, deriveDetailCropRect as R, number as Rt, RATE_CONTROL_TIGHT as S, createEvent as St, RingBuffer as T, makeProfileBrokerId as Tt, enumerateInferenceDevices as U, EventCategory as Ut, egressTranscodeSharingKey as V, string as Vt, evaluateZoneRules as W, pickClusterStepModels as X, parseProcStatus as Y, pickDetailCropConvention as Z, NativeLeaseAdmissionSchema as _, isSoftwareDecode as _t, COCO_80_LABELS as a, resolvePoolMemoryPolicy as at, PoolMemoryWatchdog as b, DeviceFeature as bt, DEFAULT_CLUSTER_STEP_MODELS as c, storageEvictableCapability as ct, DEFAULT_NATIVE_LEASE_SETTINGS as d, webrtcSessionCapability as dt, pipelineRunnerCapability as et, DEVICE_BACKEND_TO_FORMAT as f, errMsg as ft, HF_BASE_URL as g, invocationFromEncodeProfile as gt, ExportRecordSchema as h, buildFfmpegArgs as ht, BatteryStatusSchema as i, resolveEgressDecodeHwAccel as it, batteryCapability as j, sleep as jt, audioAnalyzerCapability as k, parseProfileBrokerId as kt, DEFAULT_DETAIL_CROP_CONVENTION as l, streamBrokerCapability as lt, EncodeProfileSchema as m, Fmp4BoxSplitter as mt, AUDIO_BACKEND_CHOICES as n, recordingExportCapability as nt, COCO_TO_MACRO as o, resolveRecordingProfiles as ot, EVENT_PAD_MS as p, AUDIO_PRESETS as pt, maskUrlCredentials as q, AUDIO_MACRO_LABELS as r, resolveClusterStepModelId as rt, DEFAULT_AUDIO_ANALYZER_CONFIG as s, runtimeDevices as st, APPLE_SA_TO_MACRO as t, recordingCapability as tt, DEFAULT_EVENTS_BAND_BUFFER_SEC as u, supportedRuntimes as ut, NativeLeaseSettingsSchema as v, BaseAddon as vt, RecordingConfigSchema as w, isEvent as wt, RATE_CONTROL_RELAXED as x, DeviceType as xt, OpsLogEntrySchema as y, CAM_PROFILE_ORDER as yt, deriveRecordingMode as z, object as zt };

package/dist/{dist-C11WuNUP.js → dist-gLAVhbvO.js}

@@ -8568,12 +8568,25 @@ var RecordingBandSchema = 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
 };
 DEFAULT_EVENTS_BAND_BUFFER_SEC.postBufferSec * 1e3;
@@ -17906,7 +17919,7 @@ var TrackEnvelopeSchema = 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.).
@@ -18201,6 +18214,35 @@ var TrackSchema = object({
 	*/
 	hasFace: 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: 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.
@@ -19708,6 +19750,26 @@ var DetailResultSchema = object({
 	* the consuming gate treats as accept — never as reject.
 	*/
 	embeddingMagnitude: 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: string().optional(),
 	label: string().optional(),
 	/**
 	* The tier `label` occupies, copied VERBATIM from the producing step's
@@ -21260,6 +21322,7 @@ DeviceType.Camera, method(object({
 		isBattery: boolean(),
 		reason: _enum([
 			"disabled",
+			"offline",
 			"sleeping",
 			"unreachable",
 			"waking"
@@ -21305,9 +21368,17 @@ targets: array(object({
 	sleeping: boolean(),
 	/** Current device state rendered over the cached frame. State images
 	*  remain authoritative even when their photographic background is
-	*  old; null means the link must carry a current camera frame. */
+	*  old; null means the link must carry a current camera frame.
+	*
+	*  **This is the ONLY source a surface may derive an inactive tile
+	*  from.** A client that reads a device's `online`/`disabled` flags and
+	*  draws its own verdict will disagree with the pixels it is painting
+	*  — the frame comes from here, and so must the sentence over it
+	*  (D190). Pair with `ageMs` for the age of the photograph behind the
+	*  state. */
 	stateReason: _enum([
 		"disabled",
+		"offline",
 		"sleeping",
 		"unreachable",
 		"waking"
@@ -36110,6 +36181,153 @@ TimelapseRuleInputSchema.extend({
 	createdAt: number(),
 	updatedAt: number()
 });
+/**
+* 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"
+	}]
+}];
+/**
+* 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}`;
+}
+/** 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 = 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;
+}
 var DETAIL_CROP_PADDING_KEY = "detailCropPaddingRatio";
 var DETAIL_CROP_SQUARE_KEY = "detailCropSquare";
 /**
@@ -36181,6 +36399,12 @@ function pickDetailCropConvention(view) {
 	}
 	return readDetailCropConvention(flat);
 }
+Object.freeze({
+	x: 0,
+	y: 0,
+	w: 1,
+	h: 1
+});
 DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio;
 /**
 * Derive the crop rectangle for one parent detection.
@@ -37223,6 +37447,12 @@ Object.defineProperty(exports, "DEFAULT_AUDIO_ANALYZER_CONFIG", {
 		return DEFAULT_AUDIO_ANALYZER_CONFIG;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_CLUSTER_STEP_MODELS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_CLUSTER_STEP_MODELS;
+	}
+});
 Object.defineProperty(exports, "DEFAULT_DETAIL_CROP_CONVENTION", {
 	enumerable: true,
 	get: function() {
@@ -37625,6 +37855,12 @@ Object.defineProperty(exports, "parseProfileBrokerId", {
 		return parseProfileBrokerId;
 	}
 });
+Object.defineProperty(exports, "pickClusterStepModels", {
+	enumerable: true,
+	get: function() {
+		return pickClusterStepModels;
+	}
+});
 Object.defineProperty(exports, "pickDetailCropConvention", {
 	enumerable: true,
 	get: function() {
@@ -37667,6 +37903,12 @@ Object.defineProperty(exports, "recordingExportCapability", {
 		return recordingExportCapability;
 	}
 });
+Object.defineProperty(exports, "resolveClusterStepModelId", {
+	enumerable: true,
+	get: function() {
+		return resolveClusterStepModelId;
+	}
+});
 Object.defineProperty(exports, "resolveEgressDecodeHwAccel", {
 	enumerable: true,
 	get: function() {