@tx5dr/plugin-api 1.7.12 → 2.5.0

package/dist/toolkit/parallel-qso/ParallelQSOCoordinator.d.ts

@@ -0,0 +1,134 @@
+import type { ParsedFT8Message } from '@tx5dr/contracts';
+import type { QSOFailureInfo } from '../../hooks.js';
+import type { StrategyDecisionMetaV2, StrategyQSOCompletionEffect, StrategyQSOCompletionSettlement, StrategyStreamSnapshot, StrategyTransmission, StreamPhysicalReceipt, QueuedStrategyObservationMeta } from '../../runtime.js';
+import type { ParallelQSOQueueEntry, ProtocolLane, ProtocolLaneIdentity } from './ProtocolLane.js';
+export type ParallelQueueMutationReason = 'queue_full' | 'invalid_target' | 'entry_not_found' | 'active_entry' | 'version_conflict';
+export interface ParallelQueueMutationResult<TData> {
+    outcome: 'accepted' | 'duplicate' | 'rejected';
+    reason?: ParallelQueueMutationReason;
+    version: number;
+    entry?: ParallelQSOQueueEntry<TData>;
+    affectedStreamIds: string[];
+}
+export interface ParallelQueueEntrySnapshot<TData> {
+    entry: ParallelQSOQueueEntry<TData>;
+    active: boolean;
+    streamId?: string;
+    audioFrequencyHz?: number;
+}
+export interface ParallelQueueSnapshot<TData> {
+    version: number;
+    maxActiveStreams: number;
+    activeEntryIds: string[];
+    entries: ParallelQueueEntrySnapshot<TData>[];
+}
+export interface ParallelQSOFillOptions<TData> {
+    currentTransmitCycle: 0 | 1;
+    isEligible?: (entry: Readonly<ParallelQSOQueueEntry<TData>>) => boolean | Promise<boolean>;
+}
+export interface ParallelQSOActivateEntryOptions {
+    currentTransmitCycle: 0 | 1;
+    streamId: string;
+}
+export interface ParallelQSOFillResult {
+    activatedEntryIds: string[];
+    rejectedEntryIds: string[];
+    requestedTransmitCycle?: 0 | 1;
+}
+export interface ParallelQSOReleasedEntry {
+    streamId: string;
+    entryId: string;
+    disposition: 'remove-entry' | 'retain-entry';
+    reason: string;
+}
+export interface ParallelQSODecisionResult {
+    transmissions: StrategyTransmission[];
+    qsoCompletions: StrategyQSOCompletionEffect[];
+    qsoFailures: QSOFailureInfo[];
+    streams: StrategyStreamSnapshot[];
+    activeEntryIds: string[];
+    releasedEntries: ParallelQSOReleasedEntry[];
+}
+export interface ParallelQSOCoordinatorCheckpoint<TData> {
+    version: number;
+    nextEntrySequence: number;
+    maxStreams: number;
+    entries: ParallelQSOQueueEntry<TData>[];
+    bindings: Array<{
+        streamId: string;
+        entryId: string;
+        transmitCycle: 0 | 1;
+    }>;
+    lanes: Array<{
+        streamId: string;
+        checkpoint: unknown;
+    }>;
+}
+export interface ParallelQSOCoordinatorOptions<TData> {
+    maxSupportedStreams: number;
+    initialMaxStreams: number;
+    createLane(identity: ProtocolLaneIdentity): ProtocolLane<TData>;
+    maxQueueSize?: number;
+    entryIdPrefix?: string;
+}
+/** Protocol-neutral queue and stable-lane scheduler for built-in strategies. */
+export declare class ParallelQSOCoordinator<TData> {
+    private readonly lanes;
+    private readonly lanesByStreamId;
+    private readonly maxSupportedStreams;
+    private readonly maxQueueSize;
+    private readonly entryIdPrefix;
+    private entries;
+    private bindings;
+    private version;
+    private nextEntrySequence;
+    private maxStreams;
+    constructor(options: ParallelQSOCoordinatorOptions<TData>);
+    getMaxStreams(): number;
+    setMaxStreams(maxStreams: number, options?: {
+        preemptExcess?: boolean;
+    }): string[];
+    enqueue(input: {
+        targetKey: string;
+        callsign: string;
+        requestedTransmitCycle?: 0 | 1;
+        data: TData;
+    }): ParallelQueueMutationResult<TData>;
+    reorder(entryId: string, beforeEntryId: string | null, expectedVersion: number): ParallelQueueMutationResult<TData>;
+    remove(entryId: string, expectedVersion: number): ParallelQueueMutationResult<TData>;
+    clear(expectedVersion: number): ParallelQueueMutationResult<TData>;
+    updateEntry(entryId: string, update: (data: TData) => boolean): boolean;
+    setRequestedTransmitCycle(entryId: string, cycle: 0 | 1): boolean;
+    markChanged(): void;
+    releaseEntry(entryId: string, options: {
+        removeEntry: boolean;
+        reason: string;
+        resetLane?: boolean;
+    }): string | undefined;
+    getEntry(entryId: string): ParallelQSOQueueEntry<TData> | undefined;
+    findEntryByTargetKey(targetKey: string): ParallelQSOQueueEntry<TData> | undefined;
+    getQueueSnapshot(): ParallelQueueSnapshot<TData>;
+    fillAvailableLanes(options: ParallelQSOFillOptions<TData>): Promise<ParallelQSOFillResult>;
+    activateEntry(entryId: string, options: ParallelQSOActivateEntryOptions): ParallelQSOFillResult;
+    observe(messages: ParsedFT8Message[], meta: QueuedStrategyObservationMeta): boolean;
+    decide(messages: ParsedFT8Message[], meta: StrategyDecisionMetaV2): Promise<ParallelQSODecisionResult>;
+    getTransmissions(): StrategyTransmission[];
+    getStreams(): StrategyStreamSnapshot[];
+    setStreamState(streamId: string, stateId: string, expectedLifecycleEpoch: number): boolean;
+    invokeStreamAction(streamId: string, lifecycleEpoch: number, actionId: string, payload?: unknown): Promise<import('../../runtime.js').StrategyActionResult | void>;
+    onPhysicalReceipts(receipts: StreamPhysicalReceipt[]): string[];
+    settleQSOCompletion(settlement: StrategyQSOCompletionSettlement): boolean;
+    checkpoint(): ParallelQSOCoordinatorCheckpoint<TData>;
+    restore(checkpoint: ParallelQSOCoordinatorCheckpoint<TData>): void;
+    reset(reason?: string): void;
+    private workingLanes;
+    private waitingEntries;
+    private getActiveStreamIds;
+    private findStreamIdForEntry;
+    private releaseBinding;
+    private mutationResult;
+    private bumpVersion;
+    private validateMaxStreams;
+    private validateCheckpoint;
+}
+//# sourceMappingURL=ParallelQSOCoordinator.d.ts.map

package/dist/toolkit/parallel-qso/ParallelQSOCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParallelQSOCoordinator.d.ts","sourceRoot":"","sources":["../../../src/toolkit/parallel-qso/ParallelQSOCoordinator.ts"],"names":[],"mappings":"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"}