@indigoai-us/hq-cloud 5.26.0 → 5.27.0

package/src/sync/metrics.ts

@@ -0,0 +1,158 @@
+/**
+ * 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,
+  type MetricDatum,
+} from "@aws-sdk/client-cloudwatch";
+import type { Logger } from "pino";
+
+// ── 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";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ── Client ─────────────────────────────────────────────────────────────────
+
+let _cwClient: CloudWatchClient | undefined;
+
+function getCloudWatchClient(): CloudWatchClient {
+  if (!_cwClient) {
+    _cwClient = new CloudWatchClient({});
+  }
+  return _cwClient;
+}
+
+/**
+ * Replace the CloudWatch client (for testing).
+ * @internal
+ */
+export function _setSyncCloudWatchClient(client: CloudWatchClient): void {
+  _cwClient = client;
+}
+
+// ── Publish ────────────────────────────────────────────────────────────────
+
+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 async function publishSyncLatencyMetric(
+  metric: SyncLatencyMetric,
+  opts: PublishSyncLatencyMetricOptions = {},
+): Promise<void> {
+  const datum: MetricDatum = {
+    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,
+      );
+    }
+  }
+}

package/src/sync/push-receiver.test.ts

@@ -0,0 +1,545 @@
+/**
+ * US-009 — push-receiver unit tests.
+ *
+ * Covers the five required behaviors from the PRD AC, against the SQS-backed
+ * {@link SqsPushReceiver} (mocked SQS client — NO real AWS) and the
+ * {@link InMemoryPushReceiver} (in-process fanout analogue):
+ *
+ *   1. subscribe lifecycle — start opens the poll loop / subscription, dispose
+ *      stops it; double-start is a no-op; flag-OFF stays dormant.
+ *   2. dedupe              — an event with sequenceNumber <= the highest seen
+ *      for its path is skipped; per-path counters are independent.
+ *   3. reconnect-replay    — a transient receiveMessage failure backs off and
+ *      resumes; SQS retention redelivers the buffered events; dedupe absorbs
+ *      redelivery (in-memory: disconnect buffers, reconnect drains).
+ *   4. flag gating         — dormant when the per-tenant flag is OFF; no queue
+ *      polled, connected stays false.
+ *   5. dispose drain       — dispose aborts + awaits the in-flight syncFn, then
+ *      disconnects; the loop terminates with no leaked timers.
+ *
+ * The live per-client SQS queue is NOT provisioned yet (server provisioning
+ * Lambda is an unbuilt follow-up — see references.md). Every test injects a
+ * fake SQS client / in-memory fanout.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { encodePushEvent, type PushEvent } from "./push-event.js";
+import { StaticFlagProvider } from "./feature-flags.js";
+import {
+  InMemoryFanout,
+  InMemoryPushReceiver,
+  NoopPushReceiver,
+  SqsPushReceiver,
+  createPushReceiver,
+  type SqsClientLike,
+  type SqsMessageLike,
+  type SyncEngineFn,
+} from "./push-receiver.js";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const TENANT = "tenant-indigo";
+const QUEUE_URL = "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-indigo-deviceA";
+
+function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
+  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.500Z",
+    ...overrides,
+  };
+}
+
+function msg(event: PushEvent, receiptHandle = `rh-${event.sequenceNumber}`): SqsMessageLike {
+  return {
+    Body: encodePushEvent(event),
+    ReceiptHandle: receiptHandle,
+    MessageId: `m-${event.relativePath}-${event.sequenceNumber}`,
+  };
+}
+
+/**
+ * A scriptable fake SQS client. `enqueue` adds batches that successive
+ * `receiveMessage` calls drain (one batch per call); once drained, it blocks
+ * on the abort signal (modeling an idle long-poll) so dispose ends it cleanly.
+ * `failNext(n)` makes the next `n` receiveMessage calls reject (transient).
+ */
+class FakeSqs implements SqsClientLike {
+  private batches: SqsMessageLike[][] = [];
+  private failCount = 0;
+  readonly deleted: string[] = [];
+  receiveCalls = 0;
+
+  enqueue(messages: SqsMessageLike[]): void {
+    this.batches.push(messages);
+  }
+  failNext(n: number): void {
+    this.failCount += n;
+  }
+
+  async receiveMessage(args: {
+    queueUrl: string;
+    maxMessages: number;
+    waitTimeSeconds: number;
+    signal: AbortSignal;
+  }): Promise<{ messages: SqsMessageLike[] }> {
+    this.receiveCalls += 1;
+    if (this.failCount > 0) {
+      this.failCount -= 1;
+      throw new Error("simulated SQS receive failure");
+    }
+    const next = this.batches.shift();
+    if (next && next.length > 0) {
+      return { messages: next };
+    }
+    // Idle long-poll: resolve empty on the next tick (or promptly on abort).
+    return new Promise((resolve) => {
+      if (args.signal.aborted) return resolve({ messages: [] });
+      const t = setTimeout(() => resolve({ messages: [] }), 5);
+      (t as { unref?: () => void }).unref?.();
+      args.signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(t);
+          resolve({ messages: [] });
+        },
+        { once: true },
+      );
+    });
+  }
+
+  async deleteMessage(args: { queueUrl: string; receiptHandle: string }): Promise<void> {
+    this.deleted.push(args.receiptHandle);
+  }
+}
+
+/** Wait until `predicate()` is true or `timeoutMs` elapses. */
+async function waitFor(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("waitFor: timed out");
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+// fast, abortable sleep so backoff doesn't slow the suite
+const fastSleep = (ms: number, signal: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const t = setTimeout(resolve, Math.min(ms, 5));
+    signal.addEventListener("abort", () => { clearTimeout(t); resolve(); }, { once: true });
+  });
+
+// ─── SqsPushReceiver ─────────────────────────────────────────────────────────
+
+describe("US-009: SqsPushReceiver — subscribe lifecycle", () => {
+  it("start opens the poll loop and processes a received event via syncFn, then deletes it", async () => {
+    const sqs = new FakeSqs();
+    const seen: string[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      seen.push(ctx.event.relativePath);
+    };
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+
+    await receiver.start();
+    expect(receiver.connected).toBe(true);
+    await waitFor(() => receiver.processedCount === 1);
+    expect(seen).toEqual(["companies/indigo/notes.md"]);
+    expect(sqs.deleted).toContain("rh-1");
+
+    await receiver.dispose();
+    expect(receiver.connected).toBe(false);
+  });
+
+  it("double-start is a no-op (single poll loop)", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await receiver.start();
+    // Let a couple poll iterations happen; a duplicated loop would roughly
+    // double the receive call rate. We just assert it stays connected + clean.
+    await new Promise((r) => setTimeout(r, 30));
+    expect(receiver.connected).toBe(true);
+    await receiver.dispose();
+  });
+
+  it("subscribes ONLY to its own tenant's queue (cross-tenant isolation boundary)", async () => {
+    const sqs = new FakeSqs();
+    const urls: string[] = [];
+    const spy: SqsClientLike = {
+      receiveMessage: (a) => {
+        urls.push(a.queueUrl);
+        return sqs.receiveMessage(a);
+      },
+      deleteMessage: (a) => sqs.deleteMessage(a),
+    };
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs: spy,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => urls.length >= 1);
+    await receiver.dispose();
+    expect(new Set(urls)).toEqual(new Set([QUEUE_URL]));
+  });
+
+  it("constructor rejects empty tenantId / queueUrl", () => {
+    expect(
+      () =>
+        new SqsPushReceiver({
+          tenantId: "",
+          queueUrl: QUEUE_URL,
+          sqs: new FakeSqs(),
+          syncFn: async () => undefined,
+          enabled: true,
+        }),
+    ).toThrow(/tenantId is required/);
+    expect(
+      () =>
+        new SqsPushReceiver({
+          tenantId: TENANT,
+          queueUrl: "",
+          sqs: new FakeSqs(),
+          syncFn: async () => undefined,
+          enabled: true,
+        }),
+    ).toThrow(/queueUrl is required/);
+  });
+});
+
+describe("US-009: SqsPushReceiver — dedupe", () => {
+  it("skips an event whose sequenceNumber <= the highest seen for that path", async () => {
+    const sqs = new FakeSqs();
+    const processed: number[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      processed.push(ctx.event.sequenceNumber);
+    };
+    // seq 1, then a redelivery of 1, then 2 — same path.
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-a")]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-b")]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 2 }), "rh-c")]);
+
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+
+    expect(processed).toEqual([1, 2]);
+    expect(receiver.dedupedCount).toBe(1);
+    // The deduped redelivery is still deleted (we don't need it again).
+    expect(sqs.deleted).toContain("rh-b");
+  });
+
+  it("dedupe is per-path — same sequence number on different paths both process", async () => {
+    const sqs = new FakeSqs();
+    const processed: string[] = [];
+    const syncFn: SyncEngineFn = async (ctx) => {
+      processed.push(ctx.event.relativePath);
+    };
+    sqs.enqueue([
+      msg(makeEvent({ relativePath: "companies/indigo/a.md", sequenceNumber: 5 }), "rh-1"),
+      msg(makeEvent({ relativePath: "companies/indigo/b.md", sequenceNumber: 5 }), "rh-2"),
+    ]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+    expect(new Set(processed)).toEqual(
+      new Set(["companies/indigo/a.md", "companies/indigo/b.md"]),
+    );
+    expect(receiver.dedupedCount).toBe(0);
+  });
+
+  it("drops an undecodable message at the wire boundary without crashing the loop", async () => {
+    const sqs = new FakeSqs();
+    sqs.enqueue([{ Body: "{not json", ReceiptHandle: "rh-bad", MessageId: "m-bad" }]);
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-good")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    await receiver.dispose();
+    expect(receiver.decodeFailureCount).toBe(1);
+    expect(sqs.deleted).toContain("rh-bad"); // poison message deleted
+    expect(sqs.deleted).toContain("rh-good");
+  });
+});
+
+describe("US-009: SqsPushReceiver — reconnect / catch-up replay", () => {
+  it("recovers from transient receiveMessage failures (backoff + resume) and replays the queue", async () => {
+    const sqs = new FakeSqs();
+    sqs.failNext(2); // two transient disconnects before the message lands
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }), "rh-1")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+      reconnect: { initialMs: 1, maxMs: 4, jitter: false },
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    await receiver.dispose();
+    expect(receiver.receiveErrorCount).toBe(2);
+    expect(sqs.deleted).toContain("rh-1");
+  });
+
+  it("a syncFn throw does not crash the loop and the next event still processes", async () => {
+    const sqs = new FakeSqs();
+    let calls = 0;
+    const syncFn: SyncEngineFn = async () => {
+      calls += 1;
+      if (calls === 1) throw new Error("boom");
+    };
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/x.md", sequenceNumber: 1 }), "rh-1")]);
+    sqs.enqueue([msg(makeEvent({ relativePath: "companies/indigo/y.md", sequenceNumber: 1 }), "rh-2")]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => calls === 2);
+    await receiver.dispose();
+    // First threw (processedCount not incremented), second succeeded.
+    expect(receiver.processedCount).toBe(1);
+    expect(sqs.deleted).toEqual(expect.arrayContaining(["rh-1", "rh-2"]));
+  });
+});
+
+describe("US-009: SqsPushReceiver — flag gating", () => {
+  it("is dormant when the per-tenant flag is OFF (no queue polled, connected stays false)", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      flagProvider: new StaticFlagProvider([]), // tenant NOT enabled
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(sqs.receiveCalls).toBe(0);
+    await receiver.dispose();
+  });
+
+  it("is active when the per-tenant flag includes the tenant", async () => {
+    const sqs = new FakeSqs();
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      flagProvider: new StaticFlagProvider([TENANT]),
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await waitFor(() => receiver.processedCount === 1);
+    expect(receiver.connected).toBe(true);
+    await receiver.dispose();
+  });
+
+  it("explicit enabled wins over the provider", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: false,
+      flagProvider: new StaticFlagProvider([TENANT]),
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(sqs.receiveCalls).toBe(0);
+    await receiver.dispose();
+  });
+});
+
+describe("US-009: SqsPushReceiver — dispose drain", () => {
+  it("aborts and drains the in-flight syncFn, then disconnects", async () => {
+    const sqs = new FakeSqs();
+    let aborted = false;
+    let resolveSync: (() => void) | null = null;
+    const syncFn: SyncEngineFn = (ctx) =>
+      new Promise<void>((resolve) => {
+        resolveSync = resolve;
+        ctx.signal.addEventListener("abort", () => {
+          aborted = true;
+          resolve();
+        });
+      });
+    sqs.enqueue([msg(makeEvent({ sequenceNumber: 1 }))]);
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn,
+      enabled: true,
+      sleep: fastSleep,
+      disposeDrainMs: 200,
+    });
+    await receiver.start();
+    await waitFor(() => resolveSync !== null);
+    await receiver.dispose();
+    expect(aborted).toBe(true);
+    expect(receiver.connected).toBe(false);
+  });
+
+  it("dispose is idempotent", async () => {
+    const sqs = new FakeSqs();
+    const receiver = new SqsPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs,
+      syncFn: async () => undefined,
+      enabled: true,
+      sleep: fastSleep,
+    });
+    await receiver.start();
+    await Promise.all([receiver.dispose(), receiver.dispose()]);
+    expect(receiver.connected).toBe(false);
+  });
+});
+
+// ─── InMemoryPushReceiver (transport analogue) ───────────────────────────────
+
+describe("US-009: InMemoryPushReceiver — disconnect buffering + reconnect drain", () => {
+  it("buffers events during disconnect and drains them on reconnect, deduping replays", async () => {
+    const fanout = new InMemoryFanout();
+    const processed: number[] = [];
+    const receiver = new InMemoryPushReceiver({
+      tenantId: TENANT,
+      fanout,
+      enabled: true,
+      syncFn: async (ctx) => {
+        processed.push(ctx.event.sequenceNumber);
+      },
+    });
+    await receiver.start();
+
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 1 })));
+    await waitFor(() => receiver.processedCount === 1);
+
+    receiver.simulateDisconnect();
+    expect(receiver.connected).toBe(false);
+    // Published while disconnected — buffered, not processed.
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 2 })));
+    fanout.publish(encodePushEvent(makeEvent({ sequenceNumber: 1 }))); // stale replay
+    expect(receiver.bufferedCount).toBe(2);
+
+    receiver.simulateReconnect();
+    await waitFor(() => receiver.processedCount === 2);
+    await receiver.dispose();
+
+    // seq 2 processed; the stale seq-1 replay deduped.
+    expect(processed).toEqual([1, 2]);
+    expect(receiver.dedupedCount).toBe(1);
+  });
+
+  it("is dormant when the flag is OFF", async () => {
+    const fanout = new InMemoryFanout();
+    let calls = 0;
+    const receiver = new InMemoryPushReceiver({
+      tenantId: TENANT,
+      fanout,
+      flagProvider: new StaticFlagProvider([]),
+      syncFn: async () => {
+        calls += 1;
+      },
+    });
+    await receiver.start();
+    fanout.publish(encodePushEvent(makeEvent()));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(receiver.connected).toBe(false);
+    expect(calls).toBe(0);
+    await receiver.dispose();
+  });
+});
+
+// ─── Factory + Noop ──────────────────────────────────────────────────────────
+
+describe("US-009: createPushReceiver factory", () => {
+  it("returns NoopPushReceiver for kind:noop", () => {
+    const r = createPushReceiver({ kind: "noop" });
+    expect(r).toBeInstanceOf(NoopPushReceiver);
+  });
+
+  it("returns SqsPushReceiver when a queue + sqs client are supplied", () => {
+    const r = createPushReceiver({
+      tenantId: TENANT,
+      queueUrl: QUEUE_URL,
+      sqs: new FakeSqs(),
+      syncFn: async () => undefined,
+      enabled: true,
+    });
+    expect(r).toBeInstanceOf(SqsPushReceiver);
+  });
+
+  it("NoopPushReceiver flips connected on start/dispose with no work", async () => {
+    const r = new NoopPushReceiver();
+    expect(r.connected).toBe(false);
+    await r.start();
+    expect(r.connected).toBe(true);
+    await r.dispose();
+    expect(r.connected).toBe(false);
+  });
+});