@indigoai-us/hq-cloud 5.41.0 → 5.42.0

package/src/bin/sync-runner.test.ts

@@ -18,6 +18,7 @@ import {
   resolveSkipPersonal,
   routeChangeToTarget,
   buildTargetedPushArgv,
+  resolvePullScope,
 } from "./sync-runner.js";
 import type {
   RunnerEvent,
@@ -100,6 +101,9 @@ function defaultSyncResult(overrides: Partial<SyncResult> = {}): SyncResult {
     newFilesCount: 0,
     filesExcludedByPolicy: 0,
     filesTombstoned: 0,
+    filesOutOfScope: 0,
+    scopeOrphansRemoved: 0,
+    scopeOrphansBlocked: 0,
     ...overrides,
   };
 }
@@ -1075,6 +1079,9 @@ describe("per-company fanout", () => {
       filesExcludedByPolicy: 0,
       newFiles: result.newFiles,
       newFilesCount: result.newFilesCount,
+      filesOutOfScope: result.filesOutOfScope,
+      scopeOrphansRemoved: result.scopeOrphansRemoved,
+      scopeOrphansBlocked: result.scopeOrphansBlocked,
     });
   });
 
@@ -3117,3 +3124,218 @@ describe("resolveSkipPersonal", () => {
     },
   );
 });
+
+// ---------------------------------------------------------------------------
+// resolvePullScope (US-005) — effective download scope per company leg
+// ---------------------------------------------------------------------------
+
+describe("resolvePullScope", () => {
+  function stubClient(
+    overrides: Partial<VaultClientSurface>,
+  ): VaultClientSurface {
+    return {
+      listMyMemberships: async () => [],
+      listMyPendingInvitesByEmail: async () => [],
+      claimPendingInvitesByEmail: async () => {},
+      ensureMyPersonEntity: async () => ({ uid: "p", slug: "p" }) as never,
+      entity: {
+        get: async (uid: string) => ({ uid, slug: uid }) as never,
+        listByType: async () => [],
+      },
+      ...overrides,
+    };
+  }
+
+  const membership = (companyUid: string, membershipKey: string) =>
+    ({
+      membershipKey,
+      personUid: "prs_1",
+      companyUid,
+      role: "member",
+      status: "active",
+      invitedBy: "prs_0",
+      invitedAt: "2026-01-01T00:00:00.000Z",
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    }) as never;
+
+  it("returns all when the client has no getMembershipSyncConfig", async () => {
+    const scope = await resolvePullScope(stubClient({}), "cmp_a", "acme");
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+
+  it("returns all for an all-mode membership (no prefixSet)", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "all",
+          isDefault: true,
+        }),
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+
+  it("coalesces explicit grants for a shared-mode membership", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "shared",
+          isDefault: false,
+        }),
+        listMyExplicitGrants: async () => [
+          { companyUid: "cmp_a", path: "knowledge/", permission: "read", source: "person" },
+          { companyUid: "cmp_a", path: "knowledge/sub/", permission: "read", source: "group" },
+          { companyUid: "cmp_a", path: "shared/", permission: "read", source: "open" },
+        ] as never,
+      }),
+      "cmp_a",
+      "acme",
+    );
+    // knowledge/sub/ is covered by knowledge/ → coalesced away.
+    expect(scope.syncMode).toBe("shared");
+    expect(scope.prefixSet).toEqual(["knowledge/", "shared/"]);
+  });
+
+  it("normalizes real-world mixed/glob grant paths into company-relative prefixes", async () => {
+    // The exact shapes observed in the live hq-pro vault for `indigo`:
+    // bare glob, full-anchored + /*, full-anchored exact file, slug-anchored
+    // + /*, company-relative + /*, and a company-relative exact file.
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_indigo", "mk_i")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_i",
+          syncMode: "shared",
+          isDefault: false,
+        }),
+        listMyExplicitGrants: async () =>
+          [
+            { companyUid: "cmp_indigo", path: "companies/indigo/design-pack/*", permission: "write", source: "person" },
+            { companyUid: "cmp_indigo", path: "companies/indigo/knowledge/README.md", permission: "write", source: "person" },
+            { companyUid: "cmp_indigo", path: "indigo/data/vyg/old-meetings/*", permission: "write", source: "person" },
+            { companyUid: "cmp_indigo", path: "data/vyg/*", permission: "write", source: "person" },
+            { companyUid: "cmp_indigo", path: "company.yaml", permission: "read", source: "open" },
+          ] as never,
+      }),
+      "cmp_indigo",
+      "indigo",
+    );
+    expect(scope.syncMode).toBe("shared");
+    // All anchors stripped, globs folded to startsWith-prefixes, sorted —
+    // and `data/vyg/old-meetings/` is subsumed by the broader `data/vyg/`.
+    expect(scope.prefixSet).toEqual([
+      "company.yaml",
+      "data/vyg/",
+      "design-pack/",
+      "knowledge/README.md",
+    ]);
+  });
+
+  it("a bare '*' grant resolves to everything (empty-string prefix)", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "shared",
+          isDefault: false,
+        }),
+        listMyExplicitGrants: async () =>
+          [{ companyUid: "cmp_a", path: "*", permission: "admin", source: "group" }] as never,
+      }),
+      "cmp_a",
+      "acme",
+    );
+    // A `*` grant = everything. Because coalescePrefixes drops the empty
+    // prefix (which would otherwise collapse to "nothing" and prune the
+    // tree), an everything-scope resolves to full-access `all`.
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+
+  it("uses customPaths for a custom-mode membership", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "custom",
+          customPaths: ["projects/x/", "projects/x/deep/"],
+          isDefault: false,
+        }),
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope.syncMode).toBe("custom");
+    expect(scope.prefixSet).toEqual(["projects/x/"]);
+  });
+
+  it("degrades to all for shared mode when listMyExplicitGrants is unavailable (never empty-prune)", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "shared",
+          isDefault: false,
+        }),
+        // listMyExplicitGrants intentionally absent.
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+
+  it("allows a genuinely-empty shared scope (grants method present, returns [])", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => ({
+          membershipId: "mk_a",
+          syncMode: "shared",
+          isDefault: false,
+        }),
+        listMyExplicitGrants: async () => [],
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope).toEqual({ syncMode: "shared", prefixSet: [] });
+  });
+
+  it("degrades to all when the membership is not found", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_other", "mk_o")],
+        getMembershipSyncConfig: async () => {
+          throw new Error("should not be called");
+        },
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+
+  it("degrades to all when sync-config resolution throws (never prune on error)", async () => {
+    const scope = await resolvePullScope(
+      stubClient({
+        listMyMemberships: async () => [membership("cmp_a", "mk_a")],
+        getMembershipSyncConfig: async () => {
+          throw new Error("network blip");
+        },
+      }),
+      "cmp_a",
+      "acme",
+    );
+    expect(scope).toEqual({ syncMode: "all" });
+  });
+});

package/src/bin/sync-runner.ts

@@ -71,8 +71,12 @@ import {
   type Membership,
   type EntityInfo,
   type PendingInviteByEmail,
+  type SyncMode,
+  type MembershipSyncConfig,
+  type ExplicitGrant,
 } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
+import { coalescePrefixes, grantPathToPrefix } from "../prefix-coalesce.js";
 import {
   PERSONAL_VAULT_EXCLUDED_TOP_LEVEL,
   computePersonalVaultPaths,
@@ -339,6 +343,84 @@ export interface VaultClientSurface {
     get: (uid: string) => Promise<EntityInfo>;
     listByType: (type: string) => Promise<EntityInfo[]>;
   };
+  // US-005 scope resolution. Optional so older test stubs (and any
+  // VaultClientSurface impl that predates sync-config) still satisfy the
+  // interface; when absent, `resolvePullScope` degrades to `all`.
+  getMembershipSyncConfig?: (membershipId: string) => Promise<MembershipSyncConfig>;
+  listMyExplicitGrants?: (companyUid: string) => Promise<ExplicitGrant[]>;
+}
+
+/**
+ * Effective download scope for one company leg (US-005). Resolved per company
+ * just before its pull, then handed to `sync()` as `{ syncMode, prefixSet }`.
+ */
+export interface PullScope {
+  syncMode: SyncMode;
+  /** Coalesced company-relative prefixes; omitted/undefined for `all`. */
+  prefixSet?: string[];
+}
+
+/**
+ * Resolve the effective download scope for a company target.
+ *
+ *   - `all`    → no prefix set; full-bucket pull (legacy behavior).
+ *   - `shared` → coalesced caller explicit grants (company-relative paths,
+ *                same namespace as `RemoteFile.key`).
+ *   - `custom` → coalesced `customPaths` from the sync-config row.
+ *
+ * DEGRADE-TO-`all` CONTRACT: any failure (missing client method, membership
+ * not found, network error, grant fetch error) returns `{ syncMode: "all" }`.
+ * A transient failure must NEVER silently narrow scope — that would prune the
+ * local tree. Mirrors the CLI's `resolvePerCompanyPullPlan` degrade behavior.
+ */
+export async function resolvePullScope(
+  client: VaultClientSurface,
+  companyUid: string,
+  // Company slug — required to normalize grant paths (which may be anchored
+  // at `companies/<slug>/` or `<slug>/`) into the company-relative namespace.
+  slug: string,
+): Promise<PullScope> {
+  if (!client.getMembershipSyncConfig) return { syncMode: "all" };
+  try {
+    const memberships = await client.listMyMemberships();
+    const m = memberships.find((x) => x.companyUid === companyUid);
+    if (!m) return { syncMode: "all" };
+    const cfg = await client.getMembershipSyncConfig(m.membershipKey);
+    if (cfg.syncMode === "all") return { syncMode: "all" };
+    if (cfg.syncMode === "custom") {
+      const customPrefixes = (cfg.customPaths ?? []).map((p) =>
+        grantPathToPrefix(p, slug),
+      );
+      // A bare-everything entry ("" — e.g. a `*` path) collapses under
+      // `coalescePrefixes` (which drops empties) to "nothing", which would
+      // prune the whole tree. An everything-scope is semantically `all`.
+      if (customPrefixes.some((p) => p === "")) return { syncMode: "all" };
+      return { syncMode: "custom", prefixSet: coalescePrefixes(customPrefixes) };
+    }
+    // shared: scope to the caller's explicit grants. Real grant paths are
+    // inconsistent — full (`companies/<slug>/x/*`), slug-anchored
+    // (`<slug>/x/*`), company-relative (`x/*`), bare globs (`*`), and exact
+    // files all coexist in production — so each is normalized via
+    // `grantPathToPrefix` into a company-relative, startsWith-friendly prefix
+    // (the namespace the engine's `RemoteFile.key`s live in) before coalescing.
+    //
+    // SAFETY: if the client can't fetch grants, we must NOT fall through to an
+    // empty `shared` scope — that would tell the engine "nothing is in scope"
+    // and scope-shrink would prune every clean local file. Degrade to `all`
+    // instead. A genuinely-empty grant list (the method exists and returns
+    // []) is a real "nothing shared with me" and is allowed to narrow.
+    if (!client.listMyExplicitGrants) return { syncMode: "all" };
+    const grants = await client.listMyExplicitGrants(companyUid);
+    const sharedPrefixes = grants.map((g) => grantPathToPrefix(g.path, slug));
+    // A wildcard grant (`*`) normalizes to "" = everything. Since
+    // `coalescePrefixes` drops empties (collapsing "everything" to "nothing"),
+    // treat any such grant as full-access `all` rather than risk pruning.
+    if (sharedPrefixes.some((p) => p === "")) return { syncMode: "all" };
+    return { syncMode: "shared", prefixSet: coalescePrefixes(sharedPrefixes) };
+  } catch {
+    // Degrade to `all` — never prune on a resolution failure.
+    return { syncMode: "all" };
+  }
 }
 
 /**
@@ -1066,6 +1148,9 @@ export async function runRunner(
         newFilesCount: 0,
         filesExcludedByPolicy: 0,
         filesTombstoned: 0,
+        filesOutOfScope: 0,
+        scopeOrphansRemoved: 0,
+        scopeOrphansBlocked: 0,
       };
 
       // Push first so a subsequent pull doesn't overwrite files we were about
@@ -1166,11 +1251,24 @@ export async function runRunner(
       // whichever side `--on-conflict abort` just protected.
       if (doPull && !pushResult.aborted) {
         activePhase = "pull";
+        // US-005: resolve the membership's effective download scope so the
+        // pull only materializes in-scope keys (and prunes clean orphans when
+        // scope shrank). Personal-vault legs have no membership sync-config —
+        // they stay full-scope (`all`). Degrades to `all` on any error so a
+        // transient failure can't silently prune the tree.
+        const pullScope: PullScope =
+          target.personalMode === true
+            ? { syncMode: "all" }
+            : await resolvePullScope(client, target.uid, target.slug);
         pullResult = await syncFn({
           company: target.uid,
           vaultConfig,
           hqRoot: parsed.hqRoot,
           onConflict: parsed.onConflict,
+          syncMode: pullScope.syncMode,
+          ...(pullScope.prefixSet !== undefined
+            ? { prefixSet: pullScope.prefixSet }
+            : {}),
           ...(target.personalMode !== undefined ? { personalMode: target.personalMode } : {}),
           ...(target.journalSlug !== undefined ? { journalSlug: target.journalSlug } : {}),
           // Symmetric to the push side: for the personal slot, tell sync()
@@ -1275,6 +1373,11 @@ export async function runRunner(
         aborted,
         newFiles: pullResult.newFiles,
         newFilesCount: pullResult.newFilesCount,
+        // Scope-aware download counters (US-005). Pull-only — the push leg
+        // has no scope concept — so they pass through from `pullResult`.
+        filesOutOfScope: pullResult.filesOutOfScope,
+        scopeOrphansRemoved: pullResult.scopeOrphansRemoved,
+        scopeOrphansBlocked: pullResult.scopeOrphansBlocked,
       });
       for (const p of pullResult.conflictPaths) {
         allConflicts.push({ company: companyLabel, path: p, direction: "pull" });
@@ -1316,6 +1419,11 @@ export async function runRunner(
         aborted: true,
         newFiles: [],
         newFilesCount: 0,
+        // Mid-flight throw: no clean scope counts to report. 0 keeps the
+        // event shape stable (US-005).
+        filesOutOfScope: 0,
+        scopeOrphansRemoved: 0,
+        scopeOrphansBlocked: 0,
       });
       emit({
         type: "error",