@indigoai-us/hq-cloud 6.11.7 → 6.11.9

package/src/sync/feature-flags.test.ts

@@ -49,6 +49,7 @@ import type { TreeChangeBatch } from "../watcher.js";
 function fakePushEvent(overrides: Partial<PushEvent> = {}): PushEvent {
   return {
     relativePath: "personal/notes/a.md",
+    kind: "upsert",
     contentHash: `sha256:${"a".repeat(64)}`,
     mtime: "2026-05-21T12:00:00.000Z",
     originDeviceId: "device-1",
@@ -178,6 +179,34 @@ describe("HttpPushTransport — POST /sync/push", () => {
     expect(decodePushEvent(init.body)).toEqual(event);
   });
 
+  it("POSTs a delete tombstone without contentHash or mtime", async () => {
+    const { fetch, calls } = makeFetch({ ok: true, status: 200 });
+    const transport = new HttpPushTransport({
+      apiUrl: "https://vault-api.example.com/",
+      authToken: "tok-123",
+      fetchImpl: fetch,
+    });
+    const event = fakePushEvent({
+      kind: "delete",
+      contentHash: undefined,
+      mtime: undefined,
+    });
+
+    await transport.publish(event);
+
+    expect(calls).toHaveLength(1);
+    const body = (calls[0].init as { body: string }).body;
+    expect(JSON.parse(body)).toEqual({
+      relativePath: "personal/notes/a.md",
+      kind: "delete",
+      originDeviceId: "device-1",
+      originTenantId: "indigo",
+      sequenceNumber: 0,
+      eventTimestamp: "2026-05-21T12:00:01.000Z",
+    });
+    expect(decodePushEvent(body)).toEqual(JSON.parse(body));
+  });
+
   it("resolves the auth token per-request via an async getter (self-heals across refresh)", async () => {
     const { fetch, calls } = makeFetch();
     let n = 0;
@@ -287,6 +316,7 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     expect(published).toHaveLength(1);
     const e = published[0];
     expect(e.relativePath).toBe(REL);
+    expect(e.kind).toBe("upsert");
     expect(e.originTenantId).toBe("indigo");
     expect(e.originDeviceId).toBe("dev-1");
     const expectedHex = createHash("sha256").update("hello world").digest("hex");
@@ -350,7 +380,7 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: REL });
   });
 
-  it("a missing file (hash/stat race) is surfaced, other paths still ship", async () => {
+  it("a missing file emits a delete tombstone, and other paths still ship", async () => {
     const published: PushEvent[] = [];
     const onError = vi.fn();
     const emitter = new PushEventEmitter({
@@ -362,9 +392,15 @@ describe("PushEventEmitter — emit, gating, failure handling", () => {
     });
     // REL exists; "ghost.md" does not.
     await emitter.emitForBatch(batchFor(REL, "ghost.md"));
-    expect(published.map((e) => e.relativePath)).toEqual([REL]);
-    expect(onError).toHaveBeenCalledTimes(1);
-    expect(onError.mock.calls[0][1]).toMatchObject({ relativePath: "ghost.md" });
+    expect(published.map((e) => e.relativePath).sort()).toEqual([
+      REL,
+      "ghost.md",
+    ].sort());
+    const tombstone = published.find((e) => e.relativePath === "ghost.md");
+    expect(tombstone).toMatchObject({ kind: "delete" });
+    expect(tombstone).not.toHaveProperty("contentHash");
+    expect(tombstone).not.toHaveProperty("mtime");
+    expect(onError).not.toHaveBeenCalled();
   });
 
   it("end-to-end: emit → HttpPushTransport POST with a valid schema (mocked fetch)", async () => {

package/src/sync/index.ts

@@ -13,7 +13,11 @@ export {
   encodePushEvent,
   decodePushEvent,
 } from "./push-event.js";
-export type { PushEvent, PushEventDecodeIssue } from "./push-event.js";
+export type {
+  PushEvent,
+  PushEventInput,
+  PushEventDecodeIssue,
+} from "./push-event.js";
 
 export { NoopPushTransport, HttpPushTransport } from "./push-transport.js";
 export type {

package/src/sync/logger.test.ts

@@ -70,6 +70,7 @@ async function until(predicate: () => boolean, timeoutMs = 1000): Promise<void>
 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/sync/metrics.test.ts

@@ -82,6 +82,7 @@ const QUEUE_URL =
 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/sync/push-event.test.ts

@@ -19,12 +19,14 @@ import {
   decodePushEvent,
   encodePushEvent,
   type PushEvent,
+  type PushEventInput,
 } 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",
+  kind: "upsert",
   contentHash:
     "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
   mtime: "2026-05-18T12:34:56.789Z",
@@ -34,6 +36,15 @@ const validFixture: PushEvent = {
   eventTimestamp: "2026-05-18T12:35:00.000Z",
 };
 
+const deleteFixture: PushEvent = {
+  relativePath: "docs/architecture/overview.md",
+  kind: "delete",
+  originDeviceId: "device-laptop-a",
+  originTenantId: "tenant-indigo",
+  sequenceNumber: 43,
+  eventTimestamp: "2026-05-18T12:36:00.000Z",
+};
+
 describe("PushEvent encode/decode", () => {
   // ── Acceptance #1: round-trip ──────────────────────────────────────────
   it("round-trips a known-good fixture through encode → decode", () => {
@@ -55,6 +66,21 @@ describe("PushEvent encode/decode", () => {
     expect(fromString).toEqual(validFixture);
   });
 
+  it("round-trips a delete tombstone without contentHash or mtime", () => {
+    const encoded = encodePushEvent(deleteFixture);
+    expect(JSON.parse(encoded)).toEqual(deleteFixture);
+    expect(decodePushEvent(encoded)).toEqual(deleteFixture);
+  });
+
+  it("defaults an absent kind to upsert for backward compatibility", () => {
+    const legacy = { ...validFixture } as PushEventInput;
+    delete legacy.kind;
+
+    const decoded = decodePushEvent(legacy);
+    expect(decoded).toEqual(validFixture);
+    expect(JSON.parse(encodePushEvent(legacy))).toEqual(validFixture);
+  });
+
   // ── Acceptance #2: unknown fields dropped ──────────────────────────────
   it("drops unknown extra fields silently (does not throw)", () => {
     const withExtras = {
@@ -80,8 +106,6 @@ describe("PushEvent encode/decode", () => {
   // ── Acceptance #3: missing required fields throw typed error ───────────
   it.each([
     "relativePath",
-    "contentHash",
-    "mtime",
     "originDeviceId",
     "originTenantId",
     "sequenceNumber",
@@ -106,6 +130,24 @@ describe("PushEvent encode/decode", () => {
     expect(error.issues.some((issue) => issue.path.includes(field))).toBe(true);
   });
 
+  it("rejects an upsert without contentHash and mtime via the schema refinement", () => {
+    let caught: unknown;
+    try {
+      decodePushEvent({
+        ...validFixture,
+        contentHash: undefined,
+        mtime: undefined,
+      });
+    } 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.message === "upsert requires contentHash and mtime")).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;
@@ -117,7 +159,7 @@ describe("PushEvent encode/decode", () => {
     }
     expect(caught).toBeInstanceOf(PushEventDecodeError);
     const error = caught as PushEventDecodeError;
-    expect(error.issues.length).toBeGreaterThanOrEqual(6);
+    expect(error.issues.length).toBeGreaterThanOrEqual(4);
   });
 
   // ── Supporting wire-contract invariants ────────────────────────────────

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",