@republicroad/zen-udf 0.2.0

package/src/contrib/http.test.ts

@@ -0,0 +1,230 @@
+import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'node:http';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+
+import { globalUdfRegistry } from '../register.ts';
+import { httpRequest } from './http.ts';
+
+let server: Server;
+let baseUrl: string;
+let closedUrl: string;
+
+/** /flaky 连续失败计数(每个用例开始前重置)；/missing 命中计数(用于断言 4xx 不重试) */
+let flakyRemaining = 0;
+let missingHits = 0;
+
+const json = (res: ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+
+const readBody = (req: IncomingMessage): Promise<string> =>
+  new Promise((resolve) => {
+    let data = '';
+    req.on('data', (chunk: Buffer | string) => (data += chunk));
+    req.on('end', () => resolve(data));
+  });
+
+beforeAll(async () => {
+  server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (url.pathname === '/json') {
+      json(res, 200, { ok: true, q: url.searchParams.get('q') });
+      return;
+    }
+    if (url.pathname === '/params') {
+      const query: Record<string, string> = {};
+      url.searchParams.forEach((value, key) => {
+        query[key] = value;
+      });
+      json(res, 200, query);
+      return;
+    }
+    if (url.pathname === '/echo') {
+      const bodyText = await readBody(req);
+      json(res, 200, {
+        method: req.method,
+        contentType: req.headers['content-type'] ?? null,
+        authorization: req.headers['authorization'] ?? null,
+        body: bodyText ? JSON.parse(bodyText) : null,
+      });
+      return;
+    }
+    if (url.pathname === '/slow') {
+      setTimeout(() => json(res, 200, 'late'), 500);
+      return;
+    }
+    if (url.pathname === '/flaky') {
+      if (flakyRemaining > 0) {
+        flakyRemaining -= 1;
+        res.writeHead(500);
+        res.end('boom');
+        return;
+      }
+      json(res, 200, { ok: true });
+      return;
+    }
+    if (url.pathname === '/missing') {
+      missingHits += 1;
+      res.writeHead(404);
+      res.end('not found');
+      return;
+    }
+    res.writeHead(404);
+    res.end('not found');
+  });
+  server.listen(0, '127.0.0.1', () => {
+    baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+  });
+
+  // closedUrl：起服后立即关闭，用于连接拒绝场景
+  const throwaway = createServer((_req, res) => {
+    res.end('ok');
+  });
+  await new Promise<void>((resolve) => throwaway.listen(0, '127.0.0.1', resolve));
+  closedUrl = `http://127.0.0.1:${(throwaway.address() as { port: number }).port}`;
+  throwaway.close();
+});
+
+afterAll(() => {
+  server.close();
+});
+
+const callUdf = async (kwargs: Record<string, unknown>) => (await httpRequest(kwargs)) as Record<string, unknown>;
+
+describe('http_request udf', () => {
+  test('GET 解析 JSON 响应体', async () => {
+    const result = await callUdf({ url: `${baseUrl}/json?q=abc` });
+    expect(result['status']).toBe(200);
+    expect(result['error']).toBeUndefined();
+    expect(result['body']).toEqual({ ok: true, q: 'abc' });
+    const headers = result['headers'] as Record<string, string>;
+    expect(headers['content-type']).toContain('application/json');
+  });
+
+  test('POST 自动 JSON 序列化并补充 content-type', async () => {
+    const result = await callUdf({ url: `${baseUrl}/echo`, method: 'POST', body: { a: 1 } });
+    expect(result['status']).toBe(200);
+    expect(result['body']).toEqual({
+      method: 'POST',
+      contentType: 'application/json',
+      authorization: null,
+      body: { a: 1 },
+    });
+  });
+
+  test('显式 content-type 不被覆盖，空对象视为无请求体', async () => {
+    const withBody = await callUdf({
+      url: `${baseUrl}/echo`,
+      method: 'POST',
+      headers: { 'content-type': 'text/plain' },
+      body: { a: 1 },
+    });
+    expect((withBody['body'] as Record<string, unknown>)['contentType']).toBe('text/plain');
+
+    const emptyBody = await callUdf({ url: `${baseUrl}/echo`, method: 'POST', body: {} });
+    expect((emptyBody['body'] as Record<string, unknown>)['body']).toBeNull();
+  });
+
+  test('GET/HEAD 忽略 body，非 2xx 正常返回', async () => {
+    const getWithBody = await callUdf({ url: `${baseUrl}/echo`, body: { a: 1 } });
+    expect(getWithBody['status']).toBe(200);
+    expect((getWithBody['body'] as Record<string, unknown>)['method']).toBe('GET');
+    expect((getWithBody['body'] as Record<string, unknown>)['body']).toBeNull();
+
+    const notFound = await callUdf({ url: `${baseUrl}/missing` });
+    expect(notFound['status']).toBe(404);
+    expect(notFound['body']).toBe('not found');
+    expect(notFound['error']).toBeUndefined();
+  });
+
+  test('连接拒绝返回结构化错误而非抛出', async () => {
+    const result = await callUdf({ url: closedUrl });
+    expect(result['status']).toBe(0);
+    expect(typeof result['error']).toBe('string');
+    expect(String(result['error']).length).toBeGreaterThan(0);
+  });
+
+  test('非法 HTTP 方法被白名单拦截', async () => {
+    const result = await callUdf({ url: `${baseUrl}/echo`, method: 'TRACE' });
+    expect(result['status']).toBe(0);
+    expect(result['error']).toBe("unsupported http method 'TRACE'");
+  });
+
+  test('params 合并进 URL 查询串并覆盖同名参数', async () => {
+    const result = await callUdf({
+      url: `${baseUrl}/params?existing=keep&q=old`,
+      params: { q: 'new', page: '2' },
+    });
+    expect(result['status']).toBe(200);
+    expect(result['body']).toEqual({ existing: 'keep', q: 'new', page: '2' });
+  });
+
+  test('basic 认证生成 Authorization 头，显式头优先于 auth 配置', async () => {
+    const basic = await callUdf({
+      url: `${baseUrl}/echo`,
+      auth: { type: 'basic', username: 'alice', password: 's3cret' },
+    });
+    expect((basic['body'] as Record<string, unknown>)['authorization']).toBe(
+      `Basic ${Buffer.from('alice:s3cret', 'utf8').toString('base64')}`,
+    );
+
+    const overridden = await callUdf({
+      url: `${baseUrl}/echo`,
+      headers: { authorization: 'Bearer manual' },
+      auth: { type: 'bearer', token: 'auto' },
+    });
+    expect((overridden['body'] as Record<string, unknown>)['authorization']).toBe('Bearer manual');
+
+    const bearer = await callUdf({ url: `${baseUrl}/echo`, auth: { type: 'bearer', token: 'tk-1' } });
+    expect((bearer['body'] as Record<string, unknown>)['authorization']).toBe('Bearer tk-1');
+  });
+
+  test('timeout 超时返回结构化错误', async () => {
+    const result = await callUdf({ url: `${baseUrl}/slow`, timeout: 100 });
+    expect(result['status']).toBe(0);
+    expect(typeof result['error']).toBe('string');
+  });
+
+  test('retry 仅对 5xx 重试直至成功，4xx 不重试', async () => {
+    flakyRemaining = 2;
+    const recovered = await callUdf({ url: `${baseUrl}/flaky`, retry: 2 });
+    expect(recovered['status']).toBe(200);
+    expect(recovered['body']).toEqual({ ok: true });
+
+    flakyRemaining = 5;
+    const exhausted = await callUdf({ url: `${baseUrl}/flaky`, retry: 1 });
+    expect(exhausted['status']).toBe(500);
+
+    missingHits = 0;
+    const notRetried = await callUdf({ url: `${baseUrl}/missing`, retry: 3 });
+    expect(notRetried['status']).toBe(404);
+    expect(missingHits).toBe(1);
+  });
+
+  test('非法 URL 直接报错且不重试', async () => {
+    const result = await callUdf({ url: 'not-a-url', retry: 2 });
+    expect(result['status']).toBe(0);
+    expect(String(result['error'])).toContain('invalid url');
+  });
+
+  test('引擎路径：funcBindParams 按声明顺序位置绑定，url 缺省参数回退默认值', async () => {
+    const kwargs = globalUdfRegistry.funcBindParams('http_request', [`${baseUrl}/json`]);
+    expect(Object.keys(kwargs)).toEqual(['url', 'method', 'headers', 'body', 'params', 'timeout', 'retry', 'auth']);
+    expect(kwargs['method']).toBe('GET');
+    expect(kwargs['timeout']).toBe(10000);
+    expect(kwargs['retry']).toBe(0);
+    const result = (await globalUdfRegistry.call('http_request', kwargs)) as Record<string, unknown>;
+    expect(result['status']).toBe(200);
+    expect(result['body']).toEqual({ ok: true, q: null });
+  });
+
+  test('旧图兼容：仅前 4 个位置参数时新参数回退默认值并可正常执行', async () => {
+    const kwargs = globalUdfRegistry.funcBindParams('http_request', [`${baseUrl}/json`, 'POST', { x: '1' }, { a: 1 }]);
+    expect(kwargs['params']).toEqual({});
+    expect(kwargs['auth']).toEqual({});
+    expect(kwargs['timeout']).toBe(10000);
+    expect(kwargs['retry']).toBe(0);
+    const result = (await globalUdfRegistry.call('http_request', kwargs)) as Record<string, unknown>;
+    expect(result['status']).toBe(200);
+  });
+});

package/src/contrib/http.ts

@@ -0,0 +1,283 @@
+// http 域(http_request 函数，有专属 UI 设计，文件名即 namespace)
+import { getExecContext } from '../exec-context.ts';
+import { defineContrib, defineTool } from '../register.ts';
+
+/**
+ * 出口防护端口（执行规范 §6.3，U9）：按租户校验出口 URL，拒绝时抛错。
+ * verdict 注入真实 allowlist；未配置 = 允许所有出口（开发态默认）。
+ */
+export interface EgressGuard {
+  assertAllowed(url: string, tenantId: string | undefined): void | Promise<void>;
+}
+
+/** 密钥解析端口：图内 auth 值支持 `${secret:名称}` 引用，真实凭证按租户解析，不进图内容 */
+export interface SecretResolver {
+  resolve(ref: string, tenantId: string | undefined): string | Promise<string>;
+}
+
+let egressGuard: EgressGuard | undefined;
+let secretResolver: SecretResolver | undefined;
+
+export const configureHttpUdf = (options: { egressGuard?: EgressGuard; secretResolver?: SecretResolver }): void => {
+  egressGuard = options.egressGuard;
+  secretResolver = options.secretResolver;
+};
+
+const SECRET_REF_PATTERN = /^\$\{secret:([^}]+)\}$/;
+
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 100;
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_RETRIES = 5;
+const RETRY_BASE_DELAY_MS = 200;
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+
+const httpErrorResult = (error: string) => ({ status: 0, headers: {}, body: null, error });
+
+/** 宽松整数化：null/undefined/空串/非法值回退 fallback，并夹取 [min, max] */
+const coerceCount = (value: unknown, min: number, max: number, fallback: number): number => {
+  if (value === null || value === undefined || value === '') {
+    return fallback;
+  }
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, n));
+};
+
+/** 查询参数合并：URL 解析失败返回 null（由调用方直接报错，不参与重试） */
+const buildUrlWithParams = (rawUrl: string, params: Record<string, unknown>): string | null => {
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return null;
+  }
+  for (const [key, value] of Object.entries(params)) {
+    parsed.searchParams.set(key, String(value));
+  }
+  return parsed.toString();
+};
+
+/** 认证注入：headers 显式 Authorization 优先；basic 编码 user:password，bearer 直填 token */
+const applyAuthHeader = (requestHeaders: Record<string, string>, auth: Record<string, unknown>): void => {
+  const hasAuthorization = Object.keys(requestHeaders).some((k) => k.toLowerCase() === 'authorization');
+  if (hasAuthorization) {
+    return;
+  }
+  const type = String(auth.type ?? '')
+    .trim()
+    .toLowerCase();
+  if (type === 'basic') {
+    const raw = `${String(auth.username ?? '')}:${String(auth.password ?? '')}`;
+    const encoded = Buffer.from(raw, 'utf8').toString('base64');
+    requestHeaders['authorization'] = `Basic ${encoded}`;
+  } else if (type === 'bearer') {
+    const token = String(auth.token ?? '');
+    if (token) {
+      requestHeaders['authorization'] = `Bearer ${token}`;
+    }
+  }
+};
+
+interface HttpAttemptResult {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+  error?: undefined | string;
+  /** 策略性失败（egress/secret）：不参与重试 */
+  policyBlocked?: boolean;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** 网络异常/超时(status=0)、429 与 5xx 可重试；其余 4xx 属业务错误不重试；策略性失败不重试 */
+const shouldRetryResult = (result: HttpAttemptResult): boolean =>
+  !result.policyBlocked && (result.status === 0 || result.status === 429 || result.status >= 500);
+
+export const http_request = defineTool({
+  name: 'http_request',
+  description:
+    '发起 HTTP 请求, 返回响应结果 { status, headers, body }. 支持 params 查询参数合并、timeout 单次超时(默认 10s, 上限 60s)、' +
+    'retry 重试(仅网络异常/超时/5xx/429, 指数退避)与 auth 认证({ type: "basic", username, password } 或 { type: "bearer", token }, ' +
+    'headers 显式 Authorization 优先). 失败返回结构化错误 { status: 0, error }, 不抛出异常.',
+  parametersSchema: {
+    properties: {
+      url: {
+        type: 'string',
+        title: 'URL',
+        description: '请求地址',
+      },
+      method: {
+        type: 'string',
+        title: 'Method',
+        description: 'HTTP 方法(GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS)，默认 GET',
+        default: 'GET',
+      },
+      headers: {
+        type: 'object',
+        title: 'Headers',
+        description: '请求头键值对对象，默认无',
+        default: null,
+      },
+      body: {
+        type: 'object',
+        title: 'Body',
+        description:
+          '请求体对象(自动 JSON 序列化并补充 content-type: application/json)，GET/HEAD 忽略，空对象视为无请求体',
+        default: null,
+      },
+      params: {
+        type: 'object',
+        title: 'Params',
+        description: '查询参数键值对对象，合并到 URL 查询串(URL 已有同名参数时覆盖)，默认无',
+        default: null,
+      },
+      timeout: {
+        type: 'integer',
+        title: 'Timeout',
+        description: `单次请求超时毫秒数(${MIN_TIMEOUT_MS}–${MAX_TIMEOUT_MS})，默认 ${DEFAULT_TIMEOUT_MS}`,
+        default: DEFAULT_TIMEOUT_MS,
+      },
+      retry: {
+        type: 'integer',
+        title: 'Retry',
+        description: `失败重试次数(0–${MAX_RETRIES})，仅网络异常/超时/5xx/429 触发，指数退避，默认 0`,
+        default: 0,
+      },
+      auth: {
+        type: 'object',
+        title: 'Auth',
+        description:
+          "认证配置。Basic: { type: 'basic', username, password }；Bearer: { type: 'bearer', token }。headers 显式 Authorization 优先，默认无",
+        default: null,
+      },
+    },
+    required: ['url'],
+    title: 'http_request',
+    type: 'object',
+  },
+  returnsSchema: { type: 'object', title: 'http_request 函数返回', properties: {} },
+  fn: async function httpRequestUdf(kwargs: Record<string, unknown>) {
+    const rawUrl = String(kwargs?.url ?? '').trim();
+    const method =
+      String(kwargs?.method ?? 'GET')
+        .trim()
+        .toUpperCase() || 'GET';
+    const rawBody = asRecord(kwargs?.body);
+    const rawParams = asRecord(kwargs?.params);
+    const rawAuth = asRecord(kwargs?.auth);
+    const retryCount = coerceCount(kwargs?.retry, 0, MAX_RETRIES, 0);
+
+    if (!rawUrl) {
+      return httpErrorResult('url is required');
+    }
+    if (!HTTP_METHODS.has(method)) {
+      return httpErrorResult(`unsupported http method '${method}'`);
+    }
+
+    const url = buildUrlWithParams(rawUrl, rawParams);
+    if (!url) {
+      return httpErrorResult(`invalid url '${rawUrl}'`);
+    }
+
+    // 执行规范 §6.3：出口防护（egress 拒绝属策略性失败，不重试）
+    const tenantId = getExecContext()?.tenantId;
+    try {
+      await egressGuard?.assertAllowed(url, tenantId);
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      return { ...httpErrorResult('egress blocked by policy: ' + reason), policyBlocked: true };
+    }
+
+    // 执行规范：secret 引用解析（`${secret:名称}` → 按租户解析真实凭证，不进图内容）
+    const effectiveAuth = { ...rawAuth };
+    try {
+      if (secretResolver) {
+        for (const key of ['username', 'password', 'token']) {
+          const value = effectiveAuth[key];
+          if (typeof value === 'string') {
+            const ref = value.match(SECRET_REF_PATTERN);
+            if (ref) {
+              effectiveAuth[key] = await secretResolver.resolve(ref[1], tenantId);
+            }
+          }
+        }
+      } else {
+        for (const key of ['username', 'password', 'token']) {
+          if (typeof effectiveAuth[key] === 'string' && SECRET_REF_PATTERN.test(effectiveAuth[key])) {
+            return {
+              ...httpErrorResult(`secret reference in auth.${key} requires a configured secretResolver`),
+              policyBlocked: true,
+            };
+          }
+        }
+      }
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e);
+      return { ...httpErrorResult('secret resolve failed: ' + reason), policyBlocked: true };
+    }
+
+    const requestHeaders: Record<string, string> = {};
+    for (const [key, value] of Object.entries(asRecord(kwargs?.headers))) {
+      requestHeaders[String(key)] = String(value);
+    }
+    applyAuthHeader(requestHeaders, effectiveAuth);
+
+    let requestBody: string | undefined;
+    if (method !== 'GET' && method !== 'HEAD' && Object.keys(rawBody).length > 0) {
+      requestBody = JSON.stringify(rawBody);
+      const hasContentType = Object.keys(requestHeaders).some((k) => k.toLowerCase() === 'content-type');
+      if (!hasContentType) {
+        requestHeaders['content-type'] = 'application/json';
+      }
+    }
+
+    const attemptOnce = async (): Promise<HttpAttemptResult> => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: requestHeaders,
+          body: requestBody,
+          signal: controller.signal,
+        });
+        const responseText = await response.text();
+        let responseBody: unknown;
+        try {
+          responseBody = JSON.parse(responseText);
+        } catch {
+          responseBody = responseText;
+        }
+        return {
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: responseBody,
+        };
+      } catch (e) {
+        return { status: 0, headers: {}, body: null, error: e instanceof Error ? e.message : String(e) };
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+
+    const timeoutMs = coerceCount(kwargs?.timeout, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    let result = await attemptOnce();
+    for (let attempt = 1; attempt <= retryCount && shouldRetryResult(result); attempt += 1) {
+      await sleep(RETRY_BASE_DELAY_MS * 2 ** (attempt - 1));
+      result = await attemptOnce();
+    }
+    return result;
+  },
+});
+
+export const { fn: httpRequest } = http_request;
+
+export default defineContrib(import.meta.url, {
+  tools: [http_request],
+});

package/src/contrib/ip-location.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs';
+
+import { defineContrib, defineTool } from '../register.ts';
+
+/**
+ * 旧平台函数域重建（第六十九批 D2，docs/13 §8.3）：IP 属地解析。
+ * 数据集**不捆绑**——通过 env `IP_LOCATION_DATASET` 指向 JSON 文件（结构：
+ * `{ "<ip前缀>": { "country": "..", "province": "..", "city": "..", "isp": ".." }, ... }`，
+ * 最长前缀匹配）。未配置/未命中时返回空字段 + ip 回显（图内 returnSchema 的
+ * required 字段齐全，仿真链路可跑通）。
+ */
+
+interface GeoEntry {
+  country?: string;
+  province?: string;
+  city?: string;
+  isp?: string;
+}
+
+let cachedPath: string | undefined;
+let cachedDataset: Record<string, GeoEntry> | undefined;
+
+const loadDataset = (): Record<string, GeoEntry> => {
+  const p = process.env.IP_LOCATION_DATASET;
+  if (!p) return {};
+  if (cachedPath === p && cachedDataset) return cachedDataset;
+  try {
+    cachedDataset = JSON.parse(readFileSync(p, 'utf8')) as Record<string, GeoEntry>;
+    cachedPath = p;
+  } catch (error) {
+    console.warn('[ip_location] 数据集加载失败，按未配置处理:', error instanceof Error ? error.message : error);
+    cachedDataset = {};
+    cachedPath = p;
+  }
+  return cachedDataset;
+};
+
+export default defineContrib(import.meta.url, {
+  tools: [
+    defineTool({
+      name: 'ip_location',
+      description:
+        '旧域重建·IP 属地解析：按最长前缀匹配数据集（env IP_LOCATION_DATASET 指向 JSON）返回 country/province/city/isp；未命中返回空字段。',
+      parametersSchema: {
+        properties: {
+          ip: {
+            type: 'string',
+            title: 'IP',
+            description: '待解析的 IP 地址',
+          },
+        },
+      },
+      returnsSchema: {
+        type: 'object',
+        title: 'ip_location_result',
+        properties: {
+          country: { type: 'string', title: 'Country' },
+          province: { type: 'string', title: 'Province' },
+          city: { type: 'string', title: 'City' },
+          isp: { type: 'string', title: 'Isp' },
+          ip: { type: 'string', title: 'Ip' },
+        },
+        required: ['country', 'province', 'city', 'isp', 'ip'],
+      },
+      fn: function ipLocationUdf(kwargs: Record<string, unknown>) {
+        const ip = String(kwargs?.ip ?? '');
+        const dataset = loadDataset();
+        const hit = Object.keys(dataset)
+          .filter((prefix) => ip.startsWith(prefix))
+          .sort((a, b) => b.length - a.length)[0];
+        const geo = hit ? dataset[hit] : undefined;
+        return {
+          country: geo?.country ?? '',
+          province: geo?.province ?? '',
+          city: geo?.city ?? '',
+          isp: geo?.isp ?? '',
+          ip,
+        };
+      },
+    }),
+  ],
+});

package/src/contrib/legacy-graph-acceptance.test.ts

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from '../engine.ts';
+import { runWithExecContext } from '../exec-context.ts';
+import { deleteRoster, registerRoster } from '../roster.ts';
+import './custom-list-query.ts';
+import './ip-location.ts';
+import { __resetRateWindows } from './rate-window.ts';
+import './rate-window.ts';
+
+/**
+ * 第六十九批 D2 闭环验收：撞库攻击防御.json 仿真恢复。
+ * 该图 4 个 UDF 节点依赖 custom_list_query / ip_location / rate_1h / group_distinct_1h
+ * （docs/13 §7.3：此前验收降级为加载/渲染/编辑，仿真因 udf not found 暂缓）。
+ */
+const GRAPH = path.resolve(import.meta.dirname, '../../graph/撞库攻击防御.json');
+const LIST_NAME = '熊猫ip白名单';
+const ACTOR = 'acceptance-user';
+
+describe('撞库攻击防御.json 仿真验收（第六十九批 D2 闭环）', () => {
+  test('白名单命中路径：无 udf not found，custom_list_query result:true', async () => {
+    __resetRateWindows();
+    registerRoster({ name: LIST_NAME, items: ['8.8.8.8'] }, { tenantId: 'acceptance-tenant', actor: ACTOR });
+    const content = JSON.parse(readFileSync(GRAPH, 'utf8')) as unknown;
+    const zr = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 'acceptance-tenant', userId: ACTOR }, async () =>
+      zr.createDecisionWithCacheKey('chuangku-hit', JSON.stringify(content)),
+    );
+
+    const result = (await runWithExecContext({ tenantId: 'acceptance-tenant', userId: ACTOR }, () =>
+      zr.evaluateAsync('chuangku-hit', { ip: '8.8.8.8', phone: '13800000000' }, { trace: true }),
+    )) as { result?: { reason?: string }; performance?: string };
+    const s = JSON.stringify(result);
+
+    expect(s).not.toContain('udf not found');
+    // 命中语义：最终 reason 由白名单查询结果驱动（"ip白名单,通过"）
+    expect(result.result?.reason ?? '').toContain('白名单');
+    // custom_list_query 输出 {result:true} 进入 trace
+    expect(s).toContain('"result":true');
+    deleteRoster(LIST_NAME, { tenantId: 'acceptance-tenant', actor: ACTOR });
+  });
+
+  test('非白名单路径：频控/组去重/属地函数全部解析执行', async () => {
+    __resetRateWindows();
+    registerRoster({ name: LIST_NAME, items: ['8.8.8.8'] }, { tenantId: 'acceptance-tenant', actor: ACTOR });
+    const content = JSON.parse(readFileSync(GRAPH, 'utf8')) as unknown;
+    const zr = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 'acceptance-tenant', userId: ACTOR }, async () =>
+      zr.createDecisionWithCacheKey('chuangku-miss', JSON.stringify(content)),
+    );
+
+    const result = (await runWithExecContext({ tenantId: 'acceptance-tenant', userId: ACTOR }, () =>
+      zr.evaluateAsync('chuangku-miss', { ip: '9.9.9.9', phone: '13900000000' }, { trace: true }),
+    )) as unknown as Record<string, unknown>;
+    const s = JSON.stringify(result);
+
+    expect(s).not.toContain('udf not found');
+    // 指标计算节点（非白名单路径）的 UDF 输出进入 trace：rate 计数与组去重 pv
+    expect(s).toContain('"counter":1');
+    expect(s).toContain('"pv":1');
+    // ip_location 空 dataset 回退：字段齐全 + ip 回显
+    expect(s).toContain('"ip":"9.9.9.9"');
+    deleteRoster(LIST_NAME, { tenantId: 'acceptance-tenant', actor: ACTOR });
+  });
+});