@indigoai-us/hq-cloud 5.22.0 → 5.24.0

package/src/index.ts

@@ -30,8 +30,60 @@ export {
   getEntry,
   removeEntry,
   getJournalPath,
+  // Journal v2 (US-005)
+  migrateToV2,
+  generatePullId,
+  appendPullRecord,
+  lastPullRecord,
+  tombstoneEntry,
+  isTombstone,
+  gcTombstones,
+  TOMBSTONE_TTL_MS,
+  JOURNAL_VERSION_CURRENT,
 } from "./journal.js";
 
+// Prefix coalescing helper (US-005)
+export {
+  coalescePrefixes,
+  isCoveredByAny,
+} from "./prefix-coalesce.js";
+
+// Scope-shrink detection + application (US-005)
+export {
+  buildScopeShrinkPlan,
+  applyScopeShrink,
+  ScopeShrinkBlockedError,
+} from "./scope-shrink.js";
+export type {
+  OrphanClassification,
+  ScopeShrinkPlan,
+  BuildScopeShrinkPlanInput,
+  ApplyScopeShrinkInput,
+  ApplyScopeShrinkResult,
+} from "./scope-shrink.js";
+
+// Engine-layer ACL-aware pull orchestration (US-005)
+export {
+  resolveCompanyScope,
+  batchPrefixesForVend,
+  listRemoteForScope,
+  pullCompany,
+  decideRemotePulls,
+  VEND_PATH_CAP,
+  POST_FILTER_THRESHOLD,
+  VEND_FANOUT_CONCURRENCY,
+} from "./remote-pull.js";
+export type {
+  CompanyScope,
+  ResolveCompanyScopeInput,
+  ListRemoteForScopeInput,
+  PullCompanyInput,
+  PullCompanyResult,
+  RemotePullDecision,
+  DecideRemotePullsInput,
+  SkippedKey,
+} from "./remote-pull.js";
+
 export {
   createIgnoreFilter,
   isWithinSizeLimit,
@@ -80,6 +132,11 @@ export type {
   TelemetryOptInResponse,
   UsageBatch,
   UsageIngestResult,
+  // US-004 — browse-vs-sync membership sync-mode + ACL surface
+  SyncMode,
+  MembershipSyncConfig,
+  SetMembershipSyncConfigInput,
+  ExplicitGrant,
 } from "./vault-client.js";
 
 // Usage telemetry collector (`/v1/usage`). Re-exported so wrappers other than
@@ -101,6 +158,15 @@ export type {
   StsChildCredentials,
 } from "./vault-client.js";
 
+// Raw vend (POST /vend, purpose-aware after US-009)
+export type {
+  VendPurpose,
+  VaultOperation,
+  VendInput,
+  VendResult,
+  VendCredentials,
+} from "./vault-client.js";
+
 // CLI commands
 export { share, sync } from "./cli/index.js";
 export type { ShareOptions, ShareResult, SyncOptions, SyncResult, SyncProgressEvent } from "./cli/index.js";
@@ -124,6 +190,7 @@ export type {
   Credentials,
   JournalEntry,
   SyncJournal,
+  PullRecord,
   SyncStatus,
   PushResult,
   PullResult,

package/src/journal.test.ts

@@ -16,8 +16,16 @@ import {
   readJournal,
   writeJournal,
   updateEntry,
+  migrateToV2,
+  appendPullRecord,
+  lastPullRecord,
+  tombstoneEntry,
+  isTombstone,
+  gcTombstones,
+  generatePullId,
+  TOMBSTONE_TTL_MS,
 } from "./journal.js";
-import type { SyncJournal } from "./types.js";
+import type { SyncJournal, PullRecord } from "./types.js";
 
 describe("journal", () => {
   let stateDir: string;
@@ -73,14 +81,17 @@ describe("journal", () => {
   });
 
   describe("readJournal", () => {
-    it("returns an empty journal when the file doesn't exist", () => {
+    it("returns an empty v2 journal when the file doesn't exist", () => {
       const j = readJournal("indigo");
-      expect(j.version).toBe("1");
+      expect(j.version).toBe("2");
       expect(j.files).toEqual({});
       expect(j.lastSync).toBe("");
+      expect(j.pulls).toEqual([]);
     });
 
-    it("reads a journal written with writeJournal", () => {
+    it("reads a journal written with writeJournal (round-trips through v2 migration)", () => {
+      // writeJournal upgrades the schema in-place to v2, so the read side
+      // sees v2 even if the caller handed a v1 shape.
       const original: SyncJournal = {
         version: "1",
         lastSync: "2026-04-19T00:00:00.000Z",
@@ -95,7 +106,10 @@ describe("journal", () => {
       };
       writeJournal("indigo", original);
       const roundTripped = readJournal("indigo");
-      expect(roundTripped).toEqual(original);
+      expect(roundTripped.version).toBe("2");
+      expect(roundTripped.lastSync).toBe("2026-04-19T00:00:00.000Z");
+      expect(roundTripped.files).toEqual(original.files);
+      expect(roundTripped.pulls).toEqual([]);
     });
   });
 
@@ -143,4 +157,269 @@ describe("journal", () => {
       expect(j.files["foo.md"]?.syncedAt).not.toBe("");
     });
   });
+
+  // ── Journal v2 (US-005): pulls, tombstones, GC, migration ─────────────────
+
+  describe("migrateToV2", () => {
+    it("upgrades a v1 journal in place", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      migrateToV2(j);
+      expect(j.version).toBe("2");
+      expect(j.pulls).toEqual([]);
+    });
+
+    it("is idempotent on a v2 journal", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [],
+      };
+      const before = JSON.stringify(j);
+      migrateToV2(j);
+      expect(JSON.stringify(j)).toBe(before);
+    });
+
+    it("preserves all files when migrating v1 → v2", () => {
+      const j: SyncJournal = {
+        version: "1",
+        lastSync: "2026-05-01",
+        files: {
+          "a.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "2026-05-01",
+            direction: "down",
+          },
+        },
+      };
+      migrateToV2(j);
+      expect(j.files["a.md"]).toBeDefined();
+      expect(j.files["a.md"]?.removedAt).toBeUndefined(); // not a tombstone
+    });
+
+    it("writeJournal upgrades v1 → v2 on disk", () => {
+      writeJournal("indigo", { version: "1", lastSync: "", files: {} });
+      const raw = JSON.parse(
+        fs.readFileSync(getJournalPath("indigo"), "utf-8"),
+      ) as SyncJournal;
+      expect(raw.version).toBe("2");
+      expect(raw.pulls).toEqual([]);
+    });
+  });
+
+  describe("generatePullId", () => {
+    it("produces a 26-char identifier", () => {
+      expect(generatePullId()).toHaveLength(26);
+    });
+
+    it("is time-prefixed and lexically sortable", () => {
+      const t0 = Date.parse("2026-01-01T00:00:00.000Z");
+      const t1 = Date.parse("2026-06-01T00:00:00.000Z");
+      const id0 = generatePullId(t0);
+      const id1 = generatePullId(t1);
+      expect(id0 < id1).toBe(true);
+    });
+
+    it("uses crockford base32 alphabet (no I, L, O, U)", () => {
+      const id = generatePullId();
+      expect(id).toMatch(/^[0-9A-HJKMNP-TV-Z]+$/);
+    });
+  });
+
+  describe("appendPullRecord + lastPullRecord", () => {
+    function pull(partial: Partial<PullRecord>): PullRecord {
+      return {
+        pullId: generatePullId(),
+        companyUid: "cmp_indigo",
+        startedAt: "2026-05-20T00:00:00.000Z",
+        completedAt: "2026-05-20T00:00:05.000Z",
+        syncMode: "all",
+        prefixSet: [],
+        scopeChangeDetected: false,
+        orphansRemoved: 0,
+        orphansBlocked: 0,
+        ...partial,
+      };
+    }
+
+    it("appends to pulls[] (auto-migrates v1)", () => {
+      const j: SyncJournal = { version: "1", lastSync: "", files: {} };
+      appendPullRecord(j, pull({}));
+      expect(j.version).toBe("2");
+      expect(j.pulls).toHaveLength(1);
+    });
+
+    it("lastPullRecord returns undefined when no records exist", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [],
+      };
+      expect(lastPullRecord(j, "cmp_indigo")).toBeUndefined();
+    });
+
+    it("lastPullRecord returns the most-recent by completedAt", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [
+          pull({ completedAt: "2026-05-19T00:00:00.000Z", syncMode: "all" }),
+          pull({ completedAt: "2026-05-20T00:00:00.000Z", syncMode: "shared" }),
+          pull({ completedAt: "2026-05-18T00:00:00.000Z", syncMode: "all" }),
+        ],
+      };
+      expect(lastPullRecord(j, "cmp_indigo")?.syncMode).toBe("shared");
+    });
+
+    it("lastPullRecord filters by companyUid", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [
+          pull({ companyUid: "cmp_a", completedAt: "2026-05-20T00:00:00.000Z" }),
+          pull({ companyUid: "cmp_b", completedAt: "2026-05-21T00:00:00.000Z" }),
+        ],
+      };
+      expect(lastPullRecord(j, "cmp_a")?.completedAt).toBe(
+        "2026-05-20T00:00:00.000Z",
+      );
+    });
+  });
+
+  describe("tombstoneEntry + isTombstone", () => {
+    it("marks an entry with removedAt + removedReason", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {
+          "a.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "2026-05-01T00:00:00.000Z",
+            direction: "down",
+          },
+        },
+        pulls: [],
+      };
+      tombstoneEntry(j, "a.md", "scope_shrink", "2026-05-20T00:00:00.000Z");
+      expect(j.files["a.md"]?.removedAt).toBe("2026-05-20T00:00:00.000Z");
+      expect(j.files["a.md"]?.removedReason).toBe("scope_shrink");
+      expect(isTombstone(j.files["a.md"])).toBe(true);
+    });
+
+    it("is a no-op for missing entries", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {},
+        pulls: [],
+      };
+      expect(() =>
+        tombstoneEntry(j, "missing.md", "scope_shrink"),
+      ).not.toThrow();
+    });
+
+    it("preserves the original hash/size/syncedAt (forensic trail)", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {
+          "a.md": {
+            hash: "old-hash",
+            size: 42,
+            syncedAt: "2026-05-01T00:00:00.000Z",
+            direction: "down",
+          },
+        },
+        pulls: [],
+      };
+      tombstoneEntry(j, "a.md", "scope_shrink");
+      expect(j.files["a.md"]?.hash).toBe("old-hash");
+      expect(j.files["a.md"]?.size).toBe(42);
+    });
+  });
+
+  describe("gcTombstones", () => {
+    it("removes tombstones older than TOMBSTONE_TTL_MS", () => {
+      const now = Date.parse("2026-06-01T00:00:00.000Z");
+      const old = new Date(now - TOMBSTONE_TTL_MS - 1000).toISOString();
+      const fresh = new Date(now - 1000).toISOString();
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {
+          "old-tombstone.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "2026-04-01T00:00:00.000Z",
+            direction: "down",
+            removedAt: old,
+            removedReason: "scope_shrink",
+          },
+          "fresh-tombstone.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "2026-05-01T00:00:00.000Z",
+            direction: "down",
+            removedAt: fresh,
+            removedReason: "scope_shrink",
+          },
+          "live.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "2026-05-01T00:00:00.000Z",
+            direction: "down",
+          },
+        },
+        pulls: [],
+      };
+      const removed = gcTombstones(j, now);
+      expect(removed).toBe(1);
+      expect(j.files["old-tombstone.md"]).toBeUndefined();
+      expect(j.files["fresh-tombstone.md"]).toBeDefined();
+      expect(j.files["live.md"]).toBeDefined();
+    });
+
+    it("never removes non-tombstone entries", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {
+          "live.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "1970-01-01T00:00:00.000Z",
+            direction: "down",
+          },
+        },
+        pulls: [],
+      };
+      expect(gcTombstones(j, Date.now())).toBe(0);
+      expect(j.files["live.md"]).toBeDefined();
+    });
+
+    it("ignores tombstones with un-parseable removedAt", () => {
+      const j: SyncJournal = {
+        version: "2",
+        lastSync: "",
+        files: {
+          "bogus.md": {
+            hash: "h",
+            size: 1,
+            syncedAt: "",
+            direction: "down",
+            removedAt: "not-a-date",
+            removedReason: "scope_shrink",
+          },
+        },
+        pulls: [],
+      };
+      expect(gcTombstones(j, Date.now())).toBe(0);
+      expect(j.files["bogus.md"]).toBeDefined();
+    });
+  });
 });

package/src/journal.ts

@@ -17,7 +17,13 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as crypto from "crypto";
-import type { SyncJournal, JournalEntry } from "./types.js";
+import type { SyncJournal, JournalEntry, PullRecord } from "./types.js";
+
+/** Tombstone retention. 30 days in milliseconds — roughly two release cycles. */
+export const TOMBSTONE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Current journal schema version written by all v2-aware writers. */
+export const JOURNAL_VERSION_CURRENT = "2" as const;
 
 const JOURNAL_FILE_PREFIX = "sync-journal.";
 const JOURNAL_FILE_SUFFIX = ".json";
@@ -54,16 +60,54 @@ export function getJournalPath(slug: string): string {
   );
 }
 
+/**
+ * Read a per-company journal from disk.
+ *
+ * Back-compat (US-005, v1 → v2): a v1 file on disk is returned as-is with
+ * `version: "1"` and no `pulls` field. The in-place migration to v2 happens
+ * the first time `writeJournal` runs — `migrateToV2` ensures any journal
+ * passed to the writer carries `version: "2"`, `pulls: []`, and the rest of
+ * the v2 shape. This keeps `readJournal` deterministic + cheap and confines
+ * the side effect (schema bump on disk) to writes.
+ *
+ * When the file doesn't exist, we return a fresh v2 journal directly — new
+ * installs never pass through v1 on disk.
+ */
 export function readJournal(slug: string): SyncJournal {
   const journalPath = getJournalPath(slug);
   if (fs.existsSync(journalPath)) {
     const content = fs.readFileSync(journalPath, "utf-8");
     return JSON.parse(content) as SyncJournal;
   }
-  return { version: "1", lastSync: "", files: {} };
+  return { version: JOURNAL_VERSION_CURRENT, lastSync: "", files: {}, pulls: [] };
 }
 
+/**
+ * Coerce any-version journal into a v2 shape. Idempotent for v2 inputs.
+ * Mutates the input and returns it for chainable use. Call this immediately
+ * after `readJournal` if your code-path needs the v2 fields.
+ *
+ * v1 → v2 contract: every existing `files[]` entry is preserved as-is; no
+ * tombstone fields are inserted (legacy entries are NOT scope-shrink
+ * tombstones). `pulls` becomes `[]` (empty history → treat last scope as
+ * "all" in the scope-shrink algorithm).
+ */
+export function migrateToV2(journal: SyncJournal): SyncJournal {
+  if (journal.version === "2" && Array.isArray(journal.pulls)) {
+    return journal;
+  }
+  journal.version = JOURNAL_VERSION_CURRENT;
+  if (!Array.isArray(journal.pulls)) journal.pulls = [];
+  return journal;
+}
+
+/**
+ * Write a journal to disk, migrating to the current schema version in-place.
+ * `migrateToV2` mutates the passed-in object — callers that hold a reference
+ * after the write will see the v2 shape.
+ */
 export function writeJournal(slug: string, journal: SyncJournal): void {
+  migrateToV2(journal);
   const journalPath = getJournalPath(slug);
   fs.mkdirSync(path.dirname(journalPath), { recursive: true });
   fs.writeFileSync(journalPath, JSON.stringify(journal, null, 2));
@@ -151,3 +195,124 @@ export function removeEntry(
 ): void {
   delete journal.files[relativePath];
 }
+
+// ─── Journal v2 (US-005): pulls, tombstones, GC ─────────────────────────────
+
+/** Crockford base32 alphabet (ULID-compatible). */
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/**
+ * Generate a ULID-shaped 26-char identifier without adding a runtime dep.
+ * Format: 10-char base32 of the current millisecond timestamp + 16-char
+ * base32 of random bytes. Lexically sortable, time-prefixed — same property
+ * that makes ULIDs useful for `pulls[]` ordering.
+ *
+ * We don't need full ULID spec compliance (monotonic counter, randomness
+ * spec) — just sortable + collision-resistant enough that two pulls
+ * issued in the same millisecond by different processes don't clash.
+ * 80 bits of randomness is plenty.
+ */
+export function generatePullId(now: number = Date.now()): string {
+  let time = now;
+  const timeChars: string[] = [];
+  for (let i = 0; i < 10; i++) {
+    timeChars.unshift(CROCKFORD[time % 32]!);
+    time = Math.floor(time / 32);
+  }
+  const randBytes = crypto.randomBytes(10); // 80 bits
+  const randChars: string[] = [];
+  // Encode 10 random bytes (80 bits) into 16 base32 chars.
+  let buf = 0;
+  let bits = 0;
+  for (let i = 0; i < randBytes.length; i++) {
+    buf = (buf << 8) | randBytes[i]!;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      randChars.push(CROCKFORD[(buf >> bits) & 0x1f]!);
+    }
+  }
+  if (bits > 0) {
+    randChars.push(CROCKFORD[(buf << (5 - bits)) & 0x1f]!);
+  }
+  return timeChars.join("") + randChars.slice(0, 16).join("");
+}
+
+/**
+ * Find the most-recent `PullRecord` for a company in the journal. Returns
+ * `undefined` when no record exists — scope-shrink callers treat that as
+ * "no prior scope; nothing to shrink".
+ *
+ * Order by `completedAt` descending — `pullId` is lexically sortable but
+ * `completedAt` is what semantically represents "most recent successful
+ * pull state at last close".
+ */
+export function lastPullRecord(
+  journal: SyncJournal,
+  companyUid: string,
+): PullRecord | undefined {
+  if (!journal.pulls || journal.pulls.length === 0) return undefined;
+  let best: PullRecord | undefined;
+  for (const p of journal.pulls) {
+    if (p.companyUid !== companyUid) continue;
+    if (!best || p.completedAt > best.completedAt) best = p;
+  }
+  return best;
+}
+
+/** Append a `PullRecord` (mutates `journal.pulls`). */
+export function appendPullRecord(
+  journal: SyncJournal,
+  record: PullRecord,
+): void {
+  migrateToV2(journal);
+  journal.pulls!.push(record);
+}
+
+/**
+ * Write a journal tombstone entry for `relativePath`. Used by the scope-
+ * shrink algorithm (US-005) and by `hq sync narrow --apply` (US-007).
+ *
+ * Tombstones intentionally keep the old `hash` / `size` / `syncedAt` /
+ * `direction` so a recovery flow could see what was there before pruning.
+ * They are GC'd after `TOMBSTONE_TTL_MS` via `gcTombstones`.
+ */
+export function tombstoneEntry(
+  journal: SyncJournal,
+  relativePath: string,
+  reason: "scope_shrink" | "narrow_apply" | "manual",
+  now: string = new Date().toISOString(),
+): void {
+  const entry = journal.files[relativePath];
+  if (!entry) return;
+  entry.removedAt = now;
+  entry.removedReason = reason;
+}
+
+/** True if the entry is a tombstone (set by `tombstoneEntry`). */
+export function isTombstone(entry: JournalEntry | undefined): boolean {
+  return !!entry && typeof entry.removedAt === "string";
+}
+
+/**
+ * Garbage-collect tombstones older than `TOMBSTONE_TTL_MS` from
+ * `journal.files`. Returns the number removed. Cheap — single pass over
+ * the files map, no I/O. Safe to call at the start AND end of every
+ * `pullAll` per-company leg; both runs are idempotent.
+ */
+export function gcTombstones(
+  journal: SyncJournal,
+  now: number = Date.now(),
+): number {
+  let removed = 0;
+  for (const [path, entry] of Object.entries(journal.files)) {
+    if (!entry.removedAt) continue;
+    const removedTime = Date.parse(entry.removedAt);
+    if (Number.isNaN(removedTime)) continue;
+    if (now - removedTime > TOMBSTONE_TTL_MS) {
+      delete journal.files[path];
+      removed++;
+    }
+  }
+  return removed;
+}

package/src/prefix-coalesce.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { coalescePrefixes, isCoveredByAny } from "./prefix-coalesce.js";
+
+describe("coalescePrefixes", () => {
+  it("returns empty for empty input", () => {
+    expect(coalescePrefixes([])).toEqual([]);
+  });
+
+  it("dedupes identical inputs", () => {
+    expect(coalescePrefixes(["a/", "a/"])).toEqual(["a/"]);
+  });
+
+  it("collapses nested prefixes into the broader one", () => {
+    expect(coalescePrefixes(["a/", "a/b/"])).toEqual(["a/"]);
+  });
+
+  it("collapses deeply nested chains", () => {
+    expect(coalescePrefixes(["a/", "a/b/", "a/b/c/", "a/b/c/d/"])).toEqual([
+      "a/",
+    ]);
+  });
+
+  it("keeps sibling (overlapping but non-nested) prefixes", () => {
+    expect(coalescePrefixes(["a/b/", "a/c/"])).toEqual(["a/b/", "a/c/"]);
+  });
+
+  it("mixes nested + sibling correctly", () => {
+    expect(
+      coalescePrefixes([
+        "companies/indigo/meetings/",
+        "companies/indigo/meetings/2026/",
+        "companies/indigo/scratch/jacob/",
+      ]),
+    ).toEqual([
+      "companies/indigo/meetings/",
+      "companies/indigo/scratch/jacob/",
+    ]);
+  });
+
+  it("is case-sensitive (S3 keys are case-sensitive)", () => {
+    // 'A/' and 'a/' do not cover each other — both must be kept.
+    const result = coalescePrefixes(["A/", "a/"]);
+    expect(result.sort()).toEqual(["A/", "a/"]);
+  });
+
+  it("returns prefixes sorted lexicographically (deterministic for journal)", () => {
+    expect(coalescePrefixes(["c/", "a/", "b/"])).toEqual(["a/", "b/", "c/"]);
+  });
+
+  it("drops empty-string entries (would otherwise cover everything)", () => {
+    expect(coalescePrefixes(["", "a/", ""])).toEqual(["a/"]);
+  });
+
+  it("is a pure function — input array is not mutated", () => {
+    const input = ["a/b/", "a/"];
+    const snapshot = [...input];
+    coalescePrefixes(input);
+    expect(input).toEqual(snapshot);
+  });
+
+  it("handles a single prefix unchanged", () => {
+    expect(coalescePrefixes(["companies/indigo/"])).toEqual([
+      "companies/indigo/",
+    ]);
+  });
+
+  it("does not treat 'ab/' as nested under 'a/' lexically (literal startsWith)", () => {
+    // `'ab/'.startsWith('a/')` is FALSE — `a/` would have to be a true
+    // path-segment ancestor. (Callers should pass trailing-slash-bounded
+    // prefixes — the grants endpoint always does.)
+    expect(coalescePrefixes(["a/", "ab/"]).sort()).toEqual(["a/", "ab/"]);
+  });
+});
+
+describe("isCoveredByAny", () => {
+  it("returns true when a prefix covers the path", () => {
+    expect(isCoveredByAny("a/b/c.md", ["a/"])).toBe(true);
+  });
+
+  it("returns false when no prefix covers the path", () => {
+    expect(isCoveredByAny("a/b/c.md", ["x/", "y/"])).toBe(false);
+  });
+
+  it("returns false on empty prefix set", () => {
+    expect(isCoveredByAny("a/b/c.md", [])).toBe(false);
+  });
+
+  it("treats exact match as covered", () => {
+    expect(isCoveredByAny("a/b/", ["a/b/"])).toBe(true);
+  });
+
+  it("is case-sensitive", () => {
+    expect(isCoveredByAny("A/b/c.md", ["a/"])).toBe(false);
+  });
+});