@ham2k/extension-sdk 0.5.7 → 0.6.0

package/AGENTS.md

@@ -103,6 +103,7 @@ 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
 await host.kvGet('key')        // storage, namespaced to your extension
 await host.kvSet('key', value)
 await host.showForm(form)      // ask the user something

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/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.7
+// @ham2k/extension-sdk 0.6.0
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -394,6 +394,7 @@ export interface LoggingControlDescriptor {
 	key: string;
 	label: string;
 	shortLabel?: string;
+	skipFocus?: boolean;
 	icon?: string;
 	color?: string;
 	order?: number;
@@ -634,12 +635,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 +655,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 +674,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>;
@@ -953,6 +962,7 @@ export interface ExtensionManifest {
 	enabledByDefault?: boolean;
 	hooks?: string[];
 	domains?: string[];
+	webSockets?: string[];
 	allowUserAgentOverride?: boolean;
 	requiresLocation?: boolean;
 	requiresRadioRead?: boolean;
@@ -997,6 +1007,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;
@@ -1461,6 +1494,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;
 }
@@ -1693,6 +1728,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>;

package/dist/index.js

@@ -1,3 +1,4 @@
+import { base64ToBytes, bytesToBase64 } from "./base64.js";
 export * from "./types.js";
 export * from "./svgScene.js";
 export * from "./i18n.js";
@@ -38,6 +39,85 @@ function defineExtension(def) {
     }
   });
 }
+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
@@ -76,6 +156,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 });
   },

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
 };

package/docs/distribution.md

@@ -37,7 +37,7 @@ The same manifest a built-in extension carries, plus `api`:
   "version": "1.2.3",
   "description": "Notes about the stations I work",
   "category": "dashboard",
-  "api": 1,
+  "api": 2,
   "domains": ["notes.example.org"],
   "icon": "note-text"
 }
@@ -45,7 +45,10 @@ The same manifest a built-in extension carries, plus `api`:
 
 `api` is the extension API the bundle was built against. The host refuses one
 it does not speak, so an older app meeting a newer bundle says so instead of
-failing somewhere deep in a hook.
+failing somewhere deep in a hook — and the catalog does not list it for that
+app at all. Declare the lowest version that has what the bundle uses, so it
+reaches every app that can run it: 2 adds `host.webSocket`, and the packer
+refuses a manifest declaring `webSockets` under anything less.
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -254,7 +257,7 @@ It reports every problem at once rather than one per run:
 h2kext-pack: ./build is not ready to package:
 manifest.json: missing required field 'name'
 manifest.json: key 'my-clock' must start with your callsign — 'my' is not one (e.g. ki2d-my-clock)
-manifest.json: missing 'api' — declare the extension API this was built against (currently 1)
+manifest.json: missing 'api' — declare the extension API this was built against (currently 2)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own
@@ -318,8 +321,8 @@ needs one degrades the same way it does in a build without that value
 configured.
 
 The sandbox is otherwise the same one the built-in extensions run in — no
-filesystem, no network beyond the `domains` the manifest declares and the user
-approved, no timers.
+filesystem, no network beyond the `domains` and `webSockets` the manifest
+declares and the user approved, no timers.
 
 ## Installing one
 

package/docs/hooks.md

@@ -499,11 +499,13 @@ interface ActivityHook {
   suggest?(args: SuggestArgs, ctx): Promise<ActivitySuggestion[]>
   processQsoBeforeSave?(args: { qso, operation }, ctx): Promise<Patch | null>
 }
-// LoggingControlDescriptor: {key, label, shortLabel?, icon?, color?, order?,
-//   optionType?, allowsMultiple?, editable?, input}
+// LoggingControlDescriptor: {key, label, shortLabel?, skipFocus?, icon?, color?,
+//   order?, optionType?, allowsMultiple?, editable?, input}
 // `shortLabel` is the same name in fewer characters, for a field the logging
 // row has squeezed below its label's width. The core measures and picks; the
 // extension only says what the short form is.
+// `skipFocus: true` takes a main logging field out of the Space and Tab cycle;
+// the arrow keys still reach it. Every shipped contest sets it on Our Serial.
 // SuggestArgs: {operation, location?: {lat, lon}, callsign?, searchTerm?, scoped?}
 // ActivitySuggestion: Ref & {distance?, relevance?, allowsMultiple?}
 
@@ -1161,8 +1163,10 @@ standing beside your credit, on the one row that can show only one.
 A scorer's internal *rules* stay private to its scoresheet: contests don't
 share a rule vocabulary, so only notices, alerts, points and summary tallies
 cross the boundary. `scoreQso` **may mutate** the scoresheet it's given and
-return it; copying accumulated state per QSO is quadratic, and the harness
-copies any checkpoint at its boundary.
+return it; copying accumulated state per QSO is quadratic. The batch pass
+copies the checkpoint it resumes from, once; the live paths hand the scorer a
+copy-on-write view of it instead (`copyOnWrite` in the SDK), so a candidate's
+writes land in the view and the held sheet is never touched.
 
 ```ts
 // The wire shape the harness produces, for reference:
@@ -1171,17 +1175,19 @@ interface ScoringHook {
   scoreQso?(args: ScoreQsoRequest, ctx): Promise<QsoScoreNotices>
   scoreCandidates?(args: ScoreCandidatesRequest, ctx): Promise<ScoreCandidatesResult>
 }
-// ScoreQsosRequest: {operation, qsos, ref?, segments?, resumeFrom?, resumeDay?}
+// ScoreQsosRequest: {operation, qsos, ref?, segments?, resumeFrom?, resumeDay?, resumeKey?, checkpointKey?}
 // ScoreQsosResult:  {
 //   qsoScores: Record<uuid, QsoScoreVerdict>,   // one per QSO claimed; see above
 //   daySections: {day, count, scores: Record<tallyKey, ScoreTally>}[],
 //   operationSummary: Record<tallyKey, ScoreTally>,
 //   scoresheet,                                  // checkpoint to resume from
 //   scoresheetDay?,                              // the day it ends on, handed back as resumeDay
+//   checkpointHeld?,                             // true: the harness kept the end sheet under checkpointKey
 // }
-// ScoreQsoRequest:        {operation, qso, excludeUuid?, ref?, segments?, resumeFrom?, resumeDay?, qsos?}
-// ScoreCandidatesRequest: {operation, candidates: {key, qso}[], ref?, segments?, resumeFrom?, resumeDay?, qsos?}
-// ScoreCandidatesResult:  Record<candidateKey, QsoScoreNotices>
+// ScoreQsoRequest:        {operation, qso, excludeUuid?, ref?, segments?, resumeFrom?, resumeDay?, resumeKey?, qsos?}
+// QsoScoreNotices:        {notices, alerts, dupe?, checkpointHeld?}
+// ScoreCandidatesRequest: {operation, candidates: {key, qso}[], ref?, segments?, resumeFrom?, resumeDay?, resumeKey?, qsos?}
+// ScoreCandidatesResult:  Record<candidateKey, QsoScoreNotices> + {"$checkpointHeld": true} when a checkpoint was named
 ```
 
 All three arrive already implemented by `contestScorer()`; a scorer writes the
@@ -1192,23 +1198,48 @@ both live paths for free.
 A candidate that carries no `startAtMillis` (the draft's time is still
 automatic) reaches the scorer stamped with the current time on both live
 paths, so a day-bucketed rule judges it as of now rather than at the epoch; a
-candidate that states a time keeps it. On both live paths a `resumeFrom`
-checkpoint, with the `qsos` logged since it, stands in for the whole-log read:
-the harness copies the checkpoint, replays that tail onto it (continuing the
-day `resumeDay` names, so no scorer's per-day tally restarts mid-day) and
-scores the candidate against the result. The host sends a checkpoint only when
-it can prove the log is what the checkpoint folded plus appended contacts;
-otherwise the harness reads the log through `ctx.getQsos` and folds it cold.
-The batched `scoreQsos` resumes the same way: after the first pass of a
-session, an append arrives as `resumeFrom` plus the appended contacts, and only
-their verdicts come back.
+candidate that states a time keeps it. On both live paths a checkpoint, with
+the `qsos` logged since it, stands in for the whole-log read: the harness
+views the checkpoint copy-on-write, replays that tail onto the view
+(continuing the day `resumeDay` names, so no scorer's per-day tally restarts
+mid-day) and scores the candidate against the result. The host sends a
+checkpoint only when it can prove the log is what the checkpoint folded plus
+appended contacts; otherwise the harness reads the log through `ctx.getQsos`
+and folds it cold. The batched `scoreQsos` resumes the same way: after the
+first pass of a session, an append arrives as a checkpoint plus the appended
+contacts, and only their verdicts come back.
+
+**A checkpoint is held in the runtime and named, not sent, once it is
+there.** A sheet the size of a long log's worked-call map crossing the bridge
+on every keystroke would be most of the keystroke's cost. So the host names
+each checkpoint (`checkpointKey`, derived from the checkpoint's stamp) when
+the batch pass produces it, and the harness keeps the end sheet under that
+name — one per operation, the last few operations. A live call, or the next
+append, then carries `resumeKey` alone; a `resumeFrom` that arrives beside a
+`resumeKey` is filed under it too. A name the harness does not hold — a
+runtime restarted since, or one operation more than it keeps — is an error
+(`resume-missing`), never a silent cold fold, and the host answers it by
+sending the sheet once more. The host names a checkpoint only to a harness
+that has said `checkpointHeld: true` for it; a scorer built on an SDK without
+the cache never says so and keeps receiving the sheet. A `scoreCandidates`
+answer says it under the reserved key `$checkpointHeld`, since its other
+entries are the caller's candidate keys — a candidate key never starts with
+`$`.
+
+The view a scorer gets on the live paths takes every kind of write —
+assignment, `push`, `delete`, `Object.defineProperty` — and refuses the ones
+that would reach the base sheet by other means: `Object.freeze` (or `seal`,
+`preventExtensions`) on it throws. A sheet is plain JSON; one that is frozen
+or carries accessors is outside the contract and throws at the first touch.
+
 `scoreCandidates` answers the same question for many at once, which is what the
 Spots Panel asks to mark the spots already worked: the log is folded once per
-scorer and every candidate scored against a COPY of the result, so no candidate
-can become another's duplicate. Candidates carry no uuid — a spot is not a
-record — so results come back under caller-chosen keys.
+scorer and every candidate scored against its own copy-on-write VIEW of the
+result, so no candidate can become another's duplicate and no candidate pays
+for a copy of the log. Candidates carry no uuid — a spot is not a record — so
+results come back under caller-chosen keys.
 
-`Qsos.watchForOperation` already filters deleted rows and orders by
+`QsosRepository.forOperation` already filters deleted rows and orders by
 `startAtMillis`, so unlike web-lofi's `analyzeAndSectionQSOs` there's no
 `deleted`/`event` row bookkeeping on this side of the bridge.
 `ScoringService` (`app/lib/services/scoring_service.dart`) writes

package/docs/templates.md

@@ -224,7 +224,7 @@ will jump rather than count. Show HH:MM.
 | Panel documents | `custom-text`'s content and tab name | by the operator, in the panel's config form |
 | Export filenames and titles | Registered export types and `sdk/src/exportSettings.ts` | Settings → Exports, globally and per type |
 | ADIF NOTES / COMMENT / QSLMSG | Export type settings, consumed by `core/adif` | Settings → Exports; empty templates suppress a field |
-| CW messages | Radio settings `cwMessage1..8`, keyed on F1-F8 through the radio (docs/design/cat.md § CW keying) — rendered by the `template` hook (hooks.md) | by the operator, in the Station dialog's Messages… dialog |
+| CW messages | Radio settings `cwMessage1..8`, keyed on F1-F8 through the radio (docs/design/cat.md § CW keying) — rendered by the `template` hook (hooks.md) | by the operator, in the CW Keyer dialog (Settings → Radio, or the Station dialog's keyer row) |
 
 NOTES and COMMENT default to QSO notes and are withheld when private data
 is off. QSLMSG defaults to empty for program exports, and for the whole-log

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",