@indigoai-us/hq-cloud 6.14.50 → 6.15.1

package/src/object-io.test.ts

@@ -1,1221 +0,0 @@
-/**
- * Unit tests for the ObjectIO transport seam.
- *
- * Focus is the PresignObjectIO path (the new transport): it talks to a
- * VaultClient-shaped stub for URL minting and a mocked global `fetch` for the
- * byte movement. The S3SdkObjectIO path is already covered transitively by
- * s3.test.ts (which exercises s3.ts through the default factory), plus a couple
- * of factory-selection tests here.
- */
-
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import * as http from "node:http";
-import { once } from "node:events";
-import { spawn } from "node:child_process";
-import {
-  PresignObjectIO,
-  S3SdkObjectIO,
-  setObjectIOFactory,
-  setPresignedGetTransportForTesting,
-  resolveObjectIO,
-  presignObjectIOFactory,
-  type PresignedGetTransport,
-  type PresignTransportClient,
-} from "./object-io.js";
-import type { EntityContext } from "./types.js";
-import type { PresignResultRow, VaultListedObject } from "./vault-client.js";
-import { isAccessDenied } from "./sync-core.js";
-
-const COMPANY = "cmp_test";
-
-function fetchBackedPresignedGetTransport(): PresignedGetTransport {
-  return {
-    async get(url, headers) {
-      const response = await fetch(url, { method: "GET", headers });
-      const body = response.body;
-      return {
-        status: response.status,
-        headers: response.headers,
-        body: body
-          ? (async function* (): AsyncIterable<Uint8Array> {
-              const reader = body.getReader();
-              let exhausted = false;
-              try {
-                while (true) {
-                  const { done, value } = await reader.read();
-                  if (done) {
-                    exhausted = true;
-                    return;
-                  }
-                  if (value.byteLength > 0) yield value;
-                }
-              } finally {
-                if (!exhausted) {
-                  try {
-                    await reader.cancel();
-                  } catch {
-                    // The response may already have been cancelled by destroy.
-                  }
-                }
-                reader.releaseLock();
-              }
-            })()
-          : undefined,
-        destroy: () => {
-          void body?.cancel().catch(() => undefined);
-        },
-      };
-    },
-  };
-}
-
-beforeEach(() => {
-  setPresignedGetTransportForTesting(fetchBackedPresignedGetTransport());
-});
-
-afterEach(() => {
-  setPresignedGetTransportForTesting(null);
-});
-
-function ctx(): EntityContext {
-  return {
-    uid: COMPANY,
-    slug: "test",
-    bucketName: "bucket-test",
-    region: "us-east-1",
-    credentials: {
-      accessKeyId: "AKIA",
-      secretAccessKey: "secret",
-      sessionToken: "token",
-    },
-    expiresAt: "2099-01-01T00:00:00.000Z",
-  };
-}
-
-/**
- * Minimal VaultClient stub. Each method returns whatever the per-test config
- * sets; presign records the inputs it was called with so tests can assert the
- * op/metadata/key shape the seam sends.
- */
-function makeVault() {
-  const presignCalls: Array<{
-    companyUid: string;
-    op?: string;
-    keys: unknown[];
-  }> = [];
-  let nextPresign: PresignResultRow[] = [];
-  let nextList: {
-    objects: VaultListedObject[];
-    cursor: string | null;
-    truncated: boolean;
-  } = { objects: [], cursor: null, truncated: false };
-
-  const vault: PresignTransportClient = {
-    presign: async (input) => {
-      presignCalls.push({
-        companyUid: input.companyUid,
-        op: input.op,
-        keys: input.keys,
-      });
-      return { results: nextPresign, expiresAt: "2099-01-01T00:00:00.000Z" };
-    },
-    listFiles: async () => nextList,
-  };
-
-  return {
-    vault,
-    presignCalls,
-    setPresign: (rows: PresignResultRow[]) => {
-      nextPresign = rows;
-    },
-    setList: (v: typeof nextList) => {
-      nextList = v;
-    },
-  };
-}
-
-describe("factory selection", () => {
-  afterEach(() => setObjectIOFactory(null));
-
-  it("defaults to the S3 SDK transport", () => {
-    const io = resolveObjectIO(ctx());
-    expect(io).toBeInstanceOf(S3SdkObjectIO);
-  });
-
-  it("setObjectIOFactory(null) resets to the default", () => {
-    const { vault } = makeVault();
-    setObjectIOFactory(presignObjectIOFactory(vault));
-    expect(resolveObjectIO(ctx())).toBeInstanceOf(PresignObjectIO);
-    setObjectIOFactory(null);
-    expect(resolveObjectIO(ctx())).toBeInstanceOf(S3SdkObjectIO);
-  });
-
-  it("presign factory derives companyUid from ctx.uid", async () => {
-    const { vault, presignCalls, setPresign } = makeVault();
-    setPresign([{ key: "k", op: "get", url: "https://x/get" }]);
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => new Response(Buffer.from("body"), { status: 200 })),
-    );
-    const io = presignObjectIOFactory(vault)(ctx());
-    await io.getObject("k");
-    expect(presignCalls[0].companyUid).toBe(COMPANY);
-    vi.unstubAllGlobals();
-  });
-});
-
-describe("S3SdkObjectIO.putObject — conditional-write fence", () => {
-  it("maps ifMatch (re-quoted) and ifNoneMatch onto the PutObjectCommand", async () => {
-    const io = new S3SdkObjectIO(ctx());
-    const sent: Array<Record<string, unknown>> = [];
-    // Swap the private client for a recorder — the fence mapping is pure
-    // input-shaping, no wire needed.
-    (io as unknown as { client: { send: (c: { input: Record<string, unknown> }) => Promise<unknown> } }).client = {
-      send: async (cmd) => {
-        sent.push(cmd.input);
-        return { ETag: '"landed"' };
-      },
-    };
-    await io.putObject({ key: "a", body: Buffer.from("x"), contentType: "t", ifMatch: "abc" });
-    expect(sent[0].IfMatch).toBe('"abc"'); // stripped etags re-quoted for If-Match
-    await io.putObject({ key: "a2", body: Buffer.from("x"), contentType: "t", ifMatch: '"quoted"' });
-    expect(sent[1].IfMatch).toBe('"quoted"'); // already-quoted passes through
-    await io.putObject({ key: "b", body: Buffer.from("y"), contentType: "t", ifNoneMatch: "*" });
-    expect(sent[2].IfNoneMatch).toBe("*");
-    await io.putObject({ key: "c", body: Buffer.from("z"), contentType: "t" });
-    expect(sent[3].IfMatch).toBeUndefined(); // unfenced PUT stays unfenced
-    expect(sent[3].IfNoneMatch).toBeUndefined();
-  });
-});
-
-describe("PresignObjectIO.putObject", () => {
-  let fetchMock: ReturnType<typeof vi.fn>;
-  beforeEach(() => {
-    fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-  });
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("sends op:put with metadata and replays the signed headers verbatim", async () => {
-    const { vault, presignCalls, setPresign } = makeVault();
-    setPresign([
-      {
-        key: "shared/a.md",
-        op: "put",
-        url: "https://s3/put-url",
-        headers: {
-          "content-type": "text/markdown",
-          "x-amz-server-side-encryption": "aws:kms",
-          "x-amz-meta-created-by": "me@getindigo.ai",
-        },
-      },
-    ]);
-    fetchMock.mockResolvedValue(
-      new Response(null, { status: 200, headers: { etag: '"abc123"' } }),
-    );
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const res = await io.putObject({
-      key: "shared/a.md",
-      body: Buffer.from("hello"),
-      contentType: "text/markdown",
-      metadata: { "created-by": "me@getindigo.ai" },
-    });
-
-    // Presign request carried op + per-key metadata.
-    expect(presignCalls[0].op).toBe("put");
-    expect(presignCalls[0].keys[0]).toMatchObject({
-      key: "shared/a.md",
-      op: "put",
-      contentType: "text/markdown",
-      metadata: { "created-by": "me@getindigo.ai" },
-    });
-
-    // PUT replays the exact signed headers.
-    const [url, init] = fetchMock.mock.calls[0];
-    expect(url).toBe("https://s3/put-url");
-    expect(init.method).toBe("PUT");
-    expect(init.headers).toEqual({
-      "content-type": "text/markdown",
-      "x-amz-server-side-encryption": "aws:kms",
-      "x-amz-meta-created-by": "me@getindigo.ai",
-    });
-    // ETag returned with quotes stripped.
-    expect(res.etag).toBe("abc123");
-  });
-
-  it("throws on a per-key denial (error row)", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([
-      { key: "secret/x", op: "put", error: "forbidden", code: "ACL_DENY" },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(
-      io.putObject({
-        key: "secret/x",
-        body: Buffer.from("z"),
-        contentType: "text/plain",
-      }),
-    ).rejects.toThrow(/denied for secret\/x.*forbidden.*ACL_DENY/);
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("a write denial (FILES_PRESIGN_FORBIDDEN) throws the access-denied shape so the push skips it like a denied GET", async () => {
-    const { vault, setPresign } = makeVault();
-    // The server refuses to MINT a PUT URL for a key the caller can't write
-    // (private-by-default: members hold read-only on a shared knowledge prefix).
-    setPresign([
-      {
-        key: "knowledge/clients/acme/brief.md",
-        op: "put",
-        error: "Caller lacks write permission on 'knowledge/clients/acme/brief.md'",
-        code: "FILES_PRESIGN_FORBIDDEN",
-      },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    let caught: unknown;
-    await io
-      .putObject({
-        key: "knowledge/clients/acme/brief.md",
-        body: Buffer.from("z"),
-        contentType: "text/markdown",
-      })
-      .catch((e) => {
-        caught = e;
-      });
-    // Same shape a denied GET/HEAD already throws (name === "Forbidden"), so the
-    // share.ts push catch routes it through `isAccessDenied` into the silent
-    // per-path skip (scopeExcludedSet) + the "N paths skipped — outside your
-    // granted access" aggregate, instead of a fatal `type:"error"` that exits
-    // the runner non-zero and floods Sentry. This is the PUT/GET symmetry that
-    // fixes the presign-put-denied crash-loop across user machines.
-    expect((caught as Error).name).toBe("Forbidden");
-    expect(isAccessDenied(caught)).toBe(true);
-    // Denied at mint time — the byte-moving PUT is never attempted.
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("US-006 AC5: a transcript-consent denial (FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED) is skip-with-log, not fatal", async () => {
-    const { vault, setPresign } = makeVault();
-    // The US-005 consent code ends `_REQUIRED`, not `_FORBIDDEN`, so the plain
-    // suffix test alone would MISS it and let it fall through to the fatal
-    // generic Error — the recurring partial-failure this AC5 fix prevents.
-    setPresign([
-      {
-        key: "sessions/prs_1/2026-07-11T10-00-00.json",
-        op: "get",
-        error: "transcript consent required",
-        code: "FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED",
-      },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    // Monkeypatch console.warn (vitest's console interception can shadow a spy)
-    // to assert the REAL skip log fires.
-    const warnings: string[] = [];
-    const originalWarn = console.warn;
-    console.warn = (...args: unknown[]) => {
-      warnings.push(args.map(String).join(" "));
-    };
-    let caught: unknown;
-    try {
-      await io
-        .getObject("sessions/prs_1/2026-07-11T10-00-00.json")
-        .catch((e) => {
-          caught = e;
-        });
-    } finally {
-      console.warn = originalWarn;
-    }
-    // Same shape a denied GET already throws → isAccessDenied → the per-key
-    // scope-excluded skip, NOT a fatal `type:"error"` that poisons the run.
-    expect((caught as Error).name).toBe("Forbidden");
-    expect(isAccessDenied(caught)).toBe(true);
-    // A one-line skip log fires so operators can see WHY the key was skipped.
-    expect(
-      warnings.some((w) =>
-        w.includes("FILES_PRESIGN_TRANSCRIPT_CONSENT_REQUIRED"),
-      ),
-    ).toBe(true);
-  });
-
-  it("US-006 AC5: a sessions structural-ACL denial (FILES_PRESIGN_SESSIONS_FORBIDDEN) is skip-with-log", async () => {
-    const { vault, setPresign } = makeVault();
-    // A spoofed/foreign `sessions/{uid}/` prefix the hq-pro structural gate
-    // refuses to presign. Ends `_FORBIDDEN`, so the suffix test already covers
-    // it — this pins that coverage as a regression contract for US-006.
-    setPresign([
-      {
-        key: "sessions/prs_other/y.json",
-        op: "get",
-        error: "not your session prefix",
-        code: "FILES_PRESIGN_SESSIONS_FORBIDDEN",
-      },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    let caught: unknown;
-    await io.getObject("sessions/prs_other/y.json").catch((e) => {
-      caught = e;
-    });
-    expect((caught as Error).name).toBe("Forbidden");
-    expect(isAccessDenied(caught)).toBe(true);
-  });
-
-  it("a non-authorization presign failure stays a generic (fatal) error — not silently skipped", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([
-      { key: "secret/x", op: "put", error: "boom", code: "PRESIGN_INTERNAL" },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    let caught: unknown;
-    await io
-      .putObject({ key: "secret/x", body: Buffer.from("z"), contentType: "x" })
-      .catch((e) => {
-        caught = e;
-      });
-    // Only `*_FORBIDDEN` authorization denials are reclassified; a real backend
-    // failure must still surface loudly so it is not masked as an expected skip.
-    expect(isAccessDenied(caught)).toBe(false);
-    expect((caught as Error).message).toMatch(/denied for secret\/x.*PRESIGN_INTERNAL/);
-  });
-
-  it("throws when the PUT itself fails", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "k", op: "put", url: "https://s3/put" }]);
-    fetchMock.mockResolvedValue(new Response("AccessDenied", { status: 403 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(
-      io.putObject({ key: "k", body: Buffer.from("z"), contentType: "x" }),
-    ).rejects.toThrow(/presigned PUT failed for k: 403/);
-  });
-
-  it("F01: fails closed when a fenced PUT presign omits If-Match", async () => {
-    const previous = process.env.HQ_PRESIGN_FENCE_STRICT;
-    process.env.HQ_PRESIGN_FENCE_STRICT = "true";
-    try {
-      const { vault, setPresign } = makeVault();
-      setPresign([
-        {
-          key: "stale.md",
-          op: "put",
-          url: "https://s3/unfenced-put",
-          headers: { "content-type": "text/markdown" },
-        },
-      ]);
-      fetchMock.mockResolvedValue(
-        new Response(null, { status: 200, headers: { etag: '"v2"' } }),
-      );
-
-      const io = new PresignObjectIO(vault, COMPANY);
-      await expect(
-        io.putObject({
-          key: "stale.md",
-          body: Buffer.from("old bytes"),
-          contentType: "text/markdown",
-          ifMatch: '"v1"',
-        }),
-      ).rejects.toThrow(/if-match|condition|precondition/i);
-      expect(fetchMock).not.toHaveBeenCalled();
-    } finally {
-      if (previous === undefined) {
-        delete process.env.HQ_PRESIGN_FENCE_STRICT;
-      } else {
-        process.env.HQ_PRESIGN_FENCE_STRICT = previous;
-      }
-    }
-  });
-
-  it("F01: does not satisfy a fenced PUT with an unfenced primed URL", async () => {
-    const presignCalls: Array<Parameters<PresignTransportClient["presign"]>[0]> = [];
-    const vault: PresignTransportClient = {
-      presign: async (input) => {
-        presignCalls.push(input);
-        const isFenced = input.keys.some((k) => k.ifNoneMatch === "*");
-        return {
-          results: input.keys.map((k): PresignResultRow => ({
-            key: k.key,
-            op: k.op ?? input.op ?? "put",
-            url: isFenced ? "https://s3/fenced-put" : "https://s3/unfenced-put",
-            headers: isFenced
-              ? { "content-type": "text/plain", "if-none-match": "*" }
-              : { "content-type": "text/plain" },
-            expiresIn: 900,
-          })),
-          expiresAt: "2099-01-01T00:00:00.000Z",
-        };
-      },
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-    fetchMock.mockResolvedValue(
-      new Response(null, { status: 200, headers: { etag: '"created"' } }),
-    );
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("put", [{ key: "new.md", op: "put", contentType: "text/plain" }]);
-    const afterPrime = presignCalls.length;
-
-    await io.putObject({
-      key: "new.md",
-      body: Buffer.from("new bytes"),
-      contentType: "text/plain",
-      ifNoneMatch: "*",
-    });
-
-    expect(presignCalls).toHaveLength(afterPrime + 1);
-    expect(presignCalls[afterPrime].keys[0]).toMatchObject({
-      key: "new.md",
-      op: "put",
-      ifNoneMatch: "*",
-    });
-    const [url, init] = fetchMock.mock.calls[0];
-    expect(url).toBe("https://s3/fenced-put");
-    expect(init.headers).toEqual({
-      "content-type": "text/plain",
-      "if-none-match": "*",
-    });
-  });
-
-  it("forwards the conditional-write fence on the presign request (ifMatch stripped, ifNoneMatch verbatim)", async () => {
-    // The server signs If-Match/If-None-Match into the URL (hq-pro follow-up)
-    // and echoes the headers for replay; the client's job is to ASK. Servers
-    // that predate the fields ignore them — never broken, just unconditional.
-    const { vault, presignCalls, setPresign } = makeVault();
-    setPresign([{ key: "fenced.md", op: "put", url: "https://s3/put-url" }]);
-    fetchMock.mockResolvedValue(
-      new Response(null, { status: 200, headers: { etag: '"v2"' } }),
-    );
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.putObject({
-      key: "fenced.md",
-      body: Buffer.from("x"),
-      contentType: "text/markdown",
-      ifMatch: '"v1"',
-    });
-    expect(presignCalls[0].keys[0]).toMatchObject({
-      key: "fenced.md",
-      op: "put",
-      ifMatch: "v1", // quotes stripped on the wire; server re-quotes when signing
-    });
-
-    await io.putObject({
-      key: "fresh.md",
-      body: Buffer.from("y"),
-      contentType: "text/markdown",
-      ifNoneMatch: "*",
-    });
-    expect(presignCalls[1].keys[0]).toMatchObject({
-      key: "fresh.md",
-      op: "put",
-      ifNoneMatch: "*",
-    });
-  });
-
-  it("maps a 412 PUT response to name:PreconditionFailed (the fence fired — conflict, not failure)", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "raced.md", op: "put", url: "https://s3/put-url" }]);
-    fetchMock.mockResolvedValue(
-      new Response("PreconditionFailed", { status: 412 }),
-    );
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(
-      io.putObject({
-        key: "raced.md",
-        body: Buffer.from("z"),
-        contentType: "text/plain",
-        ifMatch: "old-etag",
-      }),
-    ).rejects.toMatchObject({ name: "PreconditionFailed" });
-  });
-});
-
-describe("PresignObjectIO.getObject", () => {
-  let fetchMock: ReturnType<typeof vi.fn>;
-  beforeEach(() => {
-    fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-  });
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("returns body bytes + x-amz-meta-* metadata", async () => {
-    const { vault, presignCalls, setPresign } = makeVault();
-    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(
-      new Response(Buffer.from("file-bytes"), {
-        status: 200,
-        headers: {
-          "x-amz-meta-created-by": "me@getindigo.ai",
-          "x-amz-meta-hq-mode": "640",
-          "content-type": "text/markdown",
-        },
-      }),
-    );
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const res = await io.getObject("shared/a.md");
-
-    expect(presignCalls[0].op).toBe("get");
-    expect(res.body.toString("utf-8")).toBe("file-bytes");
-    expect(res.metadata).toEqual({
-      "created-by": "me@getindigo.ai",
-      "hq-mode": "640",
-    });
-  });
-
-  it("drains the injected transport body instead of returning empty content", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
-    const transportGet = vi.fn(async () => ({
-      status: 200,
-      headers: new Headers({ "x-amz-meta-source": "transport" }),
-      body: (async function* (): AsyncIterable<Uint8Array> {
-        yield Buffer.from("transport-bytes");
-      })(),
-      destroy: () => undefined,
-    }));
-    setPresignedGetTransportForTesting({ get: transportGet });
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const res = await io.getObject("shared/a.md");
-
-    expect(res.body.toString("utf-8")).toBe("transport-bytes");
-    expect(res.metadata).toEqual({ source: "transport" });
-    expect(transportGet).toHaveBeenCalledWith("https://s3/get", undefined);
-  });
-
-  it("throws a NotFound-named error on 404 (so s3.ts catch sites match)", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "gone", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(io.getObject("gone")).rejects.toMatchObject({
-      name: "NotFound",
-    });
-  });
-});
-
-describe("PresignObjectIO.listObjects", () => {
-  it("maps listFiles rows into the RemoteObject shape (etag, Date)", async () => {
-    const { vault, setList } = makeVault();
-    setList({
-      objects: [
-        {
-          key: "shared/a.md",
-          size: 12,
-          lastModified: "2026-01-01T00:00:00.000Z",
-          etag: "deadbeef",
-          permission: "read",
-        },
-        {
-          key: "shared/b.md",
-          size: 0,
-          lastModified: null,
-          etag: null,
-          permission: "write",
-        },
-      ],
-      cursor: "next-token",
-      truncated: true,
-    });
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const res = await io.listObjects({ prefix: "shared/" });
-
-    expect(res.nextContinuationToken).toBe("next-token");
-    expect(res.objects[0]).toEqual({
-      key: "shared/a.md",
-      size: 12,
-      lastModified: new Date("2026-01-01T00:00:00.000Z"),
-      etag: "deadbeef",
-    });
-    // null etag → "" ; null lastModified → a Date (not crash).
-    expect(res.objects[1].etag).toBe("");
-    expect(res.objects[1].lastModified).toBeInstanceOf(Date);
-  });
-
-  it("exhausted listing yields undefined nextContinuationToken", async () => {
-    const { vault, setList } = makeVault();
-    setList({ objects: [], cursor: null, truncated: false });
-    const io = new PresignObjectIO(vault, COMPANY);
-    const res = await io.listObjects({});
-    expect(res.nextContinuationToken).toBeUndefined();
-  });
-});
-
-describe("PresignObjectIO.deleteObject", () => {
-  let fetchMock: ReturnType<typeof vi.fn>;
-  beforeEach(() => {
-    fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-  });
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("sends op:delete and DELETEs the signed URL", async () => {
-    const { vault, presignCalls, setPresign } = makeVault();
-    setPresign([{ key: "shared/a.md", op: "delete", url: "https://s3/del" }]);
-    fetchMock.mockResolvedValue(new Response(null, { status: 204 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.deleteObject("shared/a.md");
-    expect(presignCalls[0].op).toBe("delete");
-    expect(fetchMock.mock.calls[0][1].method).toBe("DELETE");
-  });
-
-  it("treats a 404 DELETE as success (idempotent)", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "gone", op: "delete", url: "https://s3/del" }]);
-    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(io.deleteObject("gone")).resolves.toBeUndefined();
-  });
-});
-
-describe("PresignObjectIO.headObject", () => {
-  let fetchMock: ReturnType<typeof vi.fn>;
-  beforeEach(() => {
-    fetchMock = vi.fn();
-    vi.stubGlobal("fetch", fetchMock);
-  });
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("reads headers (etag/size/lastModified/metadata) via a presigned GET", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(
-      new Response(Buffer.from("ignored-body"), {
-        status: 200,
-        headers: {
-          etag: '"feedface"',
-          "content-length": "123",
-          "last-modified": "Wed, 01 Jan 2026 00:00:00 GMT",
-          "x-amz-meta-created-at": "2026-01-01T00:00:00.000Z",
-        },
-      }),
-    );
-    const io = new PresignObjectIO(vault, COMPANY);
-    const head = await io.headObject("shared/a.md");
-    expect(head).not.toBeNull();
-    expect(head!.etag).toBe("feedface");
-    expect(head!.size).toBe(123);
-    expect(head!.metadata).toEqual({
-      "created-at": "2026-01-01T00:00:00.000Z",
-    });
-    expect(head!.lastModified.getTime()).toBe(
-      Date.parse("Wed, 01 Jan 2026 00:00:00 GMT"),
-    );
-  });
-
-  it("returns null on 404", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "gone", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    expect(await io.headObject("gone")).toBeNull();
-  });
-
-  it("returns null on a server-confirmed FILES_PRESIGN_NOT_FOUND (absence, not denial — no GET issued)", async () => {
-    // The presign lambda HEAD'd S3 and confirmed absence. Unlike a read
-    // DENIAL (Forbidden, below), this is unambiguous "object missing", so
-    // headObject reports absent (null) and the push creates the new object —
-    // never reaching a 403-masked presigned GET.
-    const { vault, setPresign } = makeVault();
-    setPresign([
-      {
-        key: "new.md",
-        op: "get",
-        error: "Object not found: 'new.md'",
-        code: "FILES_PRESIGN_NOT_FOUND",
-      },
-    ]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    expect(await io.headObject("new.md")).toBeNull();
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("throws Forbidden when presign denies the key — denial is NOT absence", async () => {
-    // Regression: pre-fix this returned null ("absent"), which made
-    // share.ts's push guard (`if (remoteMeta)`) skip every conflict check
-    // and issue an unconditional PUT — a transient denial mid-pass silently
-    // clobbered newer remote bytes (2026-06-10..12 vault regression storm).
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "secret/x", op: "get", error: "forbidden" }]);
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(io.headObject("secret/x")).rejects.toMatchObject({
-      name: "Forbidden",
-    });
-    expect(fetchMock).not.toHaveBeenCalled();
-  });
-
-  it("throws Forbidden on a presigned-GET 403 — same SDK-parity contract", async () => {
-    // Expired presigned URL, expired signing creds, KMS or bucket-policy
-    // denial all surface as 403 on the signed GET. Unknown state — must
-    // never read as "object missing".
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "shared/a.md", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(new Response("AccessDenied", { status: 403 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(io.headObject("shared/a.md")).rejects.toMatchObject({
-      name: "Forbidden",
-    });
-  });
-
-  it("still returns null on a definitive 404 (key truly absent)", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "gone2", op: "get", url: "https://s3/get" }]);
-    fetchMock.mockResolvedValue(new Response("", { status: 404 }));
-    const io = new PresignObjectIO(vault, COMPANY);
-    expect(await io.headObject("gone2")).toBeNull();
-  });
-});
-
-/**
- * Echo vault: presign returns one signed row per requested key (url derived
- * from op+key) and records call count + total keys, so prime/cache tests can
- * assert "N files → ceil(N/100) presign calls, then zero".
- */
-function makeEchoVault() {
-  let calls = 0;
-  let totalKeys = 0;
-  const vault: PresignTransportClient = {
-    presign: async (input) => {
-      calls++;
-      totalKeys += input.keys.length;
-      return {
-        results: input.keys.map((k) => ({
-          key: k.key,
-          op: k.op ?? input.op ?? "get",
-          url: `https://signed/${k.op ?? input.op}/${encodeURIComponent(k.key)}`,
-          ...(k.op === "put" || input.op === "put"
-            ? { headers: { "content-type": "text/plain" } }
-            : {}),
-          expiresIn: input.expiresIn ?? 900,
-        })),
-        expiresAt: "2099-01-01T00:00:00.000Z",
-      };
-    },
-    listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-  };
-  return {
-    vault,
-    calls: () => calls,
-    totalKeys: () => totalKeys,
-  };
-}
-
-describe("PresignObjectIO.prime — batch URL cache", () => {
-  let fetchMock: ReturnType<typeof vi.fn>;
-  beforeEach(() => {
-    fetchMock = vi.fn(async () => new Response(Buffer.from("x"), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-  });
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("chunks at 1000 keys per presign call (the server batch cap)", async () => {
-    const { vault, calls, totalKeys } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    const keys = Array.from({ length: 2500 }, (_, i) => ({ key: `k${i}` }));
-    await io.prime("get", keys);
-    expect(calls()).toBe(3); // 1000 + 1000 + 500
-    expect(totalKeys()).toBe(2500);
-  });
-
-  it("primed getObject reuses the cache — zero extra presign calls", async () => {
-    const { vault, calls } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    const keys = Array.from({ length: 5 }, (_, i) => ({ key: `f${i}` }));
-    await io.prime("get", keys);
-    const afterPrime = calls(); // 1 chunk
-    for (const k of keys) await io.getObject(k.key);
-    expect(calls()).toBe(afterPrime); // no new presign calls
-    expect(fetchMock).toHaveBeenCalledTimes(5); // but the bytes were fetched
-    // The fetched URL is the primed (cached) one.
-    expect(fetchMock.mock.calls[0][0]).toBe("https://signed/get/f0");
-  });
-
-  it("F21: consumes primed GET URLs instead of retaining them", async () => {
-    const { vault, calls } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("get", [{ key: "single" }]);
-    const afterPrime = calls();
-
-    await io.getObject("single");
-    expect(calls()).toBe(afterPrime);
-
-    await io.getObject("single");
-    expect(calls()).toBe(afterPrime + 1);
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("R-F21: reuses a primed GET for later HEAD and clears stale primed PUT on fenced PUT", async () => {
-    fetchMock.mockImplementation(async () => (
-      new Response(Buffer.from("body"), {
-        status: 200,
-        headers: {
-          etag: '"etag-1"',
-          "content-length": "4",
-          "last-modified": "Wed, 01 Jan 2026 00:00:00 GMT",
-        },
-      })
-    ));
-    const { vault, calls } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-
-    await io.prime("get", [{ key: "doc.md" }]);
-    const afterGetPrime = calls();
-    const got = await io.getObject("doc.md");
-    expect(got.body.toString("utf-8")).toBe("body");
-
-    const head = await io.headObject("doc.md");
-    expect(head?.etag).toBe("etag-1");
-    expect(calls()).toBe(afterGetPrime);
-    expect(fetchMock.mock.calls[0][0]).toBe("https://signed/get/doc.md");
-    expect(fetchMock.mock.calls[1][0]).toBe("https://signed/get/doc.md");
-
-    await io.prime("put", [
-      { key: "stale.md", op: "put", contentType: "text/plain" },
-    ]);
-    expect(io.hasPrimedPut("stale.md")).toBe(true);
-    const afterPutPrime = calls();
-
-    await io.putObject({
-      key: "stale.md",
-      body: Buffer.from("new body"),
-      contentType: "text/plain",
-      ifMatch: "old-etag",
-    });
-
-    expect(calls()).toBe(afterPutPrime + 1);
-    expect(io.hasPrimedPut("stale.md")).toBe(false);
-  });
-
-  it("primed GET cache also serves headObject (HEAD reuses GET URLs)", async () => {
-    const { vault, calls } = makeEchoVault();
-    fetchMock.mockResolvedValue(
-      new Response(Buffer.from(""), {
-        status: 200,
-        headers: { etag: '"e"', "content-length": "0" },
-      }),
-    );
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("get", [{ key: "doc.md" }]);
-    const afterPrime = calls();
-    const head = await io.headObject("doc.md");
-    expect(head).not.toBeNull();
-    expect(calls()).toBe(afterPrime); // head used the cached GET url, no presign
-  });
-
-  it("a key NOT primed falls back to a single presign", async () => {
-    const { vault, calls } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("get", [{ key: "primed" }]);
-    const afterPrime = calls();
-    await io.getObject("not-primed");
-    expect(calls()).toBe(afterPrime + 1);
-  });
-
-  it("empty prime is a no-op (no presign call)", async () => {
-    const { vault, calls } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("get", []);
-    expect(calls()).toBe(0);
-  });
-
-  it("a chunk that throws doesn't fail prime; those keys fall back per-file", async () => {
-    let calls = 0;
-    const vault: PresignTransportClient = {
-      presign: async (input) => {
-        calls++;
-        if (calls === 1) throw new Error("transient");
-        return {
-          results: input.keys.map((k) => ({
-            key: k.key,
-            op: "get" as const,
-            url: `https://signed/get/${k.key}`,
-            expiresIn: 900,
-          })),
-          expiresAt: "2099-01-01T00:00:00.000Z",
-        };
-      },
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-    const io = new PresignObjectIO(vault, COMPANY);
-    // Single chunk that throws — prime resolves anyway, key stays uncached.
-    await expect(io.prime("get", [{ key: "k" }])).resolves.toBeUndefined();
-    // getObject then single-presigns (call #2 succeeds).
-    await io.getObject("k");
-    expect(calls).toBe(2);
-  });
-});
-
-describe("presignObjectIOFactory — memoization", () => {
-  afterEach(() => setObjectIOFactory(null));
-  it("returns the SAME instance per companyUid so prime + transfer share a cache", () => {
-    const { vault } = makeEchoVault();
-    const factory = presignObjectIOFactory(vault);
-    const a1 = factory(ctx());
-    const a2 = factory(ctx());
-    expect(a1).toBe(a2); // same company → same instance
-    const other = factory({ ...ctx(), uid: "cmp_other" });
-    expect(other).not.toBe(a1); // different company → different instance
-  });
-});
-
-describe("PresignObjectIO — transient-failure retry (SDK parity)", () => {
-  afterEach(() => {
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-  });
-
-  it("retries a transient 503 then succeeds", async () => {
-    vi.useFakeTimers();
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "k", op: "get", url: "https://s3/get" }]);
-    const fetchMock = vi
-      .fn()
-      .mockResolvedValueOnce(new Response("SlowDown", { status: 503 }))
-      .mockResolvedValueOnce(new Response(Buffer.from("ok"), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const pr = io.getObject("k");
-    await vi.runAllTimersAsync();
-    const res = await pr;
-    expect(res.body.toString("utf-8")).toBe("ok");
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("retries a network error (fetch throws) then succeeds", async () => {
-    vi.useFakeTimers();
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "k", op: "get", url: "https://s3/get" }]);
-    const fetchMock = vi
-      .fn()
-      .mockRejectedValueOnce(new Error("socket hang up"))
-      .mockResolvedValueOnce(new Response(Buffer.from("ok"), { status: 200 }));
-    vi.stubGlobal("fetch", fetchMock);
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const pr = io.getObject("k");
-    await vi.runAllTimersAsync();
-    const res = await pr;
-    expect(res.body.toString("utf-8")).toBe("ok");
-    expect(fetchMock).toHaveBeenCalledTimes(2);
-  });
-
-  it("throws after exhausting retries on persistent 503 (initial + 3 retries = 4)", async () => {
-    vi.useFakeTimers();
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "k", op: "get", url: "https://s3/get" }]);
-    const fetchMock = vi.fn().mockResolvedValue(new Response("err", { status: 503 }));
-    vi.stubGlobal("fetch", fetchMock);
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    const pr = io.getObject("k").catch((e) => e);
-    await vi.runAllTimersAsync();
-    const err = await pr;
-    expect(String(err)).toMatch(/503/);
-    expect(fetchMock).toHaveBeenCalledTimes(4);
-  });
-
-  it("does NOT retry a definitive 404", async () => {
-    const { vault, setPresign } = makeVault();
-    setPresign([{ key: "gone", op: "get", url: "https://s3/get" }]);
-    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 404 }));
-    vi.stubGlobal("fetch", fetchMock);
-
-    const io = new PresignObjectIO(vault, COMPANY);
-    await expect(io.getObject("gone")).rejects.toMatchObject({ name: "NotFound" });
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-  });
-});
-
-import { VaultClientError } from "./vault-client.js";
-
-describe("PresignObjectIO — 429 circuit breaker", () => {
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("trips on a 429: uncached keys fail fast (no further presign), primed keys still work", async () => {
-    let presignCalls = 0;
-    const vault: PresignTransportClient = {
-      presign: async (input) => {
-        presignCalls++;
-        if (input.keys.some((k) => k.key === "primed")) {
-          return {
-            results: input.keys.map((k) => ({
-              key: k.key,
-              op: k.op ?? "get",
-              url: `https://s/${k.key}`,
-              expiresIn: 900,
-            })),
-            expiresAt: "2099-01-01T00:00:00.000Z",
-          };
-        }
-        throw new VaultClientError("Rate limit exceeded: 100 requests per hour", 429);
-      },
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => new Response(Buffer.from("x"), { status: 200 })),
-    );
-    const io = new PresignObjectIO(vault, COMPANY);
-    await io.prime("get", [{ key: "primed" }]); // caches "primed"
-
-    await expect(io.getObject("uncached1")).rejects.toMatchObject({
-      name: "RateLimited",
-    });
-    const afterTrip = presignCalls;
-    // Second uncached key fails fast — NO new presign call.
-    await expect(io.getObject("uncached2")).rejects.toMatchObject({
-      name: "RateLimited",
-    });
-    expect(presignCalls).toBe(afterTrip);
-    // The primed key still resolves from cache (no presign needed).
-    const r = await io.getObject("primed");
-    expect(r.body.toString("utf-8")).toBe("x");
-  });
-
-  it("prime stops minting once a chunk 429s (breaker trips, remaining chunks skipped)", async () => {
-    let calls = 0;
-    const vault: PresignTransportClient = {
-      presign: async () => {
-        calls++;
-        throw new VaultClientError("rate", 429);
-      },
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-    const io = new PresignObjectIO(vault, COMPANY);
-    // 10 chunks (10k keys @ 1000); concurrency is 4, so at most the first
-    // concurrent batch fires before the breaker trips — far fewer than 10.
-    await io.prime(
-      "get",
-      Array.from({ length: 10_000 }, (_, i) => ({ key: `k${i}` })),
-    );
-    expect(calls).toBeLessThanOrEqual(4);
-    expect(calls).toBeLessThan(10);
-  });
-});
-
-describe("PresignObjectIO.hasPrimedPut", () => {
-  it("reflects a put prime", async () => {
-    const { vault } = makeEchoVault();
-    const io = new PresignObjectIO(vault, COMPANY);
-    expect(io.hasPrimedPut("k")).toBe(false);
-    await io.prime("put", [
-      { key: "k", op: "put", contentType: "text/plain", metadata: { "hq-mode": "644" } },
-    ]);
-    expect(io.hasPrimedPut("k")).toBe(true);
-    // A different, unprimed key stays false.
-    expect(io.hasPrimedPut("other")).toBe(false);
-  });
-});
-
-describe("presignObjectIOFactory — personal vaults route to S3 SDK", () => {
-  it("routes a person entity (prs_*) to S3SdkObjectIO, a company (cmp_*) to presign", () => {
-    const { vault } = makeEchoVault();
-    const factory = presignObjectIOFactory(vault);
-    const company = factory({ ...ctx(), uid: "cmp_real" });
-    const personal = factory({ ...ctx(), uid: "prs_real" });
-    expect(company).toBeInstanceOf(PresignObjectIO);
-    // Personal vaults use the membership-less vend-self model; the
-    // membership-gated presign endpoints 403 for them, so they stay on STS.
-    expect(personal).toBeInstanceOf(S3SdkObjectIO);
-  });
-});
-
-describe("PresignObjectIO — core HTTP presigned GET", () => {
-  function streamingVault(baseUrl: string): PresignTransportClient {
-    return {
-      presign: async (input) => ({
-        results: input.keys.map((key) => ({
-          key: key.key,
-          op: "get" as const,
-          url: `${baseUrl}/${key.key}`,
-        })),
-        expiresAt: "2099-01-01T00:00:00.000Z",
-      }),
-      listFiles: async () => ({ objects: [], cursor: null, truncated: false }),
-    };
-  }
-
-  it("destroys an early-exit response and rejects a FIN-short body", async () => {
-    setPresignedGetTransportForTesting(null);
-    let responseClosed: Promise<unknown> | undefined;
-    const server = http.createServer((req, res) => {
-      if (req.url === "/short") {
-        res.writeHead(200, { "content-length": "10" });
-        res.end("short");
-        return;
-      }
-
-      res.writeHead(200, { "content-length": "131072" });
-      res.write(Buffer.alloc(65_536, 1));
-      responseClosed = once(res, "close");
-      const finish = setTimeout(() => res.end(Buffer.alloc(65_536, 2)), 1_000);
-      res.once("close", () => clearTimeout(finish));
-    });
-    server.listen(0, "127.0.0.1");
-    await once(server, "listening");
-    const address = server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("test server did not bind a TCP port");
-    }
-
-    try {
-      const io = new PresignObjectIO(
-        streamingVault(`http://127.0.0.1:${address.port}`),
-        COMPANY,
-      );
-      const streamed = await io.getObjectStream("large");
-      const iterator = streamed.body[Symbol.asyncIterator]();
-      expect((await iterator.next()).value).toBeInstanceOf(Uint8Array);
-      await iterator.return?.();
-      if (!responseClosed) throw new Error("response did not start streaming");
-      await expect(responseClosed).resolves.toBeDefined();
-
-      await expect(io.getObject("short")).rejects.toThrow(
-        /content-length mismatch/,
-      );
-    } finally {
-      server.close();
-      await once(server, "close");
-    }
-  });
-
-  it.runIf(
-    process.platform === "win32" && /^(22|24)\./.test(process.versions.node),
-  )("keeps a child FIN safe after the consumer has applied backpressure", async () => {
-    setPresignedGetTransportForTesting(null);
-    const child = spawn(process.execPath, [
-      "-e",
-      [
-        "const http = require('node:http');",
-        "const body = Buffer.alloc(524288, 7);",
-        "const server = http.createServer((_req, res) => {",
-        "  res.writeHead(200, { 'content-length': String(body.length) });",
-        "  for (let offset = 0; offset < body.length; offset += 16384) res.write(body.subarray(offset, offset + 16384));",
-        "  res.end();",
-        "});",
-        "server.listen(0, '127.0.0.1', () => process.stdout.write(String(server.address().port) + '\\n'));",
-        "process.on('SIGTERM', () => server.close(() => process.exit(0)));",
-      ].join("\n"),
-    ], { stdio: ["ignore", "pipe", "inherit"] });
-
-    const port = await new Promise<number>((resolve, reject) => {
-      child.once("error", reject);
-      child.stdout?.once("data", (data: Buffer) => resolve(Number(data.toString())));
-      child.once("exit", (code) => reject(new Error(`child server exited (${code})`)));
-    });
-
-    try {
-      const io = new PresignObjectIO(
-        streamingVault(`http://127.0.0.1:${port}`),
-        COMPANY,
-      );
-      const streamed = await io.getObjectStream("bulk");
-      await new Promise((resolve) => setTimeout(resolve, 40));
-      let bytes = 0;
-      for await (const chunk of streamed.body) bytes += chunk.byteLength;
-      expect(bytes).toBe(524_288);
-    } finally {
-      child.kill("SIGTERM");
-    }
-  });
-});