@camstack/addon-export-hap 1.2.15 → 1.2.16

package/dist/export-hap.addon.js

@@ -15546,6 +15546,60 @@ var TrackFlagsSchema = object({
 	*  `trained` without a re-fetch. */
 	retrainStatus: RetrainStatusSchema
 });
+union([literal(1), literal(2)]);
+/**
+* WHO decided a label, and when. Carried per tier so a value can be traced to
+* the step and model that produced it — which is what makes the write rule
+* arguable after the fact ("why is 592's label `dog` and not `Canis lupus`?")
+* and what lets a migrated, UNATTRIBUTED value be told apart from a real one.
+*
+* `stepId` is the pipeline step id (`animal-classifier`, `bird-classifier`,
+* `plate-ocr`, `face-embedding`, `object-detection`), or the sentinel
+* `migration:4g` for a value the 4g migration moved from the single-slot era —
+* that value has no provenance, and the write rule lets ANY properly-attributed
+* write of the same tier replace it regardless of score.
+*/
+var LabelAttributionSchema = object({
+	stepId: string(),
+	modelId: string().optional(),
+	decidedAt: number()
+});
+/**
+* The TIERED label model (roadmap 4g), spread into `TrackSchema` and
+* `ObjectEventSchema` from ONE place so the two surfaces cannot drift — a
+* track and its events always answer the same question the same way.
+*
+* Two scalar columns, not an array: every consumer wants "the coarse one" or
+* "the fine one", and an array made both a scan. `label` is tier 1, `subLabel`
+* is tier 2, and each carries its own score + attribution.
+*
+* **Reading it.** What a human should be shown is `subLabel ?? label` — the
+* finest thing known. Before 4g the single `label` column held the finest
+* value, so a consumer that has not been updated reads the tier-1 slot and
+* shows nothing on a species-only row; that is why the migration puts every
+* pre-4g value in tier 2 (it cannot regress a display that reads the fallback)
+* and why the read surfaces were changed in the same train.
+*
+* **Writing it.** The slots are independent, which is the whole point: a
+* tier-1 write (`bird`) can never overwrite a tier-2 value (`Turdus
+* migratorius`), so fineness cannot regress by construction. Within a tier the
+* higher score wins. One rule, one implementation — see
+* `pipeline/label-tier.ts` in addon-post-analysis.
+*/
+var TieredLabelFields = {
+	/** Tier 1 — the sub-class. See {@link LabelTierSchema}. */
+	label: string().optional(),
+	/** Confidence of the tier-1 value, as reported by the deciding step. */
+	labelScore: number().optional(),
+	/** Provenance of the tier-1 value. See {@link LabelAttributionSchema}. */
+	labelMeta: LabelAttributionSchema.optional(),
+	/** Tier 2 — the instance. See {@link LabelTierSchema}. */
+	subLabel: string().optional(),
+	/** Confidence of the tier-2 value, as reported by the deciding step. */
+	subLabelScore: number().optional(),
+	/** Provenance of the tier-2 value. See {@link LabelAttributionSchema}. */
+	subLabelMeta: LabelAttributionSchema.optional()
+};
 /** Per-camera slice of a training-export estimate. */
 var TrainingExportDeviceTotalsSchema = object({
 	deviceId: number(),
@@ -15570,7 +15624,7 @@ var TrackSchema = object({
 	trackId: string(),
 	deviceId: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	producingDeviceName: string().optional(),
 	/** Track provenance. Absent ⇒ `pipeline` (legacy rows). */
 	source: TrackSourceSchema.optional(),
@@ -15683,7 +15737,7 @@ var ObjectEventSchema = object({
 	/** Omitted in slim projection. */
 	trackId: string().optional(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	/** Omitted in slim projection. */
 	confidence: number().optional(),
 	/** Heavy JSON — omitted in slim projection. */
@@ -15764,6 +15818,173 @@ var MediaFileSchema = object({
 * stored blob and a `?variant=thumb` rendering without fetching either.
 */
 var MediaFileInfoSchema = MediaFileSchema.omit({ base64: true });
+/**
+* The MACRO tier of an annotation — a CLOSED set.
+*
+* This is what the exported detector predicts, so a typo here is a new class
+* with one example in it. `label` and `subLabel` are open strings by contrast:
+* the whole point of the page is teaching the model things it does not know
+* yet, and constraining that vocabulary would make it useless.
+*
+* A macro class is NEVER a label. The provider refuses a write whose `label` or
+* `subLabel` is one of these values, in any casing, because once `person`
+* exists in both tiers "every person box" stops being answerable without
+* knowing every string anyone ever typed — and the damage is retroactive.
+*/
+var RetrainMacroClassSchema = _enum([
+	"person",
+	"vehicle",
+	"animal",
+	"package",
+	"face",
+	"plate"
+]);
+/** A subject to learn, or a phantom to unlearn (taught by OMISSION). */
+var RetrainAnnotationKindSchema = _enum(["subject", "model_error"]);
+/** Did a human draw this box, or did the assist propose it? */
+var RetrainAnnotationSourceSchema = _enum(["operator", "assist"]);
+/** Normalised `[0,1]` rectangle against the FULL frame — the canonical form. */
+var RetrainBboxSchema = object({
+	x: number(),
+	y: number(),
+	w: number(),
+	h: number()
+});
+/**
+* One annotated subject.
+*
+* `bbox` is normalised against the full frame, ALWAYS. The per-model shapes
+* (letterboxed root / zone-cropped package / subject-cropped classifier) are
+* derived from it at export and never stored — storing them is how one feature
+* space ends up holding two crops of the same subject (D52).
+*/
+var RetrainAnnotationSchema = object({
+	id: string(),
+	trackId: string(),
+	deviceId: number(),
+	/** The COPY in retrain storage — never the source track's media key. */
+	mediaKey: string(),
+	bbox: RetrainBboxSchema,
+	macroClass: RetrainMacroClassSchema,
+	label: string().optional(),
+	subLabel: string().optional(),
+	kind: RetrainAnnotationKindSchema,
+	source: RetrainAnnotationSourceSchema,
+	/** Which model proposed this box — or, on a `model_error`, drew the phantom. */
+	assistModelId: string().optional(),
+	assistScore: number().optional(),
+	exportedInBatch: string().optional(),
+	createdAt: number()
+});
+/** The write form — the server owns `id`, `createdAt` and the frame binding. */
+var RetrainAnnotationDraftSchema = RetrainAnnotationSchema.omit({
+	id: true,
+	trackId: true,
+	deviceId: true,
+	mediaKey: true,
+	createdAt: true,
+	exportedInBatch: true
+});
+/** A track sitting in `staging`, with everything the worklist needs to rank it. */
+var RetrainTrackSchema = object({
+	trackId: string(),
+	deviceId: number(),
+	className: string(),
+	label: string().optional(),
+	firstSeen: number(),
+	lastSeen: number(),
+	/** How many frames the dataset already holds from this track. */
+	frameCount: number().int(),
+	/** How many subjects have been annotated on those frames. `0` with
+	*  `frameCount: 0` is exactly "staging, still to work". */
+	annotationCount: number().int()
+});
+/** A frame the picker may offer — an index row, no blob was read to produce it. */
+var RetrainFrameCandidateSchema = object({
+	mediaKey: string(),
+	kind: MediaFileKindEnum,
+	timestamp: number(),
+	sizeBytes: number().int(),
+	/** A copy of this original already exists — selecting it is free and cannot
+	*  fail, whatever became of the original. */
+	copied: boolean()
+});
+/** A frame the dataset OWNS: bytes copied at selection time. */
+var RetrainFrameSchema = object({
+	frameId: string(),
+	deviceId: number(),
+	trackId: string(),
+	/** Provenance only. It may already point at nothing — that is expected. */
+	sourceMediaKey: string(),
+	sourceKind: MediaFileKindEnum,
+	sizeBytes: number().int(),
+	width: number().int(),
+	height: number().int(),
+	copiedAt: number()
+});
+/** Why a copy-on-select could not be honoured — named, never a silent skip. */
+var RetrainCopyRefusalSchema = _enum([
+	"source-missing",
+	"unreadable-image",
+	"write-failed"
+]);
+var RetrainFrameSelectionSchema = object({
+	copied: array(RetrainFrameSchema).readonly(),
+	refused: array(object({
+		sourceMediaKey: string(),
+		reason: RetrainCopyRefusalSchema
+	})).readonly()
+});
+var RetrainFrameListSchema = object({
+	candidates: array(RetrainFrameCandidateSchema).readonly(),
+	copies: array(RetrainFrameSchema).readonly(),
+	/** What the page pre-selects — the native key frame when one survives. */
+	autoPickMediaKey: string().optional()
+});
+/** What the operator asked the assist to look for. */
+var RetrainAssistSubjectSchema = discriminatedUnion("kind", [object({
+	kind: literal("package"),
+	zone: RetrainBboxSchema.optional()
+}), object({
+	kind: literal("objects"),
+	modelId: string(),
+	minScore: number().optional()
+})]);
+/**
+* The assist's answer — a discriminated union, because "the model saw nothing"
+* and "this node cannot run that model" lead to different next moves and a
+* nullable result cannot tell them apart.
+*/
+var RetrainAssistResultSchema = discriminatedUnion("kind", [object({
+	kind: literal("proposed"),
+	modelId: string(),
+	stepId: string(),
+	minScore: number(),
+	/** Drafts, ready to edit. `source: 'assist'` until the operator touches one. */
+	proposals: array(RetrainAnnotationDraftSchema).readonly(),
+	/** Returned by the runner but removed by the threshold. */
+	belowThreshold: number().int()
+}), object({
+	kind: literal("refused"),
+	/** `no-zone` is ours; the rest are the runner's own refusal vocabulary. */
+	reason: string(),
+	detail: string().optional()
+})]);
+/** The outcome of a lifecycle move owned by the retrain page. */
+var RetrainTransitionResultSchema = object({
+	trackId: string(),
+	/** Where the track ended up, whatever happened. */
+	retrainStatus: RetrainStatusSchema,
+	/** `false` ⇒ the move was refused or was a no-op; `reason` says which. */
+	changed: boolean(),
+	reason: _enum([
+		"unknown-track",
+		"no-frames-copied",
+		"not-staging",
+		"not-trained",
+		"unchanged"
+	]).optional()
+});
 var DEFAULT_EVENT_QUERY_LIMIT = 1e3;
 var MAX_EVENT_QUERY_LIMIT = 5e3;
 var DeviceEventQueryInput = object({
@@ -15818,7 +16039,7 @@ var KeyEventSchema = object({
 	/** Track start time (firstSeen). */
 	timestamp: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	importance: number(),
 	/** Highest-confidence ObjectEvent id for the track (empty when none). */
 	bestEventId: string(),
@@ -16092,6 +16313,79 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
 	kind: "query",
 	auth: "admin"
+}), method(object({
+	/** Empty ⇒ every camera that has staging tracks. A LIST, not a single
+	*  `deviceId`, deliberately: `deviceId` would make this device-bound and
+	*  route it at one camera's owner, and "every camera" would stop being
+	*  expressible at all. */
+	deviceIds: array(number()).optional(),
+	limit: number().int().min(1).max(500).optional()
+}), array(RetrainTrackSchema).readonly(), {
+	kind: "query",
+	auth: "admin"
+}), method(object({ trackId: string() }), RetrainFrameListSchema, {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	mediaKeys: array(string()).min(1)
+}), RetrainFrameSelectionSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string()
+}), object({
+	removed: boolean(),
+	removedAnnotations: number().int()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ frameId: string() }), object({
+	base64: string(),
+	width: number().int(),
+	height: number().int()
+}), {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string(),
+	subject: RetrainAssistSubjectSchema,
+	/** Which node runs it. Absent ⇒ wherever an unowned call lands. */
+	nodeId: string().optional()
+}), RetrainAssistResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ trackId: string() }), array(RetrainAnnotationSchema).readonly(), {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string(),
+	annotations: array(RetrainAnnotationDraftSchema)
+}), array(RetrainAnnotationSchema).readonly(), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string()
+}), RetrainTransitionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string()
+}), RetrainTransitionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
+	kind: "query",
+	auth: "admin"
 }), method(object({
 	eventId: string(),
 	kind: MediaFileKindEnum.optional()
@@ -16671,6 +16965,22 @@ var DetailResultSchema = object({
 	bbox: NativeCropBboxSchema.optional(),
 	embedding: string().optional(),
 	label: string().optional(),
+	/**
+	* The tier `label` occupies, copied VERBATIM from the producing step's
+	* `StepDefinition.labelTier` (roadmap 4g). Present only when `label` is.
+	*
+	* It rides the wire rather than being resolved by the consumer because the
+	* declaration lives with the step definition, which only the executing node
+	* has: post-analysis holds no step registry, and re-deriving the tier from
+	* `className` there would be exactly the inference this model exists to
+	* forbid. A `label` that arrives WITHOUT this field is refused by the write
+	* rule and logged (`label tier undeclared`) — an older runner therefore
+	* stops enriching rather than guessing, which is why addon-pipeline is
+	* deployed BEFORE addon-post-analysis.
+	*/
+	labelTier: union([literal(1), literal(2)]).optional(),
+	/** Model that produced `label` — carried into the tier's attribution. */
+	labelModelId: string().optional(),
 	alignedCropJpeg: string().optional(),
 	/** Face short side (px) measured on the NATIVE crop surface. The `bbox`
 	*  above is detection-frame px (≈6× smaller on a 4K camera) — min-face-size
@@ -26988,6 +27298,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.completeRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.deleteDeviceEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27000,6 +27316,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.deselectRetrainFrame": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.getActiveTracks": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27060,6 +27382,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getRetrainExportUrl": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.getRetrainFrameImage": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.getSensorEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27114,6 +27448,24 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainStaging": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listTrackMedia": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27126,6 +27478,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.proposeRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.pruneEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27156,12 +27514,30 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.restageRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineAnalytics.saveRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.searchObjectEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.selectRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.setTrackFlags": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -45421,8 +45797,21 @@ function syncStateToJson(map) {
 */
 var DEFAULT_DEVICE_SETTINGS = {
 	streamPreference: "auto",
-	hksvRecording: false
+	hksvRecording: true
 };
+/**
+* ON unless explicitly switched off — operator decision 2026-08-08 (flipped
+* from the launch default of off). ABSENT must resolve to ON or the flip is a
+* lie for every entry persisted before the field existed, so every read goes
+* through this one resolver (`!== false`), never a scattered `=== true`. The
+* cost that made off-by-default look prudent is measured and small on the only
+* branch the recorder accepts (copy: 0.7 % of a core / ~30 MB RSS, D84), and a
+* camera the recorder cannot copy refuses recording with a logged reason
+* rather than paying for a transcode.
+*/
+function resolveHksvRecording(settings) {
+	return settings?.hksvRecording !== false;
+}
 var HAP_STREAM_PREFERENCE_OPTIONS = [
 	{
 		value: "auto",
@@ -45699,7 +46088,7 @@ var ExportHapAddon = class extends BaseAddon {
 				decodeMemos: this.decodeMemos,
 				hapDeviceSettings: {
 					streamPreference: entrySettings.streamPreference ?? "auto",
-					hksvRecording: entrySettings.hksvRecording === true
+					hksvRecording: resolveHksvRecording(entrySettings)
 				}
 			}
 		});
@@ -46050,7 +46439,7 @@ var ExportHapAddon = class extends BaseAddon {
 						label: "HomeKit recording (Secure Video)",
 						description: "Offer “Stream and Allow Recording” in iOS Home. Requires iCloud+ and a home hub. Keeps a continuous 8s prebuffer for this camera (~0.7% of one CPU core, H.264 sources only).",
 						style: "switch",
-						value: settings.hksvRecording === true,
+						value: resolveHksvRecording(settings),
 						showWhen: {
 							field: enabledKey,
 							equals: true
@@ -46084,7 +46473,7 @@ var ExportHapAddon = class extends BaseAddon {
 		const enabledValue = enabledKey in patch ? Boolean(patch[enabledKey]) : wasEnabled;
 		const streamPreferenceRaw = streamPreferenceKey in patch ? patch[streamPreferenceKey] : current?.settings?.streamPreference;
 		const streamPreference = typeof streamPreferenceRaw === "string" && streamPreferenceRaw.trim().length > 0 ? streamPreferenceRaw : "auto";
-		const hksvRecording = hksvKey in patch ? Boolean(patch[hksvKey]) : current?.settings?.hksvRecording === true;
+		const hksvRecording = hksvKey in patch ? Boolean(patch[hksvKey]) : resolveHksvRecording(current?.settings);
 		const nextSettings = {
 			...current?.settings ?? DEFAULT_DEVICE_SETTINGS,
 			streamPreference,
@@ -46100,7 +46489,7 @@ var ExportHapAddon = class extends BaseAddon {
 			return { success: true };
 		}
 		const currentPref = current?.settings?.streamPreference ?? "auto";
-		const currentHksv = current?.settings?.hksvRecording === true;
+		const currentHksv = resolveHksvRecording(current?.settings);
 		await this.updateEntrySettings(deviceIdStr, nextSettings);
 		if (currentPref !== streamPreference || currentHksv !== hksvRecording) {
 			log.info("export-hap: per-camera export settings changed — refreshing accessory", { meta: {
@@ -46160,4 +46549,5 @@ exports.default = ExportHapAddon;
 exports.deriveUsername = deriveUsername;
 exports.initHapStorage = initHapStorage;
 exports.publishStandalone = publishStandalone;
+exports.resolveHksvRecording = resolveHksvRecording;
 exports.unpublishAccessory = unpublishAccessory;

package/dist/export-hap.addon.mjs

@@ -15520,6 +15520,60 @@ var TrackFlagsSchema = object({
 	*  `trained` without a re-fetch. */
 	retrainStatus: RetrainStatusSchema
 });
+union([literal(1), literal(2)]);
+/**
+* WHO decided a label, and when. Carried per tier so a value can be traced to
+* the step and model that produced it — which is what makes the write rule
+* arguable after the fact ("why is 592's label `dog` and not `Canis lupus`?")
+* and what lets a migrated, UNATTRIBUTED value be told apart from a real one.
+*
+* `stepId` is the pipeline step id (`animal-classifier`, `bird-classifier`,
+* `plate-ocr`, `face-embedding`, `object-detection`), or the sentinel
+* `migration:4g` for a value the 4g migration moved from the single-slot era —
+* that value has no provenance, and the write rule lets ANY properly-attributed
+* write of the same tier replace it regardless of score.
+*/
+var LabelAttributionSchema = object({
+	stepId: string(),
+	modelId: string().optional(),
+	decidedAt: number()
+});
+/**
+* The TIERED label model (roadmap 4g), spread into `TrackSchema` and
+* `ObjectEventSchema` from ONE place so the two surfaces cannot drift — a
+* track and its events always answer the same question the same way.
+*
+* Two scalar columns, not an array: every consumer wants "the coarse one" or
+* "the fine one", and an array made both a scan. `label` is tier 1, `subLabel`
+* is tier 2, and each carries its own score + attribution.
+*
+* **Reading it.** What a human should be shown is `subLabel ?? label` — the
+* finest thing known. Before 4g the single `label` column held the finest
+* value, so a consumer that has not been updated reads the tier-1 slot and
+* shows nothing on a species-only row; that is why the migration puts every
+* pre-4g value in tier 2 (it cannot regress a display that reads the fallback)
+* and why the read surfaces were changed in the same train.
+*
+* **Writing it.** The slots are independent, which is the whole point: a
+* tier-1 write (`bird`) can never overwrite a tier-2 value (`Turdus
+* migratorius`), so fineness cannot regress by construction. Within a tier the
+* higher score wins. One rule, one implementation — see
+* `pipeline/label-tier.ts` in addon-post-analysis.
+*/
+var TieredLabelFields = {
+	/** Tier 1 — the sub-class. See {@link LabelTierSchema}. */
+	label: string().optional(),
+	/** Confidence of the tier-1 value, as reported by the deciding step. */
+	labelScore: number().optional(),
+	/** Provenance of the tier-1 value. See {@link LabelAttributionSchema}. */
+	labelMeta: LabelAttributionSchema.optional(),
+	/** Tier 2 — the instance. See {@link LabelTierSchema}. */
+	subLabel: string().optional(),
+	/** Confidence of the tier-2 value, as reported by the deciding step. */
+	subLabelScore: number().optional(),
+	/** Provenance of the tier-2 value. See {@link LabelAttributionSchema}. */
+	subLabelMeta: LabelAttributionSchema.optional()
+};
 /** Per-camera slice of a training-export estimate. */
 var TrainingExportDeviceTotalsSchema = object({
 	deviceId: number(),
@@ -15544,7 +15598,7 @@ var TrackSchema = object({
 	trackId: string(),
 	deviceId: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	producingDeviceName: string().optional(),
 	/** Track provenance. Absent ⇒ `pipeline` (legacy rows). */
 	source: TrackSourceSchema.optional(),
@@ -15657,7 +15711,7 @@ var ObjectEventSchema = object({
 	/** Omitted in slim projection. */
 	trackId: string().optional(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	/** Omitted in slim projection. */
 	confidence: number().optional(),
 	/** Heavy JSON — omitted in slim projection. */
@@ -15738,6 +15792,173 @@ var MediaFileSchema = object({
 * stored blob and a `?variant=thumb` rendering without fetching either.
 */
 var MediaFileInfoSchema = MediaFileSchema.omit({ base64: true });
+/**
+* The MACRO tier of an annotation — a CLOSED set.
+*
+* This is what the exported detector predicts, so a typo here is a new class
+* with one example in it. `label` and `subLabel` are open strings by contrast:
+* the whole point of the page is teaching the model things it does not know
+* yet, and constraining that vocabulary would make it useless.
+*
+* A macro class is NEVER a label. The provider refuses a write whose `label` or
+* `subLabel` is one of these values, in any casing, because once `person`
+* exists in both tiers "every person box" stops being answerable without
+* knowing every string anyone ever typed — and the damage is retroactive.
+*/
+var RetrainMacroClassSchema = _enum([
+	"person",
+	"vehicle",
+	"animal",
+	"package",
+	"face",
+	"plate"
+]);
+/** A subject to learn, or a phantom to unlearn (taught by OMISSION). */
+var RetrainAnnotationKindSchema = _enum(["subject", "model_error"]);
+/** Did a human draw this box, or did the assist propose it? */
+var RetrainAnnotationSourceSchema = _enum(["operator", "assist"]);
+/** Normalised `[0,1]` rectangle against the FULL frame — the canonical form. */
+var RetrainBboxSchema = object({
+	x: number(),
+	y: number(),
+	w: number(),
+	h: number()
+});
+/**
+* One annotated subject.
+*
+* `bbox` is normalised against the full frame, ALWAYS. The per-model shapes
+* (letterboxed root / zone-cropped package / subject-cropped classifier) are
+* derived from it at export and never stored — storing them is how one feature
+* space ends up holding two crops of the same subject (D52).
+*/
+var RetrainAnnotationSchema = object({
+	id: string(),
+	trackId: string(),
+	deviceId: number(),
+	/** The COPY in retrain storage — never the source track's media key. */
+	mediaKey: string(),
+	bbox: RetrainBboxSchema,
+	macroClass: RetrainMacroClassSchema,
+	label: string().optional(),
+	subLabel: string().optional(),
+	kind: RetrainAnnotationKindSchema,
+	source: RetrainAnnotationSourceSchema,
+	/** Which model proposed this box — or, on a `model_error`, drew the phantom. */
+	assistModelId: string().optional(),
+	assistScore: number().optional(),
+	exportedInBatch: string().optional(),
+	createdAt: number()
+});
+/** The write form — the server owns `id`, `createdAt` and the frame binding. */
+var RetrainAnnotationDraftSchema = RetrainAnnotationSchema.omit({
+	id: true,
+	trackId: true,
+	deviceId: true,
+	mediaKey: true,
+	createdAt: true,
+	exportedInBatch: true
+});
+/** A track sitting in `staging`, with everything the worklist needs to rank it. */
+var RetrainTrackSchema = object({
+	trackId: string(),
+	deviceId: number(),
+	className: string(),
+	label: string().optional(),
+	firstSeen: number(),
+	lastSeen: number(),
+	/** How many frames the dataset already holds from this track. */
+	frameCount: number().int(),
+	/** How many subjects have been annotated on those frames. `0` with
+	*  `frameCount: 0` is exactly "staging, still to work". */
+	annotationCount: number().int()
+});
+/** A frame the picker may offer — an index row, no blob was read to produce it. */
+var RetrainFrameCandidateSchema = object({
+	mediaKey: string(),
+	kind: MediaFileKindEnum,
+	timestamp: number(),
+	sizeBytes: number().int(),
+	/** A copy of this original already exists — selecting it is free and cannot
+	*  fail, whatever became of the original. */
+	copied: boolean()
+});
+/** A frame the dataset OWNS: bytes copied at selection time. */
+var RetrainFrameSchema = object({
+	frameId: string(),
+	deviceId: number(),
+	trackId: string(),
+	/** Provenance only. It may already point at nothing — that is expected. */
+	sourceMediaKey: string(),
+	sourceKind: MediaFileKindEnum,
+	sizeBytes: number().int(),
+	width: number().int(),
+	height: number().int(),
+	copiedAt: number()
+});
+/** Why a copy-on-select could not be honoured — named, never a silent skip. */
+var RetrainCopyRefusalSchema = _enum([
+	"source-missing",
+	"unreadable-image",
+	"write-failed"
+]);
+var RetrainFrameSelectionSchema = object({
+	copied: array(RetrainFrameSchema).readonly(),
+	refused: array(object({
+		sourceMediaKey: string(),
+		reason: RetrainCopyRefusalSchema
+	})).readonly()
+});
+var RetrainFrameListSchema = object({
+	candidates: array(RetrainFrameCandidateSchema).readonly(),
+	copies: array(RetrainFrameSchema).readonly(),
+	/** What the page pre-selects — the native key frame when one survives. */
+	autoPickMediaKey: string().optional()
+});
+/** What the operator asked the assist to look for. */
+var RetrainAssistSubjectSchema = discriminatedUnion("kind", [object({
+	kind: literal("package"),
+	zone: RetrainBboxSchema.optional()
+}), object({
+	kind: literal("objects"),
+	modelId: string(),
+	minScore: number().optional()
+})]);
+/**
+* The assist's answer — a discriminated union, because "the model saw nothing"
+* and "this node cannot run that model" lead to different next moves and a
+* nullable result cannot tell them apart.
+*/
+var RetrainAssistResultSchema = discriminatedUnion("kind", [object({
+	kind: literal("proposed"),
+	modelId: string(),
+	stepId: string(),
+	minScore: number(),
+	/** Drafts, ready to edit. `source: 'assist'` until the operator touches one. */
+	proposals: array(RetrainAnnotationDraftSchema).readonly(),
+	/** Returned by the runner but removed by the threshold. */
+	belowThreshold: number().int()
+}), object({
+	kind: literal("refused"),
+	/** `no-zone` is ours; the rest are the runner's own refusal vocabulary. */
+	reason: string(),
+	detail: string().optional()
+})]);
+/** The outcome of a lifecycle move owned by the retrain page. */
+var RetrainTransitionResultSchema = object({
+	trackId: string(),
+	/** Where the track ended up, whatever happened. */
+	retrainStatus: RetrainStatusSchema,
+	/** `false` ⇒ the move was refused or was a no-op; `reason` says which. */
+	changed: boolean(),
+	reason: _enum([
+		"unknown-track",
+		"no-frames-copied",
+		"not-staging",
+		"not-trained",
+		"unchanged"
+	]).optional()
+});
 var DEFAULT_EVENT_QUERY_LIMIT = 1e3;
 var MAX_EVENT_QUERY_LIMIT = 5e3;
 var DeviceEventQueryInput = object({
@@ -15792,7 +16013,7 @@ var KeyEventSchema = object({
 	/** Track start time (firstSeen). */
 	timestamp: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	importance: number(),
 	/** Highest-confidence ObjectEvent id for the track (empty when none). */
 	bestEventId: string(),
@@ -16066,6 +16287,79 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 }), method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
 	kind: "query",
 	auth: "admin"
+}), method(object({
+	/** Empty ⇒ every camera that has staging tracks. A LIST, not a single
+	*  `deviceId`, deliberately: `deviceId` would make this device-bound and
+	*  route it at one camera's owner, and "every camera" would stop being
+	*  expressible at all. */
+	deviceIds: array(number()).optional(),
+	limit: number().int().min(1).max(500).optional()
+}), array(RetrainTrackSchema).readonly(), {
+	kind: "query",
+	auth: "admin"
+}), method(object({ trackId: string() }), RetrainFrameListSchema, {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	mediaKeys: array(string()).min(1)
+}), RetrainFrameSelectionSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string()
+}), object({
+	removed: boolean(),
+	removedAnnotations: number().int()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ frameId: string() }), object({
+	base64: string(),
+	width: number().int(),
+	height: number().int()
+}), {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string(),
+	subject: RetrainAssistSubjectSchema,
+	/** Which node runs it. Absent ⇒ wherever an unowned call lands. */
+	nodeId: string().optional()
+}), RetrainAssistResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ trackId: string() }), array(RetrainAnnotationSchema).readonly(), {
+	kind: "query",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string(),
+	frameId: string(),
+	annotations: array(RetrainAnnotationDraftSchema)
+}), array(RetrainAnnotationSchema).readonly(), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string()
+}), RetrainTransitionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number(),
+	trackId: string()
+}), RetrainTransitionResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
+	kind: "query",
+	auth: "admin"
 }), method(object({
 	eventId: string(),
 	kind: MediaFileKindEnum.optional()
@@ -16645,6 +16939,22 @@ var DetailResultSchema = object({
 	bbox: NativeCropBboxSchema.optional(),
 	embedding: string().optional(),
 	label: string().optional(),
+	/**
+	* The tier `label` occupies, copied VERBATIM from the producing step's
+	* `StepDefinition.labelTier` (roadmap 4g). Present only when `label` is.
+	*
+	* It rides the wire rather than being resolved by the consumer because the
+	* declaration lives with the step definition, which only the executing node
+	* has: post-analysis holds no step registry, and re-deriving the tier from
+	* `className` there would be exactly the inference this model exists to
+	* forbid. A `label` that arrives WITHOUT this field is refused by the write
+	* rule and logged (`label tier undeclared`) — an older runner therefore
+	* stops enriching rather than guessing, which is why addon-pipeline is
+	* deployed BEFORE addon-post-analysis.
+	*/
+	labelTier: union([literal(1), literal(2)]).optional(),
+	/** Model that produced `label` — carried into the tier's attribution. */
+	labelModelId: string().optional(),
 	alignedCropJpeg: string().optional(),
 	/** Face short side (px) measured on the NATIVE crop surface. The `bbox`
 	*  above is detection-frame px (≈6× smaller on a 4K camera) — min-face-size
@@ -26962,6 +27272,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.completeRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.deleteDeviceEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -26974,6 +27290,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.deselectRetrainFrame": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.getActiveTracks": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27034,6 +27356,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getRetrainExportUrl": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.getRetrainFrameImage": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.getSensorEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27088,6 +27422,24 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainStaging": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listTrackMedia": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27100,6 +27452,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.proposeRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.pruneEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -27130,12 +27488,30 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.restageRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineAnalytics.saveRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.searchObjectEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.selectRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.setTrackFlags": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -45395,8 +45771,21 @@ function syncStateToJson(map) {
 */
 var DEFAULT_DEVICE_SETTINGS = {
 	streamPreference: "auto",
-	hksvRecording: false
+	hksvRecording: true
 };
+/**
+* ON unless explicitly switched off — operator decision 2026-08-08 (flipped
+* from the launch default of off). ABSENT must resolve to ON or the flip is a
+* lie for every entry persisted before the field existed, so every read goes
+* through this one resolver (`!== false`), never a scattered `=== true`. The
+* cost that made off-by-default look prudent is measured and small on the only
+* branch the recorder accepts (copy: 0.7 % of a core / ~30 MB RSS, D84), and a
+* camera the recorder cannot copy refuses recording with a logged reason
+* rather than paying for a transcode.
+*/
+function resolveHksvRecording(settings) {
+	return settings?.hksvRecording !== false;
+}
 var HAP_STREAM_PREFERENCE_OPTIONS = [
 	{
 		value: "auto",
@@ -45673,7 +46062,7 @@ var ExportHapAddon = class extends BaseAddon {
 				decodeMemos: this.decodeMemos,
 				hapDeviceSettings: {
 					streamPreference: entrySettings.streamPreference ?? "auto",
-					hksvRecording: entrySettings.hksvRecording === true
+					hksvRecording: resolveHksvRecording(entrySettings)
 				}
 			}
 		});
@@ -46024,7 +46413,7 @@ var ExportHapAddon = class extends BaseAddon {
 						label: "HomeKit recording (Secure Video)",
 						description: "Offer “Stream and Allow Recording” in iOS Home. Requires iCloud+ and a home hub. Keeps a continuous 8s prebuffer for this camera (~0.7% of one CPU core, H.264 sources only).",
 						style: "switch",
-						value: settings.hksvRecording === true,
+						value: resolveHksvRecording(settings),
 						showWhen: {
 							field: enabledKey,
 							equals: true
@@ -46058,7 +46447,7 @@ var ExportHapAddon = class extends BaseAddon {
 		const enabledValue = enabledKey in patch ? Boolean(patch[enabledKey]) : wasEnabled;
 		const streamPreferenceRaw = streamPreferenceKey in patch ? patch[streamPreferenceKey] : current?.settings?.streamPreference;
 		const streamPreference = typeof streamPreferenceRaw === "string" && streamPreferenceRaw.trim().length > 0 ? streamPreferenceRaw : "auto";
-		const hksvRecording = hksvKey in patch ? Boolean(patch[hksvKey]) : current?.settings?.hksvRecording === true;
+		const hksvRecording = hksvKey in patch ? Boolean(patch[hksvKey]) : resolveHksvRecording(current?.settings);
 		const nextSettings = {
 			...current?.settings ?? DEFAULT_DEVICE_SETTINGS,
 			streamPreference,
@@ -46074,7 +46463,7 @@ var ExportHapAddon = class extends BaseAddon {
 			return { success: true };
 		}
 		const currentPref = current?.settings?.streamPreference ?? "auto";
-		const currentHksv = current?.settings?.hksvRecording === true;
+		const currentHksv = resolveHksvRecording(current?.settings);
 		await this.updateEntrySettings(deviceIdStr, nextSettings);
 		if (currentPref !== streamPreference || currentHksv !== hksvRecording) {
 			log.info("export-hap: per-camera export settings changed — refreshing accessory", { meta: {
@@ -46129,4 +46518,4 @@ function errMsg(err) {
 	return err instanceof Error ? err.message : String(err);
 }
 //#endregion
-export { ExportHapAddon, ExportHapAddon as default, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, deriveUsername as t };
+export { ExportHapAddon, ExportHapAddon as default, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, resolveHksvRecording, deriveUsername as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-export-hap",
-  "version": "1.2.15",
+  "version": "1.2.16",
   "description": "HomeKit (HAP) bridge exporter for CamStack devices. Publishes a bridged accessory per exposed device — MotionSensor in this MVP; Camera/Doorbell/Switch/Light follow.",
   "keywords": [
     "camstack",