@indigoai-us/hq-cloud 5.40.0 → 5.42.0

package/dist/qmd-reindex.test.js

@@ -0,0 +1,129 @@
+/**
+ * Unit tests for reindexAfterSync.
+ *
+ * The function shells out to the global `qmd` binary, so every test injects a
+ * fake `exec` that records the calls and returns canned results — no real qmd
+ * is invoked. We assert on the *sequence of qmd commands* the function would
+ * run, which is the contract that keeps a teammate's index fresh after sync.
+ */
+import { describe, it, expect } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { reindexAfterSync } from "./qmd-reindex.js";
+/** Build a fake exec that returns status 0 for everything and logs calls. */
+function fakeExec(opts) {
+    const calls = [];
+    const exec = (args) => {
+        calls.push(args);
+        if (opts?.failOn && args[0] === opts.failOn)
+            return { status: 1, stdout: "" };
+        if (args[0] === "collection" && args[1] === "list") {
+            return { status: 0, stdout: opts?.listStdout ?? "" };
+        }
+        return { status: 0, stdout: "" };
+    };
+    return { exec, calls };
+}
+describe("reindexAfterSync", () => {
+    it("no-ops when the path is not an HQ root", () => {
+        const { exec, calls } = fakeExec();
+        const r = reindexAfterSync("/tmp/not-hq", {
+            exec,
+            existsSync: () => false, // core/core.yaml absent
+        });
+        expect(r.qmdAvailable).toBe(false);
+        expect(calls).toHaveLength(0);
+    });
+    it("no-ops when qmd is unavailable (collection list errors)", () => {
+        const { exec, calls } = fakeExec({ failOn: "collection" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true, // core.yaml present
+        });
+        expect(r.qmdAvailable).toBe(false);
+        expect(r.updated).toBe(false);
+        // Only the availability probe ran, then bailed.
+        expect(calls).toEqual([["collection", "list"]]);
+    });
+    it("registers a missing company collection then runs an incremental update", () => {
+        const { exec, calls } = fakeExec({ listStdout: "Collections (1):\n\nHQ (qmd://HQ/)\n" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["acme"],
+            hasIndexableMarkdown: () => true,
+        });
+        expect(r.qmdAvailable).toBe(true);
+        expect(r.collectionsAdded).toEqual(["acme"]);
+        expect(r.updated).toBe(true);
+        expect(r.embedded).toBe(false);
+        // Expected command sequence: probe, add, context, update.
+        expect(calls).toEqual([
+            ["collection", "list"],
+            ["collection", "add", path.join("/hq", "companies", "acme", "knowledge"), "--name", "acme", "--mask", "**/*.md"],
+            ["context", "add", "qmd://acme", "Knowledge base for acme."],
+            ["update"],
+        ]);
+    });
+    it("skips collections that already exist", () => {
+        const { exec, calls } = fakeExec({ listStdout: "acme (qmd://acme/)\n" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["acme"],
+            hasIndexableMarkdown: () => true,
+        });
+        expect(r.collectionsAdded).toEqual([]);
+        // No `collection add` — straight to update.
+        expect(calls).toEqual([["collection", "list"], ["update"]]);
+    });
+    it("skips company dirs with no indexable markdown", () => {
+        const { exec, calls } = fakeExec({ listStdout: "" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => ["empty"],
+            hasIndexableMarkdown: () => false,
+        });
+        expect(r.collectionsAdded).toEqual([]);
+        expect(calls).toEqual([["collection", "list"], ["update"]]);
+    });
+    it("runs embed only when embed:true", () => {
+        const { exec, calls } = fakeExec({ listStdout: "" });
+        const r = reindexAfterSync("/hq", {
+            exec,
+            existsSync: () => true,
+            readCompanies: () => [],
+            embed: true,
+        });
+        expect(r.embedded).toBe(true);
+        expect(calls).toEqual([["collection", "list"], ["update"], ["embed"]]);
+    });
+    it("never throws even if exec misbehaves", () => {
+        const exec = () => {
+            throw new Error("boom");
+        };
+        expect(() => reindexAfterSync("/hq", { exec, existsSync: () => true })).not.toThrow();
+    });
+    it("hasIndexableMarkdown finds a real .md and ignores INDEX.md", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-qmd-test-"));
+        try {
+            const hq = path.join(dir, "hq");
+            const kdir = path.join(hq, "companies", "acme", "knowledge");
+            fs.mkdirSync(kdir, { recursive: true });
+            fs.mkdirSync(path.join(hq, "core"), { recursive: true });
+            fs.writeFileSync(path.join(hq, "core", "core.yaml"), "hqVersion: 1\n");
+            fs.writeFileSync(path.join(kdir, "INDEX.md"), "# index\n");
+            fs.writeFileSync(path.join(kdir, "note.md"), "# real\n");
+            const { exec, calls } = fakeExec({ listStdout: "" });
+            const r = reindexAfterSync(hq, { exec }); // real fs walk for md detection
+            expect(r.collectionsAdded).toEqual(["acme"]);
+            expect(calls.some((c) => c[0] === "collection" && c[1] === "add")).toBe(true);
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+//# sourceMappingURL=qmd-reindex.test.js.map

package/dist/qmd-reindex.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qmd-reindex.test.js","sourceRoot":"","sources":["../src/qmd-reindex.test.ts"],"names":[],"mappings":"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"}

package/dist/scope-shrink.d.ts

@@ -79,6 +79,24 @@ export declare class ScopeShrinkBlockedError extends Error {
     readonly code = "SCOPE_SHRINK_BLOCKED";
     constructor(companyUid: string, fromMode: PullRecord["syncMode"] | "unknown", toMode: PullRecord["syncMode"], dirty: OrphanClassification[], clean: OrphanClassification[]);
 }
+/**
+ * Structured error thrown when an AUTOMATIC scope shrink would prune more
+ * CLEAN local files than the configured safety cap in a single pull. This is
+ * the bulk-delete guard: a routine background sync should never silently
+ * delete a large local tree — whether from a deliberate-but-abrupt first
+ * narrow, a server bug returning an unexpectedly small grant set, or a
+ * mis-resolved scope. The operator runs the explicit `hq sync narrow` ritual
+ * (which has its own confirmation + dirty gate) or passes `--force-scope-shrink`
+ * to proceed. The engine never deletes anything when it throws this.
+ */
+export declare class ScopeShrinkLargePruneError extends Error {
+    readonly companyUid: string;
+    readonly toMode: PullRecord["syncMode"];
+    readonly cleanCount: number;
+    readonly cap: number;
+    readonly code = "SCOPE_SHRINK_LARGE_PRUNE";
+    constructor(companyUid: string, toMode: PullRecord["syncMode"], cleanCount: number, cap: number);
+}
 export interface ApplyScopeShrinkInput {
     journal: SyncJournal;
     plan: ScopeShrinkPlan;

package/dist/scope-shrink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-shrink.d.ts","sourceRoot":"","sources":["../src/scope-shrink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EACR,qBAAqB,GACrB,eAAe,GACf,YAAY,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,iDAAiD;IACjD,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,kDAAkD;IAClD,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,8CAA8C;IAC9C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,eAAe,CAoBjB;AA8ED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,SAAS;aAC5C,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC;aAC9B,KAAK,EAAE,oBAAoB,EAAE;aAC7B,KAAK,EAAE,oBAAoB,EAAE;IAN/C,QAAQ,CAAC,IAAI,0BAA0B;gBAErB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,SAAS,EAC5C,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,EAC9B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,KAAK,EAAE,oBAAoB,EAAE;CAShD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,QAAQ,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,GAC3B,sBAAsB,CA4BxB"}
+{"version":3,"file":"scope-shrink.d.ts","sourceRoot":"","sources":["../src/scope-shrink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EACR,qBAAqB,GACrB,eAAe,GACf,YAAY,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,iDAAiD;IACjD,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,kDAAkD;IAClD,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,8CAA8C;IAC9C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,yBAAyB,GAC/B,eAAe,CAoBjB;AA8ED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,UAAU,EAAE,MAAM;aAClB,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,SAAS;aAC5C,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC;aAC9B,KAAK,EAAE,oBAAoB,EAAE;aAC7B,KAAK,EAAE,oBAAoB,EAAE;IAN/C,QAAQ,CAAC,IAAI,0BAA0B;gBAErB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,SAAS,EAC5C,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,EAC9B,KAAK,EAAE,oBAAoB,EAAE,EAC7B,KAAK,EAAE,oBAAoB,EAAE;CAShD;AAED;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAGjC,UAAU,EAAE,MAAM;aAClB,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC;aAC9B,UAAU,EAAE,MAAM;aAClB,GAAG,EAAE,MAAM;IAL7B,QAAQ,CAAC,IAAI,8BAA8B;gBAEzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,EAC9B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM;CAU9B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,QAAQ,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,GAC3B,sBAAsB,CA4BxB"}

package/dist/scope-shrink.js

@@ -157,6 +157,34 @@ export class ScopeShrinkBlockedError extends Error {
         this.name = "ScopeShrinkBlockedError";
     }
 }
+/**
+ * Structured error thrown when an AUTOMATIC scope shrink would prune more
+ * CLEAN local files than the configured safety cap in a single pull. This is
+ * the bulk-delete guard: a routine background sync should never silently
+ * delete a large local tree — whether from a deliberate-but-abrupt first
+ * narrow, a server bug returning an unexpectedly small grant set, or a
+ * mis-resolved scope. The operator runs the explicit `hq sync narrow` ritual
+ * (which has its own confirmation + dirty gate) or passes `--force-scope-shrink`
+ * to proceed. The engine never deletes anything when it throws this.
+ */
+export class ScopeShrinkLargePruneError extends Error {
+    companyUid;
+    toMode;
+    cleanCount;
+    cap;
+    code = "SCOPE_SHRINK_LARGE_PRUNE";
+    constructor(companyUid, toMode, cleanCount, cap) {
+        super(`Refusing to auto-prune ${cleanCount} local file(s) for ${companyUid} ` +
+            `(${toMode} scope) in one sync — exceeds the safety cap of ${cap}. ` +
+            `Run \`hq sync narrow --apply\` to migrate with confirmation, raise ` +
+            `HQ_SYNC_MAX_AUTO_PRUNE, or pass --force-scope-shrink.`);
+        this.companyUid = companyUid;
+        this.toMode = toMode;
+        this.cleanCount = cleanCount;
+        this.cap = cap;
+        this.name = "ScopeShrinkLargePruneError";
+    }
+}
 /**
  * Apply a scope-shrink plan: delete clean orphans on disk + tombstone their
  * journal entries. With `forceScopeShrink: true`, dirty orphans are

package/dist/scope-shrink.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-shrink.js","sourceRoot":"","sources":["../src/scope-shrink.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scope-shrink.js","sourceRoot":"","sources":["../src/scope-shrink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoCtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAgC;IAEhC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IACnE,MAAM,OAAO,GAA2B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7D,IAAI,KAAK,CAAC,SAAS;YAAE,SAAS,CAAC,6BAA6B;QAC5D,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM;YAAE,SAAS;QACzC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC;YAAE,SAAS;QACtD,IAAI,cAAc,CAAC,OAAO,EAAE,gBAAgB,CAAC;YAAE,SAAS;QACxD,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO;QACL,OAAO;QACP,KAAK;QACL,KAAK;QACL,mBAAmB,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,cAAc,CACrB,OAAe,EACf,KAAmB,EACnB,MAAc;IAEd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,IAAc,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,YAAY;SAC1B,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,OAAO,GAAG,UAAU,GAAG,IAAI,EAAE,CAAC;QAC7D,wCAAwC;QACxC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,qBAAqB;SACnC,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,sDAAsD;IACtD,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,YAAY;SAC1B,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK;YACL,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,eAAe;SAC7B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAG9B;IACA;IACA;IACA;IACA;IANT,IAAI,GAAG,sBAAsB,CAAC;IACvC,YACkB,UAAkB,EAClB,QAA4C,EAC5C,MAA8B,EAC9B,KAA6B,EAC7B,KAA6B;QAE7C,KAAK,CACH,yBAAyB,UAAU,KAAK,QAAQ,MAAM,MAAM,KAAK;YAC/D,GAAG,KAAK,CAAC,MAAM,gDAAgD;YAC/D,gEAAgE,CACnE,CAAC;QAVc,eAAU,GAAV,UAAU,CAAQ;QAClB,aAAQ,GAAR,QAAQ,CAAoC;QAC5C,WAAM,GAAN,MAAM,CAAwB;QAC9B,UAAK,GAAL,KAAK,CAAwB;QAC7B,UAAK,GAAL,KAAK,CAAwB;QAO7C,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAGjC;IACA;IACA;IACA;IALT,IAAI,GAAG,0BAA0B,CAAC;IAC3C,YACkB,UAAkB,EAClB,MAA8B,EAC9B,UAAkB,EAClB,GAAW;QAE3B,KAAK,CACH,0BAA0B,UAAU,sBAAsB,UAAU,GAAG;YACrE,IAAI,MAAM,mDAAmD,GAAG,IAAI;YACpE,qEAAqE;YACrE,uDAAuD,CAC1D,CAAC;QAVc,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAAwB;QAC9B,eAAU,GAAV,UAAU,CAAQ;QAClB,QAAG,GAAH,GAAG,CAAQ;QAQ3B,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AAsBD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA4B;IAE5B,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,KAAK,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,cAAc,CAAC;IAC9C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,eAAe,GAAG,CAAC,CAAC;IAExB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;YACjD,IAAI,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC,CAAC,mDAAmD;QACvF,CAAC;QACD,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,YAAY,EAAE,CAAC;IACjB,CAAC;IAED,IAAI,gBAAgB,EAAE,CAAC;QACrB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,oEAAoE;YACpE,sEAAsE;YACtE,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7C,eAAe,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,CAAC;AAC3C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cloud",
-  "version": "5.40.0",
+  "version": "5.42.0",
   "description": "HQ by Indigo cloud sync engine — bidirectional S3 sync for mobile access",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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" });
+  });
+});