{
  "type": "nvuse-proposal",
  "version": 1,
  "configurationId": "cfg-20241115-001",
  "revision": 3,
  "direction": "send",                    // "send" | "recv" | "sendrecv"
  "codec": "VP9",
  "scalabilityMode": "L3T3_KEY",
  "spatialLayers": [
    { "width": 1920, "height": 1080, "maxFramerate": 30, "maxBitrate": 4500 },
    { "width": 1280, "height": 720,  "maxFramerate": 30, "maxBitrate": 2500 },
    { "width": 640,  "height": 360,  "maxFramerate": 15, "maxBitrate": 800  }
  ],
  "temporalLayers": 3,
  "encoderConfig": {
    "qpMax": 56,
    "keyFrameInterval": 3000,
    "intraRefresh": true,
    "contentHint": "motion"
  },
  "networkAdaptation": {
    "bitratePriority": "balanced",
    "degradationPreference": "maintain-framerate"
  }
}

stateDiagram-v2
    [*] --> IDLE
    IDLE --> CAP_EXCHANGE: 发起/收到 nvuse-capabilities
    CAP_EXCHANGE --> NEGOTIATING: 能力集交换完成
    NEGOTIATING --> ESTABLISHED: 双方 ACK 同一 revision
    ESTABLISHED --> RENEGOTIATING: 任意端发起 nvuse-proposal
    RENEGOTIATING --> ESTABLISHED: 达成一致 ACK
    RENEGOTIATING --> ESTABLISHED: 拒绝/超时 -> 回滚上一 revision
    ESTABLISHED --> FALLBACK: 连续 N 次失败或显式降级
    FALLBACK --> [*]: 切回 SDP O/A

interface NVUSECapabilities {
  codecs: CodecCapability[];
  maxEncodingPoints: number;      // 同时支持的编码器实例上限
  hardwareAcceleration: boolean;  // 是否有硬编/硬解
  supportedScalabilityModes: string[];
  encoderFeatureFlags: EncoderFeatureFlag[];
}

interface CodecCapability {
  mimeType: string;               // "video/VP9", "video/H264"
  profiles: string[];             // ["profile-id=0", "profile-id=1"]
  maxResolution: { width: number; height: number };
  maxFramerate: number;
  maxBitrate: number;
  spatialLayerLimit: number;
  temporalLayerLimit: number;
}

def solve_proposal(local_cap: NVUSECapabilities, remote_prop: NVUSEProposal) -> NVUSEProposal:
    # 1. 编解码器匹配
    codec = select_common_codec(local_cap.codecs, remote_prop.codec)
    # 2. 空间层裁剪
    spatial = clip_spatial_layers(local_cap, remote_prop.spatialLayers)
    # 3. 时间层对齐
    temporal = min(local_cap.temporalLayerLimit, remote_prop.temporalLayers)
    # 4. 编码器参数取交集
    encoder_cfg = intersect_encoder_config(local_cap, remote_prop.encoderConfig)
    # 5. 生成回应 proposal（revision +1）
    return NVUSEProposal(
        configurationId=remote_prop.configurationId,
        revision=remote_prop.revision + 1,
        codec=codec,
        spatialLayers=spatial,
        temporalLayers=temporal,
        encoderConfig=encoder_cfg,
        ...
    )

class NVUSENegotiator {
  private fallbackThreshold = 3;
  private consecutiveFailures = 0;

  async handleProposalResponse(response: NVUSEResponse) {
    if (response.status === 'accepted') {
      this.consecutiveFailures = 0;
      await this.applyConfiguration(response.proposal);
    } else {
      this.consecutiveFailures++;
      if (this.consecutiveFailures >= this.fallbackThreshold) {
        await this.triggerSDPFallback();
      } else {
        await this.rollbackToLastStableRevision();
      }
    }
  }

  private async triggerSDPFallback() {
    // 1. 发送 nvuse-terminate 通知对端
    // 2. 触发标准 createOffer/createAnswer 流程
    // 3. 清理 NVUSE 状态机
  }
}

interface BandwidthAdaptationPolicy {
  // 由应用层根据业务场景实现
  onBandwidthChange(availableBps: number, currentConfig: NVUSEProposal): NVUSEProposalDelta;
}

// 典型实现：维持帧率优先
class MaintainFrameratePolicy implements BandwidthAdaptationPolicy {
  onBandwidthChange(bps, cfg) {
    const target = cfg.spatialLayers.find(l => l.maxBitrate <= bps * 0.85);
    if (!target) return { temporalLayers: Math.max(1, cfg.temporalLayers - 1) };
    return { spatialLayers: cfg.spatialLayers.slice(0, target.index + 1) };
  }
}

sequenceDiagram
    participant A as 发起端
    participant S as 信令服务器/SFU
    participant B as 应答端
    Note over A,B: 阶段 0：能力探测 (并行化)
    par 能力广播
        A->>S: nvuse-capabilities (caps_A)
        B->>S: nvuse-capabilities (caps_B)
    end
    S->>A: aggregated-caps (caps_B_filtered)
    S->>B: aggregated-caps (caps_A_filtered)
    
    Note over A,B: 阶段 1：基线协商 (原子化)
    A->>S: nvuse-propose {cfgId: "c1", rev: 1, dir: "sendrecv", ...}
    S->>B: nvuse-propose (转发)
    alt 协商成功
        B->>S: nvuse-ack {cfgId: "c1", rev: 1, status: "accepted"}
        S->>A: nvuse-ack
        A->>A: applyEncoderConfig(rev=1)
        B->>B: applyEncoderConfig(rev=1)
    else 协商失败/拒绝
        B->>S: nvuse-ack {cfgId: "c1", rev: 1, status: "rejected", reason: "UNSUPPORTED_SCALABILITY"}
        S->>A: nvuse-ack
        A->>A: fallbackToSDP() / retryWithDowngrade()
    end
    
    Note over A,B: 阶段 2：运行时重协商 (乐观锁)
    loop 带宽变化/布局切换
        A->>S: nvuse-patch {cfgId: "c1", rev: 2, patch: [{op: "replace", path: "/spatialLayers/0/maxBitrate", value: 1200}]}
        S->>B: nvuse-patch
        alt 版本冲突 (B 已在 rev=3)
            B->>S: nvuse-nack {cfgId: "c1", expectedRev: 2, currentRev: 3, diff: [...]}
            S->>A: nvuse-nack
            A->>A: fetchLatestConfig() -> rebasePatch() -> retry
        else 成功
            B->>S: nvuse-ack {cfgId: "c1", rev: 2}
            S->>A: nvuse-ack
    end

// 核心数据结构
interface NVUSEState {
  configurationId: string;
  localRevision: number;      // 本地已应用版本
  remoteRevision: number;     // 远端确认版本
  pendingProposal: NVUSEProposal | null; // 待确认提案
  proposalQueue: NVUSEPatch[]; // 待发送补丁队列
}

// 发起重协商
async function proposePatch(state: NVUSEState, patch: NVUSEPatch): Promise<void> {
  // 1. 版本前置检查
  if (state.pendingProposal) {
    state.proposalQueue.push(patch); // 入队合并
    return;
  }
  
  const baseRev = state.localRevision;
  const proposal = buildProposal(state.configurationId, baseRev + 1, patch);
  
  // 2. 乐观锁发送
  state.pendingProposal = proposal;
  await signaling.send('nvuse-patch', proposal);
  
  // 3. 超时重传与退避
  const timer = setTimeout(() => handleTimeout(state), 2000);
  try {
    const ack = await waitForAck(proposal.configurationId, proposal.revision);
    clearTimeout(timer);
    handleAck(state, ack);
  } catch (e) {
    clearTimeout(timer);
    handleTimeout(state);
  }
}

// 处理远端 NACK (版本冲突)
function handleNack(state: NVUSEState, nack: NVUSENack): void {
  // 1. 同步远端最新版本
  state.remoteRevision = nack.currentRev;
  // 2. 变基本地待发队列
  state.proposalQueue = rebasePatches(state.proposalQueue, nack.diff);
  // 3. 清理 pending 状态，触发重试
  state.pendingProposal = null;
  drainQueue(state);
}

// 变基算法核心：基于 JSON Patch (RFC 6902) + Operational Transformation 简化版
function rebasePatches(queue: NVUSEPatch[], remoteDiff: NVUSEPatch[]): NVUSEPatch[] {
  return queue.map(localPatch => transformPatch(localPatch, remoteDiff));
}

// 核心抽象：编码器能力查询与配置应用
interface IVideoEncoderAdapter {
  // 能力查询（异步，首次调用缓存）
  getCapabilities(): Promise<EncoderCapabilities>;
  
  // 配置应用（原子化，支持回滚）
  applyConfig(config: NVUSEEncoderConfig, context: EncoderContext): Promise<ApplyResult>;
  
  // 运行时动态调整（无需重建编码器实例）
  reconfigure(params: Partial<NVUSEEncoderConfig>): Promise<void>;
  
  // 关键帧请求
  requestKeyFrame(spatialLayerId?: number): void;
  
  // 资源释放
  release(): void;
}

// 平台无关的上下文对象，隔离平台差异
interface EncoderContext {
  codec: 'H264' | 'VP8' | 'VP9' | 'AV1' | 'H265';
  profile: string;           // e.g., '42e01f' (H264 High)
  level: string;
  isHardwareAccelerated: boolean;
  maxResolution: { width: number; height: number };
  // 平台私有句柄（不透明指针）
  nativeHandle: number;      
}

// nvuse-propose 消息扩展字段
{
  "traceparent": "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
  "tracestate": "nvuse=cfg-20241115-001@rev=3,client=sdk-v2.4.1"
}

groups:
- name: nvuse-negotiation
  rules:
  # 1. 协商成功率跌破阈值
  - alert: NVUSE_Negotiation_Success_Rate_Drop
    expr: |
      sum(rate(nvuse_negotiation_result_total{result="success"}[5m])) 
      / sum(rate(nvuse_negotiation_result_total[5m])) < 0.98
    for: 3m
    labels: {severity: "critical", team: "rtc-core"}
    annotations:
      summary: "NVUSE 协商成功率低于 98%"
      runbook: "https://wiki.example.com/runbook/nvuse-negotiation-fail"

  # 2. 重协商风暴检测（单会话/分钟）
  - alert: NVUSE_Renegotiation_Storm
    expr: |
      histogram_quantile(0.99, rate(nvuse_renegotiation_per_session_bucket[1m])) > 10
    for: 2m
    labels: {severity: "warning"}
    annotations:
      summary: "检测到高频重协商，疑似带宽估计震荡或逻辑死循环"

  # 3. 编码器配置应用失败率
  - alert: NVUSE_Encoder_Apply_Failure
    expr: |
      sum(rate(encoder_apply_total{result="failed"}[5m])) 
      / sum(rate(encoder_apply_total[5m])) > 0.01
    for: 1m
    labels: {severity: "critical"}
    annotations:
      summary: "编码器配置应用失败率 > 1%，需排查驱动/参数合法性"

  # 4. 回退 SDP 比例异常
  - alert: NVUSE_Fallback_To_SDP_Ratio_High
    expr: |
      sum(rate(nvuse_fallback_total[10m])) / sum(rate(nvuse_session_established_total[10m])) > 0.05
    for: 5m
    labels: {severity: "warning"}
    annotations:
      summary: "NVUSE 降级 SDP 比例超 5%，可能存在兼容性问题"

# 1. 会话级诊断报告生成
$ nvuse-diag session --session-id=abc-123 --output=html
# 产出：时序图、配置变更历史、编码器参数对比、关键帧间隔抖动图

# 2. 实时参数抓取（调试模式）
$ nvuse-cli attach --peer-id=peer_xyz --dump-config
# 输出当前生效的 NVUSE 配置、编码器内部状态、SVC 层级依赖图

# 3. 兼容性矩阵自动化测试
$ nvuse-compat test --matrix=ci/matrix.yaml --report=junit
# matrix.yaml 定义：设备型号 × OS 版本 × 编码器 × 网络模板

// 场景 1：大型会议（发言人+画廊视图），上行 1080p，下行自适应
{
  "presetId": "large-meeting-speaker-view",
  "direction": "sendrecv",
  "codec": "VP9",
  "scalabilityMode": "L3T3_KEY",
  "spatialLayers": [
    {"width": 1920, "height": 1080, "maxFramerate": 30, "maxBitrate": 4000, "rid": "h"},
    {"width": 1280, "height": 720,  "maxFramerate": 30, "maxBitrate": 2000, "rid": "m"},
    {"width": 640,  "height": 360,  "maxFramerate": 15, "maxBitrate": 500,  "rid": "l"}
  ],
  "encoderConfig": {
    "qpMax": 56,
    "keyFrameInterval": 3000,
    "intraRefresh": true,
    "contentHint": "motion"
  },
  "networkAdaptation": {
    "bitratePriority": "balanced",
    "degradationPreference": "maintain-framerate"
  }
}

// 场景 2：弱网抗抖模式（移动网络、高铁/地铁）
{
  "presetId": "weak-network-resilience",
  "direction": "sendrecv",
  "codec": "H264",
  "profile": "constrained-baseline",
  "scalabilityMode": "L2T2",
  "spatialLayers": [
    {"width": 640, "height": 360, "maxFramerate": 15, "maxBitrate": 600},
    {"width": 320, "height": 180, "maxFramerate": 10, "maxBitrate": 150}
  ],
  "encoderConfig": {
    "qpMax": 51,
    "keyFrameInterval": 2000,
    "intraRefresh": false,
    "contentHint": "detail"
  },
  "networkAdaptation": {
    "bitratePriority": "framerate",
    "degradationPreference": "maintain-framerate",
    "minBitrateBps": 80000
  }
}

// 场景 3：屏幕共享/文档演示（高清晰度、低帧率、抗色度亚采样）
{
  "presetId": "screen-share-text-clarity",
  "direction": "sendonly",
  "codec": "AV1",
  "scalabilityMode": "L1T1",
  "spatialLayers": [
    {"width": 1920, "height": 1080, "maxFramerate": 5, "maxBitrate": 3000}
  ],
  "encoderConfig": {
    "qpMax": 40,
    "keyFrameInterval": 5000,
    "intraRefresh": true,
    "colorSpace": "BT.709",
    "chromaSubsampling": "4:4:4",
    "contentHint": "text"
  },
  "networkAdaptation": {
    "bitratePriority": "quality",
    "degradationPreference": "maintain-resolution"
  }
}