@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/remote-pull.test.ts

@@ -1,1130 +0,0 @@
-/**
- * Failing-test seed for the Auto-sync (Beta) remote-pull loop.
- *
- * Background: the watcher push path ships local edits to S3 in seconds,
- * but pulls happen only on a manual sync today. Auto-sync adds a periodic
- * (every 10 min) remote-pull pass per company. The decision of *which* keys
- * to download / delete locally / skip is pure given a remote listing, the
- * journal, and a set of paths currently flagged as conflicts in the
- * conflict store. Isolating that decision in a pure helper makes the
- * 10-min loop trivially testable and keeps S3/FS mocks out of the hot path.
- *
- * The function under test does NOT exist yet — this file is the seed for
- * `decideRemotePulls` in `./remote-pull.ts`. Per the project test-first
- * rule, the implementation lands AFTER these tests are validated.
- */
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import * as crypto from "crypto";
-import {
-  batchPrefixesForVend,
-  decideRemotePulls,
-  listRemoteForScope,
-  POST_FILTER_THRESHOLD,
-  pullCompany,
-  resolveCompanyScope,
-  VEND_FANOUT_CONCURRENCY,
-  VEND_PATH_CAP,
-} from "./remote-pull.js";
-import type { RemoteFile } from "./s3.js";
-import type { EntityContext, SyncJournal } from "./types.js";
-import type {
-  ExplicitGrant,
-  MembershipSyncConfig,
-} from "./vault-client.js";
-import { ScopeShrinkBlockedError } from "./scope-shrink.js";
-
-function remote(partial: Partial<RemoteFile> & { key: string }): RemoteFile {
-  return {
-    size: 100,
-    lastModified: new Date("2026-05-08T00:00:00Z"),
-    etag: "etag-default",
-    ...partial,
-  };
-}
-
-function emptyJournal(): SyncJournal {
-  return { version: "1", lastSync: "", files: {} };
-}
-
-describe("decideRemotePulls", () => {
-  it("downloads keys present remotely but absent from the journal", () => {
-    const remoteFiles = [remote({ key: "docs/new.md", etag: "abc" })];
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal: emptyJournal(),
-      conflictKeys: new Set(),
-    });
-    expect(result.download.map((f) => f.key)).toEqual(["docs/new.md"]);
-    expect(result.deleteLocal).toEqual([]);
-    expect(result.skip).toEqual([]);
-  });
-
-  it("downloads keys whose remote ETag has changed since the last sync", () => {
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/changed.md": {
-          hash: "h",
-          size: 100,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old-etag",
-        },
-      },
-    };
-    const remoteFiles = [remote({ key: "docs/changed.md", etag: "new-etag" })];
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.download.map((f) => f.key)).toEqual(["docs/changed.md"]);
-  });
-
-  it("skips keys whose ETag matches the last-synced ETag (idempotent)", () => {
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/same.md": {
-          hash: "h",
-          size: 100,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "same-etag",
-        },
-      },
-    };
-    const remoteFiles = [remote({ key: "docs/same.md", etag: "same-etag" })];
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.download).toEqual([]);
-    expect(result.skip.map((f) => f.key)).toEqual(["docs/same.md"]);
-  });
-
-  it("normalizes quoted ETags before comparison (S3 wraps in literal quotes)", () => {
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/q.md": {
-          hash: "h",
-          size: 100,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "abc123",
-        },
-      },
-    };
-    // The remote listing wraps the etag in quotes — same content, different
-    // string. decideRemotePulls must treat these as equal.
-    const remoteFiles = [remote({ key: "docs/q.md", etag: '"abc123"' })];
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.download).toEqual([]);
-    expect(result.skip.map((f) => f.key)).toEqual(["docs/q.md"]);
-  });
-
-  it("schedules a local delete for keys present in the journal but absent remotely", () => {
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/gone.md": {
-          hash: "h",
-          size: 100,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old",
-        },
-      },
-    };
-    const result = decideRemotePulls({
-      remoteFiles: [],
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.deleteLocal).toEqual(["docs/gone.md"]);
-    expect(result.download).toEqual([]);
-  });
-
-  it("F07: excludes scope-shrink tombstones from remote-delete decisions", () => {
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/scope-shrunk-dirty.md": {
-          hash: "dirty-before-shrink",
-          size: 42,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old-dirty",
-          removedAt: "2026-05-02T00:00:00Z",
-          removedReason: "scope_shrink",
-        },
-        "docs/live-gone.md": {
-          hash: "h",
-          size: 100,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old-live",
-        },
-      },
-      pulls: [],
-    };
-    const result = decideRemotePulls({
-      remoteFiles: [],
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.deleteLocal).toEqual(["docs/live-gone.md"]);
-    expect(result.download).toEqual([]);
-  });
-
-  it("R-F07: excludes scope-shrink-protected survivors from remote-delete decisions", async () => {
-    const hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rf07-"));
-    try {
-      const journal: SyncJournal = {
-        version: "2",
-        lastSync: "2026-05-01T00:00:00Z",
-        files: {
-          "companies/indigo/projects/mine.md": {
-            hash: "h-mine",
-            size: 6,
-            syncedAt: "2026-05-01T00:00:00Z",
-            direction: "down",
-            remoteEtag: "old-mine",
-            createdBySub: "owner-sub",
-          },
-          "companies/indigo/projects/legacy.md": {
-            hash: "h-legacy",
-            size: 6,
-            syncedAt: "2026-05-01T00:00:00Z",
-            direction: "down",
-            remoteEtag: "old-legacy",
-          },
-          "companies/indigo/meetings/gone.md": {
-            hash: "h-gone",
-            size: 4,
-            syncedAt: "2026-05-01T00:00:00Z",
-            direction: "down",
-            remoteEtag: "old-gone",
-            createdBySub: "peer-sub",
-          },
-        },
-        pulls: [
-          {
-            pullId: "01PREV",
-            companyUid: "cmp_indigo",
-            startedAt: "2026-05-19T00:00:00.000Z",
-            completedAt: "2026-05-19T00:00:05.000Z",
-            syncMode: "all",
-            prefixSet: ["companies/indigo/"],
-            scopeChangeDetected: false,
-            orphansRemoved: 0,
-            orphansBlocked: 0,
-          },
-        ],
-      };
-
-      const result = await pullCompany({
-        ctx: makeCtx(),
-        journal,
-        hqRoot,
-        callerSub: "owner-sub",
-        scope: {
-          companyUid: "cmp_indigo",
-          syncMode: "shared",
-          prefixSet: ["companies/indigo/meetings/"],
-          strategy: "vend-fanout",
-        },
-        listFn: async () => [],
-      });
-
-      expect(result.decision.deleteLocal).toEqual([
-        "companies/indigo/meetings/gone.md",
-      ]);
-      expect(result.decision.skip.map((f) => f.key).sort()).toEqual([
-        "companies/indigo/projects/legacy.md",
-        "companies/indigo/projects/mine.md",
-      ]);
-    } finally {
-      fs.rmSync(hqRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("never deletes locally for entries that have NEVER been synced down", () => {
-    // Push-only entries (direction: 'up') represent files we created locally
-    // and uploaded. If the user later deletes them remotely from another
-    // machine, that's still a tombstone case — but if no journal entry
-    // exists at all (e.g. ignored / untracked), there's nothing to delete.
-    // Guard: keys absent from BOTH journal and remote produce no decisions.
-    const result = decideRemotePulls({
-      remoteFiles: [],
-      journal: emptyJournal(),
-      conflictKeys: new Set(),
-    });
-    expect(result.download).toEqual([]);
-    expect(result.deleteLocal).toEqual([]);
-    expect(result.skip).toEqual([]);
-  });
-
-  it("skips files currently flagged in the conflict store (auto-pull never clobbers conflicts)", () => {
-    // Per the agreed conflict policy: auto-sync skips conflicting files and
-    // surfaces them through the existing modal — same behavior as manual
-    // sync's `--on-conflict keep`. The watcher must NEVER write over a file
-    // the user is in the middle of resolving.
-    const remoteFiles = [
-      remote({ key: "docs/conflict.md", etag: "remote-1" }),
-      remote({ key: "docs/clean.md", etag: "remote-2" }),
-    ];
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/conflict.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old",
-        },
-      },
-    };
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal,
-      conflictKeys: new Set(["docs/conflict.md"]),
-    });
-    expect(result.download.map((f) => f.key)).toEqual(["docs/clean.md"]);
-    expect(result.skip.map((f) => f.key)).toEqual(["docs/conflict.md"]);
-    expect(result.deleteLocal).toEqual([]);
-  });
-
-  it("skips a tombstone-delete when the key is in the conflict store", () => {
-    // If a remote tombstone arrives for a file the user is actively
-    // conflict-resolving locally, we must NOT delete the local copy.
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/conflict.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "down",
-          remoteEtag: "old",
-        },
-      },
-    };
-    const result = decideRemotePulls({
-      remoteFiles: [],
-      journal,
-      conflictKeys: new Set(["docs/conflict.md"]),
-    });
-    expect(result.deleteLocal).toEqual([]);
-    expect(result.skip.map((f) => f.key)).toEqual(["docs/conflict.md"]);
-  });
-
-  it("treats a journal entry without remoteEtag as 'never pulled' and downloads", () => {
-    // Backwards compat: pre-ETag journal entries (push-only or ancient
-    // installs) lack `remoteEtag`. Auto-pull must download to get into a
-    // known state rather than skipping.
-    const journal: SyncJournal = {
-      version: "1",
-      lastSync: "2026-05-01T00:00:00Z",
-      files: {
-        "docs/legacy.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "2026-05-01T00:00:00Z",
-          direction: "up",
-          // remoteEtag intentionally absent
-        },
-      },
-    };
-    const remoteFiles = [remote({ key: "docs/legacy.md", etag: "now-known" })];
-    const result = decideRemotePulls({
-      remoteFiles,
-      journal,
-      conflictKeys: new Set(),
-    });
-    expect(result.download.map((f) => f.key)).toEqual(["docs/legacy.md"]);
-  });
-});
-
-// ─── US-005 — ACL-aware narrowing in the engine layer ────────────────────────
-
-function sha256(s: string): string {
-  return crypto.createHash("sha256").update(s).digest("hex");
-}
-
-function makeCtx(): EntityContext {
-  return {
-    uid: "cmp_indigo",
-    slug: "indigo",
-    bucketName: "cmp-indigo-vault",
-    region: "us-east-1",
-    credentials: {
-      accessKeyId: "k",
-      secretAccessKey: "s",
-      sessionToken: "t",
-    },
-    expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
-  };
-}
-
-function makeSyncConfig(
-  partial: Partial<MembershipSyncConfig> & { syncMode: MembershipSyncConfig["syncMode"] },
-): MembershipSyncConfig {
-  return {
-    membershipId: "mb_test",
-    isDefault: false,
-    ...partial,
-  };
-}
-
-function makeGrant(p: string): ExplicitGrant {
-  return {
-    companyUid: "cmp_indigo",
-    path: p,
-    permission: "read",
-    source: "person",
-  };
-}
-
-describe("resolveCompanyScope", () => {
-  it("syncMode='all' returns strategy=all with the company prefix", () => {
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({ syncMode: "all" }),
-    });
-    expect(scope.strategy).toBe("all");
-    expect(scope.prefixSet).toEqual(["companies/indigo/"]);
-    expect(scope.syncMode).toBe("all");
-  });
-
-  it("syncMode='shared' coalesces explicit grants and picks vend-fanout when ≤ POST_FILTER_THRESHOLD", () => {
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({ syncMode: "shared" }),
-      explicitGrants: [
-        makeGrant("companies/indigo/meetings/"),
-        makeGrant("companies/indigo/meetings/2026/"), // nested — collapsed
-        makeGrant("companies/indigo/scratch/jacob/"),
-      ],
-    });
-    expect(scope.strategy).toBe("vend-fanout");
-    expect(scope.prefixSet).toEqual([
-      "companies/indigo/meetings/",
-      "companies/indigo/scratch/jacob/",
-    ]);
-  });
-
-  it("syncMode='shared' with no grants returns empty prefixSet (short-circuit)", () => {
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({ syncMode: "shared" }),
-      explicitGrants: [],
-    });
-    expect(scope.prefixSet).toEqual([]);
-  });
-
-  it("syncMode='shared' with > POST_FILTER_THRESHOLD coalesced prefixes picks broad-postfilter", () => {
-    const grants: ExplicitGrant[] = [];
-    for (let i = 0; i < POST_FILTER_THRESHOLD + 5; i++) {
-      grants.push(makeGrant(`companies/indigo/p${i}/`));
-    }
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({ syncMode: "shared" }),
-      explicitGrants: grants,
-    });
-    expect(scope.strategy).toBe("broad-postfilter");
-    expect(scope.prefixSet.length).toBe(POST_FILTER_THRESHOLD + 5);
-  });
-
-  it("syncMode='custom' coalesces customPaths", () => {
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({
-        syncMode: "custom",
-        customPaths: [
-          "companies/indigo/a/",
-          "companies/indigo/a/b/", // nested
-          "companies/indigo/c/",
-        ],
-      }),
-    });
-    expect(scope.prefixSet).toEqual([
-      "companies/indigo/a/",
-      "companies/indigo/c/",
-    ]);
-  });
-});
-
-describe("batchPrefixesForVend", () => {
-  it("batches into chunks of VEND_PATH_CAP", () => {
-    const prefixes = Array.from({ length: 23 }, (_, i) => `p${i}/`);
-    const batches = batchPrefixesForVend(prefixes);
-    expect(batches).toHaveLength(3);
-    expect(batches[0]).toHaveLength(VEND_PATH_CAP);
-    expect(batches[1]).toHaveLength(VEND_PATH_CAP);
-    expect(batches[2]).toHaveLength(3);
-  });
-
-  it("respects an explicit cap override", () => {
-    const prefixes = ["a/", "b/", "c/", "d/", "e/"];
-    const batches = batchPrefixesForVend(prefixes, 2);
-    expect(batches.map((b) => b.length)).toEqual([2, 2, 1]);
-  });
-
-  it("returns [] for empty input", () => {
-    expect(batchPrefixesForVend([])).toEqual([]);
-  });
-});
-
-describe("listRemoteForScope", () => {
-  it("strategy=all calls list once with the company prefix", async () => {
-    const calls: Array<string | undefined> = [];
-    const files = await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "all",
-        prefixSet: ["companies/indigo/"],
-        strategy: "all",
-      },
-      listFn: async (_ctx, prefix) => {
-        calls.push(prefix);
-        return [remote({ key: "companies/indigo/a.md", etag: "1" })];
-      },
-    });
-    expect(calls).toEqual(["companies/indigo/"]);
-    expect(files.map((f) => f.key)).toEqual(["companies/indigo/a.md"]);
-  });
-
-  it("strategy=vend-fanout issues one list per prefix and unions+dedupes", async () => {
-    const calls: Array<string | undefined> = [];
-    const files = await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: [
-          "companies/indigo/meetings/",
-          "companies/indigo/scratch/jacob/",
-        ],
-        strategy: "vend-fanout",
-      },
-      listFn: async (_ctx, prefix) => {
-        calls.push(prefix);
-        if (prefix === "companies/indigo/meetings/") {
-          return [
-            remote({ key: "companies/indigo/meetings/a.md", etag: "1" }),
-            remote({ key: "companies/indigo/meetings/shared.md", etag: "1" }),
-          ];
-        }
-        return [
-          remote({ key: "companies/indigo/scratch/jacob/draft.md", etag: "2" }),
-          // dedup target — same key reported by both prefixes if they overlap
-          remote({ key: "companies/indigo/meetings/shared.md", etag: "1" }),
-        ];
-      },
-    });
-    expect(calls.sort()).toEqual([
-      "companies/indigo/meetings/",
-      "companies/indigo/scratch/jacob/",
-    ]);
-    expect(files.map((f) => f.key).sort()).toEqual([
-      "companies/indigo/meetings/a.md",
-      "companies/indigo/meetings/shared.md",
-      "companies/indigo/scratch/jacob/draft.md",
-    ]);
-  });
-
-  it("strategy=vend-fanout with > VEND_PATH_CAP prefixes batches and lists all of them", async () => {
-    const prefixes = Array.from(
-      { length: VEND_PATH_CAP + 3 },
-      (_, i) => `companies/indigo/p${i}/`,
-    );
-    const calls = new Set<string | undefined>();
-    await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: prefixes,
-        strategy: "vend-fanout",
-      },
-      listFn: async (_ctx, prefix) => {
-        calls.add(prefix);
-        return [];
-      },
-    });
-    expect(calls.size).toBe(VEND_PATH_CAP + 3); // every prefix listed
-  });
-
-  it("F28: bounds concurrent per-prefix listings across vend-fanout batches", async () => {
-    const prefixes = Array.from(
-      { length: POST_FILTER_THRESHOLD },
-      (_, i) => `companies/indigo/p${i}/`,
-    );
-    let active = 0;
-    let maxActive = 0;
-
-    await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: prefixes,
-        strategy: "vend-fanout",
-      },
-      listFn: async () => {
-        active += 1;
-        maxActive = Math.max(maxActive, active);
-        await new Promise((resolve) => setTimeout(resolve, 1));
-        active -= 1;
-        return [];
-      },
-    });
-
-    expect(maxActive).toBeLessThanOrEqual(VEND_FANOUT_CONCURRENCY);
-  });
-
-  it("strategy=vend-fanout uses vendForBatchFn to narrow credentials per batch", async () => {
-    const vendCalls: Array<{ paths: string[] }> = [];
-    await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/a/", "companies/indigo/b/"],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => [],
-      vendForBatchFn: async (ctx, paths) => {
-        vendCalls.push({ paths });
-        return ctx;
-      },
-    });
-    expect(vendCalls).toHaveLength(1); // one batch (≤ VEND_PATH_CAP)
-    expect(vendCalls[0]?.paths).toEqual([
-      "companies/indigo/a/",
-      "companies/indigo/b/",
-    ]);
-  });
-
-  it("strategy=broad-postfilter issues one wide list + client-side filter", async () => {
-    const calls: Array<string | undefined> = [];
-    const files = await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/meetings/"],
-        strategy: "broad-postfilter",
-      },
-      listFn: async (_ctx, prefix) => {
-        calls.push(prefix);
-        return [
-          remote({ key: "companies/indigo/meetings/a.md" }),
-          remote({ key: "companies/indigo/scratch/jacob/draft.md" }),
-        ];
-      },
-    });
-    expect(calls).toEqual([undefined]); // one broad list, no prefix
-    expect(files.map((f) => f.key)).toEqual([
-      "companies/indigo/meetings/a.md",
-    ]);
-  });
-
-  it("R-F16: strategy=vend-fanout post-filters exact-grant siblings", async () => {
-    const scope = resolveCompanyScope({
-      companyUid: "cmp_indigo",
-      companyPrefix: "companies/indigo/",
-      syncConfig: makeSyncConfig({ syncMode: "shared" }),
-      explicitGrants: [makeGrant("companies/indigo/README.md")],
-    });
-    const files = await listRemoteForScope({
-      ctx: makeCtx(),
-      scope,
-      listFn: async (_ctx, prefix) => {
-        expect(prefix).toBe("companies/indigo/README.md");
-        return [
-          remote({ key: "companies/indigo/README.md" }),
-          remote({ key: "companies/indigo/README.md.bak" }),
-        ];
-      },
-    });
-
-    expect(files.map((f) => f.key)).toEqual(["companies/indigo/README.md"]);
-  });
-
-  it("strategy=vend-fanout short-circuits to [] on empty prefixSet", async () => {
-    let listed = false;
-    const files = await listRemoteForScope({
-      ctx: makeCtx(),
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: [],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => {
-        listed = true;
-        return [];
-      },
-    });
-    expect(listed).toBe(false);
-    expect(files).toEqual([]);
-  });
-});
-
-describe("pullCompany (engine orchestrator)", () => {
-  let hqRoot: string;
-
-  beforeEach(() => {
-    hqRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-pull-company-"));
-  });
-
-  afterEach(() => {
-    fs.rmSync(hqRoot, { recursive: true, force: true });
-  });
-
-  it("records syncMode + prefixSet on the PullRecord for an 'all' pull", async () => {
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {},
-      pulls: [],
-    };
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "all",
-        prefixSet: ["companies/indigo/"],
-        strategy: "all",
-      },
-      listFn: async () => [],
-    });
-    expect(result.pullRecord.syncMode).toBe("all");
-    expect(result.pullRecord.prefixSet).toEqual(["companies/indigo/"]);
-    expect(result.pullRecord.scopeChangeDetected).toBe(false);
-    expect(journal.pulls).toHaveLength(1);
-  });
-
-  it("aborts with ScopeShrinkBlockedError on dirty orphan (default mode)", async () => {
-    const abs = path.join(
-      hqRoot,
-      "companies/indigo/scratch/notes.md",
-    );
-    fs.mkdirSync(path.dirname(abs), { recursive: true });
-    fs.writeFileSync(abs, "MODIFIED");
-
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "companies/indigo/scratch/notes.md": {
-          hash: sha256("ORIGINAL"),
-          size: 8,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-          // Authored by someone else (no matching callerSub passed below), so
-          // the authorship guard correctly leaves it eligible for shrink.
-          createdBySub: "uploader-sub",
-        },
-      },
-      pulls: [
-        {
-          pullId: "01PREV",
-          companyUid: "cmp_indigo",
-          startedAt: "2026-05-19T00:00:00.000Z",
-          completedAt: "2026-05-19T00:00:05.000Z",
-          syncMode: "all",
-          prefixSet: ["companies/indigo/"],
-          scopeChangeDetected: false,
-          orphansRemoved: 0,
-          orphansBlocked: 0,
-        },
-      ],
-    };
-
-    await expect(
-      pullCompany({
-        ctx: makeCtx(),
-        journal,
-        hqRoot,
-        scope: {
-          companyUid: "cmp_indigo",
-          syncMode: "shared",
-          prefixSet: ["companies/indigo/meetings/"],
-          strategy: "vend-fanout",
-        },
-        listFn: async () => [],
-      }),
-    ).rejects.toBeInstanceOf(ScopeShrinkBlockedError);
-  });
-
-  it("applies scope-shrink + records orphansBlocked when forceScopeShrink=true", async () => {
-    const dirtyAbs = path.join(
-      hqRoot,
-      "companies/indigo/scratch/dirty.md",
-    );
-    const cleanAbs = path.join(
-      hqRoot,
-      "companies/indigo/scratch/clean.md",
-    );
-    fs.mkdirSync(path.dirname(dirtyAbs), { recursive: true });
-    fs.writeFileSync(dirtyAbs, "MODIFIED");
-    fs.writeFileSync(cleanAbs, "clean");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(cleanAbs, past / 1000, past / 1000);
-
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "companies/indigo/scratch/dirty.md": {
-          hash: sha256("ORIGINAL"),
-          size: 8,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-          createdBySub: "uploader-sub", // foreign author — eligible for shrink
-        },
-        "companies/indigo/scratch/clean.md": {
-          hash: sha256("clean"),
-          size: 5,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-          createdBySub: "uploader-sub", // foreign author — eligible for shrink
-        },
-      },
-      pulls: [
-        {
-          pullId: "01PREV",
-          companyUid: "cmp_indigo",
-          startedAt: "2026-05-19T00:00:00.000Z",
-          completedAt: "2026-05-19T00:00:05.000Z",
-          syncMode: "all",
-          prefixSet: ["companies/indigo/"],
-          scopeChangeDetected: false,
-          orphansRemoved: 0,
-          orphansBlocked: 0,
-        },
-      ],
-    };
-
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      forceScopeShrink: true,
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/meetings/"],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => [],
-    });
-
-    expect(result.pullRecord.scopeChangeDetected).toBe(true);
-    expect(result.pullRecord.orphansRemoved).toBe(1); // clean
-    expect(result.pullRecord.orphansBlocked).toBe(1); // dirty tombstoned
-    expect(fs.existsSync(cleanAbs)).toBe(false); // deleted
-    expect(fs.existsSync(dirtyAbs)).toBe(true); // preserved
-    expect(
-      journal.files["companies/indigo/scratch/dirty.md"]?.removedAt,
-    ).toBeTruthy();
-  });
-
-  it("v1 → v2 migration: empty pulls[] history treats last scope as company-prefix-wide", async () => {
-    // No previous PullRecord → engine derives `companies/indigo/` as the
-    // "last scope" so a scope shrink to a narrower prefix is correctly
-    // detected on the FIRST v2 pull after upgrade.
-    const journal: SyncJournal = {
-      version: "1", // simulate pre-upgrade
-      lastSync: "",
-      files: {
-        "companies/indigo/scratch/jacob/draft.md": {
-          hash: sha256("draft"),
-          size: 5,
-          syncedAt: new Date(Date.now() - 60_000).toISOString(),
-          direction: "down",
-          createdBySub: "uploader-sub", // foreign author — eligible for shrink
-        },
-      },
-    };
-    const draftAbs = path.join(
-      hqRoot,
-      "companies/indigo/scratch/jacob/draft.md",
-    );
-    fs.mkdirSync(path.dirname(draftAbs), { recursive: true });
-    fs.writeFileSync(draftAbs, "draft");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(draftAbs, past / 1000, past / 1000);
-
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/meetings/"],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => [],
-    });
-
-    expect(result.pullRecord.scopeChangeDetected).toBe(true);
-    expect(result.pullRecord.orphansRemoved).toBe(1);
-    expect(journal.version).toBe("2"); // migrated by appendPullRecord
-  });
-
-  it("retains a caller-authored orphan across a scope shrink (own work is never pruned)", async () => {
-    // The owner narrowed to `shared`, but `projects/mine.md` is their own work
-    // (createdBySub === callerSub). A scope shrink must NOT prune it — mode
-    // only governs mirroring OTHER people's files.
-    const mineAbs = path.join(hqRoot, "companies/indigo/projects/mine.md");
-    fs.mkdirSync(path.dirname(mineAbs), { recursive: true });
-    fs.writeFileSync(mineAbs, "mine");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(mineAbs, past / 1000, past / 1000);
-
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "companies/indigo/projects/mine.md": {
-          hash: sha256("mine"),
-          size: 4,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-          createdBySub: "owner-sub",
-        },
-      },
-      pulls: [
-        {
-          pullId: "01PREV",
-          companyUid: "cmp_indigo",
-          startedAt: "2026-05-19T00:00:00.000Z",
-          completedAt: "2026-05-19T00:00:05.000Z",
-          syncMode: "all",
-          prefixSet: ["companies/indigo/"],
-          scopeChangeDetected: false,
-          orphansRemoved: 0,
-          orphansBlocked: 0,
-        },
-      ],
-    };
-
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      callerSub: "owner-sub",
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/meetings/"],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => [],
-    });
-
-    expect(result.pullRecord.scopeChangeDetected).toBe(false);
-    expect(result.pullRecord.orphansRemoved).toBe(0);
-    expect(fs.existsSync(mineAbs)).toBe(true); // own work preserved
-  });
-
-  it("retains an unknown-author orphan on the automatic path (conservative, never auto-deletes)", async () => {
-    // A legacy entry with no recorded author. The background pull must not make
-    // a destructive guess — retain it (the explicit narrow ritual is the
-    // confirmed path that can reclaim it).
-    const legacyAbs = path.join(hqRoot, "companies/indigo/projects/legacy.md");
-    fs.mkdirSync(path.dirname(legacyAbs), { recursive: true });
-    fs.writeFileSync(legacyAbs, "legacy");
-    const past = Date.now() - 60_000;
-    fs.utimesSync(legacyAbs, past / 1000, past / 1000);
-
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "companies/indigo/projects/legacy.md": {
-          hash: sha256("legacy"),
-          size: 6,
-          syncedAt: new Date().toISOString(),
-          direction: "down",
-          // no createdBySub — predates author stamping
-        },
-      },
-      pulls: [
-        {
-          pullId: "01PREV",
-          companyUid: "cmp_indigo",
-          startedAt: "2026-05-19T00:00:00.000Z",
-          completedAt: "2026-05-19T00:00:05.000Z",
-          syncMode: "all",
-          prefixSet: ["companies/indigo/"],
-          scopeChangeDetected: false,
-          orphansRemoved: 0,
-          orphansBlocked: 0,
-        },
-      ],
-    };
-
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      callerSub: "owner-sub",
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "shared",
-        prefixSet: ["companies/indigo/meetings/"],
-        strategy: "vend-fanout",
-      },
-      listFn: async () => [],
-    });
-
-    expect(result.pullRecord.scopeChangeDetected).toBe(false);
-    expect(result.pullRecord.orphansRemoved).toBe(0);
-    expect(fs.existsSync(legacyAbs)).toBe(true); // legacy file retained
-  });
-
-  it("RF-F07DUR: scope-shrink-protected survivors are excluded on a second pull", async () => {
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "companies/indigo/projects/legacy.md": {
-          hash: "h-legacy",
-          size: 6,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          remoteEtag: "old-legacy",
-        },
-        "companies/indigo/meetings/gone.md": {
-          hash: "h-gone",
-          size: 4,
-          syncedAt: "2026-05-01T00:00:00.000Z",
-          direction: "down",
-          remoteEtag: "old-gone",
-          createdBySub: "peer-sub",
-        },
-      },
-      pulls: [
-        {
-          pullId: "01PREV",
-          companyUid: "cmp_indigo",
-          startedAt: "2026-05-19T00:00:00.000Z",
-          completedAt: "2026-05-19T00:00:05.000Z",
-          syncMode: "all",
-          prefixSet: ["companies/indigo/"],
-          scopeChangeDetected: false,
-          orphansRemoved: 0,
-          orphansBlocked: 0,
-        },
-      ],
-    };
-    const narrowedScope = {
-      companyUid: "cmp_indigo",
-      syncMode: "shared" as const,
-      prefixSet: ["companies/indigo/meetings/"],
-      strategy: "vend-fanout" as const,
-    };
-
-    const first = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      callerSub: "owner-sub",
-      scope: narrowedScope,
-      listFn: async () => [],
-    });
-
-    expect(first.decision.skip.map((f) => f.key)).toContain(
-      "companies/indigo/projects/legacy.md",
-    );
-    expect(first.decision.deleteLocal).toEqual([
-      "companies/indigo/meetings/gone.md",
-    ]);
-    expect(
-      journal.files["companies/indigo/projects/legacy.md"]?.outOfScopeProtected,
-    ).toBe(true);
-
-    const second = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      callerSub: "owner-sub",
-      scope: narrowedScope,
-      listFn: async () => [],
-    });
-
-    expect(second.decision.skip.map((f) => f.key)).toContain(
-      "companies/indigo/projects/legacy.md",
-    );
-    expect(second.decision.deleteLocal).toEqual([
-      "companies/indigo/meetings/gone.md",
-    ]);
-  });
-
-  it("GC's expired tombstones at the start of every leg", async () => {
-    const old = new Date(
-      Date.now() - 31 * 24 * 60 * 60 * 1000,
-    ).toISOString();
-    const journal: SyncJournal = {
-      version: "2",
-      lastSync: "",
-      files: {
-        "old-tombstone.md": {
-          hash: "h",
-          size: 1,
-          syncedAt: "",
-          direction: "down",
-          removedAt: old,
-          removedReason: "scope_shrink",
-        },
-      },
-      pulls: [],
-    };
-    const result = await pullCompany({
-      ctx: makeCtx(),
-      journal,
-      hqRoot,
-      scope: {
-        companyUid: "cmp_indigo",
-        syncMode: "all",
-        prefixSet: ["companies/indigo/"],
-        strategy: "all",
-      },
-      listFn: async () => [],
-    });
-    expect(result.tombstonesGcd).toBe(1);
-    expect(journal.files["old-tombstone.md"]).toBeUndefined();
-  });
-});