niceeval 0.12.1 → 0.12.2-canary.31

package/src/shared/facts.ts

@@ -1,36 +0,0 @@
-// fact(key, value) 的共享校验与归属写入实现。三处声明了 fact() 的上下文——
-// AgentContext(src/agents/types.ts)、SandboxHookContext(src/sandbox/types.ts)、
-// ExperimentHookContext(src/runner/types.ts)——运行时各自绑定不同的目标 Record
-// (attempt 级 facts 累加器 / experiment 级 facts 累加器),归属由调用方按当前作用域
-// 决定,不是本函数的职责;本函数只管「这次调用合不合法」与「写进哪个 Record」。
-// key 词法、value 标量、同 key 后写覆盖三条规则单源
-// docs/feature/record/architecture.md#facts运行事实。
-
-/** fact() 接受的标量取值;与三处 ctx.fact() 签名、AttemptRecord.facts / RunMeta.facts 同型。 */
-export type FactValue = string | number | boolean;
-
-const FACT_KEY_PATTERN = /^[a-z0-9._-]{1,64}$/;
-
-/**
- * 校验一次 `fact(key, value)` 调用并写入 `target`(同一作用域内同 key 后写覆盖先写)。
- * 校验失败按三段式抛错(现象/依据/下一步,见 docs/error-feedback.md)。
- */
-export function recordFact(target: globalThis.Record<string, FactValue>, key: string, value: FactValue): void {
-  if (!FACT_KEY_PATTERN.test(key)) {
-    throw new Error(
-      `fact() rejected key ${JSON.stringify(key)}: fact keys must match /^[a-z0-9._-]{1,64}$/ ` +
-        `(lowercase letters, digits, '.', '_', '-', 1-64 characters). ` +
-        `Rename the key to match the pattern and call fact() again.`,
-    );
-  }
-  const valueType = typeof value;
-  if (valueType !== "string" && valueType !== "number" && valueType !== "boolean") {
-    const got = value === null ? "null" : Array.isArray(value) ? "array" : valueType;
-    throw new Error(
-      `fact(${JSON.stringify(key)}, …) rejected its value: fact values must be a scalar ` +
-        `(string | number | boolean), got ${got}. ` +
-        `Pass a scalar, or JSON.stringify() structured data before calling fact().`,
-    );
-  }
-  target[key] = value;
-}

package/src/shared/failure-class.test.ts

@@ -1,195 +0,0 @@
-// cases: docs/engineering/testing/unit/eval.md
-import { describe, expect, it, vi } from "vitest";
-import {
-  EvalFatalError,
-  ExperimentFatalError,
-  attachFailureClass,
-  attemptFailureInfo,
-  failureClassOf,
-  resolveAttemptFailureClass,
-  type AttemptFailureInfo,
-} from "./failure-class.ts";
-import { isExternalCause, normalizeExternalCause } from "./external-cause.ts";
-
-describe("糖衣类 · 抛出点声明空间轴", () => {
-  it("ExperimentFatalError 携带 experiment 档,message 原样保留(它是走完全程的修复提示)", () => {
-    const error = new ExperimentFatalError("server probe failed — 修好隧道后重跑");
-    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "experiment" });
-    expect(error.message).toBe("server probe failed — 修好隧道后重跑");
-  });
-
-  it("EvalFatalError 携带 eval 档,cause 原样透传", () => {
-    const cause = new Error("ENOENT");
-    const error = new EvalFatalError("fixture 缺失", { cause });
-    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "eval" });
-    expect(error.cause).toBe(cause);
-  });
-
-  it("糖衣类是纯 Error 子类:instanceof Error 成立,可被常规 catch 捕获", () => {
-    expect(new ExperimentFatalError("x")).toBeInstanceOf(Error);
-    expect(new EvalFatalError("x")).toBeInstanceOf(Error);
-  });
-});
-
-describe("failureClassOf · 结构守卫", () => {
-  it("识别不依赖类身份:结构相同的手工对象同样命中(第二份 niceeval 实例下也不失效)", () => {
-    const impostor = { _tag: "NiceevalClassifiedError", class: { retryable: false, scope: "experiment" } };
-    expect(failureClassOf(impostor)).toEqual({ retryable: false, scope: "experiment" });
-  });
-
-  it("沿 cause 链穿透:糖衣类被上层库包装再抛,声明不丢失", () => {
-    const wrapped = new Error("sdk wrapper", { cause: new Error("layer 2", { cause: new EvalFatalError("boom") }) });
-    expect(failureClassOf(wrapped)).toEqual({ retryable: false, scope: "eval" });
-  });
-
-  it("取最外层命中:内外都带分类时,外层的声明生效", () => {
-    const outer = new ExperimentFatalError("outer", { cause: new EvalFatalError("inner") });
-    expect(failureClassOf(outer)).toEqual({ retryable: false, scope: "experiment" });
-  });
-
-  it("没有分类的错误、非对象值一律 undefined", () => {
-    expect(failureClassOf(new Error("plain"))).toBeUndefined();
-    expect(failureClassOf("just a string")).toBeUndefined();
-    expect(failureClassOf(undefined)).toBeUndefined();
-  });
-
-  it("`_tag` 对但 class 字段形状非法的对象不算命中(不把垃圾当分类喂给执行体)", () => {
-    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: "yes" } })).toBeUndefined();
-    // retryable: true 必须带 reason(类型级规则),运行时进来的非法组合同样不认
-    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: true } })).toBeUndefined();
-    expect(failureClassOf({ _tag: "NiceevalClassifiedError", class: { retryable: false, scope: "run" } })).toBeUndefined();
-  });
-});
-
-describe("ExternalCause · 跨边界快照", () => {
-  it("已归一化快照仍完整解码、复制并冻结，不长期引用调用者对象", () => {
-    const nested = {
-      _tag: "ThrownValue",
-      valueType: "string",
-      message: "socket reset",
-      cause: { _tag: "Absent" },
-    } as const;
-    const foreignSnapshot = {
-      _tag: "Error",
-      name: "Error",
-      message: "store unavailable",
-      code: { _tag: "Present", value: "ECONNRESET" },
-      status: { _tag: "Absent" },
-      stack: { _tag: "Absent" },
-      failureClass: { _tag: "Absent" },
-      cause: { _tag: "Cause", value: nested },
-    } as const;
-
-    expect(isExternalCause(foreignSnapshot)).toBe(true);
-    const normalized = normalizeExternalCause(foreignSnapshot);
-    expect(normalized).toEqual(foreignSnapshot);
-    expect(normalized).not.toBe(foreignSnapshot);
-    expect(Object.isFrozen(normalized)).toBe(true);
-    if (normalized._tag !== "ThrownValue") {
-      expect(Object.isFrozen(normalized.code)).toBe(true);
-      if (normalized.cause._tag === "Cause") {
-        expect(normalized.cause.value).not.toBe(nested);
-        expect(Object.isFrozen(normalized.cause.value)).toBe(true);
-      }
-    }
-  });
-
-  it("浅层像 ExternalCause 的伪造对象不会跳过归一化", () => {
-    const malformed = {
-      _tag: "Error",
-      name: "Error",
-      message: "untrusted",
-      code: { _tag: "Present", value: { raw: true } },
-      status: { _tag: "Absent" },
-      stack: { _tag: "Absent" },
-      failureClass: { _tag: "Absent" },
-      cause: { _tag: "Absent" },
-    };
-
-    expect(isExternalCause(malformed)).toBe(false);
-    const normalized = normalizeExternalCause(malformed);
-    expect(normalized).not.toBe(malformed);
-    expect(Object.isFrozen(normalized)).toBe(true);
-    if (normalized._tag !== "ThrownValue") expect(normalized.code).toEqual({ _tag: "Absent" });
-  });
-});
-
-describe("attachFailureClass · 框架决议出的分类附着", () => {
-  it("挂上的两个字段不可枚举:不进 JSON,只是路由标记", () => {
-    const error = attachFailureClass(new Error("boom"), { retryable: false, scope: "eval" });
-    expect(failureClassOf(error)).toEqual({ retryable: false, scope: "eval" });
-    expect(Object.keys(error)).not.toContain("class");
-    expect(JSON.stringify({ ...error })).toBe("{}");
-  });
-
-  it("抛出点已声明过的分类不被框架覆盖", () => {
-    const declared = new ExperimentFatalError("tunnel down");
-    attachFailureClass(declared, { retryable: true, reason: "rate_limit" });
-    expect(failureClassOf(declared)).toEqual({ retryable: false, scope: "experiment" });
-  });
-
-  it("非对象抛出值原样返回,不制造新失败", () => {
-    expect(attachFailureClass("string failure", { retryable: false })).toBe("string failure");
-  });
-
-  it("冻结的错误对象标记不上也不抛错(分类是旁路)", () => {
-    const frozen = Object.freeze(new Error("frozen"));
-    expect(() => attachFailureClass(frozen, { retryable: false, scope: "eval" })).not.toThrow();
-    expect(failureClassOf(frozen)).toBeUndefined();
-  });
-});
-
-describe("resolveAttemptFailureClass · 生命周期阶段的三道链", () => {
-  const info = (error: unknown): AttemptFailureInfo => attemptFailureInfo("sandbox.prepare.eval", error);
-
-  it("抛出点携带的分类命中即定,不询问实验分类器", () => {
-    const classifier = vi.fn(() => ({ retryable: false as const, scope: "attempt" as const }));
-    expect(resolveAttemptFailureClass(info(new EvalFatalError("fixture missing")), classifier)).toEqual({
-      retryable: false,
-      scope: "eval",
-    });
-    expect(classifier).not.toHaveBeenCalled();
-  });
-
-  it("实验分类器认领第三方错误,scope 与自造 reason 原样生效", () => {
-    const result = resolveAttemptFailureClass(info(new Error("connect ECONNREFUSED tunnel.example:443")), (failure) =>
-      failure.text.includes("tunnel.example")
-        ? { retryable: false, scope: "experiment", reason: "tunnel_down" }
-        : undefined,
-    );
-    expect(result).toEqual({ retryable: false, scope: "experiment", reason: "tunnel_down" });
-  });
-
-  it("链上不挂兜底正则:限流文案在这些位置也不产时间轴,缺省不可重试", () => {
-    // 同一段文本在 turn 链上会被兜底判成 rate_limit 可重试;这里没有重试执行体,
-    // 时间轴即使给出也无人消费(见 architecture.md「分类链」)。
-    expect(resolveAttemptFailureClass(info(new Error("429 too many requests, please retry later")))).toEqual({
-      retryable: false,
-    });
-  });
-
-  it("实验分类器返回 undefined / 抛错都落缺省,不掩盖原始失败", () => {
-    expect(resolveAttemptFailureClass(info(new Error("boom")), () => undefined)).toEqual({ retryable: false });
-    expect(
-      resolveAttemptFailureClass(info(new Error("boom")), () => {
-        throw new Error("classifier bug");
-      }),
-    ).toEqual({ retryable: false });
-  });
-
-  it("分类器读到的 text 与报错文案同源:错误链(含 cause)message 串接", () => {
-    const error = new Error("eval setup failed", { cause: new Error("connect ECONNREFUSED tunnel.example:443") });
-    const seen: AttemptFailureInfo[] = [];
-    resolveAttemptFailureClass(attemptFailureInfo("sandbox.prepare.eval", error), (failure) => {
-      seen.push(failure);
-      return undefined;
-    });
-    expect(seen[0].phase).toBe("sandbox.prepare.eval");
-    expect(seen[0].text).toBe("eval setup failed · connect ECONNREFUSED tunnel.example:443");
-    expect(seen[0].cause).toMatchObject({
-      _tag: "Error",
-      message: "eval setup failed",
-      cause: { _tag: "Cause", value: { _tag: "Error", message: "connect ECONNREFUSED tunnel.example:443" } },
-    });
-  });
-});

package/src/shared/failure-class.ts

@@ -1,206 +0,0 @@
-// 执行失败分类的词表、抛出点糖衣类与结构守卫——全仓唯一一份两轴词表,send 失败、生命周期
-// 阶段失败与 sandbox provisioning 失败说同一种语言(判据见
-// docs/feature/error-classification/README.md「分类」)。
-//
-// 本模块刻意零依赖(只 import type):公开面活在 Promise 世界,糖衣类不继承任何 effect 类型,
-// 生成的 .d.ts 零 effect 依赖(见 architecture.md「Effect 边界」)。send 链的实现在
-// src/context/send-failures.ts,provisioning 的内部分类在 src/sandbox/,两边各自实现、只共享
-// 这份词表。
-
-import type { LifecyclePhase } from "../runner/types.ts";
-import {
-  externalCauseMessageChain,
-  isExternalCause,
-  normalizeExternalCause,
-  type ExternalCause,
-} from "./external-cause.ts";
-
-/** 空间轴取值:失败死因的波及范围。 */
-export type FailureScope = "attempt" | "eval" | "experiment";
-
-/**
- * 一次执行失败的分类:`retryable`(时间轴)与 `scope`(空间轴)是仅有的两条决策轴;
- * `reason` 是开放词表的细分诊断,只进 activity 与诊断文案,不参与策略。内建兜底产出
- * reason `"rate_limit"` / `"network"`;声明方可自造词。`scope` 缺省 `"attempt"`。
- *
- * `retryable: true` 时 `reason` 必填:可重试的失败一定出现在 activity 行与可能的耗尽摘要里,
- * 那里需要一个给人读的词;不可重试的失败常常说不清是什么(这正是它不可重试的原因)。
- */
-export type FailureClass =
-  | { readonly retryable: true; readonly reason: string; readonly scope?: FailureScope }
-  | { readonly retryable: false; readonly reason?: string; readonly scope?: FailureScope };
-
-/**
- * 实验级分类器的输入:本实验任意 per-attempt 阶段的一次终局失败。
- */
-export interface AttemptFailureInfo {
-  /** 失败发生在哪个生命周期阶段；send 执行失败恒为 `"agent.run"`。 */
-  readonly phase: LifecyclePhase;
-  /** 与报错文案同源的失败文本:SendFailure 取 `sendFailureText`,其它阶段取错误链 message。 */
-  readonly text: string;
-  /** 动态 throwable 的有界快照；分类器只能读取 typed facts/message/cause 链。 */
-  readonly cause: ExternalCause;
-}
-
-/**
- * 实验可选分类器,挂载在 `ExperimentDef.classifyFailure`:识别自家共享基建的死因
- * (对自家隧道 host 的拒连一类)。返回 `undefined` 表示「不认识,交给后续链路」。
- * 分类器必须快、纯、不抛错——抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。
- */
-export type AttemptFailureClassifier = (failure: AttemptFailureInfo) => FailureClass | undefined;
-
-/** 携带分类的错误对象的判别字段值;识别只看这个数据字段,不看类身份。 */
-const FAILURE_CLASS_TAG = "NiceevalClassifiedError";
-
-/**
- * 少数框架内部领域错误必须保留自己的 `_tag` 供 typed failure 分支识别，同时携带同一套空间轴。
- * 这里仍按 `_tag` + `class` 的纯数据形状识别，不依赖类身份。
- */
-function isClassifiedFailureTag(tag: unknown): boolean {
-  return tag === FAILURE_CLASS_TAG;
-}
-
-/**
- * 从任意 per-attempt 阶段抛出:全实验剩余 attempt 同因必死,停止派发。
- * 携带 `{ retryable: false, scope: "experiment" }`,message 原样走完反馈流与
- * `dispatch-halted` 诊断——把它写成「现象 + 下一步」的修复提示。
- */
-export class ExperimentFatalError extends Error {
-  readonly _tag = FAILURE_CLASS_TAG;
-  readonly class: FailureClass = { retryable: false, scope: "experiment" };
-
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "ExperimentFatalError";
-  }
-}
-
-/**
- * 从任意 per-attempt 阶段抛出:本 eval 剩余 attempt 同因必死,停止派发。
- * 携带 `{ retryable: false, scope: "eval" }`;message 同样是走完全程的修复提示。
- */
-export class EvalFatalError extends Error {
-  readonly _tag = FAILURE_CLASS_TAG;
-  readonly class: FailureClass = { retryable: false, scope: "eval" };
-
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message, options);
-    this.name = "EvalFatalError";
-  }
-}
-
-/**
- * 结构守卫:识别任何携带分类的错误对象(`_tag` + `class` 两个数据字段),沿 `cause` 链逐层
- * 查找、取**最外层**命中——糖衣类被上层库包装再抛时声明不丢失。识别不依赖 `instanceof`:
- * 依赖树里出现第二份 niceeval 实例(link、版本重复)时类身份静默失效,数据不会。
- */
-export function failureClassOf(error: unknown): FailureClass | undefined {
-  if (isExternalCause(error)) return failureClassOfExternalCause(error);
-  let current: unknown = error;
-  for (let depth = 0; depth < CAUSE_CHAIN_DEPTH && current != null; depth++) {
-    if (isExternalCause(current)) return failureClassOfExternalCause(current);
-    if (typeof current === "object") {
-      const candidate = current as { _tag?: unknown; class?: unknown };
-      if (isClassifiedFailureTag(candidate._tag) && isFailureClass(candidate.class)) return candidate.class;
-    }
-    current = causeOf(current);
-  }
-  return undefined;
-}
-
-function failureClassOfExternalCause(cause: ExternalCause): FailureClass | undefined {
-  let current: ExternalCause = cause;
-  for (;;) {
-    if (current._tag !== "ThrownValue" && current.failureClass._tag === "Present") {
-      return current.failureClass.value;
-    }
-    if (current.cause._tag !== "Cause") return undefined;
-    current = current.cause.value;
-  }
-}
-
-/** cause 链与错误文本串接共用的深度上限:防御自引用 / 病态深链,不做环检测。 */
-const CAUSE_CHAIN_DEPTH = 5;
-
-function causeOf(value: unknown): unknown {
-  return typeof value === "object" && value !== null ? (value as { cause?: unknown }).cause : undefined;
-}
-
-function isFailureClass(value: unknown): value is FailureClass {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as { retryable?: unknown; reason?: unknown; scope?: unknown };
-  if (typeof v.retryable !== "boolean") return false;
-  if (v.retryable && typeof v.reason !== "string") return false;
-  if (v.reason !== undefined && typeof v.reason !== "string") return false;
-  if (v.scope !== undefined && v.scope !== "attempt" && v.scope !== "eval" && v.scope !== "experiment") return false;
-  return true;
-}
-
-/**
- * @internal 把框架决议出的分类挂到即将浮出的失败对象上,供 attempt 封口经 `failureClassOf`
- * 读取(止损闸的消费点)。两个字段都不可枚举——不进 JSON、不进 console 输出,只是路由标记;
- * 已携带分类的对象不覆盖(抛出点声明优先),不可写对象静默跳过(分类是旁路,不制造新失败)。
- */
-export function attachFailureClass<T>(target: T, cls: FailureClass): T {
-  if (typeof target !== "object" || target === null) return target;
-  if (failureClassOf(target) !== undefined) return target;
-  try {
-    Object.defineProperty(target, "_tag", { value: FAILURE_CLASS_TAG, enumerable: false, configurable: true });
-    Object.defineProperty(target, "class", { value: cls, enumerable: false, configurable: true });
-  } catch {
-    // 冻结 / 密封的错误对象:标记不上就算了,分类退化成 attempt 档,不掩盖原始失败。
-  }
-  return target;
-}
-
-/**
- * @internal 错误链(含 `cause` 链)的 message 串接:给人读的报错文案与给分类器看的失败文本
- * 用这同一段,不出现「报错说 A、分类看 B」。
- */
-export function errorChainText(error: unknown): string {
-  const parts: string[] = [];
-  let current: unknown = error;
-  for (let depth = 0; depth < CAUSE_CHAIN_DEPTH && current != null; depth++) {
-    const candidate = typeof current === "object" && current !== null
-      ? (current as { message?: unknown }).message
-      : undefined;
-    const message = typeof candidate === "string" ? candidate : current instanceof Error ? current.message : String(current);
-    if (message) parts.push(message);
-    current = causeOf(current);
-  }
-  return parts.join(" · ");
-}
-
-/**
- * @internal 调分类器的统一纪律:抛错按 `undefined` 回落(自身错误被吞掉,不得用新错误掩盖
- * 原始失败),返回值原样透出。turn 链与生命周期链共用这一处,两条链的纪律不会跑偏。
- */
-export function callClassifier<T>(classifier: ((failure: T) => FailureClass | undefined) | undefined, failure: T) {
-  if (!classifier) return undefined;
-  try {
-    return classifier(failure);
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * @internal 生命周期阶段失败的分类链(三道):抛出点携带的分类 → 实验分类器 → 缺省
- * `{ retryable: false }`。这些位置(sandbox 钩子、`EvalDef.setup`、`test(t)` 体内、
- * per-attempt teardown)没有重试执行体,链上不挂产时间轴的兜底正则——时间轴即使给出也无人
- * 消费(见 architecture.md「分类链」)。
- */
-export function resolveAttemptFailureClass(
-  info: AttemptFailureInfo,
-  experimentClassifier?: AttemptFailureClassifier,
-): FailureClass {
-  const declared = failureClassOf(info.cause);
-  if (declared) return declared;
-  return callClassifier(experimentClassifier, info) ?? { retryable: false };
-}
-
-/** @internal 从一个抛出的错误构造实验分类器的输入(文本与报错文案同源)。 */
-export function attemptFailureInfo(phase: LifecyclePhase, error: unknown): AttemptFailureInfo {
-  const cause = normalizeExternalCause(error);
-  return { phase, text: externalCauseMessageChain(cause), cause };
-}

package/src/shared/format.ts

@@ -1,26 +0,0 @@
-// server 与前端共用的数值格式化;两边展示口径(取整/单位切换阈值)必须一致,所以单独成模块。
-// 保持环境无关:不 import node/browser API。日期格式化不在这里 —— 它按前端当前 locale 做,
-// 留在 app/lib/format.ts(见 formatDateTime)。
-
-export function formatPercent(value?: number): string {
-  if (typeof value !== "number" || !Number.isFinite(value)) return "0%";
-  return Math.round(value * 100) + "%";
-}
-
-export function formatDuration(ms?: number): string {
-  if (typeof ms !== "number" || !Number.isFinite(ms) || ms <= 0) return "0ms";
-  if (ms >= 60_000) return (ms / 60_000).toFixed(1) + "m";
-  if (ms >= 1000) return (ms / 1000).toFixed(2) + "s";
-  return Math.round(ms) + "ms";
-}
-
-export function formatCost(value?: number): string {
-  // 查不到价 / 没有 model 时上游传 undefined(见 o11y/cost.ts) —— 显示 "—" 而不是騙人的 $0,
-  // 否则「真实但极小的花费」和「压根没算出成本」在界面上长得一模一样。
-  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return "—";
-  if (value >= 1) return "$" + value.toFixed(2);
-  if (value >= 0.001) return "$" + value.toFixed(3);
-  // 便宜模型 + 小样本(如 tier1 示例)常见的真实成本,3 位小数会整个舍成 0.000,
-  // 这里退到 2 位有效数字,保留"确实花了一点点钱"的信号。
-  return "$" + value.toPrecision(2);
-}

package/src/shared/json-match.ts

@@ -1,42 +0,0 @@
-import type { JsonMatch, JsonValue } from "./types.ts";
-
-/** 按 JsonMatch 递归匹配；对象为部分匹配，数组为等长逐项匹配。 */
-export function matchesJson(actual: JsonValue | undefined, expected: JsonMatch): boolean {
-  return matchesJsonAt(actual, expected, actual);
-}
-
-function matchesJsonAt(actual: JsonValue | undefined, expected: JsonMatch, root: JsonValue | undefined): boolean {
-  if (expected instanceof RegExp) {
-    if (typeof actual === "string" && testRegExp(expected, actual)) return true;
-    try {
-      return testRegExp(expected, JSON.stringify(root) ?? String(root));
-    } catch {
-      return false;
-    }
-  }
-  if (typeof expected === "function") return Boolean(expected(actual));
-  if (Array.isArray(expected)) {
-    return (
-      Array.isArray(actual) &&
-      actual.length === expected.length &&
-      expected.every((item, index) => matchesJsonAt(actual[index], item, root))
-    );
-  }
-  if (isPlainObject(expected)) {
-    if (!isPlainObject(actual)) return false;
-    const actualObject = actual as globalThis.Record<string, JsonValue>;
-    return Object.entries(expected).every(([key, value]) => matchesJsonAt(actualObject[key], value, root));
-  }
-  return Object.is(actual, expected);
-}
-
-function testRegExp(re: RegExp, value: string): boolean {
-  re.lastIndex = 0;
-  return re.test(value);
-}
-
-function isPlainObject(value: unknown): value is globalThis.Record<string, JsonMatch> {
-  if (value === null || typeof value !== "object") return false;
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}

package/src/shared/json-value.test.ts

@@ -1,24 +0,0 @@
-// cases: docs/engineering/testing/unit/adapters.md
-import { describe, expect, it } from "vitest";
-
-import { isJsonValue, normalizeJsonValue } from "./json-value.ts";
-
-describe("JSON value boundary", () => {
-  it("keeps an already valid JSON tree strongly typed", () => {
-    const value = { ok: true, rows: [1, "two", null] };
-    expect(isJsonValue(value)).toBe(true);
-    expect(normalizeJsonValue(value)).toBe(value);
-  });
-
-  it("cleans serializable SDK objects before they enter domain events", () => {
-    const value = { createdAt: new Date("2026-08-02T00:00:00.000Z"), omitted: undefined };
-    expect(normalizeJsonValue(value)).toEqual({ createdAt: "2026-08-02T00:00:00.000Z" });
-  });
-
-  it("uses a typed fallback for values JSON cannot represent", () => {
-    const cyclic: { self?: object } = {};
-    cyclic.self = cyclic;
-    expect(normalizeJsonValue(cyclic, { invalid: true })).toEqual({ invalid: true });
-    expect(normalizeJsonValue(1n)).toBeNull();
-  });
-});

package/src/shared/json-value.ts

@@ -1,36 +0,0 @@
-import type { JsonValue } from "./types.ts";
-
-/**
- * 动态 SDK/JSON 边界的运行时判定。这里只接受真正可序列化的 JSON 树；循环引用、
- * 非有限数字以及带自定义原型的实例都不能进入 NiceEval 的领域事件。
- */
-export function isJsonValue(value: unknown, ancestors: ReadonlySet<object> = new Set()): value is JsonValue {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
-  if (typeof value === "number") return Number.isFinite(value);
-  if (typeof value !== "object") return false;
-  if (ancestors.has(value)) return false;
-
-  const nextAncestors = new Set(ancestors);
-  nextAncestors.add(value);
-  if (Array.isArray(value)) return value.every((item) => isJsonValue(item, nextAncestors));
-
-  const prototype = Object.getPrototypeOf(value);
-  if (prototype !== Object.prototype && prototype !== null) return false;
-  return Object.values(value).every((item) => isJsonValue(item, nextAncestors));
-}
-
-/**
- * 把外部 SDK 值收口成 JsonValue。已经合规的值保持引用；其余值先按 JSON 语义清洗，
- * 仍无法序列化时使用调用方给出的强类型回退值。
- */
-export function normalizeJsonValue(value: unknown, fallback: JsonValue = null): JsonValue {
-  if (isJsonValue(value)) return value;
-  try {
-    const serialized = JSON.stringify(value);
-    if (serialized === undefined) return fallback;
-    const parsed: unknown = JSON.parse(serialized);
-    return isJsonValue(parsed) ? parsed : fallback;
-  } catch {
-    return fallback;
-  }
-}

package/src/shared/turn-label.test.ts

@@ -1,20 +0,0 @@
-// cases: docs/engineering/testing/unit/reports.md
-
-import { describe, expect, it } from "vitest";
-
-import { normalizeTurnLabel } from "./turn-label.ts";
-
-describe("normalizeTurnLabel", () => {
-  it("归一主会话与额外会话的旧标签", () => {
-    const main = ["s1", "t1"].join("/");
-    const extra = ["s2", "t3"].join("/");
-
-    expect(normalizeTurnLabel(main)).toBe("turn1");
-    expect(normalizeTurnLabel(extra)).toBe("session2/turn3");
-  });
-
-  it("保留当前标签与其它 opaque label", () => {
-    expect(normalizeTurnLabel("turn1")).toBe("turn1");
-    expect(normalizeTurnLabel("legacy-internal-label")).toBe("legacy-internal-label");
-  });
-});

package/src/shared/turn-label.ts

@@ -1,15 +0,0 @@
-/**
- * 生成 attempt 内跨 execution、timing、source 与 diff 的同一轮身份 token。
- *
- * 新写入只使用本函数；主会话使用 `turn<N>`，额外会话使用
- * `session<K>/turn<N>`。旧 artifact 在展示/读取边界使用 `normalizeTurnLabel`，不回写落盘值。
- */
-export function formatTurnLabel(sessionIndex: number, turnIndex: number): string {
-  return sessionIndex === 1 ? `turn${turnIndex}` : `session${sessionIndex}/turn${turnIndex}`;
-}
-
-/** 把旧 artifact 的坐标标签归一成当前展示格式；其它 opaque label 原样保留。 */
-export function normalizeTurnLabel(label: string): string {
-  const match = /^s([1-9]\d*)\/t([1-9]\d*)$/.exec(label);
-  return match === null ? label : formatTurnLabel(Number(match[1]), Number(match[2]));
-}