recallnest 2.5.4 → 2.6.1

package/src/eval.ts

@@ -8,6 +8,8 @@ import { buildSessionCheckpointRecord, normalizeCheckpointScope } from "./sessio
 import type { ResumeContextResponse, SessionCheckpointRecord } from "./session-schema.js";
 import { composeResumeContext } from "./context-composer.js";
 import { cleanText } from "./context-composer-text.js";
+import { estimateTokens } from "./context-collapse-renderer.js";
+import { TraceCollector } from "./retrieval-trace.js";
 import { createComponents, loadConfig, loadDotEnv, type LocalMemoryConfig } from "./runtime-config.js";
 import { logInfo } from "./stderr-log.js";
 import { buildWorkflowObservationRecord } from "./workflow-observation-engine.js";
@@ -80,6 +82,30 @@ export interface CanaryEvalCase {
   notes?: string;
 }
 
+/**
+ * Per-case cost accounting for the retrieval pipeline — the X axis of the
+ * Pareto curve (see hippo-wiki [[帕累托效率曲线]]).
+ *
+ * Scope: self-comparison across runs (did a retrieval change make it slower or
+ * fatter?). NOT for cross-system comparison — `contextTokens` comes from an
+ * estimator, not a real tokenizer, and this suite is not LoCoMo, so the numbers
+ * are not commensurable with competitors' published token counts.
+ */
+export interface EvalCostMetrics {
+  /** End-to-end retrieve() wall time. */
+  totalMs: number;
+  /** Number of memories returned. */
+  resultCount: number;
+  /** Estimated tokens of returned memory text — the context a caller would spend. */
+  contextTokens: number;
+  /** Duration of the rerank stage, or null when the pipeline ran no rerank.
+   *  Left as a raw fact rather than an inferred "api calls" count: a local
+   *  lightweight rerank and a remote cross-encoder both produce a stage here. */
+  rerankMs: number | null;
+  /** Three slowest stages, for locating the bottleneck. */
+  slowestStages: Array<{ name: string; durationMs: number }>;
+}
+
 export interface CanaryCaseReport {
   mode: "canary";
   name: string;
@@ -98,6 +124,8 @@ export interface CanaryCaseReport {
   topIds: string[];
   topSnippet: string;
   notes?: string;
+  /** Attached by the runner after scoring; absent when scored standalone. */
+  cost?: EvalCostMetrics;
 }
 
 export interface RetrievalCaseReport {
@@ -115,6 +143,8 @@ export interface RetrievalCaseReport {
   topScopes: string[];
   topSnippet: string;
   notes?: string;
+  /** Attached by the runner after scoring; absent when scored standalone. */
+  cost?: EvalCostMetrics;
 }
 
 export interface ContinuityCaseReport {
@@ -217,8 +247,16 @@ function matchedTerms(terms: string[] | undefined, haystack: string): string[] {
   return (terms || []).filter((term) => haystack.includes(term.toLowerCase()));
 }
 
+/**
+ * 命中比例 × 权重。
+ *
+ * 调用方必须先滤掉 case 没声明的期望、再对剩下的权重重新归一化——下面三个
+ * 评分器都是这么做的。空期望这里返回 0 而不是 weight：万一将来有第四个调用
+ * 点忘了滤，代价是少给分而不是白送分。三个现有调用点都已滤过，所以这个分支
+ * 当前走不到，纯属兜底。
+ */
 function scoreExpectation(expected: string[] | undefined, matched: string[], weight: number): number {
-  if (!expected || expected.length === 0) return weight;
+  if (!expected || expected.length === 0) return 0;
   return (matched.length / expected.length) * weight;
 }
 
@@ -236,10 +274,23 @@ export function scoreRetrievalCase(
   const matchedScopes = (evalCase.expectScopePrefixes || []).filter((scope) => scopes.some((item) => item.startsWith(scope)));
   const forbiddenMatches = matchedTerms(evalCase.forbid, joined);
 
-  let score = 0;
-  score += scoreExpectation(evalCase.expectAny, matchedAny, 0.4);
-  score += scoreExpectation(evalCase.expectAll, matchedAll, 0.3);
-  score += scoreExpectation(evalCase.expectScopePrefixes, matchedScopes, 0.2);
+  // 动态加权：只计 case 实际声明的维度，权重在这些维度间重新归一化——
+  // 和下面 canary、continuity 两个评分器已有的写法一致。
+  // 改之前未声明的维度按满权重计入，而 eval/cases.json 里 20 个 case 一个都没写
+  // expectAll，于是每个 case 白拿 0.3：expectAny 四个词命中一个再加 scope 前缀命中，
+  // 正好落在 0.7 及格线上。
+  const expectationScores = [
+    { expected: evalCase.expectAny, matched: matchedAny, weight: 0.4 },
+    { expected: evalCase.expectAll, matched: matchedAll, weight: 0.3 },
+    { expected: evalCase.expectScopePrefixes, matched: matchedScopes, weight: 0.2 },
+  ].filter((item) => (item.expected || []).length > 0);
+
+  const totalExpectedWeight = expectationScores.reduce((sum, item) => sum + item.weight, 0);
+  const normalizedExpectationScore = totalExpectedWeight > 0
+    ? expectationScores.reduce((sum, item) => sum + scoreExpectation(item.expected, item.matched, item.weight), 0) / totalExpectedWeight
+    : 0;
+
+  let score = normalizedExpectationScore * 0.9;
   if (results.length > 0) score += 0.1;
   if (forbiddenMatches.length > 0) score -= 0.3;
   score = Math.max(0, Math.min(1, score));
@@ -552,11 +603,12 @@ function markdownRetrievalReport(reports: RetrievalCaseReport[]): string {
     `- Cases: ${reports.length}`,
     `- Passed: ${passed}/${reports.length}`,
     `- Average score: ${formatPercent(average)}`,
+    ...costSummaryLines(summarizeCost(reports), reports.length),
     "",
-    "| Case | Profile | Score | Pass | Hits | Top scopes |",
-    "|------|---------|-------|------|------|------------|",
+    "| Case | Profile | Score | Pass | Hits | ms | ~tok | Top scopes |",
+    "|------|---------|-------|------|------|----|------|------------|",
     ...reports.map((item) =>
-      `| ${item.name} | ${item.profile} | ${(item.score * 100).toFixed(0)}% | ${item.passed ? "yes" : "no"} | ${item.hitCount} | ${item.topScopes.join(", ") || "-"} |`,
+      `| ${item.name} | ${item.profile} | ${(item.score * 100).toFixed(0)}% | ${item.passed ? "yes" : "no"} | ${item.hitCount} | ${item.cost?.totalMs ?? "-"} | ${item.cost?.contextTokens ?? "-"} | ${item.topScopes.join(", ") || "-"} |`,
     ),
     "",
     "## Case Notes",
@@ -575,6 +627,7 @@ function markdownRetrievalReport(reports: RetrievalCaseReport[]): string {
     lines.push(`- Matched all: ${item.matchedAll.join(", ") || "-"}`);
     lines.push(`- Matched scopes: ${item.matchedScopes.join(", ") || "-"}`);
     lines.push(`- Forbidden matches: ${item.forbiddenMatches.join(", ") || "-"}`);
+    if (item.cost) lines.push(`- Cost: ${formatCost(item.cost)}`);
     if (item.notes) lines.push(`- Notes: ${item.notes}`);
     lines.push("");
   }
@@ -596,11 +649,12 @@ function markdownCanaryReport(reports: CanaryCaseReport[]): string {
     `- Average score: ${formatPercent(average)}`,
     `- Top1 hit: ${top1}/${reports.length}`,
     `- Top3 hit: ${top3}/${reports.length}`,
+    ...costSummaryLines(summarizeCost(reports), reports.length),
     "",
-    "| Case | Profile | Score | Pass | Top1 | Top3 | Order | Forbid |",
-    "|------|---------|-------|------|------|------|-------|--------|",
+    "| Case | Profile | Score | Pass | Top1 | Top3 | Order | Forbid | ms | ~tok |",
+    "|------|---------|-------|------|------|------|-------|--------|----|------|",
     ...reports.map((item) =>
-      `| ${item.name} | ${item.profile} | ${(item.score * 100).toFixed(0)}% | ${item.passed ? "yes" : "no"} | ${item.top1Hit ? "yes" : "-"} | ${item.top3Hit ? "yes" : "-"} | ${item.orderOk === null ? "-" : item.orderOk ? "ok" : "bad"} | ${item.forbiddenIdMatches.length + item.forbiddenMatches.length || "-"} |`,
+      `| ${item.name} | ${item.profile} | ${(item.score * 100).toFixed(0)}% | ${item.passed ? "yes" : "no"} | ${item.top1Hit ? "yes" : "-"} | ${item.top3Hit ? "yes" : "-"} | ${item.orderOk === null ? "-" : item.orderOk ? "ok" : "bad"} | ${item.forbiddenIdMatches.length + item.forbiddenMatches.length || "-"} | ${item.cost?.totalMs ?? "-"} | ${item.cost?.contextTokens ?? "-"} |`,
     ),
     "",
     "## Case Notes",
@@ -619,6 +673,7 @@ function markdownCanaryReport(reports: CanaryCaseReport[]): string {
     lines.push(`- Forbidden term matches: ${item.forbiddenMatches.join(", ") || "-"}`);
     lines.push(`- Top ids: ${item.topIds.join(", ") || "-"}`);
     lines.push(`- Top snippet: ${item.topSnippet}`);
+    if (item.cost) lines.push(`- Cost: ${formatCost(item.cost)}`);
     if (item.notes) lines.push(`- Notes: ${item.notes}`);
     lines.push("");
   }
@@ -673,6 +728,88 @@ function markdownContinuityReport(reports: ContinuityCaseReport[]): string {
   return lines.join("\n");
 }
 
+/**
+ * Turn a finished TraceCollector plus the returned memories into cost metrics.
+ *
+ * The `mode` argument to finalize() only populates a display field on the trace
+ * object; this function consumes stages / totalMs only, so it is not inferred.
+ */
+function collectCostMetrics(
+  trace: TraceCollector,
+  query: string,
+  results: Array<{ entry: { text: string } }>,
+): EvalCostMetrics {
+  const finalized = trace.finalize(query, "hybrid");
+  const rerankStage = finalized.stages.find((stage) => stage.name === "rerank");
+  const slowestStages = [...finalized.stages]
+    .sort((a, b) => b.durationMs - a.durationMs)
+    .slice(0, 3)
+    .map((stage) => ({ name: stage.name, durationMs: stage.durationMs }));
+
+  return {
+    totalMs: finalized.totalMs,
+    resultCount: results.length,
+    contextTokens: results.reduce((sum, item) => sum + estimateTokens(item.entry.text), 0),
+    rerankMs: rerankStage ? rerankStage.durationMs : null,
+    slowestStages,
+  };
+}
+
+/** Aggregate cost across cases. Cases without cost data are skipped, and the
+ *  count of those that did carry it is returned so the report can be honest
+ *  about coverage rather than silently averaging over fewer cases. */
+function summarizeCost(reports: Array<{ cost?: EvalCostMetrics }>): {
+  measured: number;
+  totalMs: number;
+  avgMs: number;
+  totalTokens: number;
+  avgTokens: number;
+} | null {
+  const withCost = reports.map((item) => item.cost).filter((cost): cost is EvalCostMetrics => Boolean(cost));
+  if (withCost.length === 0) return null;
+
+  const totalMs = withCost.reduce((sum, cost) => sum + cost.totalMs, 0);
+  const totalTokens = withCost.reduce((sum, cost) => sum + cost.contextTokens, 0);
+  return {
+    measured: withCost.length,
+    totalMs,
+    avgMs: Math.round(totalMs / withCost.length),
+    totalTokens,
+    avgTokens: Math.round(totalTokens / withCost.length),
+  };
+}
+
+/** Aggregate cost lines for a report header. Returns [] when no case carried
+ *  cost data, so reports produced before this instrumentation still render. */
+function costSummaryLines(
+  summary: ReturnType<typeof summarizeCost>,
+  caseCount: number,
+): string[] {
+  if (!summary) return [];
+  const coverage = summary.measured === caseCount
+    ? ""
+    : ` (measured on ${summary.measured}/${caseCount} cases)`;
+  return [
+    `- Retrieval latency: ${summary.avgMs} ms avg, ${summary.totalMs} ms total${coverage}`,
+    `- Context tokens: ~${summary.avgTokens} avg, ~${summary.totalTokens} total`
+      + ` (estimated, not tokenizer-measured — compare across runs, not against other systems)`,
+  ];
+}
+
+/** One-line per-case cost breakdown. */
+function formatCost(cost: EvalCostMetrics): string {
+  const parts = [
+    `${cost.totalMs}ms`,
+    `~${cost.contextTokens} tok`,
+    `${cost.resultCount} results`,
+    cost.rerankMs === null ? "no rerank stage" : `rerank ${cost.rerankMs}ms`,
+  ];
+  const slowest = cost.slowestStages
+    .map((stage) => `${stage.name} ${stage.durationMs}ms`)
+    .join(", ");
+  return `${parts.join(" / ")}${slowest ? ` | slowest: ${slowest}` : ""}`;
+}
+
 export async function runRetrievalEval(
   cases: RetrievalEvalCase[],
   deps: {
@@ -690,13 +827,16 @@ export async function runRetrievalEval(
     const profileName = evalCase.profile || "default";
     const { retriever, accessTracker } = createEvalComponentsForCase(profileName);
     try {
+      const trace = new TraceCollector();
       const results = await retriever.retrieve({
         query: evalCase.query,
         limit: evalCase.limit || 5,
         scopeFilter: evalCase.scope ? [evalCase.scope] : undefined,
         source: "auto-recall",
+        trace,
       });
       const report = scoreRetrievalCase(evalCase, results);
+      report.cost = collectCostMetrics(trace, evalCase.query, results);
       reports.push(report);
       if (cases.length > 1) {
         logInfo(
@@ -728,13 +868,16 @@ export async function runCanaryEval(
     const profileName = evalCase.profile || "default";
     const { retriever, accessTracker } = createEvalComponentsForCase(profileName);
     try {
+      const trace = new TraceCollector();
       const results = await retriever.retrieve({
         query: evalCase.query,
         limit: evalCase.limit || 8,
         scopeFilter: evalCase.scope ? [evalCase.scope] : undefined,
         source: "auto-recall",
+        trace,
       });
       const report = scoreCanaryCase(evalCase, results);
+      report.cost = collectCostMetrics(trace, evalCase.query, results);
       reports.push(report);
       if (cases.length > 1) {
         logInfo(

package/src/freshness.ts

@@ -0,0 +1,192 @@
+/**
+ * Freshness — 记忆新鲜度四态判定
+ *
+ * 出处：通用Wiki上下文记忆Agent方案借鉴审计（2026-07-21，Alice 拍板落地）。
+ *
+ * 召回的记忆按"依赖状态"判定有效性，四个离散档：
+ *   - exact       依赖原封未动，可直接复用
+ *   - compatible  依赖变了，但落在声明的兼容集内，不影响结论
+ *   - uncertain   依赖变了且无法判定是否影响结论，复用前需验证
+ *   - invalid     依赖对象已失效（文件删了 / 仓库没了）
+ *
+ * 判据是"依赖状态"不是"时间"：依赖对象在不在 / revision 变没变。
+ * 失效颗粒度是结论级：每条记忆绑自己的 dependsOn，某个来源变了只降那一条。
+ *
+ * 硬边界（承重约束）：
+ *   1. 判定必须廉价 —— 单条依赖 = 一次 existsSync/statSync（O(1) syscall）
+ *      或一次 `git rev-parse`（单进程、无网络、按 repo 目录 memoize）。
+ *      绝不全量扫描、绝不调模型、绝不网络请求。
+ *   2. opt-in —— 只对显式声明了 dependsOn 的记忆生效。无声明的记忆
+ *      evaluateEntryFreshness 返回 null，零开销、行为与之前完全一致。
+ *   3. 向后兼容 —— dependsOn 存活在既有 metadata JSON 列里（照 emotion /
+ *      privacyTier 惯例），不新增数据库字段、不改破坏性 schema。
+ */
+
+import { z } from "zod";
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const FRESHNESS_STATES = ["exact", "compatible", "uncertain", "invalid"] as const;
+export type Freshness = (typeof FRESHNESS_STATES)[number];
+export const FreshnessSchema = z.enum(FRESHNESS_STATES);
+
+export const DEPENDENCY_KINDS = ["file", "git-rev"] as const;
+export type DependencyKind = (typeof DEPENDENCY_KINDS)[number];
+
+/**
+ * 一条依赖声明。首版只支持 file / git-rev（不支持任意 cmd 执行，安全优先）。
+ *   kind='file'    ref = 文件路径；expected = 文件 mtime（毫秒时间戳的整数字符串）
+ *                  作为廉价变更指纹，缺省时只做存在性检查。内容级精确请用 git-rev。
+ *   kind='git-rev' ref = git 仓库内的路径（文件或目录，取其所在仓库 HEAD）；
+ *                  expected = 期望 commit hash（支持短 hash 前缀），缺省时只做仓库存在性检查。
+ * expected 单值或数组：数组首值匹配 = exact，其余值匹配 = compatible（= 声明的兼容集）。
+ */
+export const DependencySchema = z.object({
+  kind: z.enum(DEPENDENCY_KINDS),
+  ref: z.string().min(1).max(500),
+  expected: z
+    .union([z.string().min(1).max(200), z.array(z.string().min(1).max(200)).min(1).max(8)])
+    .optional(),
+});
+export type Dependency = z.infer<typeof DependencySchema>;
+
+export const DependsOnSchema = z.array(DependencySchema).min(1).max(8);
+
+/** 判定结果按严重度排序，聚合时取最差。 */
+const SEVERITY: Record<Freshness, number> = { exact: 0, compatible: 1, uncertain: 2, invalid: 3 };
+
+/** git rev-parse 结果按 repo 目录缓存：一次判定批次内同一仓库只 spawn 一次 git。 */
+export type FreshnessCache = Map<string, string | null>;
+
+export function createFreshnessCache(): FreshnessCache {
+  return new Map();
+}
+
+/** 从记忆 metadata JSON 解析 dependsOn 声明；缺失或非法返回 null（照 parseEmotion 惯例）。 */
+export function parseDependsOn(metadata?: string): Dependency[] | null {
+  if (!metadata) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(metadata);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") return null;
+  const raw = (parsed as Record<string, unknown>).dependsOn;
+  if (raw == null) return null;
+  const result = DependsOnSchema.safeParse(raw);
+  return result.success ? result.data : null;
+}
+
+/** 校验来自 store 输入侧的 dependsOn（unknown → Dependency[] | null）。 */
+export function parseDependsOnInput(raw: unknown): Dependency[] | null {
+  if (raw == null) return null;
+  const result = DependsOnSchema.safeParse(raw);
+  return result.success ? result.data : null;
+}
+
+function toExpectedList(expected: Dependency["expected"]): string[] {
+  if (expected == null) return [];
+  return Array.isArray(expected) ? expected : [expected];
+}
+
+/**
+ * 把"当前值"归类到 exact / compatible / uncertain。
+ *   - 无 expected：只做存在性检查，存在即 exact。
+ *   - 匹配 expected[0]（首选/最新）→ exact
+ *   - 匹配 expected[1..]（声明的其他兼容值）→ compatible
+ *   - 都不匹配 → uncertain（变了，且无法判定是否影响结论）
+ */
+function classifyAgainstExpected(
+  current: string,
+  expected: string[],
+  matches: (current: string, candidate: string) => boolean,
+): Freshness {
+  if (expected.length === 0) return "exact";
+  if (matches(current, expected[0])) return "exact";
+  for (let i = 1; i < expected.length; i++) {
+    if (matches(current, expected[i])) return "compatible";
+  }
+  return "uncertain";
+}
+
+function exactMatch(current: string, candidate: string): boolean {
+  return current === candidate;
+}
+
+/** 短 hash 友好：current 是完整 HEAD（40 hex），candidate 可为完整或短前缀。 */
+function gitRevMatch(current: string, candidate: string): boolean {
+  if (!candidate) return false;
+  const a = current.toLowerCase();
+  const b = candidate.toLowerCase();
+  return a === b || a.startsWith(b);
+}
+
+function resolveHeadRev(ref: string, cache: FreshnessCache): string | null {
+  let dir: string;
+  try {
+    dir = existsSync(ref) && statSync(ref).isDirectory() ? ref : dirname(ref);
+  } catch {
+    dir = dirname(ref);
+  }
+  const cached = cache.get(dir);
+  if (cached !== undefined) return cached;
+  let rev: string | null = null;
+  try {
+    const out = execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      timeout: 2000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    rev = out.length > 0 ? out : null;
+  } catch {
+    rev = null; // 非 git 仓库 / git 不可用 / 超时 → 依赖失效
+  }
+  cache.set(dir, rev);
+  return rev;
+}
+
+/** 单条依赖的廉价判定。 */
+export function evaluateDependency(dep: Dependency, cache: FreshnessCache): Freshness {
+  const expected = toExpectedList(dep.expected);
+  if (dep.kind === "file") {
+    if (!existsSync(dep.ref)) return "invalid";
+    if (expected.length === 0) return "exact";
+    let mtime: string;
+    try {
+      mtime = String(Math.floor(statSync(dep.ref).mtimeMs));
+    } catch {
+      return "invalid"; // 存在性检查与 stat 之间被删
+    }
+    return classifyAgainstExpected(mtime, expected, exactMatch);
+  }
+  // git-rev
+  const head = resolveHeadRev(dep.ref, cache);
+  if (head === null) return "invalid";
+  return classifyAgainstExpected(head, expected, gitRevMatch);
+}
+
+/** 多条依赖聚合：取最差（worst-case）——任一依赖失效，整条记忆就不可全信。 */
+export function evaluateFreshness(deps: Dependency[], cache?: FreshnessCache): Freshness {
+  if (deps.length === 0) return "exact";
+  const revCache = cache ?? createFreshnessCache();
+  let worst: Freshness = "exact";
+  for (const dep of deps) {
+    const f = evaluateDependency(dep, revCache);
+    if (SEVERITY[f] > SEVERITY[worst]) worst = f;
+    if (worst === "invalid") break; // 已是最差档，无需继续
+  }
+  return worst;
+}
+
+/**
+ * 便捷入口：从记忆 metadata 判定新鲜度。
+ * opt-in —— 无 dependsOn 声明返回 null（调用方据此跳过展示，零开销）。
+ * @param cache 可选的跨条目共享缓存（渲染一批结果时传入，令同仓库只 spawn 一次 git）。
+ */
+export function evaluateEntryFreshness(metadata?: string, cache?: FreshnessCache): Freshness | null {
+  const deps = parseDependsOn(metadata);
+  if (!deps) return null;
+  return evaluateFreshness(deps, cache);
+}

package/src/http-request-policy.ts

@@ -0,0 +1,148 @@
+export const LOCAL_HTTP_HOSTNAME = "127.0.0.1";
+export const LOCAL_JSON_BODY_LIMIT_BYTES = 1024 * 1024;
+
+const LOCAL_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1"]);
+const DEFAULT_JSON_METHODS = ["POST"] as const;
+
+export interface LocalHttpRequestPolicyOptions {
+  jsonMethods?: readonly string[];
+  maxJsonBodyBytes?: number;
+}
+
+export type LocalHttpRequestPolicyResult =
+  | { allowed: true }
+  | { allowed: false; status: 400 | 403 | 413 | 415; message: string };
+
+function reject(
+  status: 400 | 403 | 413 | 415,
+  message: string,
+): LocalHttpRequestPolicyResult {
+  return { allowed: false, status, message };
+}
+
+function normalizeHostname(hostname: string): string {
+  const normalized = hostname.trim().toLowerCase();
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    return normalized.slice(1, -1);
+  }
+  return normalized;
+}
+
+function hostnameFromHostHeader(hostHeader: string): string | null {
+  const authority = hostHeader.trim();
+  if (!authority || /[\s/@?#\\]/.test(authority)) return null;
+
+  try {
+    return normalizeHostname(new URL(`http://${authority}`).hostname);
+  } catch {
+    return null;
+  }
+}
+
+function isLocalHostname(hostname: string): boolean {
+  return LOCAL_HOSTNAMES.has(normalizeHostname(hostname));
+}
+
+function readContentLength(request: Request): number | null {
+  const raw = request.headers.get("content-length");
+  if (raw == null) return null;
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return Number.NaN;
+  return Number(trimmed);
+}
+
+async function bodyExceedsLimit(request: Request, maxBytes: number): Promise<boolean> {
+  if (!request.body) return false;
+
+  const reader = request.clone().body?.getReader();
+  if (!reader) return false;
+
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) return false;
+      totalBytes += chunk.value.byteLength;
+      if (totalBytes > maxBytes) {
+        void reader.cancel("request body too large").catch(() => {});
+        return true;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+export async function enforceLocalHttpRequestPolicy(
+  request: Request,
+  options: LocalHttpRequestPolicyOptions = {},
+): Promise<LocalHttpRequestPolicyResult> {
+  let requestUrl: URL;
+  try {
+    requestUrl = new URL(request.url);
+  } catch {
+    return reject(400, "Invalid request URL.");
+  }
+
+  if (!isLocalHostname(requestUrl.hostname)) {
+    return reject(403, "Host is not allowed.");
+  }
+
+  const hostHeader = request.headers.get("host");
+  if (hostHeader != null) {
+    const hostname = hostnameFromHostHeader(hostHeader);
+    if (!hostname || !isLocalHostname(hostname)) {
+      return reject(403, "Host is not allowed.");
+    }
+  }
+
+  const fetchSite = request.headers.get("sec-fetch-site")?.trim().toLowerCase();
+  if (fetchSite && fetchSite !== "same-origin" && fetchSite !== "none") {
+    return reject(403, "Cross-site requests are not allowed.");
+  }
+
+  const origin = request.headers.get("origin");
+  if (origin != null) {
+    let originUrl: URL;
+    try {
+      originUrl = new URL(origin);
+    } catch {
+      return reject(403, "Origin is not allowed.");
+    }
+    if (originUrl.origin !== requestUrl.origin) {
+      return reject(403, "Origin is not allowed.");
+    }
+  }
+
+  const jsonMethods = options.jsonMethods ?? DEFAULT_JSON_METHODS;
+  if (!jsonMethods.some((method) => method.toUpperCase() === request.method.toUpperCase())) {
+    return { allowed: true };
+  }
+
+  const mediaType = request.headers.get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (mediaType !== "application/json") {
+    return reject(415, "Content-Type must be application/json.");
+  }
+
+  const maxJsonBodyBytes = options.maxJsonBodyBytes ?? LOCAL_JSON_BODY_LIMIT_BYTES;
+  const contentLength = readContentLength(request);
+  if (contentLength != null && (!Number.isSafeInteger(contentLength) || contentLength < 0)) {
+    return reject(400, "Invalid Content-Length header.");
+  }
+  if (contentLength != null && contentLength > maxJsonBodyBytes) {
+    return reject(413, `Request body exceeds ${maxJsonBodyBytes} bytes.`);
+  }
+
+  try {
+    if (await bodyExceedsLimit(request, maxJsonBodyBytes)) {
+      return reject(413, `Request body exceeds ${maxJsonBodyBytes} bytes.`);
+    }
+  } catch {
+    return reject(400, "Unable to read request body.");
+  }
+
+  return { allowed: true };
+}