berry-agent 0.1.0-alpha.1

package/dist/tools/worktree.js

@@ -0,0 +1,327 @@
+/**
+ * worktree 工具族（04 §7 worktree 条——fs 族扩展，批 16）。
+ *
+ * 三动词封闭面（路径由工具派生、非模型任意指定——封闭动词面则）：
+ * - create：`git worktree add -b <name> <派生路径> [baseRef]`——名字即分支名
+ *   即目录段（三用同源），撞名（既存 worktree 目录 / 既存分支）拒
+ *   `FS_WORKTREE_EXISTS`；
+ * - list：`git worktree list --porcelain` 枚举（只读、不登记观察态——ls 同判）；
+ * - clean：`git worktree remove`——遇未提交变更拒 `FS_WORKTREE_DIRTY`（防误清，
+ *   宁拒勿删），`force: true` 显式覆盖；**不删分支**（留史——交付物引用）。
+ *
+ * 派生路径形：仓同级 `<repo 目录名>-worktrees/<name>`（worktree 不落仓内——
+ * 避免被仓自身遍历/快照误纳）。
+ *
+ * 树级写互斥（04 §7 补钉③）：create/clean 以 worktree 根 canonical 路径入
+ * 写串行链（serializeTreeWrites）——树操作在飞时其域内文件写（serializeWrites）
+ * 排队其后，防 clean 拆掉他方正在写的根；两向握手见 fs.ts。
+ *
+ * 会话可写根授予（04 §7 补钉①）：create 成功即自动将产物 canonical 路径记入
+ * 该会话的授予集（fence 组合归装配——writableRoots provider 并入
+ * grantedRoots(sessionId)；数据目录 carve-out 在 safety 面恒优先，本件不管
+ * fence 执法只记账）；releaseSession 随会话关闭 / Job 终态回收。
+ *
+ * git 元数据白名单（04 §8 桥条款——冷读挂账 #4 词面单源锚）：本件自身的 git
+ * 调用是「工具内置受控路径」（封闭动词面则——不在 carve-out 拦截面）；
+ * `GIT_METADATA_COMMANDS` 是经 bash 的 git 命令族受控放行的闭集动词表词汇
+ * 源（执法位 = exec bash 拦截面，随该面落码批接线——先有词后有法）。
+ */
+import { execFile as execFileCallback } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { Type } from 'typebox';
+import { BaseError } from '../contracts/index.js';
+import { canonicalize, serializeTreeWrites } from './fs.js';
+const execFile = promisify(execFileCallback);
+/**
+ * git 元数据命令闭集动词表（04 §8 carve-out 桥条款白名单形——词面单源锚）。
+ * 经 bash 执行的 git 命令族元数据操作（写 `.git/objects`、`.git/refs`——
+ * worktree 形态下含 `.git/worktrees/<name>/`）受控放行的动词全集；非本表
+ * 动词（如 `fast-import`/`update-ref` 直改版本史字节）不在放行面。
+ * 执法位 = exec bash 拦截面（该面落码批接线——本常量先锚词汇）。
+ */
+export const GIT_METADATA_COMMANDS = [
+    'add',
+    'commit',
+    'branch',
+    'checkout',
+    'switch',
+    'merge',
+    'rebase',
+    'stash',
+    'tag',
+    'push',
+    'pull',
+    'fetch',
+    'status',
+    'log',
+    'diff',
+    'show',
+    'config',
+    'worktree',
+];
+/** worktree 名字词法（名即分支名即目录段三用同源——禁分隔符，首字符字母数字） */
+const WORKTREE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** 单 git 命令超时毫秒（缺省） */
+const GIT_TIMEOUT_MS = 30_000;
+/** git 输出缓冲上限字节（diff 可大——16 MiB 帽） */
+const GIT_MAX_BUFFER = 16 * 1024 * 1024;
+/** 名字词法校验（坏形 = 参数面问题——TOOL_INVALID_ARGS 语义域） */
+function assertNameValid(name) {
+    if (!WORKTREE_NAME_RE.test(name)) {
+        throw new BaseError('TOOL_INVALID_ARGS', `[TOOL_INVALID_ARGS] worktree 名字坏形：${name}（词法 ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$——名即分支名即目录段，禁分隔符）`);
+    }
+}
+/**
+ * 组 worktree 服务。git 经 execFile 直调（node: 内建全局放行域——零外部
+ * 二进制依赖）；全部 git 调用 cwd 锚主仓根。服务实例持会话授予表——同一
+ * 仓应共享单实例（授予集与树级互斥链同源）。
+ */
+export function createWorktreeService(opts) {
+    const repoRoot = opts.repoRoot;
+    const git = opts.gitCommand ?? 'git';
+    const timeoutMs = opts.timeoutMs ?? GIT_TIMEOUT_MS;
+    // 会话 → 授予路径集（canonical 形；fence 组合装配面读 grantedRoots 并入）
+    const grants = new Map();
+    /** 执行 git（cwd 锚主仓；非零退出折带 stderr 的 Error——语义码由调用方判形折码） */
+    const runGit = async (args) => {
+        try {
+            const { stdout } = await execFile(git, args, { cwd: repoRoot, timeout: timeoutMs, maxBuffer: GIT_MAX_BUFFER });
+            return stdout;
+        }
+        catch (err) {
+            const e = err;
+            const detail = (e.stderr ?? e.message ?? String(err)).trim();
+            if (e.killed === true) {
+                throw new Error(`[git ${args[0]}] 超时（${timeoutMs}ms）：${detail.slice(0, 500)}`);
+            }
+            throw new Error(`[git ${args.join(' ')}] ${detail.slice(0, 500)}`);
+        }
+    };
+    /** 派生 worktree 路径：仓同级 `<repo 目录名>-worktrees/<name>`（工具派生非模型指定） */
+    const derivedPath = (name) => join(dirname(repoRoot), `${basename(repoRoot)}-worktrees`, name);
+    /** 分支在场判定（git branch --list 前缀匹配——须整行精确比对） */
+    const branchExists = async (name) => {
+        const out = await runGit(['branch', '--list', name]);
+        return out
+            .split('\n')
+            .map((l) => l
+            .trim()
+            .replace(/^\*\s+/, '')
+            .replace(/\s+$/, ''))
+            .some((l) => l === name);
+    };
+    return {
+        async create(req) {
+            assertNameValid(req.name);
+            const path = derivedPath(req.name);
+            // 撞名两查：目录在场（前次 create 产物或同名异物）/ 分支在场
+            if (existsSync(path)) {
+                throw new BaseError('FS_WORKTREE_EXISTS', `[FS_WORKTREE_EXISTS] worktree 已存在：${req.name}（路径 ${path} 在场）`);
+            }
+            if (await branchExists(req.name)) {
+                throw new BaseError('FS_WORKTREE_EXISTS', `[FS_WORKTREE_EXISTS] 分支已存在：${req.name}（名字即分支名——分支与 worktree 同名域撞名）`);
+            }
+            // 树级入链（占位键取派生路径的最近在场祖先 canonical——建后路径才在场）
+            await serializeTreeWrites(await canonicalize(path), async () => {
+                try {
+                    await runGit(req.baseRef === undefined
+                        ? ['worktree', 'add', '-b', req.name, path]
+                        : ['worktree', 'add', '-b', req.name, path, req.baseRef]);
+                }
+                catch (err) {
+                    // 链内竞速撞名（并发 create 同名）折语义码；其余 git 失败原样上抛
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (msg.includes('already exists') || msg.includes('already checked out')) {
+                        throw new BaseError('FS_WORKTREE_EXISTS', `[FS_WORKTREE_EXISTS] worktree/分支已存在：${req.name}（并发创建竞速）`);
+                    }
+                    throw err;
+                }
+            });
+            // 建成后路径在场——canonical 全程解析（授予集记 canonical 形，与 fence 比对同基）
+            const canonical = await canonicalize(path);
+            if (req.sessionId !== undefined) {
+                let set = grants.get(req.sessionId);
+                if (set === undefined) {
+                    set = new Set();
+                    grants.set(req.sessionId, set);
+                }
+                set.add(canonical);
+            }
+            return { name: req.name, path: canonical, branch: req.name };
+        },
+        async list() {
+            const out = await runGit(['worktree', 'list', '--porcelain']);
+            const entries = [];
+            let current = {};
+            for (const line of out.split('\n')) {
+                if (line === '') {
+                    // 块尾——落项（worktree 行必有才有块）
+                    if (current.path !== undefined) {
+                        entries.push({
+                            name: basename(current.path),
+                            path: current.path,
+                            branch: current.branch ?? '',
+                        });
+                    }
+                    current = {};
+                    continue;
+                }
+                const space = line.indexOf(' ');
+                const key = space === -1 ? line : line.slice(0, space);
+                const value = space === -1 ? '' : line.slice(space + 1);
+                if (key === 'worktree')
+                    current.path = value;
+                else if (key === 'branch')
+                    current.branch = value.replace(/^refs\/heads\//, '');
+                // HEAD/bare/detached/locked/prunable 行不进枚举面
+            }
+            if (current.path !== undefined) {
+                entries.push({ name: basename(current.path), path: current.path, branch: current.branch ?? '' });
+            }
+            return entries;
+        },
+        async clean(req) {
+            assertNameValid(req.name);
+            const path = derivedPath(req.name);
+            // 在册判定（缺席 = 目标不存在——FS_NOT_FOUND 同 read/ls 语义域）。
+            // 比对基 = canonical 双侧：git 记录 realpath（macOS /var → /private/var
+            // 符号链形下与派生串不同形——字符串直比必假阴）
+            const targetCanonical = await canonicalize(path);
+            const entries = await this.list();
+            let inList = false;
+            for (const e of entries) {
+                if ((await canonicalize(e.path)) === targetCanonical) {
+                    inList = true;
+                    break;
+                }
+            }
+            if (!inList) {
+                throw new BaseError('FS_NOT_FOUND', `[FS_NOT_FOUND] worktree 不存在：${req.name}（路径 ${path}）`);
+            }
+            const dirtyLines = async () => {
+                const status = await runGit(['-C', path, 'status', '--porcelain']);
+                return status
+                    .split('\n')
+                    .map((l) => l.trim())
+                    .filter((l) => l !== '');
+            };
+            await serializeTreeWrites(await canonicalize(path), async () => {
+                // 未提交变更两查（force 显式覆盖）：链外先查给出可读拒因；链内复验——
+                // 链上写者已排空，窗口收敛到链外写者（bash 重定向等——诚实边界）
+                if (req.force !== true) {
+                    const lines = await dirtyLines();
+                    if (lines.length > 0) {
+                        throw new BaseError('FS_WORKTREE_DIRTY', `[FS_WORKTREE_DIRTY] worktree 有未提交变更拒拆除：${req.name}（${lines.length} 处，如：${lines
+                            .slice(0, 3)
+                            .join('；')}）——提交后重试或显式 force`);
+                    }
+                }
+                try {
+                    await runGit(req.force === true ? ['worktree', 'remove', '--force', path] : ['worktree', 'remove', path]);
+                }
+                catch (err) {
+                    // git 自身拒拆（本仓两查后的链外写者窗口）折同码——不裸抛
+                    const msg = err instanceof Error ? err.message : String(err);
+                    if (msg.includes('dirty')) {
+                        throw new BaseError('FS_WORKTREE_DIRTY', `[FS_WORKTREE_DIRTY] git 拒拆（未提交变更）：${req.name}——提交后重试或显式 force`);
+                    }
+                    throw err;
+                }
+            });
+            // 分支留史不删（交付物引用——04 §7 落码定形）
+            return { name: req.name, path };
+        },
+        async diffPatch(req) {
+            assertNameValid(req.name);
+            const path = derivedPath(req.name);
+            return runGit(['-C', path, 'diff', `${req.baseRef}...HEAD`]);
+        },
+        async grant(req) {
+            // canonical 化后记入（与 fence 比对同基；幂等——Set 语义）
+            const canonical = await canonicalize(req.path);
+            let set = grants.get(req.sessionId);
+            if (set === undefined) {
+                set = new Set();
+                grants.set(req.sessionId, set);
+            }
+            set.add(canonical);
+        },
+        grantedRoots(sessionId) {
+            return [...(grants.get(sessionId) ?? [])];
+        },
+        releaseSession(sessionId) {
+            const released = [...(grants.get(sessionId) ?? [])];
+            grants.delete(sessionId);
+            return released;
+        },
+    };
+}
+/**
+ * 组 worktree 三工具（04 §7 worktree 条词面定名：worktree_create/list/clean）。
+ * sessionId 取 toolCtx（会话内模型调用形态——授予自动记该会话）；件侧编排
+ * 直接调 service（同样携 owner 会话 id）。effect：create/clean = write（过
+ * 审批对），list 只读。
+ */
+export function createWorktreeTools(service) {
+    return [
+        {
+            name: 'worktree_create',
+            effect: 'write',
+            description: '在当前仓旁建独立 git worktree + 同名新分支（名字即分支名）。产物路径由工具派生（仓同级 <仓目录名>-worktrees/<名字>），建成功即自动加入本会话可写根（后续 fs 写/bash 以该 worktree 为锚）。适合并行开一条独立工作线（如同时改两个特性互不踩踏）。',
+            parameters: Type.Object({
+                name: Type.String({ description: 'worktree 名（= 新分支名；字母数字开头，可含 ._-,禁斜杠,≤64 字符）' }),
+                baseRef: Type.Optional(Type.String({ description: '基线提交/分支（缺省 HEAD）' })),
+            }),
+            execute: async (args, toolCtx) => {
+                const created = await service.create({
+                    name: args.name,
+                    baseRef: args.baseRef,
+                    sessionId: toolCtx.sessionId,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `worktree 已建：${created.name}\n路径：${created.path}\n分支：${created.branch}（此后在本会话内该路径可写）`,
+                        },
+                    ],
+                    details: { name: created.name, path: created.path, branch: created.branch },
+                };
+            },
+        },
+        {
+            name: 'worktree_list',
+            effect: 'read',
+            description: '枚举当前仓全部 git worktree（含主仓——路径/分支/名），只读。',
+            parameters: Type.Object({}),
+            execute: async () => {
+                const entries = await service.list();
+                const lines = entries.map((e) => `${e.name}\t分支 ${e.branch || '(detached)'}\t${e.path}`);
+                return {
+                    content: [{ type: 'text', text: lines.length > 0 ? lines.join('\n') : '（无 worktree）' }],
+                    details: { count: entries.length },
+                };
+            },
+        },
+        {
+            name: 'worktree_clean',
+            effect: 'write',
+            description: '拆除指定 worktree（目录与 git 登记一并移除；分支保留不删——交付物引用）。有未提交变更时拒绝（FS_WORKTREE_DIRTY）——先提交，或显式传 force=true 强拆（变更将丢失）。',
+            parameters: Type.Object({
+                name: Type.String({ description: 'worktree 名（create 时的名字）' }),
+                force: Type.Optional(Type.Boolean({ description: '强拆（丢弃未提交变更——破坏性动作）' })),
+            }),
+            execute: async (args) => {
+                const removed = await service.clean({ name: args.name, force: args.force === true });
+                return {
+                    content: [
+                        { type: 'text', text: `worktree 已拆除：${removed.name}（${removed.path}）——同名分支保留` },
+                    ],
+                    details: { name: removed.name, path: removed.path },
+                };
+            },
+        },
+    ];
+}

package/dist/web/codes.js

@@ -0,0 +1,37 @@
+/**
+ * web 域错误码注册（02 §4.1 席 18 / 07 §1.1 core:web 行——SSRF 五卫生件拦截码族）。
+ *
+ * 前缀族明列见 contracts/errors.ts ERROR_CODE_PREFIXES（02 §5.3 #1——WEB_ 族
+ * 前缀已注册，具体码名规范未逐一定名，本批落码定名〔07 §1.1 core:web 行
+ * 「原样」指席职能〕）；03 §10.3 browser 件章 L694 安全卫生条指认「拦截码
+ * 复用 WEB_ 族不自造」——browser 导航拦截消费本族。注册纪律：写入点文件
+ * 必须实际 import 本文件注册才发生（与 safety/tools 的 codes.ts 同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'WEB_URL_INVALID',
+        module: 'web',
+        description: '入口 URL 不可解析（new URL 红或空串）——SSRF 卫生件段 0 拒',
+    },
+    {
+        code: 'WEB_PROTOCOL_REJECTED',
+        module: 'web',
+        description: '协议白名单外拒——仅 http/https（03 §10.3 browser 件章协议白名单同源；file/ftp/javascript 等一律拒）',
+    },
+    {
+        code: 'WEB_PRIVATE_ADDRESS',
+        module: 'web',
+        description: '私网/环回/链路本地/未指定地址拒（SSRF 红线）——字面 IP 段与 DNS 解析结果双查（重定向每跳重查）',
+    },
+    {
+        code: 'WEB_REDIRECT_LIMIT',
+        module: 'web',
+        description: '重定向跟随跳数触帽拒（缺省 5 跳）——每跳目标经同一卫生单源复检',
+    },
+    {
+        code: 'WEB_RATE_LIMITED',
+        module: 'web',
+        description: '在飞门满拒（缺省并发 4）——fetch 与 browser 导航共享同一门实例（03 §10.3「同一在飞门第三消费位」）；可重试档',
+    },
+]);

package/dist/web/gate.js

@@ -0,0 +1,43 @@
+/**
+ * 在飞门（限流卫生件——07 §1.1 core:web 行「限流」；03 §10.3 browser 件章
+ * 「导航限流与 fetch 共享同一在飞门实例」）。
+ *
+ * 形态：并发计数 + 满即拒（fail-fast 不排队——排队会在卫生件内积压 Promise，
+ * 与超时预算相互作用产生迟到风暴；拒是可重试档，调用方自决退避）。实例经
+ * 装配根共享给 browser 导航（第三消费位）——门身份即共享点，非全局单例。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 在飞门构造（容量 ≤0 视为 1——保守钳制，配置坏形不放大并发面） */
+export function createInFlightGate(capacity) {
+    const effective = Math.max(1, Math.floor(capacity));
+    let inFlight = 0;
+    return {
+        get inFlight() {
+            return inFlight;
+        },
+        get capacity() {
+            return effective;
+        },
+        acquire() {
+            if (inFlight >= effective) {
+                throw new BaseError('WEB_RATE_LIMITED', `在飞门满（并发 ${inFlight}/${effective}）——稍后重试或降低并发`);
+            }
+            inFlight += 1;
+        },
+        release() {
+            // 配对义务面：release 多于 acquire 不负计数（防御调用方 bug，不 fail-loud
+            // ——放门在 finally 路径，抛错会吞业务异常）
+            if (inFlight > 0)
+                inFlight -= 1;
+        },
+        async run(task) {
+            this.acquire();
+            try {
+                return await task();
+            }
+            finally {
+                this.release();
+            }
+        },
+    };
+}

package/dist/web/hygiene.js

@@ -0,0 +1,195 @@
+/**
+ * SSRF 卫生件纯函数（07 §1.1 core:web 行五卫生件之「私网拒绝」+ 协议白名单；
+ * 03 §10.3 browser 件章安全卫生条：navigate 入口 URL 经本单源复用——拦截码
+ * 复用 WEB_ 族不自造）。
+ *
+ * 判定序（execute 内编排序，本件只供原子判定）：
+ *   URL 解析（WEB_URL_INVALID）→ 协议白名单 http/https（WEB_PROTOCOL_REJECTED）
+ *   → 主机私网判定（字面 IP 段查 + DNS 解析结果查——WEB_PRIVATE_ADDRESS）
+ * 重定向每跳目标重跑同一判定序。
+ *
+ * 已知边界（v1 注记）：DNS 校验与实际连接之间存在解析漂移窗（rebinding 全防
+ * 需自定义连接级 lookup/undici dispatcher）——本件落「请求前解析全查」档，
+ * 连接级钉死挂账后续批。
+ */
+import { lookup } from 'node:dns/promises';
+import { BaseError } from '../contracts/index.js';
+/** 协议白名单（http(s) 两形——03 §10.3 browser 件章同源） */
+export const WEB_PROTOCOLS = new Set(['http:', 'https:']);
+/** 缺省 DNS 解析器：node:dns/promises lookup 全地址族（生产位；测试注入桩） */
+export const defaultDnsResolver = async (hostname) => {
+    const results = await lookup(hostname, { all: true });
+    return results.map((result) => result.address);
+};
+/**
+ * 入口 URL 解析 + 协议白名单（卫生件段 0/1）。
+ * @param raw 原始 URL 串
+ * @returns 解析后的 URL 对象（原样——不做补全/改写；无协议裸主机形属调用方
+ *   语义决定，本件保守拒——补全 https:// 的宽容归工具面参数预处理，不进卫生件）
+ * @throws WEB_URL_INVALID 不可解析；WEB_PROTOCOL_REJECTED 白名单外协议
+ */
+export function parseWebUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new BaseError('WEB_URL_INVALID', `URL 不可解析：${raw}`);
+    }
+    if (!WEB_PROTOCOLS.has(url.protocol)) {
+        throw new BaseError('WEB_PROTOCOL_REJECTED', `协议 ${url.protocol} 不在白名单（仅 http/https）：${raw}`);
+    }
+    return url;
+}
+/**
+ * IPv4 私网/保留段判定（点分十进制已拆四段）。
+ * 覆盖：环回 127/8、未指定 0/8、私网三段 10/8 + 172.16/12 + 192.168/16、
+ * 链路本地 169.254/16、CGNAT 100.64/10、组播 224/4、保留 240/4。
+ */
+function isPrivateIPv4(octets) {
+    // 解构带缺省窄化索引访问（noUncheckedIndexedAccess）；缺省 -1 不落任何段
+    const [a = -1, b = -1] = octets;
+    return (a === 127 || // 环回
+        a === 0 || // 未指定
+        a === 10 || // 私网 A
+        (a === 172 && b >= 16 && b <= 31) || // 私网 B
+        (a === 192 && b === 168) || // 私网 C
+        (a === 169 && b === 254) || // 链路本地
+        (a === 100 && b >= 64 && b <= 127) || // CGNAT
+        a >= 224 // 组播 + 保留（224-255）
+    );
+}
+/**
+ * IPv6 私网/保留段判定（入参 = expandIPv6 产出的 8 组 4 位补零十六进制）。
+ * 覆盖：未指定 ::、环回 ::1、唯一本地 fc00::/7、链路本地 fe80::/10、
+ * v4 映射 ::ffff:0:0/96 与 v4 兼容 ::/96（尾 32 位还原 v4 递归查）、
+ * v4 翻译 64:ff9b::/96（同递归）。
+ */
+function isPrivateIPv6(groups) {
+    // 显式索引取位（?? 收窄 noUncheckedIndexedAccess）——解构按位置赋值，
+    // 命名跳位不等于索引跳位（首版 const [g0,g5,g6,g7] 实取 groups[0..3]，
+    // v4 映射/兼容段误判——回归锁：::ffff:8.8.8.8 → false）
+    const g0 = groups[0] ?? '';
+    const g5 = groups[5] ?? '';
+    const g6 = groups[6] ?? '0000';
+    const g7 = groups[7] ?? '0000';
+    // 未指定 ::（全零）
+    if (groups.every((group) => group === '0000'))
+        return true;
+    // 环回 ::1（前七组零 + 尾组 1）
+    if (groups.slice(0, 7).every((group) => group === '0000') && groups[7] === '0001')
+        return true;
+    // 唯一本地 fc00::/7（fc/fd 前缀）
+    if (g0.startsWith('fc') || g0.startsWith('fd'))
+        return true;
+    // 链路本地 fe80::/10（fe80–febf：第三位十六进制 8-b）
+    if (g0.startsWith('fe') && ['8', '9', 'a', 'b'].includes(g0[2] ?? ''))
+        return true;
+    // 尾 32 位还原 v4 四段（g6 高 16 位 / g7 低 16 位）
+    const decodeV4Tail = () => {
+        const high = Number.parseInt(g6, 16);
+        const low = Number.parseInt(g7, 16);
+        return [(high >> 8) & 0xff, high & 0xff, (low >> 8) & 0xff, low & 0xff];
+    };
+    // v4 映射 ::ffff:0:0/96（前 5 组零 + 第 6 组 ffff）与 v4 兼容 ::/96（前 6 组零）
+    if (groups.slice(0, 5).every((group) => group === '0000') && (g5 === 'ffff' || g5 === '0000')) {
+        return isPrivateIPv4(decodeV4Tail());
+    }
+    // v4 翻译 64:ff9b::/96（0064:ff9b 前缀 + 第 3-6 组零）
+    if (g0 === '0064' && groups[1] === 'ff9b' && groups.slice(2, 6).every((group) => group === '0000')) {
+        return isPrivateIPv4(decodeV4Tail());
+    }
+    return false;
+}
+/**
+ * 主机名私网判定（字面腿——不做 DNS）：字面 IP（v4/v6 含 [ ] 包裹形）与
+ * localhost 族（RFC 6761——*.localhost 恒解析环回）。
+ * @returns true = 私网/保留（拒）；false = 字面面非私网或非字面形（交 DNS 腿）
+ */
+export function isPrivateHostLiteral(hostname) {
+    const host = hostname.toLowerCase();
+    // IPv6 包裹形 [::1]
+    const bare = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+    // v4 字面：四段点分全数字
+    const v4Match = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4Match) {
+        const octets = v4Match.slice(1).map(Number);
+        if (octets.every((octet) => octet >= 0 && octet <= 255)) {
+            return isPrivateIPv4(octets);
+        }
+    }
+    // IPv6 字面（含 %zone 尾——链路本地常用 zone 形，直接拒）
+    if (bare.includes(':')) {
+        const zoneless = bare.split('%')[0] ?? bare;
+        const expanded = expandIPv6(zoneless);
+        if (expanded)
+            return isPrivateIPv6(expanded);
+    }
+    // localhost 族：裸 localhost 与 *.localhost（点尾任意）
+    if (host === 'localhost' || host.endsWith('.localhost'))
+        return true;
+    return false;
+}
+/**
+ * IPv6 展开辅助：把压缩形（::）展开为 8 组 4 位十六进制前 2 位小写数组；
+ * 非 8 组形（内嵌 v4 等）返回 null 交调用方原样处理。
+ * 返回形：每组保留完整 4 位十六进制（比较用）。
+ */
+function expandIPv6(input) {
+    // 内嵌 v4 尾（如 ::ffff:192.168.0.1）先转两组十六进制
+    let text = input;
+    const v4Tail = text.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
+    if (v4Tail) {
+        const [a = -1, b = -1, c = -1, d = -1] = (v4Tail[2] ?? '').split('.').map(Number);
+        if ([a, b, c, d].some((octet) => octet < 0 || octet > 255))
+            return null;
+        const high = ((a << 8) | b).toString(16);
+        const low = ((c << 8) | d).toString(16);
+        text = `${v4Tail[1] ?? ''}${high}:${low}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return null; // 双 :: 非法
+    const parseGroups = (part) => (part === '' ? [] : part.split(':'));
+    const head = parseGroups(halves[0] ?? '');
+    const tail = halves.length === 2 ? parseGroups(halves[1] ?? '') : [];
+    if (halves.length === 1 && head.length !== 8)
+        return null;
+    if (halves.length === 2 && head.length + tail.length > 7)
+        return null;
+    const fill = 8 - head.length - tail.length;
+    const groups = [...head, ...Array.from({ length: halves.length === 2 ? fill : 0 }, () => '0'), ...tail];
+    if (groups.length !== 8)
+        return null;
+    if (groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group)))
+        return null;
+    return groups.map((group) => group.padStart(4, '0'));
+}
+/**
+ * 主机私网判定全腿（字面 + DNS）：字面腿命中即拒；非字面主机名经解析器
+ * 全地址查——任一解析结果落私网段即拒（DNS rebinding 首跳防御档）。
+ * @throws WEB_PRIVATE_ADDRESS 私网/保留段命中
+ * @throws 原样上抛解析失败（非卫生拦截——网络不可达属普通失败，不携 WEB_ 码）
+ */
+export async function assertPublicHost(url, resolveDns) {
+    const hostname = url.hostname.replace(/^\[|\]$/g, ''); // URL 已剥 []，防御双保险
+    if (isPrivateHostLiteral(hostname)) {
+        throw new BaseError('WEB_PRIVATE_ADDRESS', `目标主机属私网/保留段（SSRF 红线拒）：${hostname}`);
+    }
+    const addresses = await resolveDns(hostname);
+    const hit = addresses.find((address) => {
+        const bare = address.split('%')[0] ?? address;
+        if (bare.includes(':')) {
+            const expanded = expandIPv6(bare);
+            return expanded ? isPrivateIPv6(expanded) : false;
+        }
+        const v4Match = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+        if (!v4Match)
+            return false;
+        const octets = v4Match.slice(1).map(Number);
+        return octets.every((octet) => octet >= 0 && octet <= 255) && isPrivateIPv4(octets);
+    });
+    if (hit) {
+        throw new BaseError('WEB_PRIVATE_ADDRESS', `目标主机解析命中私网/保留段地址（SSRF 红线拒）：${hostname} → ${hit}`);
+    }
+}

package/dist/web/index.js

@@ -0,0 +1,16 @@
+/**
+ * web 模块公开面（L3 core: 官方插件 15 之 #6——02 §4.1 席 18 / 07 §1.1
+ * core:web 行：fetch 工具 + ctx.fetch 服务 + SSRF 五卫生件〔两消费面同一
+ * execute〕）。
+ *
+ * 本批（14c）纯逻辑腿：卫生件纯函数 + 在飞门 + 服务（唯一 execute 编排）+
+ * fetch 工具定义。装载态集成（core:web 官方引用形 apply——注册工具 + provide
+ * ctx.fetch 服务 + 归因 sink 接 durable 落账面 + 与 browser 共享同一在飞门
+ * 实例）归批 12 装载面后装配批（03 §1.4 官方引用形；批序档装载面前置律）。
+ */
+import './codes.js';
+export { createInFlightGate } from './gate.js';
+export { WEB_PROTOCOLS, defaultDnsResolver, parseWebUrl, isPrivateHostLiteral, assertPublicHost } from './hygiene.js';
+export { createSsrfGuardedFetch } from './ssrf-guard.js';
+export { createWebFetchService, DEFAULT_WEB_LIMITS } from './service.js';
+export { createFetchTool } from './tool.js';