@camstack/addon-post-analysis 1.2.267 → 1.2.268

package/dist/pipeline-analytics/index.mjs

@@ -38359,7 +38359,7 @@ var StateAnalyzer = class {
 			}
 			const velocity = track.velocity ? Math.sqrt(track.velocity.dx ** 2 + track.velocity.dy ** 2) : 0;
 			const dwellTimeMs = timestamp - ts.enteredAt;
-			const settled = velocity <= this.config.velocityThreshold || this.windowSaysStill(ts, track.bbox, timestamp);
+			const settled = this.speedSaysSettled(ts, track.bbox, velocity) || this.windowSaysStill(ts, track.bbox, timestamp);
 			let state;
 			if (ts.frameCount <= this.config.enteringFrames) state = "entering";
 			else if (settled) {
@@ -38395,6 +38395,37 @@ var StateAnalyzer = class {
 		return results;
 	}
 	/**
+	* The SPEED half of the settled test.
+	*
+	* Uncalibrated (`stillSpeedFracPerSec` undefined) this is the original line
+	* verbatim — the tracker's px-per-update velocity against the flat
+	* `velocityThreshold`. Nothing about an uncalibrated camera changes.
+	*
+	* Calibrated, the same question is asked in the camera's own units: how far
+	* the centroid moved between the last two OBSERVED samples, over the
+	* subject's own box diagonal, over the elapsed SECONDS. Per second and not
+	* per update because these cameras are `armed:on-motion` and deliver a
+	* settle burst plus a poll — 56 ms to 2135 ms between stored positions on
+	* one subject (D399) — so a per-update figure says more about the cadence
+	* than about the subject.
+	*
+	* An interval that cannot be measured (a single sample, a non-positive
+	* elapsed time, a box with no size) is UNKNOWN, and unknown never reads as
+	* settled. A track that young is still inside `enteringFrames` anyway.
+	*/
+	speedSaysSettled(ts, bbox, velocity) {
+		const bar = this.config.stillSpeedFracPerSec;
+		if (bar === void 0) return velocity <= this.config.velocityThreshold;
+		const last = ts.recent[ts.recent.length - 1];
+		const prev = ts.recent[ts.recent.length - 2];
+		if (!last || !prev) return false;
+		const elapsedSec = (last.at - prev.at) / 1e3;
+		if (!(elapsedSec > 0)) return false;
+		const diagonal = Math.hypot(bbox.w, bbox.h);
+		if (!(diagonal > 0)) return false;
+		return Math.hypot(last.x - prev.x, last.y - prev.y) / diagonal / elapsedSec <= bar;
+	}
+	/**
 	* Whether the centroid has stayed inside a small span for the whole window.
 	*
 	* The span is measured across the samples themselves (their bounding box),
@@ -48054,6 +48085,336 @@ function makeViewerSettingsActionHandlers(store) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/stillness-calibration-actions.ts
+/**
+* stillness-calibration-actions — "measure this camera's own stillness scale".
+*
+* ## Why an `addons.custom` action and not a cap method
+*
+* Same reason as `face.rescoreTrack` beside it: a cap method's wire schema
+* lives in `@camstack/types`, which travels inside the `@camstack/server`
+* closure, so a new one is not callable until a server train ships. Here the
+* schema lives in this addon's own dist and the hub forwards an opaque
+* envelope, so `camstack deploy` is the whole delivery.
+*
+* ## Why `apply` is explicit and not a fallback
+*
+* A calibration run READS recorded tracks and does arithmetic. Applying it
+* WRITES the camera's settings and changes what the tracker calls settled from
+* the next frame on. Those are different enough in consequence that a button
+* labelled "calibrate" must not choose between them on the operator's behalf —
+* the run reports, the operator applies. A REFUSED run never writes the bar
+* whatever `apply` says; it writes only the note, so the refusal and its reason
+* are visible in the form instead of being a toast that scrolls away.
+*/
+/** Mirrors `StillnessCalibrationRefusal` — kept literal so the wire schema is
+*  self-describing and a new reason is a deliberate edit in both places. */
+var StillnessRefusalSchema = _enum([
+	"no-tracks",
+	"too-few-tracks",
+	"too-few-samples",
+	"no-motion-evidence"
+]);
+var StillnessMeasurementSchema = object({
+	/** Tracks that contributed at least one speed sample. */
+	trackCount: number().int(),
+	/** Tracks the pass actually read, after the cost bound. */
+	tracksRead: number().int(),
+	sampleCount: number().int(),
+	/** Speed quantiles, subject-box-diagonals per second. `null` when there was
+	*  nothing to measure — never 0, which would read as a measured stillness
+	*  (D393). */
+	p25: number().nullable(),
+	p50: number().nullable(),
+	p90: number().nullable(),
+	/** Median gap between stored positions (s) — the camera's real cadence. */
+	medianIntervalSec: number().nullable(),
+	/** Median subject box diagonal (px) the speeds were normalised by. */
+	medianSubjectDiagonalPx: number().nullable()
+});
+var stillnessCalibrationActions = defineCustomActions({ 
+/**
+* `admin` because it WRITES a per-camera detection threshold when `apply` is
+* set, and because the report describes how the camera's subjects move,
+* which is not a viewer-level fact.
+*/
+"stillness.calibrate": customAction(object({
+	deviceId: number().int(),
+	/** How far back to read. Bounded: this pass parses ~10 kB of trajectory a
+	*  row, so the window is a suggestion and `maxTracks` is the real bound. */
+	sinceHours: number().min(.25).max(720).default(72),
+	/** Hard cost bound on tracks read, newest first. */
+	maxTracks: number().int().min(1).max(1e3).default(200),
+	/**
+	* Write the chosen bar onto the camera. Never implicit, and never done at
+	* all for a refused run.
+	*/
+	apply: boolean().default(false)
+}), object({
+	deviceId: number().int(),
+	/** The window actually read (epoch ms). */
+	since: number().int(),
+	until: number().int(),
+	accepted: boolean(),
+	/** Why it refused. Absent on an accepted run. */
+	reason: StillnessRefusalSchema.optional(),
+	/** The chosen bar, subject-box-diagonals per second. Absent on a refusal —
+	*  never 0, which the settings layer reads as "uncalibrated". */
+	bar: number().optional(),
+	/** The raw quantile before the rails, so the clamp is arguable. */
+	rawBar: number().optional(),
+	clampedBy: _enum([
+		"none",
+		"floor",
+		"ceiling",
+		"min",
+		"max"
+	]).optional(),
+	measurement: StillnessMeasurementSchema,
+	/** The bar this camera was on BEFORE the run — `null` = uncalibrated. Read
+	*  before any write, so the operator sees both numbers. */
+	previousBar: number().nullable(),
+	/** Whether the camera's settings were actually written. */
+	applied: boolean(),
+	/** The one-line note stored on the camera (accepted or refused). */
+	note: string()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}) });
+/**
+* The shipped limits.
+*
+* `minTracks` 12 / `minSamples` 200: the four live cameras sampled above
+* produced 697–8739 samples from 42–51 tracks in a single 60-track read, so a
+* camera that cannot clear these has genuinely not been watched enough.
+* `maxTracks` 200 bounds the read: the `positions` blob averages ~10 kB a row
+* (`track-store.ts`), so this pass is ~2 MB of JSON at its worst.
+*/
+var DEFAULT_STILLNESS_CALIBRATION_LIMITS = {
+	minTracks: 12,
+	minSamples: 200,
+	maxTracks: 200,
+	minIntervalSec: .02,
+	maxIntervalSec: 3,
+	quantile: .25,
+	floorFactor: .02,
+	ceilFactor: .25,
+	minBar: .001,
+	maxBar: 1
+};
+/** Linear-interpolated quantile. `NaN` for an empty list — never 0, which
+*  would read as a measured zero (D393). */
+function quantileOf(values, p) {
+	if (values.length === 0) return NaN;
+	const sorted = [...values].sort((a, b) => a - b);
+	const idx = (sorted.length - 1) * Math.min(Math.max(p, 0), 1);
+	const lo = Math.floor(idx);
+	const hi = Math.ceil(idx);
+	const at = sorted[lo];
+	const next = sorted[hi];
+	if (at === void 0 || next === void 0) return NaN;
+	return at + (next - at) * (idx - lo);
+}
+/**
+* Per-sample centroid speeds for a camera, in subject-box-diagonals per second.
+*
+* A pair of consecutive positions contributes a sample only when the interval
+* between them is inside `[minIntervalSec, maxIntervalSec]` and the later box
+* has a positive diagonal. A gap outside that band is a session boundary or a
+* duplicate read, not a measurement of how fast anything travelled; a box with
+* no size is unknown geometry, and unknown is never a sample.
+*/
+function collectStillnessSamples(tracks, limits) {
+	const speeds = [];
+	const intervals = [];
+	const diagonals = [];
+	let trackCount = 0;
+	const read = tracks.slice(0, limits.maxTracks);
+	for (const track of read) {
+		const positions = [...track.positions].sort((a, b) => a.timestamp - b.timestamp);
+		let contributed = false;
+		for (let i = 1; i < positions.length; i++) {
+			const prev = positions[i - 1];
+			const cur = positions[i];
+			if (prev === void 0 || cur === void 0) continue;
+			const dtSec = (cur.timestamp - prev.timestamp) / 1e3;
+			if (dtSec < limits.minIntervalSec || dtSec > limits.maxIntervalSec) continue;
+			const diagonal = Math.hypot(cur.bbox.w, cur.bbox.h);
+			if (!(diagonal > 0)) continue;
+			const travelled = Math.hypot(cur.x - prev.x, cur.y - prev.y);
+			speeds.push(travelled / diagonal / dtSec);
+			intervals.push(dtSec);
+			diagonals.push(diagonal);
+			contributed = true;
+		}
+		if (contributed) trackCount++;
+	}
+	return {
+		speeds,
+		intervals,
+		diagonals,
+		trackCount,
+		tracksRead: read.length
+	};
+}
+function measure$1(samples) {
+	return {
+		trackCount: samples.trackCount,
+		sampleCount: samples.speeds.length,
+		p25: quantileOf(samples.speeds, .25),
+		p50: quantileOf(samples.speeds, .5),
+		p90: quantileOf(samples.speeds, .9),
+		medianIntervalSec: quantileOf(samples.intervals, .5),
+		medianSubjectDiagonalPx: quantileOf(samples.diagonals, .5)
+	};
+}
+/**
+* Choose this camera's stillness speed bar, or refuse with a named reason.
+*
+* The order of the gates is the order of the questions: is there anything at
+* all, is it enough tracks, is it enough samples, and did anything on this
+* camera ever actually move. The last one is not pedantry — the whole method
+* scales the bar against the camera's own travel, so with no travel there is
+* nothing to scale against and the default is the honest answer.
+*/
+function calibrateStillnessSpeed(samples, limits) {
+	const measurement = measure$1(samples);
+	if (samples.tracksRead === 0) return {
+		ok: false,
+		reason: "no-tracks",
+		measurement
+	};
+	if (samples.trackCount < limits.minTracks) return {
+		ok: false,
+		reason: "too-few-tracks",
+		measurement
+	};
+	if (samples.speeds.length < limits.minSamples) return {
+		ok: false,
+		reason: "too-few-samples",
+		measurement
+	};
+	if (!(measurement.p90 > 0)) return {
+		ok: false,
+		reason: "no-motion-evidence",
+		measurement
+	};
+	const rawBar = quantileOf(samples.speeds, limits.quantile);
+	const floor = measurement.p90 * limits.floorFactor;
+	const ceiling = measurement.p90 * limits.ceilFactor;
+	let bar = rawBar;
+	let clampedBy = "none";
+	if (bar < floor) {
+		bar = floor;
+		clampedBy = "floor";
+	} else if (bar > ceiling) {
+		bar = ceiling;
+		clampedBy = "ceiling";
+	}
+	if (bar < limits.minBar) {
+		bar = limits.minBar;
+		clampedBy = "min";
+	} else if (bar > limits.maxBar) {
+		bar = limits.maxBar;
+		clampedBy = "max";
+	}
+	return {
+		ok: true,
+		bar,
+		rawBar,
+		clampedBy,
+		measurement
+	};
+}
+/** One line an operator can read: what was measured, from how much, and what
+*  rule produced the stored number. Kept short — it rides the settings blob. */
+function describeStillnessCalibration(outcome) {
+	const m = outcome.measurement;
+	const n = (v) => Number.isFinite(v) ? v.toFixed(4) : "unknown";
+	const evidence = `${m.sampleCount} samples / ${m.trackCount} tracks, p25 ${n(m.p25)}, p50 ${n(m.p50)}, p90 ${n(m.p90)} subject-diagonals/s`;
+	if (!outcome.ok) return `refused (${outcome.reason}) — ${evidence}`;
+	return `bar ${n(outcome.bar)} (raw ${n(outcome.rawBar)}, clamp ${outcome.clampedBy}) — ${evidence}`;
+}
+//#endregion
+//#region src/pipeline-analytics/stillness-settings.ts
+/**
+* Per-device STILLNESS SCALE — the one number that says how fast a subject on
+* THIS camera has to move before it is travelling.
+*
+* A threshold belongs to whoever GENERATES the event, per device, never baked
+* into a classifier default. The judgement this feeds is
+* `StateAnalyzer.speedSaysSettled`; the measurement behind the number is
+* `pipeline/tracker/stillness-scale.ts`, which also carries the live
+* measurement showing why one number cannot serve a 30 m driveway and a 2 m
+* doorway.
+*
+* Cascade and shape mirror `stationary-settings` / `media-settings`: a
+* per-device override on top of the default, resolved per FIELD, and a parse
+* that never throws on a bad blob.
+*
+* **Absent behaves exactly as today.** The device store is a flat numeric blob
+* with no room for "unset", so the stored form of absent is `0` — and `0` is
+* not a bar anyone could want (it would mean nothing on this camera is ever
+* still) and not a value the calibration can produce (`minBar`). The decision
+* layer never sees it: {@link resolveStillSpeedFracPerSec} maps it to
+* `undefined`, and `undefined` is what leaves `StateAnalyzer` on its original
+* absolute `velocityThreshold` path.
+*/
+var StillnessSettingsSchema = object({
+	/**
+	* The camera's "not travelling" bar: centroid speed as a fraction of the
+	* SUBJECT's own box diagonal, per second. `0` = not calibrated (see above).
+	*
+	* Measured p50 on the live hub 2026-09-19, for scale: 0.0136 (device 592,
+	* close view, mostly parked subjects) to 0.3081 (device 615, far view, only
+	* transits).
+	*/
+	stillnessSpeedFracPerSec: number().min(0).max(1).default(0),
+	/**
+	* When the number above was last CHOSEN — by a calibration run or by the
+	* operator. `0` = never. Purely a readout; nothing gates on it.
+	*/
+	stillnessCalibratedAt: number().int().min(0).default(0),
+	/**
+	* What the last calibration run measured and decided, in one line
+	* (`describeStillnessCalibration`) — including a REFUSAL and its named
+	* reason, because "why is this camera still on the default" has to be
+	* answerable without re-running anything.
+	*/
+	stillnessCalibrationNote: string().max(400).default("")
+});
+var STILLNESS_DEFAULTS = StillnessSettingsSchema.parse({});
+/**
+* Resolve a per-device store blob into typed stillness settings. Unknown or
+* invalid fields fall back to the default for that field — including a bar
+* outside the calibration's own rails, which is refused rather than clamped:
+* a number the calibration could never have produced is not evidence about
+* this camera, and silently bending it into range would present it as if it
+* were.
+*/
+function resolveStillnessSettings(raw) {
+	const pick = (key) => {
+		const parsed = StillnessSettingsSchema.shape[key].safeParse(raw[key]);
+		return parsed.success ? parsed.data : STILLNESS_DEFAULTS[key];
+	};
+	return {
+		stillnessSpeedFracPerSec: pick("stillnessSpeedFracPerSec"),
+		stillnessCalibratedAt: pick("stillnessCalibratedAt"),
+		stillnessCalibrationNote: pick("stillnessCalibrationNote")
+	};
+}
+/**
+* The bar the decision layer gets: a positive, in-rails number, or
+* `undefined` for "this camera is not calibrated — judge it exactly as
+* before". The ONE place the stored-zero convention is interpreted.
+*/
+function resolveStillSpeedFracPerSec(settings) {
+	const bar = settings.stillnessSpeedFracPerSec;
+	if (!(bar >= .001) || bar > 1) return void 0;
+	return bar;
+}
+//#endregion
 //#region src/pipeline-analytics/viewer-settings-legacy-adoption.ts
 /**
 * @durable class=config owner=pipeline-analytics
@@ -71670,6 +72031,56 @@ var SyntheticTrackMaterializer = class {
 		return track;
 	}
 };
+//#endregion
+//#region src/pipeline-analytics/stationary-settings.ts
+/**
+* Per-device stationary-object (parked/idle suppression) settings. Cascade: a
+* per-device override on top of the global default, resolved per field (an
+* invalid/missing value falls back to its default — parse never throws).
+* Mirrors `media-settings` / `tracking-settings`.
+*
+* The defaults are the SAME constants the registry uses at runtime
+* (`stationary-types.ts`), imported (not copied) so an unset value and a reset
+* value both resolve to exactly today's behaviour — "reset == unset == today",
+* with no drift. Guarded by a unit test asserting the equality.
+*/
+var StationarySettingsSchema = object({
+	/** Master switch. Off ⇒ this camera gathers no evidence and suppresses
+	*  nothing (every parked object keeps spawning normal tracks). */
+	enabled: boolean().default(true),
+	/** IoU at/above which a detection is the same parked object, unmoved →
+	*  suppress its spawn. `SUPPRESS_IOU`. */
+	suppressIou: number().min(.3).max(.9).default(SUPPRESS_IOU),
+	/** Minimum IoU for a detection to be ASSOCIATED with an entry (confirm or
+	*  wake it) — the overlap gate that stops a different vehicle from waking a
+	*  parked entry (the 617 flood fix). `WAKE_ASSOC_IOU`. */
+	wakeAssocIou: number().min(.02).max(.5).default(WAKE_ASSOC_IOU),
+	/** Recent-window stillness after which a track stops holding its motion
+	*  session open (also the minimum track age). Creates nothing — birth is
+	*  decided by repeated evidence. `SESSION_STILLNESS_WINDOW_MS`. */
+	sessionStillnessWindowMs: number().int().min(5e3).max(12e4).default(SESSION_STILLNESS_WINDOW_MS),
+	/** Observed-time TTL: retire an entry unconfirmed for this long (measured on
+	*  frames-flowing time, not wall-clock). `ENTRY_TTL_MS`. */
+	entryTtlMs: number().int().min(6e4).max(18e5).default(ENTRY_TTL_MS)
+});
+var STATIONARY_DEFAULTS = StationarySettingsSchema.parse({});
+/**
+* Resolve a per-device store blob into typed stationary settings. Unknown/invalid
+* fields fall back to the default for that field (never throws on a bad blob).
+*/
+function resolveStationarySettings(raw) {
+	const pick = (key) => {
+		const parsed = StationarySettingsSchema.shape[key].safeParse(raw[key]);
+		return parsed.success ? parsed.data : STATIONARY_DEFAULTS[key];
+	};
+	return {
+		enabled: pick("enabled"),
+		suppressIou: pick("suppressIou"),
+		wakeAssocIou: pick("wakeAssocIou"),
+		sessionStillnessWindowMs: pick("sessionStillnessWindowMs"),
+		entryTtlMs: pick("entryTtlMs")
+	};
+}
 var TrackingSettingsSchema = object({
 	/**
 	* How much of a detection's box must lie inside a zone (0-1 fraction of the
@@ -71870,56 +72281,6 @@ function resolveTrackingSettings(raw) {
 	};
 }
 //#endregion
-//#region src/pipeline-analytics/stationary-settings.ts
-/**
-* Per-device stationary-object (parked/idle suppression) settings. Cascade: a
-* per-device override on top of the global default, resolved per field (an
-* invalid/missing value falls back to its default — parse never throws).
-* Mirrors `media-settings` / `tracking-settings`.
-*
-* The defaults are the SAME constants the registry uses at runtime
-* (`stationary-types.ts`), imported (not copied) so an unset value and a reset
-* value both resolve to exactly today's behaviour — "reset == unset == today",
-* with no drift. Guarded by a unit test asserting the equality.
-*/
-var StationarySettingsSchema = object({
-	/** Master switch. Off ⇒ this camera gathers no evidence and suppresses
-	*  nothing (every parked object keeps spawning normal tracks). */
-	enabled: boolean().default(true),
-	/** IoU at/above which a detection is the same parked object, unmoved →
-	*  suppress its spawn. `SUPPRESS_IOU`. */
-	suppressIou: number().min(.3).max(.9).default(SUPPRESS_IOU),
-	/** Minimum IoU for a detection to be ASSOCIATED with an entry (confirm or
-	*  wake it) — the overlap gate that stops a different vehicle from waking a
-	*  parked entry (the 617 flood fix). `WAKE_ASSOC_IOU`. */
-	wakeAssocIou: number().min(.02).max(.5).default(WAKE_ASSOC_IOU),
-	/** Recent-window stillness after which a track stops holding its motion
-	*  session open (also the minimum track age). Creates nothing — birth is
-	*  decided by repeated evidence. `SESSION_STILLNESS_WINDOW_MS`. */
-	sessionStillnessWindowMs: number().int().min(5e3).max(12e4).default(SESSION_STILLNESS_WINDOW_MS),
-	/** Observed-time TTL: retire an entry unconfirmed for this long (measured on
-	*  frames-flowing time, not wall-clock). `ENTRY_TTL_MS`. */
-	entryTtlMs: number().int().min(6e4).max(18e5).default(ENTRY_TTL_MS)
-});
-var STATIONARY_DEFAULTS = StationarySettingsSchema.parse({});
-/**
-* Resolve a per-device store blob into typed stationary settings. Unknown/invalid
-* fields fall back to the default for that field (never throws on a bad blob).
-*/
-function resolveStationarySettings(raw) {
-	const pick = (key) => {
-		const parsed = StationarySettingsSchema.shape[key].safeParse(raw[key]);
-		return parsed.success ? parsed.data : STATIONARY_DEFAULTS[key];
-	};
-	return {
-		enabled: pick("enabled"),
-		suppressIou: pick("suppressIou"),
-		wakeAssocIou: pick("wakeAssocIou"),
-		sessionStillnessWindowMs: pick("sessionStillnessWindowMs"),
-		entryTtlMs: pick("entryTtlMs")
-	};
-}
-//#endregion
 //#region src/pipeline-analytics/settings-schema-sections.ts
 /** The detection-knob sections, in their original in-form order. */
 function buildDetectionSettingsSections() {
@@ -72465,10 +72826,45 @@ function buildDetectionSettingsSections() {
 					displayScale: 1e3
 				}
 			]
-		}
+		},
+		buildStillnessScaleSection()
 	];
 }
 /**
+* The per-camera STILLNESS SCALE — one measured number plus its provenance.
+*
+* Its own section rather than a field on `detection-sensitivity` because the
+* two answer different questions: `stationaryThresholdSec` is HOW LONG a
+* settled subject must stay settled, which is an operator preference; this is
+* HOW SLOW counts as settled, which is a fact about the camera and is
+* measured. Mixing them is how a measurement ends up being guessed at.
+*/
+function buildStillnessScaleSection() {
+	return {
+		id: "stillness-scale",
+		title: "Stillness scale (per camera)",
+		description: "How slowly a subject has to move on THIS camera before it counts as settled. A camera looking down a 30 m driveway and one watching a doorway two metres away disagree about this by more than an order of magnitude, so one fleet-wide number cannot be right for both. Leave it at 0 and the camera behaves exactly as it always has (a flat 2 px-per-update bar). Run the `stillness.calibrate` action to measure it from the camera’s own recorded tracks — the run reports what it measured and REFUSES, with a reason, when the evidence is too thin.",
+		columns: 1,
+		fields: [{
+			type: "number",
+			key: "stillnessSpeedFracPerSec",
+			label: "Stillness speed bar",
+			description: "Centroid speed, as a fraction of the subject’s OWN box diagonal, per second, at or below which the subject is not travelling. Subject-relative, so perspective is already divided out; per second, so an irregular on-motion cadence cannot masquerade as speed. 0 = not calibrated (the shipped absolute bar decides, exactly as before). Live reference: 0.0136 on a close, mostly-parked view; 0.3081 on a far view whose subjects only transit.",
+			min: 0,
+			max: 1,
+			step: .001,
+			default: STILLNESS_DEFAULTS.stillnessSpeedFracPerSec
+		}, {
+			type: "text",
+			key: "stillnessCalibrationNote",
+			label: "Last calibration",
+			description: "What the last run measured, from how many samples and tracks, and what it chose — or which named reason it refused for. Display only.",
+			default: STILLNESS_DEFAULTS.stillnessCalibrationNote,
+			readonlyField: true
+		}]
+	};
+}
+/**
 * Re-home the global analytics sections into the per-device `Analytics`
 * top-tab. Every section defaults to the `Analytics` tab (so the
 * device-manager aggregator groups them) AND is marked
@@ -72494,6 +72890,7 @@ function toAnalyticsDeviceSections(sections) {
 *   - `tracking` — the tracker-tuning form incl. the FP knobs (dedup, person↔
 *     animal dedup, class voting, confirm-bypass, per-class min score).
 *   - `stationary-objects` — stationary promotion + occupancy tuning.
+*   - `stillness-scale` — the per-camera measured "how slow is settled" bar.
 * `DeviceDetail` folds `tab: 'detection-pipeline'` top-tab sections into the
 * structural Detection pipeline tab, so re-tagging is all that's needed —
 * there is no admin-ui change and no duplicate render (a section has one tab).
@@ -72502,7 +72899,8 @@ var DETECTION_PIPELINE_SECTION_IDS = new Set([
 	"detection-sensitivity",
 	"confirmation-gate",
 	"tracking",
-	"stationary-objects"
+	"stationary-objects",
+	"stillness-scale"
 ]);
 /**
 * Re-home the detection-knob sections from the `Analytics` top-tab onto the
@@ -76234,7 +76632,8 @@ var customActions = {
 	...locationDiscardActions,
 	...viewerSettingsActions,
 	...photoEnrollActions,
-	...faceRescoreActions
+	...faceRescoreActions,
+	...stillnessCalibrationActions
 };
 /**
 * Width cap on the ONE full frame a debug crop is cut from.
@@ -77074,6 +77473,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 	*  the frame path like the stationary one and a cold miss answers the
 	*  measured default. */
 	summarySettingsCache = this.settingsCaches.registerDeviceCache("summary", SETTINGS_CACHE_TTL_MS);
+	/** Per-device STILLNESS SCALE cache — the measured "how slow is settled" bar
+	*  (`stillness-settings.ts`). Read once per FrameProcessor build, so this is
+	*  a cold-path cache; it exists so a calibration applied through
+	*  `stillness.calibrate` reaches the tracker on the next processor rebuild
+	*  rather than on the next addon restart. */
+	stillnessSettingsCache = this.settingsCaches.registerDeviceCache("stillness", SETTINGS_CACHE_TTL_MS);
 	/** Turns stationary appear/depart into package-delivered/picked-up events. */
 	packageDropDetector = null;
 	/**
@@ -77778,7 +78183,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 					...locationDiscardActions,
 					...viewerSettingsActions,
 					...photoEnrollActions,
-					...faceRescoreActions
+					...faceRescoreActions,
+					...stillnessCalibrationActions
 				},
 				actionHandlers: {
 					...ncHandlers,
@@ -77786,6 +78192,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 					...this.buildDebugActionHandlers(),
 					...this.buildPhotoEnrollActionHandlers(),
 					...this.buildFaceRescoreActionHandlers(),
+					...this.buildStillnessCalibrationActionHandlers(),
 					...this.viewerSettingsSnapshots ? makeViewerSettingsActionHandlers(this.viewerSettingsSnapshots) : {}
 				}
 			} : {}
@@ -81769,6 +82176,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 	async resolveDeviceStationarySettings(deviceId) {
 		return this.stationarySettingsCache.get(deviceId, (id) => this.readDeviceSettings(id, resolveStationarySettings));
 	}
+	/** Per-device stillness scale. An absent/zero bar resolves to `undefined`
+	*  ({@link resolveStillSpeedFracPerSec}) and leaves the state analyzer on
+	*  its original absolute threshold — uncalibrated is exactly today. */
+	async resolveDeviceStillnessSettings(deviceId) {
+		return this.stillnessSettingsCache.get(deviceId, (id) => this.readDeviceSettings(id, resolveStillnessSettings));
+	}
 	/**
 	* Count SHORT + MOTIONLESS track closes per frame cell.
 	*
@@ -84165,6 +84578,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 		if (!p) {
 			const { minHits, stationaryThresholdSec, minTrackAge, cooldownSec } = await this.resolveDeviceDetectionSensitivitySettings(deviceId);
 			const trk = await this.resolveDeviceTrackingSettings(deviceId);
+			const stillSpeedFracPerSec = resolveStillSpeedFracPerSec(await this.resolveDeviceStillnessSettings(deviceId));
 			p = new FrameProcessor(deviceId, {
 				minHits,
 				iouThreshold: trk.iouThreshold,
@@ -84206,7 +84620,10 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 					vehicle: trk.minSpawnAreaFracVehicle
 				},
 				classGroupAssoc: trk.classGroupAssoc
-			}, { stationaryThresholdSec }, {
+			}, {
+				stationaryThresholdSec,
+				...stillSpeedFracPerSec !== void 0 ? { stillSpeedFracPerSec } : {}
+			}, {
 				minTrackAge,
 				cooldownSec,
 				minTrackAgeMs: trk.minTrackAgeMs
@@ -85928,6 +86345,109 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 	buildFaceRescoreActionHandlers() {
 		return { "face.rescoreTrack": (input) => this.rescoreFaceForTrack(input) };
 	}
+	buildStillnessCalibrationActionHandlers() {
+		return { "stillness.calibrate": (input) => this.calibrateStillnessForDevice(input) };
+	}
+	/**
+	* Measure ONE camera's stillness scale from its own recorded tracks.
+	*
+	* Cost-bounded by construction: one `queryRecent` page of at most
+	* `maxTracks` rows over the requested window, `projection: 'full'` because
+	* the trajectory IS the measurement, and nothing else is read. The arithmetic
+	* is `stillness-scale.ts` and is pure — this method only fetches, reports and
+	* (on `apply`) writes.
+	*
+	* A REFUSAL never writes the bar. It does write the note, because "why is
+	* this camera still on the default" has to be answerable from the form
+	* rather than from a toast nobody kept.
+	*/
+	async calibrateStillnessForDevice(input) {
+		const trackStore = this.trackStore;
+		if (!trackStore) throw new Error("stillness.calibrate: the track store is not ready");
+		const until = Date.now();
+		const since = until - Math.round(input.sinceHours * 36e5);
+		const limits = {
+			...DEFAULT_STILLNESS_CALIBRATION_LIMITS,
+			maxTracks: input.maxTracks
+		};
+		const previous = resolveStillSpeedFracPerSec(await this.resolveDeviceStillnessSettings(input.deviceId));
+		const samples = collectStillnessSamples((await trackStore.queryRecent({
+			deviceIds: [input.deviceId],
+			since,
+			until,
+			limit: limits.maxTracks,
+			projection: "full"
+		})).tracks.map((t) => ({
+			trackId: t.trackId,
+			className: t.className,
+			positions: t.positions.map((pos) => ({
+				x: pos.x,
+				y: pos.y,
+				timestamp: pos.timestamp,
+				bbox: {
+					w: pos.bbox.w,
+					h: pos.bbox.h
+				}
+			}))
+		})), limits);
+		const outcome = calibrateStillnessSpeed(samples, limits);
+		const note = describeStillnessCalibration(outcome);
+		const finite = (v) => Number.isFinite(v) ? v : null;
+		const measurement = {
+			trackCount: outcome.measurement.trackCount,
+			tracksRead: samples.tracksRead,
+			sampleCount: outcome.measurement.sampleCount,
+			p25: finite(outcome.measurement.p25),
+			p50: finite(outcome.measurement.p50),
+			p90: finite(outcome.measurement.p90),
+			medianIntervalSec: finite(outcome.measurement.medianIntervalSec),
+			medianSubjectDiagonalPx: finite(outcome.measurement.medianSubjectDiagonalPx)
+		};
+		let applied = false;
+		if (input.apply) {
+			const patch = {
+				stillnessCalibrationNote: note,
+				stillnessCalibratedAt: until
+			};
+			if (outcome.ok) patch["stillnessSpeedFracPerSec"] = outcome.bar;
+			await this.applyDeviceSettingsPatch({
+				deviceId: input.deviceId,
+				patch
+			});
+			applied = outcome.ok;
+		}
+		this.ctx.logger.info("stillness calibration", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				accepted: outcome.ok,
+				...outcome.ok ? {} : { reason: outcome.reason },
+				...outcome.ok ? {
+					bar: outcome.bar,
+					clampedBy: outcome.clampedBy
+				} : {},
+				previousBar: previous ?? null,
+				applied,
+				windowHours: input.sinceHours,
+				...measurement
+			}
+		});
+		return {
+			deviceId: input.deviceId,
+			since,
+			until,
+			accepted: outcome.ok,
+			...outcome.ok ? {} : { reason: outcome.reason },
+			...outcome.ok ? {
+				bar: outcome.bar,
+				rawBar: outcome.rawBar,
+				clampedBy: outcome.clampedBy
+			} : {},
+			measurement,
+			previousBar: previous ?? null,
+			applied,
+			note
+		};
+	}
 	buildPhotoEnrollActionHandlers() {
 		return {
 			"photo.analyze": async (input) => {
@@ -87010,6 +87530,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends BaseAddon {
 		this.trackingSettingsCache.delete(input.deviceId);
 		this.confirmationGateSettingsCache.delete(input.deviceId);
 		this.mediaSettingsCache.delete(input.deviceId);
+		this.stillnessSettingsCache.delete(input.deviceId);
 		this.forgetDeviceProcessors(input.deviceId);
 		return { success: true };
 	}