@hcmai/sdk 0.3.14 → 0.3.16

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
@@ -2372,6 +2372,861 @@ interface ReconSummary {
2372
2372
  }
2373
2373
  declare function runRecon(probe: ReconProbe, layout: ReconLayout, opts?: RunReconOptions): Promise<ReconSummary>;
2374
2374
 
2375
+ /**
2376
+ * 业务键批量索引:一次把 `{业务键元组: 目标行 id}` 拉全,供 T4 做行级 create/update 判定。
2377
+ *
2378
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/index.py`(ADR-319 刀 11a-2)。
2379
+ * 行为基线是 `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.2 的 34 条。
2380
+ *
2381
+ * ## 为什么是批量,不是逐行回读
2382
+ *
2383
+ * 底账 §九实测(`localhost:8087` / 租户 13):批量索引 `OrgUnit`(10619) + `Employee`(6777)
2384
+ * 用 `size=2000` 共 10 个请求约 22s;逐行回读同样两张表要 **17396** 个请求,
2385
+ * 现场 200ms RTT 下**仅往返就 ≈58 分钟**。页大小几乎不影响墙钟(22 次请求与 2 次请求
2386
+ * 都是 ~16s)⇒ 主导成本是服务端逐行处理(约 1.5ms/行),不是往返。
2387
+ *
2388
+ * ## 🔴 本模块的承重物是那条自证断言,不是取数
2389
+ *
2390
+ * 中石油 POC 的参照实现(`cnpc_lib.py` 的 `load_index`)用 `row.get(key)` 取键:
2391
+ * **键名写错时每行取到 `None` → 全被跳过 → 索引为空 → 每行都判成「不存在,创建」
2392
+ * → 静默产生全量重复。**
2393
+ *
2394
+ * 而服务端**不会**替你逮住这个手误:底账 §四在同一 build 上量到三个入参的处置不一致 ——
2395
+ * `filter` / `orders` 对不存在的字段名硬失败 `FIELD_NOT_FOUND`,唯独 **`fields` HTTP 200
2396
+ * 静默丢弃**。本模块正是靠 `fields` 投影取值的,所以「要了就一定拿得到」这个假设不成立。
2397
+ * ⇒ 索引载入后必须断言 `rows.size === total`,不成立就**硬失败**,不许降级成逐行回读。
2398
+ *
2399
+ * ## 🔴 失败必须归对因
2400
+ *
2401
+ * `rows.size !== total` **同时**是三种病的症状(键名错 / 键有 null / 键不唯一),
2402
+ * 文案必须并列这三种。但另有几种病是**能被单独量到的**,混进那条三选一就成了栽赃:
2403
+ *
2404
+ * | reason | 量到的事实 | 与业务键有关吗 |
2405
+ * |---|---|---|
2406
+ * | `pagination-repeat` | 同一个行 `id` 被投递了不止一次(**同页内**与**跨页**两种都算) | 无关,是分页 |
2407
+ * | `rows-incomplete` | 取回行数 ≠ `totalElements` | 无关,是取数 |
2408
+ * | `row-id-missing` | 有行没有可用的字符串 `id` | 无关,是响应 |
2409
+ * | `key-count-mismatch` | 上面三条都排除掉之后,索引条数仍 ≠ 总行数 | **是**,且三选一分不出来 |
2410
+ *
2411
+ * 顺序不能换:分页重复会让 `received > total`,先判 `rows-incomplete` 就会把
2412
+ * 「服务端忽略了 page」说成「取数不全」。
2413
+ *
2414
+ * ## 🔴 移植中 TS 与 Python 的三处真实分岔(不是省略,是语言事实不同)
2415
+ *
2416
+ * 1. **`1.0` 在 TS 里拦不住**:JSON 解析后 `1.0` 与 `1` 是同一个 `number`,
2417
+ * `Number.isInteger(1.0)` 为真。Python 侧拒 `float` 的理由(「该匹配 `"1"` 还是 `"1.0"`?」)
2418
+ * 在 TS 这一层**已经被 JSON 层抹平**,无从判起。所以本模块拒的是**非整数**(`1.5`),
2419
+ * 并留一条用例把「`1.0` 不可区分」这个事实钉住 —— 免得下一个人照 Python 契约
2420
+ * 「补一条 float 守卫」,写出一个恒不触发的分支。
2421
+ * 2. **`isinstance(True, int)` 那个坑 TS 没有**:`typeof true === 'boolean'`,
2422
+ * 布尔天然不落进数字分支。守卫照留(形态仍要拒),但**理由不同**,别照抄 Python 的注释。
2423
+ * 3. **键元组不能直接当 Map 键**:JS 的 `Map` 对数组按引用比,Python 的 tuple 按值比。
2424
+ * 本模块把键元组编码成字符串再入 Map,**且必须是长度前缀编码**——
2425
+ * 用分隔符 join 会让 `["AB","C"]` 与 `["A","BC"]` 撞成同一个键(拿 U+0000 当分隔符
2426
+ * 也不安全,服务端返回的字符串里完全可以有它)。撞键的后果是**静默错索引**,
2427
+ * 与本模块存在的理由同型。
2428
+ */
2429
+
2430
+ /** 本模块只要 `post` 这一个能力,就只声明这一个。 */
2431
+ interface KeyIndexClient {
2432
+ post(path: string, body: unknown): Promise<Outcome>;
2433
+ }
2434
+ interface KeyIndex {
2435
+ /**
2436
+ * `{编码后的业务键元组 → 目标行 id}`。编码走 {@link encodeKeyTuple},
2437
+ * 要还原成原始元组用 {@link decodeKeyTuple}。
2438
+ */
2439
+ rows: Map<string, string>;
2440
+ /** 服务端报的 `totalElements`。 */
2441
+ total: number;
2442
+ /** 本轮**实际发出**的 `list/dsl` 请求数(没有单独的计数探针)。 */
2443
+ pages: number;
2444
+ }
2445
+ /**
2446
+ * 把 `model` 上 `keyFields` 这个(复合)业务键的既存行一次性索引下来。
2447
+ *
2448
+ * 成功返回 {@link KeyIndex};任何一档前提不成立都抛 {@link IndexPremiseError},**不降级、不静默**。
2449
+ *
2450
+ * 🔴 能拿到返回值,就意味着 `rows.size === total` 已经成立过——不成立时构造不出来。
2451
+ * 下游不必(也不该)再判一次「索引是不是空的就当全新」。
2452
+ */
2453
+ declare function loadKeyIndex(client: KeyIndexClient, model: unknown, keyFields: unknown, pageSize?: unknown): Promise<KeyIndex>;
2454
+
2455
+ /**
2456
+ * 映射工件 `work/mapping.json` —— 契约、装载与校验。
2457
+ *
2458
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/artifacts.py`(ADR-319 刀 11a-3)。
2459
+ * 行为基线是 `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.4 的 80 条。
2460
+ *
2461
+ * 顾问手写一份工件,说清「客户这张表的哪一列,进 HCM 的哪个字段」。本模块把它读进来
2462
+ * ({@link loadMapping})、按工件去读源表({@link scanSources})、再拿**真实表头**校验它
2463
+ * ({@link validateMapping})。
2464
+ *
2465
+ * ## 这一层为什么值得单独守:手写件的错法**都不报错**
2466
+ *
2467
+ * - 列名少一个字 / 用了繁体 → 整列取到空 → 业务键全空 → 全部行撞成一行;
2468
+ * - `onExisting` 忘了写 → 悄悄当成 `skip` → 本该更新的行被跳过,顾问以为导完了;
2469
+ * - 同一个字段被两处赋值 → 后写覆盖先写,两处**各自看都是对的**;
2470
+ * - `valueMap` 的键写错 → 那份值映射永远不触发,而**它本想翻译的那个字段**照旧把原值灌进库里。
2471
+ *
2472
+ * 每一条的共同点是:**不报错**。所以本模块的每条校验只有一个目的 ——
2473
+ * 把静默的错法变成响亮的错法。
2474
+ *
2475
+ * ## 三个函数的分工
2476
+ *
2477
+ * | 函数 | 失败形态 | 为什么 |
2478
+ * |---|---|---|
2479
+ * | {@link loadMapping} | 抛 {@link MappingError} | 结构 / 类型错了,工件**根本用不了**;带着它往下走,后面每条校验都是级联噪音 |
2480
+ * | {@link scanSources} | 收集 {@link Problem} | 一张表读不成,另外几张仍然该校验完 —— 现场跑一次要看到全部问题 |
2481
+ * | {@link validateMapping} | 返回 `Problem[]` | 语义问题要一次报全,顾问一轮改完 |
2482
+ *
2483
+ * 🔴 **`businessKey` / `onExisting` 缺失是 `Problem` 不是 `MappingError`** ——「没写」正是
2484
+ * 最要报的那类错,把它做成抛异常会让顾问一次只看到一条。
2485
+ *
2486
+ * ## 🔴 前提级 vs 内容级:本模块的承重结构
2487
+ *
2488
+ * problem 分两类,由 {@link PREMISE_CODES} 一张表定死,`Problem.kind` 查表得出:
2489
+ *
2490
+ * - **前提级(`premise`)**:手上这份表头到底是不是这条 entry 的、业务键那一对能不能采信、
2491
+ * 这张表读没读成。**任一前提没成立,依赖它的内容级校验一律不执行**,
2492
+ * 并且必然附一条 `CONTENT_CHECKS_SKIPPED` 说清**哪几组没跑**。
2493
+ * - **内容级(`content`)**:真把工件内容看过之后看出来的问题。
2494
+ *
2495
+ * 前提没成立却照跑内容级校验,产出的是**建立在废墟上的结论**。三次实际形态(都不是设想):
2496
+ * ① 同一模型两条 entry 时,第二条的列名拿**第一条那张表**的表头去核 —— 代码从没拿到过第二张表的表头;
2497
+ * ② `businessKey` 两边不等长时代码主动不采信它,随后说「没有任何地方给这个字段赋值」——
2498
+ * 把「我没采信」说成「你没写」;③ 同名模型直接覆盖,先读到那张表的行整表消失。
2499
+ *
2500
+ * ## 🔴 GC3:「校验过、没问题」与「没校验」不许同形
2501
+ *
2502
+ * - {@link validateMapping} 返回 `[]` = **校验过、干净**。前提没成立时返回的是具名的前提级
2503
+ * problem + `CONTENT_CHECKS_SKIPPED`,**不是** `[]`。
2504
+ * - {@link scanSources} 里,读不成的模型在 `headers` / `rows` 里**根本没有键**;
2505
+ * 读到了但一行数据都没有是 `rows.get(model) == []`;同名模型的第二张表**不读、不覆盖**。
2506
+ *
2507
+ * ## 🔴 下游拼 payload 只许走 {@link assignments}
2508
+ *
2509
+ * `businessKey` / `columns` / `constants` / `valueMap` 是**四个**平行字段,
2510
+ * 最自然的写法「遍历 columns + constants」会把**业务键字段整个漏掉** —— 建出来的行没有
2511
+ * `code`,服务端补流水码,下一轮回读匹配不上,于是再建一遍(底账 §五 实测)。
2512
+ * **重复行、幂等失效,全程零报错。** 同一个论证对第四个字段一样成立(值映射)。
2513
+ *
2514
+ * ## 🔴 移植中 TS 与 Python 的分岔
2515
+ *
2516
+ * 1. **JSON 读取自己写**({@link parseJsonSource}):`JSON.parse` 既检不出重复键、
2517
+ * 又会把数字样式的键提到最前,两个失真都是静默的。理由见那个文件的头注释。
2518
+ * ⇒ 本模块内部一律拿 `Map` 表示 JSON 对象。
2519
+ * 2. **`scanSources` 是 async**:TS 侧 `readTable` 是 async(zip 层用 yauzl 流式读),
2520
+ * Python 侧是同步。这是刀 11a-1 就记过的一处签名偏离,不是本刀新引入的。
2521
+ * 3. **`headers` / `rows` 用 `Map` 而不是普通对象**:模型名是客户数据里来的字符串,
2522
+ * 普通对象上 `"constructor"` / `"__proto__"` 这类键会撞上原型链 —— `model in headers`
2523
+ * 对 `"constructor"` 恒为真,于是「没拿到表头」这条前提级判据会被静默跳过。
2524
+ * Python 的 dict 没有这个问题。
2525
+ */
2526
+
2527
+ /**
2528
+ * 本模块会发出的全部 problem code。它自己也被
2529
+ * `test_the_declared_problem_codes_are_exactly_the_ones_the_code_emits` 拿源码里的
2530
+ * 字面量双向对着 —— 少一个(新 code 没人盯它)、多一个(清单里那条早删了)都红。
2531
+ */
2532
+ declare const PROBLEM_CODES: readonly ["BUSINESS_KEY_MISSING", "BUSINESS_KEY_EMPTY", "BUSINESS_KEY_ARITY_MISMATCH", "BUSINESS_KEY_RESOLVE_BY_FIELD_UNKNOWN", "BUSINESS_KEY_RESOLVE_BY_TARGET_UNUSABLE", "BUSINESS_KEY_RESOLVE_BY_KEY_MISMATCH", "SOURCE_COLUMN_NOT_FOUND", "FIELD_ASSIGNED_TWICE", "ON_EXISTING_REQUIRED", "ON_EXISTING_INVALID", "SOURCE_HEADER_UNKNOWN", "SOURCE_UNREADABLE", "SOURCE_SHADOWED", "SOURCE_SUFFIX_UNSUPPORTED", "SHEET_REQUIRED", "SHEET_NOT_APPLICABLE", "DUPLICATE_MODEL_ENTRY", "VALUE_MAP_FIELD_NOT_ASSIGNED", "VALUE_MAP_HAS_NO_SOURCE_COLUMN", "CONTENT_CHECKS_SKIPPED"];
2533
+ type ProblemCode = (typeof PROBLEM_CODES)[number];
2534
+ /**
2535
+ * 工件结构 / 类型错了,读不下去。
2536
+ *
2537
+ * 与 `SourceError` 同形:`reason` 给程序判、`hint` 给顾问照做,两者都不许省。
2538
+ */
2539
+ declare class MappingError extends Error {
2540
+ readonly reason: string;
2541
+ readonly hint: string;
2542
+ /** 不带 `[reason]` 前缀与 hint 的那半句 —— 上层要原样转述时用。 */
2543
+ readonly detail: string;
2544
+ constructor(reason: string, message: string, hint?: string);
2545
+ }
2546
+
2547
+ /**
2548
+ * 行级导入计划 —— 每一行该建还是该对既存、先建谁、以及三类硬失败。
2549
+ *
2550
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/plan.py`(ADR-319 刀 11b-1,
2551
+ * 只搬**计算核心** `buildImportPlan`;门面与 JSON 落盘/回读在 11b-2)。
2552
+ * 行为基线是 `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.5。
2553
+ *
2554
+ * 上游三层各自回答一件事:源表读出来是什么、哪一列进哪个字段、库里已经有哪些行。
2555
+ * 本模块把三样合起来,产出**执行层照着走就行**的计划。
2556
+ *
2557
+ * ## 为什么必须有行级这一层
2558
+ *
2559
+ * 模型级顺序只能告诉你「OrgUnit 引用了 OrgUnit」,它**决定不了客户 Excel 里哪一行是
2560
+ * 哪一行的父**,也发现不了行级成环、悬挂父、业务键重复。组织树的 `parentId` 是
2561
+ * **同模型行级自引用**,父行必须先于子行写入 —— 这来自数据本身。
2562
+ *
2563
+ * ## 🔴 三类硬失败(都必须在第一次 POST 之前)
2564
+ *
2565
+ * | code | 判据 | 不报会怎样 |
2566
+ * |---|---|---|
2567
+ * | `DUPLICATE_BUSINESS_KEY` | 源表内同一业务键出现 >1 次,报**行号列表** | 幂等的支点不成立:两行抢同一个身份,重跑一次多一份 |
2568
+ * | `DANGLING_PARENT` | 父键**既不在源表行里、也不在既存索引里** | 只查源表会把正常增量导入误判成悬挂父 |
2569
+ * | `ROW_LEVEL_CYCLE` | 行级父子边成环,报**环上的键序列** | 两行互为父子,谁都先建不了,执行层会死等 |
2570
+ *
2571
+ * ## 🔴 `waves[0]` 是「对锚」,不是创建
2572
+ *
2573
+ * 底账 §七实测:不带 `parentId` 建 `OrgUnit` 直接被 `BR_MULTI_ROOT_ORG_UNIT` 拒。
2574
+ * ⇒ 根组织 / 根法人是**既存锚点**,第一波的语义是「把工件里的根**对上**既存行」,
2575
+ * **不发 POST**。所以 `Wave.kind` 是**算出来的**,不是写死的。
2576
+ *
2577
+ * ## 🔴 本模块最危险的一条:没有索引 ≠ 全是新行
2578
+ *
2579
+ * 参照实现(`cnpc_lib.py` 的 `load_index`)的洞:索引取不到 → 每行都判成「不存在,创建」
2580
+ * → **静默产生全量重复**。所以索引缺席时:`existingMatched` / `toCreate` 是 **`null`
2581
+ * 而不是 0**(0 与「查过、一条都没有」同形);每行的 `action` 是 `unknown`;
2582
+ * 悬挂父那条判据**不出结论**;父指针也**什么都不承诺**。
2583
+ *
2584
+ * ## 🔴 承诺也算「断言没拿到的事实」
2585
+ *
2586
+ * 「报错文案断言代码从没拿到过的事实」有第三种形态,**不长得像错误文案**:
2587
+ * **留下一个读者会去等、但永远不会来的后续信号**。初版的 `resolveFrom: 'wave-row'`
2588
+ * 就是 —— 真实组织树整棵都已存在时,10618 行都盖了「父行本轮待创建、稍后回填」。
2589
+ * ⇒ **任何对下游的承诺都要能兑现,先问再说。**
2590
+ *
2591
+ * 写任何一句**面向读者**的话之前,先问这一句(固定检查项):
2592
+ * **「我这句话让读者去找的东西,在这条路径上真的存在吗?」**
2593
+ *
2594
+ * ## 🔴 前提级 vs 内容级(沿用 artifacts 的结构,不是各写一份)
2595
+ *
2596
+ * `kind` 由 {@link PREMISE_CODES} **查表**得出。任一前提不成立,依赖它的那几组判据
2597
+ * **一律不执行**,并且必然附一条 `PLAN_CHECKS_SKIPPED` 说清哪几组没跑。
2598
+ * ⇒ 下游判断方式是「有没有 kind === 'premise' 的 problem」,**不是**数条数。
2599
+ *
2600
+ * ## 🔴 移植中 TS 与 Python 的分岔
2601
+ *
2602
+ * 1. **行键用 {@link encodeKeyTuple} 编码后当 Map 键**:JS 的 `Map` 对数组按引用比。
2603
+ * 与 `key-index` 共用同一个长度前缀编码 —— 两处各写一份编码就是两个键空间,
2604
+ * 而这一层的全部工作就是拿行键去撞索引的键。
2605
+ * 2. **`tables` / `indexes` 用 `Map` 不用普通对象**:模型名来自客户数据,
2606
+ * `'constructor' in obj` 恒为真 ⇒「这张源表没读到」这条前提级判据会被静默跳过。
2607
+ * 3. **重复业务键排序**:Python 对元组直接排序,TS 里逐元素比较(数组没有天然序)。
2608
+ */
2609
+
2610
+ /** 产物文件名。落盘在 11b-2。 */
2611
+ declare const IMPORT_PLAN_FILE = "import-plan.json";
2612
+ /** 本模块会发出的全部 problem code(有自证守卫拿源码里的字面量双向对着)。 */
2613
+ declare const PLAN_PROBLEM_CODES: readonly ["DUPLICATE_BUSINESS_KEY", "DANGLING_PARENT", "ROW_LEVEL_CYCLE", "MODEL_ORDER_CONFLICT", "BUSINESS_KEY_VALUE_MISSING", "BUSINESS_KEY_REFERENCE_UNRESOLVED", "SELF_REFERENCE_UNUSABLE", "EXISTING_INDEX_MISSING", "SOURCE_ROWS_MISSING", "MAPPING_NOT_USABLE", "PLAN_CHECKS_SKIPPED"];
2614
+ type PlanProblemCode = (typeof PLAN_PROBLEM_CODES)[number];
2615
+ /**
2616
+ * `RowRef.resolveFrom` 的取值域。🔴 **自维护**:守卫拿源码里的字面量与本表双向对着,
2617
+ * 并要求每一档**走得到** ——「声明里有、代码永不产出」的那一档按 ADR-120 已删。
2618
+ */
2619
+ declare const RESOLVE_FROM: readonly ["no-parent", "existing-index", "wave-row", "unchecked-no-index", "unresolved-no-index", "ref-key-mismatch", "ref-target-key-space", "ref-not-found"];
2620
+ type ResolveFrom = (typeof RESOLVE_FROM)[number];
2621
+ /** `Wave.kind` 的取值域。守法同 {@link RESOLVE_FROM}(双向 + 可达性)。 */
2622
+ declare const WAVE_KINDS: readonly ["anchor", "create", "mixed", "unknown", "fail"];
2623
+ type WaveKind = (typeof WAVE_KINDS)[number];
2624
+ /**
2625
+ * 一行的动作取值域。🔴 **唯一声明**:`action()` 是它唯一的产出方。
2626
+ *
2627
+ * 🔴 它存在的理由**不是**「再多一张表」:下游要按这个域**逐档**给归宿,
2628
+ * 而在它之前下游拿的判据是 `{行的 action} ∩ WRITING_ACTIONS` —— 求交把**没列到的取值
2629
+ * 静默归进补集**,于是 `unknown`(「没查过既存」)被读成了「这一轮不写」。
2630
+ */
2631
+ declare const ROW_ACTIONS: readonly ["create", "update", "skip", "fail", "unknown"];
2632
+ type RowAction = (typeof ROW_ACTIONS)[number];
2633
+ /**
2634
+ * 一条计划期问题。**全都是硬失败**,本模块不产出「建议」档。
2635
+ * `kind` 由 code 查 {@link PREMISE_CODES} 得出(不手填)。
2636
+ */
2637
+ interface PlanProblem {
2638
+ /**
2639
+ * 🔴 取值域**不止** {@link PLAN_PROBLEM_CODES}:门面早退那一支把工件层的 problem
2640
+ * **原样**转过来(code 与 kind 都不重判 —— 重判会撞上「本模块不认识那些 code」
2641
+ * 这个前提,把前提级降成内容级)。⇒ 这里是两层 code 的并集,
2642
+ * 而 `PLAN_PROBLEM_CODES` 说的是**本模块自己发的那些**。
2643
+ */
2644
+ code: PlanProblemCode | ProblemCode;
2645
+ model: string;
2646
+ message: string;
2647
+ hint: string;
2648
+ kind: 'premise' | 'content';
2649
+ /** `mapping.models[]` 里的下标;跨 entry 的问题是 `null`。 */
2650
+ entry: number | null;
2651
+ }
2652
+ /**
2653
+ * 这一行的某个字段要拿一个业务键去**换 id**。
2654
+ *
2655
+ * `resolveFrom` 是**这个 id 从哪来的**,**每一档都不许合并**:
2656
+ *
2657
+ * - `no-parent` —— 这一行没有父(根行);
2658
+ * - `existing-index` —— 在既存索引里查到了。🔴 **父行在源表里、但它本身已经存在**时
2659
+ * 也走这一档:它这一轮不会被创建,而它的 id 现在就在手上;
2660
+ * - `wave-row` —— 父行**这一轮真的会被创建**,`resolvedId` 恒为 `null`,
2661
+ * 执行层建完 `parentWave` 那一波之后回填;
2662
+ * - `unchecked-no-index` —— **没查过既存**。说不出这个 id 从哪来,
2663
+ * 也不许承诺「稍后会有一次 create」。`parentWave` 照给(排序信息只依赖源表内部的边);
2664
+ * - `unresolved-no-index` —— 非自引用的引用,**本轮没有那个模型的索引**;
2665
+ * - `ref-key-mismatch` —— 那个模型的索引**在**,但它是按**别的键**建的。
2666
+ * 🔴 与上一档分开,是因为下一步动作完全不同:上一档要**加模型**,这一档要**改键**;
2667
+ * - `ref-target-key-space` —— 目标模型的**业务键自己带 `resolveBy`** ⇒ 它的行键与既存
2668
+ * 索引都在**解析后的 id** 空间,而这条边手上是**源表值**,两边永不相等。
2669
+ * 🔴 这一档**重跑不会变**,要动的是数据模型或工件;`ref-not-found` 则是
2670
+ * 「先把目标行导进去再跑一次」。并成一档会同时产出**一句假判词**和
2671
+ * **一条永远不收敛的指令**;
2672
+ * - `ref-not-found` —— 索引在、键也对得上,但这个值**不在既存索引里**。
2673
+ *
2674
+ * 🔴 **头三档之外的每一档都换不出 id**,执行层一律拒。
2675
+ * ⚠️ **这里不写「后几档」这个数** —— 散文里的数一漏跟就成了假话;清单是 {@link RESOLVE_FROM}。
2676
+ */
2677
+ interface RowRef {
2678
+ field: string;
2679
+ model: string;
2680
+ keyField: string;
2681
+ value: unknown;
2682
+ resolvedId: string | null;
2683
+ resolveFrom: ResolveFrom;
2684
+ parentWave: number | null;
2685
+ }
2686
+ /**
2687
+ * 一行的计划。`row` 是**源表行号**(`headerRow + 1 + i`),不是数组下标。
2688
+ *
2689
+ * `action` 的取值域是 {@link ROW_ACTIONS};`unknown` 专给「没有索引、没查过」那一档 ——
2690
+ * 它**不许**退化成 `create`,也**不等于**「这一行不写」。
2691
+ */
2692
+ interface RowPlan {
2693
+ row: number;
2694
+ /** 业务键元组。跟索引撞键时走 {@link encodeKeyTuple}。 */
2695
+ key: string[];
2696
+ action: RowAction;
2697
+ existingId: string | null;
2698
+ fields: Map<string, unknown>;
2699
+ refs: RowRef[];
2700
+ }
2701
+ interface Wave {
2702
+ wave: number;
2703
+ kind: WaveKind;
2704
+ rows: RowPlan[];
2705
+ }
2706
+ interface SelfReferenceNote {
2707
+ declared: boolean | null;
2708
+ usable: boolean | null;
2709
+ reason: string;
2710
+ field: string | null;
2711
+ keyField: string | null;
2712
+ }
2713
+ /** 一个模型的计划。🔴 **`null` 与 `0` 不是一回事**:`null` = 这一档没跑。 */
2714
+ interface ModelPlan {
2715
+ model: string;
2716
+ businessKeyFields: string[];
2717
+ rowCount: number | null;
2718
+ waves: Wave[] | null;
2719
+ existingMatched: number | null;
2720
+ toCreate: number | null;
2721
+ /**
2722
+ * 🔴 `toCreate` 与 `plannedToCreate` 是**两套划分**:前者数的是**全部行**里有多少行
2723
+ * 库里没有,被排除出波次的行照样计入;后者只数**进得了波次**的那些 ——
2724
+ * 这一轮真正会**新建**的行数是**后者**。
2725
+ * ⚠️ 它**不含** update 行(那些也要发请求,但发的是更新不是 create)。
2726
+ */
2727
+ plannedToCreate: number | null;
2728
+ onExisting: string | null;
2729
+ planned: boolean;
2730
+ blockedChecks: Map<string, string[]>;
2731
+ rowsNotInWaves: Map<string, number>;
2732
+ selfReference: SelfReferenceNote;
2733
+ }
2734
+ /**
2735
+ * 这份计划是照哪一份基线算出来的。**只记出处,不记指纹**。
2736
+ * `path` 是相对 `<--out>/recon/` 的两段路径,**不是绝对路径** ——
2737
+ * FDE 的主路径正是跨机器拷 work 目录。
2738
+ */
2739
+ interface BaselineRef {
2740
+ path: string;
2741
+ roundId: string | null;
2742
+ }
2743
+ /**
2744
+ * 🔴 三个数组都是**可空**的,而 `null` 与 `[]` 是两件事:
2745
+ * `[]` = 扫过了、结论是零;`null` = **这一档根本没跑**。
2746
+ * 工件没过校验那条路(门面,11b-2)三个键一律 `null` —— 那时连边都没扫。
2747
+ * 让它们在类型上就可空,是为了下游只能显式分开处理这两件事。
2748
+ */
2749
+ interface CrossModelOrder {
2750
+ checkedAgainst: string;
2751
+ topologyJsonRead: boolean;
2752
+ edges: Array<{
2753
+ from: string;
2754
+ to: string;
2755
+ field: string;
2756
+ targetInArtifact: boolean;
2757
+ }> | null;
2758
+ modelsNotScanned: Array<{
2759
+ model: string;
2760
+ why: string;
2761
+ }> | null;
2762
+ unverifiedOrderEdges: Array<{
2763
+ from: string;
2764
+ to: string;
2765
+ field: string;
2766
+ why: string;
2767
+ }> | null;
2768
+ note: string;
2769
+ }
2770
+ interface ImportPlan {
2771
+ version: number;
2772
+ roundId: string;
2773
+ models: ModelPlan[];
2774
+ problems: PlanProblem[];
2775
+ notes: Record<string, unknown>[];
2776
+ /**
2777
+ * 🔴 GC3:跨模型顺序核到什么程度,产物必须**自己说出来**。
2778
+ * 没有这一段时,「没报顺序问题」会被读成「顺序核过了」。
2779
+ */
2780
+ crossModelOrder: CrossModelOrder;
2781
+ /** `null` = 这份计划**没记出处**(老产物),不是「出处是空的」。 */
2782
+ baseline: BaselineRef | null;
2783
+ }
2784
+
2785
+ /**
2786
+ * 风险清单 `work/risk.json` —— 顾问据以决定「这份计划能不能往下走」的那一页。
2787
+ *
2788
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/risk.py`(ADR-319 刀 11b-3a/3b/3c:
2789
+ * 常量与分级骨架 · recon 只读层 · 各组判据与 `riskModel` · 豁免通道与 `buildRisk`。
2790
+ * 门面 / 产物 JSON / 落盘在 `risk-io.ts`)。行为基线是
2791
+ * `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.8。
2792
+ *
2793
+ * 源表读取说「客户这张表读出来是什么」、工件说「哪一列进哪个字段」、索引说「库里已经有
2794
+ * 哪些行」、计划说「每一行怎么办」。**四层都没有问过 HCM 那边:这个字段真的存在吗?
2795
+ * 必填的填齐了吗?这个值域我们到底看全了没有?** 本模块就是那一句的兑现。
2796
+ *
2797
+ * ## 🔴 本模块的全部内容都是**写给顾问看的断言**
2798
+ *
2799
+ * `risk.json` **没有别的产物可躲**:它从头到尾就是一份断言清单。所以本模块的每一句
2800
+ * 面向读者的话都要过那两条固定检查项:
2801
+ *
2802
+ * 1. **「我这句话让读者去找的东西 / 去等的信号 / 据以行动的事实,在这条路径上真的存在吗?」**
2803
+ * 2. **「我说我做了的那件事,代码里真的有吗?」**
2804
+ *
2805
+ * 三种变形也都算:**过度告警**(承诺一件不会发生的事)· **过度宣称守卫覆盖方向**
2806
+ * (「多拦不漏拦」那类)· 把「暂时不做」写成「做不了」。
2807
+ *
2808
+ * ## 🔴 GC3 在本模块的落点:「查过且不合格」与「压根没查到」不许同形
2809
+ *
2810
+ * 说「因为值域是 `partial` 所以禁止生成写脚本」时,**必须真的读到过那个 `completeness`**。
2811
+ * `recon/valuedomain/<X>.json` 不存在时产出的是 `VALUE_DOMAIN_MISSING`(前提级)
2812
+ * **而不是**一句「值域不完整」:后者会把顾问打发去查 RBAC,而真相是那张对照表
2813
+ * 这一轮根本没爬到。四对分档都不许合并:
2814
+ *
2815
+ * | 查过、结论不合格 | 压根没查到 |
2816
+ * |---|---|
2817
+ * | `VALUE_DOMAIN_NOT_AUTHORITATIVE` / `AC6_PREMISE_VALUEDOMAIN_NOT_COMPLETE` | `VALUE_DOMAIN_MISSING` / `VALUE_DOMAIN_UNREADABLE` |
2818
+ * | `ENUM_VALUE_NOT_IN_DOMAIN` | `ENUM_DOMAIN_MISSING` / `ENUM_DOMAIN_UNREADABLE` / `ENUM_ROW_MISSING` |
2819
+ * | `FIELD_NOT_IN_MODEL` | `RECON_SHEET_MISSING` / `RECON_SHEET_UNREADABLE` / `RECON_FIELDS_UNJUDGED` |
2820
+ * | `REQUIRED_FIELD_UNMAPPED` | 同上 |
2821
+ *
2822
+ * ## 🔴 值域那条闸为什么连 `visible-complete` 也拦
2823
+ *
2824
+ * 理由不是「取得不够多」,是**取满了也不构成全集证据**:查询引擎先注入 RBAC 过滤
2825
+ * 再分页与 count,`totalElements` 本身就是**裁剪后**的可见总数。
2826
+ * ⇒ 放行档只有 {@link AUTHORITATIVE} 一个,而 `recon/valuedomain.ts` 自己声明
2827
+ * **本版本永远不会产出它**。**所以这条闸在今天的产物上等于「凡是靠码表对照表落值的字段,
2828
+ * 一律拦」** —— 这不是副作用,是 spec 要的结果;本模块把这句话原样写进产物的
2829
+ * {@link WORDING},免得下一个人看到「全都拦」以为是 bug。
2830
+ *
2831
+ * ⚠️ 唯一的出口是**逐条豁免**(11b-3c):顾问离线确认那个字段的取值范围之后签一份带
2832
+ * `by` / `at` / `reason` / `roundId` 的记录,**只盖它签的那一条**。没有全局开关,
2833
+ * 前提级问题结构性签不动,豁免锚在 recon 的轮次身份上、值域换一轮就自动失效。
2834
+ *
2835
+ * ## 前提级 vs 内容级 / blocking vs advisory
2836
+ *
2837
+ * `kind` 由 {@link PREMISE_CODES} **查表**得出,`severity` 由 {@link BLOCKING_CODES} 查表得出。
2838
+ * ⚠️ **两个维度,别当成一个**:`RISK_CHECKS_SKIPPED` 是前提级(它是「有几组没跑」的回执)
2839
+ * 却**不是** blocking —— 真正拦路的是发出它的那几条前提码本身。
2840
+ *
2841
+ * ## 🔴 与 Python 的一处分岔:路径遏制判据只留一份
2842
+ *
2843
+ * Python 侧 `_unsafe_rel_reason` 与 `layout._path` 是**两份同款实现**,靠注释说「照它来」。
2844
+ * 这里直接复用 `layout.ts` 导出的 {@link hasDotDotComponent} / {@link isInside} ——
2845
+ * 两份「同款」之间没有任何东西绑住,而漂的方向是**读盘侧比写盘侧松一格**,
2846
+ * 那时「这份 sheet 根本不会存在」就成了一句假话。
2847
+ */
2848
+
2849
+ /** 产物文件名。落盘收的是 **work 目录**,写这一份。 */
2850
+ declare const RISK_FILE = "risk.json";
2851
+ /**
2852
+ * 🔴 **哪几条拦路**。这是 `Risk.blocking` 的唯一来源(命令层的退出码接它)。
2853
+ * 判据是「不修它就不许生成写脚本」,与 `kind` 是**两个维度**。
2854
+ */
2855
+ 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"];
2856
+ /**
2857
+ * 豁免锚在**它所依据的那份证据**上:recon 两份索引的 `roundId`。
2858
+ * 值域换了一轮 ⇒ 顾问当初确认的那份对照表已经不是现在这份 ⇒ 豁免自动失效。
2859
+ * 🔴 读不到轮次身份时 **fail-closed**(豁免不生效):无从判新旧却照样放行,
2860
+ * 等于把「没查」当成「查过、没问题」。
2861
+ */
2862
+ declare const ROUND_ANCHORS: readonly ["mapping/_index.json", "valuedomain/_index.json"];
2863
+ /**
2864
+ * 一条风险。
2865
+ *
2866
+ * `kind` ∈ `{premise, content}`、`severity` ∈ `{blocking, advisory}`,**都由 code 查表得出**
2867
+ * (不手填:手填迟早与两张表漂开,而漂的方向是「拦路的那条被标成 advisory」)。
2868
+ *
2869
+ * `field` 是这条风险落在哪个字段上;不针对具体字段的是 `null`。
2870
+ * ⚠️ **写能力闸那两条落的不是模型字段**:它们的 `field` 是 `mutation.<op>`
2871
+ * (`mutation.create` / `mutation.update`)。这个槽位就是**豁免的粒度** ——
2872
+ * 签字签的是「这一个模型的这一个写动作」,写成 `null` 的话豁免的三元组永远匹配不上,
2873
+ * 这两条就成了签不动的死码(而它们按裁定必须可签)。
2874
+ *
2875
+ * `evidence` 是**下这条结论时手上的那几个数**。🔴 它存在的理由只有一个:豁免台账要记
2876
+ * 「签的时候证据是什么」,而**反解本条 message 去拿那个值**是最脆的一种耦合。
2877
+ * 没有证据要记的是 `{}`。
2878
+ *
2879
+ * `exempted` = 这条风险有没有被一份**有效**豁免盖住。🔴 盖住了它**照样在这张清单里**
2880
+ * (只是不再让 `blocking` 为真)—— 「顾问签过字」与「闸没触发」在产物里必须分得开。
2881
+ */
2882
+ interface RiskProblem {
2883
+ code: string;
2884
+ model: string;
2885
+ field: string | null;
2886
+ message: string;
2887
+ hint: string;
2888
+ kind: 'premise' | 'content';
2889
+ severity: 'blocking' | 'advisory';
2890
+ entry: number | null;
2891
+ evidence: Record<string, unknown>;
2892
+ exempted: boolean;
2893
+ }
2894
+ /** 一个模型的风险画像。🔴 **`null` 与 `0` 不是一回事**:`null` = 这一档没跑。 */
2895
+ interface ModelRisk {
2896
+ model: string;
2897
+ entry: number;
2898
+ /** 那份 sheet 读到没有、读到的是什么。 */
2899
+ reconSheet: Record<string, unknown>;
2900
+ /** 组 → `{ran, why, applicable?}`。 */
2901
+ checks: Record<string, Record<string, unknown>>;
2902
+ /** 各档计数;没跑的那一档是 `null`。 */
2903
+ counts: Record<string, number | null>;
2904
+ }
2905
+ interface Risk {
2906
+ version: number;
2907
+ roundId: string;
2908
+ blocking: boolean;
2909
+ models: ModelRisk[];
2910
+ problems: RiskProblem[];
2911
+ /** 源表读取器留下的原始 note,原样带出。 */
2912
+ notes: Record<string, unknown>[];
2913
+ /**
2914
+ * 🔴 `notes === []` 有两种成因,这个布尔把它们分开:
2915
+ * `true` = 扫过源表、一列都没丢;`false` = 这一轮压根没把 notes 传进来。
2916
+ */
2917
+ notesProvided: boolean;
2918
+ /**
2919
+ * 豁免台账:逐条记「谁 / 何时 / 盖了哪一条 / 依据的证据是什么 / 生没生效」。
2920
+ * 🔴 它是**产物的一部分**,不是命令的输出 —— 产物是被单独拷走的那一半。
2921
+ */
2922
+ exemptions: Record<string, unknown>[];
2923
+ exemptionsProvided: boolean;
2924
+ /**
2925
+ * 🔴 `models === []` 的两种成因:`true` = 逐个模型评估过、这份工件里就是没有模型;
2926
+ * `false` = **门面早退了,一个模型都没评估**。合并就是「没查」冒充「查过、没问题」,
2927
+ * 而这一档恰恰最不能冒充:早退时 `blocking` 为真,读者更需要知道「零条风险」
2928
+ * 是因为没查,不是因为干净。
2929
+ */
2930
+ modelsAssessed: boolean;
2931
+ /**
2932
+ * 🔴 「本轮有判据**没跑**」—— 顶层那一格(GC3 长在产物最外层)。
2933
+ * `blocking` 回答的是「查出问题没有」,回答不了「有没有**根本没查**」;
2934
+ * 而顾问在现场是 `jq .blocking` 读这份产物的,那是离他最近的一格。
2935
+ *
2936
+ * 三档靠**这一个键与 `modelsAssessed` 这一对**读得出来,不另造键:
2937
+ * - `checksSkipped=false, modelsAssessed=true` = 该跑的都跑了;
2938
+ * - `checksSkipped=true, modelsAssessed=true` = 逐个模型评估过,但**有组没跑**;
2939
+ * - `checksSkipped=true, modelsAssessed=false` = 工件没过校验,**连组都没分**。
2940
+ *
2941
+ * 🔴 第四种组合(`false` + `false`)**不存在**:一个模型都没评估时每一组都没跑。
2942
+ * ⚠️ 「连组都没分」那一档**不用 `null` 表示**:`jq .checksSkipped` 得到 `null`
2943
+ * 在 shell 里是**假值**,于是它会被读成「没有跳过」—— 那正是本键要治的那次塌陷。
2944
+ */
2945
+ checksSkipped: boolean;
2946
+ /**
2947
+ * 🔴 「这一轮**判没判**基线的轮次身份」,与 `notesProvided` / `exemptionsProvided`
2948
+ * 逐字同一条口径:**没有 `BASELINE_ROUND_NOT_COMPLETE`** 有两种成因 ——
2949
+ * `true` = 判过、这份基线是一轮完整跑出来的;`false` = **这一轮压根没把轮次结论传进来**。
2950
+ * ⚠️ 它**不进 `checksSkipped`**:那一格 roll-up 的是 `CHECK_GROUPS`(按定义只装内容级
2951
+ * code),而轮次身份是**整轮级的前提**,进不去那张登记表 —— 所以它自己长在产物最外层。
2952
+ */
2953
+ roundJudged: boolean;
2954
+ wording: string;
2955
+ }
2956
+ interface BuildRiskOptions {
2957
+ /** 源表读取器留下的「被丢弃的无名空列」。**没给**与**给了空表**在产物里分得开。 */
2958
+ notes?: readonly Record<string, unknown>[] | null;
2959
+ /** `{模型名: [行…]}`。**只有**日期序列号那一条判据用它。 */
2960
+ tables?: Map<string, unknown[]> | null;
2961
+ /** 顾问离线确认之后**逐条**签下的豁免。 */
2962
+ exemptions?: readonly unknown[] | null;
2963
+ roundId?: string;
2964
+ /** 计划层算好的那份 `ImportPlan`。🔴 **本模块不重算一份**。 */
2965
+ plan?: ImportPlan | null;
2966
+ /** 门 0 对这份基线轮次身份的判词。🔴 **本层不自己算它**。 */
2967
+ roundPremise?: readonly unknown[] | null;
2968
+ }
2969
+
2970
+ /**
2971
+ * 🔴 **一张退出码表,凡走这一档的子命令都共用**,写成模块常量而不是在各分支里散着
2972
+ * `return 0/1/2`:散着写的表现是「某一条分支的 rc 与文档对不上」,而顾问的脚本正是按 rc
2973
+ * 分流的 —— 一个错的 rc 会让「有阻断风险」被读成「干净」,然后照着跑下去。
2974
+ *
2975
+ * - `clean` —— `plan`:无阻断风险、无计划问题;`apply`:干跑通过,或真跑且每行都落到计划里那一档
2976
+ * - `blocked` —— `plan`:risk 命中 {@link BLOCKING_CODES},或计划里有内容级问题;
2977
+ * `apply`:有行 writeFailed / quarantined / blocked,或整轮被中止
2978
+ * - `premise` —— `plan`:工件/源表读不了、`PLAN_CHECKS_SKIPPED`、索引前提不成立;
2979
+ * `apply`:计划文件读不了、前提错、租约冲突
2980
+ *
2981
+ * 🔴 `quarantined` **必须**落 `blocked`,不许算 `clean`:它的语义是「服务端接受过一次写、
2982
+ * 业务键却查不回来」——给 0 就是让脚本带着一条**状态未知**的写继续往下走。
2983
+ *
2984
+ * ⚠️ **这里不写「几个子命令共用」**:那种数在没有任何东西会红的情况下会变成假话
2985
+ *(kit 侧就这么漂过一次:写的是「两个子命令」,此后 `verify` 与 `meta` 各自接了进来)。
2986
+ * 要现取就看 `fde-seed-command.test.ts` 里那条「退出码是一张模块常量表」的守卫 ——
2987
+ * 它从命令层源码现扫,不在这里抄一个会过期的数。
2988
+ */
2989
+ declare const INIT_EXIT_CODES: {
2990
+ readonly clean: 0;
2991
+ readonly blocked: 1;
2992
+ readonly premise: 2;
2993
+ };
2994
+ type InitExitName = keyof typeof INIT_EXIT_CODES;
2995
+ /**
2996
+ * `plan` / `apply` 共用的两个落点常量。**两个子命令的缺省算法必须逐字相同**,否则
2997
+ * `plan` 写进 A 目录、`apply` 去 B 目录读,报出来的是「计划文件不在」——
2998
+ * 一条把人指向「你没跑 plan」的假消息。
2999
+ */
3000
+ declare const WORK_DIRNAME = "work";
3001
+ declare const MAPPING_FILE = "mapping.json";
3002
+ /**
3003
+ * **零网络**的命令。`plan` / `apply` / `verify`(联网那一档)都不在里面。
3004
+ *
3005
+ * 🔴 它不是文档,是判据:写命令的三道前置闸只挡写、放行只读,而「哪些是只读」
3006
+ * 由这一份说了算。散一份在别处的后果是两份说法不一致时,闸按其中一份放行。
3007
+ */
3008
+ declare const OFFLINE_COMMANDS: readonly ["find", "values"];
3009
+ interface SeedPathArgs {
3010
+ /** `--out`:recon 产物根。 */
3011
+ out: string;
3012
+ /** `--tenant`:**未归一**的租户串,归一交给 {@link tenantSegment}。 */
3013
+ tenant: string;
3014
+ /** `--work`:给了就直接用它。 */
3015
+ work?: string | null;
3016
+ /** `--mapping`:给了就直接用它。 */
3017
+ mapping?: string | null;
3018
+ }
3019
+ /**
3020
+ * work 目录:`--work` 给了就用它,否则 `<--out>/work/<租户段>/`。
3021
+ *
3022
+ * 🔴 **租户段走 `tenantSegment`**,与 recon 产物同一个归一函数。这里若直接拼裸 tenant,
3023
+ * 任何被归一改写过的 tenant(含冒号/空格等)都会让 recon 写进 `recon/a_b/`
3024
+ * 而这里去 `recon/a:b/` 找,于是**对着一份确实存在的基线报「先跑一次 recon」**。
3025
+ */
3026
+ declare function seedWorkDir(args: SeedPathArgs): string;
3027
+ declare function seedMappingPath(args: SeedPathArgs, work: string): string;
3028
+ /** 一份基线候选:`index/fields.jsonl` 的路径,与它所属的基线目录。 */
3029
+ interface BaselineCandidate {
3030
+ /** `<out>/recon/<租户段>/<sourceKey段>/index/fields.jsonl` */
3031
+ indexFile: string;
3032
+ /** `<out>/recon/<租户段>/<sourceKey段>` —— 风险层要读的那个目录 */
3033
+ reconDir: string;
3034
+ }
3035
+ /**
3036
+ * → `[租户基线根, 排好序的候选]`。
3037
+ *
3038
+ * 🔴 **必须与写入端用同一个归一函数**(同 {@link seedWorkDir} 那条)。
3039
+ * `find` / `values` / `round` 与 `plan` 四条路都从这里取,不是四条路各拼一遍。
3040
+ */
3041
+ declare function seedBaselines(out: string, tenant: string): [string, BaselineCandidate[]];
3042
+ /**
3043
+ * 两份产物 → 一个退出码。**先判前提级,再判阻断级**。
3044
+ *
3045
+ * 🔴 顺序不能反:前提级的意思是「**这份清单建立在一个不成立的前提上**」。
3046
+ * 它有两种落法 —— 门面早退那一档(这一轮压根没判),以及**判据跑完了、而结论不作数**
3047
+ *(`RISK_CHECKS_SKIPPED` 的一部分、`BASELINE_ROUND_NOT_COMPLETE` 整条)。
3048
+ * 两种都归 `premise` —— 本函数**结构上**就是「任意一条 `kind === 'premise'` ⇒ premise」,
3049
+ * 这一条是既定语义,不因新增哪条码而改。
3050
+ *
3051
+ * 给 `blocked` 会让顾问去逐条修一份**不作数**的风险清单。
3052
+ *
3053
+ * 🔴 **决定 rc 的字段就是这三个**:`plan.problems[].kind` · `risk.problems[].kind` ·
3054
+ * `risk.blocking`(外加「计划有没有问题」)。散文里点名的字段与这里读的字段由守卫对着。
3055
+ */
3056
+ declare const RC_DECIDING_FIELDS: readonly ["plan.problems", "risk.problems", "risk.blocking"];
3057
+ declare function planRc(plan: ImportPlan, risk: Risk): number;
3058
+ /**
3059
+ * 「被丢弃的无名空列」那一段。
3060
+ *
3061
+ * 🔴 GC3:空数组说的是「扫过、一列都没丢」,不是「没扫」——两者不许长得一样。
3062
+ */
3063
+ declare function discardedColumnLines(notes: readonly Record<string, unknown>[]): string[];
3064
+ /**
3065
+ * 汇总行。
3066
+ *
3067
+ * 🔴 **三个数必须构成一个划分,否则这个句式本身在说谎**:`blocking` 画在 **severity** 轴上、
3068
+ * `premise` 画在 **kind** 轴上,两者**交叉**。写成「阻断项 N 条 / 前提未成立 M 条 / 共 K 条」
3069
+ * 时,一条既 blocking 又 premise 的 problem 会渲染成「阻断 1 / 前提 1 / 共 1」——
3070
+ * 顾问读到的是两条。**`1 + 1 = 1` 是数上的谎**。
3071
+ * ⇒ 拿 **kind** 当划分(两个数**能相加**、和恒等于总数),severity 另起一句。
3072
+ *
3073
+ * 🔴 那句免责**按本轮的事实说,不写成恒成立**:「横跨上面两档」在**单档**轮次上不是
3074
+ * 这一轮的事实。真跨了才说「横跨」,只落一档就点名是哪一档;操作性子句「不另计」
3075
+ * 两种都要有 —— 它才是防止读者把三个数相加的那一句。
3076
+ */
3077
+ declare function planSummaryLine(plan: ImportPlan, risk: Risk): string;
3078
+ /**
3079
+ * 逐条问题。计划的**全打**;风险的只打「前提级」与「未被豁免的拦路项」。
3080
+ *
3081
+ * 🔴 **前提级一律打出来,哪怕它不拦路**:`RISK_CHECKS_SKIPPED` 正是这一档
3082
+ *(前提级 / advisory),而它是「哪几组这一轮没跑」的**唯一**回执。只按拦路码印,
3083
+ * 就会出现「rc=premise 说前提没成立、屏幕上一个字都没有」的形态 ——
3084
+ * 「没查」与「查过、没问题」在顾问那一端又合成了同一个样子。
3085
+ *
3086
+ * 🔴 **`hint` 也要上屏**:`message` 说的是「出了什么事」、`hint` 说的是「**该怎么办**」。
3087
+ * 后者只躺在 `risk.json` 里的话,rc 告诉顾问「前提没成立」而屏幕不告诉他怎么办。
3088
+ */
3089
+ declare function planProblemLines(plan: ImportPlan, risk: Risk): string[];
3090
+ /**
3091
+ * 豁免台账装载。→ `[台账, 错误信息]`;两者恰有一个非 `null`。
3092
+ *
3093
+ * 🔴 「没给」与「给了一份空台账」**不是一回事**:前者是 `null`,后者是 `[]`,
3094
+ * 它们在 `risk.json` 里是两个值。所以顶层不是数组时**拒绝**,不悄悄当空台账。
3095
+ */
3096
+ declare function loadExemptions(file: string): [unknown[] | null, string | null];
3097
+ /**
3098
+ * 基线**不是一轮完整跑出来的**时那句告警,按 `state` 分档。
3099
+ *
3100
+ * 🔴 **键集与 {@link ROUND_STATES} 去掉 `complete` 之后精确对等**(守卫双向对着):
3101
+ * 少一档 ⇒ 那个状态落到兜底句,顾问看到的是一句说不出所以然的话;
3102
+ * 多一档 ⇒ 有人登记了一个 `inspectRound` 永远不会产出的状态。
3103
+ *
3104
+ * ⚠️ 本层**只读结论、不做任何判断** —— 档位整个由 `inspectRound` 给,
3105
+ * CLI 不自己比 roundId(与 `find` / `round` 同一条纪律)。
3106
+ */
3107
+ declare const ROUND_WARNINGS: Record<string, string>;
3108
+ /** 登记表以外的 `state` 落这里。**说得出它是什么**,不假装认识它。 */
3109
+ declare const ROUND_WARNING_FALLBACK: string;
3110
+ /** → 出处行之后那句告警;`complete` 时是空串。**只读结论,不做任何判断。** */
3111
+ declare function roundWarning(round: {
3112
+ state?: string;
3113
+ } | null): string;
3114
+ /** {@link ROUND_WARNINGS} 该覆盖的那些状态 —— 现取自 {@link ROUND_STATES},不手抄。 */
3115
+ declare const WARNED_ROUND_STATES: ("unknown" | "mixed")[];
3116
+
3117
+ /**
3118
+ * 行级导入计划的**门面与产物**:读工件 → 扫源表 → 校验 → 建既存索引 → 建计划 → 落盘 / 回读。
3119
+ *
3120
+ * 移植自 `hcm_nx_core` 的 `tools/fde-kit/hcmnx_kit/init/plan.py` 的后半段
3121
+ * (ADR-319 刀 11b-2)。计算核心在 {@link ../seed/plan}(刀 11b-1)。
3122
+ * 行为基线是 `docs/superpowers/specs/2026-08-28-fde-kit-behavior-contract.md` §9.5。
3123
+ *
3124
+ * ## 为什么与计算核心分成两个文件(与 Python 的一处分岔)
3125
+ *
3126
+ * Python 侧全在 `plan.py` 一个文件里。这里分开的理由不是行数,是**依赖方向**:
3127
+ * `plan.ts` 是纯计算(不碰 fs、不碰网络),本文件才引进 `node:fs` 与 `KeyIndexClient`。
3128
+ * 🔴 **写出去的与读回来的仍然住在一起** —— Python 那段注释点的名是这一条
3129
+ * (「形状知识分两处的表现,是加了一个键之后写得出、读不回来,且产物看上去完全正常」),
3130
+ * 而 {@link planToJson} 与 {@link readImportPlan} 就在同一屏里,共用 {@link PLAN_JSON_KEYS}。
3131
+ *
3132
+ * ## 🔴 工件没过校验就一发请求都不发
3133
+ *
3134
+ * `validateMapping` 返回非空的语义就是「不许往下走」:拿一份自己都说不圆的工件
3135
+ * 去问后端要数据,问回来的也是废墟。
3136
+ *
3137
+ * ## 🔴 早退那一支也要记出处、也要如实说「顺序没核」
3138
+ *
3139
+ * 这份计划仍然会落盘、仍然会被 `apply` 读回来。出处在那一支缺席的话,
3140
+ * 「这份计划没记出处」与「这份计划记了、只是没算成」在下游长成同一个样子;
3141
+ * `crossModelOrder` 三个数组一律 `null` 而不是 `[]`,因为**连边都没扫**。
3142
+ *
3143
+ * ## 🔴 TS 与 Python 的两处真实分岔(都不是风格问题)
3144
+ *
3145
+ * 1. **非 UTF-8 要显式检**:Python 的 `read_text(encoding="utf-8-sig")` 遇到坏字节
3146
+ * 抛 `UnicodeDecodeError`;Node 的 `readFileSync(p, 'utf-8')` **不抛**,
3147
+ * 它把坏字节静默换成 `U+FFFD`。照抄写法会让 `plan-unreadable` 那一档**永不触发**,
3148
+ * 而一份被动过的产物会以「JSON 解析失败」或干脆「读得回来」的面目往下走。
3149
+ * ⇒ 这里读 `Buffer` 并用 `new TextDecoder('utf-8', { fatal: true })` 解。
3150
+ * 2. **行键的元素类型也要查**:Python 的 `_key_from_json` 只拦容器类型(`tuple()`
3151
+ * 会把字符串摊成字符、把对象摊成它的键)。TS 里容器那一半同样要拦,
3152
+ * 而且 `RowPlan.key` 标着 `string[]` —— 不查元素类型的话那个标注就是一句假话,
3153
+ * 且下游 `encodeKeyTuple` 会拿 `undefined.length` 炸在一个完全指不到真因的地方。
3154
+ */
3155
+
3156
+ interface PlanFromArtifactsOptions {
3157
+ /**
3158
+ * 这份计划照的是哪一份基线。
3159
+ * 🔴 它是**具名**选项而不是第四个位置参数:`sourceDir` 之后再挂一个 `string`,
3160
+ * 调用方漏写一个逗号就把路径传成了出处,而两者都是 `string`,谁都不会红。
3161
+ */
3162
+ baseline?: BaselineRef | null;
3163
+ /** 只为测试可注入(与 `scanSources` 同款);生产不传。 */
3164
+ loadKeyIndexImpl?: typeof loadKeyIndex;
3165
+ }
3166
+ /**
3167
+ * 「读源表 → 校验工件 → 建既存索引 → 建计划」这条链的**唯一入口**。
3168
+ *
3169
+ * `notes` 在这里被接住:源表读取器记下的「被丢弃的无名空列」经 `scanSources`
3170
+ * 补上 model / file 两个键后,由本函数放进产物 —— 在此之前它有出参、没有消费方,
3171
+ * 等于**留痕在现实中不成立**。
3172
+ */
3173
+ declare function planFromArtifacts(client: KeyIndexClient, mappingPath: string, sourceDir?: string, options?: PlanFromArtifactsOptions): Promise<ImportPlan>;
3174
+ /**
3175
+ * 把计划写成 `<out>/import-plan.json`。`out` 是 **work 目录**,不是文件名。
3176
+ * 返回写出去的那个完整路径。
3177
+ */
3178
+ declare function writeImportPlan(plan: ImportPlan, out: string): string;
3179
+ /**
3180
+ * `import-plan.json` 读不回来 —— **数据/前提问题**,不是代码 bug
3181
+ * (所以不是 `PlanInvariantError`)。形态与 `IndexPremiseError` / `MappingError` 一致:
3182
+ * `reason` 给程序判、`hint` 给顾问照做。
3183
+ */
3184
+ declare class PlanReadError extends Error {
3185
+ readonly reason: string;
3186
+ readonly hint: string;
3187
+ /**
3188
+ * **裸**消息(不含 `[reason]` 前缀与 hint 尾巴)。
3189
+ *
3190
+ * 🔴 `message` 是**拼好**的那一句,给人直接读;下游要按 `reason` / 消息 / `hint`
3191
+ * 三段自己排版时(`verify` 的前提就是这么排的),拿 `message` 去拼会把 reason 与 hint
3192
+ * **各印两遍**。⇒ 原料与成品各留一份,谁都不用去反解析另一个。
3193
+ */
3194
+ readonly detail: string;
3195
+ constructor(reason: string, message: string, hint?: string);
3196
+ }
3197
+ /**
3198
+ * 把 `<out>/import-plan.json` 读回成 {@link ImportPlan}。`out` 是 **work 目录**
3199
+ * (与 {@link writeImportPlan} 同一个入参形态,两端不许各拼各的)。
3200
+ *
3201
+ * 🔴 **读不出就抛,不返回一份空计划**:空计划的下游语义是「零个模型、零行」,
3202
+ * `apply` 照着它跑会安安静静地什么都不做,然后报「跑完了」。
3203
+ */
3204
+ declare function readImportPlan(out: string): ImportPlan;
3205
+
3206
+ interface RiskFromArtifactsOptions {
3207
+ sourceDir?: string;
3208
+ exemptions?: BuildRiskOptions['exemptions'];
3209
+ plan?: BuildRiskOptions['plan'];
3210
+ roundPremise?: BuildRiskOptions['roundPremise'];
3211
+ }
3212
+ /**
3213
+ * 「读工件 → 读源表 → 校验工件 → 算风险」这条链的唯一入口。
3214
+ *
3215
+ * 🔴 **工件没过校验就不算风险**:`validateMapping` 返回非空的语义是「不许往下走」,
3216
+ * 拿一份自己都说不圆的工件去判风险,判出来的每一条都建立在废墟上。
3217
+ */
3218
+ declare function riskFromArtifacts(mappingPath: string, reconDir: string, options?: RiskFromArtifactsOptions): Promise<Risk>;
3219
+ /**
3220
+ * 把风险清单写成 `<out>/risk.json`。`out` 是 **work 目录**,不是文件名。
3221
+ *
3222
+ * 🔴 走 {@link WorkLayout} 而不是直接 `writeFileSync`:`src/fde/**` 的写入全部收口在
3223
+ * `layout.ts`,由 ArchUnit 同款的守卫钉住。
3224
+ * ⚠️ 这与 Python 侧的做法**不同**(那边绕开了自己的 layout 门面,理由是它的扫描器按方法名
3225
+ * 认 writer、会把任何 `Path` 写入误当成产物路径)—— TS 侧的守卫认的是**模块边界**,
3226
+ * 没有那个坑,所以这里回到唯一收口点。
3227
+ */
3228
+ declare function writeRisk(risk: Risk, out: string): string;
3229
+
2375
3230
  declare const ACLASS_KINDS: readonly ["fieldKey", "fieldLabel", "enumValue", "modelName", "codeValue", "naturalKey", "caliber"];
2376
3231
  type AclassKind = (typeof ACLASS_KINDS)[number];
2377
3232
  /** 枚举元素里**属于租户事实**的那几个键。 */
@@ -3017,4 +3872,4 @@ interface TriageRoundResult {
3017
3872
  */
3018
3873
  declare function runTriageRound(probe: ReconProbe, artifactsDir: string, entriesIn: readonly TriageEntry[]): Promise<TriageRoundResult>;
3019
3874
 
3020
- 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, 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, type IdentityMeta, type ImportClient, type ImportOptions, type ImportResult, 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, 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, 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, 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 Premise, type Principal, type ProfileConfig, type ProtocolFact, type QueryResult, 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, ROUND_EXIT_CODES, ROUND_STAMPED_PRODUCTS, ROUND_STATES, ROUND_SUBCOMMAND, 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 RoundResult, type RoundState, type RowResult, type RowStatus, SCOPES, SDK_VERSION, SEGMENT_SEPARATOR, type SaveMetaResult, type ScanOptions, type ScanResult, 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, WORKSPACES_PATH, 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, 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, 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, probeAll, probeExtensionSource, profileDir, profileFile, pullMiniAppProject, pushMiniAppProject, readBusinessKeyFields, readMiniContext, readPullManifest, refreshToken, remove, renderRound, renderTriage, replHistoryFile, resetSettingItem, resolveActiveEnv, resolveActiveIdentity, resolveActiveProfile, resolveAllSkillsInstallOrder, resolveChironBase, resolveRefs, resolveSkillInstallOrder, roundAge, runDoctor, runImport, runMiniSmokeChecks, runRecon, runTriageRound, safeSegment, saveConversationState, saveEnv, saveGlobalConfig, saveIdentity, saveProfile, saveTenantMeta, saveWorkspaceFileContent, scan, segmentsOf, sendMessageAndStream, snakeToCamel, tenantSegment, toJson, toOrigin, toPrincipal, toTable, toYaml, truncateDisplay, unguardedKinds, update, uploadDocument, validateMiniProject };
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 };