feat(ww-digi): isolate contest logs and refine workflow

Author: boybook

packages/builtin-plugins/src/standard-qso/index.ts

@@ -112,7 +112,7 @@ export const standardQSOStrategyPlugin = definePlugin({
   name: BUILTIN_STANDARD_QSO_PLUGIN_NAME,
   version: '1.0.0',
   type: 'strategy',
-  description: 'Built-in FT8/FT4 standard QSO automation strategy',
+  description: 'Built-in FT8/FT4 standard QSO strategy',
 
   settings: standardQSOSettings,
 

packages/builtin-plugins/src/standard-qso/locales/en.json

@@ -1,6 +1,6 @@
 {
   "pluginName": "Standard QSO",
-  "pluginDescription": "Built-in FT8/FT4 standard QSO automation strategy",
+  "pluginDescription": "Built-in FT8/FT4 standard QSO strategy",
   "strategyOverview": "Strategy Overview",
   "strategyOverviewDesc": "This strategy plugin drives the standard FT8/FT4 QSO flow, including answering others' CQ, automatic target picking, timeout handling, and retry behavior.",
   "autoReplyToCQ": "Answer others' CQ",

packages/builtin-plugins/src/standard-qso/locales/ja.json

@@ -1,6 +1,6 @@
 {
   "pluginName": "標準交信",
-  "pluginDescription": "FT8/FT4標準交信自動化戦略を内蔵",
+  "pluginDescription": "FT8/FT4標準交信ストラテジーを内蔵",
   "strategyOverview": "戦略の説明",
   "strategyOverviewDesc": "このポリシー プラグインは、他局の CQ への応答、自動選局、タイムアウトと再試行動作の制御など、標準の FT8/FT4 交信プロセスを担当します。",
   "autoReplyToCQ": "他局の CQ に自動応答",

packages/builtin-plugins/src/standard-qso/locales/zh.json

@@ -1,6 +1,6 @@
 {
   "pluginName": "标准通联",
-  "pluginDescription": "内置 FT8/FT4 标准通联自动化策略",
+  "pluginDescription": "内置 FT8/FT4 标准通联策略",
   "strategyOverview": "策略说明",
   "strategyOverviewDesc": "该策略插件负责标准 FT8/FT4 通联流程，包括回应他人 CQ、自动选台以及控制超时与重试行为。",
   "autoReplyToCQ": "自动回应他人 CQ",

packages/builtin-plugins/src/ww-digi/WWDigiProtocolLane.ts

@@ -441,6 +441,14 @@ export class WWDigiProtocolLane implements ProtocolLane<WWDigiEntryData> {
       completion.emitted = true;
       return { qsoCompletions: [structuredClone(completion.effect)] };
     }
+    if (actionId === 'retry-log') {
+      if (!this.completion || this.completion.settled !== 'failed') {
+        throw new Error('log_retry_not_available');
+      }
+      this.completion.settled = undefined;
+      this.completion.emitted = true;
+      return { qsoCompletions: [structuredClone(this.completion.effect)] };
+    }
     if (actionId === 'end-qso') {
       this.releaseRequested = true;
       return { requestDecision: true };
@@ -597,6 +605,14 @@ export class WWDigiProtocolLane implements ProtocolLane<WWDigiEntryData> {
       ];
     }
     if (!this.active) return [];
+    if (this.completion?.settled === 'failed') {
+      return [{
+        id: 'retry-log', label: 'actionRetry', icon: 'rotate-right', tone: 'primary', presentation: 'primary',
+      }, {
+        id: 'end-qso', label: 'actionEndQso', icon: 'xmark', tone: 'danger', presentation: 'menu',
+        confirmation: { title: 'confirmEndQso', description: 'confirmEndQsoDesc', confirmLabel: 'actionEndQso' },
+      }];
+    }
     const actions: StrategyActionDescriptor[] = [
       this.paused
         ? { id: 'resume', label: 'actionResume', icon: 'play', tone: 'primary', presentation: 'primary' }

packages/builtin-plugins/src/ww-digi/WWDigiStrategyRuntime.test.ts

@@ -94,6 +94,7 @@ function createRuntime(options: {
   workedCallsigns?: string[];
   busyCallsigns?: string[];
   transmitBlocked?: boolean;
+  sessionId?: string;
 } = {}) {
   let transmitting = options.transmitting ?? false;
   const busy = new Set((options.busyCallsigns ?? []).map((callsign) => callsign.toUpperCase()));
@@ -125,7 +126,9 @@ function createRuntime(options: {
       config.frequency + 300,
     ], undefined, () => options.transmitBlocked
       ? { transmitGate: { allowed: false, reason: 'confirmSettings' } }
-      : {}),
+      : {}, () => options.sessionId
+      ? { kind: 'plugin-session', sessionId: options.sessionId }
+      : undefined),
     setTransmitting(value: boolean) { transmitting = value; },
     config,
   };
@@ -533,7 +536,7 @@ describe('WWDigiStrategyRuntime protocol flows', () => {
   });
 
   it('completes the outbound grid, R-grid, RR73 sequence after physical TX', async () => {
-    const { runtime } = createRuntime({ transmitting: true });
+    const { runtime } = createRuntime({ transmitting: true, sessionId: 'ww-digi-session' });
     runtime.enqueueTarget({ callsign: 'JA1AAA', lastMessage: selected('CQ WW JA1AAA PM95') });
 
     const grid = await runtime.decide([], decision());
@@ -552,6 +555,7 @@ describe('WWDigiStrategyRuntime protocol flows', () => {
     expect(completion.qsoCompletions?.[0]).toMatchObject({
       streamId: 'stream-1',
       persistencePolicy: 'preserve-distinct',
+      destination: { kind: 'plugin-session', sessionId: 'ww-digi-session' },
       record: {
         callsign: 'JA1AAA',
         grid: 'PM95',
@@ -841,7 +845,7 @@ describe('WWDigiStrategyRuntime settlement and refill', () => {
     });
   });
 
-  it('projects a failed settlement as review without re-emitting completion', async () => {
+  it('keeps a failed settlement in review until the operator retries the same completion', async () => {
     const { runtime } = createRuntime({ transmitting: true });
     const started = await activateInbound(runtime, 'JA1AAA', 'PM95');
     confirmTransmissions(runtime, started);
@@ -867,5 +871,18 @@ describe('WWDigiStrategyRuntime settlement and refill', () => {
       tone: 'danger',
     });
     expect(reviewed.transmissions).toEqual([]);
+
+    const stream = runtime.getSnapshot().streams![0]!;
+    expect(stream.actions?.map((action) => action.id)).toContain('retry-log');
+    const retry = await runtime.invokeAction({
+      target: { kind: 'stream', streamId: stream.streamId, lifecycleEpoch: stream.qsoLifecycleEpoch },
+      actionId: 'retry-log',
+    });
+    expect(retry?.qsoCompletions).toEqual([
+      expect.objectContaining({
+        lifecycleEpoch: effect!.lifecycleEpoch,
+        record: expect.objectContaining({ id: effect!.record.id }),
+      }),
+    ]);
   });
 });

packages/builtin-plugins/src/ww-digi/WWDigiStrategyRuntime.ts

@@ -11,6 +11,7 @@ import type {
   QueuedStrategyTargetRequest,
   StrategyDecisionMetaV2,
   StrategyDecisionResult,
+  StrategyQSOCompletionEffect,
   StrategyQSOCompletionSettlement,
   StrategyRuntimeCheckpoint,
   StrategyRuntimeContext,
@@ -125,6 +126,7 @@ export class WWDigiStrategyRuntime implements QueuedStrategyRuntime {
       mode: 'FT8' | 'FT4',
     ) => Promise<{ encodable: boolean; error?: string; reason?: string }> = async () => ({ encodable: true }),
     private readonly snapshotExtension: () => WWDigiSnapshotExtension = () => ({}),
+    private readonly completionDestination: () => StrategyQSOCompletionEffect['destination'] = () => undefined,
   ) {
     const resolveFrequencies = typeof audioFrequenciesHz === 'function'
       ? audioFrequenciesHz
@@ -721,11 +723,15 @@ export class WWDigiStrategyRuntime implements QueuedStrategyRuntime {
     requestedTransmitCycle?: number;
     stop?: boolean;
   } = {}): StrategyDecisionResult {
+    const qsoCompletions = options.qsoCompletions?.map((effect) => {
+      const destination = this.completionDestination();
+      return { ...effect, ...(destination ? { destination } : {}) };
+    });
     return {
       transmission: null,
       transmissions: this.getTransmissions(),
       snapshot: this.getSnapshot(),
-      qsoCompletions: options.qsoCompletions,
+      qsoCompletions,
       qsoFailures: options.qsoFailures,
       requestedTransmitCycle: options.requestedTransmitCycle,
       stop: options.stop ?? false,

packages/builtin-plugins/src/ww-digi/index.test.ts

@@ -41,31 +41,40 @@ function createContestContext(options: {
   contestYear?: number;
   logBookId?: string | null;
   records?: QSORecord[];
+  awaitReady?: () => Promise<void>;
+  simulation?: boolean;
 } = {}) {
-  const queryQSOs = vi.fn(async () => options.records ?? []);
+  const queryQSOs = vi.fn(async (_filter?: unknown) => options.records ?? []);
   const ctx = createMockContext({
-    permissions: ['logbook:read', 'operator:transmit-control', 'plugin:event-bus'] as const,
+    permissions: ['logbook:session', 'operator:transmit-control', 'plugin:event-bus'] as const,
     callsign: 'BG5DRB',
     grid: 'OL32',
+    radio: { isSimulation: options.simulation === true },
     config: {
       contestYear: options.contestYear ?? 2026,
       location: 'DX',
       categoryBand: 'ALL',
       categoryPower: 'LOW',
     },
-    logbook: {
-      forCallsign: () => ({
-        callsign: 'BG5DRB',
-        getLogBookId: async () => options.logBookId === undefined ? 'logbook-BG5DRB' : options.logBookId,
-        queryQSOs,
-        readQsoSnapshot: async () => ({ revision: 'revision-1', records: [] }),
-        countQSOs: async () => 0,
-        getStatistics: async () => null,
-        addQSO: async (record: QSORecord) => record,
-        updateQSO: async (_id: string, updates: Partial<QSORecord>) => qsoRecord('updated', 0, updates.contestId),
-        applyQsoBatch: async () => ({ revision: 'revision-1', outcomes: [] }),
-        notifyUpdated: async () => {},
-      }),
+    logbookSessions: {
+      open: async (descriptor) => {
+        if (options.logBookId === null) throw new Error('WW Digi logbook is unavailable');
+        return {
+          id: options.logBookId ?? 'plugin-session-ww-digi-2026',
+          title: descriptor.title,
+          callsign: 'BG5DRB',
+          getLogBookId: async () => options.logBookId ?? 'plugin-session-ww-digi-2026',
+          awaitReady: options.awaitReady ?? (async () => {}),
+          queryQSOs,
+          readQsoSnapshot: async () => ({ revision: 'revision-1', records: [] }),
+          countQSOs: async () => 0,
+          getStatistics: async () => null,
+          addQSO: async (record: QSORecord) => record,
+          updateQSO: async (_id: string, updates: Partial<QSORecord>) => qsoRecord('updated', 0, updates.contestId),
+          applyQsoBatch: async () => ({ revision: 'revision-1', outcomes: [] }),
+          notifyUpdated: async () => {},
+        };
+      },
     },
   });
   return { ctx, queryQSOs };
@@ -80,7 +89,27 @@ describe('WW Digi contest edition persistence', () => {
     });
   });
 
-  it('reconciles all eligible FT4/FT8 records into a shared callsign/year session', async () => {
+  it('waits for the host logbook readiness signal before startup reconciliation', async () => {
+    let releaseReady!: () => void;
+    const awaitReady = vi.fn()
+      .mockImplementationOnce(() => new Promise<void>((resolve) => { releaseReady = resolve; }))
+      .mockResolvedValue(undefined);
+    const { ctx, queryQSOs } = createContestContext({ awaitReady });
+    const loading = wwDigiStrategyPlugin.onLoad!(ctx as never);
+
+    await vi.waitFor(() => expect(awaitReady).toHaveBeenCalledOnce());
+    expect(queryQSOs).not.toHaveBeenCalled();
+
+    releaseReady();
+    await loading;
+    expect(queryQSOs).toHaveBeenCalledOnce();
+    expect(ctx.store.operator.get(wwDigiTestables.runtimeLogbookIdKey(2026)))
+      .toBe('plugin-session-ww-digi-2026');
+    expect(ctx.store.global.get<{ health?: { state?: string } }>(wwDigiTestables.sessionKey('BG5DRB', 2026))?.health)
+      .toMatchObject({ state: 'healthy' });
+  });
+
+  it('refreshes the contest projection only from its independent session', async () => {
     const in2026 = qsoRecord('qso-2026', Date.UTC(2026, 7, 29, 12, 0));
     const in2025 = qsoRecord('qso-2025', Date.UTC(2025, 7, 30, 12, 0));
     const nonContest = qsoRecord('not-ww-digi', Date.UTC(2026, 7, 29, 12, 1), 'OTHER');
@@ -90,7 +119,7 @@ describe('WW Digi contest edition persistence', () => {
       [contestQso('retained-2025', Date.UTC(2025, 7, 30, 12))],
     );
 
-    await expect(wwDigiTestables.reconcileLedger(ctx, 2026)).resolves.toEqual({ imported: 1, total: 2 });
+    await expect(wwDigiTestables.refreshContestProjection(ctx, 2026)).resolves.toEqual({ total: 1 });
 
     expect(queryQSOs).toHaveBeenCalledWith(expect.objectContaining({
       orderDirection: 'asc',
@@ -104,23 +133,52 @@ describe('WW Digi contest edition persistence', () => {
     expect(await wwDigiTestables.readContestRecords(ctx, 2026))
       .toEqual(expect.arrayContaining([
         expect.objectContaining({ qsoId: 'qso-2026', source: 'ww-digi' }),
-        expect.objectContaining({ qsoId: 'not-ww-digi', source: 'reconciled' }),
       ]));
     expect(ctx.store.operator.get<ContestQso[]>(wwDigiTestables.ledgerKey(2025)))
       .toEqual([expect.objectContaining({ qsoId: 'retained-2025' })]);
     expect(ctx.store.global.get<{ health?: { state?: string } }>(wwDigiTestables.sessionKey('BG5DRB', 2026))?.health)
       .toEqual(expect.objectContaining({ state: 'healthy' }));
   });
 
+  it('includes out-of-period FT4/FT8 records only for a virtual radio', async () => {
+    const outsidePeriod = qsoRecord('virtual-qso', Date.UTC(2026, 7, 28, 9, 20, 15));
+    const physical = createContestContext({ records: [outsidePeriod] });
+    const virtual = createContestContext({ records: [outsidePeriod], simulation: true });
+
+    await expect(wwDigiTestables.refreshContestProjection(physical.ctx, 2026))
+      .resolves.toEqual({ total: 0 });
+    expect(physical.queryQSOs).toHaveBeenCalledWith(expect.objectContaining({
+      timeRange: expect.any(Object),
+    }));
+
+    await expect(wwDigiTestables.refreshContestProjection(virtual.ctx, 2026))
+      .resolves.toEqual({ total: 1 });
+    expect(virtual.queryQSOs.mock.calls[0]?.[0]).not.toHaveProperty('timeRange');
+    await expect(wwDigiTestables.readContestRecords(virtual.ctx, 2026))
+      .resolves.toEqual([expect.objectContaining({ qsoId: 'virtual-qso' })]);
+  });
+
   it('marks an unavailable logbook degraded and refuses Cabrillo rendering', async () => {
     const { ctx } = createContestContext({ logBookId: null });
 
-    await expect(wwDigiTestables.reconcileLedgerWithHealth(ctx, 2026))
+    await expect(wwDigiTestables.refreshContestProjectionWithHealth(ctx, 2026))
       .rejects.toThrow(/logbook is unavailable/);
     expect(ctx.store.global.get<{ health?: { state?: string } }>(wwDigiTestables.sessionKey('BG5DRB', 2026))?.health)
       .toEqual(expect.objectContaining({ state: 'degraded' }));
     await expect(wwDigiTestables.renderCabrillo(ctx, 2026))
-      .rejects.toThrow(/reconcile it before download/);
+      .rejects.toThrow(/logbook is unavailable/);
+  });
+
+  it('exports only independent WW Digi session records as standard ADIF', async () => {
+    const contest = qsoRecord('contest', Date.UTC(2026, 7, 29, 12, 0));
+    const unrelated = { ...qsoRecord('other', Date.UTC(2026, 7, 29, 12, 1), 'OTHER'), callsign: 'K1OTHER' };
+    const { ctx } = createContestContext({ records: [contest, unrelated] });
+
+    const adif = await wwDigiTestables.renderADIF(ctx, 2026);
+    expect(adif).toContain('<programid:13>TX5DR-WW-DIGI');
+    expect(adif).toContain('<call:6>JA1AAA');
+    expect(adif).toContain('<station_callsign:6>BG5DRB');
+    expect(adif).not.toContain('K1OTHER');
   });
 
   it('migrates a schema v1 session to an unconfirmed v2 session without losing overrides', async () => {
@@ -138,7 +196,7 @@ describe('WW Digi contest edition persistence', () => {
       operatorTransmitters: {}, migratedOperators: {}, health: { state: 'healthy' },
     });
 
-    await wwDigiTestables.reconcileLedger(ctx, 2026);
+    await wwDigiTestables.refreshContestProjection(ctx, 2026);
     expect(ctx.store.global.get<Record<string, unknown>>(key)).toMatchObject({
       schemaVersion: 2,
       setup: { status: 'unconfirmed' },
@@ -161,6 +219,25 @@ describe('WW Digi contest edition persistence', () => {
       .toEqual(expect.objectContaining({ 'qso-2026': expect.objectContaining({ operatorId: 'operator-0', transmitterId: 0 }) }));
   });
 
+  it('records an out-of-period completion only when the active radio is virtual', async () => {
+    const record = qsoRecord('local-simulation-qso', Date.UTC(2026, 7, 28, 9, 20, 15));
+    const physical = createContestContext({ records: [record] });
+    const virtual = createContestContext({ records: [record], simulation: true });
+    const hook = wwDigiStrategyPlugin.hooks?.onQSOComplete;
+
+    await hook!(record, physical.ctx);
+    expect(physical.ctx.store.global.get<{ overrides?: Record<string, unknown> }>(
+      wwDigiTestables.sessionKey('BG5DRB', 2026),
+    )?.overrides).toBeUndefined();
+
+    await hook!(record, virtual.ctx);
+    expect(virtual.ctx.store.global.get<{ overrides?: Record<string, unknown> }>(
+      wwDigiTestables.sessionKey('BG5DRB', 2026),
+    )?.overrides).toEqual(expect.objectContaining({
+      'local-simulation-qso': expect.objectContaining({ operatorId: 'operator-0' }),
+    }));
+  });
+
   it('defaults the setting to the current UTC year with bounded input', () => {
     const descriptor = wwDigiStrategyPlugin.settings?.contestYear;
     expect(descriptor).toMatchObject({