@camstack/types 1.2.259 → 1.2.261

package/dist/interfaces/addon.d.ts

@@ -489,6 +489,17 @@ export interface AddonContext<TConfig = Record<string, unknown>> {
          * allowlisted engine-cascade holdouts are the only callers.
          */
         readAddonStore(): Promise<Record<string, unknown>>;
+        /**
+         * The same read, THREE-WAY: a stored blob, no blob, or a read that FAILED.
+         * `readAddonStore` folds a failure into `{}`, which a caller cannot tell
+         * from "never written"; this one does not (D651). Optional: a settings view
+         * that predates it answers nothing, and the caller must treat that as
+         * unreadable, never as empty.
+         *
+         * @internal Same rule as `readAddonStore`: addons reach it only through
+         * `BaseAddon.readStoredGlobalKey`.
+         */
+        readAddonStoreResult?(): Promise<AddonStoreRead>;
         /**
          * Write a patch into the addon store. Keys not in the patch are
          * preserved. Keys explicitly set to `null` are preserved as-is (they
@@ -1409,3 +1420,33 @@ export interface InternalAddonContext extends AddonContext {
     /** Resolve the preferred provider for a capability. Kernel-only. */
     resolveProvider<T = unknown>(capabilityName: string): T | null;
 }
+/**
+ * A three-way read of an addon's own store (D651). `missing` and `failed` are
+ * distinct on purpose: folding them is how a failed read becomes "defaults".
+ */
+export type AddonStoreRead = {
+    readonly kind: 'value';
+    readonly value: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'failed';
+    readonly error: string;
+};
+/** One stored key of an addon's own store, read three-way (D651). */
+export type StoredKeyRead = 
+/** The key was written; `value` is what is stored. */
+{
+    readonly kind: 'present';
+    readonly value: unknown;
+}
+/** The store answered and the key was never written. */
+ | {
+    readonly kind: 'absent';
+}
+/** The store did not answer, or this node's settings view cannot say. */
+ | {
+    readonly kind: 'unreadable';
+    readonly reason: 'store-read-failed' | 'three-way-read-unavailable';
+    readonly error?: string;
+};

package/dist/interfaces/event-bus.d.ts

@@ -165,6 +165,16 @@ export interface PipelineAnalyticsFrameTrackedPayload {
      * a dropped frame just lets the session close slightly earlier.
      */
     readonly hasLiveTrack?: boolean;
+    /**
+     * How many objects the TRACKER holds on this frame — moving OR still,
+     * i.e. `result.tracked.length` (D652). Diagnostics only: it decides nothing.
+     * {@link hasLiveTrack} deliberately subtracts a still subject, so a session
+     * that closed on a parked car and one that closed on an empty street both
+     * saw `false` last; this count is what tells them apart on the orchestrator's
+     * close line (`liveTracks`). Absent ⇒ unknown (an older post-analysis),
+     * which the consumer reports as `null`, never as 0.
+     */
+    readonly liveTrackCount?: number;
     [key: string]: unknown;
 }
 /** Lifecycle phase of a tracked object: it appears (`start`), its best
@@ -1260,7 +1270,7 @@ export interface EventCatalog {
             readonly engine: PipelineEngineChoice;
             readonly modelsLoaded: readonly string[];
             readonly inUseByCameras: readonly number[];
-            readonly kind: 'runtime' | 'warm-override' | 'device-pool';
+            readonly kind: 'runtime' | 'device-pool';
             readonly poolPid: number | null;
             readonly idleMs: number | null;
             readonly idleTtlMs: number | null;

package/dist/interfaces/pipeline-executor-capability.d.ts

@@ -33,14 +33,12 @@ export interface PipelineStepInput {
  *  - `imageBase64`: one-shot benchmark (ImageTab "Run")
  *  - `referenceImage`: named file from the reference-image store
  *
- * `engine` + `deviceId` are optional contextual hints — the executor uses
- * `deviceId` for per-device overrides and traces, and `engine` to select
- * the factory (when absent, falls back to the executor's persisted
- * selection during the migration window).
+ * `deviceId` is an optional contextual hint — the executor uses it for
+ * per-device overrides and traces. There is no `engine` (D646): the pool is
+ * the node's own engine, or the `deviceKey` pool when one is named.
  */
 export interface PipelineRunInput {
     readonly steps: readonly PipelineStepInput[];
-    readonly engine?: PipelineEngineChoice;
     readonly frame?: FrameInput;
     /** Same-process lazy source; never forwarded over UDS/Moleculer. */
     readonly frameRef?: FrameRef;
@@ -93,6 +91,16 @@ export interface PipelineRunInput {
      * mutually-exclusive image inputs. Absent ⇒ tile-crop children.
      */
     readonly nativeCropRef?: NativeCropRef;
+    /**
+     * Offline REPLAY of stored media for `deviceId` (D56, D646). The call runs
+     * the camera's structure — its detection-stage zone gate and per-device
+     * overrides, exactly as a live frame — over a recorded image, and it is
+     * PINNED: every executing step runs the model it names on the `deviceKey`
+     * pool it names, or the call refuses (`model-not-servable` /
+     * `device-not-servable`) before any pool is touched. Nothing is emitted on
+     * the camera's live trace stream. Absent ⇒ unchanged behaviour.
+     */
+    readonly replay?: true;
 }
 /**
  * Singleton capability provided by the pipeline-executor addon.
@@ -121,6 +129,8 @@ export interface IPipelineExecutorProvider {
      */
     validatePipeline(input: {
         readonly steps: readonly PipelineStepInput[];
+        /** Validate against this device pool's format; absent ⇒ the node default. */
+        readonly deviceKey?: string;
     }): Promise<PipelineValidationResult>;
     /** Get the currently selected engine (bootstrap default on the node). */
     getSelectedEngine(): Promise<PipelineEngineChoice>;
@@ -172,7 +182,6 @@ export interface IPipelineExecutorProvider {
      */
     runPipelineBatch(input: {
         readonly steps: readonly PipelineStepInput[];
-        readonly engine?: PipelineEngineChoice;
         readonly frames: readonly FrameInput[];
         readonly deviceId?: number;
         readonly sessionId?: string;

package/dist/interfaces/platform.d.ts

@@ -47,7 +47,7 @@ export interface CoralInfo {
 }
 /** A probed backend with availability and score */
 export interface PlatformScore {
-    readonly runtime: 'node' | 'python';
+    readonly runtime: 'python';
     readonly backend: string;
     readonly format: 'onnx' | 'coreml' | 'openvino' | 'tflite';
     readonly score: number;
@@ -77,7 +77,7 @@ export interface ModelRequirement {
 /** Resolved config — the tripletta chosen by the scorer for an addon */
 export interface ResolvedInferenceConfig {
     readonly modelId: string;
-    readonly runtime: 'node' | 'python';
+    readonly runtime: 'python';
     readonly backend: string;
     readonly format: import('../types/models.js').ModelFormat;
     readonly reason: string;

package/dist/interfaces/stream-broker.d.ts

@@ -18,11 +18,11 @@ export declare const DecoderSessionConfigSchema: z.ZodObject<{
     codec: z.ZodString;
     maxFps: z.ZodDefault<z.ZodNumber>;
     outputFormat: z.ZodDefault<z.ZodEnum<{
-        rgb: "rgb";
-        gray: "gray";
         jpeg: "jpeg";
+        rgb: "rgb";
         bgr: "bgr";
         yuv420: "yuv420";
+        gray: "gray";
     }>>;
     scale: z.ZodDefault<z.ZodNumber>;
     width: z.ZodOptional<z.ZodNumber>;

package/dist/node.d.ts

@@ -13,6 +13,7 @@ export { FfmpegProcess } from './ffmpeg/process.js';
 export type { ChildCostClaimHandle, ChildCostClaimInput, ProcStatReader, } from './process/child-cost-registry.js';
 export { ChildCostRegistry, NO_COST_CLAIM, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, } from './process/child-cost-registry.js';
 export { FilesystemStorageProvider } from './storage/filesystem-storage-provider.js';
+export { writeFileAtomic } from './storage/atomic-write.js';
 export type { PhysicalRoot, RealpathSync } from './storage/physical-root.js';
 export { containsOrEquals, physicalRootOf } from './storage/physical-root.js';
 export { canonicalHash } from './utils/canonical-hash.js';

package/dist/node.js

@@ -1744,6 +1744,69 @@ var ChildCostRegistry = class {
 	}
 };
 //#endregion
+//#region src/storage/atomic-write.ts
+/** Errors a Windows rename over a file another process has open can raise. */
+var WINDOWS_RENAME_BUSY = new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
+var WINDOWS_RENAME_RETRIES = 3;
+var WINDOWS_RENAME_RETRY_MS = 25;
+function errnoCode(err) {
+	return err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : void 0;
+}
+/**
+* Replace `filePath` with `data` so that a concurrent reader sees EITHER the
+* old complete file OR the new complete file — never a prefix (D654).
+*
+* A plain `writeFile` truncates the target and then writes it in chunks, so a
+* reader in between gets a torn file: a fixed-path single-instance media kind
+* (`lastFrame`, `lastSceneFrame`) is overwritten every roll while a
+* notification may be reading it. Here the bytes go to a temp file in the SAME
+* directory (same filesystem, so the rename cannot degrade to a copy), and a
+* `rename` swaps it in — atomic on POSIX. A reader that already opened the old
+* file keeps reading the old inode to the end.
+*
+* The temp name is DOT-prefixed so every directory scan that skips dot entries
+* (occupancy, D327) never counts it; it is removed on any failure. A process
+* killed between the write and the rename leaves one `.<name>.<uuid>.tmp`.
+*
+* Windows: a rename over a file another process holds open can fail with
+* EPERM/EACCES/EBUSY. It is retried briefly and then falls back to copying the
+* temp over the target — non-atomic, exactly the pre-D654 behaviour, rather
+* than losing the write.
+*
+* Cost: one extra `rename` (and, on failure, one `rm`) per write — a metadata
+* operation, independent of the payload size.
+*/
+async function writeFileAtomic(filePath, data) {
+	const tmp = node_path.join(node_path.dirname(filePath), `.${node_path.basename(filePath)}.${(0, node_crypto.randomUUID)()}.tmp`);
+	try {
+		await node_fs.promises.writeFile(tmp, data);
+		await renameOver(tmp, filePath);
+	} catch (err) {
+		await node_fs.promises.rm(tmp, { force: true }).catch(() => void 0);
+		throw err;
+	}
+}
+async function renameOver(tmp, filePath) {
+	for (let attempt = 0;; attempt += 1) try {
+		await node_fs.promises.rename(tmp, filePath);
+		return;
+	} catch (err) {
+		const code = errnoCode(err);
+		if (!(process.platform === "win32" && code !== void 0 && WINDOWS_RENAME_BUSY.has(code))) throw err;
+		if (attempt < WINDOWS_RENAME_RETRIES) {
+			await new Promise((resolve) => setTimeout(resolve, WINDOWS_RENAME_RETRY_MS));
+			continue;
+		}
+		await node_fs.promises.copyFile(tmp, filePath);
+		await node_fs.promises.rm(tmp, { force: true });
+		return;
+	}
+}
+//#endregion
 //#region src/storage/filesystem-storage-provider.ts
 var STORAGE_LOCATION_TYPES = [
 	"data",
@@ -1817,14 +1880,16 @@ var FilesystemStorageProvider = class {
 			relativePath
 		});
 		await node_fs.promises.mkdir(node_path.dirname(filePath), { recursive: true });
-		if (Buffer.isBuffer(data)) await node_fs.promises.writeFile(filePath, data);
+		if (Buffer.isBuffer(data)) await writeFileAtomic(filePath, data);
 		else {
-			const writeStream = node_fs.createWriteStream(filePath);
-			await new Promise((resolve, reject) => {
-				data.pipe(writeStream);
-				writeStream.on("finish", resolve);
-				writeStream.on("error", reject);
-			});
+			const tmp = node_path.join(node_path.dirname(filePath), `.${node_path.basename(filePath)}.${(0, node_crypto.randomUUID)()}.tmp`);
+			try {
+				await (0, node_stream_promises.pipeline)(data, node_fs.createWriteStream(tmp));
+				await node_fs.promises.rename(tmp, filePath);
+			} catch (err) {
+				await node_fs.promises.rm(tmp, { force: true }).catch(() => void 0);
+				throw err;
+			}
 		}
 	}
 	async read({ location, relativePath }) {
@@ -2090,3 +2155,4 @@ exports.readProcessCost = readProcessCost;
 exports.resolveExportFingerprint = resolveExportFingerprint;
 exports.signExpiringUrl = signExpiringUrl;
 exports.verifyExpiringUrl = verifyExpiringUrl;
+exports.writeFileAtomic = writeFileAtomic;

package/dist/node.mjs

@@ -1721,6 +1721,69 @@ var ChildCostRegistry = class {
 	}
 };
 //#endregion
+//#region src/storage/atomic-write.ts
+/** Errors a Windows rename over a file another process has open can raise. */
+var WINDOWS_RENAME_BUSY = new Set([
+	"EPERM",
+	"EACCES",
+	"EBUSY"
+]);
+var WINDOWS_RENAME_RETRIES = 3;
+var WINDOWS_RENAME_RETRY_MS = 25;
+function errnoCode(err) {
+	return err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : void 0;
+}
+/**
+* Replace `filePath` with `data` so that a concurrent reader sees EITHER the
+* old complete file OR the new complete file — never a prefix (D654).
+*
+* A plain `writeFile` truncates the target and then writes it in chunks, so a
+* reader in between gets a torn file: a fixed-path single-instance media kind
+* (`lastFrame`, `lastSceneFrame`) is overwritten every roll while a
+* notification may be reading it. Here the bytes go to a temp file in the SAME
+* directory (same filesystem, so the rename cannot degrade to a copy), and a
+* `rename` swaps it in — atomic on POSIX. A reader that already opened the old
+* file keeps reading the old inode to the end.
+*
+* The temp name is DOT-prefixed so every directory scan that skips dot entries
+* (occupancy, D327) never counts it; it is removed on any failure. A process
+* killed between the write and the rename leaves one `.<name>.<uuid>.tmp`.
+*
+* Windows: a rename over a file another process holds open can fail with
+* EPERM/EACCES/EBUSY. It is retried briefly and then falls back to copying the
+* temp over the target — non-atomic, exactly the pre-D654 behaviour, rather
+* than losing the write.
+*
+* Cost: one extra `rename` (and, on failure, one `rm`) per write — a metadata
+* operation, independent of the payload size.
+*/
+async function writeFileAtomic(filePath, data) {
+	const tmp = path$1.join(path$1.dirname(filePath), `.${path$1.basename(filePath)}.${randomUUID()}.tmp`);
+	try {
+		await fs.promises.writeFile(tmp, data);
+		await renameOver(tmp, filePath);
+	} catch (err) {
+		await fs.promises.rm(tmp, { force: true }).catch(() => void 0);
+		throw err;
+	}
+}
+async function renameOver(tmp, filePath) {
+	for (let attempt = 0;; attempt += 1) try {
+		await fs.promises.rename(tmp, filePath);
+		return;
+	} catch (err) {
+		const code = errnoCode(err);
+		if (!(process.platform === "win32" && code !== void 0 && WINDOWS_RENAME_BUSY.has(code))) throw err;
+		if (attempt < WINDOWS_RENAME_RETRIES) {
+			await new Promise((resolve) => setTimeout(resolve, WINDOWS_RENAME_RETRY_MS));
+			continue;
+		}
+		await fs.promises.copyFile(tmp, filePath);
+		await fs.promises.rm(tmp, { force: true });
+		return;
+	}
+}
+//#endregion
 //#region src/storage/filesystem-storage-provider.ts
 var STORAGE_LOCATION_TYPES = [
 	"data",
@@ -1794,14 +1857,16 @@ var FilesystemStorageProvider = class {
 			relativePath
 		});
 		await fs.promises.mkdir(path$1.dirname(filePath), { recursive: true });
-		if (Buffer.isBuffer(data)) await fs.promises.writeFile(filePath, data);
+		if (Buffer.isBuffer(data)) await writeFileAtomic(filePath, data);
 		else {
-			const writeStream = fs.createWriteStream(filePath);
-			await new Promise((resolve, reject) => {
-				data.pipe(writeStream);
-				writeStream.on("finish", resolve);
-				writeStream.on("error", reject);
-			});
+			const tmp = path$1.join(path$1.dirname(filePath), `.${path$1.basename(filePath)}.${randomUUID()}.tmp`);
+			try {
+				await pipeline(data, fs.createWriteStream(tmp));
+				await fs.promises.rename(tmp, filePath);
+			} catch (err) {
+				await fs.promises.rm(tmp, { force: true }).catch(() => void 0);
+				throw err;
+			}
 		}
 	}
 	async read({ location, relativePath }) {
@@ -2033,4 +2098,4 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl };
+export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, signExpiringUrl, verifyExpiringUrl, writeFileAtomic };

package/dist/notification/system-event-summary.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The STATE SUMMARY delivery of a system-event rule (D647): which rules may use
+ * it, and how an editor presents its schedule. One module, read by the hub's
+ * save guard, the notification centre's scheduler and both rule editors.
+ *
+ * A `device-events` or `system` rule may say `systemEventDelivery: { mode:
+ * 'summary', schedule }`: it then sends nothing per event, and at the END of
+ * each window of `schedule` it sends the current state of its kinds. The alarm
+ * stays instant (an alarm summarised at 08:00 is an alarm nobody heard), and a
+ * `mixed` rule is read-only (D637), so neither may carry it.
+ *
+ * Pure: no clock, no I/O.
+ */
+import type { NcDelivery, NcRuleActions, NcSchedule, NcSystemEventCondition, NcSystemEventDelivery } from '../capabilities/notification-rules.cap.js';
+import { type NcSystemEventFamily } from './system-event-families.js';
+/** The families a rule may summarise. The alarm is not one of them. */
+export declare const NC_SYSTEM_EVENT_SUMMARY_FAMILIES: readonly NcSystemEventFamily[];
+/** The part of a rule the summary delivery is judged on. */
+export interface NcSystemEventDeliverySubject {
+    readonly delivery: NcDelivery;
+    readonly conditions: {
+        readonly systemEvent?: NcSystemEventCondition;
+    };
+    readonly systemEventDelivery?: NcSystemEventDelivery;
+    readonly schedule?: NcSchedule;
+    readonly actions?: NcRuleActions;
+}
+export type NcSystemEventDeliveryProblem = {
+    readonly code: 'not-a-system-rule';
+    readonly delivery: NcDelivery;
+} | {
+    readonly code: 'family-not-summarisable';
+    readonly family: NcSystemEventFamily | 'mixed';
+} | {
+    readonly code: 'empty-schedule';
+} | {
+    readonly code: 'degenerate-window';
+    readonly index: number;
+} | {
+    readonly code: 'schedule-beside-summary';
+} | {
+    readonly code: 'actions-beside-summary';
+};
+/** The summary's schedule, or `null` for any rule that is not a summary system rule. */
+export declare function systemEventSummaryScheduleOf(rule: Pick<NcSystemEventDeliverySubject, 'delivery' | 'systemEventDelivery'>): NcSchedule | null;
+/** Absent and `instant` are the same answer: a notification per event. */
+export declare function isSystemEventSummaryRule(rule: Pick<NcSystemEventDeliverySubject, 'delivery' | 'systemEventDelivery'>): boolean;
+/**
+ * Why the hub refuses this rule's delivery. Empty = accepted. An instant rule
+ * (absent or `{ mode: 'instant' }`) is never refused here.
+ *
+ * Beside a summary, two fields are refused because they would do nothing:
+ * the rule's own `schedule` (the summary's schedule is the send time; a second
+ * active-hours gate would silently empty it) and `actions` (a summary is not a
+ * match, so nothing would ever run them).
+ */
+export declare function systemEventDeliveryProblems(rule: NcSystemEventDeliverySubject): readonly NcSystemEventDeliveryProblem[];
+export declare function describeSystemEventDeliveryProblem(problem: NcSystemEventDeliveryProblem): string;
+/** One send time as an editor presents it: the days it is sent on, and the minute. */
+export interface NcSummarySendTime {
+    readonly days: readonly number[];
+    /** Minute of the day, 0–1439. */
+    readonly minute: number;
+}
+/**
+ * A send time is a ONE-MINUTE window that closes at that minute: the summary is
+ * sent when a window ends. Midnight starts the window at 23:59 of the day
+ * BEFORE, because a window's `days` are the days it STARTS on.
+ */
+export declare function scheduleForSendTimes(times: readonly NcSummarySendTime[], timezone?: string): NcSchedule;
+/**
+ * The send times a schedule stands for, or `null` when it is not a list of
+ * one-minute windows (an inverted or a longer window): the editor then shows
+ * the raw windows and says the summary is sent when each one ENDS.
+ */
+export declare function sendTimesOfSchedule(schedule: NcSchedule): readonly NcSummarySendTime[] | null;
+/**
+ * Does a custom BODY carry the summary's content (`{{summaryText}}` or a
+ * section variable)? A body that does not would send a summary with nothing
+ * in it; the hub then appends `{{summaryText}}` and the admin warns (review
+ * M3). An absent or blank body uses the hub's own wording, which does.
+ */
+export declare function templateCarriesSummary(body: string | undefined): boolean;

package/dist/notification/template-vars.d.ts

@@ -36,6 +36,21 @@ export declare const NC_TEMPLATE_HELD_BACK_SYSTEM_EVENT_KINDS: readonly NcSystem
  * rule an installed viewer can author, which is exactly true.
  */
 export declare function servedTemplateVars(): NcTemplateVarDescriptor[];
+/**
+ * Is this descriptor held back from the SERVED catalog as a whole (D647)?
+ * A summary-only variable is: an installed viewer does not read the delivery
+ * axis, and would offer it on every instant system rule. The admin, built
+ * from the workspace, restores it from its own `NC_TEMPLATE_VARS`.
+ */
+export declare function isHeldBackTemplateVar(d: NcTemplateVarDescriptor): boolean;
+/**
+ * Does a descriptor have a value on a system rule of this DELIVERY (D647)?
+ * Read only for a system rule kind. An absent axis is `instant` for a
+ * descriptor that names `systemEventKinds` (a per-event fact: a summary row
+ * has no one device, node or package) and BOTH for one that does not
+ * (`{{rule}}`, `{{time}}`).
+ */
+export declare function templateVarDeliveryApplies(d: NcTemplateVarDescriptor, ctx: NcTemplateVarContext): boolean;
 /**
  * Does a descriptor declared for `declared` kinds have a value for a rule of
  * `kind`?

package/dist/pipeline/cluster-model-scope.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Why the orchestrator cannot say which model the operator chose for a
+ * cluster-scoped step (D651).
+ */
+export declare const CLUSTER_MODEL_CHOICE_UNREADABLE_REASONS: readonly ["owner-not-ready", "store-read-failed", "three-way-read-unavailable", "invalid-stored", "not-cluster-scoped"];
 /**
  * How a step's model is chosen.
  *
@@ -66,13 +71,58 @@ export declare function isClusterScopedStep(stepId: string): boolean;
 export type ClusterStepModels = Readonly<Record<string, string>>;
 /** The cluster row when nobody has configured one — today's catalog defaults. */
 export declare const DEFAULT_CLUSTER_STEP_MODELS: ClusterStepModels;
+/**
+ * What ONE stored `clusterModel:<stepId>` value means (D651 fix round 4).
+ *
+ *  - `absent` — nobody chose. The key was never written, or the settings form
+ *    cleared it: a select clears a field with a `null` patch, and `hydrateSchema`
+ *    reads a stored `null` as `value ?? default` on every hydrated surface, so
+ *    `null` and `''` are the same statement as "never written".
+ *  - `chosen` — a non-empty string, taken VERBATIM. Not checked against the
+ *    step's `options`: the runtime pins an id the catalog does not list on
+ *    purpose (`cluster-model-resolution.ts`: a custom encoder from
+ *    `custom-model-registry` is the operator's own compatibility problem), and
+ *    the dropdown is guarded separately by `scripts/check-cluster-model-scope.ts`.
+ *    An owner that called such an id invalid while the runner ran it would give
+ *    the same stored key two meanings — the defect this function removes.
+ *  - `invalid` — anything else (a number, an object). The form cannot write it;
+ *    it is a hand edit or a corrupted row.
+ *
+ * Both readers of the key go through this function: the runner's
+ * {@link readClusterStepModels} and the owner's `decideClusterModelChoice`
+ * (addon-pipeline-orchestrator). They differ only in what they DO with
+ * `invalid`: a live row is total, so the runner falls to the catalog default
+ * and says so in its log (`ClusterModelSource`); a pass that would rewrite an
+ * index on it refuses (`invalid-stored`).
+ */
+export type StoredClusterModelInterpretation = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'chosen';
+    readonly modelId: string;
+} | {
+    readonly kind: 'invalid';
+    readonly value: unknown;
+};
+export declare function interpretStoredClusterModel(raw: unknown): StoredClusterModelInterpretation;
+/** One stored cluster model value the interpretation rejected. */
+export interface InvalidClusterStepModelEntry {
+    readonly stepId: string;
+    readonly value: unknown;
+}
+/**
+ * The cluster-scoped steps whose stored value is `invalid` under
+ * {@link interpretStoredClusterModel} — for the runtime's log line, so the
+ * default it runs on such a row is never run in silence.
+ */
+export declare function invalidClusterStepModelEntries(config: Readonly<Record<string, unknown>>): readonly InvalidClusterStepModelEntry[];
 /**
  * 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
+ * junk face model must not also discard a valid clip model. An `absent` or
+ * `invalid` value ({@link interpretStoredClusterModel}) resolves to the step's
+ * catalog default — 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.
  */
@@ -98,6 +148,12 @@ export interface HydratedClusterView {
  * (addon mid-boot) is the defaults.
  */
 export declare function pickClusterStepModels(view: HydratedClusterView | null): ClusterStepModels;
+/**
+ * The `invalid` stored cluster model values a hydrated view carries — what the
+ * runtime logs when it runs a default on a row it could not read as a choice.
+ * A `null` view (owner mid-boot) carries nothing to judge.
+ */
+export declare function pickInvalidClusterStepModels(view: HydratedClusterView | null): readonly InvalidClusterStepModelEntry[];
 /**
  * The cluster model for `stepId`, or `null` when the step is node-scoped.
  *