@indigoai-us/hq-cloud 5.25.0 → 5.27.0

package/dist/sync/metrics.test.js

@@ -0,0 +1,280 @@
+/**
+ * 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
+ */
+import { Writable } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mockClient } from "aws-sdk-client-mock";
+import { CloudWatchClient, PutMetricDataCommand, } from "@aws-sdk/client-cloudwatch";
+import { SYNC_LATENCY_METRIC_NAME, SYNC_METRIC_NAMESPACE, _setSyncCloudWatchClient, publishSyncLatencyMetric, } from "./metrics.js";
+import { createLogger } from "./logger.js";
+import { encodePushEvent } from "./push-event.js";
+import { SqsPushReceiver, } from "./push-receiver.js";
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function makeMetric(overrides = {}) {
+    return {
+        tenantId: "tenant-A",
+        relativePath: "docs/overview.md",
+        sequenceNumber: 42,
+        latencySeconds: 1.234,
+        timestamp: new Date("2026-05-19T12:00:00.000Z"),
+        ...overrides,
+    };
+}
+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)),
+    };
+}
+const TENANT = "tenant-indigo";
+const QUEUE_URL = "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-indigo-deviceB";
+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: 7,
+        eventTimestamp: "2026-05-21T12:34:56.000Z",
+        ...overrides,
+    };
+}
+/** Minimal fake SQS that drains one batch then idles until abort. */
+class OneBatchSqs {
+    batch;
+    deleted = [];
+    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(args) {
+        this.deleted.push(args.receiptHandle);
+    }
+}
+/** Wait until `predicate()` is true (polling), or throw after `timeoutMs`. */
+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));
+    }
+}
+// ── publishSyncLatencyMetric (CloudWatch contract) ───────────────────────────
+const cwMock = mockClient(CloudWatchClient);
+describe("publishSyncLatencyMetric", () => {
+    beforeEach(() => {
+        cwMock.reset();
+        _setSyncCloudWatchClient(cwMock);
+    });
+    it("sends a single PutMetricData with the documented namespace + metric name", async () => {
+        cwMock.on(PutMetricDataCommand).resolves({});
+        await publishSyncLatencyMetric(makeMetric());
+        const calls = cwMock.commandCalls(PutMetricDataCommand);
+        expect(calls).toHaveLength(1);
+        const input = calls[0].args[0].input;
+        expect(input.Namespace).toBe(SYNC_METRIC_NAMESPACE);
+        expect(input.Namespace).toBe("HQPro/Sync");
+        expect(input.MetricData).toHaveLength(1);
+        expect(input.MetricData[0].MetricName).toBe(SYNC_LATENCY_METRIC_NAME);
+        expect(input.MetricData[0].MetricName).toBe("hq-cloud.sync.p95_latency_seconds");
+    });
+    it("uses Unit=Seconds and stamps the supplied timestamp", async () => {
+        cwMock.on(PutMetricDataCommand).resolves({});
+        const ts = new Date("2026-05-19T07:00:00.000Z");
+        await publishSyncLatencyMetric(makeMetric({ timestamp: ts }));
+        const datum = cwMock.commandCalls(PutMetricDataCommand)[0].args[0].input
+            .MetricData[0];
+        expect(datum.Unit).toBe("Seconds");
+        expect(datum.Timestamp).toEqual(ts);
+    });
+    it("publishes the observed latencySeconds value verbatim", async () => {
+        cwMock.on(PutMetricDataCommand).resolves({});
+        await publishSyncLatencyMetric(makeMetric({ latencySeconds: 2.71828 }));
+        const datum = cwMock.commandCalls(PutMetricDataCommand)[0].args[0].input
+            .MetricData[0];
+        expect(datum.Value).toBe(2.71828);
+    });
+    it("attaches a `TenantId` dimension carrying the tenantId", async () => {
+        cwMock.on(PutMetricDataCommand).resolves({});
+        await publishSyncLatencyMetric(makeMetric({ tenantId: "tenant-prs_xyz" }));
+        const datum = cwMock.commandCalls(PutMetricDataCommand)[0].args[0].input
+            .MetricData[0];
+        expect(datum.Dimensions).toEqual([
+            { Name: "TenantId", Value: "tenant-prs_xyz" },
+        ]);
+    });
+    it("does not throw when the CloudWatch SDK rejects (sync loop must not crash)", async () => {
+        cwMock
+            .on(PutMetricDataCommand)
+            .rejects(new Error("CloudWatch unavailable"));
+        const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        await expect(publishSyncLatencyMetric(makeMetric())).resolves.toBeUndefined();
+        expect(consoleSpy).toHaveBeenCalledWith("Failed to publish sync latency metric to CloudWatch:", "CloudWatch unavailable");
+        consoleSpy.mockRestore();
+    });
+    it("routes SDK failures through the supplied pino logger when provided", async () => {
+        cwMock.on(PutMetricDataCommand).rejects(new Error("ThrottlingException"));
+        const { stream, lines } = captureStream();
+        const logger = createLogger({
+            component: "metrics-test",
+            destination: stream,
+            level: "debug",
+        });
+        await publishSyncLatencyMetric(makeMetric({ sequenceNumber: 99, relativePath: "a.md" }), { logger });
+        const failureLine = lines().find((l) => l.event === "sync.metric.publish_failed");
+        expect(failureLine).toBeDefined();
+        expect(failureLine).toMatchObject({
+            event: "sync.metric.publish_failed",
+            tenantId: "tenant-A",
+            relativePath: "a.md",
+            sequenceNumber: 99,
+        });
+    });
+    it("accepts a per-call client override (does not call the singleton)", async () => {
+        cwMock
+            .on(PutMetricDataCommand)
+            .rejects(new Error("singleton should not be used"));
+        const overrideMock = mockClient(CloudWatchClient);
+        overrideMock.on(PutMetricDataCommand).resolves({});
+        await publishSyncLatencyMetric(makeMetric(), {
+            client: overrideMock,
+        });
+        expect(overrideMock.commandCalls(PutMetricDataCommand)).toHaveLength(1);
+        expect(cwMock.commandCalls(PutMetricDataCommand)).toHaveLength(0);
+        overrideMock.restore();
+    });
+});
+// ── Receive-success-path metric emission (US-011 AC: "metric emission unit-
+//    tested on the receive success path") ──────────────────────────────────
+describe("SqsPushReceiver metric emission on the receive-success path", () => {
+    let receiver;
+    afterEach(async () => {
+        if (receiver) {
+            await receiver.dispose();
+            receiver = undefined;
+        }
+    });
+    it("publishes exactly one latency datum per processed event (mocked publish, no real AWS)", async () => {
+        const published = [];
+        const publishMetric = async (m) => {
+            published.push(m);
+        };
+        const event = makeEvent({ sequenceNumber: 7 });
+        receiver = new SqsPushReceiver({
+            tenantId: TENANT,
+            queueUrl: QUEUE_URL,
+            sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-7" }]),
+            syncFn: async () => {
+                /* successful pull */
+            },
+            enabled: true,
+            publishMetric,
+            // Fake clock: start measured at T, success at T+1500ms → 1.5s latency.
+            now: (() => {
+                let t = Date.parse(event.eventTimestamp);
+                return () => {
+                    const cur = t;
+                    t += 1500;
+                    return cur;
+                };
+            })(),
+        });
+        await receiver.start();
+        await until(() => published.length >= 1);
+        expect(published).toHaveLength(1);
+        expect(published[0]).toMatchObject({
+            tenantId: TENANT,
+            relativePath: event.relativePath,
+            sequenceNumber: 7,
+        });
+        expect(published[0].latencySeconds).toBeGreaterThanOrEqual(0);
+        expect(Number.isFinite(published[0].latencySeconds)).toBe(true);
+    });
+    it("does NOT publish a metric when the syncFn throws (failures don't skew p95)", async () => {
+        const published = [];
+        const event = makeEvent({ sequenceNumber: 8 });
+        receiver = new SqsPushReceiver({
+            tenantId: TENANT,
+            queueUrl: QUEUE_URL,
+            sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-8" }]),
+            syncFn: async () => {
+                throw new Error("pull failed");
+            },
+            enabled: true,
+            publishMetric: async (m) => {
+                published.push(m);
+            },
+        });
+        await receiver.start();
+        // Give the loop a few ticks to process the message + (not) publish.
+        await new Promise((r) => setTimeout(r, 50));
+        expect(published).toHaveLength(0);
+        expect(receiver.processedCount).toBe(0);
+    });
+    it("a throwing publish seam does not crash the receiver loop", async () => {
+        const event = makeEvent({ sequenceNumber: 9 });
+        let synced = false;
+        receiver = new SqsPushReceiver({
+            tenantId: TENANT,
+            queueUrl: QUEUE_URL,
+            sqs: new OneBatchSqs([{ Body: encodePushEvent(event), ReceiptHandle: "rh-9" }]),
+            syncFn: async () => {
+                synced = true;
+            },
+            enabled: true,
+            publishMetric: async () => {
+                throw new Error("metric backend down");
+            },
+        });
+        await receiver.start();
+        await until(() => synced);
+        // The sync still completed and the receiver is still alive (connected).
+        expect(receiver.processedCount).toBe(1);
+        expect(receiver.connected).toBe(true);
+    });
+});
+//# sourceMappingURL=metrics.test.js.map

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

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

package/dist/sync/push-event.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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";
+/**
+ * `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 declare const CONTENT_HASH_PATTERN: RegExp;
+/**
+ * Strict ISO-8601 datetime regex matching what `z.iso.datetime()` produces.
+ *
+ * Format: `YYYY-MM-DDTHH:MM:SS(.fff)?(Z|±HH:MM)`
+ */
+export declare const ISO8601_DATETIME_PATTERN: RegExp;
+/**
+ * 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 declare const PushEventSchema: z.ZodObject<{
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    mtime: z.ZodString;
+    originDeviceId: z.ZodString;
+    originTenantId: z.ZodString;
+    sequenceNumber: z.ZodNumber;
+    eventTimestamp: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The canonical PushEvent type. All fields are required; producers and
+ * consumers share this exact shape.
+ */
+export type PushEvent = z.infer<typeof PushEventSchema>;
+/**
+ * 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 declare 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;
+    });
+}
+/**
+ * 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 declare function encodePushEvent(event: PushEvent): string;
+/**
+ * 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 declare function decodePushEvent(input: unknown): PushEvent;
+//# sourceMappingURL=push-event.d.ts.map

package/dist/sync/push-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-event.d.ts","sourceRoot":"","sources":["../../src/sync/push-event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAA0B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAC+B,CAAC;AAIrE;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;iBAqClB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;AAEpD;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAAC;gBAGjD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;QACxC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAAC;QAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAOJ;AAID;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CASxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAkCzD"}

package/dist/sync/push-event.js

@@ -0,0 +1,153 @@
+/**
+ * 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();
+/**
+ * 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 {
+    issues;
+    stage;
+    constructor(message, args) {
+        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) {
+    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) {
+    let candidate = 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,
+                    },
+                ],
+                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;
+}
+//# sourceMappingURL=push-event.js.map

package/dist/sync/push-event.js.map

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

package/dist/sync/push-event.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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`.
+ */
+export {};
+//# sourceMappingURL=push-event.test.d.ts.map

package/dist/sync/push-event.test.d.ts.map

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