@hcmai/sdk 0.3.17 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -2127,6 +2127,83 @@ declare class ReconLayout {
2127
2127
  readJsonlRows(rel: string): unknown[];
2128
2128
  readJson(rel: string): unknown;
2129
2129
  }
2130
+ /**
2131
+ * `init` 侧 work 目录的落盘收口点:`<work>/<rel>`。
2132
+ *
2133
+ * 🔴 **为什么不复用 {@link ReconLayout}**:那个类的目录是**算**出来的
2134
+ * (`<root>/recon/<租户>/<sourceKey>`,按爬取身份分叉),而 work 目录是顾问自己给的
2135
+ * 一个平铺目录 —— 硬塞进去要么伪造一个租户段,要么把 `dir` 改成可覆写,
2136
+ * 两条都会削弱那个类正在守的东西。
2137
+ *
2138
+ * 🔴 **为什么不让 `seed/plan-io.ts` 自己 `writeFileSync`**:`fde-layout-writer-containment`
2139
+ * 那条守卫要求 `src/fde/**` 的落盘全部收口在本文件。它守的不是「遏制函数对不对」,
2140
+ * 而是「**每一个写文件的入口都真的调了它**」—— 绕过去一个,产物就能被静默顶掉。
2141
+ * ⚠️ 就本模块当下的用法而言,两道闸确实拦不到东西(`rel` 是模块常量,没有调用方可控的
2142
+ * 分量)。收口的价值不在这一次调用,在于**下一个人往 work 目录里写按 modelKey 拼的路径时
2143
+ * 闸已经在那儿了** —— 那时再补就晚了。
2144
+ */
2145
+ declare class WorkLayout {
2146
+ readonly dir: string;
2147
+ constructor(dir: string);
2148
+ /** 与 {@link ReconLayout.resolvePath} 同样的两道闸,理由见那里。 */
2149
+ resolvePath(rel: string, createParents?: boolean): string;
2150
+ /** 写一份 JSON 产物。中文逐字落盘(本地 grep 才找得到),末尾带换行。 */
2151
+ writeJson(rel: string, obj: unknown): string;
2152
+ /**
2153
+ * 往一份产物**追加一行**(末尾补换行)。→ 落盘路径。
2154
+ *
2155
+ * 🔴 台账(`journal.jsonl`)是 append-only 的:整份重写的话,崩在中途会把
2156
+ * **已经落好的全部**记录一起赔进去;而追加一行崩在半行上,下一次读会**响亮地**
2157
+ * 报出坏行,不会静默少一行 —— 少的那几行恰恰会被重放成重复行。
2158
+ *
2159
+ * `sync`:
2160
+ * - `false` = 只 flush(字节交给内核)⇒ 进程被 `kill -9` 丢不了;
2161
+ * - `true` = 再 `fsync` 一次 ⇒ **机器掉电**也丢不了,但**只对文件内容成立**。
2162
+ * 🔴 说准一格:**第一次追加会创建这个文件**,而目录项的落盘要 fsync **目录**,
2163
+ * 本方法没做 ⇒ 掉电后**文件本身**可能不存在。没补的理由:目录 fsync 在 Windows 上
2164
+ * 不可用、且无从写出可信的用例;而 `kill -9` 这个现实中的主要形态由 flush 完整覆盖。
2165
+ * 两者都挡不住介质损坏。
2166
+ *
2167
+ * ⚠️ `sync` 由调用方给,**不在这里按行的内容判**:什么行值得多买一次 fsync
2168
+ * 是调用方的语义,落盘路径只有这一条。
2169
+ */
2170
+ appendLine(rel: string, line: string, sync?: boolean): string;
2171
+ /**
2172
+ * **原子地**创建一份**内容已完整**的产物;已存在则抛(`code === 'EEXIST'`)。
2173
+ *
2174
+ * 🔴 为什么不是「先建空文件再写内容」:那两步之间崩一下会留下一份 **0 字节**产物,
2175
+ * 而 0 字节读不出内容 ⇒ 走 fail-closed 分支 ⇒ 对租约来说,
2176
+ * **心跳超时对它永远无效,只能人工删** —— 「120 秒后自动恢复」的局面被换成了
2177
+ * 「必须有人到场」的局面。
2178
+ * 用「写完整临时文件 + 硬链接」让产物**一出现就是完整的**,这个窗口从此不存在
2179
+ * (不是变小):崩在写 tmp 期间 ⇒ 根本没有产物;崩在 link 之后 ⇒ 产物完整。
2180
+ *
2181
+ * ⚠️ 硬链接的原子性在**本地 POSIX 文件系统**上成立;网络文件系统上**没有量过**。
2182
+ * ⚠️ FAT / exFAT / 部分 SMB **不支持硬链接**,那里会抛 `EPERM` / `ENOTSUP` ——
2183
+ * 调用方要把它翻成人话,别让顾问拿到一个裸的 fs 错误。
2184
+ */
2185
+ createExclusive(rel: string, text: string): string;
2186
+ /**
2187
+ * 先写同目录临时文件再改名顶上去(用于**覆盖**已有产物)。
2188
+ *
2189
+ * 🔴 这样读者永远读不到**半个**文件(同一文件系统上改名是原子的)。
2190
+ * ⚠️ 它保证的只是「不会读到半个」,**不保证**读—判—写这三步之间没有窗口。
2191
+ */
2192
+ replaceAtomically(rel: string, text: string): string;
2193
+ /** 删一份产物。→ 真的删了没有(不存在 / 删不掉都回 false,不抛)。 */
2194
+ remove(rel: string): boolean;
2195
+ /** 读出**文本**,按 UTF-8 严格解码(BOM 先剥掉)。解不出时抛 `TypeError`。 */
2196
+ readText(rel: string): string;
2197
+ /**
2198
+ * 读出**原始字节**,不解码。
2199
+ *
2200
+ * 🔴 故意不返回字符串:调用方要自己用 `TextDecoder(..., { fatal: true })` 解,
2201
+ * 才分得出「不是 UTF-8」与「不是合法 JSON」—— Node 的 `readFileSync(p,'utf-8')`
2202
+ * 把坏字节静默换成 `U+FFFD`,那一档会永不触发。
2203
+ */
2204
+ readBytes(rel: string): Buffer;
2205
+ exists(rel: string): boolean;
2206
+ }
2130
2207
  /**
2131
2208
  * 路径遏制被触发。
2132
2209
  *
@@ -2543,6 +2620,63 @@ declare class MappingError extends Error {
2543
2620
  readonly detail: string;
2544
2621
  constructor(reason: string, message: string, hint?: string);
2545
2622
  }
2623
+ /**
2624
+ * 这一列填的是引用字段,要拿源表里的值去**换 id**。
2625
+ *
2626
+ * `model === 所在模型自身` 即为自引用(组织树的 `parentId`),T4 据此建行级父子边。
2627
+ */
2628
+ interface ResolveBy {
2629
+ model: string;
2630
+ keyField: string;
2631
+ }
2632
+ interface Column {
2633
+ /** 源表列名(客户自己的中文列名) */
2634
+ source: string;
2635
+ /** HCM 字段名 */
2636
+ field: string;
2637
+ resolveBy: ResolveBy | null;
2638
+ }
2639
+ /**
2640
+ * 幂等的支点:`fields[i]` ← `sourceColumns[i]`,按序配对(复合键)。
2641
+ *
2642
+ * 🔴 这一对**既是匹配键也是写入值** —— 别再在 `columns` 里重复声明同一个 field。
2643
+ *
2644
+ * `resolveBy` 按**字段名**索引(与 `valueMap` 同款),不是与 `fields` 等长的第三个数组:
2645
+ * ① 本工件已有的同款语义就是按字段名索引的;② 「逐字段可选」在位置数组里只能靠 `null`
2646
+ * 占位,而少写/多写一个洞会让后面几个字段整体挪位;③ 不给 `BUSINESS_KEY_ARITY_MISMATCH`
2647
+ * 再添一个必须同步的长度。
2648
+ */
2649
+ interface BusinessKey {
2650
+ fields: string[];
2651
+ sourceColumns: string[];
2652
+ /**
2653
+ * 字段名 → 这个字段要拿源值去哪个模型换 id。**逐字段可选**:不在这份表里的
2654
+ * 业务键字段照旧原样写入(复合业务键里可以一个字段要解析、另一个不要)。
2655
+ */
2656
+ resolveBy: Map<string, ResolveBy>;
2657
+ }
2658
+ interface SourceRef {
2659
+ file: string;
2660
+ sheet: string | null;
2661
+ headerRow: number;
2662
+ }
2663
+ interface ModelMapping {
2664
+ model: string;
2665
+ source: SourceRef;
2666
+ businessKey: BusinessKey | null;
2667
+ onExisting: string | null;
2668
+ columns: Column[];
2669
+ constants: Map<string, string | number | boolean>;
2670
+ valueMap: Map<string, Map<string, string>>;
2671
+ }
2672
+ interface Mapping {
2673
+ version: number;
2674
+ models: ModelMapping[];
2675
+ /** 工件自己的路径:源表相对它解析,报错也指得出是哪份工件。 */
2676
+ path: string;
2677
+ }
2678
+ /** 读 `work/mapping.json`。结构 / 类型不对就抛 {@link MappingError}。 */
2679
+ declare function loadMapping(file: string): Mapping;
2546
2680
 
2547
2681
  /**
2548
2682
  * 行级导入计划 —— 每一行该建还是该对既存、先建谁、以及三类硬失败。
@@ -2848,11 +2982,41 @@ interface ImportPlan {
2848
2982
 
2849
2983
  /** 产物文件名。落盘收的是 **work 目录**,写这一份。 */
2850
2984
  declare const RISK_FILE = "risk.json";
2985
+ /**
2986
+ * 本模块会发出的全部 problem code。守法与工件层 / 计划层同款:用例拿源码里的
2987
+ * `problem('…')` 字面量与本表**双向**对着 —— 少一个、多一个都红。
2988
+ */
2989
+ declare const RISK_CODES: readonly ["MAPPING_NOT_USABLE", "MODEL_KEY_UNSAFE", "RECON_SHEET_MISSING", "RECON_SHEET_UNREADABLE", "RECON_FIELDS_UNJUDGED", "VALUE_DOMAIN_MISSING", "VALUE_DOMAIN_UNREADABLE", "ENUM_DOMAIN_MISSING", "ENUM_DOMAIN_UNREADABLE", "ENUM_ROW_MISSING", "RISK_CHECKS_SKIPPED", "RISK_NOT_BUILT", "AC6_PREMISE_SOURCE_ROWS_EMPTY", "AC6_PREMISE_VALUEDOMAIN_NOT_COMPLETE", "BASELINE_ROUND_NOT_COMPLETE", "REQUIRED_FIELD_UNMAPPED", "REQUIRED_FIELD_SERVER_FILLED", "FIELD_NOT_IN_MODEL", "FIELD_NOT_WRITABLE", "AUTO_GENERATED_BUSINESS_KEY", "VALUE_DOMAIN_NOT_AUTHORITATIVE", "VALUE_MAP_TARGET_MISSING_FROM_DOMAIN", "ENUM_VALUE_NOT_IN_DOMAIN", "CONFUSABLE_COLUMN_PAIR", "EXCEL_DATE_SERIAL_SUSPECTED", "SOURCE_COLUMN_DISCARDED", "MUTATION_NOT_ALLOWED", "MUTATION_UNKNOWN", "EXEMPTION_NOT_APPLICABLE", "EXEMPTION_INCOMPLETE", "EXEMPTION_STALE", "EXEMPTION_ANCHOR_UNVERIFIABLE", "EXEMPTION_UNMATCHED"];
2851
2990
  /**
2852
2991
  * 🔴 **哪几条拦路**。这是 `Risk.blocking` 的唯一来源(命令层的退出码接它)。
2853
2992
  * 判据是「不修它就不许生成写脚本」,与 `kind` 是**两个维度**。
2854
2993
  */
2855
2994
  declare const BLOCKING_CODES: readonly ["MAPPING_NOT_USABLE", "MODEL_KEY_UNSAFE", "RECON_SHEET_MISSING", "RECON_SHEET_UNREADABLE", "RECON_FIELDS_UNJUDGED", "VALUE_DOMAIN_MISSING", "VALUE_DOMAIN_UNREADABLE", "ENUM_DOMAIN_MISSING", "ENUM_DOMAIN_UNREADABLE", "ENUM_ROW_MISSING", "REQUIRED_FIELD_UNMAPPED", "FIELD_NOT_IN_MODEL", "VALUE_DOMAIN_NOT_AUTHORITATIVE", "ENUM_VALUE_NOT_IN_DOMAIN", "MUTATION_NOT_ALLOWED", "MUTATION_UNKNOWN", "EXEMPTION_NOT_APPLICABLE", "EXEMPTION_INCOMPLETE", "EXEMPTION_STALE", "EXEMPTION_ANCHOR_UNVERIFIABLE", "RISK_NOT_BUILT", "AC6_PREMISE_SOURCE_ROWS_EMPTY", "AC6_PREMISE_VALUEDOMAIN_NOT_COMPLETE", "BASELINE_ROUND_NOT_COMPLETE"];
2995
+ declare const ADVISORY_CODES: ("MAPPING_NOT_USABLE" | "MODEL_KEY_UNSAFE" | "RECON_SHEET_MISSING" | "RECON_SHEET_UNREADABLE" | "RECON_FIELDS_UNJUDGED" | "VALUE_DOMAIN_MISSING" | "VALUE_DOMAIN_UNREADABLE" | "ENUM_DOMAIN_MISSING" | "ENUM_DOMAIN_UNREADABLE" | "ENUM_ROW_MISSING" | "RISK_CHECKS_SKIPPED" | "RISK_NOT_BUILT" | "AC6_PREMISE_SOURCE_ROWS_EMPTY" | "AC6_PREMISE_VALUEDOMAIN_NOT_COMPLETE" | "BASELINE_ROUND_NOT_COMPLETE" | "REQUIRED_FIELD_UNMAPPED" | "REQUIRED_FIELD_SERVER_FILLED" | "FIELD_NOT_IN_MODEL" | "FIELD_NOT_WRITABLE" | "AUTO_GENERATED_BUSINESS_KEY" | "VALUE_DOMAIN_NOT_AUTHORITATIVE" | "VALUE_MAP_TARGET_MISSING_FROM_DOMAIN" | "ENUM_VALUE_NOT_IN_DOMAIN" | "CONFUSABLE_COLUMN_PAIR" | "EXCEL_DATE_SERIAL_SUSPECTED" | "SOURCE_COLUMN_DISCARDED" | "MUTATION_NOT_ALLOWED" | "MUTATION_UNKNOWN" | "EXEMPTION_NOT_APPLICABLE" | "EXEMPTION_INCOMPLETE" | "EXEMPTION_STALE" | "EXEMPTION_ANCHOR_UNVERIFIABLE" | "EXEMPTION_UNMATCHED")[];
2996
+ /**
2997
+ * 豁免通道自己的五条 code。它们**不可被豁免**(下面求交时显式排除)。
2998
+ *
2999
+ * 🔴 减号该留,理由有两条(第一版给的理由被实测证伪,这里是更正后的):
3000
+ * ① **语义**:这五条说的是「**你这份豁免本身不合规**」,不是「一条查过且不合格的风险」;
3001
+ * ② **纵深防御**:它们哪天改成在匹配**之前**发出,减号就是唯一挡着
3002
+ * 「拿一份豁免盖掉另一份豁免的回执」的东西 —— 而那次改动本身不会有任何用例提醒作者。
3003
+ */
3004
+ declare const EXEMPTION_CODES: readonly ["EXEMPTION_NOT_APPLICABLE", "EXEMPTION_INCOMPLETE", "EXEMPTION_STALE", "EXEMPTION_ANCHOR_UNVERIFIABLE", "EXEMPTION_UNMATCHED"];
3005
+ /**
3006
+ * 🔴 **可豁免集合是求交算出来的,不是第三张手维护的表**:`content ∩ blocking` ——
3007
+ * 也就是「**查过且不合格**」那一类。
3008
+ *
3009
+ * 前提级 code **结构性地**进不来:它们的语义是「这条结论建立在一个不成立的前提上」。
3010
+ * 一份为 `partial` 签的豁免若能连带盖掉 `VALUE_DOMAIN_MISSING`,**就是 GC3 在豁免层塌陷**
3011
+ * —— 顾问签的是「我确认过这份对照表」,而被盖掉的那条说的是「这份对照表压根没爬到」。
3012
+ */
3013
+ declare const EXEMPTIBLE_CODES: ("MAPPING_NOT_USABLE" | "MODEL_KEY_UNSAFE" | "RECON_SHEET_MISSING" | "RECON_SHEET_UNREADABLE" | "RECON_FIELDS_UNJUDGED" | "VALUE_DOMAIN_MISSING" | "VALUE_DOMAIN_UNREADABLE" | "ENUM_DOMAIN_MISSING" | "ENUM_DOMAIN_UNREADABLE" | "ENUM_ROW_MISSING" | "RISK_CHECKS_SKIPPED" | "RISK_NOT_BUILT" | "AC6_PREMISE_SOURCE_ROWS_EMPTY" | "AC6_PREMISE_VALUEDOMAIN_NOT_COMPLETE" | "BASELINE_ROUND_NOT_COMPLETE" | "REQUIRED_FIELD_UNMAPPED" | "REQUIRED_FIELD_SERVER_FILLED" | "FIELD_NOT_IN_MODEL" | "FIELD_NOT_WRITABLE" | "AUTO_GENERATED_BUSINESS_KEY" | "VALUE_DOMAIN_NOT_AUTHORITATIVE" | "VALUE_MAP_TARGET_MISSING_FROM_DOMAIN" | "ENUM_VALUE_NOT_IN_DOMAIN" | "CONFUSABLE_COLUMN_PAIR" | "EXCEL_DATE_SERIAL_SUSPECTED" | "SOURCE_COLUMN_DISCARDED" | "MUTATION_NOT_ALLOWED" | "MUTATION_UNKNOWN" | "EXEMPTION_NOT_APPLICABLE" | "EXEMPTION_INCOMPLETE" | "EXEMPTION_STALE" | "EXEMPTION_ANCHOR_UNVERIFIABLE" | "EXEMPTION_UNMATCHED")[];
3014
+ /**
3015
+ * 一份豁免必须写全的键。缺一个就不是一条能追责的台账记录。
3016
+ * `field` 也是必填 —— 这就是「**逐条**豁免、不许全局 `--force`」的落点:
3017
+ * 没有任何写法能一次盖住一个模型的全部风险项。
3018
+ */
3019
+ declare const EXEMPTION_REQUIRED_KEYS: readonly ["code", "model", "field", "by", "at", "reason", "roundId"];
2856
3020
  /**
2857
3021
  * 豁免锚在**它所依据的那份证据**上:recon 两份索引的 `roundId`。
2858
3022
  * 值域换了一轮 ⇒ 顾问当初确认的那份对照表已经不是现在这份 ⇒ 豁免自动失效。
@@ -2860,6 +3024,13 @@ declare const BLOCKING_CODES: readonly ["MAPPING_NOT_USABLE", "MODEL_KEY_UNSAFE"
2860
3024
  * 等于把「没查」当成「查过、没问题」。
2861
3025
  */
2862
3026
  declare const ROUND_ANCHORS: readonly ["mapping/_index.json", "valuedomain/_index.json"];
3027
+ /**
3028
+ * 🔴 组 → 它发哪些 code。用例拿它与 {@link CONTENT_CODES} **双向**对着:
3029
+ * 新加一条内容级判据 ⇒ 新 code 进 {@link RISK_CODES} ⇒ 自动进 `CONTENT_CODES` ⇒
3030
+ * **不归组则并集变小,守卫当场红**,作者被强制回答「它属于哪一组」——
3031
+ * 而「属于哪一组」正好就是「哪些前提挡得住它」({@link PREMISE_BLOCKS} 按组接线)。
3032
+ */
3033
+ declare const CHECK_GROUPS: Record<string, readonly string[]>;
2863
3034
  /**
2864
3035
  * 一条风险。
2865
3036
  *
@@ -3113,6 +3284,86 @@ declare function roundWarning(round: {
3113
3284
  } | null): string;
3114
3285
  /** {@link ROUND_WARNINGS} 该覆盖的那些状态 —— 现取自 {@link ROUND_STATES},不手抄。 */
3115
3286
  declare const WARNED_ROUND_STATES: ("unknown" | "mixed")[];
3287
+ /**
3288
+ * 报告 → 退出码。
3289
+ *
3290
+ * 🔴 `quarantined` 与 `writeFailed` 同档:服务端接受过一次写、业务键却查不回来 ——
3291
+ * 给 `clean` 就是让脚本带着一条**状态未知**的写继续跑。
3292
+ *
3293
+ * 🔴 `blocked` **进**这一档:它是「计划要建、而这一轮确定没建」的行。漏掉它时
3294
+ * rc 会给 0,而那条路真的走得到(work 目录从别处拷来、台账里父行记着 `done`
3295
+ * 却没有 `serverId`)。
3296
+ *
3297
+ * ⚠️ `unverified` **不**进这一档:它是「建成了但这一轮没回读复验」,在不带 `--sample`
3298
+ * 的正常一轮里是常态,拿它判红会让 rc=1 变成噪音。
3299
+ */
3300
+ declare const RC_DECIDING_REPORT_FIELDS: readonly ["aborted", "writeFailed", "quarantined", "blocked"];
3301
+ declare function applyRc(report: {
3302
+ aborted: string | null;
3303
+ writeFailed: number;
3304
+ quarantined: number;
3305
+ blocked: number;
3306
+ }): number;
3307
+ /**
3308
+ * `applyPlan` 穿出来的台账错误:**按成因分档**,每档三格
3309
+ * `[抬头, 下一步, 台账真的在盘上时才说的那句]`。
3310
+ *
3311
+ * 🔴 「台账写不下去」与「这份计划自己前后对不上」是两件事,**不许共用一段话**:
3312
+ * 顾问看到的不是栈,而是**一条自信地指错方向的话** —— 那比栈更贵,栈至少不骗人。
3313
+ *
3314
+ * 🔴 **不设一个共用磁盘/权限那段话的兜底档**:认不出的 `reason` 走
3315
+ * {@link JOURNAL_STOP_UNKNOWN},它只说本层此刻查到的事实、**不给方向**。
3316
+ *
3317
+ * ⚠️ 表里的键必须是台账真抛得出的 `reason` —— 守卫从 `journal.ts` 现抠,防死登记项。
3318
+ */
3319
+ declare const JOURNAL_STOP_KINDS: Record<string, [string, string, string]>;
3320
+ declare const JOURNAL_STOP_UNKNOWN: [string, string, string];
3321
+ /**
3322
+ * 「台账在哪 / 在不在」—— **本层此刻从盘上查到的事实**,不是从异常里推的。
3323
+ *
3324
+ * 🔴 台账**还不存在**时不许说「已经发出去的写都记在里面」「先备份走」——
3325
+ * 那是叫人去备份一个不存在的文件。
3326
+ */
3327
+ declare function journalNote(journalPath: string, whenPresent?: string): string;
3328
+ /**
3329
+ * 「明说不覆盖」的终端载体:`apply` 只把计划与工件对过两格。
3330
+ *
3331
+ * 🔴 模块文档与 README 里都写了,**顾问在终端上也得看得见** —— 他多半只看这一屏。
3332
+ * 措辞与那两处同源,别在这里另说一套。
3333
+ */
3334
+ declare const APPLY_CAVEAT: string;
3335
+ declare const DRY_RUN_TAIL = "\u2191 \u8FD9\u662F**\u5E72\u8DD1**\uFF1A\u4E00\u53D1\u5199\u8BF7\u6C42\u90FD\u6CA1\u6709\u53D1\u3002\u8981\u771F\u5199\uFF0C\u52A0 `--execute`\u3002";
3336
+ /**
3337
+ * 「计划 vs 基线」那一条前提 —— **与漂移门不是一回事**。
3338
+ *
3339
+ * 漂移门比的是「基线 vs 环境」;这一条比的是「计划 vs 基线」。重跑一次 recon 会把
3340
+ * 指纹刷成与环境相符,于是漂移门说「同源」,而这份计划是照**旧的基线内容**算的
3341
+ *(行动作、既存索引、风险清单全是那时候算的)。
3342
+ *
3343
+ * 🔴 **判据收成一条 `plannedRound !== nowRound`,措辞分三种** —— 取值域从此是
3344
+ * **结构性质**,不是「每撞一次补一条」。2×2 全在:
3345
+ * ① 两边都有戳且相同 ⇒ 放过 · ② 都有戳且不同 ⇒ 查实的「不是同一轮」 ·
3346
+ * ③ 计划没记戳、盘上现在有 ⇒ 前提级「**分不清**」 ·
3347
+ * ④ 计划记了戳、盘上现在读不出 ⇒ 观测级「**判不清**」 ·
3348
+ * ⑤ 两边都没戳 ⇒ `null !== null` 为假 ⇒ **自然放过**(它不需要一条 `if`,
3349
+ * 这正是收成一条的好处)。
3350
+ *
3351
+ * 🔴 ③④ 的判词**不许**说成「这份基线换过了 / 被动过」——重爬同一个环境会产生
3352
+ * 内容相同但**新的**戳;而 ④ 的四种子态里「权限读不了」那一种**基线字节一个都没变**。
3353
+ * 说「被动过」是假的,照那句话去重跑 recon 反而换掉了好产物。
3354
+ *
3355
+ * → `[message, hint]`,判得过时是 `null`。
3356
+ */
3357
+ declare function planVsBaselinePremise(baselinePath: string, plannedRound: string | null, nowRound: string | null): [string, string] | null;
3358
+ /**
3359
+ * 🔴 放行开关的字面量在 `drift` 那一支(`FORCE_STALE_FLAG`)。本模块**不 import 它**,
3360
+ * 因为 `command` 是给命令层用的薄层、而 `drift` 是判据层 —— 反过来引会让两层成环。
3361
+ * ⇒ 这里保留一份**文本**,并由守卫断言它与 `drift.FORCE_STALE_FLAG` 逐字相同:
3362
+ * 判据是「两份相等」这个关系,不是「谁抄谁」。
3363
+ */
3364
+ declare const FORCE_STALE_FLAG_TEXT = "--force-stale";
3365
+ /** 已有台账、又没带 `--resume` 时那一句。🔴 **CLI 绝不自己删台账**。 */
3366
+ declare function existingJournalStop(journalPath: string, entries: number): [string, string];
3116
3367
 
3117
3368
  /**
3118
3369
  * 行级导入计划的**门面与产物**:读工件 → 扫源表 → 校验 → 建既存索引 → 建计划 → 落盘 / 回读。
@@ -3203,6 +3454,960 @@ declare class PlanReadError extends Error {
3203
3454
  */
3204
3455
  declare function readImportPlan(out: string): ImportPlan;
3205
3456
 
3457
+ /** 产物文件名。所有入口收的都是 **work 目录**,台账固定落在它下面这一份。 */
3458
+ declare const JOURNAL_FILE = "journal.jsonl";
3459
+ /**
3460
+ * 🔴 状态取值域。语义见模块头注释:`unknown` 之外的每一档都是**查过之后**的结论,
3461
+ * `unknown` 是「不知道」。
3462
+ *
3463
+ * ⚠️ 扩这个域**不是禁令,是重活**:加一档要同时动 {@link NEXT_STEP}(值域守卫双向盯着)、
3464
+ * 想清楚它算不算 {@link NEEDS_PRIOR_RECORD},并给出**真的会产出它的生产者**。
3465
+ */
3466
+ declare const STATUSES: readonly ["done", "skipped", "failed", "unknown", "quarantined"];
3467
+ type Status = (typeof STATUSES)[number];
3468
+ declare const STEP_NOTHING = "nothing";
3469
+ /**
3470
+ * 🔴 **停下来点名要人**。与 {@link STEP_NOTHING} 不是一回事:那是「不必再动」,
3471
+ * 这是「**不许**自动再动」—— 自动再动会多出一条按业务键查不回来的野行。
3472
+ */
3473
+ declare const STEP_STOP = "stop";
3474
+ /**
3475
+ * 「这一行接下来该做什么」。
3476
+ *
3477
+ * 🔴 这是**唯一**的判据表,`needsReadback` / `shouldReplay` 都从它派生 ——
3478
+ * 两个布尔各写一套 if 的话,迟早出现「都为 false」或「都为 true」的组合,
3479
+ * 而那两种都不是本模块承认的结局。
3480
+ *
3481
+ * 🔴 键 `null` = **这一行从没落过账**,与 `failed` 是两回事:前者是「没试过」,
3482
+ * 后者是「试过、被明确拒绝」。合并就是 GC3 塌在台账上。
3483
+ */
3484
+ declare const NEXT_STEP: Record<string, string>;
3485
+ /**
3486
+ * 台账的前提不成立。
3487
+ *
3488
+ * 与 `SourceError` / `MappingError` 同形:`reason` 给程序判、`hint` 给顾问照做,
3489
+ * 两者都不许省。
3490
+ *
3491
+ * ⚠️ `detail` 是 Python 侧 `.message` 的对等物(「看到了什么」那一段)。JS 的
3492
+ * `Error.message` 恒是三段拼起来的整句 —— 两者都留着,别把断言写在会漂的那一个上。
3493
+ */
3494
+ declare class JournalError extends Error {
3495
+ readonly reason: string;
3496
+ readonly detail: string;
3497
+ readonly hint: string;
3498
+ constructor(reason: string, detail: string, hint?: string);
3499
+ }
3500
+ /** 一行的一次结局。 */
3501
+ interface Entry {
3502
+ /** 源表行号(计划层 `RowPlan.row`,`headerRow + 1 + i`)。 */
3503
+ sourceRowId: number;
3504
+ model: string;
3505
+ /** 业务键元组,**元素必须是非空字符串**(理由见 {@link businessKeyOf})。 */
3506
+ businessKey: readonly string[];
3507
+ /** {@link payloadHash} 的产物;没有时是 `null`。 */
3508
+ payloadHash: string | null;
3509
+ /** 服务端的行 id;没有(尚未建成 / 建不成)时是 `null`。 */
3510
+ serverId: string | null;
3511
+ status: Status;
3512
+ /** 这一行发过几次请求(`begin()` 自动 +1)。 */
3513
+ attempts: number;
3514
+ /** 哪一轮记的(计划层 `plan.roundId` 的同一个值)。 */
3515
+ roundId: string;
3516
+ /** 产品错误信封**原样**,只在有值时落盘。 */
3517
+ error?: unknown;
3518
+ }
3519
+ /**
3520
+ * 一次 `--force-stale` 放行 —— **「这一批行是在什么前提下写出去的」的唯一留痕**。
3521
+ *
3522
+ * 它与 {@link Entry} 不是一回事,所以不进 `entries`:`Entry` 说的是**某一行**的结局,
3523
+ * Waiver 说的是**整整一轮**是在什么样的前提下跑的。混进 `entries.length` 就会让
3524
+ * 「这一轮记了几行」多出一条不是行的东西。
3525
+ */
3526
+ interface Waiver {
3527
+ roundId: string;
3528
+ /** ISO 8601 带 `+00:00`。 */
3529
+ at: string;
3530
+ verdict: string;
3531
+ causes: readonly string[];
3532
+ gateDiffs: readonly string[];
3533
+ incomplete: readonly string[];
3534
+ advisory: readonly string[];
3535
+ /** 那一轮点名的基线出处;计划里没说是哪一份时是 `null`。 */
3536
+ baseline: string | null;
3537
+ }
3538
+ /**
3539
+ * append-only 的行级台账。**最后一条记录赢**(同一个模型 + 业务键)。
3540
+ *
3541
+ * 为什么是 append-only 而不是「一行一条、原地改」:原地改要么整份重写(中途被打断就把
3542
+ * **已经落好的全部**记录一起赔进去),要么定长记录(脆)。追加一行的代价是常数,
3543
+ * 而且崩在半行上时下一次 `load` 会**响亮地**报出来,不会静默少一行。
3544
+ */
3545
+ declare class Journal {
3546
+ readonly workDir: string;
3547
+ readonly path: string;
3548
+ readonly entries: Entry[];
3549
+ readonly waivers: Waiver[];
3550
+ /**
3551
+ * 🔴 `entries === []` 有两种成因,这个布尔把它们分开:
3552
+ * true = 文件在、里面一条都没有;false = 文件**根本不存在**(第一轮)。
3553
+ */
3554
+ exists: boolean;
3555
+ private readonly layout;
3556
+ private readonly latestByKey;
3557
+ constructor(workDir: string, entries?: readonly Entry[], exists?: boolean, waivers?: readonly Waiver[]);
3558
+ /**
3559
+ * 读回台账。`path` 是 **work 目录**,台账固定落在它下面的 `journal.jsonl`。
3560
+ *
3561
+ * 🔴 **读不了就抛,不返回空台账**:空台账的下游语义是「每一行都没记过 ⇒ 全部重放」,
3562
+ * 也就是全量重复。
3563
+ */
3564
+ static load(p: string): Journal;
3565
+ /** 这个模型 + 业务键**最后一条**记录;从没记过返回 `null`。 */
3566
+ latest(model: string, key: unknown): Entry | null;
3567
+ /**
3568
+ * → {@link STATUSES} 里的一档,或 `null`。
3569
+ *
3570
+ * 🔴 `null` = **这一行本模块从没记过**,与 `'failed'` 是两回事,也与 `'skipped'`
3571
+ * 是两回事。三者的下一步动作分别是「发」「发」「什么都不做」—— 看着有两档相同,
3572
+ * 但**理由**不同,合并就没法解释产物了。
3573
+ */
3574
+ statusOf(model: string, key: unknown): Status | null;
3575
+ /**
3576
+ * 这一行接下来该做什么 —— 取值域恒等于 `NEXT_STEP` 的值集。
3577
+ *
3578
+ * 🔴 **推荐调用方只读这一个**:两个布尔(`needsReadback` / `shouldReplay`)是从这里
3579
+ * 派生的**投影**,它们「都为 false」时有**三**种完全不同的含义
3580
+ * (已建好 / 已跳过 / **中毒了要人处理**),单看任何一个都读不出来。
3581
+ */
3582
+ nextStep(model: string, key: unknown): string;
3583
+ /** 这一行要不要**先按业务键回读**再决定 —— 只有 `unknown` 是 true。 */
3584
+ needsReadback(model: string, key: unknown): boolean;
3585
+ /**
3586
+ * 这一行可不可以**直接重发**请求。
3587
+ *
3588
+ * 🔴 `unknown` / `quarantined` 恒为 false:那两条路正是产生重复行的路。
3589
+ * ⚠️ true 的含义是「重发是安全的」,**不是**「重发会成功」—— `failed` 那一档多半要
3590
+ * 顾问先把源表改对。
3591
+ */
3592
+ shouldReplay(model: string, key: unknown): boolean;
3593
+ /**
3594
+ * **发请求之前**先落一条 `unknown`(写前落账)。
3595
+ *
3596
+ * `attempts` 在这里自动 +1(前一条没有就从 1 起)—— 让调用方自己数,两处状态迟早漂,
3597
+ * 而漂的方向是「重试了 5 次,台账里写着 1」。
3598
+ */
3599
+ begin(sourceRowId: number, model: string, key: unknown, payloadHashValue: string | null, roundId: string): Entry;
3600
+ /**
3601
+ * 把一条结局追加进台账(内存 + 磁盘)。
3602
+ *
3603
+ * 校验三件事,任一不成立**硬失败**:状态在取值域内 · 业务键是字符串序列 ·
3604
+ * 终态必须有前置记录(写前落账协议)。
3605
+ */
3606
+ append(entry: Entry): Entry;
3607
+ /**
3608
+ * 把一次 `--force-stale` 放行追加进台账(内存 + 磁盘)。
3609
+ *
3610
+ * 🔴 **不 fsync**:它不是崩溃标记 —— 丢了不会让任何一行被重放,而写前落账那一条丢了
3611
+ * 就等于那一行没落过账。
3612
+ * 🔴 走 `append` 同一条落盘路径与同一条错误边界:写失败时内存态一个字节都不许动,
3613
+ * 否则「台账里有据可查」这句话会在盘上落空而在内存里成立。
3614
+ */
3615
+ appendWaiver(waiver: Waiver): Waiver;
3616
+ /**
3617
+ * 真正落盘的那一步。单独拆出来只为**让写失败有一个明确的边界** ——
3618
+ * 内存态的更新必须留在这个边界之外(写失败时台账不许在内存里「已经有了」)。
3619
+ *
3620
+ * 🔴 `sync` 由调用方给,不在这里按行的内容判:两种行走的是**同一条**落盘路径,
3621
+ * 而「值不值得 fsync」是各自的语义。
3622
+ */
3623
+ private writeLine;
3624
+ }
3625
+ /** 回读只要 `post` 这一个能力,就只声明这一个。 */
3626
+ interface ReadbackClient {
3627
+ post(path: string, body: unknown): Promise<Outcome>;
3628
+ }
3629
+ /** 租约文件名。与台账同一个 work 目录。 */
3630
+ declare const LEASE_FILE = ".lease.json";
3631
+ /**
3632
+ * 租约拿不到,或者拿到之后被别人顶掉了 —— **硬停**,不降级。
3633
+ *
3634
+ * 🔴 `age-unknown` / `lease-unreadable` 是 **fail-closed**:判不出这份租约是新是旧,
3635
+ * 就不许把它当陈旧的抢过来。「没查出来」当成「查过、没问题」正是本 kit 反复在治的病。
3636
+ */
3637
+ declare class LeaseViolation extends Error {
3638
+ readonly reason: string;
3639
+ readonly detail: string;
3640
+ readonly hint: string;
3641
+ constructor(reason: string, detail: string, hint?: string);
3642
+ }
3643
+ /**
3644
+ * 两个钟,各管各的。
3645
+ *
3646
+ * 🔴 **盘上的 `heartbeatAt` 必须是墙钟**(`now()`):别的进程要拿它减自己的当下、
3647
+ * 与 {@link LEASE_STALE_SECONDS} 比 —— 换成单调秒就成了一个**跨进程无意义**的数
3648
+ * (每个进程的单调原点都不一样)。
3649
+ * 🔴 **「距上次盖章多久」必须是单调秒**(`monotonic()`):墙钟会被 NTP 往回拨,
3650
+ * 一拨就再也不到钟。
3651
+ *
3652
+ * ⚠️ 做成入参而不是模块级函数,是为了让上面那条纪律**测得出来** ——
3653
+ * 用例要能把两个钟分别往前 / 往回拨。
3654
+ */
3655
+ interface Clock {
3656
+ /** 当前墙钟时刻。 */
3657
+ now(): Date;
3658
+ /** **单调**秒,只用来量「距上次多久」—— 永远不写进租约文件。原点是任意的。 */
3659
+ monotonic(): number;
3660
+ }
3661
+ interface LeasePayload {
3662
+ host: string;
3663
+ pid: number;
3664
+ roundId: string;
3665
+ acquiredAt: string;
3666
+ heartbeatAt: string;
3667
+ }
3668
+ /** 被顶掉的那一份的身份 —— `Lease.reclaimed` 上摆的东西。 */
3669
+ interface Reclaimed {
3670
+ identity: [unknown, unknown, unknown];
3671
+ heartbeatAt: unknown;
3672
+ ageSeconds: number;
3673
+ }
3674
+ /**
3675
+ * 一份**协作式**的单写者租约。
3676
+ *
3677
+ * 🔴 **诚实声明**(不许软化,也不许夸大):
3678
+ *
3679
+ * - 它挡的是**另一个照规矩走 kit 的进程**;顾问自己 curl、别的工具、产品 UI 上有人在点
3680
+ * —— 一概挡不住,客户的 HCM 对这个文件一无所知。**这一条是结构上做不到。**
3681
+ * - `kill -9` 之后没有 `release()` 的机会,陈旧租约靠**心跳超时**回收;也就是说超时
3682
+ * 窗口内一个已经死掉的租约照样拦人。
3683
+ * ⚠️ 例外那一档(崩在「创建」与「写内容」之间留下 0 字节租约 ⇒ 超时永远回收不了)
3684
+ * 已经被「写完整 tmp + 硬链接」消掉了。但**别读成「任何读不出的租约都不会发生」**:
3685
+ * 文件被别的工具改坏、介质出错时照样会走 `lease-unreadable` 的 fail-closed 分支。
3686
+ * - **陈旧回收那一步(读—判—写)不原子**:两个进程可以同时判定「陈旧」然后都写自己的
3687
+ * 租约。🔴 这一档是**暂时不做**,**不是做不到** —— 把暂时不做写成做不了,
3688
+ * 会永久注销一件做得了的事。纯客户端就有原子 CAS(rename-to-claim),
3689
+ * 但「怎么用它」比「它原不原子」难:天真版(人人都重建租约)实测会出**多个**赢家
3690
+ * (上限 = 并发进程数,8 进程实测到 6;发生率随负载在 1%–45% 之间摆动,
3691
+ * **跑几轮都好并不说明它没有**),必须把「读 + 判陈旧」放在 rename **前面**。
3692
+ * 要连重试循环与前置判据一起验,所以至今不做。
3693
+ *
3694
+ * `reclaimed` 记的是「这份租约是从一份陈旧租约手里回收来的」。🔴 摆出来是因为
3695
+ * **静默顶掉别人**是本模块最危险的一种沉默 —— 真出双写事故时,这是唯一能回溯
3696
+ * 「谁在什么时候被判成死了」的记录。
3697
+ */
3698
+ declare class Lease {
3699
+ readonly layout: WorkLayout;
3700
+ readonly path: string;
3701
+ readonly host: string;
3702
+ readonly pid: number;
3703
+ readonly roundId: string;
3704
+ readonly acquiredAt: Date;
3705
+ heartbeatAt: Date;
3706
+ readonly reclaimed: Reclaimed | null;
3707
+ private readonly clock;
3708
+ /** 节流用的**单调**标记,与 `heartbeatAt`(墙钟、要落盘)分开两个钟。 */
3709
+ private beatMark;
3710
+ constructor(layout: WorkLayout, spec: {
3711
+ host: string;
3712
+ pid: number;
3713
+ roundId: string;
3714
+ acquiredAt: Date;
3715
+ heartbeatAt: Date;
3716
+ }, reclaimed?: Reclaimed | null, clock?: Clock);
3717
+ /**
3718
+ * 🔴 身份是 `(host, pid, roundId)` 三件套。
3719
+ *
3720
+ * 单靠 `pid` 不行:`kill -9` 之后 pid 会被复用,一个**别的**进程会被认成自己。
3721
+ * `roundId` 后半截是随机的,撞不上。
3722
+ */
3723
+ get identity(): [string, number, string];
3724
+ payload(): LeasePayload;
3725
+ /**
3726
+ * 盖一次心跳。**先核对这份租约还是不是自己的**,不是就抛 `lost`。
3727
+ *
3728
+ * 🔴 不核对的话,本进程会把一份**已经被别人回收**的租约悄悄抢回来 ——
3729
+ * 于是两个写者都以为自己独占。核对一次的代价是一次读文件。
3730
+ *
3731
+ * 🔴 **这个方法无条件盖章,不看间隔** —— 想要节流的走 {@link heartbeatIfDue}。
3732
+ * 两种语义**不塞进一个名字**:真正想强制盖一次的地方拿到的必须是「一定盖」,
3733
+ * 而不是「可能盖了、可能没盖」。
3734
+ *
3735
+ * ⚠️ 本模块**不起后台线程**:要调用方自己调。心跳与请求在同一个线程上,
3736
+ * 一次阻塞的请求期间它发不出去 —— {@link LEASE_STALE_SECONDS} 就是照这一点定的。
3737
+ */
3738
+ heartbeat(): Lease;
3739
+ /**
3740
+ * 距上一次盖章不足 {@link LEASE_HEARTBEAT_SECONDS} 就**不盖**,够了才盖一次。
3741
+ *
3742
+ * 🔴 **节流住在这一侧**:执行器每花掉一次请求就调它一次,而「多久算够」是租约的事
3743
+ * —— 执行器不该知道那两个时间常量。少了这一层,一轮 3000 行就是 3000 次
3744
+ * 「读租约 + 写租约」。
3745
+ *
3746
+ * 比的是**本对象上一次盖章以来的单调秒**,既不是盘上那个值、也不是墙钟差:
3747
+ * 盘上的值可能是别人写的;而墙钟被 NTP 往回拨一次,「距上次多久」会变成负数,
3748
+ * 从此再也不到钟。**盘上写的仍然是墙钟** —— 别的进程要拿它比阈值,两个钟别串。
3749
+ *
3750
+ * ⚠️ {@link heartbeat} 写失败时不推进那个标记 ⇒ 下一次调用照样够钟。
3751
+ * ⚠️ 没到钟的那一次**什么都不做**,原样返回 `this`(不读文件、不写文件)——
3752
+ * 也就**不核身份**:本方法**不是**「租约还归我吗」的探针。
3753
+ */
3754
+ heartbeatIfDue(): Lease;
3755
+ /**
3756
+ * 释放租约(删文件)。→ 真的删了没有。
3757
+ *
3758
+ * 🔴 **只删自己的那一份**:文件已经易主时什么都不做并返回 false。
3759
+ * 删别人的租约等于给下一个进程发一张假的通行证。
3760
+ */
3761
+ release(): boolean;
3762
+ }
3763
+ /**
3764
+ * 拿下这个 work 目录的单写者租约;拿不到抛 {@link LeaseViolation},**硬停**。
3765
+ *
3766
+ * 判定顺序:
3767
+ *
3768
+ * 1. **没有租约文件** ⇒ 写完整 tmp 再硬链接上去(本地 POSIX 上原子,且租约**一出现
3769
+ * 就是完整的**);
3770
+ * 2. **有,且身份就是自己**(同 host + pid + roundId)⇒ 幂等重入,刷一次心跳戳返回;
3771
+ * 3. **有,但读不出 / 心跳时间戳读不出年龄** ⇒ `LeaseViolation`,**fail-closed**;
3772
+ * 4. **有,心跳在 {@link LEASE_STALE_SECONDS} 内** ⇒ `LeaseViolation`(另一个写者活着);
3773
+ * 5. **有,心跳已陈旧** ⇒ 回收,并把被顶掉的那份身份记在 `Lease.reclaimed` 上。
3774
+ */
3775
+ declare function acquireLease(workDir: string, roundId: string, clock?: Clock): Lease;
3776
+
3777
+ /**
3778
+ * 执行器:对锚 → 分波写入 → 回读比对。
3779
+ *
3780
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/execute.py`(ADR-319 刀 11d-1)。
3781
+ * 行为基线是 `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.6。
3782
+ * ⚠️ 本刀只搬**常量、分档结构、payload 与前置闸**;主流程(`applyPlan` / 逐行执行 /
3783
+ * 回读判定)与报告落盘在刀 11d-2 / 11d-3。
3784
+ *
3785
+ * 🔴 **这是 seed 链路上第一个产生不可逆后果的模块。** 前面几个模块全是规划与记录,
3786
+ * 从这里开始,写错了就是客户库里的脏数据。所以本模块的默认值、闸门与判据都按
3787
+ * 「**宁可什么都不做**」的方向倒过来定:
3788
+ *
3789
+ * - `dryRun` 默认 **true** —— 忘了传参不许变成一次真实写入;
3790
+ * - 计划有任何一条 problem ⇒ **一发请求都不发**(计划层自己的口径就是「全都是硬失败」);
3791
+ * - 有一行的动作本执行器执行不了 ⇒ **整轮不执行**,不是静默跳过那几行;
3792
+ * - 判不出结局的行留在 `unknown`,**不许**猜成 `done` 也不许猜成 `failed`。
3793
+ *
3794
+ * ## 五条承重规则(每条都来自真机实测)
3795
+ *
3796
+ * 1. **业务键字段必须送**,不管元数据说它 `writable` 与否。本模块**从不读**可写性那一列:
3797
+ * payload 只由工件的赋值集合决定,而业务键那一对在计划层算一次字段赋值 ⇒ 它天然在
3798
+ * `RowPlan.fields` 里。{@link assertBusinessKeySent} 是兜底闸(说准一格:它与行键同源,
3799
+ * 挡的是「拼 payload 时把业务键过滤掉/改写了」,不是「工件本身写错了」)。
3800
+ * 2. **create 后必须回读比对**「存下来的业务键 == 送进去的」。实测 `OrgUnit` / `Position`
3801
+ * 的 `code` 元数据标 `auto-generated`,不送就被换成 `OU202608170001` —— 不比对时这件事
3802
+ * **本轮完全无痕**,要到下一轮才以「重复行」爆出来。
3803
+ * 3. **判「已存在」只查自己的索引**。**绝不解析产品错误码/消息**:实测同一类事件产品用
3804
+ * 多种形态上报,`details` 还不是 i18n 的;`error.code` 跨模型糊成同一个值、`details` 里
3805
+ * 方括号那个 token 跨模型不一致 ⇒ **两处都不可机读**。
3806
+ * 4. **产品返回重复类错误 = 索引与现实不一致**(跑前快照过期,或有别的写入者)⇒ 记 `failed`
3807
+ * 并把**原始 `error` 信封原样落台账**,不做归类猜测。
3808
+ * ⚠️ **只有 4xx 才配写 `failed`**:`failed` 断言的是「服务端**什么都没建**」,
3809
+ * 而 `network` / 5xx 时我们**不知道** —— 那一档必须停在 `unknown`。
3810
+ * 5. `sample` 是「小样本先跑」:先跑 N 行 → 保证每一行都被回读查实过 → 报告 →
3811
+ * 由顾问决定是否全量。
3812
+ *
3813
+ * ## 🔴 与计划层的耦合(改本模块前必读)
3814
+ *
3815
+ * ⚠️ **不写「共几处」这个数**(同 {@link BUCKETS} 那条纪律)。下面每一条都点名盯着它的
3816
+ * 那条用例,**表与守卫互为清单**。
3817
+ *
3818
+ * 1. **动作集合**。计划层的 {@link WRITING_ACTIONS} 是**它那一层**用来判「引用方有没有行
3819
+ * 真的会被写」的集合;判成 clean 时**产物里零痕迹** ⇒ 执行器若写了它之外的动作,
3820
+ * 那条 clean 结论会**静默失效**,而没有任何地方会报出来。
3821
+ * 本模块的 {@link EXECUTABLE_ACTIONS} 与它的交集恒为 `{'create'}` —— 是**真子集**,
3822
+ * 只会比计划层假设的写得更少,所以顺序结论照旧成立。
3823
+ * 2. **执行顺序**。计划层的顺序闸结论**只对「照 `models[]` 书写顺序执行」成立**,
3824
+ * 重排之后不适用。本模块严格按 `plan.models` 的顺序、每个模型内按 waves 升序、
3825
+ * 波内按给定行序执行,**不重排**。
3826
+ * 3. **引用档**。计划层的 {@link RESOLVE_FROM} 被切成两半:{@link RESOLVABLE_REFS}
3827
+ * (换得出 id,放行)与 {@link UNRESOLVABLE_REFS}(换不出,逐档给下一步)。
3828
+ * 🔴 **判据用前者**(allow-list,未知即拒),后者只供 hint —— 极性与耦合 1 一致。
3829
+ * 守卫**双向**盯着「两半的并 == 计划层的取值域、且互不相交」:少跟一档就红,
3830
+ * 不会再静默放行。
3831
+ */
3832
+
3833
+ /**
3834
+ * 本模块会发出的全部 problem code。
3835
+ *
3836
+ * 守法沿用计划层:守卫拿源码里 `problem('…')` 的第一个字面量双向对着,少一个 / 多一个都红。
3837
+ */
3838
+ declare const APPLY_PROBLEM_CODES: readonly ["PLAN_NOT_CLEAN", "PLAN_MAPPING_MISMATCH", "PLAN_ROW_KEY_ARITY_MISMATCH", "PLAN_ROW_KEY_INVALID", "ACTION_NOT_EXECUTABLE", "REF_UNRESOLVED", "CREATE_REJECTED", "BUSINESS_KEY_NOT_ROUND_TRIPPED", "READBACK_FAILED", "CREATE_OUTCOME_UNKNOWN", "PARENT_NOT_WRITTEN", "SAMPLE_VERIFY_FAILED", "ROW_QUARANTINED", "LEASE_HEARTBEAT_FAILED"];
3839
+ type ApplyProblemCode = (typeof APPLY_PROBLEM_CODES)[number];
3840
+ /**
3841
+ * 🔴 报告的**分档**清单 —— 每一行恰好落进其中一档,各档之和 == 计划行数。
3842
+ *
3843
+ * 这是这个概念的**单一来源**。
3844
+ * 🔴 **这里不写「共几档」这个数**:散在多处的那个数,加一档时只会改到其中一处,
3845
+ * 另外几处一个字都不用改就变成了假的,而没有任何东西会红。
3846
+ * ⇒ 档的**清单**是本数组,档的**个数**不写进任何一句散文。
3847
+ *
3848
+ * | 档 | 意思 | 发过请求吗 |
3849
+ * |---|---|---|
3850
+ * | `created` | 这一轮建成了 | 是 |
3851
+ * | `skipped` | 计划判的是 `skip`(命中既存)| 否 |
3852
+ * | `already` | 计划判的是 `create`,但**台账**说它已经建成/跳过了 | 否 |
3853
+ * | `writeFailed` | 明确失败:产品拒绝(4xx),**或**本轮建完按业务键回读查不到 | 是 |
3854
+ * | `unverified` | **不知道**:回读问不出来 / network·5xx,台账停在 `unknown` | 是 |
3855
+ * | `blocked` | 上游(父行)没写成,这一行的引用换不出 id | 否 |
3856
+ * | `quarantined` | **台账**说它上一轮就中毒了 ⇒ 本轮停手等人(零请求)| 否 |
3857
+ * | `notAttempted` | `sample` 名额用完 / 本轮已中止 | 否 |
3858
+ * | `wouldCreate` | `dryRun` 下「会建」的行 | 否 |
3859
+ *
3860
+ * 🔴 **报告的 `writeFailed` 档与台账的 `failed` 状态不是同一件事**:本轮「建完查不回来」
3861
+ * 的行进**报告**的 `writeFailed` 档,而它的**台账**状态是 `quarantined`;报告的
3862
+ * `quarantined` 档只装**上一轮**就已经中毒、本轮一发请求都不发的行。
3863
+ * ⚠️ 台账状态 `failed` 与回读判词 `ReadbackResult.status === 'failed'` **仍然共用**
3864
+ * 这个字符串 —— 那是**已知的第二处同名**,至今没有动它。
3865
+ */
3866
+ declare const BUCKETS: readonly ["created", "skipped", "already", "writeFailed", "unverified", "blocked", "quarantined", "notAttempted", "wouldCreate"];
3867
+ /** 入参/前提不成立,执行不了。形态与 `JournalError` 一致。 */
3868
+ declare class ApplyPremiseError extends Error {
3869
+ readonly reason: string;
3870
+ readonly detail: string;
3871
+ readonly hint: string;
3872
+ constructor(reason: string, detail: string, hint?: string);
3873
+ }
3874
+ /**
3875
+ * 本模块自己的不变量被破坏了 —— **代码 bug,不是数据问题**,所以不走 problems。
3876
+ *
3877
+ * 与 `PlanInvariantError` 同款:走到这里说明上游给的东西与它自己的契约矛盾,
3878
+ * 继续走下去会往客户库里写一个说不清来历的 payload。
3879
+ */
3880
+ declare class ApplyInvariantError extends Error {
3881
+ constructor(message: string);
3882
+ }
3883
+ /**
3884
+ * 一条执行期问题。**全都是硬失败**,本模块不产出「建议」档。
3885
+ *
3886
+ * - `row` —— 源表行号(`RowPlan.row`);跨行的问题是 `null`;
3887
+ * - `rawError` —— 产品错误信封**原样**。🔴 **不做归类猜测**:实测 `error.code` 与
3888
+ * `details` 里的方括号 token **两处都不可机读**,读出来的任何「结论」都是编的。
3889
+ */
3890
+ interface ApplyProblem {
3891
+ code: ApplyProblemCode;
3892
+ model: string;
3893
+ row: number | null;
3894
+ key: readonly string[] | null;
3895
+ message: string;
3896
+ hint: string;
3897
+ rawError?: unknown;
3898
+ }
3899
+ interface ModelApply {
3900
+ model: string;
3901
+ rows: number;
3902
+ created: number;
3903
+ skipped: number;
3904
+ already: number;
3905
+ writeFailed: number;
3906
+ unverified: number;
3907
+ blocked: number;
3908
+ quarantined: number;
3909
+ notAttempted: number;
3910
+ wouldCreate: number;
3911
+ requests: number;
3912
+ }
3913
+ /**
3914
+ * 一轮执行的结果。分档计数的语义见 {@link BUCKETS} 那张表。
3915
+ *
3916
+ * - `executed` —— 有没有进入执行阶段(前置闸拦下时是 `false`,此时**零请求**);
3917
+ * - `aborted` —— 中止原因;`null` = 没有中止(**不是**「成功」,看计数);
3918
+ * - `requests` —— 本轮实际发出的**写**请求数(回读不计,它在 `readbacks` 里)。
3919
+ */
3920
+ interface ApplyReport {
3921
+ version: number;
3922
+ roundId: string;
3923
+ dryRun: boolean;
3924
+ sample: number | null;
3925
+ executed: boolean;
3926
+ aborted: string | null;
3927
+ models: ModelApply[];
3928
+ created: number;
3929
+ skipped: number;
3930
+ already: number;
3931
+ writeFailed: number;
3932
+ unverified: number;
3933
+ blocked: number;
3934
+ quarantined: number;
3935
+ notAttempted: number;
3936
+ wouldCreate: number;
3937
+ requests: number;
3938
+ readbacks: number;
3939
+ problems: ApplyProblem[];
3940
+ }
3941
+ /** 写请求只要 `post` 这一个能力,就只声明这一个(与回读那一侧同形)。 */
3942
+ interface WriteClient extends ReadbackClient {
3943
+ post(path: string, body: unknown): Promise<Outcome>;
3944
+ }
3945
+ /** {@link applyPlan} 的可选项。 */
3946
+ interface ApplyOptions {
3947
+ /** 🔴 **默认 `true`** —— 忘了传参不许变成一次真实写入。 */
3948
+ dryRun?: boolean;
3949
+ /** 只处理前 N 行「需要发请求」的行,并对建成的每一行**回读复验**。 */
3950
+ sample?: number | null;
3951
+ /** 每一行真的花掉了一次请求之后调一次,无参。生产上它是 `Lease.heartbeatIfDue`。 */
3952
+ onRequestSpent?: (() => void) | null;
3953
+ }
3954
+ /**
3955
+ * 按计划把行写进系统。**默认 `dryRun = true`**。
3956
+ *
3957
+ * - `client` —— 写走 `POST /api/models/{M}`,回读也走它;
3958
+ * - `plan` —— 计划层的 `ImportPlan`;
3959
+ * - `mapping` —— **必须是算这份计划时用的那一份**。
3960
+ * 🔴 **前置闸只对得上两格**,别读成「对过了」:① 模型清单**有序相等**;
3961
+ * ② 每个模型的 `businessKey.**fields**` 相等。**除这两格之外,工件里的一切**改了本闸
3962
+ * 都**一条都报不出来** —— 列映射 / `valueMap` / 常量 / `source.file` / `source.sheet` /
3963
+ * `onExisting` / `headerRow`,以及 `businessKey.**sourceColumns**`(它长在 `businessKey`
3964
+ * 内部,最容易被读成「整个 businessKey 都比过了」)。而请求体是从**计划里的 `fields`**
3965
+ * 拼的,写出去的就是上一版口径。⚠️ 这一格是**结构上对不出来**,不是「这一轮没查」:
3966
+ * `mapping` 在本模块**只**被 {@link preflight} 用(执行期一个字节都不再看工件),
3967
+ * 且计划里没有工件指纹。⇒ **工件改过就重新跑一次 plan**;
3968
+ * - `journal` —— 写前落账 + 续跑判定都靠它;
3969
+ * - `onRequestSpent` —— **每一行真的花掉了一次请求之后调一次**。
3970
+ * 🔴 **驱动它的是「行」,不是「波」**:波 = 自引用树的层级,**没有自引用的模型整表就是
3971
+ * 一波**,所以「波与波之间盖章」在那一档等于整轮只盖一次 —— 一个只在够快时才成立的
3972
+ * 保证,不是保证。行是本模块**推进的最小单位**,它才是「还在动」的证据。
3973
+ * 🔴 **不起后台线程**:线程会把「主线程卡在一次 30 秒的请求里」这件事遮住 ——
3974
+ * 心跳照发,而实际上什么进展都没有。**谁在推进谁就该盖章。**
3975
+ * 🔴 **「花掉一次请求」不是「写成一行」**:产品 4xx 拒了那一行、或者续跑时这一行只发了
3976
+ * 一次回读 —— 都**没有写成任何东西**,而钩子照调。**这是对的**:心跳要答的是
3977
+ * 「我还在推进吗」,不是「我建成了几行」。⚠️ **一发请求都没出去的行不调**
3978
+ * (`skip` / 台账说已建成 / 名额用完 / dry-run 的 wouldCreate / 被父行挡住)——
3979
+ * 那几档不是推进。**这张档位清单是唯一的一份。**
3980
+ * ⚠️ **节流不在这一层**:本模块**不知道**租约的时间参数,多久盖一次由
3981
+ * `Lease.heartbeatIfDue` 自己判。
3982
+ * 🔴 **它抛 {@link LeaseViolation} ⇒ 当场中止整轮**,**其后一发写请求都不发**
3983
+ * (判在行循环里,不是波与波之间):心跳挂了还接着写,等于把「我还是唯一写者」
3984
+ * **假设**成立。其余异常**不接**(回调自己有 bug 时,吞掉只会让它变成一次静默的双写)。
3985
+ *
3986
+ * 前提级问题抛 {@link ApplyPremiseError},自身不变量被破抛 {@link ApplyInvariantError}
3987
+ * (那是代码 bug,不是数据问题)。
3988
+ */
3989
+ declare function applyPlan(client: WriteClient, plan: ImportPlan, mapping: Mapping, journal: Journal, options?: ApplyOptions): Promise<ApplyReport>;
3990
+ /**
3991
+ * `ApplyReport` → JSON 形状(供 CLI / 手工跑批打印,**不落盘**)。
3992
+ *
3993
+ * ⚠️ 键名逐字与 Python 侧对齐 —— 同一份产物两边都能被同一段脚本读。
3994
+ */
3995
+ declare function applyReportToJson(report: ApplyReport): Record<string, unknown>;
3996
+ /** 给顾问看的一段话(缩进版 JSON —— 现场只有终端)。 */
3997
+ declare function applyReportText(report: ApplyReport): string;
3998
+
3999
+ /** 同源。 */
4000
+ declare const VERDICT_SAME = "same";
4001
+ /** 不同源。 */
4002
+ declare const VERDICT_DIVERGED = "diverged";
4003
+ /** 比不了 —— 🔴 **不是**「比过了、一样」。 */
4004
+ declare const VERDICT_INCOMPARABLE = "incomparable";
4005
+ declare const VERDICTS$2: readonly ["same", "diverged", "incomparable"];
4006
+ type DriftVerdictName = (typeof VERDICTS$2)[number];
4007
+ declare const CAUSE_INCOMPLETE_CURRENT = "incomplete-current";
4008
+ declare const INCOMPARABLE_CAUSES: readonly ["plan-has-no-baseline", "baseline-not-on-disk", "fingerprint-unreadable", "incomplete-recorded", "incomplete-current"];
4009
+ type IncomparableCause = (typeof INCOMPARABLE_CAUSES)[number];
4010
+ /**
4011
+ * 放行开关的**唯一字面量**。判词里要点它的名,CLI 注册参数时也用它 ——
4012
+ * 两处各写一个字符串,改了名就会长出「判词教人敲一个不存在的参数」。
4013
+ */
4014
+ declare const FORCE_STALE_FLAG = "--force-stale";
4015
+ interface DriftVerdict {
4016
+ verdict: DriftVerdictName;
4017
+ /** 门分量里不相等的那几个(⊆ {@link GATE_COMPONENTS})。 */
4018
+ gateDiffs: readonly string[];
4019
+ /** compare 给的 `incomplete:` 条目,原样。 */
4020
+ incomplete: readonly string[];
4021
+ /** 非门上报项(`capabilities` 落这里)。 */
4022
+ advisory: readonly string[];
4023
+ /** ⊆ {@link INCOMPARABLE_CAUSES};非 incomparable 时恒空。 */
4024
+ causes: readonly string[];
4025
+ /** `<租户段>/<sourceKey段>`,读不到时 `null`。 */
4026
+ baseline: string | null;
4027
+ /** 给人的判词,含成因与出路。 */
4028
+ message: string;
4029
+ }
4030
+ /**
4031
+ * `baselineRef` → 盘上那份基线目录。→ `[目录, 成因]`;成功时成因是 `null`。
4032
+ *
4033
+ * 🔴 **两道越界闸只写在这里**:抄两份的表现是一处收紧了另一处没收,而那等于没收。
4034
+ * ① 拒 `..` 分量与绝对路径(`\` 与 `/` **都**当分隔符 —— `a/..\b` 这种形态在只认 `/`
4035
+ * 的实现里恒返 false);② 拒 resolve 之后落在 `recon/` 之外。
4036
+ * 越界与「目录不在」同归 {@link CAUSE_BASELINE_NOT_ON_DISK}:两者的出路是同一条。
4037
+ */
4038
+ declare function resolveBaselineDir(outRoot: string, baselineRef: string | null): [string | null, IncomparableCause | null];
4039
+ /**
4040
+ * → `[旧指纹, 装载成因]`。成功时成因是 `null`;失败时指纹是 `null`。
4041
+ *
4042
+ * `baselineRef` = `<租户段>/<sourceKey段>`(`plan` 写进 `import-plan.json` 的那一串)。
4043
+ *
4044
+ * 🔴 **路径越界一律拒**:`baselineRef` 来自一份**文件**,而文件是可以被手改、也可以是
4045
+ * 别的机器上算出来再拷过来的。
4046
+ */
4047
+ declare function loadRecordedFingerprint(outRoot: string, baselineRef: string | null): [Record<string, unknown> | null, IncomparableCause | null];
4048
+ /**
4049
+ * 三档判据。**纯函数**:不发请求、不读盘。
4050
+ *
4051
+ * ```
4052
+ * loadCause 非 null → INCOMPARABLE(成因 = loadCause)
4053
+ * gateDiffs 非空 → DIVERGED # 🔴 即使同时有 incomplete
4054
+ * incomplete 非空 → INCOMPARABLE(成因从 incomplete 项现推)
4055
+ * 否则 → SAME(advisory 照样上报,不改档)
4056
+ * ```
4057
+ *
4058
+ * 🔴 **`gateDiffs` 与 `incomplete` 同时非空时判 `diverged`,不判 `incomparable`**:
4059
+ * `diverged` 已经是硬停这一档,「另外还有几格没查成」不会让结论变软;反过来判成
4060
+ * `incomparable` 就把一条**已经查实**的不相等降格成「不知道」。
4061
+ *
4062
+ * 🔴 **`loadCause` 非 null 时前提级短路**:装载都没成功,`recorded` 是 `null`,
4063
+ * 这时再去比一遍就是在废墟上出结论。四个 diff 字段一律留空 —— 那是实话:这一轮**一格都没比**。
4064
+ */
4065
+ declare function judgeDrift(recorded: unknown, current: unknown, options?: {
4066
+ baseline?: string | null;
4067
+ loadCause?: IncomparableCause | null;
4068
+ }): DriftVerdict;
4069
+ declare const DRY_RUN_NOTE: string;
4070
+ declare const WAIVER_REPLAY = "\u26A0\uFE0F \u8FD9\u4E2A work \u76EE\u5F55\u91CC\u5DF2\u6709 `{flag}` \u653E\u884C\u8BB0\u5F55\uFF1A{detail}";
4071
+ /** 漂移被判成该拦而未放行时抛它。 */
4072
+ declare class DriftDetected extends Error {
4073
+ readonly verdict: DriftVerdict;
4074
+ constructor(verdict: DriftVerdict);
4075
+ }
4076
+ /**
4077
+ * 台账里那一笔放行 → 一行给人看的话。**只转述字段,不重判**。
4078
+ *
4079
+ * 🔴 转述而不重判是有理由的:这一笔说的是**上一轮**的事,而这一轮的判据算的是此刻的环境。
4080
+ * 拿这一轮的结论去改写上一轮那一笔,等于让上一轮写出去的行改口。
4081
+ */
4082
+ declare function describeWaiver(waiver: Waiver): string;
4083
+ /**
4084
+ * 处置一档判决。→ `null`(同源,无话可说)或一段要打给人看的 WARN 文本。
4085
+ *
4086
+ * 该拦而未放行 ⇒ 抛 {@link DriftDetected}。
4087
+ * `forced` 且真的绕过了闸 ⇒ 往台账追一笔 waiver(`dryRun` 时不写,只返文本)。
4088
+ *
4089
+ * 三支的次序**不许调**:
4090
+ *
4091
+ * 1. `same` 排最前 —— 同源那一轮压根没有闸可绕,`forced` 在这里只该得到一句「没用上」。
4092
+ * 把它排在 `forced` 之后就会写出一笔**没有放行发生**的 waiver,而台账里那一笔的语义是
4093
+ * 「这一批行是带着漂移写的」。
4094
+ * 2. `dryRun` 排在拦与放行之前 —— 干跑一发写请求都不发,**没有可拦的东西,也没有可放行的
4095
+ * 东西**。判词照打,退出码不动。
4096
+ * 3. 最后才是「拦 / 放行」那一格。
4097
+ */
4098
+ declare function enforceDriftGate(verdict: DriftVerdict, options: {
4099
+ journal: Journal;
4100
+ roundId: string;
4101
+ forced: boolean;
4102
+ dryRun: boolean;
4103
+ }): string | null;
4104
+
4105
+ /** 前提的编号。ASCII,给程序判;给人看的话在 `detail` 里。 */
4106
+ declare const PREMISE_JOURNAL_ON_DISK = "journal-on-disk";
4107
+ declare const PREMISE_JOURNAL_HAS_ENTRIES = "journal-has-entries";
4108
+ declare const PREMISE_PLAN_READABLE = "plan-readable";
4109
+ declare const PREMISE_CODES: readonly ["journal-on-disk", "journal-has-entries", "plan-readable"];
4110
+ /** 🔴 未成立的前提**逐条以它开头**,成立的那几条一个字都不带它。 */
4111
+ declare const PREMISE_UNMET = "\u524D\u63D0\u672A\u6210\u7ACB";
4112
+ /**
4113
+ * 一条前提 —— 它成不成立,以及不成立时该看哪里。
4114
+ *
4115
+ * `detail` 在**不成立**时以 {@link PREMISE_UNMET} 开头、成立时是空串;
4116
+ * `hint` 原样转载被判方给的下一步(读计划那一档来自 `PlanReadError.hint`),
4117
+ * 本模块不另写一套文案。
4118
+ */
4119
+ interface Premise$1 {
4120
+ code: string;
4121
+ ok: boolean;
4122
+ detail: string;
4123
+ hint: string;
4124
+ }
4125
+ /**
4126
+ * 计划里有、台账里一条记录都没有的一行。
4127
+ *
4128
+ * `action` 是计划给这一行判的动作(取值域是计划层的 `ROW_ACTIONS`,与台账状态是
4129
+ * **两个域**,别拿去和 `byStatus` 的档对齐)。
4130
+ */
4131
+ interface PlannedRow {
4132
+ model: string;
4133
+ key: readonly string[];
4134
+ sourceRowId: number;
4135
+ action: string;
4136
+ }
4137
+ /** 一次交付(= 一个 work 目录)的证据聚合。字段的取舍理由见模块头注释。 */
4138
+ interface DeliveryRun {
4139
+ workDir: string;
4140
+ journalExists: boolean;
4141
+ rounds: readonly string[];
4142
+ rows: readonly Entry[];
4143
+ byStatus: Record<Status, number>;
4144
+ unresolved: readonly Entry[];
4145
+ waivers: readonly Waiver[];
4146
+ /** 🔴 `null` = 够不到答案(计划读不回来);`[]` = 真的一件没落下。 */
4147
+ plannedWithoutRecord: readonly PlannedRow[] | null;
4148
+ premises: readonly Premise$1[];
4149
+ notCovered: readonly string[];
4150
+ label: string;
4151
+ }
4152
+ /**
4153
+ * 把一个 **work 目录**聚合成一份可签字的基线。
4154
+ *
4155
+ * `workDir` 收的是 work 目录(`journal.jsonl` 与 `import-plan.json` 同在其中),
4156
+ * 与 `Journal.load` / `readImportPlan` / `acquireLease` 是同一个入参形态。
4157
+ *
4158
+ * 🔴 台账读不回来时**照抛不误**(`JournalError`):那一档行级判据一次都没跑过。
4159
+ * 台账不在 / 为空 / 计划读不回来这三档**不抛**,记进 `premises`。
4160
+ */
4161
+ declare function buildDeliveryRun(workDir: string): DeliveryRun;
4162
+ /** 供守卫现算:本模块交出去的对象里有没有裸 `roundId` 字段。 */
4163
+ declare function deliveryRunFields(run: DeliveryRun): string[];
4164
+
4165
+ declare const VERDICTS$1: readonly ["confirmed", "id-differs", "contradicts", "unattributed", "invisible", "unreadable", "not-checked"];
4166
+ type Verdict = (typeof VERDICTS$1)[number];
4167
+ /**
4168
+ * 🔴 三张表**是一个划分**(并集 == 全集、两两不交),由
4169
+ * `test_the_three_shelves_are_a_partition_of_the_verdict_domain` 断关系。
4170
+ * 新加一档判定必须有人决定它上哪张架子 —— 漏登的那一档会同时不在任何一张表里,
4171
+ * 而「不在任何表里」在计数上与「一条都没有」同形。
4172
+ */
4173
+ declare const AGREEING_VERDICTS: readonly ["confirmed"];
4174
+ /**
4175
+ * 逐档的人话。🔴 `invisible` 那一格是本层的承重物:它必须**自己**说出三种成因,
4176
+ * 否则读的人会把它读成「没写进去」——而那正是本层要挡的那个假绿。
4177
+ */
4178
+ declare const VERDICT_WORDS: Record<string, string>;
4179
+ /**
4180
+ * 前提的编号。
4181
+ * 🔴 前三条是**零网络**的闸:任一条不成立就一发请求都不发。身份那一条**不是闸** ——
4182
+ * 不知道用谁的身份读的,照样读得回来,只是那份结论说不出口径。
4183
+ */
4184
+ declare const PREMISE_ROWS_TO_CHECK = "journal-rows-to-check";
4185
+ declare const PREMISE_KEY_FIELDS = "plan-business-key-fields";
4186
+ declare const PREMISE_CLIENT = "client-on-hand";
4187
+ declare const PREMISE_IDENTITY = "readback-identity";
4188
+ /**
4189
+ * 🔴 **拦网的那三条**(顺序即判定顺序)。它与 {@link PREMISE_CODES} 的关系由
4190
+ * `test_the_gates_that_stop_the_network_are_the_zero_network_ones` 断住:
4191
+ * 身份那一条**不在**里面,是有意的。
4192
+ */
4193
+ declare const NETWORK_GATES: readonly ["journal-rows-to-check", "plan-business-key-fields", "client-on-hand"];
4194
+ /**
4195
+ * 一行的对账结论:账本说的 · 库里现在的 · 判定。
4196
+ *
4197
+ * - `ledgerStatus` / `ledgerServerId` —— **账本说的**,原样来自第一层的 `rows`
4198
+ * (取值域是台账状态,与 `verdict` 是两个域,别对齐着读)。
4199
+ * 🔴 它是**台账口径 · 历轮累计**:`(model, businessKey)` 最后一条赢,
4200
+ * 说的**不是**「这一轮这一行怎么了」;
4201
+ * - `serverNow` —— **库里现在的**:按这个业务键此刻看得见的那一行的 id。
4202
+ * 🔴 它是 `null` 时**有三种意思**(查不到 / 问不出来 / 根本没查),
4203
+ * 这三者由 `verdict` 分开 —— 别拿这一格当「在不在」的判据;
4204
+ * - `verdict` —— 取值域是本模块的 {@link VERDICTS}。
4205
+ */
4206
+ interface Finding {
4207
+ sourceRowId: number;
4208
+ model: string;
4209
+ businessKey: readonly string[];
4210
+ ledgerStatus: string;
4211
+ ledgerServerId: string | null;
4212
+ serverNow: string | null;
4213
+ verdict: Verdict;
4214
+ }
4215
+ /**
4216
+ * 一个模型这一轮回读到了什么。
4217
+ *
4218
+ * - `keyFields` —— `null` = 盘上那份计划里问不出它(⇒ 这个模型名下每一行 not-checked);
4219
+ * - `visibleTotal` —— 服务端报的 `totalElements`。🔴 **裁剪后**的可见总数,不是这张表的行数;
4220
+ * - `pages` —— 本轮为这个模型实际发出的取数请求数;
4221
+ * - `problem` —— 索引没建成时,把那一层给的判词(reason / message / hint)**原样**带出来。
4222
+ * 本层不重新分类:重新判会把前提级问题降成内容级。
4223
+ */
4224
+ interface ModelReadback {
4225
+ model: string;
4226
+ keyFields: readonly string[] | null;
4227
+ visibleTotal: number | null;
4228
+ pages: number | null;
4229
+ problem: string | null;
4230
+ }
4231
+ /**
4232
+ * 一次对账。🔴 `findings` / `byVerdict` / `differences` / `undecided` / `models`
4233
+ * 五格**同进同退**:拦网的三条前提任一不成立时它们**全是 `null`**(这一问没有答案),
4234
+ * 而不是空表 —— 空表与「查过、一条都没有」逐字同形。
4235
+ *
4236
+ * ⚠️ **`differences` / `undecided` 今天在生产侧零读者**:渲染层**故意**不读它们,
4237
+ * 而是拿 {@link AGREEING_VERDICTS} 的**补集**现算 —— 那是更稳的写法(加一档 verdict 时
4238
+ * 补集自动跟上,两份预分好的元组不会)。这两格因此是**给下游可归档产物预留的出口**,
4239
+ * 靠「三张架子是一个划分」那条守卫钉着它们与补集一致。
4240
+ * 🔴 按 ADR-120 §2(YAGNI / delete-on-supersede):那一刀落地时要么**接上**,
4241
+ * 要么**删掉** —— 不许它们以「零实现扩展点」的形态长期留着。
4242
+ */
4243
+ interface Reconciliation {
4244
+ workDir: string;
4245
+ label: string;
4246
+ identity: ReconIdentity | null;
4247
+ findings: readonly Finding[] | null;
4248
+ byVerdict: Record<string, number> | null;
4249
+ differences: readonly Finding[] | null;
4250
+ undecided: readonly Finding[] | null;
4251
+ models: readonly ModelReadback[] | null;
4252
+ premises: readonly Premise$1[];
4253
+ notCovered: readonly string[];
4254
+ /**
4255
+ * 🔴 与 `notCovered` **同形**:逐档人话必须**随对象走**,渲染层拿到这个对象就自动带着,
4256
+ * 不必「记得」另外 import 一份。它恰恰是那条防假绿的承重物(`invisible` 那格)。
4257
+ */
4258
+ verdictWords: Record<string, string>;
4259
+ }
4260
+ /** 回读要的能力就 `post` 一个。 */
4261
+ type ReconcileClient = KeyIndexClient & {
4262
+ identity?: ReconIdentity | null;
4263
+ };
4264
+ /**
4265
+ * 「这一份是用谁的身份读的」说得出来吗 —— **判值,不判对象空不空**。
4266
+ *
4267
+ * 锚点与 `doctor` 那条 identity 判据**同一个**(`tenantId` 非空):生产唯一造客户端的
4268
+ * 地方恒发四个键,服务端没给 user 时发出来的是四个**空值**。拿「对象非空」当判据
4269
+ * 会把那一档判成「知道了」。
4270
+ */
4271
+ declare function identityKnown(identity: unknown): boolean;
4272
+ /**
4273
+ * 把第一层那份基线**对到库上**。
4274
+ *
4275
+ * `client` 给 `null` 表示**手上没有服务端**(气隙 / 没有凭据):那一档
4276
+ * **一发请求都不发**,五格结论全是 `null`,并由前提说明为什么。
4277
+ *
4278
+ * 🔴 零网络的三条前提**判完**才碰网({@link NETWORK_GATES})。
4279
+ */
4280
+ declare function buildReconciliation(delivery: DeliveryRun, client: ReconcileClient | null): Promise<Reconciliation>;
4281
+ /**
4282
+ * **这一趟根本没问过库** —— 只出台账那一层时用它。
4283
+ *
4284
+ * 与 `buildReconciliation(delivery, null)` **不是同一件事**,两者都要留着:
4285
+ *
4286
+ * - `buildReconciliation(..., null)` = 「**我要对账,可手上没有客户端**」⇒
4287
+ * `client-on-hand` 这条前提**未成立**,rc 因此落前提级。它守的是
4288
+ * 「客户端建失败之后静默退化成气隙口径」那一档;
4289
+ * - 本函数 = 「**我压根没打算问**」⇒ 联网那几条前提**不进这份 premise 集**。
4290
+ * 🔴 这不是第三种状态:`premises` 只是**更短**(空的),
4291
+ * 而「库那一侧没查过」这件事**逐字落在 `notCovered` 里**,用的就是 `WHY_NO_CLIENT`
4292
+ * 那一段 —— 全树唯一逐字写着「这条出路在气隙机器上走不通 …… 也**不**产出一份
4293
+ * 『对账通过』」的地方。前提移走而这段话跟着消失,等于把本层最贵的那格资产
4294
+ * (防假绿)顺手拆掉。
4295
+ *
4296
+ * 🔴 **`premises` 为空就是本档的判据**(`buildReconciliation` 恒发四条),
4297
+ * 渲染层据此把抬头写成「这一趟没问过库」,不必再多一个标志位。
4298
+ */
4299
+ declare function notAsked(delivery: DeliveryRun): Reconciliation;
4300
+ /** 供守卫现算:三张架子对 {@link VERDICTS} 是不是一个划分。 */
4301
+ declare function shelfPartition(): {
4302
+ missing: string[];
4303
+ extra: string[];
4304
+ overlap: string[];
4305
+ };
4306
+
4307
+ /**
4308
+ * `hcm delivery seed verify` 的**命令面**:两层证据 → 一页可签字的纸 + 一个退出码。
4309
+ *
4310
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/cli.py` 里 `_verify_*` 那一族
4311
+ * (ADR-319 刀 11g-4)。行为基线是
4312
+ * `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §6.3。
4313
+ *
4314
+ * ## 为什么判据整个住在 core,而命令层只做接线
4315
+ *
4316
+ * 这一页纸的每一句话都是**判据**,不是排版:「这一趟问过库没有」「这一格是查过没有
4317
+ * 还是这一问没有答案」「哪些行还要人看」。放在命令层就等于让它与引擎那两层各说各的,
4318
+ * 而顾问看到的是命令层这一份。
4319
+ *
4320
+ * ## 三处「空 ≠ 没有」在这一页上各有载体
4321
+ *
4322
+ * - `recon.premises` 空 = **这一趟压根没问库**(`notAsked` 给空集,`buildReconciliation`
4323
+ * 恒发四条)⇒ 抬头自己说出来,代码里没有第二个判据;
4324
+ * - `delivery.plannedWithoutRecord === null` = **这一问没有答案**,不是「一件没落下」;
4325
+ * - `recon.findings === null` = 同上一档,但成因写在第二层的前提里。
4326
+ */
4327
+
4328
+ /**
4329
+ * 🔴 **开关名只写一处**(口径同 `drift.FORCE_STALE_FLAG`):声明它的地方、判词里指路的
4330
+ * 地方、文档守卫读它的地方,说的必须是同一个名字。
4331
+ */
4332
+ declare const LEDGER_ONLY_FLAG = "--ledger-only";
4333
+ /**
4334
+ * 🔴 **段名一处定义**:这几个段名各自**被印两次** —— 一次是段落抬头本身,一次是正文里
4335
+ * 指路的那句「射程见…」/「写在…的最后一条里」。写成两份独立字面量的话**改一处不红**:
4336
+ * 指路那句会指向一个页面上不存在的段名,而顾问按名字在这页纸上 grep 会零命中。
4337
+ */
4338
+ declare const NOT_COVERED_SELF = "\u5DF2\u77E5\u4E0D\u8986\u76D6 \u00B7 \u672C\u547D\u4EE4";
4339
+ declare const NOT_COVERED_LAYER1 = "\u5DF2\u77E5\u4E0D\u8986\u76D6 \u00B7 \u7B2C\u4E00\u5C42";
4340
+ declare const NOT_COVERED_LAYER2 = "\u5DF2\u77E5\u4E0D\u8986\u76D6 \u00B7 \u7B2C\u4E8C\u5C42";
4341
+ /**
4342
+ * 「这台机器连不上客户内网」时的那条出路。
4343
+ *
4344
+ * 🔴 **反极性**:这条出路**只对 `verify` 成立**。挂到别的命令的判词上就是指一条走不通的路
4345
+ * —— `plan` 与 `apply` 没有气隙口径,敲这个开关它们连认都不认。
4346
+ *
4347
+ * 🔴 四格缺一不可,每一格少了都是一种**具体的**误导:开关名(敲什么)· 它给得出什么 ·
4348
+ * 它**给不出**什么 · 别拿它当验收通过。第三格与第四格是这段话里最要紧的两格 ——
4349
+ * 少了它们,人会拿一份从没问过库的产物去签字。
4350
+ */
4351
+ declare function ledgerOnlySignpost(cmd: string): string;
4352
+ interface VerifyArgs {
4353
+ ledgerOnly?: boolean;
4354
+ }
4355
+ /**
4356
+ * 这一次调用会不会发请求 —— `false` = 要 `--host` 与口令。
4357
+ *
4358
+ * 🔴 **按意图分派,不按「手上有没有客户端」**。拿「有没有客户端」去猜「操作员想不想问库」,
4359
+ * 后果是 fail-open:没敲任何离线开关、客户端恰好缺席、台账干净 ⇒ **rc=0 且首行说
4360
+ * 「这一趟没问过库」**,与真联网那一趟的退出码完全相同 —— 库一个字没问,退出码说一切正常。
4361
+ */
4362
+ declare function isZeroNetwork(args: VerifyArgs): boolean;
4363
+ /**
4364
+ * 这一趟**问过库没有** —— 判据是第二层发没发前提,不是它答出了什么。
4365
+ *
4366
+ * `notAsked` 给的是**空的** premise 集(联网那几条压根不进这一趟),而
4367
+ * `buildReconciliation` 恒发四条。⇒ 「空」就是「没问过」,代码里没有第二个判据。
4368
+ */
4369
+ declare function askedTheDatabase(recon: Reconciliation): boolean;
4370
+ /**
4371
+ * → `[台账那一侧, 计划那一侧, 对账那一侧]` 三组**要人看的行**。
4372
+ *
4373
+ * 🔴 三组的判据都是**关系**,不是名单:
4374
+ * - 台账那一侧问 {@link NEXT_STEP}(那张表是「这一行接下来该做什么」的**唯一**判据):
4375
+ * 下一步不是 {@link STEP_NOTHING} 的,就是还没了结的行。这样写,`quarantined`
4376
+ * 落进来**不靠这里记得它** —— 它在那张表里是 `stop`。台账新加一档时这里跟着变,
4377
+ * 不必有人回来补名单;
4378
+ * - 计划那一侧就是 `plannedWithoutRecord`(`null` 时那一问没有答案,由前提顶 rc=2,
4379
+ * 走不到这里);
4380
+ * - 对账那一侧问 {@link AGREEING_VERDICTS} 那张架子的**补集**(差异 ∪ 分不清)——
4381
+ * 三张架子是一个划分,所以「不在对得上那张架子上」把新加的判定档也一并收进来。
4382
+ */
4383
+ declare function verifyAttention(delivery: DeliveryRun, recon: Reconciliation): [Entry[], PlannedRow[], Finding[]];
4384
+ /**
4385
+ * 给 FDE 签字看的那一页。**逐格说清「这一问有没有答案」**。
4386
+ *
4387
+ * 🔴 空表与 `null` 在这里**分两种话说**:`[]` 是「查过、一条都没有」,`null` 是
4388
+ * 「这一问没有答案」—— 两者在计数上同形(都是 0),而下一步完全不同。
4389
+ */
4390
+ declare function verifyText(delivery: DeliveryRun, recon: Reconciliation): string;
4391
+ /**
4392
+ * 两层证据 → 一个退出码。**说结构,不枚举成因**(口径同 `planRc`)。
4393
+ *
4394
+ * ```
4395
+ * 任意一条前提未成立(两层 premises 并集里有 ok=false) ⇒ 2
4396
+ * 否则 verifyAttention 三组里有任何一行 ⇒ 1
4397
+ * 否则 ⇒ 0
4398
+ * ```
4399
+ *
4400
+ * 🔴 **次序不能反**,理由与 `planRc` 逐字相同:前提未成立的意思是「这份清单建立在一个
4401
+ * 不成立的前提上」,给 1 会让顾问去逐条修一份**不作数**的清单。
4402
+ *
4403
+ * 🔴 **rc 只对「这一趟问过的那几问」成立**:`--ledger-only` 那一趟**没问过库**,
4404
+ * 联网那几条前提因此**不进它的 premise 集**(`notAsked`),于是它的 rc 由台账与计划那一层
4405
+ * 决定 —— 台账干净就是 0。⚠️ 这样一来「rc 分得开两趟」这个区分物就没了,所以
4406
+ * **产物第一行必须自己说得清**这一趟问过什么,并且「库那一侧一个字都没问」由
4407
+ * `notCovered` 逐字承载。三件缺一,一份没查过库的证据就会长得和验收通过一模一样。
4408
+ */
4409
+ declare function verifyRc(delivery: DeliveryRun, recon: Reconciliation): number;
4410
+
3206
4411
  interface RiskFromArtifactsOptions {
3207
4412
  sourceDir?: string;
3208
4413
  exemptions?: BuildRiskOptions['exemptions'];
@@ -3872,4 +5077,4 @@ interface TriageRoundResult {
3872
5077
  */
3873
5078
  declare function runTriageRound(probe: ReconProbe, artifactsDir: string, entriesIn: readonly TriageEntry[]): Promise<TriageRoundResult>;
3874
5079
 
3875
- export { ACLASS_EMPTY_WHY, ACLASS_KINDS, ARTIFACT_ROOT, ARTIFACT_SUFFIXES, ARTIFACT_WORDING, AUTH_INFO_PATH, type Aclass, type AclassKind, type AclassProblem, type ActionHttpMethod, type ActionInput, type ActionMeta, type ActionResult, type ActionScope, type AdminResetPasswordRequest, type AdminResetPasswordResult, type AnyStreamEvent, type ApprovalConfirmPayload, type ApprovalRejectPayload, type AttachmentMeta, type AuthScheme, BLIND_SPOTS, BLOCKING_CODES, type BaselineCandidate, type BootstrapReconcileResult, type BootstrapTenantRequest, type BootstrapTenantResult, CARRIER_BLIND, CARRIER_HIT, CARRIER_KEYS, CARRIER_LABELS, CARRIER_MISS, CARRIER_UNAVAILABLE, CARRIER_VERDICTS, CHANNELS, CHANNEL_ACLASS, CHANNEL_ARTIFACT, CHANNEL_NO_PROBE, CHANNEL_REGISTERED_IS_ACLASS, CHANNEL_UNREGISTERED, CLASS_REASONS, CLASS_SCOPE, type CacheClearResult, type CacheStats, type CarrierKey, type CarrierResult, type CarrierVerdict, type CarryOver, type ChangePasswordInput, type Channel, type ChironCategory, type ChironManifest, type ChironSkill, type ChironSkillFile, type ChironStage, type ClearMetaCacheOpts, CliError, CliErrorCode, type CliErrorInit, type ClientAuthContext, type ClientCredentialsInput, type ConnectionMessage, type ControlChannelEnvelope, type ConversationListItem, type ConversationListResult, type ConversationState, type CreateResult, type CreatedConversation, DATA_PACKAGE_BLIND_NOTE, DEBT_PREFIX, DEBT_UNKNOWN, DEFAULT_AGENT_ID, DEFAULT_SESSION_TTL_SECONDS, DOCTOR_ANCHORS, type DescribeOpts, type DoctorAnchor, type DoctorCheck, type DoctorReport, ENDPOINT_PREFIXES, ENTRY_SCOPE, ENUM_ELEMENT_KEYS, EXTENSION_SOURCE_HEADER, type EnvConfig, ExitCode, FACTS_REASONS, FOLDED_NOTE, FULLWIDTH_ALNUM_RANGES, type FactsProblem, type FieldMeta, type Fingerprint, type Fixture, type FormatOptions, GAP_CJK_INSIDE_LONGER_RUN, GAP_NOISE_TOKEN, GAP_REASONS, GATE_COMPONENTS, type Gap, type GlobalConfig, HcmClient, type HcmClientOpts, type HttpClientOptions, IMPORT_PLAN_FILE, INIT_EXIT_CODES, type IdentityMeta, type ImportClient, type ImportOptions, type ImportPlan, type ImportResult, type InitExitName, type InteractionAnswerPayload, type InteractionRequest, type InteractionResolved, KIT_CARRY_OVER_KEY, KIT_CRAWLED_AT_FILE, LEDGER_MISSING_WORD, LayoutContainmentError, type ListTenantMetaOpts, type LoginOutcome, MANIFEST_PATH, MAPPING_ARTIFACT_VERSION, MAPPING_FILE, MAX_MANIFEST_PAGES, MAX_SOURCE_PROBES, META_PATH, MINI_CONTEXT_FILE, MINI_CONTEXT_KIND, MINI_CONTEXT_VERSION, MINI_PULL_MANIFEST_FILE, MINI_REMOTE_ROOT, MINI_STATE_DIR, MODELS_PATH, MappingArtifactError, MappingError, Matcher, type MessageClass, type MessageCreatePayload, type MessageStreamHandle, type MigrationSummary, type MiniFileSnapshot, type MiniInitArgs, type MiniLocalFile, type MiniLocalStatus, type MiniPreviewTarget, type MiniProjectContext, type MiniPullArgs, type MiniPullManifest, type MiniPullResult, type MiniPushArgs, type MiniPushConflict, type MiniPushOperation, type MiniPushPlanItem, type MiniPushResult, type MiniSmokeCheckArgs, type MiniSmokeFetch, type MiniSmokeFetchResponse, type MiniSmokeResult, type MiniSmokeTargetKind, type MiniSmokeTargetResult, type MiniStatusEntry, type MiniSurface, type MiniTemplateArgs, type MiniTemplateKind, type MiniValidationResult, type MiniVerifyAgentReport, type MiniVerifyBrowserAcceptance, type MiniVerifyChangedFile, type MiniVerifyNextAction, type MiniVerifyPlan, type MiniVerifyPreviewUrl, type MiniVerifyReport, type MiniVerifySummary, type MiniWritableTemplateConfig, type ModelDescription, type ModelEntry, type ModelQueryDsl, OFFLINE_COMMANDS, type OneShotOpts, type OneShotResult, type OneShotToolCall, type Outcome, type OutputFormat, PASSWORD_CHANGE_REQUIRED, PREMISE_REASONS, PREMISE_REGISTRY_REASONS, PROACTIVE_REFRESH_MARGIN_SECONDS, PROBE_MARK_PREFIX, PRODUCT_RELATIVE_SHAPES, PRODUCT_STATE_WORDS, PROTOCOL_FACTS, type PairingLoginInput, type ParsedPlaceholder, type PasswordChangeChallenge, type PasswordLoginInput, type PatLoginInput, type PlanProblem, PlanReadError, type Premise, type Principal, type ProfileConfig, type ProtocolFact, type QueryResult, RC_DECIDING_FIELDS, REASON_DUPLICATE_TOKEN, REASON_EMPTY, REASON_NO_ENTRIES, REASON_PROBE_ABSENT, REASON_PROBE_SHAPE, REASON_PROBE_UNVERIFIED, REASON_UNREAD, RECON_DIRNAME, RECON_SEGMENTS_BELOW_ROOT, RED_REASONS, REGISTRY_REASONS, REGISTRY_SCOPE, REQUIRED_SECTIONS, RISK_FILE, ROUND_ANCHORS, ROUND_EXIT_CODES, ROUND_STAMPED_PRODUCTS, ROUND_STATES, ROUND_SUBCOMMAND, ROUND_WARNINGS, ROUND_WARNING_FALLBACK, type ReconIdentity, ReconLayout, type ReconProbe, type ReconSummary, type Red, RefStore, type RefreshInput, type RelationMeta, type RemoveResult, type ResponseCompletedPayload, type ResponseFailedPayload, type ResponsePartDeltaPayload, type ResponseStartedPayload, type ResumeSummary, type ResumeTurn, type Risk, type RiskProblem, type RoundResult, type RoundState, type RowResult, type RowStatus, SCOPES, SDK_VERSION, SEGMENT_SEPARATOR, type SaveMetaResult, type ScanOptions, type ScanResult, type SeedPathArgs, type SendMessageOpts, type SettingItem, type SettingWrite, type StreamCancelPayload, type StreamCommand, type StreamCommandEnvelope, type StreamCommandType, type StreamEventEnvelope, type StreamEventType, CONFIG as TRIAGE_CONFIG, GAP as TRIAGE_GAP, VERDICTS as TRIAGE_VERDICTS, TargetModelNotFound, type TaskProgressPayload, type TenantMetaEntry, type TimelineItemLite, type TokenRecord, TokenStore, type ToolCallFailedPayload, type ToolCallResultPayload, type ToolCallStartedPayload, type TriageEntry, type TriageProblem, type TriageProblemRow, type TriageRoundResult, type TriageVerdict, type V4RenderSink, type V4StreamEventType, VERSION_PATH, WARNED_ROUND_STATES, WORKSPACES_PATH, WORK_DIRNAME, type WorkspaceFileContent, type WorkspaceFileItem, type WorkspaceFileListResult, WsClient, type WsClientOpts, absoluteDownloadUrl, adminResetPassword, archiveDir, artifactReason, assertSafeReferencePath, assertSafeSkillFilePath, assertSafeSkillId, baselineRoundPremise, bootstrapTenant, boundedFind, buildAnswer, buildCarrierResult, buildConfirm, buildInterrupt, buildMiniAppTemplateFiles, buildMiniPreviewTargets, buildMiniVerifyAgentReport, buildReject, buildResumeSummary, buildSteer, camelizeKeys, changePassword, checkCoherence, checkGaps, checkPremise, checkReds, cjkRunAt, classifyMessage, clearMetaCache, clearModelCache, compareFingerprint, computeFingerprint, computeReconSourceKey, conversationStateFile, covered, create, createConversation, createHttpClient, createV4Reducer, createWorkspaceFile, credentialsFile, defaultDownloadDir, defaultMiniRequiredScopes, deleteEnv, deleteIdentity, deleteTenantMeta, deleteWorkspaceFile, deriveAclass, deriveNamelessToolLabel, describePrincipal, detectDelegationPause, detectDirectInteractionPending, detectPasswordChangeChallenge, discardedColumnLines, displayWidth, downloadDocument, endpointsIn, ensureSessionFresh, envDir, envFile, envsDir, exitCode, exitCodeFor, extractNextSteps, factsIndex, fetchConversationTimeline, fetchConversationTimelineStrict, fetchRecentConversations, fetchReconIdentity, fetchSkillCatalog, fetchSkillFile, fetchSkillMarkdown, fetchSkillReference, filterByStage, findLastAssistantSeq, flattenSkills, foldConfusables, foldedNoteFor, formatMiniVerifyReport, formatObject, formatRows, fromAxiosError, getCacheStats, getMiniStatus, getSettingDomain, getTenantMeta, globalConfigFile, guessMimeType, hcmConfigDir, httpProbe, identitiesDir, identityDir, identityMetaFile, inGap, inferEnvName, inferMiniWritableTemplateOptionsFromModel, initMiniAppProject, inspectRound, isCjk, isDelegationToolName, isReadOnly, isServerSlidingSession, listEnvs, listIdentities, listModels, listProfiles, listTenantMeta, listWorkspaceFiles, loadConversationState, loadEnv, loadExemptions, loadGlobalConfig, loadIdentity, loadProfile, loadProtocolFacts, loadWorkspaceFileContent, loginClientCredentials, loginPairing, loginPassword, loginPat, matchSkills, migrateLegacyProfiles, modelEntries, modelKeys, needsRefresh, newRoundId, normalize, normalizeReferences, oneShot, parseConfirmToolName, parseFixture, parseInteractionRequest, parseInteractionResolved, parsePlaceholder, parseSettingAssignment, parseSkillFrontmatter, parseSkillRequirements, patchSettingDomain, planFromArtifacts, planProblemLines, planRc, planSummaryLine, probeAll, probeExtensionSource, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readBusinessKeyFields, readImportPlan, readMiniContext, readPullManifest, refreshToken, remove, renderRound, renderTriage, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveAllSkillsInstallOrder, resolveChironBase, resolveRefs, resolveSkillInstallOrder, riskFromArtifacts, roundAge, roundWarning, runDoctor, runImport, runMiniSmokeChecks, runRecon, runTriageRound, safeSegment, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, scan, seedBaselines, seedMappingPath, seedWorkDir, segmentsOf, sendMessageAndStream, snakeToCamel, tenantSegment, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, unguardedKinds, update, uploadDocument, validateMiniProject, writeImportPlan, writeRisk };
5080
+ export { ACLASS_EMPTY_WHY, ACLASS_KINDS, ADVISORY_CODES, AGREEING_VERDICTS, APPLY_CAVEAT, APPLY_PROBLEM_CODES, ARTIFACT_ROOT, ARTIFACT_SUFFIXES, ARTIFACT_WORDING, AUTH_INFO_PATH, type Aclass, type AclassKind, type AclassProblem, type ActionHttpMethod, type ActionInput, type ActionMeta, type ActionResult, type ActionScope, type AdminResetPasswordRequest, type AdminResetPasswordResult, type AnyStreamEvent, ApplyInvariantError, ApplyPremiseError, type ApplyReport, type ApprovalConfirmPayload, type ApprovalRejectPayload, type AttachmentMeta, type AuthScheme, BLIND_SPOTS, BLOCKING_CODES, BUCKETS, type BaselineCandidate, type BootstrapReconcileResult, type BootstrapTenantRequest, type BootstrapTenantResult, CARRIER_BLIND, CARRIER_HIT, CARRIER_KEYS, CARRIER_LABELS, CARRIER_MISS, CARRIER_UNAVAILABLE, CARRIER_VERDICTS, CAUSE_INCOMPLETE_CURRENT, CHANNELS, CHANNEL_ACLASS, CHANNEL_ARTIFACT, CHANNEL_NO_PROBE, CHANNEL_REGISTERED_IS_ACLASS, CHANNEL_UNREGISTERED, CHECK_GROUPS, CLASS_REASONS, CLASS_SCOPE, type CacheClearResult, type CacheStats, type CarrierKey, type CarrierResult, type CarrierVerdict, type CarryOver, type ChangePasswordInput, type Channel, type ChironCategory, type ChironManifest, type ChironSkill, type ChironSkillFile, type ChironStage, type ClearMetaCacheOpts, CliError, CliErrorCode, type CliErrorInit, type ClientAuthContext, type ClientCredentialsInput, type ConnectionMessage, type ControlChannelEnvelope, type ConversationListItem, type ConversationListResult, type ConversationState, type CreateResult, type CreatedConversation, DATA_PACKAGE_BLIND_NOTE, DEBT_PREFIX, DEBT_UNKNOWN, DEFAULT_AGENT_ID, DEFAULT_SESSION_TTL_SECONDS, PREMISE_CODES as DELIVERY_PREMISE_CODES, DOCTOR_ANCHORS, DRY_RUN_NOTE, DRY_RUN_TAIL, type Premise$1 as DeliveryPremise, type DeliveryRun, type DescribeOpts, type DoctorAnchor, type DoctorCheck, type DoctorReport, DriftDetected, ENDPOINT_PREFIXES, ENTRY_SCOPE, ENUM_ELEMENT_KEYS, EXEMPTIBLE_CODES, EXEMPTION_CODES, EXEMPTION_REQUIRED_KEYS, EXTENSION_SOURCE_HEADER, type EnvConfig, ExitCode, FACTS_REASONS, FOLDED_NOTE, FORCE_STALE_FLAG, FORCE_STALE_FLAG_TEXT, FULLWIDTH_ALNUM_RANGES, type FactsProblem, type FieldMeta, type Finding, type Fingerprint, type Fixture, type FormatOptions, GAP_CJK_INSIDE_LONGER_RUN, GAP_NOISE_TOKEN, GAP_REASONS, GATE_COMPONENTS, type Gap, type GlobalConfig, HcmClient, type HcmClientOpts, type HttpClientOptions, IMPORT_PLAN_FILE, INIT_EXIT_CODES, type IdentityMeta, type ImportClient, type ImportOptions, type ImportPlan, type ImportResult, type InitExitName, type InteractionAnswerPayload, type InteractionRequest, type InteractionResolved, JOURNAL_FILE, JOURNAL_STOP_KINDS, JOURNAL_STOP_UNKNOWN, Journal, JournalError, KIT_CARRY_OVER_KEY, KIT_CRAWLED_AT_FILE, LEASE_FILE, LEDGER_MISSING_WORD, LEDGER_ONLY_FLAG, LayoutContainmentError, Lease, LeaseViolation, type ListTenantMetaOpts, type LoginOutcome, MANIFEST_PATH, MAPPING_ARTIFACT_VERSION, MAPPING_FILE, MAX_MANIFEST_PAGES, MAX_SOURCE_PROBES, META_PATH, MINI_CONTEXT_FILE, MINI_CONTEXT_KIND, MINI_CONTEXT_VERSION, MINI_PULL_MANIFEST_FILE, MINI_REMOTE_ROOT, MINI_STATE_DIR, MODELS_PATH, MappingArtifactError, MappingError, Matcher, type MessageClass, type MessageCreatePayload, type MessageStreamHandle, type MigrationSummary, type MiniFileSnapshot, type MiniInitArgs, type MiniLocalFile, type MiniLocalStatus, type MiniPreviewTarget, type MiniProjectContext, type MiniPullArgs, type MiniPullManifest, type MiniPullResult, type MiniPushArgs, type MiniPushConflict, type MiniPushOperation, type MiniPushPlanItem, type MiniPushResult, type MiniSmokeCheckArgs, type MiniSmokeFetch, type MiniSmokeFetchResponse, type MiniSmokeResult, type MiniSmokeTargetKind, type MiniSmokeTargetResult, type MiniStatusEntry, type MiniSurface, type MiniTemplateArgs, type MiniTemplateKind, type MiniValidationResult, type MiniVerifyAgentReport, type MiniVerifyBrowserAcceptance, type MiniVerifyChangedFile, type MiniVerifyNextAction, type MiniVerifyPlan, type MiniVerifyPreviewUrl, type MiniVerifyReport, type MiniVerifySummary, type MiniWritableTemplateConfig, type ModelDescription, type ModelEntry, type ModelQueryDsl, NETWORK_GATES, NEXT_STEP, NOT_COVERED_LAYER1, NOT_COVERED_LAYER2, NOT_COVERED_SELF, OFFLINE_COMMANDS, type OneShotOpts, type OneShotResult, type OneShotToolCall, type Outcome, type OutputFormat, PASSWORD_CHANGE_REQUIRED, PREMISE_CLIENT, PREMISE_IDENTITY, PREMISE_JOURNAL_HAS_ENTRIES, PREMISE_JOURNAL_ON_DISK, PREMISE_KEY_FIELDS, PREMISE_PLAN_READABLE, PREMISE_REASONS, PREMISE_REGISTRY_REASONS, PREMISE_ROWS_TO_CHECK, PREMISE_UNMET, PROACTIVE_REFRESH_MARGIN_SECONDS, PROBE_MARK_PREFIX, PRODUCT_RELATIVE_SHAPES, PRODUCT_STATE_WORDS, PROTOCOL_FACTS, type PairingLoginInput, type ParsedPlaceholder, type PasswordChangeChallenge, type PasswordLoginInput, type PatLoginInput, type PlanProblem, PlanReadError, type PlannedRow, type Premise, type Principal, type ProfileConfig, type ProtocolFact, type QueryResult, RC_DECIDING_FIELDS, RC_DECIDING_REPORT_FIELDS, REASON_DUPLICATE_TOKEN, REASON_EMPTY, REASON_NO_ENTRIES, REASON_PROBE_ABSENT, REASON_PROBE_SHAPE, REASON_PROBE_UNVERIFIED, REASON_UNREAD, VERDICTS$1 as RECONCILE_VERDICTS, RECON_DIRNAME, RECON_SEGMENTS_BELOW_ROOT, RED_REASONS, REGISTRY_REASONS, REGISTRY_SCOPE, REQUIRED_SECTIONS, RISK_CODES, RISK_FILE, ROUND_ANCHORS, ROUND_EXIT_CODES, ROUND_STAMPED_PRODUCTS, ROUND_STATES, ROUND_SUBCOMMAND, ROUND_WARNINGS, ROUND_WARNING_FALLBACK, type ReconIdentity, ReconLayout, type ReconProbe, type ReconSummary, type Reconciliation, type Red, RefStore, type RefreshInput, type RelationMeta, type RemoveResult, type ResponseCompletedPayload, type ResponseFailedPayload, type ResponsePartDeltaPayload, type ResponseStartedPayload, type ResumeSummary, type ResumeTurn, type Risk, type RiskProblem, type RoundResult, type RoundState, type RowResult, type RowStatus, SCOPES, SDK_VERSION, SEGMENT_SEPARATOR, STATUSES, STEP_NOTHING, STEP_STOP, type SaveMetaResult, type ScanOptions, type ScanResult, type SeedPathArgs, type SendMessageOpts, type SettingItem, type SettingWrite, type StreamCancelPayload, type StreamCommand, type StreamCommandEnvelope, type StreamCommandType, type StreamEventEnvelope, type StreamEventType, CONFIG as TRIAGE_CONFIG, GAP as TRIAGE_GAP, VERDICTS as TRIAGE_VERDICTS, TargetModelNotFound, type TaskProgressPayload, type TenantMetaEntry, type TimelineItemLite, type TokenRecord, TokenStore, type ToolCallFailedPayload, type ToolCallResultPayload, type ToolCallStartedPayload, type TriageEntry, type TriageProblem, type TriageProblemRow, type TriageRoundResult, type TriageVerdict, type V4RenderSink, type V4StreamEventType, VERDICTS$2 as VERDICTS, VERDICT_DIVERGED, VERDICT_INCOMPARABLE, VERDICT_SAME, VERDICT_WORDS, VERSION_PATH, WAIVER_REPLAY, WARNED_ROUND_STATES, WORKSPACES_PATH, WORK_DIRNAME, type WorkspaceFileContent, type WorkspaceFileItem, type WorkspaceFileListResult, WsClient, type WsClientOpts, absoluteDownloadUrl, acquireLease, adminResetPassword, applyPlan, applyRc, applyReportText, applyReportToJson, archiveDir, artifactReason, askedTheDatabase, assertSafeReferencePath, assertSafeSkillFilePath, assertSafeSkillId, baselineRoundPremise, bootstrapTenant, boundedFind, buildAnswer, buildCarrierResult, buildConfirm, buildDeliveryRun, buildInterrupt, buildMiniAppTemplateFiles, buildMiniPreviewTargets, buildMiniVerifyAgentReport, buildReconciliation, buildReject, buildResumeSummary, buildSteer, camelizeKeys, changePassword, checkCoherence, checkGaps, checkPremise, checkReds, cjkRunAt, classifyMessage, clearMetaCache, clearModelCache, compareFingerprint, computeFingerprint, computeReconSourceKey, conversationStateFile, covered, create, createConversation, createHttpClient, createV4Reducer, createWorkspaceFile, credentialsFile, defaultDownloadDir, defaultMiniRequiredScopes, deleteEnv, deleteIdentity, deleteTenantMeta, deleteWorkspaceFile, deliveryRunFields, deriveAclass, deriveNamelessToolLabel, describePrincipal, describeWaiver, detectDelegationPause, detectDirectInteractionPending, detectPasswordChangeChallenge, discardedColumnLines, displayWidth, downloadDocument, endpointsIn, enforceDriftGate, ensureSessionFresh, envDir, envFile, envsDir, existingJournalStop, exitCode, exitCodeFor, extractNextSteps, factsIndex, fetchConversationTimeline, fetchConversationTimelineStrict, fetchRecentConversations, fetchReconIdentity, fetchSkillCatalog, fetchSkillFile, fetchSkillMarkdown, fetchSkillReference, filterByStage, findLastAssistantSeq, flattenSkills, foldConfusables, foldedNoteFor, formatMiniVerifyReport, formatObject, formatRows, fromAxiosError, getCacheStats, getMiniStatus, getSettingDomain, getTenantMeta, globalConfigFile, guessMimeType, hcmConfigDir, httpProbe, identitiesDir, identityDir, identityKnown, identityMetaFile, inGap, inferEnvName, inferMiniWritableTemplateOptionsFromModel, initMiniAppProject, inspectRound, isCjk, isDelegationToolName, isReadOnly, isServerSlidingSession, isZeroNetwork, journalNote, judgeDrift, ledgerOnlySignpost, listEnvs, listIdentities, listModels, listProfiles, listTenantMeta, listWorkspaceFiles, loadConversationState, loadEnv, loadExemptions, loadGlobalConfig, loadIdentity, loadMapping, loadProfile, loadProtocolFacts, loadRecordedFingerprint, loadWorkspaceFileContent, loginClientCredentials, loginPairing, loginPassword, loginPat, matchSkills, migrateLegacyProfiles, modelEntries, modelKeys, needsRefresh, newRoundId, normalize, normalizeReferences, notAsked, oneShot, parseConfirmToolName, parseFixture, parseInteractionRequest, parseInteractionResolved, parsePlaceholder, parseSettingAssignment, parseSkillFrontmatter, parseSkillRequirements, patchSettingDomain, planFromArtifacts, planProblemLines, planRc, planSummaryLine, planVsBaselinePremise, probeAll, probeExtensionSource, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readBusinessKeyFields, readImportPlan, readMiniContext, readPullManifest, refreshToken, remove, renderRound, renderTriage, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveAllSkillsInstallOrder, resolveBaselineDir, resolveChironBase, resolveRefs, resolveSkillInstallOrder, riskFromArtifacts, roundAge, roundWarning, runDoctor, runImport, runMiniSmokeChecks, runRecon, runTriageRound, safeSegment, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, scan, seedBaselines, seedMappingPath, seedWorkDir, segmentsOf, sendMessageAndStream, shelfPartition, snakeToCamel, tenantSegment, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, unguardedKinds, update, uploadDocument, validateMiniProject, verifyAttention, verifyRc, verifyText, writeImportPlan, writeRisk };