@hyperframes/share 0.9.27 → 0.9.28-alpha.0

package/src/reviewExport.mjs

@@ -39,9 +39,10 @@ import { versionSentence } from "./reviewVersionSentences.mjs";
  * definitive result; `reviewSent`: cleanup cutoff, with attribution only when the accepted attempt is
  * known; `last`: the newest version.
  * @typedef {{ pending: { body: ExportRequest, videoId: string | null, projectId?: string | null,
- *   checkingSince?: number, snapshotRefused?: boolean, unanswered?: boolean, reviewSent?: ReviewSent } | null,
- *   last: { fingerprint: string, versionId: string, exportedAt: string, projectId: string, files?: boolean, checksum?: string }
- *   | null }} VersionRecord */
+ *   renderKey?: string, checkingSince?: number, snapshotRefused?: boolean, unanswered?: boolean, reviewSent?: ReviewSent } | null,
+ *   last: { fingerprint: string, versionId: string, exportedAt: string, projectId: string, files?: boolean,
+ *     snapshot?: ExportRequest["snapshot"], checksum?: string }
+ *   | null, failure?: (Failure & { projectId: string }) | null }} VersionRecord */
 
 /** `onAdded`: a version went ready, with whether it carries files and whether it is the page's first from here.
  * @typedef {{ onProgress?: (progress: ReviewExportProgress | null) => void, onUploaded?: () => Promise<void>,
@@ -49,10 +50,11 @@ import { versionSentence } from "./reviewVersionSentences.mjs";
 
 /** `projectId` overrides the recorded review project; `open`: a held video is watched only while the project is open.
  * `filesForExport`: the synced snapshot a new version carries, null for
- * none.
+ * none. `allowPending` lets a host treat accepted processing or screening as a successful return.
  * @typedef {VersionHooks & { projectPath: string, title: string, client: ReviewClient, put?: typeof putFile,
  *   sleep?: (ms: number) => Promise<void>, probe?: (file: string) => Promise<VideoFacts | null>, now?: () => number,
- *   projectId?: string | null, filesForExport?: FilesForRender, fromReview?: FromReview | null }} VersionRequest */
+ *   projectId?: string | null, filesForExport?: FilesForRender, fromReview?: FromReview | null,
+ *   allowPending?: boolean, requireSource?: boolean, omitSource?: boolean }} VersionRequest */
 
 /** The snapshot of `rendered`, the project as the export was rendered; null when the folder is not that render.
  * @typedef {(projectPath: string, rendered: string | null) => Promise<import("./types/reviewWire.js").SnapshotRef | null>}
@@ -177,18 +179,36 @@ function isLast(value) {
     isSavedId(value.versionId) &&
     isSavedId(value.exportedAt) &&
     isSavedId(value.projectId) &&
+    isLastMetadata(value)
+  );
+}
+
+/** @param {Record<string, unknown>} value */
+function isLastMetadata(value) {
+  return (
     isOptionalBoolean(value.files) &&
+    isOptionalSnapshot(value.snapshot) &&
     (value.checksum === undefined || isSavedId(value.checksum))
   );
 }
 
 /** @param {Record<string, unknown>} saved
- * @returns {saved is {pending?: VersionRecord["pending"], last?: SavedLast | null}} */
+ * @returns {saved is {pending?: VersionRecord["pending"], last?: SavedLast | null, failure?: unknown}} */
 const isExportState = (saved) =>
   ("pending" in saved || "last" in saved) &&
   (saved.pending == null || isPending(saved.pending)) &&
   (saved.last == null || isLast(saved.last));
 
+/** @param {unknown} value @returns {value is Failure & { projectId: string }} */
+const isSavedFailure = (value) =>
+  isJsonObject(value) &&
+  isSavedId(value.projectId) &&
+  typeof value.exportKey === "string" &&
+  typeof value.sentence === "string" &&
+  typeof value.final === "boolean" &&
+  typeof value.exportHelps === "boolean" &&
+  isOptionalBoolean(value.held);
+
 /** @param {string} dir @returns {Promise<VersionRecord>} */
 async function readState(dir) {
   const file = statePath(dir);
@@ -198,6 +218,7 @@ async function readState(dir) {
   const { last, pending } = saved;
   return {
     pending: pending ?? null,
+    failure: isSavedFailure(saved.failure) ? saved.failure : null,
     last: typeof last?.fingerprint === "string" ? { ...last, fingerprint: last.fingerprint } : null,
   };
 }
@@ -234,7 +255,7 @@ const failures = new Map();
 /** Which export a failure was about: the newest export file and the project as it was rendered. @param {string} dir */
 const exportKeyOf = (dir) => {
   const latest = latestExportFile(dir);
-  return latest ? `${latest.path}\n${latest.fingerprint ?? ""}` : "";
+  return latest ? `${latest.path}\n${latest.fingerprint ?? ""}\n${latest.id}` : "";
 };
 
 /** Whether the newest export can go up now: there is one, it is MP4, and the project has not moved past it.
@@ -259,7 +280,8 @@ export async function reviewVersion(projectPath, server = {}) {
   const last = state.last?.projectId === projectId ? state.last : null;
   const onServer =
     server.latestReadyVersionId === undefined || server.latestReadyVersionId === last?.versionId;
-  const failed = failures.get(key);
+  const savedFailure = state.failure?.projectId === projectId ? state.failure : null;
+  const failed = savedFailure ?? failures.get(key);
   return {
     last: last
       ? { exportedAt: last.exportedAt, current: last.fingerprint === now && onServer }
@@ -279,8 +301,8 @@ export async function reviewVersion(projectPath, server = {}) {
 
 /** The newest MP4 and the body that adds it; a stale, non-MP4, too big or too long export never sends anything.
  * @param {string} dir @param {string} title @param {(file: string) => Promise<VideoFacts | null>} probe
- * @param {FilesForRender} filesForExport */
-async function exportSource(dir, title, probe, filesForExport) {
+ * @param {FilesForRender} filesForExport @param {boolean} requireSource */
+async function exportSource(dir, title, probe, filesForExport, requireSource) {
   const latest = latestExportFile(dir);
   if (!latest || sourceOf(dir, await projectFingerprint(dir)) !== "ready")
     return { failure: local("Export an MP4 of the project as it is now first.") };
@@ -307,18 +329,34 @@ async function exportSource(dir, title, probe, filesForExport) {
       content_type: "video/mp4",
     },
   };
-  const snapshot = await filesForExport(dir, body.source_fingerprint).catch((error) => {
-    // expected: the version still goes up, and Share's files line says it has no files and offers Sync now.
-    console.error(
-      "[review files] couldn't read the synced snapshot; the version goes up without files:",
-      error,
-    );
-    return null;
-  });
+  const snapshot = await sourceSnapshot(
+    dir,
+    body.source_fingerprint,
+    filesForExport,
+    requireSource,
+  );
+  if (missingRequiredSource(requireSource, snapshot))
+    return {
+      failure: local(
+        "Source changed after preparation. Retry sharing, or choose video-only explicitly.",
+      ),
+    };
   if (snapshot) body.snapshot = snapshot;
   return { file: latest.path, body };
 }
 
+/** @param {boolean} required @param {import("./types/reviewWire.js").SnapshotRef | null} snapshot */
+const missingRequiredSource = (required, snapshot) => required && !snapshot;
+
+/** @param {string} dir @param {string | null} rendered @param {FilesForRender} filesForExport @param {boolean} requireSource */
+async function sourceSnapshot(dir, rendered, filesForExport, requireSource) {
+  return filesForExport(dir, rendered).catch((error) => {
+    if (requireSource) throw error;
+    console.error("[review files] could not read source; adding video only:", error);
+    return null;
+  });
+}
+
 /** @param {ExportRequest["snapshot"]} a @param {ExportRequest["snapshot"]} b */
 const sameSnapshot = (a, b) =>
   a?.space_id === b?.space_id &&
@@ -368,7 +406,7 @@ async function createdExport(r, id, pending, kept) {
     return await sendCreate(r, id, pending, kept);
   } catch (error) {
     const refused = error instanceof ReviewFailed && error.reason === "snapshot_mismatch";
-    if (!refused || !pending.body.snapshot || pending.unanswered) throw error;
+    if (!refused || !pending.body.snapshot || pending.unanswered || r.requireSource) throw error;
     console.error("[review] snapshot refused; the version goes up without files:", error);
     const body = { ...pending.body, client_operation_id: `export-${randomUUID()}` };
     delete body.snapshot;
@@ -564,17 +602,31 @@ const spent = (error, pending) =>
  * @param {string} id @param {ExportDTO} done @param {FromReview | null} fromReview @returns {Promise<Said | null>} */
 async function finish(dir, state, pending, id, done, fromReview) {
   const ready = done.status === "ready";
-  const last = {
-    fingerprint: pending.body.source_fingerprint ?? "",
-    versionId: done.version_id,
-    exportedAt: done.exported_at,
-    projectId: id,
-    files: Boolean(pending.body.snapshot),
-    checksum: pending.body.local_upload.checksum_sha256,
-  };
-  await writeState(dir, { pending: null, last: ready ? last : state.last });
+  const last = readyRecord(pending, id, done);
+  const failure = ready ? null : said(new ReviewFailed(200, done.error?.reason ?? ""));
+  await writeState(dir, {
+    pending: null,
+    last: ready ? last : state.last,
+    ...(failure && {
+      failure: { ...failure, projectId: id, exportKey: await failedExportKey(dir, pending) },
+    }),
+  });
   if (ready) await sharedFromReview(fromReview, dir, pending.reviewSent?.since);
-  return ready ? null : said(new ReviewFailed(200, done.error?.reason ?? ""));
+  return failure;
+}
+
+/** @param {string} dir @param {NonNullable<VersionRecord["pending"]>} pending */
+async function failedExportKey(dir, pending) {
+  if (typeof pending.renderKey === "string") return pending.renderKey;
+  const latest = latestExportFile(dir);
+  if (!latest) return "";
+  const checksum =
+    latest.fingerprint === pending.body.source_fingerprint
+      ? await fileSha256Base64(latest.path).catch(() => null)
+      : null;
+  return checksum === pending.body.local_upload.checksum_sha256
+    ? exportKeyOf(dir)
+    : `pending:${pending.body.client_operation_id}`;
 }
 
 /** @param {Required<VersionRequest>} r @param {(progress: ReviewExportProgress) => void} report
@@ -582,17 +634,37 @@ async function finish(dir, state, pending, id, done, fromReview) {
 async function run(r, report) {
   report({ step: "preparing", sent: 0, total: 0 });
   const state = await readState(r.projectPath);
-  const source = await exportSource(r.projectPath, r.title, r.probe, r.filesForExport);
+  const source = await exportSource(
+    r.projectPath,
+    r.title,
+    r.probe,
+    r.omitSource ? noSource : r.filesForExport,
+    r.requireSource,
+  );
   if ("failure" in source) return source.failure ?? null;
   const id = r.projectId ?? (await reviewProjectId(r.projectPath));
   if (!id) return local("Share the project first, then add a version.");
-  if (await alreadyUploaded(r.client, id, state, source.body)) return null;
+  if (
+    sameSourceMode(r, state.last, source.body.snapshot) &&
+    (await alreadyUploaded(r.client, id, state, source.body))
+  )
+    return null;
   return sendVersion(r, report, source, id, state);
 }
+const noSource = async () => null;
+
+/** @param {Required<VersionRequest>} r @param {VersionRecord["last"]} last @param {ExportRequest["snapshot"]} snapshot */
+function sameSourceMode(r, last, snapshot) {
+  if (r.requireSource) return sameSnapshot(last?.snapshot, snapshot);
+  if (r.omitSource) return last?.files !== true;
+  return true;
+}
+
 /** @param {ReviewClient} client @param {string} id @param {VersionRecord} state @param {ExportRequest} body */
 async function alreadyUploaded(client, id, state, body) {
   const last = state.last;
-  if (state.pending || !last || last.projectId !== id) return false;
+  if (state.pending || state.failure?.projectId === id || !last || last.projectId !== id)
+    return false;
   if (
     last.fingerprint !== body.source_fingerprint ||
     last.checksum !== body.local_upload.checksum_sha256
@@ -604,8 +676,10 @@ async function alreadyUploaded(client, id, state, body) {
  * @param {{file: string, body: ExportRequest}} source @param {string} id @param {VersionRecord} state */
 async function sendVersion(r, report, source, id, state) {
   const first = state.last?.projectId !== id;
-  let pending = bodyToSend(state, source.body, id);
-  await writeState(r.projectPath, (state = { ...state, pending }));
+  let pending = bindRenderKey(bodyToSend(state, source.body, id), r.projectPath);
+  const sourceConflict = pendingSourceConflict(r, pending, source.body);
+  if (sourceConflict) return local(sourceConflict);
+  await writeState(r.projectPath, (state = { ...state, pending, failure: null }));
   try {
     const answer = await createdExport(r, id, pending, (next) =>
       writeState(r.projectPath, (state = { ...state, pending: next })),
@@ -637,10 +711,21 @@ async function sendVersion(r, report, source, id, state) {
   }
 }
 
+/** @param {Required<VersionRequest>} r @param {NonNullable<VersionRecord["pending"]>} pending @param {ExportRequest} fresh */
+function pendingSourceConflict(r, pending, fresh) {
+  if (r.requireSource && !pending.body.snapshot)
+    return "A pending video-only upload must finish before attaching source. Retry with --video-only, then share source again.";
+  if (r.omitSource && pending.body.snapshot)
+    return "A pending upload includes source. Check its status or retry with source before creating a video-only version.";
+  if (r.requireSource && !sameSnapshot(pending.body.snapshot, fresh.snapshot))
+    return "A pending upload includes a different source snapshot. Check its status before sharing again.";
+  return null;
+}
+
 /** @param {Required<VersionRequest>} r @param {VersionRecord} state
  * @param {NonNullable<VersionRecord["pending"]>} pending @param {string} id @param {ExportDTO} done @param {boolean} first */
 async function finishRun(r, state, pending, id, done, first) {
-  if (going(done)) return stillGoing(done);
+  if (going(done)) return r.allowPending ? null : stillGoing(done);
   const failed = await finish(r.projectPath, state, pending, id, done, r.fromReview);
   if (!failed) {
     const fromReview = pending.reviewSent?.value;
@@ -663,8 +748,11 @@ export async function addVersion(request) {
     now: () => Date.now(),
     onProgress: () => {},
     open: () => true,
-    filesForExport: async () => null,
+    allowPending: false,
+    filesForExport: noSource,
     fromReview: null,
+    requireSource: false,
+    omitSource: false,
     onAdded: () => {},
     ...request,
     projectId: request.projectId ?? null,
@@ -755,7 +843,7 @@ async function settleSavedExport(dir, client, fromReview) {
   const id = await reviewProjectId(dir);
   if (!pending?.videoId || !id || pending.projectId !== id) return;
   const done = await client.readExport(id, pending.videoId);
-  if (going(done)) return;
+  if (done.status === "upload_pending" || going(done)) return;
   const failure = await finish(dir, state, pending, id, done, fromReview);
   const key = normalize(dir);
   if (failure) failures.set(key, { ...failure, exportKey: exportKeyOf(dir) });
@@ -825,3 +913,23 @@ export async function pendingReviewExport(projectPath) {
     checksum: pending.body.local_upload.checksum_sha256,
   };
 }
+
+/** @param {NonNullable<VersionRecord["pending"]>} pending @param {string} id @param {ExportDTO} done */
+function readyRecord(pending, id, done) {
+  return {
+    fingerprint: pending.body.source_fingerprint ?? "",
+    versionId: done.version_id,
+    exportedAt: done.exported_at,
+    projectId: id,
+    files: Boolean(pending.body.snapshot),
+    ...(pending.body.snapshot && { snapshot: pending.body.snapshot }),
+    checksum: pending.body.local_upload.checksum_sha256,
+  };
+}
+
+/** @param {NonNullable<VersionRecord["pending"]>} pending @param {string} dir */
+function bindRenderKey(pending, dir) {
+  return typeof pending.renderKey === "string"
+    ? pending
+    : { ...pending, renderKey: exportKeyOf(dir) };
+}

package/src/reviewUpload.mjs

@@ -18,6 +18,22 @@ export function fileSha256Base64(file) {
 
 /** @typedef {"sent" | "expired" | "refused" | "offline"} PutOutcome */
 
+/** @param {string} url */
+export function trustedUploadUrl(url) {
+  if (!URL.canParse(url)) return null;
+  const target = new URL(url);
+  const loopback = target.protocol === "http:" && target.hostname === "127.0.0.1";
+  if (
+    (target.protocol !== "https:" && !loopback) ||
+    target.username ||
+    target.password ||
+    target.hash ||
+    !reviewUploadOrigins().includes(target.origin)
+  )
+    return null;
+  return target;
+}
+
 /** Streams the file to the signed URL through main's fetch (the app's proxy), the server's headers as given plus
  * the length, and no bearer. Nothing sent or answered for `stallMs` ends it as offline, never "Uploading" forever.
  * @param {{ put_url: string, headers: Record<string, string> }} upload @param {string} file @param {number} size
@@ -29,22 +45,8 @@ export async function putFile(
   onSent,
   { stallMs = 60_000, fetchImpl = fetch } = {},
 ) {
-  let target;
-  try {
-    target = new URL(upload.put_url);
-  } catch {
-    return "refused";
-  }
-  const loopback = target.protocol === "http:" && target.hostname === "127.0.0.1";
-  if (
-    (target.protocol !== "https:" && !loopback) ||
-    target.username ||
-    target.password ||
-    target.hash ||
-    !reviewUploadOrigins().includes(target.origin)
-  ) {
-    return "refused";
-  }
+  const target = trustedUploadUrl(upload.put_url);
+  if (!target) return "refused";
   const stall = new AbortController();
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;

package/src/shareSources.mjs

@@ -0,0 +1,236 @@
+// @ts-check
+import { realpath } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { projectFingerprint } from "./projectSnapshot.mjs";
+import { withProjectShareLock } from "./projectLock.mjs";
+import { captureProject } from "./sources/capture.mjs";
+import { sourceApi } from "./sources/api.mjs";
+import { createProjectShareSourceStore } from "./sources/store.mjs";
+import { realWait } from "./sources/transfer.mjs";
+import { recoverSourceUpload, uploadSource } from "./sources/upload.mjs";
+
+/** @typedef {import("./sources/adapterTypes.js").SourceResult} SourceResult
+ * @typedef {import("./sources/types.js").Binding} Binding */
+/** @param {string} reason @returns {SourceResult} */
+const unavailable = (reason) => ({ at: "unavailable", reason });
+/** Content identity for sharing, including portable hidden render inputs. The Desktop watch inventory stays separate.
+ * @param {string} projectPath @returns {Promise<string | null>} */
+export async function shareSourceFingerprint(projectPath) {
+  const capture = await captureProject(await realpath(projectPath));
+  return capture.at === "captured" && !captureRefusal(capture) ? capture.manifest.sha256 : null;
+}
+/** @param {Binding} binding @param {string} space */
+function bindingRefusal(binding, space) {
+  if (binding.ownerSpaceId !== space) return "source_other_workspace";
+  if (binding.sharedFrom) return "source_owned_by_someone_else";
+  if (binding.gettingFromCloud || binding.duplicate) return "source_operation_in_progress";
+  return null;
+}
+/** @param {import("./sources/types.js").Capture} capture */
+function captureRefusal(capture) {
+  if (capture.at === "too-big") return `source_${capture.over.limit}_exceeded`;
+  if (capture.at === "problems") return `source_${capture.problems[0]?.problem ?? "invalid"}`;
+  if (capture.settled.agentTurnOpen || capture.settled.projectLocked || capture.waiting.length)
+    return "source_edit_in_progress";
+  return null;
+}
+
+/** Prepare source explicitly before adding the video version. No unexpected network or filesystem failure is
+ * converted to video-only. `filesForExport` revalidates the prepared bytes and never starts another upload.
+ * @param {import("./sources/adapterTypes.js").SourceOptions} options */
+export function shareSources(options) {
+  const store = options.store ?? createProjectShareSourceStore();
+  const fingerprint = options.fingerprint ?? projectFingerprint;
+  const signal = options.signal ?? new AbortController().signal;
+  /** @type {Map<string, { rendered: string, digest: string, snapshot: import("./types/reviewWire.js").SnapshotRef, account: string, backend: string }>} */
+  const prepared = new Map();
+  /** @param {string} projectPath @param {string | null} rendered @returns {Promise<SourceResult>} */
+  const prepare = async (projectPath, rendered) => {
+    const root = await realpath(projectPath);
+    prepared.delete(root);
+    if (!enabled(options)) return unavailable("source_disabled");
+    if (!rendered || (await fingerprint(root)) !== rendered)
+      return unavailable("source_render_changed");
+    return withProjectShareLock(
+      root,
+      "source",
+      async () => {
+        const signed = await options.access();
+        if (!signed?.owner) return unavailable("source_signed_out");
+        const key = { backend: signed.heygenApi, account: signed.owner, projectPath: root };
+        const guardedAccess = async (/** @type {string | undefined} */ refused) => {
+          const next = await options.access(refused);
+          if (!next || next.owner !== key.account || next.heygenApi !== key.backend)
+            throw new Error("Source account or backend changed while sharing.");
+          return next;
+        };
+        const api =
+          options.api ?? sourceApi({ access: guardedAccess, fetchImpl: options.fetchImpl });
+        const { own, existing, binding } = await selectBinding(key, options, store);
+        const refused = bindingRefusal(binding, options.spaceId);
+        if (refused) return unavailable(refused);
+        const result = await prepareBinding({
+          binding,
+          own: Boolean(own),
+          external: Boolean(existing),
+          api,
+          store,
+          options,
+          signal,
+          fingerprint,
+          rendered,
+        });
+        const manifest = result.manifest;
+        await guardedAccess(undefined);
+        if (result.at !== "ready" || !manifest) return result;
+        if (!(await stillMatches(root, rendered, manifest.sha256, fingerprint)))
+          return unavailable("source_render_changed");
+        prepared.set(root, {
+          rendered,
+          digest: manifest.sha256,
+          snapshot: result.snapshot,
+          account: key.account,
+          backend: key.backend,
+        });
+        return { at: "ready", snapshot: result.snapshot };
+      },
+      { signal },
+    );
+  };
+  /** @param {string} projectPath @param {string | null} rendered */
+  const filesForExport = async (projectPath, rendered) => {
+    const root = await realpath(projectPath);
+    const held = prepared.get(root);
+    const signed = await options.access();
+    if (
+      !held ||
+      !rendered ||
+      held.rendered !== rendered ||
+      !sameOwner(signed, held) ||
+      !enabled(options)
+    )
+      return null;
+    return (await stillMatches(root, rendered, held.digest, fingerprint)) ? held.snapshot : null;
+  };
+  return { prepare, filesForExport };
+}
+
+/** @param {import("./sources/adapterTypes.js").SourceOptions} options */
+const enabled = (options) => options.enabled?.() ?? true;
+/** @param {Awaited<ReturnType<import("./signedInRequest.mjs").SignedInAccess>>} signed
+ * @param {{account: string, backend: string}} held */
+const sameOwner = (signed, held) =>
+  signed?.owner === held.account && signed?.heygenApi === held.backend;
+/** @typedef {{ binding: Binding, own: boolean, external: boolean, api: import("./sources/api.mjs").SourceApi,
+ * store: import("./sources/adapterTypes.js").SourceStore, options: import("./sources/adapterTypes.js").SourceOptions,
+ * signal: AbortSignal, fingerprint: (path: string) => Promise<string | null>, rendered: string }} Preparation */
+/** @param {Preparation} job @returns {Promise<SourceResult & {manifest?: import("./sources/types.js").Manifest}>} */
+async function prepareBinding(job) {
+  const { binding, api, fingerprint, rendered } = job;
+  const limits = await api.limits(binding.ownerSpaceId);
+  if (!limits.syncAllowed) return unavailable("source_plan_required");
+  const capture = await captureProject(binding.projectPath, { limits: limits.push });
+  const bad = captureRefusal(capture);
+  if (bad) return unavailable(bad);
+  if (capture.at !== "captured") return unavailable("source_invalid");
+  if ((await fingerprint(binding.projectPath)) !== rendered)
+    return unavailable("source_render_changed");
+  const result = await snapshotFor(job, capture.manifest, limits);
+  return { ...result, manifest: capture.manifest };
+}
+/** @param {Preparation} job @param {import("./sources/types.js").Manifest} manifest
+ * @param {Extract<import("./sources/types.js").SyncLimitsRead, {at: "read"}>} limits @returns {Promise<SourceResult>} */
+async function snapshotFor(job, manifest, limits) {
+  const { binding, api, store, options, signal } = job;
+  const blocked = await recoverEarlierCapture(job, manifest.sha256);
+  if (blocked) return blocked;
+  if (binding.base?.manifestSha256 === manifest.sha256 && !binding.inflight)
+    return reuseSnapshot(api, binding, manifest.sha256);
+  if (job.external) return unavailable("source_sync_required");
+  if (!job.own && limits.compositions >= limits.maxCompositions)
+    return unavailable("source_composition_limit");
+  await store.write(binding);
+  binding.composition = await api.create(
+    binding.ownerSpaceId,
+    binding.compositionId,
+    basename(binding.projectPath),
+  );
+  await store.write(binding);
+  return uploadSource({ binding, manifest, api, store, signal, ...uploadOptions(options) });
+}
+/** @param {Preparation} job @param {string} digest */
+function recoverEarlierCapture({ external, binding, api, store }, digest) {
+  const inflight = binding.inflight;
+  if (external || !inflight || inflight.manifestSha256 === digest) return null;
+  return recoverSourceUpload({ binding, api, store });
+}
+
+/** @param {import("./sources/adapterTypes.js").SourceOptions} options */
+function uploadOptions(options) {
+  return {
+    fetchImpl: options.fetchImpl ?? fetch,
+    wait: options.wait ?? realWait,
+    timeoutMs: options.verificationTimeoutMs ?? 120_000,
+    onProgress: options.onProgress ?? (() => {}),
+  };
+}
+
+/** @param {import("./sources/types.js").BindingKey} key @param {import("./sources/adapterTypes.js").SourceOptions} options
+ * @param {import("./sources/adapterTypes.js").SourceStore} store */
+async function selectBinding(key, options, store) {
+  const own = await store.read(key);
+  const existing = own ? null : await options.existingBinding?.(key);
+  return { own, existing, binding: own ?? existing ?? newBinding(key, options.spaceId) };
+}
+/** @param {import("./sources/types.js").BindingKey} key @param {string} space @returns {Binding} */
+function newBinding(key, space) {
+  return {
+    ...key,
+    version: 1,
+    compositionId: randomUUID(),
+    ownerSpaceId: space,
+    boundAt: Date.now(),
+    composition: null,
+    etag: null,
+    base: null,
+    inflight: null,
+  };
+}
+/** @param {import("./sources/api.mjs").SourceApi} api @param {Binding} binding @param {string} digest @returns {Promise<SourceResult>} */
+async function reuseSnapshot(api, binding, digest) {
+  if (!binding.base) return unavailable("source_sync_required");
+  const remote = await api.snapshot(
+    binding.ownerSpaceId,
+    binding.compositionId,
+    binding.base.snapshotId,
+  );
+  if (
+    remote.id !== binding.base.snapshotId ||
+    remote.compositionId !== binding.compositionId ||
+    remote.manifestSha256 !== digest ||
+    remote.manifest?.sha256 !== digest ||
+    remote.publicationOutcome !== "published"
+  )
+    return unavailable("source_snapshot_mismatch");
+  return {
+    at: "ready",
+    snapshot: {
+      space_id: binding.ownerSpaceId,
+      composition_id: binding.compositionId,
+      snapshot_id: remote.id,
+    },
+  };
+}
+/** @param {string} root @param {string} rendered @param {string} digest @param {(path: string) => Promise<string | null>} fingerprint */
+async function stillMatches(root, rendered, digest, fingerprint) {
+  if ((await fingerprint(root)) !== rendered) return false;
+  const capture = await captureProject(root);
+  return (
+    !captureRefusal(capture) &&
+    capture.at === "captured" &&
+    capture.manifest.sha256 === digest &&
+    (await fingerprint(root)) === rendered
+  );
+}
+export { createProjectShareSourceStore } from "./sources/store.mjs";

package/src/sources/adapterTypes.d.ts

@@ -0,0 +1,39 @@
+import type { Binding, BindingKey, Manifest } from "./types.js";
+import type { SnapshotRef } from "../types/reviewWire.js";
+import type { SignedInAccess } from "../signedInRequest.mjs";
+import type { SourceApi } from "./api.mjs";
+
+export interface SourceStore {
+  read(key: BindingKey): Promise<Binding | null>;
+  write(binding: Binding): Promise<void>;
+}
+export type SourceResult =
+  | { at: "ready"; snapshot: SnapshotRef }
+  | { at: "unavailable"; reason: string };
+export interface SourceOptions {
+  access: SignedInAccess;
+  spaceId: string;
+  store?: SourceStore;
+  enabled?: () => boolean;
+  fingerprint?: (path: string) => Promise<string | null>;
+  /** Host-owned Desktop bindings may be read for exact reuse, never overwritten. */
+  existingBinding?: (key: BindingKey) => Promise<Binding | null>;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  verificationTimeoutMs?: number;
+  onProgress?: (bytes: number) => void;
+  /** Test/host seams; the default is the authenticated v3 client. */
+  api?: SourceApi;
+  wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export interface SourceRun {
+  binding: Binding;
+  manifest: Manifest;
+  api: SourceApi;
+  store: SourceStore;
+  fetchImpl: typeof fetch;
+  signal: AbortSignal;
+  wait: (ms: number, signal?: AbortSignal) => Promise<void>;
+  timeoutMs: number;
+  onProgress: (bytes: number) => void;
+}