crewly 1.6.4 → 1.6.5

package/dist/cli/backend/src/services/core/crewly-home.utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Crewly home directory resolution utility.
+ *
+ * Single source of truth for resolving the path the Crewly backend
+ * should treat as `~/.crewly` for the current process. Honours the
+ * `CREWLY_HOME` environment variable so test profiles, dry-run kits,
+ * and ESTestNode acceptance harnesses can isolate their state from a
+ * developer's real home directory.
+ *
+ * Why this exists
+ * ---------------
+ * Several callers used to inline `path.join(os.homedir(), '.crewly')`
+ * directly. That pattern silently ignores `CREWLY_HOME`, so a test
+ * harness that exports `CREWLY_HOME=/tmp/...` would still write into
+ * the developer's real `~/.crewly`. That broke:
+ *   - ESTestNode acceptance path
+ *   - Mia's KR3 walkthrough on a `/tmp/...` profile (P0 surfaced
+ *     2026-05-05 during the live walk-through pre-flight)
+ *
+ * Use this helper everywhere the backend needs the Crewly home path.
+ * Do NOT re-implement the env read inline — that is the same
+ * anti-pattern the bug above targeted.
+ *
+ * @module services/core/crewly-home.utils
+ */
+/**
+ * Resolve the Crewly home directory for the current process.
+ *
+ * Priority order:
+ * 1. `process.env.CREWLY_HOME` (highest — for test profiles, dry-run
+ *    kits, and ESTestNode acceptance harnesses).
+ * 2. `path.join(os.homedir(), '.crewly')` (default for normal
+ *    developer / production usage).
+ *
+ * An empty-string `CREWLY_HOME` is treated as unset (returns the
+ * default). A whitespace-only value is treated as set (returned as-is)
+ * — callers that care about that should validate the path themselves.
+ *
+ * @returns Absolute path to the Crewly home directory.
+ *
+ * @example
+ * ```ts
+ * import { getCrewlyHomePath } from './crewly-home.utils.js';
+ *
+ * const teamsDir = path.join(getCrewlyHomePath(), 'teams');
+ * // CREWLY_HOME=/tmp/foo  → /tmp/foo/teams
+ * // CREWLY_HOME unset      → /Users/<user>/.crewly/teams
+ * ```
+ */
+export declare function getCrewlyHomePath(): string;
+//# sourceMappingURL=crewly-home.utils.d.ts.map

package/dist/cli/backend/src/services/core/crewly-home.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crewly-home.utils.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/core/crewly-home.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/cli/backend/src/services/core/crewly-home.utils.js

@@ -0,0 +1,59 @@
+/**
+ * Crewly home directory resolution utility.
+ *
+ * Single source of truth for resolving the path the Crewly backend
+ * should treat as `~/.crewly` for the current process. Honours the
+ * `CREWLY_HOME` environment variable so test profiles, dry-run kits,
+ * and ESTestNode acceptance harnesses can isolate their state from a
+ * developer's real home directory.
+ *
+ * Why this exists
+ * ---------------
+ * Several callers used to inline `path.join(os.homedir(), '.crewly')`
+ * directly. That pattern silently ignores `CREWLY_HOME`, so a test
+ * harness that exports `CREWLY_HOME=/tmp/...` would still write into
+ * the developer's real `~/.crewly`. That broke:
+ *   - ESTestNode acceptance path
+ *   - Mia's KR3 walkthrough on a `/tmp/...` profile (P0 surfaced
+ *     2026-05-05 during the live walk-through pre-flight)
+ *
+ * Use this helper everywhere the backend needs the Crewly home path.
+ * Do NOT re-implement the env read inline — that is the same
+ * anti-pattern the bug above targeted.
+ *
+ * @module services/core/crewly-home.utils
+ */
+import * as os from 'os';
+import * as path from 'path';
+/**
+ * Resolve the Crewly home directory for the current process.
+ *
+ * Priority order:
+ * 1. `process.env.CREWLY_HOME` (highest — for test profiles, dry-run
+ *    kits, and ESTestNode acceptance harnesses).
+ * 2. `path.join(os.homedir(), '.crewly')` (default for normal
+ *    developer / production usage).
+ *
+ * An empty-string `CREWLY_HOME` is treated as unset (returns the
+ * default). A whitespace-only value is treated as set (returned as-is)
+ * — callers that care about that should validate the path themselves.
+ *
+ * @returns Absolute path to the Crewly home directory.
+ *
+ * @example
+ * ```ts
+ * import { getCrewlyHomePath } from './crewly-home.utils.js';
+ *
+ * const teamsDir = path.join(getCrewlyHomePath(), 'teams');
+ * // CREWLY_HOME=/tmp/foo  → /tmp/foo/teams
+ * // CREWLY_HOME unset      → /Users/<user>/.crewly/teams
+ * ```
+ */
+export function getCrewlyHomePath() {
+    const envValue = process.env.CREWLY_HOME;
+    if (envValue && envValue.length > 0) {
+        return envValue;
+    }
+    return path.join(os.homedir(), '.crewly');
+}
+//# sourceMappingURL=crewly-home.utils.js.map

package/dist/cli/backend/src/services/core/crewly-home.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crewly-home.utils.js","sourceRoot":"","sources":["../../../../../../backend/src/services/core/crewly-home.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACzC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC"}

package/dist/cli/backend/src/services/core/state-invariant.types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * State Invariant Types
+ *
+ * Error types and helpers for boot-time state invariant checks (C1 of the
+ * 2026-05-03 persistence-fix spec). The invariant is: a backend MUST NOT
+ * start serving traffic if its on-disk state has been silently wiped while
+ * a healthy backup snapshot exists. Booting in that condition would let
+ * the UI present an "empty teams" page that the user might "fix" by
+ * re-creating teams against the wiped state — destroying recovery options.
+ *
+ * @module services/core/state-invariant.types
+ */
+/**
+ * Environment variable that operators can set to force-boot past an
+ * invariant violation. Used for legitimate first-boot / explicit reset
+ * scenarios where the empty state is intentional.
+ *
+ * Example: `CREWLY_FORCE_EMPTY_BOOT=1 npm start`
+ */
+export declare const FORCE_EMPTY_BOOT_ENV = "CREWLY_FORCE_EMPTY_BOOT";
+/**
+ * Thrown when the boot-time state invariant check detects a mismatch
+ * between live state (empty) and backup state (populated).
+ *
+ * Caller (boot sequence) should catch this and exit before HTTP server
+ * starts, surfacing a clear remediation message.
+ */
+export declare class StateInvariantViolation extends Error {
+    /** Number of teams found in the live state (typically 0 when this fires) */
+    readonly currentTeamCount: number;
+    /** Number of teams found in the most-recent backup snapshot */
+    readonly backupTeamCount: number;
+    /** ISO timestamp of the backup snapshot, if known */
+    readonly backupTimestamp: string | null;
+    /**
+     * Construct a StateInvariantViolation.
+     *
+     * @param message - Human-readable description with remediation hint
+     * @param details - Counts and metadata for structured logging
+     */
+    constructor(message: string, details: {
+        currentTeamCount: number;
+        backupTeamCount: number;
+        backupTimestamp: string | null;
+    });
+}
+/**
+ * Whether the current process has the FORCE_EMPTY_BOOT override active.
+ *
+ * @returns true when the env var is set to a truthy value ('1', 'true', 'yes')
+ */
+export declare function isForceEmptyBootActive(): boolean;
+//# sourceMappingURL=state-invariant.types.d.ts.map

package/dist/cli/backend/src/services/core/state-invariant.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-invariant.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/core/state-invariant.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAE9D;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,4EAA4E;IAC5E,SAAgB,gBAAgB,EAAE,MAAM,CAAC;IACzC,+DAA+D;IAC/D,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC,qDAAqD;IACrD,SAAgB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/C;;;;;OAKG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,gBAAgB,EAAE,MAAM,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC;CAQJ;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAKhD"}

package/dist/cli/backend/src/services/core/state-invariant.types.js

@@ -0,0 +1,61 @@
+/**
+ * State Invariant Types
+ *
+ * Error types and helpers for boot-time state invariant checks (C1 of the
+ * 2026-05-03 persistence-fix spec). The invariant is: a backend MUST NOT
+ * start serving traffic if its on-disk state has been silently wiped while
+ * a healthy backup snapshot exists. Booting in that condition would let
+ * the UI present an "empty teams" page that the user might "fix" by
+ * re-creating teams against the wiped state — destroying recovery options.
+ *
+ * @module services/core/state-invariant.types
+ */
+/**
+ * Environment variable that operators can set to force-boot past an
+ * invariant violation. Used for legitimate first-boot / explicit reset
+ * scenarios where the empty state is intentional.
+ *
+ * Example: `CREWLY_FORCE_EMPTY_BOOT=1 npm start`
+ */
+export const FORCE_EMPTY_BOOT_ENV = 'CREWLY_FORCE_EMPTY_BOOT';
+/**
+ * Thrown when the boot-time state invariant check detects a mismatch
+ * between live state (empty) and backup state (populated).
+ *
+ * Caller (boot sequence) should catch this and exit before HTTP server
+ * starts, surfacing a clear remediation message.
+ */
+export class StateInvariantViolation extends Error {
+    /** Number of teams found in the live state (typically 0 when this fires) */
+    currentTeamCount;
+    /** Number of teams found in the most-recent backup snapshot */
+    backupTeamCount;
+    /** ISO timestamp of the backup snapshot, if known */
+    backupTimestamp;
+    /**
+     * Construct a StateInvariantViolation.
+     *
+     * @param message - Human-readable description with remediation hint
+     * @param details - Counts and metadata for structured logging
+     */
+    constructor(message, details) {
+        super(message);
+        this.name = 'StateInvariantViolation';
+        this.currentTeamCount = details.currentTeamCount;
+        this.backupTeamCount = details.backupTeamCount;
+        this.backupTimestamp = details.backupTimestamp;
+    }
+}
+/**
+ * Whether the current process has the FORCE_EMPTY_BOOT override active.
+ *
+ * @returns true when the env var is set to a truthy value ('1', 'true', 'yes')
+ */
+export function isForceEmptyBootActive() {
+    const v = process.env[FORCE_EMPTY_BOOT_ENV];
+    if (!v)
+        return false;
+    const lower = v.trim().toLowerCase();
+    return lower === '1' || lower === 'true' || lower === 'yes';
+}
+//# sourceMappingURL=state-invariant.types.js.map

package/dist/cli/backend/src/services/core/state-invariant.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-invariant.types.js","sourceRoot":"","sources":["../../../../../../backend/src/services/core/state-invariant.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,4EAA4E;IAC5D,gBAAgB,CAAS;IACzC,+DAA+D;IAC/C,eAAe,CAAS;IACxC,qDAAqD;IACrC,eAAe,CAAgB;IAE/C;;;;;OAKG;IACH,YACE,OAAe,EACf,OAIC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QACjD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IACjD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,KAAK,CAAC;AAC9D,CAAC"}

package/dist/cli/backend/src/services/core/storage.service.d.ts

@@ -59,6 +59,26 @@ export declare class StorageService {
      * @returns Absolute path to the crewly home directory (e.g. ~/.crewly)
      */
     getCrewlyHome(): string;
+    /**
+     * Boot-time state invariant check (C1 of the 2026-05-03 persistence-fix
+     * spec). Compares the current on-disk team count to the latest backup
+     * snapshot. If the live state is empty but a non-empty backup exists,
+     * the invariant has been violated — the backend is refusing to boot
+     * rather than serving an "empty teams" UI that the user might "fix"
+     * by re-creating teams against the wiped state.
+     *
+     * Operators can override via `CREWLY_FORCE_EMPTY_BOOT=1` env var for
+     * legitimate first-boot or explicit-reset scenarios.
+     *
+     * Best-effort: failures inside the backup-status read path log a
+     * warning and do NOT block boot — the invariant should never become a
+     * boot-time hard dependency itself.
+     *
+     * @throws {StateInvariantViolation} when live teams are empty but the
+     *   most-recent backup snapshot has data, and the override env var
+     *   is not set.
+     */
+    verifyStateInvariantOnBoot(): Promise<void>;
     /**
      * Ensures the crewly home and teams directories exist, creating them if necessary
      */

package/dist/cli/backend/src/services/core/storage.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/core/storage.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/core/storage.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/core/storage.service.js

@@ -4,12 +4,14 @@ import { existsSync, mkdirSync, watch } from 'fs';
 import { parse as parseYAML } from 'yaml';
 import { TeamModel, ProjectModel, TicketModel } from '../../models/index.js';
 import { v4 as uuidv4 } from 'uuid';
-import * as os from 'os';
 import { CREWLY_CONSTANTS, RUNTIME_TYPES } from '../../constants.js';
 import { LoggerService } from './logger.service.js';
 import { TeamsBackupService } from './teams-backup.service.js';
+import { getCrewlyHomePath } from './crewly-home.utils.js';
 import { atomicWriteFile, withOperationLock } from '../../utils/file-io.utils.js';
+import { atomicWriteJsonWithGuard } from '../../utils/integrity-guarded-write.utils.js';
 import { addGeminiTrustedFolders, getProjectTrustPaths } from '../../utils/gemini-trusted-folders.js';
+import { StateInvariantViolation, isForceEmptyBootActive, FORCE_EMPTY_BOOT_ENV, } from './state-invariant.types.js';
 export class StorageService {
     static instance = null;
     static instanceHome = null;
@@ -40,7 +42,7 @@ export class StorageService {
     listeners = [];
     constructor(crewlyHome) {
         this.logger = LoggerService.getInstance().createComponentLogger('StorageService');
-        this.crewlyHome = crewlyHome || path.join(os.homedir(), '.crewly');
+        this.crewlyHome = crewlyHome || getCrewlyHomePath();
         this.teamsFile = path.join(this.crewlyHome, 'teams.json'); // Legacy, kept for migration
         this.teamsDir = path.join(this.crewlyHome, 'teams');
         // Orchestrator now uses directory structure: teams/orchestrator/config.json
@@ -59,7 +61,7 @@ export class StorageService {
      * from interfering with each other's file operations
      */
     static getInstance(crewlyHome) {
-        const homeDir = crewlyHome || path.join(os.homedir(), '.crewly');
+        const homeDir = crewlyHome || getCrewlyHomePath();
         // Return existing instance if it matches the same home directory
         if (StorageService.instance && StorageService.instanceHome === homeDir) {
             return StorageService.instance;
@@ -85,6 +87,79 @@ export class StorageService {
     getCrewlyHome() {
         return this.crewlyHome;
     }
+    /**
+     * Boot-time state invariant check (C1 of the 2026-05-03 persistence-fix
+     * spec). Compares the current on-disk team count to the latest backup
+     * snapshot. If the live state is empty but a non-empty backup exists,
+     * the invariant has been violated — the backend is refusing to boot
+     * rather than serving an "empty teams" UI that the user might "fix"
+     * by re-creating teams against the wiped state.
+     *
+     * Operators can override via `CREWLY_FORCE_EMPTY_BOOT=1` env var for
+     * legitimate first-boot or explicit-reset scenarios.
+     *
+     * Best-effort: failures inside the backup-status read path log a
+     * warning and do NOT block boot — the invariant should never become a
+     * boot-time hard dependency itself.
+     *
+     * @throws {StateInvariantViolation} when live teams are empty but the
+     *   most-recent backup snapshot has data, and the override env var
+     *   is not set.
+     */
+    async verifyStateInvariantOnBoot() {
+        let currentTeams;
+        try {
+            currentTeams = await this.getTeams();
+        }
+        catch (loadError) {
+            // If we can't even load teams, defer to the existing error path —
+            // do not synthesize a violation from a load failure.
+            this.logger.warn('Boot invariant check could not load teams; skipping check', {
+                error: loadError instanceof Error ? loadError.message : String(loadError),
+            });
+            return;
+        }
+        let backupStatus;
+        try {
+            const backupService = TeamsBackupService.getInstance(this.crewlyHome);
+            backupStatus = await backupService.getBackupStatus(currentTeams);
+        }
+        catch (statusError) {
+            // Backup-status read failure is non-fatal: better to boot than to
+            // wedge the process on a transient I/O issue with the backup file.
+            this.logger.warn('Boot invariant check could not read backup status; skipping check', { error: statusError instanceof Error ? statusError.message : String(statusError) });
+            return;
+        }
+        if (!backupStatus.hasMismatch) {
+            this.logger.info('Boot invariant check passed', {
+                currentTeamCount: backupStatus.currentTeamCount,
+                backupTeamCount: backupStatus.backupTeamCount,
+            });
+            return;
+        }
+        // hasMismatch === true → currentTeams.length === 0 && backupTeams.length > 0
+        if (isForceEmptyBootActive()) {
+            this.logger.warn('STATE INVARIANT VIOLATED but FORCE_EMPTY_BOOT override active — booting anyway', {
+                envVar: FORCE_EMPTY_BOOT_ENV,
+                backupTeamCount: backupStatus.backupTeamCount,
+                backupTimestamp: backupStatus.backupTimestamp,
+            });
+            return;
+        }
+        this.logger.error('STATE INVARIANT VIOLATED: empty teams but backup has data', {
+            currentTeamCount: backupStatus.currentTeamCount,
+            backupTeamCount: backupStatus.backupTeamCount,
+            backupTimestamp: backupStatus.backupTimestamp,
+        });
+        throw new StateInvariantViolation(`Refusing to start: teams directory is empty but backup contains ` +
+            `${backupStatus.backupTeamCount} teams (snapshot ${backupStatus.backupTimestamp ?? 'unknown'}). ` +
+            `Restore from POST /api/teams/backup/restore (live) or POST /api/teams/backup/restore/:slot (rotating snapshot), ` +
+            `or set ${FORCE_EMPTY_BOOT_ENV}=1 to override.`, {
+            currentTeamCount: backupStatus.currentTeamCount,
+            backupTeamCount: backupStatus.backupTeamCount,
+            backupTimestamp: backupStatus.backupTimestamp,
+        });
+    }
     /**
      * Ensures the crewly home and teams directories exist, creating them if necessary
      */
@@ -714,8 +789,12 @@ export class StorageService {
             else {
                 projects.push(project);
             }
-            const newContent = JSON.stringify(projects, null, 2);
-            await atomicWriteFile(this.projectsFile, newContent);
+            // A1: integrity-guarded write — refuses to wipe out all projects
+            // unless the caller explicitly opts in (delete path uses
+            // allowExplicitDelete).
+            await atomicWriteJsonWithGuard(this.projectsFile, projects, {
+                countOf: (arr) => (Array.isArray(arr) ? arr.length : 0),
+            });
             this.logger.info('Project saved successfully', {
                 projectId: project.id,
                 projectName: project.name,
@@ -1050,7 +1129,10 @@ This is a foundational task that should be completed first before other developm
             else {
                 messages.push(scheduledMessage);
             }
-            await atomicWriteFile(this.scheduledMessagesFile, JSON.stringify(messages, null, 2));
+            // A1: integrity-guarded write — refuses collapse-to-empty
+            await atomicWriteJsonWithGuard(this.scheduledMessagesFile, messages, {
+                countOf: (arr) => (Array.isArray(arr) ? arr.length : 0),
+            });
         }
         catch (error) {
             this.logger.error('Error saving scheduled message', { error: error instanceof Error ? error.message : String(error) });
@@ -1129,7 +1211,10 @@ This is a foundational task that should be completed first before other developm
             else {
                 checks.push(check);
             }
-            await atomicWriteFile(this.recurringChecksFile, JSON.stringify(checks, null, 2));
+            // A1: integrity-guarded write — refuses collapse-to-empty
+            await atomicWriteJsonWithGuard(this.recurringChecksFile, checks, {
+                countOf: (arr) => (Array.isArray(arr) ? arr.length : 0),
+            });
         }
         catch (error) {
             this.logger.error('Error saving recurring check', {
@@ -1222,7 +1307,10 @@ This is a foundational task that should be completed first before other developm
             else {
                 checks.push(check);
             }
-            await atomicWriteFile(this.oneTimeChecksFile, JSON.stringify(checks, null, 2));
+            // A1: integrity-guarded write — refuses collapse-to-empty
+            await atomicWriteJsonWithGuard(this.oneTimeChecksFile, checks, {
+                countOf: (arr) => (Array.isArray(arr) ? arr.length : 0),
+            });
         }
         catch (error) {
             this.logger.error('Error saving one-time check', {