@indigoai-us/hq-cloud 5.46.0 → 5.47.1

package/dist/s3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkBhD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AA6BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAuG3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAgMhD;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,EAAE,CAAC,CAwDvB;AAED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBvG"}
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../src/s3.ts"],"names":[],"mappings":"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"}

package/dist/s3.js

@@ -7,22 +7,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { S3Client, PutObjectCommand, GetObjectCommand, ListObjectsV2Command, DeleteObjectCommand, HeadObjectCommand, } from "@aws-sdk/client-s3";
-/**
- * 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) {
-    return new S3Client({
-        region: ctx.region,
-        credentials: {
-            accessKeyId: ctx.credentials.accessKeyId,
-            secretAccessKey: ctx.credentials.secretAccessKey,
-            sessionToken: ctx.credentials.sessionToken,
-        },
-    });
-}
+import { resolveObjectIO } from "./object-io.js";
 /**
  * S3 user metadata is ASCII-only (lowercased on read, capped at 2 KB total).
  * Values that fail the printable-ASCII test or would push the keys over the
@@ -212,100 +197,172 @@ export const FILE_BTIME_META_KEY = "hq-btime";
 export function encodeSymlinkBody(target) {
     return Buffer.from(SYMLINK_BODY_PREFIX + target, "utf-8");
 }
-export async function uploadFile(ctx, localPath, key, author) {
-    const client = buildClient(ctx);
-    const body = fs.readFileSync(localPath);
-    // 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;
-    let mtimeMsStamp;
-    let btimeMsStamp;
-    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).
+/**
+ * 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, op, keys) {
+    if (keys.length === 0)
+        return;
+    const io = resolveObjectIO(ctx);
+    if (!io.prime)
+        return;
+    await io.prime(op, keys.map((key) => ({ key })));
+}
+/**
+ * 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) {
+    const meta = {};
+    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);
     }
-    // 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.
+    return meta;
+}
+/**
+ * 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, key, author) {
     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;
+}
+/**
+ * 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, items) {
+    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 = [];
+    const CONCURRENCY = 16;
+    let next = 0;
+    const worker = async () => {
+        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 = {};
+                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, localPath, key, author) {
+    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 = {};
+    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 = {
         ...(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 } : {}),
-    }));
-    return { etag: response.ETag || "" };
+    const response = await io.putObject({
+        key,
+        body,
+        contentType: getMimeType(key),
+        metadata: Metadata,
+    });
+    return { etag: response.etag };
 }
 /**
  * Upload a symlink as a zero-byte object whose user metadata carries the
@@ -320,23 +377,22 @@ export async function uploadFile(ctx, localPath, key, author) {
  * caller (currently: upload anyway, never silently rewrite).
  */
 export async function uploadSymlink(ctx, target, key, author) {
-    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 = {
         // Marker-only: a constant flag value, not the target. The body
         // is the source of truth for the target (no 2 KiB cap, no
@@ -345,20 +401,19 @@ export async function uploadSymlink(ctx, target, key, author) {
         [SYMLINK_TARGET_META_KEY]: SYMLINK_MARKER_META_VALUE,
         ...(author ? buildAuthorMetadata(author, createdAt) : {}),
     };
-    const response = await client.send(new PutObjectCommand({
-        Bucket: ctx.bucketName,
-        Key: key,
+    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: encodeSymlinkBody(target),
-        ContentType: "application/octet-stream",
-        Metadata,
-    }));
-    return { etag: response.ETag || "" };
+        body: symlinkBody,
+        contentType: "application/octet-stream",
+        metadata: Metadata,
+    });
+    return { etag: response.etag };
 }
 /**
  * Download an object to localPath and return its S3 user-metadata.
@@ -370,14 +425,13 @@ export async function uploadSymlink(ctx, target, key, author) {
  * attribute downloaded files to their author with zero extra network.
  */
 export async function downloadFile(ctx, key, localPath) {
-    const client = buildClient(ctx);
-    const response = await client.send(new GetObjectCommand({
-        Bucket: ctx.bucketName,
-        Key: key,
-    }));
-    if (!response.Body) {
-        throw new Error(`Empty response for ${key}`);
-    }
+    const io = resolveObjectIO(ctx);
+    // 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)) {
         fs.mkdirSync(dir, { recursive: true });
@@ -390,21 +444,25 @@ export async function downloadFile(ctx, key, localPath) {
     // 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 isSymlinkRecord = typeof symlinkMarker === "string" && symlinkMarker.length > 0;
+    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) ||
+        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 = [];
-        const stream = response.Body;
-        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;
         if (bodyString.startsWith(SYMLINK_BODY_PREFIX)) {
             symlinkTarget = bodyString.slice(SYMLINK_BODY_PREFIX.length);
@@ -414,8 +472,12 @@ export async function downloadFile(ctx, key, localPath) {
             // 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) {
             throw new Error(`Symlink record for ${key} had no target (body: ${bodyString.length} bytes, marker: ${symlinkMarker})`);
@@ -436,7 +498,7 @@ export async function downloadFile(ctx, key, localPath) {
             }
         }
         fs.symlinkSync(symlinkTarget, localPath);
-        return { metadata: response.Metadata };
+        return { metadata };
     }
     // Symmetric to the symlink branch above: when a key was previously a
     // symlink and is later replaced in S3 by a regular object, the local
@@ -460,12 +522,7 @@ export async function downloadFile(ctx, key, localPath) {
             throw err;
         }
     }
-    const chunks = [];
-    const stream = response.Body;
-    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:
     // a malformed value falls through with no chmod so the umask default
@@ -480,7 +537,7 @@ export async function downloadFile(ctx, key, localPath) {
     // 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) {
@@ -519,7 +576,7 @@ export async function downloadFile(ctx, key, localPath) {
     // 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)) {
@@ -543,26 +600,15 @@ export async function downloadFile(ctx, key, localPath) {
     // The push side already emits hq-btime when the source FS tracks a
     // 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 async function listRemoteFiles(ctx, prefix) {
-    const client = buildClient(ctx);
+    const io = resolveObjectIO(ctx);
     const files = [];
     let continuationToken;
     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
@@ -572,61 +618,39 @@ export async function listRemoteFiles(ctx, prefix) {
             // → 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)
+            // 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;
 }
 export async function deleteRemoteFile(ctx, key) {
-    const client = buildClient(ctx);
-    await client.send(new DeleteObjectCommand({
-        Bucket: ctx.bucketName,
-        Key: key,
-    }));
+    await resolveObjectIO(ctx).deleteObject(key);
 }
 /**
  * Check if a remote key exists and return its metadata.
  */
 export async function headRemoteFile(ctx, key) {
-    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) {
-        if (err && typeof err === "object" && "name" in err && err.name === "NotFound") {
-            return null;
-        }
-        throw err;
-    }
+    return resolveObjectIO(ctx).headObject(key);
 }
 function getMimeType(filePath) {
     const ext = path.extname(filePath).toLowerCase();