@camstack/addon-post-analysis 1.2.104 → 1.2.106

package/dist/{dist-IZLiqXRa.mjs → dist-DiU9qiuA.mjs}

@@ -7790,7 +7790,7 @@ var RecordingBandSchema = object({
 * visit is derived, not a second copy of the files.
 */
 var VISIT_MERGE_GAP_MS = {
-	preBufferSec: 10,
+	preBufferSec: 15,
 	postBufferSec: 30
 }.postBufferSec * 1e3;
 /**
@@ -17208,7 +17208,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.).
@@ -17503,6 +17503,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.
@@ -19299,6 +19328,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
@@ -38885,6 +38934,140 @@ function readTimelapseGeneratedAt(rule, deviceId) {
 	if (map !== void 0) return map[String(deviceId)] ?? 0;
 	return rule.lastGeneratedAt ?? 0;
 }
+/**
+* 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);
+}
 object({
 	/**
 	* Fraction of the box's own size added on EACH side before cutting.
@@ -38905,10 +39088,39 @@ object({
 	*/
 	square: boolean()
 });
-({
+/**
+* The convention in force when nobody has configured one — byte-for-byte the
+* behaviour of the pre-unification LIVE path (`DETAIL_CROP_PADDING_RATIO`).
+*/
+var DEFAULT_DETAIL_CROP_CONVENTION = {
 	paddingRatio: .15,
 	square: false
-}).paddingRatio;
+};
+/**
+* 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
+});
+DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio;
 /**
 * WHICH delivered frames the decode worker retains a native copy of.
 *
@@ -39364,4 +39576,4 @@ function vectorDimFromBase64(encoded) {
 	return Math.floor(Buffer.from(encoded, "base64").byteLength / 4);
 }
 //#endregion
-export { encodeVectorBase64 as $, RetrainStatusSchema as A, literal as At, TrackSourceSchema as B, NcSnoozeSchema as C, isDeviceScopedCap as Ct, OpsLogEntrySchema as D, array as Dt, NcTaxonomySchema as E, _enum as Et, SceneMonitorSchema as F, string as Ft, audioMetricsCapability as G, addonWidgetsSourceCapability as H, TIMELAPSE_DENSE_FLOOR_SEC as I, unknown as It, cosineSimilarity as J, audioModeOf as K, TimelapseRuleInputSchema as L, EventCategory as Lt, SCENE_DEFAULT_ANCHOR_THRESHOLD as M, object as Mt, SCENE_DEFAULT_UNCOVERED_POLICY as N, partialRecord as Nt, PoolMemoryWatchdog as O, boolean as Ot, SCENE_DIVERGED as P, record as Pt, embeddingEncoderCapability as Q, TimelapseRulePatchSchema as R, NcSnoozeInputSchema as S, hydrateSchema as St, NcSystemEventKindSchema as T, sleep as Tt, alarmPanelCapability as U, VISIT_MERGE_GAP_MS as V, assertTimelapseCadences as W, defineCustomActions as X, customAction as Y, deriveRecordingMode as Z, NcRuleInputSchema as _, zoneAnalyticsCapability as _t, DETECTION_PIPELINE_CAP_NAME as a, notificationRulesCapability as at, NcRuleTargetSchema as b, DeviceType as bt, EVENT_PAD_MS as c, plateGalleryCapability as ct, NC_ALARM_SYSTEM_EVENT_KINDS as d, resolvePoolMemoryPolicy as dt, faceGalleryCapability as et, NC_CONDITION_CATALOG as f, sceneMonitorCapability as ft, NcConditionDescriptorSchema as g, videoclipsCapability as gt, NC_TAXONOMY as h, vectorDimFromBase64 as ht, DETECTION_MACRO_CLASSES as i, kebabToCamel as it, SCENE_CONFIRM_DEFAULT_TIMEOUT_MS as j, number as jt, RECORDING_EXPORT_MAX_READ_BYTES as k, discriminatedUnion as kt, LabelAttributionSchema as l, readDeviceStateFrom as lt, NC_SNOOZE_MAX_MINUTES as m, systemEventFilterApplies as mt, DEFAULT_EVENT_COLOR as n, isDetectionMacroClass as nt, DeclaredDevices as o, parseProcStatus as ot, NC_DEFAULT_SNOOZE_MINUTES as p, subKindsOf as pt, buildEventKindDescriptor as q, DEFAULT_TIMELAPSE_PREVIEW_TEXT as r, isScheduleActive as rt, EVENT_KIND_BY_CAP as s, pipelineAnalyticsCapability as st, BaseDevice as t, hfModelUrl as tt, MACRO_LABELS as u, readTimelapseGeneratedAt as ut, NcRulePatchSchema as v, errMsg as vt, NcSnoozeSuppressedSchema as w, nodePin as wt, NcScheduleSchema as x, createEvent as xt, NcRuleSchema as y, BaseAddon as yt, TimelapseRuleSchema as z };
+export { deriveRecordingMode as $, PoolMemoryWatchdog as A, array as At, TimelapseRulePatchSchema as B, EventCategory as Bt, NcScheduleSchema as C, DeviceType as Ct, NcSystemEventKindSchema as D, nodePin as Dt, NcSnoozeSuppressedSchema as E, isDeviceScopedCap as Et, SCENE_DEFAULT_UNCOVERED_POLICY as F, object as Ft, alarmPanelCapability as G, TrackSourceSchema as H, SCENE_DIVERGED as I, partialRecord as It, audioModeOf as J, assertTimelapseCadences as K, SceneMonitorSchema as L, record as Lt, RetrainStatusSchema as M, discriminatedUnion as Mt, SCENE_CONFIRM_DEFAULT_TIMEOUT_MS as N, literal as Nt, NcTaxonomySchema as O, sleep as Ot, SCENE_DEFAULT_ANCHOR_THRESHOLD as P, number as Pt, defineCustomActions as Q, TIMELAPSE_DENSE_FLOOR_SEC as R, string as Rt, NcRuleTargetSchema as S, BaseAddon as St, NcSnoozeSchema as T, hydrateSchema as Tt, VISIT_MERGE_GAP_MS as U, TimelapseRuleSchema as V, addonWidgetsSourceCapability as W, cosineSimilarity as X, buildEventKindDescriptor as Y, customAction as Z, NC_TAXONOMY as _, systemEventFilterApplies as _t, DETECTION_MACRO_CLASSES as a, isScheduleActive as at, NcRulePatchSchema as b, zoneAnalyticsCapability as bt, EVENT_KIND_BY_CAP as c, parseProcStatus as ct, LabelAttributionSchema as d, plateGalleryCapability as dt, embeddingEncoderCapability as et, MACRO_LABELS as f, readDeviceStateFrom as ft, NC_SNOOZE_MAX_MINUTES as g, subKindsOf as gt, NC_DEFAULT_SNOOZE_MINUTES as h, sceneMonitorCapability as ht, DEFAULT_TIMELAPSE_PREVIEW_TEXT as i, isDetectionMacroClass as it, RECORDING_EXPORT_MAX_READ_BYTES as j, boolean as jt, OpsLogEntrySchema as k, _enum as kt, EVENT_PAD_MS as l, pickClusterStepModels as lt, NC_CONDITION_CATALOG as m, resolvePoolMemoryPolicy as mt, CLUSTER_MODEL_SCOPED_STEPS as n, faceGalleryCapability as nt, DETECTION_PIPELINE_CAP_NAME as o, kebabToCamel as ot, NC_ALARM_SYSTEM_EVENT_KINDS as p, readTimelapseGeneratedAt as pt, audioMetricsCapability as q, DEFAULT_EVENT_COLOR as r, hfModelUrl as rt, DeclaredDevices as s, notificationRulesCapability as st, BaseDevice as t, encodeVectorBase64 as tt, FULL_IMAGE_BBOX as u, pipelineAnalyticsCapability as ut, NcConditionDescriptorSchema as v, vectorDimFromBase64 as vt, NcSnoozeInputSchema as w, createEvent as wt, NcRuleSchema as x, errMsg as xt, NcRuleInputSchema as y, videoclipsCapability as yt, TimelapseRuleInputSchema as z, unknown as zt };

package/dist/{dist-KXhjlCmh.js → dist-FAVcx3hJ.js}

@@ -7821,7 +7821,7 @@ var RecordingBandSchema = object({
 * visit is derived, not a second copy of the files.
 */
 var VISIT_MERGE_GAP_MS = {
-	preBufferSec: 10,
+	preBufferSec: 15,
 	postBufferSec: 30
 }.postBufferSec * 1e3;
 /**
@@ -17239,7 +17239,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.).
@@ -17534,6 +17534,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.
@@ -19330,6 +19359,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
@@ -38916,6 +38965,140 @@ function readTimelapseGeneratedAt(rule, deviceId) {
 	if (map !== void 0) return map[String(deviceId)] ?? 0;
 	return rule.lastGeneratedAt ?? 0;
 }
+/**
+* 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);
+}
 object({
 	/**
 	* Fraction of the box's own size added on EACH side before cutting.
@@ -38936,10 +39119,39 @@ object({
 	*/
 	square: boolean()
 });
-({
+/**
+* The convention in force when nobody has configured one — byte-for-byte the
+* behaviour of the pre-unification LIVE path (`DETAIL_CROP_PADDING_RATIO`).
+*/
+var DEFAULT_DETAIL_CROP_CONVENTION = {
 	paddingRatio: .15,
 	square: false
-}).paddingRatio;
+};
+/**
+* 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
+});
+DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio;
 /**
 * WHICH delivered frames the decode worker retains a native copy of.
 *
@@ -39407,6 +39619,12 @@ Object.defineProperty(exports, "BaseDevice", {
 		return BaseDevice;
 	}
 });
+Object.defineProperty(exports, "CLUSTER_MODEL_SCOPED_STEPS", {
+	enumerable: true,
+	get: function() {
+		return CLUSTER_MODEL_SCOPED_STEPS;
+	}
+});
 Object.defineProperty(exports, "DEFAULT_EVENT_COLOR", {
 	enumerable: true,
 	get: function() {
@@ -39461,6 +39679,12 @@ Object.defineProperty(exports, "EventCategory", {
 		return EventCategory;
 	}
 });
+Object.defineProperty(exports, "FULL_IMAGE_BBOX", {
+	enumerable: true,
+	get: function() {
+		return FULL_IMAGE_BBOX;
+	}
+});
 Object.defineProperty(exports, "LabelAttributionSchema", {
 	enumerable: true,
 	get: function() {
@@ -39863,6 +40087,12 @@ Object.defineProperty(exports, "partialRecord", {
 		return partialRecord;
 	}
 });
+Object.defineProperty(exports, "pickClusterStepModels", {
+	enumerable: true,
+	get: function() {
+		return pickClusterStepModels;
+	}
+});
 Object.defineProperty(exports, "pipelineAnalyticsCapability", {
 	enumerable: true,
 	get: function() {