# breakpoint-candidates（子模块规范）

## 子模块名称

breakpoint-candidates（候选断点生成与裁剪）

## 目标描述

基于 token 序列生成“可控规模、确定性排序”的候选断点集合（breakpoints），并应用去重、排序与约束过滤，确保后续搜索器复杂度可控且跨端一致。

本模块输出的是“断点候选集合”，不负责“组合搜索选最优”。

## 输入/输出定义

### 输入

- `tokens: Token[]`
- `lang: 'TC' | 'EN'`
- `maxLines: number`
- `constraints?: { protectedPhrases?: string[]; forbiddenBreakRanges?: Array<{ start: number; end: number }> }`
- `config: { tcMaxCandidateBreaks: number; tcPunctuations: string[]; balanceRange: number }`

### 输出

- `breakpoints: Array<{ pos: number; kind: 'PUNCT' | 'SPACE' | 'BALANCE' | 'OTHER'; priority: number }>`
  - **pos**：token 边界索引（0..N）
  - **排序**：按 `pos` 升序（最终输出必须确定性）
- `meta?: { pruned: boolean; originalCount: number; finalCount: number }`

## 验收标准（可验证）

- **EN 口径**：
  - tokens 仅为 WORD（不生成 SPACE token），断点仅存在于词间
  - 每个词边界产生 `kind=SPACE` 的候选断点（按配置可做裁剪，但必须确定性）
- **TC 口径**：
  - 标点后断点 `kind=PUNCT` 优先级最高
  - 空格后断点 `kind=SPACE` 次之
  - BALANCE 断点：围绕理想切分点附近生成少量断点（允许落在短语 span 内，是否可用交给评分惩罚）
- **去重/排序/过滤确定性**：
  - 同一 `pos` 多来源断点：保留 priority 更高者
  - 输出按 `pos` 升序
  - `forbiddenBreakRanges` 命中者必定被剔除
- **规模上限生效**：
  - TC 输出候选断点数不超过 `tcMaxCandidateBreaks`
  - 截断策略确定性（按 priority + 距离理想位置等固定规则）

## 依赖与关联

- **依赖**：`core-contract`（token 与索引语义）、`grapheme-segmentation`（TC tokens）
- **被依赖**：`search-engine-app`、`search-engine-widget`