@indigoai-us/hq-cloud 5.25.0 → 5.26.0

package/src/bin/sync-runner.ts

@@ -88,6 +88,12 @@ import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
+import {
+  TreeWatcher,
+  WatchPushDriver,
+  systemClock,
+  type Clock,
+} from "../watcher.js";
 
 /**
  * Sync direction for a run.
@@ -442,6 +448,15 @@ interface ParsedArgs {
   watch: boolean;
   /** Auto-sync (Beta): ms between remote-pull passes. Required when watch=true. */
   pollRemoteMs?: number;
+  /**
+   * Event-driven push (Phase 1). When set (and `--watch` is on), the runner
+   * starts a {@link TreeWatcher} alongside the poll loop and pushes a targeted
+   * company/subtree within the debounce window of a local edit — instead of
+   * waiting up to a full `--poll-remote-ms` cycle. Gated OFF by default; the
+   * menubar passes it only for `@getindigo.ai` identities (see PRD decision).
+   * No-op without `--watch` (the one-shot path has nothing to keep alive).
+   */
+  eventPush: boolean;
   /**
    * Drop the personal target from the fanout. Combined with the
    * `HQ_SYNC_SKIP_PERSONAL` env var by `resolveSkipPersonal()` — either
@@ -460,6 +475,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let watch = false;
   let pollRemoteMs: number | undefined;
   let skipPersonal = false;
+  let eventPush = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -519,6 +535,12 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         // resolveSkipPersonal().
         skipPersonal = true;
         break;
+      case "--event-push":
+        // Phase 1 event-driven push enable flag. Requires --watch (validated
+        // below). Gated OFF by default; the menubar only passes it for
+        // @getindigo.ai identities for the first release.
+        eventPush = true;
+        break;
       default:
         return { error: `Unknown argument: ${arg}` };
     }
@@ -533,8 +555,21 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   if (pollRemoteMs !== undefined && !watch) {
     return { error: "--poll-remote-ms requires --watch" };
   }
+  if (eventPush && !watch) {
+    return { error: "--event-push requires --watch" };
+  }
 
-  return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs, skipPersonal };
+  return {
+    companies,
+    company,
+    onConflict,
+    hqRoot,
+    direction,
+    watch,
+    pollRemoteMs,
+    skipPersonal,
+    eventPush,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -1169,29 +1204,290 @@ const isDirectInvocation = (() => {
  * exit 0 today and so will retry — acceptable noise for the beta; deal with
  * it via a richer return shape if it shows up in Sentry.
  */
-export async function runRunnerWithLoop(argv: string[]): Promise<number> {
+/**
+ * Test/event-driven seam (US-001).
+ *
+ * `runRunnerWithLoop` performs an unbounded poll loop in production. To make
+ * the loop deterministically testable (US-003 wires the event-driven watcher
+ * into this same loop), the inter-pass sleep is injectable via `deps.sleep`.
+ * The default uses the host timer and preserves exact production behavior.
+ *
+ * A test (or US-003's wiring) injects a fake sleep that resolves immediately
+ * and/or coordinates with the {@link WatchPushDriver} seam in `../watcher.js`,
+ * so the loop can be exercised without a real 10-minute wait.
+ */
+export interface RunnerLoopDeps {
+  /** Sleep `ms` between passes. Default: host setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+  /**
+   * Run a single sync pass. Defaults to {@link runRunner}. Injected by tests
+   * (and the event-push wiring) so the poll loop and the watcher-triggered
+   * targeted push share one seam and one in-flight guard. The default ignores
+   * `deps` and forwards just the argv to `runRunner`.
+   */
+  runPass?: (passArgv: string[]) => Promise<number>;
+  /**
+   * Clock seam for the event-push watcher's debounce window. Defaults to
+   * {@link systemClock}; tests inject a `FakeClock` to advance the window
+   * deterministically. Only consulted when `--event-push` is on.
+   */
+  clock?: Clock;
+  /**
+   * Factory for the file watcher used in event-push mode. Defaults to a real
+   * {@link TreeWatcher} over `hqRoot`. Tests inject a stub exposing the same
+   * `onChange`/`start`/`stop`/`dispose` surface so no real chokidar runs.
+   */
+  createWatcher?: (opts: {
+    hqRoot: string;
+    debounceMs: number;
+    clock: Clock;
+  }) => WatcherSurface;
+  /**
+   * Register a one-shot shutdown signal handler. Defaults to listening for
+   * SIGTERM/SIGINT on `process`. Tests inject a controllable trigger to assert
+   * clean teardown without sending real signals. The returned fn detaches the
+   * handler (called during teardown so tests don't leak listeners).
+   */
+  onShutdownSignal?: (handler: () => void) => () => void;
+}
+
+/**
+ * The minimal watcher surface the loop drives. {@link TreeWatcher} satisfies
+ * it; tests inject a lighter stub. Kept narrow so the loop never reaches past
+ * the lifecycle + change-subscription contract.
+ *
+ * `onChange`'s listener receives an OPTIONAL changed relative path. The real
+ * {@link TreeWatcher} emits a bare debounced signal (no path) — in that case
+ * the loop routes the targeted push to the personal vault. A path-aware
+ * watcher (or a test stub) can pass the changed `companies/<slug>/...`
+ * relative path so the loop targets just that company.
+ */
+export interface WatcherSurface {
+  onChange(listener: (changedRelPath?: string) => void): () => void;
+  start(): void;
+  stop(): void;
+  dispose(): void;
+}
+
+/**
+ * Route a changed relative path to the push target that owns it.
+ *
+ * - `companies/<slug>/...` → a single-company push for `<slug>` (the targeted
+ *   pass per PRD decision — push only the changed company, not a full
+ *   `--companies` fanout).
+ * - anything else under hqRoot → the personal target (a `--companies` push
+ *   restricted to personal via the personal-vault scope; modeled here as the
+ *   "personal" route the caller maps to the right argv).
+ *
+ * Returns `null` for paths the routing cannot attribute (defensive — the
+ * watcher's filter already drops excluded top-levels, so this is belt-and-
+ * suspenders for synthetic events).
+ */
+export function routeChangeToTarget(
+  relPath: string,
+): { kind: "company"; slug: string } | { kind: "personal" } | null {
+  const norm = relPath.split(path.sep).join("/").replace(/^\.\//, "");
+  if (norm === "" || norm.startsWith("..")) return null;
+  const segments = norm.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return null;
+  if (segments[0] === "companies") {
+    // companies/<slug>/... — need at least the slug segment to target.
+    if (segments.length < 2 || segments[1].length === 0) return null;
+    return { kind: "company", slug: segments[1] };
+  }
+  return { kind: "personal" };
+}
+
+/**
+ * Build the argv for a targeted push pass from a routed change. The push runs
+ * `--direction push` for just the routed target so a local edit propagates in
+ * seconds without a full fanout. Company routes use `--company <slug>`;
+ * personal routes use `--companies --direction push` (the personal-vault scope
+ * is resolved inside runRunner's fanout; skipUnchanged no-ops the company
+ * subtrees that didn't change). Inherits `--hq-root` / `--on-conflict` from
+ * the base argv. Pure helper, exported for unit testing the routing→argv map.
+ */
+export function buildTargetedPushArgv(
+  route: { kind: "company"; slug: string } | { kind: "personal" },
+  baseArgv: string[],
+): string[] {
+  const carried = carriedFlags(baseArgv);
+  if (route.kind === "company") {
+    return ["--company", route.slug, "--direction", "push", ...carried];
+  }
+  return ["--companies", "--direction", "push", ...carried];
+}
+
+export async function runRunnerWithLoop(
+  argv: string[],
+  deps: RunnerLoopDeps = {},
+): Promise<number> {
   if (!argv.includes("--watch")) {
     return runRunner(argv);
   }
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const runPass = deps.runPass ?? ((passArgv: string[]) => runRunner(passArgv));
   const pollIdx = argv.indexOf("--poll-remote-ms");
   const pollMs =
     pollIdx >= 0 && argv[pollIdx + 1] ? Number(argv[pollIdx + 1]) : 600_000;
+  const eventPush = argv.includes("--event-push");
+  const hqIdx = argv.indexOf("--hq-root");
+  const hqRoot =
+    hqIdx >= 0 && argv[hqIdx + 1] ? argv[hqIdx + 1] : DEFAULT_HQ_ROOT;
 
-  // Strip --watch / --poll-remote-ms before delegating: the parser inside
-  // runRunner accepts them, but we don't want runRunner to think it's
-  // re-entering watch mode each iteration.
+  // Strip the loop-only flags before delegating: the parser inside runRunner
+  // accepts --watch/--poll-remote-ms/--event-push, but we don't want a per-
+  // iteration pass to think it's re-entering watch mode.
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
     if (a === "--poll-remote-ms") return false;
+    if (a === "--event-push") return false;
     if (i > 0 && argv[i - 1] === "--poll-remote-ms") return false;
     return true;
   });
 
-  while (true) {
-    const code = await runRunner(passArgv);
-    if (code !== 0) return code;
-    await new Promise<void>((resolve) => setTimeout(resolve, pollMs));
+  // ---- shared in-flight guard ------------------------------------------
+  // The poll loop AND watcher-triggered targeted pushes funnel through this
+  // mutex so a watcher push never overlaps an in-flight pass (PRD AC). A
+  // trigger that arrives while a pass runs is collapsed by WatchPushDriver's
+  // own pending-while-pushing logic, then re-armed after the pass settles.
+  let inFlight = false;
+  let stopped = false;
+  const runGuarded = async (
+    pass: () => Promise<number>,
+  ): Promise<number | "skipped"> => {
+    if (inFlight) return "skipped";
+    inFlight = true;
+    try {
+      return await pass();
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  // ---- event-push wiring (Phase 1) -------------------------------------
+  let watcher: WatcherSurface | null = null;
+  let driver: WatchPushDriver | null = null;
+  let detachSignal: (() => void) | null = null;
+  let lastChangedRel: string | null = null;
+
+  if (eventPush) {
+    const clock = deps.clock ?? systemClock;
+    const debounceMs = 2000;
+    const createWatcher =
+      deps.createWatcher ??
+      ((opts) =>
+        new TreeWatcher({
+          hqRoot: opts.hqRoot,
+          debounceMs: opts.debounceMs,
+          clock: opts.clock,
+          personalMode: true,
+        }));
+    watcher = createWatcher({ hqRoot, debounceMs, clock });
+
+    // The driver runs the targeted push when a debounced burst settles. Its
+    // concurrency guard collapses a trigger that lands mid-pass; we ALSO gate
+    // through `runGuarded` so a poll pass in flight is never overlapped.
+    driver = new WatchPushDriver({
+      debounceMs: 0, // TreeWatcher already debounces; the driver just guards.
+      clock,
+      push: async () => {
+        if (stopped) return;
+        const rel = lastChangedRel;
+        const route = rel
+          ? routeChangeToTarget(rel)
+          : { kind: "personal" as const };
+        if (!route) return;
+        const targetedArgv = buildTargetedPushArgv(route, passArgv);
+        await runGuarded(() => runPass(targetedArgv));
+      },
+    });
+
+    // A debounced TreeWatcher 'changed' signal feeds the driver, which fires
+    // the targeted push after its own (zero) window — i.e. immediately, but
+    // still serialized behind any in-flight pass. A path-aware watcher passes
+    // the changed relative path so the push targets just its owning company;
+    // the bare-signal TreeWatcher leaves it null → personal-vault route.
+    watcher.onChange((changedRelPath) => {
+      if (stopped) return;
+      lastChangedRel = changedRelPath ?? null;
+      driver?.notifyChange();
+    });
+    watcher.start();
+  }
+
+  // ---- clean shutdown --------------------------------------------------
+  // SIGTERM (menubar stop_daemon) / SIGINT must tear down BOTH the watcher and
+  // the poll loop with no leaked timers or fds. We flip `stopped`, dispose the
+  // watcher + driver, and let the poll loop observe `stopped` on its next tick.
+  let resolveStopped: (() => void) | null = null;
+  const stoppedSignal = new Promise<void>((resolve) => {
+    resolveStopped = resolve;
+  });
+  const shutdown = (): void => {
+    if (stopped) return;
+    stopped = true;
+    try {
+      driver?.dispose();
+    } catch {
+      /* ignore */
+    }
+    try {
+      watcher?.dispose();
+    } catch {
+      /* ignore */
+    }
+    resolveStopped?.();
+  };
+  const onShutdownSignal =
+    deps.onShutdownSignal ??
+    ((handler: () => void) => {
+      const wrapped = () => handler();
+      process.on("SIGTERM", wrapped);
+      process.on("SIGINT", wrapped);
+      return () => {
+        process.off("SIGTERM", wrapped);
+        process.off("SIGINT", wrapped);
+      };
+    });
+  detachSignal = onShutdownSignal(shutdown);
+
+  try {
+    while (!stopped) {
+      const result = await runGuarded(() => runPass(passArgv));
+      // A poll pass that was skipped because a watcher push held the guard is
+      // benign — the next iteration retries after the poll interval.
+      if (typeof result === "number" && result !== 0) {
+        return result;
+      }
+      // Sleep the poll interval, but wake early on shutdown so SIGTERM stops
+      // the loop promptly instead of waiting out a 10-minute cycle.
+      await Promise.race([sleep(pollMs), stoppedSignal]);
+    }
+    return 0;
+  } finally {
+    shutdown();
+    detachSignal?.();
+  }
+}
+
+/**
+ * Extract the `--hq-root` / `--on-conflict` pair-flags from a base argv so a
+ * re-targeted push pass inherits the same root and conflict policy. Pure
+ * helper used by the event-push targeted-push composer.
+ */
+function carriedFlags(baseArgv: string[]): string[] {
+  const carried: string[] = [];
+  for (let i = 0; i < baseArgv.length; i++) {
+    const a = baseArgv[i];
+    if (a === "--hq-root" || a === "--on-conflict") {
+      carried.push(a);
+      if (baseArgv[i + 1] !== undefined) carried.push(baseArgv[++i]);
+    }
   }
+  return carried;
 }
 
 if (isDirectInvocation) {

package/src/index.ts

@@ -281,3 +281,20 @@ export {
   _setSignalsS3Factory,
   _resetSignalsS3Factory,
 } from "./signals/internals.js";
+
+// Event-driven sync — PushEvent wire contract + PushTransport shipping seam
+// (ported from hq-pro PR #112 per project event-driven-sync-menubar US-007).
+export {
+  CONTENT_HASH_PATTERN,
+  ISO8601_DATETIME_PATTERN,
+  PushEventSchema,
+  PushEventDecodeError,
+  encodePushEvent,
+  decodePushEvent,
+  NoopPushTransport,
+} from "./sync/index.js";
+export type {
+  PushEvent,
+  PushEventDecodeIssue,
+  PushTransport,
+} from "./sync/index.js";

package/src/sync/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @indigoai-us/hq-cloud — event-driven sync (`src/sync`) barrel.
+ *
+ * Surfaces the PushEvent wire contract + the PushTransport shipping seam
+ * ported from hq-pro PR #112 (project event-driven-sync-menubar US-007).
+ */
+
+export {
+  CONTENT_HASH_PATTERN,
+  ISO8601_DATETIME_PATTERN,
+  PushEventSchema,
+  PushEventDecodeError,
+  encodePushEvent,
+  decodePushEvent,
+} from "./push-event.js";
+export type { PushEvent, PushEventDecodeIssue } from "./push-event.js";
+
+export { NoopPushTransport } from "./push-transport.js";
+export type { PushTransport } from "./push-transport.js";

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);
+  });
+});