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,119 @@
+/**
+ * 任务视图与草稿层叠加 —— 纯逻辑,零 IO(编码规范 §7.2 / §5.3)。
+ *
+ * 语义出处 OS 09 / AM 10.3:
+ *   任务视图 = 正式版 + 本任务草稿层(**读己之写**:本任务可见、正式版不可见、不产生数据事件);
+ *   环内推进读任务视图,不依赖事件;跨任务监听只认正式版事件。
+ */
+import type { LedgerKey, LedgerRow } from '@contracts';
+
+export type DraftEntry = {
+  readonly key: LedgerKey;
+  readonly patch: LedgerRow;
+  readonly tombstone: boolean;
+  /** 草稿建立时读到的基线值 —— 放行前的数据冲突检查用 */
+  readonly baseline: LedgerRow;
+};
+
+/** 主键的规范化串:字段名排序后拼接,保证同一行的键恒等 */
+export function keyOf(key: LedgerKey): string {
+  return Object.keys(key)
+    .sort()
+    .map((k) => `${k}=${String(key[k])}`)
+    .join('|');
+}
+
+/**
+ * 叠加:正式版行 + 本任务草稿 patch → 任务视图行。
+ * 草稿新增的行(正式版没有)也出现在视图里;tombstone 的行从视图中消失。
+ */
+export function overlay(
+  official: readonly LedgerRow[],
+  drafts: readonly DraftEntry[],
+  primaryKey: readonly string[],
+): LedgerRow[] {
+  const draftByKey = new Map(drafts.map((d) => [keyOf(d.key), d]));
+  const seen = new Set<string>();
+  const out: LedgerRow[] = [];
+
+  for (const row of official) {
+    const k = keyOf(pickKey(row, primaryKey));
+    seen.add(k);
+    const draft = draftByKey.get(k);
+    if (draft === undefined) {
+      out.push(row);
+      continue;
+    }
+    if (draft.tombstone) continue;
+    out.push({ ...row, ...draft.patch });
+  }
+
+  for (const draft of drafts) {
+    const k = keyOf(draft.key);
+    if (seen.has(k) || draft.tombstone) continue;
+    out.push({ ...draft.key, ...draft.patch });
+  }
+
+  return out;
+}
+
+export function pickKey(row: LedgerRow, primaryKey: readonly string[]): LedgerKey {
+  const key: Record<string, string | number> = {};
+  for (const field of primaryKey) {
+    const value = row[field];
+    if (typeof value === 'string' || typeof value === 'number') key[field] = value;
+    else if (value !== undefined && value !== null) key[field] = String(value);
+  }
+  return key;
+}
+
+/* ── 数据冲突检查(落地预检第五项,OS 7.3) ────────────────────────── */
+
+export type ConflictFinding = {
+  readonly key: LedgerKey;
+  readonly field: string;
+  readonly baseline: unknown;
+  readonly official: unknown;
+  readonly draft: unknown;
+};
+
+/**
+ * 草稿层所改字段与正式版的并发冲突:**他单已改同一字段即预检不过**,
+ * 打回环内基于新正式版重拟。
+ *
+ * 判据:草稿建立时读到的基线值 ≠ 当前正式版值 ⇒ 冲突。
+ * 只检查草稿实际修改过的字段 —— 没碰的字段被别人改了不算冲突。
+ */
+export function detectConflicts(
+  drafts: readonly DraftEntry[],
+  officialByKey: ReadonlyMap<string, LedgerRow>,
+): ConflictFinding[] {
+  const findings: ConflictFinding[] = [];
+  for (const draft of drafts) {
+    const official = officialByKey.get(keyOf(draft.key));
+    if (official === undefined) continue; // 草稿新增的行,无从冲突
+    for (const field of Object.keys(draft.patch)) {
+      const baseline = draft.baseline[field];
+      const current = official[field];
+      if (!sameValue(baseline, current)) {
+        findings.push({
+          key: draft.key,
+          field,
+          baseline,
+          official: current,
+          draft: draft.patch[field],
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function sameValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || a === undefined) return b === null || b === undefined;
+  if (b === null || b === undefined) return false;
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  if (typeof a === 'object' || typeof b === 'object') return JSON.stringify(a) === JSON.stringify(b);
+  return String(a) === String(b);
+}