@indigoai-us/hq-cloud 5.41.0 → 5.42.0

package/src/cli/sync-scope.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Unit tests for scope-aware download (US-005 wiring into `sync()`).
+ *
+ * Covers the contract added when `syncMode` / `prefixSet` were threaded
+ * through `computePullPlan` + the scope-shrink pass:
+ *
+ *   - `all`    → no filtering (regression guard lives in sync.test.ts).
+ *   - `shared` → only keys covered by `prefixSet` download; the rest are
+ *                classified `skip-out-of-scope` (NOT downloaded).
+ *   - `custom` → same mechanism, driven by the explicit path list.
+ *   - Idempotency → a second `shared` pull downloads nothing and removes
+ *                   nothing (the PullRecord makes scope-change a no-op).
+ *   - Scope shrink → narrowing `all → shared` prunes the now-out-of-scope
+ *                    CLEAN local orphan; a DIRTY orphan aborts with
+ *                    `ScopeShrinkBlockedError` unless `forceScopeShrink`.
+ *
+ * The security contract (this filter is footprint-only, never an authz
+ * boundary) is asserted indirectly: out-of-scope keys are still LISTED and
+ * accessible — the engine simply chooses not to materialize them.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { clearContextCache } from "../context.js";
+import type { VaultServiceConfig } from "../types.js";
+
+// Mutable remote-file list so each test controls what the vault returns.
+const REMOTE: { current: Array<{ key: string; size: number; lastModified: Date; etag: string }> } = {
+  current: [
+    { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
+    { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
+  ],
+};
+
+vi.mock("../s3.js", async () => {
+  const innerFs = await import("fs");
+  const innerPath = await import("path");
+  const { vi: innerVi } = await import("vitest");
+  return {
+    uploadFile: innerVi.fn().mockResolvedValue(undefined),
+    downloadFile: innerVi
+      .fn()
+      .mockImplementation(async (_ctx: unknown, key: string, localPath: string) => {
+        const dir = innerPath.dirname(localPath);
+        if (!innerFs.existsSync(dir)) innerFs.mkdirSync(dir, { recursive: true });
+        // Deterministic per-key body so re-downloads produce a stable hash.
+        innerFs.writeFileSync(localPath, `mock:${key}`);
+        return { metadata: {} };
+      }),
+    listRemoteFiles: innerVi.fn().mockImplementation(async () => REMOTE.current),
+    deleteRemoteFile: innerVi.fn().mockResolvedValue(undefined),
+    // HEAD returns metadata (object exists) for any key still in REMOTE,
+    // null otherwise — mirrors the real bucket so the tombstone HEAD-verify
+    // pass behaves correctly for out-of-scope (still-present) keys.
+    headRemoteFile: innerVi.fn().mockImplementation(async (_ctx: unknown, key: string) => {
+      const hit = REMOTE.current.find((r) => r.key === key);
+      return hit ? { metadata: {}, size: hit.size, etag: hit.etag } : null;
+    }),
+  };
+});
+
+import { sync } from "./sync.js";
+import {
+  ScopeShrinkBlockedError,
+  ScopeShrinkLargePruneError,
+} from "../scope-shrink.js";
+
+const mockConfig: VaultServiceConfig = {
+  apiUrl: "https://vault-api.test",
+  authToken: "test-jwt-token",
+  region: "us-east-1",
+};
+
+const mockEntity = {
+  uid: "cmp_01ABCDEF",
+  slug: "acme",
+  bucketName: "hq-vault-acme-123",
+  status: "active",
+};
+
+const mockVendResponse = {
+  credentials: {
+    accessKeyId: "ASIA_TEST_KEY",
+    secretAccessKey: "test-secret",
+    sessionToken: "test-session-token",
+    expiration: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+  },
+  expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
+};
+
+function setupFetchMock() {
+  const fetchMock = vi.fn().mockImplementation(async (url: string) => {
+    const urlStr = String(url);
+    if (urlStr.includes("/entity/check-slug/me")) {
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
+        text: async () => "",
+      };
+    }
+    if (urlStr.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(urlStr)) {
+      return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
+    }
+    if (urlStr.includes("/sts/vend")) {
+      return { ok: true, status: 200, json: async () => mockVendResponse, text: async () => "" };
+    }
+    return { ok: false, status: 404, text: async () => "Not found" };
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+describe("sync — scope-aware download (US-005)", () => {
+  let tmpDir: string;
+  let stateDir: string;
+  const companyRel = (p: string) => path.join(tmpDir, "companies", "acme", p);
+
+  beforeEach(() => {
+    clearContextCache();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-sync-scope-"));
+    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-state-scope-"));
+    process.env.HQ_STATE_DIR = stateDir;
+    // Reset the remote list every test (a prior test may have mutated it).
+    REMOTE.current = [
+      { key: "docs/handoff.md", size: 42, lastModified: new Date(), etag: '"abc123"' },
+      { key: "knowledge/readme.md", size: 100, lastModified: new Date(), etag: '"def456"' },
+    ];
+    setupFetchMock();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.clearAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(stateDir, { recursive: true, force: true });
+    delete process.env.HQ_STATE_DIR;
+  });
+
+  it("shared mode downloads only keys covered by prefixSet; rest are skip-out-of-scope", async () => {
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+    });
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesOutOfScope).toBe(1);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+    // docs/handoff.md is out of scope — never materialized.
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
+  });
+
+  it("custom mode behaves like shared, driven by the explicit prefix list", async () => {
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "custom",
+      prefixSet: ["docs/"],
+    });
+
+    expect(result.filesDownloaded).toBe(1);
+    expect(result.filesOutOfScope).toBe(1);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
+  });
+
+  it("shared mode with empty prefixSet downloads nothing", async () => {
+    const result = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: [],
+    });
+
+    expect(result.filesDownloaded).toBe(0);
+    expect(result.filesOutOfScope).toBe(2);
+  });
+
+  it("is idempotent: a second shared pull downloads and removes nothing", async () => {
+    const opts = {
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared" as const,
+      prefixSet: ["knowledge/"],
+    };
+    const first = await sync(opts);
+    expect(first.filesDownloaded).toBe(1);
+
+    const second = await sync(opts);
+    expect(second.filesDownloaded).toBe(0);
+    expect(second.scopeOrphansRemoved).toBe(0);
+    expect(second.scopeOrphansBlocked).toBe(0);
+    // knowledge file still present; nothing churned.
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+  });
+
+  it("scope shrink (all → shared) prunes the clean out-of-scope orphan", async () => {
+    // First pull EVERYTHING under all-mode.
+    const all = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "all",
+    });
+    expect(all.filesDownloaded).toBe(2);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+
+    // Narrow to shared/knowledge → docs/handoff.md is now a clean orphan.
+    const shared = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+    });
+    expect(shared.scopeOrphansRemoved).toBe(1);
+    expect(shared.scopeOrphansBlocked).toBe(0);
+    // The clean orphan was pruned; the in-scope file stays.
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
+    expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+  });
+
+  it("refuses a bulk auto-prune over the safety cap, then proceeds when forced", async () => {
+    // Pull both files under all-mode, then narrow to a scope covering neither
+    // → 2 clean orphans. With the cap set to 1, the auto-prune is refused.
+    await sync({ company: "acme", vaultConfig: mockConfig, hqRoot: tmpDir, syncMode: "all" });
+
+    // Narrow to a scope covering neither file → 2 clean orphans; cap at 1.
+    process.env.HQ_SYNC_MAX_AUTO_PRUNE = "1";
+    try {
+      await expect(
+        sync({
+          company: "acme",
+          vaultConfig: mockConfig,
+          hqRoot: tmpDir,
+          syncMode: "shared",
+          prefixSet: ["nonexistent/"],
+        }),
+      ).rejects.toBeInstanceOf(ScopeShrinkLargePruneError);
+      // Nothing deleted on the refused run.
+      expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(true);
+
+      // Forced: the prune proceeds despite the cap.
+      const forced = await sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "shared",
+        prefixSet: ["nonexistent/"],
+        forceScopeShrink: true,
+      });
+      expect(forced.scopeOrphansRemoved).toBe(2);
+      expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(false);
+      expect(fs.existsSync(companyRel("knowledge/readme.md"))).toBe(false);
+    } finally {
+      delete process.env.HQ_SYNC_MAX_AUTO_PRUNE;
+    }
+  });
+
+  it("scope shrink aborts on a DIRTY orphan unless forceScopeShrink is set", async () => {
+    await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "all",
+    });
+    // Locally modify the soon-to-be-orphan so it's dirty (hash mismatch).
+    fs.writeFileSync(companyRel("docs/handoff.md"), "LOCAL EDIT — do not delete");
+
+    // Default: abort with the structured error; the dirty file is untouched.
+    await expect(
+      sync({
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        syncMode: "shared",
+        prefixSet: ["knowledge/"],
+      }),
+    ).rejects.toBeInstanceOf(ScopeShrinkBlockedError);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+    expect(fs.readFileSync(companyRel("docs/handoff.md"), "utf-8")).toBe(
+      "LOCAL EDIT — do not delete",
+    );
+
+    // With force: the leg proceeds, the dirty file is LEFT ON DISK, only its
+    // journal entry is tombstoned.
+    const forced = await sync({
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      syncMode: "shared",
+      prefixSet: ["knowledge/"],
+      forceScopeShrink: true,
+    });
+    expect(forced.scopeOrphansBlocked).toBe(1);
+    expect(fs.existsSync(companyRel("docs/handoff.md"))).toBe(true);
+  });
+});

package/src/cli/sync.ts

@@ -8,6 +8,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import type { VaultServiceConfig, SyncJournal } from "../types.js";
+import type { SyncMode } from "../vault-client.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
 import { downloadFile, listRemoteFiles, headRemoteFile } from "../s3.js";
 import type { RemoteFile } from "../s3.js";
@@ -20,7 +21,19 @@ import {
   removeEntry,
   getEntry,
   normalizeEtag,
+  migrateToV2,
+  gcTombstones,
+  lastPullRecord,
+  appendPullRecord,
+  generatePullId,
 } from "../journal.js";
+import {
+  buildScopeShrinkPlan,
+  applyScopeShrink,
+  ScopeShrinkBlockedError,
+  ScopeShrinkLargePruneError,
+} from "../scope-shrink.js";
+import { coalescePrefixes, isCoveredByAny } from "../prefix-coalesce.js";
 import { createIgnoreFilter } from "../ignore.js";
 import { isEphemeralPath } from "./share.js";
 import { resolveConflict } from "./conflict.js";
@@ -255,6 +268,40 @@ export interface SyncOptions {
    * TS runner and Rust first-push share idempotency state.
    */
   journalSlug?: string;
+  /**
+   * Effective sync mode for this leg (US-005 wiring). Defaults to `"all"`
+   * when absent, preserving the legacy full-bucket pull. The runner resolves
+   * this from the membership's sync-config (`getMembershipSyncConfig`).
+   *
+   * SECURITY NOTE: this is a footprint/UX filter, NOT an authorization
+   * boundary. The security boundary is the server (STS credential scope +
+   * ACL). An owner's STS is wide (role-bypass), so this client-side scope is
+   * what makes selective download durable for owners — but it never grants
+   * access beyond what STS already permits.
+   */
+  syncMode?: SyncMode;
+  /**
+   * Coalesced, COMPANY-RELATIVE prefixes the current pull is scoped to when
+   * `syncMode` is `"shared"` or `"custom"` (same namespace as `RemoteFile.key`
+   * and the per-slug journal keys — e.g. `"knowledge/"`, `"projects/x/"`).
+   * Ignored when `syncMode` is `"all"`. The runner derives this from the
+   * caller's explicit grants (`shared`) or `customPaths` (`custom`) and is
+   * responsible for normalizing into the company-relative namespace.
+   *
+   * A `shared` leg with an empty/undefined `prefixSet` means "nothing is
+   * shared with me" → download nothing. The runner MUST fall back to `"all"`
+   * (not empty `"shared"`) on any grant-resolution error, so a transient
+   * failure can never silently prune the local tree.
+   */
+  prefixSet?: string[];
+  /**
+   * When the effective scope shrinks relative to the last pull and the shrink
+   * would orphan locally-modified ("dirty") files, `sync()` aborts with a
+   * `ScopeShrinkBlockedError` by default. Set `true` to proceed anyway:
+   * dirty files are LEFT ON DISK and only their journal entries are
+   * tombstoned. Mirrors `hq sync narrow --force`.
+   */
+  forceScopeShrink?: boolean;
 }
 
 export interface SyncResult {
@@ -297,6 +344,42 @@ export interface SyncResult {
    * disappeared from the remote.
    */
   filesTombstoned: number;
+  /**
+   * Count of remote keys NOT downloaded this run because they fall outside
+   * the effective `syncMode` scope (US-005). Always 0 in `all` mode. Distinct
+   * from `filesSkipped` (which measures "unchanged on this run") so consumers
+   * can render a "N outside your sync scope" line. The matching local cleanup
+   * of previously-downloaded-now-out-of-scope files is reported via
+   * `scopeOrphansRemoved`.
+   */
+  filesOutOfScope: number;
+  /**
+   * Clean local orphans deleted this run because a scope shrink moved them
+   * outside the effective scope (US-005). 0 when scope did not shrink.
+   */
+  scopeOrphansRemoved: number;
+  /**
+   * Dirty (locally-modified) orphans that a scope shrink would have pruned.
+   * When `forceScopeShrink` is false these are surfaced via a thrown
+   * `ScopeShrinkBlockedError` and the leg never reaches this result; when
+   * true they are left on disk and tombstoned, and counted here.
+   */
+  scopeOrphansBlocked: number;
+}
+
+/**
+ * Resolve the auto-prune safety cap (US-005 bulk-delete guard). An automatic
+ * scope shrink that would delete more than this many CLEAN local files in one
+ * pull is refused with `ScopeShrinkLargePruneError`. Default 100; `0` (or a
+ * non-positive / unparseable value) disables the cap (unlimited). Override via
+ * `HQ_SYNC_MAX_AUTO_PRUNE`.
+ */
+export function resolveAutoPruneCap(): number {
+  const raw = process.env.HQ_SYNC_MAX_AUTO_PRUNE;
+  if (raw === undefined || raw === "") return 100;
+  const parsed = Number.parseInt(raw, 10);
+  // NaN or negative → treat as "unlimited" (0) rather than silently capping.
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
 }
 
 /**
@@ -330,13 +413,32 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     : path.join(hqRoot, "companies", ctx.slug);
   const shouldSync = createIgnoreFilter(hqRoot);
   const journalSlug = options.journalSlug ?? ctx.slug;
-  const journal = readJournal(journalSlug);
+  const startedAt = new Date().toISOString();
+  // Migrate v1 → v2 in place so the scope-shrink / pull-record machinery has
+  // its fields, and GC any tombstones past the 30-day retention window before
+  // we re-evaluate orphans (so a long-pruned path can re-download cleanly).
+  const journal = migrateToV2(readJournal(journalSlug));
+  gcTombstones(journal, Date.now());
+
+  // ── Effective download scope (US-005) ─────────────────────────────────────
+  // `all`  → prefixSet `[""]`, which `isCoveredByAny` treats as "covers
+  //          everything" — so the download filter and the scope-shrink
+  //          comparison both become no-ops, preserving legacy full-bucket
+  //          behavior bit-for-bit.
+  // `shared`/`custom` → the coalesced, company-relative prefix set the runner
+  //          resolved. An empty set means "nothing in scope" → download
+  //          nothing (the runner falls back to `all` on resolution errors, so
+  //          empty here is an intentional "nothing shared", never a failure).
+  const syncMode: SyncMode = options.syncMode ?? "all";
+  const currentPrefixSet =
+    syncMode === "all" ? [""] : coalescePrefixes(options.prefixSet ?? []);
 
   let filesDownloaded = 0;
   let bytesDownloaded = 0;
   let filesSkipped = 0;
   let conflicts = 0;
   let filesTombstoned = 0;
+  let filesOutOfScope = 0;
   const conflictPaths: string[] = [];
 
   // List all remote files (IAM session policy filters at the AWS layer)
@@ -353,6 +455,7 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     options.personalMode === true,
     options.includeLocalCompanies === true,
     options.teamSyncedSlugs ?? null,
+    currentPrefixSet,
   );
 
   emit({
@@ -367,6 +470,83 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     filesToDelete: 0,
   });
 
+  // ── Scope-shrink cleanup (US-005) ─────────────────────────────────────────
+  // If the effective scope narrowed since the last pull, files that were
+  // pulled under the old scope but fall outside the new one are orphans. We
+  // delete only CLEAN orphans (provably unchanged since last sync); dirty
+  // (locally-modified) orphans are sacred. By default a dirty orphan aborts
+  // the leg with a structured error the CLI renders; `forceScopeShrink` keeps
+  // dirty files on disk and only tombstones their journal entries.
+  //
+  // `companyRoot` is passed as the module's `hqRoot` so its `path.join(root,
+  // key)` resolves company-relative journal keys correctly (the scope-shrink
+  // module is namespace-agnostic — root + keys + prefixSet must simply agree).
+  //
+  // Note: this is the durable selective-download fix for OWNERS. An owner's
+  // STS is wide (role-bypass), so the remote LIST returns everything and the
+  // AWS layer never narrows the pull. This client-side shrink is what makes
+  // `hq sync mode shared` actually stick across re-syncs for an owner.
+  const lastRecord = lastPullRecord(journal, ctx.uid);
+  // A missing record, or a v1-migrated record with an empty prefixSet, means
+  // "no recorded scope" → treat the last scope as full-bucket `all` (`[""]`),
+  // per the PullRecord.prefixSet contract in types.ts.
+  const lastPrefixSet =
+    lastRecord && lastRecord.prefixSet.length > 0
+      ? lastRecord.prefixSet
+      : [""];
+  const shrinkPlan = buildScopeShrinkPlan({
+    journal,
+    hqRoot: companyRoot,
+    lastPrefixSet,
+    currentPrefixSet,
+  });
+  if (shrinkPlan.dirty.length > 0 && options.forceScopeShrink !== true) {
+    throw new ScopeShrinkBlockedError(
+      ctx.uid,
+      lastRecord?.syncMode ?? "unknown",
+      syncMode,
+      shrinkPlan.dirty,
+      shrinkPlan.clean,
+    );
+  }
+  // Bulk-delete guard: refuse to auto-prune more than the safety cap of CLEAN
+  // files in a single background sync. A deliberate large narrow goes through
+  // `hq sync narrow --apply` (its own confirmation), and `--force-scope-shrink`
+  // (or raising HQ_SYNC_MAX_AUTO_PRUNE) overrides. Cap of 0 = unlimited (opt
+  // out). The engine deletes nothing when it throws here.
+  const autoPruneCap = resolveAutoPruneCap();
+  if (
+    options.forceScopeShrink !== true &&
+    autoPruneCap > 0 &&
+    shrinkPlan.clean.length > autoPruneCap
+  ) {
+    throw new ScopeShrinkLargePruneError(
+      ctx.uid,
+      syncMode,
+      shrinkPlan.clean.length,
+      autoPruneCap,
+    );
+  }
+  const shrinkResult = applyScopeShrink({
+    journal,
+    plan: shrinkPlan,
+    hqRoot: companyRoot,
+    forceScopeShrink: options.forceScopeShrink === true,
+    reason: "scope_shrink",
+  });
+  // Surface each removed clean orphan as a `deleted` progress event so the
+  // menubar stream renders the prune the same way it renders a cross-machine
+  // tombstone (the Rust parser already handles `deleted: true`).
+  for (const orphan of shrinkPlan.clean) {
+    emit({
+      type: "progress",
+      path: orphan.path,
+      bytes: 0,
+      deleted: true,
+      message: "scope-narrowed (removed local copy outside sync scope)",
+    });
+  }
+
   // Stage 2: execute the plan. Per-item branching mirrors the pre-refactor
   // inline loop; the only structural change is that classification has
   // already happened (so `localHash` is reused instead of re-hashing).
@@ -419,6 +599,13 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
       // run", not a catch-all for everything we didn't download.
       continue;
     }
+    if (item.action === "skip-out-of-scope") {
+      // Outside the effective `syncMode` scope (US-005). Counted on its own
+      // axis so `filesSkipped` keeps meaning "unchanged on this run" — these
+      // are "deliberately not downloaded because of your sync scope".
+      filesOutOfScope++;
+      continue;
+    }
 
     if (item.action === "download") {
       downloadItems.push(item);
@@ -515,6 +702,12 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
           // 0 so the field shape stays stable for consumers that
           // destructure it.
           filesTombstoned: 0,
+          // Scope-shrink ran before execution, so its counts are real even on
+          // a conflict abort. `filesOutOfScope` reflects how far the serial
+          // pass got before the abort; that's acceptable for an abort result.
+          filesOutOfScope,
+          scopeOrphansRemoved: shrinkResult.cleanRemoved,
+          scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
         };
         break;
       }
@@ -841,6 +1034,22 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     });
   }
 
+  // Record this pull's boundary (US-005) so the NEXT pull can diff its scope
+  // against ours and detect a shrink. Append before the journal write so it
+  // persists. `prefixSet` is stored in the same company-relative namespace as
+  // the journal keys; `all` mode records `[""]` (covers everything).
+  appendPullRecord(journal, {
+    pullId: generatePullId(),
+    companyUid: ctx.uid,
+    startedAt,
+    completedAt: new Date().toISOString(),
+    syncMode,
+    prefixSet: currentPrefixSet,
+    scopeChangeDetected: shrinkPlan.scopeChangeDetected,
+    orphansRemoved: shrinkResult.cleanRemoved,
+    orphansBlocked: shrinkResult.dirtyTombstoned,
+  });
+
   // Stamp lastSync on every successful run so the menubar's "Last sync · X ago"
   // ticks even when nothing transferred. updateEntry only fires on actual
   // downloads; without this, a no-op sync leaves lastSync at the time of the
@@ -859,6 +1068,9 @@ export async function sync(options: SyncOptions): Promise<SyncResult> {
     newFilesCount: plan.newFilesCount,
     filesExcludedByPolicy: plan.filesExcludedByPolicy,
     filesTombstoned,
+    filesOutOfScope,
+    scopeOrphansRemoved: shrinkResult.cleanRemoved,
+    scopeOrphansBlocked: shrinkResult.dirtyTombstoned,
   };
 }
 
@@ -911,6 +1123,10 @@ type PullPlanItem =
   // refused to upload these since 5.33.0; the pull walker now refuses to
   // download them so legacy litter in cloud staging drains naturally.
   | { action: "skip-excluded-policy"; remoteFile: RemoteFile; localPath: string }
+  // Remote keys outside the effective `syncMode` scope (US-005). Present in
+  // the remote LIST (and accessible per STS) but deliberately not downloaded
+  // because the membership's sync scope doesn't cover them.
+  | { action: "skip-out-of-scope"; remoteFile: RemoteFile; localPath: string }
   | {
       action: "conflict";
       remoteFile: RemoteFile;
@@ -945,6 +1161,8 @@ interface PullPlan {
   newFilesCount: number;
   /** Count of remote keys refused by ephemeral-mirror policy. */
   filesExcludedByPolicy: number;
+  /** Count of remote keys skipped because they fall outside the sync scope. */
+  filesOutOfScope: number;
   /**
    * Journal-known keys missing from the remote LIST. The executor will
    * apply each as a local delete (file or symlink) + journal removal,
@@ -973,6 +1191,10 @@ function computePullPlan(
   personalMode: boolean,
   includeLocalCompanies: boolean,
   teamSyncedSlugs: ReadonlySet<string> | null,
+  // Coalesced, company-relative prefixes the pull is scoped to (US-005).
+  // `[""]` (the `all`-mode value) covers everything via `isCoveredByAny`, so
+  // the scope filter below becomes a no-op and legacy behavior is preserved.
+  prefixSet: string[],
 ): PullPlan {
   const items: PullPlanItem[] = [];
 
@@ -1017,6 +1239,17 @@ function computePullPlan(
       }
     }
 
+    // Scope filter (US-005). Keys outside the effective `syncMode` prefix set
+    // are not downloaded. `prefixSet` is `[""]` in `all` mode, which
+    // `isCoveredByAny` treats as covering everything — so this is a no-op for
+    // `all` and preserves the legacy full-bucket pull bit-for-bit. The
+    // previously-downloaded counterparts of these keys (if scope just shrank)
+    // are pruned separately by the scope-shrink pass in `sync()`.
+    if (!isCoveredByAny(remoteFile.key, prefixSet)) {
+      items.push({ action: "skip-out-of-scope", remoteFile, localPath });
+      continue;
+    }
+
     // LIST gives us no kind signal for the remote object — we don't
     // know whether this key is a regular file or a symlink record
     // until we either HEAD it (expensive — N extra calls per pull) or
@@ -1175,6 +1408,7 @@ function computePullPlan(
   let filesToSkip = 0;
   let filesToConflict = 0;
   let filesExcludedByPolicy = 0;
+  let filesOutOfScope = 0;
   const newFiles: Array<{ path: string; bytes: number }> = [];
   for (const item of items) {
     if (item.action === "download") {
@@ -1191,6 +1425,10 @@ function computePullPlan(
       // distinct class surfaced via filesExcludedByPolicy so consumers
       // can render a "N refused by policy" line independently of the
       // generic "N unchanged" tally.
+    } else if (item.action === "skip-out-of-scope") {
+      // Out-of-scope items get their own axis too, mirroring excluded-policy:
+      // they're "deliberately not downloaded (sync scope)", not "unchanged".
+      filesOutOfScope++;
     } else {
       filesToSkip++;
     }
@@ -1294,6 +1532,7 @@ function computePullPlan(
     newFiles,
     newFilesCount: newFiles.length,
     filesExcludedByPolicy,
+    filesOutOfScope,
     tombstones,
   };
 }

package/src/index.ts

@@ -46,6 +46,7 @@ export {
 export {
   coalescePrefixes,
   isCoveredByAny,
+  grantPathToPrefix,
 } from "./prefix-coalesce.js";
 
 // Scope-shrink detection + application (US-005)