@indigoai-us/hq-cloud 6.11.8 → 6.11.9

package/src/sync/push-event.ts

@@ -2,17 +2,20 @@
  * 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.
+ * Producers (the watcher) emit one PushEvent per local content change or
+ * delete tombstone.
  * 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.
+ * - `kind` is `"upsert"` for content changes and `"delete"` for delete
+ *   tombstones. Missing `kind` defaults to `"upsert"` for older producers.
+ * - `contentHash` is required for upserts and absent for delete tombstones.
+ *   It 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
@@ -59,15 +62,18 @@ export const PushEventSchema = z
     relativePath: z
       .string()
       .min(1, "relativePath must be a non-empty string"),
+    kind: z.enum(["upsert", "delete"]).optional().default("upsert"),
     contentHash: z
       .string()
       .regex(
         CONTENT_HASH_PATTERN,
         "contentHash must match `sha256:<64 lowercase hex>`",
-      ),
+      )
+      .optional(),
     mtime: z
       .string()
-      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime"),
+      .regex(ISO8601_DATETIME_PATTERN, "mtime must be an ISO-8601 datetime")
+      .optional(),
     originDeviceId: z
       .string()
       .min(1, "originDeviceId must be a non-empty string"),
@@ -91,13 +97,23 @@ export const PushEventSchema = z
   })
   // `.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();
+  .strip()
+  .refine(
+    (e) => e.kind === "delete" || (e.contentHash != null && e.mtime != null),
+    { message: "upsert requires contentHash and mtime" },
+  );
+
+/**
+ * The canonical decoded PushEvent type. `kind` is always present after decode;
+ * `contentHash` and `mtime` are present for upserts and absent for deletes.
+ */
+export type PushEvent = z.output<typeof PushEventSchema>;
 
 /**
- * The canonical PushEvent type. All fields are required; producers and
- * consumers share this exact shape.
+ * Input accepted by the schema. Kept public so encode callers can hand in
+ * legacy upsert payloads where `kind` is absent.
  */
-export type PushEvent = z.infer<typeof PushEventSchema>;
+export type PushEventInput = z.input<typeof PushEventSchema>;
 
 // ─── Errors ────────────────────────────────────────────────────────────────
 
@@ -145,7 +161,7 @@ export class PushEventDecodeError extends Error {
  * Extra keys on `event` are dropped — the returned JSON string contains
  * only the declared PushEvent fields.
  */
-export function encodePushEvent(event: PushEvent): string {
+export function encodePushEvent(event: PushEventInput): string {
   const parsed = PushEventSchema.safeParse(event);
   if (!parsed.success) {
     throw new PushEventDecodeError(

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

@@ -45,6 +45,7 @@ const QUEUE_URL = "https://sqs.us-east-1.amazonaws.com/123456789012/sync-push-in
 function makeEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "companies/indigo/notes.md",
+    kind: "upsert",
     contentHash:
       "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     mtime: "2026-05-21T12:34:56.000Z",

package/src/watcher.test.ts

@@ -7,7 +7,11 @@ import {
   WatchPushDriver,
   TreeWatcher,
   createWatchPathFilter,
+  PushEventEmitter,
 } from "./watcher.js";
+import { StaticFlagProvider } from "./sync/feature-flags.js";
+import type { PushEvent } from "./sync/push-event.js";
+import type { PushTransport } from "./sync/push-transport.js";
 
 /**
  * US-001 — Phase 1 test harness: watch-triggered push seam + latency assertion.
@@ -427,3 +431,80 @@ describe("US-002: TreeWatcher — lifecycle (real chokidar over a temp dir)", ()
     w.dispose();
   }, 10_000);
 });
+
+describe("PushEventEmitter — directory and delete tombstone handling", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "pushemit-")));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  function makeEmitter(opts?: {
+    published?: PushEvent[];
+    onError?: ReturnType<typeof vi.fn>;
+    getSequenceNumber?: () => number;
+  }): PushEventEmitter {
+    const published = opts?.published ?? [];
+    const transport: PushTransport = {
+      start: async () => {},
+      dispose: async () => {},
+      connected: true,
+      publish: async (event) => {
+        published.push(event);
+      },
+    };
+    return new PushEventEmitter({
+      originTenantId: "tenant-indigo",
+      originDeviceId: "device-a",
+      transport,
+      flagProvider: new StaticFlagProvider(["tenant-indigo"]),
+      now: () => new Date("2026-06-18T12:00:00.000Z"),
+      getSequenceNumber: opts?.getSequenceNumber,
+      onError: opts?.onError,
+    });
+  }
+
+  it("skips directory changes silently without publishing or reporting an error", async () => {
+    const published: PushEvent[] = [];
+    const onError = vi.fn();
+    const subdir = path.join(dir, "folder");
+    fs.mkdirSync(subdir);
+    const emitter = makeEmitter({ published, onError });
+
+    await emitter.emitForBatch({ paths: new Map([[subdir, "folder"]]) });
+
+    expect(published).toEqual([]);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("emits and publishes a delete tombstone when the changed file is gone", async () => {
+    const published: PushEvent[] = [];
+    const onError = vi.fn();
+    const emitter = makeEmitter({
+      published,
+      onError,
+      getSequenceNumber: () => 99,
+    });
+    const missing = path.join(dir, "deleted.md");
+
+    await emitter.emitForBatch({ paths: new Map([[missing, "deleted.md"]]) });
+
+    expect(onError).not.toHaveBeenCalled();
+    expect(published).toEqual([
+      {
+        kind: "delete",
+        relativePath: "deleted.md",
+        originDeviceId: "device-a",
+        originTenantId: "tenant-indigo",
+        sequenceNumber: 99,
+        eventTimestamp: "2026-06-18T12:00:00.000Z",
+      },
+    ]);
+    expect(published[0]).not.toHaveProperty("contentHash");
+    expect(published[0]).not.toHaveProperty("mtime");
+  });
+});

package/src/watcher.ts

@@ -862,11 +862,12 @@ export class PushEventEmitter {
   ): Promise<void> {
     let event: PushEvent | undefined;
     try {
-      const [contentHash, st] = await Promise.all([
-        computeContentHash(absolutePath),
-        stat(absolutePath),
-      ]);
+      const st = await stat(absolutePath);
+      if (st.isDirectory()) return;
+
+      const contentHash = await computeContentHash(absolutePath);
       event = {
+        kind: "upsert",
         relativePath,
         contentHash,
         mtime: st.mtime.toISOString(),
@@ -876,12 +877,28 @@ export class PushEventEmitter {
         eventTimestamp: this.now().toISOString(),
       };
     } catch (err) {
-      // File deleted between debounce fire and hash read (legal race), or stat
-      // failed. Surface, don't crash.
-      this.onError(err instanceof Error ? err : new Error(String(err)), {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      if (code !== "ENOENT") {
+        // Genuine stat/read failure. Surface, don't crash.
+        this.onError(err instanceof Error ? err : new Error(String(err)), {
+          relativePath,
+        });
+        return;
+      }
+
+      // Deleted before/during capture: publish a tombstone so peers run a
+      // targeted pull and let the vault-confirmed tombstone path remove it.
+      event = {
+        kind: "delete",
         relativePath,
-      });
-      return;
+        originDeviceId: this.originDeviceId,
+        originTenantId: this.originTenantId,
+        sequenceNumber: this.nextSeq(),
+        eventTimestamp: this.now().toISOString(),
+      };
     }
 
     // US-011: 1st link of the 3-log diagnostic chain. Stamps the same
@@ -891,6 +908,7 @@ export class PushEventEmitter {
     this.logger?.info(
       {
         event: "watcher.emit",
+        kind: event.kind,
         originTenantId: event.originTenantId,
         originDeviceId: event.originDeviceId,
         relativePath: event.relativePath,

package/test/e2e/sync/cross-tenant-isolation.test.ts

@@ -215,6 +215,7 @@ function makeEvent(opts: {
 }): PushEvent {
   return {
     relativePath: opts.relativePath,
+    kind: "upsert",
     contentHash: ZERO_HASH,
     mtime: "2026-05-21T12:00:00.000Z",
     originDeviceId: opts.deviceId,
@@ -540,6 +541,7 @@ describe("US-018: receive path with vended credentials (isolation extension)", (
   function phase3Event(overrides: Partial<PushEvent>): PushEvent {
     return {
       relativePath: "companies/indigo/docs/x.md",
+      kind: "upsert",
       contentHash: `sha256:${"b".repeat(64)}`,
       mtime: "2026-06-10T12:00:00.000Z",
       originDeviceId: "peer",