/* v1_engine.h — 统一 C API 公共头 */
#ifndef V1_ENGINE_H
#define V1_ENGINE_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* —— 版本与能力查询 —— */
typedef struct { uint32_t major, minor, patch; const char* git_sha; } V1Version;
int32_t v1_version_get(V1Version* out);

/* —— 不透明句柄 —— */
typedef struct V1EngineImpl* V1EngineHandle;
typedef struct V1RoomImpl* V1RoomHandle;

/* —— 回调签名（用户态线程安全） —— */
typedef void (*V1OnError)(int32_t code, const char* msg, void* user_data);
typedef void (*V1OnFrame)(const V1VideoFrame* frame, void* user_data);

/* —— 核心生命周期 —— */
int32_t v1_engine_create(const V1EngineConfig* cfg, V1EngineHandle* out);
int32_t v1_engine_destroy(V1EngineHandle h);

/* —— 房间管理 —— */
int32_t v1_engine_join_room(V1EngineHandle h, const char* room_id,
                            const V1JoinOptions* opt, V1RoomHandle* out);
int32_t v1_room_leave(V1RoomHandle h);

/* —— 媒体控制 —— */
int32_t v1_room_publish_video(V1RoomHandle h, const V1VideoEncConfig* cfg);
int32_t v1_room_subscribe_video(V1RoomHandle h, const char* user_id,
                                V1OnFrame cb, void* user_data);

#ifdef __cplusplus
}
#endif
#endif

# api_def/v1_engine.yaml
module: v1_engine
version: "1.4.0"
types:
  - name: EngineConfig
    fields:
      - {name: log_level, type: int32_t, default: 2}
      - {name: data_dir, type: "const char*", nullable: true}
  - name: VideoFrame
    fields:
      - {name: width, type: uint32_t}
      - {name: height, type: uint32_t}
      - {name: format, type: PixelFormat}  # 枚举引用
      - {name: planes, type: "const uint8_t*[3]"}
      - {name: strides, type: "uint32_t[3]"}
      - {name: timestamp_us, type: int64_t}
enums:
  - name: PixelFormat
    values: [I420, NV12, RGBA, BGRA]
functions:
  - name: engine_create
    ret: int32_t
    params:
      - {name: cfg, type: "const EngineConfig*", dir: in}
      - {name: out, type: "EngineHandle*", dir: out}
    thread_safety: "Main Thread Only"
  - name: room_subscribe_video
    ret: int32_t
    params:
      - {name: room, type: "RoomHandle", dir: in}
      - {name: user_id, type: "const char*", dir: in}
      - {name: cb, type: "OnFrameCallback", dir: in}
      - {name: user_data, type: "void*", dir: in}
    thread_safety: "Thread Safe"
callbacks:
  - name: OnFrameCallback
    params:
      - {name: frame, type: "const VideoFrame*", dir: in}
      - {name: user_data, type: "void*", dir: in}

graph LR
    A[api_def/*.yaml] --> B[Python 生成器核心]
    B --> C[Jinja2 模板库]
    C --> D[C 头文件 v1_engine.h]
    C --> E[C# P/Invoke 绑定]
    C --> F[Java JNI 绑定]
    C --> G[Swift 绑定]
    C --> H[TS/JS WASM 绑定]
    C --> I[Python ctypes 绑定]
    C --> J[Go CGO 绑定]
    C --> K[Dart FFI 绑定]
    D & E & F & G & H & I & J & K --> L[CI 矩阵编译验证]
    L --> M[发布 npm / nuget / maven / pypi / pub.dev]

# generator/main.py
import yaml, jinja2, pathlib

TEMPLATES = pathlib.Path("templates")
ENV = jinja2.Environment(loader=jinja2.FileSystemLoader(TEMPLATES),
                         trim_blocks=True, lstrip_blocks=True)

def render_all(spec_path: pathlib.Path, out_root: pathlib.Path):
    spec = yaml.safe_load(spec_path.read_text())
    targets = {
        "c": "v1_engine.h.j2",
        "csharp": "V1Engine.cs.j2",
        "java": "V1Engine.java.j2",
        "swift": "V1Engine.swift.j2",
        "ts": "v1_engine.d.ts.j2",
        "python": "v1_engine.py.j2",
        "go": "v1_engine.go.j2",
        "dart": "v1_engine.dart.j2",
    }
    for lang, tpl_name in targets.items():
        tpl = ENV.get_template(tpl_name)
        out_dir = out_root / lang
        out_dir.mkdir(parents=True, exist_ok=True)
        (out_dir / tpl_name.replace(".j2", "")).write_text(tpl.render(spec))

// templates/V1Engine.cs.j2
using System;
using System.Runtime.InteropServices;

namespace {{ module }} {
    public static partial class Native {
        {{ "#region Version" }}
        [DllImport(LIB, CallingConvention = CallingConvention.Cdecl)]
        public static extern void v1_version_get(out VersionInfo info);

        [StructLayout(LayoutKind.Sequential)]
        public struct VersionInfo {
            public uint major, minor, patch;
            [MarshalAs(UnmanagedType.LPStr)] public string git_sha;
        }
        {{ "#endregion" }}

        {{ "#region Engine" }}
        [DllImport(LIB, CallingConvention = CallingConvention.Cdecl)]
        public static extern int v1_engine_create(
            [In] ref EngineConfig cfg, out IntPtr handle);

        [DllImport(LIB, CallingConvention = CallingConvention.Cdecl)]
        public static extern int v1_engine_destroy(IntPtr handle);

        [StructLayout(LayoutKind.Sequential)]
        public struct EngineConfig {
            public int log_level;
            [MarshalAs(UnmanagedType.LPStr)] public string data_dir;
        }
        {{ "#endregion" }}

        {% for fn in functions %}
        [DllImport(LIB, CallingConvention = CallingConvention.Cdecl)]
        public static extern int {{ fn.name }}({% for p in fn.params %}
            {% if p.dir == "in" %}[In] {% endif %}
            {{ map_type(p.type) }} {{ p.name }}{% if not loop.last %}, {% endif %}
        {% endfor %});
        {% endfor %}
    }
}

/* C 层提供统一调度器，绑定层仅需桥接 */
typedef void (*V1TaskFn)(void* ctx);
int32_t v1_dispatch_main(V1TaskFn fn, void* ctx);   // 投递至主线程
int32_t v1_dispatch_io(V1TaskFn fn, void* ctx);     // 投递至 IO 线程池

# .github/workflows/bindings.yml
jobs:
  build-bindings:
    strategy:
      matrix:
        include:
          - {os: ubuntu-latest,   target: linux-x64,   lang: [csharp, java, python, go, dart, ts]}
          - {os: macos-latest,    target: macos-x64,   lang: [csharp, java, python, go, dart, ts, swift]}
          - {os: macos-latest,    target: macos-arm64, lang: [csharp, java, python, go, dart, ts, swift]}
          - {os: windows-latest,  target: win-x64,     lang: [csharp, python, go, dart, ts]}
          - {os: ubuntu-latest,   target: android-arm64, lang: [java, dart]}
          - {os: ubuntu-latest,   target: ios-arm64,   lang: [swift, dart]}
          - {os: ubuntu-latest,   target: wasm32,      lang: [ts]}
    steps:
      - uses: actions/checkout@v4
      - name: Setup toolchains
        uses: ./.github/actions/setup-toolchains
        with: {target: ${{ matrix.target }}}
      - name: Generate bindings
        run: python generator/main.py api_def/v1_engine.yaml out/${{ matrix.target }}
      - name: Compile & Test each language
        run: |
          for lang in ${{ matrix.lang }}; do
            ./ci/build_${lang}.sh ${{ matrix.target }}
            ./ci/test_${lang}.sh ${{ matrix.target }}
          done
      - name: Publish artifacts
        if: github.event_name == 'release'
        run: ./ci/publish.sh ${{ matrix.target }}

/* v1_buffer.h — 零拷贝核心契约 */
typedef enum {
    V1_MEM_HOST   = 0x01,  // 系统堆 malloc/mmap
    V1_MEM_DMABUF = 0x02,  // Linux DMA-BUF FD
    V1_MEM_IOSURF = 0x03,  // macOS/iOS IOSurfaceRef
    V1_MEM_DXGI   = 0x04,  // Windows ID3D11Texture2D / HANDLE
    V1_MEM_VK     = 0x05,  // Vulkan VkImage / VkDeviceMemory
    V1_MEM_CUDA   = 0x06,  // CUDA CUdeviceptr
    V1_MEM_WASM   = 0x07   // WASM 线性内存 offset+len
} V1MemType;

typedef struct {
    V1MemType type;
    union {
        struct { void* ptr; size_t size; void (*free_fn)(void* ctx); void* ctx; } host;
        struct { int fd; uint32_t fourcc; uint32_t width; uint32_t height; uint32_t strides[4]; uint32_t offsets[4]; } dma_buf;
        struct { void* handle; uint32_t width; uint32_t height; uint32_t format; } iosurf;
        struct { void* handle; uint32_t subresource; } dxgi;
        struct { uint64_t img_handle; uint64_t mem_handle; } vk;
        struct { CUdeviceptr ptr; size_t size; } cuda;
        struct { uint32_t offset; uint32_t len; } wasm;
    };
    uint64_t timestamp_us;      // 统一时间基（CLOCK_MONOTONIC）
    uint32_t ref_count;         // 原子引用计数，跨语言统一生命周期
    void*   reserved[4];        // 扩展字段，避免 ABI 破坏
} V1Buffer;

/* 引用计数操作（线程安全） */
int32_t v1_buffer_retain(V1Buffer* buf);
int32_t v1_buffer_release(V1Buffer* buf);

/* 同步原语：跨 API 边界等待 GPU 完成 */
int32_t v1_buffer_wait_sync(V1Buffer* buf, uint64_t timeout_us);
int32_t v1_buffer_signal_sync(V1Buffer* buf);

typedef struct V1PoolImpl* V1PoolHandle;
int32_t v1_pool_create(const V1PoolConfig* cfg, V1PoolHandle* out);
int32_t v1_pool_acquire(V1PoolHandle h, V1Buffer** out);
int32_t v1_pool_recycle(V1PoolHandle h, V1Buffer* buf);  // 非阻塞

typedef void (*V1SimdKernelFn)(const V1Buffer* src, V1Buffer* dst, const V1SimdParams* params, void* ctx);

int32_t v1_register_simd_kernel(const char* name, V1SimdKernelFn fn, V1SimdIsa isa_mask);
/* isa_mask: V1_ISA_NEON | V1_ISA_AVX2 | V1_ISA_WASM_SIMD128 */

// plugin_manifest.json (嵌入插件 .so/.dll/.dylib 资源段)
{
  "plugin_id": "com.vendor.ai_denoise",
  "version": "2.1.0",
  "min_core_api": "1.4.0",
  "max_core_api": "1.9.9",
  "capabilities": ["audio_preprocess", "audio_postprocess"],
  "entry_point": "v1_plugin_entry",
  "dependencies": [
    {"name": "onnxruntime", "version": "1.16.0", "optional": false},
    {"name": "libv1_simd", "version": "1.0.0", "optional": true}
  ],
  "resources": {
    "model": "assets/denoise.onnx",
    "license": "assets/LICENSE"
  }
}

// v1_plugin_loader.c
typedef struct {
    const char* plugin_id;
    int32_t (*init)(const V1PluginContext* ctx);
    int32_t (*process)(V1PluginHandle h, V1Buffer* in_out, V1Buffer* aux);
    int32_t (*destroy)(V1PluginHandle h);
    int32_t (*configure)(V1PluginHandle h, const char* key, const V1Variant* val);
} V1PluginVTable;

int32_t v1_plugin_load(const char* path, V1PluginHandle* out) {
    // 1. dlopen/LoadLibraryEx(LOAD_WITH_ALTERED_SEARCH_PATH)
    // 2. 校验 manifest 签名（Ed25519 公钥内置核心）
    // 3. 版本兼容性检查：semver satisfies [min_core, max_core]
    // 4. 符号解析：dlsym/GetProcAddress("v1_plugin_entry")
    // 5. 依赖注入：将核心 API 表 (v1_core_api_v1) 传入插件 init
    // 6. 沙箱隔离：可选 seccomp-bpf / AppContainer / Seatbelt 限制插件权限
}

# security_hardening.cmake
if(CMAKE_SYSTEM_NAME STREQUAL "Linux" OR CMAKE_SYSTEM_NAME STREQUAL "Android")
    add_compile_options(
        -fstack-protector-strong
        -D_FORTIFY_SOURCE=2
        -fcf-protection=full          # CET / IBT
        -fstack-clash-protection
        -Wformat=2 -Wformat-security
        -fvisibility=hidden           # 默认隐藏符号
        -fPIE -pie                    # PIE/ASLR
    )
    add_link_options(
        -Wl,-z,relro,-z,now           # RELRO + BIND_NOW
        -Wl,-z,noexecstack
        -Wl,--strip-all               # 剥离调试符号
    )
elseif(CMAKE_SYSTEM_NAME STREQUAL "Windows")
    add_compile_options(
        /GS /guard:cf /sdl /Qspectre
        /DYNAMICBASE /NXCOMPAT        # ASLR + DEP
    )
    add_link_options(/DEBUG:NONE /OPT:REF /OPT:ICF)
elseif(CMAKE_SYSTEM_NAME STREQUAL "Darwin")
    add_compile_options(-fstack-protector-strong -fPIE)
    add_link_options(-Wl,-pie -Wl,-dead_strip -Wl,-exported_symbols_list,exports.sym)
endif()

# benchmarks/claims_evidence.yaml
claims:
  - id: "latency_p99_200ms"
    description: "端到端延迟 P99 ≤ 200ms (良网)"
    test_case: "bench/e2e_latency.py --profile=good_net --duration=300"
    evidence_artifact: "s3://bucket/evidence/latency_p99_200ms_2024Q3.html"
    ci_gate: true  # 每次发布必须通过
  - id: "cpu_1080p_30fps_lt_15%"
    description: "单路 1080p@30fps 编解码 CPU ≤ 15% (i7-1265U)"
    test_case: "bench/cpu_profile.py --codec=h264 --res=1080p --fps=30"
    evidence_artifact: "s3://bucket/evidence/cpu_1080p_15pct_2024Q3.json"
    ci_gate: true
  - id: "packet_loss_30_recover"
    description: "30% 丢包下仍可维持 720p@15fps 可视"
    test_case: "bench/net_emulate.py --loss=30 --jitter=50"
    evidence_artifact: "s3://bucket/evidence/loss30_recover_2024Q3.mp4"
    ci_gate: false  # 仅作参考

// v1_metrics.h
typedef enum {
    V1_METRIC_COUNTER,
    V1_METRIC_GAUGE,
    V1_METRIC_HISTOGRAM
} V1MetricType;

typedef struct {
    const char* name;           // 如 "v1_engine_encode_duration_ms"
    V1MetricType type;
    const char* unit;           // "ms", "bytes", "packets"
    const char* help;           // 说明
    const char* const* labels;  // 标签键名数组，如 {"codec","hw_accel"}
    uint32_t labels_count;
} V1MetricDesc;

/* 核心层仅注册描述 + 快速记录（无锁环形缓冲） */
int32_t v1_metrics_register(const V1MetricDesc* desc, uint32_t count);
int32_t v1_metric_record(const char* name, double value, const char* const* label_vals);

// v1_log.h
typedef enum { V1_LOG_TRACE, V1_LOG_DEBUG, V1_LOG_INFO, V1_LOG_WARN, V1_LOG_ERROR, V1_LOG_FATAL } V1LogLevel;

typedef void (*V1LogFn)(V1LogLevel level, const char* tag, const char* fmt, ...); // printf-like

/* 设置全局日志回调，绑定层桥接至 log4j / Serilog / zap / slog / os_log */
void v1_log_set_callback(V1LogFn fn, void* ctx);

/* Trace Context 传递（W3C TraceContext 兼容） */
typedef struct {
    char trace_id[32];      // 16 bytes hex
    char span_id[16];       // 8 bytes hex
    uint8_t trace_flags;    // 0x01 = sampled
} V1TraceContext;

int32_t v1_trace_get_current(V1TraceContext* out);   // 从 TLS/ContextVar 获取
int32_t v1_trace_set_current(const V1TraceContext* ctx);

// C# 绑定层
public static class V1Trace {
    private static readonly AsyncLocal<V1TraceContext> _current = new();
    public static V1TraceContext Current { get => _current.Value; set => _current.Value = value; }

    [UnmanagedCallersOnly(CallConvs = new[] { typeof(CallConvCdecl) })]
    private static void GetCurrent(out V1TraceContext ctx) => ctx = Current ?? default;

    [UnmanagedCallersOnly(CallConvs = new[] { typeof(CallConvCdecl) })]
    private static void SetCurrent(in V1TraceContext ctx) => Current = ctx;

    static V1Trace() {
        Native.v1_trace_set_callbacks(GetCurrent, SetCurrent);
    }
}

SDK 版本 = Core_API_Version . Feature_Version . Patch_Version
           ↑                  ↑                ↑
        破坏性变更        新增功能/优化      仅修复 Bug
        (Major)           (Minor)           (Patch)

// v1_remote_config.h
typedef enum {
    V1_CFG_BOOL, V1_CFG_INT32, V1_CFG_UINT64, V1_CFG_DOUBLE, V1_CFG_STRING, V1_CFG_JSON
} V1CfgType;

typedef struct {
    const char* key;
    V1CfgType type;
    const void* default_val;
    const char* description;
    bool restart_required;  // true 需重启引擎生效
} V1ConfigDef;

/* 启动时拉取，后台定时轮询（指数退避），变更回调通知上层 */
int32_t v1_config_init(const V1ConfigDef* defs, uint32_t count, const char* fetch_url);
typedef void (*V1OnConfigChange)(const char* key, const V1Variant* new_val, void* ctx);
int32_t v1_config_subscribe(const char* key, V1OnConfigChange cb, void* ctx);

// v1_circuit_breaker.h
typedef struct {
    const char* scope;        // "join_room", "publish", "subscribe"
    uint32_t failure_threshold; // 连续失败次数
    uint32_t success_threshold; // 半开状态成功次数
    uint64_t timeout_ms;      // 熔断持续时间
} V1CircuitBreakerConfig;

int32_t v1_circuit_breaker_configure(const V1CircuitBreakerConfig* cfgs, uint32_t count);
/* 核心层自动统计错误码（非 0 即失败），状态机：CLOSED → OPEN → HALF_OPEN → CLOSED */

graph TD
    A[开发提交 PR: api_def/v1_engine.yaml] --> B{CI: 破坏性变更检测}
    B -- 仅新增/兼容 --> C[自动生成绑定代码 Diff]
    B -- 破坏性变更 --> D[阻断合并, 要求 Major 版本号 + 升级指南]
    C --> E[Code Review: 架构师 + 多语言 Owner]
    E --> F[合并主干]
    F --> G[夜ly 触发全矩阵编译测试]
    G --> H[生成版本候选 RC]
    H --> I[灰度验证 48h]
    I --> J[发布 GA + 同步推送包管理器]

# ci/check_breaking_changes.py
import yaml, subprocess, sys

def load_spec(path): return yaml.safe_load(open(path))

def diff(old, new):
    breaking = []
    # 1. 函数签名变更
    for fn in old['functions']:
        if fn['name'] not in [f['name'] for f in new['functions']]:
            breaking.append(f"Function removed: {fn['name']}")
        else:
            new_fn = next(f for f in new['functions'] if f['name'] == fn['name'])
            if fn['ret'] != new_fn['ret'] or len(fn['params']) != len(new_fn['params']):
                breaking.append(f"Signature changed: {fn['name']}")
            for i, (op, np) in enumerate(zip(fn['params'], new_fn['params'])):
                if op['type'] != np['type'] or op['dir'] != np['dir']:
                    breaking.append(f"Param {i} changed in {fn['name']}: {op} -> {np}")
    # 2. 结构体字段删除/类型变更
    # 3. 枚举值删除
    return breaking

if __name__ == "__main__":
    old_spec = load_spec("api_def/v1_engine.yaml@HEAD~1")
    new_spec = load_spec("api_def/v1_engine.yaml")
    issues = diff(old_spec, new_spec)
    if issues:
        print("::error::Breaking changes detected:")
        for i in issues: print(f"  - {i}")
        print("nPlease bump MAJOR version and provide UPGRADE guide.")
        sys.exit(1)
    print("No breaking changes. Safe to release as MINOR/PATCH.")

# .github/workflows/docs.yml
jobs:
  docs:
    steps:
      - uses: actions/checkout@v4
      - name: Generate API Reference
        run: |
          python generator/main.py api_def/v1_engine.yaml out/docs --lang=all --doc-only
          # 产出: out/docs/{csharp,java,swift,ts,python,go,dart}/*.md
      - name: Validate Links & Examples
        run: |
          markdown-link-check out/docs/**/*.md
          # 校验代码片段可编译
          for lang in csharp java swift ts python go dart; do
            ./ci/verify_snippets.sh $lang out/docs/$lang
          done
      - name: Deploy to Portal
        if: github.ref == 'refs/heads/main'
        run: rsync -av out/docs/ s3://docs.v1-engine.io/$GITHUB_SHA/

# toolchain.lock.toml (由 CI 自动生成，纳入版本控制)
[toolchain]
cmake = "3.28.3"
ninja = "1.12.1"
clang = "18.1.8"
msvc = "14.40.33810"
android_ndk = "r27b"
xcode = "15.4"
emscripten = "3.1.58"

[codegen]
python = "3.12.4"
jinja2 = "3.1.4"
pyyaml = "6.0.1"
cbindgen = "0.26.0"
bindgen = "0.69.4"

[test]
gtest = "1.14.0"
xunit = "2.8.1"
junit = "5.10.2"
xctest = "15.4"
vitest = "2.0.5"
pytest = "8.2.0"
go_test = "1.22.4"
dart_test = "3.4.3"

[packaging]
nuget = "6.10.0"
maven = "3.9.6"
pypi = "twine-5.1.1"
npm = "10.8.2"
pub = "3.4.3"
cargo = "1.79.0"

# 开发机一键复现官方构建环境
docker run --rm -v $(pwd):/src v1-sdk-builder:1.4.0 
  bash -c "cd /src && ./ci/build_all.sh linux-x64 && ./ci/test_all.sh linux-x64"