# Connector SDK v1 开发指南

## 最小接入

从 `app.core.connectors` 导入 `Connector`、`ConnectorManifest`、`OperationRequest`、
`OperationResult` 和 `ConnectorRegistry`。连接器声明唯一 `connector_id`、语义版本、固定
`sdk_version=1.0`、能力清单与 `additionalProperties: false` 的配置 Schema，实现八个统一方法，
然后调用 `registry.register(connector)`。不要修改 runtime 或采集 dispatcher。

配置由 JSON Schema Draft 2020-12 递归校验，包括嵌套对象、数组、上下界、组合规则和未知字段。
非 dry-run 机器运行不得出现调用方 config 字段，即使值为 `{}` 也拒绝。Oracle、SQL Server、REST
均须先由管理员创建版本化 source binding，再将 principal 绑定到同一 connector/version/source/
domain/environment；runtime 只使用服务端批准的完整配置，包括非 REST 的 credential reference。
配置只能保存连接信息与秘密引用。秘密字段必须命名为 `*_ref`，值使用 `env:`、`vault:` 或
`secret:` 引用；不得把 password、token、API key、Authorization 或私钥放入配置、manifest、
异常、日志或 evidence。

## 契约规则

1. 所有外部读取必须有超时、响应/记录上界与明确 scope；SQL 必须只读且参数化。
2. `OperationResult` 返回不可变 records、cursor、checkpoint 和安全 evidence。增量和恢复必须
   使用已持久化的 cursor/checkpoint。大型 snapshot checkpoint 应保存有界 hash/count 摘要；若没有
   足够信息精确重建 added/removed/changed，就明确 `details_materialized=false`，不得伪造明细。evidence 超过
   32 KiB 时拒绝；records、cursor 和 checkpoint 也分别受 10,000 条/1 MiB、32 KiB、256 KiB
   上界。所有通道在持久化前递归脱敏，列表只暴露 checkpoint/cursor 摘要。
3. 未声明能力、未知版本、非法配置、重复运行和不允许状态迁移必须失败关闭。
4. 上游异常映射到 configuration/authentication/permission/rate_limit/timeout/upstream/
   contract/cancelled 稳定类别，响应不携带驱动原始错误。
5. capability 必须与实际行为一致；未实现的方法不得写入 manifest。使用通用兼容套件验证已声明
   方法、幂等、重试、取消、恢复、脱敏和注册零核心修改。
6. 普通 connector operation 的 `OperationResult.status` 只能是 `succeeded`；不得返回 running、failed
   或 cancelled 让 runtime 写入悬挂状态。dry-run 状态由 runtime 产生。

受控 REST Catalog 是参考实现。生产 transport 必须使用首次验证的公共 IP 建立连接，同时保留
原始 host 用于 TLS SNI、证书 hostname 与 Host 校验；不得跟随重定向，也不得在 DNS 重解析后
更换目标。响应必须流式限长；秘密解析器只能将解析值送入 Authorization，不得写入配置或证据。
默认环境解析器仅接受 `env:DATAOPS_CONNECTOR_*`；`vault:` 和 `secret:` 必须在部署方显式注入
后端解析器，否则稳定失败关闭。

人工管理接口仅用于显式 dry-run；execute/resume 均不得调用真实 operation、secret resolver 或 I/O。
真实非 dry-run 采集必须使用 connector principal 的一次性
短期凭证，并同时匹配 connector/version/source/business-domain/environment、操作及资源 scope。
execute 与 resume 共用单个运行的五次总 attempt 上限；resume 失败必须落回 failed 并保留原
checkpoint，不能停留在 resumable。持久化适配器的状态更新必须返回显式 CAS ownership 结果；
每次 attempt 使用不可复用 lease token，只有 exact attempt + lease 的 `acquired=true` 调用方可提交
终态。竞争失败方必须返回冲突或 already-running，
不得把“读取到当前行”解释成已获得运行权，也不得追加重复 attempt。

取消是协作式协议：先持久化运行取消标志，再由连接器在 I/O 边界探测；最长响应时间受数据库驱动
query timeout 与 REST read timeout 限制。不要用 connector 实例的 source 级内存标志，否则会把
同一来源的其他运行误取消。REST 分页还必须拒绝重复/倒退 cursor，并设置页数和总记录数上界。

SQL Server 连接默认启用加密并验证服务器证书。可信 environment 必须从已认证 source binding 传给
连接管理器，禁止在 `tls_options` 中自报 development。staging/production 不允许
`TrustServerCertificate=yes` 或 `Encrypt=no`；development 例外必须显式声明，仅用于本地验证并留警告。