@indigoai-us/hq-cloud 5.35.0 → 5.37.0

package/src/s3.test.ts

@@ -88,6 +88,8 @@ import {
   SYMLINK_MARKER_META_VALUE,
   encodeSymlinkMetadataValue,
   decodeSymlinkMetadataValue,
+  FILE_MTIME_META_KEY,
+  FILE_BTIME_META_KEY,
 } from "./s3.js";
 import type { EntityContext } from "./types.js";
 
@@ -219,6 +221,66 @@ describe("uploadFile", () => {
     }
   });
 
+  it("stamps source file mtimeMs as hq-mtime metadata (5.37.0 — preserve mtime)", async () => {
+    // Symmetric to Bug #5's mode preservation. A file's modification time
+    // should follow it across machines instead of resetting to "the time of
+    // sync." Push stamps `hq-mtime` = integer-ms epoch string; pull applies
+    // it via utimesSync. See FILE_MTIME_META_KEY doc.
+    const knownMs = 1_700_000_000_000; // 2023-11-14T22:13:20Z, comfortably finite
+    const knownDate = new Date(knownMs);
+    fs.utimesSync(tmpFile, knownDate, knownDate);
+
+    await uploadFile(makeCtx(), tmpFile, "stamped.md");
+
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    expect(put).toBeDefined();
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.[FILE_MTIME_META_KEY]).toBe(String(knownMs));
+  });
+
+  it("stamps hq-btime only when birthtime is supported AND distinct from mtime", async () => {
+    // Many filesystems (Linux/ext4 historically, tmpfs, some FUSE mounts)
+    // return birthtimeMs === 0 or birthtimeMs === mtimeMs. Stamping in
+    // those cases would be pure noise; the upload side filters it out.
+    // We don't control the test filesystem's birthtime semantics, so the
+    // assertion is shape-only: IF hq-btime is present, it's a numeric
+    // string AND it's distinct from hq-mtime.
+    await uploadFile(makeCtx(), tmpFile, "btime.md");
+
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    const btime = meta?.[FILE_BTIME_META_KEY];
+    const mtime = meta?.[FILE_MTIME_META_KEY];
+    if (typeof btime === "string") {
+      expect(btime).toMatch(/^[0-9]{1,16}$/);
+      expect(btime).not.toBe(mtime);
+    }
+  });
+
+  it("does NOT stamp hq-mtime / hq-btime for symlinks (uploadFile branch)", async () => {
+    // uploadFile is the regular-file path; uploadSymlink is the symlink
+    // path. uploadFile's lstat.isSymbolicLink() guard skips ALL three of
+    // mode + mtime + btime stamping for symlinks, mirroring the existing
+    // hq-mode policy: symlink times are OS-controlled and fs.utimesSync
+    // would follow the link and mutate the target. The link is set up
+    // pointing at a real target so fs.readFileSync (which follows links)
+    // doesn't ENOENT before the metadata stamping branch even runs.
+    const targetPath = path.join(os.tmpdir(), `s3-link-target-${Date.now()}-${Math.random()}.txt`);
+    fs.writeFileSync(targetPath, "real-bytes");
+    const linkPath = path.join(os.tmpdir(), `s3-link-test-${Date.now()}-${Math.random()}.lnk`);
+    fs.symlinkSync(targetPath, linkPath);
+
+    await uploadFile(makeCtx(), linkPath, "link.md");
+
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    const meta = put!.input.Metadata as Record<string, string> | undefined;
+    expect(meta?.[FILE_MTIME_META_KEY]).toBeUndefined();
+    expect(meta?.[FILE_BTIME_META_KEY]).toBeUndefined();
+
+    fs.unlinkSync(linkPath);
+    fs.unlinkSync(targetPath);
+  });
+
   it("elides non-ASCII or empty author fields rather than throwing", async () => {
     // S3 user-defined metadata must be ASCII-only and total ≤ 2KB. Partial
     // attribution beats hard failure — values that fail the printable check
@@ -770,6 +832,240 @@ describe("downloadFile", () => {
     expect(fs.readFileSync(localPath, "utf-8")).toBe("legacy");
   });
 
+  it("applies hq-mtime via utimesSync after byte write (5.37.0 — preserve mtime)", async () => {
+    // Round-trip pair to the s3.upload mtime stamp test. The receiver must
+    // set the local file's mtime to the metadata-stamped value AFTER the
+    // byte write, mirroring the chmod-after-write shape from Bug #5.
+    const knownMs = 1_700_000_000_000;
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([116, 105, 109, 101]); // "time"
+      })(),
+      Metadata: { [FILE_MTIME_META_KEY]: String(knownMs) },
+    };
+
+    const localPath = path.join(tmpRoot, "mtime-applied.bin");
+    await downloadFile(makeCtx(), "mtime-applied.bin", localPath);
+
+    const stat = fs.statSync(localPath);
+    // ±50ms tolerance accommodates ms-precision filesystems and the
+    // utimesSync→stat round-trip rounding. macOS APFS reports full ms;
+    // some Linux filesystems round to seconds — guard with tolerance.
+    expect(Math.abs(stat.mtimeMs - knownMs)).toBeLessThanOrEqual(50);
+  });
+
+  it("rejects malformed hq-mtime metadata via strict-numeric regex", async () => {
+    // Symmetric to the hq-mode Codex P2 lesson: parseInt accepts partial-
+    // prefix garbage ("175junk" → 175). A strict `^[0-9]{1,16}$` regex
+    // BEFORE parseInt rejects empty / signed / decimals / whitespace /
+    // oversized / non-numeric and falls through to "no utimes call,"
+    // leaving the file at write-time mtime — the legacy back-compat path.
+    // NOTE: `-100` is intentionally NOT in this list — Codex PR #27 P2 pointed
+    // out that legitimate epoch values include 0 (Unix epoch) and negatives
+    // (e.g. reproducible-build clamping pre-1970). Negative-but-well-formed
+    // strings are now accepted; see the dedicated round-trip tests below.
+    const malformed = [
+      "175junk",   // trailing garbage — parseInt parses 175 pre-fix
+      "abc",       // non-numeric
+      "",          // empty
+      "  100  ",   // whitespace
+      "--100",     // double-sign — only ONE optional leading "-" allowed
+      "+100",      // explicit plus rejected (regex only allows optional "-")
+      "3.14",      // decimal
+      "99999999999999999", // >16 digits
+    ];
+    for (const bad of malformed) {
+      // Establish a known pre-write mtime by writing the file first.
+      const localPath = path.join(tmpRoot, `bad-mtime-${malformed.indexOf(bad)}.bin`);
+      nextGetObjectResponse = {
+        Body: (async function* () {
+          yield new Uint8Array([98]); // "b"
+        })(),
+        Metadata: { [FILE_MTIME_META_KEY]: bad },
+      };
+      const before = Date.now();
+      await downloadFile(makeCtx(), `bad-mtime-${malformed.indexOf(bad)}.bin`, localPath);
+      const stat = fs.statSync(localPath);
+      // The file's mtime MUST be wall-clock-now (write-time), NOT the
+      // partial-parse value. For "175junk", that means mtime is in the
+      // current millis range, not ms=175 (1970-01-01T00:00:00.175Z).
+      // Generic check: mtime is near `before` (within 5s).
+      expect(Math.abs(stat.mtimeMs - before)).toBeLessThan(5000);
+      // Specific check: never the partial-parse epoch (~175ms after epoch).
+      expect(stat.mtimeMs).toBeGreaterThan(1_000_000_000_000);
+    }
+  });
+
+  it("round-trips mtimeMs === 0 (Unix epoch — Codex PR #27 P2)", async () => {
+    // Codex flagged that filtering `mtimeMs > 0` drops legitimate epoch-0
+    // timestamps (and reproducible-build clamping uses exactly 0). The
+    // receiver must accept "0", parse it, and stamp `new Date(0)` on disk.
+    const sourcePath = path.join(tmpRoot, "epoch-zero-src.bin");
+    fs.writeFileSync(sourcePath, "epoch-bytes");
+    fs.utimesSync(sourcePath, new Date(0), new Date(0));
+
+    sentCommands.length = 0;
+    await uploadFile(makeCtx(), sourcePath, "epoch-zero.bin");
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    const stampedMeta = put!.input.Metadata as Record<string, string>;
+    const stampedBody = put!.input.Body as Buffer;
+    expect(stampedMeta[FILE_MTIME_META_KEY]).toBe("0");
+
+    fs.unlinkSync(sourcePath);
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array(stampedBody);
+      })(),
+      Metadata: stampedMeta,
+    };
+    await downloadFile(makeCtx(), "epoch-zero.bin", sourcePath);
+
+    const stat = fs.statSync(sourcePath);
+    // 0 is integer-clean — exact match expected, but allow 50ms tolerance
+    // for any underlying FS rounding shenanigans.
+    expect(Math.abs(stat.mtimeMs - 0)).toBeLessThanOrEqual(50);
+    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("epoch-bytes");
+  });
+
+  it("round-trips a negative mtime (pre-epoch — Codex PR #27 P2)", async () => {
+    // Some filesystems / reproducible-build pipelines clamp mtime to values
+    // before the Unix epoch (negative ms). `new Date(-86400000)` is a legal
+    // Date; `fs.utimesSync` accepts it. The receiver MUST NOT drop these.
+    const sourceMs = -86_400_000; // 1969-12-31T00:00:00Z, one day before epoch
+    const sourcePath = path.join(tmpRoot, "pre-epoch-src.bin");
+    fs.writeFileSync(sourcePath, "pre-epoch-bytes");
+    fs.utimesSync(sourcePath, new Date(sourceMs), new Date(sourceMs));
+
+    sentCommands.length = 0;
+    await uploadFile(makeCtx(), sourcePath, "pre-epoch.bin");
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    const stampedMeta = put!.input.Metadata as Record<string, string>;
+    const stampedBody = put!.input.Body as Buffer;
+    expect(stampedMeta[FILE_MTIME_META_KEY]).toBe(String(sourceMs));
+
+    fs.unlinkSync(sourcePath);
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array(stampedBody);
+      })(),
+      Metadata: stampedMeta,
+    };
+    await downloadFile(makeCtx(), "pre-epoch.bin", sourcePath);
+
+    const stat = fs.statSync(sourcePath);
+    expect(Math.abs(stat.mtimeMs - sourceMs)).toBeLessThanOrEqual(50);
+    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("pre-epoch-bytes");
+  });
+
+  it("accepts well-formed negative hq-mtime (e.g. '-100') on download", async () => {
+    // Migration of the old rejection-list case for `-100`. Codex PR #27 P2:
+    // negative epoch-ms values are legitimate; the regex now allows a single
+    // optional leading `-`, and utimesSync handles it.
+    const localPath = path.join(tmpRoot, "negative-mtime.bin");
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([110]); // "n"
+      })(),
+      Metadata: { [FILE_MTIME_META_KEY]: "-100" },
+    };
+    await downloadFile(makeCtx(), "negative-mtime.bin", localPath);
+
+    const stat = fs.statSync(localPath);
+    // mtime should be ~ -100 ms, NOT wall-clock-now. The old code would have
+    // left this at write-time; the new code applies the negative stamp.
+    expect(Math.abs(stat.mtimeMs - -100)).toBeLessThanOrEqual(50);
+  });
+
+  it("downloads with default mtime when hq-mtime metadata is absent (back-compat)", async () => {
+    // Legacy uploads (pre-5.37.0) carry no hq-mtime header. The receiver
+    // must NOT crash and must NOT alter the on-disk mtime away from the
+    // default `fs.writeFileSync` wall-clock-now behavior. Mirrors the
+    // hq-mode back-compat test.
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array([108, 101, 103]); // "leg"
+      })(),
+      Metadata: {},
+    };
+
+    const before = Date.now();
+    const localPath = path.join(tmpRoot, "legacy-mtime.bin");
+    await downloadFile(makeCtx(), "legacy-mtime.bin", localPath);
+
+    const stat = fs.statSync(localPath);
+    expect(Math.abs(stat.mtimeMs - before)).toBeLessThan(5000);
+    expect(fs.readFileSync(localPath, "utf-8")).toBe("leg");
+  });
+
+  it("does NOT call utimesSync on the symlink branch (5.37.0)", async () => {
+    // fs.utimesSync follows symlinks (mutates the target's mtime, not the
+    // link's). On the symlink branch we must skip the utimes block entirely
+    // so we don't accidentally mutate an unrelated target file. The
+    // symlink record's hq-mtime, if any, is ignored — symlink mtime is
+    // OS-controlled and Node has no stable lutimes API. Easiest verifier:
+    // the link is materialized AND the test doesn't crash.
+    const targetPath = path.join(tmpRoot, "untouched-target.txt");
+    fs.writeFileSync(targetPath, "do-not-touch");
+    const knownTargetMs = 1_500_000_000_000;
+    fs.utimesSync(targetPath, new Date(knownTargetMs), new Date(knownTargetMs));
+
+    const linkPath = path.join(tmpRoot, "the-link");
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield Buffer.from(SYMLINK_BODY_PREFIX + "untouched-target.txt");
+      })(),
+      Metadata: {
+        "hq-symlink-target": SYMLINK_MARKER_META_VALUE,
+        // Even if a misbehaving uploader stamped hq-mtime on a symlink
+        // record, the downloader's symlink branch returns BEFORE the
+        // utimes block, so the target's mtime stays at knownTargetMs.
+        [FILE_MTIME_META_KEY]: "1_900_000_000_000",
+      },
+    };
+
+    await downloadFile(makeCtx(), "the-link", linkPath);
+
+    expect(fs.lstatSync(linkPath).isSymbolicLink()).toBe(true);
+    expect(fs.readlinkSync(linkPath)).toBe("untouched-target.txt");
+    // Target's mtime is unchanged — utimes block was skipped.
+    const targetStat = fs.statSync(targetPath);
+    expect(Math.abs(targetStat.mtimeMs - knownTargetMs)).toBeLessThanOrEqual(50);
+  });
+
+  it("round-trips mtime across upload + download (5.37.0 user-visible promise)", async () => {
+    // The whole point of the feature: a file's mtime should follow it
+    // across the wire. Push captures source mtime → metadata; pull applies
+    // metadata → local mtime. This test wires upload's PutObject capture
+    // into download's GetObject response so the contract round-trips end-
+    // to-end through s3.ts without bringing in journal/CLI state.
+    const sourceMs = 1_650_000_000_000; // 2022-04-15T03:33:20Z
+    const sourcePath = path.join(tmpRoot, "round-trip-src.bin");
+    fs.writeFileSync(sourcePath, "round-trip-bytes");
+    fs.utimesSync(sourcePath, new Date(sourceMs), new Date(sourceMs));
+
+    sentCommands.length = 0;
+    await uploadFile(makeCtx(), sourcePath, "round-trip.bin");
+    const put = sentCommands.find((c) => c.name === "PutObjectCommand");
+    const stampedMeta = put!.input.Metadata as Record<string, string>;
+    const stampedBody = put!.input.Body as Buffer;
+
+    // Wipe the local copy and pull via download — simulating a different
+    // machine receiving the file.
+    fs.unlinkSync(sourcePath);
+    nextGetObjectResponse = {
+      Body: (async function* () {
+        yield new Uint8Array(stampedBody);
+      })(),
+      Metadata: stampedMeta,
+    };
+    await downloadFile(makeCtx(), "round-trip.bin", sourcePath);
+
+    const stat = fs.statSync(sourcePath);
+    // Within 100ms — covers FS rounding on both ends of the round-trip.
+    expect(Math.abs(stat.mtimeMs - sourceMs)).toBeLessThanOrEqual(100);
+    expect(fs.readFileSync(sourcePath, "utf-8")).toBe("round-trip-bytes");
+  });
+
   it("returns the object's user-metadata (including created-by) for a regular file", async () => {
     nextGetObjectResponse = {
       Body: (async function* () {

package/src/s3.ts

@@ -182,6 +182,62 @@ export const SYMLINK_BODY_PREFIX = "hq-symlink:";
  */
 export const FILE_MODE_META_KEY = "hq-mode";
 
+/**
+ * S3 user-metadata key carrying the source-side file modification time
+ * (mtimeMs) as an integer-millisecond epoch string ("1700000000000"). On
+ * download, downloadFile parses this with a strict-numeric regex BEFORE
+ * parseInt, then applies it via `fs.utimesSync(localPath, mtimeDate,
+ * mtimeDate)` after the byte write.
+ *
+ * 5.37.0 symmetric to the 5.34.0 Bug #5 mode preservation: a file's
+ * modification time should follow it across machines instead of resetting
+ * to "the time of sync." Without this metadata, every receiver's mtime is
+ * wall-clock-now at write-time — making "newer than" comparisons,
+ * mtime-keyed caches, and reproducible builds break across sync.
+ *
+ * Symlinks: skipped at upload time (symlink mtime is OS-controlled and
+ * `lstat` on a symlink already returns the symlink's own times — but we
+ * don't stamp them because the symlink record wire body is `hq-symlink:`
+ * + target string, not real file content, so its mtime isn't user-
+ * meaningful) and skipped on download (`fs.utimesSync` follows symlinks
+ * and would mutate the target's mtime instead; `lutimesSync` is not in
+ * stable Node).
+ *
+ * Composition with 5.36.0 lstat fast-path: the journal stamp is captured
+ * AFTER utimesSync runs (the share/sync call sites lstat AFTER
+ * downloadFile returns), so the journal's mtimeMs matches the post-utimes
+ * lstat. The next sync's fast-path correctly skips re-hashing.
+ *
+ * Clock skew: a peer with a wrong clock pushes file with mtimeMs=<wrong>;
+ * receivers apply <wrong>. This is the same trade git's "file from the
+ * future" warning makes — silent in our case, deliberately. Clock skew
+ * is the user's problem, not the sync engine's.
+ *
+ * Back-compat: legacy uploads (pre-5.37.0) have no `hq-mtime` header —
+ * the receiver leaves the on-disk mtime at write-time, matching pre-
+ * 5.37.0 behavior. Forward-compat: pre-5.37.0 pullers ignore `hq-mtime`
+ * and keep their current "mtime = write-time" behavior. Both work; only
+ * the receiver upgrade unlocks the feature.
+ */
+export const FILE_MTIME_META_KEY = "hq-mtime";
+
+/**
+ * S3 user-metadata key carrying the source-side file birthtime (birthtimeMs)
+ * as an integer-millisecond epoch string. Stamped on upload ONLY when
+ * `birthtimeMs > 0 && birthtimeMs !== mtimeMs` — many filesystems (Linux
+ * ext4 historically, tmpfs, some FUSE mounts) return 0 (unsupported) or
+ * the same value as mtime (no separate creation time tracking). The
+ * filter keeps the metadata header free of noise on those platforms.
+ *
+ * Pull: NO-OP for now. Node has no API to set birthtime on POSIX as of
+ * v24 (no `lbirthtime`, no `birthtimeSync`). The push side stamps it
+ * anyway so a future receiver upgrade — once Node lands the API — can
+ * apply it without a server-side data migration.
+ *
+ * Symlinks: skipped on both sides for the same reasons as `hq-mtime`.
+ */
+export const FILE_BTIME_META_KEY = "hq-btime";
+
 /**
  * Encode/decode the symlink wire body. Kept as exported helpers so the
  * format is centrally defined and tests can probe both sides without
@@ -204,14 +260,61 @@ export async function uploadFile(
   // 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 modeOctal undefined; receiver applies its umask default.
+    // Leave stamps undefined; receiver applies its umask default and
+    // leaves mtime at write-time (the legacy back-compat path).
   }
 
   // Preserve the original `created-at` across re-uploads when the object
@@ -237,6 +340,8 @@ export async function uploadFile(
   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 } : {}),
   };
 
   const response = await client.send(
@@ -473,6 +578,55 @@ export async function downloadFile(
     }
   }
 
+  // 5.37.0 — apply source-side mtime after the byte write (and after the
+  // chmod above; ordering between chmod and utimes doesn't matter, but
+  // both must run AFTER writeFileSync because writeFileSync resets mtime
+  // to wall-clock-now). See FILE_MTIME_META_KEY for the metadata contract.
+  //
+  // Strict-numeric regex BEFORE parseInt — same Codex P2 lesson as hq-mode.
+  // `^-?[0-9]{1,16}$` rejects partial-prefix garbage ("175junk" → 175),
+  // empty, double-signed, decimals, whitespace, and oversized strings. A
+  // single optional leading `-` is allowed so pre-epoch / reproducible-build
+  // timestamps round-trip (Codex PR #27 P2 — `mtimeMs === 0` and negative
+  // epoch values are legitimate). 16 digits comfortably covers any plausible
+  // epoch-ms value (year ~5138 is 16 digits; we'll cross that bridge later).
+  //
+  // fs.utimesSync FOLLOWS symlinks — that's fine here because we're on
+  // the regular-file branch (the symlink branch above already returned
+  // before we reach this code).
+  //
+  // Composition with the 5.36.0 lstat fast-path: the journal stamp at the
+  // share/sync call sites runs AFTER downloadFile returns, so the lstat
+  // it captures sees the post-utimes mtime. Verified in cli/sync.ts
+  // (downloadFile → lstatSync → updateEntry) and cli/share.ts (pull path
+  // 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];
+  if (typeof mtimeRaw === "string" && /^-?[0-9]{1,16}$/.test(mtimeRaw)) {
+    const mtimeMs = parseInt(mtimeRaw, 10);
+    if (Number.isFinite(mtimeMs)) {
+      try {
+        // utimesSync accepts seconds OR Date; use Date(ms) for precision.
+        // atime = mtime is fine — many filesystems are mounted noatime
+        // and distinguishing "access" vs "modification" time doesn't
+        // matter for sync semantics. Setting both keeps the on-disk
+        // state deterministic across receivers.
+        const mtimeDate = new Date(mtimeMs);
+        fs.utimesSync(localPath, mtimeDate, mtimeDate);
+      } catch {
+        // EPERM / read-only FS / file just unlinked → non-fatal. The
+        // file is materialized at write-time mtime; the source-of-truth
+        // can re-sync next pass.
+      }
+    }
+  }
+
+  // TODO: stamp hq-btime once Node lands lbirthtime (or birthtimeSync).
+  // 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 };
 }
 

package/src/types.ts

@@ -34,6 +34,22 @@ export interface JournalEntry {
    * against `syncedAt`.
    */
   remoteEtag?: string;
+  /**
+   * Local mtime (epoch ms) of the file at the moment we last synced it. Used
+   * by the push planner as the fast-path "is this file unchanged?" check:
+   * when `lstat.size === entry.size && lstat.mtimeMs === entry.mtimeMs`,
+   * the SHA256 is skipped and the file is classified `unchanged` without
+   * reading its bytes. Same trade-off rsync/gitignore use — a same-length
+   * edit that doesn't bump mtime will be missed, but that's vanishingly
+   * rare in practice and the speedup on no-op syncs (~5–10×) is the goal.
+   *
+   * Optional for backwards compatibility: entries written before this field
+   * existed (or symlink entries, where lstat.mtimeMs is the link's own
+   * mtime and the prefixed-hash check is already cheap) fall through to
+   * `hashFile()` on the first post-upgrade sync; the next `updateEntry`
+   * stamps the field so subsequent syncs use the fast-path.
+   */
+  mtimeMs?: number;
   /**
    * Tombstone marker (Journal v2, US-005). When set, this entry represents
    * a file that was pruned by a scope shrink — either implicitly (next pull