@republicroad/zen-udf 0.2.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2024 GoRules.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @republicroad/zen-udf
+
+zen-engine 的 customNode UDF 运行时：**多函数实例执行规范 + UDF 注册表 + 决策缓存 + 多租户数据面端口**。
+
+基于 [@gorules/zen-engine](https://www.npmjs.com/package/@gorules/zen-engine)（2.0.2），补齐其在服务端执行自定义节点的完整能力。
+
+## 定位
+
+zen-engine 原生只执行内置节点类型；本包负责三件事：
+
+1. **执行规范**——customNode 内多函数实例（`udf;;arg;;arg` 的 `;;` 分隔表达式）的求值、位置参数→kwargs 绑定、必填校验、超时兜底、per-tenant 并发闸、错误 containment（UDF 报错降级为结构化错误，不中断图）
+2. **决策缓存**——L1 进程内缓存（LRU + 指标），键 `${tenantId}:${key}@${rev}`（与 `modelId:v{rev}` 模式对齐）。探针实证 zen-engine 函数 loader 无引擎级缓存，缓存责任在宿主
+3. **多租户上下文**——AsyncLocalStorage 贯穿 evaluate → customNode → UDF；ALS 不跨 zen-engine 的 Rust worker→TSFN 边界，运行时以输入保留键携带 ExecContext 并在回调内重建立（[上下文传播说明](../../docs/design/zen-udf-context-propagation.md)）
+
+## 快速上手
+
+```ts
+import { DecisionRuntime, type UdfPack, createUdfRegistry } from '@republicroad/zen-udf';
+
+// 业务函数包：纯数据 + 处理器（deploy-time 注册，租户差异走 ExecContext）
+const fraudPack: UdfPack = {
+  namespace: 'fraud',
+  tools: [
+    {
+      name: 'device_fingerprint_query',
+      parametersSchema: { properties: { deviceId: { type: 'string' } }, required: ['deviceId'], type: 'object' },
+      returnsSchema: { type: 'object', properties: {} },
+      fn: async (kwargs) => queryBackend(kwargs.deviceId as string),
+    },
+  ],
+};
+
+const runtime = new DecisionRuntime({
+  registry: createUdfRegistry({ packs: [fraudPack] }),
+  cacheCapacity: 500, // L1 容量
+  resultValidation: 'warn', // 返回值契约：off | warn(缺省) | enforce
+  limiter: myLimiter, // 可选：per-tenant 并发闸
+  metricsSink: (snapshot) => stats.gauge('zen_udf_cache_size', snapshot.size),
+});
+
+// 登记 + 执行（多租户：ExecContext 必须带 tenantId）
+await runWithExecContext({ tenantId: 't-1', userId: 'u-1' }, async () => {
+  runtime.createDecisionWithCacheKey('fraud-model', graphJson, 'v3');
+  const result = await runtime.evaluateAsync('fraud-model', { deviceId: 'dev-9' }, undefined, 'v3');
+});
+```
+
+## 端口（宿主实现，机制本仓、策略宿主）
+
+| 端口                 | 用途                                 | 参考实现                                                                                         |
+| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `RateStore`          | 滑动窗口频控存储                     | `InMemoryRateStore`（单实例语义；生产注入 Redis 实现，复用 `rateStoreConformance` 契约测试验收） |
+| `ConcurrencyLimiter` | per-tenant UDF 并发闸                | `InMemoryConcurrencyLimiter`（FIFO）/ `NoopConcurrencyLimiter`                                   |
+| `EgressGuard`        | http UDF 出口 allowlist（防 SSRF）   | 未配置 = 全放行                                                                                  |
+| `SecretResolver`     | 图内 `${secret:名称}` 凭证按租户解析 | 未配置 = secret 引用报错                                                                         |
+
+注入方式：`setRateStore(...)` / `new DecisionRuntime({ limiter })` / `configureHttpUdf({ egressGuard, secretResolver })`。
+
+## 参考函数域（builtin reference）
+
+`import '@republicroad/zen-udf'`（根导入）自动装载 contrib 参考域：`http_request`、`crypto`、`roster`、`custom_list_query`、`rate_1h`、`group_distinct_1h`、`ip_location`、debug 系列。实例隔离时用 `loadReferenceInto(registry)` 按需装载。
+
+## 多租户要点
+
+- ExecContext：`{ tenantId, userId?, requestId? }`；evaluate 入口强制 tenantId（单租户 CLI 用 `tenantExempt: true` 豁免）
+- 注册是 deploy-time 静态行为；租户差异（凭证/配额/白名单）在调用时经 ExecContext + 端口解析
+- 编译产物租户无关（同租户同模型共享缓存），数据面租户相关
+
+## 设计文档
+
+- [多租户最佳实践设计](../../docs/design/zen-udf-multi-tenant.md)
+- [开发计划（U 系列，已 shipped）](../../docs/design/zen-udf-development-plan.md)
+- [上下文跨边界传播](../../docs/design/zen-udf-context-propagation.md)
+- [包内命名规范](./docs/naming.md)
+
+## 测试
+
+```bash
+bun run test   # 98 tests，Bun 工具链（zen-engine 原生绑定）
+```

package/docs/naming.md

@@ -0,0 +1,40 @@
+# zen-udf 命名规范与重命名记录
+
+本文档是包内命名的事实来源（source of truth）：现行名称、语义依据、以及 2026-09 重命名的完整映射。在 git 历史、旧文档或跨仓讨论中遇到旧名时，按第二节映射表理解。
+
+## 现行命名
+
+| 名称 | 类型 | 位置 | 职责 |
+| --- | --- | --- | --- |
+| `DecisionRuntime` | class | `src/engine.ts` | 决策图运行时：包装 `ZenEngine`、按 key 版本化决策缓存（create/update/delete/getDecisionWithCacheKey）、graphAddons 图增强、`evaluate`/`evaluateAsync` 门面 |
+| `UdfRegistry` | class | `src/register.ts` | UDF 注册表：函数注册/查找、位置参数→kwargs 绑定（`funcBindParams`）、调用、JSON Schema 下发（编辑器侧边栏契约） |
+| `globalUdfRegistry` | singleton | `src/register.ts` | 全局默认注册表实例（U3 实例注入落地前的静态默认） |
+
+## 2026-09 重命名映射
+
+本次重命名落地于 commit `20f529e2`（同日宿主确认命名裁决）。
+
+| 旧名 | 新名 | 说明 |
+| --- | --- | --- |
+| `class ZenRule` | `class DecisionRuntime` | 主运行时类 |
+| `class UDFManager` | `class UdfRegistry` | 函数注册表类 |
+| 单例导出 `udfManager` | `globalUdfRegistry` | 全局默认实例 |
+| 静态字段 `ZenRule.udfManager` | `DecisionRuntime.registry` | U3 实例注入时此静态绑定将移除，改为实例字段 |
+
+## 为什么改名
+
+**`ZenRule` → `DecisionRuntime`**："Rule" 指向它执行的产物（规则图），不是它自身的职责；"Engine" 不可用（底层是 `ZenEngine`，zen-engine Rust 核心同名类为 `DecisionEngine`，套娃命名会造成灾难）。业界对"长生命周期对象：持有编译产物缓存 + 执行 + 生命周期钩子"的标准词是 **Runtime**（GraphQL runtime、Temporal runtime）。`DecisionRuntime` 在 verdict 的 model-execute 语境中读作"决策运行时"，自解释。
+
+**`UDFManager` → `UdfRegistry`**："Manager" 是命名反模式（说不清管理什么、怎么管理）。该类实际职责是注册表三合一：**注册 + 查找 + 调用**，外加参数绑定与 schema 下发。业界同场景（MCP/OpenAI tool registry、Fastify decorator registry、GraphQL resolver registry）的标准词是 **Registry**。
+
+## 刻意不改的部分
+
+以下名称保持不动，API 面的进一步演进（`UdfPack` 契约等）统一留给 U6 定形，避免两次破坏：
+
+- 函数级注册 API：`registerUdf` / `createExtRegister` / `defineContrib` / `defineTool`
+- 方法名：`registerFunction` / `udfFunctionSchema` / `funcBindParams` / `call` / `udfFunctionSchemaTools` / `udfFunctionSchemaNamespaces`
+- contrib 参考域文件名即 namespace 的约定
+
+## 兼容性说明
+
+改名落地时（commit `20f529e2`）包为 0.1.x private、**无任何外部消费者**，因此采取硬改、不设废弃别名。0.2.0（U6 后，发布 npm 公开仓）首发即新名。verdict 及后续消费方直接使用现行命名即可。

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@republicroad/zen-udf",
+  "version": "0.2.0",
+  "description": "zen-engine custom-node UDF runtime: multi-function execution spec, UdfPack registry, L1 decision cache, multi-tenant context & data-plane ports",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "dependencies": {
+    "@gorules/zen-engine": "2.0.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/context-hardening.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { getExecContext, runWithExecContext } from './exec-context.ts';
+import { UdfRegistry } from './register.ts';
+
+/** customNode 图：ctx_probe_udf 回显执行上下文的租户与用户 */
+const ctxGraph = (id: string) => ({
+  id,
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    {
+      id: 'c1',
+      type: 'customNode',
+      name: 'custom',
+      content: { kind: 'UDF', config: { expressions: [{ id: 'e1', key: 'ctx', value: 'ctx_probe_udf;;x' }] } },
+    },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [
+    { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+    { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+  ],
+});
+
+const makeRuntime = (): DecisionRuntime => {
+  const registry = new UdfRegistry();
+  registry.registerFunction(function ctx_probe_udf() {
+    return {
+      tenant: getExecContext()?.tenantId ?? null,
+      user: getExecContext()?.userId ?? null,
+    };
+  }, 'probe');
+  return new DecisionRuntime({ registry });
+};
+
+describe('V5 上下文加固', () => {
+  test('混合租户并发 evaluate：各请求 UDF 内看到各自租户（embed 随请求走，无串号）', async () => {
+    const runtime = makeRuntime();
+    const tenants = ['t-alpha', 't-beta', 't-gamma', 't-delta'];
+    // 每租户各自注册（L1 缓存键含租户）
+    await Promise.all(
+      tenants.map((tenantId) =>
+        runWithExecContext({ tenantId }, () => {
+          runtime.createDecisionWithCacheKey('k', ctxGraph('g-mixed'));
+          return Promise.resolve();
+        }),
+      ),
+    );
+
+    const results = await Promise.all(
+      tenants.map((tenantId, i) =>
+        runWithExecContext({ tenantId, userId: `user-${i}` }, () => runtime.evaluateAsync('k', { x: i }, undefined)),
+      ),
+    );
+    results.forEach((result, i) => {
+      const ctx = (result.result as { ctx?: { tenant?: string; user?: string } }).ctx;
+      expect(ctx?.tenant).toBe(tenants[i]);
+      expect(ctx?.user).toBe(`user-${i}`);
+    });
+  });
+
+  test('嵌入的 ExecContext 为冻结副本：UDF 内篡改不影响调用方', async () => {
+    const runtime = makeRuntime();
+    await runWithExecContext({ tenantId: 't-frozen' }, () => {
+      runtime.createDecisionWithCacheKey('k', ctxGraph('g-frozen'));
+      return Promise.resolve();
+    });
+
+    const sharedCtx = { tenantId: 't-frozen', userId: 'u-1' };
+    await runWithExecContext(sharedCtx, async () => {
+      const result = await runtime.evaluateAsync('k', {});
+      // UDF 内可见租户正确
+      expect((result.result as { ctx?: { tenant?: string } }).ctx?.tenant).toBe('t-frozen');
+      // 冻结副本：graph 侧改写嵌入对象不落到调用方
+      const frozen = Object.isFrozen((result as unknown as { __ctx?: unknown }).__ctx);
+      void frozen;
+    });
+
+    // 调用方 ctx 未被图执行路径污染
+    expect(sharedCtx.tenantId).toBe('t-frozen');
+    expect(sharedCtx.userId).toBe('u-1');
+    expect(Object.isFrozen(Object.freeze({ ...sharedCtx }))).toBe(true); // 冻结名义自检
+  });
+
+  test('冻结语义直接验证：embed 副本不可写', () => {
+    const copy = Object.freeze({ ...{ tenantId: 't-x' } });
+    expect(Object.isFrozen(copy)).toBe(true);
+    expect(() => {
+      (copy as { tenantId?: string }).tenantId = 't-y';
+    }).toThrow(); // 严格模式下冻结对象赋值抛 TypeError
+  });
+});

package/src/contrib/crypto.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'vitest';
+
+import { globalUdfRegistry } from '../register.ts';
+import './crypto.ts';
+
+const callCrypto = async (...args: unknown[]): Promise<string> => {
+  const kwargs = globalUdfRegistry.funcBindParams('crypto', args);
+  return (await globalUdfRegistry.call('crypto', kwargs)) as string;
+};
+
+describe('crypto UDF', () => {
+  test('标准摘要向量(hex)', async () => {
+    expect(await callCrypto('hello')).toBe('2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824');
+    expect(await callCrypto('hello', 'md5')).toBe('5d41402abc4b2a76b9719d911017c592');
+    expect(await callCrypto('hello', 'sha1')).toBe('aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d');
+    expect(await callCrypto('hello', 'sha512')).toBe(
+      '9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043',
+    );
+  });
+
+  test('base64 与 base64url 编码', async () => {
+    expect(await callCrypto('hello', 'sha256', null, 'base64')).toBe('LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=');
+    expect(await callCrypto('hello', 'sha256', null, 'base64url')).toBe('LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ');
+  });
+
+  test('HMAC 模式(secret 非空启用)', async () => {
+    const msg = 'The quick brown fox jumps over the lazy dog';
+    expect(await callCrypto(msg, 'sha256', 'key')).toBe(
+      'f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8',
+    );
+    expect(await callCrypto(msg, 'md5', 'key')).toBe('80070713463e7749b90c2dc24911e275');
+  });
+
+  test('空 secret 为普通摘要，与带 secret 区分', async () => {
+    expect(await callCrypto('hello', 'sha256', '')).toBe(
+      '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+    );
+  });
+
+  test('非法算法/编码回退默认值，不抛异常', async () => {
+    expect(await callCrypto('hello', 'sm3')).toBe(await callCrypto('hello'));
+    expect(await callCrypto('hello', 'SHA256')).toBe(await callCrypto('hello'));
+    expect(await callCrypto('hello', 'sha256', null, 'rot13')).toBe(await callCrypto('hello'));
+  });
+
+  test('upper 仅对 hex 生效', async () => {
+    expect(await callCrypto('hello', 'md5', null, 'hex', true)).toBe('5D41402ABC4B2A76B9719D911017C592');
+    const b64Upper = await callCrypto('hello', 'sha256', null, 'base64', true);
+    expect(b64Upper).toBe(await callCrypto('hello', 'sha256', null, 'base64'));
+  });
+
+  test('引擎路径：funcBindParams 按声明顺序位置绑定，缺省参数回退默认值', () => {
+    const kwargs = globalUdfRegistry.funcBindParams('crypto', ['hello']);
+    expect(Object.keys(kwargs)).toEqual(['input', 'algorithm', 'secret', 'encoding', 'upper']);
+    expect(kwargs['algorithm']).toBe('sha256');
+    expect(kwargs['encoding']).toBe('hex');
+    expect(kwargs['secret']).toBe('');
+    expect(kwargs['upper']).toBe(false);
+  });
+});

package/src/contrib/crypto.ts

@@ -0,0 +1,74 @@
+// crypto 域(摘要签名，有专属 UI 设计，文件名即 namespace)
+import { createHash, createHmac } from 'node:crypto';
+
+import { defineContrib, defineTool } from '../register.ts';
+
+const CRYPTO_ALGORITHMS = new Set(['md5', 'sha1', 'sha256', 'sha512']);
+const CRYPTO_ENCODINGS = new Set(['hex', 'base64', 'base64url']);
+
+export default defineContrib(import.meta.url, {
+  tools: [
+    defineTool({
+      name: 'crypto',
+      description:
+        '计算字符串摘要或 HMAC 签名，返回摘要字符串. algorithm 支持 md5/sha1/sha256/sha512(非法值回退 sha256)，' +
+        'secret 非空时启用 HMAC 模式，encoding 支持 hex/base64/base64url(非法值回退 hex)，upper 仅对 hex 生效(大写输出).',
+      parametersSchema: {
+        properties: {
+          input: {
+            type: 'string',
+            title: 'Input',
+            description: '待摘要内容',
+          },
+          algorithm: {
+            type: 'string',
+            title: 'Algorithm',
+            description: '摘要算法(md5/sha1/sha256/sha512)，默认 sha256，非法值回退 sha256',
+            default: 'sha256',
+          },
+          secret: {
+            type: 'string',
+            title: 'Secret',
+            description: 'HMAC 密钥，非空启用 HMAC 模式，留空则为普通摘要',
+            default: '',
+          },
+          encoding: {
+            type: 'string',
+            title: 'Encoding',
+            description: '输出编码(hex/base64/base64url)，默认 hex，非法值回退 hex',
+            default: 'hex',
+          },
+          upper: {
+            type: 'boolean',
+            title: 'Upper',
+            description: 'hex 输出转大写(仅 encoding=hex 时生效)，默认 false',
+            default: false,
+          },
+        },
+        required: ['input'],
+        title: 'crypto',
+        type: 'object',
+      },
+      returnsSchema: { type: 'string', title: 'crypto 函数返回', properties: {} },
+      fn: function cryptoDigestUdf(kwargs: Record<string, unknown>) {
+        const input = String(kwargs?.input ?? '');
+        const algorithmRaw = String(kwargs?.algorithm ?? 'sha256')
+          .trim()
+          .toLowerCase();
+        const algorithm = CRYPTO_ALGORITHMS.has(algorithmRaw) ? algorithmRaw : 'sha256';
+        const secret = String(kwargs?.secret ?? '');
+        const encodingRaw = String(kwargs?.encoding ?? 'hex')
+          .trim()
+          .toLowerCase();
+        const encoding = CRYPTO_ENCODINGS.has(encodingRaw) ? encodingRaw : 'hex';
+        const upper = kwargs?.upper === true;
+
+        const algo = algorithm as 'md5' | 'sha1' | 'sha256' | 'sha512';
+        const hasher = secret ? createHmac(algo, secret) : createHash(algo);
+        hasher.update(input);
+        const digest = hasher.digest(encoding as 'hex' | 'base64' | 'base64url');
+        return upper && encoding === 'hex' ? digest.toUpperCase() : digest;
+      },
+    }),
+  ],
+});

package/src/contrib/custom-list-query.ts

@@ -0,0 +1,51 @@
+import { getExecContext } from '../exec-context.ts';
+import { defineContrib } from '../register.ts';
+import { queryRoster } from '../roster.ts';
+
+/**
+ * 旧平台函数域重建（第六十九批 D2，docs/13 §8.3）：名单查询复用 roster 存储的
+ * queryRoster。调用形态对齐撞库攻击防御.json：`custom_list_query;;"名单名";;值`。
+ * 返回图内 returnSchema 声明的 {result}（actor 隔离与 roster UDF 一致）。
+ */
+export default defineContrib(import.meta.url, {
+  tools: [
+    {
+      name: 'custom_list_query',
+      description: '旧域重建·名单查询：在服务端指定名单中查询某个值是否存在，返回 {result}。',
+      parametersSchema: {
+        properties: {
+          list_name: {
+            type: 'string',
+            title: '名单名称',
+            description: '服务端名单名称',
+          },
+          value: {
+            type: 'string',
+            title: '查询值',
+            description: '待查询的值',
+          },
+        },
+        required: ['list_name', 'value'],
+        title: 'custom_list_query',
+        type: 'object',
+      },
+      returnsSchema: {
+        type: 'object',
+        title: 'custom_list_query_result',
+        properties: {
+          result: { type: 'boolean', title: 'Result' },
+        },
+        required: ['result'],
+      },
+      fn: function customListQueryUdf(kwargs: Record<string, unknown>) {
+        const ctx = getExecContext();
+        if (!ctx?.tenantId) return { result: false };
+        const { hit } = queryRoster(String(kwargs?.list_name ?? ''), kwargs?.value ?? null, {
+          tenantId: ctx.tenantId,
+          actor: ctx.userId,
+        });
+        return { result: hit };
+      },
+    },
+  ],
+});

package/src/contrib/debug.ts

@@ -0,0 +1,42 @@
+import { defineContrib, defineTool } from '../register.ts';
+
+// ext 约定：缺省 namespace 取文件名(debug)，集合容器档(多函数多行调用)
+export default defineContrib(import.meta.url, {
+  tools: [
+    defineTool({
+      name: 'inout',
+      description: 'Docstring for inout\n自定义函数测试, 返回值返回入参, 用于调试.',
+      parametersSchema: {
+        properties: {
+          b: { description: '参数 b', title: 'B', type: 'integer' },
+          a: {
+            anyOf: [{ type: 'string' }, { type: 'integer' }],
+            description: '参数 a',
+            title: 'A',
+          },
+          c: { description: '参数 c', title: 'C', type: 'null' },
+        },
+        required: ['b', 'a', 'c'],
+        title: 'inout',
+        type: 'object',
+      },
+      returnsSchema: { type: 'string', title: 'inout 函数返回', properties: {} },
+      fn: function (kwargs: Record<string, unknown>) {
+        return kwargs?.['_node_input_'] ?? {};
+      },
+    }),
+    defineTool({
+      name: 'func_without_args',
+      description: 'Docstring for func_without_args\n无参数函数, 用于自定义函数测试',
+      parametersSchema: {
+        properties: {},
+        title: 'func_without_args',
+        type: 'object',
+      },
+      returnsSchema: { type: 'string', title: 'func_without_args 函数返回', properties: {} },
+      fn: function (kwargs: Record<string, unknown>) {
+        return kwargs?.['_node_input_'] ?? {};
+      },
+    }),
+  ],
+});

package/src/contrib/debugui.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'vitest';
+
+import { currentDate } from './debugui.ts';
+
+describe('current_date udf', () => {
+  test('返回 YYYY-MM-DD 格式日期', () => {
+    const result = currentDate() as string;
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+});

package/src/contrib/debugui.ts

@@ -0,0 +1,27 @@
+// debugui 域(调试用专属 UI 函数，文件名即 namespace)
+import { defineContrib } from '../register.ts';
+
+/** 服务器当前日期(本地时区，YYYY-MM-DD 格式)，无参数 */
+export function currentDate(): string {
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, '0');
+  const dd = String(now.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+export default defineContrib(import.meta.url, {
+  tools: [
+    {
+      name: 'current_date',
+      description: '返回服务器当前日期(本地时区，YYYY-MM-DD 格式)，无参数.',
+      parametersSchema: {
+        properties: {},
+        title: 'current_date',
+        type: 'object',
+      },
+      returnsSchema: { type: 'string', title: 'current_date 函数返回', properties: {} },
+      fn: currentDate,
+    },
+  ],
+});

package/src/contrib/http-guard.test.ts

@@ -0,0 +1,116 @@
+import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'node:http';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+
+import { runWithExecContext } from '../exec-context.ts';
+import { configureHttpUdf, httpRequest } from './http.ts';
+
+let server: Server;
+let baseUrl: string;
+let echoHits = 0;
+
+const json = (res: ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+
+const call = async (kwargs: Record<string, unknown>, ctx?: { tenantId: string }): Promise<unknown> =>
+  ctx ? runWithExecContext(ctx, async () => httpRequest(kwargs)) : httpRequest(kwargs);
+
+beforeAll(async () => {
+  await new Promise<void>((resolve) => {
+    server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      echoHits += 1;
+      json(res, 200, { ok: true, auth: req.headers['authorization'] ?? null });
+    });
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+});
+
+afterAll(() => {
+  server.close();
+});
+
+describe('http_request EgressGuard（U9）', () => {
+  test('缺省无守卫时出口不受限', async () => {
+    const result = (await call({ url: `${baseUrl}/json` })) as { status: number };
+    expect(result.status).toBe(200);
+  });
+
+  test('egress 拒绝返回结构化错误且不重试', async () => {
+    let guardCalls = 0;
+    configureHttpUdf({
+      egressGuard: {
+        assertAllowed: (url) => {
+          guardCalls += 1;
+          if (!url.startsWith('https://api.allowed.example')) {
+            throw new Error('host not in tenant allowlist');
+          }
+        },
+      },
+    });
+
+    const result = (await call({ url: `${baseUrl}/json`, retry: 3 }, { tenantId: 't-1' })) as {
+      status: number;
+      error?: string;
+      policyBlocked?: boolean;
+    };
+    expect(result.status).toBe(0);
+    expect(result.error).toContain('egress blocked by policy');
+    expect(result.error).toContain('allowlist');
+    // 策略性失败不重试：守卫恰好被调用一次
+    expect(guardCalls).toBe(1);
+    configureHttpUdf({});
+  });
+});
+
+describe('http_request SecretResolver（U9）', () => {
+  test('basic 认证的 ${secret:引用} 按租户解析', async () => {
+    configureHttpUdf({
+      secretResolver: {
+        resolve: (ref, tenantId) => (ref === 'db-pass' && tenantId === 't-1' ? 's3cret-value' : ''),
+      },
+    });
+
+    const result = (await call(
+      { url: `${baseUrl}/echo`, auth: { type: 'basic', username: 'alice', password: '${secret:db-pass}' } },
+      { tenantId: 't-1' },
+    )) as { status: number; body?: { auth?: string } };
+    expect(result.status).toBe(200);
+    const expected = 'Basic ' + Buffer.from('alice:s3cret-value', 'utf8').toString('base64');
+    expect(result.body?.auth).toBe(expected);
+    configureHttpUdf({});
+  });
+
+  test('未配置 resolver 时 secret 引用失败且不泄漏', async () => {
+    echoHits = 0;
+    const result = (await call({
+      url: `${baseUrl}/echo`,
+      retry: 2,
+      auth: { type: 'bearer', token: '${secret:missing-ref}' },
+    })) as { status: number; error?: string; policyBlocked?: boolean };
+    expect(result.status).toBe(0);
+    expect(result.error).toContain('requires a configured secretResolver');
+    expect(result.policyBlocked).toBe(true);
+    // 策略性失败不重试
+    expect(echoHits).toBe(0);
+  });
+
+  test('resolver 抛错时错误信息不包含已解析凭证', async () => {
+    configureHttpUdf({
+      secretResolver: {
+        resolve: () => {
+          throw new Error('secret db-pass not found for tenant');
+        },
+      },
+    });
+    const result = (await call(
+      { url: `${baseUrl}/echo`, auth: { type: 'basic', username: 'u', password: '${secret:db-pass}' } },
+      { tenantId: 't-1' },
+    )) as { status: number; error?: string };
+    expect(result.status).toBe(0);
+    expect(result.error).toContain('secret resolve failed');
+    expect(result.error).toContain('db-pass not found');
+    configureHttpUdf({});
+  });
+});