@ham2k/extension-sdk 0.10.0 → 0.11.0

package/dist/activityExports.js

@@ -83,7 +83,8 @@ function activityExportHook(rules) {
         exportData: args.exportData,
         exportTitle: args.exportTitle,
         mainHandler: rules.key,
-        includeFieldsFrom: rules.includeFieldsFrom
+        includeFieldsFrom: rules.includeFieldsFrom,
+        operatorFallback: rules.operatorFallback
       });
       return {
         filename: filenameFor(args.operation, args.qsos, wanted, args.compactFilenames),
@@ -155,7 +156,8 @@ function huntingExportHook(rules) {
         // key ('pota'), which is what its `adifFields` hook registers under;
         // the '-hunter' suffix belongs to the export registration alone.
         mainHandler: rules.key,
-        includeFieldsFrom: rules.includeFieldsFrom
+        includeFieldsFrom: rules.includeFieldsFrom,
+        operatorFallback: rules.operatorFallback
       });
       return {
         // The FULL qsos list, matching the option's filename — see
@@ -177,7 +179,8 @@ async function adifForExport({
   exportData,
   exportTitle,
   mainHandler,
-  includeFieldsFrom
+  includeFieldsFrom,
+  operatorFallback
 }) {
   const { hooks } = await import("@ham2k/extension-sdk");
   const entries = await hooks.invokeOne("export", "adif", "generateExport", {
@@ -193,7 +196,8 @@ async function adifForExport({
     exportData,
     exportTitle,
     mainHandler,
-    includeFieldsFrom
+    includeFieldsFrom,
+    operatorFallback
   });
   const content = entries.find((e) => e.ok)?.value?.content;
   if (!content) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.10.0
+// @ham2k/extension-sdk 0.11.0
 /** Experimental v1 panel scene contract. All coordinates are in the scene's viewBox. */
 export interface PanelScene {
 	version: 1;
@@ -661,6 +661,7 @@ export interface AdifFieldsHook {
 	fieldsForOneQSO(args: {
 		qso: Record<string, JSONValue>;
 		operation: Record<string, JSONValue>;
+		mainHandler?: boolean;
 	}, ctx: HookContext): Promise<{
 		name: string;
 		value: string;
@@ -718,7 +719,9 @@ export interface ExportRequest {
 	includePrivateData?: boolean;
 	mainHandler?: string;
 	includeFieldsFrom?: string[];
+	operatorFallback?: OperatorFallback;
 }
+export type OperatorFallback = "base" | "station";
 export interface ExportResult {
 	filename: string;
 	mimeType: string;
@@ -1057,6 +1060,24 @@ export interface SyncTransportHook {
 		ref?: string | null;
 		error?: string;
 	}>;
+	uploadStashFile?(args: {
+		file: {
+			filename: string;
+			content: string;
+			mimeType?: string;
+			format?: string;
+		};
+		groupUuid: string;
+		groupTitle?: string;
+	}, ctx: HookContext): Promise<{
+		uploaded?: boolean;
+		error?: string;
+		fatal?: boolean;
+	}>;
+	listStashFiles?(args: {
+		limit?: number;
+	}, ctx: HookContext): Promise<Record<string, JSONValue>>;
+	emailStashLink?(args: Record<string, never>, ctx: HookContext): Promise<Record<string, JSONValue>>;
 }
 export interface AccountField {
 	key: string;
@@ -1760,6 +1781,7 @@ export interface ActivityExportRules {
 	activationType: string;
 	icon?: string;
 	includeFieldsFrom?: string[];
+	operatorFallback?: OperatorFallback;
 }
 export declare function activityExportHook(rules: ActivityExportRules): {
 	getExportTypes(): Promise<ExportTypeDefinition[]>;
@@ -1774,13 +1796,14 @@ export interface HuntingExportRules {
 	icon?: string;
 	color?: string;
 	includeFieldsFrom?: string[];
+	operatorFallback?: OperatorFallback;
 }
 export declare function huntingExportHook(rules: HuntingExportRules): {
 	getExportTypes(): Promise<ExportTypeDefinition[]>;
 	suggestExportOptions({ operation, qsos, compactFilenames }: ExportOptionsRequest, ctx: HookContext): Promise<ExportOption[]>;
 	generateExport(args: ExportRequest, ctx: HookContext): Promise<ExportResult>;
 };
-export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom, }: {
+export declare function adifForExport({ operation, qsos, segments, includePrivateData, includeLookupData, exportSettings, exportData, exportTitle, mainHandler, includeFieldsFrom, operatorFallback, }: {
 	operation: Record<string, JSONValue>;
 	qsos: Record<string, JSONValue>[];
 	segments?: OperationSegmentPayload[];
@@ -1791,6 +1814,7 @@ export declare function adifForExport({ operation, qsos, segments, includePrivat
 	exportTitle?: string;
 	mainHandler: string;
 	includeFieldsFrom?: string[];
+	operatorFallback?: OperatorFallback;
 }): Promise<string>;
 export interface ActivityAdifImportRules {
 	sig: string;

package/docs/distribution.md

@@ -310,12 +310,10 @@ packer refuses anything else.
 There is no signing yet, so anyone could claim it, and the key is what the app
 shows when it says where a hook came from.
 
-The extensions built into the app use bare keys (`pota`, `sota`, …). Those are
-reserved too: hook identity has to stay unambiguous, and build-secret
-visibility is by key prefix, so an installed extension calling itself `sota`
-would be asking to read `SOTA_*`. The app refuses any collision at install —
-the packer cannot, because a standalone tool has no way to know what the app it
-will be installed into contains.
+The core extensions built into the app use bare keys (`adif`, `scoring`, …).
+Those are reserved too: hook identity has to stay unambiguous. The app refuses
+any collision at install — the packer cannot, because a standalone tool has no
+way to know what the app it will be installed into contains.
 
 ## What an installed extension does not get
 
@@ -325,14 +323,14 @@ follows where the code came from, not what it calls itself. A feature that
 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
+The sandbox is otherwise the same one the core extensions run in — no
 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
 
-**Settings → Extensions → Install from file…**, pick the `.h2kext`, and agree
+**Settings → Extensions & Features → Install from file…**, pick the `.h2kext`, and agree
 to what it asks for. The runtime restarts with it loaded, and the extension
 appears in its own category alongside the app's own, marked *Installed* and
 with a way to remove it again.
@@ -381,108 +379,126 @@ came from. Nothing is written until the operator agrees.
 
 ### Pre-loaded extensions
 
-The app ships eight of the catalog's own extensions already packaged, under
-`app/assets/preloaded-extensions/`, and installs them into the ordinary store
-on first run: `ham2k-pota`, `ham2k-sota`, `ham2k-wwff`, and the five lookups.
-Afterwards they are ordinary installed extensions — the same rows, the same
-update check, the same Update and uninstall — so an operator starts with a
-working app and the catalog can move it forward from there.
+The app builds in only its **core** extensions — the ones that are the app
+itself: `adif`, `scoring`, `lookups`, `templates`, the command sets and
+`ham2k-lofi` sync. Every other extension is a catalog bundle, and the app ships
+some of them already packaged under `app/assets/preloaded-extensions/`,
+installing them into the ordinary store on first run. Afterwards they are
+ordinary installed extensions — the same rows, the same update check, the same
+Update and uninstall — so an operator starts with a working app and the catalog
+can move it forward from there.
+
+Which ones ship is staged. Today it is the catalog twin of every extension the
+app used to build in (see [Retired built-ins](#retired-built-ins)), so that an
+install moving off them has every one to hand with no network. Once installs
+still on a build with the built-ins are few enough, it shrinks to the eight a
+new install needs — `ham2k-pota`, `ham2k-sota`, `ham2k-wwff` and the five
+lookups — and the rest are fetched from the catalog when switched on
+([HALO-743](https://cabo.ham2k.com/halo/c/743)). The app's own tests rely on
+only those eight, the core, and the never-shipped samples, so the shrink
+touches none of them.
+
+**They have to be kept current.** A pre-load is frozen into the binary, so
+every release must carry the catalog's current stable release of each one: an
+older one starts every new install behind the catalog until its first update
+check. `node scripts/preloaded-extensions.mjs check` compares them with what
+the catalog serves, byte for byte and at the app's extension API level;
+`node scripts/preloaded-extensions.mjs update` replaces any that are behind
+(`update <key>` adds one). Publishing a new release of a pre-loaded extension
+is therefore also a change to this repository, and the release cut refuses to
+ship pre-loads that fail the check ([releases.md §6.4](https://github.com/ham2k/halo/blob/main/docs/releases.md)).
 
 They are installed once, not every launch. A record of the highest version
 ever pre-loaded per key is what makes that true: an app update carrying a
 newer bundle installs it, a catalog release already ahead of it is left
 alone, and a key the operator uninstalled stays gone.
 
-Each one that renames a built-in — `ham2k-pota` is the built-in `pota` under
-a name the catalog can serve — carries the operator's settings, panel values
-and account credentials across on its first install. Copied, not moved: the
-built-in's own state stays where it is.
-
-One rule bends for these, and only for them:
-
-- **Built-in collisions.** An installed bundle may not claim a key the app
-  ships — judged against what the app is currently OFFERING, which once the
-  upgrade to catalog extensions is taken is the core extensions and nothing
-  else. `ham2k-lookup`
-  is both a built-in and a pre-load, and could otherwise never install.
-
-**Build secrets are not among them, and used to be.** A pre-load holding a
-`ham2k-` key could once read the values its name granted. Nothing needs that
-now: every value it carried — SOTA's OAuth client id, WWFF's API key — ships
-as a constant inside the extension that uses it, because these bundles are
-served to anyone who asks and a `.h2kext` is a zip. An installed extension
-sees no build secret, whatever key it claims and wherever it came from.
-
-### The upgrade to catalog extensions
-
-A new install — one whose default profile has never had a callsign — starts
-on the catalog at its first boot, on the bundles the app ships, with nothing
-to offer and nothing to carry; the decision is recorded once
-(`seedExtensionsMigratedDefault`). Onboarding still names its activities by
-their built-in keys, which `offeredKeyFor` maps to the shipped twin that
-actually runs. An install that has been running the app's own extensions is
-offered the move at start, on every launch until it is taken. Only a taken upgrade withdraws
-anything, and the offer may be deferred. A catalog that cannot be reached
-raises no offer and says nothing: it is a launch nobody was watching, and the
-offer comes back next time.
-
-Accepting installs the pre-loads, then fetches the catalog's twin of every
-other built-in the operator had switched on — `wca` becomes `ham2k-wca` —
-carrying its settings and credentials the same way. Nothing is withdrawn until
-that finishes; a download that fails puts the app's own extensions back in use
-and the offer returns next launch. Twins that did arrive stay on disk, unused
-until an upgrade completes — the built-in each one supersedes is what runs
-meanwhile.
-
-A bundle the engine will not evaluate takes the whole runtime with it, so the
-upgrade puts that one aside — the boot names the bundle it died on — and
-restarts once more. What boots then is the upgrade minus that extension, named
-in the dialog in a sentence of its own. Refused rather than
-withdrawn: the panel still lists it, badged, because the row is where an
-operator sees that something they installed is doing nothing, and updating it
-there is what lifts the refusal. Keyed by the VERSION that failed, so a fixed
-release arrives as an ordinary update and clears it. Only an INSTALLED
-extension is ever put aside; a built-in that
-will not evaluate is a defect in the app, and skipping it would ship an
-install quietly missing part of itself.
-
-A refusal is kept even when putting the bundle aside did not get a runtime
-back: it still will not evaluate, and an extension with no built-in behind it
-is in the reverted set too, so re-admitting it there would kill the boot that
-was about to give the operator everything back. Every dialog, and the notice
-that stands in for one, names what stayed out — except a downloaded copy the
-revert superseded, whose built-in is running again. Uninstalling clears the
-record, so a reinstall of the same bytes gets its chance.
-
-A refused extension is treated like a revoked one in everything else: it
-keeps its switch, and its downloaded data expires on the same clock as any
-extension the app is not loading.
-
-What this does NOT cover is a failure that names no bundle. Only a bundle
-that fails while it is being EVALUATED names itself: a kernel that will not
-load, or an extension that throws while ACTIVATING, takes the generation down
-under a name that is not a key. Those revert the whole upgrade as before, and
-it is offered again at the next launch.
-
-The upgrade restarts the extension runtime, which takes the footer items of
-the generation going down with it: a data file's import raises an error rather
-than returning into a torn-down runtime, so its progress line is cleared and
-the file is left unstamped for the next sweep instead of recorded as fresh
-with nothing imported.
-
-A few built-ins have no twin on purpose — `qp`, which the catalog carries as
-one extension per party instead — and the app names them itself
-(`kBuiltInsWithoutTwin`). Those are withdrawn without asking the catalog, and
-the dialog that reports the upgrade finished names each one the operator had
-switched on, since it is where they learn it is gone. Any other twin missing
-from the listing fails the upgrade and is asked for again next launch: a
-listing lacks a key the same way whether the catalog will never serve it or has
-not published it yet, and only the app knows which. A built-in retired from the
-catalog on purpose joins that list in the same change.
+An installed bundle may not claim a key the app builds in, and a pre-load is
+no exception: it goes through the same door as any other install.
+
+**Build secrets are not among what they get.** Every value a twin once needed —
+SOTA's OAuth client id, WWFF's API key — ships as a constant inside the
+extension that uses it, because these bundles are served to anyone who asks and
+a `.h2kext` is a zip. An installed extension sees no build secret, whatever key
+it claims and wherever it came from.
+
+### Retired built-ins
+
+The app used to build in forty-one more extensions — the activities, contests,
+lookups, a spot source and a dashboard panel. Their catalog copies are the same
+extensions under the reserved prefix (`pota` became `ham2k-pota`; `ham2k-lookup`
+kept its name), because the catalog cannot serve a bare key. Everything the app
+stores per extension hangs off the name — its settings group, its panel values,
+its account credentials, the operator's on/off choice — so each twin inherits
+from its built-in. The app keeps a table of the retired keys and whether each
+was on by default (`kRetiredBuiltIns`), since an install may skip any number of
+releases between the last one with its built-ins and this one; it never shrinks.
+
+**The move.** An install that ran the built-ins — one whose default profile had
+a callsign before its extension state was first recorded
+(`seedExtensionsMigratedDefault`) — moves onto their twins at its first boot on
+a build without them, unasked: there is nothing left to run instead. The boot's
+catch-up (`catchUpOnCatalogExtensions`) carries each built-in's on/off choice
+onto its twin, over whatever an earlier attempt left there; installs the
+pre-loads, which carry the built-in's settings, panel values and credentials on
+a twin's first install, and its default where the operator never chose; then
+fetches the twin of any other built-in the operator had switched on. It records
+the move done once the pre-load has run, so a boot killed half way carries the
+choices again next time. It needs no network while every twin is pre-loaded.
+The boot starts the extension runtime before settings are wired in, so a
+catch-up that finds none does not count, and wiring them runs it.
+Choices keep being carried after the move, too: onboarding and the
+`ONBOARD_AS` define name activities by their built-in keys, and
+`offeredKeyFor` writes each choice under both names, so a twin that arrives
+later still inherits it.
+
+Once moved, the operator sees one notice — not a dialog, since the move was not
+theirs to decide — saying their extensions now come from the catalog, naming
+anything that did not come along, and counting the twins still to arrive from a
+catalog that could not be reached. Any catch-up, the move or not, raises the
+same notice when an extension was put aside or the runtime would not start at
+all, and says so in place of "ready".
+
+A pre-load is recorded as offered only once it installed, or when the store
+refuses the bundle itself: a keychain that would not open or a full disk is
+tried again next launch, and meanwhile the adoption fetches the catalog's copy
+if the operator had it on. A twin the pre-load did install is never fetched
+back after the operator uninstalls it. A choice stored under the pre-load's own
+name — `ham2k-lookup`'s, which kept its name — is kept rather than dropped as
+stale.
+
+**What does not come along.** A few built-ins have no twin on purpose — `qp`,
+which the catalog carries as one extension per party instead, and `stateparks`,
+one per event — and the app names them itself (`kBuiltInsWithoutTwin`). The
+notice names each one the operator had switched on, since it is where they learn
+it is gone. Any other twin missing from the listing is asked for again next
+launch: a listing lacks a key the same way whether the catalog will never serve
+it or has not published it yet, and only the app knows which. A built-in
+retired from the catalog on purpose joins that list in the same change.
+
+**A twin that will not run.** A bundle the engine will not evaluate takes the
+whole runtime with it, so the catch-up puts that one aside — the boot names the
+bundle it died on — and restarts once more, the notice naming it in a sentence
+of its own. Refused rather than withdrawn: the panel still lists it, badged,
+because the row is where an operator sees that something they installed is
+doing nothing, and updating it there is what lifts the refusal. Keyed by the
+VERSION that failed, so a fixed release arrives as an ordinary update and
+clears it. Only an INSTALLED extension is ever put aside; a core one that will
+not evaluate is a defect in the app, and skipping it would ship an install
+quietly missing part of itself. A refused extension is treated like a revoked
+one in everything else: it keeps its switch, and its downloaded data expires on
+the same clock as any extension the app is not loading. A failure that names no
+bundle — a kernel that will not load, an extension that throws while
+ACTIVATING — puts nothing aside, and is reported.
+
+A twin fills the same lookup categories its built-in did, under data-file keys
+of its own. Each retired built-in is stamped disabled, so a week on the
+stale-data purge clears the data files it left — leaving alone the rows a live
+extension's data file still fills.
 
 ### Installing from the catalog
 
-**Settings → Extensions → Catalog** lists what [catalog.ham2k.net](https://catalog.ham2k.net)
+**Settings → Extensions & Features** lists what [catalog.ham2k.net](https://catalog.ham2k.net)
 publishes on its `stable` channel, in the catalog's own order for the
 operator's callsign (`relevance`, above). Install and Update go through the same consent screen as a
 file, over bytes that must hash to the sha256 the listing gives — a mismatch
@@ -496,6 +512,39 @@ catalog's own bundle links (`…/api/v1/extensions/<key>/versions/<version>/bund
 take this verified path when they arrive as a deep link; every other host
 takes the plain one above.
 
+### Release tracks
+
+A catalog channel — `stable`, `unstable` or `bleeding` — says how finished a
+release is, and the catalog cascades: asking for `unstable` sees unstable and
+stable releases. The panel's listing asks for `stable`. Under developer mode,
+**Developer → Extension Catalog → Catalog Search Tracks** (Only Stable,
+Unstable or better, Bleeding or better) widens it; turning developer mode off
+puts the listing back on stable without touching anything installed. Only
+the panel's listing reads it: fetching the catalog twins of retired built-ins
+reads stable, since those install with no consent screen, and restoring a
+missing extension reads the track it followed.
+
+The other way to an unfinished release is a link: the catalog's install
+button, or an address pasted into the panel's search field — a catalog
+bundle URL, an extension's page (`/extensions/<key>?channel=unstable`, which
+installs that channel's current release), the `install_extension` deep link
+itself, or an https URL ending in `.h2kext`; anything else is a search. A
+bundle URL is resolved against the listing on `bleeding`, which sees every
+release, and the version's channel is the steadiest one it is approved on. A
+page link records the channel it asked for as the track even when the release
+there turns out to be steadier — the operator chose that track.
+
+Whichever way it arrives, the consent screen warns over a release that is not
+stable, and the install records its channel in the provenance record as the
+TRACK the extension follows (`channel`, absent meaning stable). The update
+check asks about each extension on its own track — one request per track in
+use, side by side — and offers only what is newer than what is installed, so an extension installed at `0.1` unstable is updated to `1.0` stable,
+and then to `1.0.1` unstable. The track only widens on an install: a stable
+release landing over an unstable install leaves it on unstable. A pre-load
+counts as the catalog's own here. The row and the details show the track, and
+the details' **Follow stable releases only** puts it back on stable; an
+uninstall or a file install clears it with the rest of the record.
+
 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.
@@ -526,15 +575,72 @@ Beyond what the packer already refused:
 
 Each has its own message. A bundle that cannot be installed says why.
 
-## Native only, for now
-
-Installed bundles are files on disk. On web the app runs from its own assets
-and, for authors, the dev server — [development.md](https://github.com/ham2k/halo/blob/main/docs/extensions/development.md). So on
-web there is nothing to install into: no install from a file, no install or
-update from the catalog, and none of the pre-loaded extensions above.
-
-"For now" is a deferral, not a fact about the platform. Almost everything
-here is already platform-neutral — the zip walk, the manifest rules, the
-consent screen, the hash check — and what is left is a persistence seam of
-about six operations. `HALO-583` is the card that picks it up, and says what
-has to be decided first.
+## Where installed bundles live
+
+Everything above is platform-neutral — the zip walk, the manifest rules, the
+consent screen, the hash check. What differs is only where the bytes are kept
+(`BundleStorage`):
+
+- **natively**, one directory per key under the app's data directory, one
+  file per bundle entry;
+- **on web**, one IndexedDB record per key (database `halo-extensions`),
+  holding every entry's bytes under its own name. IndexedDB rather than the
+  Origin Private File System, which would mirror the native layout: every
+  browser HaLo runs in supports it the same way, while OPFS writes from the
+  page are newer and patchier on Safari.
+
+So the web build installs from a file, installs and updates from the catalog,
+pre-loads the shipped bundles and moves off the retired built-ins exactly as
+the native ones do.
+
+### When the store is lost
+
+The store can go while the preferences describing it survive: a browser
+clearing IndexedDB alone, a data directory deleted by hand, a store that
+failed mid-session. (When a browser clears a whole site, preferences go with
+it, and the app starts as a new install.) So what the operator installed is
+kept apart from the store that holds it, and put back from there.
+
+`extensionsInstalled` records every extension the operator installed
+(`{key: name}`). Every install writes it; only an uninstall — or Forget, below
+— removes it. An install that predates it is seeded from its store once, and
+after that it never follows the store: a store found short is exactly what it
+must not shrink to. Whatever is recorded there and not in the store is
+**missing**, however it went — judged by the keys the store holds, not by the
+extensions the app offers, since a built-in or a dev server can stand in front
+of an installed bundle. A store that cannot be read at all has lost nothing:
+that launch offers nothing, rather than everything back into a failing store.
+Where each came from is its provenance record's answer, and a key with none
+came from a file.
+
+The operator's on/off choice for a missing extension is kept too: the boot
+cleanup that prunes settings for keys the app no longer knows treats every
+recorded key as known.
+
+Putting them back, after the app starts:
+
+- **Shipped bundles** come back at boot from the app's own assets, unasked and
+  offline. The pre-load record says they were already offered, which is true
+  and beside the point; they are installed anyway, never as a first install,
+  so their settings and on/off choice stand. An install that has not taken the
+  upgrade gets back only what it had.
+- **Everything else** is offered in a dialog once the boot has settled:
+  - extensions from the catalog in use are listed to install, at the release
+    it serves now. **Later** keeps every one for the next launch;
+  - extensions from a file are listed to install again from their files, and
+    ones from a different catalog as not available here. Neither is fetched —
+    the bytes would come from a publisher the operator never agreed to;
+  - every row has **Forget**, which drops it with everything it stored — the
+    only way out for one the catalog no longer serves, which would otherwise
+    be offered, and fail, every launch.
+- **Install** installs each on its own: one that is not listed, will not
+  download or fails the check costs only itself. The runtime restarts with
+  everything that landed; a bundle it will not evaluate is set aside, as the
+  upgrade does, and the runtime restarts without it. The result names what
+  could not be installed (offered again next launch) and what installed but
+  would not run (kept, marked in the panel, where an update is the way back);
+  says so when the runtime would not start at all, rather than calling it a
+  success; and says the app is still busy — offering them again next launch
+  — when another catalog pass holds the store.
+- The offer waits for the boot's catch-up to finish, or for an upgrade that
+  every catch-up stepped aside for to let go.

package/docs/hooks.md

@@ -162,7 +162,8 @@ describes it whenever it was last worked. It still labels a carried-forward
 field by where it came from (`Call History` for a typed one, `Call History
 (guess)` for a guessed one), and a station's whole location travels in one
 of the two so the merge's grid/city reconciliation cannot split it — see
-`extensions/lookups/call-history/src/index.ts`.
+`ham2k-call-history`'s `src/index.ts` in
+[ham2k/extensions](https://github.com/ham2k/extensions).
 
 ## ✅ `recentContextLookup` — live-context lookups
 
@@ -741,12 +742,17 @@ knowing them. Called by the `adif` extension **inside the runtime** via
 
 ```ts
 interface AdifFieldsHook {
-  fieldsForOneQSO(args: { qso, operation }, ctx): Promise<{name, value}[]>
+  fieldsForOneQSO(args: { qso, operation, mainHandler? }, ctx): Promise<{name, value}[]>
   // One field set PER ADIF RECORD this contact should produce.
-  fieldCombinationsForOneQSO?(args: { qso, operation }, ctx): Promise<{name, value}[][]>
+  fieldCombinationsForOneQSO?(args: { qso, operation, mainHandler? }, ctx): Promise<{name, value}[][]>
 }
 ```
 
+`mainHandler` is true when the file is this extension's own export — app-polo's
+argument of the same name. It is how a program writes what only its own
+submission asks for: SOTA's files carry both stations' gridsquares, which the
+full export leaves to the contact's own privacy rules.
+
 POTA contributes `SIG/SIG_INFO/POTA_REF` (hunted refs on the QSO) and
 `MY_SIG/MY_SIG_INFO/MY_POTA_REF` (activation refs on the operation).
 
@@ -819,11 +825,24 @@ 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 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 every
+and a summit both answer `MY_SIG` — the later one is dropped. 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. The
+contact's own fields come after every hook's: a program knows what its file
+needs in a field better than the contact's generic answer does (the section a
+Field Day station sent, a satellite's downlink band). The exception is what
+identifies the contact — `CALL`, `QSO_DATE`, `TIME_ON`, `QSO_DATE_OFF`,
+`TIME_OFF`, `BAND`, `FREQ`, `MODE`, `SUBMODE`, `STATION_CALLSIGN`,
+`OPERATOR`: a hook answering one of those is dropped, since it would rewrite
+every record it is asked about, the whole-log backup included. A program whose
+uploader needs `OPERATOR` on every record asks for it on the export instead,
+`ExportRequest.operatorFallback` (`operatorFallback` on `activityExportHook`'s
+and `huntingExportHook`'s rules): the core writes `OPERATOR` only where it says
+something `STATION_CALLSIGN` doesn't, and with `'base'` or `'station'` it
+writes the contact's own operator on every record, falling back to the station
+call's base call or the station call itself. This is a
+deliberate divergence from app-polo, whose contact fields come first and whose
+main handler's are appended unchecked, so a name both answer is written twice. 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.
@@ -1397,6 +1416,26 @@ report — as a real CaBo card; the host writes the title, body and kind, the
 transport adds who/where/what-build and owns the account gate.
 Implemented by: `ham2k-lofi`.
 
+`uploadStashFile` / `listStashFiles` / `emailStashLink`
+(optional) back the Exports pane's Stash button, which sends export files
+to a store the operator fetches from any browser (Ham2K's File Stash, at
+stash.ham2k.net). `uploadStashFile` takes ONE file and the `groupUuid` of
+the batch it belongs to — the host mints it, since the sandbox has no uuid
+source, and calls once per file: its call timeout does not stop a hook, so a
+whole batch in one call would go on uploading unseen after the host had
+told the operator it failed. It answers `{ uploaded: true }` or `{ error }`,
+never a throw, with `fatal: true` on any failure but the server refusing
+that one file — sync off, no account or permission, no answer — so the host
+stops instead of having every remaining file fail the same way. No answer
+says the file may have arrived: a body can reach the server after the reply
+is lost.
+`listStashFiles` answers the server's `{ stash_files: [...] }`, newest
+first, which the host reads to warn a free account before a new stash
+replaces one not yet fetched; `emailStashLink` mails the account's own
+address a link to its stash. Both answer `{ error }` for a refusal. All
+three own the same sync gate `submitReport` does.
+Implemented by: `ham2k-lofi`.
+
 ## ✅ `panel` — panes an extension contributes to a view
 
 A panel is a PANE the operator can put in a customizable view's layout

package/docs/settings.md

@@ -521,5 +521,5 @@ standalone dialog — not inline in a `settingsPanel`'s `FormRenderer`.
 
 A `settingsPanel` field can reference an account for display/navigation via
 `fieldType: 'account'` (see above), but the account itself is still fully
-owned by its `AccountHook` registration. `extensions/lookups/qrz` continues
+owned by its `AccountHook` registration. `ham2k-qrz` continues
 to register under `account` — there is no migration to do.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",
@@ -71,12 +71,12 @@
     "build": "node build.mjs"
   },
   "//peerDependencies": [
-    "The libraries the extension host carries. An extension does NOT need these",
+    "The libraries the extension host provides. An extension does NOT need these",
     "installed: the build preset rewrites each one the manifest declares into a",
     "lookup on the host's single instance, before esbuild ever resolves it, and",
-    "the published .d.ts carries their types rolled in. They are here, optional,",
+    "the published .d.ts has their types rolled in. They are here, optional,",
     "for the one case that does reach the filesystem \u2014 `inline: [...]`, which",
-    "ships your own copy because you need a version the host does not carry."
+    "ships your own copy because you need a version the host does not provide."
   ],
   "peerDependencies": {
     "@ham2k/lib-callsigns": "*",

package/samples/k2hrc-cqww/src/index.ts

@@ -17,8 +17,8 @@
 // band, one contact per station per band. What this sample leaves out is
 // everything around them — Cabrillo export, the ADIF exchange fields, the
 // country-file zone suggestion, and writing a guessed exchange onto the QSO.
-// See `docs/hooks.md` §`scoring`, and `contests/cqww` in the app's repository
-// for the whole thing.
+// See `docs/hooks.md` §`scoring`, and the catalog's `ham2k-cqww` for the whole
+// thing.
 
 import { annotateCallAgainstCountryFile, contestArithmetic, contestScorer, contestSummary, defineExtension } from "@ham2k/extension-sdk"
 import type { ContestScorer, HookContext, JSONValue, LoggingControlDescriptor, Ref } from "@ham2k/extension-sdk"