@gotcos/glasses-server 6.99.12 → 6.99.20

package/server/web-control/panes/messages.js

@@ -62,10 +62,16 @@
   function headline(q) {
     var s = String(q || '').replace(/\s+/g, ' ').trim();
     if (!s) return '(empty query)';
-    return s.length > 60 ? s.slice(0, 57) + '…' : s;
+    return s.length > 240 ? s.slice(0, 239) + '…' : s;
   }
   function modelOf(t) { var m = String(t.modelPreference || ''); return /^[A-Za-z0-9._:-]{1,64}$/.test(m) ? m : ''; }
-  function originTag(t) { return t.origin === 'routine' ? 'ROUTINE' : t.origin === 'task' ? 'TASK' : ''; }
+  // 6.99.15: the row says "Opus", not "opus"; a model id it does not know stays as the server wrote it.
+  var MODEL_NAMES = { opus: 'Opus', sonnet: 'Sonnet', fable: 'Fable', haiku: 'Haiku' };
+  function modelName(m) { return MODEL_NAMES[m] || m; }
+  // A preview of an answer whose progress lines were joined with no space ("now.Reading the tax"): one space after a
+  // sentence's end when the next sentence starts at once. Previews only; the reader shows the answer as written.
+  function previewText(text) { return stripMd(text).replace(/([a-z0-9)][.!?])([A-Z][a-z])/g, '$1 $2'); }
+  function originTag(t) { return t.origin === 'routine' ? 'Routine' : t.origin === 'task' ? 'Task' : ''; }
   function originTitle(t) {
     var id = t.originId ? ' (' + t.originId + ')' : '';
     return t.origin === 'routine' ? 'Produced by a scheduled routine on your Mac' + id : t.origin === 'task' ? 'Produced by an agent working a task on your Mac' + id : '';
@@ -285,8 +291,8 @@
     var detail;
     if (S.recentState === 'loading' && !S.recent) detail = 'Loading…';
     else if (S.recentState === 'error') detail = S.recentError === 'signed-out' ? 'Signed out' : 'Could not load messages';
-    else if (S.recent && S.recent.length) detail = 'Newest first · ' + S.recent.length + ' ' + W.plural(S.recent.length, 'turn', 'turns');
-    else if (S.recent) detail = 'No turns today';
+    else if (S.recent && S.recent.length) detail = S.recent.length + ' ' + W.plural(S.recent.length, 'message', 'messages') + ', newest first';
+    else if (S.recent) detail = 'No messages today';
     else detail = 'Refresh to load';
     return '<header class="cx-hero" data-tint="messages">' +
       '<span class="cx-glyph"><svg class="icon"><use href="#i-messages"/></svg></span>' +
@@ -298,7 +304,7 @@
   }
   function controlsHtml() {
     return '<div class="cx-controls">' +
-      '<div class="cx-switch" role="group" aria-label="Message view"><span class="cx-switch-label">Message view</span>' +
+      '<div class="cx-switch" role="group" aria-label="Message view">' +
         '<button type="button" data-msg="view" data-view="recent" aria-pressed="' + (S.view === 'recent') + '">Recent</button>' +
         '<button type="button" data-msg="view" data-view="archive" aria-pressed="' + (S.view === 'archive') + '">Archive</button>' +
       '</div>' +
@@ -318,24 +324,26 @@
       ? '<span>' + esc(recentSide) + '</span><span>·</span><button type="button" class="door" data-msg="view" data-view="archive">' + esc(archSide) + '<svg class="icon" aria-hidden="true"><use href="#i-chev"/></svg></button>'
       : '<button type="button" class="door" data-msg="view" data-view="recent">' + esc(recentSide) + '<svg class="icon" aria-hidden="true"><use href="#i-chev"/></svg></button><span>·</span><span>' + esc(archSide) + '</span>') + '</p>';
   }
+  // 6.99.15: one row is the ask as its title with the time beside it, the answer under it, and one quiet line of
+  // facts (number, Routine or Task, model, attachments). No glyph per row: every row was the same bubble.
   function recentRowHtml(t, i) {
     var a = atts(t);
     var kinds = a.map(attKind);
     var n = numOf(t);
     var tag = originTag(t);
     var model = modelOf(t);
-    return '<button type="button" class="cx-row" data-msg="open" data-key="' + esc(keyOf(t, i)) + '">' +
-      '<span class="cx-row-glyph"><svg class="icon"><use href="#i-messages"/></svg>' +
-        (a.length ? '<span class="cx-badge-icon"><svg class="icon"><use href="#i-' + attIcon(kinds) + '"/></svg></span>' : '') + '</span>' +
+    var facts = [];
+    if (n != null) facts.push('<span class="cx-num">#' + esc(n) + '</span>');
+    if (tag) facts.push('<span class="cx-tag" title="' + esc(originTitle(t)) + '">' + tag + '</span>');
+    if (model) facts.push('<span class="cx-model">' + esc(modelName(model)) + '</span>');
+    if (a.length) facts.push('<span class="cx-att" title="' + esc(attTitle(a)) + '"><svg class="icon"><use href="#i-' + attIcon(kinds) + '"/></svg>' + esc(attTitle(a)) + '</span>');
+    var sub = previewText(t.text);
+    return '<button type="button" class="cx-row cx-msgrow" data-msg="open" data-key="' + esc(keyOf(t, i)) + '">' +
       '<span class="cx-row-body">' +
-        '<span class="cx-meta"><span class="cx-num">' + (n != null ? 'Message #' + esc(n) : 'Message') + '</span>' +
-          '<span class="cx-time">' + esc(timeLabel(t.timestamp)) + '</span>' +
-          (tag ? '<span class="cx-tag" title="' + esc(originTitle(t)) + '">' + tag + '</span>' : '') +
-          (model ? '<span class="cx-model">' + esc(model) + '</span>' : '') +
-          (a.length ? '<span class="cx-att" title="' + esc(attTitle(a)) + '"><svg class="icon"><use href="#i-' + attIcon(kinds) + '"/></svg>' + a.length + '</span>' : '') +
-        '</span>' +
-        '<span class="cx-row-title">' + esc(headline(t.query)) + '</span>' +
-        '<span class="cx-row-sub">' + esc(stripMd(t.text)) + '</span>' +
+        '<span class="cx-msg-top"><span class="cx-row-title">' + esc(headline(t.query)) + '</span>' +
+          '<span class="cx-time">' + esc(timeLabel(t.timestamp)) + '</span></span>' +
+        (sub ? '<span class="cx-row-sub">' + esc(sub) + '</span>' : '') +
+        (facts.length ? '<span class="cx-meta cx-facts">' + facts.join('') + '</span>' : '') +
       '</span><span class="chev"></span></button>';
   }
   // The pinned COS chat, first in Recent (Drop it on only, and not while a search narrows the list).
@@ -361,8 +369,7 @@
       return '<div class="cx-list"><p class="cx-empty">No recent message contains “' + esc(q) + '”' +
         (days ? ', but ' + days + ' archived ' + W.plural(days, 'day', 'days') + ' ' + (days === 1 ? 'does' : 'do') + '.' : '. The archive goes back further.') + '</p></div>';
     }
-    return '<div class="cx-list">' + shown.map(function (t) { return recentRowHtml(t, list.indexOf(t)); }).join('') + '</div>' +
-      '<p class="cx-note">ROUTINE and TASK mark a run your Mac started.</p>';
+    return '<div class="cx-list">' + shown.map(function (t) { return recentRowHtml(t, list.indexOf(t)); }).join('') + '</div>';
   }
   function archiveBody() {
     var q = S.q.trim();

package/shared/meeting-ask.ts

@@ -33,8 +33,12 @@ export interface MeetingAskFile {
     status: 'ready' | 'pending' | 'unsupported' | 'failed' | 'removed' | 'secret-held';
     text: string;
     notice?: string;
-    /** "phone" for a file the phone attached through POST files/media (6.71.1). Control's rows omit it. */
-    origin?: 'phone';
+    /**
+     * "phone" for a file the phone attached through POST files/media (6.71.1). "prep" (6.99.19) for a copy a Prep bind
+     * adopted (id prep_<draftId>_<fileId>, or prep_<draftId>_steer for "Prep notes"). Control's own rows omit it, and a
+     * client that does not know a value shows the row as a plain file.
+     */
+    origin?: 'phone' | 'prep';
 }
 export interface MeetingAskSource {
   /** Server-owned accepted post-stop quotation; no live turn target or precise word clock. */

package/shared/prep.ts

@@ -0,0 +1,317 @@
+/**
+ * Prep v1.1 (server 6.99.19, protocol 1): notes and files added before a call, a prep run from them, and an explicit
+ * bind that carries them into the live meeting and its saved notes. Contract: PREP_CONTRACT_v1_2026-11-06.md, with its
+ * "v1.1 amendments" section (which wins where they differ).
+ *
+ * Identity rule: a draft is NEVER matched to a meeting by its title or time. `occurrence` is filled only when a client
+ * (or a future calendar bridge) supplies provider, calendarId, eventId or externalId, and startsAt; its key only FINDS a
+ * draft. Files reach a meeting only through POST /prep/drafts/:id/bind with that meeting's sessionId.
+ *
+ * Types, pure validators and the Web Crypto client job id only: no node imports, so a browser bundle can share it.
+ *
+ * Routes (all under /api, X-Cos-Token, Cache-Control: no-store; writes answer 503 {error:'maintenance'} while a
+ * maintenance drain is closing admissions). Every mutation requires the header X-COS-Expected-Server-Instance
+ * (v1.1 #19): missing is 428 {error:'server_instance_required'}, a different server is 409
+ * {error:'server_instance_mismatch'}. A body serverInstanceId is also checked when sent. Every JSON response, errors
+ * included, carries the top-level `serverInstanceId`; the original-bytes route sends it as X-COS-Server-Instance.
+ * - POST   /prep/drafts {clientDraftId,title?,startsAt?,occurrence?} -> 201 {draft} (200 and the same draft on a repeat)
+ * - GET    /prep/drafts?occurrence=&state=active&limit=20 -> {drafts}, newest first
+ * - GET    /prep/drafts/:id -> {draft}
+ * - DELETE /prep/drafts/:id -> {draft}: archives it (state 'archived'); files and snapshots stay, by-session still works
+ * - PATCH  /prep/drafts/:id {revision,title?,startsAt?,steer?,occurrence?} -> {draft}; stale -> 409 {error:'revision_conflict',draft}
+ * - POST   /prep/drafts/:id/files {operationId,revision,media:[{id,name?,sourceRef?,sha256}]} -> {draft}; over 10 -> 413
+ *          {error:'prep_file_limit'}; a copy whose sha256 differs -> 409 {error:'media_hash_mismatch'} with nothing written
+ * - DELETE /prep/drafts/:id/files/:fileId?revision=N -> {draft}
+ * - GET    /prep/drafts/:id/files/:fileId -> original bytes; GET .../text -> {text} ('' for a held or unread file)
+ * - POST   /prep/drafts/:id/run {clientRequestId,revision,model?,effort?,continue?} -> 202 {job,run,draft}. While
+ *          another run is in the way (a 'submitting' receipt, or an accepted job with no session yet), a NEW id is
+ *          409 {error:'run_in_progress', run} with no side effect; only a retry with that run's own clientRequestId
+ *          re-drives it. Replaying a failed run is 409 {error:'run_failed', run}.
+ * - GET    /prep/drafts/:id/runs/:clientRequestId -> 200 {run,job} once admitted; 202 {run} while its admission is in
+ *          flight; 404 {error:'run_not_accepted', run?} when no job exists for it and none is being admitted (a
+ *          'submitting' run left by a restart: send the same run again); 503 {error:'run_status_unknown'} when the
+ *          job lookup failed
+ * - POST   /prep/drafts/:id/bind {revision,sessionId,surface,serverInstanceId?} -> {draft,files}
+ * - DELETE /prep/drafts/:id/bind/:sessionId -> {draft}
+ * - GET    /prep/by-session/:sessionId -> {snapshots: PrepSessionSnapshot[]} (frozen per bind, never the latest draft)
+ * - GET    /prep/suggest?sessionId=&startedAt=<ms> -> {drafts}: at most 5 active drafts, nearest startsAt first (a draft
+ *          with no start after, newest first); suggestions only, never a bind
+ *
+ * Replay before CAS (v1.1 #3): a repeat of a create (clientDraftId), files call (operationId), run (clientRequestId) or
+ * bind (sessionId + revision) returns the original result without checking revision. A repeat with a different body is
+ * 409 {error:'request_reused'}.
+ */
+
+export const PREP_PROTOCOL = 1 as const
+
+export const PREP_LIMITS = Object.freeze({
+  /** Files per draft, counting every file not removed. */
+  maxFiles: 10,
+  steerChars: 4_000,
+  titleChars: 300,
+  /** Extracted text kept per file, in UTF-8 bytes (the phone Meeting Ask file cap). Also the answer kept on a run. */
+  fileTextBytes: 100_000,
+  activeDrafts: 300,
+  /** The whole Prep store: drafts, originals, extracted text and run prompts. */
+  storeBytes: 1024 * 1024 * 1024,
+  /** The durable query job prompt limit (QUERY_JOB_LIMITS.promptChars). */
+  promptChars: 48_000,
+  listLimit: 50,
+  /** Suggestions returned by GET /prep/suggest. */
+  suggestLimit: 5,
+  /** The answer kept on one run, and on all of a draft's runs together (the draft file must reload under 5 MB). */
+  runAnswerBytes: 20_000,
+  draftAnswerBytes: 1_000_000,
+  /** Snapshots kept per (draft, meeting). */
+  snapshotsPerSession: 20,
+  /** An unbound draft whose start is this far past may be archived to make room at the 300-draft limit. */
+  autoArchiveAfterMs: 7 * 24 * 60 * 60_000,
+  /** Meeting Ask's limits for one meeting's files (MeetingAskStore.putFiles), checked before a bind writes. */
+  meetingFiles: 100,
+  meetingTextBytes: 500_000,
+})
+
+/** GET /api/health -> capabilities.prep (health adds `serverInstanceId`). Absent on an older server: "Prep me" stays a plain Ask. */
+export const PREP_CAPABILITY = Object.freeze({ protocol: PREP_PROTOCOL, maxFiles: PREP_LIMITS.maxFiles, steerChars: PREP_LIMITS.steerChars, bind: true, suggest: true })
+
+export type PrepProvider = 'eventkit' | 'm365' | 'google'
+export type PrepSurface = 'web' | 'control' | 'phone' | 'g2'
+export type PrepFileKind = 'document' | 'image' | 'text' | 'other'
+export type PrepFileStatus = 'ready' | 'unsupported' | 'failed' | 'secret-held' | 'removed'
+
+export interface PrepOccurrence {
+  /**
+   * "occ:v2:" + hex sha256("occ:v2:" + provider + "|" + account + "|" + calendarId + "|" + (eventId or "") + "|" +
+   * (externalId or "") + "|" + startsAt as exact UTC ISO, e.g. 2026-11-06T22:00:00.000Z). No quantization: distinct
+   * occurrences never share a key. Lookup only; it never binds.
+   */
+  key: string
+  provider: PrepProvider
+  /** The calendar account (an email or provider account id), or null when the provider has none. */
+  account: string | null
+  calendarId: string
+  eventId: string | null
+  externalId: string | null
+  startsAt: string
+  endsAt: string | null
+}
+
+export interface PrepFile {
+  id: string
+  /** The /api/media id it was copied from: one draft never holds the same media twice. */
+  mediaId: string
+  name: string
+  mime: string
+  bytes: number
+  /**
+   * sha256 (lowercase hex) of the bytes the Prep store keeps for this file, which are the bytes /api/media stored.
+   * For documents and plain text (and a video /api/media has not compressed) those are exactly the bytes the client
+   * uploaded, so this equals uploadSha256 and the add was refused unless they matched. For images /api/media keeps a
+   * re-encoded JPEG (original-normalized.jpg), so this is the hash of that JPEG and differs from uploadSha256.
+   */
+  sha256: string
+  /**
+   * The sha256 the client sent in POST files: the hash of the bytes it sent to /api/media. Checked against the copy
+   * where /api/media keeps bytes verbatim (409 media_hash_mismatch otherwise). Where /api/media re-encodes (images, a
+   * compressed video) the upload's bytes no longer exist on the server, so the copy is checked against the media
+   * store's own hash of what it stored instead, and this value is kept as the client's statement.
+   */
+  uploadSha256: string
+  addedAt: string
+  kind: PrepFileKind
+  status: PrepFileStatus
+  notice?: string
+  textChars: number
+  source: 'upload' | 'control-local'
+  /** Control's opaque local source id, echoed back, never interpreted. */
+  sourceRef?: string
+}
+
+/** One files call, kept so a repeat of its operationId replays (v1.1 #14). */
+export interface PrepFileOperation {
+  operationId: string
+  fingerprint: string
+  fileIds: string[]
+  at: string
+}
+
+/**
+ * One run, frozen when it was asked (v1.1 #7). `state` is 'submitting' from the moment the prompt is saved until the
+ * job is admitted ('accepted'), or 'failed' when the admission refused it (a replay is then 409 run_failed). Once the
+ * job ends, its status and answer (up to 20 KB; all of a draft's answers up to 1 MB, oldest dropped first) are copied
+ * here when the draft or run is read, without moving the draft's revision. A new run is refused (409 run_in_progress)
+ * only until the previous one has a session; after that a second run may go into the same conversation while the
+ * first is still answering.
+ */
+export interface PrepRun {
+  clientRequestId: string
+  clientJobId: string
+  jobId: string | null
+  sessionId: string | null
+  draftRevision: number
+  createdAt: string
+  state: 'submitting' | 'accepted' | 'failed'
+  /** sha256 of the canonical request minus volatile fields (revision, serverInstanceId). */
+  fingerprint: string
+  promptSha256: string
+  steerSha256: string
+  files: Array<{ id: string; sha256: string }>
+  model?: string
+  effort?: string
+  continue?: boolean
+  error?: string
+  /** Copied from the job once it is terminal (optional per v1.1 #22; absent means read the job, or it is gone). */
+  status?: string
+  /** The answer as copied, or null when the job was gone before any answer was copied (outcome 'unavailable'). */
+  answer?: string | null
+  /**
+   * 'unavailable': the run was accepted but its job is no longer kept (retention), so the server recorded it as ended
+   * with no answer. Terminal: it never blocks a new run, and GET .../runs answers 200 {run, job: null}.
+   */
+  outcome?: 'unavailable'
+  answerTruncated?: boolean
+  settledAt?: string
+}
+
+/**
+ * What one bind adopted, frozen (v1.1 #21), exactly {draftRevision, steer, files}. `revision` is the Meeting Ask copy
+ * revision (prep_<draftId>_<fileId> in the meeting); `sha256` is PrepFile.sha256. A re-bind is a new snapshot.
+ */
+export interface PrepBindingSnapshot {
+  draftRevision: number
+  /** '' with held: true when the notes looked like a password or key (the meeting got them as secret-held, no text). */
+  steer: string
+  files: Array<{ id: string; name: string; revision: string; sha256: string }>
+  held?: true
+}
+
+/**
+ * One bind of a draft to a meeting, kept append-only (newest last, at most 20 per meeting) so a rebind never erases
+ * what the meeting used before. `state` is the snapshot's own: 'applying' until its rows reached Meeting Ask (and
+ * forever, if it was interrupted and then superseded), 'applied' once they did, 'removed' once the bind was taken back.
+ */
+export interface PrepSnapshotRecord {
+  sessionId: string
+  state: 'applying' | 'applied' | 'removed'
+  boundAt: string
+  surface: PrepSurface
+  title: string
+  startsAt: string | null
+  snapshot: PrepBindingSnapshot
+}
+
+/**
+ * One row of GET /prep/by-session/:sessionId -> {serverInstanceId, snapshots}: a binding's frozen snapshot plus the
+ * title and start frozen with it. Never the latest draft, so an edit after a bind cannot rewrite what the meeting used.
+ */
+export interface PrepSessionSnapshot extends PrepBindingSnapshot {
+  draftId: string
+  sessionId: string
+  title: string
+  startsAt: string | null
+  surface: PrepSurface
+  /** This snapshot's own state (PrepSnapshotRecord.state). An 'applying' snapshot never reached the meeting. */
+  state: 'applying' | 'applied' | 'removed'
+  boundAt: string
+  /** True for the snapshot the meeting's copies hold now; false for an earlier bind of the same draft. */
+  current: boolean
+  /** Set on every snapshot of a draft whose binding to this meeting was taken back. */
+  removedAt?: string
+}
+
+/**
+ * 413 {error:'file_context_limit', needBytes, haveBytes, needFiles, haveFiles} from a bind, with nothing written.
+ * needBytes: UTF-8 text bytes this bind would put in the meeting (the notes and each adopted file).
+ * haveBytes: room left, 500,000 minus the text bytes of the meeting's current files that are not this draft's own
+ * copies (a bind replaces its own copies). needFiles: the meeting's file count after the bind. haveFiles: 100.
+ */
+export interface PrepFileContextLimit { error: 'file_context_limit'; needBytes: number; haveBytes: number; needFiles: number; haveFiles: number }
+
+/** A bind is written as 'applying' before the meeting files change and 'applied' after (v1.1 #11). */
+export interface PrepBinding {
+  sessionId: string
+  serverInstanceId: string
+  /** The draft revision this bind froze and attached. */
+  revision: number
+  state: 'applying' | 'applied'
+  boundAt: string
+  surface: PrepSurface
+  /** The Meeting Ask file ids this bind adopted (prep_<draftId>_steer, prep_<draftId>_<fileId>). */
+  fileIds: string[]
+  snapshot: PrepBindingSnapshot
+  /** The draft's title and start when it was bound, frozen with the snapshot. */
+  title: string
+  startsAt: string | null
+  removedAt?: string
+}
+
+export interface PrepDraft {
+  id: string
+  clientDraftId: string
+  /** The server that holds this draft (getServerInstanceId()), or null before it has one. */
+  serverInstanceId: string | null
+  /** CAS revision: +1 on every write. */
+  revision: number
+  createdAt: string
+  updatedAt: string
+  title: string
+  /** Display only; never used to match a meeting. */
+  startsAt: string | null
+  occurrence: PrepOccurrence | null
+  identity: 'provider' | 'none'
+  steer: string
+  files: PrepFile[]
+  fileOperations: PrepFileOperation[]
+  runs: PrepRun[]
+  conversation: { sessionId: string | null }
+  bindings: PrepBinding[]
+  /** Every bind's frozen snapshot, append-only (GET /prep/by-session reads these). */
+  snapshots: PrepSnapshotRecord[]
+  state: 'active' | 'archived'
+}
+
+/** "prep_" + 26 lowercase base32 (RFC 4648 alphabet). */
+export const PREP_DRAFT_ID = /^prep_[a-z2-7]{26}$/
+/** "pf_" + 16 hex. */
+export const PREP_FILE_ID = /^pf_[0-9a-f]{16}$/
+/** A client-made identity (clientDraftId, clientRequestId, operationId): a lowercase UUID v4. */
+export const PREP_UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+export const PREP_PROVIDERS: readonly PrepProvider[] = ['eventkit', 'm365', 'google']
+export const PREP_SURFACES: readonly PrepSurface[] = ['web', 'control', 'phone', 'g2']
+
+/** The Meeting Ask file id the steer text takes in a bound meeting. */
+export function prepSteerFileId(draftId: string): string { return `prep_${draftId}_steer` }
+/** The Meeting Ask file id a Prep file takes in a bound meeting. */
+export function prepAdoptedFileId(draftId: string, fileId: string): string { return `prep_${draftId}_${fileId}` }
+/** A Meeting Ask file a Prep bind adopted (notes or a file). Saved-transcript cleanup does not take vocabulary from these. */
+export function isPrepCopyId(id: string): boolean { return /^prep_prep_[a-z2-7]{26}_/.test(id) }
+/** The Meeting Ask file name of the steer text. */
+export const PREP_STEER_FILE_NAME = 'Prep notes'
+
+/** The text prefix hashed into a Prep run's clientJobId. */
+export const PREP_RUN_JOB_PREFIX = 'prep-run:v1:'
+
+/**
+ * The durable query job identity of one Prep run (generation 1), v1.1 #5:
+ *
+ *   hex  = sha256(UTF-8 of "prep-run:v1:" + draftId + ":" + clientRequestId)
+ *   hex[12] = '4'; hex[16] = '89ab'[parseInt(hex[16], 16) & 3]   (UUID v4 version and variant)
+ *   id   = hex[0:8]-hex[8:12]-hex[12:16]-hex[16:20]-hex[20:32]
+ *
+ * A client that lost the 202 can find the job with GET /api/query-jobs/by-client/<id>?generation=1 (or
+ * GET /api/prep/drafts/:id/runs/:clientRequestId), and the server finds the same job on a retry instead of submitting
+ * a second one. Web Crypto (browsers and Node 20+), so the server, the web client and tests share this function.
+ */
+export async function prepClientJobId(draftId: string, clientRequestId: string): Promise<string> {
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${PREP_RUN_JOB_PREFIX}${draftId}:${clientRequestId}`))
+  return uuidV4FromHex([...new Uint8Array(digest)].map(b => b.toString(16).padStart(2, '0')).join(''))
+}
+
+/** The first 32 hex characters with the UUID v4 version and variant nibbles forced, dashed 8-4-4-4-12. */
+export function uuidV4FromHex(hex: string): string {
+  const h = hex.slice(0, 32).toLowerCase().split('')
+  h[12] = '4'
+  h[16] = '89ab'[parseInt(h[16], 16) & 3]
+  const s = h.join('')
+  return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`
+}