@indigoai-us/hq-cloud 6.2.2 → 6.2.4

package/src/remote-pull.test.ts

@@ -594,6 +594,9 @@ describe("pullCompany (engine orchestrator)", () => {
           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: [
@@ -651,12 +654,14 @@ describe("pullCompany (engine orchestrator)", () => {
           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: [
@@ -711,6 +716,7 @@ describe("pullCompany (engine orchestrator)", () => {
           size: 5,
           syncedAt: new Date(Date.now() - 60_000).toISOString(),
           direction: "down",
+          createdBySub: "uploader-sub", // foreign author — eligible for shrink
         },
       },
     };
@@ -741,6 +747,118 @@ describe("pullCompany (engine orchestrator)", () => {
     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("GC's expired tombstones at the start of every leg", async () => {
     const old = new Date(
       Date.now() - 31 * 24 * 60 * 60 * 1000,

package/src/remote-pull.ts

@@ -368,6 +368,13 @@ export interface PullCompanyInput {
   conflictKeys?: Set<string>;
   /** Honor the operator override on dirty orphans (US-005 contract). */
   forceScopeShrink?: boolean;
+  /**
+   * The caller's own Cognito `sub` for the scope-shrink authorship guard — a
+   * scope shrink never prunes content the caller authored. Defaults to the
+   * cached session sub (`resolveCallerSubFromCache()`); pass explicitly when
+   * the runner already decoded its idToken claims.
+   */
+  callerSub?: string;
   /** Listing override hook — see `ListRemoteForScopeInput.listFn`. */
   listFn?: ListRemoteForScopeInput["listFn"];
   vendForBatchFn?: ListRemoteForScopeInput["vendForBatchFn"];
@@ -432,6 +439,11 @@ export async function pullCompany(
     hqRoot: input.hqRoot,
     lastPrefixSet,
     currentPrefixSet: input.scope.prefixSet,
+    callerSub: input.callerSub,
+    // Background runner pull: protect the caller's own work and don't make a
+    // destructive guess about unknown-author (legacy) orphans. The explicit
+    // `hq sync narrow` ritual is the confirmed path that opts out of this.
+    protectUnknownAuthors: true,
   });
 
   let scopeShrinkApplied: ApplyScopeShrinkResult | null = null;

package/src/scope-shrink.test.ts

@@ -239,6 +239,134 @@ describe("buildScopeShrinkPlan", () => {
     });
     expect(plan.orphans).toEqual([]);
   });
+
+  // ── Authorship guard ──────────────────────────────────────────────────────
+  // Sync mode decides whether you mirror OTHER people's files; it must never
+  // orphan content the caller authored. Owners hold their whole vault by
+  // role-bypass, so without this guard a `shared`/`custom` scope would treat
+  // their own un-granted work as "someone else's file" and prune it.
+
+  it("never orphans a file the caller authored, even out of scope", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "companies/indigo/projects/mine.md": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-05-01T00:00:00.000Z",
+          direction: "down",
+          createdBySub: "sub-corey",
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      lastPrefixSet: ["companies/indigo/"],
+      currentPrefixSet: ["companies/indigo/meetings/"],
+      callerSub: "sub-corey",
+    });
+    expect(plan.orphans).toEqual([]);
+    expect(plan.scopeChangeDetected).toBe(false);
+  });
+
+  it("orphans a file authored by someone else (mode stops mirroring others' files)", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "companies/indigo/projects/theirs.md": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-05-01T00:00:00.000Z",
+          direction: "down",
+          createdBySub: "sub-jacob",
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      lastPrefixSet: ["companies/indigo/"],
+      currentPrefixSet: ["companies/indigo/meetings/"],
+      callerSub: "sub-corey",
+      protectUnknownAuthors: true,
+    });
+    expect(plan.orphans.map((o) => o.path)).toEqual([
+      "companies/indigo/projects/theirs.md",
+    ]);
+  });
+
+  it("retains an unknown-author orphan when protectUnknownAuthors is set (conservative auto path)", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "companies/indigo/projects/legacy.md": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-05-01T00:00:00.000Z",
+          direction: "down",
+          // no createdBySub — a legacy entry predating author stamping
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      lastPrefixSet: ["companies/indigo/"],
+      currentPrefixSet: ["companies/indigo/meetings/"],
+      callerSub: "sub-corey",
+      protectUnknownAuthors: true,
+    });
+    expect(plan.orphans).toEqual([]);
+  });
+
+  it("prunes an unknown-author orphan when protectUnknownAuthors is off (explicit narrow path)", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "companies/indigo/projects/legacy.md": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-05-01T00:00:00.000Z",
+          direction: "down",
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      lastPrefixSet: ["companies/indigo/"],
+      currentPrefixSet: ["companies/indigo/meetings/"],
+      callerSub: "sub-corey",
+    });
+    expect(plan.orphans.map((o) => o.path)).toEqual([
+      "companies/indigo/projects/legacy.md",
+    ]);
+  });
+
+  it("ignores authorship when no callerSub is supplied (back-compat)", () => {
+    const journal: SyncJournal = {
+      ...emptyJournal(),
+      files: {
+        "companies/indigo/projects/mine.md": {
+          hash: "h",
+          size: 1,
+          syncedAt: "2026-05-01T00:00:00.000Z",
+          direction: "down",
+          createdBySub: "sub-corey",
+        },
+      },
+    };
+    const plan = buildScopeShrinkPlan({
+      journal,
+      hqRoot,
+      lastPrefixSet: ["companies/indigo/"],
+      currentPrefixSet: ["companies/indigo/meetings/"],
+    });
+    expect(plan.orphans.map((o) => o.path)).toEqual([
+      "companies/indigo/projects/mine.md",
+    ]);
+  });
 });
 
 describe("applyScopeShrink", () => {

package/src/scope-shrink.ts

@@ -62,6 +62,26 @@ export interface BuildScopeShrinkPlanInput {
   lastPrefixSet: string[];
   /** Coalesced prefixes the CURRENT pull will use. */
   currentPrefixSet: string[];
+  /**
+   * The caller's own Cognito `sub`. When set, a file the caller authored
+   * (`entry.createdBySub === callerSub`) is NEVER orphaned by a scope shrink —
+   * regardless of mode. This is the core of the authorship contract: sync mode
+   * governs whether you mirror *other people's* files; it must never disown
+   * your own work. Owners hold their whole vault by role-bypass, so without
+   * this guard a `shared`/`custom` scope would treat their own un-granted
+   * content as "someone else's file I happen to see" and prune it.
+   */
+  callerSub?: string;
+  /**
+   * When `true`, an orphan whose authorship is unknown (`createdBySub`
+   * undefined — a legacy entry predating author stamping, or an object
+   * uploaded without author metadata) is also retained rather than pruned.
+   * The automatic background pull sets this so a routine sync never makes a
+   * destructive guess about pre-stamp content; the explicit `hq sync narrow`
+   * ritual (which carries its own confirmation + dirty gate) leaves it off so
+   * a deliberately-confirmed narrow can still reclaim legacy files.
+   */
+  protectUnknownAuthors?: boolean;
 }
 
 /**
@@ -84,6 +104,7 @@ export function buildScopeShrinkPlan(
   input: BuildScopeShrinkPlanInput,
 ): ScopeShrinkPlan {
   const { journal, hqRoot, lastPrefixSet, currentPrefixSet } = input;
+  const { callerSub, protectUnknownAuthors } = input;
   const orphans: OrphanClassification[] = [];
 
   for (const [relPath, entry] of Object.entries(journal.files)) {
@@ -91,6 +112,14 @@ export function buildScopeShrinkPlan(
     if (entry.direction !== "down") continue;
     if (!isCoveredByAny(relPath, lastPrefixSet)) continue;
     if (isCoveredByAny(relPath, currentPrefixSet)) continue;
+    // Authorship guard: sync mode decides whether you mirror OTHER people's
+    // files — it must never disown your own. A file the caller authored is
+    // sacred and never orphaned, even out of the current prefix scope. When
+    // `protectUnknownAuthors` is set (the automatic pull path), a legacy
+    // entry with no recorded author is also retained — a routine background
+    // sync should never make a destructive guess about pre-stamp content.
+    if (callerSub && entry.createdBySub === callerSub) continue;
+    if (protectUnknownAuthors && entry.createdBySub === undefined) continue;
     orphans.push(classifyOrphan(relPath, entry, hqRoot));
   }
 

package/src/types.ts

@@ -26,6 +26,18 @@ export interface JournalEntry {
   size: number;
   syncedAt: string;
   direction: "up" | "down";
+  /**
+   * Cognito `sub` of the file's author, captured from the object's
+   * `created-by-sub` S3 user-metadata at download time (zero extra network —
+   * the GET response already carries it). Powers the scope-shrink authorship
+   * guard: a scope shrink must never orphan content the caller authored, so
+   * sync mode only ever governs whether you ALSO mirror *other people's*
+   * files. Optional for backwards compatibility — entries written before this
+   * field existed (or uploaded without author metadata) leave it `undefined`,
+   * which the automatic prune path treats conservatively (never auto-delete an
+   * unknown-author orphan).
+   */
+  createdBySub?: string;
   /**
    * S3 ETag of the remote object as of last successful sync, normalized (no
    * surrounding quotes). Optional for backwards compatibility: entries