@indigoai-us/hq-cloud 5.25.0 → 5.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/.github/workflows/ci.yml +34 -0
  2. package/dist/bin/sync-runner.d.ts +138 -1
  3. package/dist/bin/sync-runner.d.ts.map +1 -1
  4. package/dist/bin/sync-runner.js +288 -16
  5. package/dist/bin/sync-runner.js.map +1 -1
  6. package/dist/bin/sync-runner.test.js +372 -1
  7. package/dist/bin/sync-runner.test.js.map +1 -1
  8. package/dist/index.d.ts +4 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +6 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/sync/feature-flags.d.ts +136 -0
  13. package/dist/sync/feature-flags.d.ts.map +1 -0
  14. package/dist/sync/feature-flags.js +160 -0
  15. package/dist/sync/feature-flags.js.map +1 -0
  16. package/dist/sync/feature-flags.test.d.ts +24 -0
  17. package/dist/sync/feature-flags.test.d.ts.map +1 -0
  18. package/dist/sync/feature-flags.test.js +330 -0
  19. package/dist/sync/feature-flags.test.js.map +1 -0
  20. package/dist/sync/index.d.ts +19 -0
  21. package/dist/sync/index.d.ts.map +1 -0
  22. package/dist/sync/index.js +13 -0
  23. package/dist/sync/index.js.map +1 -0
  24. package/dist/sync/logger.d.ts +61 -0
  25. package/dist/sync/logger.d.ts.map +1 -0
  26. package/dist/sync/logger.js +51 -0
  27. package/dist/sync/logger.js.map +1 -0
  28. package/dist/sync/logger.test.d.ts +19 -0
  29. package/dist/sync/logger.test.d.ts.map +1 -0
  30. package/dist/sync/logger.test.js +199 -0
  31. package/dist/sync/logger.test.js.map +1 -0
  32. package/dist/sync/metrics.d.ts +89 -0
  33. package/dist/sync/metrics.d.ts.map +1 -0
  34. package/dist/sync/metrics.js +105 -0
  35. package/dist/sync/metrics.js.map +1 -0
  36. package/dist/sync/metrics.test.d.ts +19 -0
  37. package/dist/sync/metrics.test.d.ts.map +1 -0
  38. package/dist/sync/metrics.test.js +280 -0
  39. package/dist/sync/metrics.test.js.map +1 -0
  40. package/dist/sync/push-event.d.ts +110 -0
  41. package/dist/sync/push-event.d.ts.map +1 -0
  42. package/dist/sync/push-event.js +153 -0
  43. package/dist/sync/push-event.js.map +1 -0
  44. package/dist/sync/push-event.test.d.ts +15 -0
  45. package/dist/sync/push-event.test.d.ts.map +1 -0
  46. package/dist/sync/push-event.test.js +188 -0
  47. package/dist/sync/push-event.test.js.map +1 -0
  48. package/dist/sync/push-receiver.d.ts +442 -0
  49. package/dist/sync/push-receiver.d.ts.map +1 -0
  50. package/dist/sync/push-receiver.js +782 -0
  51. package/dist/sync/push-receiver.js.map +1 -0
  52. package/dist/sync/push-receiver.test.d.ts +25 -0
  53. package/dist/sync/push-receiver.test.d.ts.map +1 -0
  54. package/dist/sync/push-receiver.test.js +477 -0
  55. package/dist/sync/push-receiver.test.js.map +1 -0
  56. package/dist/sync/push-transport.d.ts +150 -0
  57. package/dist/sync/push-transport.d.ts.map +1 -0
  58. package/dist/sync/push-transport.js +150 -0
  59. package/dist/sync/push-transport.js.map +1 -0
  60. package/dist/watcher.d.ts +271 -0
  61. package/dist/watcher.d.ts.map +1 -1
  62. package/dist/watcher.js +480 -3
  63. package/dist/watcher.js.map +1 -1
  64. package/dist/watcher.test.d.ts +2 -0
  65. package/dist/watcher.test.d.ts.map +1 -0
  66. package/dist/watcher.test.js +334 -0
  67. package/dist/watcher.test.js.map +1 -0
  68. package/package.json +10 -5
  69. package/src/bin/sync-runner.test.ts +487 -1
  70. package/src/bin/sync-runner.ts +406 -9
  71. package/src/index.ts +38 -0
  72. package/src/sync/feature-flags.test.ts +392 -0
  73. package/src/sync/feature-flags.ts +229 -0
  74. package/src/sync/index.ts +74 -0
  75. package/src/sync/logger.test.ts +241 -0
  76. package/src/sync/logger.ts +79 -0
  77. package/src/sync/metrics.test.ts +380 -0
  78. package/src/sync/metrics.ts +158 -0
  79. package/src/sync/push-event.test.ts +224 -0
  80. package/src/sync/push-event.ts +208 -0
  81. package/src/sync/push-receiver.test.ts +545 -0
  82. package/src/sync/push-receiver.ts +1077 -0
  83. package/src/sync/push-transport.ts +231 -0
  84. package/src/watcher.test.ts +388 -0
  85. package/src/watcher.ts +672 -4
  86. package/test/e2e/sync/cross-tenant-isolation.test.ts +502 -0
  87. package/test/e2e/watcher-real-chokidar.test.ts +105 -0
@@ -0,0 +1,241 @@
1
+ /**
2
+ * US-011 — unit tests for the pino logger factory + the 3-log diagnostic
3
+ * chain's CLIENT-side correlated fields.
4
+ *
5
+ * The PRD requires three correlated logs sharing the same `sequenceNumber`:
6
+ * 1. `watcher.emit` — client push (US-008 PushEventEmitter) [client]
7
+ * 2. `push.receive` — server (hq-pro) [server]
8
+ * 3. `fanout.receive` — client fanout-receive (US-009 receiver) [client]
9
+ *
10
+ * This package owns the two CLIENT-side links. These tests prove:
11
+ * - `createLogger` stamps the `component` tag on every line and respects
12
+ * level + injected destination.
13
+ * - the watcher emits `event=watcher.emit` carrying `sequenceNumber`.
14
+ * - the receiver emits `event=fanout.receive` carrying the SAME
15
+ * `sequenceNumber` → an operator can join the two client links (and the
16
+ * server `push.receive` line, which carries the same key) end-to-end.
17
+ */
18
+
19
+ import { mkdtemp, rm, writeFile } from "node:fs/promises";
20
+ import { tmpdir } from "node:os";
21
+ import { join } from "node:path";
22
+ import { Writable } from "node:stream";
23
+
24
+ import { afterEach, describe, expect, it } from "vitest";
25
+
26
+ import { createLogger } from "./logger.js";
27
+ import { encodePushEvent, type PushEvent } from "./push-event.js";
28
+ import { NoopPushTransport } from "./push-transport.js";
29
+ import { StaticFlagProvider } from "./feature-flags.js";
30
+ import {
31
+ SqsPushReceiver,
32
+ type SqsClientLike,
33
+ type SqsMessageLike,
34
+ } from "./push-receiver.js";
35
+ import { PushEventEmitter, type TreeChangeBatch } from "../watcher.js";
36
+
37
+ const TENANT = "tenant-indigo";
38
+
39
+ // ── Capture stream + JSON line reader ─────────────────────────────────────────
40
+
41
+ function captureStream(): { stream: Writable; lines: () => Array<Record<string, unknown>> } {
42
+ const chunks: string[] = [];
43
+ const stream = new Writable({
44
+ write(chunk, _enc, cb) {
45
+ chunks.push(
46
+ typeof chunk === "string" ? chunk : (chunk as Buffer).toString("utf8"),
47
+ );
48
+ cb();
49
+ },
50
+ });
51
+ return {
52
+ stream,
53
+ lines: () =>
54
+ chunks
55
+ .join("")
56
+ .split("\n")
57
+ .filter((s) => s.length > 0)
58
+ .map((s) => JSON.parse(s) as Record<string, unknown>),
59
+ };
60
+ }
61
+
62
+ async function until(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
63
+ const start = Date.now();
64
+ while (!predicate()) {
65
+ if (Date.now() - start > timeoutMs) throw new Error("until() timed out");
66
+ await new Promise((r) => setTimeout(r, 5));
67
+ }
68
+ }
69
+
70
+ function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
71
+ return {
72
+ relativePath: "companies/indigo/notes.md",
73
+ contentHash:
74
+ "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
75
+ mtime: "2026-05-21T12:34:56.000Z",
76
+ originDeviceId: "device-A",
77
+ originTenantId: TENANT,
78
+ sequenceNumber: 1,
79
+ eventTimestamp: "2026-05-21T12:34:56.000Z",
80
+ ...overrides,
81
+ };
82
+ }
83
+
84
+ class OneBatchSqs implements SqsClientLike {
85
+ private batch: SqsMessageLike[] | null;
86
+ constructor(messages: SqsMessageLike[]) {
87
+ this.batch = messages;
88
+ }
89
+ async receiveMessage(args: {
90
+ queueUrl: string;
91
+ maxMessages: number;
92
+ waitTimeSeconds: number;
93
+ signal: AbortSignal;
94
+ }): Promise<{ messages: SqsMessageLike[] }> {
95
+ if (this.batch) {
96
+ const b = this.batch;
97
+ this.batch = null;
98
+ return { messages: b };
99
+ }
100
+ return new Promise((resolve) => {
101
+ if (args.signal.aborted) return resolve({ messages: [] });
102
+ const t = setTimeout(() => resolve({ messages: [] }), 5);
103
+ (t as { unref?: () => void }).unref?.();
104
+ args.signal.addEventListener(
105
+ "abort",
106
+ () => {
107
+ clearTimeout(t);
108
+ resolve({ messages: [] });
109
+ },
110
+ { once: true },
111
+ );
112
+ });
113
+ }
114
+ async deleteMessage(): Promise<void> {
115
+ /* no-op */
116
+ }
117
+ }
118
+
119
+ // ── createLogger ──────────────────────────────────────────────────────────────
120
+
121
+ describe("createLogger", () => {
122
+ it("stamps the `component` tag on every line", () => {
123
+ const { stream, lines } = captureStream();
124
+ const log = createLogger({
125
+ component: "sync-watcher",
126
+ destination: stream,
127
+ level: "info",
128
+ });
129
+ log.info({ event: "x" }, "hello");
130
+ log.warn({ event: "y" }, "world");
131
+ const out = lines();
132
+ expect(out).toHaveLength(2);
133
+ expect(out.every((l) => l.component === "sync-watcher")).toBe(true);
134
+ });
135
+
136
+ it("respects the injected level (debug below info is dropped at info)", () => {
137
+ const { stream, lines } = captureStream();
138
+ const log = createLogger({
139
+ component: "c",
140
+ destination: stream,
141
+ level: "info",
142
+ });
143
+ log.debug({ event: "d" }, "dropped");
144
+ log.info({ event: "i" }, "kept");
145
+ const out = lines();
146
+ expect(out).toHaveLength(1);
147
+ expect(out[0]!.event).toBe("i");
148
+ });
149
+ });
150
+
151
+ // ── 3-log chain: client-side correlated fields share sequenceNumber ───────────
152
+
153
+ describe("3-log diagnostic chain (client links share sequenceNumber)", () => {
154
+ let tmp: string | undefined;
155
+ let receiver: SqsPushReceiver | undefined;
156
+
157
+ afterEach(async () => {
158
+ if (receiver) {
159
+ await receiver.dispose();
160
+ receiver = undefined;
161
+ }
162
+ if (tmp) {
163
+ await rm(tmp, { recursive: true, force: true });
164
+ tmp = undefined;
165
+ }
166
+ });
167
+
168
+ it("watcher.emit and fanout.receive carry the SAME sequenceNumber", async () => {
169
+ const SEQ = 4242;
170
+
171
+ // ── Link 1: watcher.emit (client push side) ──────────────────────────
172
+ tmp = await mkdtemp(join(tmpdir(), "us011-logger-"));
173
+ const absPath = join(tmp, "notes.md");
174
+ await writeFile(absPath, "hello world", "utf8");
175
+
176
+ const watcherCap = captureStream();
177
+ const watcherLog = createLogger({
178
+ component: "sync-watcher",
179
+ destination: watcherCap.stream,
180
+ level: "info",
181
+ });
182
+
183
+ const emitter = new PushEventEmitter({
184
+ originTenantId: TENANT,
185
+ originDeviceId: "device-A",
186
+ transport: new NoopPushTransport(),
187
+ flagProvider: new StaticFlagProvider([TENANT]),
188
+ getSequenceNumber: () => SEQ,
189
+ logger: watcherLog,
190
+ });
191
+
192
+ const batch: TreeChangeBatch = {
193
+ paths: new Map([[absPath, "companies/indigo/notes.md"]]),
194
+ };
195
+ await emitter.emitForBatch(batch);
196
+
197
+ const emitLine = watcherCap
198
+ .lines()
199
+ .find((l) => l.event === "watcher.emit");
200
+ expect(emitLine).toBeDefined();
201
+ expect(emitLine!.sequenceNumber).toBe(SEQ);
202
+ expect(emitLine!.component).toBe("sync-watcher");
203
+
204
+ // ── Link 3: fanout.receive (client receive side) ─────────────────────
205
+ const receiverCap = captureStream();
206
+ const receiverLog = createLogger({
207
+ component: "sync-receiver",
208
+ destination: receiverCap.stream,
209
+ level: "info",
210
+ });
211
+ const event = makeEvent({ sequenceNumber: SEQ });
212
+
213
+ receiver = new SqsPushReceiver({
214
+ tenantId: TENANT,
215
+ queueUrl: "https://sqs.local/q",
216
+ sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh" }]),
217
+ syncFn: async () => {
218
+ /* success */
219
+ },
220
+ enabled: true,
221
+ logger: receiverLog,
222
+ // Inject a no-op metric so no real AWS is touched.
223
+ publishMetric: async () => {},
224
+ });
225
+
226
+ await receiver.start();
227
+ await until(() =>
228
+ receiverCap.lines().some((l) => l.event === "fanout.receive"),
229
+ );
230
+
231
+ const recvLine = receiverCap
232
+ .lines()
233
+ .find((l) => l.event === "fanout.receive");
234
+ expect(recvLine).toBeDefined();
235
+ expect(recvLine!.sequenceNumber).toBe(SEQ);
236
+ expect(recvLine!.component).toBe("sync-receiver");
237
+
238
+ // ── The join key matches across both client links ────────────────────
239
+ expect(emitLine!.sequenceNumber).toBe(recvLine!.sequenceNumber);
240
+ });
241
+ });
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Component-tagged logger factory for the hq-cloud sync subsystem
3
+ * (project event-driven-sync-menubar US-011).
4
+ *
5
+ * Every log line emitted from a sync module SHOULD carry a `component` field
6
+ * so operators can grep / route by subsystem in the aggregated JSON stream.
7
+ * `createLogger({ component: "sync-watcher" })` is the canonical entry point —
8
+ * modules call this once at module-load time and use the returned logger for
9
+ * the lifetime of the process.
10
+ *
11
+ * The 3-log diagnostic chain (US-011)
12
+ * ───────────────────────────────────
13
+ * Three correlated log lines share a single `sequenceNumber` join key so an
14
+ * operator can walk one event end-to-end:
15
+ * 1. `event=watcher.emit` — client push side (US-008 PushEventEmitter)
16
+ * 2. `event=push.receive` — server side (hq-pro; context only here)
17
+ * 3. `event=fanout.receive` — client fanout-receive side (US-009 receiver)
18
+ * The watcher.emit + fanout.receive halves live in this client package; the
19
+ * push.receive half lives server-side in hq-pro. All three stamp the same
20
+ * `sequenceNumber` for log-chain correlation.
21
+ *
22
+ * Output format: pino's default newline-delimited JSON. No transports, no
23
+ * pretty-printing — the daemon consumes the raw JSON stream. (Operators who
24
+ * want pretty output pipe through `pino-pretty` themselves.)
25
+ *
26
+ * Destination injection: tests pass a `destination` stream so they can capture
27
+ * log lines and assert on them. Production callers omit it and pino defaults
28
+ * to `process.stdout`.
29
+ *
30
+ * Adapted from indigoai-us/hq-pro PR #112 (src/sync/logger.ts) into
31
+ * @indigoai-us/hq-cloud (Path B).
32
+ */
33
+
34
+ import {
35
+ pino,
36
+ type DestinationStream,
37
+ type Level,
38
+ type Logger,
39
+ type LoggerOptions,
40
+ } from "pino";
41
+
42
+ export interface CreateLoggerOptions {
43
+ /**
44
+ * Component tag stamped on every log line as `"component": <value>`.
45
+ * Required so daemon / watcher / receiver lines never appear in the stream
46
+ * untagged.
47
+ */
48
+ component: string;
49
+ /**
50
+ * Optional pino level. Default: pino's own default (`info`). Set via
51
+ * `LOG_LEVEL` env var, command-line flag, or test injection.
52
+ */
53
+ level?: Level;
54
+ /**
55
+ * Optional pino destination. Default: `process.stdout`. Tests inject a
56
+ * memory stream here to capture lines for assertion.
57
+ */
58
+ destination?: DestinationStream;
59
+ }
60
+
61
+ /**
62
+ * Build a pino logger pre-bound to a `component` tag.
63
+ *
64
+ * Use this — not a bare `pino()` call — so every sync module's log lines carry
65
+ * the tag uniformly. Adding more bound fields (e.g. `deviceId`, `tenantId`) is
66
+ * a `logger.child({ ... })` call away.
67
+ */
68
+ export function createLogger(opts: CreateLoggerOptions): Logger {
69
+ const { component, level, destination } = opts;
70
+ const pinoOpts: LoggerOptions = {
71
+ base: { component },
72
+ ...(level === undefined ? {} : { level }),
73
+ };
74
+ return destination === undefined
75
+ ? pino(pinoOpts)
76
+ : pino(pinoOpts, destination);
77
+ }
78
+
79
+ export type { Logger } from "pino";
@@ -0,0 +1,380 @@
1
+ /**
2
+ * US-011 — unit tests for `src/sync/metrics.ts` + the receive-success-path
3
+ * metric emission wired into {@link SqsPushReceiver}.
4
+ *
5
+ * Mirrors the hq-pro PR #112 metrics test:
6
+ * - mock the CloudWatchClient via `aws-sdk-client-mock`
7
+ * - inject the mocked client via the `_setSyncCloudWatchClient` test seam
8
+ * - assert namespace, metric name, unit, dimensions, value
9
+ * - assert SDK errors are CAUGHT (the receive loop must never crash on a
10
+ * CloudWatch outage)
11
+ *
12
+ * Plus the US-011-specific receiver wiring:
13
+ * - on the receive-SUCCESS path, the receiver publishes exactly one latency
14
+ * datum carrying the event's tenantId + sequenceNumber (mocked publish seam
15
+ * — no real AWS)
16
+ * - a failing publish seam does NOT crash the receiver loop
17
+ */
18
+
19
+ import { Writable } from "node:stream";
20
+
21
+ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
22
+ import { mockClient } from "aws-sdk-client-mock";
23
+ import {
24
+ CloudWatchClient,
25
+ PutMetricDataCommand,
26
+ } from "@aws-sdk/client-cloudwatch";
27
+
28
+ import {
29
+ SYNC_LATENCY_METRIC_NAME,
30
+ SYNC_METRIC_NAMESPACE,
31
+ _setSyncCloudWatchClient,
32
+ publishSyncLatencyMetric,
33
+ type SyncLatencyMetric,
34
+ } from "./metrics.js";
35
+ import { createLogger } from "./logger.js";
36
+ import { encodePushEvent, type PushEvent } from "./push-event.js";
37
+ import {
38
+ SqsPushReceiver,
39
+ type PublishMetricFn,
40
+ type SqsClientLike,
41
+ type SqsMessageLike,
42
+ } from "./push-receiver.js";
43
+
44
+ // ── Helpers ─────────────────────────────────────────────────────────────────
45
+
46
+ function makeMetric(overrides: Partial<SyncLatencyMetric> = {}): SyncLatencyMetric {
47
+ return {
48
+ tenantId: "tenant-A",
49
+ relativePath: "docs/overview.md",
50
+ sequenceNumber: 42,
51
+ latencySeconds: 1.234,
52
+ timestamp: new Date("2026-05-19T12:00:00.000Z"),
53
+ ...overrides,
54
+ };
55
+ }
56
+
57
+ function captureStream(): { stream: Writable; lines: () => unknown[] } {
58
+ const chunks: string[] = [];
59
+ const stream = new Writable({
60
+ write(chunk, _enc, cb) {
61
+ chunks.push(
62
+ typeof chunk === "string" ? chunk : (chunk as Buffer).toString("utf8"),
63
+ );
64
+ cb();
65
+ },
66
+ });
67
+ return {
68
+ stream,
69
+ lines: () =>
70
+ chunks
71
+ .join("")
72
+ .split("\n")
73
+ .filter((s) => s.length > 0)
74
+ .map((s) => JSON.parse(s) as unknown),
75
+ };
76
+ }
77
+
78
+ const TENANT = "tenant-indigo";
79
+ const QUEUE_URL =
80
+ "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-indigo-deviceB";
81
+
82
+ function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
83
+ return {
84
+ relativePath: "companies/indigo/notes.md",
85
+ contentHash:
86
+ "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
87
+ mtime: "2026-05-21T12:34:56.000Z",
88
+ originDeviceId: "device-A",
89
+ originTenantId: TENANT,
90
+ sequenceNumber: 7,
91
+ eventTimestamp: "2026-05-21T12:34:56.000Z",
92
+ ...overrides,
93
+ };
94
+ }
95
+
96
+ /** Minimal fake SQS that drains one batch then idles until abort. */
97
+ class OneBatchSqs implements SqsClientLike {
98
+ private batch: SqsMessageLike[] | null;
99
+ readonly deleted: string[] = [];
100
+
101
+ constructor(messages: SqsMessageLike[]) {
102
+ this.batch = messages;
103
+ }
104
+
105
+ async receiveMessage(args: {
106
+ queueUrl: string;
107
+ maxMessages: number;
108
+ waitTimeSeconds: number;
109
+ signal: AbortSignal;
110
+ }): Promise<{ messages: SqsMessageLike[] }> {
111
+ if (this.batch) {
112
+ const b = this.batch;
113
+ this.batch = null;
114
+ return { messages: b };
115
+ }
116
+ return new Promise((resolve) => {
117
+ if (args.signal.aborted) return resolve({ messages: [] });
118
+ const t = setTimeout(() => resolve({ messages: [] }), 5);
119
+ (t as { unref?: () => void }).unref?.();
120
+ args.signal.addEventListener(
121
+ "abort",
122
+ () => {
123
+ clearTimeout(t);
124
+ resolve({ messages: [] });
125
+ },
126
+ { once: true },
127
+ );
128
+ });
129
+ }
130
+
131
+ async deleteMessage(args: {
132
+ queueUrl: string;
133
+ receiptHandle: string;
134
+ }): Promise<void> {
135
+ this.deleted.push(args.receiptHandle);
136
+ }
137
+ }
138
+
139
+ /** Wait until `predicate()` is true (polling), or throw after `timeoutMs`. */
140
+ async function until(
141
+ predicate: () => boolean,
142
+ timeoutMs = 1000,
143
+ ): Promise<void> {
144
+ const start = Date.now();
145
+ while (!predicate()) {
146
+ if (Date.now() - start > timeoutMs) {
147
+ throw new Error("until() timed out");
148
+ }
149
+ await new Promise((r) => setTimeout(r, 5));
150
+ }
151
+ }
152
+
153
+ // ── publishSyncLatencyMetric (CloudWatch contract) ───────────────────────────
154
+
155
+ const cwMock = mockClient(CloudWatchClient);
156
+
157
+ describe("publishSyncLatencyMetric", () => {
158
+ beforeEach(() => {
159
+ cwMock.reset();
160
+ _setSyncCloudWatchClient(cwMock as unknown as CloudWatchClient);
161
+ });
162
+
163
+ it("sends a single PutMetricData with the documented namespace + metric name", async () => {
164
+ cwMock.on(PutMetricDataCommand).resolves({});
165
+
166
+ await publishSyncLatencyMetric(makeMetric());
167
+
168
+ const calls = cwMock.commandCalls(PutMetricDataCommand);
169
+ expect(calls).toHaveLength(1);
170
+
171
+ const input = calls[0]!.args[0].input;
172
+ expect(input.Namespace).toBe(SYNC_METRIC_NAMESPACE);
173
+ expect(input.Namespace).toBe("HQPro/Sync");
174
+ expect(input.MetricData).toHaveLength(1);
175
+ expect(input.MetricData![0].MetricName).toBe(SYNC_LATENCY_METRIC_NAME);
176
+ expect(input.MetricData![0].MetricName).toBe(
177
+ "hq-cloud.sync.p95_latency_seconds",
178
+ );
179
+ });
180
+
181
+ it("uses Unit=Seconds and stamps the supplied timestamp", async () => {
182
+ cwMock.on(PutMetricDataCommand).resolves({});
183
+
184
+ const ts = new Date("2026-05-19T07:00:00.000Z");
185
+ await publishSyncLatencyMetric(makeMetric({ timestamp: ts }));
186
+
187
+ const datum = cwMock.commandCalls(PutMetricDataCommand)[0]!.args[0].input
188
+ .MetricData![0];
189
+ expect(datum.Unit).toBe("Seconds");
190
+ expect(datum.Timestamp).toEqual(ts);
191
+ });
192
+
193
+ it("publishes the observed latencySeconds value verbatim", async () => {
194
+ cwMock.on(PutMetricDataCommand).resolves({});
195
+
196
+ await publishSyncLatencyMetric(makeMetric({ latencySeconds: 2.71828 }));
197
+
198
+ const datum = cwMock.commandCalls(PutMetricDataCommand)[0]!.args[0].input
199
+ .MetricData![0];
200
+ expect(datum.Value).toBe(2.71828);
201
+ });
202
+
203
+ it("attaches a `TenantId` dimension carrying the tenantId", async () => {
204
+ cwMock.on(PutMetricDataCommand).resolves({});
205
+
206
+ await publishSyncLatencyMetric(makeMetric({ tenantId: "tenant-prs_xyz" }));
207
+
208
+ const datum = cwMock.commandCalls(PutMetricDataCommand)[0]!.args[0].input
209
+ .MetricData![0];
210
+ expect(datum.Dimensions).toEqual([
211
+ { Name: "TenantId", Value: "tenant-prs_xyz" },
212
+ ]);
213
+ });
214
+
215
+ it("does not throw when the CloudWatch SDK rejects (sync loop must not crash)", async () => {
216
+ cwMock
217
+ .on(PutMetricDataCommand)
218
+ .rejects(new Error("CloudWatch unavailable"));
219
+ const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
220
+
221
+ await expect(
222
+ publishSyncLatencyMetric(makeMetric()),
223
+ ).resolves.toBeUndefined();
224
+
225
+ expect(consoleSpy).toHaveBeenCalledWith(
226
+ "Failed to publish sync latency metric to CloudWatch:",
227
+ "CloudWatch unavailable",
228
+ );
229
+
230
+ consoleSpy.mockRestore();
231
+ });
232
+
233
+ it("routes SDK failures through the supplied pino logger when provided", async () => {
234
+ cwMock.on(PutMetricDataCommand).rejects(new Error("ThrottlingException"));
235
+ const { stream, lines } = captureStream();
236
+ const logger = createLogger({
237
+ component: "metrics-test",
238
+ destination: stream,
239
+ level: "debug",
240
+ });
241
+
242
+ await publishSyncLatencyMetric(
243
+ makeMetric({ sequenceNumber: 99, relativePath: "a.md" }),
244
+ { logger },
245
+ );
246
+
247
+ const failureLine = (lines() as Array<{ event?: string }>).find(
248
+ (l) => l.event === "sync.metric.publish_failed",
249
+ );
250
+ expect(failureLine).toBeDefined();
251
+ expect(failureLine).toMatchObject({
252
+ event: "sync.metric.publish_failed",
253
+ tenantId: "tenant-A",
254
+ relativePath: "a.md",
255
+ sequenceNumber: 99,
256
+ });
257
+ });
258
+
259
+ it("accepts a per-call client override (does not call the singleton)", async () => {
260
+ cwMock
261
+ .on(PutMetricDataCommand)
262
+ .rejects(new Error("singleton should not be used"));
263
+
264
+ const overrideMock = mockClient(CloudWatchClient);
265
+ overrideMock.on(PutMetricDataCommand).resolves({});
266
+
267
+ await publishSyncLatencyMetric(makeMetric(), {
268
+ client: overrideMock as unknown as CloudWatchClient,
269
+ });
270
+
271
+ expect(overrideMock.commandCalls(PutMetricDataCommand)).toHaveLength(1);
272
+ expect(cwMock.commandCalls(PutMetricDataCommand)).toHaveLength(0);
273
+
274
+ overrideMock.restore();
275
+ });
276
+ });
277
+
278
+ // ── Receive-success-path metric emission (US-011 AC: "metric emission unit-
279
+ // tested on the receive success path") ──────────────────────────────────
280
+
281
+ describe("SqsPushReceiver metric emission on the receive-success path", () => {
282
+ let receiver: SqsPushReceiver | undefined;
283
+
284
+ afterEach(async () => {
285
+ if (receiver) {
286
+ await receiver.dispose();
287
+ receiver = undefined;
288
+ }
289
+ });
290
+
291
+ it("publishes exactly one latency datum per processed event (mocked publish, no real AWS)", async () => {
292
+ const published: SyncLatencyMetric[] = [];
293
+ const publishMetric: PublishMetricFn = async (m) => {
294
+ published.push(m);
295
+ };
296
+ const event = makeEvent({ sequenceNumber: 7 });
297
+
298
+ receiver = new SqsPushReceiver({
299
+ tenantId: TENANT,
300
+ queueUrl: QUEUE_URL,
301
+ sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-7" }]),
302
+ syncFn: async () => {
303
+ /* successful pull */
304
+ },
305
+ enabled: true,
306
+ publishMetric,
307
+ // Fake clock: start measured at T, success at T+1500ms → 1.5s latency.
308
+ now: (() => {
309
+ let t = Date.parse(event.eventTimestamp);
310
+ return () => {
311
+ const cur = t;
312
+ t += 1500;
313
+ return cur;
314
+ };
315
+ })(),
316
+ });
317
+
318
+ await receiver.start();
319
+ await until(() => published.length >= 1);
320
+
321
+ expect(published).toHaveLength(1);
322
+ expect(published[0]).toMatchObject({
323
+ tenantId: TENANT,
324
+ relativePath: event.relativePath,
325
+ sequenceNumber: 7,
326
+ });
327
+ expect(published[0]!.latencySeconds).toBeGreaterThanOrEqual(0);
328
+ expect(Number.isFinite(published[0]!.latencySeconds)).toBe(true);
329
+ });
330
+
331
+ it("does NOT publish a metric when the syncFn throws (failures don't skew p95)", async () => {
332
+ const published: SyncLatencyMetric[] = [];
333
+ const event = makeEvent({ sequenceNumber: 8 });
334
+
335
+ receiver = new SqsPushReceiver({
336
+ tenantId: TENANT,
337
+ queueUrl: QUEUE_URL,
338
+ sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-8" }]),
339
+ syncFn: async () => {
340
+ throw new Error("pull failed");
341
+ },
342
+ enabled: true,
343
+ publishMetric: async (m) => {
344
+ published.push(m);
345
+ },
346
+ });
347
+
348
+ await receiver.start();
349
+ // Give the loop a few ticks to process the message + (not) publish.
350
+ await new Promise((r) => setTimeout(r, 50));
351
+
352
+ expect(published).toHaveLength(0);
353
+ expect(receiver.processedCount).toBe(0);
354
+ });
355
+
356
+ it("a throwing publish seam does not crash the receiver loop", async () => {
357
+ const event = makeEvent({ sequenceNumber: 9 });
358
+ let synced = false;
359
+
360
+ receiver = new SqsPushReceiver({
361
+ tenantId: TENANT,
362
+ queueUrl: QUEUE_URL,
363
+ sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-9" }]),
364
+ syncFn: async () => {
365
+ synced = true;
366
+ },
367
+ enabled: true,
368
+ publishMetric: async () => {
369
+ throw new Error("metric backend down");
370
+ },
371
+ });
372
+
373
+ await receiver.start();
374
+ await until(() => synced);
375
+
376
+ // The sync still completed and the receiver is still alive (connected).
377
+ expect(receiver.processedCount).toBe(1);
378
+ expect(receiver.connected).toBe(true);
379
+ });
380
+ });