@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/dist/sync/logger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Component-tagged logger factory for the hq-cloud sync subsystem
+ * (project event-driven-sync-menubar US-011).
+ *
+ * Every log line emitted from a sync module SHOULD carry a `component` field
+ * so operators can grep / route by subsystem in the aggregated JSON stream.
+ * `createLogger({ component: "sync-watcher" })` is the canonical entry point —
+ * modules call this once at module-load time and use the returned logger for
+ * the lifetime of the process.
+ *
+ * The 3-log diagnostic chain (US-011)
+ * ───────────────────────────────────
+ * Three correlated log lines share a single `sequenceNumber` join key so an
+ * operator can walk one event end-to-end:
+ *   1. `event=watcher.emit`    — client push side (US-008 PushEventEmitter)
+ *   2. `event=push.receive`    — server side (hq-pro; context only here)
+ *   3. `event=fanout.receive`  — client fanout-receive side (US-009 receiver)
+ * The watcher.emit + fanout.receive halves live in this client package; the
+ * push.receive half lives server-side in hq-pro. All three stamp the same
+ * `sequenceNumber` for log-chain correlation.
+ *
+ * Output format: pino's default newline-delimited JSON. No transports, no
+ * pretty-printing — the daemon consumes the raw JSON stream. (Operators who
+ * want pretty output pipe through `pino-pretty` themselves.)
+ *
+ * Destination injection: tests pass a `destination` stream so they can capture
+ * log lines and assert on them. Production callers omit it and pino defaults
+ * to `process.stdout`.
+ *
+ * Adapted from indigoai-us/hq-pro PR #112 (src/sync/logger.ts) into
+ * @indigoai-us/hq-cloud (Path B).
+ */
+import { type DestinationStream, type Level, type Logger } from "pino";
+export interface CreateLoggerOptions {
+    /**
+     * Component tag stamped on every log line as `"component": <value>`.
+     * Required so daemon / watcher / receiver lines never appear in the stream
+     * untagged.
+     */
+    component: string;
+    /**
+     * Optional pino level. Default: pino's own default (`info`). Set via
+     * `LOG_LEVEL` env var, command-line flag, or test injection.
+     */
+    level?: Level;
+    /**
+     * Optional pino destination. Default: `process.stdout`. Tests inject a
+     * memory stream here to capture lines for assertion.
+     */
+    destination?: DestinationStream;
+}
+/**
+ * Build a pino logger pre-bound to a `component` tag.
+ *
+ * Use this — not a bare `pino()` call — so every sync module's log lines carry
+ * the tag uniformly. Adding more bound fields (e.g. `deviceId`, `tenantId`) is
+ * a `logger.child({ ... })` call away.
+ */
+export declare function createLogger(opts: CreateLoggerOptions): Logger;
+export type { Logger } from "pino";
+//# sourceMappingURL=logger.d.ts.map

package/dist/sync/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/sync/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACV,KAAK,MAAM,EAEZ,MAAM,MAAM,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAS9D;AAED,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC"}

package/dist/sync/logger.js

@@ -0,0 +1,51 @@
+/**
+ * Component-tagged logger factory for the hq-cloud sync subsystem
+ * (project event-driven-sync-menubar US-011).
+ *
+ * Every log line emitted from a sync module SHOULD carry a `component` field
+ * so operators can grep / route by subsystem in the aggregated JSON stream.
+ * `createLogger({ component: "sync-watcher" })` is the canonical entry point —
+ * modules call this once at module-load time and use the returned logger for
+ * the lifetime of the process.
+ *
+ * The 3-log diagnostic chain (US-011)
+ * ───────────────────────────────────
+ * Three correlated log lines share a single `sequenceNumber` join key so an
+ * operator can walk one event end-to-end:
+ *   1. `event=watcher.emit`    — client push side (US-008 PushEventEmitter)
+ *   2. `event=push.receive`    — server side (hq-pro; context only here)
+ *   3. `event=fanout.receive`  — client fanout-receive side (US-009 receiver)
+ * The watcher.emit + fanout.receive halves live in this client package; the
+ * push.receive half lives server-side in hq-pro. All three stamp the same
+ * `sequenceNumber` for log-chain correlation.
+ *
+ * Output format: pino's default newline-delimited JSON. No transports, no
+ * pretty-printing — the daemon consumes the raw JSON stream. (Operators who
+ * want pretty output pipe through `pino-pretty` themselves.)
+ *
+ * Destination injection: tests pass a `destination` stream so they can capture
+ * log lines and assert on them. Production callers omit it and pino defaults
+ * to `process.stdout`.
+ *
+ * Adapted from indigoai-us/hq-pro PR #112 (src/sync/logger.ts) into
+ * @indigoai-us/hq-cloud (Path B).
+ */
+import { pino, } from "pino";
+/**
+ * Build a pino logger pre-bound to a `component` tag.
+ *
+ * Use this — not a bare `pino()` call — so every sync module's log lines carry
+ * the tag uniformly. Adding more bound fields (e.g. `deviceId`, `tenantId`) is
+ * a `logger.child({ ... })` call away.
+ */
+export function createLogger(opts) {
+    const { component, level, destination } = opts;
+    const pinoOpts = {
+        base: { component },
+        ...(level === undefined ? {} : { level }),
+    };
+    return destination === undefined
+        ? pino(pinoOpts)
+        : pino(pinoOpts, destination);
+}
+//# sourceMappingURL=logger.js.map

package/dist/sync/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/sync/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EACL,IAAI,GAKL,MAAM,MAAM,CAAC;AAqBd;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC/C,MAAM,QAAQ,GAAkB;QAC9B,IAAI,EAAE,EAAE,SAAS,EAAE;QACnB,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;KAC1C,CAAC;IACF,OAAO,WAAW,KAAK,SAAS;QAC9B,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;QAChB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AAClC,CAAC"}

package/dist/sync/logger.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * US-011 — unit tests for the pino logger factory + the 3-log diagnostic
+ * chain's CLIENT-side correlated fields.
+ *
+ * The PRD requires three correlated logs sharing the same `sequenceNumber`:
+ *   1. `watcher.emit`    — client push (US-008 PushEventEmitter)   [client]
+ *   2. `push.receive`    — server (hq-pro)                          [server]
+ *   3. `fanout.receive`  — client fanout-receive (US-009 receiver)  [client]
+ *
+ * This package owns the two CLIENT-side links. These tests prove:
+ *   - `createLogger` stamps the `component` tag on every line and respects
+ *     level + injected destination.
+ *   - the watcher emits `event=watcher.emit` carrying `sequenceNumber`.
+ *   - the receiver emits `event=fanout.receive` carrying the SAME
+ *     `sequenceNumber` → an operator can join the two client links (and the
+ *     server `push.receive` line, which carries the same key) end-to-end.
+ */
+export {};
+//# sourceMappingURL=logger.test.d.ts.map

package/dist/sync/logger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.d.ts","sourceRoot":"","sources":["../../src/sync/logger.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/sync/logger.test.js

@@ -0,0 +1,199 @@
+/**
+ * US-011 — unit tests for the pino logger factory + the 3-log diagnostic
+ * chain's CLIENT-side correlated fields.
+ *
+ * The PRD requires three correlated logs sharing the same `sequenceNumber`:
+ *   1. `watcher.emit`    — client push (US-008 PushEventEmitter)   [client]
+ *   2. `push.receive`    — server (hq-pro)                          [server]
+ *   3. `fanout.receive`  — client fanout-receive (US-009 receiver)  [client]
+ *
+ * This package owns the two CLIENT-side links. These tests prove:
+ *   - `createLogger` stamps the `component` tag on every line and respects
+ *     level + injected destination.
+ *   - the watcher emits `event=watcher.emit` carrying `sequenceNumber`.
+ *   - the receiver emits `event=fanout.receive` carrying the SAME
+ *     `sequenceNumber` → an operator can join the two client links (and the
+ *     server `push.receive` line, which carries the same key) end-to-end.
+ */
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Writable } from "node:stream";
+import { afterEach, describe, expect, it } from "vitest";
+import { createLogger } from "./logger.js";
+import { encodePushEvent } from "./push-event.js";
+import { NoopPushTransport } from "./push-transport.js";
+import { StaticFlagProvider } from "./feature-flags.js";
+import { SqsPushReceiver, } from "./push-receiver.js";
+import { PushEventEmitter } from "../watcher.js";
+const TENANT = "tenant-indigo";
+// ── Capture stream + JSON line reader ─────────────────────────────────────────
+function captureStream() {
+    const chunks = [];
+    const stream = new Writable({
+        write(chunk, _enc, cb) {
+            chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+            cb();
+        },
+    });
+    return {
+        stream,
+        lines: () => chunks
+            .join("")
+            .split("\n")
+            .filter((s) => s.length > 0)
+            .map((s) => JSON.parse(s)),
+    };
+}
+async function until(predicate, timeoutMs = 1000) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs)
+            throw new Error("until() timed out");
+        await new Promise((r) => setTimeout(r, 5));
+    }
+}
+function makeEvent(overrides = {}) {
+    return {
+        relativePath: "companies/indigo/notes.md",
+        contentHash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+        mtime: "2026-05-21T12:34:56.000Z",
+        originDeviceId: "device-A",
+        originTenantId: TENANT,
+        sequenceNumber: 1,
+        eventTimestamp: "2026-05-21T12:34:56.000Z",
+        ...overrides,
+    };
+}
+class OneBatchSqs {
+    batch;
+    constructor(messages) {
+        this.batch = messages;
+    }
+    async receiveMessage(args) {
+        if (this.batch) {
+            const b = this.batch;
+            this.batch = null;
+            return { messages: b };
+        }
+        return new Promise((resolve) => {
+            if (args.signal.aborted)
+                return resolve({ messages: [] });
+            const t = setTimeout(() => resolve({ messages: [] }), 5);
+            t.unref?.();
+            args.signal.addEventListener("abort", () => {
+                clearTimeout(t);
+                resolve({ messages: [] });
+            }, { once: true });
+        });
+    }
+    async deleteMessage() {
+        /* no-op */
+    }
+}
+// ── createLogger ──────────────────────────────────────────────────────────────
+describe("createLogger", () => {
+    it("stamps the `component` tag on every line", () => {
+        const { stream, lines } = captureStream();
+        const log = createLogger({
+            component: "sync-watcher",
+            destination: stream,
+            level: "info",
+        });
+        log.info({ event: "x" }, "hello");
+        log.warn({ event: "y" }, "world");
+        const out = lines();
+        expect(out).toHaveLength(2);
+        expect(out.every((l) => l.component === "sync-watcher")).toBe(true);
+    });
+    it("respects the injected level (debug below info is dropped at info)", () => {
+        const { stream, lines } = captureStream();
+        const log = createLogger({
+            component: "c",
+            destination: stream,
+            level: "info",
+        });
+        log.debug({ event: "d" }, "dropped");
+        log.info({ event: "i" }, "kept");
+        const out = lines();
+        expect(out).toHaveLength(1);
+        expect(out[0].event).toBe("i");
+    });
+});
+// ── 3-log chain: client-side correlated fields share sequenceNumber ───────────
+describe("3-log diagnostic chain (client links share sequenceNumber)", () => {
+    let tmp;
+    let receiver;
+    afterEach(async () => {
+        if (receiver) {
+            await receiver.dispose();
+            receiver = undefined;
+        }
+        if (tmp) {
+            await rm(tmp, { recursive: true, force: true });
+            tmp = undefined;
+        }
+    });
+    it("watcher.emit and fanout.receive carry the SAME sequenceNumber", async () => {
+        const SEQ = 4242;
+        // ── Link 1: watcher.emit (client push side) ──────────────────────────
+        tmp = await mkdtemp(join(tmpdir(), "us011-logger-"));
+        const absPath = join(tmp, "notes.md");
+        await writeFile(absPath, "hello world", "utf8");
+        const watcherCap = captureStream();
+        const watcherLog = createLogger({
+            component: "sync-watcher",
+            destination: watcherCap.stream,
+            level: "info",
+        });
+        const emitter = new PushEventEmitter({
+            originTenantId: TENANT,
+            originDeviceId: "device-A",
+            transport: new NoopPushTransport(),
+            flagProvider: new StaticFlagProvider([TENANT]),
+            getSequenceNumber: () => SEQ,
+            logger: watcherLog,
+        });
+        const batch = {
+            paths: new Map([[absPath, "companies/indigo/notes.md"]]),
+        };
+        await emitter.emitForBatch(batch);
+        const emitLine = watcherCap
+            .lines()
+            .find((l) => l.event === "watcher.emit");
+        expect(emitLine).toBeDefined();
+        expect(emitLine.sequenceNumber).toBe(SEQ);
+        expect(emitLine.component).toBe("sync-watcher");
+        // ── Link 3: fanout.receive (client receive side) ─────────────────────
+        const receiverCap = captureStream();
+        const receiverLog = createLogger({
+            component: "sync-receiver",
+            destination: receiverCap.stream,
+            level: "info",
+        });
+        const event = makeEvent({ sequenceNumber: SEQ });
+        receiver = new SqsPushReceiver({
+            tenantId: TENANT,
+            queueUrl: "https://sqs.local/q",
+            sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh" }]),
+            syncFn: async () => {
+                /* success */
+            },
+            enabled: true,
+            logger: receiverLog,
+            // Inject a no-op metric so no real AWS is touched.
+            publishMetric: async () => { },
+        });
+        await receiver.start();
+        await until(() => receiverCap.lines().some((l) => l.event === "fanout.receive"));
+        const recvLine = receiverCap
+            .lines()
+            .find((l) => l.event === "fanout.receive");
+        expect(recvLine).toBeDefined();
+        expect(recvLine.sequenceNumber).toBe(SEQ);
+        expect(recvLine.component).toBe("sync-receiver");
+        // ── The join key matches across both client links ────────────────────
+        expect(emitLine.sequenceNumber).toBe(recvLine.sequenceNumber);
+    });
+});
+//# sourceMappingURL=logger.test.js.map

package/dist/sync/logger.test.js.map

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

package/dist/sync/metrics.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Sync pipeline metrics — CloudWatch custom metrics for the event-driven push
+ * receive loop (project event-driven-sync-menubar US-011).
+ *
+ * Publishes one `hq-cloud.sync.p95_latency_seconds` datum per successfully
+ * processed push event to the `HQPro/Sync` namespace, with a `TenantId`
+ * dimension so the dashboard widget can be filtered per tenant. CloudWatch
+ * aggregates p50/p95/p99 across the time window via the dashboard's
+ * `Statistics` setting; the receive-loop side just emits one raw value per
+ * event.
+ *
+ * Best-effort emission
+ * ────────────────────
+ *   - module-level singleton CloudWatchClient with a `_setSyncCloudWatchClient`
+ *     test seam
+ *   - `publishSyncLatencyMetric` catches all errors and NEVER throws — a
+ *     CloudWatch outage MUST NOT crash the sync receive loop. The cadence
+ *     safety net still picks up missed work and metric blanks are recoverable;
+ *     a crashed loop is not.
+ *   - explicit `Unit` + `Timestamp` + `Dimensions` per datum
+ *
+ * Why latency (and not also "events received" / "events failed")?
+ * ───────────────────────────────────────────────────────────────
+ * US-011 AC#1 calls for the p95 latency metric specifically. The receive-loop's
+ * existing `processedCount` / log lines cover the count/failure dimensions for
+ * now; widening to additional metric names happens in a follow-up if the
+ * operator dashboard grows.
+ *
+ * Adapted from indigoai-us/hq-pro PR #112 (src/sync/metrics.ts) into
+ * @indigoai-us/hq-cloud (Path B).
+ */
+import { CloudWatchClient } from "@aws-sdk/client-cloudwatch";
+import type { Logger } from "pino";
+/**
+ * CloudWatch metric namespace for the sync pipeline. Matches the server-side
+ * namespace (hq-pro PR #112) so the dashboard + alarm cover the client path.
+ */
+export declare const SYNC_METRIC_NAMESPACE = "HQPro/Sync";
+/**
+ * Metric name for per-event sync latency in seconds. The dashboard widget
+ * applies `Statistics: ["p95"]` to aggregate across the time window — the
+ * receive loop just emits one raw `Seconds` value per processed event.
+ *
+ * Name chosen to match the PRD's alarm threshold (`p95 > 10s`).
+ */
+export declare const SYNC_LATENCY_METRIC_NAME = "hq-cloud.sync.p95_latency_seconds";
+/**
+ * One latency observation. `latencySeconds` is the wall-clock duration from
+ * save-on-A to visible-on-B (or, on the receive loop, the `syncFn(ctx)`
+ * duration); we ONLY publish on the success path so failed syncs don't skew
+ * p95 toward infinity.
+ *
+ * `relativePath` and `sequenceNumber` are NOT used as CloudWatch dimensions
+ * (cardinality explosion) — they're captured here for the optional debug log
+ * emitted on failure so operators can correlate back to the 3-log chain when
+ * investigating a spike.
+ */
+export interface SyncLatencyMetric {
+    tenantId: string;
+    relativePath: string;
+    sequenceNumber: number;
+    latencySeconds: number;
+    timestamp: Date;
+}
+/**
+ * Replace the CloudWatch client (for testing).
+ * @internal
+ */
+export declare function _setSyncCloudWatchClient(client: CloudWatchClient): void;
+export interface PublishSyncLatencyMetricOptions {
+    /** Override the CloudWatch client (tests). Defaults to the module singleton. */
+    client?: CloudWatchClient;
+    /** Optional pino logger for emission failures. */
+    logger?: Logger;
+}
+/**
+ * Publish a single latency datum to CloudWatch.
+ *
+ * Best-effort: any error from the SDK is CAUGHT and logged. A CloudWatch outage
+ * MUST NOT crash the sync receive loop — the cadence safety net still picks up
+ * missed work, and metric blanks are recoverable; a crashed loop is not.
+ *
+ * Dimension: `TenantId` only. The `relativePath`/`sequenceNumber` fields on the
+ * input are intentionally NOT promoted to dimensions (cardinality), but they
+ * ride along on the failure log so an operator can correlate a missed datum to
+ * its 3-log chain entry.
+ */
+export declare function publishSyncLatencyMetric(metric: SyncLatencyMetric, opts?: PublishSyncLatencyMetricOptions): Promise<void>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/sync/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/sync/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,gBAAgB,EAGjB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAI5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,IAAI,CAAC;CACjB;AAaD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAEvE;AAID,MAAM,WAAW,+BAA+B;IAC9C,gFAAgF;IAChF,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,iBAAiB,EACzB,IAAI,GAAE,+BAAoC,GACzC,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/sync/metrics.js

@@ -0,0 +1,105 @@
+/**
+ * Sync pipeline metrics — CloudWatch custom metrics for the event-driven push
+ * receive loop (project event-driven-sync-menubar US-011).
+ *
+ * Publishes one `hq-cloud.sync.p95_latency_seconds` datum per successfully
+ * processed push event to the `HQPro/Sync` namespace, with a `TenantId`
+ * dimension so the dashboard widget can be filtered per tenant. CloudWatch
+ * aggregates p50/p95/p99 across the time window via the dashboard's
+ * `Statistics` setting; the receive-loop side just emits one raw value per
+ * event.
+ *
+ * Best-effort emission
+ * ────────────────────
+ *   - module-level singleton CloudWatchClient with a `_setSyncCloudWatchClient`
+ *     test seam
+ *   - `publishSyncLatencyMetric` catches all errors and NEVER throws — a
+ *     CloudWatch outage MUST NOT crash the sync receive loop. The cadence
+ *     safety net still picks up missed work and metric blanks are recoverable;
+ *     a crashed loop is not.
+ *   - explicit `Unit` + `Timestamp` + `Dimensions` per datum
+ *
+ * Why latency (and not also "events received" / "events failed")?
+ * ───────────────────────────────────────────────────────────────
+ * US-011 AC#1 calls for the p95 latency metric specifically. The receive-loop's
+ * existing `processedCount` / log lines cover the count/failure dimensions for
+ * now; widening to additional metric names happens in a follow-up if the
+ * operator dashboard grows.
+ *
+ * Adapted from indigoai-us/hq-pro PR #112 (src/sync/metrics.ts) into
+ * @indigoai-us/hq-cloud (Path B).
+ */
+import { CloudWatchClient, PutMetricDataCommand, } from "@aws-sdk/client-cloudwatch";
+// ── Constants ──────────────────────────────────────────────────────────────
+/**
+ * CloudWatch metric namespace for the sync pipeline. Matches the server-side
+ * namespace (hq-pro PR #112) so the dashboard + alarm cover the client path.
+ */
+export const SYNC_METRIC_NAMESPACE = "HQPro/Sync";
+/**
+ * Metric name for per-event sync latency in seconds. The dashboard widget
+ * applies `Statistics: ["p95"]` to aggregate across the time window — the
+ * receive loop just emits one raw `Seconds` value per processed event.
+ *
+ * Name chosen to match the PRD's alarm threshold (`p95 > 10s`).
+ */
+export const SYNC_LATENCY_METRIC_NAME = "hq-cloud.sync.p95_latency_seconds";
+// ── Client ─────────────────────────────────────────────────────────────────
+let _cwClient;
+function getCloudWatchClient() {
+    if (!_cwClient) {
+        _cwClient = new CloudWatchClient({});
+    }
+    return _cwClient;
+}
+/**
+ * Replace the CloudWatch client (for testing).
+ * @internal
+ */
+export function _setSyncCloudWatchClient(client) {
+    _cwClient = client;
+}
+/**
+ * Publish a single latency datum to CloudWatch.
+ *
+ * Best-effort: any error from the SDK is CAUGHT and logged. A CloudWatch outage
+ * MUST NOT crash the sync receive loop — the cadence safety net still picks up
+ * missed work, and metric blanks are recoverable; a crashed loop is not.
+ *
+ * Dimension: `TenantId` only. The `relativePath`/`sequenceNumber` fields on the
+ * input are intentionally NOT promoted to dimensions (cardinality), but they
+ * ride along on the failure log so an operator can correlate a missed datum to
+ * its 3-log chain entry.
+ */
+export async function publishSyncLatencyMetric(metric, opts = {}) {
+    const datum = {
+        MetricName: SYNC_LATENCY_METRIC_NAME,
+        Value: metric.latencySeconds,
+        Unit: "Seconds",
+        Timestamp: metric.timestamp,
+        Dimensions: [{ Name: "TenantId", Value: metric.tenantId }],
+    };
+    try {
+        const client = opts.client ?? getCloudWatchClient();
+        await client.send(new PutMetricDataCommand({
+            Namespace: SYNC_METRIC_NAMESPACE,
+            MetricData: [datum],
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (opts.logger) {
+            opts.logger.warn({
+                event: "sync.metric.publish_failed",
+                tenantId: metric.tenantId,
+                relativePath: metric.relativePath,
+                sequenceNumber: metric.sequenceNumber,
+                err: { message },
+            }, "failed to publish sync latency metric to CloudWatch");
+        }
+        else {
+            console.error("Failed to publish sync latency metric to CloudWatch:", message);
+        }
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/sync/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/sync/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,4BAA4B,CAAC;AAGpC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,mCAAmC,CAAC;AAuB5E,8EAA8E;AAE9E,IAAI,SAAuC,CAAC;AAE5C,SAAS,mBAAmB;IAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAwB;IAC/D,SAAS,GAAG,MAAM,CAAC;AACrB,CAAC;AAWD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAyB,EACzB,OAAwC,EAAE;IAE1C,MAAM,KAAK,GAAgB;QACzB,UAAU,EAAE,wBAAwB;QACpC,KAAK,EAAE,MAAM,CAAC,cAAc;QAC5B,IAAI,EAAE,SAAS;QACf,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;KAC3D,CAAC;IAEF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACpD,MAAM,MAAM,CAAC,IAAI,CACf,IAAI,oBAAoB,CAAC;YACvB,SAAS,EAAE,qBAAqB;YAChC,UAAU,EAAE,CAAC,KAAK,CAAC;SACpB,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CACd;gBACE,KAAK,EAAE,4BAA4B;gBACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,GAAG,EAAE,EAAE,OAAO,EAAE;aACjB,EACD,qDAAqD,CACtD,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CACX,sDAAsD,EACtD,OAAO,CACR,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/sync/metrics.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * US-011 — unit tests for `src/sync/metrics.ts` + the receive-success-path
+ * metric emission wired into {@link SqsPushReceiver}.
+ *
+ * Mirrors the hq-pro PR #112 metrics test:
+ *   - mock the CloudWatchClient via `aws-sdk-client-mock`
+ *   - inject the mocked client via the `_setSyncCloudWatchClient` test seam
+ *   - assert namespace, metric name, unit, dimensions, value
+ *   - assert SDK errors are CAUGHT (the receive loop must never crash on a
+ *     CloudWatch outage)
+ *
+ * Plus the US-011-specific receiver wiring:
+ *   - on the receive-SUCCESS path, the receiver publishes exactly one latency
+ *     datum carrying the event's tenantId + sequenceNumber (mocked publish seam
+ *     — no real AWS)
+ *   - a failing publish seam does NOT crash the receiver loop
+ */
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/sync/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../../src/sync/metrics.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}