@tx5dr/contracts 1.7.12 → 2.5.0

package/src/schema/operator.schema.ts

@@ -1,19 +1,27 @@
 import { z } from 'zod';
 import { ModeDescriptorSchema } from './mode.schema.js';
 import { sanitizeCallsignInput } from '../utils/callsign.js';
+import { sanitizeGridInput } from '../utils/grid.js';
+import { StrategyRuntimeSnapshotSchema } from './websocket.schema.js';
 
 const OperatorCallsignSchema = z
   .string()
   .transform(sanitizeCallsignInput)
   .pipe(z.string().min(1, '呼号不能为空').max(10, '呼号不能超过10个字符'));
 
+const OperatorGridSchema = z
+  .string()
+  .transform(sanitizeGridInput)
+  .pipe(z.string().min(4, '网格坐标至少4位').max(8, '网格坐标不能超过8位'));
+
 // 操作员配置 Schema (重命名以避免冲突)
 export const RadioOperatorConfigSchema = z.object({
   id: z.string().min(1, '操作员ID不能为空'),
   createdByTokenId: z.string().optional(), // 创建者 Token ID（仅用于审计，不参与权限判断）
   myCallsign: OperatorCallsignSchema,
-  myGrid: z.string().min(4, '网格坐标至少4位').max(8, '网格坐标不能超过8位').optional(),
+  myGrid: OperatorGridSchema.optional(),
   frequency: z.number().min(0).max(1000000000, '频率必须在0-1GHz之间').default(1000), // 音频偏移频率（Hz），默认1000Hz，创建时自动分配不重复值
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
   transmitCycles: z.array(z.number().min(0).max(1)).default([0]), // 0=偶数周期，1=奇数周期
   mode: ModeDescriptorSchema.optional(),
   logBookId: z.string().optional(), // 连接的日志本ID，如果未指定则使用默认日志本
@@ -61,6 +69,7 @@ export const RadioOperatorStatusResponseSchema = z.object({
     context: z.object({
       myCall: z.string(),
       myGrid: z.string(),
+      targetCalls: z.array(z.string()).optional(),
       targetCall: z.string(),
       targetGrid: z.string().optional(),
       frequency: z.number().optional(),
@@ -72,25 +81,7 @@ export const RadioOperatorStatusResponseSchema = z.object({
       state: z.string(),
       availableSlots: z.array(z.string()),
     }),
-    runtime: z.object({
-      currentState: z.string(),
-      slots: z.object({
-        TX1: z.string().optional(),
-        TX2: z.string().optional(),
-        TX3: z.string().optional(),
-        TX4: z.string().optional(),
-        TX5: z.string().optional(),
-        TX6: z.string().optional(),
-      }).optional(),
-      context: z.object({
-        targetCallsign: z.string().optional(),
-        targetGrid: z.string().optional(),
-        reportSent: z.number().optional(),
-        reportReceived: z.number().optional(),
-        actualFrequency: z.number().optional(),
-      }).optional(),
-      availableSlots: z.array(z.string()).optional(),
-    }).optional(),
+    runtime: StrategyRuntimeSnapshotSchema.optional(),
     slots: z.object({
       TX1: z.string().optional(),
       TX2: z.string().optional(),

package/src/schema/plugin.schema.ts

@@ -17,6 +17,16 @@ export const PluginTypeSchema = z.enum(['strategy', 'utility']);
  */
 export type PluginType = z.infer<typeof PluginTypeSchema>;
 
+export const StrategyFeaturesSchema = z.object({
+  targetQueue: z.literal(1).optional(),
+  parallelTargetQueue: z.literal(1).optional(),
+  queueActivation: z.enum(['immediate', 'operator-toggle']).optional(),
+  manualInitiation: z.literal(1).optional(),
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
+  maxSimultaneousSignals: z.number().int().min(1).max(5).optional(),
+}).optional();
+export type StrategyFeatures = z.infer<typeof StrategyFeaturesSchema>;
+
 /**
  * Runtime instance scope for a plugin.
  *
@@ -38,10 +48,17 @@ export type PluginInstanceScope = z.infer<typeof PluginInstanceScopeSchema>;
  */
 export const PluginPermissionSchema = z.enum([
   'network',
+  'plugin:event-bus',
   'host:hamlib',
+  'operator:transmit-control',
   'radio:read',
   'radio:control',
+  'radio:tuner-control',
   'radio:power',
+  'logbook:read',
+  'logbook:write',
+  'logbook:session',
+  'logbook:sync',
   'settings:ft8',
   'settings:decode-windows',
   'settings:realtime',
@@ -74,7 +91,17 @@ export type PluginPanelComponent = z.infer<typeof PluginPanelComponentSchema>;
  * These values control both validation expectations and default frontend
  * rendering in plugin settings UIs.
  */
-export const PluginSettingTypeSchema = z.enum(['boolean', 'number', 'string', 'string[]', 'object[]', 'keyedStringArrays', 'info']);
+export const PluginSettingTypeSchema = z.enum([
+  'boolean',
+  'number',
+  'string',
+  'string[]',
+  'object[]',
+  'keyedStringArrays',
+  'keyedObjectArrays',
+  'keyedObjects',
+  'info',
+]);
 
 /**
  * Supported generated-form field types for plugin settings.
@@ -94,6 +121,11 @@ export const PluginSettingOptionSchema = z.object({
  */
 export type PluginSettingOption = z.infer<typeof PluginSettingOptionSchema>;
 
+/**
+ * Field descriptor used for each item in an `object[]` or `keyedObjectArrays`
+ * setting editor. `key` becomes the object property; `type` controls the Host
+ * input; `required` and `default` are applied per item.
+ */
 export const PluginObjectArrayFieldSchema = z.object({
   key: z.string(),
   type: z.enum(['string', 'number', 'boolean']).optional().default('string'),
@@ -101,9 +133,14 @@ export const PluginObjectArrayFieldSchema = z.object({
   description: z.string().optional(),
   placeholder: z.string().optional(),
   required: z.boolean().optional(),
+  default: z.unknown().optional(),
 });
 export type PluginObjectArrayField = z.infer<typeof PluginObjectArrayFieldSchema>;
 
+/**
+ * Fixed key exposed by keyed setting editors. `key` is persisted in the value;
+ * `label` and `description` are literal text or plugin locale keys.
+ */
 export const PluginKeyedStringArrayKeySchema = z.object({
   key: z.string(),
   label: z.string(),
@@ -111,10 +148,18 @@ export const PluginKeyedStringArrayKeySchema = z.object({
 });
 export type PluginKeyedStringArrayKey = z.infer<typeof PluginKeyedStringArrayKeySchema>;
 
+/**
+ * Declarative condition evaluated against values in the same settings form.
+ * A leaf compares one `setting` with `equals` or `notEquals`; `allOf` requires
+ * every nested condition and `anyOf` requires at least one. Nested groups may
+ * be combined recursively.
+ */
 export interface PluginSettingCondition {
   /** Single setting key to compare. Preserves the original condition shape. */
   setting?: string;
+  /** Match when the referenced value is strictly equal to this value. */
   equals?: unknown;
+  /** Match when the referenced value is not strictly equal to this value. */
   notEquals?: unknown;
   /** All nested conditions must match. */
   allOf?: PluginSettingCondition[];
@@ -130,6 +175,7 @@ export const PluginSettingConditionSchema: z.ZodType<PluginSettingCondition> = z
   anyOf: z.array(PluginSettingConditionSchema).optional(),
 }));
 
+/** Description override selected when its condition matches. */
 export const PluginSettingConditionalDescriptionSchema = z.object({
   when: PluginSettingConditionSchema,
   description: z.string(),
@@ -156,6 +202,17 @@ export type PluginSettingScope = z.infer<typeof PluginSettingScopeSchema>;
  *
  * The host uses this schema to generate configuration forms, validate updates
  * and resolve default values before injecting them into `ctx.config`.
+ *
+ * Collection defaults must match the selected renderer:
+ * - `string[]` -> `string[]`
+ * - `object[]` -> `Array<Record<string, unknown>>` described by `itemFields`
+ * - `keyedStringArrays` -> `Record<string, string[]>`
+ * - `keyedObjectArrays` -> `Record<string, Array<Record<string, unknown>>>`
+ * - `keyedObjects` -> `Record<string, Record<string, unknown>>`
+ *
+ * Keyed editors use `keys` for their fixed outer keys; object-based editors use
+ * `itemFields` for the nested shape. `info` is display-only and cannot be used
+ * by `quickSettings`.
  */
 export const PluginSettingDescriptorSchema = z.object({
   type: PluginSettingTypeSchema,
@@ -167,7 +224,7 @@ export const PluginSettingDescriptorSchema = z.object({
   options: z.array(PluginSettingOptionSchema).optional(),
   /** Field schema used by generated editors for `object[]` settings. */
   itemFields: z.array(PluginObjectArrayFieldSchema).optional(),
-  /** Fixed key list used by generated editors for `keyedStringArrays` settings. */
+  /** Fixed key list used by generated keyed setting editors. */
   keys: z.array(PluginKeyedStringArrayKeySchema).optional(),
   /** Conditionally show the field based on another setting in the same form. */
   visibleWhen: PluginSettingConditionSchema.optional(),
@@ -231,6 +288,7 @@ export type PluginQuickSetting = z.infer<typeof PluginQuickSettingSchema>;
  * about plugin roles without hard-coding specific plugin names.
  */
 export const PluginCapabilitySchema = z.enum([
+  'auto_call_control',
   'auto_call_candidate',
   'auto_call_execution',
 ]);
@@ -247,6 +305,7 @@ export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
  *
  * - `operator`: shown in the expanded operator card's live-panel area (default).
  * - `automation`: shown inside the top-right automation quick-action popover.
+ * - `operator-action`: shown beside the built-in logbook action on an operator card.
  * - `main-right`: shown in the optional main layout plugin pane on the far right.
  * - `voice-left-top`: shown above the voice frequency control card.
  * - `voice-right-top`: shown in the tabbed top area of the voice right panel.
@@ -256,6 +315,7 @@ export type PluginCapability = z.infer<typeof PluginCapabilitySchema>;
 export const PluginPanelSlotSchema = z.enum([
   'operator',
   'automation',
+  'operator-action',
   'main-right',
   'voice-left-top',
   'voice-right-top',
@@ -284,12 +344,15 @@ export const PluginPanelWidthSchema = z.enum(['half', 'full']);
 export type PluginPanelWidth = z.infer<typeof PluginPanelWidthSchema>;
 
 /**
- * How an iframe panel is opened when rendered as a toolbar entry.
+ * How an iframe panel is opened when rendered as an action entry.
+ *
+ * `page` opens the referenced custom UI in the host's standalone plugin-page
+ * route instead of embedding it in the radio workspace.
  */
-export const PluginPanelOpenModeSchema = z.enum(['popover', 'modal']);
+export const PluginPanelOpenModeSchema = z.enum(['popover', 'modal', 'page']);
 
 /**
- * How an iframe panel is opened when rendered as a toolbar entry.
+ * How an iframe panel is opened when rendered as an action entry.
  */
 export type PluginPanelOpenMode = z.infer<typeof PluginPanelOpenModeSchema>;
 
@@ -330,21 +393,28 @@ export const PluginPanelDescriptorSchema = z.object({
   /** Optional controlled UI size hint for toolbar popovers/modals. */
   uiSize: PluginPanelUISizeSchema.optional(),
 }).superRefine((panel, ctx) => {
-  if (panel.slot !== 'radio-control-toolbar') {
+  if (panel.slot !== 'radio-control-toolbar' && panel.slot !== 'operator-action') {
     return;
   }
   if (panel.component !== 'iframe') {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       path: ['component'],
-      message: 'radio-control-toolbar panels must use iframe component',
+      message: `${panel.slot} panels must use iframe component`,
     });
   }
   if (!panel.pageId) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       path: ['pageId'],
-      message: 'radio-control-toolbar panels must declare pageId',
+      message: `${panel.slot} panels must declare pageId`,
+    });
+  }
+  if (panel.slot === 'operator-action' && panel.openMode !== 'page') {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['openMode'],
+      message: 'operator-action panels must use page openMode',
     });
   }
 });
@@ -354,6 +424,10 @@ export const PluginPanelDescriptorSchema = z.object({
  */
 export type PluginPanelDescriptor = z.infer<typeof PluginPanelDescriptorSchema>;
 
+/**
+ * Plugin instance that owns a runtime panel contribution: the single global
+ * instance or one explicitly identified operator instance.
+ */
 export const PluginUIPanelContributionTargetSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('global') }),
   z.object({ kind: z.literal('operator'), operatorId: z.string() }),
@@ -448,6 +522,11 @@ export type PluginStorageConfig = z.infer<typeof PluginStorageConfigSchema>;
 
 // ===== 插件清单 =====
 
+const SemanticVersionSchema = z.string().regex(
+  /^v?(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/,
+  'must be a semantic version',
+);
+
 /**
  * Normalized manifest describing a plugin's static metadata and declarations.
  *
@@ -455,9 +534,12 @@ export type PluginStorageConfig = z.infer<typeof PluginStorageConfigSchema>;
  * host can expose to management UI and diagnostics.
  */
 export const PluginManifestSchema = z.object({
+  apiVersion: z.literal(2).optional(),
   name: z.string(),
   version: z.string(),
+  minPluginApiVersion: SemanticVersionSchema.optional(),
   type: PluginTypeSchema,
+  strategyFeatures: StrategyFeaturesSchema,
   instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
   description: z.string().optional(),
   permissions: z.array(PluginPermissionSchema).optional(),
@@ -503,6 +585,7 @@ export type PluginLocales = z.infer<typeof PluginLocalesSchema>;
 export const PluginStatusSchema = z.object({
   name: z.string(),
   type: PluginTypeSchema,
+  strategyFeatures: StrategyFeaturesSchema,
   instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
   version: z.string(),
   description: z.string().optional(),
@@ -521,6 +604,8 @@ export const PluginStatusSchema = z.object({
   panels: z.array(PluginPanelDescriptorSchema).optional(),
   permissions: z.array(PluginPermissionSchema).optional(),
   capabilities: z.array(PluginCapabilitySchema).optional(),
+  autoCallEnabledOperatorIds: z.array(z.string()).optional(),
+  pausedOperatorIds: z.array(z.string()).optional(),
   ui: PluginUIConfigSchema.optional(),
   locales: PluginLocalesSchema.optional(),
   source: PluginSourceSchema.optional(),
@@ -586,6 +671,8 @@ export const PluginDistributionSchema = z.enum([
 export type PluginDistribution = z.infer<typeof PluginDistributionSchema>;
 
 export const PluginRuntimeInfoSchema = z.object({
+  hostVersion: z.string(),
+  pluginApiVersion: SemanticVersionSchema,
   pluginDir: z.string(),
   pluginDataDir: z.string(),
   dataDir: z.string(),
@@ -616,13 +703,17 @@ export const PluginMarketScreenshotSchema = z.object({
 });
 export type PluginMarketScreenshot = z.infer<typeof PluginMarketScreenshotSchema>;
 
-export const PluginMarketCatalogEntrySchema = z.object({
+const PluginMarketCatalogEntryInputSchema = z.object({
   name: z.string(),
   title: z.string(),
   description: z.string(),
+  readmeMarkdown: z.string().max(100 * 1024).optional(),
+  readmeSourceUrl: z.string().url().optional(),
   locales: PluginLocalesSchema.optional(),
   latestVersion: z.string(),
-  minHostVersion: z.string(),
+  minPluginApiVersion: SemanticVersionSchema.optional(),
+  /** Catalog schema v1 compatibility alias; normalized on read. */
+  minHostVersion: SemanticVersionSchema.optional(),
   author: z.string().optional(),
   license: z.string().optional(),
   repository: z.string().url().optional(),
@@ -635,15 +726,93 @@ export const PluginMarketCatalogEntrySchema = z.object({
   sha256: z.string().regex(/^[a-f0-9]{64}$/i),
   size: z.number().int().nonnegative(),
   publishedAt: z.string(),
+  artifactManifestVersion: z.literal(1).optional(),
+}).superRefine((value, context) => {
+  if (!value.minPluginApiVersion && !value.minHostVersion) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['minPluginApiVersion'],
+      message: 'minPluginApiVersion is required',
+    });
+  }
+  if (value.minPluginApiVersion && value.minHostVersion
+      && value.minPluginApiVersion !== value.minHostVersion) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['minPluginApiVersion'],
+      message: 'minPluginApiVersion conflicts with legacy minHostVersion',
+    });
+  }
+});
+
+export const PluginMarketCatalogEntrySchema = PluginMarketCatalogEntryInputSchema.transform((value) => {
+  const { minHostVersion: _legacyMinimum, ...entry } = value;
+  return {
+    ...entry,
+    minPluginApiVersion: value.minPluginApiVersion ?? value.minHostVersion!,
+  };
 });
 export type PluginMarketCatalogEntry = z.infer<typeof PluginMarketCatalogEntrySchema>;
 
-export const PluginMarketCatalogSchema = z.object({
-  schemaVersion: z.number().int().positive(),
-  generatedAt: z.string(),
-  channel: PluginMarketChannelSchema,
-  plugins: z.array(PluginMarketCatalogEntrySchema),
+const PluginMarketCatalogV2EntrySchema = PluginMarketCatalogEntryInputSchema.superRefine(
+  (value, context) => {
+    if (!value.minPluginApiVersion) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['minPluginApiVersion'],
+        message: 'catalog schema v2 requires minPluginApiVersion',
+      });
+    }
+    if (value.minHostVersion) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['minHostVersion'],
+        message: 'catalog schema v2 does not support legacy minHostVersion',
+      });
+    }
+    if (value.artifactManifestVersion !== 1) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['artifactManifestVersion'],
+        message: 'catalog schema v2 requires artifactManifestVersion 1',
+      });
+    }
+  },
+).transform((value) => {
+  const { minHostVersion: _legacyMinimum, ...entry } = value;
+  return {
+    ...entry,
+    minPluginApiVersion: value.minPluginApiVersion!,
+  };
+});
+
+export const PluginArtifactManifestSchema = z.object({
+  schemaVersion: z.literal(1),
+  name: z.string(),
+  version: z.string(),
+  minPluginApiVersion: SemanticVersionSchema,
+  apiVersion: z.literal(2).optional(),
+  type: PluginTypeSchema,
+  instanceScope: PluginInstanceScopeSchema.optional().default('operator'),
+  permissions: z.array(PluginPermissionSchema).optional().default([]),
+  strategyFeatures: StrategyFeaturesSchema,
 });
+export type PluginArtifactManifest = z.infer<typeof PluginArtifactManifestSchema>;
+
+export const PluginMarketCatalogSchema = z.discriminatedUnion('schemaVersion', [
+  z.object({
+    schemaVersion: z.literal(1),
+    generatedAt: z.string(),
+    channel: PluginMarketChannelSchema,
+    plugins: z.array(PluginMarketCatalogEntrySchema),
+  }),
+  z.object({
+    schemaVersion: z.literal(2),
+    generatedAt: z.string(),
+    channel: PluginMarketChannelSchema,
+    plugins: z.array(PluginMarketCatalogV2EntrySchema),
+  }),
+]);
 export type PluginMarketCatalog = z.infer<typeof PluginMarketCatalogSchema>;
 
 export const PluginMarketCatalogResponseSchema = z.object({
@@ -686,6 +855,8 @@ export const PluginsConfigSchema = z.object({
     z.string(),
     z.record(z.string(), z.record(z.string(), z.unknown()))
   ).optional().default({}),
+  /** 每操作员暂停的 transmit-control 插件：operatorId → pluginName[] */
+  operatorPluginPauses: z.record(z.string(), z.array(z.string())).optional().default({}),
 });
 export type PluginsConfig = z.infer<typeof PluginsConfigSchema>;
 

package/src/schema/pskreporter.schema.ts

@@ -16,9 +16,7 @@ export const PSKReporterStatsSchema = z.object({
   consecutiveFailures: z.number().default(0),
 });
 
-/**
- * PSKReporter 配置 Schema
- */
+/** PSK Reporter publishing identity, antenna metadata, interval and counters. */
 export const PSKReporterConfigSchema = z.object({
   /** 是否启用 PSKReporter 上报 */
   enabled: z.boolean().default(false),

package/src/schema/qso.schema.ts

@@ -49,6 +49,61 @@ export const SubdivisionConfidenceSchema = z.enum([
   'low',
 ]);
 
+/** Maximum UTF-8 JSON size of contest-owned data persisted with one QSO. */
+export const CONTEST_QSO_ENVELOPE_MAX_BYTES = 8 * 1024;
+
+const ContestQsoExchangeSchema = z.record(z.string(), z.string());
+const ContestQsoAnnotationValueSchema = z.union([z.string(), z.number().finite(), z.boolean()]);
+
+function durableContestQsoJson(value: unknown): string {
+  return JSON.stringify(value).replace(/[<>\u007f-\uffff]/g, character => (
+    `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`
+  ));
+}
+
+/**
+ * Versioned contest facts that must be committed atomically with their QSO.
+ *
+ * The shape is deliberately shallow and bounded. Contest plugins may choose
+ * their exchange and annotation keys, but cannot persist arbitrary object
+ * graphs or binary payloads in the logbook record.
+ */
+export const ContestQsoEnvelopeSchema = z.object({
+  schemaVersion: z.literal(1),
+  contestId: z.string().min(1),
+  editionId: z.string().min(1),
+  rulesetVersion: z.string().min(1),
+  sent: ContestQsoExchangeSchema,
+  received: ContestQsoExchangeSchema,
+  annotations: z.record(z.string(), ContestQsoAnnotationValueSchema).optional(),
+}).strict().superRefine((value, context) => {
+  if (new TextEncoder().encode(durableContestQsoJson(value)).byteLength > CONTEST_QSO_ENVELOPE_MAX_BYTES) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Contest QSO envelope must not exceed ${CONTEST_QSO_ENVELOPE_MAX_BYTES} UTF-8 JSON bytes`,
+    });
+  }
+});
+
+/**
+ * Serialize a validated contest envelope as ASCII-only JSON for durable ADIF
+ * private fields. Escaping non-ASCII and angle brackets keeps legacy string
+ * ADIF readers byte-safe without changing the decoded data.
+ */
+export function serializeContestQsoEnvelope(value: ContestQsoEnvelope): string {
+  return durableContestQsoJson(ContestQsoEnvelopeSchema.parse(value));
+}
+
+/** Parse and validate an envelope read from a durable private field. */
+export function parseContestQsoEnvelope(value: string): ContestQsoEnvelope | undefined {
+  try {
+    const parsed = ContestQsoEnvelopeSchema.safeParse(JSON.parse(value));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // 操作配置
 export const OperatorConfigSchema = z.object({
   id: z.string(),
@@ -60,6 +115,7 @@ export const OperatorConfigSchema = z.object({
   maxQSOTimeoutCycles: z.number(),
   maxCallAttempts: z.number(),
   frequency: z.number(),
+  maxConcurrentStreams: z.number().int().min(1).max(5).optional(),
   autoResumeCQAfterFail: z.boolean().default(false),
   autoResumeCQAfterSuccess: z.boolean().default(false),
   replyToWorkedStations: z.boolean().default(false),
@@ -91,6 +147,13 @@ export const QslSimpleStatusSchema = z.enum(['Y', 'N']).optional();
  * - DXCC enrichment and review metadata;
  * - LoTW / QRZ confirmation state;
  * - station-location metadata used when exporting ADIF-like records.
+ *
+ * `frequency` is the RF frequency in hertz; `startTime`/`endTime` and QSL dates
+ * are Unix epoch milliseconds. `mode` is the ADIF main mode and `submode` is the
+ * optional ADIF submode. `messageHistory` contains the raw digital-mode exchange.
+ * Sync providers update the service-specific LoTW/QRZ fields using ADIF status
+ * codes (`Y`, `N`, `R`, `Q`, `I`, and received-only `V`) rather than a generic
+ * `qslStatus` field.
  */
 export const QSORecordSchema = z.object({
   id: z.string(),
@@ -105,6 +168,8 @@ export const QSORecordSchema = z.object({
   reportReceived: z.string().optional(), // 接收的信号报告
   messageHistory: z.array(z.string()), // 内部消息历史（FT8 等数字模式）
   comment: z.string().optional(), // 标准 ADIF COMMENT 字段
+  contestId: z.string().optional(), // ADIF CONTEST_ID
+  contestEntry: ContestQsoEnvelopeSchema.optional(), // TX-5DR atomic contest facts
   myCallsign: z.string().optional(), // 我的呼号（操作员呼号）
   myGrid: z.string().optional(), // 我的网格定位（操作员网格）
   qth: z.string().optional(), // 对方 QTH（地点，语音通联常用）
@@ -141,8 +206,19 @@ export const QSORecordSchema = z.object({
 
   // 附注（对应 ADIF NOTES 字段）
   notes: z.string().optional(),
+}).superRefine((value, context) => {
+  if (value.contestId && value.contestEntry && value.contestId !== value.contestEntry.contestId) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['contestEntry', 'contestId'],
+      message: 'contestEntry.contestId must match contestId',
+    });
+  }
 });
 
+/** Host persistence behavior for an automatically completed QSO. */
+export const QSOPersistencePolicySchema = z.enum(['merge-nearby', 'preserve-distinct']);
+
 // 策略执行结果
 export const StrategiesResultSchema = z.object({
   stop: z.boolean().optional(),
@@ -162,6 +238,7 @@ export type DxccStatus = z.infer<typeof DxccStatusSchema>;
 export type DxccSource = z.infer<typeof DxccSourceSchema>;
 export type DxccConfidence = z.infer<typeof DxccConfidenceSchema>;
 export type QSOContext = z.infer<typeof QSOContextSchema>;
+export type ContestQsoEnvelope = z.infer<typeof ContestQsoEnvelopeSchema>;
 
 /**
  * Canonical persisted QSO record used by TX-5DR logbooks and plugin hooks.
@@ -170,4 +247,5 @@ export type QSOContext = z.infer<typeof QSOContextSchema>;
  * logbook queries.
  */
 export type QSORecord = z.infer<typeof QSORecordSchema>;
+export type QSOPersistencePolicy = z.infer<typeof QSOPersistencePolicySchema>;
 export type StrategiesResult = z.infer<typeof StrategiesResultSchema>; 

package/src/schema/radio-capability.schema.ts

@@ -36,9 +36,7 @@ export type CapabilityUpdateMode = z.infer<typeof CapabilityUpdateModeSchema>;
 export const CapabilityOptionValueSchema = z.union([z.string(), z.number()]);
 export type CapabilityOptionValue = z.infer<typeof CapabilityOptionValueSchema>;
 
-/**
- * 运行时能力值。
- */
+/** Runtime value carried by a radio capability state. */
 export const CapabilityValueSchema = z.union([z.boolean(), z.number(), z.string()]);
 export type CapabilityValue = z.infer<typeof CapabilityValueSchema>;
 
@@ -84,10 +82,7 @@ export const CapabilityDisplaySchema = z.object({
 });
 export type CapabilityDisplay = z.infer<typeof CapabilityDisplaySchema>;
 
-/**
- * 能力描述符
- * 由服务端在运行时下发，作为当前连接会话的真源。
- */
+/** Host-provided descriptor that defines one capability for the current session. */
 export const CapabilityDescriptorSchema = z.object({
   /** 全局唯一能力 ID，如 'tuner_switch', 'rf_power', 'lock_mode' */
   id: z.string(),
@@ -165,10 +160,7 @@ export const CapabilityDescriptorSchema = z.object({
 
 export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptorSchema>;
 
-/**
- * 能力运行时状态
- * 动态数据，通过 WebSocket 实时同步到前端。
- */
+/** Dynamic support, availability and value state for one capability. */
 export const CapabilityStateSchema = z.object({
   /** 能力 ID，与 CapabilityDescriptor.id 对应 */
   id: z.string(),
@@ -209,9 +201,7 @@ export const CapabilityStateSchema = z.object({
 
 export type CapabilityState = z.infer<typeof CapabilityStateSchema>;
 
-/**
- * 能力列表快照（radioCapabilityList WS 消息 / REST 响应的 data 部分）
- */
+/** Complete descriptor/state snapshot returned by radio capability APIs. */
 export const CapabilityListSchema = z.object({
   descriptors: z.array(CapabilityDescriptorSchema),
   capabilities: z.array(CapabilityStateSchema),
@@ -220,7 +210,8 @@ export const CapabilityListSchema = z.object({
 export type CapabilityList = z.infer<typeof CapabilityListSchema>;
 
 /**
- * 写命令负载（writeRadioCapability WS 命令的 data 部分）
+ * Legacy WebSocket payload for writing a generic radio capability.
+ * Plugin API v2 uses explicit radio/tuner command ports instead.
  */
 export const WriteCapabilityPayloadSchema = z.object({
   /** 能力 ID */
@@ -284,6 +275,7 @@ export const CAPABILITY_IDS = [
   'agc_mode',
   'preamp',
   'attenuator',
+  'radio_mode',
   'mode_bandwidth',
   'split_enabled',
   'vfo_select',
@@ -303,6 +295,7 @@ export const CAPABILITY_IDS = [
   'spectrum_rbw',
   'spectrum_during_tx',
   'spectrum_center_type',
+  'tci_iq_sample_rate',
   'dcs_code',
 ] as const;
 

package/src/schema/radio-power-support.ts

@@ -111,6 +111,9 @@ export function decidePowerSupport(
       // ICOM WLAN 的 CI-V-over-UDP 通道在电台关机后无法维持；即便已连接
       // 发送 powerstat(off) 也不能可靠恢复。整体不暴露电源控制。
       return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
+    case 'tci':
+      // TCI/ExpertSDR does not expose a safe physical power-on path here.
+      return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };
     case 'serial': {
       if (!rigInfo) {
         return { canPowerOn: false, canPowerOff: false, supportedStates: [], reason: 'model-unsupported' };