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

tools/it-database.ts

@@ -0,0 +1,60 @@
+/**
+ * 集成测试的库夹具(编码规范 §1:集成测试用 Testcontainers(PG))。
+ *
+ * 取库次序:
+ *   ① `JCAI_TEST_DATABASE_URL` / `DATABASE_URL` 指向的库可连 → 直接用(本机 docker-compose 最快)
+ *   ② 否则起一个 Testcontainers 的 PG16
+ *   ③ 两者都不可得 → 返回 undefined,集成测试**跳过并告警**(单元测试不受影响)
+ *
+ * 每个套件用**独立 schema 前缀**建表,互不干扰;结束即清理。
+ */
+import { Pool } from 'pg';
+
+export type ItDatabase = {
+  readonly url: string;
+  stop(): Promise<void>;
+};
+
+const FOUR_SCHEMAS = ['sys', 'ledger', 'mastra', 'queue'];
+
+async function reachable(url: string): Promise<boolean> {
+  const pool = new Pool({ connectionString: url, max: 1, connectionTimeoutMillis: 1500 });
+  try {
+    await pool.query('select 1');
+    return true;
+  } catch {
+    return false;
+  } finally {
+    await pool.end().catch(() => undefined);
+  }
+}
+
+async function ensureSchemas(url: string): Promise<void> {
+  const pool = new Pool({ connectionString: url, max: 1 });
+  try {
+    for (const schema of FOUR_SCHEMAS) await pool.query(`create schema if not exists "${schema}"`);
+  } finally {
+    await pool.end();
+  }
+}
+
+export async function startItDatabase(): Promise<ItDatabase | undefined> {
+  const configured = process.env['JCAI_TEST_DATABASE_URL'] ?? process.env['DATABASE_URL'] ?? 'postgres://jcai:jcai@localhost:54329/jcai';
+  if (await reachable(configured)) {
+    await ensureSchemas(configured);
+    return { url: configured, stop: async () => undefined };
+  }
+
+  try {
+    const { PostgreSqlContainer } = await import('@testcontainers/postgresql');
+    const container = await new PostgreSqlContainer('postgres:16-alpine').start();
+    const url = container.getConnectionUri();
+    await ensureSchemas(url);
+    return { url, stop: () => container.stop().then(() => undefined) };
+  } catch (error) {
+    process.stderr.write(
+      `⚠️  集成测试跳过:既连不上 ${configured},也起不了 Testcontainers(${error instanceof Error ? error.message : String(error)})\n`,
+    );
+    return undefined;
+  }
+}