# core-contract（子模块规范）

## 子模块名称

core-contract（核心口径与契约）

## 目标描述

定义并固化跨端一致的“基础口径”，为后续断点生成、搜索与评分提供统一契约，避免实现偏差：

- **索引体系**：EN/TC 的 token 与断点 `pos` 语义
- **文本重组**：从 token 区间稳定重组回行文本
- **规范化**：空白归一化策略（默认折叠空白、去首尾）
- **EN 关键词命中规则**：全词等值匹配（`lowercase → strip 两端常见标点 → 等值比较`），禁止 substring/contains
- **配置与版本**：`configVersion` 的语义与回溯字段；全端一致的默认值入口
- **确定性比较**：layout tie-break 的字典序比较口径（作为后续模块复用工具）

本模块不负责“换行搜索”，只负责**定义数据结构与基础函数**。

## 输入/输出定义

### 输入

- `text: string`
- `lang: 'TC' | 'EN'`
- `options?: { preserveRawSeparators?: boolean }`
- `config: { punctuationStripSetEN: string[]; whitespacePolicy: 'NORMALIZE' | 'PRESERVE' }`

### 输出

- `normalizedText: string`
- `tokens: Array<{ text: string; start: number; end: number }>`
  - EN：token 仅为 WORD（不产生 SPACE token；标点视为词内字符）
  - TC：token 为 grapheme cluster（具体分割由 `grapheme-segmentation` 模块实现/提供）
- `rawSeparators?: string[]`
  - 可选：当选择保留原始空白时，输出 token 间分隔符映射
- 基础工具函数（逻辑输出）：
  - `joinTokens(start, end) -> string`
  - `normalizeENKeyword(tokenText) -> string`
  - `matchENKeyword(tokenText, keyword) -> boolean`

## 验收标准（可验证）

- **索引语义一致**：
  - EN：`"I am so tired"` tokens=`[I, am, so, tired]`，断点 `pos=2` 必然切为 `"I am"` / `"so tired"`
  - TC：断点 `pos` 表示在第 `pos` 个 grapheme 之前断开
- **EN 标点极简派一致**：
  - `"tired."` 作为一个 token；断点只允许在词与词之间
- **EN 关键词命中无误伤**：
  - keyword=`"but"`：`"but,"` 命中；`"rebuttal"` 不命中
- **空白归一化确定性**：
  - 输入含多空格/首尾空白时，输出 `normalizedText` 可预测且稳定
- **工具函数确定性**：相同输入在多次调用与多端实现中输出一致

## 依赖与关联

- **被依赖**：`breakpoint-candidates`、`scoring-tiebreak`、`search-engine-*`、`overflow-fallback`、`integration`
- **依赖**：TC token 分割依赖 `grapheme-segmentation`