@indigoai-us/hq-cloud 6.11.5 → 6.11.7

package/src/sources/get.test.ts

@@ -2,13 +2,14 @@
  * Unit tests for sources/get.ts.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { GetObjectCommand, type S3Client } from "@aws-sdk/client-s3";
 import { getSource, SourceNotFoundError } from "./get.js";
 import {
   _setSourcesS3Factory,
   _resetSourcesS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSourceChannelError } from "../schemas/source-channels.js";
 
@@ -164,3 +165,105 @@ describe("getSource", () => {
     expect(doc.body).toBe("Just a body, no frontmatter.");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+/**
+ * A presign-capable vault stub + a `fetch` mock keyed by the presigned URL.
+ * presign() mints a URL that encodes the key; fetch() returns the object's
+ * bytes (404 when absent, so a missing key surfaces as SourceNotFoundError —
+ * matching the S3 NoSuchKey path).
+ */
+function makePresignVault(objects: Record<string, string>): PresignTransportClient {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const content = objects[key];
+      if (content === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(content, "utf-8"), { status: 200 });
+    }),
+  );
+  return {
+    presign: async (input) => ({
+      results: input.keys.map((k) => ({
+        key: k.key,
+        op: k.op ?? input.op ?? "get",
+        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
+      })),
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    }),
+    listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
+  };
+}
+
+describe("getSource — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("reads via presign and never touches S3", async () => {
+    // S3 factory throws if used — proves the read went through presign.
+    _setSourcesS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const vault = makePresignVault({ "sources/meetings/abc.md": MEETING_MD });
+
+    const doc = await getSource({
+      entity: ENTITY,
+      channel: "meeting",
+      sourceId: "abc",
+      vault,
+    });
+
+    expect(doc.frontmatter).toEqual({
+      source_id: "abc",
+      source_type: "meeting",
+      title: "Q1 Planning",
+    });
+    expect(doc.body).toContain("Body text line 1.");
+  });
+
+  it("maps a presign 404 to SourceNotFoundError", async () => {
+    const vault = makePresignVault({});
+    await expect(
+      getSource({ entity: ENTITY, channel: "meeting", sourceId: "missing", vault }),
+    ).rejects.toBeInstanceOf(SourceNotFoundError);
+  });
+
+  it("includeRaw via presign reads the .raw.json sibling", async () => {
+    const vault = makePresignVault({
+      "sources/meetings/abc.md": MEETING_MD,
+      "sources/meetings/abc.raw.json": JSON.stringify(RAW_PAYLOAD),
+    });
+    const doc = await getSource({
+      entity: ENTITY,
+      channel: "meeting",
+      sourceId: "abc",
+      includeRaw: true,
+      vault,
+    });
+    expect(doc.raw).toEqual(RAW_PAYLOAD);
+  });
+
+  it("personal vault (prs_) ignores the vault client and stays on direct S3", async () => {
+    // S3 stub serves the doc; the presign fetch would 404 if (wrongly) used.
+    installStub({ "sources/meetings/abc.md": MEETING_MD });
+    const vault = makePresignVault({});
+    const personal: EntityContext = { ...ENTITY, uid: "prs_me" };
+
+    const doc = await getSource({
+      entity: personal,
+      channel: "meeting",
+      sourceId: "abc",
+      vault,
+    });
+
+    expect(doc.body).toContain("Body text line 1.");
+  });
+});

package/src/sources/get.ts

@@ -3,9 +3,8 @@
  * sibling) from an entity bucket and return parsed frontmatter + body.
  */
 
-import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { readObjectText, tryReadObjectText } from "./internals.js";
 import { parseMarkdown } from "./parse.js";
 import type { GetSourceOptions, SourceDocument } from "./types.js";
 
@@ -19,15 +18,18 @@ export class SourceNotFoundError extends Error {
 function isNoSuchKey(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const name = (err as { name?: unknown }).name;
-  // AWS SDK v3 throws either a `NoSuchKey` exception or a `NotFound` head error.
-  return name === "NoSuchKey" || name === "NoSuchKeyException";
+  // The transport normalizes a missing object to a `NoSuchKey`-named error on
+  // both the S3 and presigned paths (a presign 404 → NoSuchKey). `NotFound` is
+  // kept for defense in depth (S3 HEAD-style errors).
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
 }
 
 export async function getSource(opts: GetSourceOptions): Promise<SourceDocument> {
-  // Validate channel BEFORE any S3 call (acceptance criterion).
+  // Validate channel BEFORE any read (acceptance criterion).
   assertSourceChannel(opts.channel);
 
-  const client = getS3Client(opts.entity);
   // sources-pipeline writes "meeting" channel to sources/meetings/...; other
   // channels pass through. See schemas/source-channels.ts:sourcePathSegment.
   const segment = sourcePathSegment(opts.channel);
@@ -35,13 +37,7 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
 
   let body: string;
   try {
-    const response = await client.send(
-      new GetObjectCommand({
-        Bucket: opts.entity.bucketName,
-        Key: key,
-      }),
-    );
-    body = await streamToString(response.Body);
+    body = await readObjectText(opts, key);
   } catch (err) {
     if (isNoSuchKey(err)) {
       throw new SourceNotFoundError(key);
@@ -58,19 +54,11 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
   };
 
   if (opts.includeRaw) {
+    // Raw sibling is optional; tryReadObjectText returns null when absent.
     const rawKey = `sources/${segment}/${opts.sourceId}.raw.json`;
-    try {
-      const rawResponse = await client.send(
-        new GetObjectCommand({
-          Bucket: opts.entity.bucketName,
-          Key: rawKey,
-        }),
-      );
-      const rawText = await streamToString(rawResponse.Body);
+    const rawText = await tryReadObjectText(opts, rawKey);
+    if (rawText !== null) {
       document.raw = JSON.parse(rawText);
-    } catch (err) {
-      if (!isNoSuchKey(err)) throw err;
-      // Raw sibling is optional; leave undefined when absent.
     }
   }
 

package/src/sources/internals.ts

@@ -1,15 +1,37 @@
 /**
  * Internal helpers shared between sources/list.ts and sources/get.ts.
  *
- * The S3 client factory hook exists so tests can inject an in-memory stub
- * without standing up vi.mock for @aws-sdk/client-s3. Production code never
- * calls the setter.
+ * Two transports back the read surface:
+ *   - presigned-URL (HQ-59): when a vault client is supplied AND the entity is a
+ *     company vault (cmp_*), reads go through the vault `list`/`presign`
+ *     endpoints — the client never talks to S3 directly. This is the path every
+ *     company read should take going forward.
+ *   - direct S3 (legacy / personal): no vault client, or a personal vault
+ *     (prs_*, whose membership-less creds 403 the membership-gated presign
+ *     endpoints). Goes through `getS3Client`, whose factory hook lets tests
+ *     inject an in-memory stub without vi.mock.
  */
 
-import { S3Client } from "@aws-sdk/client-s3";
+import {
+  S3Client,
+  GetObjectCommand,
+  ListObjectsV2Command,
+} from "@aws-sdk/client-s3";
 import type { EntityContext } from "../types.js";
+import { PresignObjectIO, type PresignTransportClient } from "../object-io.js";
 
 function defaultFactory(ctx: EntityContext): S3Client {
+  if (!ctx.credentials) {
+    // The direct-S3 read path needs STS creds. A credential-less context only
+    // exists on the presign path (HQ-59 company vend-skip), which reads via the
+    // vault list/presign endpoints, not this S3 client — so arriving here with
+    // no creds is a routing bug. Fail loudly rather than 403 opaquely later.
+    throw new Error(
+      `Sources S3 read for ${ctx.uid} requires STS credentials but got a ` +
+        `presign-only context; company presign reads must go through the ` +
+        `vault transport, not getS3Client.`,
+    );
+  }
   return new S3Client({
     region: ctx.region,
     credentials: {
@@ -44,3 +66,133 @@ export async function streamToString(body: unknown): Promise<string> {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+
+// ---------------------------------------------------------------------------
+// Transport seam (presign for cmp_, direct-S3 otherwise)
+// ---------------------------------------------------------------------------
+
+/** Common shape of every reader's options: an entity + an optional vault client. */
+export interface ReaderTransportOpts {
+  entity: EntityContext;
+  /**
+   * Presign-capable vault client. When supplied and the entity is a company
+   * vault (cmp_*), reads use the presigned-URL transport instead of direct S3.
+   */
+  vault?: PresignTransportClient;
+}
+
+/** Lightweight listed object (transport-agnostic). */
+export interface ListedKey {
+  key: string;
+  size: number;
+  lastModified: Date;
+}
+
+/** True when this read should use the presigned-URL transport. */
+export function usePresign(opts: ReaderTransportOpts): boolean {
+  return opts.vault != null && opts.entity.uid.startsWith("cmp_");
+}
+
+/** A not-found error normalized to the S3 `NoSuchKey` shape callers test for. */
+function noSuchKeyError(key: string): Error {
+  return Object.assign(new Error(`No such key: ${key}`), { name: "NoSuchKey" });
+}
+
+function isNotFound(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return (
+    name === "NoSuchKey" || name === "NoSuchKeyException" || name === "NotFound"
+  );
+}
+
+/**
+ * Read an object's UTF-8 text. Throws a `NoSuchKey`-named error when the object
+ * is absent (both transports), so callers' existing not-found checks work
+ * unchanged.
+ */
+export async function readObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    try {
+      const { body } = await io.getObject(key);
+      return body.toString("utf-8");
+    } catch (err) {
+      if (isNotFound(err)) throw noSuchKeyError(key);
+      throw err;
+    }
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new GetObjectCommand({ Bucket: opts.entity.bucketName, Key: key }),
+  );
+  return streamToString(res.Body);
+}
+
+/** Like {@link readObjectText} but returns null when the object is absent. */
+export async function tryReadObjectText(
+  opts: ReaderTransportOpts,
+  key: string,
+): Promise<string | null> {
+  try {
+    return await readObjectText(opts, key);
+  } catch (err) {
+    if (isNotFound(err)) return null;
+    throw err;
+  }
+}
+
+/**
+ * List one page of objects under `prefix`.
+ *
+ * Under the presigned transport the vault `list` endpoint is ACL-filtered and
+ * controls page size server-side, so `limit` is advisory — paginate via the
+ * returned `nextToken` (the opaque vault cursor) until it is undefined. Under
+ * direct S3, `limit` maps to `MaxKeys`.
+ */
+export async function listObjects(
+  opts: ReaderTransportOpts,
+  prefix: string,
+  page: { limit?: number; continuationToken?: string },
+): Promise<{ contents: ListedKey[]; nextToken?: string }> {
+  if (usePresign(opts)) {
+    const io = new PresignObjectIO(opts.vault!, opts.entity.uid);
+    const res = await io.listObjects({
+      prefix,
+      continuationToken: page.continuationToken,
+    });
+    return {
+      contents: res.objects.map((o) => ({
+        key: o.key,
+        size: o.size,
+        lastModified: o.lastModified,
+      })),
+      nextToken: res.nextContinuationToken,
+    };
+  }
+  const client = getS3Client(opts.entity);
+  const res = await client.send(
+    new ListObjectsV2Command({
+      Bucket: opts.entity.bucketName,
+      Prefix: prefix,
+      MaxKeys: page.limit,
+      ContinuationToken: page.continuationToken,
+    }),
+  );
+  const contents: ListedKey[] = [];
+  for (const obj of res.Contents ?? []) {
+    if (!obj.Key) continue;
+    contents.push({
+      key: obj.Key,
+      size: obj.Size ?? 0,
+      lastModified: obj.LastModified ?? new Date(0),
+    });
+  }
+  return {
+    contents,
+    nextToken: res.IsTruncated ? res.NextContinuationToken : undefined,
+  };
+}

package/src/sources/list.test.ts

@@ -5,7 +5,7 @@
  * hook so we don't have to stand up vi.mock for @aws-sdk/client-s3.
  */
 
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import {
   GetObjectCommand,
   ListObjectsV2Command,
@@ -16,6 +16,8 @@ import {
   _setSourcesS3Factory,
   _resetSourcesS3Factory,
 } from "./internals.js";
+import type { PresignTransportClient } from "../object-io.js";
+import type { VaultListedObject } from "../vault-client.js";
 import type { EntityContext } from "../types.js";
 import { InvalidSourceChannelError } from "../schemas/source-channels.js";
 
@@ -245,3 +247,132 @@ describe("listSources", () => {
     expect(observed.commands).toHaveLength(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Presigned transport (vault client + company vault) — HQ-59
+// ---------------------------------------------------------------------------
+
+interface PresignVaultStub {
+  vault: PresignTransportClient;
+  listCalls: Array<{ prefix?: string; cursor?: string }>;
+}
+
+/**
+ * Vault stub for the list path: `listFiles` returns the configured ACL-filtered
+ * page (the server is the ACL boundary — only readable keys come back) + an
+ * opaque cursor; `presign`+fetch serve per-entry frontmatter GETs.
+ */
+function makePresignVault(
+  page: { objects: VaultListedObject[]; cursor: string | null },
+  contents: Record<string, string> = {},
+): PresignVaultStub {
+  const listCalls: Array<{ prefix?: string; cursor?: string }> = [];
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const key = new URL(url).searchParams.get("key") ?? "";
+      const c = contents[key];
+      if (c === undefined) return new Response(null, { status: 404 });
+      return new Response(Buffer.from(c, "utf-8"), { status: 200 });
+    }),
+  );
+  const vault: PresignTransportClient = {
+    presign: async (input) => ({
+      results: input.keys.map((k) => ({
+        key: k.key,
+        op: k.op ?? input.op ?? "get",
+        url: `https://signed.example/?key=${encodeURIComponent(k.key)}`,
+      })),
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    }),
+    listFiles: async (_company, prefix, cursor) => {
+      listCalls.push({ prefix, cursor });
+      return {
+        objects: page.objects,
+        cursor: page.cursor,
+        truncated: page.cursor != null,
+      };
+    },
+  };
+  return { vault, listCalls };
+}
+
+function listed(key: string): VaultListedObject {
+  return {
+    key,
+    size: 10,
+    lastModified: "2026-02-01T00:00:00.000Z",
+    etag: "etag",
+    permission: "read",
+  };
+}
+
+describe("listSources — presigned transport (vault + cmp_)", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("lists via the ACL-filtered vault endpoint and never touches S3", async () => {
+    _setSourcesS3Factory(
+      () =>
+        ({
+          send: async () => {
+            throw new Error("S3 must not be used on the presign path");
+          },
+        }) as unknown as S3Client,
+    );
+    const { vault, listCalls } = makePresignVault({
+      objects: [listed("sources/meetings/a.md"), listed("sources/meetings/a.raw.json")],
+      cursor: null,
+    });
+
+    const res = await listSources({ entity: ENTITY, channel: "meeting", vault });
+
+    // .raw.json sibling is skipped; only the .md entry surfaces.
+    expect(res.entries.map((e) => e.sourceId)).toEqual(["a"]);
+    expect(res.entries[0].key).toBe("sources/meetings/a.md");
+    expect(res.nextToken).toBeUndefined();
+    // listFiles was called with the channel prefix (ACL filtering is server-side).
+    expect(listCalls[0].prefix).toBe("sources/meetings/");
+  });
+
+  it("surfaces the opaque vault cursor as nextToken (advisory limit)", async () => {
+    const { vault } = makePresignVault({
+      objects: [listed("sources/meetings/a.md")],
+      cursor: "OPAQUE_CURSOR",
+    });
+    const res = await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      limit: 1,
+      vault,
+    });
+    expect(res.nextToken).toBe("OPAQUE_CURSOR");
+  });
+
+  it("includeFrontmatter parses each entry via a presigned GET", async () => {
+    const { vault } = makePresignVault(
+      { objects: [listed("sources/meetings/a.md")], cursor: null },
+      { "sources/meetings/a.md": MEETING_MD },
+    );
+    const res = await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      includeFrontmatter: true,
+      vault,
+    });
+    expect(res.entries[0].frontmatter).toMatchObject({ title: "Hello" });
+  });
+
+  it("forwards the continuationToken as the vault cursor", async () => {
+    const { vault, listCalls } = makePresignVault({
+      objects: [],
+      cursor: null,
+    });
+    await listSources({
+      entity: ENTITY,
+      channel: "meeting",
+      continuationToken: "RESUME_HERE",
+      vault,
+    });
+    expect(listCalls[0].cursor).toBe("RESUME_HERE");
+  });
+});

package/src/sources/list.ts

@@ -6,12 +6,8 @@
  * the summary (callers fetch them via getSource({ includeRaw: true })).
  */
 
-import {
-  GetObjectCommand,
-  ListObjectsV2Command,
-} from "@aws-sdk/client-s3";
 import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
-import { getS3Client, streamToString } from "./internals.js";
+import { listObjects, readObjectText } from "./internals.js";
 import { parseFrontmatter } from "./parse.js";
 import type {
   ListSourcesOptions,
@@ -40,46 +36,37 @@ function deriveSourceId(
 }
 
 export async function listSources(opts: ListSourcesOptions): Promise<ListSourcesResult> {
-  // Validate channel BEFORE any S3 call (acceptance criterion).
+  // Validate channel BEFORE any read (acceptance criterion).
   assertSourceChannel(opts.channel);
 
-  const client = getS3Client(opts.entity);
   // Use the canonical path segment from the schema; channel "meeting" maps
   // to the plural "meetings/" prefix the sources-pipeline writes to.
   const prefix = `sources/${sourcePathSegment(opts.channel)}/`;
 
-  const response = await client.send(
-    new ListObjectsV2Command({
-      Bucket: opts.entity.bucketName,
-      Prefix: prefix,
-      MaxKeys: opts.limit,
-      ContinuationToken: opts.continuationToken,
-    }),
-  );
+  // Presign transport ACL-filters server-side and controls page size, so
+  // `limit` is advisory there; under direct S3 it maps to MaxKeys. Paginate via
+  // the returned nextToken regardless of transport.
+  const page = await listObjects(opts, prefix, {
+    limit: opts.limit,
+    continuationToken: opts.continuationToken,
+  });
 
   const entries: SourceSummary[] = [];
-  for (const obj of response.Contents ?? []) {
-    if (!obj.Key) continue;
-    const derived = deriveSourceId(obj.Key, prefix);
+  for (const obj of page.contents) {
+    const derived = deriveSourceId(obj.key, prefix);
     if (!derived || derived.isRawSibling) continue;
 
     const summary: SourceSummary = {
       sourceId: derived.sourceId,
       channel: opts.channel,
-      key: obj.Key,
-      lastModified: obj.LastModified ?? new Date(0),
-      size: obj.Size ?? 0,
+      key: obj.key,
+      lastModified: obj.lastModified,
+      size: obj.size,
     };
 
     if (opts.includeFrontmatter) {
       try {
-        const get = await client.send(
-          new GetObjectCommand({
-            Bucket: opts.entity.bucketName,
-            Key: obj.Key,
-          }),
-        );
-        const text = await streamToString(get.Body);
+        const text = await readObjectText(opts, obj.key);
         const fm = parseFrontmatter(text);
         if (fm) summary.frontmatter = fm;
       } catch {
@@ -92,6 +79,6 @@ export async function listSources(opts: ListSourcesOptions): Promise<ListSources
 
   return {
     entries,
-    nextToken: response.IsTruncated ? response.NextContinuationToken : undefined,
+    nextToken: page.nextToken,
   };
 }

package/src/sources/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { SourceChannel } from "../schemas/source-channels.js";
+import type { PresignTransportClient } from "../object-io.js";
 
 /**
  * Lightweight summary returned by listSources(). `frontmatter` is only
@@ -44,12 +45,23 @@ export interface SourceDocument {
 export interface ListSourcesOptions {
   entity: import("../types.js").EntityContext;
   channel: SourceChannel;
-  /** Max keys per page; defaults to S3 default (1000). */
+  /**
+   * Max keys per page. Under direct S3 this maps to `MaxKeys`; under the
+   * presigned transport ({@link vault} + a company vault) it is advisory — the
+   * vault `list` endpoint controls page size server-side. Defaults to the S3
+   * default (1000) on the direct path.
+   */
   limit?: number;
   /** Opaque continuation token returned by a prior page. */
   continuationToken?: string;
   /** When true, fetches+parses each entry's frontmatter (extra GETs). */
   includeFrontmatter?: boolean;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (ACL-filtered, no
+   * direct S3). Personal vaults and the absent-client path stay on direct S3.
+   */
+  vault?: PresignTransportClient;
 }
 
 export interface ListSourcesResult {
@@ -64,4 +76,9 @@ export interface GetSourceOptions {
   sourceId: string;
   /** When true, also fetches the `.raw.json` sibling. */
   includeRaw?: boolean;
+  /**
+   * Presign-capable vault client. When supplied and {@link entity} is a company
+   * vault (cmp_*), reads use the presigned-URL transport (no direct S3).
+   */
+  vault?: PresignTransportClient;
 }

package/src/sync/event-sync.ts

@@ -7,9 +7,8 @@
  * runner's receiver seam defaults to {@link NoopPushReceiver}. This module is
  * the connective tissue that turns both on for enrolled accounts:
  *
- *  - {@link resolveEventSync} — the rollout gate. EXACT-email allowlist
- *    (mirrors `resolvePresignTransport`'s shape in sync-runner.ts, but full
- *    address, not domain suffix) + `HQ_SYNC_EVENT_SYNC` env override in both
+ *  - {@link resolveEventSync} — the rollout gate. EXACT-email allowlist (full
+ *    address, not a domain suffix) + `HQ_SYNC_EVENT_SYNC` env override in both
  *    directions. ONE gate governs publish AND receive so a device is never
  *    publish-only or receive-only in a half-rolled state.
  *  - {@link subscribeSyncReceive} — `POST /v1/sync/subscribe` (US-015/US-016):
@@ -58,8 +57,8 @@ import type { TreeChangeBatch } from "../watcher.js";
  * single-account Phase 3 rollout (2026-06-10) targets the operator's own
  * devices; `xhassaan@getindigo.ai` and `hassaan@getindigo.ai.evil.com` must
  * never match. Broadening later is an entry here, then a domain set, then a
- * GA default-on switch (the path the presigned-URL transport already took in
- * `resolvePresignTransport`).
+ * GA default-on switch (the same rollout path the presigned-URL sync transport
+ * already took to GA).
  */
 export const EVENT_SYNC_ROLLOUT_EMAILS: ReadonlySet<string> = new Set([
   "hassaan@getindigo.ai",
@@ -68,8 +67,8 @@ export const EVENT_SYNC_ROLLOUT_EMAILS: ReadonlySet<string> = new Set([
 /**
  * Decide whether this session runs event-driven sync (publish + receive).
  *
- * Mirrors `resolvePresignTransport` precedence: `HQ_SYNC_EVENT_SYNC`
- * overrides in both directions (`1`/`true`/`yes`/`on` → force on,
+ * Env-override-in-both-directions precedence: `HQ_SYNC_EVENT_SYNC`
+ * overrides (`1`/`true`/`yes`/`on` → force on,
  * `0`/`false`/`no`/`off` → force off) so unenrolled testers can exercise it
  * and enrolled accounts can be rolled back without a release. An unset/blank
  * override falls through to the exact-email check; an unrecognized override