| name | standard-providers |
| description | Use when changing retikz providers layer code, builtin definitions, registry resolvers, BUILTIN_* collections, reserved or removed keys, custom definition merging, provider diagnostics, or implementation of contract capabilities. |
Standard Providers
providers/ 是契约实现层：实现内置 definition，合并用户 definition，并向 pipeline / compile 提供可消费的 registry。它可以依赖 shared、schemas、contract，不依赖 pipeline / compile。
职责
- 提供内置 definition、内置集合和默认 provider。
- 合并内置与用户 definition。
- 诊断重复 key、内置冲突、保留名、已移除名。
- 暴露 registry resolver 和按 key 查询 helper。
不要让消费侧复制内置白名单；不要把用户 definition 放到与内置不同的旁路逻辑。
组织与命名
| 形态 | 规则 |
|---|
providers/<capability>/definitions.ts | 内置 definition 集合，或组装各内置项 |
providers/<capability>/registry.ts | resolveXxxRegistry()、索引 map、重复 key / 保留名诊断 |
providers/<capability>/<builtin>.ts | 复杂内置项的单独实现 |
BUILTIN_XXXS | 内置 definition 数组或集合 |
BUILTIN_XXX_DEFINITIONS_BY_<KEY> | 按真实 discriminator 建索引 map |
RESERVED_XXX_<KEYS> / REMOVED_XXX_<KEYS> | 保留名和已移除名诊断依据 |
xxxDefinitionOf() | 按 key 查询 definition |
<KEY> 后缀必须匹配真实 discriminator，不要 kind / name 混用。
Registry 合并
- 内置先注册，用户 definition 后注册。
- 用户可使用自定义 key；覆盖内置 key 只有在明确设计为 override 时允许。
- 重复用户 key fail-loud，不静默 last-wins。
- fallback 是 resolver / lookup 策略，不是消费侧旁路。
- resolver 返回的结构应让 pipeline / compile 只消费解析结果。
内置实现
- 内置项也通过
defineXxx() 或同等 contract 入口创建。
- 名称、kind、type 使用 schema / shared vocabulary 成员，不写裸字符串。
- 内置 helper 若有可扩展配置项，使用
options 对象承载；不要把第三个及之后的位置参数作为未来扩展槽。
- helper 默认留在 provider 内部；跨层复用时再抽到
shared。
改代码前检查
- 内置和用户 definition 是否同路注册、解析、消费？
- key 冲突、保留名和已移除名诊断是否集中在 resolver？
- pipeline / compile 是否只消费 resolver 输出？
- 内置集合是否在
definitions.ts 组装，registry.ts 是否只负责 resolver？
BUILTIN_* 数组里是否只放命名 definition，不直接内联长对象？- 新增内置项是否补了索引、默认值、测试和必要文档？
