@ham2k/extension-sdk 0.5.7 → 0.7.0

package/AGENTS.md

@@ -103,6 +103,8 @@ evaluating one script. Reach the outside world through `host`:
 import { host } from "@ham2k/extension-sdk"
 
 await host.fetch(url)          // https only, and only domains your manifest lists
+host.webSocket(url)            // wss:// to hosts your manifest's webSockets lists
+host.setTimeout(fn, ms)        // timers — plain setTimeout reaches these too
 await host.kvGet('key')        // storage, namespaced to your extension
 await host.kvSet('key', value)
 await host.showForm(form)      // ask the user something
@@ -131,6 +133,10 @@ host.log('…')                  // the app's console
   reserved.
 - **`host.secret()` returns null** for anything not built into the app. Degrade;
   don't throw. A hook that throws takes its whole feature down.
+- **Timers are budgeted, not free.** An extension's callbacks may average 10%
+  of real time; past that, or after five throwing in a row, its timers are
+  suspended until the extensions restart. At most 16 at once. Reconnect with a
+  growing delay, never straight from `onclose`.
 - **Hook method names are routed by string.** The host finds your hook by its
   registered key and then calls the method by name, so `renderPanel` where
   `render` was meant is an extension that installs, activates, and does nothing.

package/dist/base64.js

@@ -0,0 +1,38 @@
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const VALUES = new Map([...ALPHABET].map((c, i) => [c, i]));
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    const n = a << 16 | b << 8 | c;
+    out += ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63];
+    out += i + 1 < bytes.length ? ALPHABET[n >> 6 & 63] : "=";
+    out += i + 2 < bytes.length ? ALPHABET[n & 63] : "=";
+  }
+  return out;
+}
+function base64ToBytes(text) {
+  if (text.length % 4 !== 0) throw new Error("invalid base64");
+  const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  const bytes = new Uint8Array(text.length / 4 * 3 - padding);
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    let n = 0;
+    for (let j = 0; j < 4; j++) {
+      const ch = text[i + j];
+      const value = ch === "=" && i + 4 === text.length && j >= 4 - padding ? 0 : VALUES.get(ch);
+      if (value === void 0) throw new Error("invalid base64");
+      n = n << 6 | value;
+    }
+    if (o < bytes.length) bytes[o++] = n >> 16 & 255;
+    if (o < bytes.length) bytes[o++] = n >> 8 & 255;
+    if (o < bytes.length) bytes[o++] = n & 255;
+  }
+  return bytes;
+}
+export {
+  base64ToBytes,
+  bytesToBase64
+};

package/dist/copyOnWrite.js

@@ -0,0 +1,71 @@
+function copyOnWrite(base) {
+  return isContainer(base) ? wrap(base) : base;
+}
+function isContainer(value) {
+  return typeof value === "object" && value !== null;
+}
+function wrap(target) {
+  const own = /* @__PURE__ */ new Map();
+  const deleted = /* @__PURE__ */ new Set();
+  return new Proxy(target, {
+    get(t, key) {
+      if (own.has(key)) return own.get(key);
+      if (deleted.has(key)) return void 0;
+      const value = Reflect.get(t, key);
+      if (isContainer(value) && Object.prototype.hasOwnProperty.call(t, key)) {
+        const view = wrap(value);
+        own.set(key, view);
+        return view;
+      }
+      return value;
+    },
+    set(_t, key, value) {
+      own.set(key, value);
+      deleted.delete(key);
+      return true;
+    },
+    has(t, key) {
+      if (deleted.has(key)) return false;
+      return own.has(key) || key in t;
+    },
+    deleteProperty(t, key) {
+      const descriptor = Reflect.getOwnPropertyDescriptor(t, key);
+      if (descriptor && !descriptor.configurable) return false;
+      own.delete(key);
+      if (descriptor) deleted.add(key);
+      return true;
+    },
+    ownKeys(t) {
+      const keys = Reflect.ownKeys(t).filter((key) => !deleted.has(key));
+      for (const key of own.keys()) {
+        if (!keys.includes(key)) keys.push(key);
+      }
+      return keys;
+    },
+    getOwnPropertyDescriptor(t, key) {
+      if (deleted.has(key)) return void 0;
+      const descriptor = Reflect.getOwnPropertyDescriptor(t, key);
+      if (!own.has(key)) return descriptor;
+      return descriptor ? { ...descriptor, value: own.get(key) } : { value: own.get(key), writable: true, enumerable: true, configurable: true };
+    },
+    // The other ways to write. Without these traps `Object.defineProperty`
+    // and `Object.freeze` fall through to the base — the held checkpoint —
+    // and one such call would enter a candidate into every later verdict, or
+    // lock the sheet for the rest of the session.
+    defineProperty(_t, key, descriptor) {
+      if ("get" in descriptor || "set" in descriptor) return false;
+      own.set(key, descriptor.value);
+      deleted.delete(key);
+      return true;
+    },
+    preventExtensions() {
+      return false;
+    },
+    setPrototypeOf() {
+      return false;
+    }
+  });
+}
+export {
+  copyOnWrite
+};

package/dist/hookCategories.js

@@ -0,0 +1,25 @@
+const HOOK_CATEGORIES = [
+  "account",
+  "activity",
+  "adifFields",
+  "adifImport",
+  "bench",
+  "callNotes",
+  "command",
+  "dataFile",
+  "export",
+  "form",
+  "lookup",
+  "lookupService",
+  "panel",
+  "recentContextLookup",
+  "runtime",
+  "scoring",
+  "settingsPanel",
+  "spots",
+  "syncTransport",
+  "template"
+];
+export {
+  HOOK_CATEGORIES
+};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.7
+// @ham2k/extension-sdk 0.7.0
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -116,6 +116,30 @@ export interface PanelSceneEvent {
 export interface PanelSceneEventResult {
 	values: Record<string, number>;
 }
+export declare const HOOK_CATEGORIES: readonly [
+	"account",
+	"activity",
+	"adifFields",
+	"adifImport",
+	"bench",
+	"callNotes",
+	"command",
+	"dataFile",
+	"export",
+	"form",
+	"lookup",
+	"lookupService",
+	"panel",
+	"recentContextLookup",
+	"runtime",
+	"scoring",
+	"settingsPanel",
+	"spots",
+	"syncTransport",
+	"template"
+];
+export type HookCategory = (typeof HOOK_CATEGORIES)[number];
+export type HookCategoryName = HookCategory | `ref:${string}`;
 export type CallInfo = {
 	call: string;
 	baseCall?: string;
@@ -394,6 +418,7 @@ export interface LoggingControlDescriptor {
 	key: string;
 	label: string;
 	shortLabel?: string;
+	skipFocus?: boolean;
 	icon?: string;
 	color?: string;
 	order?: number;
@@ -634,12 +659,15 @@ export interface ScoreQsosRequest {
 	ref?: Record<string, JSONValue>;
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
+	resumeKey?: string;
+	checkpointKey?: string;
 }
 export interface ScoreQsosResult {
 	qsoScores: Record<string, QsoScoreVerdict>;
 	daySections: DayScoreSummary[];
 	operationSummary: Record<string, ScoreTally>;
 	scoresheet?: JSONValue;
+	checkpointHeld?: true;
 	scoresheetDay?: number;
 }
 export interface ScoreQsoRequest {
@@ -651,11 +679,13 @@ export interface ScoreQsoRequest {
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
 	qsos?: Record<string, JSONValue>[];
+	resumeKey?: string;
 }
 export interface QsoScoreNotices {
 	notices: string[];
 	alerts: string[];
 	dupe?: boolean;
+	checkpointHeld?: true;
 }
 export interface ScoreCandidatesRequest {
 	operation: Record<string, JSONValue>;
@@ -668,8 +698,11 @@ export interface ScoreCandidatesRequest {
 	resumeFrom?: JSONValue;
 	resumeDay?: number;
 	qsos?: Record<string, JSONValue>[];
+	resumeKey?: string;
 }
-export type ScoreCandidatesResult = Record<string, QsoScoreNotices>;
+export type ScoreCandidatesResult = Record<string, QsoScoreNotices> & {
+	$checkpointHeld?: true;
+};
 export interface ScoringHook {
 	scoreQsos(args: ScoreQsosRequest, ctx: HookContext): Promise<ScoreQsosResult>;
 	scoreQso?(args: ScoreQsoRequest, ctx: HookContext): Promise<QsoScoreNotices>;
@@ -784,6 +817,7 @@ export interface CommandAction {
 	devBench?: {
 		qsoCount?: number;
 	};
+	devLogCat?: Record<string, never>;
 	toggleExperiment?: {
 		token: string;
 	};
@@ -929,8 +963,12 @@ export interface RegisterHookParams {
 	priority?: number;
 }
 export interface ActivationApi {
-	registerHook(category: string, params: RegisterHookParams): void;
+	registerHook(category: HookCategoryName, params: RegisterHookParams): void;
 	hostCall(method: string, params: Record<string, unknown>): Promise<unknown>;
+	timers?: {
+		set(callback: unknown, delay: unknown, repeat: boolean, args: unknown[]): number;
+		clear(id: unknown): void;
+	};
 }
 export interface ExtensionRelevance {
 	entities?: string[];
@@ -952,7 +990,9 @@ export interface ExtensionManifest {
 	category?: string;
 	enabledByDefault?: boolean;
 	hooks?: string[];
+	adifFieldsScope?: "always";
 	domains?: string[];
+	webSockets?: string[];
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
@@ -967,6 +1007,8 @@ export interface ExtensionManifest {
 }
 export interface ExtensionDefinition extends ExtensionManifest {
 	onActivation(api: ActivationApi): void;
+	onShow?(): void | Promise<void>;
+	onHide?(): void | Promise<void>;
 }
 export interface FetchOptions {
 	method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -997,6 +1039,29 @@ export interface FetchResponse {
 	status: number;
 	body: string;
 }
+export interface WebSocketOptions {
+	protocols?: string[];
+}
+export interface WebSocketCloseEvent {
+	code: number;
+	reason: string;
+	wasClean: boolean;
+}
+export interface ExtensionWebSocket {
+	readonly url: string;
+	readonly readyState: 0 | 1 | 2 | 3;
+	readonly protocol: string;
+	onopen: (() => void) | null;
+	onmessage: ((event: {
+		data: string | ArrayBuffer;
+	}) => void) | null;
+	onerror: ((event: {
+		message: string;
+	}) => void) | null;
+	onclose: ((event: WebSocketCloseEvent) => void) | null;
+	send(data: string | ArrayBuffer | ArrayBufferView): void;
+	close(code?: number, reason?: string): void;
+}
 export interface DeviceLocation {
 	latitude: number;
 	longitude: number;
@@ -1376,6 +1441,10 @@ export interface PanelHook {
 		event: PanelSceneEvent;
 	}, ctx: HookContext): Promise<PanelSceneEventResult>;
 }
+declare function setTimeout$1(callback: (...args: any[]) => unknown, delay?: number, ...args: unknown[]): number;
+declare function setInterval$1(callback: (...args: any[]) => unknown, delay?: number, ...args: unknown[]): number;
+declare function clearTimeout$1(id?: number): void;
+declare function clearInterval$1(id?: number): void;
 /**
  * The standard per-extension translator: takes the extension's i18next
  * resources once and returns a `tFor(ctx)` that hooks call with their
@@ -1461,6 +1530,8 @@ export declare function isUnexpectedSideband(mode: string | undefined | null, {
 	freqKHz?: number;
 	band?: string;
 }): boolean;
+export declare const RESUME_MISSING = "resume-missing";
+export declare const CHECKPOINT_HELD_KEY = "$checkpointHeld";
 export interface ContestScorerOptions {
 	scope?: ScoringScope;
 }
@@ -1658,25 +1729,35 @@ export interface TemplateContextArgs {
 	log?: LogValues;
 	appName?: string;
 	atMillis?: number;
+	keyer?: {
+		messages: string[];
+		current?: number;
+	};
 	nowMillis?: number;
 }
 export declare function templateContext(args: TemplateContextArgs): Record<string, unknown>;
 export declare function isTestOperation(stationCall: JSONValue | undefined): boolean;
 export declare function defineExtension(def: ExtensionDefinition): void;
 export declare const hooks: {
-	invokeAll(category: string, method: string, args: unknown, online?: boolean): Promise<{
+	invokeAll(category: HookCategoryName, method: string, args: unknown, online?: boolean): Promise<{
+		key: string;
+		ok: boolean;
+		value?: unknown;
+		error?: string;
+	}[]>;
+	invokeOne(category: HookCategoryName, key: string, method: string, args: unknown, online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
 		error?: string;
 	}[]>;
-	invokeOne(category: string, key: string, method: string, args: unknown, online?: boolean): Promise<{
+	invokeForRefs(category: HookCategoryName, method: string, args: unknown, refs: unknown[], online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
 		error?: string;
 	}[]>;
-	invokeAllSequential(category: string, method: string, initialArgs: unknown, fold: (args: unknown, hookResult: unknown, hookKey: string) => unknown, online?: boolean): Promise<{
+	invokeAllSequential(category: HookCategoryName, method: string, initialArgs: unknown, fold: (args: unknown, hookResult: unknown, hookKey: string) => unknown, online?: boolean): Promise<{
 		key: string;
 		ok: boolean;
 		value?: unknown;
@@ -1693,6 +1774,7 @@ export declare const host: {
 	}): Promise<PanelRadioTuneResult>;
 	tuneRadio(args: PanelRadioTune): Promise<PanelRadioTuneResult>;
 	fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
+	webSocket(url: string, options?: WebSocketOptions): ExtensionWebSocket;
 	kvGet(key: string): Promise<JSONValue | null>;
 	getLocation(): Promise<DeviceLocation | null>;
 	getVersionInfo(): Promise<VersionInfo>;
@@ -1717,6 +1799,10 @@ export declare const host: {
 		dismissNotice(key: string): Promise<void>;
 	};
 	log(message: string): void;
+	setTimeout: typeof setTimeout$1;
+	setInterval: typeof setInterval$1;
+	clearTimeout: typeof clearTimeout$1;
+	clearInterval: typeof clearInterval$1;
 	updateInterpretation(input: string, interpretation: Record<string, unknown>): void;
 };
 

package/dist/index.js

@@ -1,4 +1,7 @@
+import { base64ToBytes, bytesToBase64 } from "./base64.js";
+import { adoptExtensionTimers, clearInterval, clearTimeout, setInterval, setTimeout } from "./timers.js";
 export * from "./types.js";
+export * from "./hookCategories.js";
 export * from "./svgScene.js";
 export * from "./i18n.js";
 export * from "./dxcc.js";
@@ -32,12 +35,97 @@ function defineExtension(def) {
   currentExtensionKey = def.key;
   kernel().defineExtension({
     ...def,
+    // Called on the author's own object, as onActivation is below, so `this`
+    // is the same object in all three: state kept on it at activation is there
+    // to stop on hide.
+    onShow: def.onShow && (() => def.onShow()),
+    onHide: def.onHide && (() => def.onHide()),
     onActivation(api) {
       if (typeof api.hostCall === "function") privilegedHostCalls[def.key] = api.hostCall;
+      adoptExtensionTimers(def.key, currentExtensionKey, api.timers);
       return def.onActivation(api);
     }
   });
 }
+const MAX_FRAME_SIZE = 1024 * 1024;
+function utf8Length(text) {
+  let length = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    length += cp < 128 ? 1 : cp < 2048 ? 2 : cp < 65536 ? 3 : 4;
+  }
+  return length;
+}
+function openWebSocket(call, url, options) {
+  let readyState = 0;
+  let protocol = "";
+  const failed = (what) => (e) => kernel().log(`webSocket ${what} on ${url} failed: ${e instanceof Error ? e.message : String(e)}`);
+  const socket = {
+    url,
+    get readyState() {
+      return readyState;
+    },
+    get protocol() {
+      return protocol;
+    },
+    onopen: null,
+    onmessage: null,
+    onerror: null,
+    onclose: null,
+    send(data) {
+      if (readyState !== 1) throw new Error("WebSocket is not open");
+      let frame;
+      if (typeof data === "string") {
+        if (data.length > MAX_FRAME_SIZE) throw new Error("WebSocket message too big");
+        frame = { data };
+      } else {
+        const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        if (bytes.length > MAX_FRAME_SIZE) throw new Error("WebSocket message too big");
+        frame = { binary: bytesToBase64(bytes) };
+      }
+      call("webSocketSend", { socketId, ...frame }).catch(failed("send"));
+    },
+    close(code, reason) {
+      if (code !== void 0 && (!Number.isInteger(code) || code !== 1e3 && (code < 3e3 || code > 4999))) {
+        throw new Error("close code must be 1000 or 3000-4999");
+      }
+      if (reason !== void 0 && (typeof reason !== "string" || utf8Length(reason) > 123)) {
+        throw new Error("close reason must be a string of at most 123 UTF-8 bytes");
+      }
+      if (readyState >= 2) return;
+      const before = readyState;
+      readyState = 2;
+      call("webSocketClose", { socketId, ...code !== void 0 ? { code } : {}, ...reason !== void 0 ? { reason } : {} }).catch((e) => {
+        if (readyState === 2) readyState = before;
+        failed("close")(e);
+      });
+    }
+  };
+  if (typeof kernel().registerSocket !== "function") throw new Error("host.webSocket needs a newer version of HaLo");
+  const socketId = kernel().registerSocket((event) => {
+    switch (event.type) {
+      case "open":
+        if (readyState !== 0) return;
+        readyState = 1;
+        protocol = String(event.protocol ?? "");
+        return socket.onopen?.();
+      case "message": {
+        const data = typeof event.binary === "string" ? base64ToBytes(event.binary).buffer : String(event.data);
+        return socket.onmessage?.({ data });
+      }
+      case "error":
+        return socket.onerror?.({ message: String(event.message ?? "") });
+      case "close":
+        readyState = 3;
+        return socket.onclose?.({ code: Number(event.code), reason: String(event.reason ?? ""), wasClean: event.wasClean === true });
+    }
+  });
+  call("webSocketOpen", { socketId, url, ...options?.protocols ? { protocols: options.protocols } : {} }).catch((e) => {
+    kernel().socketEvent(socketId, JSON.stringify({ type: "error", message: e instanceof Error ? e.message : String(e) }));
+    kernel().socketEvent(socketId, JSON.stringify({ type: "close", code: 1006, reason: "", wasClean: false }));
+  });
+  return socket;
+}
 const hooks = {
   /// EVERY hook in the category — including the CALLER's own. A hook that
   /// delegates within its own category therefore re-enters itself; use
@@ -53,6 +141,15 @@ const hooks = {
   invokeOne(category, key, method, args, online) {
     return kernel().invokeLocal(category, method, args, online, key);
   },
+  /// Like `invokeAll`, but only the hooks of the extensions that answer for one
+  /// of [refs] — for each, those holding the strongest `ref:<type>` claim on it
+  /// (a `ref:<type>/<code>` prefix beats the bare type) — plus, for
+  /// `adifFields`, any whose manifest sets `adifFieldsScope: "always"`.
+  /// For a fan-out over programs that must leave out the ones a contact has
+  /// nothing to do with, as the full ADIF export does.
+  invokeForRefs(category, method, args, refs, online) {
+    return kernel().invokeLocal(category, method, args, online, null, refs);
+  },
   /// Like `invokeAll`, but calls hooks one at a time in priority order,
   /// threading each result into the next call's args via `fold` — needed
   /// when later hooks must see earlier hooks' contributions.
@@ -76,6 +173,11 @@ const host = {
   async fetch(url, options) {
     return await hostCallFn()("fetch", { url, ...options });
   },
+  /// A WebSocket to a host the manifest's `webSockets` lists — see
+  /// `ExtensionWebSocket`. Returns at once, connecting, as a browser's does.
+  webSocket(url, options) {
+    return openWebSocket(hostCallFn(), url, options);
+  },
   async kvGet(key) {
     return await hostCallFn()("kvGet", { ns: currentExtensionKey, key });
   },
@@ -233,6 +335,14 @@ const host = {
   log(message) {
     kernel().log(`[${currentExtensionKey}] ${message}`);
   },
+  /// Browser-shaped timers, on real time, bound to this extension and held to
+  /// its budget (docs/extensions/README.md, "Timers"). A bundle built for
+  /// extension API 3 reaches these from a plain `setTimeout` too, npm
+  /// dependencies included (sdk/src/timers.ts).
+  setTimeout,
+  setInterval,
+  clearTimeout,
+  clearInterval,
   /// Pushes a later CommandInterpretation for the same `input` a `command`
   /// hook's `interpret()` was called with — see CommandHook's doc. One-way,
   /// like `log`: call it, don't await anything back.

package/dist/scoring.js

@@ -1,9 +1,13 @@
+import { copyOnWrite } from "./copyOnWrite.js";
 const DAY_IN_MILLIS = 1e3 * 60 * 60 * 24;
+const HELD_CHECKPOINTS = 4;
+const RESUME_MISSING = "resume-missing";
+const CHECKPOINT_HELD_KEY = "$checkpointHeld";
 function copySheet(sheet) {
   return JSON.parse(JSON.stringify(sheet));
 }
-function openCheckpoint(resumeFrom, resumeDay) {
-  return { sheet: copySheet(resumeFrom), day: typeof resumeDay === "number" ? resumeDay : void 0 };
+function operationUuidOf(operation) {
+  return typeof operation.uuid === "string" ? operation.uuid : "";
 }
 function dayOf(qso) {
   const millis = Number(qso.startAtMillis ?? 0);
@@ -25,6 +29,26 @@ function candidateAsOfNow(qso) {
 function contestScorer(scorer, options = {}) {
   const scope = options.scope ?? "always";
   const scopedRefTypes = typeof scope === "object" && Array.isArray(scope.refTypes) ? scope.refTypes : void 0;
+  const held = /* @__PURE__ */ new Map();
+  function hold(operationUuid, key, sheet, day) {
+    held.delete(operationUuid);
+    held.set(operationUuid, { key, sheet, day });
+    while (held.size > HELD_CHECKPOINTS) held.delete(held.keys().next().value);
+  }
+  function resolveCheckpoint(args) {
+    const operationUuid = operationUuidOf(args.operation);
+    const key = typeof args.resumeKey === "string" ? args.resumeKey : void 0;
+    if (args.resumeFrom !== void 0) {
+      const day = typeof args.resumeDay === "number" ? args.resumeDay : void 0;
+      const sheet = args.resumeFrom;
+      if (key !== void 0) hold(operationUuid, key, sheet, day);
+      return { key: key ?? "", sheet, day };
+    }
+    if (key === void 0) return void 0;
+    const entry = held.get(operationUuid);
+    if (entry === void 0 || entry.key !== key) throw new Error(`${RESUME_MISSING}: ${key}`);
+    return entry;
+  }
   function refOfScopedType(operation) {
     if (!scopedRefTypes) return void 0;
     const refs = operation.refs ?? [];
@@ -66,11 +90,12 @@ function contestScorer(scorer, options = {}) {
     return { sheet, day: currentDay };
   }
   async function liveScoresheet(args, ctx, excludeUuid) {
-    if (args.resumeFrom !== void 0) {
-      const { sheet, day } = openCheckpoint(args.resumeFrom, args.resumeDay);
+    const resumed = resolveCheckpoint(args);
+    if (resumed !== void 0) {
+      const sheet = copyOnWrite(resumed.sheet);
       const tail = chronological(args.qsos ?? []).filter((q) => !excludeUuid || q.uuid !== excludeUuid);
-      if (tail.length === 0) return { sheet, day };
-      return fold(sheet, tail, args, ctx, void 0, void 0, args.segments, day);
+      if (tail.length === 0) return { sheet, day: resumed.day };
+      return fold(sheet, tail, args, ctx, void 0, void 0, args.segments, resumed.day);
     }
     const uuid = typeof args.operation.uuid === "string" ? args.operation.uuid : void 0;
     const log = uuid ? await ctx.getQsos?.(uuid) ?? [] : [];
@@ -81,8 +106,8 @@ function contestScorer(scorer, options = {}) {
     scope,
     async scoreQsos(args, ctx) {
       const qsos = chronological(args.qsos);
-      const resumed = args.resumeFrom !== void 0 ? openCheckpoint(args.resumeFrom, args.resumeDay) : void 0;
-      const start = resumed?.sheet ?? scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx);
+      const resumed = resolveCheckpoint(args);
+      const start = resumed !== void 0 ? copySheet(resumed.sheet) : scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx);
       const qsoScores = {};
       const daySections = [];
       const { sheet: end, day: endDay } = fold(
@@ -103,12 +128,15 @@ function contestScorer(scorer, options = {}) {
         args.segments,
         resumed?.day
       );
+      const checkpointHeld = typeof args.checkpointKey === "string";
+      if (checkpointHeld) hold(operationUuidOf(args.operation), args.checkpointKey, end, endDay);
       return {
         qsoScores,
         daySections,
         operationSummary: scorer.summarizeScore({ scoresheet: end, operation: args.operation, ref: args.ref, scope: "operation" }, ctx),
         scoresheet: end,
-        ...endDay !== void 0 && { scoresheetDay: endDay }
+        ...endDay !== void 0 && { scoresheetDay: endDay },
+        ...checkpointHeld && { checkpointHeld: true }
       };
     },
     /// Live path: score the candidate against the log so far and report only
@@ -117,26 +145,35 @@ function contestScorer(scorer, options = {}) {
     async scoreQso(args, ctx) {
       const { sheet } = await liveScoresheet(args, ctx, args.excludeUuid);
       const { score } = scorer.scoreQso({ scoresheet: sheet, qso: candidateAsOfNow(args.qso), operation: args.operation, ref: args.ref, isNewDay: false }, ctx);
-      return { notices: score.notices ?? [], alerts: score.alerts ?? [], ...score.dupe !== void 0 && { dupe: score.dupe } };
+      const checkpointHeld = typeof args.resumeKey === "string";
+      return {
+        notices: score.notices ?? [],
+        alerts: score.alerts ?? [],
+        ...score.dupe !== void 0 && { dupe: score.dupe },
+        ...checkpointHeld && { checkpointHeld: true }
+      };
     },
     /// The same live judgement as `scoreQso`, for many candidates at once —
     /// the Spots Panel annotating every spot on screen. The log is folded ONCE
-    /// and each candidate scored against its own copy of the result, so a
+    /// and each candidate scored against its own view of the result, so a
     /// candidate can neither see nor become a duplicate of another (both spots
     /// for the same unworked call read as unworked, which is what an operator
     /// scanning a band expects).
     ///
-    /// The copy is per candidate rather than per call because
+    /// The view is per candidate rather than per call because
     /// `ContestScorer.scoreQso` may mutate the scoresheet it is handed — the
     /// contract that makes the batch fold linear. Without it the first
-    /// candidate's call would count as worked for every candidate after it.
+    /// candidate's call would count as worked for every candidate after it. A
+    /// view, not a copy: copying a long log's worked-call map forty times over
+    /// was the cost of the whole pass.
     async scoreCandidates(args, ctx) {
       const { sheet: base } = await liveScoresheet(args, ctx);
       const result = {};
+      if (typeof args.resumeKey === "string") result[CHECKPOINT_HELD_KEY] = true;
       for (const candidate of args.candidates) {
         const { score } = scorer.scoreQso(
           {
-            scoresheet: copySheet(base),
+            scoresheet: copyOnWrite(base),
             qso: candidateAsOfNow(candidate.qso),
             operation: args.operation,
             ref: args.ref,
@@ -158,6 +195,8 @@ function tally(key, forScope, total, extra = {}) {
   return { key, for: forScope, total, ...extra };
 }
 export {
+  CHECKPOINT_HELD_KEY,
+  RESUME_MISSING,
   contestScorer,
   tally
 };