M1: 底座 —— @contracts 首版 + event / ledger / org / llm

@contracts 首版(§8.1 九个文件): - id 品牌 ID / terminal 终态五名与归侧四标签 / envelope 信封六字段与四类事件 - card 工单两模式 + 对话卡族(形状对齐 2026-07-26 原型定稿) - contract7 契约七件 / ledger 三级寻址与写三分 / process-package 流程包 DSL 与触发器三类 - manifest 活动包清单六区(含 CMMN·DMN·步序声明的资产形状)/ org / api 路由契约模块(L1): - event 信封存储、归属解析三级短路、投递五诺、监听注册表、三级消费裁定 - ledger schema 自生长(最大化合并/最宽类型/只增不破坏)、任务视图叠加、写三分、冲突检查 - org 岗位授权(客体三类×动作三种)、停用前置检查、会话、种子播种 - llm 四元绑定、ModelGateway 三模式(live/record/replay)—— 两缝之一 app 装配:Hono 服务 + 鉴权中间件 + 治理台/工作台路由;drizzle 迁移;AES-256-GCM 凭证密封 ADR-007 工具链与门禁 · ADR-008 投递队列 · ADR-009 凭证加密 (ADR 编号自 007 续:编码规范 §14 已用到 006,README 写「从 005 续」是笔误) 门禁五道全绿;96 个测试通过,含对真实 PG 的 ledger 集成测试 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KeDBx2PHLavbURXB8LJJ7m
2026-07-27 00:59:14 +08:00
parent 7cd664af3a
commit 14d4fa046a
120 changed files with 15236 additions and 78 deletions
@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { isBound, pickSystemUse, toPublicView, validateBinding } from '../internal/domain/model-binding.ts';
+import type { ModelBinding } from '../internal/domain/model-binding.ts';
+import { callFingerprint, replayKey, stableStringify } from '../internal/domain/replay-key.ts';
+import type { TaskId } from '@contracts';
+
+const binding = (over: Partial<ModelBinding> = {}): ModelBinding => ({
+  id: 'i1',
+  name: 'quote-extractor',
+  provider: 'openai-compatible',
+  baseUrl: 'https://api.example.com/v1',
+  model: 'gpt-4o-mini',
+  apiKeyCipher: 'v1.aa.bb.cc',
+  systemUse: false,
+  enabled: true,
+  ...over,
+});
+
+describe('validateBinding —— 四元齐备才算绑定', () => {
+  it('四元齐备通过', () => {
+    expect(validateBinding(binding())).toEqual([]);
+    expect(isBound(binding())).toBe(true);
+  });
+
+  it('缺 API-Key 即未绑定', () => {
+    const v = validateBinding(binding({ apiKeyCipher: undefined }));
+    expect(v.map((x) => x.field)).toEqual(['apiKey']);
+    expect(isBound(binding({ apiKeyCipher: undefined }))).toBe(false);
+  });
+
+  it('URL 必须是 http(s)', () => {
+    expect(validateBinding(binding({ baseUrl: 'ftp://x' })).map((x) => x.field)).toEqual(['baseUrl']);
+    expect(validateBinding(binding({ baseUrl: '' })).map((x) => x.field)).toEqual(['baseUrl']);
+  });
+
+  it('模型名不得为空', () => {
+    expect(validateBinding(binding({ model: '  ' })).map((x) => x.field)).toEqual(['model']);
+  });
+
+  it('自定义模型名有字符集约束', () => {
+    expect(validateBinding(binding({ name: '模型 一' })).map((x) => x.field)).toEqual(['name']);
+  });
+});
+
+describe('toPublicView —— 结构上不可能泄漏密钥', () => {
+  it('只回是否已绑定', () => {
+    const view = toPublicView(binding());
+    expect(view).toEqual({
+      id: 'i1',
+      name: 'quote-extractor',
+      provider: 'openai-compatible',
+      baseUrl: 'https://api.example.com/v1',
+      model: 'gpt-4o-mini',
+      apiKeyBound: true,
+      systemUse: false,
+      enabled: true,
+    });
+    expect(JSON.stringify(view)).not.toContain('v1.aa.bb.cc');
+  });
+
+  it('未绑定时 apiKeyBound = false', () => {
+    expect(toPublicView(binding({ apiKeyCipher: '' })).apiKeyBound).toBe(false);
+  });
+});
+
+describe('pickSystemUse', () => {
+  it('取启用且标记系统用途的实例', () => {
+    const picked = pickSystemUse([
+      binding({ id: 'a', name: 'a', systemUse: false }),
+      binding({ id: 'b', name: 'b', systemUse: true, enabled: false }),
+      binding({ id: 'c', name: 'c', systemUse: true }),
+    ]);
+    expect(picked?.id).toBe('c');
+  });
+
+  it('没有即 undefined', () => {
+    expect(pickSystemUse([])).toBeUndefined();
+  });
+});
+
+describe('replayKey —— 按任务 × 步序号', () => {
+  it('有任务与步序号时用定位键', () => {
+    expect(replayKey({ model: 'm', prompt: 'p', taskId: 't1' as TaskId, stepNo: 3 })).toBe('task:t1#3');
+  });
+
+  it('缺定位时退到内容指纹,且同输入同键', () => {
+    const a = replayKey({ model: 'm', prompt: 'p', temperature: 0 });
+    const b = replayKey({ model: 'm', prompt: 'p', temperature: 0 });
+    expect(a).toBe(b);
+    expect(a.startsWith('fp:')).toBe(true);
+  });
+
+  it('不同 prompt 得不同键', () => {
+    expect(replayKey({ model: 'm', prompt: 'p1' })).not.toBe(replayKey({ model: 'm', prompt: 'p2' }));
+  });
+
+  it('指纹不含凭证字段', () => {
+    expect(callFingerprint({ model: 'm', prompt: 'p' })).not.toMatch(/key|token|authorization/i);
+  });
+});
+
+describe('stableStringify —— 键排序,指纹不随属性顺序漂移', () => {
+  it('对象键排序', () => {
+    expect(stableStringify({ b: 1, a: 2 })).toBe(stableStringify({ a: 2, b: 1 }));
+  });
+  it('嵌套与数组', () => {
+    expect(stableStringify({ a: [1, { d: 4, c: 3 }] })).toBe('{"a":[1,{"c":3,"d":4}]}');
+  });
+  it('null 与标量', () => {
+    expect(stableStringify(null)).toBe('null');
+    expect(stableStringify(3)).toBe('3');
+  });
+});