@indigoai-us/hq-cloud 6.14.9 → 6.14.10

package/src/cli/share.test.ts

@@ -71,6 +71,19 @@ function makeEntityContext(overrides: Partial<EntityContext> = {}): EntityContex
   };
 }
 
+function deleteIntent(
+  remoteEtag: string,
+  localHash: string,
+  localKind: "file" | "symlink" = "file",
+) {
+  return {
+    version: 1 as const,
+    remoteEtag,
+    localHash,
+    localKind,
+  };
+}
+
 describe("wrapFilterWithIgnoreVisibility", () => {
   it("records noteworthy base-ignore exclusions while counting all rejections", () => {
     const hqRoot = path.join("/tmp", "hqroot");
@@ -1950,6 +1963,12 @@ describe("share", () => {
             syncedAt: new Date().toISOString(),
             direction: "up",
             remoteEtag: "knowledge-etag",
+            kind: "symlink",
+            localDeleteIntent: deleteIntent(
+              "knowledge-etag",
+              "irrelevant-not-checked",
+              "symlink",
+            ),
           },
         },
       }),
@@ -2189,6 +2208,11 @@ describe("share", () => {
             syncedAt: new Date().toISOString(),
             direction: "up",
             remoteEtag: "gone-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent(
+              "gone-etag",
+              "irrelevant-not-checked-here",
+            ),
           },
         },
       }),
@@ -2231,6 +2255,9 @@ describe("share", () => {
             size: 42,
             syncedAt: new Date().toISOString(),
             direction: "up",
+            remoteEtag: "removed-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("removed-etag", "h"),
           },
         },
       }),
@@ -2318,6 +2345,9 @@ describe("share", () => {
             size: 1,
             syncedAt: new Date().toISOString(),
             direction: "up",
+            remoteEtag: "in-scope-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("in-scope-etag", "h"),
           },
           "other/also-gone.md": {
             hash: "h",
@@ -2371,6 +2401,9 @@ describe("share", () => {
             size: 5,
             syncedAt: new Date().toISOString(),
             direction: "up",
+            remoteEtag: "flaky-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("flaky-etag", "h"),
           },
         },
       }),
@@ -2446,6 +2479,9 @@ describe("share", () => {
           "i-uploaded.md": {
             hash: "h", size: 1, syncedAt: new Date().toISOString(),
             direction: "up",
+            remoteEtag: "uploaded-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("uploaded-etag", "h"),
           },
         },
       }),
@@ -2482,6 +2518,9 @@ describe("share", () => {
           "pulled.md": {
             hash: "h", size: 1, syncedAt: new Date().toISOString(),
             direction: "down",
+            remoteEtag: "pulled-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("pulled-etag", "h"),
           },
         },
       }),
@@ -2526,6 +2565,9 @@ describe("share", () => {
           "active/current.md": {
             hash: "h", size: 1, syncedAt: new Date().toISOString(),
             direction: "up",
+            remoteEtag: "active-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("active-etag", "h"),
           },
         },
       }),
@@ -2586,6 +2628,8 @@ describe("share", () => {
             hash: "h", size: 100, syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "abc123",
+            kind: "file",
+            localDeleteIntent: deleteIntent("abc123", "h"),
           },
         },
       }),
@@ -2637,6 +2681,8 @@ describe("share", () => {
             syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "abc123",
+            kind: "file",
+            localDeleteIntent: deleteIntent("abc123", "h"),
             removedAt: new Date().toISOString(),
             removedReason: "local-delete",
           },
@@ -2688,6 +2734,8 @@ describe("share", () => {
             hash: "h", size: 50, syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "stale-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("stale-etag", "h"),
           },
         },
       }),
@@ -2733,6 +2781,64 @@ describe("share", () => {
     expect(result.filesTombstoned).toBe(0);
   });
 
+  it("currency-gated: preserves a file recreated after the delete plan", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const recreatedPath = path.join(companyRoot, "racy.md");
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "2",
+        lastSync: new Date().toISOString(),
+        files: {
+          "racy.md": {
+            hash: "synced-hash",
+            size: 10,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+            remoteEtag: "racy-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("racy-etag", "synced-hash"),
+          },
+        },
+        pulls: [],
+      }),
+    );
+
+    // The currency HEAD establishes the remote revision, then a local writer
+    // recreates the file before the planned DeleteObject can run.
+    vi.mocked(headRemoteFile).mockImplementationOnce(async () => {
+      fs.writeFileSync(recreatedPath, "recreated after planning");
+      return { lastModified: new Date(), etag: '"racy-etag"', size: 10 };
+    });
+
+    const events: Array<{ type: string; path?: string; reason?: string }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+      propagateDeletes: true,
+      propagateDeletePolicy: "currency-gated",
+      onEvent: (e) => events.push(e as { type: string }),
+    });
+
+    expect(result.filesDeleted).toBe(0);
+    expect(deleteRemoteFile).not.toHaveBeenCalled();
+    expect(fs.readFileSync(recreatedPath, "utf-8")).toBe("recreated after planning");
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf-8"));
+    expect(journal.files["racy.md"]).toBeDefined();
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: "delete-refused-stale-etag",
+        path: "racy.md",
+        reason: "intent-changed",
+      }),
+    );
+  });
+
   it("currency-gated: refuses delete for a divergent-local entry (journal-honesty — never delete a remote the local never genuinely matched)", async () => {
     const companyRoot = path.join(tmpDir, "companies", "acme");
     fs.mkdirSync(companyRoot, { recursive: true });
@@ -2814,6 +2920,8 @@ describe("share", () => {
             hash: "h", size: 25, syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "doesnt-matter",
+            kind: "file",
+            localDeleteIntent: deleteIntent("doesnt-matter", "h"),
           },
         },
       }),
@@ -2894,12 +3002,13 @@ describe("share", () => {
 
     expect(result.filesDeleted).toBe(0);
     expect(deleteRemoteFile).not.toHaveBeenCalled();
-    // HEAD must NOT be called — we short-circuit on the missing journal etag.
+    // HEAD must NOT be called — the explicit-intent gate rejects legacy
+    // entries before any remote operation.
     expect(headRemoteFile).not.toHaveBeenCalled();
     const refused = events.find((e) => e.type === "delete-refused-stale-etag");
     expect(refused).toMatchObject({
-      journalEtag: "<legacy-no-etag>",
-      reason: "legacy-no-etag",
+      journalEtag: "<missing-delete-intent>",
+      reason: "missing-delete-intent",
     });
     expect(result.filesRefusedStale).toBe(1);
   });
@@ -2925,6 +3034,8 @@ describe("share", () => {
             hash: "h", size: 200, syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "upstream-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("upstream-etag", "h"),
           },
         },
       }),
@@ -3059,6 +3170,8 @@ describe("share", () => {
             hash: "h", size: 5, syncedAt: new Date().toISOString(),
             direction: "up",
             remoteEtag: "regular-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("regular-etag", "h"),
           },
         },
       }),
@@ -3385,6 +3498,8 @@ describe("share", () => {
             hash: "h", size: 1, syncedAt: new Date().toISOString(),
             direction: "up",
             remoteEtag: "abc",
+            kind: "file",
+            localDeleteIntent: deleteIntent("abc", "h"),
           },
         },
       }),
@@ -3892,6 +4007,8 @@ describe("share", () => {
           syncedAt: string;
           direction: "up" | "down";
           remoteEtag: string;
+          kind: "file";
+          localDeleteIntent: ReturnType<typeof deleteIntent>;
         }
       > = {};
       for (let i = 0; i < total; i++) {
@@ -3902,6 +4019,8 @@ describe("share", () => {
           syncedAt: new Date().toISOString(),
           direction,
           remoteEtag: `etag-${i}`,
+          kind: "file",
+          localDeleteIntent: deleteIntent(`etag-${i}`, "h"),
         };
         if (i >= missing) {
           fs.writeFileSync(path.join(companyRoot, key), "hi");
@@ -4135,17 +4254,22 @@ describe("share", () => {
       const files: Record<string, {
         hash: string; size: number; syncedAt: string;
         direction: "up" | "down"; remoteEtag: string;
+        kind: "file"; localDeleteIntent: ReturnType<typeof deleteIntent>;
       }> = {};
       const now = new Date().toISOString();
       for (let i = 0; i < 50; i++) {
         files[`d-${i.toString().padStart(4, "0")}.md`] = {
           hash: "h", size: 5, syncedAt: now,
           direction: "down", remoteEtag: `down-etag-${i}`,
+          kind: "file",
+          localDeleteIntent: deleteIntent(`down-etag-${i}`, "h"),
         };
       }
       files["only-up.md"] = {
         hash: "h", size: 5, syncedAt: now,
         direction: "up", remoteEtag: "up-etag",
+        kind: "file",
+        localDeleteIntent: deleteIntent("up-etag", "h"),
       };
       const journalPath = path.join(stateDir, "sync-journal.acme.json");
       fs.writeFileSync(journalPath, JSON.stringify({ version: "1", lastSync: now, files }));
@@ -4293,6 +4417,8 @@ describe("currency-gated: journal version 2 fixtures", () => {
             syncedAt: new Date().toISOString(),
             direction: "down",
             remoteEtag: "v2-etag",
+            kind: "file",
+            localDeleteIntent: deleteIntent("v2-etag", "h"),
           },
         },
         pulls: [],

package/src/cli/share.ts

@@ -41,6 +41,7 @@ import {
   wrapFilterWithPersonalVaultDefaults,
   type PersonalVaultExclusion,
 } from "../personal-vault-exclusions.js";
+import { isPersonalVaultDeletionExcluded } from "../personal-vault.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
@@ -1101,7 +1102,7 @@ async function buildSharePlans(run: PushRunContext): Promise<SharePlans> {
           run.journal,
           run.options.decommissionPrefixes ?? [],
           run.propagateDeletePolicy,
-          new Set([...deletePlan.toDelete, ...deletePlan.toTombstone]),
+          new Set([...deletePlan.toDelete.map((item) => item.key), ...deletePlan.toTombstone]),
         )
       : [];
 
@@ -1240,7 +1241,11 @@ async function executeUploads(
     // second HQ root that shares this machine's sync journal) would otherwise read as
     // `localChanged && !remoteChanged`, slip past the conflict-scoped guard below, and
     // rewind the server's value — the `.last-run` watermark clobber. Skip before HEAD.
-    if (isCloudAuthoritative(relativePath)) {
+    // board.json is the one push-side exception: local board appends are
+    // legitimate, but must flow through the conditional PUT fence below. It
+    // remains cloud-authoritative on pull so server automation still wins a
+    // pull conflict.
+    if (relativePath !== "board.json" && isCloudAuthoritative(relativePath)) {
       run.emit({ type: "reconciled", path: relativePath, direction: "push" });
       counters.filesSkipped++;
       return;
@@ -1293,6 +1298,8 @@ async function executeUploads(
           "up",
           remoteMeta.etag,
           lstat.mtimeMs,
+          undefined,
+          item.kind,
         );
         run.emit({ type: "reconciled", path: relativePath, direction: "push" });
         counters.filesSkipped++;
@@ -1350,7 +1357,17 @@ async function executeUploads(
         ? await uploadSymlink(run.ctx, item.target, relativePath, run.options.author, pc)
         : await uploadFile(run.ctx, absolutePath, relativePath, run.options.author, pc);
 
-      updateEntry(run.journal, relativePath, localHash, size, "up", etag, mtimeMs);
+      updateEntry(
+        run.journal,
+        relativePath,
+        localHash,
+        size,
+        "up",
+        etag,
+        mtimeMs,
+        undefined,
+        item.kind,
+      );
       if (run.message) {
         run.journal.files[relativePath] = {
           ...run.journal.files[relativePath],
@@ -1501,14 +1518,39 @@ async function executeDeletes(
   counters: ShareCounters,
   filesRefusedStalePaths: string[],
 ): Promise<void> {
-  const deleteKeys = [...deletePlan.toDelete, ...decommissionPlan];
+  const deleteItems = [
+    ...deletePlan.toDelete.map((item) => ({ ...item, decommission: false })),
+    ...decommissionPlan.map((key) => ({ key, intentVersion: null, decommission: true })),
+  ];
+  const deleteKeys = deleteItems.map((item) => item.key);
   await primeObjectTransport(run.ctx, "delete", deleteKeys);
-  for (const relativePath of deleteKeys) {
+  for (const item of deleteItems) {
+    const { key: relativePath } = item;
     if (run.vaultConfig && isExpiringSoon(run.ctx.expiresAt)) {
       run.ctx = await refreshEntityContext(run.companyRef, run.vaultConfig);
     }
     try {
       const entry = run.journal.files[relativePath];
+      if (
+        !item.decommission &&
+        item.intentVersion !== null &&
+        (!hasCurrentLocalDeleteIntent(entry) ||
+          entry!.localDeleteIntent!.version !== item.intentVersion ||
+          !isLocallyAbsent(path.join(run.syncRoot, relativePath)))
+      ) {
+        counters.filesRefusedStale++;
+        if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
+          filesRefusedStalePaths.push(relativePath);
+        }
+        run.emit({
+          type: "delete-refused-stale-etag",
+          path: relativePath,
+          journalEtag: entry?.remoteEtag ?? "<missing-delete-intent>",
+          remoteEtag: "<not-checked>",
+          reason: "intent-changed",
+        });
+        continue;
+      }
       const size = entry?.size ?? 0;
       await deleteRemoteFile(run.ctx, relativePath);
       removeEntry(run.journal, relativePath);
@@ -2027,7 +2069,9 @@ type RefusedStaleReason =
   | "stale-etag"
   | "legacy-no-etag"
   | "bulk-asymmetry"
-  | "divergent-local";
+  | "divergent-local"
+  | "missing-delete-intent"
+  | "intent-changed";
 
 /**
  * Bulk-asymmetry circuit-breaker — refuses to convert a suspiciously-large
@@ -2091,7 +2135,7 @@ function isBulkAsymmetryOverride(): boolean {
  *                      uses. Emitted as `delete-refused-stale-etag` events.
  */
 interface DeletePlan {
-  toDelete: string[];
+  toDelete: Array<{ key: string; intentVersion: 1 | null }>;
   toTombstone: string[];
   refusedStale: Array<{
     key: string;
@@ -2113,6 +2157,34 @@ interface DeletePlan {
   };
 }
 
+function hasCurrentLocalDeleteIntent(
+  entry: SyncJournal["files"][string] | undefined,
+): boolean {
+  const intent = entry?.localDeleteIntent;
+  return !!(
+    intent &&
+    intent.version === 1 &&
+    entry.remoteEtag &&
+    entry.kind &&
+    intent.remoteEtag === entry.remoteEtag &&
+    intent.localHash === entry.hash &&
+    intent.localKind === entry.kind
+  );
+}
+
+function isLocallyAbsent(localPath: string): boolean {
+  try {
+    fs.lstatSync(localPath);
+    return false;
+  } catch (err: unknown) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? (err as { code?: string }).code
+        : undefined;
+    return code === "ENOENT";
+  }
+}
+
 /**
  * Concurrency cap for the per-file HEAD-O-meter (currency-gated). Sequential
  * HEADs would add ~N×(50-200ms) to a sync — for the 261-mirror real-world
@@ -2216,7 +2288,7 @@ async function computeDeletePlan(
   // all), or queue it for HEAD (currency-gated). Keeping this synchronous
   // means the HEAD pass below sees a single, deduplicated candidate list
   // and the journal-mutation buckets are already settled before any I/O.
-  type HeadCandidate = { key: string; journalEtag: string };
+  type HeadCandidate = { key: string; journalEtag: string; intentVersion: 1 };
   const headCandidates: HeadCandidate[] = [];
   // Litter drain bucket — kept separate from `plan.toDelete` so the
   // bulk-asymmetry breaker (which moves toDelete + headCandidates into
@@ -2263,6 +2335,10 @@ async function computeDeletePlan(
     }
     if (presentLocally) continue;
 
+    if (!companyScoped && isPersonalVaultDeletionExcluded(relativeKey)) {
+      continue;
+    }
+
     // Vault-litter drain (6.0.2): conflict mirrors + rescue drift markers
     // ALWAYS drain, bypassing `shouldSync` (which would skip them when the
     // parent path is in personal-vault default exclusions like
@@ -2316,10 +2392,23 @@ async function computeDeletePlan(
       continue;
     }
 
+    if (!hasCurrentLocalDeleteIntent(entry)) {
+      plan.refusedStale.push({
+        key: relativeKey,
+        journalEtag: entry.remoteEtag ?? "<missing-delete-intent>",
+        remoteEtag: "<not-checked>",
+        reason: "missing-delete-intent",
+      });
+      continue;
+    }
+
     if (policy === "all") {
       // policy:"all" is the explicit-opt-out emergency-reconcile mode; the
       // bulk-asymmetry guard skips this branch (caller asserted intent).
-      plan.toDelete.push(relativeKey);
+      plan.toDelete.push({
+        key: relativeKey,
+        intentVersion: entry.localDeleteIntent!.version,
+      });
       continue;
     }
     bulkCandidatePicks++;
@@ -2332,7 +2421,10 @@ async function computeDeletePlan(
         bulkCandidatePicks--;
         continue;
       }
-      plan.toDelete.push(relativeKey);
+      plan.toDelete.push({
+        key: relativeKey,
+        intentVersion: entry.localDeleteIntent!.version,
+      });
       continue;
     }
     // currency-gated: queue for HEAD unless the entry is legacy (no etag).
@@ -2346,7 +2438,11 @@ async function computeDeletePlan(
       });
       continue;
     }
-    headCandidates.push({ key: relativeKey, journalEtag });
+    headCandidates.push({
+      key: relativeKey,
+      journalEtag,
+      intentVersion: entry.localDeleteIntent!.version,
+    });
   }
 
   // Bulk-asymmetry circuit-breaker. See `BULK_ASYMMETRY_*` constants for
@@ -2375,7 +2471,7 @@ async function computeDeletePlan(
         samplePaths.push(key);
       }
     };
-    for (const key of plan.toDelete) pushRefused(key);
+    for (const item of plan.toDelete) pushRefused(item.key);
     for (const c of headCandidates) pushRefused(c.key);
     plan.toDelete = [];
     plan.bulkAsymmetry = {
@@ -2389,7 +2485,7 @@ async function computeDeletePlan(
     // of user content; litter cleanup is orthogonal and should never be
     // refused for the same reason new-litter producer-side exclusions
     // shouldn't block it.
-    plan.toDelete.push(...litterToDelete);
+    plan.toDelete.push(...litterToDelete.map((key) => ({ key, intentVersion: null })));
     return plan;
   }
 
@@ -2436,7 +2532,10 @@ async function computeDeletePlan(
       }
       const currentEtag = normalizeEtag(remote.etag);
       if (currentEtag === candidate.journalEtag) {
-        plan.toDelete.push(candidate.key);
+        plan.toDelete.push({
+          key: candidate.key,
+          intentVersion: candidate.intentVersion,
+        });
       } else {
         plan.refusedStale.push({
           key: candidate.key,
@@ -2453,7 +2552,7 @@ async function computeDeletePlan(
   // delete loop tombstones each key identically (DeleteObject + remove from
   // journal). Merged at the end so the bulk-asymmetry breaker above had its
   // chance to NOT include litter in either the numerator or the sweep.
-  plan.toDelete.push(...litterToDelete);
+  plan.toDelete.push(...litterToDelete.map((key) => ({ key, intentVersion: null })));
 
   return plan;
 }