@ham2k/extension-sdk 0.5.7 → 0.7.0

package/dist/templateContext.js

@@ -1,3 +1,4 @@
+import { TemplateError, renderTemplate } from "./templates.js";
 function utcDate(millis) {
   return new Date(millis).toISOString().slice(0, 10);
 }
@@ -59,10 +60,19 @@ function opValues(operation, extra = {}) {
 function qsoValues(qso) {
   const their = qso.their ?? {};
   const our = qso.our ?? {};
+  const callField = qso.callField ?? {};
+  const guess = their.guess ?? {};
   const startMillis = Number(qso.startAtMillis ?? 0);
   const serialSent = refField(qso.refs, "ourSerial");
   return {
-    call: their.call ?? "",
+    // `||`, not `??`: a blank reading still means "no call", and the field
+    // as typed is a better answer than keying nothing.
+    call: callField.call || their.call || "",
+    // The panel's split of `call` — a logged contact's call is a full one.
+    fullCall: callField.fullCall ?? their.call ?? "",
+    partial: callField.partial ?? "",
+    nextCall: callField.nextCall ?? "",
+    nextPartial: callField.nextPartial ?? "",
     their,
     our,
     band: qso.band ?? "",
@@ -80,12 +90,26 @@ function qsoValues(qso) {
     // that is where these get typed.
     rst: our.sent ?? "",
     serial: serialSent,
+    // What was typed, else what the lookup found — the two places a CW
+    // message's "GM BOB" or "NY" would otherwise have to be chained by hand.
+    // `name` is the first word only: a lookup's "Robert J Smith" keyed in
+    // full is not how anyone greets a station.
+    state: firstText(their.state, guess.state),
+    name: firstText(their.name, guess.name).split(/\s+/)[0],
     notes: qso.notes ?? "",
     refs: qso.refs ?? [],
     ...startMillis > 0 ? dateValues(startMillis) : { date: "", dateCompact: "", time: "", at: "" },
     startAtMillis: startMillis
   };
 }
+function firstText(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const text = value.trim();
+    if (text !== "") return text;
+  }
+  return "";
+}
 function refField(refs, field) {
   if (!Array.isArray(refs)) return "";
   for (const ref of refs) {
@@ -115,7 +139,7 @@ function logValues(values) {
 }
 function templateContext(args) {
   const nowMillis = args.nowMillis ?? Date.now();
-  return {
+  const context = {
     app: { name: args.appName ?? "" },
     now: utcIso(nowMillis),
     ...args.operation ? { op: opValues(args.operation, { qsoCount: args.qsoCount, atMillis: args.atMillis }) } : {},
@@ -123,6 +147,23 @@ function templateContext(args) {
     ...args.log ? { log: logValues(args.log) } : {},
     ...args.config ? { config: args.config } : {}
   };
+  if (args.keyer) context.keyer = keyerValues(context, args.keyer.messages ?? [], args.keyer.current ? [args.keyer.current] : []);
+  return context;
+}
+function keyerValues(base, messages, chain) {
+  const keyer = {};
+  messages.forEach((template, i) => {
+    const n = i + 1;
+    Object.defineProperty(keyer, `msg${n}`, {
+      enumerable: true,
+      get() {
+        const path = [...chain, n];
+        if (chain.includes(n)) throw new TemplateError(`a message includes itself: ${path.map((k) => `F${k}`).join(" \u2192 ")}`);
+        return renderTemplate(template ?? "", { ...base, keyer: keyerValues(base, messages, path) });
+      }
+    });
+  });
+  return keyer;
 }
 export {
   dateValues,

package/dist/timerQueue.js

@@ -0,0 +1,187 @@
+const MAX_TIMERS_PER_EXTENSION = 16;
+const FIRE_COST_MILLIS = 1;
+const TIMER_DUTY_CYCLE = 0.1;
+const TIMER_BURST_MILLIS = 5e3;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const RUN_SLICE_MILLIS = 1e3;
+const MAX_DELAY_MILLIS = 2 ** 31 - 1;
+function createTimerQueue(host) {
+  const timers = /* @__PURE__ */ new Map();
+  const accounts = /* @__PURE__ */ new Set();
+  let nextId = 1;
+  let armed = null;
+  let inCallback = null;
+  function rearm() {
+    let earliest = null;
+    for (const t of timers.values()) {
+      if (earliest === null || t.deadline < earliest) earliest = t.deadline;
+    }
+    if (earliest === armed) return;
+    armed = earliest;
+    host.wake(earliest === null ? null : Math.max(0, Math.ceil(earliest - host.realNow())));
+  }
+  function suspend(owner, reason) {
+    if (owner.suspended || owner.revoked) return;
+    owner.suspended = reason;
+    for (const t of [...timers.values()]) {
+      if (t.owner === owner) timers.delete(t.id);
+    }
+    const why = {
+      budget: `its callbacks used more than ${TIMER_DUTY_CYCLE * 100}% of the time`,
+      failures: `${MAX_CONSECUTIVE_FAILURES} callbacks in a row failed`,
+      interrupted: "a callback ran past the engine's time limit"
+    }[reason];
+    host.log(`ERROR ${owner.key} timers suspended: ${why}`);
+    host.suspended(owner.key, reason);
+    rearm();
+  }
+  function cancelAll(owner) {
+    for (const t of [...timers.values()]) {
+      if (t.owner === owner) timers.delete(t.id);
+    }
+  }
+  function refuse(owner, why) {
+    if (!owner.refusalsLogged.has(why)) {
+      owner.refusalsLogged.add(why);
+      host.log(`ERROR ${owner.key} set a timer ${why}; it will not fire`);
+    }
+    return nextId++;
+  }
+  function charge(owner, cost) {
+    const now = host.realNow();
+    owner.debt = Math.max(0, owner.debt - (now - owner.chargedAt) * TIMER_DUTY_CYCLE) + cost;
+    owner.chargedAt = now;
+    if (owner.debt > TIMER_BURST_MILLIS) suspend(owner, "budget");
+  }
+  function failed(owner, e) {
+    host.log(`ERROR ${owner.key} timer callback: ${host.describeError(e)}`);
+    owner.failures++;
+    if (owner.failures >= MAX_CONSECUTIVE_FAILURES) suspend(owner, "failures");
+  }
+  function succeeded(owner) {
+    owner.failures = 0;
+  }
+  function fire(t, wakeCost) {
+    const startedAt = host.realNow();
+    let result;
+    let threw = false;
+    inCallback = t;
+    try {
+      result = t.callback(...t.args);
+    } catch (e) {
+      threw = true;
+      failed(t.owner, e);
+    }
+    inCallback = null;
+    charge(t.owner, host.realNow() - startedAt + wakeCost);
+    if (threw) return;
+    succeeded(t.owner);
+    if (result instanceof Promise) {
+      result.catch((e) => host.log(`ERROR ${t.owner.key} timer callback: ${host.describeError(e)}`));
+    }
+  }
+  return {
+    owner(key) {
+      const owner = { key, debt: 0, chargedAt: host.realNow(), failures: 0, suspended: null, revoked: false, refusalsLogged: /* @__PURE__ */ new Set() };
+      accounts.add(owner);
+      return owner;
+    },
+    set(handle, callback, delay, repeat, args) {
+      const owner = handle;
+      if (typeof callback !== "function") throw new TypeError("timer callback must be a function");
+      if (owner.revoked) return refuse(owner, "after it was unloaded");
+      if (owner.suspended) return refuse(owner, "while its timers are suspended");
+      let live = 0;
+      for (const t of timers.values()) if (t.owner === owner) live++;
+      if (live >= MAX_TIMERS_PER_EXTENSION) return refuse(owner, `beyond its ${MAX_TIMERS_PER_EXTENSION} live timers`);
+      const n = Number(delay);
+      const ms = n > 0 ? Math.min(Math.trunc(n), MAX_DELAY_MILLIS) : 0;
+      const id = nextId++;
+      timers.set(id, {
+        id,
+        owner,
+        callback,
+        args,
+        deadline: host.realNow() + ms,
+        interval: repeat ? ms : null
+      });
+      rearm();
+      return id;
+    },
+    /// Ids are guessable, so one owner's clear never reaches another's timer.
+    clear(handle, id) {
+      const t = timers.get(id);
+      if (!t || t.owner !== handle) return;
+      timers.delete(t.id);
+      rearm();
+    },
+    /// Fires what was due when it started. A timer set by one of these
+    /// callbacks waits for the next wake even at zero delay: running it here
+    /// would let a zero-delay chain spin inside a single evaluation.
+    run() {
+      armed = null;
+      if (inCallback) {
+        const cutShort = inCallback;
+        inCallback = null;
+        suspend(cutShort.owner, "interrupted");
+      }
+      const now = host.realNow();
+      const due = [...timers.values()].filter((t) => t.deadline <= now).sort((a, b) => a.deadline - b.deadline || a.id - b.id);
+      const woken = /* @__PURE__ */ new Set();
+      for (const t of due) {
+        if (host.realNow() - now >= RUN_SLICE_MILLIS) break;
+        if (timers.get(t.id) !== t) continue;
+        if (t.interval === null) timers.delete(t.id);
+        const wakeCost = woken.has(t.owner) ? 0 : FIRE_COST_MILLIS;
+        woken.add(t.owner);
+        fire(t, wakeCost);
+        if (t.interval !== null && timers.get(t.id) === t) t.deadline = host.realNow() + t.interval;
+      }
+      rearm();
+    },
+    /// Cancels what one activation — one that failed — has set, and nothing
+    /// of a newer activation's: a dev reload can start the new one before the
+    /// old one's failure arrives. The handle stays good, because the hooks
+    /// that activation registered before failing are still called.
+    cancel(handle) {
+      cancelAll(handle);
+      rearm();
+    },
+    /// Revokes every activation of [keys]: their timers go, their handles
+    /// ignore new ones, and a reloaded extension starts clean on a new handle.
+    drop(keys) {
+      for (const owner of [...accounts]) {
+        if (!keys.includes(owner.key)) continue;
+        owner.revoked = true;
+        accounts.delete(owner);
+        cancelAll(owner);
+      }
+      rearm();
+    }
+  };
+}
+function removeAmbientTimers(global = globalThis) {
+  for (const name of ["setTimeout", "setInterval", "clearTimeout", "clearInterval"]) {
+    try {
+      delete global[name];
+    } catch (e) {
+    }
+    if (typeof global[name] === "function") {
+      try {
+        global[name] = void 0;
+      } catch (e) {
+      }
+    }
+  }
+  return ["setTimeout", "setInterval", "clearTimeout", "clearInterval"].every((name) => typeof global[name] !== "function");
+}
+export {
+  FIRE_COST_MILLIS,
+  MAX_CONSECUTIVE_FAILURES,
+  MAX_TIMERS_PER_EXTENSION,
+  RUN_SLICE_MILLIS,
+  TIMER_BURST_MILLIS,
+  TIMER_DUTY_CYCLE,
+  createTimerQueue,
+  removeAmbientTimers
+};

package/dist/timers.js

@@ -0,0 +1,42 @@
+const bound = {};
+let preferredKey = null;
+let activated = false;
+function adoptExtensionTimers(key, currentKey, timers) {
+  activated = true;
+  preferredKey = currentKey;
+  if (timers) bound[key] = timers;
+}
+function boundTimers() {
+  return (preferredKey !== null ? bound[preferredKey] : void 0) ?? Object.values(bound)[0];
+}
+const refusalsLogged = /* @__PURE__ */ new Set();
+function set(callback, delay, repeat, args) {
+  const timers = boundTimers();
+  if (timers) return timers.set(callback, delay, repeat, args);
+  const why = activated ? "this version of HaLo has no timers" : "set before the extension activated";
+  if (!refusalsLogged.has(why)) {
+    refusalsLogged.add(why);
+    const who = preferredKey !== null ? `${preferredKey}: ` : "";
+    globalThis.__polo?.log(`ERROR ${who}a timer was ignored: ${why}`);
+  }
+  return 0;
+}
+function setTimeout(callback, delay, ...args) {
+  return set(callback, delay, false, args);
+}
+function setInterval(callback, delay, ...args) {
+  return set(callback, delay, true, args);
+}
+function clearTimeout(id) {
+  boundTimers()?.clear(id);
+}
+function clearInterval(id) {
+  clearTimeout(id);
+}
+export {
+  adoptExtensionTimers,
+  clearInterval,
+  clearTimeout,
+  setInterval,
+  setTimeout
+};

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,12 @@ 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; 3 adds timers
+and `onShow`/`onHide`, and from 3 the build rewrites a bare `setTimeout` into
+the SDK's (README's "Timers").
 
 Three fields are **refused** in a distributed bundle, and it is worth
 understanding why:
@@ -254,7 +259,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 3)
 ```
 
 `--force-name` waives the naming convention below. It exists for Ham2K's own
@@ -318,8 +323,9 @@ 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, and timers only within their budget
+(README's "Timers").
 
 ## Installing one
 
@@ -342,6 +348,14 @@ that key is compared — a bundle can change completely and still ask for the
 same things. That may be worth revisiting once a bundle can be shown to come
 from whoever it claims; it is not worth it while a key is all there is.
 
+**Update all is the one exception.** It takes every pending catalog update on
+a single confirmation that names each extension and the version it moves to,
+and skips the per-extension screen for each of them: asking once per entry for
+the one thing the operator asked for once is how a screen gets pressed through
+unread. It is a confirmation of a job the operator started, never a way to
+start one — `install_consent_scope_test` holds it to the one function that
+shows that confirmation first.
+
 Removing an extension removes what it stored with it.
 
 ### Installing from a link
@@ -477,7 +491,14 @@ takes the plain one above.
 At most once every six hours — on launch and on resume — the app asks the
 catalog whether anything installed has a newer release, and says so in the
 status bar and on the row; the notice comes down with the last update taken.
-It never installs unasked. A release the catalog has revoked is put on record
+It never installs unasked: the notice's **Update all** is the panel's own,
+behind the same confirmation, and **More info** opens the panel.
+
+An install or update narrates itself as one status-bar progress item, from the
+first downloaded byte to "Installed", and the Extensions panel mirrors that
+item on the row being installed. Installs share one queue
+(`ExtensionInstaller`): downloads run side by side, while the writes go one at
+a time, since each restarts the runtime. A release the catalog has revoked is put on record
 (`extensionRevoked`: version and note) and stops loading on the spot,
 whatever the operator's own switch says — the row shows "Revoked" with the
 note and no switch, and the record dies with an install of another version

package/docs/hooks.md

@@ -2,11 +2,30 @@
 
 Hooks are registered under a **category** with an optional **key** (defaults
 to the extension key) and **priority** (higher runs first; default 0). The
-host invokes them two ways:
+host invokes them three ways:
 
 - `invokeHook(category, key?, method, args)` — best (highest-priority) hook.
 - `invokeHookAll(category, method, args)` — every hook in the category, one
   bridge round-trip, per-source error isolation.
+- `invokeHookBatch(calls)` — several `invokeHook` calls, one bridge
+  round-trip, per-call error isolation. Each call reaches the same hook it
+  would reach on its own, so a hook cannot tell a batched call from a single
+  one.
+
+The categories are a closed list. `registerHook` takes a `HookCategory`
+([`extensions/sdk/src/hookCategories.ts`](https://github.com/ham2k/halo/blob/main/extensions/sdk/src/hookCategories.ts))
+or `ref:<type>`, so a misspelled category fails the typecheck rather than
+registering a hook nothing calls, and the build rejects a manifest `hooks`
+entry that is neither. A new category goes into that list — and, when the host
+calls it, into the host's catalog as well
+(`packages/halo_core/lib/src/hook_names.dart`).
+
+In both shapes that answer many hooks at once, one hook failing costs its own
+entry and nothing else — whether it throws, has no handler, or answers
+something JSON cannot carry (a circular object, a `BigInt`). One that runs out
+of time does too, when the caller asks for partial results; otherwise, and for
+a batch of several calls that runs out of time before any answer has reached
+the host, the whole call fails.
 
 All argument and result types below are defined in
 [`extensions/sdk/src/types.ts`](https://github.com/ham2k/halo/blob/main/extensions/sdk/src/types.ts). Every
@@ -422,6 +441,18 @@ interface RefHandlerHook {
 etc.); results update ref chips asynchronously in the UI. Implemented by:
 `pota` (both types).
 
+**The core asks about references in batches.** Every reference an ADIF import
+or a deep link brings is decorated in one bridge round-trip, and so is every
+link a list of search results needs, every outline a map draws, and every
+phrase of an operation's title. Each reference is still its own call, to the
+handler `invokeHook` would pick for it (qualified claims included), so a
+handler implements the single-reference methods above and nothing else. The
+time budget belongs to the batch, though: ten seconds for all of its calls
+together. A handler that has not answered by then costs only its own
+reference — it stays as it was, with no name, link or outline — and every
+other reference keeps its answer. A `decorateRef` that goes to the network
+should answer well within that.
+
 `linkForRef` says where a reference can be read about on the web — the
 program's own page for it (POTA's park page, SOTA's summit page), or, for a
 contest, the rules the event is run under. The Operation Setup sheet asks for
@@ -499,11 +530,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?}
 
@@ -596,8 +629,12 @@ true when THIS extension alone was asked — the operator tapped its "Activity
 Types" row or typed its key as a scope — which a bare scope otherwise cannot be
 told from the nearby list, since neither carries a `searchTerm`. An extension
 that keeps itself out of the nearby list (`cwt`, offered only around a session)
-answers a scoped call anyway: it is the one being asked. The core fans
-out to every `activity` hook via `invokeHookAll`, merges results, and ranks them
+answers a scoped call anyway: it is the one being asked. The core fans out to
+every `activity` hook via `invokeHookAll`; a scoped search asks only its own
+hooks, in one batch (`invokeHookBatch`); and a search naming a type without the
+colon asks that type's hooks in one batch AND fans out to every hook — two
+round-trips, kept apart so a fan-out that runs out of time cannot cost the named
+type's answers. The core merges results and ranks them
 in TWO BANDS (`app/lib/tools/activity_suggestions.dart`): everything carrying a
 `distance` first, by `distance / relevance` ascending — a more relevant hit
 counts as nearer — then everything without one, by DESCENDING `relevance`, with
@@ -713,9 +750,38 @@ file claims its own reference; ask every hook and both programs'
 program to guess which is its. The delegate cannot work out who called it, so
 naming yourself is not optional.
 
-The full ADIF export names no `mainHandler` and every hook contributes —
-polo's `includeOtherRefs`, which only its full export sets. That is the export
-claiming no program: the complete copy the operator keeps.
+The full ADIF export names no `mainHandler`, and every program the contact
+belongs to contributes — polo's `includeOtherRefs`, which only its full export
+sets. That is the export claiming no program: the complete copy the operator
+keeps.
+
+**The full export asks only the extensions a contact belongs to.** For each
+reference on the contact's operation (the segment-effective one) and on the
+contact itself, the kernel takes every extension holding the strongest claim
+on it — the longest `ref:<type>/<code>` prefix that begins the reference's
+code, or else the bare `ref:<type>` — and asks those extensions' hooks, and no
+other's. A hunted reference on the contact counts as much as an activation on
+the operation, so a chaser's log keeps its `SOTA_REF`s. A longer claim excludes
+a shorter one: an old `{type: 'qp', ref: 'CA'}` reference belongs to the party
+that claims `qp/ca`, not also to the extension claiming all of `qp`. Equal
+claims are all asked, whatever their priority: WCA also registers
+`ref:ecaActivation` to resolve a castle while ECA is off, and ECA's fields
+must not depend on which of the two registered first. An installed extension the
+contact has nothing to do with is never asked, so a hook that forgets to check
+its own references costs nothing here; checking them is still how a hook
+behaves correctly when named by a program's own export.
+
+An extension that genuinely has something to say about every contact opts in
+from its **manifest**, `"adifFieldsScope": "always"`, and is asked whatever the
+contact carries. The field lives in the manifest, not on the hook, so the
+packer can check it without running the bundle: a manifest listing
+`adifFields` with neither a `ref:` type nor the opt-in is refused at packing
+and at publishing, and the app's own build refuses it too. The kernel reads the
+opt-in from the extension's definition, so spread the manifest into
+`defineExtension`, and it logs an error at activation for an extension that
+registers `adifFields` but answers for no reference and does not opt in.
+`mainHandler` and `includeFieldsFrom` are unaffected: a named hook is asked
+whatever the contact carries.
 
 An export can also name a **list** of other hooks it accepts,
 `includeFieldsFrom` — polo's all-or-nothing flag narrowed to what the program
@@ -728,13 +794,13 @@ would claim no reference at all.
 
 **A field name is written once per record, and the first to carry a value
 wins.** ADIF gives no meaning to a repeated field, so where two hooks answer
-the same name — the full export asks everyone, and a park and a summit both
-answer `MY_SIG` — the later one is dropped, and the contact's own fields
+the same name — the full export asks every program on the contact, and a park
+and a summit both answer `MY_SIG` — the later one is dropped, and the contact's own fields
 outrank all of them. Hooks are asked main handler first, then each
 `includeFieldsFrom` key in the order given, so that order decides — whichever
 of the two methods each hook answered. app-polo resolves a collision the same
-way ("keep the first one defined"). The **full export**, which asks everyone,
-has no such order: hooks answering `fieldCombinationsForOneQSO` are asked as one
+way ("keep the first one defined"). The **full export**, which asks every
+program on the contact, has no such order: hooks answering `fieldCombinationsForOneQSO` are asked as one
 group and hooks answering `fieldsForOneQSO` as another, so which of two programs
 keeps a shared `MY_SIG` there is not something either of them chose.
 
@@ -1161,8 +1227,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 +1239,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 +1262,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
@@ -1448,6 +1543,14 @@ fires when a lookup is ANSWERED, not while a call is being typed, and the
 guess is inside `args.qso` either way — declaring `'lookup'` is enough to be
 sent the draft, so what it saves over `'qso'` is renders, not the QSO.
 
+Beside the QSON, a draft carries one key a logged record never does:
+`callField`, the call field read at the cursor (`call`, `fullCall`,
+`partial`, `nextCall`, `nextPartial`). `their.call` is the field as typed, which may be a whole
+`//` stack or comma list; `callField.call` is the one call Enter logs. It
+is what [templates.md](templates.md)'s `qso.call` renders from, so a panel
+rendering a template needs nothing more, and moving the cursor within a
+stack or a list wakes a `'qso'` panel even when the QSON is unchanged.
+
 `'lookup'` fires when the panel is shown a callsign that HAS an answer —
 which includes opening a QSO whose stored record already carries one, not
 only a fresh lookup resolving. It does not fire when a lookup starts, fails,