@tbox.cn/app-toolkit 0.8.1 → 0.8.3

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.
@@ -173,6 +173,25 @@ function memoHit(appDir: string, entry: MemoEntry): boolean {
173
173
  return candidateFingerprint(resolvedNow) === candidateFingerprint(entry.resolved);
174
174
  }
175
175
 
176
+ /** contracts 能力分层单源(写/求值双策略共用——降级写批 0.8.2):
177
+ * - degraded:version null(未安装/源码态未构建/导入拒绝)——无可用 contracts 代码,写轴允许降级
178
+ * (跳过 zod + STRICT_VALIDATION_SKIPPED warning);求值轴仍 503(求值结果造不出)。
179
+ * - blocked:包在场但能力缺失(<0.9 无严格面 / ≥0.9 缺 OWNERSHIP_BINDING_V6 标记 / 畸形)——
180
+ * v6 形状(modules[owner] 键)写入旧代码语境会被忽略(v5 宽松读)或拒绝(0.9.x 旧 zod),
181
+ * fail-visible 503 + 升级指引,不静默降级。
182
+ * 分层判据 = 包可解析性(version null 与否)而非严格校验面——<0.9 已装与未安装非同态
183
+ * (前者旧代码在场、后者 v6 世代装后即追齐)。
184
+ * 消费策略:写轴 = tier !== 'blocked'(degraded 放行);evaluate = tier === 'ok'(严选)。 */
185
+ export type ContractsTier = 'ok' | 'degraded' | 'blocked';
186
+
187
+ export function contractsTier(
188
+ c: Pick<ResolvedContracts, 'version' | 'strictValidation' | 'ownershipBindingV6'>,
189
+ ): ContractsTier {
190
+ if (c.version === null) return 'degraded';
191
+ if (!c.ownershipBindingV6 || !c.strictValidation) return 'blocked';
192
+ return 'ok';
193
+ }
194
+
176
195
  /** 探测单候选:返回已解析产物或 null(该候选不可用——缺席/导入拒绝) */
177
196
  async function probeCandidate(
178
197
  candidate: string,
@@ -211,7 +230,7 @@ async function probeCandidate(
211
230
  const evaluation = EVALUATION_EXPORT_NAMES.every((name) => mod[name] !== undefined);
212
231
  const strictValidation = mod[STRICT_EXPORT_NAME] !== undefined;
213
232
  // v6 形状标记(出口在场性——判据先例 STRICT_EXPORT_NAME);缺席时不在此 push note
214
- // (503 文案归 factory assertContractsUsable 门控单点——)
233
+ // (503 文案归 factory 门控单点 assertWritableContracts/assertFullyUsable——)
215
234
  const ownershipBindingV6 = mod[OWNERSHIP_MARKER_NAME] === true;
216
235
  return {
217
236
  version,
@@ -37,8 +37,8 @@ export class AppToolkitError extends Error {
37
37
  * P-4:notes 优先——resolver 在全部不可解析路径均已 push 携带操作指引的 notes(导入失败/
38
38
  * 产物缺失/未安装/<0.9 升级);现行 version===null 分支会把 notes 内细分指引吞成通用文案。
39
39
  * 分支保留为兜底(防御性——正常路径 notes 恒非空)。
40
- * v7:+= ownershipBindingV6 分支(标记门第四分支单源化——写门控 assertContractsUsable 与
41
- * 读求值轴降级 statusMessage 共用同一文案;可选参向后兼容)。 */
40
+ * v7:+= ownershipBindingV6 分支(标记门第四分支单源化——写门控(现 assertWritableContracts /
41
+ * assertFullyUsable,0.8.2 降级写批拆分)与读求值轴降级 statusMessage 共用同一文案;可选参向后兼容)。 */
42
42
  export function contractsNotResolvedMessage(contracts: {
43
43
  version: string | null;
44
44
  strictValidation: boolean;
@@ -98,6 +98,9 @@ export const resourceNeedContribSchema = z.object({
98
98
 
99
99
  export const moduleDescriptorSchema = z
100
100
  .object({
101
+ // 元键(类型可选、行为惰性):供 CLI/schema 文档写入指针;strict 根形状下显式放行。
102
+ $comment: z.union([z.string(), z.record(z.string(), z.unknown())]).optional(),
103
+ $schema: z.string().optional(),
101
104
  schemaVersion: z.number().default(1),
102
105
  // v7 词汇统一(标识/展示名分轴):id = 标识键(唯一、寻址,键 = install id 规约形态);
103
106
  // name = 展示名(中文、可选)——回退归视图层(name ?? id),schema 不灌值
package/src/dto.ts CHANGED
@@ -264,6 +264,9 @@ export interface ServiceResolutionDetail {
264
264
 
265
265
  /** root 节点 */
266
266
  export interface AppIntegrationNode {
267
+ /** 元键(类型可选、行为惰性——文档指针;GET 回显、PUT 仅保活,noDiff 排除) */
268
+ $comment?: string | Record<string, unknown>;
269
+ $schema?: string;
267
270
  /** 恒字符串(app/module 级无内联形态) */
268
271
  provider?: string;
269
272
  config?: Record<string, unknown>;
@@ -279,6 +282,8 @@ export interface AppIntegrationNode {
279
282
  * (缺席根键删除;services/modules 域不在其中;v6 domains 键退役)+ views/app 投影
280
283
  * (GET 预填 ≡ PUT body,/L1——文件含 services/modules 但 root 节点投影只含本键集)) */
281
284
  export const APP_INTEGRATION_NODE_KEYS = [
285
+ '$comment',
286
+ '$schema',
282
287
  'provider',
283
288
  'config',
284
289
  'configByInstance',
@@ -299,6 +304,14 @@ export interface ModuleIntegrationNode {
299
304
  * (键集外 400;resources 恒随既有节点保全)+ views/modules 投影(GET ≡ PUT,三同构)) */
300
305
  export const MODULE_INTEGRATION_NODE_KEYS = ['provider', 'config'] as const;
301
306
 
307
+ /** ServiceIntegrationNode 可写键集单源(applyService 节点键纪律白名单——assertNodeKeys
308
+ * 无条件静态防线,zod 未知键拒绝语义前移,两态一致 400;0.8.2 降级写批新增。
309
+ * 锁步约束:键集须 ⊆ contracts zod 节点 schema(tests 键集锁步用例锁定)) */
310
+ export const SERVICE_INTEGRATION_NODE_KEYS = ['provider', 'implementation', 'config', 'credentialRef', 'instances'] as const;
311
+
312
+ /** services[s].instances[k] 可写键集单源(同上——实例位节点;'*' 通配为 map 键位,不属节点键集) */
313
+ export const SERVICE_INSTANCE_NODE_KEYS = ['provider', 'implementation', 'config', 'credentialRef', 'enabled'] as const;
314
+
302
315
  /** 模块资源回显(只读投影——N2 读半边:写侧仍仅 provider/config,resources 恒保全)。
303
316
  * 原值文件镜像(L1)+ ref 台账展开态:`ref` 在场且同目录 knowledge.json 命中时
304
317
  * `resolvedDatasetId` = 台账 datasetId(镜像 SDK resolveKnowledge 展开语义),未命中/台账缺失 = null。
@@ -483,6 +496,10 @@ export interface ContractsResolution {
483
496
  version: string | null;
484
497
  evaluation: boolean;
485
498
  strictValidation: boolean;
499
+ /** v6 形状标记(内部 ResolvedContracts.ownershipBindingV6 判据投影;additive 0.8.2——
500
+ * 消费语义:false = 偏斜降级(写轴 503 / 前端禁保存);**缺席 = 旧 toolkit 未投影,不得按降级处理**;
501
+ * 降级/阻断判定矩阵单源 = api.md §5 消费指引) */
502
+ ownershipBindingV6?: boolean;
486
503
  notes: string[];
487
504
  }
488
505
 
package/src/factory.ts CHANGED
@@ -3,7 +3,7 @@ import { writeAtomic } from './core/fskit.js';
3
3
  import { walkManifests as internalsWalk } from './assembly/walk-manifests.js';
4
4
  import type { FileCache } from './core/file-cache.js';
5
5
  import { createFileCache } from './core/file-cache.js';
6
- import { resolveContractsForApp, invalidateContractsResolver } from './core/contracts-resolver.js';
6
+ import { resolveContractsForApp, invalidateContractsResolver, contractsTier } from './core/contracts-resolver.js';
7
7
  import type { ResolvedContracts } from './core/contracts-resolver.js';
8
8
  import { parseModuleDescriptor } from './core/module-schema.js';
9
9
  import { loadProviderServiceDetailView, loadProvidersView } from './views/providers.js';
@@ -58,13 +58,15 @@ import type {
58
58
  * Read+Write = HTTP 直通面 additive 冻结(L1 端点↔方法 1:1,L3 命名镜像:Integration=节点级 /
59
59
  * Config=文件级);Internals = CLI/doctor/桥消费(自由演进)。
60
60
  *
61
- * **门控断言单点(policy at edge——v7 读求值轴退役后范围 = 写 + 迁移面)**:写(4)+
62
- * ensureMockBindings / writeIntegrationsConfig / evaluateIntegrationServices 入口
63
- * assertContractsUsable——strictValidation === false → 503 CONTRACTS_NOT_RESOLVED;静态方法不门控
64
- * (永不 503——铁律 #3);**读求值轴(loadServiceResolutions/loadServiceResolution 及 include 装配)
65
- * v7 起不再 503**——contracts 不可用 → 200 降级骨架(evaluation-unavailable,doctor 分级/ 先例
66
- * 对齐;依据链与裁决见 Agent Note evaluation-axis-degrade);**include 装配为条件分支非门控**
67
- * (null 分支退役——三条件门 + 内嵌轴同步降级,四面统一骨架);integrations/ views/ 机制层保持纯函数。
61
+ * **门控断言单点(policy at edge——0.8.2 降级写批收窄为 contractsTier 两策略)**:写×4 =
62
+ * tier !== 'blocked'(version null 降级放行——跳过 zod + STRICT_VALIDATION_SKIPPED warning 承载
63
+ * 感知;<0.9 已装/偏斜 503 升级指引);evaluate = tier === 'ok'(求值无降级语义);
64
+ * ensureMockBindings / writeIntegrationsConfig 无门(行为不随 contracts 状态分叉——纯 fs 派生 /
65
+ * 透传整写,blanket 残留摘除);静态方法不门控(永不 503——铁律 #3);**读求值轴(
66
+ * loadServiceResolutions/loadServiceResolution 及 include 装配)v7 起不再 503**——contracts 不可用
67
+ * → 200 降级骨架(evaluation-unavailable,doctor 分级先例对齐;依据链与裁决见 Agent Note
68
+ * evaluation-axis-degrade);**include 装配为条件分支非门控**(四面统一骨架);
69
+ * integrations/ views/ 机制层保持纯函数。
68
70
  *
69
71
  * 并发:进程内写串行(per-factory promise chain)+ 原子写 + 写后本实例缓存即刻失效。
70
72
  * onApplied:toolkit 判定「需要重启」(实际落盘且非 dryRun/no-diff)→ 调用一次 +
@@ -170,8 +172,10 @@ export interface AppToolkitInternals {
170
172
  loadProviderCatalogRaw(): ReturnType<typeof loadProviderCatalogRaw>;
171
173
  /** 文件级读(doctor/migrate;宽松透传——strict 校验归门控面) */
172
174
  readIntegrationsConfig(): Promise<Record<string, unknown> | null>;
173
- /** 文件级整写(provider-migrate;门控同款) */
175
+ /** 文件级整写(provider-migrate;0.8.2 降级写批摘门——行为不随 contracts 状态分叉,
176
+ * config 形状兼容性责任在调用方(保形迁移)) */
174
177
  writeIntegrationsConfig(config: Record<string, unknown>): Promise<void>;
178
+ /** mock 绑定物化(0.8.2 降级写批摘门——纯 fs 派生零 contracts 依赖) */
175
179
  ensureMockBindings(): Promise<ReturnType<typeof ensureMockBindings>>;
176
180
  /** 谓词单源(contracts 注入签名;结构化输出) */
177
181
  evaluateIntegrationServices(input: Omit<Parameters<typeof evaluateIntegrationServices>[0], 'contracts'>): Promise<IntegrationServiceIssue[]>;
@@ -185,15 +189,24 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
185
189
 
186
190
  const viewCtx = { appDir, cache };
187
191
 
188
- /** 门控断言(policy at edge)——strictValidation false → 503(message 三分支 N1);
189
- * v6 标记门:ownershipBindingV6 false → 503 第四分支(v5 contracts + v6 toolkit 偏斜
190
- * ——防静默忽略 ownerOf;门控范围 = 求值 + 写 + migrate 全体,本函数为唯一调用点)。 */
191
- function assertContractsUsable(contracts: ResolvedContracts): void {
192
- if (!contracts.strictValidation) {
192
+ /** 门控断言单点(policy at edge——0.8.2 降级写批收窄为 contractsTier 两策略,判据单源
193
+ * = core/contracts-resolver contractsTier;message 单源 = contractsNotResolvedMessage N1):
194
+ * - assertWritableContracts(写×4):tier === 'blocked' → 503——包在场但能力缺失(<0.9 已装 /
195
+ * 偏斜缺 v6 标记),v6 形状写入旧语境静默无效或被旧 zod 拒,fail-visible 拒绝 + 升级指引;
196
+ * version null(未装/未构建/导入拒绝)降级放行,跳过 zod 由写核 STRICT_VALIDATION_SKIPPED
197
+ * warning 承载感知。
198
+ * - assertFullyUsable(evaluate):tier !== 'ok' → 503——求值产物即求值结果,无降级可言
199
+ * (version null 亦不可求值)。
200
+ * - ensureMockBindings / writeIntegrationsConfig:无门(行为不随 contracts 状态分叉——
201
+ * 纯 fs 派生 / 透传整写零校验零形状生成,blanket 门控残留摘除;形状兼容性责任在调用方)。 */
202
+ function assertWritableContracts(contracts: ResolvedContracts): void {
203
+ if (contractsTier(contracts) === 'blocked') {
193
204
  throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
194
205
  }
195
- if (!contracts.ownershipBindingV6) {
196
- // v6 标记门第四分支(文案单源 = contractsNotResolvedMessage——降级轴 statusMessage 同源)
206
+ }
207
+
208
+ function assertFullyUsable(contracts: ResolvedContracts): void {
209
+ if (contractsTier(contracts) !== 'ok') {
197
210
  throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
198
211
  }
199
212
  }
@@ -365,13 +378,13 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
365
378
  async writeAppIntegration(node: AppIntegrationNode, o?: WriteOptions) {
366
379
  await core.warmup();
367
380
  const contracts = await resolveContractsForApp(appDir);
368
- assertContractsUsable(contracts);
381
+ assertWritableContracts(contracts);
369
382
  return enqueue(() => core.applyApp(node as Record<string, unknown>, o));
370
383
  },
371
384
  async writeModuleIntegration(moduleId: string, node: ModuleIntegrationNode, o?: WriteOptions) {
372
385
  await core.warmup();
373
386
  const contracts = await resolveContractsForApp(appDir);
374
- assertContractsUsable(contracts);
387
+ assertWritableContracts(contracts);
375
388
  // enqueue 闭包内双键解析(写时新鲜度)——落盘键恒真实 id
376
389
  return enqueue(() => {
377
390
  const mod = resolveModuleKey(snapshot(contracts).walk, moduleId);
@@ -381,7 +394,7 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
381
394
  async writeServiceIntegration(service: string, node: ServiceIntegrationNode, o?: WriteOptions) {
382
395
  await core.warmup();
383
396
  const contracts = await resolveContractsForApp(appDir);
384
- assertContractsUsable(contracts);
397
+ assertWritableContracts(contracts);
385
398
  return enqueue(() => {
386
399
  const snap = snapshot(contracts);
387
400
  const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
@@ -391,7 +404,7 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
391
404
  async deleteServiceIntegration(service: string) {
392
405
  await core.warmup();
393
406
  const contracts = await resolveContractsForApp(appDir);
394
- assertContractsUsable(contracts);
407
+ assertWritableContracts(contracts);
395
408
  return enqueue(() => {
396
409
  const snap = snapshot(contracts);
397
410
  const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
@@ -421,21 +434,20 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
421
434
  return readIntegrationsConfig(appDir, cache);
422
435
  },
423
436
  async writeIntegrationsConfig(config: Record<string, unknown>) {
424
- await core.warmup();
425
- const contracts = await resolveContractsForApp(appDir);
426
- assertContractsUsable(contracts);
437
+ // 无门(0.8.2 降级写批——行为不随 contracts 状态分叉:透传整写、零校验零形状生成,
438
+ // blanket 门控残留摘除;config 形状兼容性责任在调用方——CLI provider-migrate 保形迁移)。
439
+ // warmup 一并摘除(不跑 zod——严格校验缓存预热无消费方)
427
440
  return enqueue(() => coreWriteIntegrationsConfig(appDir, config, cache));
428
441
  },
429
442
  async ensureMockBindings() {
430
- await core.warmup();
431
- const contracts = await resolveContractsForApp(appDir);
432
- assertContractsUsable(contracts);
443
+ // 无门(0.8.2 降级写批——纯 fs 派生零 contracts 依赖,输出 v4 兼容形状(terse/双字段均无
444
+ // modules 键);fresh clone 装依赖前物化 mock 绑定正当)。warmup 一并摘除(零校验无消费方)
433
445
  return enqueue(() => ensureMockBindings(appDir));
434
446
  },
435
447
  async evaluateIntegrationServices(input) {
436
448
  await core.warmup();
437
449
  const contracts = await resolveContractsForApp(appDir);
438
- assertContractsUsable(contracts);
450
+ assertFullyUsable(contracts);
439
451
  const predicateContracts: PredicateContracts = {
440
452
  resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
441
453
  buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
@@ -1,4 +1,4 @@
1
- import { existsSync } from 'node:fs';
1
+ import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { walkManifests } from '../assembly/walk-manifests.js';
4
4
  import { writeAtomic } from '../core/fskit.js';
@@ -22,10 +22,40 @@ export interface MockBindingsResult {
22
22
  services: string[];
23
23
  }
24
24
 
25
+ /** 元键(create 种子可能预置 `$comment` 指针;生成绑定须保全——不可因派生覆盖丢失)。 */
26
+ const META_KEYS = ['$comment', '$schema'] as const;
27
+
28
+ /**
29
+ * pristine-empty 判定:文件在场但仍是 create 种子的空骨架(仅 services:{} + 可选元键)。
30
+ * 语义 = 视同缺席继续派生;任何用户事实(binding / modules / instances / credentialRef / config)
31
+ * 在场即 in-place 零侵入。坏 JSON 亦按用户文件处理(不覆盖)。
32
+ */
33
+ function isPristineEmpty(file: string): { pristine: boolean; meta: Record<string, unknown> } {
34
+ try {
35
+ const parsed = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown> | null;
36
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return { pristine: false, meta: {} };
37
+ // 只认「services + 元键」白名单:任何未知键 = 用户内容(含拼错键与全部事实键),不得覆盖。
38
+ const allowed = new Set<string>(['services', ...META_KEYS]);
39
+ if (Object.keys(parsed).some((key) => !allowed.has(key))) return { pristine: false, meta: {} };
40
+ const services = parsed.services;
41
+ if (!services || typeof services !== 'object' || Array.isArray(services) || Object.keys(services).length > 0) {
42
+ return { pristine: false, meta: {} };
43
+ }
44
+ const meta: Record<string, unknown> = {};
45
+ for (const key of META_KEYS) if (key in parsed) meta[key] = parsed[key];
46
+ return { pristine: true, meta };
47
+ } catch {
48
+ return { pristine: false, meta: {} };
49
+ }
50
+ }
51
+
25
52
  export function ensureMockBindings(appDir: string): MockBindingsResult {
26
53
  const file = join(appDir, 'config', 'integrations.json');
54
+ let meta: Record<string, unknown> = {};
27
55
  if (existsSync(file)) {
28
- return { generated: false, reason: 'in-place', services: [] };
56
+ const state = isPristineEmpty(file);
57
+ if (!state.pristine) return { generated: false, reason: 'in-place', services: [] };
58
+ meta = state.meta;
29
59
  }
30
60
  const slots: Array<{ service: string; provider: string; implementation: string }> = [];
31
61
  for (const mod of walkManifests(appDir).modules) {
@@ -43,13 +73,13 @@ export function ensureMockBindings(appDir: string): MockBindingsResult {
43
73
  // 单一 local 厂商 → terse:root.provider 继承 + 空槽对象(instances 缺席 = 通配激活)
44
74
  const [vendor] = vendors;
45
75
  for (const s of slots) services[s.service] = {};
46
- writeAtomic(file, `${JSON.stringify({ provider: vendor, services }, null, 2)}\n`);
76
+ writeAtomic(file, `${JSON.stringify({ ...meta, provider: vendor, services }, null, 2)}\n`);
47
77
  } else {
48
78
  // 异构兜底:逐槽双字段(显式绑定组——无 root 继承位;同样零拓扑)
49
79
  for (const s of slots) {
50
80
  services[s.service] = { provider: s.provider, implementation: s.implementation };
51
81
  }
52
- writeAtomic(file, `${JSON.stringify({ services }, null, 2)}\n`);
82
+ writeAtomic(file, `${JSON.stringify({ ...meta, services }, null, 2)}\n`);
53
83
  }
54
84
  return { generated: true, reason: 'generated', services: slots.map((s) => s.service).sort() };
55
85
  }
@@ -48,7 +48,7 @@ export async function readIntegrationsStrict(
48
48
  if (contracts.strictValidation && contracts.module.parseIntegrationsConfig) {
49
49
  // 严格链:assertNoInlineSecrets → 旧键直切防线 → zod strict(contracts 单源);
50
50
  // 失败转换(A1——裸 ZodError/Error 穿透 500 的同族缺口):zod → 400 + fields(原始路径——
51
- // 文件级读无节点上下文);普通 Error → 400 直通。结构性判定同 write.runStrictValidation。
51
+ // 文件级读无节点上下文);普通 Error → 400 直通。结构性判定同 write.validateOrDegrade。
52
52
  try {
53
53
  const parsed = contracts.module.parseIntegrationsConfig(raw);
54
54
  return { config: parsed as unknown as Record<string, unknown>, strict: true, contracts };
@@ -1,7 +1,7 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { join, resolve } from 'node:path';
3
3
  import Ajv from 'ajv';
4
- import { resolveContractsForApp } from '../core/contracts-resolver.js';
4
+ import { resolveContractsForApp, contractsTier } from '../core/contracts-resolver.js';
5
5
  import { stemToFilePath } from '../core/credential-format.js';
6
6
  import type { FileCache } from '../core/file-cache.js';
7
7
  import { writeAtomic } from '../core/fskit.js';
@@ -20,8 +20,8 @@ import type { IntegrationServiceIssue } from './predicate.js';
20
20
  import { checkInstanceKeys } from './predicate.js';
21
21
  import { isKnownService } from './read.js';
22
22
  import { moduleOwnershipWritable } from './module-binding.js';
23
- import { AppToolkitError } from '../core/errors.js';
24
- import { MODULE_INTEGRATION_NODE_KEYS } from '../dto.js';
23
+ import { AppToolkitError, contractsNotResolvedMessage } from '../core/errors.js';
24
+ import { MODULE_INTEGRATION_NODE_KEYS, SERVICE_INTEGRATION_NODE_KEYS, SERVICE_INSTANCE_NODE_KEYS } from '../dto.js';
25
25
 
26
26
  /**
27
27
  * 写核心(write;FX-1c 管线重排—— 九步定序 + D-B2 语义 + 输入扩位):
@@ -85,6 +85,33 @@ export function deepEqual(a: unknown, b: unknown): boolean {
85
85
  return false;
86
86
  }
87
87
 
88
+ /** 根级元键($comment/$schema):类型可选、行为惰性(contracts strictObject 显式放行)。
89
+ * 写路径保活——全量替换语义下从 current 显式携带;noDiff 由 deepEqualIgnoringRootMeta 排除根级元键。
90
+ * 节点级元键不种入(节点 schema 未放行),因此只需根级单点。 */
91
+ const META_KEYS = ['$comment', '$schema'] as const;
92
+
93
+ function carryRootMeta(next: Record<string, unknown>, current: Record<string, unknown> | null): void {
94
+ if (!current) return;
95
+ for (const key of META_KEYS) {
96
+ if (!(key in next) && key in current) next[key] = current[key];
97
+ }
98
+ }
99
+
100
+ /** noDiff 比较排除根级元键(纯注释变化不触发写;实际注释由 carryRootMeta 保全)。 */
101
+ function withoutRootMeta(value: Record<string, unknown> | null): Record<string, unknown> | null {
102
+ if (value === null) return null;
103
+ const rest = { ...value };
104
+ for (const key of META_KEYS) delete rest[key];
105
+ return rest;
106
+ }
107
+
108
+ function deepEqualIgnoringRootMeta(
109
+ a: Record<string, unknown> | null,
110
+ b: Record<string, unknown> | null,
111
+ ): boolean {
112
+ return deepEqual(withoutRootMeta(a), withoutRootMeta(b));
113
+ }
114
+
88
115
  /** 输入约束①(安全钉子, 扩位):node 内 provider/instanceId 值位 + map 键位字符集校验
89
116
  * (第一道;deriveStem 断言为第二道)。违例 → 400 + fields 指向。 */
90
117
  function assertSafeNames(value: unknown, path: string): void {
@@ -148,6 +175,25 @@ function assertSafeInstanceKeys(node: Record<string, unknown>, writeOpts: WriteO
148
175
  assertSafeMapKeys(writeOpts.credentialsByInstance, 'credentialsByInstance', false);
149
176
  }
150
177
 
178
+ /** 节点键集纪律单点(0.8.2 降级写批):未知键 400——zod 未知键拒绝语义前移为静态检查,
179
+ * 两态一致(降级态无 zod 此为唯一形状防线;ok 态同码 400 先行、fields 更精确)。
180
+ * 维度边界:仅键集(键名 ∈ 白名单),不查值类型/嵌套形状——非对象值静默跳过由 zod
181
+ * (ok 态)/ 滞后校验(降级态,后装依赖 doctor/求值轴暴露)兜底。
182
+ * 锁步约束:allowed 须 ⊆ contracts zod 节点 schema 键集(tests 键集锁步用例锁定)。 */
183
+ function assertNodeKeys(node: unknown, allowed: readonly string[], where: string): void {
184
+ if (!node || typeof node !== 'object' || Array.isArray(node)) return;
185
+ for (const k of Object.keys(node as Record<string, unknown>)) {
186
+ if (!(allowed as readonly string[]).includes(k)) {
187
+ throw new AppToolkitError(
188
+ 'VALIDATION_FAILED',
189
+ 400,
190
+ `${where} 仅接受 ${allowed.join('/')} 键(收到 ${k})`,
191
+ [k],
192
+ );
193
+ }
194
+ }
195
+ }
196
+
151
197
  /** 写时读当前配置(cache 优先;缺席 → null——调用方决定骨架物化) */
152
198
  function loadConfig(appDir: string, cache?: FileCache): Record<string, unknown> | null {
153
199
  const file = join(appDir, INTEGRATIONS_FILE);
@@ -298,21 +344,36 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
298
344
  .filter((p) => p.length > 0);
299
345
  }
300
346
 
301
- /** 严格整文档校验(A1 单点转换):zod → 400 + fields(节点相对);普通 Error(旧键直切/
302
- * 内联密钥防线——contracts parseIntegrationsConfig 内部 assert 族)→ 同族 400 message 直通。
303
- * 结构性 ZodError 判定(禁 instanceof——contracts 动态 import,类身份跨模块实例不可靠)。 */
304
- function runStrictValidation(next: Record<string, unknown>, issues: IntegrationServiceIssue[], prefix: string): void {
305
- const strict = strictContracts;
306
- if (!strict || !strict.strictValidation || !strict.module.parseIntegrationsConfig) {
347
+ /** 整文档校验三向(0.8.2 降级写批——runStrictValidation 重构为 contractsTier 分流):
348
+ * ok → contracts zod 严格校验(zod → 400 + fields 节点相对,A1 单点转换;普通 Error
349
+ * ——旧键直切/内联密钥防线——同族 400 message 直通;结构性 ZodError 判定禁 instanceof
350
+ * ——contracts 动态 import,类身份跨模块实例不可靠);degraded → 跳过 zod +
351
+ * STRICT_VALIDATION_SKIPPED warning(message = contractsNotResolvedMessage N1 单源——
352
+ * 装/构建指引随行,fail-visible);blocked → 防御式 503(工厂边缘 assertWritableContracts
353
+ * 应已拦截,此处兜底)。 */
354
+ function validateOrDegrade(next: Record<string, unknown>, issues: IntegrationServiceIssue[], prefix: string): void {
355
+ if (!strictContracts) {
307
356
  throw new AppToolkitError(
308
357
  'CONTRACTS_NOT_RESOLVED',
309
358
  503,
310
- 'contracts 严格校验面不可用(需 ≥0.9)——写路径门控失败(工厂边缘断言应先行拦截)',
359
+ 'contracts 严格校验面不可用——写路径门控失败(工厂边缘断言应先行拦截)',
311
360
  );
312
361
  }
313
- void issues;
362
+ const tier = contractsTier(strictContracts);
363
+ if (tier === 'blocked') {
364
+ throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(strictContracts));
365
+ }
366
+ if (tier === 'degraded') {
367
+ issues.push({
368
+ severity: 'warning',
369
+ code: 'STRICT_VALIDATION_SKIPPED',
370
+ message: contractsNotResolvedMessage(strictContracts),
371
+ });
372
+ return;
373
+ }
314
374
  try {
315
- strict.module.parseIntegrationsConfig(next);
375
+ // tier ok 蕴含 parseIntegrationsConfig 在场(resolver strictValidation 判据 = 该导出在场)
376
+ strictContracts.module.parseIntegrationsConfig!(next);
316
377
  } catch (err) {
317
378
  if (err instanceof Error && Array.isArray((err as { issues?: unknown }).issues)) {
318
379
  throw new AppToolkitError(
@@ -332,6 +393,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
332
393
  applyApp(node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
333
394
  assertSafeNames(node, 'root');
334
395
  assertSafeInstanceKeys(node, writeOpts, 'root');
396
+ assertNodeKeys(node, APP_INTEGRATION_NODE_KEYS, 'root');
335
397
  const issues: IntegrationServiceIssue[] = [];
336
398
  const current = loadConfig(appDir, cache);
337
399
  const base: Record<string, unknown> = current ?? { services: {} };
@@ -343,7 +405,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
343
405
  });
344
406
  }
345
407
  // root 全量替换(无例外语义):缺席根键删除(services/modules 域不在根键集——随 base 保留;v6 domains 键已退役),
346
- // node 全键置入(未知键交严格 zod 拒——fail-visible;B10:原实现 spread+merge 残留 stale 根键)
408
+ // node 全键置入(未知键已被 assertNodeKeys 前置 400——0.9.0 键集静态防线;B10:原实现 spread+merge 残留 stale 根键)
347
409
  const next: Record<string, unknown> = { ...base };
348
410
  for (const k of APP_INTEGRATION_NODE_KEYS) if (!(k in node)) delete next[k];
349
411
  for (const [k, v] of Object.entries(node)) next[k] = v;
@@ -361,12 +423,13 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
361
423
  }
362
424
  next.credentialRefByInstance = byInstance;
363
425
  }
426
+ carryRootMeta(next, current);
364
427
  const hasCredentialInput = writeOpts.credentials !== undefined || writeOpts.credentialsByInstance !== undefined;
365
- const noDiff = deepEqual(current, next);
428
+ const noDiff = deepEqualIgnoringRootMeta(current, next);
366
429
  if (noDiff && !hasCredentialInput) {
367
430
  return { written: false, restartScheduled: false, files: [], credentials: [], issues };
368
431
  }
369
- runStrictValidation(next, issues, '');
432
+ validateOrDegrade(next, issues, '');
370
433
  // 凭据工件落盘(后置于校验通过;dryRun 零写盘 + existsSync 预览)
371
434
  const dryRun = writeOpts.dryRun === true;
372
435
  const applied = writeCredentialArtifacts(appDir, plan, dryRun);
@@ -409,17 +472,8 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
409
472
  const base: Record<string, unknown> = current ?? { services: {} };
410
473
  const modulesNode = { ...((base.modules as Record<string, unknown>) ?? {}) };
411
474
  const existing = { ...((modulesNode[moduleId] as Record<string, unknown> | undefined) ?? {}) };
412
- // 键集纪律:node 内仅接受 MODULE_INTEGRATION_NODE_KEYS 成员(未知键交严格 zod 拒——fail-visible)
413
- for (const k of Object.keys(node)) {
414
- if (!(MODULE_INTEGRATION_NODE_KEYS as readonly string[]).includes(k)) {
415
- throw new AppToolkitError(
416
- 'VALIDATION_FAILED',
417
- 400,
418
- `模块集成位仅接受 ${MODULE_INTEGRATION_NODE_KEYS.join('/')} 键(收到 ${k})`,
419
- [k],
420
- );
421
- }
422
- }
475
+ // 键集纪律(assertNodeKeys 单点——无条件两态一致 400;resources 不属可写键集恒保全)
476
+ assertNodeKeys(node, MODULE_INTEGRATION_NODE_KEYS, `modules.${moduleId}`);
423
477
  // 全量替换(键集内):缺席键删除;空对象/空串值 = 删除(≡ 缺席——模块节点不留空键);
424
478
  // PUT {} = 清 provider/config,resources 恒随 existing 保全(N2:清集成位不杀资源绑定)
425
479
  const nextNode: Record<string, unknown> = { ...existing };
@@ -436,10 +490,11 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
436
490
  modulesNode[moduleId] = nextNode;
437
491
  }
438
492
  const next: Record<string, unknown> = { ...base, modules: modulesNode };
493
+ carryRootMeta(next, current);
439
494
  if (deepEqual(current, next)) {
440
495
  return { written: false, restartScheduled: false, files: [], credentials: [], issues };
441
496
  }
442
- runStrictValidation(next, issues, `modules.${moduleId}.`);
497
+ validateOrDegrade(next, issues, `modules.${moduleId}.`);
443
498
  issues.push(...registryCheck(next));
444
499
  return finalize(next, [], issues, writeOpts.dryRun);
445
500
  },
@@ -447,6 +502,12 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
447
502
  applyService(service: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
448
503
  assertSafeNames(node, 'root');
449
504
  assertSafeInstanceKeys(node, writeOpts, 'slot');
505
+ // 键集纪律(assertNodeKeys 单点):节点位 + 实例位双层('*' 为 instances map 键位,
506
+ // 不属实例节点键集;实例 map 键字符集归 assertSafeInstanceKeys)
507
+ assertNodeKeys(node, SERVICE_INTEGRATION_NODE_KEYS, `services.${service}`);
508
+ for (const [k, inst] of Object.entries((node.instances as Record<string, Record<string, unknown>> | undefined) ?? {})) {
509
+ assertNodeKeys(inst, SERVICE_INSTANCE_NODE_KEYS, `services.${service}.instances.${k}`);
510
+ }
450
511
  const issues: IntegrationServiceIssue[] = [];
451
512
  const current = loadConfig(appDir, cache);
452
513
  // 服务身份判据单源(A2):写入集 = 词汇 ∪ 已配置 ∪ 归属——未知服务(含 typo)404(api.md §5;
@@ -466,6 +527,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
466
527
  const base: Record<string, unknown> = current ?? { services: {} };
467
528
  const services = { ...((base.services as Record<string, unknown>) ?? {}) };
468
529
  const next: Record<string, unknown> = { ...base, services };
530
+ carryRootMeta(next, current);
469
531
  // N3:服务节点 {} 不归一化(显式通配激活 = 合法 TIER0 态,与键缺席两义)——原样落位
470
532
  services[service] = { ...node };
471
533
  // 凭据纯派生 + 校验链(dryRun 也跑;内联声明 credentialType 为校验链输入)
@@ -491,12 +553,13 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
491
553
  }
492
554
  slotNode.instances = instances;
493
555
  }
556
+ carryRootMeta(next, current);
494
557
  const hasCredentialInput = writeOpts.credentials !== undefined || writeOpts.credentialsByInstance !== undefined;
495
- const noDiff = deepEqual(current, next);
558
+ const noDiff = deepEqualIgnoringRootMeta(current, next);
496
559
  if (noDiff && !hasCredentialInput) {
497
560
  return { written: false, restartScheduled: false, files: [], credentials: [], issues };
498
561
  }
499
- runStrictValidation(next, issues, `services.${service}.`);
562
+ validateOrDegrade(next, issues, `services.${service}.`);
500
563
  // 凭据工件落盘(后置于校验通过;dryRun 零写盘 + existsSync 预览)
501
564
  const dryRun = writeOpts.dryRun === true;
502
565
  const applied = writeCredentialArtifacts(appDir, plan, dryRun);
@@ -39,6 +39,7 @@ function toContractsResolution(contracts: ResolvedContracts): ContractsResolutio
39
39
  version: contracts.version,
40
40
  evaluation: contracts.evaluation,
41
41
  strictValidation: contracts.strictValidation,
42
+ ownershipBindingV6: contracts.ownershipBindingV6,
42
43
  notes: [...contracts.notes],
43
44
  };
44
45
  }
@@ -369,9 +370,10 @@ export type { IntegrationIssue };
369
370
  // contracts 不可用(未安装 / 无严格面 / 求值面缺席 / v6 标记缺席)时,读求值轴不再 503,
370
371
  // 改投静态骨架(walk + integrations 纯文件投影,零 contracts 依赖)+ evaluation-unavailable 标记。
371
372
  // 依据链:doctor 分级先例(未安装 = warning 正常态)+ include→null 先例;fail-visible 语义
372
- // 保留在数据内(status + statusMessage N1 分支文案),写路径与 internals 门控不变。
373
+ // 保留在数据内(status + statusMessage N1 分支文案),写路径与 internals 门控不变(0.8.2 降级
374
+ // 写批起写轴分层演进:version null 降级写 / blocked 503——见 Agent Note write-axis-degrade)。
373
375
 
374
- /** 读求值轴可用判据(三条件与——降级门单源;写路径 assertContractsUsable 另有 503 语义,不复用) */
376
+ /** 读求值轴可用判据(三条件与——降级门单源;写路径 assertWritableContracts 另有 503 语义,不复用) */
375
377
  export function contractsEvaluable(contracts: ResolvedContracts): boolean {
376
378
  return contracts.evaluation && contracts.strictValidation && contracts.ownershipBindingV6;
377
379
  }
@@ -1,7 +1,7 @@
1
1
  import { describe, it, expect, beforeEach } from 'vitest';
2
2
  import { mkdirSync, writeFileSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
- import { resolveContractsForApp, invalidateContractsResolver } from '../src/core/contracts-resolver.js';
4
+ import { resolveContractsForApp, invalidateContractsResolver, contractsTier } from '../src/core/contracts-resolver.js';
5
5
  import {
6
6
  bumpMtime,
7
7
  createTempApp,
@@ -201,3 +201,18 @@ describe('contracts-resolver(D3 方案心脏)', () => {
201
201
  expect(after.strictValidation).toBe(true);
202
202
  });
203
203
  });
204
+
205
+ describe('contractsTier 状态机(0.8.2 降级写批——穷举锁)', () => {
206
+ it('四可达组合 + 畸形保守 blocked(version-null 分界轴:无包可依 = degraded,包在场能力缺失 = blocked)', () => {
207
+ // 未安装/未构建/导入拒绝(UNRESOLVED 形态)——唯一降级放行态
208
+ expect(contractsTier({ version: null, strictValidation: false, ownershipBindingV6: false })).toBe('degraded');
209
+ // 健康全绿
210
+ expect(contractsTier({ version: '0.13.0', strictValidation: true, ownershipBindingV6: true })).toBe('ok');
211
+ // <0.9 已装(v5 旧代码在场——v6 形状写入静默无效)
212
+ expect(contractsTier({ version: '0.8.2', strictValidation: false, ownershipBindingV6: false })).toBe('blocked');
213
+ // 偏斜(≥0.9 缺 OWNERSHIP_BINDING_V6 标记——v6 形状被旧 zod 拒)
214
+ expect(contractsTier({ version: '0.9.0', strictValidation: true, ownershipBindingV6: false })).toBe('blocked');
215
+ // 畸形(有标记无严格面——现实中不可达,保守 blocked)
216
+ expect(contractsTier({ version: '0.13.0', strictValidation: false, ownershipBindingV6: true })).toBe('blocked');
217
+ });
218
+ });
package/tests/demo-app.ts CHANGED
@@ -76,7 +76,7 @@ export interface FakeContractsOptions {
76
76
  * 入参 (integrations, service, instanceId, supplies, ownerOf),需 return EffectiveServiceResolution 形状) */
77
77
  resolveBody?: string;
78
78
  /** v6 形状标记(OWNERSHIP_BINDING_V6)缺席 fixture——默认在场(v6 假件签名随动 N11);
79
- * false = v5 contracts 形态(ownershipBindingV6: false → assertContractsUsable 503 第四分支) */
79
+ * false = v5 contracts 形态(ownershipBindingV6: false → contractsTier blocked 503——写轴阻断保留) */
80
80
  withMarker?: boolean;
81
81
  /** service-slots.json 词汇(P9 身份判据/求值键集;缺省不物化 = 词汇空) */
82
82
  slots?: string[];