fix(phase-2): B51-R1 收口——failure_category 落库+写点全接线+双读按文案优先

判死/重试/重开原先只读 biz_file_task.error_message 里的中文子串决定:改一句用户看得见的
文案=静默改一次整单生死,而且改的人不会知道。V186 补 failure_category(可空、存量不回填),
TaskFailureLedger 作为唯一写入口把「那次判断的结果」与文案同笔落库——词汇表仍只有
TaskRetryEligibility 一处,ledger 不抄第二份 markers(B52 那族的复发形状)。

- wrapper 面 22 处写点全部同笔派生写列;实体面接线第二批(外观专利 4/相似ASIN 4/采集 1),
  正是 DELIVERY/BALANCE 那几族被判死消费的文案
- 读侧 category(task) 取「文案判得出按文案、判不出才按列」:名单外的实体写点改文案带不动列,
  无条件读列=让一列陈旧判决判死当前这一单,那是本笔自己引入的漂移,比它要修的 bug 更糟
- FileTaskEntity.failureCategory 标 @TableField(updateStrategy = ALWAYS):updateById 默认跳过
  null 字段,「清错误」的分支会留下陈旧列;让 null 真落库,最坏只退回文案判定=加列前的今天
- 判据:TaskFailureCategoryGuardrailTest(5)+TaskFailureCategoryMigrationV186Test(5),已反向验证
  「删任一处配对即红」;SourceScanTest 台账裸名 24→25、调用方 17→18
- 门禁:mvn -o test 整量 5267/0 失败/0 错误/19 skipped;_push_gate.py full overall=pass

Contract 阶段(收 contains(<中文>) 判定)按蓝图登记留到读侧全切之后,本轮不动。
This commit is contained in:
2026-11-03 12:49:45 +08:00
parent 34f730d403
commit 51401de2d5
22 changed files with 588 additions and 12 deletions
@@ -0,0 +1,116 @@
package com.nanri.aiimage.config;
import com.baomidou.mybatisplus.annotation.FieldStrategy;
import com.baomidou.mybatisplus.annotation.TableField;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.modules.task.service.TaskRetryEligibility;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* V186 给 {@code biz_file_task} 补 {@code failure_category} 列,本类钉它的形状(B51-R1 Expand 半边)。
*
* <p>立账出处是蓝图 {@code docs/REFACTOR_PLAN.md} §3.1 与 SLIMMING 报告的 B51:重试/重开/判死
* 原先全靠读 {@code error_message} 的中文子串决定,改一句用户看得见的文案就静默改一次整单生死。
* 这一列把「那次判断的结果」记下来,读侧从此有列读列。
*
* <p>三件事各守一个炸法:
* <ol>
* <li><b>必须可空且不回填</b>:存量行与尚未接 {@code TaskFailureLedger} 的实体式写入面都是 NULL,
* 读侧按「无列则回落文案」处理。加 {@code NOT NULL} 或 {@code DEFAULT ''} 会让存量行在
* 迁移那一刻集体变成一种新状态;写一条 {@code UPDATE} 回填更是把「分类」变成
* 「按今天的文案重判一遍历史」——历史行的判定不该被后来的词汇表改动。</li>
* <li><b>值域不另起炉灶</b>:列宽必须容得下 {@code TaskRetryEligibility.Category} 的全部枚举名,
* 且 SQL 里点名的出处就是那一处(否则 B52 那族「词汇表多正本」在这里重生)。</li>
* <li><b>列名与实体字段对齐</b>:MyBatis-Plus 靠驼峰↔下划线映射,列名与字段名对不上时
* 写入会静默不落库(列存在但恒为 NULL,读侧永远回落,等于白加)。</li>
* </ol>
*/
class TaskFailureCategoryMigrationV186Test {
private static final Path SQL = Path.of(System.getProperty("user.dir"),
"src/main/resources/db/V186__task_failure_category.sql");
private static String sql() throws IOException {
assertTrue(Files.exists(SQL), "V186 迁移脚本不在:" + SQL);
return Files.readString(SQL);
}
@Test
void 列是biz_file_task上的可空窄列且紧跟error_message() throws IOException {
String text = sql();
assertTrue(text.contains("ALTER TABLE `biz_file_task`"), "迁移对象必须是 biz_file_task");
assertTrue(text.contains("ADD COLUMN `failure_category` VARCHAR(16) NULL"),
"必须是可空窄列:NOT NULL/DEFAULT 都会让存量行集体变成一种新状态");
assertTrue(text.contains("AFTER `error_message`"),
"紧跟 error_message:这两列是一件事的记账与文案,读的人要能一眼成对");
assertFalse(text.toUpperCase().contains("UPDATE `BIZ_FILE_TASK`"),
"Expand 阶段不回填:历史行的判定不能按今天的词汇表重判一遍");
assertTrue(text.contains("DROP COLUMN `failure_category`"),
"回滚语句必须写在脚本注释里(与 V183 同一口径)");
}
@Test
void 头注释版本号与文件名一致() throws IOException {
String first = sql().lines().findFirst().orElse("");
assertTrue(first.startsWith("-- V186:"), "头注释必须写 V186,实际是:" + first);
}
@Test
void 列宽容得下词汇表的每一个枚举名() throws IOException {
String text = sql();
int width = Integer.parseInt(text.replaceAll("(?s).*`failure_category` VARCHAR\\((\\d+)\\).*", "$1"));
int longest = 0;
for (TaskRetryEligibility.Category category : TaskRetryEligibility.Category.values()) {
longest = Math.max(longest, category.name().length());
}
assertTrue(width >= longest,
"列宽 " + width + " 装不下最长的枚举名(" + longest + " 字符)⇒ 写入会被截断或报错");
assertTrue(text.contains("TaskRetryEligibility.Category"),
"SQL 注释必须点明值域出处就是那一处词汇表,不许另造一套");
}
/** 列名与实体字段对不上时 MyBatis-Plus 会静默不落库:这一格把两者绑死。 */
@Test
void 实体字段与列名按驼峰下划线一一对应() throws Exception {
assertNotNull(FileTaskEntity.class.getDeclaredField("failureCategory"),
"实体缺 failureCategory 字段 ⇒ 列永远不会被写");
assertEquals("failure_category", camelToSnake("failureCategory"));
assertTrue(sql().contains("`failure_category`"));
}
/**
* {@code updateStrategy=ALWAYS} 是名单外实体式写面的兜底:默认策略跳过 null 字段,
* 于是「partial entity 更新」会把这一列留在旧值上——陈旧的一列比没有列更危险(它会让一单
* 被上一次失败的原因判死)。让 null 真的落库,最坏只是退回文案判定,逐字等于加列之前的今天。
*/
@Test
void 实体字段必须让_null_真的落库() throws Exception {
TableField field = FileTaskEntity.class.getDeclaredField("failureCategory")
.getAnnotation(TableField.class);
assertNotNull(field, "failureCategory 没标 @TableField ⇒ updateById 会跳过 null,清错误的分支带不动列");
assertEquals(FieldStrategy.ALWAYS, field.updateStrategy(),
"updateStrategy 不是 ALWAYS ⇒ 实体式更新留下陈旧分类");
}
private static String camelToSnake(String name) {
StringBuilder out = new StringBuilder();
for (char c : name.toCharArray()) {
if (Character.isUpperCase(c)) {
out.append('_').append(Character.toLowerCase(c));
} else {
out.append(c);
}
}
return out.toString();
}
}
@@ -0,0 +1,248 @@
package com.nanri.aiimage.modules.task.service;
import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
import com.nanri.aiimage.testutil.SourceScan;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;
import static org.assertj.core.api.Assertions.assertThat;
/**
* 失败分类列的写入面与读侧面判据(B51-R1,Expand 半边)。
*
* <p><b>为什么打在源码上而不是四份单测夹具</b>:这一格要守的是「写了文案就必须同笔写列」这条
* <em>连线</em>。用 mock 造一枚任务实体测一遍分类,改天新增一处 {@code setErrorMessage} 而忘了
* 写列,那份单测照样全绿——而这正是"改一句文案静默改判死"的复发路径。
*
* <p>四件事各守一个方向:
* <ol>
* <li>每一处任务失败文案的 wrapper 写点,下一行必须同笔写 {@code failure_category}
* (把任一处配对删掉 ⇒ 本类红);</li>
* <li>已接线的<b>实体式</b>写面({@code task.setErrorMessage + updateById},名单见
* {@code ENTITY_FACE_FILES})必须同笔经 {@link TaskFailureLedger} 派生写列——
* 这批写的正是判死/重试消费的那几族文案,漏列=读侧对这一行永远退回中文子串;</li>
* <li>列的值只能由 {@link TaskFailureLedger} 从 {@link TaskRetryEligibility} 推导,
* ledger 自己不许再抄一份中文 markers(否则 B52 那族「词汇表多正本」在这里重生);</li>
* <li>读侧「文案判得出按文案、判不出按列」:措辞漂移时列把判决钉在原处,列不在必须逐字退回
* 原判据,存量行为一字不变;列与文案背离(名单外的实体式写点)时按文案——陈旧列不许判死。</li>
* </ol>
*/
class TaskFailureCategoryGuardrailTest {
private static final String MESSAGE_SET = ".set(FileTaskEntity::getErrorMessage, ";
private static final String CATEGORY_SET = ".set(FileTaskEntity::getFailureCategory, ";
/** 现网在册写点的下限:低于这个数说明扫描面或写法变了,而不是"违规被修完了"。 */
private static final int MIN_WRITE_SITES = 20;
/** 实体式写面的接线名单(第二批):只有列在这里的文件受 {@code 已接线的实体式任务写点...} 那格管。 */
private static final List<String> ENTITY_FACE_FILES = List.of(
"AppearancePatentResultJobSupport.java",
"SimilarAsinTaskService.java",
"CollectDataService.java");
/** 名单内在册写点数(AP 4 +相似ASIN 4 +采集 1);低于它=写点被挪走或改了写法。 */
private static final int ENTITY_FACE_MIN_WRITE_SITES = 9;
@Test
void 任务失败文案写点必须同笔写分类列() {
List<String> violations = new ArrayList<>();
int sites = 0;
for (Path file : mainJavaFiles()) {
List<String> lines = readLines(file);
for (int i = 0; i < lines.size(); i++) {
String line = lines.get(i);
if (!line.contains(MESSAGE_SET) || isComment(line)) {
continue;
}
sites++;
String paired = i + 1 < lines.size() ? lines.get(i + 1) : "";
String self = line.contains(CATEGORY_SET) ? line : paired;
if (!self.contains(CATEGORY_SET)) {
violations.add(file.getFileName() + ":" + (i + 1) + " 只写了文案没写列");
} else if (!pairingIsForSameMessage(line, paired)) {
violations.add(file.getFileName() + ":" + (i + 1) + " 写的列与文案不是同一个来源");
}
}
}
assertThat(violations)
.as("biz_file_task.error_message 的每一处落库都必须把 TaskRetryEligibility 的判定结果一起记下来"
+ "(B51-R1:否则读侧永远只能靠中文子串猜当时判了什么)")
.isEmpty();
assertThat(sites)
.as("扫到的写点数低于下限=扫描面或写法变了,不是违规清零了")
.isGreaterThanOrEqualTo(MIN_WRITE_SITES);
}
/**
* 实体式写面({@code task.setErrorMessage(...)} + {@code updateById})第二批接线。
*
* <p>这三面写出的正是判死/重试真正消费的那些文案(DELIVERY/BALANCE 家族:结果文件多次生成
* 失败、LLM 上游欠费)。它们不走 wrapper,上面那格扫不到;漏写列的后果不是崩,而是读侧对这一行
* <b>永远</b>退回中文子串——加了一列却没买到任何免疫力,这正是 B51 的病灶形状。
*
* <p>名单之外(其它实体的 {@code setErrorMessage}、以及尚未接线的 {@code FileTaskEntity} 写面)
* 本格不管:按面分批收是 {@code docs/REFACTOR_PLAN.md} §5 登记的口径,Contract 阶段前逐批加进来。
*/
@Test
void 已接线的实体式任务写点必须同笔派生写列() {
List<String> violations = new ArrayList<>();
int sites = 0;
for (Path file : mainJavaFiles()) {
if (!ENTITY_FACE_FILES.contains(file.getFileName().toString())) {
continue;
}
List<String> lines = readLines(file);
for (int i = 0; i < lines.size(); i++) {
String line = lines.get(i).trim();
if (isComment(line) || !line.startsWith("task.setErrorMessage(")) {
continue;
}
sites++;
String paired = i + 1 < lines.size() ? lines.get(i + 1).trim() : "";
if (!paired.startsWith("task.setFailureCategory(TaskFailureLedger.categoryOf(")) {
violations.add(file.getFileName() + ":" + (i + 1) + " 只写了文案没同笔派生写列");
}
}
}
assertThat(violations)
.as("名单内的任务实体写点必须经 TaskFailureLedger 把分类一起落库(把配对删掉即红)")
.isEmpty();
assertThat(sites)
.as("三面在册写点数低于下限=写法变了或写点被挪走,不是违规清零了")
.isGreaterThanOrEqualTo(ENTITY_FACE_MIN_WRITE_SITES);
}
@Test
void 分类值只能由词汇表那一处推导_ledger不得再抄一份markers() {
String ledger = SourceScan.withoutComments(SourceScan.sourceText("TaskFailureLedger.java"));
assertThat(ledger)
.as("ledger 必须把判定委托给 TaskRetryEligibility,不自己判")
.contains("TaskRetryEligibility.forceMajeureCategory");
assertThat(ledger)
.as("ledger 里出现 contains( =抄了第二份中文 markers 正本,B52 那族的复发形状")
.doesNotContain(".contains(");
}
@Test
void 列登记过就读列_没登记就逐字退回文案判定() {
FileTaskEntity task = new FileTaskEntity();
// ① 列在、文案已漂移 ⇒ 以列为准:这就是本列存在的意义
task.setFailureCategory(TaskRetryEligibility.Category.BALANCE.name());
task.setErrorMessage("上游提示已更新,不再含任何已知字样");
assertThat(TaskRetryEligibility.category(task))
.as("文案判不出时以登记列为准——判死不随措辞漂移")
.isEqualTo(TaskRetryEligibility.Category.BALANCE);
// ② 列没登记(存量行 / 尚未接 ledger 的实体式写入面)⇒ 逐字回落到今天的口径
task.setFailureCategory(null);
task.setErrorMessage("LLM 服务余额欠费(上游账户额度不足,非本行数据问题)");
assertThat(TaskRetryEligibility.category(task))
.as("空列不等于「无类别」,必须回落到文案判定")
.isEqualTo(TaskRetryEligibility.Category.BALANCE);
// ③ 列里是不认识的值(脏数据 / 将来改名)⇒ 同样回落,且不得抛
task.setFailureCategory("BALANCE_BUT_TYPO");
task.setErrorMessage("任务心跳超时,已自动失败");
assertThat(TaskRetryEligibility.category(task))
.as("不可识别的分类名按未登记处理:读侧不许因为一列脏值把判定改成「无可重试」")
.isNull();
// ④ 列与文案都判得出、却不同类 ⇒ 列是<b>陈旧</b>的(实体式 setErrorMessage 改文案带不动列,
// 这批写点本轮未接 ledger)。读文案=逐字等于加列之前的今天;读列就是本笔自己引入的漂移。
task.setFailureCategory(TaskRetryEligibility.Category.BALANCE.name());
task.setErrorMessage("已收到 73 个结果分片,但结果文件生成多次失败,任务已自动结束");
assertThat(TaskRetryEligibility.category(task))
.as("背离时按文案:陈旧的一列不许判死这一单")
.isEqualTo(TaskRetryEligibility.Category.DELIVERY);
}
@Test
void 空列与脏列都不许被读成一种新状态() {
assertThat(TaskRetryEligibility.categoryByName(null)).isNull();
assertThat(TaskRetryEligibility.categoryByName(" ")).isNull();
assertThat(TaskRetryEligibility.categoryByName("UNKNOWN")).isNull();
assertThat(TaskRetryEligibility.categoryByName(" balance ")).isNull();
// 逐值比对要认得住合法值(大小写敏感:写侧落的是 name())
assertThat(TaskRetryEligibility.categoryByName("STOPPED"))
.isEqualTo(TaskRetryEligibility.Category.STOPPED);
assertThat(TaskRetryEligibility.category(null)).isNull();
}
/** 配对行必须引用同一个表达式来源,防止「写了列但写的是另一句文案的分类」。 */
private static boolean pairingIsForSameMessage(String messageLine, String categoryLine) {
String messageExpr = expressionOf(messageLine, MESSAGE_SET);
String categoryExpr = expressionOf(categoryLine, CATEGORY_SET);
if (messageExpr == null || categoryExpr == null) {
return false;
}
if (isNullish(messageExpr) || isNullish(categoryExpr)) {
// 清错误的那一侧同时清列:两边都空才是配对的
return isNullish(messageExpr) && isNullish(categoryExpr);
}
return categoryExpr.contains(messageExpr) || messageExpr.contains(categoryExpr);
}
private static String expressionOf(String line, String marker) {
if (line == null) {
return null;
}
int idx = line.indexOf(marker);
if (idx < 0 || isComment(line)) {
return null;
}
String tail = line.substring(idx + marker.length());
// 从 .set( 的下一位开始配平:深度回到 0 的那个 ')' 才是本 set(...) 的闭括号,
// 链尾还挂着 update(...) 的闭括号与分号,不能按"最后一个右括号"倒推(那会把
// `null));` 切成 `null)`,读成"不是 null")。
int depth = 1;
for (int i = 0; i < tail.length(); i++) {
char c = tail.charAt(i);
if (c == '(') {
depth++;
} else if (c == ')') {
depth--;
if (depth == 0) {
return tail.substring(0, i).trim();
}
}
}
return null;
}
private static boolean isNullish(String expression) {
return "null".equals(expression) || expression.isBlank();
}
private static boolean isComment(String line) {
String stripped = line.trim();
return stripped.startsWith("//") || stripped.startsWith("*") || stripped.startsWith("/*");
}
private static List<Path> mainJavaFiles() {
Path root = SourceScan.mainSourcesRoot();
try (Stream<Path> stream = Files.walk(root)) {
return new ArrayList<>(stream.filter(p -> p.toString().endsWith(".java"))
.collect(java.util.stream.Collectors.toList()));
} catch (IOException ex) {
throw new UncheckedIOException("扫描面读不到:" + root, ex);
}
}
private static List<String> readLines(Path file) {
try {
return Files.readAllLines(file);
} catch (IOException ex) {
throw new UncheckedIOException(ex);
}
}
}
@@ -151,4 +151,40 @@ class TaskRetryEligibilityMarkersSnapshotTest {
.as("只有 BusinessException 才算业务判据,运行时异常必须走正常失败重试")
.isFalse();
}
/**
* 2026-11-03 Phase 2 ⑤(B51-R1)——<b>更新即登记</b>,不是静默改绿。
*
* <p>六组 markers 本体一字未改(上面那几格仍是正本),但读侧多了一层:<b>任务行上登记过
* {@code failure_category} 就以列为准,没登记才回落到这些 markers</b>。这一格把"切换是渐进的"
* 写死——Expand 阶段存量行与未接 ledger 的写入面列都是 NULL,回落必须逐字等于今天的判定,
* 否则加一列就把历史任务的续跑口径整体改掉。
*
* <p>仍留在文案判定上的三处是<b>边界</b>不是漏网,后续 Contract 阶段也不该顺手"切列":
* {@code TaskResultFileJobWorker#isOrphanJobFailure} 判的是查库抛回来的异常文本
* ("任务不存在"/"task not found"),不是任务失败原因,{@code Category} 值域里也没有这一类;
* {@code AppearancePatentResultJobSupport#isFatalLlmArrearsFailure} 与
* {@code SimilarAsinTaskService#terminalizeOnFatalLlmFailure} 判的是<b>刚生成、尚未落库</b>的
* 消息,那一刻列还不存在。
*/
@Test
void 列登记后判定不随文案漂移_未登记则逐字回落() {
com.nanri.aiimage.modules.task.model.entity.FileTaskEntity task =
new com.nanri.aiimage.modules.task.model.entity.FileTaskEntity();
task.setFailureCategory(TaskRetryEligibility.Category.SERVICE_DOWN.name());
task.setErrorMessage("这句文案后来被改成了任何人话");
assertThat(TaskRetryEligibility.category(task))
.as("列登记过就以列为准:这正是本列存在的唯一理由")
.isEqualTo(TaskRetryEligibility.Category.SERVICE_DOWN);
task.setFailureCategory(null);
for (String marker : List.of("余额不足", "密钥无效", "服务不可用", "aiprice 未登录",
"结果文件生成多次失败", "卡死重排")) {
task.setErrorMessage(marker);
assertThat(TaskRetryEligibility.category(task))
.as("列不在时必须逐字退回 markers 判定:" + marker)
.isEqualTo(TaskRetryEligibility.forceMajeureCategory(marker));
}
}
}
@@ -39,7 +39,7 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
* 那条数是 {@code grep -rl 'sourceText('} 数出来的,而第 9 支是 {@code SourceScan.java:22} 里
* {@code public static String sourceText(String fileName)} 这行<b>被调方自己的声明</b>——它不是调用点。
* 所以真实形状是 <b>调用点/调用方/引用方三类数各自成立</b>(2026-10-28 v1.1 Phase 0 起调用方 16 支、
* 裸名 24 个,增量逐笔登记在 {@code REGISTERED_BARE_NAMES} 的注释里)。下面第 3 格把这些数同时钉住,
* 裸名 25 个,增量逐笔登记在 {@code REGISTERED_BARE_NAMES} 的注释里)。下面第 3 格把这些数同时钉住,
* 免得下一个人拿 {@code grep} 再数一遍又把声明算进去。</p>
*/
class SourceScanTest {
@@ -89,7 +89,12 @@ class SourceScanTest {
// 因此能算出两个归属。回落口径合并成 TaskOwnerJsonFallback 一处之后,判据只能打在
// "那一处确实按 result_json → request_json 的顺序读"这条源码连线上——mock 造不出
// "谁先谁后",四份夹具各测一遍照样全绿。
"TaskOwnerJsonFallback.java");
"TaskOwnerJsonFallback.java",
// —— 2026-11-03 Phase 2 ⑤(B51-R1 failure_category)追加(1 名)——
// TaskFailureCategoryGuardrailTest 要钉「写了失败文案就必须同笔写分类列」这条连线:
// 用 mock 造任务实体测分类,挡不住"新增一处 setErrorMessage 忘了写列"——
// 那正是"改一句文案静默改判死"的复发路径,只能打在源码上。顺带钉 ledger 不抄第二份 markers。
"TaskFailureLedger.java");
@TempDir
Path tmp;
@@ -105,7 +110,7 @@ class SourceScanTest {
}
@Test
void census_唯一裸名恰为24且与已登记集合相等() {
void census_唯一裸名恰为25且与已登记集合相等() {
Set<String> found = SourceScan.censusSourceTextCallSites().stream()
.map(SourceScan.CallSite::bareName)
.collect(Collectors.toSet());
@@ -113,11 +118,11 @@ class SourceScanTest {
assertThat(found)
.as("唯一裸名集合必须与类头台账逐字相等——多一个说明有人新引了单文件口径,少一个说明尺子漏扫")
.isEqualTo(REGISTERED_BARE_NAMES)
.hasSize(24);
.hasSize(25);
}
@Test
void census_调用方文件恰为17而声明件在外() {
void census_调用方文件恰为18而声明件在外() {
List<SourceScan.CallSite> sites = SourceScan.censusSourceTextCallSites();
Set<String> callerFiles = sites.stream()
.map(SourceScan.CallSite::relativeFile)
@@ -126,9 +131,9 @@ class SourceScanTest {
String declarationFile = "src/test/java/com/nanri/aiimage/testutil/SourceScan.java";
assertThat(callerFiles)
.as("真实字面量调用点落在 17 支调用方文件里(8 支既有 + 2026-10-28 v1.1 Phase 0 预置契约 8 支"
+ " + 2026-11-02 归属死锁绊线 1 支)")
.hasSize(17);
.as("真实字面量调用点落在 18 支调用方文件里(8 支既有 + 2026-10-28 v1.1 Phase 0 预置契约 8 支"
+ " + 2026-11-02 归属死锁绊线 1 支 + 2026-11-03 B51-R1 双写绊线 1 支)")
.hasSize(18);
assertThat(callerFiles)
.as("plan 原文记的「9 支」= grep -rl 'sourceText(' 的条数,第 9 支是被调方自己的声明行"
+ "(SourceScan.java:22 的 `public static String sourceText(String fileName)`),"