@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/sync-health-check.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Sync Health Check — Read-Only Drift Diagnostics
+ *
+ * Compares SQLite source-of-truth counts against PG mirror counts
+ * and reports mismatches as read-only diagnostics.
+ *
+ * @module tools/cmos/sync-health-check
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSyncHealth = checkSyncHealth;
+exports.formatSyncHealthForLLM = formatSyncHealthForLLM;
+const cmos_db_backfill_1 = require("./cmos-db-backfill");
+// ─── Core Health Check ──────────────────────────────────────────────────────
+/**
+ * Run a sync health check: reconcile SQLite vs PG counts (read-only).
+ *
+ * @param options - Configuration options
+ * @returns SyncHealthCheckResult with drift details
+ */
+async function checkSyncHealth(options = {}) {
+    const reconcileResult = await (0, cmos_db_backfill_1.cmosDbReconcile)({
+        projectRoot: options.projectRoot,
+    });
+    if (!reconcileResult.success || !reconcileResult.data) {
+        return {
+            checked: false,
+            allMatch: false,
+            totalDelta: 0,
+            mismatchedTables: 0,
+            mismatches: [],
+            message: `Sync health check skipped: ${reconcileResult.error?.message ?? 'dashboard unreachable'}`,
+            warnings: [],
+        };
+    }
+    const reconciliation = reconcileResult.data;
+    if (reconciliation.allMatch) {
+        return {
+            checked: true,
+            allMatch: true,
+            totalDelta: 0,
+            mismatchedTables: 0,
+            mismatches: [],
+            message: 'Sync health: all tables match',
+            warnings: [],
+        };
+    }
+    // Calculate drift metrics
+    const mismatches = reconciliation.tables
+        .filter((t) => !t.match)
+        .map((t) => ({
+        table: t.table,
+        sqliteCount: t.sqliteCount,
+        pgCount: t.pgCount,
+        delta: t.delta,
+    }));
+    const totalDelta = mismatches.reduce((sum, m) => sum + Math.abs(m.delta), 0);
+    const warnings = [];
+    warnings.push(`Sync drift detected: ${mismatches.length} table(s) mismatched, total delta ${totalDelta}`);
+    for (const m of mismatches) {
+        const direction = m.delta > 0 ? 'SQLite ahead' : 'PG ahead';
+        warnings.push(`  ${m.table}: SQLite=${m.sqliteCount} PG=${m.pgCount} (${direction} by ${Math.abs(m.delta)})`);
+    }
+    return {
+        checked: true,
+        allMatch: false,
+        totalDelta,
+        mismatchedTables: mismatches.length,
+        mismatches,
+        message: `Sync drift detected: delta ${totalDelta}`,
+        warnings,
+    };
+}
+/**
+ * Format sync health check result for LLM readability.
+ */
+function formatSyncHealthForLLM(result) {
+    if (!result.checked) {
+        return result.message;
+    }
+    if (result.allMatch) {
+        return 'Sync health: all tables match between SQLite and PG mirror';
+    }
+    const lines = [
+        `Sync drift: ${result.mismatchedTables} table(s), total delta ${result.totalDelta}`,
+    ];
+    for (const m of result.mismatches) {
+        const direction = m.delta > 0 ? 'SQLite ahead' : 'PG ahead';
+        lines.push(`  ${m.table}: SQLite=${m.sqliteCount} PG=${m.pgCount} (${direction} by ${Math.abs(m.delta)})`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=sync-health-check.js.map

package/dist/tools/cmos/sync-health-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-health-check.js","sourceRoot":"","sources":["../../../src/tools/cmos/sync-health-check.ts"],"names":[],"mappings":"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"}

package/dist/tools/cmos/sync-hooks.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Sync Hook Infrastructure
+ *
+ * Post-write hook system that fires after successful CMOS database writes.
+ * Designed for Phase 1 live sync: fire-and-forget event push to dashboard.
+ *
+ * - No-op when no listeners registered (zero cost when dashboard unconfigured)
+ * - All listener errors are caught and logged (never fails the write operation)
+ * - Listeners receive typed SyncEvent payloads after commits succeed
+ *
+ * @module tools/cmos/sync-hooks
+ */
+/**
+ * All CMOS write operations that produce sync events.
+ * This is the event type registry — dashboard team builds against these.
+ */
+export declare const SYNC_EVENT_TYPES: readonly ["mission_started", "mission_completed", "mission_blocked", "mission_unblocked", "mission_added", "mission_updated", "decision_captured", "learning_captured", "session_started", "session_captured", "session_completed", "sprint_added", "sprint_updated", "sprint_completed", "project_initialized", "dependency_added", "dependency_removed", "context_updated"];
+export type SyncEventType = (typeof SYNC_EVENT_TYPES)[number];
+/**
+ * Sync event envelope. Carries the event type, timestamp, and domain payload.
+ */
+export interface SyncEvent<T = unknown> {
+    /** Event type from the registry */
+    type: SyncEventType;
+    /** ISO timestamp when the event was emitted (after write committed) */
+    timestamp: string;
+    /** Domain-specific payload (tool result data) */
+    payload: T;
+}
+/**
+ * Callback type for sync hook listeners.
+ * Listeners MUST NOT throw — the registry catches errors defensively,
+ * but well-behaved listeners should handle their own errors.
+ */
+export type SyncHookListener = (event: SyncEvent) => void;
+/**
+ * Resolve the sync event type for a given tool + action combination.
+ * Returns undefined if the operation is read-only or not sync-relevant.
+ */
+export declare function resolveSyncEventType(toolName: string, action: string | undefined): SyncEventType | undefined;
+/**
+ * Singleton registry for sync hook listeners.
+ *
+ * Usage:
+ * - Register listeners at startup (e.g., when dashboard env vars are present)
+ * - Emit events after successful writes in the tool dispatch pipeline
+ * - When no listeners registered, emit() is effectively a no-op
+ */
+declare class SyncHookRegistry {
+    private listeners;
+    /**
+     * Register a listener that will be called for every sync event.
+     * Returns a dispose function to unregister the listener.
+     */
+    register(listener: SyncHookListener): () => void;
+    /**
+     * Emit a sync event to all registered listeners.
+     * Fire-and-forget: errors are caught and logged, never propagated.
+     * When no listeners are registered, this is a no-op (zero cost).
+     */
+    emit(event: SyncEvent): void;
+    /** Number of registered listeners. */
+    get listenerCount(): number;
+    /** Remove all listeners (useful for testing). */
+    clear(): void;
+}
+/** Global sync hook registry singleton. */
+export declare const syncHooks: SyncHookRegistry;
+/**
+ * Emit a sync event if the tool operation was a successful write.
+ * Called from the main tool dispatch pipeline after handler returns.
+ *
+ * @param toolName - The MCP tool name (e.g., 'cmos_mission_transition')
+ * @param action - The action parameter (e.g., 'start', 'complete')
+ * @param result - The tool result (only emits if result.success is true)
+ */
+export declare function emitIfWriteSucceeded(toolName: string, action: string | undefined, result: {
+    success: boolean;
+    data?: unknown;
+}): void;
+export {};
+//# sourceMappingURL=sync-hooks.d.ts.map

package/dist/tools/cmos/sync-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-hooks.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/sync-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;GAGG;AACH,eAAO,MAAM,gBAAgB,+WAmBnB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,mCAAmC;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAwC1D;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,aAAa,GAAG,SAAS,CAG3B;AAID;;;;;;;GAOG;AACH,cAAM,gBAAgB;IACpB,OAAO,CAAC,SAAS,CAA0B;IAE3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAQhD;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAe5B,sCAAsC;IACtC,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,iDAAiD;IACjD,KAAK,IAAI,IAAI;CAGd;AAED,2CAA2C;AAC3C,eAAO,MAAM,SAAS,kBAAyB,CAAC;AAIhD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,IAAI,CAWN"}

package/dist/tools/cmos/sync-hooks.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Sync Hook Infrastructure
+ *
+ * Post-write hook system that fires after successful CMOS database writes.
+ * Designed for Phase 1 live sync: fire-and-forget event push to dashboard.
+ *
+ * - No-op when no listeners registered (zero cost when dashboard unconfigured)
+ * - All listener errors are caught and logged (never fails the write operation)
+ * - Listeners receive typed SyncEvent payloads after commits succeed
+ *
+ * @module tools/cmos/sync-hooks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncHooks = exports.SYNC_EVENT_TYPES = void 0;
+exports.resolveSyncEventType = resolveSyncEventType;
+exports.emitIfWriteSucceeded = emitIfWriteSucceeded;
+// ─── Sync Event Types ────────────────────────────────────────────────────────
+/**
+ * All CMOS write operations that produce sync events.
+ * This is the event type registry — dashboard team builds against these.
+ */
+exports.SYNC_EVENT_TYPES = [
+    'mission_started',
+    'mission_completed',
+    'mission_blocked',
+    'mission_unblocked',
+    'mission_added',
+    'mission_updated',
+    'decision_captured',
+    'learning_captured',
+    'session_started',
+    'session_captured',
+    'session_completed',
+    'sprint_added',
+    'sprint_updated',
+    'sprint_completed',
+    'project_initialized',
+    'dependency_added',
+    'dependency_removed',
+    'context_updated',
+];
+// ─── Tool-to-Event Mapping ──────────────────────────────────────────────────
+/**
+ * Maps tool name + action to the corresponding sync event type.
+ * Returns undefined for read-only operations (no sync needed).
+ */
+const TOOL_ACTION_EVENT_MAP = {
+    cmos_mission_transition: {
+        start: 'mission_started',
+        complete: 'mission_completed',
+        block: 'mission_blocked',
+        unblock: 'mission_unblocked',
+    },
+    cmos_mission: {
+        add: 'mission_added',
+        update: 'mission_updated',
+        depends: 'dependency_added',
+        undepends: 'dependency_removed',
+    },
+    cmos_session: {
+        start: 'session_started',
+        capture: 'session_captured',
+        complete: 'session_completed',
+    },
+    cmos_sprint: {
+        add: 'sprint_added',
+        update: 'sprint_updated',
+        complete: 'sprint_completed',
+    },
+    cmos_project: {
+        init: 'project_initialized',
+    },
+    cmos_context: {
+        update: 'context_updated',
+        condense: 'context_updated',
+    },
+};
+/**
+ * Resolve the sync event type for a given tool + action combination.
+ * Returns undefined if the operation is read-only or not sync-relevant.
+ */
+function resolveSyncEventType(toolName, action) {
+    if (!action)
+        return undefined;
+    return TOOL_ACTION_EVENT_MAP[toolName]?.[action];
+}
+// ─── Sync Hook Registry ─────────────────────────────────────────────────────
+/**
+ * Singleton registry for sync hook listeners.
+ *
+ * Usage:
+ * - Register listeners at startup (e.g., when dashboard env vars are present)
+ * - Emit events after successful writes in the tool dispatch pipeline
+ * - When no listeners registered, emit() is effectively a no-op
+ */
+class SyncHookRegistry {
+    constructor() {
+        this.listeners = [];
+    }
+    /**
+     * Register a listener that will be called for every sync event.
+     * Returns a dispose function to unregister the listener.
+     */
+    register(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx >= 0)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    /**
+     * Emit a sync event to all registered listeners.
+     * Fire-and-forget: errors are caught and logged, never propagated.
+     * When no listeners are registered, this is a no-op (zero cost).
+     */
+    emit(event) {
+        if (this.listeners.length === 0)
+            return;
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                console.warn(`[sync-hooks] Listener error for ${event.type}:`, error instanceof Error ? error.message : error);
+            }
+        }
+    }
+    /** Number of registered listeners. */
+    get listenerCount() {
+        return this.listeners.length;
+    }
+    /** Remove all listeners (useful for testing). */
+    clear() {
+        this.listeners = [];
+    }
+}
+/** Global sync hook registry singleton. */
+exports.syncHooks = new SyncHookRegistry();
+// ─── Dispatch Helper ─────────────────────────────────────────────────────────
+/**
+ * Emit a sync event if the tool operation was a successful write.
+ * Called from the main tool dispatch pipeline after handler returns.
+ *
+ * @param toolName - The MCP tool name (e.g., 'cmos_mission_transition')
+ * @param action - The action parameter (e.g., 'start', 'complete')
+ * @param result - The tool result (only emits if result.success is true)
+ */
+function emitIfWriteSucceeded(toolName, action, result) {
+    if (!result.success)
+        return;
+    const eventType = resolveSyncEventType(toolName, action);
+    if (!eventType)
+        return;
+    exports.syncHooks.emit({
+        type: eventType,
+        timestamp: new Date().toISOString(),
+        payload: result.data,
+    });
+}
+//# sourceMappingURL=sync-hooks.js.map

package/dist/tools/cmos/sync-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-hooks.js","sourceRoot":"","sources":["../../../src/tools/cmos/sync-hooks.ts"],"names":[],"mappings":"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"}

package/dist/tools/cmos/sync-pusher.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Sync Pusher — Queue-Backed Event Push to Dashboard
+ *
+ * Registers as a sync hook listener and pushes events to the dashboard API
+ * via DashboardClient. When a SyncQueue is provided, events are persisted
+ * to SQLite before push, surviving MCP restarts.
+ *
+ * Key properties:
+ * - Non-blocking: push happens asynchronously, tool operations never wait
+ * - No-op when dashboard is not configured (DashboardClient.fromEnv() fails)
+ * - Error-resilient: network failures log a warning, never throw
+ * - Queue-backed: events survive MCP restarts when SyncQueue is provided
+ * - Backward-compatible: works without queue (fire-and-forget fallback)
+ * - Tracks push stats for diagnostics
+ *
+ * @module tools/cmos/sync-pusher
+ */
+import { DashboardClient } from './dashboard-client';
+import type { ProjectIdentity } from './sync-event-payloads';
+import type { SyncQueue, DrainResult } from './sync-queue';
+/**
+ * In-memory sync push statistics.
+ * Used by diagnostics to surface health info.
+ */
+export interface SyncPushStats {
+    /** Total events pushed successfully */
+    totalPushed: number;
+    /** Total push failures (after retries exhausted) */
+    totalFailed: number;
+    /** Total events that succeeded on retry */
+    totalRetried: number;
+    /** Last successful push timestamp (ISO) or null */
+    lastPushAt: string | null;
+    /** Last failure timestamp (ISO) or null */
+    lastFailureAt: string | null;
+    /** Last failure message or null */
+    lastFailureMessage: string | null;
+}
+export declare class SyncPusher {
+    private readonly client;
+    private readonly identity;
+    private dispose;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    /** Optional persistent queue — when present, events are durable */
+    private readonly queue;
+    /** Drain timer for debouncing rapid enqueues */
+    private drainTimer;
+    /** In-memory push statistics */
+    readonly stats: SyncPushStats;
+    constructor(client: DashboardClient, identity: ProjectIdentity, options?: {
+        maxRetries?: number;
+        retryDelayMs?: number;
+        queue?: SyncQueue;
+    });
+    /**
+     * Try to create a SyncPusher from environment variables.
+     * Returns null if dashboard is not configured (no-op path).
+     *
+     * @param identity - Project identity for the envelope
+     * @param queue - Optional persistent sync queue
+     * @returns SyncPusher instance or null
+     */
+    static fromEnv(identity: ProjectIdentity, queue?: SyncQueue): SyncPusher | null;
+    /**
+     * Register this pusher as a sync hook listener.
+     * Events will be queued (if queue available) or pushed fire-and-forget.
+     */
+    start(): void;
+    /**
+     * Unregister from sync hooks and stop pushing.
+     */
+    stop(): void;
+    /**
+     * Whether the pusher is currently active (registered as listener).
+     */
+    get isActive(): boolean;
+    /**
+     * Whether the pusher is backed by a persistent queue.
+     */
+    get hasQueue(): boolean;
+    /**
+     * Drain pending events from the queue.
+     * Call this on startup to recover events from prior runs.
+     * Returns null if no queue is configured.
+     */
+    drainQueue(): Promise<DrainResult | null>;
+    /**
+     * Handle a sync event by building the payload and either queuing or pushing.
+     * This is the hook listener callback — it must never throw.
+     */
+    private handleEvent;
+    /**
+     * Schedule an async drain after a short debounce.
+     * Batches rapid enqueues to avoid per-event HTTP calls.
+     */
+    private scheduleDrain;
+    /**
+     * Async push with retry logic (legacy path). Not awaited by the caller.
+     * Retries on server errors (5xx) up to maxRetries times with delay.
+     */
+    private pushAsync;
+    private pushWithRetry;
+    /** Determine if an error code is retryable (server errors, not client errors) */
+    private isRetryable;
+}
+/**
+ * Set the active SyncPusher instance.
+ * Called from main() after creating and starting the pusher.
+ */
+export declare function setActiveSyncPusher(pusher: SyncPusher | null): void;
+/**
+ * Get the sync status for diagnostics (used by cmos_agent_onboard).
+ * Returns null if sync is not configured (no dashboard env vars).
+ */
+export declare function getSyncStatus(): SyncStatusSummary | null;
+/**
+ * Sync status summary for onboard diagnostics.
+ */
+export interface SyncStatusSummary {
+    /** Whether the pusher is actively listening */
+    active: boolean;
+    /** Whether the pusher is backed by a persistent queue */
+    queueBacked: boolean;
+    /** Push statistics snapshot */
+    stats: SyncPushStats;
+}
+//# sourceMappingURL=sync-pusher.d.ts.map

package/dist/tools/cmos/sync-pusher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-pusher.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/sync-pusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIrD,OAAO,KAAK,EAAqB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAI3D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAWD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,OAAO,CAA6B;IAE5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IAEzC,gDAAgD;IAChD,OAAO,CAAC,UAAU,CAA8C;IAEhE,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAO3B;gBAGA,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE;QACR,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,SAAS,CAAC;KACnB;IASH;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,eAAe,EACzB,KAAK,CAAC,EAAE,SAAS,GAChB,UAAU,GAAG,IAAI;IAQpB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI;IAWZ;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAmB/C;;;OAGG;IACH,OAAO,CAAC,WAAW;IA+BnB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAerB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IA2CrB,iFAAiF;IACjF,OAAO,CAAC,WAAW;CAWpB;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAEnE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,iBAAiB,GAAG,IAAI,CAQxD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,MAAM,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,+BAA+B;IAC/B,KAAK,EAAE,aAAa,CAAC;CACtB"}