@indigoai-us/hq-cloud 5.46.0 → 5.47.1

package/src/s3.ts

@@ -8,31 +8,14 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import {
-  S3Client,
-  PutObjectCommand,
-  GetObjectCommand,
-  ListObjectsV2Command,
-  DeleteObjectCommand,
-  HeadObjectCommand,
-} from "@aws-sdk/client-s3";
 import type { EntityContext } from "./types.js";
+import { resolveObjectIO, type ObjectIO } from "./object-io.js";
 
-/**
- * Build an S3Client from an EntityContext's STS-scoped credentials.
- * A new client is created each time to ensure fresh credentials are used
- * (the caller handles caching/refresh at the EntityContext level).
- */
-function buildClient(ctx: EntityContext): S3Client {
-  return new S3Client({
-    region: ctx.region,
-    credentials: {
-      accessKeyId: ctx.credentials.accessKeyId,
-      secretAccessKey: ctx.credentials.secretAccessKey,
-      sessionToken: ctx.credentials.sessionToken,
-    },
-  });
-}
+// Byte/metadata transport is resolved per-call via resolveObjectIO(ctx) — the
+// default is the AWS S3 SDK over STS-vended credentials (S3SdkObjectIO), but a
+// session may select the presigned-URL transport (PresignObjectIO) via
+// setObjectIOFactory. The symlink/mode/mtime/created-at semantics below are
+// transport-agnostic: they compose on top of the ObjectIO primitives.
 
 /**
  * Author identity stamped onto S3 user-defined metadata at upload time. The
@@ -247,114 +230,215 @@ export function encodeSymlinkBody(target: string): Buffer {
   return Buffer.from(SYMLINK_BODY_PREFIX + target, "utf-8");
 }
 
-export async function uploadFile(
+/**
+ * Batch pre-mint transport URLs for `keys` under `op` so the subsequent
+ * per-file transfer calls (downloadFile/headRemoteFile/…) reuse them instead
+ * of presigning one key at a time. On the presigned-URL transport this turns
+ * an N-file leg from N presign requests into ceil(N/100) — the difference
+ * between completing a bulk pull and 429ing past the 100-req/hr limit. No-op
+ * on the S3 SDK transport (which has no presign step) and harmless if called
+ * with an empty list. Best-effort: a prime failure never propagates — the
+ * per-file path falls back to a single presign.
+ *
+ * Call it once, right before a transfer loop, with the full key set the loop
+ * will touch. The presigned transport memoizes one IO instance per company for
+ * the run, so the warmed cache is the same one the loop drains.
+ */
+export async function primeObjectTransport(
   ctx: EntityContext,
-  localPath: string,
-  key: string,
-  author?: UploadAuthor,
-): Promise<{ etag: string }> {
-  const client = buildClient(ctx);
-  const body = fs.readFileSync(localPath);
+  op: "get" | "put" | "delete",
+  keys: string[],
+): Promise<void> {
+  if (keys.length === 0) return;
+  const io = resolveObjectIO(ctx);
+  if (!io.prime) return;
+  await io.prime(
+    op,
+    keys.map((key) => ({ key })),
+  );
+}
 
-  // Capture source-side file mode (permission bits only) for Bug #5 — see
-  // FILE_MODE_META_KEY doc. Best-effort: lstat failure (raced rm, EPERM)
-  // falls through to "no mode header" and the receiver keeps its umask
-  // default — same as the legacy back-compat path.
-  //
-  // 5.37.0: same lstat call also yields mtimeMs + birthtimeMs for the
-  // hq-mtime / hq-btime metadata headers. Single lstat keeps the syscall
-  // budget identical to 5.36.0; the additional metadata fields are pure
-  // in-memory work on the lstat result. Symlinks skip ALL THREE stamps
-  // — symlink mode is OS-controlled, symlink mtime isn't user-meaningful
-  // because the wire body is `hq-symlink:` + target (not real file
-  // content), and fs.utimesSync follows links so applying it on receive
-  // would mutate the target's mtime instead of the link's.
-  let modeOctal: string | undefined;
-  let mtimeMsStamp: string | undefined;
-  let btimeMsStamp: string | undefined;
-  try {
-    const lstat = fs.lstatSync(localPath);
-    if (!lstat.isSymbolicLink()) {
-      modeOctal = (lstat.mode & 0o777).toString(8);
-      // Math.floor truncates the sub-millisecond fractional component
-      // some filesystems report (APFS returns full ms+fraction; ext4
-      // is integer-ms). String(int) on the read side matches the
-      // strict-numeric regex `^-?[0-9]{1,16}$` — optional leading `-`,
-      // no leading zeros, no decimals, no exponents.
-      //
-      // Codex PR #27 P2: accept the full finite range, including 0
-      // (Unix epoch) and negatives (pre-epoch / reproducible-build
-      // clamping). Earlier `> 0` filter silently dropped legitimate
-      // timestamps and broke the round-trip guarantee for that subset.
-      const mtimeFloor = Math.floor(lstat.mtimeMs);
-      if (Number.isFinite(lstat.mtimeMs)) {
-        mtimeMsStamp = String(mtimeFloor);
-      }
-      // birthtimeMs filter: only stamp when the filesystem actually
-      // tracks a separate creation time. ext4 historically returns 0
-      // (unsupported) or equals mtimeMs (no distinct tracking); tmpfs
-      // and some FUSE mounts behave similarly. Filtering at the source
-      // keeps the metadata header free of noise — the receiver can
-      // assume hq-btime, if present, carries real signal.
-      //
-      // Compare the floored values (not raw lstat.birthtimeMs vs
-      // lstat.mtimeMs) because APFS exposes sub-millisecond fractions —
-      // two timestamps representing the "same moment" for sync purposes
-      // can differ by < 1 ms and pass a strict `!==` check while serializing
-      // to the same integer-ms string. Comparing floor-to-floor matches
-      // what we actually emit on the wire.
-      const btimeFloor = Math.floor(lstat.birthtimeMs);
-      if (
-        Number.isFinite(lstat.birthtimeMs) &&
-        btimeFloor > 0 &&
-        btimeFloor !== mtimeFloor
-      ) {
-        btimeMsStamp = String(btimeFloor);
-      }
-    }
-  } catch {
-    // Leave stamps undefined; receiver applies its umask default and
-    // leaves mtime at write-time (the legacy back-compat path).
+/**
+ * Source-side mode + mtime (+ btime when distinct) metadata for a regular
+ * file, from a single lstat. Symlinks carry none (OS-controlled mode; a link's
+ * mtime isn't user-meaningful — the wire body is the target string, not file
+ * content). Shared by uploadFile and the primeUploads pre-pass so the PUT
+ * metadata they produce is byte-identical. See the FILE_*_META_KEY docs for the
+ * per-field rationale.
+ */
+function buildModeTimeMetadata(lstat: fs.Stats): Record<string, string> {
+  const meta: Record<string, string> = {};
+  if (lstat.isSymbolicLink()) return meta;
+  meta[FILE_MODE_META_KEY] = (lstat.mode & 0o777).toString(8);
+  const mtimeFloor = Math.floor(lstat.mtimeMs);
+  if (Number.isFinite(lstat.mtimeMs)) meta[FILE_MTIME_META_KEY] = String(mtimeFloor);
+  const btimeFloor = Math.floor(lstat.birthtimeMs);
+  if (
+    Number.isFinite(lstat.birthtimeMs) &&
+    btimeFloor > 0 &&
+    btimeFloor !== mtimeFloor
+  ) {
+    meta[FILE_BTIME_META_KEY] = String(btimeFloor);
   }
+  return meta;
+}
 
-  // Preserve the original `created-at` across re-uploads when the object
-  // already exists with author metadata — same convention the hq-console
-  // upload route uses, so the NEW-pill ageing window doesn't reset on every
-  // sync tick. HEAD failure (NoSuchKey, perm, transient 5xx) falls through
-  // to "now", which is correct for a first upload.
+/**
+ * Resolve the created-at to stamp: the existing object's value (preserved
+ * across re-uploads so the hq-console NEW-pill window doesn't reset) or now for
+ * a first upload. HEAD failure / no author → now. Shared by upload* and
+ * primeUploads so both agree on the value signed into the PUT.
+ */
+async function resolveCreatedAt(
+  io: ObjectIO,
+  key: string,
+  author?: UploadAuthor,
+): Promise<string> {
   let createdAt = new Date().toISOString();
   if (author) {
     try {
-      const head = await client.send(
-        new HeadObjectCommand({ Bucket: ctx.bucketName, Key: key }),
-      );
-      const existing = head.Metadata?.["created-at"];
+      const head = await io.headObject(key);
+      const existing = head?.metadata?.["created-at"];
       if (typeof existing === "string" && existing.length > 0) {
         createdAt = existing;
       }
     } catch {
-      // Object doesn't exist yet, or HEAD denied — keep `now`.
+      // Object doesn't exist yet, or HEAD failed — keep now (first upload).
+    }
+  }
+  return createdAt;
+}
+
+/**
+ * One upload's identity for {@link primeUploads}: the vault key, the local
+ * path (to lstat for mode/mtime), whether it's a symlink, and the author.
+ */
+export interface UploadPrimeItem {
+  key: string;
+  localPath: string;
+  isSymlink: boolean;
+  author?: UploadAuthor;
+}
+
+/**
+ * Batch pre-mint PUT URLs (+ the created-at HEADs they depend on) for a set of
+ * uploads, signing the SAME metadata uploadFile/uploadSymlink would compute so
+ * the transfer loop can replay the cached headers. Turns an N-file push from
+ * ~N presign calls (1 per PUT, sometimes 2-3 with HEADs) into ceil(N/1000) GET
+ * + ceil(N/1000) PUT — the difference between completing a bulk push and 429ing
+ * past the 100/hr limit. No-op on the S3 SDK transport; best-effort.
+ *
+ * The per-item created-at HEADs run over the GET cache primed first, so they
+ * cost S3 round-trips but NO extra presign calls (not counted against 100/hr).
+ */
+export async function primeUploads(
+  ctx: EntityContext,
+  items: UploadPrimeItem[],
+): Promise<void> {
+  const io = resolveObjectIO(ctx);
+  if (!io.prime || items.length === 0) return;
+
+  // Prime GET first so each item's created-at HEAD reuses a cached URL.
+  await io.prime(
+    "get",
+    items.map((i) => ({ key: i.key })),
+  );
+
+  // Build per-key PUT metadata with the SAME builders the upload path uses,
+  // bounded-concurrently (the HEADs are cheap cached-GET fetches).
+  const putKeys: Array<{
+    key: string;
+    contentType: string;
+    metadata: Record<string, string>;
+  }> = [];
+  const CONCURRENCY = 16;
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const it = items[next++];
+      const createdAt = await resolveCreatedAt(io, it.key, it.author);
+      if (it.isSymlink) {
+        putKeys.push({
+          key: it.key,
+          contentType: "application/octet-stream",
+          metadata: {
+            [SYMLINK_TARGET_META_KEY]: SYMLINK_MARKER_META_VALUE,
+            ...(it.author ? buildAuthorMetadata(it.author, createdAt) : {}),
+          },
+        });
+      } else {
+        let modeTime: Record<string, string> = {};
+        try {
+          modeTime = buildModeTimeMetadata(fs.lstatSync(it.localPath));
+        } catch {
+          // raced rm / EPERM — leave stamps off (receiver umask default).
+        }
+        putKeys.push({
+          key: it.key,
+          contentType: getMimeType(it.key),
+          metadata: {
+            ...(it.author ? buildAuthorMetadata(it.author, createdAt) : {}),
+            ...modeTime,
+          },
+        });
+      }
     }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, items.length) }, worker),
+  );
+
+  await io.prime("put", putKeys);
+}
+
+export async function uploadFile(
+  ctx: EntityContext,
+  localPath: string,
+  key: string,
+  author?: UploadAuthor,
+): Promise<{ etag: string }> {
+  const io = resolveObjectIO(ctx);
+  const body = fs.readFileSync(localPath);
+
+  // Fast path: a primeUploads() pre-pass already signed this file's metadata
+  // into a cached PUT URL. Skip the lstat-metadata + created-at HEAD and just
+  // send the body — putObject replays the cached headers (computed by the SAME
+  // builders below, so identical). hasPrimedPut only reports true with >60s of
+  // URL lifetime left, so the cache can't expire before the putObject below.
+  if (io.hasPrimedPut?.(key)) {
+    const primed = await io.putObject({
+      key,
+      body,
+      contentType: getMimeType(key),
+      metadata: {},
+    });
+    return { etag: primed.etag };
   }
 
+  // Source-side mode/mtime/btime (Bug #5 + 5.37.0) and the preserved
+  // created-at (so the NEW-pill window doesn't reset on re-upload). Both via
+  // the shared builders that primeUploads uses, so a primed PUT carries the
+  // identical metadata — see buildModeTimeMetadata / resolveCreatedAt.
+  let modeTime: Record<string, string> = {};
+  try {
+    modeTime = buildModeTimeMetadata(fs.lstatSync(localPath));
+  } catch {
+    // raced rm / EPERM — leave stamps off; receiver keeps its umask default.
+  }
+  const createdAt = await resolveCreatedAt(io, key, author);
   const Metadata: Record<string, string> = {
     ...(author ? buildAuthorMetadata(author, createdAt) : {}),
-    ...(modeOctal ? { [FILE_MODE_META_KEY]: modeOctal } : {}),
-    ...(mtimeMsStamp ? { [FILE_MTIME_META_KEY]: mtimeMsStamp } : {}),
-    ...(btimeMsStamp ? { [FILE_BTIME_META_KEY]: btimeMsStamp } : {}),
+    ...modeTime,
   };
 
-  const response = await client.send(
-    new PutObjectCommand({
-      Bucket: ctx.bucketName,
-      Key: key,
-      Body: body,
-      ContentType: getMimeType(key),
-      ...(Object.keys(Metadata).length > 0 ? { Metadata } : {}),
-    }),
-  );
+  const response = await io.putObject({
+    key,
+    body,
+    contentType: getMimeType(key),
+    metadata: Metadata,
+  });
 
-  return { etag: response.ETag || "" };
+  return { etag: response.etag };
 }
 
 /**
@@ -375,26 +459,25 @@ export async function uploadSymlink(
   key: string,
   author?: UploadAuthor,
 ): Promise<{ etag: string }> {
-  const client = buildClient(ctx);
-
-  // Same created-at preservation logic as uploadFile so the hq-console
-  // NEW-pill ageing window doesn't reset when a symlink is re-uploaded
-  // unchanged across syncs.
-  let createdAt = new Date().toISOString();
-  if (author) {
-    try {
-      const head = await client.send(
-        new HeadObjectCommand({ Bucket: ctx.bucketName, Key: key }),
-      );
-      const existing = head.Metadata?.["created-at"];
-      if (typeof existing === "string" && existing.length > 0) {
-        createdAt = existing;
-      }
-    } catch {
-      // First upload of this key, or HEAD denied — keep `now`.
-    }
+  const io = resolveObjectIO(ctx);
+  const symlinkBody = encodeSymlinkBody(target);
+
+  // Fast path: primeUploads() already signed this symlink's metadata into a
+  // cached PUT URL — send the body, replay the cached headers.
+  if (io.hasPrimedPut?.(key)) {
+    const primed = await io.putObject({
+      key,
+      body: symlinkBody,
+      contentType: "application/octet-stream",
+      metadata: {},
+    });
+    return { etag: primed.etag };
   }
 
+  // Same created-at preservation as uploadFile (shared resolveCreatedAt) so the
+  // NEW-pill window doesn't reset on re-upload, and so a primed PUT matches.
+  const createdAt = await resolveCreatedAt(io, key, author);
+
   const Metadata: Record<string, string> = {
     // Marker-only: a constant flag value, not the target. The body
     // is the source of truth for the target (no 2 KiB cap, no
@@ -404,23 +487,20 @@ export async function uploadSymlink(
     ...(author ? buildAuthorMetadata(author, createdAt) : {}),
   };
 
-  const response = await client.send(
-    new PutObjectCommand({
-      Bucket: ctx.bucketName,
-      Key: key,
-      // Body = SYMLINK_BODY_PREFIX + target (UTF-8). The prefix is what
-      // makes a symlink record's ETag distinguishable from a regular
-      // file whose contents happen to equal the target string — the
-      // LIST-based pull planner can't see per-object metadata, so ETag
-      // is its only drift signal across symlink ↔ regular-file
-      // transitions. See SYMLINK_BODY_PREFIX doc above.
-      Body: encodeSymlinkBody(target),
-      ContentType: "application/octet-stream",
-      Metadata,
-    }),
-  );
+  const response = await io.putObject({
+    key,
+    // Body = SYMLINK_BODY_PREFIX + target (UTF-8). The prefix is what
+    // makes a symlink record's ETag distinguishable from a regular
+    // file whose contents happen to equal the target string — the
+    // LIST-based pull planner can't see per-object metadata, so ETag
+    // is its only drift signal across symlink ↔ regular-file
+    // transitions. See SYMLINK_BODY_PREFIX doc above.
+    body: symlinkBody,
+    contentType: "application/octet-stream",
+    metadata: Metadata,
+  });
 
-  return { etag: response.ETag || "" };
+  return { etag: response.etag };
 }
 
 /**
@@ -437,18 +517,14 @@ export async function downloadFile(
   key: string,
   localPath: string,
 ): Promise<{ metadata?: Record<string, string> }> {
-  const client = buildClient(ctx);
-
-  const response = await client.send(
-    new GetObjectCommand({
-      Bucket: ctx.bucketName,
-      Key: key,
-    }),
-  );
+  const io = resolveObjectIO(ctx);
 
-  if (!response.Body) {
-    throw new Error(`Empty response for ${key}`);
-  }
+  // The transport returns the full object body buffered + its user metadata.
+  // downloadFile already buffered the whole object (writeFileSync of the
+  // concatenated chunks), so buffering at the transport layer is behavior-
+  // preserving — symlink record bodies are tiny and regular files were read
+  // fully into memory regardless.
+  const { body: objectBody, metadata } = await io.getObject(key);
 
   const dir = path.dirname(localPath);
   if (!fs.existsSync(dir)) {
@@ -463,23 +539,26 @@ export async function downloadFile(
   // S3 lowercases user-metadata keys on read (and sometimes on
   // write), so the lookup uses the lowercased form. We don't
   // normalize Metadata keys ourselves — the AWS SDK already does it.
-  const symlinkMarker = response.Metadata?.[SYMLINK_TARGET_META_KEY];
+  const symlinkMarker = metadata?.[SYMLINK_TARGET_META_KEY];
+  // Discriminator: the metadata marker is the primary signal, but the body
+  // prefix is a header-loss fallback (S3 cross-region replication of data
+  // only, a console copy that drops Metadata, a metadata-stripping transport,
+  // or a poisoned regular-file re-upload of a sentinel). Honor BOTH — a
+  // marker-less object whose body starts with SYMLINK_BODY_PREFIX still
+  // rematerializes as a link instead of being written out as plain
+  // `hq-symlink:<target>` text, which would poison the key on the next push.
+  // The body is already buffered (tiny for symlink records); reading it here
+  // is behavior-preserving for regular files (whose body never starts with
+  // the prefix per the SYMLINK_BODY_PREFIX doc). See SYMLINK_BODY_PREFIX.
+  const bodyString = objectBody.toString("utf-8");
   const isSymlinkRecord =
-    typeof symlinkMarker === "string" && symlinkMarker.length > 0;
+    (typeof symlinkMarker === "string" && symlinkMarker.length > 0) ||
+    bodyString.startsWith(SYMLINK_BODY_PREFIX);
   if (isSymlinkRecord) {
-    // Consume the body to extract the target. Symlink record bodies
-    // are bounded by target length (typically <300 bytes for
-    // relative paths, hard-capped by S3's 5 GB object size); the
-    // read is cheap. Drain explicitly so the SDK's HTTP socket is
-    // released back to the connection pool — without this, a sync
-    // over a tree with many symlinks can stall or pool-exhaust.
-    const chunks: Buffer[] = [];
-    const stream = response.Body as AsyncIterable<Uint8Array>;
-    for await (const chunk of stream) {
-      chunks.push(Buffer.from(chunk));
-    }
-    const bodyString = Buffer.concat(chunks).toString("utf-8");
-
+    // The target lives in the body (marker-only metadata convention).
+    // Symlink record bodies are bounded by target length (typically
+    // <300 bytes for relative paths, hard-capped by S3's 5 GB object
+    // size); the transport already buffered it.
     let symlinkTarget: string;
     if (bodyString.startsWith(SYMLINK_BODY_PREFIX)) {
       symlinkTarget = bodyString.slice(SYMLINK_BODY_PREFIX.length);
@@ -488,8 +567,12 @@ export async function downloadFile(
       // this PR's lifetime stored the target in metadata (raw or
       // base64) rather than the body. decodeSymlinkMetadataValue
       // round-trip-validates so a raw value passes through and a
-      // base64 value decodes; either way we get the target.
-      symlinkTarget = decodeSymlinkMetadataValue(symlinkMarker);
+      // base64 value decodes; either way we get the target. This branch
+      // is only reachable when the body lacks the prefix, which (given
+      // isSymlinkRecord) means the marker is present — the `?? ""` is a
+      // type guard for that invariant, and the length-0 check below
+      // catches the impossible empty case rather than passing it on.
+      symlinkTarget = decodeSymlinkMetadataValue(symlinkMarker ?? "");
     }
 
     if (symlinkTarget.length === 0) {
@@ -515,7 +598,7 @@ export async function downloadFile(
       }
     }
     fs.symlinkSync(symlinkTarget, localPath);
-    return { metadata: response.Metadata };
+    return { metadata };
   }
 
   // Symmetric to the symlink branch above: when a key was previously a
@@ -542,12 +625,7 @@ export async function downloadFile(
     }
   }
 
-  const chunks: Buffer[] = [];
-  const stream = response.Body as AsyncIterable<Uint8Array>;
-  for await (const chunk of stream) {
-    chunks.push(Buffer.from(chunk));
-  }
-  fs.writeFileSync(localPath, Buffer.concat(chunks));
+  fs.writeFileSync(localPath, objectBody);
 
   // Bug #5 — apply source-side mode after the byte write. See
   // FILE_MODE_META_KEY for the metadata contract. Parses defensively:
@@ -563,7 +641,7 @@ export async function downloadFile(
   // requires 1–4 pure octal digits (`[0-7]{1,4}$`), which matches what
   // the upload side stamps (`(mode & 0o777).toString(8)` → at most
   // three digits, all 0–7) and rejects everything else.
-  const modeOctal = response.Metadata?.[FILE_MODE_META_KEY];
+  const modeOctal = metadata?.[FILE_MODE_META_KEY];
   if (typeof modeOctal === "string" && /^[0-7]{1,4}$/.test(modeOctal)) {
     const parsed = parseInt(modeOctal, 8);
     if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 0o777) {
@@ -602,7 +680,7 @@ export async function downloadFile(
   // similarly lstats after downloadFile). If a future caller stamps the
   // journal BEFORE downloadFile completes, the fast-path will stale and
   // re-hash every sync forever — keep the call-site invariant intact.
-  const mtimeRaw = response.Metadata?.[FILE_MTIME_META_KEY];
+  const mtimeRaw = metadata?.[FILE_MTIME_META_KEY];
   if (typeof mtimeRaw === "string" && /^-?[0-9]{1,16}$/.test(mtimeRaw)) {
     const mtimeMs = parseInt(mtimeRaw, 10);
     if (Number.isFinite(mtimeMs)) {
@@ -627,7 +705,7 @@ export async function downloadFile(
   // distinct creation time, so a future receiver upgrade picks it up
   // automatically without a server-side data migration.
 
-  return { metadata: response.Metadata };
+  return { metadata };
 }
 
 export interface RemoteFile {
@@ -641,26 +719,14 @@ export async function listRemoteFiles(
   ctx: EntityContext,
   prefix?: string,
 ): Promise<RemoteFile[]> {
-  const client = buildClient(ctx);
+  const io = resolveObjectIO(ctx);
   const files: RemoteFile[] = [];
   let continuationToken: string | undefined;
 
   do {
-    const response = await client.send(
-      new ListObjectsV2Command({
-        Bucket: ctx.bucketName,
-        Prefix: prefix,
-        ContinuationToken: continuationToken,
-      }),
-    );
-
-    for (const obj of response.Contents || []) {
-      // Pre-fix this guard was `!obj.Key || !obj.Size`. The `!obj.Size` test
-      // is truthy when Size === 0 (a real 0-byte object like `.gitkeep`),
-      // silently filtering legitimate placeholder files out of every pull
-      // plan. Narrow the guard to "no key" only; surface real 0-byte
-      // objects to the planner.
-      if (!obj.Key) continue;
+    const page = await io.listObjects({ prefix, continuationToken });
+
+    for (const obj of page.objects) {
       // Drop S3 directory-marker objects: the canonical shape is `0-byte
       // key ending in '/'` (S3 console "Create folder", `aws s3 sync` of
       // empty dirs, sync tools that mirror empty trees). Two downstream
@@ -670,29 +736,29 @@ export async function listRemoteFiles(
       // → EISDIR "open" after the parent mkdir creates the leaf as a
       // directory). Filtering here eliminates both.
       //
-      // Narrow on Size===0 (not just trailing-slash) so a hypothetical
+      // Narrow on size===0 (not just trailing-slash) so a hypothetical
       // non-empty object whose key happens to end in '/' is NOT silently
       // hidden — it stays visible and downloadFile surfaces the same
       // EISDIR "open" error pointing at the specific key, which is the
       // signal an operator needs to reconcile the bucket. The vault
       // service doesn't have a code path that produces such an object,
-      // but ListObjectsV2 returns whatever lives in the bucket; silent
+      // but the listing returns whatever lives in the bucket; silent
       // drop would be worse than loud failure for that case.
       //
       // Real 0-byte placeholders like `.gitkeep` never end in `/` and
       // continue to flow through — the 5.13.0 `.gitkeep` regression
-      // remains fixed.
-      if (obj.Key.endsWith("/") && (obj.Size ?? 0) === 0) continue;
+      // remains fixed. (The `!key` guard now lives in the ObjectIO layer.)
+      if (obj.key.endsWith("/") && obj.size === 0) continue;
 
       files.push({
-        key: obj.Key,
-        size: obj.Size ?? 0,
-        lastModified: obj.LastModified || new Date(),
-        etag: obj.ETag || "",
+        key: obj.key,
+        size: obj.size,
+        lastModified: obj.lastModified,
+        etag: obj.etag,
       });
     }
 
-    continuationToken = response.NextContinuationToken;
+    continuationToken = page.nextContinuationToken;
   } while (continuationToken);
 
   return files;
@@ -702,14 +768,7 @@ export async function deleteRemoteFile(
   ctx: EntityContext,
   key: string,
 ): Promise<void> {
-  const client = buildClient(ctx);
-
-  await client.send(
-    new DeleteObjectCommand({
-      Bucket: ctx.bucketName,
-      Key: key,
-    }),
-  );
+  await resolveObjectIO(ctx).deleteObject(key);
 }
 
 /**
@@ -719,26 +778,7 @@ export async function headRemoteFile(
   ctx: EntityContext,
   key: string,
 ): Promise<{ lastModified: Date; etag: string; size: number; metadata?: Record<string, string> } | null> {
-  const client = buildClient(ctx);
-  try {
-    const response = await client.send(
-      new HeadObjectCommand({
-        Bucket: ctx.bucketName,
-        Key: key,
-      }),
-    );
-    return {
-      lastModified: response.LastModified || new Date(),
-      etag: response.ETag || "",
-      size: response.ContentLength || 0,
-      metadata: response.Metadata,
-    };
-  } catch (err: unknown) {
-    if (err && typeof err === "object" && "name" in err && err.name === "NotFound") {
-      return null;
-    }
-    throw err;
-  }
+  return resolveObjectIO(ctx).headObject(key);
 }
 
 function getMimeType(filePath: string): string {