crewly 1.6.4 → 1.6.5

package/dist/backend/backend/src/utils/esm-require.utils.js

@@ -0,0 +1,124 @@
+/**
+ * ESM/CJS-dual-mode helpers for the lazy `nodeRequire` pattern.
+ *
+ * Background
+ * ----------
+ * Several services in this codebase use the canonical `nodeRequire` pattern
+ * (commit `070cd3e5` — `fix(esm): anchor createRequire to process.argv[1]`)
+ * to lazily load modules without forcing every test that transitively imports
+ * them to mock the dependency. The pattern looks like:
+ *
+ *     const nodeRequire: NodeRequire =
+ *       typeof require === 'function'
+ *         ? require
+ *         : createRequire(pathToFileURL(process.argv[1] || process.cwd()).href);
+ *
+ * That pattern works **only** for npm-package targets (e.g.
+ * `nodeRequire('better-sqlite3')`) — Node's resolver walks UP from the anchor
+ * (`process.argv[1]`) to find `node_modules`, so the anchor's exact location
+ * does not matter for package resolution.
+ *
+ * It silently breaks for **relative project paths** like
+ * `nodeRequire('../v3/request.service.js')`. In production ESM, the relative
+ * spec is resolved against `process.argv[1]` (the entry script) — NOT against
+ * the calling module — so the require fails with `Cannot find module …`. In
+ * tests (ts-jest CJS transpile) the per-module `require` parameter is used
+ * instead, so the relative spec resolves correctly against the calling file
+ * and the bug stays hidden.
+ *
+ * Symptom that motivated this helper: `core/get-my-active-work` returned 500
+ * with "Cannot find module '../v3/request.service.js'" because
+ * `ActiveWorkBriefingService.getInstance()` called
+ * `nodeRequire('../v3/request.service.js')` from
+ * `services/agent/active-work-briefing.service.js` while `nodeRequire` was
+ * anchored to `dist/backend/backend/src/index.js`.
+ *
+ * What this helper does
+ * ---------------------
+ * `resolveProjectModulePath(testRelativePath, prodPathFromEntryDir)` returns:
+ *
+ * 1. In test mode (`typeof require === 'function'` — ts-jest CJS) — the
+ *    `testRelativePath` unchanged, so the per-module CJS require resolves it
+ *    relative to the calling file (its existing, working behavior).
+ * 2. In production ESM — an absolute path computed by joining
+ *    `path.dirname(process.argv[1])` with `prodPathFromEntryDir`.
+ *    Absolute paths are accepted by `nodeRequire` regardless of anchor.
+ *
+ * Why this is two-arg rather than one
+ * -----------------------------------
+ * We considered single-arg variants:
+ *   • `import.meta.url` — triggers TS1343 under ts-jest's CJS target. Even with
+ *     `// @ts-expect-error`, ts-jest's transpile may still fail at parse.
+ *   • `new Function('return import.meta.url')()` — was tried (PR #323) and is
+ *     forbidden — `new Function` evaluates in non-module scope where
+ *     `import.meta` is a SyntaxError. Crashed production at startup.
+ *   • `eval('import.meta.url')` — works at runtime via direct-eval scope
+ *     inheritance, but trips ESLint `no-eval` and is fragile across engines.
+ *   • Stack-trace introspection — gross and slow.
+ *
+ * Asking the caller to spell out **two** equivalent paths (one usable from the
+ * caller's perspective, one usable from the entry script's perspective) is
+ * verbose but unambiguous, parse-clean under both TS targets, and free of any
+ * runtime tricks.
+ *
+ * Usage
+ * -----
+ *     // Caller is at `backend/src/services/agent/active-work-briefing.service.ts`
+ *     // Target is at `backend/src/services/v3/request.service.ts`
+ *     // Entry script (process.argv[1]) is `dist/backend/backend/src/index.js`
+ *     // → from the caller's perspective: `../v3/request.service.js`
+ *     // → from the entry-script-dir's perspective: `services/v3/request.service.js`
+ *
+ *     const spec = resolveProjectModulePath(
+ *       '../v3/request.service.js',
+ *       'services/v3/request.service.js',
+ *     );
+ *     const { RequestService } = nodeRequire(spec);
+ *
+ * Test guard
+ * ----------
+ * `esm-require.utils.test.ts` exercises both branches and locks the contract
+ * (test branch ↔ untouched relative path; prod branch ↔ absolute path joined
+ * to `process.argv[1]`'s dirname).
+ *
+ * @module utils/esm-require.utils
+ */
+import path from 'path';
+/**
+ * Resolves a project-relative require spec to a string safe to pass to
+ * `nodeRequire` in both ts-jest CJS test mode and production ESM mode.
+ *
+ * @param testRelativePath - The require spec written from the calling file's
+ *   perspective. Used verbatim in test mode (ts-jest CJS) where each module
+ *   gets its own `require` and relative resolution Just Works. Example:
+ *   `'../v3/request.service.js'`.
+ * @param prodPathFromEntryDir - The require spec rewritten as a path under
+ *   `path.dirname(process.argv[1])`. Used in production ESM where
+ *   `nodeRequire` is anchored to the entry script. Example:
+ *   `'services/v3/request.service.js'` (under `dist/backend/backend/src/`).
+ * @returns A string suitable for `nodeRequire(...)`.
+ *
+ * @example
+ * ```typescript
+ * const { RequestService } = nodeRequire(
+ *   resolveProjectModulePath(
+ *     '../v3/request.service.js',
+ *     'services/v3/request.service.js',
+ *   ),
+ * );
+ * ```
+ */
+export function resolveProjectModulePath(testRelativePath, prodPathFromEntryDir) {
+    // The same `typeof require` probe the canonical `nodeRequire` pattern uses.
+    // Under ts-jest's CJS transpile, the per-module `require` parameter is
+    // defined and is the correct anchor for relative resolution. Under
+    // production ESM, `require` is undefined globally and we must hand
+    // `nodeRequire` an absolute path.
+    if (typeof require === 'function') {
+        return testRelativePath;
+    }
+    const entryScript = process.argv[1] || process.cwd();
+    const entryDir = path.dirname(entryScript);
+    return path.join(entryDir, prodPathFromEntryDir);
+}
+//# sourceMappingURL=esm-require.utils.js.map

package/dist/backend/backend/src/utils/esm-require.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"esm-require.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/esm-require.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,wBAAwB,CACtC,gBAAwB,EACxB,oBAA4B;IAE5B,4EAA4E;IAC5E,uEAAuE;IACvE,mEAAmE;IACnE,mEAAmE;IACnE,kCAAkC;IAClC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;AACnD,CAAC"}

package/dist/backend/backend/src/utils/integrity-guarded-write.utils.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Integrity-Guarded Atomic Write Utilities
+ *
+ * Wraps {@link atomicWriteJson} with a write-time integrity invariant
+ * (a "decrease-guard"): rejects suspicious writes that would persist a
+ * collection that has shrunk too aggressively versus the on-disk state.
+ *
+ * **Why this exists**
+ *
+ * On 2026-05-03, a backend restart corrupted `~/.crewly/teams.json` and
+ * every per-project `teams/{id}/config.json` to `teams: []`. Atomic writes
+ * already covered the *transactional* side of the persistence layer, but
+ * the gap was at the *semantic* level — any code path that emitted
+ * `teams: []` (whether via race during shutdown, destructive migration, or
+ * cache nuke + flush) would happily atomic-write the empty state and
+ * overwrite the single-snapshot backup as well.
+ *
+ * This utility closes that gap by reading the existing on-disk count
+ * before every aggregate write and aborting if the count would drop from
+ * N>0 to 0 (or by an unacceptable percentage) without explicit operator
+ * intent. Callers who legitimately want to clear a collection pass
+ * `allowExplicitDelete: true`.
+ *
+ * **Design contract**
+ *
+ * - **Failure mode**: integrity violations throw {@link IntegrityViolationError}
+ *   so the failure surfaces loudly instead of being silently swallowed.
+ *   Callers that prefer "log + continue" semantics should wrap with their
+ *   own try/catch.
+ * - **First-ever write** (no prior file) is always allowed — `prevCount = 0`,
+ *   no decrease.
+ * - **Read failure**: if the prior file exists but cannot be read or parsed,
+ *   the guard treats `prevCount` as `null` and proceeds with the write
+ *   (a corrupted prior file should not block recovery).
+ *
+ * @module utils/integrity-guarded-write.utils
+ */
+/**
+ * Thrown when a guarded write is rejected because it would shrink the
+ * persisted collection past the decrease threshold without explicit
+ * operator opt-in.
+ *
+ * Carries diagnostic metadata (path, prevCount, nextCount, reason) for
+ * structured logging and debugging.
+ */
+export declare class IntegrityViolationError extends Error {
+    /** Absolute path of the file the rejected write targeted */
+    readonly path: string;
+    /** Item count read from the prior on-disk state */
+    readonly prevCount: number;
+    /** Item count of the rejected next state */
+    readonly nextCount: number;
+    /** Machine-readable reason code */
+    readonly reason: 'collapse-to-empty' | 'decrease-exceeds-threshold';
+    /**
+     * @param message - Human-readable error message
+     * @param details - Diagnostic metadata
+     */
+    constructor(message: string, details: {
+        path: string;
+        prevCount: number;
+        nextCount: number;
+        reason: IntegrityViolationError['reason'];
+    });
+}
+/**
+ * Options for {@link atomicWriteJsonWithGuard}.
+ */
+export interface IntegrityGuardOptions<T> {
+    /**
+     * Function that extracts the "item count" from a value (parsed prior
+     * state or proposed next state). Defaults to `(d) => Array.isArray(d) ? d.length : 0`,
+     * suitable for plain array-shaped collections.
+     */
+    countOf?: (data: T) => number;
+    /**
+     * Maximum allowed decrease as a percentage of the prior count.
+     * Default 50 — i.e., next count must be ≥ ceil(prevCount / 2).
+     * Pass 100 to allow any decrease (effectively only the
+     * collapse-to-empty branch fires).
+     */
+    maxDecreasePct?: number;
+    /**
+     * If true, bypass the decrease and collapse-to-empty guards. Use this
+     * for legitimate "clear all" or "delete N" operations where the caller
+     * has confirmed operator intent.
+     */
+    allowExplicitDelete?: boolean;
+}
+/**
+ * Atomically write a JSON file, rejecting writes that would shrink an
+ * existing collection past the decrease threshold without explicit opt-in.
+ *
+ * **Behavior**:
+ * 1. If the destination file does not exist → first-ever write → proceed.
+ * 2. If the prior file exists but cannot be read/parsed → log warning,
+ *    proceed (corrupted prior should not block recovery).
+ * 3. If `prevCount > 0 && nextCount === 0 && !allowExplicitDelete`
+ *    → throw {@link IntegrityViolationError} with `reason: 'collapse-to-empty'`.
+ * 4. If `nextCount < prevCount * (1 - maxDecreasePct/100) && !allowExplicitDelete`
+ *    → throw {@link IntegrityViolationError} with `reason: 'decrease-exceeds-threshold'`.
+ * 5. Otherwise → call {@link atomicWriteJson}.
+ *
+ * @param filePath - Destination JSON file path
+ * @param next - Value to serialize and write
+ * @param opts - Guard configuration
+ * @throws {IntegrityViolationError} if the guard rejects the write
+ * @throws The underlying fs error if the atomic write itself fails
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteJsonWithGuard(teamsPath, teams, {
+ *   countOf: (t) => t.length,
+ *   maxDecreasePct: 50,
+ * });
+ * ```
+ */
+export declare function atomicWriteJsonWithGuard<T>(filePath: string, next: T, opts?: IntegrityGuardOptions<T>): Promise<void>;
+//# sourceMappingURL=integrity-guarded-write.utils.d.ts.map

package/dist/backend/backend/src/utils/integrity-guarded-write.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-guarded-write.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/integrity-guarded-write.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AA4BH;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,4BAA4B,CAAC;IAEpE;;;OAGG;gBAED,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAA;KAAE;CAS7G;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,EACP,IAAI,GAAE,qBAAqB,CAAC,CAAC,CAAM,GAClC,OAAO,CAAC,IAAI,CAAC,CAgEf"}

package/dist/backend/backend/src/utils/integrity-guarded-write.utils.js

@@ -0,0 +1,212 @@
+/**
+ * Integrity-Guarded Atomic Write Utilities
+ *
+ * Wraps {@link atomicWriteJson} with a write-time integrity invariant
+ * (a "decrease-guard"): rejects suspicious writes that would persist a
+ * collection that has shrunk too aggressively versus the on-disk state.
+ *
+ * **Why this exists**
+ *
+ * On 2026-05-03, a backend restart corrupted `~/.crewly/teams.json` and
+ * every per-project `teams/{id}/config.json` to `teams: []`. Atomic writes
+ * already covered the *transactional* side of the persistence layer, but
+ * the gap was at the *semantic* level — any code path that emitted
+ * `teams: []` (whether via race during shutdown, destructive migration, or
+ * cache nuke + flush) would happily atomic-write the empty state and
+ * overwrite the single-snapshot backup as well.
+ *
+ * This utility closes that gap by reading the existing on-disk count
+ * before every aggregate write and aborting if the count would drop from
+ * N>0 to 0 (or by an unacceptable percentage) without explicit operator
+ * intent. Callers who legitimately want to clear a collection pass
+ * `allowExplicitDelete: true`.
+ *
+ * **Design contract**
+ *
+ * - **Failure mode**: integrity violations throw {@link IntegrityViolationError}
+ *   so the failure surfaces loudly instead of being silently swallowed.
+ *   Callers that prefer "log + continue" semantics should wrap with their
+ *   own try/catch.
+ * - **First-ever write** (no prior file) is always allowed — `prevCount = 0`,
+ *   no decrease.
+ * - **Read failure**: if the prior file exists but cannot be read or parsed,
+ *   the guard treats `prevCount` as `null` and proceeds with the write
+ *   (a corrupted prior file should not block recovery).
+ *
+ * @module utils/integrity-guarded-write.utils
+ */
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import { atomicWriteJson } from './file-io.utils.js';
+import { LoggerService } from '../services/core/logger.service.js';
+/**
+ * Default maximum decrease percentage (compared to prior on-disk count)
+ * tolerated before the guard rejects a write.
+ *
+ * 50% means: if prior had N items, next must have at least ceil(N/2) items
+ * unless `allowExplicitDelete: true` is set.
+ */
+const DEFAULT_MAX_DECREASE_PCT = 50;
+/**
+ * Logger lazily acquired so this module can be imported by tests that
+ * mock the logger service before initialization.
+ */
+let logger = null;
+function getLogger() {
+    if (!logger) {
+        logger = LoggerService.getInstance().createComponentLogger('IntegrityGuardedWrite');
+    }
+    return logger;
+}
+/**
+ * Thrown when a guarded write is rejected because it would shrink the
+ * persisted collection past the decrease threshold without explicit
+ * operator opt-in.
+ *
+ * Carries diagnostic metadata (path, prevCount, nextCount, reason) for
+ * structured logging and debugging.
+ */
+export class IntegrityViolationError extends Error {
+    /** Absolute path of the file the rejected write targeted */
+    path;
+    /** Item count read from the prior on-disk state */
+    prevCount;
+    /** Item count of the rejected next state */
+    nextCount;
+    /** Machine-readable reason code */
+    reason;
+    /**
+     * @param message - Human-readable error message
+     * @param details - Diagnostic metadata
+     */
+    constructor(message, details) {
+        super(message);
+        this.name = 'IntegrityViolationError';
+        this.path = details.path;
+        this.prevCount = details.prevCount;
+        this.nextCount = details.nextCount;
+        this.reason = details.reason;
+    }
+}
+/**
+ * Atomically write a JSON file, rejecting writes that would shrink an
+ * existing collection past the decrease threshold without explicit opt-in.
+ *
+ * **Behavior**:
+ * 1. If the destination file does not exist → first-ever write → proceed.
+ * 2. If the prior file exists but cannot be read/parsed → log warning,
+ *    proceed (corrupted prior should not block recovery).
+ * 3. If `prevCount > 0 && nextCount === 0 && !allowExplicitDelete`
+ *    → throw {@link IntegrityViolationError} with `reason: 'collapse-to-empty'`.
+ * 4. If `nextCount < prevCount * (1 - maxDecreasePct/100) && !allowExplicitDelete`
+ *    → throw {@link IntegrityViolationError} with `reason: 'decrease-exceeds-threshold'`.
+ * 5. Otherwise → call {@link atomicWriteJson}.
+ *
+ * @param filePath - Destination JSON file path
+ * @param next - Value to serialize and write
+ * @param opts - Guard configuration
+ * @throws {IntegrityViolationError} if the guard rejects the write
+ * @throws The underlying fs error if the atomic write itself fails
+ *
+ * @example
+ * ```typescript
+ * await atomicWriteJsonWithGuard(teamsPath, teams, {
+ *   countOf: (t) => t.length,
+ *   maxDecreasePct: 50,
+ * });
+ * ```
+ */
+export async function atomicWriteJsonWithGuard(filePath, next, opts = {}) {
+    const countOf = opts.countOf ?? defaultCountOf;
+    const maxDecreasePct = opts.maxDecreasePct ?? DEFAULT_MAX_DECREASE_PCT;
+    const allowExplicitDelete = opts.allowExplicitDelete ?? false;
+    const nextCount = countOf(next);
+    const prevCount = await readPriorCount(filePath, countOf);
+    if (prevCount === null) {
+        // No prior file or unreadable — proceed without guard.
+        await atomicWriteJson(filePath, next);
+        return;
+    }
+    if (!allowExplicitDelete) {
+        // Branch 3: collapse-to-empty
+        if (prevCount > 0 && nextCount === 0) {
+            const message = `Refusing to write empty collection: prior had ${prevCount} item(s), next would have 0. ` +
+                `If this is intentional, pass allowExplicitDelete: true. Path: ${filePath}`;
+            getLogger().error('integrity:write-rejected', {
+                path: filePath,
+                prevCount,
+                nextCount,
+                reason: 'collapse-to-empty',
+                stack: new Error('decrease-guard trace').stack,
+            });
+            throw new IntegrityViolationError(message, {
+                path: filePath,
+                prevCount,
+                nextCount,
+                reason: 'collapse-to-empty',
+            });
+        }
+        // Branch 4: decrease exceeds threshold
+        if (prevCount > 0 && maxDecreasePct < 100) {
+            const minAllowed = Math.ceil(prevCount * (1 - maxDecreasePct / 100));
+            if (nextCount < minAllowed) {
+                const message = `Refusing to write shrunken collection: prior had ${prevCount} item(s), next would have ` +
+                    `${nextCount} (below ${maxDecreasePct}%-decrease threshold of ${minAllowed}). ` +
+                    `If this is intentional, pass allowExplicitDelete: true. Path: ${filePath}`;
+                getLogger().error('integrity:write-rejected', {
+                    path: filePath,
+                    prevCount,
+                    nextCount,
+                    maxDecreasePct,
+                    minAllowed,
+                    reason: 'decrease-exceeds-threshold',
+                    stack: new Error('decrease-guard trace').stack,
+                });
+                throw new IntegrityViolationError(message, {
+                    path: filePath,
+                    prevCount,
+                    nextCount,
+                    reason: 'decrease-exceeds-threshold',
+                });
+            }
+        }
+    }
+    // Guard passed (or bypassed). Proceed with the atomic write.
+    await atomicWriteJson(filePath, next);
+}
+/**
+ * Default countOf implementation: returns array length, or 0 for non-arrays.
+ *
+ * @param data - Parsed prior state or proposed next state
+ * @returns Item count
+ */
+function defaultCountOf(data) {
+    return Array.isArray(data) ? data.length : 0;
+}
+/**
+ * Read the prior on-disk JSON file and apply countOf.
+ *
+ * @param filePath - File to read
+ * @param countOf - Counter function
+ * @returns The prior count, or null if the file does not exist or cannot be parsed
+ */
+async function readPriorCount(filePath, countOf) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        if (!raw.trim())
+            return null;
+        const parsed = JSON.parse(raw);
+        return countOf(parsed);
+    }
+    catch (error) {
+        getLogger().warn('integrity:prior-read-failed', {
+            path: filePath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+}
+//# sourceMappingURL=integrity-guarded-write.utils.js.map

package/dist/backend/backend/src/utils/integrity-guarded-write.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity-guarded-write.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/integrity-guarded-write.utils.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/utils/native-binding.utils.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Native-binding fail-fast helpers.
+ *
+ * When a native Node addon (e.g. `better-sqlite3`, `node-pty`,
+ * `sqlite-vec-darwin-*`) is built for the wrong CPU/ABI and Node tries
+ * to `dlopen` it, the loader emits a recognisable error pattern:
+ *
+ * ```
+ * dlopen .../foo.node, 0x0001
+ * mach-o file, but is an incompatible architecture
+ * (have 'x86_64', need 'arm64e' or 'arm64')
+ * ```
+ *
+ * This module exists for one reason: those errors must NEVER be
+ * silently swallowed by a try/catch wrapper at the gateway layer
+ * (which used to downgrade chat-v2 to a JSON-file fallback while
+ * `chat.db` quietly went stale — F-CYCLE7-1, audit 2026-05-07 §2.1).
+ *
+ * The contract:
+ *
+ *   1. {@link loadNativeAddonOrFatal} wraps `require(name)`.
+ *   2. If the require throws and the error matches a known native-arch
+ *      / dlopen pattern, we rethrow as {@link NativeBindingFatalError},
+ *      which carries `fatal: true`.
+ *   3. The boot-time wiring (`backend/src/index.ts`, the chat-v2 init
+ *      try/catch) inspects caught errors with {@link isNativeBindingFatalError}
+ *      and **rethrows fatal errors** rather than logging them as
+ *      "non-critical". This crashes the process at boot — which is the
+ *      desired behaviour: an arch-mismatched binary can be fixed by
+ *      `npm rebuild <pkg> --build-from-source`, but only if the operator
+ *      sees the failure.
+ *
+ * @module utils/native-binding.utils
+ */
+/**
+ * Marker class for native-binding failures that MUST crash the
+ * process at boot rather than be downgraded to a runtime fallback.
+ *
+ * Holds the original underlying error in `cause` so logs surface
+ * the full dlopen trace.
+ */
+export declare class NativeBindingFatalError extends Error {
+    /** Discriminator readable by `instanceof` and structural callers. */
+    readonly fatal: true;
+    /**
+     * The npm package name that failed to load (`'better-sqlite3'`,
+     * `'node-pty'`, etc.). Used in the boot-failure log line and the
+     * remediation hint that follows it.
+     */
+    readonly moduleName: string;
+    /**
+     * The original error thrown by `require(name)`. Preserved for log
+     * fidelity — the dlopen line itself is the most useful piece of
+     * context for whoever has to run the rebuild.
+     */
+    readonly cause: unknown;
+    /**
+     * Build a fatal-error wrapper.
+     *
+     * @param moduleName - The npm package that failed to load
+     * @param cause - The underlying error from the failed require
+     * @param remediation - One-line remediation hint shown in the message
+     *   (default: `npm rebuild <moduleName> --build-from-source`)
+     */
+    constructor(moduleName: string, cause: unknown, remediation?: string);
+}
+/**
+ * Type guard for {@link NativeBindingFatalError}. Survives realm
+ * boundaries (unlike a bare `instanceof`) by also checking the
+ * structural `fatal === true` + `name === 'NativeBindingFatalError'`
+ * shape — useful when the same module is loaded via two different
+ * resolver paths (ts-jest vs. native ESM) and `instanceof` would
+ * unexpectedly miss.
+ *
+ * @param err - Any thrown value
+ * @returns True iff the error is a fatal native-binding load failure
+ */
+export declare function isNativeBindingFatalError(err: unknown): err is NativeBindingFatalError;
+/**
+ * Decide whether the given error indicates a native-addon arch / ABI
+ * mismatch (vs. a benign "package not installed" error or a runtime
+ * SQL bug from inside the addon).
+ *
+ * Stable, narrow behaviour — only matches the patterns in
+ * {@link FATAL_NATIVE_PATTERNS}. Callers can refine further by
+ * inspecting `err.code === 'ERR_DLOPEN_FAILED'` (Node ≥ 16 emits this
+ * for any failed `dlopen`, including arch mismatches) before calling
+ * this helper if they want a broader net.
+ *
+ * @param err - Any thrown value
+ * @returns True iff the error message matches a known native-mismatch pattern
+ */
+export declare function isNativeArchMismatchError(err: unknown): boolean;
+/**
+ * Load a native Node addon by name, escalating arch / ABI mismatches
+ * to {@link NativeBindingFatalError}.
+ *
+ * Behaviour:
+ *   - On success: returns the require'd module unchanged.
+ *   - On failure that matches {@link isNativeArchMismatchError}:
+ *     throws {@link NativeBindingFatalError}.
+ *   - On any other failure (e.g. `Cannot find module 'foo'` because
+ *     the package isn't installed at all): rethrows the original
+ *     error unchanged, so callers can keep their existing
+ *     "package missing → soft error" semantics.
+ *
+ * @param moduleName - Package name (`'better-sqlite3'`, `'node-pty'`)
+ * @param requireFn - The CJS-style require to use (typically the result
+ *   of `createBareModuleRequire(...)` from `node-require.utils.ts`)
+ * @param remediation - Optional override for the remediation hint shown
+ *   in the wrapped error message
+ * @returns The loaded module
+ *
+ * @throws {NativeBindingFatalError} when the require fails with a
+ *   recognised native-arch / ABI / dlopen pattern.
+ *
+ * @example
+ * ```ts
+ * import { loadNativeAddonOrFatal } from '../../utils/native-binding.utils.js';
+ *
+ * const Database = loadNativeAddonOrFatal<typeof import('better-sqlite3')>(
+ *   'better-sqlite3',
+ *   nodeRequire,
+ * );
+ * ```
+ */
+export declare function loadNativeAddonOrFatal<T = unknown>(moduleName: string, requireFn: NodeRequire, remediation?: string): T;
+//# sourceMappingURL=native-binding.utils.d.ts.map

package/dist/backend/backend/src/utils/native-binding.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-binding.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/native-binding.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,qEAAqE;IACrE,SAAgB,KAAK,EAAG,IAAI,CAAU;IAEtC;;;;OAIG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;;;OAIG;IACH,SAAyB,KAAK,EAAE,OAAO,CAAC;IAExC;;;;;;;OAOG;gBACS,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM;CAiBpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,GAAG,EAAE,OAAO,GACV,GAAG,IAAI,uBAAuB,CAWhC;AAqCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQ/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EACjD,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,WAAW,EACtB,WAAW,CAAC,EAAE,MAAM,GAClB,CAAC,CASH"}