@indigoai-us/hq-cloud 5.25.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-event.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Unit tests for `src/sync/push-event.ts` (US-007 port).
+ *
+ * Covers the three required acceptance assertions:
+ *  1. A known-good fixture round-trips through encode → decode unchanged.
+ *  2. Unknown extra fields on the input are dropped silently (no throw).
+ *  3. Missing required fields throw a typed `PushEventDecodeError` whose
+ *     `.issues` exposes the underlying zod issues.
+ *
+ * Also covers the supporting invariants needed to keep the wire contract
+ * stable across the watcher → server → receiver hop: malformed JSON, bad
+ * hash/timestamp formats, and the integer/range bounds on `sequenceNumber`.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  PushEventDecodeError,
+  decodePushEvent,
+  encodePushEvent,
+  type PushEvent,
+} from "../../src/sync/index.js";
+
+// A canonical, valid PushEvent. All other tests derive from this fixture so
+// any single field mutation can't accidentally pass for the wrong reason.
+const validFixture: PushEvent = {
+  relativePath: "docs/architecture/overview.md",
+  contentHash:
+    "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  mtime: "2026-05-18T12:34:56.789Z",
+  originDeviceId: "device-laptop-a",
+  originTenantId: "tenant-indigo",
+  sequenceNumber: 42,
+  eventTimestamp: "2026-05-18T12:35:00.000Z",
+};
+
+describe("PushEvent encode/decode", () => {
+  // ── Acceptance #1: round-trip ──────────────────────────────────────────
+  it("round-trips a known-good fixture through encode → decode", () => {
+    const encoded = encodePushEvent(validFixture);
+    expect(typeof encoded).toBe("string");
+
+    const decoded = decodePushEvent(encoded);
+    expect(decoded).toEqual(validFixture);
+
+    // Re-encoding the decoded value must produce byte-identical output —
+    // catches accidental field re-ordering or coercion drift.
+    expect(encodePushEvent(decoded)).toBe(encoded);
+  });
+
+  it("decodes from a pre-parsed object as well as from a JSON string", () => {
+    const fromObject = decodePushEvent({ ...validFixture });
+    const fromString = decodePushEvent(JSON.stringify(validFixture));
+    expect(fromObject).toEqual(validFixture);
+    expect(fromString).toEqual(validFixture);
+  });
+
+  // ── Acceptance #2: unknown fields dropped ──────────────────────────────
+  it("drops unknown extra fields silently (does not throw)", () => {
+    const withExtras = {
+      ...validFixture,
+      // Future producers may add fields like `originAppVersion`; today's
+      // consumers must not crash on them.
+      originAppVersion: "1.2.3",
+      experimentalFlag: true,
+      nested: { ignored: "yes" },
+    };
+
+    const decoded = decodePushEvent(withExtras);
+    expect(decoded).toEqual(validFixture);
+    expect(decoded).not.toHaveProperty("originAppVersion");
+    expect(decoded).not.toHaveProperty("experimentalFlag");
+    expect(decoded).not.toHaveProperty("nested");
+
+    // Round-tripping through JSON behaves the same way.
+    const decodedFromJson = decodePushEvent(JSON.stringify(withExtras));
+    expect(decodedFromJson).toEqual(validFixture);
+  });
+
+  // ── Acceptance #3: missing required fields throw typed error ───────────
+  it.each([
+    "relativePath",
+    "contentHash",
+    "mtime",
+    "originDeviceId",
+    "originTenantId",
+    "sequenceNumber",
+    "eventTimestamp",
+  ] as const)("throws PushEventDecodeError when %s is missing", (field) => {
+    const partial: Record<string, unknown> = { ...validFixture };
+    delete partial[field];
+
+    let caught: unknown;
+    try {
+      decodePushEvent(partial);
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.stage).toBe("schema-validation");
+    expect(error.issues.length).toBeGreaterThan(0);
+    // The zod issue path must point at the missing field — that's what
+    // downstream callers rely on to render structured diagnostics.
+    expect(error.issues.some((issue) => issue.path.includes(field))).toBe(true);
+  });
+
+  it("PushEventDecodeError carries the underlying zod issues array", () => {
+    // Multiple missing fields → multiple issues, all reachable via `.issues`.
+    const sparse = { relativePath: "x.md" } as unknown;
+    let caught: unknown;
+    try {
+      decodePushEvent(sparse);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.issues.length).toBeGreaterThanOrEqual(6);
+  });
+
+  // ── Supporting wire-contract invariants ────────────────────────────────
+  it("throws PushEventDecodeError on malformed JSON input", () => {
+    let caught: unknown;
+    try {
+      decodePushEvent("{not valid json");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.stage).toBe("json-parse");
+    expect(error.issues.length).toBe(1);
+  });
+
+  it("surfaces a JSON-parseable non-object payload as schema-validation, not json-parse", () => {
+    // `'42'` is syntactically valid JSON, so the parse stage clears; the
+    // object-shape check is what fails. Pinning this here keeps the JSDoc
+    // contract (see decodePushEvent docs) honest.
+    let caught: unknown;
+    try {
+      decodePushEvent("42");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.stage).toBe("schema-validation");
+  });
+
+  it.each([
+    ["raw hex without `sha256:` prefix", "e".repeat(64)],
+    ["wrong algorithm prefix", `md5:${"a".repeat(64)}`],
+    ["uppercase hex", `sha256:${"A".repeat(64)}`],
+    ["too few hex chars", `sha256:${"a".repeat(63)}`],
+  ])("rejects contentHash: %s", (_label, badHash) => {
+    expect(() =>
+      decodePushEvent({ ...validFixture, contentHash: badHash }),
+    ).toThrow(PushEventDecodeError);
+  });
+
+  it.each([
+    ["missing timezone", "2026-05-18T12:34:56.789"],
+    ["space separator", "2026-05-18 12:34:56Z"],
+    ["date only", "2026-05-18"],
+  ])("rejects ISO-8601 timestamps: %s", (_label, badTimestamp) => {
+    expect(() =>
+      decodePushEvent({ ...validFixture, mtime: badTimestamp }),
+    ).toThrow(PushEventDecodeError);
+    expect(() =>
+      decodePushEvent({ ...validFixture, eventTimestamp: badTimestamp }),
+    ).toThrow(PushEventDecodeError);
+  });
+
+  it("accepts a sequenceNumber of 0 and rejects negative / fractional / oversized values", () => {
+    // 0 is allowed — sequence numbers are non-negative, not strictly positive.
+    expect(decodePushEvent({ ...validFixture, sequenceNumber: 0 })).toEqual({
+      ...validFixture,
+      sequenceNumber: 0,
+    });
+
+    expect(() =>
+      decodePushEvent({ ...validFixture, sequenceNumber: -1 }),
+    ).toThrow(PushEventDecodeError);
+    expect(() =>
+      decodePushEvent({ ...validFixture, sequenceNumber: 1.5 }),
+    ).toThrow(PushEventDecodeError);
+    expect(() =>
+      decodePushEvent({
+        ...validFixture,
+        sequenceNumber: Number.MAX_SAFE_INTEGER + 1,
+      }),
+    ).toThrow(PushEventDecodeError);
+  });
+
+  it("encodePushEvent validates and drops unknown fields from the output", () => {
+    // We cast through `unknown` because the public type forbids extra keys —
+    // this models a producer that hands us a wider object by mistake.
+    const wider = {
+      ...validFixture,
+      stray: "field",
+    } as unknown as PushEvent;
+    const encoded = encodePushEvent(wider);
+    expect(encoded.includes("stray")).toBe(false);
+    expect(JSON.parse(encoded)).toEqual(validFixture);
+  });
+
+  it("encodePushEvent throws PushEventDecodeError when input is invalid", () => {
+    const bad = { ...validFixture, contentHash: "not-a-hash" } as PushEvent;
+    let caught: unknown;
+    try {
+      encodePushEvent(bad);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PushEventDecodeError);
+    const error = caught as PushEventDecodeError;
+    expect(error.stage).toBe("schema-validation");
+    expect(
+      error.issues.some((issue) => issue.path.includes("contentHash")),
+    ).toBe(true);
+  });
+});

package/src/sync/push-event.ts

@@ -0,0 +1,208 @@
+/**
+ * PushEvent — the wire-shared payload exchanged between every link in the
+ * event-driven-hq-cloud-sync pipeline.
+ *
+ * Producers (the watcher) emit one PushEvent per local content change.
+ * Consumers (the push endpoint / receiver / coalescer) decode the payload,
+ * validate it, and act on it. Because the same shape crosses a network
+ * boundary, it has its own dedicated module.
+ *
+ * Conventions
+ * ───────────
+ * - `contentHash` is `sha256:<64-lowercase-hex>`. The `<algorithm>:<hex>`
+ *   prefix lets a future hash migration ship without breaking the wire
+ *   format — consumers can branch on the prefix and fall back to refusing
+ *   unknown algorithms.
+ * - `mtime` and `eventTimestamp` are strict ISO-8601 datetime strings.
+ *   `mtime` is the filesystem modification time of the source file at the
+ *   moment of capture; `eventTimestamp` is when the watcher emitted the
+ *   event. They diverge whenever the watcher coalesces or retries.
+ * - `sequenceNumber` is a non-negative safe integer. Monotonicity per
+ *   `originDeviceId` is a producer-side invariant — a single PushEvent
+ *   can't be self-monotonic, so the schema only validates the bounds.
+ * - Unknown extra fields are dropped silently by `decodePushEvent` to
+ *   permit forwards-compatible additions on the producer side without
+ *   forcing every consumer to upgrade in lockstep.
+ *
+ * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-event.ts) into
+ * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
+ */
+
+import { z } from "zod";
+
+// ─── Constants ─────────────────────────────────────────────────────────────
+
+/**
+ * `sha256:` + 64 lowercase hex chars. The algorithm prefix is mandatory so
+ * future hash migrations stay non-breaking; consumers can switch on the
+ * prefix and reject unknown algorithms explicitly.
+ */
+export const CONTENT_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+/**
+ * Strict ISO-8601 datetime regex matching what `z.iso.datetime()` produces.
+ *
+ * Format: `YYYY-MM-DDTHH:MM:SS(.fff)?(Z|±HH:MM)`
+ */
+export const ISO8601_DATETIME_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+// ─── Zod schema ────────────────────────────────────────────────────────────
+
+/**
+ * Runtime schema for PushEvent. Unknown extra keys are dropped via the zod
+ * default `.strip()` behavior — that is load-bearing for forwards
+ * compatibility (see module JSDoc).
+ */
+export const PushEventSchema = z
+  .object({
+    relativePath: z
+      .string()
+      .min(1, "relativePath must be a non-empty string"),
+    contentHash: z
+      .string()
+      .regex(
+        CONTENT_HASH_PATTERN,
+        "contentHash must match `sha256:<64 lowercase hex>`",
+      ),
+    mtime: z
+      .string()
+      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime"),
+    originDeviceId: z
+      .string()
+      .min(1, "originDeviceId must be a non-empty string"),
+    originTenantId: z
+      .string()
+      .min(1, "originTenantId must be a non-empty string"),
+    sequenceNumber: z
+      .number()
+      .int("sequenceNumber must be an integer")
+      .min(0, "sequenceNumber must be non-negative")
+      .max(
+        Number.MAX_SAFE_INTEGER,
+        "sequenceNumber must be <= Number.MAX_SAFE_INTEGER",
+      ),
+    eventTimestamp: z
+      .string()
+      .regex(
+        ISO8601_DATETIME_PATTERN,
+        "eventTimestamp must be an ISO-8601 datetime",
+      ),
+  })
+  // `.strip()` is the zod 4 default; called explicitly here so the intent is
+  // obvious to future readers. Unknown keys MUST NOT throw — see module JSDoc.
+  .strip();
+
+/**
+ * The canonical PushEvent type. All fields are required; producers and
+ * consumers share this exact shape.
+ */
+export type PushEvent = z.infer<typeof PushEventSchema>;
+
+// ─── Errors ────────────────────────────────────────────────────────────────
+
+/**
+ * Public alias for a single decode issue. Aliased here (rather than re-exporting
+ * the `$`-prefixed zod internal symbol directly) so consumers can annotate
+ * against `PushEventDecodeIssue` without importing zod internals. The alias is
+ * structurally identical to `z.core.$ZodIssue`, so this is a non-breaking
+ * narrowing of the public surface.
+ */
+export type PushEventDecodeIssue = z.core.$ZodIssue;
+
+/**
+ * Thrown by `decodePushEvent` (and `encodePushEvent` on invalid input) when
+ * the payload fails validation. `.issues` carries the underlying zod issues
+ * so callers can render structured diagnostics — see the test suite for an
+ * example of asserting on the issue path.
+ */
+export class PushEventDecodeError extends Error {
+  readonly issues: readonly PushEventDecodeIssue[];
+  readonly stage: "json-parse" | "schema-validation";
+
+  constructor(
+    message: string,
+    args: {
+      issues: readonly PushEventDecodeIssue[];
+      stage: "json-parse" | "schema-validation";
+      cause?: unknown;
+    },
+  ) {
+    super(message, args.cause === undefined ? undefined : { cause: args.cause });
+    this.name = "PushEventDecodeError";
+    this.issues = args.issues;
+    this.stage = args.stage;
+  }
+}
+
+// ─── Encode / Decode ───────────────────────────────────────────────────────
+
+/**
+ * Validate `event` against `PushEventSchema` and return the canonical JSON
+ * serialization. Validating on encode catches producer-side mistakes early
+ * (and ensures the output always round-trips through `decodePushEvent`).
+ *
+ * Extra keys on `event` are dropped — the returned JSON string contains
+ * only the declared PushEvent fields.
+ */
+export function encodePushEvent(event: PushEvent): string {
+  const parsed = PushEventSchema.safeParse(event);
+  if (!parsed.success) {
+    throw new PushEventDecodeError(
+      "encodePushEvent: input failed PushEvent schema validation",
+      { issues: parsed.error.issues, stage: "schema-validation" },
+    );
+  }
+  return JSON.stringify(parsed.data);
+}
+
+/**
+ * Parse and validate an incoming PushEvent. Accepts either a raw JSON string
+ * (the on-the-wire form) or an already-parsed object (handy for in-process
+ * wiring and tests).
+ *
+ * - Unknown extra fields are dropped silently — see module JSDoc.
+ * - Missing required fields throw `PushEventDecodeError` whose `.issues`
+ *   exposes the underlying zod issues.
+ * - Malformed JSON throws `PushEventDecodeError` with `stage:"json-parse"`
+ *   and a synthetic issue at the root path.
+ * - A JSON string that parses to a non-object value (e.g. `'42'`, `'"text"'`,
+ *   `'null'`) surfaces as `stage: 'schema-validation'` — the JSON itself was
+ *   syntactically valid, so it clears the parse stage before failing the
+ *   object-shape check.
+ */
+export function decodePushEvent(input: unknown): PushEvent {
+  let candidate: unknown = input;
+
+  if (typeof input === "string") {
+    try {
+      candidate = JSON.parse(input);
+    } catch (err) {
+      throw new PushEventDecodeError(
+        "decodePushEvent: input string is not valid JSON",
+        {
+          issues: [
+            {
+              code: "custom",
+              message:
+                err instanceof Error ? err.message : "invalid JSON input",
+              path: [],
+              input,
+            } as PushEventDecodeIssue,
+          ],
+          stage: "json-parse",
+          cause: err,
+        },
+      );
+    }
+  }
+
+  const parsed = PushEventSchema.safeParse(candidate);
+  if (!parsed.success) {
+    throw new PushEventDecodeError(
+      "decodePushEvent: payload failed PushEvent schema validation",
+      { issues: parsed.error.issues, stage: "schema-validation" },
+    );
+  }
+  return parsed.data;
+}