crewly 1.13.0 → 1.13.1

package/dist/cli/backend/src/types/v2/workspace.types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * V2 Shared Workspace Type Definitions
+ *
+ * A Workspace is a structured, versioned JSON document that agents can
+ * read and write. Optimistic locking (CAS — Compare-And-Swap) ensures
+ * consistency: writes must include the expectedVersion, and fail with
+ * a conflict if another writer has updated the document since the read.
+ *
+ * Usage discipline (CEO requirement):
+ * - Each workspace has an owner (agent/team/system)
+ * - Schema defines allowed structure
+ * - Access mode controls append vs overwrite
+ * - Ownership prevents unauthorized writes
+ *
+ * @module types/v2/workspace.types
+ */
+/**
+ * Access mode for workspace writes.
+ * - overwrite: Replace entire data on write
+ * - append: Merge/append new data to existing
+ * - structured: Write to specific paths within the document
+ */
+export type WorkspaceAccessMode = 'overwrite' | 'append' | 'structured';
+/** All valid access modes. */
+export declare const WORKSPACE_ACCESS_MODES: readonly WorkspaceAccessMode[];
+/**
+ * Who owns the workspace.
+ */
+export type WorkspaceOwnerType = 'agent' | 'team' | 'mission' | 'system';
+/** All valid owner types. */
+export declare const WORKSPACE_OWNER_TYPES: readonly WorkspaceOwnerType[];
+/**
+ * A versioned, structured JSON workspace.
+ *
+ * Each write increments the version counter. Reads return the current
+ * version, which must be passed back on writes for CAS validation.
+ */
+export interface Workspace {
+    /** UUID v4 */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Who owns this workspace */
+    ownerType: WorkspaceOwnerType;
+    /** Owner identifier (agent session, team ID, mission ID, or 'system') */
+    ownerId: string;
+    /** Access mode — how data can be modified */
+    accessMode: WorkspaceAccessMode;
+    /** The actual workspace data (arbitrary JSON-serializable object) */
+    data: Record<string, unknown>;
+    /** Monotonically increasing version number (starts at 1) */
+    version: number;
+    /** Which sessions are allowed to write (empty = owner only) */
+    allowedWriters: string[];
+    /** ISO8601 timestamps */
+    createdAt: string;
+    updatedAt: string;
+    /** Who last wrote to this workspace */
+    lastWrittenBy?: string;
+}
+/**
+ * Input for creating a new Workspace.
+ */
+export interface CreateWorkspaceInput {
+    name: string;
+    description?: string;
+    ownerType: WorkspaceOwnerType;
+    ownerId: string;
+    accessMode?: WorkspaceAccessMode;
+    data?: Record<string, unknown>;
+    allowedWriters?: string[];
+}
+/**
+ * Input for writing to a workspace.
+ * Requires expectedVersion for CAS validation.
+ */
+export interface WriteWorkspaceInput {
+    /** The version the client believes is current — CAS check */
+    expectedVersion: number;
+    /** New data to write (interpretation depends on accessMode) */
+    data: Record<string, unknown>;
+    /** Who is performing the write */
+    writerId: string;
+}
+/**
+ * Input for a structured write to a specific path.
+ */
+export interface StructuredWriteInput {
+    /** The version the client believes is current */
+    expectedVersion: number;
+    /** Dot-notation path to write to (e.g., "results.phase1") */
+    path: string;
+    /** Value to set at the path */
+    value: unknown;
+    /** Who is performing the write */
+    writerId: string;
+}
+/**
+ * Error thrown when a CAS conflict occurs.
+ * The client's expectedVersion doesn't match the current version.
+ */
+export declare class WorkspaceConflictError extends Error {
+    readonly workspaceId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    constructor(workspaceId: string, expectedVersion: number, actualVersion: number);
+}
+/**
+ * Error thrown when a writer is not authorized.
+ */
+export declare class WorkspaceAccessError extends Error {
+    readonly workspaceId: string;
+    readonly writerId: string;
+    constructor(workspaceId: string, writerId: string);
+}
+/**
+ * Checks whether a string is a valid WorkspaceAccessMode.
+ */
+export declare function isValidWorkspaceAccessMode(value: string): value is WorkspaceAccessMode;
+/**
+ * Checks whether a string is a valid WorkspaceOwnerType.
+ */
+export declare function isValidWorkspaceOwnerType(value: string): value is WorkspaceOwnerType;
+/**
+ * Validates that an unknown value is structurally a valid Workspace.
+ */
+export declare function isWorkspace(value: unknown): value is Workspace;
+/**
+ * Validates CreateWorkspaceInput.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export declare function validateCreateWorkspaceInput(input: CreateWorkspaceInput): string[];
+/**
+ * Validates WriteWorkspaceInput.
+ */
+export declare function validateWriteWorkspaceInput(input: WriteWorkspaceInput): string[];
+/**
+ * Creates a new Workspace with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated Workspace at version 1
+ *
+ * @example
+ * ```typescript
+ * const ws = createWorkspace({
+ *   name: 'Sprint 1 Results',
+ *   ownerType: 'team',
+ *   ownerId: 'team-product',
+ * });
+ * ```
+ */
+export declare function createWorkspace(input: CreateWorkspaceInput): Workspace;
+//# sourceMappingURL=workspace.types.d.ts.map

package/dist/cli/backend/src/types/v2/workspace.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/types/v2/workspace.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAExE,8BAA8B;AAC9B,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAIvD,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzE,6BAA6B;AAC7B,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAKrD,CAAC;AAMX;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,EAAE,mBAAmB,CAAC;IAChC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,WAAW,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAShF;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAMlD;AAMD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,mBAAmB,CAEtF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAEpF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAiB9D;AAMD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAelF;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,EAAE,CAYhF;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAetE"}

package/dist/cli/backend/src/types/v2/workspace.types.js

@@ -0,0 +1,173 @@
+/**
+ * V2 Shared Workspace Type Definitions
+ *
+ * A Workspace is a structured, versioned JSON document that agents can
+ * read and write. Optimistic locking (CAS — Compare-And-Swap) ensures
+ * consistency: writes must include the expectedVersion, and fail with
+ * a conflict if another writer has updated the document since the read.
+ *
+ * Usage discipline (CEO requirement):
+ * - Each workspace has an owner (agent/team/system)
+ * - Schema defines allowed structure
+ * - Access mode controls append vs overwrite
+ * - Ownership prevents unauthorized writes
+ *
+ * @module types/v2/workspace.types
+ */
+import { v4 as uuidv4 } from 'uuid';
+/** All valid access modes. */
+export const WORKSPACE_ACCESS_MODES = [
+    'overwrite',
+    'append',
+    'structured',
+];
+/** All valid owner types. */
+export const WORKSPACE_OWNER_TYPES = [
+    'agent',
+    'team',
+    'mission',
+    'system',
+];
+// ---------------------------------------------------------------------------
+// CAS Error
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown when a CAS conflict occurs.
+ * The client's expectedVersion doesn't match the current version.
+ */
+export class WorkspaceConflictError extends Error {
+    workspaceId;
+    expectedVersion;
+    actualVersion;
+    constructor(workspaceId, expectedVersion, actualVersion) {
+        super(`Workspace conflict: expected version ${expectedVersion} but current is ${actualVersion}`);
+        this.name = 'WorkspaceConflictError';
+        this.workspaceId = workspaceId;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+    }
+}
+/**
+ * Error thrown when a writer is not authorized.
+ */
+export class WorkspaceAccessError extends Error {
+    workspaceId;
+    writerId;
+    constructor(workspaceId, writerId) {
+        super(`Access denied: '${writerId}' is not authorized to write to workspace '${workspaceId}'`);
+        this.name = 'WorkspaceAccessError';
+        this.workspaceId = workspaceId;
+        this.writerId = writerId;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether a string is a valid WorkspaceAccessMode.
+ */
+export function isValidWorkspaceAccessMode(value) {
+    return WORKSPACE_ACCESS_MODES.includes(value);
+}
+/**
+ * Checks whether a string is a valid WorkspaceOwnerType.
+ */
+export function isValidWorkspaceOwnerType(value) {
+    return WORKSPACE_OWNER_TYPES.includes(value);
+}
+/**
+ * Validates that an unknown value is structurally a valid Workspace.
+ */
+export function isWorkspace(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.id === 'string' &&
+        typeof obj.name === 'string' &&
+        typeof obj.ownerType === 'string' &&
+        isValidWorkspaceOwnerType(obj.ownerType) &&
+        typeof obj.ownerId === 'string' &&
+        typeof obj.accessMode === 'string' &&
+        isValidWorkspaceAccessMode(obj.accessMode) &&
+        typeof obj.data === 'object' && obj.data !== null &&
+        typeof obj.version === 'number' && obj.version >= 1 &&
+        Array.isArray(obj.allowedWriters) &&
+        typeof obj.createdAt === 'string' &&
+        typeof obj.updatedAt === 'string');
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates CreateWorkspaceInput.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export function validateCreateWorkspaceInput(input) {
+    const errors = [];
+    if (!input.name || typeof input.name !== 'string') {
+        errors.push('name is required and must be a non-empty string');
+    }
+    if (!input.ownerType || !isValidWorkspaceOwnerType(input.ownerType)) {
+        errors.push(`ownerType must be one of: ${WORKSPACE_OWNER_TYPES.join(', ')}`);
+    }
+    if (!input.ownerId || typeof input.ownerId !== 'string') {
+        errors.push('ownerId is required and must be a non-empty string');
+    }
+    if (input.accessMode && !isValidWorkspaceAccessMode(input.accessMode)) {
+        errors.push(`accessMode must be one of: ${WORKSPACE_ACCESS_MODES.join(', ')}`);
+    }
+    return errors;
+}
+/**
+ * Validates WriteWorkspaceInput.
+ */
+export function validateWriteWorkspaceInput(input) {
+    const errors = [];
+    if (typeof input.expectedVersion !== 'number' || input.expectedVersion < 1) {
+        errors.push('expectedVersion must be a positive integer');
+    }
+    if (typeof input.data !== 'object' || input.data === null) {
+        errors.push('data must be a non-null object');
+    }
+    if (!input.writerId || typeof input.writerId !== 'string') {
+        errors.push('writerId is required and must be a non-empty string');
+    }
+    return errors;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates a new Workspace with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated Workspace at version 1
+ *
+ * @example
+ * ```typescript
+ * const ws = createWorkspace({
+ *   name: 'Sprint 1 Results',
+ *   ownerType: 'team',
+ *   ownerId: 'team-product',
+ * });
+ * ```
+ */
+export function createWorkspace(input) {
+    const now = new Date().toISOString();
+    return {
+        id: uuidv4(),
+        name: input.name,
+        description: input.description,
+        ownerType: input.ownerType,
+        ownerId: input.ownerId,
+        accessMode: input.accessMode ?? 'overwrite',
+        data: input.data ?? {},
+        version: 1,
+        allowedWriters: input.allowedWriters ?? [],
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+//# sourceMappingURL=workspace.types.js.map

package/dist/cli/backend/src/types/v2/workspace.types.js.map

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

package/dist/cli/backend/src/utils/async.utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Async Utilities
+ *
+ * Shared async helper functions used across backend services.
+ *
+ * @module async-utils
+ */
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * This is the standard delay utility used throughout the backend
+ * for timing-sensitive operations like terminal interactions.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```typescript
+ * // Wait 500ms before next operation
+ * await delay(500);
+ *
+ * // Use with configured constants
+ * await delay(SESSION_COMMAND_DELAYS.MESSAGE_DELAY);
+ * ```
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Execute a function with a timeout, returning a default value if timeout expires.
+ *
+ * @param fn - Async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param defaultValue - Value to return if timeout expires
+ * @returns Promise resolving to function result or default value
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   () => fetchData(),
+ *   5000,
+ *   null
+ * );
+ * ```
+ */
+export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, defaultValue: T): Promise<T>;
+/**
+ * Execute a function with a timeout, throwing an error if timeout expires.
+ *
+ * @param fn - Async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param errorMessage - Error message if timeout expires
+ * @returns Promise resolving to function result
+ * @throws Error if timeout expires
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await withTimeoutError(
+ *     () => fetchData(),
+ *     5000,
+ *     'Operation timed out'
+ *   );
+ * } catch (error) {
+ *   console.error(error.message);
+ * }
+ * ```
+ */
+export declare function withTimeoutError<T>(fn: () => Promise<T>, timeoutMs: number, errorMessage: string): Promise<T>;
+//# sourceMappingURL=async.utils.d.ts.map

package/dist/cli/backend/src/utils/async.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.utils.d.ts","sourceRoot":"","sources":["../../../../../backend/src/utils/async.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,GACb,OAAO,CAAC,CAAC,CAAC,CAKZ;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/cli/backend/src/utils/async.utils.js

@@ -0,0 +1,80 @@
+/**
+ * Async Utilities
+ *
+ * Shared async helper functions used across backend services.
+ *
+ * @module async-utils
+ */
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * This is the standard delay utility used throughout the backend
+ * for timing-sensitive operations like terminal interactions.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```typescript
+ * // Wait 500ms before next operation
+ * await delay(500);
+ *
+ * // Use with configured constants
+ * await delay(SESSION_COMMAND_DELAYS.MESSAGE_DELAY);
+ * ```
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with a timeout, returning a default value if timeout expires.
+ *
+ * @param fn - Async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param defaultValue - Value to return if timeout expires
+ * @returns Promise resolving to function result or default value
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   () => fetchData(),
+ *   5000,
+ *   null
+ * );
+ * ```
+ */
+export async function withTimeout(fn, timeoutMs, defaultValue) {
+    return Promise.race([
+        fn(),
+        new Promise((resolve) => setTimeout(() => resolve(defaultValue), timeoutMs)),
+    ]);
+}
+/**
+ * Execute a function with a timeout, throwing an error if timeout expires.
+ *
+ * @param fn - Async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param errorMessage - Error message if timeout expires
+ * @returns Promise resolving to function result
+ * @throws Error if timeout expires
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await withTimeoutError(
+ *     () => fetchData(),
+ *     5000,
+ *     'Operation timed out'
+ *   );
+ * } catch (error) {
+ *   console.error(error.message);
+ * }
+ * ```
+ */
+export async function withTimeoutError(fn, timeoutMs, errorMessage) {
+    return Promise.race([
+        fn(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error(errorMessage)), timeoutMs)),
+    ]);
+}
+//# sourceMappingURL=async.utils.js.map

package/dist/cli/backend/src/utils/async.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.utils.js","sourceRoot":"","sources":["../../../../../backend/src/utils/async.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,EAAoB,EACpB,SAAiB,EACjB,YAAe;IAEf,OAAO,OAAO,CAAC,IAAI,CAAC;QACnB,EAAE,EAAE;QACJ,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,CAAC;KAC/E,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,EAAoB,EACpB,SAAiB,EACjB,YAAoB;IAEpB,OAAO,OAAO,CAAC,IAAI,CAAC;QACnB,EAAE,EAAE;QACJ,IAAI,OAAO,CAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC5B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,SAAS,CAAC,CAC5D;KACD,CAAC,CAAC;AACJ,CAAC"}

package/dist/cli/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/cli/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"}