@republicroad/zen-udf 0.2.0

package/src/contrib/rate-store-conformance.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'vitest';
+
+import type { RateStore } from './rate-window.ts';
+
+/**
+ * RateStore 契约测试（U8）：任何 RateStore 实现（含 verdict 侧 Redis 实现）都应
+ * 用本套件验证同一行为语义。工厂接收可注入时钟 now()——实现应使用该时钟打点
+ * （Redis 实现可将 now() 的时间戳随命令传入，而非依赖服务器时钟）。
+ */
+export const rateStoreConformance = (name: string, createStore: (now: () => number) => RateStore): void => {
+  describe(`RateStore conformance: ${name}`, () => {
+    let nowMs = 1_700_000_000_000;
+    let store: RateStore;
+
+    const advance = (ms: number): void => {
+      nowMs += ms;
+    };
+
+    test('rate：首次计数 1、递增、实体间独立', async () => {
+      store = createStore(() => nowMs);
+      const a1 = await store.rate('ip-a', 3_600_000);
+      const a2 = await store.rate('ip-a', 3_600_000);
+      const b1 = await store.rate('ip-b', 3_600_000);
+      expect([a1.counter, a2.counter, b1.counter]).toEqual([1, 2, 1]);
+      expect(a1.v).toBe('ip-a');
+      expect(a1.idle).toBe(0);
+      expect(typeof a1.timestamp).toBe('string');
+    });
+
+    test('rate：窗口滑出后计数重置，idle 为距上次事件秒数', async () => {
+      nowMs = 1_700_000_000_000;
+      store = createStore(() => nowMs);
+      await store.rate('ip-w', 60_000);
+      advance(30_000);
+      const second = await store.rate('ip-w', 60_000);
+      expect(second.counter).toBe(2);
+      expect(second.idle).toBe(30);
+      advance(61_000); // 两次事件均滑出 60s 窗口
+      const third = await store.rate('ip-w', 60_000);
+      expect(third.counter).toBe(1);
+    });
+
+    test('groupDistinct：pv 累计、uv 按值去重、组间独立', async () => {
+      nowMs = 1_800_000_000_000;
+      store = createStore(() => nowMs);
+      const r1 = await store.groupDistinct('g-ip', 'p1', 3_600_000);
+      const r2 = await store.groupDistinct('g-ip', 'p1', 3_600_000);
+      const r3 = await store.groupDistinct('g-ip', 'p2', 3_600_000);
+      const other = await store.groupDistinct('g-other', 'p1', 3_600_000);
+      expect([r1.pv, r1.uv]).toEqual([1, 1]);
+      expect([r2.pv, r2.uv]).toEqual([2, 1]);
+      expect([r3.pv, r3.uv]).toEqual([3, 2]);
+      expect(other.pv).toBe(1);
+      expect(other.group).toBe('g-other');
+      expect(other.v).toBe('p1');
+    });
+
+    test('groupDistinct：窗口滑出后 pv/uv 重置', async () => {
+      nowMs = 1_900_000_000_000;
+      store = createStore(() => nowMs);
+      await store.groupDistinct('g-w', 'v1', 60_000);
+      await store.groupDistinct('g-w', 'v2', 60_000);
+      advance(61_000);
+      const after = await store.groupDistinct('g-w', 'v3', 60_000);
+      expect([after.pv, after.uv]).toEqual([1, 1]);
+    });
+  });
+};

package/src/contrib/rate-store.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest';
+
+import { rateStoreConformance } from './rate-store-conformance.ts';
+import { InMemoryRateStore, __resetRateWindows, setRateStore } from './rate-window.ts';
+
+// 参考实现（InMemoryRateStore）必须通过契约测试——verdict 的 Redis 实现
+// 复用 rateStoreConformance 验证同一语义（宿主裁决 D1）
+rateStoreConformance('InMemoryRateStore', (now) => new InMemoryRateStore(now));
+
+describe('RateStore 注入点', () => {
+  test('setRateStore 后 UDF 语义经注入实现执行；__resetRateWindows 调用 reset', async () => {
+    const calls: string[] = [];
+    setRateStore({
+      rate: (entity) => {
+        calls.push('rate:' + entity);
+        return { counter: 42, v: entity, idle: 0, timestamp: 'injected' };
+      },
+      groupDistinct: (group, value) => {
+        calls.push('group:' + group);
+        return { idle: 0, pv: 0, uv: 0, gidle: 0, vidle: 0, group, v: value, timestamp: 'injected' };
+      },
+      reset: () => calls.push('reset'),
+    });
+    __resetRateWindows();
+    expect(calls).toContain('reset');
+    // 还原缺省实现，避免影响其它测试
+    setRateStore(new InMemoryRateStore());
+    __resetRateWindows();
+  });
+});

package/src/contrib/rate-window.ts

@@ -0,0 +1,195 @@
+import { defineContrib, defineTool } from '../register.ts';
+
+/**
+ * 旧平台函数域重建（第六十九批 D2，docs/13 §8.3）：滑动窗口频控。
+ * U8 起拆分为 RateStore 端口 + 进程内参考实现：
+ *  - 端口（RateStore）是机制契约；verdict 侧提供 Redis 真实实现（宿主裁决 D1），
+ *    并复用 rate-store-conformance.ts 的同一套契约测试。
+ *  - InMemoryRateStore 为单实例语义的开发态参考实现，仅测试/本地使用。
+ *
+ * 字段语义按图内 returnSchema 重建（撞库攻击防御.json）：
+ *  - rate(entity, window) → RateCommonResult {counter 窗口内事件数, v 实体, idle 距上次事件秒数, timestamp}
+ *  - groupDistinct(group, value, window) → GroupDistinctCommonResult
+ *    {pv 组窗口内事件数, uv 组窗口内去重值数, idle 距该 (group,value) 对上次事件秒数,
+ *     gidle 距该组上次事件秒数, vidle 距该值上次事件秒数(跨组), group, v, timestamp}
+ */
+export interface RateCommonResult {
+  counter: number;
+  v: string;
+  idle: number;
+  timestamp: string;
+}
+
+export interface GroupDistinctCommonResult {
+  idle: number;
+  pv: number;
+  uv: number;
+  gidle: number;
+  vidle: number;
+  group: string;
+  v: string;
+  timestamp: string;
+}
+
+/** 频控存储端口：Redis 化实现（verdict 侧）须通过 rate-store-conformance 契约测试 */
+export interface RateStore {
+  rate(entity: string, windowMs: number): RateCommonResult | Promise<RateCommonResult>;
+  groupDistinct(
+    group: string,
+    value: string,
+    windowMs: number,
+  ): GroupDistinctCommonResult | Promise<GroupDistinctCommonResult>;
+  /** 清空状态（测试辅助；生产实现可为 no-op） */
+  reset?(): void;
+}
+
+const secondsSince = (now: number, t?: number): number => (t ? Math.max(0, Math.floor((now - t) / 1000)) : 0);
+
+/** 进程内滑动窗口参考实现（单实例语义；多副本请使用 Redis 化实现） */
+export class InMemoryRateStore implements RateStore {
+  private rateWindows = new Map<string, number[]>();
+  private groupWindows = new Map<string, { pv: number[]; values: Map<string, number[]> }>();
+  private valueWindows = new Map<string, number[]>();
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  reset(): void {
+    this.rateWindows.clear();
+    this.groupWindows.clear();
+    this.valueWindows.clear();
+  }
+
+  rate(entity: string, windowMs: number): RateCommonResult {
+    const now = this.now();
+    const stamps = (this.rateWindows.get(entity) ?? []).filter((t) => now - t < windowMs);
+    const previous = stamps[stamps.length - 1];
+    stamps.push(now);
+    this.rateWindows.set(entity, stamps);
+    return {
+      counter: stamps.length,
+      v: entity,
+      idle: secondsSince(now, previous),
+      timestamp: new Date(now).toISOString(),
+    };
+  }
+
+  groupDistinct(group: string, value: string, windowMs: number): GroupDistinctCommonResult {
+    const now = this.now();
+
+    const entry = this.groupWindows.get(group) ?? { pv: [], values: new Map<string, number[]>() };
+    entry.pv = entry.pv.filter((t) => now - t < windowMs);
+    const groupPrevious = entry.pv[entry.pv.length - 1];
+    entry.pv.push(now);
+
+    const valueStamps = (entry.values.get(value) ?? []).filter((t) => now - t < windowMs);
+    const pairPrevious = valueStamps[valueStamps.length - 1];
+    valueStamps.push(now);
+    entry.values.set(value, valueStamps);
+    for (const [v, stamps] of entry.values) {
+      if (stamps.filter((t) => now - t < windowMs).length === 0) entry.values.delete(v);
+    }
+    this.groupWindows.set(group, entry);
+
+    const globalStamps = (this.valueWindows.get(value) ?? []).filter((t) => now - t < windowMs);
+    const globalPrevious = globalStamps[globalStamps.length - 1];
+    globalStamps.push(now);
+    this.valueWindows.set(value, globalStamps);
+
+    return {
+      idle: secondsSince(now, pairPrevious),
+      pv: entry.pv.length,
+      uv: entry.values.size,
+      gidle: secondsSince(now, groupPrevious),
+      vidle: secondsSince(now, globalPrevious),
+      group,
+      v: value,
+      timestamp: new Date(now).toISOString(),
+    };
+  }
+}
+
+/** 活动存储：缺省为进程内参考实现；宿主经 setRateStore 注入 Redis 化实现 */
+let activeStore: RateStore = new InMemoryRateStore();
+
+export const setRateStore = (store: RateStore): void => {
+  activeStore = store;
+};
+
+export const getRateStore = (): RateStore => activeStore;
+
+/** 测试辅助：重置活动存储（若实现支持 reset；生产勿用） */
+export const __resetRateWindows = (): void => {
+  activeStore.reset?.();
+};
+
+const WINDOW_MS = 60 * 60 * 1000;
+
+const rate_1h = defineTool({
+  name: 'rate_1h',
+  description: '旧域重建·频次统计：记录实体事件并返回其 1 小时滑动窗口内的事件计数。',
+  parametersSchema: {
+    properties: {
+      entity: {
+        type: 'string',
+        title: '实体',
+        description: '计数实体（如 ip、phone）',
+      },
+    },
+  },
+  returnsSchema: {
+    type: 'object',
+    title: 'RateCommonResult',
+    properties: {
+      counter: { type: 'integer', title: 'Counter', default: 0 },
+      v: { type: 'string', title: 'V', default: '' },
+      idle: { type: 'integer', title: 'Idle', default: 0 },
+      timestamp: { type: 'string', title: 'Timestamp', default: '' },
+    },
+  },
+  fn: function rateUdf(kwargs: Record<string, unknown>) {
+    const entity = String(kwargs?.entity ?? '');
+    return Promise.resolve(getRateStore().rate(entity, WINDOW_MS));
+  },
+});
+
+const group_distinct_1h = defineTool({
+  name: 'group_distinct_1h',
+  description: '旧域重建·组去重统计：记录 (组, 值) 事件并返回 1 小时滑动窗口内组事件数(pv)与去重值数(uv)。',
+  parametersSchema: {
+    properties: {
+      group: {
+        type: 'string',
+        title: '组',
+        description: '分组键（如 ip）',
+      },
+      value: {
+        type: 'string',
+        title: '值',
+        description: '组内观测值（如 phone）',
+      },
+    },
+  },
+  returnsSchema: {
+    type: 'object',
+    title: 'GroupDistinctCommonResult',
+    properties: {
+      idle: { type: 'integer', title: 'Idle', default: 0 },
+      pv: { type: 'integer', title: 'Pv', default: 0 },
+      uv: { type: 'integer', title: 'Uv', default: 0 },
+      gidle: { type: 'integer', title: 'Gidle', default: 0 },
+      vidle: { type: 'integer', title: 'Vidle', default: 0 },
+      group: { type: 'string', title: 'Group', default: '' },
+      v: { type: 'string', title: 'V', default: '' },
+      timestamp: { type: 'string', title: 'Timestamp', default: '' },
+    },
+  },
+  fn: function groupDistinctUdf(kwargs: Record<string, unknown>) {
+    const group = String(kwargs?.group ?? '');
+    const value = String(kwargs?.value ?? '');
+    return Promise.resolve(getRateStore().groupDistinct(group, value, WINDOW_MS));
+  },
+});
+
+export default defineContrib(import.meta.url, {
+  tools: [rate_1h, group_distinct_1h],
+});

package/src/contrib/rebuilt-functions.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'vitest';
+
+import { runWithExecContext } from '../exec-context.ts';
+import { globalUdfRegistry } from '../register.ts';
+import { registerRoster } from '../roster.ts';
+import './custom-list-query.ts';
+import './ip-location.ts';
+import './rate-window.ts';
+import { __resetRateWindows } from './rate-window.ts';
+
+const call = <T>(name: string, args: unknown[]): Promise<T> =>
+  globalUdfRegistry.call(name, globalUdfRegistry.funcBindParams(name, args)) as Promise<T>;
+
+describe('custom_list_query（D2 重建）', () => {
+  test('名单命中返回 result:true，未命中 false（actor 隔离）', async () => {
+    registerRoster({ name: 'clq_list', items: ['v-hit'] }, { tenantId: 'clq-tenant', actor: 'clq-user' });
+    const hit = await runWithExecContext({ tenantId: 'clq-tenant', userId: 'clq-user' }, () =>
+      call<{ result: boolean }>('custom_list_query', ['clq_list', 'v-hit']),
+    );
+    const miss = await runWithExecContext({ tenantId: 'clq-tenant', userId: 'clq-user' }, () =>
+      call<{ result: boolean }>('custom_list_query', ['clq_list', 'v-miss']),
+    );
+    expect(hit.result).toBe(true);
+    expect(miss.result).toBe(false);
+  });
+});
+
+describe('rate_1h / group_distinct_1h（D2 重建，内存滑动窗口）', () => {
+  test('同实体计数递增，异实体独立', async () => {
+    __resetRateWindows();
+    const a1 = await call<{ counter: number; v: string; timestamp: string }>('rate_1h', ['1.1.1.1']);
+    const a2 = await call<{ counter: number; v: string; timestamp: string }>('rate_1h', ['1.1.1.1']);
+    const b1 = await call<{ counter: number; v: string; timestamp: string }>('rate_1h', ['2.2.2.2']);
+    expect(a1.counter).toBe(1);
+    expect(a2.counter).toBe(2);
+    expect(b1.counter).toBe(1);
+    expect(typeof a1.timestamp).toBe('string');
+  });
+
+  test('group_distinct_1h：pv 累计、uv 按值去重、组间独立', async () => {
+    __resetRateWindows();
+    const r1 = await call<{ pv: number; uv: number }>('group_distinct_1h', ['g-ip', 'p1']);
+    const r2 = await call<{ pv: number; uv: number }>('group_distinct_1h', ['g-ip', 'p1']);
+    const r3 = await call<{ pv: number; uv: number }>('group_distinct_1h', ['g-ip', 'p2']);
+    const other = await call<{ pv: number; uv: number }>('group_distinct_1h', ['g-other', 'p1']);
+    expect(r1.pv).toBe(1);
+    expect(r1.uv).toBe(1);
+    expect(r2.pv).toBe(2);
+    expect(r2.uv).toBe(1);
+    expect(r3.uv).toBe(2);
+    expect(other.pv).toBe(1);
+  });
+
+  test('ip_location：数据集最长前缀命中，未配置返回空字段', async () => {
+    __resetRateWindows();
+    const miss = await call<{ country: string; ip: string }>('ip_location', ['9.9.9.9']);
+    expect(miss.country).toBe('');
+    expect(miss.ip).toBe('9.9.9.9');
+  });
+});

package/src/contrib/roster.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from 'vitest';
+
+import { runWithExecContext } from '../exec-context.ts';
+import { globalUdfRegistry } from '../register.ts';
+import { deleteRoster, registerRoster } from '../roster.ts';
+import './roster.ts';
+
+describe('roster UDF', () => {
+  test('并发双 ctx 下各自命中 actor 私有名单', async () => {
+    registerRoster({ name: 'o_udf_a', items: ['ip-a'] }, { tenantId: 'roster-tenant', actor: 'udf-user-a' });
+    registerRoster({ name: 'o_udf_b', items: ['ip-b'] }, { tenantId: 'roster-tenant', actor: 'udf-user-b' });
+
+    const call = () =>
+      globalUdfRegistry.call('roster', globalUdfRegistry.funcBindParams('roster', ['o_udf_a', 'ip-a'])) as Promise<{
+        hit: boolean;
+      }>;
+    const [asA, asB] = await Promise.all([
+      runWithExecContext({ tenantId: 'roster-tenant', userId: 'udf-user-a' }, call),
+      runWithExecContext({ tenantId: 'roster-tenant', userId: 'udf-user-b' }, call),
+    ]);
+    expect(asA.hit).toBe(true);
+    expect(asB.hit).toBe(false);
+
+    deleteRoster('o_udf_a', { tenantId: 'roster-tenant', actor: 'udf-user-a' });
+    deleteRoster('o_udf_b', { tenantId: 'roster-tenant', actor: 'udf-user-b' });
+  });
+});

package/src/contrib/roster.ts

@@ -0,0 +1,38 @@
+import { getExecContext } from '../exec-context.ts';
+import { defineContrib } from '../register.ts';
+import { queryRoster } from '../roster.ts';
+
+export default defineContrib(import.meta.url, {
+  tools: [
+    {
+      name: 'roster',
+      description: '查询名单：在服务端指定名单中查询某个值是否存在，返回命中结果.',
+      parametersSchema: {
+        properties: {
+          roster: {
+            type: 'string',
+            title: '名单',
+            description: '服务端名单名称(从名单下拉中动态选择)',
+          },
+          value: {
+            type: 'string',
+            title: '查询值',
+            description: '待查询的值',
+          },
+        },
+        required: ['roster', 'value'],
+        title: 'roster',
+        type: 'object',
+      },
+      returnsSchema: { type: 'object', title: 'roster 函数返回', properties: {} },
+      fn: function queryListUdf(kwargs: Record<string, unknown>) {
+        const ctx = getExecContext();
+        if (!ctx?.tenantId) return { hit: false, roster: String(kwargs?.roster ?? ''), value: kwargs?.value ?? null };
+        return queryRoster(String(kwargs?.roster ?? ''), kwargs?.value ?? null, {
+          tenantId: ctx.tenantId,
+          actor: ctx.userId,
+        });
+      },
+    },
+  ],
+});

package/src/decision-cache.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionCache } from './decision-cache.ts';
+import { DecisionRuntime } from './engine.ts';
+import { runWithExecContext } from './exec-context.ts';
+import './reference.ts';
+
+const makeEntry = (v: number) => ({ decision: v as unknown as never, content: v });
+
+describe('DecisionCache（U4 L1 缓存机制）', () => {
+  test('LRU：get 刷新位次，超容量驱逐最旧', () => {
+    const cache = new DecisionCache({ capacity: 2 });
+    cache.set('a', makeEntry(1));
+    cache.set('b', makeEntry(2));
+    cache.get('a'); // a 变最新
+    cache.set('c', makeEntry(3)); // 驱逐 b
+
+    expect(cache.has('a')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+    expect(cache.has('c')).toBe(true);
+    expect(cache.snapshot().evictions).toBe(1);
+  });
+
+  test('同键 set 即原子替换（copy-on-write 热更新）', () => {
+    const cache = new DecisionCache();
+    cache.set('k', makeEntry(1));
+    cache.set('k', makeEntry(2));
+    expect(cache.get('k')?.content).toBe(2);
+    expect(cache.snapshot().evictions).toBe(0);
+  });
+
+  test('指标：hits/misses 计数与快照', () => {
+    const cache = new DecisionCache();
+    cache.set('k', makeEntry(1));
+    cache.get('k');
+    cache.get('missing');
+    const snap = cache.snapshot();
+    expect(snap.hits).toBe(1);
+    expect(snap.misses).toBe(1);
+    expect(snap.size).toBe(1);
+  });
+
+  test('metricsSink 在读写后回调', () => {
+    const snapshots: number[] = [];
+    const cache = new DecisionCache({ metricsSink: (s) => snapshots.push(s.size) });
+    cache.set('k', makeEntry(1));
+    cache.get('k');
+    expect(snapshots.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test('build 计时埋点累计 builds/buildMicros', () => {
+    const cache = new DecisionCache();
+    const t = cache.markBuildStart();
+    cache.markBuildEnd(t);
+    const snap = cache.snapshot();
+    expect(snap.builds).toBe(1);
+    expect(snap.buildMicros).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe('DecisionRuntime L1 缓存接入（U4）', () => {
+  const graph = {
+    id: 'g',
+    nodes: [
+      { id: 'in', type: 'inputNode', name: 'Request' },
+      { id: 'out', type: 'outputNode', name: 'Response' },
+    ],
+    edges: [],
+  };
+
+  test('缓存键按租户隔离：同 key 不同租户互不可见', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 't-1' }, async () => {
+      runtime.createDecisionWithCacheKey('model', structuredClone(graph));
+    });
+
+    // t-2 命中不了 t-1 的条目
+    await expect(runWithExecContext({ tenantId: 't-2' }, () => runtime.evaluateAsync('model', {}))).rejects.toThrow(
+      /not found, please use createDecisionWithCacheKey/,
+    );
+
+    // t-1 正常命中
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('model', {}));
+    expect(result.result).toBeDefined();
+  });
+
+  test('同租户同 key 不同 rev 并存', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('model', structuredClone(graph), 'v1');
+      runtime.createDecisionWithCacheKey('model', structuredClone(graph), 'v2');
+      return Promise.resolve();
+    });
+
+    await runWithExecContext({ tenantId: 't-1' }, async () => {
+      expect(runtime.getDecisionCache('model', 'v1')).toBeDefined();
+      expect(runtime.getDecisionCache('model', 'v2')).toBeDefined();
+      expect(runtime.getContentCache('model')).toBeUndefined(); // 缺省 rev=latest → 未创建
+      expect(runtime.getContentCache('model', 'v1')).toBeDefined();
+    });
+  });
+
+  test('update/delete 按 rev 定位，latest 互不干扰', async () => {
+    const runtime = new DecisionRuntime({});
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('m', structuredClone(graph), 'v1');
+      runtime.updateDecisionWithCacheKey('m', structuredClone(graph), 'v1');
+      runtime.deleteDecisionWithCacheKey('m', 'v1');
+      return Promise.resolve();
+    });
+
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      expect(runtime.getDecisionCache('m', 'v1')).toBeUndefined();
+      return Promise.resolve();
+    });
+  });
+
+  test('缺省构造回落 globalUdfRegistry（reference 装载后工具非空）', () => {
+    const runtime = new DecisionRuntime();
+    expect(runtime.udfFunctionSchemaTools().length).toBeGreaterThan(0);
+  });
+});

package/src/decision-cache.ts

@@ -0,0 +1,104 @@
+import type { ZenDecision } from '@gorules/zen-engine';
+
+/**
+ * L1 决策缓存（多租户设计 docs/design/zen-udf-multi-tenant.md §3）。
+ *
+ * 探针实证（src/engine-cache-semantics.test.ts）：zen-engine 函数 loader 无引擎级缓存，
+ * 缓存责任在宿主——本类即宿主侧缓存机制：
+ *  - 键由 DecisionRuntime 组合（`${tenantId}:${key}@${rev}`），本类只管存取与驱逐
+ *  - Map 插入序实现 LRU：get 触碰刷新位次，超容量按最旧驱逐
+ *  - 原子替换语义：set 同键即整体换新（copy-on-write 热更新），绝不原地改
+ *  - in-flight 安全：被驱逐条目若仍被请求持有引用，evaluate 不受影响，GC 兜底
+ */
+export interface CacheMetricsSnapshot {
+  hits: number;
+  misses: number;
+  evictions: number;
+  builds: number;
+  buildMicros: number;
+  size: number;
+}
+
+export interface DecisionCacheEntry {
+  decision: ZenDecision;
+  content: unknown;
+}
+
+export interface DecisionCacheOptions {
+  /** 容量上限（条目数），默认 500 */
+  capacity?: number;
+  /** 指标 sink：每次 get/set/delete 后回调快照（verdict 接 Prometheus 用） */
+  metricsSink?: (snapshot: CacheMetricsSnapshot) => void;
+}
+
+const DEFAULT_CAPACITY = 500;
+
+export class DecisionCache {
+  private readonly entries = new Map<string, DecisionCacheEntry>();
+  private readonly capacity: number;
+  private readonly metricsSink?: (snapshot: CacheMetricsSnapshot) => void;
+  private metrics = { hits: 0, misses: 0, evictions: 0, builds: 0, buildMicros: 0 };
+
+  constructor(options: DecisionCacheOptions = {}) {
+    this.capacity = Math.max(1, options.capacity ?? DEFAULT_CAPACITY);
+    this.metricsSink = options.metricsSink;
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** 命中并刷新 LRU 位次；未命中计 miss */
+  get(key: string): DecisionCacheEntry | undefined {
+    const entry = this.entries.get(key);
+    if (entry) {
+      this.metrics.hits += 1;
+      // 刷新位次（Map 迭代序 = 插入序，删除再插入即移到最新）
+      this.entries.delete(key);
+      this.entries.set(key, entry);
+    } else {
+      this.metrics.misses += 1;
+    }
+    this.metricsSink?.(this.snapshot());
+    return entry;
+  }
+
+  /** 写入/原子替换；超容量按最旧驱逐 */
+  set(key: string, entry: DecisionCacheEntry): void {
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.capacity) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== undefined) {
+        this.entries.delete(oldest);
+        this.metrics.evictions += 1;
+      }
+    }
+    this.entries.set(key, entry);
+    this.metricsSink?.(this.snapshot());
+  }
+
+  delete(key: string): boolean {
+    const deleted = this.entries.delete(key);
+    this.metricsSink?.(this.snapshot());
+    return deleted;
+  }
+
+  has(key: string): boolean {
+    return this.entries.has(key);
+  }
+
+  /** 构建计时埋点：DecisionRuntime 在 createDecision 前后调用 */
+  markBuildStart(): bigint {
+    return process.hrtime.bigint();
+  }
+
+  markBuildEnd(startedAt: bigint): void {
+    this.metrics.builds += 1;
+    this.metrics.buildMicros += Number(process.hrtime.bigint() - startedAt) / 1000;
+  }
+
+  snapshot(): CacheMetricsSnapshot {
+    return { ...this.metrics, size: this.entries.size };
+  }
+}