diff --git a/README.md b/README.md
index 1fa777e..0b45d90 100644
--- a/README.md
+++ b/README.md
@@ -383,8 +383,9 @@ telemetry and the stop action. Operator-manual acquisition still finalizes only
local reception; plugin-commanded v0.5.0 acquisition uses the separately gated
canonical K1 START/STOP dialogue.
-Plugin v0.6.0 makes the local connection direction explicit. Bridge remains the
-default and accepted product path; Direct Connect sends the reviewed station
+Plugin v0.7.0 supervises the v0.6.0 local connection matrix with separate
+desired, configured and active modes plus exact DeviceInfo-backed Ready.
+Bridge remains the default and accepted product path; Direct Connect sends the reviewed station
provisioning frame for an already-running controller hotspot. Quick Connect
sends one separately reviewed AP-enable frame and can associate a prepared Mac
through CoreWLAN. Its device activation and prepared-host association were
diff --git a/apps/control-station/README.md b/apps/control-station/README.md
index 2b2efd4..d076462 100644
--- a/apps/control-station/README.md
+++ b/apps/control-station/README.md
@@ -321,10 +321,12 @@ facts и старые presentation-поля `phase`, `message`, `devices`,
активным между сессиями; для его закрытия нужно остановить `k1link serve`.
- Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body,
очищается после успешного ответа и не сохраняется в URL/local storage.
-- Bridge и Direct Connect выполняют только отдельно рассмотренную provisioning-
- запись; Quick Connect не пишет в GATT и передаёт пароль короткоживущему
- CoreWLAN helper только через stdin. Случайные GATT writes и автоматические
- повторы запрещены.
+- Bridge и Direct Connect выполняют только отдельно рассмотренную 99-байтную
+ provisioning-запись. Quick Connect выполняет отдельную рассмотренную
+ 100-байтную AP-enable запись и после AP-ready допускает ровно одну системную
+ ассоциацию с заранее материализованным exact-firmware профилем. Пароль не
+ попадает в браузер/API/argv; системный Wi-Fi Keychain, post-write prompt и
+ автоматические повторы запрещены.
- MQTT data live/replay остаётся subscribe-only. Команды изолированы в
plugin-owned canonical control session и доступны только через отдельные
operator-present UI checkpoints.
diff --git a/apps/control-station/src/App.tsx b/apps/control-station/src/App.tsx
index 23f7571..e8063b9 100644
--- a/apps/control-station/src/App.tsx
+++ b/apps/control-station/src/App.tsx
@@ -63,7 +63,7 @@ import {
workspacesForRoot,
type RootId,
} from "./productModel";
-import { backendLabel, phaseLabel, phaseTone } from "./presentation";
+import { backendLabel, localConnectionPhaseLabel, phaseTone } from "./presentation";
import {
defaultSceneSettings,
type PointColorMode,
@@ -595,8 +595,8 @@ export default function App() {
setRecordedReplayLabel(null);
setSourceUrl("");
setSourceDraft("");
- }, []);
-
+ observationLayout.activateAutomaticDefaults();
+ }, [observationLayout.activateAutomaticDefaults]);
useEffect(() => {
if (!["recordings", "lab-archive"].includes(activeDefinition?.kind ?? "")) {
setReplayTransitioning(false);
@@ -638,6 +638,8 @@ export default function App() {
const contentActions = useApplicationPanelActions({
definition: activeDefinition,
refreshRuntime: runtime.refresh,
+ resetConnectionScenario: runtime.resetConnectionScenario,
+ connectionScenarioResetting: runtime.pendingAction === "mode",
saveWorkspaceLayout,
workspaceLayoutSaving: workspaceLayoutProfile.state === "saving",
systemUtilityActions: computeContourSettings.utilityActions,
@@ -728,10 +730,7 @@ export default function App() {
{
id: "local-contour",
label: "Локальный контур",
- description:
- runtime.state?.activeDevice?.endpointLabel ||
- selection?.model.displayName ||
- "Модель не выбрана",
+ description: selection ? "Подключение" : "Модель не выбрана",
icon: ,
active:
runtime.backendStatus !== "offline"
@@ -777,7 +776,7 @@ export default function App() {
headerTools={
activeDefinition.kind === "device" ? (
- {phaseLabel(runtime.state?.phase)}
+ {localConnectionPhaseLabel(runtime.state?.phase)}
) : activeDefinition.kind === "spatial" ? (
/,
+ );
+ assert.match(form, /disabled=\{provisioningFieldsDisabled\}/);
+ assert.match(form, /value=\{connectionAttemptOwnsDraft \? "" : password\}/);
+ assert.match(
+ styles,
+ /\.field-stack,\s*\.session-form\s*\{\s*display:\s*grid;\s*gap:\s*0\.85rem;/,
+ );
+});
+
+test("applied-network recovery spends the old intent and admits only explicit server-authorized paths", () => {
+ const source = readFileSync(provisioningSourceUrl, "utf8");
+ const apply = sourceSlice(source, "const submitConnect", "const verifyAppliedNetwork");
+ const recoveryState = sourceSlice(
+ source,
+ "const appliedNetworkAttempt",
+ "const localProvisioningPrerequisitesReady",
+ );
+ const appliedRecoveryTarget = sourceSlice(
+ source,
+ "const appliedNetworkRecoveryTarget",
+ "const networkRecoveryModeLabel",
+ );
+ const connectAuthority = sourceSlice(
+ source,
+ "const canConnect",
+ "const scanAllowedByPolicy",
+ );
+ const scanAuthority = sourceSlice(
+ source,
+ "const backendScanAllowed",
+ "const physicalStopRecoverySettling",
+ );
+ const search = sourceSlice(source, "const repeatDeviceScan", "const submitConnect");
+ const recovery = sourceSlice(
+ source,
+ "const verifyAppliedNetwork",
+ "const verifyConnectionRecoveryTarget",
+ );
+ const prepare = sourceSlice(
+ source,
+ "const prepareReconfiguration",
+ "const changeDesiredConnectionMode",
+ );
+ const mode = sourceSlice(
+ source,
+ "const changeDesiredConnectionMode",
+ "const selectFreshDevice",
+ );
+ const selection = sourceSlice(
+ source,
+ "const selectFreshDevice",
+ "// Only an explicit public search",
+ );
+ const recoveryEscape = sourceSlice(
+ source,
+ "const recoverBySelectingAnotherDevice",
+ "const attemptButtonLabel",
+ );
+
+ assert.doesNotMatch(apply, /verifyConnection\(/);
+ assert.match(recoveryState, /state\?\.connection_attempt\?\.phase === "network_applied"/);
+ assert.match(
+ recoveryState,
+ /connectionAttemptOwnsAppliedNetworkRecovery\(appliedNetworkAttempt\)/,
+ );
+ assert.match(
+ recoveryState,
+ /`\$\{snapshotRuntimeId\}:\$\{appliedNetworkAttempt\.attempt_id\}`/,
+ );
+ assert.match(
+ recoveryState,
+ /escapedAppliedAttemptKey === appliedAttemptRecoveryKey[\s\S]*?\|\| appliedRecoveryReconfigurationPrepared/,
+ );
+ assert.match(
+ recoveryState,
+ /connectionAttemptOwnsAppliedNetworkRecovery\(appliedNetworkAttempt\)[\s\S]*?&& !appliedRecoveryExplicitlyEscaped/,
+ );
+ assert.match(recoveryState, /const networkRecoveryRequired = unresolvedAppliedAttempt !== null/);
+ assert.match(
+ recoveryState,
+ /const appliedControlSettlementPending = Boolean\([\s\S]*?\["accepted", "running"\]\.includes\(unresolvedAppliedAttempt\.status\)[\s\S]*?safe_next_action === "wait-for-current-attempt"/,
+ );
+ assert.doesNotMatch(
+ appliedRecoveryTarget,
+ /\bconnectionMode\b|selectedDeviceId|selectedTarget/,
+ );
+ assert.match(
+ appliedRecoveryTarget,
+ /serverBoundAppliedNetworkObservationTarget\(\s*state,\s*unresolvedAppliedAttempt\.connection_mode/,
+ );
+
+ assert.match(connectAuthority, /!unresolvedAppliedAttempt/);
+ assert.match(scanAuthority, /!networkRecoveryRequired/);
+ assert.match(apply, /\|\| unresolvedAppliedAttempt/);
+ assert.match(apply, /provisioningIntentKey\(null\)/);
+ assert.match(mode, /if \(modeResetInFlight\) return/);
+ assert.match(mode, /reset_scenario: true/);
+ assert.match(selection, /networkRecoveryRequired\s*\|\|/);
+ assert.doesNotMatch(
+ source,
+ /powerConfirmed|powerConfirmationEpoch|resetPowerConfirmation|Питание включено|title="Питание"/,
+ );
+ assert.match(source, /value=\{connectionMode\}[\s\S]*?onChange=\{\(value\) => void changeDesiredConnectionMode\(value\)\}/);
+ assert.match(
+ sourceSlice(source, " void repeatDeviceScan\(\{\s*appliedRecoveryEscape: true/,
+ );
+ assert.match(source, /Начать новый поиск Bluetooth/);
+ assert.match(source, /Подтверждаем управляющее подключение/);
+ assert.match(source, /BLE-команда не повторяется/);
+ assert.match(
+ source,
+ /status=\{\s*searchActive[\s\S]*?: physicalRecoveryRequired[\s\S]*?: networkRecoveryRequired[\s\S]*?>\s*\{searchActive \? \([\s\S]*?Поиск Bluetooth · \{scanSecondsRemaining \?\? 6\} с[\s\S]*?: networkRecoveryRequired && !connectionAttemptSettling \? \(/,
+ );
+
+ assert.match(
+ source,
+ /if \(!appliedNetworkAttempt\) return;[\s\S]*?setExplicitProvisioningDraft\(null\);[\s\S]*?setSsid\(""\);[\s\S]*?setPassword\(""\)/,
+ );
+ const appliedAttemptEffect = sourceSlice(
+ source,
+ "if (!appliedNetworkAttempt) return;",
+ "if (connectionAttemptView !== \"retired\") return;",
+ );
+ assert.doesNotMatch(appliedAttemptEffect, /setConnectionAttemptPresentation\(null\)/);
+ assert.doesNotMatch(apply, /void submitConnect|repeatDeviceScan\(/);
+
+ const settlingState = durableTopologyState();
+ settlingState.connection_attempt = {
+ schema_version: "missioncore.xgrids-k1-connection-attempt/v1",
+ attempt_id: "network-apply-settling",
+ connection_mode: "bridge",
+ status: "running",
+ phase: "network_applied",
+ control_state: "unknown",
+ stage: "host-route-and-control-endpoint",
+ public_error_code: null,
+ side_effect_status: "none",
+ safe_next_action: "wait-for-current-attempt",
+ automatic_retry: false,
+ accepted_at: OBSERVED_AT,
+ completed_at: null,
+ recovery_operation_id: null,
+ timeline: [],
+ };
+ const settlingMarkup = renderProvisioning({
+ controller: provisioningController(settlingState),
+ desiredMode: "bridge",
+ });
+ assert.match(settlingMarkup, /Подтверждаем управляющее подключение/);
+ assert.match(settlingMarkup, /BLE-команда не повторяется/);
+ assert.doesNotMatch(settlingMarkup, /Сеть (?:готова|настроена)|Сетевые настройки уже применены/);
+ assert.equal(
+ (settlingMarkup.match(/class="connection-action-progress"/g) ?? []).length,
+ 1,
+ );
+ assert.doesNotMatch(
+ settlingMarkup,
+ /Проверить подключение без изменения сети|Начать выбор другого K1|Начать новый поиск Bluetooth/,
+ );
+});
+
+
+test("incomplete historical recovery policy stays outside the normal connection form", () => {
+ const state = durableTopologyState();
+ state.network_mutation_ledger = {
+ ...state.network_mutation_ledger,
+ status: "unresolved",
+ mutation_allowed: false,
+ operation_id: "operation-002",
+ transport_ref: "ble-k1-001",
+ intended_mode: "bridge",
+ stage: "observing",
+ revision: 6,
+ };
+ state.connection_policy = {
+ schema_version: "missioncore.xgrids-k1-connection-policy/v1",
+ facts: { retained_context_is_presence: false },
+ allowed_actions: ["observe-configured-device-network"],
+ actions: {
+ "observe-configured-device-network": {
+ allowed: true,
+ reason_codes: [],
+ target_source: "durable-configured-state",
+ required_transport_ref: "ble-k1-001",
+ required_connection_mode: null,
+ requires_live_gatt_validation: true,
+ automatic_retry: false,
+ },
+ },
+ recommended_action: "observe-configured-device-network",
+ };
+
+ const markup = renderProvisioning({
+ controller: provisioningController(state),
+ desiredMode: "bridge",
+ });
+
+ assert.doesNotMatch(markup, /Сервер пока не выдал одну точную цель/);
+ assert.doesNotMatch(markup, /не подменяют UUID и режим незавершённой операции/);
+ assert.doesNotMatch(markup, /Проверить .*без записи/);
+ assert.equal(
+ buttonMarkupWithText(markup, "Подключиться к сохранённому устройству").length,
+ 0,
+ );
+ assert.doesNotMatch(markup, /class="connection-action-progress"/);
+ assert.doesNotMatch(markup, /Проверить связь/);
+ assert.doesNotMatch(markup, /Подключить K1 к общей сети/);
+});
+
+
+test("configured endpoint policy explains missing durable evidence without implying BLE", () => {
+ const state = durableTopologyState();
+ state.semantic_topology_store = {
+ status: "empty",
+ configured_offline_evidence: false,
+ live_connection_authority: false,
+ reason_code: null,
+ record: null,
+ };
+ state.connection_policy = {
+ schema_version: "missioncore.xgrids-k1-connection-policy/v1",
+ facts: { retained_context_is_presence: false },
+ allowed_actions: [],
+ actions: {
+ "inspect-configured-endpoint": {
+ allowed: false,
+ reason_codes: ["configured-endpoint-unavailable"],
+ target_source: "configured-topology",
+ required_transport_ref: null,
+ requires_live_gatt_validation: false,
+ automatic_retry: false,
+ },
+ },
+ recommended_action: "inspect-host-network",
+ };
+
+ const guidance = connectionPolicyOperatorGuidance(
+ state,
+ "inspect-configured-endpoint",
+ );
+ assert.match(guidance.reason, /Нет подтверждённого сохранённого адреса K1/);
+ assert.match(guidance.nextAction, /Проверьте активную локальную сеть/);
+ assert.doesNotMatch(`${guidance.reason} ${guidance.nextAction}`, /Bluetooth|BLE/);
+});
+
+test("spatial controls distinguish control authority from data authority", () => {
+ const live = runtimeState();
+ assert.deepEqual(k1SpatialAuthorityState(live), {
+ controlAuthoritative: true,
+ dataAuthoritative: true,
+ softwareCommanded: true,
+ authorityFailure: null,
+ });
+
+ live.connection_supervisor = supervisor({ control: true, data: false });
+ const waiting = k1SpatialAuthorityState(live);
+ assert.equal(waiting.controlAuthoritative, true);
+ assert.equal(waiting.dataAuthoritative, false);
+ assert.equal(waiting.softwareCommanded, true);
+ assert.match(waiting.authorityFailure, /Телеметрия скрыта/);
+
+ live.connection_supervisor = supervisor({ control: false, data: false });
+ const lost = k1SpatialAuthorityState(live);
+ assert.equal(lost.controlAuthoritative, false);
+ assert.equal(lost.dataAuthoritative, false);
+ assert.equal(lost.softwareCommanded, false);
+ assert.match(lost.authorityFailure, /команды устройству запрещены/);
+});
+
+test("spatial controls explain the bounded K1 calibration wait before point data", () => {
+ const acquisition = runtimeState().acquisition;
+ assert.ok(acquisition);
+ for (const state of ["awaiting_external_start", "starting"]) {
+ const phase = k1SpatialPhasePresentation({ ...acquisition, state }, true);
+ assert.equal(phase.busy, true);
+ assert.match(phase.label, /калибруется.*облако точек/i);
+ assert.match(phase.detail, /десятки секунд/i);
+ assert.match(phase.detail, /не перемещайте/i);
+ assert.doesNotMatch(phase.detail, /30\s*с/i);
+ }
+});
+
+test("contour health never promotes selection or replay metrics to live authority", () => {
+ const selectedOnly = {
+ phase: "starting",
+ sourceMode: "idle",
+ activeDevice: {
+ pluginId: "xgrids-k1",
+ modelId: "lixelkity-k1",
+ displayName: "XGRIDS LixelKity K1",
+ instanceId: "device-k1-001",
+ endpointLabel: "192.168.68.52",
+ },
+ deviceSession: {
+ sessionId: "device-session-001",
+ deviceId: "device-k1-001",
+ compatibilityProfileId: PROFILE_ID,
+ connectivity: "unknown",
+ },
+ metrics: { aiFrameRateHz: 8 },
+ };
+ const unverified = contourRuntimeAuthorityPresentation(selectedOnly);
+ assert.equal(unverified.controlledDevice, null);
+ assert.equal(unverified.aiActive, false);
+
+ const live = contourRuntimeAuthorityPresentation({
+ ...selectedOnly,
+ phase: "streaming",
+ sourceMode: "live",
+ deviceSession: { ...selectedOnly.deviceSession, connectivity: "connected" },
+ });
+ assert.equal(live.controlledDevice.instanceId, "device-k1-001");
+ assert.equal(live.aiActive, true);
+
+ const replay = contourRuntimeAuthorityPresentation({
+ ...selectedOnly,
+ phase: "replaying",
+ sourceMode: "replay",
+ deviceSession: { ...selectedOnly.deviceSession, connectivity: "connected" },
+ });
+ assert.equal(replay.aiActive, false);
+});
diff --git a/apps/control-station/test/liveReceiverWatchdog.test.mjs b/apps/control-station/test/liveReceiverWatchdog.test.mjs
index e0cf274..d13a14f 100644
--- a/apps/control-station/test/liveReceiverWatchdog.test.mjs
+++ b/apps/control-station/test/liveReceiverWatchdog.test.mjs
@@ -4,9 +4,14 @@ import { after, before, test } from "node:test";
import { createServer } from "vite";
let server;
+let advanceLiveReceiverOpenWatchdog;
let advanceLiveReceiverWatchdog;
+let initialLiveReceiverOpenWatchdogState;
let initialLiveReceiverWatchdogState;
let initialLiveReceiverRecoveryState;
+let liveReceiverRecoveryAuthorityIsCurrent;
+let liveReceiverRecoveryRetryDelay;
+let liveRerunRecoveryAuthorityIdentity;
let requestLiveReceiverRecovery;
before(async () => {
@@ -16,9 +21,14 @@ before(async () => {
server: { middlewareMode: true },
});
({
+ advanceLiveReceiverOpenWatchdog,
advanceLiveReceiverWatchdog,
+ initialLiveReceiverOpenWatchdogState,
initialLiveReceiverRecoveryState,
initialLiveReceiverWatchdogState,
+ liveReceiverRecoveryAuthorityIsCurrent,
+ liveReceiverRecoveryRetryDelay,
+ liveRerunRecoveryAuthorityIdentity,
requestLiveReceiverRecovery,
} = await server.ssrLoadModule("/src/core/observation/liveReceiverWatchdog.ts"));
});
@@ -92,3 +102,217 @@ test("startup failures request only three bounded viewer restarts", () => {
assert.equal(exhausted.attempt, 3);
assert.equal(exhausted.state.awaitingRecovery, false);
});
+
+function livePointCloudDescriptor(overrides = {}) {
+ return {
+ id: "xgrids-k1:lixelkity-k1:sensor.lidar.primary",
+ sourceId: "sensor.lidar.primary",
+ semanticChannelId: "spatial.point-cloud.live",
+ label: "K1 point cloud",
+ description: "live",
+ modality: "point-cloud",
+ role: "primary",
+ availability: "streaming",
+ transport: "rerun-grpc",
+ endpointLabel: "Rerun gRPC",
+ previewUrl: "rerun+http://127.0.0.1:9877/proxy",
+ delivery: null,
+ activation: null,
+ presentationLease: null,
+ provider: {
+ pluginId: "xgrids-k1",
+ pluginVersion: "0.1.0",
+ modelId: "lixelkity-k1",
+ compatibilityProfileId: "xgrids.lixelkity-k1.fw-3.0.2.local-network.v2",
+ },
+ binding: {
+ deviceId: "device-k1-001",
+ deviceSessionId: "device-session-001",
+ acquisitionId: "acquisition-001",
+ },
+ capabilities: {
+ overlay: false,
+ fullscreen: true,
+ resizable: false,
+ defaultVisible: true,
+ timelineMode: "live-only",
+ seekable: false,
+ sessionRecording: false,
+ clockId: "acquisition-001",
+ spatialRegistration: "native",
+ },
+ ...overrides,
+ };
+}
+
+const liveSpatialSource = {
+ id: "acquisition-001",
+ url: "rerun+http://127.0.0.1:9877/proxy",
+ label: "Live",
+ kind: "rerun-grpc",
+};
+
+test("exact live Rerun authority gets durable retries with capped delay", () => {
+ const authority = liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor(),
+ liveSpatialSource,
+ );
+ assert.ok(authority);
+ assert.equal(liveReceiverRecoveryAuthorityIsCurrent(authority, authority), true);
+
+ let state = initialLiveReceiverRecoveryState();
+ const delays = [];
+ for (let attempt = 1; attempt <= 8; attempt += 1) {
+ const recovery = requestLiveReceiverRecovery(state, {
+ activeAuthorityIdentity: authority,
+ expectedAuthorityIdentity: authority,
+ });
+ assert.equal(recovery.signal, "retry");
+ assert.equal(recovery.attempt, attempt);
+ delays.push(recovery.delayMs);
+ state = recovery.state;
+ }
+ assert.deepEqual(delays, [400, 1_000, 2_000, 5_000, 5_000, 5_000, 5_000, 5_000]);
+ assert.equal(state.attempts, 8);
+ assert.equal(liveReceiverRecoveryRetryDelay(100), 5_000);
+});
+
+test("Rerun durable retry fails closed when exact authority is replaced", () => {
+ const authority = liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor(),
+ liveSpatialSource,
+ );
+ assert.ok(authority);
+ const replacement = liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor({
+ binding: {
+ deviceId: "device-k1-001",
+ deviceSessionId: "device-session-002",
+ acquisitionId: "acquisition-002",
+ },
+ capabilities: {
+ ...livePointCloudDescriptor().capabilities,
+ clockId: "acquisition-002",
+ },
+ }),
+ { ...liveSpatialSource, id: "acquisition-002" },
+ );
+ assert.ok(replacement);
+
+ const stale = requestLiveReceiverRecovery(initialLiveReceiverRecoveryState(), {
+ activeAuthorityIdentity: replacement,
+ expectedAuthorityIdentity: authority,
+ });
+ assert.equal(stale.signal, "stale");
+ assert.equal(stale.delayMs, null);
+ assert.deepEqual(stale.state, initialLiveReceiverRecoveryState());
+});
+
+test("connecting Rerun authority requires an exact recovery generation lease", () => {
+ const recoveryLease = {
+ kind: "active-stream-recovery",
+ runtimeId: "runtime-recovery-001",
+ acquisitionId: "acquisition-001",
+ acquisitionStateRevision: 4,
+ producerGeneration: 17,
+ recoveryGeneration: 6,
+ };
+ const recoveredAuthority = liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor({
+ availability: "connecting",
+ presentationLease: recoveryLease,
+ }),
+ liveSpatialSource,
+ );
+ assert.ok(recoveredAuthority);
+ assert.equal(
+ liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor({ availability: "connecting" }),
+ liveSpatialSource,
+ ),
+ null,
+ );
+ assert.equal(
+ liveRerunRecoveryAuthorityIdentity(
+ livePointCloudDescriptor({
+ availability: "connecting",
+ presentationLease: { ...recoveryLease, producerGeneration: 0 },
+ }),
+ liveSpatialSource,
+ ),
+ null,
+ );
+});
+
+test("opening receiver gets bounded rolling patience while backend publication advances", () => {
+ let openState = initialLiveReceiverOpenWatchdogState(0, 0);
+ let recoveryState = initialLiveReceiverRecoveryState();
+
+ const samples = [
+ [134, 3_999, "wait-for-store"],
+ [266, 4_000, "refresh-receiver"],
+ ];
+ for (const [backendActivitySequence, nowMs, expectedSignal] of samples) {
+ const observed = advanceLiveReceiverOpenWatchdog(
+ openState,
+ recoveryState,
+ backendActivitySequence,
+ nowMs,
+ );
+ assert.equal(observed.signal, expectedSignal);
+ assert.equal(observed.state.lastBackendActivitySequence, backendActivitySequence);
+ assert.deepEqual(observed.recoveryState, {
+ attempts: 0,
+ awaitingRecovery: false,
+ });
+ openState = observed.state;
+ recoveryState = observed.recoveryState;
+ }
+});
+
+test("unchanged opening sequence delegates to bounded receiver restart", () => {
+ const openState = initialLiveReceiverOpenWatchdogState(486);
+ const recoveryState = initialLiveReceiverRecoveryState();
+ const unchanged = advanceLiveReceiverOpenWatchdog(
+ openState,
+ recoveryState,
+ 486,
+ );
+
+ assert.equal(unchanged.signal, "restart-receiver");
+ const restart = requestLiveReceiverRecovery(unchanged.recoveryState);
+ assert.equal(restart.signal, "retry");
+ assert.equal(restart.attempt, 1);
+});
+
+test("fresh backend progress preserves earlier restart debt until viewer admission", () => {
+ const openState = initialLiveReceiverOpenWatchdogState(486, 0);
+ const consumedRestart = requestLiveReceiverRecovery(initialLiveReceiverRecoveryState());
+ const observed = advanceLiveReceiverOpenWatchdog(
+ openState,
+ consumedRestart.state,
+ 600,
+ 3_999,
+ );
+
+ assert.equal(observed.signal, "wait-for-store");
+ assert.deepEqual(observed.recoveryState, {
+ attempts: 1,
+ awaitingRecovery: true,
+ });
+});
+
+test("aged active receiver refresh does not spend or erase restart debt", () => {
+ const openState = initialLiveReceiverOpenWatchdogState(486, 0);
+ const consumedRestart = requestLiveReceiverRecovery(initialLiveReceiverRecoveryState());
+ const observed = advanceLiveReceiverOpenWatchdog(
+ openState,
+ consumedRestart.state,
+ 900,
+ 4_000,
+ );
+
+ assert.equal(observed.signal, "refresh-receiver");
+ assert.deepEqual(observed.recoveryState, consumedRestart.state);
+ assert.equal(observed.openForMs, 4_000);
+});
diff --git a/apps/control-station/test/liveViewerDiagnostics.test.mjs b/apps/control-station/test/liveViewerDiagnostics.test.mjs
new file mode 100644
index 0000000..0447951
--- /dev/null
+++ b/apps/control-station/test/liveViewerDiagnostics.test.mjs
@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import { after, before, test } from "node:test";
+
+import { createServer } from "vite";
+
+let createLiveViewerDiagnosticLifecycle;
+let createAbortFencedBuildVerifier;
+let createUiBuildStaleCoordinator;
+let liveViewerDiagnosticBody;
+let server;
+let uiBuildIdFromModuleScripts;
+
+before(async () => {
+ server = await createServer({
+ appType: "custom",
+ logLevel: "silent",
+ server: { middlewareMode: true },
+ });
+ ({
+ createAbortFencedBuildVerifier,
+ createLiveViewerDiagnosticLifecycle,
+ createUiBuildStaleCoordinator,
+ liveViewerDiagnosticBody,
+ uiBuildIdFromModuleScripts,
+ } = await server.ssrLoadModule("/src/core/observation/liveViewerDiagnostics.ts"));
+});
+
+after(async () => {
+ await server?.close();
+});
+
+function createFakeScheduler() {
+ let now = 0;
+ let nextHandle = 1;
+ const jobs = new Map();
+ const schedule = (callback, delay, interval) => {
+ const handle = nextHandle;
+ nextHandle += 1;
+ jobs.set(handle, { callback, due: now + delay, interval });
+ return handle;
+ };
+ const clear = (handle) => jobs.delete(handle);
+ return {
+ scheduler: {
+ setTimeout: (callback, delay) => schedule(callback, delay, null),
+ clearTimeout: clear,
+ setInterval: (callback, delay) => schedule(callback, delay, delay),
+ clearInterval: clear,
+ },
+ advance(milliseconds) {
+ const target = now + milliseconds;
+ while (true) {
+ const next = [...jobs.entries()]
+ .filter(([, job]) => job.due <= target)
+ .sort((left, right) => left[1].due - right[1].due)[0];
+ if (!next) break;
+ const [handle, job] = next;
+ now = job.due;
+ if (job.interval === null) jobs.delete(handle);
+ else job.due += job.interval;
+ job.callback();
+ }
+ now = target;
+ },
+ pending: () => jobs.size,
+ };
+}
+
+const lineage = (viewerInstanceId, lifecycleGeneration = 1) => ({
+ uiBuildId: "/assets/index-abcdefgh.js",
+ documentInstanceId: "00000000-0000-4000-8000-000000000001",
+ viewerInstanceId,
+ lifecycleGeneration,
+});
+
+test("mounted viewer admission terminally fences 60 seconds of stale timers", () => {
+ const clock = createFakeScheduler();
+ const callbacks = [];
+ const posts = [];
+ const lifecycle = createLiveViewerDiagnosticLifecycle({
+ lineage: lineage("00000000-0000-4000-8000-000000000011"),
+ scheduler: clock.scheduler,
+ diagnosticPoster: (event, eventLineage) => posts.push({ event, eventLineage }),
+ buildVerifier: () => undefined,
+ });
+
+ lifecycle.armAdmissionTimeout(() => callbacks.push("timeout"), 12_000);
+ lifecycle.armAdmissionInterval(() => callbacks.push("discovery"), 100);
+ lifecycle.markAdmitted();
+ lifecycle.post({ eventCode: "live_receiver_active_store_admitted" });
+ clock.advance(60_000);
+
+ assert.deepEqual(callbacks, []);
+ assert.equal(clock.pending(), 0);
+ assert.equal(posts.length, 1);
+ assert.equal(posts[0].eventLineage.lifecycleGeneration, 1);
+});
+
+test("two mounted viewers keep timer and diagnostic lineage isolated", () => {
+ const clock = createFakeScheduler();
+ const posts = [];
+ const first = createLiveViewerDiagnosticLifecycle({
+ lineage: lineage("00000000-0000-4000-8000-000000000021"),
+ scheduler: clock.scheduler,
+ diagnosticPoster: (event, eventLineage) => posts.push({ event, eventLineage }),
+ buildVerifier: () => undefined,
+ });
+ const second = createLiveViewerDiagnosticLifecycle({
+ lineage: lineage("00000000-0000-4000-8000-000000000022", 7),
+ scheduler: clock.scheduler,
+ diagnosticPoster: (event, eventLineage) => posts.push({ event, eventLineage }),
+ buildVerifier: () => undefined,
+ });
+
+ first.armAdmissionTimeout(() => {
+ first.post({ eventCode: "live_receiver_error" });
+ }, 12_000);
+ second.armAdmissionTimeout(() => {
+ second.post({ eventCode: "live_receiver_error" });
+ }, 12_000);
+ first.markAdmitted();
+ clock.advance(12_000);
+
+ assert.equal(posts.length, 1);
+ assert.equal(
+ posts[0].eventLineage.viewerInstanceId,
+ "00000000-0000-4000-8000-000000000022",
+ );
+ assert.equal(posts[0].eventLineage.lifecycleGeneration, 7);
+});
+
+test("stale-build and unmount fence callbacks before one reload", () => {
+ const clock = createFakeScheduler();
+ const order = [];
+ const posts = [];
+ const lifecycle = createLiveViewerDiagnosticLifecycle({
+ lineage: lineage("00000000-0000-4000-8000-000000000031"),
+ scheduler: clock.scheduler,
+ diagnosticPoster: (event) => posts.push(event),
+ buildVerifier: () => undefined,
+ });
+ lifecycle.armAdmissionTimeout(() => {
+ lifecycle.post({ eventCode: "live_receiver_error" });
+ }, 12_000);
+ const coordinator = createUiBuildStaleCoordinator({
+ scheduleReload: (callback, delay) => {
+ order.push(`scheduled:${delay}`);
+ clock.scheduler.setTimeout(callback, delay);
+ },
+ reload: () => order.push("reload"),
+ });
+ coordinator.subscribe(() => {
+ order.push("local-transports-closed");
+ lifecycle.dispose();
+ });
+
+ coordinator.report({
+ loadedUiBuildId: "/assets/index-abcdefgh.js",
+ expectedUiBuildId: "/assets/index-ijklmnop.js",
+ });
+ coordinator.report({
+ loadedUiBuildId: "/assets/index-abcdefgh.js",
+ expectedUiBuildId: "/assets/index-qrstuvwx.js",
+ });
+ clock.advance(60_000);
+ lifecycle.post({ eventCode: "live_receiver_error" });
+
+ assert.deepEqual(order, ["local-transports-closed", "scheduled:50", "reload"]);
+ assert.deepEqual(posts, []);
+ assert.equal(lifecycle.active(), false);
+});
+
+test("last unsubscribe fences an already queued build verification callback", () => {
+ const controller = new AbortController();
+ const observedSignals = [];
+ const queuedVerify = createAbortFencedBuildVerifier(
+ controller.signal,
+ (signal) => observedSignals.push(signal),
+ );
+
+ queuedVerify();
+ // stopBuildMonitor aborts the locally captured controller when the last
+ // mounted viewer unsubscribes. A browser callback already queued before the
+ // interval/listener removal can still run once, but cannot start a fetch.
+ controller.abort();
+ queuedVerify();
+
+ assert.deepEqual(observedSignals, [controller.signal]);
+ assert.equal(observedSignals[0].aborted, true);
+});
+
+test("diagnostic body and build id retain exact document/viewer/build lineage", () => {
+ const eventLineage = lineage("00000000-0000-4000-8000-000000000041", 9);
+ assert.deepEqual(
+ liveViewerDiagnosticBody(
+ { eventCode: "live_receiver_recovered", streamId: "acquisition-42" },
+ eventLineage,
+ ),
+ {
+ schema_version: "missioncore.live-viewer-diagnostic/v2",
+ event_code: "live_receiver_recovered",
+ ui_build_id: "/assets/index-abcdefgh.js",
+ document_instance_id: "00000000-0000-4000-8000-000000000001",
+ viewer_instance_id: "00000000-0000-4000-8000-000000000041",
+ lifecycle_generation: 9,
+ stream_id: "acquisition-42",
+ },
+ );
+ assert.equal(
+ uiBuildIdFromModuleScripts(
+ ["https://mission.local/assets/index-dT7dN-y4.js"],
+ "https://mission.local/park",
+ ),
+ "/assets/index-dT7dN-y4.js",
+ );
+});
diff --git a/apps/control-station/test/observationSources.test.mjs b/apps/control-station/test/observationSources.test.mjs
index f9f960b..c0f39d2 100644
--- a/apps/control-station/test/observationSources.test.mjs
+++ b/apps/control-station/test/observationSources.test.mjs
@@ -12,6 +12,20 @@ let openObservationSource;
let shouldRestartObservationSource;
let consumeCameraLeaseRetry;
let resetCameraLeaseRetryBudget;
+let cameraTransportRecoveryIsCurrent;
+let cameraTransportCanOpen;
+let cameraPendingQueueCanAccept;
+let cameraTransportCloseRecoveryMessage;
+let createCameraStartupWatchdog;
+let cameraStartupWatchdogRecoveryMessage;
+let CAMERA_FIRST_MEDIA_TIMEOUT_MS;
+let CAMERA_FIRST_PLAYABLE_FRAME_TIMEOUT_MS;
+let liveCameraPlaybackAuthorityIdentity;
+let initialCameraPlaybackRecoveryState;
+let reduceCameraPlaybackRecovery;
+let cameraTransportCallbackIsCurrent;
+let cameraBrowserTransportIdentity;
+let liveRerunRecoveryAuthorityIdentity;
let initialObservationWindowRect;
let ObservationTimeline;
let shouldCaptureWorkspacePointer;
@@ -48,12 +62,33 @@ before(async () => {
({ openObservationSource, shouldRestartObservationSource } = await server.ssrLoadModule(
"/src/core/observation/layoutPolicy.ts",
));
- ({ consumeCameraLeaseRetry, resetCameraLeaseRetryBudget } = await server.ssrLoadModule(
- "/src/components/MseFmp4WebSocketPlayer.tsx",
+ ({
+ consumeCameraLeaseRetry,
+ resetCameraLeaseRetryBudget,
+ cameraTransportRecoveryIsCurrent,
+ cameraTransportCanOpen,
+ cameraPendingQueueCanAccept,
+ cameraTransportCloseRecoveryMessage,
+ createCameraStartupWatchdog,
+ cameraStartupWatchdogRecoveryMessage,
+ CAMERA_FIRST_MEDIA_TIMEOUT_MS,
+ CAMERA_FIRST_PLAYABLE_FRAME_TIMEOUT_MS,
+ } = await server.ssrLoadModule("/src/components/MseFmp4WebSocketPlayer.tsx"));
+ ({
+ liveCameraPlaybackAuthorityIdentity,
+ initialCameraPlaybackRecoveryState,
+ reduceCameraPlaybackRecovery,
+ cameraTransportCallbackIsCurrent,
+ cameraBrowserTransportIdentity,
+ } = await server.ssrLoadModule(
+ "/src/core/observation/liveCameraRecovery.ts",
));
({ initialObservationWindowRect, shouldCaptureWorkspacePointer } = await server.ssrLoadModule(
"/src/components/FloatingObservationWindow.tsx",
));
+ ({ liveRerunRecoveryAuthorityIdentity } = await server.ssrLoadModule(
+ "/src/core/observation/liveReceiverWatchdog.ts",
+ ));
({
ObservationTimeline,
normalizeTimelineRange,
@@ -574,6 +609,134 @@ function cameraRow(sourceId, label) {
};
}
+function connectionSupervisor({ dataAuthoritative = false, dataPlaneState = "idle" } = {}) {
+ const observedAt = "2026-08-06T12:00:00Z";
+ const target = { ipv4: "192.168.68.52", port: 1883 };
+ return {
+ schema_version: "missioncore.k1-connection-supervisor/v1",
+ revision: 7,
+ closed: false,
+ intent: {
+ intent_id: "intent-001",
+ requested_mode: "bridge",
+ expected_device_id: "device-k1-001",
+ requested_at: observedAt,
+ },
+ observed: {
+ device_network: {
+ state: "applied",
+ intent_id: "intent-001",
+ transport_ref: "ble-k1-001",
+ connection_mode: "bridge",
+ target,
+ source: "ble-read-only-status",
+ observed_at: observedAt,
+ },
+ host_path: {
+ epoch: 3,
+ available: true,
+ fingerprint: "en0:192.168.68.10",
+ interface: "en0",
+ source_ipv4: "192.168.68.10",
+ route_class: "direct",
+ reason_code: null,
+ observed_at: observedAt,
+ },
+ endpoint: {
+ target,
+ tcp_state: "reachable",
+ intent_id: "intent-001",
+ host_path_epoch: 3,
+ reason_code: null,
+ observed_at: observedAt,
+ },
+ device_identity: {
+ state: "verified",
+ intent_id: "intent-001",
+ logical_device_id: "device-k1-001",
+ compatibility_profile_id: "xgrids.lixelkity-k1.fw-3.0.2.local-network.v2",
+ connection_mode: "bridge",
+ source: "mqtt-device-info",
+ host_path_epoch: 3,
+ observed_at: observedAt,
+ },
+ control_plane: {
+ state: "healthy",
+ session_id: "control-session-001",
+ host_path_epoch: 3,
+ reason_code: null,
+ observed_at: observedAt,
+ },
+ data_plane: {
+ state: dataAuthoritative ? "healthy" : dataPlaneState,
+ session_id: dataAuthoritative || dataPlaneState !== "idle" ? "data-session-001" : null,
+ host_path_epoch: dataAuthoritative || dataPlaneState !== "idle" ? 3 : null,
+ reason_code: null,
+ observed_at: dataAuthoritative || dataPlaneState !== "idle" ? observedAt : null,
+ },
+ },
+ lease: {
+ state: "reachable",
+ generation: 4,
+ intent_id: "intent-001",
+ host_path_epoch: 3,
+ connection_mode: "bridge",
+ target,
+ logical_device_id: "device-k1-001",
+ reason_code: null,
+ observed_at: observedAt,
+ },
+ authority: {
+ network_mutation_allowed: false,
+ control_allowed: true,
+ acquisition_start_allowed: true,
+ data_ingest_authoritative: dataAuthoritative,
+ physical_motion_allowed: false,
+ reason_codes: [],
+ },
+ last_known: null,
+ allowed_actions: ["stop-acquisition"],
+ };
+}
+
+function connectionLifecycle() {
+ return {
+ schema_version: "missioncore.xgrids-k1-connection-lifecycle/v1",
+ revision: 8,
+ desired_mode: "bridge",
+ configured_mode: "bridge",
+ active_mode: "bridge",
+ mode_change: {
+ state: "ready",
+ from: "bridge",
+ to: "bridge",
+ },
+ mode_selection: {
+ allowed: false,
+ reason_codes: ["connection-mode-selection-acquisition-active"],
+ automatic_retry: false,
+ },
+ active_binding_key: "binding-intent-001-bridge",
+ active_binding: {
+ binding_key: "binding-intent-001-bridge",
+ intent_id: "intent-001",
+ transport_ref: "ble-k1-001",
+ connection_mode: "bridge",
+ target_ipv4: "192.168.68.52",
+ target_port: 1883,
+ host_path_epoch: 3,
+ control_session_id: "control-session-001",
+ logical_device_id: "device-k1-001",
+ compatibility_profile_id: "xgrids.lixelkity-k1.fw-3.0.2.local-network.v2",
+ },
+ connection_ready: true,
+ ready_to_start: true,
+ operation: null,
+ allowed_actions: ["stop-acquisition"],
+ automatic_retry: false,
+ };
+}
+
function declaredState(cameraRows = [
cameraRow("sensor.camera.left", "K1 · камера слева"),
cameraRow("sensor.camera.right", "K1 · камера справа"),
@@ -582,6 +745,7 @@ function declaredState(cameraRows = [
return {
phase: "connected",
source_mode: "idle",
+ connection_mode: "bridge",
k1_ip: "192.168.7.10",
foxglove_ws_url: "ws://192.168.7.10:8765",
foxglove_viewer_url: "http://192.168.7.10:8765/vendor-viewer",
@@ -601,6 +765,16 @@ function declaredState(cameraRows = [
compatibility_profile_id: "xgrids.lixelkity-k1.fw-3.0.2.local-network.v2",
connectivity: "connected",
},
+ connection_supervisor: connectionSupervisor(),
+ connection_lifecycle: connectionLifecycle(),
+ application_control_session: {
+ verified_control: {
+ logical_device_id: "device-k1-001",
+ compatibility_profile_id: "xgrids.lixelkity-k1.fw-3.0.2.local-network.v2",
+ control_session_id: "control-session-001",
+ source: "mqtt-device-info",
+ },
+ },
sensor_catalog: {
schema_version: "missioncore.sensor-catalog/v1alpha2",
revision: "test-profile",
@@ -620,10 +794,12 @@ function declaredState(cameraRows = [
}
function pointCloudStreamingState() {
+ const state = declaredState();
return {
- ...declaredState(),
+ ...state,
phase: "streaming",
source_mode: "live",
+ connection_supervisor: connectionSupervisor({ dataAuthoritative: true }),
rerun_grpc_url: "rerun+http://127.0.0.1:9877/proxy",
acquisition: {
acquisition_id: "acquisition-001",
@@ -668,9 +844,83 @@ function cameraStreamingState(sourceId) {
active_source_id: sourceId,
delivery,
};
+ state.connection_recovery = {
+ schema_version: "missioncore.xgrids-k1-active-stream-recovery/v1",
+ state: "inactive",
+ generation: 0,
+ acquisition_id: null,
+ attempt: 0,
+ started_at_utc: null,
+ elapsed_ms: null,
+ reason_code: null,
+ force_finish_allowed: false,
+ automatic_read_only_rebind: false,
+ automatic_command_retry: false,
+ start_performed: false,
+ stop_performed: false,
+ ble_operation_performed: false,
+ network_mutation_performed: false,
+ runtime_producer_generation: null,
+ camera_recovery: "inactive",
+ camera_media_state: "ready",
+ camera_media_ready: true,
+ camera_epoch: {
+ generation: 7,
+ init_committed: true,
+ init_committed_age_ms: 100,
+ first_media_committed: true,
+ first_media_committed_age_ms: 80,
+ committed_media_segment_count: 2,
+ last_media_segment_age_ms: 20,
+ },
+ };
return state;
}
+function cameraRecoveringState(sourceId, recoveryOverrides = {}, stateOverrides = {}) {
+ const state = cameraStreamingState(sourceId);
+ return {
+ ...state,
+ snapshot_runtime_id: "runtime-camera-recovery-001",
+ snapshot_revision: 29,
+ producer_generation: 17,
+ phase: "reconnecting",
+ connection_supervisor: connectionSupervisor({ dataPlaneState: "lost" }),
+ connection_recovery: {
+ schema_version: "missioncore.xgrids-k1-active-stream-recovery/v1",
+ state: "reconnecting",
+ generation: 6,
+ acquisition_id: state.acquisition.acquisition_id,
+ attempt: 2,
+ started_at_utc: "2026-08-11T21:19:59Z",
+ elapsed_ms: 16_869,
+ reason_code: "host-route-unavailable",
+ force_finish_allowed: true,
+ automatic_read_only_rebind: true,
+ automatic_command_retry: false,
+ start_performed: false,
+ stop_performed: false,
+ ble_operation_performed: false,
+ network_mutation_performed: false,
+ runtime_producer_generation: 17,
+ camera_recovery: "owned",
+ camera_media_state: "pending-first-media",
+ camera_media_ready: false,
+ camera_epoch: {
+ generation: 7,
+ init_committed: true,
+ init_committed_age_ms: 250,
+ first_media_committed: false,
+ first_media_committed_age_ms: null,
+ committed_media_segment_count: 0,
+ last_media_segment_age_ms: null,
+ },
+ ...recoveryOverrides,
+ },
+ ...stateOverrides,
+ };
+}
+
function collectUrlLikeStrings(value, found = []) {
if (typeof value === "string") {
if (value.includes("://")) found.push(value);
@@ -719,6 +969,41 @@ test("descriptor ids remain stable while point cloud and selected camera start s
assert.equal(streaming[0].previewUrl, "rerun+http://127.0.0.1:9877/proxy");
});
+test("legacy selected-device fields cannot attest or stream observation sources", () => {
+ const state = cameraStreamingState("sensor.camera.left");
+ delete state.connection_supervisor;
+ delete state.application_control_session;
+
+ const sources = xgridsK1ObservationSources(state, model());
+ const pointCloud = sources.find(({ modality }) => modality === "point-cloud");
+ const left = sources.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(pointCloud && left);
+ assert.equal(pointCloud.availability, "unverified");
+ assert.equal(pointCloud.previewUrl, null);
+ assert.equal(pointCloud.binding.deviceId, null);
+ assert.equal(pointCloud.binding.deviceSessionId, null);
+ assert.equal(left.availability, "unverified");
+ assert.equal(left.activation.selected, false);
+ assert.equal(left.activation.controllable, false);
+ assert.equal(left.delivery, null);
+});
+
+test("data-plane loss keeps control identity but withdraws all live deliveries", () => {
+ const state = cameraStreamingState("sensor.camera.left");
+ state.connection_supervisor = connectionSupervisor({ dataPlaneState: "lost" });
+
+ const sources = xgridsK1ObservationSources(state, model());
+ const pointCloud = sources.find(({ modality }) => modality === "point-cloud");
+ const left = sources.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(pointCloud && left);
+ assert.equal(pointCloud.availability, "degraded");
+ assert.equal(pointCloud.previewUrl, null);
+ assert.equal(pointCloud.binding.deviceId, "device-k1-001");
+ assert.equal(left.activation.selected, true);
+ assert.equal(left.availability, "degraded");
+ assert.equal(left.delivery, null);
+});
+
test("only the authoritative selected camera receives browser delivery", () => {
const sources = xgridsK1ObservationSources(
cameraStreamingState("sensor.camera.left"),
@@ -740,6 +1025,43 @@ test("only the authoritative selected camera receives browser delivery", () => {
assert.match(left.activation.groupId, /device-session-001/);
});
+test("ordinary camera delivery requires ready media facts from the exact current epoch", () => {
+ const pending = cameraStreamingState("sensor.camera.left");
+ pending.connection_recovery = {
+ ...pending.connection_recovery,
+ camera_media_state: "pending-first-media",
+ camera_media_ready: false,
+ camera_epoch: {
+ generation: 7,
+ init_committed: true,
+ init_committed_age_ms: 20,
+ first_media_committed: false,
+ first_media_committed_age_ms: null,
+ committed_media_segment_count: 0,
+ last_media_segment_age_ms: null,
+ },
+ };
+ const staleEpoch = cameraStreamingState("sensor.camera.left");
+ staleEpoch.connection_recovery = {
+ ...staleEpoch.connection_recovery,
+ camera_epoch: {
+ ...staleEpoch.connection_recovery.camera_epoch,
+ generation: 6,
+ },
+ };
+
+ for (const state of [pending, staleEpoch]) {
+ const camera = xgridsK1ObservationSources(state, model()).find(
+ ({ sourceId }) => sourceId === "sensor.camera.left",
+ );
+ assert.ok(camera);
+ assert.equal(camera.activation.selected, false);
+ assert.equal(camera.delivery, null);
+ assert.equal(camera.availability, "available");
+ assert.equal(liveCameraPlaybackAuthorityIdentity(camera), null);
+ }
+});
+
test("switching left to right keeps ids stable and never exposes both deliveries", () => {
const left = xgridsK1ObservationSources(
cameraStreamingState("sensor.camera.left"),
@@ -781,6 +1103,8 @@ test("unattested, duplicate and unsafe camera entries fail closed", () => {
const state = cameraStreamingState("sensor.camera.left");
state.compatibility.profile_id = null;
state.device_session.compatibility_profile_id = null;
+ state.connection_supervisor.observed.device_identity.state = "mismatch";
+ state.application_control_session.verified_control = null;
state.sensor_catalog.streams.push(duplicate);
state.camera_preview.delivery = {
...state.camera_preview.delivery,
@@ -825,14 +1149,14 @@ test("camera delivery rejects literal and encoded endpoint or credential leaks",
}
});
-test("manual camera reconnect restores an exhausted lease retry budget", () => {
+test("authoritative camera transport retries indefinitely with a capped backoff", () => {
let budget = resetCameraLeaseRetryBudget("delivery-7");
- for (const expectedDelay of [400, 1_000, 2_000]) {
+ for (const expectedDelay of [400, 1_000, 2_000, 5_000, 5_000, 5_000]) {
const retry = consumeCameraLeaseRetry(budget, "delivery-7");
assert.equal(retry.delay, expectedDelay);
budget = retry.budget;
}
- assert.equal(consumeCameraLeaseRetry(budget, "delivery-7").delay, null);
+ assert.equal(budget.count, 4);
budget = resetCameraLeaseRetryBudget("delivery-7");
const retryAfterManualReset = consumeCameraLeaseRetry(budget, "delivery-7");
@@ -840,6 +1164,592 @@ test("manual camera reconnect restores an exhausted lease retry budget", () => {
assert.equal(retryAfterManualReset.budget.count, 1);
});
+test("camera startup watchdog replaces an open-but-silent MSE or WebSocket", () => {
+ const scheduled = new Map();
+ const timeouts = [];
+ let nextHandle = 1;
+ const watchdog = createCameraStartupWatchdog({
+ schedule(callback, timeoutMs) {
+ const handle = nextHandle;
+ nextHandle += 1;
+ scheduled.set(handle, { callback, timeoutMs });
+ return handle;
+ },
+ cancel(handle) {
+ scheduled.delete(handle);
+ },
+ onTimeout(stage) {
+ timeouts.push(stage);
+ },
+ });
+
+ watchdog.armFirstMedia();
+ watchdog.armFirstMedia();
+ assert.equal(watchdog.pendingStage(), "first-media");
+ assert.equal(scheduled.size, 1);
+ const [{ callback, timeoutMs }] = scheduled.values();
+ assert.equal(timeoutMs, CAMERA_FIRST_MEDIA_TIMEOUT_MS);
+ callback();
+
+ assert.deepEqual(timeouts, ["first-media"]);
+ assert.equal(watchdog.pendingStage(), null);
+ assert.match(
+ cameraStartupWatchdogRecoveryMessage("first-media"),
+ /не передаёт медиаданные; восстанавливаем/,
+ );
+});
+
+test("first media starts one non-sliding first-playable-frame deadline", () => {
+ const scheduled = new Map();
+ const cancelled = [];
+ const timeouts = [];
+ let nextHandle = 10;
+ const watchdog = createCameraStartupWatchdog({
+ schedule(callback, timeoutMs) {
+ const handle = nextHandle;
+ nextHandle += 1;
+ scheduled.set(handle, { callback, timeoutMs });
+ return handle;
+ },
+ cancel(handle) {
+ cancelled.push(handle);
+ scheduled.delete(handle);
+ },
+ onTimeout(stage) {
+ timeouts.push(stage);
+ },
+ });
+
+ watchdog.armFirstMedia();
+ watchdog.markMediaReceived();
+ const playableHandle = nextHandle - 1;
+ assert.deepEqual(cancelled, [10]);
+ assert.equal(watchdog.pendingStage(), "first-playable-frame");
+ assert.equal(scheduled.get(playableHandle).timeoutMs, CAMERA_FIRST_PLAYABLE_FRAME_TIMEOUT_MS);
+
+ watchdog.markMediaReceived();
+ assert.equal(nextHandle - 1, playableHandle, "later fragments must not extend the deadline");
+ scheduled.get(playableHandle).callback();
+ assert.deepEqual(timeouts, ["first-playable-frame"]);
+ assert.match(
+ cameraStartupWatchdogRecoveryMessage("first-playable-frame"),
+ /первый кадр не воспроизводится; пересоздаём decoder/,
+ );
+});
+
+test("playing clears the camera startup watchdog", () => {
+ const scheduled = new Map();
+ const cancelled = [];
+ const watchdog = createCameraStartupWatchdog({
+ schedule(callback) {
+ scheduled.set(21, callback);
+ return 21;
+ },
+ cancel(handle) {
+ cancelled.push(handle);
+ scheduled.delete(handle);
+ },
+ onTimeout() {
+ assert.fail("a playing transport must not time out");
+ },
+ });
+
+ watchdog.armFirstMedia();
+ watchdog.markMediaReceived();
+ watchdog.markPlaying();
+ assert.equal(watchdog.pendingStage(), null);
+ assert.deepEqual(cancelled, [21, 21]);
+ assert.equal(scheduled.size, 0);
+});
+
+test("browser append queue absorbs the complete bounded server backlog", () => {
+ assert.equal(
+ cameraPendingQueueCanAccept(8 * 1024 * 1024, 64, 1024 * 1024),
+ true,
+ );
+ assert.equal(
+ cameraPendingQueueCanAccept(11 * 1024 * 1024, 95, 1024 * 1024),
+ true,
+ );
+ assert.equal(
+ cameraPendingQueueCanAccept(12 * 1024 * 1024, 64, 1),
+ false,
+ );
+ assert.equal(
+ cameraPendingQueueCanAccept(8 * 1024 * 1024, 96, 1),
+ false,
+ );
+});
+
+test("server slow-reader close is an automatic browser-only camera recovery", () => {
+ assert.match(
+ cameraTransportCloseRecoveryMessage(4_008),
+ /отстал от эфира; восстанавливаем текущую камеру/,
+ );
+ assert.match(cameraTransportCloseRecoveryMessage(1_008), /переподключаемся/);
+ assert.match(cameraTransportCloseRecoveryMessage(1_000), /восстанавливаем/);
+ assert.match(cameraTransportCloseRecoveryMessage(1_011), /восстанавливаем/);
+});
+
+test("a laptop sleep gap reopens only the exact authoritative live camera transport", () => {
+ const source = xgridsK1ObservationSources(
+ cameraStreamingState("sensor.camera.right"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.right");
+ assert.ok(source);
+ const authority = liveCameraPlaybackAuthorityIdentity(source);
+ assert.ok(authority);
+
+ const initial = initialCameraPlaybackRecoveryState(authority, 1_000);
+ const wake = reduceCameraPlaybackRecovery(initial, { type: "heartbeat" }, {
+ activeAuthorityIdentity: authority,
+ now: 7_000,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(wake.reopen, true);
+ assert.equal(wake.state.lastReopenAt, 7_000);
+
+ const staleSource = reduceCameraPlaybackRecovery(initial, { type: "heartbeat" }, {
+ activeAuthorityIdentity: `${authority}:replaced`,
+ now: 7_000,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(staleSource.reopen, false);
+});
+
+test("visibility, pageshow and online wake burst owns one replacement decoder", () => {
+ const authority = "camera-authority-acquisition-1";
+ let state = initialCameraPlaybackRecoveryState(authority, 1_000);
+ ({ state } = reduceCameraPlaybackRecovery(state, { type: "document-hidden" }, {
+ activeAuthorityIdentity: authority,
+ now: 2_000,
+ documentVisible: false,
+ networkOnline: true,
+ }));
+
+ const visible = reduceCameraPlaybackRecovery(state, { type: "document-visible" }, {
+ activeAuthorityIdentity: authority,
+ now: 8_000,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(visible.reopen, true);
+ state = visible.state;
+
+ for (const event of [
+ { type: "page-restore", persisted: true },
+ { type: "network-online" },
+ { type: "heartbeat" },
+ ]) {
+ const duplicate = reduceCameraPlaybackRecovery(state, event, {
+ activeAuthorityIdentity: authority,
+ now: 8_100,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(duplicate.reopen, false);
+ state = duplicate.state;
+ }
+
+ ({ state } = reduceCameraPlaybackRecovery(state, { type: "document-hidden" }, {
+ activeAuthorityIdentity: authority,
+ now: 12_000,
+ documentVisible: false,
+ networkOnline: true,
+ }));
+ const secondWake = reduceCameraPlaybackRecovery(state, { type: "document-visible" }, {
+ activeAuthorityIdentity: authority,
+ now: 18_000,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(secondWake.reopen, true);
+ assert.equal(secondWake.state.lastReopenAt, 18_000);
+});
+
+test("healthy visible camera heartbeats do not churn its WebSocket or decoder", () => {
+ const authority = "camera-authority-acquisition-healthy";
+ let state = initialCameraPlaybackRecoveryState(authority, 1_000);
+ for (const now of [2_000, 3_000, 4_000, 5_000]) {
+ const heartbeat = reduceCameraPlaybackRecovery(state, { type: "heartbeat" }, {
+ activeAuthorityIdentity: authority,
+ now,
+ documentVisible: true,
+ networkOnline: true,
+ });
+ assert.equal(heartbeat.reopen, false);
+ state = heartbeat.state;
+ }
+ assert.equal(state.lastReopenAt, null);
+});
+
+test("callbacks from a replaced camera WebSocket and SourceBuffer are fenced", () => {
+ assert.equal(cameraTransportCallbackIsCurrent(4, 4, false), true);
+ assert.equal(cameraTransportCallbackIsCurrent(5, 4, false), false);
+ assert.equal(cameraTransportCallbackIsCurrent(4, 4, true), false);
+});
+
+test("an already-stale document opens zero camera transports on mount", () => {
+ let transportOpenCount = 0;
+ const uiBuildStaleRef = { current: false };
+ const subscribeToAlreadyStaleCoordinator = (listener) => {
+ listener();
+ return () => undefined;
+ };
+
+ subscribeToAlreadyStaleCoordinator(() => {
+ uiBuildStaleRef.current = true;
+ });
+ if (cameraTransportCanOpen(uiBuildStaleRef.current)) transportOpenCount += 1;
+
+ assert.equal(uiBuildStaleRef.current, true);
+ assert.equal(transportOpenCount, 0);
+});
+
+test("only the current acquisition authority may schedule a replacement decoder", () => {
+ const authority = "camera-authority-acquisition-current";
+ assert.equal(
+ cameraTransportRecoveryIsCurrent(authority, authority, 7, 7, false),
+ true,
+ );
+ assert.equal(
+ cameraTransportRecoveryIsCurrent(`${authority}:replaced`, authority, 7, 7, false),
+ false,
+ );
+ assert.equal(
+ cameraTransportRecoveryIsCurrent(authority, authority, 8, 7, false),
+ false,
+ );
+ assert.equal(
+ cameraTransportRecoveryIsCurrent(authority, authority, 7, 7, true),
+ false,
+ );
+ assert.equal(
+ cameraTransportRecoveryIsCurrent(null, authority, 7, 7, false),
+ false,
+ );
+});
+
+test("same camera delivery gets a new browser transport owner for a new acquisition", () => {
+ const camera = xgridsK1ObservationSources(
+ cameraStreamingState("sensor.camera.right"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.right");
+ assert.ok(camera?.delivery && camera.delivery.kind === "mse-fmp4-websocket");
+ const previousAuthority = liveCameraPlaybackAuthorityIdentity(camera);
+ const nextAuthority = liveCameraPlaybackAuthorityIdentity({
+ ...camera,
+ binding: {
+ ...camera.binding,
+ deviceSessionId: "device-session-002",
+ acquisitionId: "acquisition-002",
+ },
+ });
+ assert.ok(previousAuthority && nextAuthority);
+ assert.notEqual(nextAuthority, previousAuthority);
+ assert.notEqual(
+ cameraBrowserTransportIdentity(camera.delivery, nextAuthority),
+ cameraBrowserTransportIdentity(camera.delivery, previousAuthority),
+ );
+});
+
+test("malformed camera exclusivity or media descriptors cannot own wake recovery", () => {
+ const camera = xgridsK1ObservationSources(
+ cameraStreamingState("sensor.camera.left"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(camera?.activation && camera.delivery?.kind === "mse-fmp4-websocket");
+
+ for (const malformed of [
+ { ...camera, activation: { ...camera.activation, groupId: " " } },
+ { ...camera, activation: { ...camera.activation, groupId: null } },
+ { ...camera, activation: { ...camera.activation, maxActive: 2 } },
+ { ...camera, delivery: { ...camera.delivery, mediaType: " " } },
+ { ...camera, delivery: { ...camera.delivery, mediaType: null } },
+ { ...camera, delivery: { ...camera.delivery, mediaType: "video/webm" } },
+ ]) {
+ assert.equal(liveCameraPlaybackAuthorityIdentity(malformed), null);
+ }
+});
+
+test("point-cloud recovery cannot revive a dead or stale camera delivery", () => {
+ const sources = xgridsK1ObservationSources(
+ cameraStreamingState("sensor.camera.left"),
+ model(),
+ );
+ const pointCloud = sources.find(({ modality }) => modality === "point-cloud");
+ const camera = sources.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(pointCloud && camera);
+ assert.equal(pointCloud.availability, "streaming");
+ assert.ok(liveCameraPlaybackAuthorityIdentity(camera));
+
+ assert.equal(liveCameraPlaybackAuthorityIdentity({
+ ...camera,
+ availability: "error",
+ }), null);
+ assert.equal(liveCameraPlaybackAuthorityIdentity({
+ ...camera,
+ binding: { ...camera.binding, acquisitionId: "acquisition-replaced" },
+ activation: { ...camera.activation, selected: false },
+ }), null);
+});
+
+test("exact active recovery retains the same camera delivery without controls", () => {
+ const healthy = xgridsK1ObservationSources(
+ cameraStreamingState("sensor.camera.left"),
+ model(),
+ );
+ const recovering = xgridsK1ObservationSources(
+ cameraRecoveringState("sensor.camera.left"),
+ model(),
+ );
+ const healthyPointCloud = healthy.find(({ modality }) => modality === "point-cloud");
+ const recoveryPointCloud = recovering.find(({ modality }) => modality === "point-cloud");
+ const healthyCamera = healthy.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ const recoveryCamera = recovering.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(healthyPointCloud && recoveryPointCloud && healthyCamera && recoveryCamera);
+
+ assert.equal(recoveryPointCloud.id, healthyPointCloud.id);
+ assert.equal(recoveryPointCloud.previewUrl, healthyPointCloud.previewUrl);
+ assert.equal(recoveryPointCloud.availability, "connecting");
+ assert.equal(recoveryCamera.id, healthyCamera.id);
+ assert.deepEqual(recoveryCamera.delivery, healthyCamera.delivery);
+ assert.equal(recoveryCamera.activation.selected, true);
+ assert.equal(recoveryCamera.activation.controllable, false);
+ assert.equal(recoveryCamera.availability, "connecting");
+ assert.deepEqual(recoveryCamera.presentationLease, {
+ kind: "active-stream-recovery",
+ runtimeId: "runtime-camera-recovery-001",
+ acquisitionId: "acquisition-001",
+ acquisitionStateRevision: 3,
+ producerGeneration: 17,
+ recoveryGeneration: 6,
+ });
+
+ const healthyAuthority = liveCameraPlaybackAuthorityIdentity(healthyCamera);
+ const recoveryAuthority = liveCameraPlaybackAuthorityIdentity(recoveryCamera);
+ assert.ok(healthyAuthority && recoveryAuthority);
+ assert.notEqual(recoveryAuthority, healthyAuthority);
+ assert.equal(
+ liveCameraPlaybackAuthorityIdentity(
+ xgridsK1ObservationSources(
+ cameraRecoveringState("sensor.camera.left"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.left"),
+ ),
+ recoveryAuthority,
+ "repeated snapshots of the same recovery generation keep one browser owner",
+ );
+});
+
+test("camera recovery stays connecting until the current epoch has durable first media", () => {
+ const pending = xgridsK1ObservationSources(
+ cameraRecoveringState("sensor.camera.left"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.left");
+ const ready = xgridsK1ObservationSources(
+ cameraRecoveringState("sensor.camera.left", {
+ camera_media_state: "ready",
+ camera_media_ready: true,
+ camera_epoch: {
+ generation: 7,
+ init_committed: true,
+ init_committed_age_ms: 500,
+ first_media_committed: true,
+ first_media_committed_age_ms: 100,
+ committed_media_segment_count: 1,
+ last_media_segment_age_ms: 100,
+ },
+ }),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.left");
+
+ assert.ok(pending?.delivery && ready?.delivery);
+ assert.equal(pending.activation.selected, true);
+ assert.equal(pending.availability, "connecting");
+ assert.ok(pending.presentationLease);
+ assert.equal(ready.activation.selected, true);
+ assert.equal(ready.availability, "streaming");
+ assert.ok(ready.presentationLease);
+});
+
+test("first recovered PCL keeps the exact camera authority until browser media is playable", () => {
+ const reconnectingState = cameraRecoveringState("sensor.camera.left");
+ const recoveredState = cameraRecoveringState(
+ "sensor.camera.left",
+ {
+ state: "recovered",
+ force_finish_allowed: false,
+ elapsed_ms: null,
+ reason_code: null,
+ },
+ {
+ phase: "live",
+ connection_supervisor: connectionSupervisor({ dataAuthoritative: true }),
+ },
+ );
+ recoveredState.camera_preview = {
+ ...recoveredState.camera_preview,
+ phase: "connecting",
+ };
+ recoveredState.sensor_catalog = {
+ ...recoveredState.sensor_catalog,
+ streams: recoveredState.sensor_catalog.streams.map((stream) =>
+ stream.source_id === "sensor.camera.left"
+ ? { ...stream, availability: "connecting" }
+ : stream),
+ };
+
+ const reconnecting = xgridsK1ObservationSources(reconnectingState, model());
+ const recovered = xgridsK1ObservationSources(recoveredState, model());
+ const reconnectingCamera = reconnecting.find(
+ ({ sourceId }) => sourceId === "sensor.camera.left",
+ );
+ const recoveredCamera = recovered.find(
+ ({ sourceId }) => sourceId === "sensor.camera.left",
+ );
+ const reconnectingPointCloud = reconnecting.find(
+ ({ modality }) => modality === "point-cloud",
+ );
+ const recoveredPointCloud = recovered.find(
+ ({ modality }) => modality === "point-cloud",
+ );
+ assert.ok(
+ reconnectingCamera
+ && recoveredCamera
+ && reconnectingPointCloud
+ && recoveredPointCloud,
+ );
+
+ assert.equal(recoveredCamera.availability, "connecting");
+ assert.equal(recoveredCamera.activation.selected, true);
+ assert.equal(recoveredCamera.activation.controllable, true);
+ assert.deepEqual(recoveredCamera.delivery, reconnectingCamera.delivery);
+ assert.deepEqual(recoveredCamera.presentationLease, reconnectingCamera.presentationLease);
+ assert.deepEqual(
+ recoveredPointCloud.presentationLease,
+ reconnectingPointCloud.presentationLease,
+ );
+ assert.equal(
+ liveCameraPlaybackAuthorityIdentity(recoveredCamera),
+ liveCameraPlaybackAuthorityIdentity(reconnectingCamera),
+ "reconnecting→recovered must not retire the decoder before first playable frame",
+ );
+ const spatialSource = {
+ id: "acquisition-001",
+ url: reconnectingPointCloud.previewUrl,
+ label: "Live",
+ kind: "rerun-grpc",
+ };
+ assert.equal(
+ liveRerunRecoveryAuthorityIdentity(recoveredPointCloud, spatialSource),
+ liveRerunRecoveryAuthorityIdentity(reconnectingPointCloud, spatialSource),
+ "the first recovered PCL keeps one exact Rerun browser authority",
+ );
+});
+
+test("camera recovery fails closed while the exact spatial lease may continue", () => {
+ const cameraStreamError = cameraRecoveringState("sensor.camera.left");
+ cameraStreamError.sensor_catalog.streams = cameraStreamError.sensor_catalog.streams.map(
+ (stream) => stream.source_id === "sensor.camera.left"
+ ? { ...stream, availability: "error" }
+ : stream,
+ );
+ const mismatchedDelivery = cameraRecoveringState("sensor.camera.left");
+ mismatchedDelivery.camera_preview.delivery = {
+ ...mismatchedDelivery.camera_preview.delivery,
+ id: "preview-generation-replaced:sensor.camera.left",
+ };
+ const missingDelivery = cameraRecoveringState("sensor.camera.left");
+ missingDelivery.camera_preview.delivery = null;
+ missingDelivery.sensor_catalog.streams = missingDelivery.sensor_catalog.streams.map(
+ (stream) => stream.source_id === "sensor.camera.left"
+ ? { ...stream, delivery: null }
+ : stream,
+ );
+ const cases = [
+ cameraRecoveringState("sensor.camera.left", { camera_recovery: "blocked" }),
+ cameraRecoveringState("sensor.camera.left", {}, {
+ device_session: {
+ ...cameraStreamingState("sensor.camera.left").device_session,
+ device_session_id: "device-session-replaced",
+ },
+ }),
+ cameraRecoveringState("sensor.camera.left", {}, {
+ camera_preview: {
+ ...cameraStreamingState("sensor.camera.left").camera_preview,
+ phase: "error",
+ },
+ }),
+ cameraStreamError,
+ mismatchedDelivery,
+ missingDelivery,
+ ];
+
+ for (const state of cases) {
+ const sources = xgridsK1ObservationSources(state, model());
+ const pointCloud = sources.find(({ modality }) => modality === "point-cloud");
+ const camera = sources.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(pointCloud && camera);
+ assert.equal(pointCloud.previewUrl, "rerun+http://127.0.0.1:9877/proxy");
+ assert.equal(pointCloud.availability, "connecting");
+ assert.equal(camera.activation.selected, false);
+ assert.equal(camera.activation.controllable, false);
+ assert.equal(camera.delivery, null);
+ assert.equal(camera.presentationLease, null);
+ assert.equal(liveCameraPlaybackAuthorityIdentity(camera), null);
+ }
+});
+
+test("stale and terminal recovery states withdraw both retained transports", () => {
+ const staleProducer = cameraRecoveringState("sensor.camera.left");
+ staleProducer.producer_generation += 1;
+ const differentAcquisition = cameraRecoveringState("sensor.camera.left", {
+ acquisition_id: "acquisition-stale",
+ });
+ for (const state of [
+ staleProducer,
+ differentAcquisition,
+ cameraRecoveringState("sensor.camera.left", { state: "blocked" }),
+ cameraRecoveringState("sensor.camera.left", { state: "standby" }),
+ cameraRecoveringState("sensor.camera.left", { state: "fault" }),
+ ]) {
+ const sources = xgridsK1ObservationSources(state, model());
+ const pointCloud = sources.find(({ modality }) => modality === "point-cloud");
+ const camera = sources.find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(pointCloud && camera);
+ assert.equal(pointCloud.previewUrl, null);
+ assert.equal(pointCloud.presentationLease, null);
+ assert.equal(camera.activation.selected, false);
+ assert.equal(camera.delivery, null);
+ assert.equal(camera.presentationLease, null);
+ }
+});
+
+test("malformed recovery leases cannot own a camera WebSocket or decoder", () => {
+ const camera = xgridsK1ObservationSources(
+ cameraRecoveringState("sensor.camera.left"),
+ model(),
+ ).find(({ sourceId }) => sourceId === "sensor.camera.left");
+ assert.ok(camera?.presentationLease);
+
+ for (const presentationLease of [
+ null,
+ { ...camera.presentationLease, runtimeId: " " },
+ { ...camera.presentationLease, acquisitionId: "acquisition-stale" },
+ { ...camera.presentationLease, acquisitionStateRevision: 0 },
+ { ...camera.presentationLease, producerGeneration: 0 },
+ { ...camera.presentationLease, recoveryGeneration: 0 },
+ ]) {
+ assert.equal(
+ liveCameraPlaybackAuthorityIdentity({ ...camera, presentationLease }),
+ null,
+ );
+ }
+});
+
test("layout policy evicts only exclusive camera peers", () => {
const sources = xgridsK1ObservationSources(
cameraStreamingState("sensor.camera.left"),
diff --git a/apps/control-station/test/rerunViewportAtomicAdmission.test.mjs b/apps/control-station/test/rerunViewportAtomicAdmission.test.mjs
index 807625e..bb7e5e1 100644
--- a/apps/control-station/test/rerunViewportAtomicAdmission.test.mjs
+++ b/apps/control-station/test/rerunViewportAtomicAdmission.test.mjs
@@ -5,7 +5,9 @@ import { after, before, test } from "node:test";
import { createServer } from "vite";
let server;
+let claimExclusiveLiveViewer;
let createRecordedOpenWatchdog;
+let createReentrantViewerDisposer;
let recordedOpenWatchdogTimeoutMs;
let rerunViewerInitialSource;
let resolveRecordedViewerSourceUrl;
@@ -17,7 +19,9 @@ before(async () => {
server: { middlewareMode: true },
});
({
+ claimExclusiveLiveViewer,
createRecordedOpenWatchdog,
+ createReentrantViewerDisposer,
recordedOpenWatchdogTimeoutMs,
rerunViewerInitialSource,
resolveRecordedViewerSourceUrl,
@@ -118,6 +122,45 @@ test("complete recorded admission clears its watchdog", () => {
assert.deepEqual(cancelled, [23]);
});
+test("deferred viewer start cannot reopen after stale unmount", async () => {
+ let resolveStart;
+ const start = new Promise((resolve) => {
+ resolveStart = resolve;
+ });
+ let disposed = false;
+ let cleanupCount = 0;
+ let closeCount = 0;
+ let stopCount = 0;
+ const diagnostics = [];
+ const disposeViewer = createReentrantViewerDisposer(
+ () => {
+ cleanupCount += 1;
+ },
+ () => {
+ closeCount += 1;
+ stopCount += 1;
+ },
+ );
+ const pendingMount = (async () => {
+ await start;
+ if (disposed) {
+ disposeViewer();
+ return;
+ }
+ diagnostics.push("admitted");
+ })();
+
+ disposed = true;
+ disposeViewer();
+ resolveStart();
+ await pendingMount;
+
+ assert.equal(cleanupCount, 1);
+ assert.equal(closeCount, 2);
+ assert.equal(stopCount, 2);
+ assert.deepEqual(diagnostics, []);
+});
+
test("recorded RRD bytes are never split across LogChannel.send_rrd calls", async () => {
const source = await readFile(
new URL("../src/components/RerunViewport.tsx", import.meta.url),
@@ -129,7 +172,7 @@ test("recorded RRD bytes are never split across LogChannel.send_rrd calls", asyn
assert.match(source, /viewer\.start\(\s*rerunViewerInitialSource\(resolvedSource\)/s);
assert.match(
source,
- /recordingOpened = true;[\s\S]*clearLiveRecordingOpenTimer\(\);[\s\S]*clearLiveRecordingDiscoveryTimer\(\);/,
+ /recordingOpened = true;[\s\S]*diagnosticLifecycle\.markAdmitted\(\);/,
);
assert.match(
source,
@@ -145,12 +188,31 @@ test("recorded RRD bytes are never split across LogChannel.send_rrd calls", asyn
);
});
+test("one live document owns one native Rerun receiver", async () => {
+ const releases = [];
+ const releaseFirstClaim = claimExclusiveLiveViewer(() => releases.push("first"));
+ const releaseSecondClaim = claimExclusiveLiveViewer(() => releases.push("second"));
+
+ assert.deepEqual(releases, ["first"]);
+ releaseFirstClaim();
+ assert.deepEqual(releases, ["first"]);
+ releaseSecondClaim();
+
+ const releaseThirdClaim = claimExclusiveLiveViewer(() => releases.push("third"));
+ assert.deepEqual(releases, ["first"]);
+ releaseThirdClaim();
+});
+
test("raw replay exercises the same streaming receiver lifecycle as a live scan", async () => {
const source = await readFile(
new URL("../src/workspaces/Workspaces.tsx", import.meta.url),
"utf8",
);
assert.match(source, /followLive=\{!recordedReplay && streamActive\}/);
+ assert.match(
+ source,
+ /sourceUrl\.trim\(\) && pointCloudVisible && !intentionalSourceEnd/,
+ );
});
test("the complete vendor canvas host is hidden during partial and failed admission", async () => {
diff --git a/apps/control-station/test/runtimeStateOrdering.test.mjs b/apps/control-station/test/runtimeStateOrdering.test.mjs
index 29d728a..d65871a 100644
--- a/apps/control-station/test/runtimeStateOrdering.test.mjs
+++ b/apps/control-station/test/runtimeStateOrdering.test.mjs
@@ -42,6 +42,113 @@ function snapshot(revision, generation, phase = "streaming", sessionId = "device
};
}
+function stampedSnapshot({
+ runtimeStartedAt = "2026-08-06T10:00:00Z",
+ runtimeStartedMonotonicNs = "1000000",
+ runtimeId = "runtime-a",
+ snapshotRevision = 1,
+ cameraRevision = snapshotRevision,
+ generation = 1,
+} = {}) {
+ return {
+ ...snapshot(cameraRevision, generation),
+ snapshot_runtime_started_at_utc: runtimeStartedAt,
+ snapshot_runtime_started_monotonic_ns: runtimeStartedMonotonicNs,
+ snapshot_runtime_id: runtimeId,
+ snapshot_revision: snapshotRevision,
+ };
+}
+
+test("uses the process snapshot revision before camera-local counters", () => {
+ const current = stampedSnapshot({ snapshotRevision: 8, cameraRevision: 2 });
+ const stale = stampedSnapshot({ snapshotRevision: 7, cameraRevision: 99 });
+ const newer = stampedSnapshot({ snapshotRevision: 9, cameraRevision: 1 });
+
+ assert.equal(selectMonotonicXgridsState(current, stale), current);
+ assert.equal(selectMonotonicXgridsState(current, newer), newer);
+});
+
+test("accepts a newer runtime and rejects a delayed snapshot from the old runtime", () => {
+ const oldRuntime = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T10:00:00Z",
+ runtimeStartedMonotonicNs: "1000000",
+ runtimeId: "runtime-old",
+ snapshotRevision: 300,
+ });
+ const newRuntime = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T10:05:00Z",
+ runtimeStartedMonotonicNs: "2000000",
+ runtimeId: "runtime-new",
+ snapshotRevision: 1,
+ });
+ const delayedOldRuntime = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T10:00:00Z",
+ runtimeStartedMonotonicNs: "1000000",
+ runtimeId: "runtime-old",
+ snapshotRevision: 301,
+ });
+
+ assert.equal(selectMonotonicXgridsState(oldRuntime, newRuntime), newRuntime);
+ assert.equal(
+ selectMonotonicXgridsState(newRuntime, delayedOldRuntime),
+ newRuntime,
+ );
+});
+
+test("orders restarts by monotonic time even when UTC moves backwards", () => {
+ const oldRuntime = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T10:05:00Z",
+ runtimeStartedMonotonicNs: "2000000",
+ runtimeId: "runtime-old",
+ snapshotRevision: 900,
+ });
+ const newRuntime = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T09:55:00Z",
+ runtimeStartedMonotonicNs: "3000000",
+ runtimeId: "runtime-new",
+ snapshotRevision: 1,
+ });
+
+ assert.equal(selectMonotonicXgridsState(oldRuntime, newRuntime), newRuntime);
+ assert.equal(selectMonotonicXgridsState(newRuntime, oldRuntime), newRuntime);
+});
+
+test("orders two runtimes sharing the same UTC millisecond", () => {
+ const first = stampedSnapshot({
+ runtimeStartedMonotonicNs: "4000000",
+ runtimeId: "runtime-first",
+ });
+ const second = stampedSnapshot({
+ runtimeStartedMonotonicNs: "4000001",
+ runtimeId: "runtime-second",
+ });
+
+ assert.equal(selectMonotonicXgridsState(first, second), second);
+});
+
+test("a malformed monotonic stamp cannot replace valid runtime authority", () => {
+ const current = stampedSnapshot({
+ runtimeStartedMonotonicNs: "5000000",
+ runtimeId: "runtime-current",
+ });
+ const malformed = stampedSnapshot({
+ runtimeStartedAt: "2026-08-06T11:00:00Z",
+ runtimeStartedMonotonicNs: "not-a-number",
+ runtimeId: "runtime-malformed",
+ snapshotRevision: 9999,
+ });
+
+ assert.equal(selectMonotonicXgridsState(current, malformed), current);
+});
+
+test("does not let an unstamped legacy response replace stamped authority", () => {
+ const current = stampedSnapshot({ snapshotRevision: 8 });
+ const legacy = snapshot(99, 99);
+
+ assert.equal(selectMonotonicXgridsState(current, legacy), current);
+ assert.equal(selectMonotonicXgridsState(legacy, current), current);
+});
+
test("accepts the first camera preview snapshot", () => {
const incoming = snapshot(1, 1);
assert.equal(selectMonotonicXgridsState(null, incoming), incoming);
diff --git a/apps/control-station/test/workspaceLayout.test.mjs b/apps/control-station/test/workspaceLayout.test.mjs
index b67ae86..1341afa 100644
--- a/apps/control-station/test/workspaceLayout.test.mjs
+++ b/apps/control-station/test/workspaceLayout.test.mjs
@@ -13,6 +13,9 @@ let projectObservationLayoutSnapshot;
let saveObservationWorkspaceLayoutProfile;
let WorkspaceLayoutApiError;
let WorkspaceLayoutContractError;
+let admitLiveDefaultPresentations;
+let automaticLivePresentationIdentity;
+let livePresentationCloseFence;
let observationPresentationSourceAfterLayoutApply;
let visibleSourceIdsAfterRecordedCatalogActivation;
@@ -33,6 +36,9 @@ before(async () => {
WorkspaceLayoutContractError,
} = await server.ssrLoadModule("/src/core/observation/workspaceLayout.ts"));
({
+ admitLiveDefaultPresentations,
+ automaticLivePresentationIdentity,
+ livePresentationCloseFence,
observationPresentationSourceAfterLayoutApply,
visibleSourceIdsAfterRecordedCatalogActivation,
} = await server.ssrLoadModule("/src/core/observation/useObservationLayout.ts"));
@@ -213,6 +219,95 @@ test("opening a recorded catalog reveals its sealed cameras beside the point clo
);
});
+test("a sequential live acquisition re-arms the same camera without reopening a deliberate close", () => {
+ const pointCloud = {
+ id: "k1:sensor.lidar.primary",
+ sourceId: "sensor.lidar.primary",
+ modality: "point-cloud",
+ availability: "streaming",
+ transport: "rerun-grpc",
+ previewUrl: "grpc://127.0.0.1:9876/proxy",
+ delivery: null,
+ activation: null,
+ binding: {
+ deviceId: "k1-a",
+ deviceSessionId: "device-session-reused",
+ acquisitionId: "acquisition-a",
+ },
+ capabilities: { defaultVisible: true, overlay: false },
+ };
+ const camera = (acquisitionId, deliveryId) => ({
+ id: "k1:sensor.camera.right",
+ sourceId: "sensor.camera.right",
+ modality: "video",
+ availability: "streaming",
+ transport: "websocket",
+ previewUrl: null,
+ delivery: {
+ id: deliveryId,
+ kind: "mse-fmp4-websocket",
+ url: "/camera-preview/reused",
+ mediaType: 'video/mp4; codecs="avc1.641028"',
+ },
+ activation: {
+ groupId: "k1:device-session-reused:camera.preview.decoder",
+ maxActive: 1,
+ selected: true,
+ controllable: true,
+ },
+ binding: {
+ deviceId: "k1-a",
+ deviceSessionId: "device-session-reused",
+ acquisitionId,
+ },
+ capabilities: { defaultVisible: true, overlay: true },
+ });
+
+ const firstCamera = camera("acquisition-a", "camera-preview-2");
+ const first = admitLiveDefaultPresentations(
+ [pointCloud.id],
+ [pointCloud, firstCamera],
+ new Set(),
+ new Set(),
+ );
+ assert.deepEqual(first.visibleIds, [pointCloud.id, firstCamera.id]);
+ assert.deepEqual(first.admittedIdentities, [
+ automaticLivePresentationIdentity(firstCamera),
+ ]);
+
+ const sameAcquisitionNewDelivery = camera("acquisition-a", "camera-preview-3");
+ const closedInFirstAcquisition = new Set([
+ livePresentationCloseFence(firstCamera),
+ ]);
+ const afterDeliberateClose = admitLiveDefaultPresentations(
+ [pointCloud.id],
+ [pointCloud, sameAcquisitionNewDelivery],
+ new Set(first.admittedIdentities),
+ closedInFirstAcquisition,
+ );
+ assert.deepEqual(afterDeliberateClose.visibleIds, [pointCloud.id]);
+ assert.deepEqual(afterDeliberateClose.admittedIdentities, []);
+
+ const nextAcquisitionSameDelivery = camera("acquisition-b", "camera-preview-3");
+ assert.notEqual(
+ automaticLivePresentationIdentity(nextAcquisitionSameDelivery),
+ automaticLivePresentationIdentity(sameAcquisitionNewDelivery),
+ );
+ const second = admitLiveDefaultPresentations(
+ [pointCloud.id],
+ [
+ { ...pointCloud, binding: { ...pointCloud.binding, acquisitionId: "acquisition-b" } },
+ nextAcquisitionSameDelivery,
+ ],
+ new Set(first.admittedIdentities),
+ closedInFirstAcquisition,
+ );
+ assert.deepEqual(second.visibleIds, [pointCloud.id, nextAcquisitionSameDelivery.id]);
+ assert.deepEqual(second.admittedIdentities, [
+ automaticLivePresentationIdentity(nextAcquisitionSameDelivery),
+ ]);
+});
+
test("workspace layout API uses the canonical endpoint and optimistic revision", async () => {
const calls = [];
const current = decodeObservationWorkspaceLayoutProfile(wireProfile());
diff --git a/docs/04_K1_WIFI_PROVISIONING_PROFILE.md b/docs/04_K1_WIFI_PROVISIONING_PROFILE.md
index 1eff7bb..fa95b66 100644
--- a/docs/04_K1_WIFI_PROVISIONING_PROFILE.md
+++ b/docs/04_K1_WIFI_PROVISIONING_PROFILE.md
@@ -111,6 +111,27 @@ handle from the operator's scan and connects that exact selected handle in the
following network action. A fallback lookup remains only for non-UI callers
that did not perform discovery first.
+The public advertisement cache is deliberately separate from an admitted
+device session. Rows from the latest explicit scan generation remain stable
+without wall-clock expiry while the operator completes the form. They still
+grant no mutation authority without exact retained-handle capture and live
+GATT validation. An admitted selected session ends only on proven disconnect,
+explicit stop, app/backend restart, selection of another K1, or connection-mode
+switch. A later scan may replace unselected candidates but never auto-connects
+any of them.
+
+An explicit Quick Connect to Bridge request for that same device can therefore
+continue when K1 no longer advertises after AP activation. The preconditions
+are: no active acquisition, no pending evidence cleanup, no active local source,
+and a terminal/released control session. A mode switch closes the old selected
+session first; the operator then scans, selects the K1, and creates a clean new
+GATT session for Bridge. Before the station command the code performs the
+normal internal `7f02` baseline read and allows exactly one 99-byte `7f01`
+write. A powered-off or unreachable peripheral ends that attempt. An
+unobserved post-write result is recorded as terminal `outcome-unknown`; it is
+never retried automatically and never blocks a later distinct explicit
+scan-select-connect attempt.
+
The 2026-07-20 prepared-host acceptance installed the exact firmware provider,
found one expected K1 candidate, emitted one AP-enable write, observed AP-ready
and completed one CoreWLAN association without an iPhone or manual credential.
@@ -136,12 +157,19 @@ mode. It never fragments or retries the payload automatically.
A completed GATT write only proves transport completion. It does not prove that
the K1 joined Wi-Fi or began beaconing. The application polls `7f02`; the
-observed response frame contains a fixed-width mode slot, an address slot, a
-status byte at offset 50 and the AP-ready flag at offset 51. The stale AP
+observed response frame contains a fixed-width text slot, an address slot, a
+status byte at offset 50 and the AP-ready flag at offset 51. The text slot is
+not a uniform mode enum: AP state uses the `WIFI_AP` control literal, while the
+2026-08-08 FW 3.0.2 Bridge observation returned the joined network name. The stale AP
baseline reports `WIFI_AP / 192.168.56.1 / byte51=0`; the physically observed
ready transition reports the same mode/address with `byte51=1`.
-For Bridge/Direct Connect, acceptance requires at least one of:
+For Bridge/Direct, acceptance requires the post-write `7f02` text slot to match
+the exact requested network name and the address slot to contain a valid
+non-AP private IPv4. This proves the desired target even when the K1 was
+already joined to the same network before the explicit idempotent command. A
+legacy literal-only `WIFI_CLIENT` observation retains the older conservative
+cross-family rules and requires at least one of:
1. `7f02` reports a non-AP IPv4 address;
2. the same address appears as a new router/ARP client after the write;
@@ -150,6 +178,15 @@ For Bridge/Direct Connect, acceptance requires at least one of:
Do not infer success from a write callback alone.
+An interrupted attempt with no exact post-write network-name observation is not
+made successful by a write callback, changed DHCP address, router/ARP row or
+reachable endpoint. Likewise, an already AP-ready baseline alone cannot prove
+the outcome of an interrupted Quick-to-Quick attempt. Such an attempt remains
+`outcome-unknown` in historical audit and is never replayed automatically. It
+does not create a permanent mutation barrier: after the old active operation
+and cleanup have terminated, a later explicit operator scan, selection, and
+connect is a distinct session with its own single reviewed write.
+
The Bridge/Direct Connect address is a DHCP lease, not configuration and not
device identity. Mission Core re-reads `7f02` without writing before every new
LAN control session, implicit-host acquisition and factory-calibration read.
@@ -157,6 +194,10 @@ If the value changes, it rotates `device_session_id`; it never retargets an
active acquisition. A correlated MQTT `DeviceInfo` response supplies the live
model/firmware/serial identity barrier.
+The joined network name is used only for exact in-process comparison with the
+current explicit request. Durable network audit stores the normalized semantic
+family and never stores or publishes the raw network name.
+
The 2026-07-20 reboot/power-cycle check observed the startup race directly:
one read returned the earlier `.54` lease while that exact address had no ARP or
application endpoint; a later read returned `.52`, where exact probes found
@@ -166,7 +207,9 @@ and why a BLE lease observation alone is not reported as live DeviceInfo.
For Quick Connect, host association is not admitted until the canonical
byte-51 ready flag is observed. CoreWLAN then searches only for the exact
-device-profile SSID for at most 15 seconds and performs at most one association.
+device-profile SSID for at most 30 seconds and performs at most one association.
+AP-ready is a device-state barrier, not proof that the host has already observed
+the RF beacon; a retained successful run required 18.142 seconds of discovery.
## Safety, recovery and stop conditions
@@ -176,9 +219,17 @@ device-profile SSID for at most 15 seconds and performs at most one association.
secure store. Missing or mismatched firmware material fails before the AP
write. Never extrapolate this provider to another firmware or model.
- The macOS adapter materializes a device-scoped Keychain item from the exact
- firmware source, then performs one association. Standard Wi-Fi Keychain and
- native prompt paths remain compatibility fallbacks, not the reviewed
- zero-touch path. It never asks the browser for a password.
+ firmware source before the BLE write, then performs one association using
+ only that exact profile. Standard Wi-Fi Keychain lookup, native password
+ prompts and post-write profile rewrites are prohibited. It never asks the
+ browser for a password. Preflight reads are non-interactive and validate the
+ exact SSID/source inside the helper before K1 changes network state.
+- The prepared-host laboratory adapter launches the reviewed Swift source only
+ through `/usr/bin/xcrun swift`. Runtime `swiftc` compilation to an ad-hoc
+ executable is prohibited because its unstable process identity regressed
+ Keychain ACL and CoreWLAN behavior. Product packaging still requires a
+ prebuilt, properly signed helper with a stable designated identity and
+ explicit CoreWLAN authorization.
- Do not alter Deco settings, scan the subnet, or guess any credential.
- If the status does not change, do not retry automatically.
- If the supplied credentials are wrong, reconnect over BLE and overwrite them
diff --git a/docs/06_K1_LIVE_VIEWER.md b/docs/06_K1_LIVE_VIEWER.md
index d20d73d..b20002a 100644
--- a/docs/06_K1_LIVE_VIEWER.md
+++ b/docs/06_K1_LIVE_VIEWER.md
@@ -110,12 +110,11 @@ directly and use their sibling metadata receive timestamps when present.
## Connect and stream live
1. Power K1 to its normal steady-green standby state.
-2. Confirm the manual power checklist in **Парк → Локальное устройство**.
-3. Run the real six-second BLE scan and select the intended device from the
+2. Run the real six-second BLE scan and select the intended device from the
complete visible-device list.
-4. Enter the existing router SSID/password and explicitly authorize the reviewed
+3. Enter the existing router SSID/password and explicitly authorize the reviewed
provisioning write. The backend does not retry the write automatically.
-5. Enter the required project name, confirm operator presence, closed LixelGO,
+4. Enter the required project name, confirm operator presence, closed LixelGO,
storage/power and steady green, then choose **Запустить сканирование и
локальный приём** once.
6. Mission Core emits operations 1–6, waits for their correlated device
diff --git a/docs/20_K1_CONNECTION_SUPERVISION_CANON.md b/docs/20_K1_CONNECTION_SUPERVISION_CANON.md
new file mode 100644
index 0000000..3b08e9e
--- /dev/null
+++ b/docs/20_K1_CONNECTION_SUPERVISION_CANON.md
@@ -0,0 +1,1141 @@
+# K1 connection supervision canon
+
+Status: canonical target and product acceptance contract, updated 2026-08-11;
+implementation/hardware conformance remains tracked by the acceptance manifest.
+
+Operator recovery procedure: [`runbooks/K1_CONNECTION_RECOVERY.md`](runbooks/K1_CONNECTION_RECOVERY.md).
+Production macOS association-observer boundary:
+[`adr/0014-k1-macos-association-observer.md`](adr/0014-k1-macos-association-observer.md).
+Physical-state loss and recovery boundary:
+[`adr/0015-k1-physical-state-recovery.md`](adr/0015-k1-physical-state-recovery.md).
+
+This document defines the connection state model for the local Mission Core
+runtime. It replaces the earlier assumption that one remembered K1 IPv4
+address, one retained CoreBluetooth object, one open TCP port, or one incoming
+point packet means that the device is connected.
+
+The product goal is a simple operator-owned lifecycle: every app start,
+disconnect, explicit stop, or committed network-mode transition ends the old
+connection session. A normal connection has one discovery intent and one
+application intent: the operator explicitly searches, selects one fresh result,
+enters the network data immediately, and presses **Применить** once. Opening the
+UI, selecting a result and editing credentials are presentation inputs only.
+Changing mode is one explicit local scenario-reset operation; it performs no
+device or host I/O and starts no discovery. Historical attempts are audit
+evidence only. They never
+change a row label or make an available K1 look connected. Durable physical
+START/STOP ambiguity remains a separate safety barrier: it can deny Apply and
+START until an explicit recovery action reconciles the exact target, but it may
+not turn mode, selection or input into hidden recovery work.
+
+## Product boundary
+
+### Product-surface brief
+
+The operator connects the selected K1 inside the existing device plugin section.
+The surrounding job/entity/lifecycle model is unchanged. This interaction is
+novelty A: a focused improvement to the existing connection surface, not a new
+product area. The chosen surface is the existing plugin section; a separate
+wizard, modal workflow or mandatory preflight/recovery screen is rejected.
+
+The surface reuses the canonical shared `Button`, `TextField`,
+`ActivityIndicator` and `StatusBadge` components. It introduces no shared
+entity, job type or lifecycle state, and it does not implement raw local
+`button`/`input` controls or literal local status colors.
+
+- Bridge/shared-LAN is the product path.
+- Quick Connect/device-AP is a prepared-host laboratory and recovery path.
+- Direct Connect/controller-hotspot remains a distinct topology and is never
+ silently treated as Bridge merely because both can expose a private IPv4.
+- The browser does not own Bluetooth, Wi-Fi, MQTT, or device state. It renders
+ the backend snapshot and invokes explicit operator actions.
+- Operator errors are secret-free. The UI maps an allowlisted public error code
+ to canonical copy; an unknown exception/message uses a canonical fallback.
+ Raw backend messages, credentials, SSIDs, payloads and stack traces are never
+ rendered.
+- No ambient background monitor or passive poll may originate Verify, Scan,
+ selection, reconnect, BLE writes, Wi-Fi provisioning, START, STOP, or repeat
+ an operator mutation. Backend events and bounded state polling may passively
+ refresh already available state; they create no operator progress state and
+ no new device operation. The sole declared exception is a supervised
+ read-only control bootstrap already owned by the exact active Apply intent;
+ after the durable ACK it may finish evidence collection but cannot mutate,
+ retry, create a UI action or outlive that intent's authority.
+- Discovery starts only from one explicit operator action, runs for six seconds
+ per click, and never auto-connects or auto-selects a device. Every ordinary
+ connectable result has the same one enabled **Выбрать** action, including an
+ exact UUID seen in an earlier connection scenario. Selection is a local draft
+ transition: it immediately reveals the selected card and applicable network
+ inputs and performs no Scan, GATT connect, Verify, retirement/reopen or other
+ backend I/O. Fresh discovery results never expose **Переподключиться** or
+ route through physical-recovery UI. Reconnect belongs only to a previously
+ established session after a proven interruption.
+- One explicit **Применить** click owns the resulting connection intent. It uses
+ only the selected transport captured by the completed scan, performs no
+ hidden discovery or read-only preflight, and crosses at most one reviewed
+ device-mutation boundary. An ended or ambiguous intent is never replayed.
+- Normal Bridge Apply never opts into changing the controlling Mac's Wi-Fi
+ association. Host-network switching is a separate future consequential
+ operator action, not a hidden part of Apply. Successful K1 provisioning may
+ therefore end as `network_applied` with `control_not_ready`.
+- The exact REST response to Apply is authoritative for that mutation boundary.
+ When `connection_attempt.phase=network_applied`, the controller accepts the
+ network intent as completed even when `control_state` is
+ `control_not_ready` or `unknown` and returns that durable ACK immediately; it
+ does not wait for WebSocket/poll convergence or full connection-ready. The
+ service may continue the same intent's supervised control bootstrap after the
+ ACK, but that continuation is read-only: no BLE/host mutation, mutation retry,
+ new UI action or second Apply. It is not a hidden frontend Scan or Verify.
+ Full exact readiness remains a separate gate for control and physical START.
+ The old Apply and its credentials are spent, but `connection_attempt` is a
+ read model rather than permanent lifecycle authority: a later new intent may
+ be admitted only by current server policy and a new explicit operator path.
+- App/backend restart, proven BLE disconnect, explicit stop, and a committed
+ Bridge/Quick network transition close that active session. Passive BLE Scan
+ is discovery only; it does not by itself provision, switch topology or
+ resolve a physical command.
+- Loss of Mission Core control does not prove that K1 stopped recording. It
+ revokes local authority and makes the physical device state unknown.
+- Physical motion authority is always false in this layer. A mobile platform
+ requires its own local watchdog and fail-safe stop independent of Mission
+ Core, the Mac, the router, and the browser.
+
+### One-intent connection surface
+
+The existing plugin section uses one progressive two-part surface. Its only
+model-bearing heading is **Подключение XGRIDS LixelKity K1**. The parts are
+**Подключение** and **Сеть**; saved/original/previous device
+terminology, physical-ledger state and protocol recovery names are not operator
+ceremonies.
+
+1. A cold plugin section shows the connection-mode selector and Step 01
+ **Подключение** with its explicit Bluetooth search action. Historical K1
+ identity never adds a reconnect prompt on cold entry. Opening or polling the
+ surface performs no action.
+ Each selector/escape gesture sends one explicit CAS-fenced
+ `reset_scenario`; it may seal only old local receiver/camera/control owners
+ and retire their audit lineage, but performs no BLE, device/host Wi-Fi,
+ MQTT publish, Verify, reconnect, provisioning, START, STOP or automatic
+ Scan.
+2. Bluetooth discovery starts only from the explicit search action;
+ while it runs the same step shows an activity indicator and visible seconds
+ countdown. Every completed connectable result keeps one enabled **Выбрать**
+ action, including an exact prior UUID. No found row renders a reconnect CTA,
+ a disabled primary action or a historical-device decision. The completed
+ explicit search is authoritative for this new connection draft; a projected
+ historical recovery fact cannot hijack it and require a second search.
+3. One **Выбрать** click updates browser-local selection only. It keeps the
+ selected row/card visible and immediately reveals Step 02 **Сеть** for Bridge
+ and Direct Connect. SSID/password editing is also local-only. Quick Connect
+ immediately shows its selected-device Apply summary without credential
+ fields. Selection starts no loader and calls no controller method.
+4. One explicit **Применить** click creates the only device connection/mutation
+ intent. The desired mode already belongs to the acknowledged scenario-reset
+ revision; Apply may perform at most one reviewed K1 mutation. Its frontend
+ handler never performs a hidden
+ Scan or Verify,
+ reconnect, retirement/reopen, candidate substitution or retry. The supervisor
+ and ledgers remain the authority before admission and after dispatch.
+
+The successful Apply response latches its post-mutation state immediately. An
+exact REST snapshot whose `connection_attempt.phase` is `network_applied` ends
+and spends the old Apply intent even if control is not ready or is unknown.
+While its exact service-owned child is `accepted` or `running` with
+`safe_next_action=wait-for-current-attempt`, ordinary controls and recovery
+actions remain locked behind one passive **Сеть настроена · подтверждаем
+управление** indicator. Once that child is terminal, an unready/unknown result
+enters the applied-network recovery choice. Delayed WebSocket/poll convergence
+cannot turn the accepted mutation into an error or replay the same intent.
+Verify is then the recommended read-only choice, not a prerequisite imposed by
+the read model. Any new connection path has a new idempotency identity and must
+be explicitly admitted from current backend policy.
+
+The service-owned same-intent bootstrap may still publish a later ready/unready
+snapshot after the REST ACK. It owns no blocking Apply loader and cannot call
+the browser's Scan/Verify/Apply handlers; the frontend may render only its
+passive exact-child settling indicator. Failure simply leaves the spent attempt
+in the explicit recovery-choice presentation; it never replays the network
+write.
+
+The ordinary **Выбрать** action does not weaken backend safety because it grants
+no authority. An admitted fresh candidate exposes inputs immediately. After an
+explicit scenario reset, only a successfully completed successor Scan may make
+an exact previously retired transport eligible for this ordinary draft. Apply
+still requires that exact current-generation CoreBluetooth handle, live GATT
+baseline validation and the existing network-mutation admission; it performs
+at most one write. Immediately before that sole write, the backend may append
+one exact local `reset-network-intent-read-only-settlement` reopen checkpoint,
+bound to the reset, successor Scan, immutable retirement and network request.
+This preserves the retirement and original unknown outcome as append-only
+audit, grants no START/STOP authority and is never exposed as a reconnect step.
+After an applied network result, the same service-owned intent may classify the
+reopened record from fresh DeviceInfo plus non-retained DeviceStatus: READY
+settles standby, while identity-bound initialized SCANNING settles active without replaying
+START and materializes only a STOP-only control shell. A reset-owned settlement
+never restarts the retired receiver, camera, evidence writer or acquisition.
+Exact operator-facing physical recovery keeps its backend CAS and
+transport pinning, but appears only inside an established session after an
+actual interruption, never in cold entry or Bluetooth results.
+
+Outside that reset-owned STOP-only settlement, fresh non-retained READY proof
+resolves physical ambiguity as standby; fresh exact same-project SCANNING resolves it as active and exposes only the
+separately guarded stop path outside the connection surface. Identity, GATT,
+CAS, route/control or policy failure leaves physical outcome unknown. No
+password, hidden START/STOP, provisioning or automatic retry bypasses it.
+
+`physical-command.retire-unavailable` remains a local durable backend primitive
+for an unresolved target that is truly unavailable or replaced. It requires a
+separate explicit recovery confirmation and exact runtime/operation/revision/
+transport CAS. It performs zero device I/O, starts no scan, preserves the
+unknown historical outcome and activates the exact transport deny. Selecting a
+row or pressing Apply never invokes it implicitly.
+
+FW 3.0.2 BLE `7f02` does not expose the stable DeviceInfo identity. Therefore a
+physical unit that reappears under a new CoreBluetooth UUID cannot currently be
+recognized as the retired identity before provisioning; this is an explicit
+protocol/field-acceptance gap, not a closed pre-provision identity invariant.
+
+Cancel is an exact revision/intent CAS and is local-only: it sends no BLE,
+Wi-Fi, MQTT, START or STOP command and does not resurrect an old socket. It is
+available only while no scan, Verify, Connect or other lifecycle winner is in
+flight. A stale browser tab cannot cancel or complete a newer dialogue.
+
+The browser may prefill a currently observable SSID when the operating system
+provides it, but it must not claim that macOS can silently disclose the Wi-Fi
+password. Bridge credentials are explicit operator input, retained only in the
+current browser operation memory, and fenced by backend runtime, device,
+connection mode, discovery generation and reconfiguration revision/intent.
+Any draft-fence change clears the password and submit
+authority; a backend runtime or reconfiguration-fence change also clears the
+SSID.
+
+## One connection is a chain of independent evidence
+
+The word `connected` is reserved for the final, current binding. The following
+facts must not be collapsed into one boolean.
+
+| Fact | What it proves | What it does **not** prove |
+| --- | --- | --- |
+| Operator `intent` | Which device and topology the current operation requests | Device presence, a completed mutation, host association, or authority |
+| Fresh BLE advertisement | A transport UUID was observed by the current explicit scan | Selection, a connected GATT session, that K1 is on a network, or that MQTT works |
+| Active selected BLE session | The operator selected one discovered transport and Mission Core established the current reviewed GATT connection | That K1 is on the requested network, that MQTT works, or that the session survives disconnect/restart/stop/mode switch |
+| Live GATT baseline/status | The reviewed K1 GATT contract answered during this explicit operation | That a write is safe to repeat or that the Mac followed K1 to its network |
+| Semantic device topology (`device_network`) | K1 reported the exact requested AP/STA result and, for LAN modes, a valid target address | That the Mac has a route, TCP is open, DeviceInfo matches, or data is fresh |
+| Host association (`host_network`) | The Mac currently has a particular interface, source address, route fingerprint, and host epoch toward the target | That the target is K1 or that port 1883 is reachable |
+| TCP endpoint reachability (`endpoint`) | Port 1883 answered for the exact target in the current host epoch | K1 identity, MQTT application dialogue, control authority, or live sensor data |
+| DeviceInfo/control proof (`control`) | Current MQTT dialogue returned the expected K1 DeviceInfo for the exact intent, mode, target, and host epoch | Fresh point/camera data or that a physical recording stopped after control loss |
+| Live data evidence (`data`) | Point, camera, or telemetry evidence arrived for a bounded acquisition session | Control authority, K1 identity by itself, or permission to start another action |
+| Network-attempt audit | What the previous explicit attempt requested, whether its single write boundary was crossed, and how the attempt ended | Presence, a live session, permission for automatic retry, or a veto over a later explicit session |
+| `last_known` | Historical troubleshooting context from a previously admitted connection | Presence, reachability, selection, lease, or command authority |
+
+The authoritative control binding is the exact tuple:
+
+```text
+(intent_id, transport_ref, connection_mode, target_ipv4:port,
+ host_path_epoch, logical_device_id, compatibility_profile_id,
+ control_session_id)
+```
+
+Evidence for a different intent, transport, mode, target, device identity, or
+host epoch cannot complete this tuple. "Same mode" is not "same connection";
+Bridge to a different K1 is a new intent and must earn new evidence.
+
+## Infrastructure failure domains
+
+The implementation treats every boundary below as independently fallible. A
+failure in one row must revoke only the authority that depended on it and must
+not fabricate the state of another row.
+
+| Boundary that can fail | Typical real scenario | Required response |
+| --- | --- | --- |
+| Browser ↔ local API | app refresh/restart, closed tab, suspended renderer, lost HTTP response | App restart/close ends its operator connection session without sending a device command; a single lost response never repeats an action. The next app session starts with discovery and selection. |
+| Mission Core process | crash, upgrade, second process, stale worker thread | Close the active connection session on restart; retain terminal audit only; stable process locks prevent a second controller; old runtime generations cannot publish evidence into a new session. |
+| CoreBluetooth discovery/GATT | K1 powers off, Mac sleeps, disconnect callback arrives, scan callback arrives late | Close and clear the selected session on proven disconnect. A later operator scan and selection establish a new GATT connection. Unselected rows remain stable for the latest admitted scan generation and are invalidated only by an explicit successor/reset, runtime-owner teardown or proven exact-target GATT failure. A row never grants mutation authority without exact-handle capture and live GATT validation. |
+| Mac Wi-Fi association | Quick AP is left manually, Bridge router changes, same IP is reused by another AP | Rotate host epoch using an opaque OS association identity in addition to route/interface/source IP. Rebuild TCP and protocol proof. |
+| IP route ↔ TCP probe | route changes while port 1883 connect is in flight | Admit reachability only for one correlated `route A → TCP → route B` sample where A and B are identical. |
+| MQTT control | socket half-open, broker disappears, wrong service answers 1883, late DeviceInfo | Revoke control lease. Require exact current intent, BLE transport, target, host epoch, durable device pin and DeviceInfo before commands. |
+| MQTT/data producers | old capture thread drains late, points continue after control loss, new acquisition starts | Stamp every message with an immutable producer generation; stale generations remain non-authoritative and cannot revive the new session. |
+| Router/phone hotspot | power loss, LTE/Wi-Fi reset, DHCP reassignment | Preserve only the semantically proven K1 topology. Host/TCP/control/data become offline independently; no provisioning retry follows. |
+| Physical K1 | battery removal before/during/after a BLE network write or START/STOP | End the network attempt as interrupted/unknown and allow a later explicit clean network session without replay. For physical START/STOP, preserve the separate durable ambiguity barrier and never infer STOP. |
+
+This is also the design boundary for a future vehicle. Mission Core may report
+loss quickly, but a drive controller must independently enter a locally safe
+state when its sensor/control heartbeat expires. A laptop, router, MQTT broker
+or UI can never be the only motion watchdog.
+
+## Product state and authority matrix
+
+These rows are ordered by proof, not by UI optimism. `Data` is intentionally
+shown independently from `Control`.
+
+| Product state | Device topology | Host path | TCP | DeviceInfo/control | Data | Authority and required presentation |
+| --- | --- | --- | --- | --- | --- | --- |
+| Not selected | none | any/unknown | unknown | absent | idle | No device or network authority. Offer device discovery/selection. |
+| Intent pending | previous only as `last_known` | unknown/current | unknown | revoked | previous stream non-authoritative at most | Show requested topology separately; do not call it connected. |
+| Active connection attempt | previous topology is historical only | unknown/current | unknown | revoked | previous stream non-authoritative at most | One selected K1, one mode, one active GATT session and at most one network write for this explicit intent. |
+| Attempt ended/interrupted | last observation is audit only | unknown/stale | unknown | revoked | evidence-only at most | Clear the active selection/session. Offer the normal scan-select-connect flow; no dedicated recovery action and no automatic retry. |
+| Configured offline | exact intended topology semantically proven | unavailable, wrong, or stale | unknown/unreachable | absent/lost | idle or evidence-only | Preserve the K1 topology fact. Show offline/degraded transport and a read-only host/endpoint verification action. |
+| Reachable unverified | exact current topology | fresh exact host epoch | reachable | absent, stale, or mismatch | independent | `degraded`, never `connected`. TCP alone grants no command or acquisition-start authority. |
+| Connected/controlled | exact current topology | fresh exact host epoch | reachable and fresh | exact current binding, fresh | idle/healthy/stalled/lost | Control allowed. Acquisition start allowed only when its separate lifecycle preconditions also pass. |
+| Control lost, data alive | exact topology remains last proven | current or changing | failed/stale | lost | fresh evidence still arriving | Revoke commands and start authority immediately. Keep data visibly labelled evidence-only; do not send STOP automatically. |
+| Standby unconfirmed | exact topology remains last proven | unavailable/stale | unknown/unreachable | STOP acknowledged and SCAN_STOPPING observed, but READY not observed | local receiver closed/evidence-only | Show `standby-unconfirmed`. After cleanup offer explicit bounded exact-target read-only recovery; deny provisioning and START. The always-available scenario reset may retire only the old local/audit lineage and start a clean Step 01, but does not prove standby or replay STOP. |
+| Standby unknown after STOP deadline | exact topology remains last proven | unavailable/stale | unknown/unreachable | STOP accepted, but neither READY nor SCAN_STOPPING arrived before the backend operation deadline | local receiver/camera/ingress closed locally; evidence-only archive retained | Terminalize the operation as `timed_out` and present product state `standby-unknown`, with `side_effect_status=unknown`, `safe_to_retry=false`; keep the physical ledger unresolved. Allow passive BLE/read-only recovery after successful cleanup, but deny every mutation, START and STOP until exact reconciliation. |
+| Recovery active rebind | exact topology and physical `transport_ref` match | fresh exact epoch | reachable | exactly re-proven DeviceInfo plus fresh same-project SCANNING | old data non-authoritative | Allow passive Scan and one single-use explicit STOP on the still-open recovery binding. An explicit scenario reset supersedes the read-only rebind, locally seals its receiver/camera/control owners and retires the old lineage without a device command; otherwise deny provisioning, START and automatic commands. |
+| Control alive, data stalled | exact current topology | fresh exact host epoch | reachable | exact current binding | stalled/lost | Control may remain available; data is not healthy. Offer stop/diagnosis according to backend `allowed_actions`. |
+| Closed supervisor | historical facts only | stale/unknown | stale/unknown | revoked | non-authoritative | No actions except reopening the product runtime through its normal lifecycle. |
+
+`connected` therefore requires all of the following at once:
+
+1. the current intent exists;
+2. K1's exact semantic topology matches that intent;
+3. the Mac host-path observation is fresh and belongs to the current epoch;
+4. TCP reachability is fresh for the exact target in that epoch;
+5. DeviceInfo and MQTT control proof match the exact binding;
+6. the proof has not expired and no route/sleep/network transition has revoked
+ it.
+
+Live data is not a seventh condition for control connectivity, because data and
+control may fail independently. It is a separate condition for declaring an
+acquisition healthy or its evidence authoritative.
+
+## Non-negotiable invariants
+
+- Ordinary discovery and selection are explicit and never auto-connect. One
+ search click owns exactly one six-second discovery. The operator selects
+ exactly one candidate; **Выбрать** is local-only and merely binds the form to
+ that transport. It starts no backend chain and grants no mutation authority.
+- Candidate presentation and active-session liveness are different. The latest
+ admitted scan generation remains visible without a wall-clock expiry while
+ the operator reads or completes the form. A successor Scan, explicit scenario
+ reset, runtime-owner teardown or proven exact-target GATT failure invalidates
+ that generation. A visible row is never mutation authority: Apply still
+ requires its exact captured CoreBluetooth object and live GATT validation.
+ Proven disconnect, explicit stop, app/backend restart, or a committed network
+ transition ends an admitted session.
+- A disconnect callback closes the active session and clears its live
+ selection. Rediscovery never reconnects the network automatically. UI entry,
+ row selection and form input perform no I/O. Mode/new-device choice performs
+ only its explicit local scenario reset and no device/host I/O. The
+ operator explicitly searches, selects, enters data and presses **Применить**.
+- Passive `scan-ble` means non-mutating with respect to K1; CoreBluetooth Scan
+ is still active discovery, not RF sniffing. It sends no K1 GATT/network or
+ physical command. After local
+ receiver/control cleanup has completed and the BLE runtime lease is free, an
+ unknown or proven-active physical record must **not** disable passive Scan.
+ It still blocks provisioning and START on the old lineage; scenario reset may
+ retire that lineage without resolving it. A discovered row is presence
+ evidence only and grants none of those actions.
+- Physical-state recovery is pinned to the durable physical record's exact
+ `transport_ref`. A fresh candidate for another K1 may be displayed, but it
+ cannot replace the recovery target, change semantic topology, reconcile the
+ ledger or authorize any command. Selecting or probing the wrong K1 is a
+ fail-closed, no-topology-change outcome.
+- `physical-command.retire-unavailable` is the only exception for an exact
+ physical target that the operator confirms is permanently unavailable or
+ replaced. It is a local ledger/authority transition, not physical
+ reconciliation and not device takeover: the original outcome remains
+ unknown, no device I/O or automatic Scan occurs, and the exact retired
+ transport receives an active deny for provisioning, Verify/adoption,
+ control, calibration, physical commands and network writes. The retirement
+ and unknown original outcome remain permanent historical audit even if that
+ active deny is later reopened. Explicit passive Scan/GATT metadata/MQTT
+ capture is non-authoritative evidence and cannot by itself restore topology
+ or control. Only a fresh exact same-UUID row plus the explicit exact-CAS
+ `physical-command.reopen-retired-reconciliation` transition may remove that
+ one active retirement deny for read-only reconciliation. Reopen performs no
+ device I/O. It is normally invoked only by a separate explicit recovery
+ action. The sole cold-flow exception is the exact local reopen checkpoint
+ inside a reset-owned, successor-Scan-owned Apply, durably ordered after the
+ network PREPARED record and before the one write-dispatch edge. Row selection
+ never invokes either path and no reconnect UI is rendered. A retired durable
+ identity, once DeviceInfo makes it observable, remains denied control and
+ successor START outside that exact reopened reconciliation. Because BLE
+ `7f02` has no stable device identity, a new UUID for the same hardware remains
+ a pre-provision detection gap.
+- Bridge to Quick, Quick to Bridge, same-mode reconnect, and selecting another
+ K1 all close the old connection session before starting the new one. Old
+ host, endpoint, control, data and BLE ownership cannot cross that boundary.
+- Every explicit network intent creates a new connect, validates the reviewed
+ GATT contract, and may read internal baseline `7f02` before exactly one
+ reviewed write. The baseline is internal protocol validation, not a mandatory
+ operator recovery step or separate product button.
+- A fresh Bridge `7f02` observation is provisional when it comes from the
+ explicit Apply-owned network operation.
+ It may be projected in memory for route/TCP/DeviceInfo checks, but it does
+ not replace durable semantic topology until the exact MQTT DeviceInfo has
+ matched or created the immutable transport/profile identity pin. Identity
+ mismatch, cancellation, route/control failure or process death leaves the
+ previous durable device A unchanged, or leaves the store empty on first
+ contact, and retires only the provisional B session. A previously dispatched
+ unresolved network write keeps its separate durable-first reconciliation
+ semantics.
+- FW 3.0.2 `7f02` uses its first text slot as `WIFI_AP` in AP state and as the
+ joined network name in station state. Bridge/Direct admission compares that
+ post-write name exactly with the current explicit request and a valid non-AP
+ private IPv4. The parser publishes only the normalized `WIFI_CLIENT` family;
+ raw network names remain inside the sensitive operation evidence and never
+ enter the public API or durable secret-free audit.
+- A timeout, disconnect, cancellation, browser loss, or process death never
+ triggers an automatic network write retry. The attempt becomes terminal audit
+ (`not-dispatched`, `completed`, `failed`, `interrupted`, or `outcome-unknown`)
+ and releases its right to block a later distinct explicit session.
+- Repeating an explicit operator action creates a new intent and may perform
+ its own one reviewed write after ordinary current-session preconditions pass.
+ The previous attempt is not replayed and its payload/credentials are not
+ reused automatically.
+- Network-attempt audit is secret-free, atomically recorded, and useful for
+ diagnosis. It is not durable connection authority and cannot require a
+ read-only reconciliation UI before another explicit connect.
+- Active concurrency remains fail-closed: a process-wide BLE owner and stable
+ cross-process lease admit at most one discovery/GATT/network operation at a
+ time. A new operator intent does not bypass an operation that is still
+ actively executing or native cleanup whose completion is unproved. Once that
+ active work terminates, historical audit cannot keep the lease fenced.
+- Route or MQTT failure after a proven device topology does not make the BLE
+ write unknown. It produces configured-offline/degraded state with no control
+ authority.
+- Bridge provisioning does not silently move the Mac to another Wi-Fi network.
+ The ordinary UI sends no host-switch opt-in. `network_applied` is a successful
+ terminal K1 mutation even when control is not ready; the UI must not repeat
+ that intent's BLE write. Recommended separately explicit read-only Verify may
+ establish host route, endpoint and control proof for the applied topology; a
+ server-policy-admitted new intent follows its own fresh path. Any future
+ host-switch action requires its own consequential confirmation and intent.
+- `network_applied` plus `control_not_ready` or unknown outcome spends the old
+ Apply. An exact accepted/running service child first keeps ordinary controls
+ and recovery actions behind a passive settling indicator. After that child is
+ terminal, the UI presents an explicit recovery choice, independent of the
+ browser-local mode. It never authorizes an automatic or same-intent replay.
+ Recommended Verify accepts only the backend `serverBound` current/configured
+ transport and mode; browser selection, remembered rows and local mode can
+ never substitute its target.
+- A new intent is nevertheless possible when current server policy admits an
+ explicit path. Bridge uses the distinct `prepare-select-device` local-only
+ CAS with zero device/host I/O; only after success may the operator start a
+ fresh six-second scan. Quick and Direct use an explicit policy-gated
+ `scan-ble`, then the latest fresh row and a new idempotency Apply. A mode or
+ same-mode new-device request instead uses the local `reset_scenario` CAS,
+ available across every non-reset owner, and is followed by a fresh explicit
+ scan. None of these
+ choices selects a row, scans, Verify, provisions
+ or continues Apply behind another click; the browser grants no authority.
+- A pre-write failure records no network side effect and ends the new attempt.
+ Previous topology may remain historical context, but no old active session is
+ resurrected.
+- Selecting any mode, including the current one through **Подключить другой
+ K1**, sends one explicit idempotent `reset_scenario` with exact desired-mode
+ revision. The first reset supersedes an older non-reset local action; while it
+ owns `mode`, the visible reset controls dispatch no second intent. It seals
+ retained receiver/camera/control owners, invalidates BLE candidates,
+ credentials and topology authority, and durably retires ambiguous old
+ physical lineage without resolving it. It performs no device command, BLE,
+ host-network write or automatic Scan. The resulting Step 01 starts clean and
+ search remains a separate click. Apply remains the only boundary that creates
+ a new network intent and may cross the reviewed device-write edge.
+- Host route/interface epoch changes, manual Wi-Fi switches, sleep/wake,
+ endpoint loss, MQTT failure, or stale protocol evidence revoke their live
+ authority immediately. Re-admission is explicit and never writes
+ automatically.
+- A host epoch includes an opaque, process-scoped association token supplied by
+ the OS helper. Raw SSID/BSSID values never enter API state or logs. Missing
+ association evidence remains explicitly `unavailable` and never becomes
+ association proof. The laboratory helper keeps one fallback token only for
+ the same process/interface/failure scope so an unchanged kernel route is not
+ falsely rotated every second. Its proven association token is derived from
+ interface+BSSID, not SSID visibility, so the same BSSID remains stable across
+ `ssid+bssid` and `bssid-only` observations. For an already exact healthy
+ DeviceInfo/control binding only, an unproven helper observation with the same
+ raw kernel fingerprint/interface/source retains the preceding proven host
+ fingerprint while the monitor still performs TCP and a final raw-route
+ recheck. This refreshes route/TCP liveness, not association or control proof.
+ Interface/source/route loss, a proven different BSSID, endpoint/control loss,
+ proof expiry, intent/target change, or process restart still revokes. An
+ unverified path remains bounded and fail-closed. Authority still requires
+ fresh TCP plus exact DeviceInfo/control evidence; the fallback token alone
+ grants nothing.
+- A TCP success is admissible only when host route/association observations
+ taken immediately before and after the connect are identical. A success
+ attached to a different or unknown epoch is discarded.
+- TCP port 1883 being open is diagnostic only. Correlated K1 protocol evidence
+ is required for device identity and control authority.
+- `connection.endpoint-probe` is the only configured/offline host-only action.
+ It selects either the exact coherent current supervisor target or the latest
+ valid durable semantic-topology record on the server, performs one bounded
+ association-bound host-route/TCP:1883/association-bound host-route sample
+ through the same process-owned macOS association observer used by the
+ supervisor, without mutating supervisor evidence, and publishes
+ `missioncore.xgrids-k1-configured-endpoint-probe/v1`. It never enters the BLE
+ runtime, never reads DeviceInfo, never changes K1 networking, never retries
+ automatically and never grants
+ control authority. The result carries the exact transport plus current intent
+ or durable semantic revision, so a result from an older target is not rendered
+ as evidence for a replacement topology. It is diagnostics, not a prerequisite
+ for the normal scan-select-connect lifecycle.
+- The first exact MQTT DeviceInfo accepted for one BLE `transport_ref` creates
+ a private durable identity pin. A later logical-device/profile mismatch is a
+ hard identity conflict and cannot overwrite that pin automatically.
+- Exactly one local Mission Core process may own the application-control lease.
+ Process death releases the OS lock, but a second live process cannot open a
+ competing control dialogue or emit START/STOP.
+- The same stable OS lease is acquired at the lowest supported CoreBluetooth
+ boundary for discovery, status/calibration reads, GATT inspection, AP enable
+ and Wi-Fi provisioning. A higher-level network transaction may explicitly
+ borrow its already-held lease, but no service, CLI or read-only helper may
+ bypass it or acquire a second lock file.
+- Caller timeout/cancellation does not release that OS lease. Ownership moves
+ to the detached native cleanup and is released only when CoreBluetooth has
+ actually completed. An unproved cleanup poisons the BLE runtime and retains
+ the lease until process exit; a new loop or request cannot guess that the
+ adapter is idle.
+- Control and data freshness are independent. Either can fail without
+ inventing the state of the other.
+- No command is automatically replayed after timeout, reconnect, wake, browser
+ refresh, process restart, or network change.
+- There is one narrowly scoped service-owned exception to the general
+ no-background-reconnect rule: an already running, plugin-commanded
+ acquisition with a composite-confirmed START may rebind its **read-only data
+ and inspection transports** after transient host-path loss. This exception is
+ defined below. It is not an operation retry and grants no command or network
+ mutation authority.
+- UI entry, mode, selection and credential input never
+ start recovery work. Apply is the only normal connection intent. It performs
+ no hidden discovery, browser Verify, candidate substitution or command
+ replay. The exact post-reset retired-UUID exception defined above may append
+ one request-bound local reopen checkpoint inside Apply and settle it through
+ the service-owned read-only continuation; it is not a UI recovery step and
+ grants no extra write or START/STOP. There is no loop, timer-driven retry, similar-device fallback,
+ continuation after completion or background resumption. A later Apply creates
+ a new bounded intent; the ended one never restarts itself. Exact target
+ authority comes only from the captured fresh discovery, backend policy,
+ semantic topology and supervisor/ledger fences; browser memory cannot
+ manufacture it.
+- The read-only observation may open a non-reconnecting pre-START control
+ generation for the exact target. Outbound ordinal 1 is exactly one canonical
+ DeviceInfo request; it publishes nothing else and then, when physical
+ classification is required, waits passively for a fresh, non-retained
+ DeviceStatus received after the DeviceInfo barrier. Each requested read-only
+ observation emits zero BLE writes, Wi-Fi provisioning writes, DeviceConfig,
+ ModelingStatus/status solicitations, time sync, workspace, project, START or
+ STOP. It is not a network reconnect and grants no mutation authority.
+- A denied Apply terminates before device I/O with an explicit stale or
+ safety-blocked outcome. An Apply whose response is lost after dispatch is
+ explicitly outcome-unknown and `safe_to_retry=false`; it never reuses the
+ password or restarts itself. Step 02 remains visible with the selected card so
+ the operator can understand the result and deliberately start a new scan or
+ intent. Physical recovery remains pinned to its durable `transport_ref`, so
+ another K1 cannot be substituted by client inference.
+- Fresh canonical READY records cessation/standby without inventing a
+ successful STOP. Fresh initialized SCANNING for the exact same project may
+ rebind the successful or ambiguous physical START to the exact new control
+ generation and expose one single-use, explicitly confirmed STOP. It never
+ replays START, never sends STOP automatically and never grants a second STOP
+ from the same confirmation/checkpoint.
+- A STOP application acknowledgement is not a READY observation. If
+ SCAN_STOPPING was observed and Wi-Fi or MQTT is then lost before READY, local
+ receiver/control cleanup may finish and the product state becomes
+ `standby-unconfirmed`. Explicit passive Scan and explicit bounded exact-target
+ read-only recovery remain available; provisioning and START remain blocked on
+ that lineage. Scenario reset may retire it without claiming READY.
+- If STOP was accepted but neither READY nor SCAN_STOPPING arrives before the
+ backend-owned operation deadline, Mission Core performs local-only
+ receiver/camera/perception-ingress cleanup, terminalizes the operation as
+ `timed_out`, and presents the local result as `standby-unknown`, with
+ `side_effect_status=unknown` and
+ `safe_to_retry=false`. The durable physical ledger stays unresolved. After
+ cleanup, passive BLE and read-only observation are allowed; provisioning,
+ START and STOP remain denied on that lineage until exact reconciliation.
+ Scenario reset remains available as a local retirement escape. A cleanup
+ failure retains the local lease/fence and retries
+ only host cleanup; it never repeats the physical STOP.
+- Every runtime message is bound to the acquisition producer generation that
+ created it. A callback from an older generation is rejected before it can
+ update data freshness, perception ingress, metrics, or authority.
+- In particular, **no automatic BLE network write or retry is allowed after an
+ ambiguous dispatch**. A later explicit operator attempt is a new session and
+ is allowed after the old active operation and cleanup have terminated.
+- The network-attempt journal and semantic topology store are deliberately
+ separate. The journal is historical audit; the topology store answers only
+ what an exact current observation last proved. Neither restores BLE presence,
+ host, endpoint, DeviceInfo, control or data authority after restart.
+- Legacy unresolved network records are terminalized as historical
+ `abandoned-by-restart`/`outcome-unknown` audit during migration. They are not
+ silently declared successful and do not authorize replay, but they also do
+ not veto a new explicit operator session.
+
+### Sole automatic active-stream read-only rebind exception
+
+This exception exists only while one process still owns the exact active
+acquisition. Admission requires every fact below at the instant data transport
+reports connection loss:
+
+- the physical ledger has one resolved, composite-confirmed START with publish
+ return, QoS2 completion, successful application response and fresh
+ non-retained initialized same-project SCANNING;
+- the current acquisition id, device id/session, evidence session, snapshot
+ runtime id, runtime producer generation, connection intent/mode/target,
+ transport ref and physical operation id all match that START lineage;
+- the acquisition-owned right-camera recording root still matches the same
+ evidence session; and
+- no explicit mode/reset/force-finish owner has superseded the lineage.
+
+When admitted, the runtime remains neutral `reconnecting`; a short route loss
+does not terminalize the acquisition. Retry cadence is bounded backoff
+`0.5s, 1s, 2s, 4s`, then `5s` capped. There is no automatic terminal timeout:
+the owner remains reconnecting/blocked until exact recovery, truthful physical
+standby/fault evidence, or explicit local force-finish. A late failure from the
+old application-control socket is classified as superseded transport evidence
+and cannot raise a global terminal operation while this recovery generation is
+current.
+
+Local force-finish invalidates that recovery generation before closing any
+socket or producer. A receiver, camera or archive cleanup failure therefore
+cannot resurrect the old acquisition: it is a visible retryable **local-only**
+finalization failure, retains the evidence cleanup fence, and leaves the
+physical START proof untouched. Only an explicit local cleanup retry or exact
+connection-scenario reset may finish those retained host resources; neither
+path may publish START/STOP, enter BLE, or write device/host network state.
+
+Each attempt may perform only:
+
+1. exact host-route/association and TCP observation for the frozen target;
+2. one inspection-only DeviceInfo bootstrap on a new globally fresh control
+ generation; and
+3. passive receipt of a fresh, non-retained DeviceStatus after that DeviceInfo
+ barrier.
+
+It performs zero BLE discovery/write, Wi-Fi association/provisioning,
+DeviceConfig, time sync, workspace/project mutation, START or STOP. The raw
+capture evidence writer is retained across MQTT client replacement. A durable
+read-only reconciliation may advance the physical record revision; a failed
+first MQTT SUBACK may retry only while every immutable lineage field is equal
+and that revision advanced monotonically for the same operation.
+
+Recovery outcomes are fail-closed:
+
+- exact same identity and initialized same-project `SCANNING` append a durable
+ active rebind, adopt the fresh control generation and resubscribe data without
+ replaying START;
+- fresh unbound `READY` appends durable cessation and interrupts/seals local
+ acquisition owners without STOP;
+- fresh `SCAN_OVER` is also durably classified as cessation, but leaves a
+ `scan-over-awaiting-ready` read-only fence. It is no longer modeled as an
+ active START, yet a later START remains denied until another fresh exact
+ `READY` reconciliation;
+- foreign identity/same-IP substitution, changed target/session/runtime or
+ camera lineage blocks recovery for explicit operator handling; and
+- device/system fault or unsafe status terminalizes locally as fault without
+ STOP or retry.
+
+If the acquisition-owned FFmpeg process exited or has emitted no complete
+segment for the stall threshold, recovery may CAS-restart only the same right
+camera/source/target/recording session and exact source-generation/active-epoch.
+The old archive epoch is sealed `interrupted`, a new epoch is opened once, and
+late callbacks from the old epoch are generation-rejected. This is local
+producer recovery, not public camera selection or a device command.
+
+`acquisition.force-finish-local` is the explicit escape hatch for permanent
+loss. The request is fenced by snapshot runtime, acquisition id/state revision,
+recovery generation and runtime producer generation. The backend invalidates
+and cancels the recovery owner before closing local control, receiver, camera
+and perception ingress; it preserves physical START evidence and sends no
+STOP. A queued mode reset uses the same idempotent helper. Whichever wins the
+local lifecycle gate supersedes the other, and no late recovery success may
+revive the old acquisition.
+
+## Network-attempt lifecycle and audit
+
+The live operation may pass through `prepared`, `dispatching`, and `observing`.
+Those stages fence concurrent work only while that explicit operation or its
+native cleanup is active. The durable record is an audit trail, not a
+cross-session mutation barrier.
+
+| Stage/outcome | Meaning | Next explicit session |
+| --- | --- | --- |
+| `prepared` | Current selected session passed preconditions; no write crossed the dispatch boundary | If interrupted, record `not-dispatched`, release active ownership, and allow a new scan-select-connect attempt. |
+| `dispatching` | Audit was persisted immediately before the one reviewed BLE write | If the process/transport ends without a result, record `outcome-unknown`; never replay automatically. |
+| `observing` | The one write returned and bounded status observation is running | Record the observed outcome or `outcome-unknown`, then release active ownership. |
+| `completed` | Current attempt observed its intended topology | Rebuild host/TCP/DeviceInfo for this session; later explicit intents still start cleanly. |
+| `failed` / `interrupted` / `outcome-unknown` | Current attempt ended without a usable connected session | Clear selected/live session. The normal operator flow may start a distinct new attempt; no special recovery control is required. |
+| Corrupt audit | Historical data cannot be trusted | Quarantine/report the audit record without manufacturing success or replay. If the active process lease is free, corrupt history alone does not make the physical K1 permanently unusable. |
+
+An unknown result remains honestly unknown in history. Mission Core does not
+claim that the command was applied or not applied. That uncertainty prohibits
+automatic replay of the old attempt; it does not prohibit a later fresh,
+explicit operator intent from sending its own single reviewed command.
+
+## Transition rules
+
+### Switching Quick Connect and Bridge
+
+1. A mode choice or same-mode **Подключить новый K1** click is one explicit,
+ idempotent `reset_scenario` under desired-mode CAS. It remains available
+ during active, reconnecting, cleanup-pending and unknown-physical states.
+ Mission Core locally seals/retire receiver, camera and control ownership,
+ invalidates candidates/drafts/credentials and retains truthful audit that
+ the previous K1 may still be scanning. It sends no device command, BLE,
+ host-network write or automatic Scan.
+ The top-right refresh-shaped utility is also this explicit reset, not
+ `state.read`: **Сбросить подключение** sends one reset to the canonical
+ Bridge default. While pending its label is **Сбрасываем подключение** and it
+ is non-dispatchable until that bounded reset settles, preventing a second
+ browser token from abandoning the accepted result. It still supersedes any
+ other pending local action. The committed revision overwrites even a dirty
+ browser mode draft with canonical Bridge.
+2. Choosing the original mode is a new-device reset, not cancellation of a
+ browser-local draft. A duplicate `reset_id` replays the committed result;
+ a newer reset supersedes an older waiting reset before teardown.
+3. Explicit Scan is a separate later action and runs one six-second bounded
+ passive discovery. Mission Core proves that
+ local runtime/native cleanup has completed and the BLE discovery lease is
+ free. It may close only a safe pre-START local control session and locally
+ abort an exactly prepared/no-receiver acquisition without STOP. An unknown
+ or active physical record does not block this Scan. The committed reset
+ marker remains `active=true` until a successfully admitted explicit Scan
+ completes, including an empty successful result. The Scan captures the
+ exact reset id/revision/mode at action entry, then stores its admitted
+ discovery generation and sets only that unchanged marker inactive. Failure,
+ cancellation, generation invalidation or a different
+ newer pending reset leaves it active. The inactive marker remains available
+ for exact `reset_id` replay and old-operation suppression. It continues to
+ fence the saved/reconnect presentation of the retired scenario, including
+ after reload, but never hides a newly correlated connection attempt admitted
+ after the reset revision. A new failed or outcome-unknown attempt renders
+ its current recovery/error surface immediately.
+4. Scan does not revoke or replace semantic topology and starts no connect or
+ Verify. Physical recovery remains pinned to the exact `transport_ref`.
+5. The operator selects one ordinary fresh K1 and immediately enters applicable
+ credentials. Selection is local-only. Apply proves physical standby, exact
+ mode/discovery/runtime CAS and the selected transport. Physical unknown/
+ active blocks Apply and START while leaving separately explicit recovery.
+6. Apply retires old live authority, creates the new connection
+ intent, opens a new GATT session for that selected transport, may read
+ internal baseline `7f02`, and performs at most one reviewed network write.
+ It is never retried automatically.
+7. Success admits the observed topology. Normal Bridge Apply does not switch Mac
+ Wi-Fi. Host/TCP/DeviceInfo may therefore remain unready and require explicit
+ read-only Verify. Failure/disconnect ends the new session; the next operator
+ attempt starts with explicit discovery and selection.
+
+Quick to Bridge and Bridge to Quick obey the same transition. Neither path may
+carry an old Mac route, TCP result, DeviceInfo response, control session, data
+session, or UI `connected` label across the intent boundary.
+
+### Losing K1, the router, or the Mac route
+
+- Loss before dispatch records `not-dispatched`; loss at/after dispatch records
+ `interrupted`/`outcome-unknown`. Both end the active connection session and
+ permit a later distinct explicit attempt. Neither automatically retries.
+- Loss after the target was semantically proven preserves that K1 topology but
+ revokes host, endpoint, DeviceInfo, control, and acquisition-start authority.
+- During acquisition, fresh data that survives control loss is evidence-only.
+ Mission Core must not infer that recording stopped, nor issue an automatic
+ STOP over a newly recovered connection.
+- Once local receiver/control/native cleanup is complete, physical unknown or
+ active state leaves passive BLE Scan available. It continues to deny Apply
+ and START on the old lineage. Explicit read-only recovery targets only the
+ durable physical record's `transport_ref`; alternatively, scenario reset may
+ retire that old lineage without resolving it and open a clean new Step 01.
+- If that exact target is permanently unavailable, retirement/reopen requires a
+ separate explicit recovery confirmation with exact CAS. Neither **Выбрать**
+ nor **Применить** owns that local mutation or subsequent Verify.
+- If STOP reached SCAN_STOPPING and the Mac loses Wi-Fi before a fresh READY
+ status, the local operation is `standby-unconfirmed`, not a generic connected
+ state and not a proven STOP. If STOP was accepted but neither READY nor
+ SCAN_STOPPING arrived before the backend operation deadline, local-only
+ cleanup produces terminal `standby-unknown`, while the physical ledger stays
+ unresolved. In both cases only exact read-only recovery may classify READY or
+ same-project SCANNING; no command is replayed automatically.
+- A manual Mac Wi-Fi change and an unplanned router/hotspot failure have the
+ same authority consequence: host epoch changes or expires, so all evidence
+ bound to the old epoch is rejected.
+
+### Browser, sleep, wake, and backend process lifecycle
+
+- Browser app refresh/close emits no device command but ends that operator
+ connection session. The next page load starts with no selected live K1 and
+ renders the cold mode + Step 01 **Подключение** surface. Backend-owned history
+ stays internal; only explicit search, Apply, or a separately rendered exact
+ recovery action may create I/O. Uniform ordinary **Выбрать** creates only a
+ browser-local draft.
+- Mac sleep/wake always invalidates the old host epoch and lease, even if the
+ interface name and IPv4 appear unchanged after wake.
+- Backend restart closes every old network connection session. A live network
+ attempt is terminalized as `not-dispatched` when dispatch was not crossed or
+ `abandoned-by-restart`/`outcome-unknown` otherwise. Backend startup does not
+ verify, scan, reconnect, provision, START or STOP automatically. A later
+ operator action may invoke one bounded exact-target read-only attempt.
+- A resolved target may restore semantic topology after restart, but it starts
+ configured/offline. Host path, TCP and DeviceInfo must be observed afresh.
+- Restart discards every in-memory CoreBluetooth object, selection and session
+ token. The UI starts with no selected live K1. Explicit search plus ordinary
+ **Выбрать** creates only the new local candidate draft; it never internally
+ re-observes a target. A distinct exact recovery action may perform the one
+ backend-authorized read-only observation when policy requires it.
+ Old network-attempt audit has no role in admission. Host association, TCP
+ reachability, DeviceInfo/control and data remain separate proofs.
+- Service shutdown cancels and owns an exact control-bootstrap child while its
+ owner event loop is running. If synchronous shutdown begins only after that
+ loop has already stopped or become unavailable, Python cannot physically
+ join the now-unrunnable Task. The service must still terminalize the durable
+ child fail-closed and set a closing fence before releasing ownership, so a
+ retained Task reference cannot later publish success, perform I/O or grant
+ control authority; the reference may remain until loop/service destruction.
+
+## Required acceptance scenarios
+
+Each scenario must assert backend state, durable ledger state, authority,
+allowed next action, and product presentation. Passing only the HTTP request or
+showing a green lamp is insufficient.
+
+### Topology transitions and device identity
+
+| ID | Scenario | Required acceptance |
+| --- | --- | --- |
+| CONN-01 | Quick Connect to Bridge succeeds | Quick session closes; the operator starts a new Bridge scan, local selection and Apply; one Bridge write at most; exact STA/LAN status commits Bridge; host/TCP/DeviceInfo rebuild; `connected` appears only after the exact new binding. |
+| CONN-02 | Bridge to Quick Connect succeeds | Same guarantees in reverse; old Bridge session closes before new Quick discovery, local selection and Apply; AP status commits Quick even before the Mac joins it; old Bridge route/DeviceInfo cannot authorize Quick. |
+| CONN-03 | Quick to Bridge fails before dispatch | New attempt terminalizes `not-dispatched`; old Quick facts are historical only, no live session is restored; no BLE side effect, no automatic retry, and a later explicit attempt is allowed. |
+| CONN-04 | Bridge to Quick fails before dispatch | New attempt terminalizes `not-dispatched`; old Bridge facts are historical only; active ownership releases and a later explicit attempt is allowed. |
+| CONN-05 | Bridge to Bridge, same mode but different K1 | Different transport/device creates a new intent. Old K1 TCP/DeviceInfo is rejected; the new K1 must pass exact discovery, topology, target, identity and control proof. |
+| CONN-06 | Same UUID is rediscovered after the prior session ended | It remains a candidate until the operator presses the same **Выбрать** action used by every row. That click updates only the local form and immediately exposes applicable inputs. It performs no Scan, connect, Verify, reopen, network mutation or command. |
+| CONN-07 | Wall-clock time passes beyond the legacy candidate TTL after one explicit Scan or admitted Apply | Unselected rows remain stable for the current scan generation; the active GATT session also remains usable. A successor Scan/reset/runtime-owner teardown or proven exact-target GATT failure invalidates the applicable candidate/session, while every Apply still requires exact-handle capture and live GATT validation. |
+| CONN-08 | Backend/app restarts after any network-attempt stage | No in-memory CoreBluetooth handle, selection or active network session survives. The previous attempt becomes terminal audit and never causes automatic discovery/write or blocks the normal new scan-select-Apply flow. |
+
+### Hard K1 power loss by operation phase
+
+| ID | Fault point | Required acceptance |
+| --- | --- | --- |
+| CONN-10 | Power removed before `prepared` | No write. Active selection/session clears; previous state is historical only; operator may power K1, scan, select and Apply again. |
+| CONN-11 | Power removed after `prepared`, before `dispatching` | Attempt terminalizes `not-dispatched`; no previous live session is restored; active ownership releases and a later explicit attempt is allowed. |
+| CONN-12 | Power removed after `dispatching`, before write result | Attempt is terminal `outcome-unknown`, no automatic retry occurs, active selection/session clears, and a later explicit operator scan-select-Apply intent is allowed after current safety gates. Physical START/STOP ambiguity rules are unaffected. |
+| CONN-13 | Power removed during `observing` | Last bounded observation remains audit; attempt ends and active ownership releases. No automatic BLE retry and no mandatory read-only recovery UI. |
+| CONN-14 | Power removed after target topology was semantically applied, before host association | New device topology stays committed; state is configured-offline, not mutation-unknown and not connected. |
+| CONN-15 | Power removed while connected but idle | Host/TCP/control lease expires; topology becomes last proven context; no device command is inferred or replayed. |
+| CONN-16 | Power removed during acquisition | Control and data transition independently to lost/stale. A process-owned composite START may enter the sole read-only active-stream recovery generation, but a powered-off K1 cannot satisfy route/TCP/DeviceInfo and remains reconnecting/blocked until explicit local force-finish. Physical recording stays unknown/last-proven-active; no automatic STOP/START or network write occurs. |
+| CONN-17 | Process crashes at any START/STOP publish boundary | Durable physical-command state distinguishes `prepared` from `dispatching/observing`. Only `prepared` can become `not-dispatched`; every later ambiguous stage blocks replay and automatic START/STOP after restart. |
+| CONN-18 | A proven START survives, but its original MQTT process/socket is lost while the same process-owned acquisition and project are still SCANNING | The sole service-owned active-stream exception retries exact host/TCP plus inspection-only DeviceInfo and passively receives a fresh non-retained initialized SCANNING status for the frozen lineage. The original START remains `succeeded`; the raw writer and producer generation are preserved, START is not replayed, and data resubscribe resumes only after durable same-lineage rebind. |
+| CONN-18A | Active-stream recovery observes fresh SCAN_OVER | Append a durable cessation audit for the same START, interrupt/seal local owners without STOP, clear active physical classification and retain a `scan-over-awaiting-ready` read-only fence. A fresh START remains denied until another exact fresh READY reconciliation. |
+| CONN-19 | A proven START survives, then K1 is power-cycled and a fresh explicit observation sees READY | The bounded exact-target attempt publishes one DeviceInfo request and passively observes fresh non-retained READY. Record physical cessation without inventing a successful STOP; the original START remains `succeeded` and effective physical state becomes standby. A later START still requires a fresh normal control session and READY baseline on the socket that will publish it. |
+
+### Host network continuity
+
+| ID | Scenario | Required acceptance |
+| --- | --- | --- |
+| CONN-20 | Shared router or phone hotspot disappears | Host epoch/endpoint/control revoke; Bridge topology remains last semantically proven. The plugin section returns to its ordinary cold progressive flow, not provisioning success, a stale connected state or a technical recovery ceremony. |
+| CONN-21 | Router returns with the same SSID/IP | Similar-looking network values do not resurrect the old lease. Fresh host observation, TCP probe and exact DeviceInfo/control proof are required. |
+| CONN-22 | Operator manually switches Mac Wi-Fi during Bridge | Epoch changes immediately; in-flight old-epoch TCP/DeviceInfo results are rejected; no automatic BLE write follows the switch. |
+| CONN-23 | Operator manually leaves K1 AP during Quick Connect | Quick topology remains the device fact, while host/endpoint/control become offline; returning to the AP requires read-only re-verification. |
+| CONN-24 | Mac sleeps and wakes on the apparently same network | Old epoch, endpoint and DeviceInfo proof are stale; reacquire them read-only before control returns. |
+| CONN-25 | Mac route changes between host probe and TCP result | The result for the earlier epoch is discarded and cannot create reachable or connected state. |
+| CONN-26 | TCP 1883 is open on a wrong/non-K1 target | Endpoint may show reachable diagnostic only; missing/mismatched DeviceInfo keeps connectivity degraded and authority false. |
+| CONN-27 | MQTT socket is half-open or heartbeat/control proof stops advancing | Route and TCP alone do not preserve authority. Exact-session control proof expires on monotonic and suspend-aware TTL; control/start revoke without sending a command. |
+| CONN-28 | Physical-state recovery is required after an ambiguous/interrupted command or a resolved active START whose control socket was lost | Normal row selection stays local and Apply stays denied. A separately explicit recovery action for the exact physical record `transport_ref` may own at most one read-only Verify; another row cannot substitute for it. Each observation generation publishes exactly one canonical DeviceInfo request and passively accepts only a fresh non-retained DeviceStatus after its DeviceInfo barrier. READY records standby/cessation. Exact same-project initialized SCANNING records an active rebind and exposes one single-use explicit STOP outside connection setup. No recovery action scans, provisions, retries or replays a command. |
+| CONN-29 | K1 is already SCANNING but there is no matching durable Mission Core START chain, or a different K1 is discovered during recovery | Treat it as external/foreign state, not as our successful START. The foreign candidate may remain visible as passive discovery evidence, but it cannot replace the physical record's `transport_ref`, mutate topology, reconcile the ledger or authorize START/STOP. No automatic STOP is sent; takeover requires a separate explicit durable policy. |
+| CONN-29A | Mac Wi-Fi/route disappears for longer than the old control keepalive while one composite-confirmed acquisition remains owned, then returns | Keep acquisition neutral `reconnecting`; retire the late old-control failure as superseded transport. Exact route/TCP/DeviceInfo plus fresh same-lineage SCANNING resumes the receiver. Wrong identity, runtime/session replacement or changed physical operation fails closed. |
+| CONN-29B | Operator chooses `Завершить локально` while recovery is pending, concurrently with a mode reset or late recovery success | One lifecycle-gated idempotent cleanup wins, invalidates recovery generation first, seals receiver/camera/control locally and preserves physical evidence. No STOP/START/BLE/network mutation is sent and no late callback revives acquisition. |
+
+### Durable restart and concurrency
+
+| ID | Restart/concurrency point | Required acceptance |
+| --- | --- | --- |
+| CONN-30 | Browser/app refresh or close during a network connection attempt | End the operator connection session without automatic command. Reload starts with no selected live K1 and offers the normal discovery flow; prior attempt remains audit only. |
+| CONN-31 | Server restarts with no active operation | No automatic device action and no restored live selection. Historical topology may display as historical/offline context only. |
+| CONN-32 | Server restarts at `prepared` | Terminalize as `not-dispatched`, release active ownership, and allow a later explicit new session. |
+| CONN-33 | Server restarts at `dispatching` | Terminalize as `abandoned-by-restart`/`outcome-unknown`; never replay automatically; do not block a later explicit new session. |
+| CONN-34 | Server restarts at `observing` | Preserve the last observation as audit, terminalize the attempt, release ownership, and allow a later explicit new session. |
+| CONN-35 | Server restarts after a completed target observation | Historical topology may display configured/offline, never as live reachability, selection or authority. |
+| CONN-36 | Server restarts after `not-dispatched` | Preserve audit/context only; no old active session is restored. |
+| CONN-37 | Network-attempt audit JSON is corrupt, oversized, wrong-schema, wrong-permission or symlinked | Quarantine/report the historical record and never invent success/replay. Once active process ownership is known free, corrupt audit alone does not permanently block a fresh explicit session. |
+| CONN-38 | Two local server processes request mutations concurrently | Cross-process lease serializes live admission. At most one process owns the selected GATT/write operation; the other performs no BLE write. |
+| CONN-39 | A stale process tries to update another operation ID/revision | CAS rejects the stale audit transition and cannot alter the current active operation or emit a BLE write. |
+
+### Control and data plane independence
+
+| ID | Scenario | Required acceptance |
+| --- | --- | --- |
+| CONN-40 | TCP remains open but MQTT DeviceInfo/control dialogue fails | Connectivity is degraded/unverified; control and acquisition-start authority are false. |
+| CONN-41 | MQTT control fails while points continue | Control is lost immediately; points may remain visible only as evidence for the current bounded session; no command is issued automatically. |
+| CONN-42 | Point/camera stream stalls while control remains healthy | Data state becomes stalled/lost without inventing control loss; operator may stop or diagnose according to `allowed_actions`. |
+| CONN-43 | Old acquisition packets arrive after intent/host epoch change | Packets cannot become authoritative for the new binding/session and cannot make the device connected. |
+| CONN-44 | DeviceInfo response from old target/epoch arrives late | Exact binding mismatch rejects it; no lease or green connected state is created. |
+| CONN-45 | Read-only control observation succeeds after an acquisition interruption | DeviceInfo proves only current identity/control. Physical recovery also requires a fresh non-retained same-generation DeviceStatus after the DeviceInfo barrier. Mission Core does not infer previous physical recording state and does not replay START or STOP; exact same-project SCANNING may expose one explicit single-use STOP only through the durable rebind. |
+| CONN-46 | A message from producer generation N arrives after generation N+1 starts | It is rejected before data freshness/perception admission; it cannot mark the new acquisition healthy. |
+| CONN-47 | A second local process opens application control while the first is alive | Stable OS lock denies the second process before MQTT commands; no competing START/STOP is emitted. |
+| CONN-48 | Camera producer generation N drains after N+1 is bound | The archived N fragment remains evidence, but the live perception ingress rejects it before the new acquisition queue. |
+| CONN-49 | Read-only connection monitor raises an unexpected exception | Supervisor revokes authority for that observation, the monitor remains supervised with bounded backoff, and later passive polls can refresh presentation without a process restart. Polling starts no Verify/Scan/reconnect and creates no operator progress state. |
+
+### Freshness, identity and presentation
+
+| ID | Scenario | Required acceptance |
+| --- | --- | --- |
+| CONN-50 | Candidate wall-clock age advances, or Mac sleeps/wakes | Wall-clock age alone removes no row from the latest scan generation and grants no mutation authority. Sleep/wake or an actual disconnect revokes live host/control authority; runtime-owner teardown also invalidates captured handles, so a later Apply must fail cleanly or require explicit rediscovery rather than use UUID memory as authority. |
+| CONN-51 | Same route/interface/source IP appears after association changed | Opaque association token changes host epoch; old TCP/DeviceInfo/control proof is rejected. |
+| CONN-52 | Logical K1 DeviceInfo changes for a durably pinned BLE transport | Identity conflict is shown; control/start remain blocked; the pin is not overwritten automatically. |
+| CONN-53 | Restart with a valid semantic topology record and no live network | UI shows configured/offline historical evidence. It does not show a fresh BLE candidate, reachable endpoint, green control state or live telemetry. |
+| CONN-54 | An old interrupted/unknown network-attempt audit and valid older semantic topology coexist | Both may be displayed as historical context. Neither restores a live session, triggers replay, requires a recovery button, or blocks a distinct explicit scan-select-connect attempt. |
+| CONN-55 | Plugin container crosses any acceptance width while an error panel is open | Blocks stack without overlap or clipping; the factual state and normal safe next action remain visible; resize fires no device action. |
+| CONN-56 | Long translated copy or an unknown future reason code exceeds a panel width | Content reflows and stays reachable. Panels do not use clipping/hidden overflow as an acceptance mechanism; geometry tests detect every escaped interactive element. |
+| CONN-57 | The physical K1 is replaced after the previous command chain reached an effective standby state | Identity/profile history is never overwritten in place. Supporting replacement of a resolved-standby identity requires a distinct operator-confirmed archive/rotation transaction; `physical-command.retire-unavailable` applies only to an unresolved unavailable target and is not that transaction. Until resolved-standby rotation exists, the new identity is rejected and no physical command is emitted. |
+| CONN-58 | A direct service/CLI/read-only BLE entrypoint runs while another process owns K1 or while native cleanup is detached | The call is rejected before CoreBluetooth admission. Every BLE entrypoint uses the same OS lock; timeout retains it through proven cleanup, and cleanup failure requires process restart. |
+| CONN-59 | Network-attempt audit admission succeeds but the in-memory operation journal cannot admit the request | The record is terminalized as failed with `side_effect_status=none`; no BLE call occurs, active ownership releases, and no ghost blocks a later explicit attempt. |
+| CONN-60 | A physical START/STOP confirmation is open while topology, device, acquisition or control CAS changes | The modal-open fence becomes stale, all confirmations are discarded and no request is sent. A confirm action may use only the exact immutable checkpoint displayed when the modal opened. |
+
+### Cross-layer recovery and executable UI policy
+
+| ID | Scenario | Required acceptance |
+| --- | --- | --- |
+| CONN-61 | A legacy server left a network record at `dispatching` or `observing` | Under the lifecycle lease, migration terminalizes it as secret-free `abandoned-by-restart`/`outcome-unknown` audit. It never touches BLE or retries the old write, and the terminal historical record does not block a new explicit session. |
+| CONN-62 | The browser closes or refreshes while the event WebSocket is active | A proven WebSocket disconnect or closed transport finishes that browser stream quietly and changes no device/backend state. Only the exact closed-send exceptions are normalized; an unrelated runtime failure is still logged/test-visible. No device operation is retried. |
+| CONN-63 | One live process/runtime authority blocks an action that the supervisor alone would allow | The composite policy intersects supervisor evidence with active BLE/process ownership, acquisition/runtime state, cleanup, identity pins and the separate physical-command ledger. Active contention is denied; historical network audit is not. The UI does not recreate authority from mode labels or remembered addresses. |
+| CONN-64 | Acquisition data is lost while control is healthy, or control and data are both lost | With healthy exact control, a physical STOP remains available only through the durable physical-command/CAS gates. With control lost, physical STOP is denied; local receiver cleanup remains available, the physical K1 state is labelled unknown and manual device follow-up is shown. A nonexistent acknowledgement action never replaces either executable path. |
+| CONN-65 | Only durable configured/offline topology remains after restart | A diagnostic endpoint probe may use that exact historical target without entering BLE or mutating K1, but it is optional diagnostics and grants no control. Cold UI entry and polling start no work. A mode/same-mode reset performs one local-only CAS, retires the old lineage and exposes clean Step 01 without automatic Scan or device/host I/O. One explicit six-second scan produces candidates. **Выбрать** is local-only and immediately reveals the applicable Step 02 inputs. Only Apply may create a connection intent; there is no background Verify, discovery, reconnect or mutation. |
+| CONN-66 | The one-second connection monitor observes macOS association continuity for a long session | Association identity comes from a bounded compiled or long-lived observer. The monitor does not compile/launch the Swift source twice per poll, cannot hold its shared observation lock for tens of seconds, and revokes freshness while the observer is unavailable instead of delaying the whole control lifecycle. It never invokes Verify, BLE discovery, selection or reconnect and never owns a UI action loader. |
+| CONN-67 | A Quick-to-Quick, Bridge-to-Bridge, or cross-mode attempt ends after dispatch with an unknown result | Record the old attempt as terminal `outcome-unknown`, clear its active selected session, and never replay automatically. A later explicit operator scan, selection and Apply is a distinct intent and may perform its own single reviewed write after safety admission; no historical deadlock and no mandatory preflight. Real-K1 repeated reconnect/mode-switch acceptance remains required. |
+| CONN-68 | STOP is acknowledged, K1 enters SCAN_STOPPING, and Mac Wi-Fi is lost before fresh READY | Complete local receiver/control cleanup and present `standby-unconfirmed`, not a generic global error and not proven standby. Passive BLE Scan remains allowed after cleanup but starts only from an operator action. An explicit scenario reset may retire the old local/audit lineage and expose clean Step 01 without resolving standby or sending a command; provisioning and START stay denied on the old lineage. Exact read-only recovery may classify fresh non-retained READY or same-project SCANNING; no automatic retry or command. |
+| CONN-69 | K1 is hard-powered off during Bridge acquisition, then rebooted while Mission Core remains open | The lost acquisition becomes terminal locally without cache/backend reset; stale control/data cannot revive it. Session recovery remains a separate exact-target surface and passive BLE Scan runs only when requested. A new connection scenario requires explicit reset, then a successor Scan; every admitted result uses **Выбрать**, including the prior UUID. READY records cessation; fresh non-retained identity-bound SCANNING establishes only read-only control proof and exposes one explicit STOP outside connection setup. It never restarts the retired receiver, camera, writer or acquisition. Bridge field acceptance is required; Quick Connect was not exercised by this live incident. |
+| CONN-70 | UI enters a disconnected/configured K1 | UI entry, passive polling, row selection and input run no Verify, BLE discovery, connect or mutation. A mode/same-mode gesture owns one visible local scenario-reset action, then clean Step 01 is visible; it never starts discovery automatically. Search runs exactly once for six seconds per explicit click. Every result has **Выбрать**; selection retains the card and immediately reveals applicable Step 02 inputs. One Apply creates one connection intent with at most one K1 mutation and no hidden Scan/Verify/replay. |
+| CONN-71 | STOP is accepted, but neither READY nor SCAN_STOPPING arrives before the backend operation deadline | Automatically close only host-owned receiver, camera, perception ingress and control resources. Terminalize the operation as `timed_out` and present `standby-unknown`, with `side_effect_status=unknown`, `safe_to_retry=false`; keep the durable physical record unresolved. After successful cleanup allow a separately explicit exact bounded read-only recovery. An explicit scenario reset instead retires the old local lineage and exposes clean Step 01 while preserving the auditable physical outcome. Its successor Scan uses uniform **Выбрать** rows and never enters recovery from the candidate list. Repeated state polls are idempotent and never replay STOP or start recovery; local cleanup failure retains the local fence and retries cleanup only. |
+| CONN-72 | A connected or previously configured Bridge surface is opened | Render the existing plugin section, not a separate wizard or recovery dashboard. Mode, one explicit six-second scan, uniform results, local selection, immediate credentials and one Apply form one predictable path. Backend revision, random intent ID, desired-mode revision, supervisor and ledger CAS remain internal. Only Scan and Apply show truthful action-specific progress. |
+| CONN-73 | Apply for fresh cold Bridge candidate B returns a provisional post-write topology before MQTT identity is known | Record the single write exactly once and keep control unready. Commit identity/control authority only after exact DeviceInfo and durable transport/profile pin success. On mismatch or control bootstrap failure, preserve durable A where required, retain B's network-attempt audit, return `network_applied/control_not_ready`, and never repeat the same intent. Recommended read-only Verify may establish control. Alternatively, current server policy may admit an explicitly new intent; the historical attempt itself grants no authority. |
+| CONN-74 | The operator chooses **Изменить сеть** while neighboring BLE devices may be advertising | Pin the exact authoritative Bridge transport/mode and reveal credentials immediately. Opening and editing perform no I/O. Apply performs no hidden discovery or Verify and crosses at most one reviewed K1 write-dispatch edge. Reject stale-tab, stale candidate, missing exact device and changed-binding requests before device I/O with an explicit stale outcome. A post-dispatch ambiguous result is explicit outcome-unknown and never replayed. |
+| CONN-75 | A safe pre-START holder, active/reconnecting/cleanup-pending acquisition, unresolved durable physical history or stale runtime overlaps a mode/new-device request | The selector, same-mode escape and top-right **Сбросить подключение** utility send one idempotent `reset_scenario` with exact runtime/mode revision; the utility targets canonical Bridge and is never passive `state.read`. The reset queues behind and supersedes old local lifecycle ownership without deadlock, then locally seals receiver/camera/control resources, cancels late recovery generations, invalidates candidates/drafts/credentials and retires the old physical lineage truthfully. It performs zero START/STOP, BLE, device-network, host-network or automatic-Scan I/O. Terminal cleanup failure remains visible and retryable without committing the mode revision. On success the clean Step 01 requires a separate explicit Scan. |
+| CONN-76 | An unresolved physical START/STOP target is unavailable or has been replaced while the operator selects a fresh candidate | Selection remains local and cannot retire authority. Without an explicit committed reset plus its successor Scan, Apply is denied before device I/O. `physical-command.retire-unavailable` retains stable idempotency identity and exact runtime/operation/revision/transport CAS, preserves unknown-outcome audit, performs zero device I/O and starts no Scan. Product UI exposes no checker, confirmation ceremony or reconnect action in Bluetooth results. |
+| CONN-77 | A fresh post-reset scan returns candidates, including the exact actively retired UUID | Search runs once for six seconds. A successful admitted generation settles only the exact active reset marker captured at Scan entry; a Scan started before a later reset, failed/cancelled Scan or a newer pending reset does not. Every connectable row has one enabled **Выбрать**. Selection immediately exposes the local network draft and performs zero I/O. The explicit reset plus exact successor generation may admit one new network Apply to that rediscovered transport, still gated by exact handle capture and live GATT baseline and limited to one reviewed write. Before dispatch the backend may append one request-bound local reopen checkpoint; it preserves retirement/original-outcome audit and grants no START/STOP. A fresh service-owned DeviceInfo + non-retained READY/SCANNING observation settles that checkpoint without a UI Verify or command replay. SCANNING creates only explicit STOP authority and never resurrects reset-owned receiver/camera/acquisition state. Any other post-reset network dispatch consumes the exception. |
+| CONN-78 | One-intent UI contract | A mode, same-mode new-device or top-right **Сбросить подключение** gesture invokes exactly one visible local-only `reset_scenario`; the top-right action changes to **Сбрасываем подключение** while pending and never calls passive refresh instead. While that reset owns `mode`, every reset entry point dispatches no B intent. Its authoritative revision clears the dirty selector and all old click-owned attempt presentation. Row selection and every SSID/password keystroke still invoke no controller I/O. The reset has a stable idempotency identity, sends no device/host command and starts no Scan. One explicit search invokes exactly one six-second scan. One Apply invokes one connect request, no frontend Scan/Verify/reopen and at most one device mutation. Pre-dispatch authority drift is rendered explicitly stale; post-dispatch uncertainty is rendered outcome-unknown and never replayed. `network_applied` plus unready/unknown control spends the old Apply and gates ordinary controls behind an explicit recovery choice. Recommended Verify accepts only the backend server-bound target. Every new Apply has a new idempotency identity, and no new-intent path runs as a hidden frontend or mutating continuation. The already-declared service-owned same-intent read-only bootstrap after the durable ACK is the sole continuation exception; it creates no UI action and cannot mutate or retry. The plugin reuses canonical `Button`, `TextField`, `ActivityIndicator` and `StatusBadge`, with no raw local controls, literal status colors, new shared entities or lifecycle changes. |
+
+## Composite action policy
+
+`connection_supervisor.allowed_actions` covers only host, endpoint, identity,
+control and data evidence. It is deliberately insufficient to authorize a BLE
+or physical mutation. The API therefore publishes
+`missioncore.xgrids-k1-connection-policy/v1`, composed from:
+
+1. the current supervisor revision and exact evidence epochs;
+2. the current explicit network intent and active-operation generation;
+3. the network-attempt audit/idempotency record, which prevents automatic
+ replay inside that attempt but is not a cross-session veto;
+4. the durable physical-command ledger (highest precedence for START/STOP and
+ deliberately unaffected by the simpler network lifecycle);
+5. the process-wide BLE runtime/quarantine state and the stable cross-process
+ lifecycle lease;
+6. current acquisition/runtime/cleanup state;
+7. fresh unselected BLE candidates and, separately, the one admitted active
+ selected session;
+8. the exact `connection_reconfiguration` revision, random intent ID, required
+ transport/mode and minimum fresh discovery generation;
+9. semantic topology and identity-pin store health.
+
+Every action carries an `allowed` bit, reason codes, target source, required
+transport reference and whether a new live GATT validation is mandatory. The
+browser may add form-local prerequisites, such as an entered password or an
+exact fresh local selection. It may not turn a denied/missing backend
+decision into an enabled action. There is no product-level
+`recover-current-device-network` prerequisite. Latest-generation candidate rows
+and an active selected session do not disappear because wall-clock time elapsed;
+generation/runtime/GATT fences and the connection lifecycle clear them at their
+respective authority boundaries.
+
+`scan-ble` is evaluated separately from every mutation. Once local/native
+cleanup and the BLE discovery lease are clear, physical unknown/active does not
+deny passive Scan. The same physical fact must deny
+`provision-fresh-device` and acquisition START on that lineage, but cannot deny
+the local-only scenario-reset escape.
+Every recovery observation and any recovery STOP are additionally pinned to
+the physical record's exact `transport_ref`; a browser-selected or newly
+discovered foreign transport cannot substitute for it or change topology.
+Recovery is a separately explicit action. Normal row selection remains a local
+draft and never admits observation or mutation.
+
+`physical_command.operator_retirement` is a separate backend projection. Its
+`allowed` decision is true only for one exact unresolved post-dispatch target
+after acquisition, runtime, control, BLE/native cleanup and cross-process
+lifecycle owners are safe. The browser may invoke
+`physical-command.retire-unavailable` only from that projection and must echo
+the exact backend runtime, operation, revision and transport checkpoint. This
+local durable mutation neither inherits `scan-ble` permission nor invokes it.
+Success clears only current authority for the retired target and creates an
+active exact-transport deny at every adopting or mutating entrypoint, including
+provisioning, Verify/adoption, control, calibration, physical commands and
+network writes. It applies the retired durable identity fence once DeviceInfo
+makes that identity observable. The retirement record and unknown original
+outcome remain permanent audit.
+
+`physical_command.operator_reconciliation_reopen` is a separate backend
+projection for exact recovery of a previously established session. The browser
+may invoke `physical-command.reopen-retired-reconciliation` only from that
+session-recovery projection, never from a cold Bluetooth result row, and must
+echo the exact backend runtime, ledger revision, active retirement ID,
+transport and discovery generation, plus a stable reopening ID and explicit
+operator confirmation. The local durable transition appends a
+reopen audit, restores only the retired record's original unresolved stage and
+removes only that retirement's active deny. It performs zero BLE, Wi-Fi, MQTT,
+DeviceConfig, ModelingStatus, workspace, project, START or STOP I/O and starts
+no Scan. The separately explicit recovery intent may then perform one exact
+read-only Verify under its original runtime/action/candidate fences; it grants
+no provisioning or command authority until fresh READY or exact same-project
+SCANNING proof reconciles the record. It never continues into Apply.
+Explicit passive Scan/GATT metadata/MQTT capture outside this transition remains
+a non-authoritative diagnostic surface and cannot restore topology/control. The
+policy does not claim pre-provision identity detection across a changed
+CoreBluetooth UUID.
+
+Physical device commands are fail-closed when the policy is absent, malformed
+or denied. Purely local risk-reduction actions are different: stopping or
+aborting a local receiver/replay remains possible even when the K1 physical
+state is unknown. Such cleanup never claims that K1 received STOP, and the UI
+must present the required manual device follow-up.
+
+## Adaptive UI contract
+
+The UI is a projection of backend evidence, not a second connection state
+machine.
+
+- Layout responds to the plugin container width, not only the viewport width.
+- At every width, connection/topology, project/intake, status, metrics, and
+ error surfaces either fit side by side or stack in document order. They never
+ overlap, escape their panel, rely on horizontal clipping, or cover primary
+ actions.
+- Wide composition may use two columns. Narrow composition stacks the network
+ connection block before project/acquisition controls; fields and actions use
+ the full available width.
+- Requested topology, semantically observed K1 topology, current Mac
+ association, endpoint reachability, DeviceInfo/control state, and data state
+ are visually distinct. A single green lamp cannot stand in for all planes.
+- `last_known` and stale observations are labelled as
+ historical/non-authoritative and are never rendered as a live selectable or
+ connected device.
+- The mode selector, same-mode **Подключить новый K1** action and top utility
+ remain available through every non-reset lifecycle owner and send one explicit
+ local-only scenario-reset CAS. The first reset may supersede another pending
+ local action. While that bounded reset owns `mode`, all reset entry points
+ report cleanup and dispatch no B intent. On success the authoritative reset
+ revision clears old click-owned presentation and a dirty selector, then shows
+ clean Step 01 plus truthful warning when the previous K1 may still scan;
+ search never starts automatically. Provisioning and START retain separate
+ backend gates, and Apply remains the normal topology/device-mutation boundary.
+ The reset marker suppresses only the retired scenario: a later correlated
+ failed or outcome-unknown attempt must render immediately and survive reload
+ without reviving the old reconnect prompt.
+- The only model-bearing plugin-section heading is **Подключение XGRIDS LixelKity K1**.
+ Below it, copy uses the neutral step names **Подключение** and **Сеть**. It
+ does not label devices as saved, original, previous or retired,
+ and it does not surface physical-ledger terminology.
+- Progressive disclosure is intent-oriented. A cold surface shows mode and
+ Step 01 **Подключение** with its explicit Scan action. A completed explicit
+ scan shows candidates. Selecting one immediately retains its card and reveals
+ Step 02 inputs (or the Quick Connect summary) without an operation.
+- Step 01 search begins only when pressed, runs exactly six seconds, and shows
+ an `ActivityIndicator` plus a visible seconds countdown. After completion,
+ every connectable result row has one enabled **Выбрать** action and the base
+ anatomy, including an exact UUID from an earlier scenario. Selection has no
+ loader and invokes no controller method. A transport without safe current
+ draft admission is explicit unavailable evidence, not a disabled primary
+ affordance or a reconnect CTA.
+- Selection retains the candidate card and immediately exposes applicable
+ fields. Form input invokes no I/O. Candidate/runtime/intent drift produces an
+ explicit stale state and an explicit search action; it never triggers a scan
+ or clears the result as a hidden continuation.
+- **Изменить сеть** retains one exact device card and reveals credentials
+ without I/O. **Применить** names the one network operation, performs no hidden
+ exact-UUID refresh/Verify and crosses at most one device-write boundary.
+- Apply accepts the exact REST `network_applied` snapshot immediately for
+ `control_not_ready` and `unknown`. It does not await WebSocket/poll proof or
+ full connection-ready. It spends the old Apply and credentials. While the
+ exact service child is accepted/running, one passive settling indicator is
+ shown and no recovery action is enabled; terminal unready/unknown state then
+ presents explicit recovery choices. Verify is recommended and server-bound,
+ not mandatory. A new server-policy-admitted intent uses Bridge
+ `prepare-select-device`, Quick/Direct explicit `scan-ble`, or an explicit
+ scenario reset; every route still requires a later fresh scan and a new
+ idempotency Apply, with no hidden frontend or mutating continuation. The
+ declared service-owned same-intent read-only bootstrap is the only post-ACK
+ continuation and creates no UI action.
+- After that fast ACK, the service may finish a supervised read-only control
+ bootstrap for the same intent. It performs no BLE/host mutation or retry and
+ creates no frontend Scan/Verify/new-Apply action or blocking Apply loader. Its
+ exact accepted/running state may own one passive settling indicator only.
+- Selecting a fresh Bridge or Direct device reveals SSID/password immediately.
+ Quick Connect reveals no credential fields. A stale global error from device
+ A cannot own device B's form, and a backend runtime/fence change invalidates
+ credentials and renders a clear stale outcome rather than scanning or
+ replaying automatically.
+- The plugin surface uses shared `Button`, `TextField`, `ActivityIndicator` and
+ `StatusBadge`. Raw local HTML controls and literal local status colors are not
+ accepted; no new shared entities are introduced.
+- During an actively executing `prepared`, `dispatching`, or `observing`
+ operation, controls that could create a competing mutation are replaced by a
+ truthful action-specific progress row. When that attempt terminates, its audit
+ cannot keep the next explicit connect unavailable. An unresolved/active
+ physical record may hide mutation controls, but it does not deny an explicit
+ passive BLE Scan after local cleanup. Once that explicit scan completes, Step
+ 01 shows its complete result set, including unrelated BLE devices, as passive
+ discovery evidence. Ordinary connectable rows keep one enabled **Выбрать**
+ action when current backend policy admits a fresh draft; an exact prior UUID
+ is not special in this list. Another row cannot replace the durable target or
+ reveal Apply while admission remains denied. A
+ configured-but-unverified topology or physical recovery target starts no
+ operation from UI entry or polling. Only explicit search
+ and Apply create I/O.
+ Physical recovery stays pinned to the durable `transport_ref`;
+ each requested observation generation publishes exactly one DeviceInfo
+ request and passively waits for fresh non-retained status.
+- Backend events and bounded state polling converge the presentation after
+ disconnect, cleanup, read-only recovery success/failure, and power-cycle
+ recovery. Polling is passive presentation convergence: it starts no device
+ action, shows no recovery spinner by itself and cannot extend an ended action.
+ Clearing browser cache/local storage, restarting the backend, or pressing a
+ generic reset is never a required recovery procedure. Optional state reads
+ and endpoint diagnostics are read-only and cannot manufacture authority.
+- A human-readable error states which product fact failed (discovery, device
+ topology, Mac association, endpoint, identity/control, data, or active
+ lifecycle contention). A released local acquisition after acknowledged STOP
+ plus Wi-Fi loss is rendered as `standby-unconfirmed` with plain recovery
+ guidance, not as an unexplained global `Ошибка`. A STOP acceptance whose
+ READY/SCAN_STOPPING deadline expires is rendered as terminal
+ `standby-unknown`; after local cleanup it offers read-only recovery, while all
+ mutations remain fenced. Internal stack traces and reason taxonomies remain
+ in engineering logs, not in the primary product surface.
+- Every idle/error state exposes only relevant actions derived from backend
+ `allowed_actions`. Historical recovery never runs behind **Выбрать** or
+ **Применить**; UI heuristics do not manufacture authority, loop, or
+ reinterpret legacy convenience fields.
+- Telemetry and acquisition metrics disappear or become explicitly unavailable
+ when their data source is stale. The UI does not preserve old numbers as live
+ measurements.
+- Browser refresh never invokes provisioning and starts a fresh operator
+ session with no restored live selection. Resizing and panel expansion do not
+ change the current session or topology.
+
+Acceptance widths are container widths `1948`, `1680`, `1481`, `1281`, `1280`,
+`1024`, `761`, `760`, and `390` px. At each width, acceptance requires:
+
+1. no overlap or clipped content;
+2. readable requested/observed/authoritative distinctions;
+3. reachable primary action and error recovery action;
+4. the latest-generation BLE rows remain stable across wall-clock age, are not
+ presented as mutation authority without exact-handle/live-GATT proof, and no
+ admitted active session is cleared merely because wall-clock time elapsed;
+5. no green connected/control state without the exact backend binding;
+6. no stale telemetry presented as current;
+7. no action fired by layout change, refresh, or hydration.
+
+## Operational acceptance rule
+
+A scenario is complete only when its test evidence covers all applicable
+layers:
+
+1. network-attempt audit transition and active cross-process exclusion;
+2. supervisor evidence planes and host epoch handling;
+3. exact DeviceInfo/control binding and independent data state;
+4. API snapshot and `allowed_actions`;
+5. adaptive product presentation at the boundary widths;
+6. for real K1 acceptance, one explicitly operated hardware run with redacted
+ logs and no automatic mutation retry.
+
+The 2026-08-09 live incidents exercised Bridge only: STOP acknowledgement plus
+Mac Wi-Fi loss before READY, and K1 hard power loss/reboot during acquisition.
+They are field evidence for `CONN-68`/`CONN-69`, not Quick Connect acceptance.
+Quick Connect recovery remains unaccepted until it is exercised separately.
+
+Synthetic/unit acceptance can prove the state machine and regressions. It does
+not by itself claim that a real K1, router, CoreBluetooth stack, or macOS sleep
+transition has been physically validated.
diff --git a/docs/adr/0003-device-plugin-ui-and-runtime-boundary.md b/docs/adr/0003-device-plugin-ui-and-runtime-boundary.md
index 857cfce..b1135b0 100644
--- a/docs/adr/0003-device-plugin-ui-and-runtime-boundary.md
+++ b/docs/adr/0003-device-plugin-ui-and-runtime-boundary.md
@@ -136,7 +136,7 @@ The current XGRIDS contribution maps its proven internal workflow into those
platform states without changing the wire protocol:
```text
-confirm power -> scan BLE -> select candidate -> enter Wi-Fi
+scan BLE -> select candidate -> enter Wi-Fi
-> provision once -> receive LAN address -> start source
-> wait for first point frame -> streaming
```
diff --git a/docs/adr/0013-k1-local-connection-matrix.md b/docs/adr/0013-k1-local-connection-matrix.md
index 3269e93..d8f84b7 100644
--- a/docs/adr/0013-k1-local-connection-matrix.md
+++ b/docs/adr/0013-k1-local-connection-matrix.md
@@ -1,6 +1,6 @@
# ADR 0013: explicit K1 local connection matrix
-- Status: amended 2026-07-20; Bridge is the product path, Quick Connect retained as a prepared-host laboratory path
+- Status: amended 2026-08-08; Bridge is the product path, Quick Connect retained as a prepared-host laboratory path
- Date: 2026-07-19
- Extends: ADR 0004, ADR 0005 and ADR 0012
@@ -47,6 +47,23 @@ for the previous session. An active acquisition is never retargeted in place.
The later correlated MQTT `DeviceInfo` response supplies model, firmware,
serial and vendor identity; IP equality alone cannot identify a K1.
+The 2026-08-08 physical Bridge trace corrected the earlier field model: the
+first `7f02` text slot is `WIFI_AP` in AP state but contains the joined network
+name in FW 3.0.2 station state. Mission Core therefore normalizes that station
+response to `WIFI_CLIENT` internally and admits Bridge/Direct only when the raw
+post-write name exactly matches the current explicit request plus a valid
+non-AP private address. The raw name is not persisted in the secret-free
+network audit or published through API state.
+
+The limitation still applies when recording an interrupted attempt that has no
+exact post-write network-name observation. A changed private DHCP address alone
+cannot identify the selected network. An already AP-ready baseline likewise
+cannot prove the outcome of an interrupted Quick-to-Quick attempt. Mission Core
+therefore records that attempt as terminal `outcome-unknown` and never replays it automatically. The
+historical uncertainty is not a permanent barrier: after the old active
+operation and cleanup have ended, a later explicit operator scan, selection,
+and connect is a distinct session with its own one reviewed write.
+
Product decision on 2026-07-20: Bridge/direct-LAN is the continuing route.
Quick Connect remains visible and executable on an already prepared host, but
is not a deployment dependency or portability claim.
@@ -86,12 +103,65 @@ and the following cold Swift/CoreWLAN process missed the beacon. The corrected
implementation holds the selected `BleakClient` open through bounded native
SSID discovery and the single association call.
-BLE discovery and the selected device action form one host session. A physical
-run proved that immediately rediscovering the same K1 by its CoreBluetooth UUID
-can fail even though the preceding scan exposed it. Mission Core retains the
-non-serializable `BLEDevice` handle process-locally and uses that exact handle
-for the next selected network action; it never exposes the handle through API
-state or treats the macOS UUID as durable device identity.
+One explicit six-second BLE discovery and the later Apply action form one
+operator intent without a second discovery. A physical run proved that
+immediately rediscovering the same K1 by its CoreBluetooth UUID can fail even
+though the preceding scan exposed it. Mission Core retains the non-serializable
+`BLEDevice` handle process-locally and uses that exact handle for Apply; it never
+exposes the handle through API state or treats the macOS UUID as durable device
+identity. UI row selection itself performs no GATT or backend I/O.
+
+The operator-visible candidate list, local selected draft and admitted active
+session are separate contracts. Every explicit scan replaces the candidate
+set. Selection only binds a local form to one result from the latest admitted
+generation. Wall-clock age does not remove that generation while the operator
+completes the form. Apply admits only its exact retained handle and live GATT
+validation may create the active session; a remembered UUID is never mutation
+authority. Proven disconnect, explicit stop, app/backend restart, another
+explicit Scan, or a committed mode transition revokes the applicable candidate
+or live session. Rediscovery never auto-connects.
+
+Quick Connect to Bridge is an explicit topology transition, not another scan
+heuristic. Selecting Bridge — or choosing another K1 while Bridge is already
+selected — sends one idempotent local `reset_scenario` CAS. It seals retained
+receiver/camera/control ownership, invalidates candidates and credentials and
+retires old physical lineage truthfully, while sending no device command, BLE,
+host-network write or automatic Scan. The next explicit Scan starts the clean
+discovery flow, while Apply remains the topology and device-mutation boundary.
+The operator selects one discovered K1, sees the Bridge credentials immediately
+and submits once. The new GATT
+session reads internal baseline `7f02` and emits exactly one reviewed 99-byte
+station write. A connect failure ends that attempt. An ambiguous post-write
+failure is terminal `outcome-unknown` audit, not a permanent cross-session
+fence. There is no automatic BLE or network-write retry.
+
+Likewise, an exact REST `network_applied` result with unready/unknown control
+spends that Apply and its credentials without making the read-model attempt a
+permanent topology lock. Recommended Verify is pinned to the backend
+current/configured target. A separately explicit new intent still requires
+current server policy: Bridge prepares `select-device` before a later fresh
+scan; Quick and Direct run an admitted fresh scan, select only its latest row
+and create a new idempotency Apply; a mode or same-mode new-device transition
+uses one idempotent local-only `reset_scenario` before that fresh scan. None of
+these new-intent UI paths reuses the old
+intent or runs as a hidden frontend/mutating continuation. The service-owned
+same-intent read-only bootstrap declared below is the sole post-ACK exception.
+
+The Apply REST call returns as soon as the exact durable
+`network_applied` proof is available. The service may continue the same
+intent's supervised control bootstrap read-only after that ACK. This performs
+no BLE/host mutation or retry and creates no frontend Verify, Scan, Apply or
+blocking Apply loader. While the exact child is accepted/running, the UI may
+show only a passive **Сеть настроена · подтверждаем управление** indicator and
+must keep every recovery action disabled. Later control state arrives only as
+backend presentation convergence; terminal unready/unknown state then exposes
+the explicit server-policy recovery choices.
+
+Bridge and Quick Connect were physically accepted as separate paths before
+this amendment. The combined Quick Connect to Bridge transition has automated
+contract coverage but remains a distinct physical acceptance gate; it must not
+be reported as field-accepted until one redacted live run records both sides of
+the transition.
The corrected host boundary derives a non-secret, device-scoped profile ID from
the selected SSID. The reviewed client contains per-device `WiFiAP_SSID` and
@@ -110,13 +180,40 @@ that opaque source before any BLE write. A missing provider fails closed. The
browser, API, argv, logs, manifests and evidence never receive the secret; the
importer's short-lived mutable buffer is zeroized after the Keychain handoff.
+The 2026-08-06 field regression established that process identity is part of
+this prepared-host contract. Runtime `swiftc` compilation produced an ad-hoc
+helper with an unstable designated identity. macOS then requested Keychain
+authorization repeatedly and the same process context failed to expose the
+exact K1 SSID through CoreWLAN even after K1 had acknowledged AP-ready. That
+runtime-compiled route is rejected. The laboratory adapter uses the previously
+physically accepted Apple-signed interpreter path,
+`/usr/bin/xcrun swift `, and validates the source path before
+launch. A portable product implementation still requires a packaged,
+precompiled and properly signed helper with a stable bundle identifier,
+designated requirement, Location/CoreWLAN authorization and Keychain ACL; the
+current prepared-host path does not claim that packaging work is complete.
+
+Before any BLE write, the helper's preflight is non-interactive. It first checks
+Keychain item existence through metadata, then validates the selected profile's
+SSID and `exact-firmware-profile` provenance inside the helper without returning
+secret data. Provider material is also read with interaction disabled if a
+missing device profile must be materialized. The association phase accepts only
+that already materialized exact profile. It never
+falls back to the system Wi-Fi Keychain, rewrites a profile opportunistically,
+or opens a password/authorization dialog after K1 has changed network state.
+An unavailable or unauthorized profile therefore fails closed with a precise
+reason code and no automatic device retry.
+
The host-network boundary, rather than the XGRIDS frontend, owns platform
association. Browsers expose no Wi-Fi join API, and Apple's iOS
`NEHotspotConfiguration` consent flow is unavailable on macOS. The current
implementation therefore uses a short-lived Swift/CoreWLAN + macOS Keychain
helper; Windows Credential Manager and Linux Secret Service adapters remain
separate platform work. The helper performs repeated read-only exact-SSID scans
-inside one 15-second discovery window and at most one association. It never
+inside one 30-second discovery window and at most one association. The larger
+window covers the physically observed 18.142-second beacon-discovery case;
+AP-ready confirms K1 state but does not prove that macOS has already observed
+the RF beacon. It never
repeats the BLE command, guesses a password or treats `7f01` as a credential-read
command. The credential-bearing 99-byte station-provisioning frame and fixed
100-byte AP-enable frame are separate reviewed payloads.
@@ -128,12 +225,13 @@ The owner also observed no explicit device/account pairing in the normal
LixelGo onboarding flow; this is consistent with a firmware-defined AP secret,
but does not establish account-wide authorization for arbitrary scanners.
-Connection verification refreshes the session-scoped lease with the same
-read-only BLE status operation. It does not write a characteristic, re-provision
+Apply may read BLE baseline internally while establishing a new selected
+session. Selection never does so, and the normal flow has no mandatory or hidden
+"verify without write" recovery step. The baseline read does not re-provision
Wi-Fi, scan the subnet, change a host route, or touch VPN configuration. The
-later canonical MQTT session supplies the real data-plane connection and live
-`DeviceInfo` identity check. A BLE lease observation is therefore not by itself
-a claim that MQTT/RTSP is reachable.
+later canonical MQTT
+session supplies the real data-plane connection and live `DeviceInfo` identity
+check; BLE status alone is not a claim that MQTT/RTSP is reachable.
## Consequences
@@ -148,6 +246,10 @@ a claim that MQTT/RTSP is reachable.
therefore not scheduled for this Quick Connect path.
- Direct Connect requires an already-running hotspot and a controller route;
Mission Core does not create or manage that hotspot.
+- Discovery never auto-connects devices. Mode, selection and input are local
+ only. App restart, disconnect, explicit stop and mode transition require a
+ fresh explicit scan-select-Apply session. Apply performs no hidden rescan or
+ Verify and may cross at most one device-mutation boundary.
- The application-control, START/STOP and raw-first acquisition protocol is
unchanged after a target address is admitted.
- Direct Connect remains explicitly pending one owner-operated physical
diff --git a/docs/adr/0014-k1-macos-association-observer.md b/docs/adr/0014-k1-macos-association-observer.md
new file mode 100644
index 0000000..d5d705d
--- /dev/null
+++ b/docs/adr/0014-k1-macos-association-observer.md
@@ -0,0 +1,177 @@
+# ADR 0014: long-lived macOS host-association observer
+
+Status: planned production boundary; software contract may be developed behind
+a disabled feature flag.
+
+Related acceptance item: `CONN-66` in
+[`../20_K1_CONNECTION_SUPERVISION_CANON.md`](../20_K1_CONNECTION_SUPERVISION_CANON.md).
+
+## Context
+
+Mission Core must distinguish a K1 that is configured for a network from a Mac
+that is currently attached to the same network. Route, TCP, DeviceInfo,
+control and data evidence are bound to a host-path epoch; a Wi-Fi switch,
+sleep/wake cycle or observer restart must invalidate that epoch before any late
+TCP/MQTT result can restore command authority.
+
+The current laboratory implementation is fail-closed but not a production
+observer. One normal connection-monitor poll samples the host path before and
+after its TCP probe. Each sample synchronously invokes:
+
+```text
+/usr/bin/xcrun swift plugins/xgrids-k1/macos/associate_wifi.swift
+```
+
+under one process-local lock with a 30-second timeout. At the one-second
+monitor interval this can launch two Swift processes per second. A failed
+cycle can occupy the lock for roughly sixty seconds, and cancellation of the
+Python `asyncio.to_thread()` waiter does not terminate the native process or
+thread. Physical-command validation shares this observation path. Shorter
+timeouts, cached shell output or automatic fallback would hide rather than
+remove the lifecycle defect.
+
+## Decision
+
+Production host-association evidence will come from one signed, long-lived,
+read-only agent in the user's macOS login session.
+
+- The agent owns one `CWWiFiClient` for its process lifetime.
+- It observes CoreWLAN link/association/power events and macOS sleep/wake.
+- It never scans BLE, changes Wi-Fi, reads K1 credentials, reconnects MQTT or
+ sends START/STOP.
+- It is packaged in a minimal container app and registered with `SMAppService`;
+ it is not a `LaunchDaemon` and is not launched through `xcrun` at runtime.
+- The required Wi-Fi event entitlement and Location authorization are checked
+ before K1 network mutation is offered. Missing authorization produces
+ explicit unavailable evidence, not a crash loop or guessed association.
+- The existing Wi-Fi mutator remains a separate component under the exclusive
+ network process lease. Observer authority and mutation authority are never
+ combined.
+
+The backend communicates with the observer through bounded local IPC. Each
+backend session supplies a random HMAC key. SSID and BSSID remain inside the
+agent; only an opaque continuity token is returned and it cannot be correlated
+between backend processes. The token material is interface plus BSSID; SSID is
+used only to report evidence quality. This keeps one AP identity stable when
+macOS alternates between `ssid+bssid` and `bssid-only` disclosure.
+
+## Observer contract
+
+```text
+schema_version: missioncore.macos-host-association/v2
+agent_instance_id: random 128-bit process instance
+sequence: uint64
+association_epoch: uint64
+interface_name: string | null
+wifi_interface: true | false | null
+state: associated | not-associated | inactive | not-wifi | unavailable
+evidence_quality: ssid+bssid | bssid-only | not-wifi | unavailable
+continuity_token: 64 lowercase hex | null
+reason_code: string | null
+observed_monotonic_ns: uint64
+sample_age_ms: uint32
+cause: initial | link-change | association-change | power-change |
+ permission-change | will-sleep | did-wake | poll-correction |
+ observer-restart
+```
+
+`sequence` changes for every event or heartbeat. `association_epoch` changes
+when interface, power, state, SSID or BSSID changes. Sleep and wake each create
+a barrier even if the visible network looks unchanged afterward. A new agent
+instance, IPC reconnect, sequence rollback/gap, malformed frame or timeout is
+also a discontinuity.
+
+The backend adds its own `observer_session_epoch`; the effective host-route
+fingerprint includes the agent instance, observer session, association epoch
+and opaque token. A response from an old session or sequence is discarded.
+Unknown schema/state or incomplete evidence is `unavailable` and immediately
+revokes host authority.
+
+## Timing and failure semantics
+
+- Heartbeat: 1 second.
+- Maximum cached-snapshot age: 750 ms.
+- Snapshot RPC deadline: 250 ms.
+- Initial handshake deadline: 2 seconds.
+- Two missed heartbeats or one invalid IPC frame revoke authority immediately.
+- Reconnect backoff: 250 ms, 500 ms, 1 s, 2 s, then at most 5 s.
+- There is no automatic fallback to the Swift source runner.
+- Agent loss affects only read-only host evidence. It never triggers a K1
+ network write, MQTT reconnect or physical command.
+- A discontinuity first marks the supervisor host path unavailable and rotates
+ its epoch. Recovery then requires fresh route, TCP and DeviceInfo/control
+ evidence in that order.
+
+## Delivery phases
+
+Phase A is safe without signing or a physical K1:
+
+1. Define the Python observer protocol and validate the v2 schema.
+2. Add a fake/in-memory transport and backend session/sequence validator.
+3. Implement immediate epoch invalidation and bounded cached lookup.
+4. Inject the observer into the monitor behind a disabled feature flag.
+5. Implement the Swift reducer and local transport as a testable Swift package.
+6. Test sleep/wake, timeout, event gaps, delayed replies, crash/restart and
+ manual network changes.
+7. Expose secret-free observer health and next action to the UI.
+8. Prove 10,000 samples launch no child process and cause no lock starvation.
+
+Phase B requires the actual Mac signing and permission environment:
+
+1. Package and register the user-session agent.
+2. Obtain the Wi-Fi events entitlement and complete Location onboarding.
+3. Run the observer in shadow mode beside the current fail-closed probe.
+4. Cut over only after the physical fault matrix and an eight-hour soak show no
+ unexplained divergence.
+
+## Acceptance gate
+
+- No `xcrun`, `swift` or `swiftc` occurs on the observer path.
+- One agent and one CoreWLAN client serve one login session.
+- Snapshot p99 is below 50 ms, hard deadline 250 ms, monitor-cycle p99 below
+ 1.5 seconds.
+- No mutex is held across native or IPC calls.
+- Sleep, wake, agent restart, sequence gap and timeout always invalidate the
+ effective host epoch.
+- Late TCP/DeviceInfo evidence from an old epoch is rejected.
+- SSID, BSSID and credentials never enter IPC logs, API state or artifacts.
+- Quick-to-Bridge, Bridge-to-Quick, manual Wi-Fi switch, Wi-Fi off/on,
+ router loss/return with the same SSID/IP, backend restart and Location denial
+ all revoke control authority within two seconds and recover only through
+ fresh route, TCP and DeviceInfo evidence.
+
+Until this gate passes, the current association probe remains explicitly a
+laboratory implementation and `CONN-66` remains open.
+
+## Laboratory containment while Location evidence is hidden
+
+The source-runner helper can return `association-identity-unavailable` on a
+connected Mac when macOS privacy rules hide SSID and BSSID from the CLI child
+process. Rotating a random fallback token on every one-second poll made a
+stable route and a successful TCP probe mutually impossible: every following
+sample revoked the preceding endpoint result as a fictitious network switch.
+
+Until the signed observer above replaces the source runner, the laboratory
+probe uses one random, process-scoped token for the same interface and
+unavailable-evidence scope. This is not promoted to association evidence:
+
+- the public evidence quality remains `unavailable`;
+- interface, source address, kernel route, availability, a proven different
+ BSSID and process restart remain epoch barriers;
+- endpoint reachability alone remains `configured-unverified`;
+- only fresh exact DeviceInfo/control evidence can grant control authority;
+- `CONN-66`, sleep/wake and same-subnet network-switch acceptance remain open.
+
+For an already reachable lease whose exact DeviceInfo identity and control
+session remain healthy, a temporary helper timeout or privacy-limited
+association sample may retain the preceding proven association fingerprint
+only while the kernel route fingerprint, interface, source, intent and target
+are unchanged. That retained sample still performs TCP contact and a second
+kernel-route check, refreshing only route/TCP observation TTLs. Endpoint loss,
+control loss, control-proof expiry, target/intent change, a proven association
+identity change or any raw route change revokes immediately. A
+`configured-unverified` path does not receive this bridge and remains bounded
+by the existing technical-failure debounce and transport TTL.
+
+This containment removes the false per-poll epoch churn observed on the field
+Mac without claiming that the planned production observer has been delivered.
diff --git a/docs/adr/0015-k1-physical-state-recovery.md b/docs/adr/0015-k1-physical-state-recovery.md
new file mode 100644
index 0000000..b2c7da9
--- /dev/null
+++ b/docs/adr/0015-k1-physical-state-recovery.md
@@ -0,0 +1,309 @@
+# ADR 0015: explicit K1 recovery beside the one-intent connection flow
+
+Status: accepted product, recovery and presentation contract; executable
+coverage and remaining hardware acceptance are tracked in
+`docs/k1-connection-acceptance.manifest.json`.
+
+Related acceptance items: `CONN-16` through `CONN-19`, `CONN-28`, `CONN-29`,
+`CONN-65`, and `CONN-68` through `CONN-78` in
+[`../20_K1_CONNECTION_SUPERVISION_CANON.md`](../20_K1_CONNECTION_SUPERVISION_CANON.md).
+
+## Problem
+
+Loss of K1 power, the router, Mac Wi-Fi, MQTT control or the backend does not
+prove whether K1 is physically scanning. Retained points, an open TCP port and a
+historical START are insufficient. Replaying START or STOP after an ambiguous
+dispatch boundary can create a second physical edge.
+
+The durable physical-command ledger, exact read-only classification and
+fail-closed supervisor must remain. They must not make ordinary connection slow
+or surprising. In particular, selecting a device must not secretly connect,
+Verify, retire/reopen history or delay network credentials.
+
+## Decision
+
+### Existing product surface
+
+K1 connection stays in the existing device plugin section headed
+**Подключение XGRIDS LixelKity K1**. The surrounding job, entity and lifecycle
+models do not change. This is novelty A: an improvement to an existing product
+surface. A separate wizard, modal flow and mandatory preflight/recovery surface
+are rejected.
+
+The section reuses canonical shared `Button`, `TextField`, `ActivityIndicator`
+and `StatusBadge`. It creates no shared entity and uses no raw local HTML
+controls or literal local status colors.
+
+### One-intent normal flow
+
+The normal flow is:
+
+1. choose Bridge, Direct Connect or Quick Connect locally;
+2. press the explicit Bluetooth search action;
+3. wait for exactly one six-second discovery;
+4. press **Выбрать** on one result;
+5. enter Bridge/Direct credentials immediately, or review the Quick Connect
+ summary;
+6. press **Применить** once.
+
+Opening the section, changing mode, selecting a row and every
+SSID/password keystroke perform zero browser-controller, device or host I/O.
+They create no backend operation and show no operation loader. An admitted fresh
+selection retains the selected card and exposes applicable inputs immediately.
+A candidate without current draft authority is omitted or presented only as
+non-actionable evidence; it never receives a misleading disabled primary.
+
+Each explicit search owns exactly one bounded six-second discovery. It performs
+no connect, Verify, selection or mutation. Results are never auto-selected.
+
+One Apply owns the normal connection intent. It may commit the local desired-mode
+draft under backend CAS and may cross at most one reviewed K1 mutation boundary.
+Its frontend handler performs no hidden Scan, Verify, reconnect, retirement,
+reopen, candidate substitution or retry. Quick, Bridge and Direct use the same single primary
+**Применить** action; credentials are required only for Bridge and Direct.
+
+Ordinary Bridge Apply never opts into changing the controlling Mac's Wi-Fi
+association. Host switching is a separate future consequential operator action,
+not an Apply substep. K1 provisioning can therefore succeed as
+`network_applied` while control is `control_not_ready`. That result must not
+repeat that intent's BLE write. Recommended separately explicit read-only
+Verify/recovery may establish route, endpoint and DeviceInfo/control evidence
+for the applied topology; a new intent remains separately policy-gated.
+
+The exact REST response owns completion of the Apply mutation. A snapshot with
+`connection_attempt.phase=network_applied` is accepted immediately when
+`control_state` is `control_not_ready` or `unknown`; the controller does not
+wait for WebSocket/poll convergence or call the full connection-ready
+requirement. The service may continue supervised same-intent control bootstrap
+after this fast durable ACK, but only read-only: no BLE/host mutation, mutation
+retry, new UI action or second Apply. This is not a hidden frontend Scan or
+Verify. Exact connection-ready remains mandatory before control or physical
+START. This separation spends the old intent before a delayed state channel
+could invite its duplicate replay. `connection_attempt` is a read model, not
+permanent lifecycle authority; current server policy may admit a separately
+explicit new intent.
+
+While the exact service-owned bootstrap child is `accepted` or `running` and
+projects `safe_next_action=wait-for-current-attempt`, the UI shows only one
+passive **Сеть настроена · подтверждаем управление** indicator. It enables no
+Verify, mode change, Scan, row or Apply action. Terminal unready/unknown child
+state then exposes the separately explicit policy-gated recovery choices.
+
+`network_applied` plus unready or unknown control spends the old Apply and gates
+ordinary mode change, Scan, row selection and Apply. It first waits passively
+for an exact active service child; after terminal settlement it presents an
+explicit recovery choice, regardless of browser-local mode. It never authorizes
+automatic or same-intent replay. Recommended Verify is pinned to the backend
+`serverBound` current/configured transport and mode; it never falls back to a
+selected browser row and is not a prerequisite for every new intent.
+
+Current server policy may admit a distinct, explicit new-intent path. Bridge
+uses `prepare-select-device`, a local-only CAS with zero device/host I/O; only
+after its success may the operator initiate a fresh six-second Scan. Quick and
+Direct use explicit policy-gated `scan-ble`, then the latest fresh row and a new
+idempotency Apply. A mode change requires backend `mode_selection` authority and
+then a fresh explicit Scan. No recovery choice performs hidden Scan, selection,
+Verify, provisioning or continuation of the old Apply, and the browser never
+manufactures authority.
+
+### Freshness and outcome semantics
+
+Apply is admitted only for the exact selected transport, completed discovery
+generation, backend runtime, desired-mode revision, reconfiguration intent and
+policy snapshot. Authority drift before dispatch is a terminal, zero-device-I/O
+`stale` result. The UI keeps the result understandable, labels it explicitly and
+offers a new explicit six-second search. It never starts that search itself.
+
+A failure before the reviewed mutation boundary is `not-dispatched` or
+`failed`, with zero K1 mutation. A lost response, timeout, power failure or
+process death after dispatch is `outcome-unknown`, with
+`safe_to_retry=false`. The durable network-attempt ledger prevents replay.
+Credentials are never reused automatically. A later operator Apply is a new
+intent and must pass all current gates.
+
+## Physical safety remains separate
+
+Network attempts are disposable; physical START/STOP ambiguity is durable:
+
+- START and STOP never replay automatically;
+- control loss does not prove scanning stopped;
+- local receiver/camera/ingress cleanup is not physical STOP;
+- a wrong K1/transport/profile/project cannot reconcile the record;
+- READY records cessation without rewriting historical command outcome;
+- exact same-project SCANNING may mint one single-use confirmed STOP permit on
+ the still-open exact control binding;
+- accepted STOP without READY or SCAN_STOPPING by the backend deadline closes
+ only host-owned resources, records `timed_out` / `standby-unknown`, preserves
+ the unresolved ledger and keeps every mutation fenced.
+
+The composite supervisor and physical-command ledger can disable Apply before
+device I/O. Their denial does not turn mode, selection or input into recovery.
+
+### Explicit read-only recovery
+
+Recovery is a distinct, explicitly requested exceptional action. It is never a
+continuation of row selection or Apply. The browser supplies neither endpoint,
+substitute transport nor ledger authority. The backend pins the durable record's
+exact transport, identity/profile, operation/revision, acquisition/project,
+topology revision and host epoch.
+
+The non-reconnecting observation is:
+
+```text
+topology-probed
+ -> pre-start-control-opened
+ -> device-info-requested (ordinal 1; exactly one publish)
+ -> device-info-verified
+ -> awaiting-passive-fresh-status
+ -> cessation | active-same-project | foreign-active | inconclusive | failed
+```
+
+It publishes exactly one canonical DeviceInfo request and then accepts only a
+fresh non-retained DeviceStatus from the same socket generation after that
+barrier. It publishes no status solicitation, DeviceConfig, time sync,
+workspace, project, START or STOP; it never scans, reconnects, provisions or
+continues into Apply.
+
+Canonical READY records cessation/standby. Initialized SCANNING may rebind only
+when operation/acquisition, identity/profile, transport, host epoch and project
+all match; it exposes one separate single-use confirmed STOP checkpoint.
+Foreign, stale or inconclusive evidence changes no topology or authority.
+
+### Explicit retirement and reopen
+
+`physical-command.retire-unavailable` is a separately confirmed local durable
+recovery action for one unresolved target that is truly unavailable or replaced.
+Admission requires stable idempotency identity and exact backend runtime,
+operation, ledger revision and transport CAS plus safe lifecycle ownership. It
+preserves the original unknown outcome, activates the exact-transport deny,
+performs zero device/host I/O and starts no discovery.
+
+`physical-command.reopen-retired-reconciliation` is also separately confirmed.
+It requires an exact fresh same-transport candidate, stable `reopening_id`, exact
+runtime/revision/retirement/transport/discovery CAS and safe lifecycle ownership.
+It preserves retirement audit, removes only that retirement's active deny and
+performs zero device/host I/O. The explicit recovery intent may then run one
+exact read-only observation. **Выбрать** never invokes retirement, reopen or
+Verify. The only Apply exception is an internal, request-bound local reopen
+checkpoint for an explicit scenario reset plus its exact successor Scan. It is
+ordered after network PREPARED and before the sole dispatch edge, remains
+invisible in the wizard and grants no command authority. The same applied
+intent may then settle it read-only from fresh DeviceInfo plus non-retained
+READY/SCANNING evidence.
+
+FW 3.0.2 BLE `7f02` contains no stable DeviceInfo identity. Mission Core cannot
+prove during BLE-only discovery that the same physical unit has a new
+CoreBluetooth UUID. This remains an explicit protocol/hardware gap.
+
+### Bounded durable audit rollover
+
+An explicit local scenario reset must not become unavailable merely because
+closed retire/reopen history filled the 64 KiB hot ledger. Before a transition
+would exceed that bound, Mission Core durably publishes the complete previous
+ledger as a private, owner-only, content-addressed archive segment and then
+atomically publishes a compact v4 main record. The main record retains every
+active retirement deny, the newest lost-response retire/reopen checkpoint, and
+all reconciliation/confirmation proof required by the current physical
+operation. Compaction never changes a device outcome and performs no device,
+network or host I/O.
+
+Archive segments form a predecessor hash chain with exact sequence and byte
+accounting. Reload verifies directory and file ownership/mode, rejects symlink
+traversal, bounds total segments and bytes, reparses every embedded ledger and
+fails closed for a missing, replayed, reordered or tampered segment. Operation,
+reconciliation, verification, confirmation, retirement and reopening identities
+remain globally one-use across the hot record and archive. The archive segment
+is fsynced before the main-file replace: a crash may leave only an inert orphan,
+while retry of the same CAS reuses identical bytes and cannot duplicate the
+referenced chain.
+
+Scenario reset asks the ledger to build the exact prospective retirement or
+prepared→not-dispatched plan before closing any local receiver, camera,
+control-session or network ownership. That shared planner applies the same hot
+serialization, compaction, segment, count and total-byte bounds as commit. When
+rollover is required, preflight may idempotently prepublish only the immutable
+content-addressed predecessor; the main revision/CAS and physical disposition
+remain unchanged. This also proves owner/mode, symlink and content-collision
+conditions before teardown.
+
+Archive publication is restart-safe at the hard-link boundary. A process death
+after destination link and directory fsync but before temporary-name unlink may
+leave exactly two private names for one inode. Retry removes only a strictly
+named, owner-only temporary alias whose bytes and inode exactly match the
+expected destination and whose link count is exactly two, fsyncs that cleanup,
+then reuses the destination. Any unrelated hard link, extra temporary, symlink,
+metadata mismatch or byte mismatch remains a fail-closed corruption condition.
+
+## Failure and restart semantics
+
+- UI entry, mode, selection, input, polling, refresh and layout changes
+ start no device operation.
+- Search starts only when pressed, runs once for six seconds and terminalizes.
+- Apply starts only when pressed, uses one exact fresh candidate and may perform
+ at most one K1 mutation.
+- Candidate/runtime/intent drift is explicit stale, never hidden rescan.
+- Post-dispatch uncertainty is explicit outcome-unknown, never automatic replay.
+- K1 power loss revokes the active session without inventing standby.
+- Wi-Fi loss and WAN loss are distinct: local LAN control may survive WAN loss;
+ route/association loss revokes only dependent host/control evidence.
+- Browser refresh restores no live local selection and causes no I/O.
+- Backend restart restores durable audit and safety ledgers, but no live BLE,
+ control or operator intent.
+- Mac sleep/restart rotates host/runtime authority and rejects late work.
+
+## Acceptance
+
+- Mode, selection and input result in zero controller calls.
+- Each Search click issues exactly one scan with duration `6`; no effect, timer,
+ selection or Apply path calls Scan.
+- Every result keeps the same ordinary **Выбрать** action. Selection retains
+ the card, shows applicable inputs immediately, shows no loader and calls no
+ controller. After an explicit committed scenario reset and its successfully
+ completed successor Scan, this includes the exact UUID used by the retired
+ prior scenario; the row never exposes a reconnect/reopen/Verify CTA.
+- During unresolved physical recovery, a completed explicit Scan still renders
+ passive BLE evidence but cannot substitute a foreign target for the durable
+ recovery record. Exact recovery remains a separate established-session
+ action outside the cold result list; ordinary **Выбрать** never invokes its
+ reopen or read-only Verify. A new network flow first requires explicit reset
+ and a successor Scan.
+- Bridge/Direct show SSID/password; Quick Connect does not.
+- Exactly one primary **Применить** owns the connection request. Its frontend
+ handler calls no Scan/Verify/reopen helper and it permits at most one device
+ mutation. For an exact reset-owned retired UUID, the backend may append only
+ the internal local settlement checkpoint described above before dispatch.
+ A later SCANNING settlement grants only explicit STOP authority and never
+ restarts the reset-owned receiver, camera, writer or acquisition.
+- Stale/pre-dispatch and unknown/post-dispatch outcomes are visibly distinct.
+- Applied-but-unready/unknown spends the old Apply and gates ordinary mode,
+ Scan, selection and Apply behind an explicit recovery choice; recommended
+ Verify has only a server-bound backend target and no browser fallback.
+- A new intent remains possible only through current backend policy. Bridge
+ uses explicit local-only `prepare-select-device`; Quick/Direct use an explicit
+ admitted Scan and latest fresh row; mode change requires `mode_selection`.
+ Each route starts no hidden frontend or mutating continuation and ends in a
+ later fresh Scan/new idempotency Apply. The declared service-owned
+ same-intent read-only bootstrap after the durable ACK is the sole continuation
+ exception and creates no UI action.
+- The exact Apply REST snapshot with `phase=network_applied` completes the
+ network intent for both `control_not_ready` and `unknown`, without requiring
+ connection-ready or waiting for WebSocket/poll convergence.
+- A service-owned supervised control bootstrap may continue read-only after
+ that ACK. It performs no BLE/host mutation or retry and creates no frontend
+ Scan/Verify/new-Apply action or blocking Apply loader. Its exact
+ accepted/running state may own one passive settling indicator only.
+- Operator error copy comes only from an allowlisted public error-code mapping;
+ unknown/raw messages use a canonical secret-free fallback and never render
+ credentials, SSIDs, payloads or stack traces.
+- No timeout, disconnect, refresh, restart or state update starts a continuation
+ or replays an ended action.
+- Supervisor, identity pin, network-attempt ledger, physical-command ledger,
+ process/BLE lease and one-use recovery STOP remain authoritative.
+- The plugin uses shared `Button`, `TextField`, `ActivityIndicator` and
+ `StatusBadge`; contract tests reject raw local controls and literal colors.
+- Geometry and long-copy tests keep all actions reachable without overlap.
+- Bridge and Quick Connect retain separate real-hardware acceptance.
+
+This ADR does not itself declare hardware coverage. The manifest may mark a
+scenario software-covered only when named executable tests cover the software
+invariant; remaining K1/macOS/router and Quick Connect gaps stay explicit.
diff --git a/docs/k1-connection-acceptance.manifest.json b/docs/k1-connection-acceptance.manifest.json
new file mode 100644
index 0000000..a81a35f
--- /dev/null
+++ b/docs/k1-connection-acceptance.manifest.json
@@ -0,0 +1,93 @@
+{
+ "schema_version": "missioncore.k1-connection-acceptance/v1",
+ "canonical_document": "docs/20_K1_CONNECTION_SUPERVISION_CANON.md",
+ "meaning": {
+ "software-covered": "The listed automated tests cover the software invariant; this is not hardware acceptance.",
+ "partial": "At least one software layer is covered and an explicit remaining gap is listed.",
+ "planned": "The scenario is specified but does not yet have adequate executable coverage."
+ },
+ "scenarios": [
+ {"id":"CONN-01","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs"],"remaining":["real K1 Quick-to-Bridge evidence"]},
+ {"id":"CONN-02","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs"],"remaining":["real K1 Bridge-to-Quick evidence"]},
+ {"id":"CONN-03","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["hardware pre-dispatch fault injection"]},
+ {"id":"CONN-04","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["hardware pre-dispatch fault injection"]},
+ {"id":"CONN-05","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_device_identity_pin_store.py"],"remaining":["two-K1 hardware evidence"]},
+ {"id":"CONN-06","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_ble_scanner.py","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["CoreBluetooth hardware evidence"]},
+ {"id":"CONN-07","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real K1 wait-beyond-TTL acceptance"]},
+ {"id":"CONN-08","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real app/backend restart reconnect acceptance"]},
+
+ {"id":"CONN-10","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["hardware pre-prepare power-loss fault injection"]},
+ {"id":"CONN-11","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["process-kill acceptance at the prepared boundary"]},
+ {"id":"CONN-12","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real K1 post-dispatch power-loss acceptance"]},
+ {"id":"CONN-13","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real K1 observation-loss evidence"]},
+ {"id":"CONN-14","status":"software-covered","test_files":["tests/test_xgrids_semantic_topology_store.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["hardware host-association loss"]},
+ {"id":"CONN-15","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["hard-power hardware evidence"]},
+ {"id":"CONN-16","status":"partial","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_physical_command_ledger.py"],"remaining":["end-to-end passive Scan policy after acquisition power loss","exact-target read-only recovery/rebind integration","Bridge hardware power-loss acceptance","Quick Connect recovery not exercised"]},
+ {"id":"CONN-17","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py"],"remaining":["transport dispatch integration","restart acceptance"]},
+ {"id":"CONN-18","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_application_mqtt.py"],"remaining":["facade exact-target resolved-active rebind","single-use explicit recovery STOP presentation/action integration","same-project Bridge hardware acceptance","Quick Connect recovery not exercised"]},
+ {"id":"CONN-19","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_application_mqtt.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["facade exact-target resolved-active READY cessation integration","Bridge reboot hardware acceptance","Quick Connect recovery not exercised"]},
+
+ {"id":"CONN-20","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_macos_wifi.py"],"remaining":["router-loss hardware evidence"]},
+ {"id":"CONN-21","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_macos_wifi.py"],"remaining":["same-SSID router-return evidence"]},
+ {"id":"CONN-22","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_macos_wifi.py"],"remaining":["manual macOS switch evidence"]},
+ {"id":"CONN-23","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real Quick AP leave/return"]},
+ {"id":"CONN-24","status":"partial","test_files":["tests/test_connection_supervisor.py","tests/test_ble_scanner.py"],"remaining":["macOS sleep/wake hardware acceptance"]},
+ {"id":"CONN-25","status":"software-covered","test_files":["tests/test_connection_supervisor.py"],"remaining":["route-race integration evidence"]},
+ {"id":"CONN-26","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["wrong-service integration evidence"]},
+ {"id":"CONN-27","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_application_mqtt.py","tests/test_xgrids_application_session.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["half-open MQTT hardware acceptance"]},
+ {"id":"CONN-28","status":"partial","test_files":["tests/test_xgrids_application_mqtt.py","tests/test_xgrids_physical_command_coordinator.py","tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["full facade policy for passive Scan with unknown/active physical state","physical-record transport_ref pinning across bounded observation and wrong-K1 no-topology-change","resolved-active SCANNING one-STOP integration","real K1 passive READY/SCANNING DeviceStatus acceptance"]},
+ {"id":"CONN-29","status":"planned","test_files":[],"remaining":["durable external-active takeover contract","operator-confirmed same-binding STOP"]},
+
+ {"id":"CONN-30","status":"planned","test_files":[],"remaining":["browser/app close clean-session acceptance at every stage"]},
+ {"id":"CONN-31","status":"software-covered","test_files":["tests/test_xgrids_network_mutation_ledger.py","tests/test_xgrids_semantic_topology_store.py"],"remaining":["restart integration acceptance"]},
+ {"id":"CONN-32","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real backend restart acceptance from a prepared network mutation"]},
+ {"id":"CONN-33","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real backend restart acceptance from a dispatching network mutation"]},
+ {"id":"CONN-34","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real backend restart acceptance from an observing network mutation"]},
+ {"id":"CONN-35","status":"software-covered","test_files":["tests/test_xgrids_network_mutation_ledger.py","tests/test_xgrids_semantic_topology_store.py"],"remaining":["restart integration acceptance"]},
+ {"id":"CONN-36","status":"planned","test_files":[],"remaining":["restart acceptance proving no old live session restoration"]},
+ {"id":"CONN-37","status":"planned","test_files":[],"remaining":["corrupt historical audit quarantine without permanent K1 block","operator diagnosis UI"]},
+ {"id":"CONN-38","status":"software-covered","test_files":["tests/test_xgrids_network_mutation_ledger.py","tests/test_xgrids_ble_runtime_arbiter.py"],"remaining":["two-service integration acceptance"]},
+ {"id":"CONN-39","status":"software-covered","test_files":["tests/test_xgrids_network_mutation_ledger.py"],"remaining":[]},
+
+ {"id":"CONN-40","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_application_session.py"],"remaining":["real wrong/failed DeviceInfo evidence"]},
+ {"id":"CONN-41","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["MQTT fault-injection integration"]},
+ {"id":"CONN-42","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["camera and point stall integration"]},
+ {"id":"CONN-43","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["late packet integration evidence"]},
+ {"id":"CONN-44","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_application_session.py"],"remaining":["late DeviceInfo integration evidence"]},
+ {"id":"CONN-45","status":"partial","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_application_control_process_lease.py"],"remaining":["durable physical-command integration"]},
+ {"id":"CONN-46","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_camera_gateway.py"],"remaining":["combined MQTT/camera late-producer integration"]},
+ {"id":"CONN-47","status":"software-covered","test_files":["tests/test_xgrids_application_control_process_lease.py"],"remaining":["two-service integration acceptance"]},
+ {"id":"CONN-48","status":"software-covered","test_files":["tests/test_xgrids_camera_gateway.py"],"remaining":["drain-timeout integration evidence"]},
+ {"id":"CONN-49","status":"software-covered","test_files":["tests/test_connection_supervisor.py"],"remaining":["long-running fault-injection acceptance"]},
+
+ {"id":"CONN-50","status":"partial","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["macOS sleep/wake hardware acceptance"]},
+ {"id":"CONN-51","status":"software-covered","test_files":["tests/test_xgrids_macos_wifi.py","tests/test_connection_supervisor.py"],"remaining":["compiled association observer"]},
+ {"id":"CONN-52","status":"software-covered","test_files":["tests/test_xgrids_device_identity_pin_store.py","tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["two-identity hardware evidence"]},
+ {"id":"CONN-53","status":"software-covered","test_files":["tests/test_xgrids_semantic_topology_store.py","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["restart browser acceptance"]},
+ {"id":"CONN-54","status":"planned","test_files":[],"remaining":["historical unknown audit does not block fresh explicit connect","restart browser acceptance"]},
+ {"id":"CONN-55","status":"partial","test_files":["apps/control-station/test/devicePluginFrontendBoundary.test.mjs"],"remaining":["automated browser geometry matrix"]},
+ {"id":"CONN-56","status":"partial","test_files":["apps/control-station/test/devicePluginFrontendBoundary.test.mjs"],"remaining":["automated long-copy browser geometry"]},
+ {"id":"CONN-57","status":"planned","test_files":[],"remaining":["operator-confirmed physical-ledger archive and identity rotation"]},
+ {"id":"CONN-58","status":"software-covered","test_files":["tests/test_xgrids_ble_runtime_arbiter.py","tests/test_xgrids_application_control_process_lease.py","tests/test_ble_scanner.py","tests/test_wifi_provisioning.py","tests/test_xgrids_ap_activation.py"],"remaining":["two-service CoreBluetooth hardware acceptance","native cleanup fault injection on macOS"]},
+ {"id":"CONN-59","status":"partial","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_network_provisioning_idempotency_journal.py"],"remaining":["prove failed audit admission releases active ownership for a new explicit attempt"]},
+ {"id":"CONN-60","status":"software-covered","test_files":["apps/control-station/test/devicePluginContracts.test.mjs"],"remaining":["manual browser confirmation-dismissal acceptance"]},
+ {"id":"CONN-61","status":"planned","test_files":[],"remaining":["legacy unresolved record terminalization without BLE or cross-session block","process-kill acceptance"]},
+ {"id":"CONN-62","status":"software-covered","test_files":["tests/test_web_validation_security.py"],"remaining":["manual browser refresh/close acceptance"]},
+ {"id":"CONN-63","status":"planned","test_files":[],"remaining":["composite policy denies active contention but ignores terminal historical network audit","manual policy presentation acceptance"]},
+ {"id":"CONN-64","status":"software-covered","test_files":["tests/test_connection_supervisor.py","tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs"],"remaining":["real K1 control/data loss acceptance"]},
+ {"id":"CONN-65","status":"partial","test_files":["tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["resolved-active same-project one-STOP UI action acceptance","real restart/browser host-route and passive DeviceStatus acceptance","Quick Connect recovery not exercised"]},
+ {"id":"CONN-66","status":"planned","test_files":[],"remaining":["compiled or long-lived macOS association observer","long-running monitor latency/fault acceptance"]},
+ {"id":"CONN-67","status":"partial","test_files":["tests/test_xgrids_acquisition_lifecycle.py"],"remaining":["real K1 repeated same-mode and cross-mode reconnect acceptance"]},
+ {"id":"CONN-68","status":"partial","test_files":["tests/test_xgrids_application_session.py","tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["Bridge STOP-ack plus Wi-Fi-loss hardware rerun","Quick Connect recovery not exercised"]},
+ {"id":"CONN-69","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["resolved-active same-project one explicit STOP browser acceptance","Bridge hardware rerun with redacted evidence","Quick Connect recovery not exercised"]},
+ {"id":"CONN-70","status":"software-covered","test_files":["apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real Bridge one-scan/select/immediate-credentials/Apply acceptance","Quick Connect recovery not exercised"]},
+ {"id":"CONN-71","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real Bridge STOP-deadline fault injection","Quick Connect recovery not exercised"]},
+ {"id":"CONN-72","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_plugin_runtime.py","apps/control-station/test/devicePluginContracts.test.mjs","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real Bridge existing-plugin-section acceptance","manual two-tab browser acceptance","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-73","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_semantic_topology_store.py","tests/test_xgrids_device_identity_pin_store.py"],"remaining":["real cold Bridge and two-K1 identity-mismatch/restart evidence","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-74","status":"software-covered","test_files":["tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_network_mutation_ledger.py","tests/test_xgrids_network_provisioning_idempotency_journal.py","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real Bridge Apply with no hidden discovery/Verify","post-dispatch hardware fault injection","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-75","status":"software-covered","test_files":["tests/test_xgrids_connection_scenario_reset.py","tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_application_control_process_lease.py","apps/control-station/test/devicePluginFrontendBoundary.test.mjs"],"remaining":["real disconnected/idle desired-mode draft no-I/O acceptance with unresolved durable physical history plus live-owner denial","real pre-START orphan and backend-runtime credential invalidation acceptance","manual top-right emergency-reset acceptance","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-76","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_physical_command_coordinator.py","tests/test_xgrids_acquisition_lifecycle.py","tests/test_xgrids_application_control_process_lease.py","tests/test_xgrids_ble_runtime_arbiter.py","tests/test_xgrids_camera_gateway.py","tests/test_cli.py","tests/test_plugin_runtime.py","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real separate explicit retirement confirmation while selection and Apply remain mutation-free","same-hardware/new-CoreBluetooth-UUID cannot be identified before provisioning because FW 3.0.2 BLE 7f02 exposes no stable DeviceInfo identity","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-77","status":"partial","test_files":["tests/test_xgrids_physical_command_ledger.py","tests/test_xgrids_physical_command_coordinator.py","tests/test_xgrids_acquisition_lifecycle.py","tests/test_plugin_runtime.py","apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["real retired exact-UUID selection remains local and Apply denied","real separately explicit reopen followed by READY and same-project SCANNING outcomes","Quick Connect live acceptance remains separate"]},
+ {"id":"CONN-78","status":"software-covered","test_files":["apps/control-station/test/devicePluginFrontendBoundary.test.mjs","apps/control-station/test/k1SupervisorPresentation.test.mjs"],"remaining":["manual Bridge and Quick one-intent timing acceptance","manual top-right idle/pending accessible-label acceptance","real stale-before-dispatch and unknown-after-dispatch fault injection","real fast REST network_applied plus delayed service-owned read-only control-bootstrap convergence","real Bridge prepare-select-device and Quick/Direct scan-new-intent recovery acceptance","manual canonical shared-control visual acceptance"]}
+ ]
+}
diff --git a/docs/runbooks/K1_CONNECTION_RECOVERY.md b/docs/runbooks/K1_CONNECTION_RECOVERY.md
new file mode 100644
index 0000000..ff516d3
--- /dev/null
+++ b/docs/runbooks/K1_CONNECTION_RECOVERY.md
@@ -0,0 +1,393 @@
+# K1 connection lifecycle and recovery runbook
+
+Canonical model: [`../20_K1_CONNECTION_SUPERVISION_CANON.md`](../20_K1_CONNECTION_SUPERVISION_CANON.md).
+This runbook is the operator-facing projection of that model. Technical terms in
+the internal-safety sections are engineering evidence; they are not wizard copy.
+
+## One operator wizard
+
+The connection surface is one progressive wizard, not a recovery dashboard.
+Its only model-bearing heading is **Подключение XGRIDS LixelKity K1**. Inside
+the wizard the two step names are exactly **Подключение** and **Сеть**.
+
+### Cold entry
+
+On a clean cold entry show only:
+
+- the connection-mode selector;
+- Step 01 **Подключение** with the explicit Bluetooth search action.
+
+Historical K1 identity never adds a reconnect choice to cold entry. If local
+session ownership or an older connection scenario exists, one explicit
+`reset_scenario` CAS first closes only that local scenario. Only after the reset
+is accepted does clean Step 01 expose **Найти по Bluetooth** as a separate
+click; reset never starts Scan itself.
+
+Do not render Step 02 yet and do not start discovery automatically. The mode
+selector and same-mode **Подключить новый K1** escape remain available through
+every other lifecycle state. The first gesture may supersede another pending
+local action. While that one bounded scenario reset itself owns `mode`, all
+three reset entry points show pending and dispatch no B intent. Each accepted
+gesture sends one idempotent local `reset_scenario` CAS: it queues behind old
+local lifecycle ownership, seals retained receiver/camera/control resources,
+invalidates candidates/drafts/credentials and retires the old physical lineage
+without resolving its outcome. It sends no BLE, device or host network command,
+MQTT publish, Verify, provisioning, START, STOP or automatic Scan. Opening and
+polling the surface still do nothing. Scan, Verify, provisioning and START
+retain separate backend gates.
+
+The top-right refresh-shaped utility is the same explicit emergency reset, not
+a passive state refresh. Its accessible label is **Сбросить подключение**; while
+the request owns the current action it reads **Сбрасываем подключение** and
+does not dispatch a second reset until that bounded request settles. It remains
+available to supersede any other local action. The accepted revision always
+returns the new local scenario and even a dirty browser selector to canonical
+**Bridge**, clears the old browser/backend presentation and source owners, and
+leaves Scan as a separate click. It performs no hidden Scan, Verify, Connect,
+START, STOP, BLE or network write and never substitutes a passive `state.read`
+for the reset mutation. After settlement the product surface contains no prior
+UUID, result count, **Повторить поиск**, reconnect error, selected device,
+credentials or recovery card; it returns to **Найти по Bluetooth**. Late
+Scan/Verify settlements from the retired scenario cannot repopulate it.
+The retained reset marker fences only work that belonged to the retired
+scenario. A newly correlated post-reset network attempt that fails or has an
+unknown outcome must immediately render its current recovery/error surface;
+reload must neither hide that new failure nor resurrect the prior prompt.
+
+### Step 01 — Подключение
+
+Step 01 **Подключение** is visible immediately.
+
+1. Bluetooth discovery starts only after the operator presses the search
+ action.
+2. For the full bounded search, show an activity indicator and a visible
+ seconds countdown in the same step.
+3. After search completes, show the result count or the empty result. Every
+ connectable result row keeps the same one enabled **Выбрать** action,
+ including an exact UUID used in an earlier scenario. That action is
+ local-only and never invokes reopen or Verify. Fresh results never render a
+ reconnect CTA, a disabled competing primary or an old/new-device decision.
+ A successful admitted Scan first settles only the reset marker whose
+ id/revision/mode it captured at action entry, recording the later admitted
+ discovery generation while retaining the marker for idempotent reset replay.
+ Failed/cancelled Scan and an older Scan racing a newer pending reset leave
+ the marker active and do not expose stale recovery authority.
+4. After ordinary **Выбрать**, retain the chosen device card and reveal only
+ the applicable local draft inputs. Selection itself has no loader and makes
+ no controller call.
+5. Only an authoritative successful connection outcome renders Step 01 green
+ as **Подключение установлено** and advances the normal connection flow.
+
+The wizard never labels a candidate as saved, original, retired or physically
+ambiguous and never exposes ledger, CAS, retirement, reopen or reconnect
+terminology in the search list. Exact recovery belongs only to a previously
+established session after an actual interruption.
+
+### Step 02 — Сеть
+
+Step 02 **Сеть** exists only after Step 01 has a confirmed green connection.
+
+- If the selected device is already usable on the chosen connection path,
+ show the network result without asking for credentials.
+- If backend policy has safely admitted explicit network setup, show the exact
+ retained device context and SSID/password fields here, never beside the
+ candidate list.
+- One explicit submit owns any exact hidden revalidation and at most one
+ reviewed network write.
+- **Изменить сеть** belongs only to this step and starts no Bluetooth search
+ when its form opens.
+- A stale tab, changed runtime/binding or policy denial fails before a write and
+ never exposes a foreign candidate.
+
+## Ordinary selection
+
+The ordinary **Выбрать** action is presentation simplification, not relaxed
+safety. It creates only a browser-local candidate draft and performs no
+controller I/O. It never selects an internal recovery path:
+
+- an ordinary fresh candidate becomes only the selected local draft;
+- an exact prior candidate uses the same **Выбрать** action as every row;
+- no candidate selection retires old authority, reopens a ledger record, calls
+ Verify, connects GATT, scans again or changes topology or the device;
+- a foreign, stale, non-connectable or policy-denied candidate remains
+ unavailable and changes no topology, ledger or device.
+
+After an explicit committed scenario reset, only its successfully completed
+successor Scan may make an exact previously retired transport eligible for a
+new network draft. Apply still captures that exact current-generation handle,
+validates the live GATT baseline and crosses at most one reviewed write edge.
+Selection performs no recovery action. At the final Apply boundary, the backend
+may append one exact request-bound local reopen checkpoint after network
+PREPARED and before write dispatch. That checkpoint preserves physical
+retirement/original-outcome audit, performs no device I/O and authorizes no
+START or STOP. The same applied intent then uses fresh DeviceInfo plus a
+non-retained DeviceStatus to settle READY as standby or identity-bound SCANNING as
+active, without a visible Verify step or command replay. In the SCANNING case
+it materializes only explicit STOP authority; it does not restart the retired
+receiver, camera, evidence writer or acquisition.
+
+### Exact internal recovery for an established session
+
+For an exact target belonging to a previously established session with one
+active retirement,
+`physical-command.reopen-retired-reconciliation` requires:
+
+- `operator_confirmed=true`, bound to a separately explicit session-recovery
+ action outside cold entry and the Bluetooth result list;
+- a stable `reopening_id` and reason
+ `device-returned-for-explicit-reconciliation`;
+- exact `expected_snapshot_runtime_id`, `expected_revision`,
+ `expected_retirement_id`, `expected_transport_ref` and
+ `expected_discovery_generation` CAS;
+- a current connectable candidate and safe lifecycle/process ownership.
+
+The transaction changes only the local durable ledger. It appends reopen audit,
+preserves the retirement and unknown command outcome as history, restores the
+original unresolved `dispatching` or `observing` stage and removes only that
+retirement's active deny. It performs zero BLE, Wi-Fi, MQTT, DeviceConfig,
+ModelingStatus, workspace, project, START or STOP I/O and starts no Scan.
+
+The same still-current session-recovery action may then own one exact read-only
+Verify. Ordinary **Выбрать** never invokes either half. Recovery never replays
+historical START/STOP and never silently provisions:
+
+- fresh non-retained READY resolves standby;
+- fresh exact same-project SCANNING resolves active and permits only the
+ separately guarded stop path;
+- identity, GATT, CAS, route/control or policy failure leaves the outcome
+ unknown and ends the established-session recovery without entering the new
+ connection wizard.
+
+If the action response is lost, refreshed state may continue the same click
+only when it proves that exact `reopening_id` audit was committed and every
+original runtime, candidate and authority fence still matches. A second tab,
+new discovery generation, new retirement or different reopening identity cannot
+inherit the continuation.
+
+### Internal retirement
+
+`physical-command.retire-unavailable` is a local durable primitive for an
+unresolved target that is truly unavailable or replaced. It may run only from
+its separately confirmed recovery/reset path, never from ordinary candidate
+selection, UI entry, polling or a timer. Admission requires explicit
+confirmation, stable `retirement_id` and exact backend runtime,
+operation, revision and transport CAS while every local owner is safe.
+
+Retirement preserves the complete old attempt and unknown command outcome,
+activates an exact-transport deny and performs zero device I/O or automatic
+discovery. Retirement history remains durable even if an exact later recovery
+action uses the reopen transaction. The wizard exposes no retirement
+transaction or historical label. Any plain-language exact recovery CTA belongs
+only to the established-session surface when backend authority permits it.
+
+Current FW 3.0.2 BLE `7f02` does not expose stable DeviceInfo identity. The same
+hardware under a new CoreBluetooth UUID cannot be recognized before DeviceInfo
+becomes available. This remains an explicit protocol/hardware acceptance gap;
+the wizard must not speculate.
+
+## Session and freshness rules
+
+A scan result is an unselected presence candidate owned by the latest explicit
+scan generation. Wall-clock age does not remove its row while the operator is
+reading or completing the form. A successor Scan, explicit scenario reset,
+runtime-owner teardown or proven exact-target GATT failure invalidates it. The
+row itself is never network authority: Apply still requires the exact captured
+CoreBluetooth object and live GATT validation before any write.
+
+The selected session ends on proven disconnect, explicit lifecycle stop, a
+committed network transition, selection of another device, backend restart or
+proven native cleanup. A later connection always requires an explicit search
+and **Выбрать**. Polling can update presentation but starts neither operation.
+
+Bridge, Quick Connect and Direct Connect are separate topologies. In
+any state, changing the mode or choosing another K1 in the same mode sends one
+local scenario-reset CAS. It can wait for and supersede live/recovery ownership,
+seal retained local producers and retire unresolved old lineage, but performs
+zero device/host I/O and starts no Scan. Scan, Verify, provisioning and START
+remain independently fenced until an explicit candidate intent crosses its
+reviewed transition. No old host route, endpoint, control, data or BLE authority
+crosses a committed reset boundary.
+
+## Active scanning: transient host-path recovery
+
+This is the sole automatic read-only rebind exception. It exists only after
+Mission Core itself has a composite-confirmed START and still owns the exact
+acquisition/runtime/device/connection/evidence lineage. It does not apply on a
+cold connection screen, after backend restart, to an external SCANNING K1 or to
+an unresolved/foreign START.
+
+When the Mac loses Wi-Fi/route or the data socket while that acquisition is
+running, the active scanning pane shows a neutral spinner and
+**Восстанавливаем соединение** with attempt/elapsed time. Do not show a red
+terminal operation banner for the expected late failure of the superseded old
+control socket. Keep the acquisition and evidence session owned while the
+backend retries exact route/TCP and inspection-only DeviceInfo/status proof.
+
+The recovery loop never sends BLE, changes Wi-Fi, writes DeviceConfig, repeats
+START or sends STOP. Outcomes are:
+
+- exact same-device/same-project initialized `SCANNING`: silently resume the
+ point stream/control binding and, when necessary, CAS-restart the dead or
+ stalled acquisition-owned right-camera FFmpeg epoch;
+- fresh `READY`: interrupt/seal host-owned acquisition resources truthfully,
+ without STOP;
+- fresh `SCAN_OVER`: persist cessation, interrupt/seal locally and retain a
+ read-only `awaiting READY` fence that denies a new START;
+- wrong identity/same IP, changed lineage or failed camera CAS: remain blocked
+ for explicit operator handling; and
+- device/system fault or unsafe status: show a truthful terminal fault, with no
+ command retry.
+
+While state is `reconnecting` or `blocked`, expose **Завершить локально**. The
+action `acquisition.force-finish-local` requires the current snapshot runtime,
+acquisition id/state revision, recovery generation, producer generation match,
+an idempotency key and explicit confirmation. It cancels recovery first, then
+seals only local receiver/camera/control/perception owners. It preserves the
+physical START ledger and sends no STOP. If a connection-mode reset races this
+action, the shared lifecycle gate makes cleanup idempotent; the loser cannot
+overwrite the new mode or revive the old acquisition.
+
+If receiver, camera or evidence sealing fails, the recovery generation is
+still irrevocably cancelled first. The force-finish operation ends with a
+visible `local-cleanup-failed` result whose retryability applies only to local
+finalization; the terminal acquisition retains `cleanup_pending` and blocks a
+replacement session. A later explicit local stop or exact connection-scenario
+reset may retry those host resources. It must not retry START, STOP, BLE or a
+network write, and a late success from the retired recovery generation remains
+fenced.
+
+## Failure matrix
+
+| Event | Product result | Operator path |
+| --- | --- | --- |
+| Cold entry | Mode plus Step 01 and explicit Scan; zero device I/O before Scan | Start search explicitly |
+| Disconnected/idle mode or same-mode new-device request with unresolved durable physical history | Local session/audit lineage is retired under one reset CAS; zero device/host I/O and no automatic Scan | Start the clean Step 01 search explicitly; the old physical outcome remains auditable |
+| Mode reset while live, reconnecting or terminal cleanup still owns local sources | Reset supersedes recovery and locally seals receiver/camera/control; previous K1 may still scan | Wait for the bounded local cleanup or retry the same reset if local sealing fails |
+| Search running | Step 01 spinner and visible countdown | Wait or let the bounded search end |
+| Search finds no candidates | Step 01 reports no matches | Repeat search explicitly |
+| Search finds one or many candidates | Every connectable row has one enabled **Выбрать**, including the exact prior UUID | Select one row; no reconnect or recovery action appears in search results |
+| Wall-clock time passes after Scan before selection | Latest-generation rows remain stable; no operation starts | Select normally; exact capture and live GATT will gate Apply |
+| A new Scan/reset/runtime teardown or exact-target GATT failure invalidates the generation | Old rows disappear or the attempted action fails cleanly before mutation | Run one explicit new search if needed |
+| Selection is rejected by identity, GATT, CAS, lifecycle or safety policy | Loader ends; nothing changed; Step 02 remains absent | **Повторить** or **Выбрать другое** |
+| Selection completes exact device connection | Step 01 turns green | Continue in Step 02 **Сеть** |
+| Network setup is safely required | Credentials appear only in Step 02 | Submit once |
+| Network write becomes ambiguous after dispatch | Attempt ends unknown; no replay | Wait for cleanup, then create a distinct explicit attempt |
+| Device powers off or BLE disconnects | Live selection and authority revoke after proof | Search and select explicitly after the device is available |
+| Router, Mac Wi-Fi or MQTT control is lost while idle/pre-START | Host/control authority revokes; data may remain evidence only | Restore reachability, then use the same wizard flow |
+| Mac Wi-Fi/route is briefly lost during one composite-confirmed owned acquisition | Active pane remains neutral **Восстанавливаем соединение**; no START/STOP/network retry | Wait for exact automatic read-only rebind or press **Завершить локально** |
+| Active recovery returns READY or SCAN_OVER | Local receiver/camera seal without STOP; SCAN_OVER remains fenced until fresh READY | Start another scenario only after backend policy reports it safe |
+| Active recovery sees another K1 on the same IP or changed lineage | Recovery blocks fail-closed; no camera/data resurrection | Finish locally or explicitly choose/reset connection scenario |
+| A physical START/STOP edge is unresolved | Mutation stays fenced; no technical wizard ceremony | Search/select remains explicit; backend admits only a safe exact path |
+| Exact actively retired UUID is present after committed reset and successor Scan | The row exposes the same enabled **Выбрать** as every candidate | Select locally; Apply remains exact-handle/live-GATT gated and may append one internal local settlement checkpoint before its sole write; audit remains append-only and START/STOP stay denied until fresh read-only classification |
+| Another candidate is selected while old authority is unavailable and no reset-owned new scenario exists | Selection stays local and Apply remains denied | Start an explicit new connection scenario, then Scan and select again |
+| Browser refresh or backend restart | No automatic operation and no restored live selection | Begin from the cold progressive wizard |
+
+## Physical START/STOP safety remains separate
+
+The simplified wizard never weakens physical-command safety:
+
+- loss of control does not prove that K1 stopped recording;
+- START and STOP are never replayed automatically;
+- local receiver/camera/ingress cleanup is not physical STOP;
+- an ambiguous post-dispatch command remains unknown until exact fresh proof;
+- read-only recovery is pinned to the durable transport, identity/profile,
+ host epoch and project;
+- each observation publishes exactly one DeviceInfo request and may classify
+ only a fresh non-retained DeviceStatus after that barrier;
+- READY records cessation without inventing a successful STOP;
+- SCAN_OVER records cessation without inventing STOP, but keeps a durable
+ read-only fence until a later fresh unbound READY observation;
+- exact same-project SCANNING may mint one single-use, separately confirmed STOP
+ checkpoint; it does not send STOP automatically;
+- a wrong transport/device/project changes no topology or ledger state;
+- accepted STOP without READY or SCAN_STOPPING by the backend deadline closes
+ only host-owned resources, yields `timed_out` / `standby-unknown`, preserves
+ the unresolved ledger and keeps mutation fenced.
+
+Engineering logs and state APIs retain these distinctions. The connection
+wizard projects only the ordinary progressive flow and a non-technical terminal
+selection result.
+
+## No automatic action rule
+
+None of these events may scan, select, reconnect, Verify, provision, START or
+STOP:
+
+- opening or resizing the connection surface;
+- backend event delivery or state polling;
+- an acknowledged scenario reset (it may perform only its explicit local
+ retirement, never any listed device/network action or automatic Scan);
+- candidate list refresh after an ended search;
+- browser refresh, sleep/wake or backend restart;
+- timeout, disconnect or a historical audit record.
+
+The only exception is the service-owned active-stream read-only rebind above.
+It is triggered by the already-owned receiver's transport loss, not UI entry or
+polling, and is limited to route/TCP, DeviceInfo/status inspection, receiver
+resubscribe and exact local camera-epoch restart. It never performs discovery,
+provisioning, START, STOP or any device/network write.
+
+Only the currently pressed search, distinct exact recovery CTA, network submit
+or separately guarded acquisition control may own corresponding I/O. Ordinary
+**Выбрать** owns only a browser-local draft and never owns a loader. Every
+loader belongs to the explicit action that created it and ends with it.
+
+## Hardware acceptance order
+
+Software tests do not replace a real K1/macOS/router run. Accept sequentially:
+
+1. Open cold and prove mode plus Step 01 and its explicit Scan action are
+ visible, while Step 02 is absent and no discovery starts automatically. With both empty and
+ unresolved durable physical history, change the mode and prove one local
+ reset CAS, zero device/host calls and no automatic Scan. Repeat from active,
+ reconnecting and terminal `cleanup_pending` states; prove local sources are
+ sealed, the old K1 is not claimed stopped, and a local cleanup failure leaves
+ the exact reset retryable. With an exact prior connection, prove cold entry
+ contains no historical reconnect prompt; after one reset CAS and zero Scan,
+ a separate clean **Найти по Bluetooth** action remains clean after reload.
+2. Start discovery and prove the spinner and seconds countdown remain visible
+ for the bounded search, then the exact result count appears.
+3. With multiple advertisements, prove every ordinary connectable row keeps
+ exactly one enabled **Выбрать** action and none auto-selects or auto-connects.
+ Repeat with the exact prior UUID after reset and prove it has the same
+ **Выбрать** action, with no reconnect/reopen/Verify path.
+4. Select a Bridge device, including that prior UUID, and prove the card remains visible through
+ **Подключение…**, then Step 01 turns green before Step 02 **Сеть** appears.
+5. Prove network fields never coexist with candidate rows, and one explicit
+ submit owns at most one write.
+6. Wait beyond the legacy candidate TTL and prove both the latest-generation
+ unselected rows and an admitted selected session remain stable; then prove a
+ missing exact handle/live GATT failure blocks Apply before any write.
+7. Exercise identity, GATT, stale-CAS, lifecycle-busy, disconnect and power-off
+ failures; each ends the loader, leaves Step 02 absent and offers only ordinary
+ retry/choose-another copy.
+8. Retire an unresolved target in controlled fault injection, perform one
+ scenario reset and rediscover its exact UUID in the successor Scan. Prove its
+ sole action is **Выбрать**, selection performs no I/O and Step 02 appears
+ immediately. Apply once and prove exact current-generation handle capture,
+ live GATT baseline, exactly one request-bound append-only physical reopen
+ checkpoint and at most one network write. The original retirement/outcome
+ audit remains immutable; the service-owned continuation uses only DeviceInfo
+ and non-retained status, with zero START/STOP and no browser Verify. Inject
+ failed and outcome-unknown network results; each current error/recovery
+ surface remains visible after reload.
+9. Try a different device while old authority is unavailable and prove its
+ ordinary selection triggers no hidden retirement/reopen/Verify and cannot
+ bypass the durable target.
+10. Prove no row labels a device saved/original/retired, says
+ **Переподключиться**, or exposes physical-state/ledger terminology. The model name
+ appears only in the top heading; step names remain **Подключение / Сеть**.
+11. During a composite-confirmed live acquisition, remove host Wi-Fi for longer
+ than the old control keepalive and restore it. Prove neutral reconnecting,
+ same-lineage SCANNING resume, raw-writer continuity, exact camera epoch
+ restart when stalled, and zero START/STOP/BLE/network mutation. Repeat with
+ READY, SCAN_OVER, wrong identity and permanent loss plus
+ **Завершить локально**.
+12. Repeat idle/pre-START Bridge network loss, Mac Wi-Fi switch, sleep/wake,
+ hard K1 power loss, STOP deadline and backend restart; prove zero automatic
+ command or retry outside the sole active-stream exception.
+13. Repeat the entire acceptance separately for Quick Connect before claiming
+ Quick coverage.
+
+The current software contract is not real-hardware acceptance. The acceptance
+manifest lists executable coverage and the remaining Bridge/Quick field gaps.
diff --git a/experiments/perception/worker/run_e15_shadow_inference.py b/experiments/perception/worker/run_e15_shadow_inference.py
index a1d41e9..5007558 100644
--- a/experiments/perception/worker/run_e15_shadow_inference.py
+++ b/experiments/perception/worker/run_e15_shadow_inference.py
@@ -254,13 +254,11 @@ def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
}
if (
not isinstance(replay_source, dict)
- or replay_source.get("session_id")
- != "20260720T065719Z_viewer_live"
+ or replay_source.get("session_id") != "20260720T065719Z_viewer_live"
or replay_source.get("display_name") != "RAVNOVES00"
or replay_source.get("selection") != "complete-recording"
or float(replay_source.get("speed", 0)) != 1.0
- or float(replay_source.get("minimum_source_span_seconds", 0))
- < 450
+ or float(replay_source.get("minimum_source_span_seconds", 0)) < 450
or replay_source.get("look_ahead") is not False
or any(
not isinstance(replay_source.get(key), int)
@@ -269,9 +267,7 @@ def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
for key, expected in replay_integer_contract.items()
)
):
- raise RuntimeError(
- "LAB E28 complete-recording worker replay contract is invalid"
- )
+ raise RuntimeError("LAB E28 complete-recording worker replay contract is invalid")
elif replay_source is not None:
raise RuntimeError("LAB E15 non-replay profile carries replay source state")
if local_surface is not None:
@@ -280,9 +276,7 @@ def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
)
local_acceptance = (
- local_surface.get("acceptance")
- if isinstance(local_surface, dict)
- else None
+ local_surface.get("acceptance") if isinstance(local_surface, dict) else None
)
expected_profile_sha256 = hashlib.sha256(
canonical_json(DEFAULT_K1_LOCAL_SURFACE_PROFILE.to_dict())
@@ -293,29 +287,20 @@ def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
"maximum_runtime_drop_fraction",
)
point_capacity = (
- local_surface.get("point_queue_capacity")
- if isinstance(local_surface, dict)
- else None
+ local_surface.get("point_queue_capacity") if isinstance(local_surface, dict) else None
)
pose_capacity = (
- local_surface.get("pose_buffer_capacity")
- if isinstance(local_surface, dict)
- else None
+ local_surface.get("pose_buffer_capacity") if isinstance(local_surface, dict) else None
)
result_capacity = (
- local_surface.get("result_capacity")
- if isinstance(local_surface, dict)
- else None
+ local_surface.get("result_capacity") if isinstance(local_surface, dict) else None
)
if (
- profile.get("mode")
- not in {"worker-replay-gate", "physical-shadow-gate"}
+ profile.get("mode") not in {"worker-replay-gate", "physical-shadow-gate"}
or not isinstance(local_surface, dict)
or local_surface.get("enabled") is not True
- or local_surface.get("profile_id")
- != DEFAULT_K1_LOCAL_SURFACE_PROFILE.profile_id
- or local_surface.get("profile_sha256")
- != expected_profile_sha256
+ or local_surface.get("profile_id") != DEFAULT_K1_LOCAL_SURFACE_PROFILE.profile_id
+ or local_surface.get("profile_sha256") != expected_profile_sha256
or not isinstance(point_capacity, int)
or isinstance(point_capacity, bool)
or point_capacity not in range(1, 9)
@@ -328,27 +313,16 @@ def read_live_profile(path: Path) -> tuple[dict[str, Any], str]:
or not 0
<= float(local_surface.get("future_pose_wait_ms", -1))
<= DEFAULT_K1_LOCAL_SURFACE_PROFILE.maximum_pose_binding_ms
- or not 0.1
- <= float(local_surface.get("retention_seconds", 0))
- <= 30
+ or not 0.1 <= float(local_surface.get("retention_seconds", 0)) <= 30
or float(temporal.get("maximum_pose_point_delta_ms", 0))
!= DEFAULT_K1_LOCAL_SURFACE_PROFILE.maximum_pose_binding_ms
or not isinstance(local_acceptance, dict)
or int(local_acceptance.get("minimum_bound_frames", 0)) < 2
- or any(
- not 0 <= float(local_acceptance.get(key, -1)) <= 1
- for key in local_fractions
- )
- or float(
- local_acceptance.get("maximum_p95_result_age_ms", 0)
- )
- <= 0
- or float(local_acceptance.get("minimum_effective_fps", 0))
- <= 0
+ or any(not 0 <= float(local_acceptance.get(key, -1)) <= 1 for key in local_fractions)
+ or float(local_acceptance.get("maximum_p95_result_age_ms", 0)) <= 0
+ or float(local_acceptance.get("minimum_effective_fps", 0)) <= 0
):
- raise RuntimeError(
- "LAB E28 worker local-surface profile contract is invalid"
- )
+ raise RuntimeError("LAB E28 worker local-surface profile contract is invalid")
fractions = (
"detector_maximum_drop_fraction",
"semantic_maximum_drop_fraction",
@@ -429,64 +403,45 @@ def _local_surface_acceptance_checks(
return {
"local_surface_session_initialized": bool(runtime),
- "local_surface_closed": snapshot.get("closed") is True
- and runtime.get("closed") is True,
+ "local_surface_closed": snapshot.get("closed") is True and runtime.get("closed") is True,
"local_surface_minimum_bound_frames": point_bound
>= int(acceptance["minimum_bound_frames"]),
- "local_surface_binder_accounting": point_bound
- + point_missed
- + point_dropped
- + point_depth
+ "local_surface_binder_accounting": point_bound + point_missed + point_dropped + point_depth
== point_published,
- "local_surface_binder_to_runtime_accounting": point_bound
- == runtime_published,
+ "local_surface_binder_to_runtime_accounting": point_bound == runtime_published,
"local_surface_point_buffer_bound": (
int(points.get("capacity", 0)) == int(config["point_queue_capacity"])
- and int(points.get("maximum_depth", 0))
- <= int(points.get("capacity", 0))
+ and int(points.get("maximum_depth", 0)) <= int(points.get("capacity", 0))
and point_depth == 0
),
"local_surface_pose_buffer_bound": (
int(poses.get("capacity", 0)) == int(config["pose_buffer_capacity"])
- and int(poses.get("maximum_depth", 0))
- <= int(poses.get("capacity", 0))
+ and int(poses.get("maximum_depth", 0)) <= int(poses.get("capacity", 0))
),
- "local_surface_maximum_pose_miss_fraction": point_missed
- / max(1, point_published)
+ "local_surface_maximum_pose_miss_fraction": point_missed / max(1, point_published)
<= float(acceptance["maximum_pose_miss_fraction"]),
- "local_surface_maximum_point_drop_fraction": point_dropped
- / max(1, point_published)
+ "local_surface_maximum_point_drop_fraction": point_dropped / max(1, point_published)
<= float(acceptance["maximum_point_drop_fraction"]),
- "local_surface_runtime_accounting": runtime_consumed
- + runtime_dropped
- + runtime_depth
+ "local_surface_runtime_accounting": runtime_consumed + runtime_dropped + runtime_depth
== runtime_published,
- "local_surface_runtime_result_accounting": result_published
- + result_failed
+ "local_surface_runtime_result_accounting": result_published + result_failed
== runtime_consumed,
"local_surface_runtime_queue_bound": (
int(queue_state.get("capacity", 0)) == int(config["point_queue_capacity"])
- and int(queue_state.get("maximum_depth", 0))
- <= int(queue_state.get("capacity", 0))
+ and int(queue_state.get("maximum_depth", 0)) <= int(queue_state.get("capacity", 0))
and runtime_depth == 0
),
- "local_surface_maximum_runtime_drop_fraction": runtime_dropped
- / max(1, runtime_published)
+ "local_surface_maximum_runtime_drop_fraction": runtime_dropped / max(1, runtime_published)
<= float(acceptance["maximum_runtime_drop_fraction"]),
- "local_surface_minimum_effective_fps": float(
- delivery.get("effective_fps", 0)
- )
+ "local_surface_minimum_effective_fps": float(delivery.get("effective_fps", 0))
>= float(acceptance["minimum_effective_fps"]),
"local_surface_zero_runtime_failures": result_failed == 0,
"local_surface_maximum_p95_result_age_ms": (
isinstance(p95_result_age, (int, float))
and not isinstance(p95_result_age, bool)
- and float(p95_result_age)
- <= float(acceptance["maximum_p95_result_age_ms"])
- ),
- "local_surface_profile_pinned": (
- runtime_profile.get("profile_id") == config["profile_id"]
+ and float(p95_result_age) <= float(acceptance["maximum_p95_result_age_ms"])
),
+ "local_surface_profile_pinned": (runtime_profile.get("profile_id") == config["profile_id"]),
"local_surface_shadow_authority_only": (
snapshot.get("authority")
== {
@@ -622,6 +577,7 @@ class _TransportState:
camera_sequence_gaps: int = 0
last_camera_source_sequence: int | None = None
session_id: str | None = None
+ session_generation: int | None = None
session_end_seen: bool = False
timed_out: bool = False
results_published: int = 0
@@ -956,8 +912,7 @@ class _StageExecutionTelemetry:
self._last_frame_by_stage.get(stage_id),
)
for stage_id in self._stage_ids
- if stage_id in self._native_started
- and stage_id not in self._native_failed
+ if stage_id in self._native_started and stage_id not in self._native_failed
]
for stage_id, elapsed_seconds, activations, frame_index in rows:
self._emit_native(
@@ -1012,9 +967,7 @@ class _StageExecutionTelemetry:
"elapsed_seconds": round(elapsed[stage_id], 6),
"activations": self._activations[stage_id],
"share_percent": (
- round(elapsed[stage_id] / total * 100, 6)
- if total > 0
- else None
+ round(elapsed[stage_id] / total * 100, 6) if total > 0 else None
),
}
for stage_id in self._stage_ids
@@ -1127,11 +1080,20 @@ def _receiver(
state.first_ingress_sequence = sequence
state.last_ingress_sequence = sequence
session_id = str(header["session_id"])
+ session_generation_value = header["session_generation"]
+ if (
+ not isinstance(session_generation_value, int)
+ or isinstance(session_generation_value, bool)
+ or session_generation_value < 1
+ ):
+ raise ShadowRuntimeError("shadow session generation is invalid")
+ session_generation = session_generation_value
if state.session_id is None:
state.session_id = session_id
+ state.session_generation = session_generation
if local_surface is not None:
local_surface.begin_session(session_id)
- elif state.session_id != session_id:
+ elif state.session_id != session_id or state.session_generation != session_generation:
raise ShadowRuntimeError("shadow session identity changed")
modality = str(header["modality"])
state.counts[modality] += 1
@@ -1272,9 +1234,7 @@ def _common(args: argparse.Namespace) -> dict[str, Any]:
"k1link/ground_segmentation.py",
}
if not required_surface_sources <= worker_sources:
- raise RuntimeError(
- "LAB E28 worker package lacks local-surface runtime"
- )
+ raise RuntimeError("LAB E28 worker package lacks local-surface runtime")
stability = None
stability_sha256 = None
if args.stability_profile is not None:
@@ -1400,11 +1360,7 @@ def run(
if not token or len(token) < 40:
raise RuntimeError("LAB E15 shadow token is missing")
- stage_telemetry = (
- runtime_state.get("_stage_telemetry")
- if runtime_state is not None
- else None
- )
+ stage_telemetry = runtime_state.get("_stage_telemetry") if runtime_state is not None else None
if not isinstance(stage_telemetry, _StageExecutionTelemetry):
stage_telemetry = _StageExecutionTelemetry()
if runtime_state is not None:
@@ -1461,9 +1417,7 @@ def run(
local_surface = K1LocalSurfaceShadowCoordinator(
point_capacity=int(local_surface_config["point_queue_capacity"]),
pose_capacity=int(local_surface_config["pose_buffer_capacity"]),
- future_pose_wait_ms=float(
- local_surface_config["future_pose_wait_ms"]
- ),
+ future_pose_wait_ms=float(local_surface_config["future_pose_wait_ms"]),
retention_seconds=float(local_surface_config["retention_seconds"]),
result_capacity=int(local_surface_config["result_capacity"]),
)
@@ -1890,7 +1844,11 @@ def run(
optimize=False,
)
with stage_telemetry.measure("result-publication", envelope.frame_index):
+ if transport.session_id is None or transport.session_generation is None:
+ raise ShadowRuntimeError("shadow result session identity is unavailable")
live_result = encode_live_perception_result(
+ session_id=transport.session_id,
+ session_generation=transport.session_generation,
frame_index=envelope.frame_index,
source_frame_index=int(envelope.timeline["source_frame_index"]),
session_seconds=frame_seconds,
@@ -1969,9 +1927,7 @@ def run(
temporal_semantic_summary = (
None if semantic_stabilizer is None else semantic_stabilizer.snapshot()
)
- local_surface_snapshot = (
- None if local_surface is None else local_surface.snapshot()
- )
+ local_surface_snapshot = None if local_surface is None else local_surface.snapshot()
acceptance = live["acceptance"]
checks = {
"minimum_camera_frames": decoded_frame_count >= int(acceptance["minimum_camera_frames"]),
@@ -2356,9 +2312,7 @@ def _persistent_run_telemetry_identity(
if isinstance(stability, dict) and isinstance(stability.get("profile_id"), str)
else "lab-e15-shadow-inference-v1"
)
- method_id = (
- INLINE_TEMPORAL_PIPELINE_ID if isinstance(stability, dict) else PIPELINE_ID
- )
+ method_id = INLINE_TEMPORAL_PIPELINE_ID if isinstance(stability, dict) else PIPELINE_ID
return PipelineTelemetryIdentity(
contour_id=telemetry.get("contour_id"),
agent_id=telemetry.get("agent_id"),
@@ -2545,9 +2499,7 @@ def serve(args: argparse.Namespace) -> int:
state["last_run_outcome"] = {
"request_id": request_id,
"state": "failed",
- "duration_ms": (
- round(duration_ms, 6) if duration_ms is not None else None
- ),
+ "duration_ms": (round(duration_ms, 6) if duration_ms is not None else None),
"exit_code": None,
"error_type": type(exc).__name__,
}
diff --git a/plugins/xgrids-k1/README.md b/plugins/xgrids-k1/README.md
index aae6079..d7df916 100644
--- a/plugins/xgrids-k1/README.md
+++ b/plugins/xgrids-k1/README.md
@@ -95,6 +95,14 @@ Validate the current exact-match profile without device I/O with:
uv run python plugins/xgrids-k1/profile_loader.py
```
+Plugin v0.7.0 adds the backend-owned supervised connection lifecycle. Operator
+mode choice is a CAS-fenced draft; an explicit Scan commits a safe pre-START
+mode switch, while Connect reaches Ready only after the exact current
+`DeviceInfo` authority is confirmed. Configured, active and desired modes are
+separate facts. Terminal pre-START failures and purely local prepared sessions
+self-retire without a device command, and an applied network configuration is
+recovered through a separate read-only Verify instead of replaying Wi-Fi.
+
Plugin v0.6.0 retains the physically accepted v0.5.0 control transport and adds
the connection matrix behind the existing explicit `network.provision` action.
Bridge remains the default. Direct Connect sends the same single reviewed
@@ -102,13 +110,19 @@ Bridge remains the default. Direct Connect sends the same single reviewed
Connect accepts no browser/API credential: it sends one reviewed fixed 100-byte
AP-enable frame to the selected K1, waits up to 15 seconds for the canonical
byte-51 AP-ready flag, and keeps that BLE session alive while the macOS adapter
-performs bounded exact-SSID CoreWLAN discovery and one association. Credentials
+performs up to 30 seconds of exact-SSID CoreWLAN discovery and one association.
+AP-ready does not imply that macOS has already observed the RF beacon. Credentials
are resolved by a preinstalled exact `3.0.2` firmware provider. Its optional laboratory importer
validates the reviewed official archive, extracts the single AP declaration and
installs firmware-scoped material in the OS secure store. The macOS helper then
materializes the selected device profile entirely inside Keychain before any
BLE write. The secret never enters the browser, API, argv, logs or evidence;
the importer's short-lived mutable buffer is zeroized after the stdin handoff.
+The prepared-host adapter uses the accepted Apple-signed
+`/usr/bin/xcrun swift` runner. It does not runtime-compile an ad-hoc executable,
+query the standard Wi-Fi Keychain or open a password dialog after the K1 write.
+Production portability still requires a packaged, properly signed helper with
+a stable designated identity and explicit CoreWLAN authorization.
There is no automatic BLE-write or association retry. A clean host cannot
obtain the provider from BLE and the product does not download firmware during
connection. Windows/Linux Quick Connect adapters are not planned while that
diff --git a/plugins/xgrids-k1/frontend/README.md b/plugins/xgrids-k1/frontend/README.md
index 8dc7c95..1cc1ca8 100644
--- a/plugins/xgrids-k1/frontend/README.md
+++ b/plugins/xgrids-k1/frontend/README.md
@@ -6,17 +6,23 @@ generic application source tree.
The contribution contains:
-- `K1ProvisioningPipeline` for power confirmation, BLE discovery and the three
- explicit local connection directions: Bridge, Quick Connect and Direct
- Connect;
+- `K1ProvisioningPipeline` for explicit BLE discovery and the three local
+ connection directions: Bridge, Quick Connect and Direct Connect;
- `K1AcquisitionPipeline` for explicit canonical connection/workspace/project/
START checkpoints, local receiver preparation and compatibility file replay;
- `K1SpatialControls` for an explicit no-retry STOP followed by the separate
READY plus steady-green completion gate;
- plugin-local diagnostics, metrics, API state, lifecycle mapping,
observation-source mapping and scoped styles;
-- typed v0.6.0 local-network and interactive application-control state plus legacy shadow
+- typed v0.7.0 supervised connection lifecycle and interactive application-control state plus legacy shadow
inspection contracts;
+- a click-correlated, non-secret provisioning presentation latch: after Apply,
+ Steps 01–02 keep their selected-device/form anatomy with disabled controls
+ until the exact connection attempt becomes reachable or reaches bounded
+ recovery; the Wi-Fi password is cleared before asynchronous dispatch;
+- policy-gated retirement of an unavailable historical K1 as an explicit
+ local ledger action; it never emits a device command and never bypasses the
+ public `retire-unavailable-physical-target` decision;
- `plugin.ts`, which binds the manifest `device.connection` component key to
the runtime provider and connection view.
diff --git a/plugins/xgrids-k1/frontend/src/XgridsK1Connection.tsx b/plugins/xgrids-k1/frontend/src/XgridsK1Connection.tsx
index 3036792..aa13fe9 100644
--- a/plugins/xgrids-k1/frontend/src/XgridsK1Connection.tsx
+++ b/plugins/xgrids-k1/frontend/src/XgridsK1Connection.tsx
@@ -1,31 +1,264 @@
-import { Button, StatusBadge, type StatusTone } from "@nodedc/ui-react";
+import { useEffect, useRef, useState } from "react";
+import { StatusBadge, type StatusTone } from "@nodedc/ui-react";
import type { DevicePluginConnectionProps } from "@mission-core/plugin-sdk";
+import {
+ activeStreamRecoveryPresentation,
+ suppressGenericErrorDuringActiveStreamRecovery,
+} from "./activeStreamRecovery";
import { K1AcquisitionPipeline } from "./components/K1AcquisitionPipeline";
import { K1Diagnostics } from "./components/K1Diagnostics";
import { K1Metrics } from "./components/K1Metrics";
-import { K1ProvisioningPipeline } from "./components/K1ProvisioningPipeline";
+import { K1OperatorError } from "./components/K1OperatorError";
import {
+ K1ProvisioningPipeline,
+ unavailablePhysicalRetirementAuthority,
+} from "./components/K1ProvisioningPipeline";
+import {
+ backendConnectionTopology,
+ connectionAttemptForRuntimeError,
+ hasControlAuthority,
isConfirmedLiveState,
+ isPhysicalStopRecoverySettling,
+ isRecoveredPhysicalScanning,
+ isReleasedTerminalAcquisitionFailure,
isSourceRuntimeBusy,
+ readOnlyConnectionObservationTarget,
recoverableAcquisition,
+ requiresCanonicalStopAfterTerminalLocalFailure,
+ requiresReadOnlyPhysicalRecovery,
sourceStatusLabel,
} from "./lifecycle";
-import { localizeRuntimeMessage } from "./messages";
import { phaseLabel, phaseTone } from "./presentation";
-import { useXgridsK1Controller } from "./runtimeContext";
+import {
+ useXgridsK1Controller,
+ type XgridsK1Controller,
+} from "./runtimeContext";
+import type { XgridsK1State } from "./api";
+import {
+ DEFAULT_CONNECTION_MODE,
+ type ConnectionMode,
+} from "./configuration";
+
+export { K1OperatorError };
+
+export function shouldRenderK1GenericRuntimeError(
+ error: string | null | undefined,
+ hasCorrelatedConnectionAttempt: boolean,
+ state: XgridsK1State | null | undefined,
+ errorAction?: string | null,
+): boolean {
+ return Boolean(
+ error
+ && !hasCorrelatedConnectionAttempt
+ && !suppressGenericErrorDuringActiveStreamRecovery(state, errorAction),
+ );
+}
+
+export function physicalRecoveryConnectionDetail(
+ state: XgridsK1State | null | undefined,
+): string | null {
+ if (!requiresReadOnlyPhysicalRecovery(state)) return null;
+ const retirementAvailable = Boolean(
+ unavailablePhysicalRetirementAuthority(state),
+ );
+ const readOnlyVerificationAvailable = Boolean(
+ readOnlyConnectionObservationTarget(state)?.serverBound,
+ );
+ if (retirementAvailable && readOnlyVerificationAvailable) {
+ return "Если прежний K1 снова доступен, проверьте его состояние без изменений: проверка читает состояние и не отправляет START, STOP или настройки сети. Если K1 недоступен постоянно или заменён, его можно локально исключить без связи с устройством.";
+ }
+ if (readOnlyVerificationAvailable) {
+ return "Проверьте состояние прежнего K1 без изменений устройства. Проверка использует сохранённое системой подключение и не отправляет START, STOP или настройки сети.";
+ }
+ if (retirementAvailable) {
+ return "Прежний K1 можно локально исключить без связи с устройством: действие не отправляет START, STOP или настройки сети. После этого можно отдельно выбрать другой K1.";
+ }
+ return "Безопасная сверка прежнего K1 сейчас недоступна. Обновите состояние; новые команды устройству заблокированы.";
+}
+
+function connectionPhaseFallbackLabel(phase: string | null | undefined): string {
+ if (phase === "device_selected") return "Выбор выполнен";
+ if (phase === "connected") return "Сетевой адрес получен";
+ return phaseLabel(phase);
+}
+
+/**
+ * Keep the disconnected connection job focused on its progressive pipeline.
+ * Persisted topology is evidence, not live control authority. Operational
+ * panels return only when they are actionable or required to finish an
+ * already-started lifecycle, especially STOP and recovery.
+ */
+export function shouldRenderK1OperationalPanels(
+ state: XgridsK1State | null | undefined,
+): boolean {
+ return Boolean(
+ hasControlAuthority(state)
+ || state?.source_mode === "live"
+ || state?.source_mode === "replay"
+ || recoverableAcquisition(state)
+ || state?.acquisition?.cleanup_pending === true
+ || requiresCanonicalStopAfterTerminalLocalFailure(state)
+ || isRecoveredPhysicalScanning(state)
+ || isPhysicalStopRecoverySettling(state)
+ || activeStreamRecoveryPresentation(state) !== null
+ );
+}
+
+export function K1ConnectionPipelines({
+ controller,
+ desiredConnectionMode,
+ onDesiredConnectionModeChange,
+ operationalPanelsVisible,
+ openSpatialScene,
+ activateAutomaticSpatialSource,
+ sourceLabel,
+}: {
+ controller: XgridsK1Controller;
+ desiredConnectionMode: ConnectionMode;
+ onDesiredConnectionModeChange: (mode: ConnectionMode) => void | Promise;
+ operationalPanelsVisible: boolean;
+ openSpatialScene: () => void;
+ activateAutomaticSpatialSource: () => void;
+ sourceLabel: string;
+}) {
+ return (
+ <>
+ {operationalPanelsVisible ? : null}
+
+