@hyperframes/share 0.9.27 → 0.9.28-alpha.0

package/src/sources/unicode.mjs

@@ -0,0 +1,163 @@
+// @ts-check
+// Use the bundled Unicode 15.1 tables so path comparison is independent of the runtime Unicode version.
+import { readContract } from "./contract.mjs";
+
+export const UNICODE_VERSION = "15.1.0";
+
+/** @typedef {{ unicode_version: string, casefold: Record<string, string>, combining: Record<string, number>,
+ *   decomposition: Record<string, number[]>, composition: Record<string, number>,
+ *   assigned_ranges: [number, number][] }} UnicodeTableFile */
+
+const HANGUL_BASE = 0xac00;
+const HANGUL_COUNT = 11172;
+const L_BASE = 0x1100;
+const V_BASE = 0x1161;
+const T_BASE = 0x11a7;
+const L_COUNT = 19;
+const V_COUNT = 21;
+const T_COUNT = 28;
+const N_COUNT = V_COUNT * T_COUNT;
+
+/** The table re-keyed by code point, decompositions fully expanded. @param {UnicodeTableFile} raw */
+function tablesOf(raw) {
+  if (raw.unicode_version !== UNICODE_VERSION)
+    throw new Error(`unicode table is ${raw.unicode_version}, expected ${UNICODE_VERSION}`);
+  const hex = (/** @type {string} */ code) => Number.parseInt(code, 16);
+  const casefold = new Map(Object.entries(raw.casefold).map(([code, to]) => [hex(code), to]));
+  const combining = new Map(Object.entries(raw.combining).map(([code, cc]) => [hex(code), cc]));
+  const direct = new Map(Object.entries(raw.decomposition).map(([code, seq]) => [hex(code), seq]));
+  /** @param {number} code @returns {number[]} */
+  const expand = (code) => direct.get(code)?.flatMap(expand) ?? [code];
+  const decomposition = new Map([...direct.keys()].map((code) => [code, expand(code)]));
+  const composition = new Map(
+    Object.entries(raw.composition).map(([pair, composite]) => {
+      const [first = "", second = ""] = pair.split(",");
+      return [`${hex(first)},${hex(second)}`, composite];
+    }),
+  );
+  const starts = raw.assigned_ranges.map(([start]) => start);
+  const ends = raw.assigned_ranges.map(([, end]) => end);
+  return { casefold, combining, decomposition, composition, starts, ends };
+}
+
+/** @type {ReturnType<typeof tablesOf> | null} */
+let loaded = null;
+/** The table, read and indexed when a path is first compared: an app that never syncs never reads it. */
+const tables = () => (loaded ??= tablesOf(readContract("unicode-15.1.0.json")));
+
+/** @param {number} code */
+const classOf = (code) => tables().combining.get(code) ?? 0;
+
+/** @param {number} code @returns {readonly number[]} */
+function decompose(code) {
+  const syllable = code - HANGUL_BASE;
+  if (syllable >= 0 && syllable < HANGUL_COUNT) {
+    const trailing = syllable % T_COUNT;
+    const leading = [
+      L_BASE + Math.floor(syllable / N_COUNT),
+      V_BASE + Math.floor((syllable % N_COUNT) / T_COUNT),
+    ];
+    return trailing ? [...leading, T_BASE + trailing] : leading;
+  }
+  return tables().decomposition.get(code) ?? [code];
+}
+
+/** @param {number} first @param {number} second @returns {number | undefined} */
+function composePair(first, second) {
+  if (first >= L_BASE && first < L_BASE + L_COUNT && second >= V_BASE && second < V_BASE + V_COUNT)
+    return HANGUL_BASE + ((first - L_BASE) * V_COUNT + second - V_BASE) * T_COUNT;
+  return composeSyllable(first, second) ?? tables().composition.get(`${first},${second}`);
+}
+/** @param {number} first @param {number} second */
+function composeSyllable(first, second) {
+  if (
+    first >= HANGUL_BASE &&
+    first < HANGUL_BASE + HANGUL_COUNT &&
+    (first - HANGUL_BASE) % T_COUNT === 0 &&
+    second > T_BASE &&
+    second < T_BASE + T_COUNT
+  )
+    return first + second - T_BASE;
+}
+
+/** Canonical decomposition then canonical ordering of combining marks. @param {string} value */
+function orderedCodes(value) {
+  /** @type {number[]} */
+  const ordered = [];
+  for (const char of value) {
+    for (const code of decompose(char.codePointAt(0) ?? 0)) {
+      const current = classOf(code);
+      let position = ordered.length;
+      while (current && position && classOf(ordered[position - 1] ?? 0) > current) position--;
+      ordered.splice(position, 0, code);
+    }
+  }
+  return ordered;
+}
+
+/** Canonical composition under the pinned Unicode table. @param {number[]} ordered */
+function composed(ordered) {
+  /** @type {number[]} */
+  const result = [];
+  let starter = 0;
+  let lastClass = 0;
+  for (const code of ordered) {
+    const current = classOf(code);
+    const head = result[starter];
+    const composite = head === undefined ? undefined : composePair(head, code);
+    if (composite !== undefined && (lastClass < current || lastClass === 0)) {
+      result[starter] = composite;
+      continue;
+    }
+    if (current === 0) starter = result.length;
+    result.push(code);
+    lastClass = current;
+  }
+  return String.fromCodePoint(...result);
+}
+
+const ASCII = /^\p{ASCII}*$/u;
+
+/** NFC (UAX #15) under the pinned table. @param {string} value */
+export const nfc = (value) => (ASCII.test(value) ? value : composed(orderedCodes(value)));
+
+/** Default full case folding (status C and F), so `ß` folds to `ss`. @param {string} value */
+function fullCasefold(value) {
+  if (ASCII.test(value)) return value.toLowerCase();
+  let folded = "";
+  for (const char of value) folded += tables().casefold.get(char.codePointAt(0) ?? 0) ?? char;
+  return folded;
+}
+
+/** Whether every code point is assigned in Unicode 15.1. @param {string} value */
+export function allAssigned(value) {
+  const { starts, ends } = tables();
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    let low = 0;
+    let high = starts.length;
+    while (low < high) {
+      const middle = (low + high) >>> 1;
+      if ((starts[middle] ?? Infinity) <= code) low = middle + 1;
+      else high = middle;
+    }
+    if (low === 0 || code > (ends[low - 1] ?? -1)) return false;
+  }
+  return true;
+}
+
+/** Directory names repeat across a manifest's paths, and each segment is keyed twice (policy, then collisions). */
+const KEYS_KEPT = 16384;
+/** @type {Map<string, string>} */
+const keys = new Map();
+
+/** The spelling two names share on a case-insensitive or normalizing filesystem: NFC(casefold(NFC(value))).
+ * @param {string} value */
+export function comparisonKey(value) {
+  const known = keys.get(value);
+  if (known !== undefined) return known;
+  const key = nfc(fullCasefold(nfc(value)));
+  if (keys.size >= KEYS_KEPT) keys.clear();
+  keys.set(value, key);
+  return key;
+}

package/src/sources/upload.mjs

@@ -0,0 +1,201 @@
+// @ts-check
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { NotWritable, uploadNeeded } from "./uploadFiles.mjs";
+import { parseStoredManifest } from "./manifest.mjs";
+import { SyncApiError } from "./errors.mjs";
+
+/** @typedef {import("./adapterTypes.js").SourceRun} SourceRun
+ * @typedef {Pick<SourceRun, "binding" | "api" | "store">} SourceUpload
+ * @typedef {import("./types.js").UploadReceipt} UploadReceipt */
+/** @param {SourceUpload & Pick<SourceRun, "manifest">} run */
+async function begin(run) {
+  const { binding, manifest, api, store } = run;
+  if (!binding.inflight) {
+    binding.inflight = {
+      idempotencyKey: randomUUID(),
+      baseSnapshotId: binding.base?.snapshotId ?? null,
+      resolvesConflictSnapshotIds: [],
+      summary: null,
+      manifest: manifest.document,
+      manifestSha256: manifest.sha256,
+      uploadId: null,
+      snapshotId: null,
+      uploadDeadline: null,
+      verificationDeadline: null,
+      begunAt: Date.now(),
+      sent: [],
+      multipart: {},
+    };
+    await store.write(binding);
+  }
+  const inflight = binding.inflight;
+  const receipt = await api.begin(binding.ownerSpaceId, binding.compositionId, {
+    ...inflight,
+    manifest,
+  });
+  assertReceipt(binding, receipt);
+  Object.assign(inflight, {
+    uploadId: receipt.uploadId,
+    snapshotId: receipt.snapshotId,
+    uploadDeadline: receipt.uploadDeadline,
+    verificationDeadline: receipt.verificationDeadline,
+  });
+  await store.write(binding);
+  return receipt;
+}
+/** @param {SourceRun} run @param {import("./types.js").BeginResult} receipt */
+async function sendFiles(run, receipt) {
+  const { binding, manifest, store } = run;
+  if (!binding.inflight) throw new Error("Missing source upload intent.");
+  const local = new Map(
+    manifest.document.files.map((file) => [
+      file.sha256,
+      { path: file.path, full: join(binding.projectPath, file.path) },
+    ]),
+  );
+  const known = new Map(manifest.document.files.map((file) => [file.sha256, file.size]));
+  for (const blob of receipt.needed)
+    if (known.get(blob.sha256) !== blob.size)
+      throw new Error("Upload requested an unknown source file.");
+  let persisted = Promise.resolve();
+  await uploadNeeded({
+    api: run.api,
+    space: binding.ownerSpaceId,
+    composition: binding.compositionId,
+    uploadId: receipt.uploadId,
+    inflight: binding.inflight,
+    local,
+    needed: receipt.needed,
+    fetchImpl: run.fetchImpl,
+    wait: run.wait,
+    signal: run.signal,
+    now: Date.now,
+    persist: () => {
+      persisted = persisted.then(() => store.write(binding));
+    },
+    onBytes: run.onProgress,
+    onFile: () => {},
+  }).finally(() => persisted);
+  return run.api.submit(binding.ownerSpaceId, binding.compositionId, receipt.uploadId);
+}
+/** @param {SourceUpload["binding"]} binding @param {UploadReceipt} receipt */
+function assertReceipt(binding, receipt) {
+  const saved = binding.inflight;
+  if (!saved || receipt.manifestSha256 !== saved.manifestSha256)
+    throw new Error("Source upload receipt does not match the captured project.");
+  if (receipt.compositionId !== binding.compositionId)
+    throw new Error("Source upload receipt does not match the composition.");
+  if (saved.uploadId !== null && receipt.uploadId !== saved.uploadId)
+    throw new Error("Source upload receipt identity changed.");
+  if (saved.snapshotId !== null && receipt.snapshotId !== saved.snapshotId)
+    throw new Error("Source snapshot identity changed.");
+}
+
+/** @param {SourceUpload} job @param {UploadReceipt} receipt */
+async function storePublished({ binding, store }, receipt) {
+  const saved = binding.inflight;
+  const result = receipt.result;
+  if (!saved || !result || result.snapshotId !== receipt.snapshotId)
+    throw new Error("Source snapshot identity changed.");
+  binding.base = {
+    snapshotId: result.snapshotId,
+    manifest: saved.manifest,
+    manifestSha256: saved.manifestSha256,
+  };
+  await clearIntent({ binding, store });
+}
+
+/** @param {Pick<SourceUpload, "binding" | "store">} job */
+async function clearIntent({ binding, store }) {
+  binding.inflight = null;
+  await store.write(binding);
+}
+
+/** @param {SourceUpload} job @param {UploadReceipt} receipt */
+async function cancelPending({ binding, api }, receipt) {
+  const { ownerSpaceId, compositionId } = binding;
+  try {
+    return await api.cancel(ownerSpaceId, compositionId, receipt.uploadId);
+  } catch (error) {
+    if (!(error instanceof SyncApiError) || error.kind !== "upload-not-pending") throw error;
+    return api.status(ownerSpaceId, compositionId, receipt.uploadId);
+  }
+}
+
+/** Resolve an older capture before starting an upload for the current files.
+ * @param {SourceUpload} job @returns {Promise<import("./adapterTypes.js").SourceResult | null>} */
+export async function recoverSourceUpload(job) {
+  const { binding, api } = job;
+  const saved = binding.inflight;
+  if (!saved) return null;
+  const manifest = parseStoredManifest(saved.manifest);
+  if (manifest.sha256 !== saved.manifestSha256)
+    throw new Error("Saved source upload manifest does not match its checksum.");
+  let receipt = saved.uploadId
+    ? await api.status(binding.ownerSpaceId, binding.compositionId, saved.uploadId)
+    : await begin({ ...job, manifest });
+  assertReceipt(binding, receipt);
+  if (receipt.status === "pending") receipt = await cancelPending(job, receipt);
+  assertReceipt(binding, receipt);
+  return recoverReceipt(job, receipt);
+}
+
+/** @param {SourceUpload} job @param {UploadReceipt} receipt */
+async function recoverReceipt(job, receipt) {
+  if (receipt.status === "completed") {
+    if (receipt.result?.publicationOutcome !== "published")
+      return { at: /** @type {const} */ ("unavailable"), reason: "source_conflict" };
+    await storePublished(job, receipt);
+  } else if (terminalFailure(receipt)) await clearIntent(job);
+  else return { at: /** @type {const} */ ("unavailable"), reason: "source_verification_pending" };
+  return null;
+}
+
+/** @param {UploadReceipt} receipt */
+const terminalFailure = (receipt) => receipt.status === "failed" || receipt.status === "expired";
+
+/** Only published verification results can become share source; conflict_saved is preserved for explicit recovery.
+ * @param {SourceRun} run @returns {Promise<import("./adapterTypes.js").SourceResult>} */
+export async function uploadSource(run) {
+  const receipt = await begin(run);
+  let status;
+  try {
+    status = receipt.status === "pending" ? await sendFiles(run, receipt) : receipt;
+  } catch (error) {
+    if (!(error instanceof NotWritable)) throw error;
+    return (
+      (await recoverSourceUpload(run)) ?? {
+        at: "unavailable",
+        reason: "source_upload_not_writable",
+      }
+    );
+  }
+  const deadline = Date.now() + run.timeoutMs;
+  while (status.status === "verifying") {
+    run.signal.throwIfAborted();
+    if (Date.now() >= deadline) return { at: "unavailable", reason: "source_verification_pending" };
+    await run.wait(1000, run.signal);
+    status = await run.api.status(
+      run.binding.ownerSpaceId,
+      run.binding.compositionId,
+      receipt.uploadId,
+    );
+  }
+  assertReceipt(run.binding, status);
+  if (status.status !== "completed" || !status.result) {
+    if (terminalFailure(status)) await clearIntent(run);
+    return { at: "unavailable", reason: status.errorCode ?? `source_upload_${status.status}` };
+  }
+  if (status.result.publicationOutcome !== "published")
+    return { at: "unavailable", reason: "source_conflict" };
+  await storePublished(run, status);
+  return {
+    at: "ready",
+    snapshot: {
+      space_id: run.binding.ownerSpaceId,
+      composition_id: run.binding.compositionId,
+      snapshot_id: status.snapshotId,
+    },
+  };
+}

package/src/sources/uploadFiles.mjs

@@ -0,0 +1,263 @@
+// @ts-check
+// The files a Begin said are needed, written to the upload's staging through signed URLs: one PUT for a file up to
+// 64 MiB, parts of 64 MiB above that through the file's one pinned multipart upload. URLs live at most 15 minutes, so
+// one about to end is asked for again; a send resumed after a quit skips what the in-flight record says was written.
+import { SyncApiError } from "./errors.mjs";
+import {
+  TransferError,
+  backoffMs,
+  eachLimit,
+  isAbort,
+  partDigests,
+  putRange,
+} from "./transfer.mjs";
+import { lstat } from "node:fs/promises";
+
+/** @typedef {import("./types.js").FileGrant} FileGrant @typedef {import("./types.js").GrantRequest} GrantRequest
+ * @typedef {import("./types.js").InflightUpload} InflightUpload */
+
+/** The server's single-PUT ceiling and part size. */
+const PART_BYTES = 64 * 1024 * 1024;
+const GRANT_FILES = 100;
+const PARTS_PER_GRANT = 8;
+const AT_ONCE = 4;
+const ATTEMPTS = 5;
+/** A URL with less than this left is asked for again rather than started. */
+const URL_MARGIN_MS = 60_000;
+
+/** The file's multipart upload can take no more parts (`hyperframes_composition_upload_file_not_writable`): this
+ * upload cannot finish, so its owner must resolve it before a retry can begin a new one. */
+export class NotWritable extends Error {
+  constructor() {
+    super("composition sync: a file's multipart upload can no longer take parts");
+    this.name = "NotWritable";
+  }
+}
+
+/** @typedef {import("./types.js").UploadJob} UploadJob */
+
+/** @param {UploadJob} job @param {unknown} error @param {number} attempt the attempt that just failed, from 1
+ * @returns {Promise<boolean>} whether to try again */
+async function againAfter(job, error, attempt) {
+  if (attempt >= ATTEMPTS || isAbort(error)) return false;
+  const transient =
+    (error instanceof TransferError && (error.kind === "transient" || error.kind === "corrupt")) ||
+    (error instanceof SyncApiError &&
+      ["offline", "unavailable", "server-error", "rate-limited"].includes(error.kind));
+  if (!transient) return false;
+  const asked = error instanceof SyncApiError ? error.retryAfterMs : null;
+  await job.wait(backoffMs(attempt, asked), job.signal);
+  return true;
+}
+
+/** A refusal of a pinned multipart id, which its refusal says to drop and ask again without.
+ * @param {unknown} error @param {GrantRequest[]} asked */
+const wrongPinnedId = (error, asked) =>
+  error instanceof SyncApiError &&
+  error.kind === "invalid-parameter" &&
+  (error.param ?? "").endsWith("multipart_upload_id") &&
+  asked.some((file) => file.multipartUploadId);
+
+/** Write grants for `files`, sent again on a transient failure. A file that can take no more parts throws NotWritable.
+ * @param {UploadJob} job @param {GrantRequest[]} files @returns {Promise<FileGrant[]>} */
+async function grant(job, files) {
+  let asked = files;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await job.api.uploadUrls(job.space, job.composition, job.uploadId, asked);
+    } catch (error) {
+      if (error instanceof SyncApiError && error.kind === "file-not-writable")
+        throw new NotWritable();
+      if (wrongPinnedId(error, asked))
+        asked = asked.map(({ multipartUploadId: _dropped, ...file }) => file);
+      else if (!(await againAfter(job, error, attempt))) throw error;
+    }
+  }
+}
+
+/** @param {UploadJob} job @param {string} sha256 */
+function localFile(job, sha256) {
+  const file = job.local.get(sha256);
+  if (!file) throw new Error(`composition sync: needed file ${sha256} is not in the capture`);
+  return file;
+}
+
+/** @typedef {{ url: string, headers: Record<string, string>, expiresAt: string }} Signed
+ * @typedef {{ number: number, sha256: string, start: number, length: number }} Part
+ * @typedef {{ file: { path: string, full: string }, start: number, length: number, sha256: string }} Bytes */
+
+/** One PUT attempt: `done` once stored (or found already stored), `expired` when storage says the URL has, else the
+ * failure. Bytes counted for an attempt that failed are taken back.
+ * @param {UploadJob} job @param {Signed} held @param {Bytes} bytes
+ * @returns {Promise<"done" | "expired" | { failed: unknown }>} */
+async function attemptPut(job, held, { file, ...range }) {
+  let sent = 0;
+  try {
+    await putRange({
+      fetchImpl: job.fetchImpl,
+      url: held.url,
+      headers: held.headers,
+      file: file.full,
+      path: file.path,
+      ...range,
+      signal: job.signal,
+      onBytes: (count) => ((sent += count), job.onBytes(count)),
+    });
+    return "done";
+  } catch (error) {
+    job.onBytes(-sent);
+    if (!(error instanceof TransferError)) return { failed: error };
+    if (error.kind === "exists") return (job.onBytes(range.length), "done");
+    return error.kind === "expired" ? "expired" : { failed: error };
+  }
+}
+
+/** Writes `bytes` through `given`, or a fresh grant when it is missing or about to end; asks again when storage says
+ * the URL ended, and sends again after a transient failure.
+ * @param {UploadJob} job @param {Signed | null} given @param {() => Promise<Signed>} fresh @param {Bytes} bytes */
+async function putWithGrant(job, given, fresh, bytes) {
+  const usable = (/** @type {Signed | null} */ signed) =>
+    signed && Date.parse(signed.expiresAt) - job.now() >= URL_MARGIN_MS ? signed : null;
+  let held = usable(given);
+  for (let attempt = 1; ; attempt++) {
+    held ??= await fresh();
+    const outcome = await attemptPut(job, held, bytes);
+    if (outcome === "done") return;
+    if (outcome === "expired" && attempt < ATTEMPTS) held = null;
+    else {
+      const failed = outcome === "expired" ? new TransferError("expired") : outcome.failed;
+      if (!(await againAfter(job, failed, attempt))) throw failed;
+    }
+  }
+}
+
+/** @param {FileGrant | undefined} held @returns {Signed} */
+function singleUrl(held) {
+  if (!held?.url) throw new Error("composition sync: a single-PUT grant came without its URL");
+  return { url: held.url, headers: held.headers, expiresAt: held.expiresAt };
+}
+
+/** Files up to 64 MiB: grants a hundred at a time, written four at once. @param {UploadJob} job
+ * @param {{ sha256: string, size: number }[]} blobs */
+async function sendSmall(job, blobs) {
+  for (let at = 0; at < blobs.length; at += GRANT_FILES) {
+    const batch = blobs.slice(at, at + GRANT_FILES);
+    const grants = await grant(
+      job,
+      batch.map((blob) => ({ sha256: blob.sha256 })),
+    );
+    const bySha = new Map(grants.map((one) => [one.sha256, one]));
+    await eachLimit(batch, AT_ONCE, async (blob) => {
+      const given = bySha.has(blob.sha256) ? singleUrl(bySha.get(blob.sha256)) : null;
+      const fresh = async () => singleUrl((await grant(job, [{ sha256: blob.sha256 }]))[0]);
+      const bytes = {
+        file: localFile(job, blob.sha256),
+        start: 0,
+        length: blob.size,
+        sha256: blob.sha256,
+      };
+      await putWithGrant(job, given, fresh, bytes);
+      (job.inflight.sent ??= []).push(blob.sha256);
+      job.persist();
+      job.onFile();
+    });
+  }
+}
+
+/** Grants for `parts` of a multipart file, naming its pinned upload once one is known, and keeping the id the server
+ * pins. @param {UploadJob} job @param {{ sha256: string }} blob @param {Part[]} parts */
+async function partGrants(job, blob, parts) {
+  const pinned = job.inflight.multipart?.[blob.sha256];
+  const [held] = await grant(job, [
+    {
+      sha256: blob.sha256,
+      ...(pinned && { multipartUploadId: pinned.uploadId }),
+      parts: parts.map((part) => ({ partNumber: part.number, sha256: part.sha256 })),
+    },
+  ]);
+  if (!held?.multipartUploadId)
+    throw new Error("composition sync: a multipart grant came without its upload id");
+  // Parts recorded as written belong to the pinned upload; another id would leave them unwritten.
+  if (pinned && pinned.uploadId !== held.multipartUploadId) throw new NotWritable();
+  if (!pinned) {
+    job.inflight.multipart = {
+      ...job.inflight.multipart,
+      [blob.sha256]: { uploadId: held.multipartUploadId, partsDone: [] },
+    };
+    job.persist();
+  }
+  return { expiresAt: held.expiresAt, parts: held.parts };
+}
+
+/** The file's parts still to write, each with its SHA-256; throws `changed` when the file no longer hashes to the
+ * captured SHA-256. @param {UploadJob} job @param {{ sha256: string, size: number }} blob
+ * @returns {Promise<Part[]>} */
+async function partsToSend(job, blob) {
+  const file = localFile(job, blob.sha256);
+  const digests = await partDigests(file.full, blob.size, PART_BYTES, job.signal).catch((error) => {
+    if (isAbort(error)) throw error;
+    throw new TransferError("unreadable", { path: file.path });
+  });
+  if (digests.whole !== blob.sha256 || !digests.complete)
+    throw new TransferError("changed", { path: file.path });
+  const done = new Set(job.inflight.multipart?.[blob.sha256]?.partsDone ?? []);
+  return digests.parts
+    .map((sha256, index) => ({
+      number: index + 1,
+      sha256,
+      start: index * PART_BYTES,
+      length: Math.min(PART_BYTES, blob.size - index * PART_BYTES),
+    }))
+    .filter((part) => !done.has(part.number));
+}
+
+/** A file over 64 MiB, eight parts a grant, four parts at once; its size and time are compared after, so a file that
+ * changed while its parts were read fails as changed. @param {UploadJob} job
+ * @param {{ sha256: string, size: number }} blob */
+async function sendLarge(job, blob) {
+  const file = localFile(job, blob.sha256);
+  const before = await lstat(file.full);
+  const parts = await partsToSend(job, blob);
+  job.onBytes(blob.size - parts.reduce((sum, part) => sum + part.length, 0));
+  for (let at = 0; at < parts.length; at += PARTS_PER_GRANT) {
+    const batch = parts.slice(at, at + PARTS_PER_GRANT);
+    const granted = await partGrants(job, blob, batch);
+    const byNumber = new Map(granted.parts.map((part) => [part.partNumber, part]));
+    await eachLimit(batch, AT_ONCE, async (part) => {
+      const signed = byNumber.get(part.number);
+      const given = signed
+        ? { url: signed.url, headers: signed.headers, expiresAt: granted.expiresAt }
+        : null;
+      const fresh = async () => {
+        const again = await partGrants(job, blob, [part]);
+        const one = again.parts[0];
+        if (!one) throw new Error("composition sync: a part grant came without its part");
+        return { url: one.url, headers: one.headers, expiresAt: again.expiresAt };
+      };
+      await putWithGrant(job, given, fresh, { file, ...part });
+      job.inflight.multipart?.[blob.sha256]?.partsDone.push(part.number);
+      job.persist();
+    });
+  }
+  const after = await lstat(file.full).catch(() => null);
+  if (!after || after.size !== before.size || after.mtimeMs !== before.mtimeMs)
+    throw new TransferError("changed", { path: file.path });
+  (job.inflight.sent ??= []).push(blob.sha256);
+  job.persist();
+  job.onFile();
+}
+
+/** Writes every needed file the in-flight record does not list as sent. @param {UploadJob} job */
+export async function uploadNeeded(job) {
+  const sent = new Set(job.inflight.sent ?? []);
+  const waiting = job.needed.filter((blob) => !sent.has(blob.sha256));
+  for (const blob of job.needed.filter((one) => sent.has(one.sha256))) {
+    job.onBytes(blob.size);
+    job.onFile();
+  }
+  await sendSmall(
+    job,
+    waiting.filter((blob) => blob.size <= PART_BYTES),
+  );
+  for (const blob of waiting.filter((one) => one.size > PART_BYTES)) await sendLarge(job, blob);
+}