@harrylabsj/kiwi 0.6.0

package/dist/negotiation/recovery/types.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/negotiation/recovery/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/negotiation/recovery/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/negotiation/state/phase.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { TargetScope } from "../domain/objects.js";
+/** KNP/1.0 八态（§21.1 / 基线 §18.1）。 */
+export declare const NEGOTIATION_PHASES: readonly ["OPEN", "AWAITING_CLARIFICATION", "OFFER_OPEN", "AGREEMENT_REACHED", "DECLINED", "WITHDRAWN", "CANCELLED", "EXPIRED"];
+export type NegotiationPhase = (typeof NEGOTIATION_PHASES)[number];
+/** 终态：不得重开（§17.4 / 基线 §14.4）。 */
+export declare const TERMINAL_PHASES: readonly ["AGREEMENT_REACHED", "DECLINED", "WITHDRAWN", "CANCELLED", "EXPIRED"];
+export type TerminalPhase = (typeof TERMINAL_PHASES)[number];
+/** AWAITING_CLARIFICATION 的可恢复相位（§21.2 "previous phase / restore"）。 */
+export type ResumePhase = "OPEN" | "OFFER_OPEN";
+/** Phase 事件（对齐 §21.2 转换表的事件列）。 */
+export type NegotiationPhaseEvent = {
+    type: "clarification";
+} | {
+    type: "clarification_response";
+} | {
+    type: "offer";
+    offer_id: string;
+} | {
+    type: "counter_offer";
+    offer_id: string;
+} | {
+    type: "conditional_offer";
+    offer_id: string;
+} | {
+    type: "offer_expired";
+} | {
+    type: "accept_nonbinding";
+    offer_id: string;
+} | {
+    type: "withdraw";
+    scope: TargetScope;
+} | {
+    type: "decline";
+    scope: TargetScope;
+} | {
+    type: "cancel";
+} | {
+    type: "negotiation_expired";
+};
+export interface NegotiationPhaseState {
+    negotiation_id: string;
+    phase: NegotiationPhase;
+    /** 当前 active offer（§21.2 notes：set / replaced / cleared）。 */
+    active_offer_id?: string;
+    /** AWAITING_CLARIFICATION 时保存的恢复相位（clarification_response 时还原）。 */
+    resume_phase?: ResumePhase;
+}
+export declare function isTerminalPhase(phase: NegotiationPhase): boolean;
+/** 新 negotiation 的初始状态：对应转换表首行 none → Inquiry/RFQ start → OPEN。 */
+export declare function createNegotiationPhase(negotiation_id: string): NegotiationPhaseState;
+/**
+ * 按 §21.2 转换表推进 phase。终态拒绝一切事件（不可重开）；表中不存在的
+ * 组合抛 state_conflict。返回新状态，不改动输入。
+ */
+export declare function transitionPhase(state: NegotiationPhaseState, event: NegotiationPhaseEvent): NegotiationPhaseState;

package/dist/negotiation/state/phase.js

@@ -0,0 +1,200 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * KNP/1.0 Negotiation Phase 状态机（子规范 §21，基线 §18.1）。
+ *
+ * 八态：OPEN / AWAITING_CLARIFICATION / OFFER_OPEN / AGREEMENT_REACHED /
+ * DECLINED / WITHDRAWN / CANCELLED / EXPIRED。
+ *
+ * 事件驱动转换严格对应子规范 §21.2 Core Transition Table；表中不存在的转换
+ * fail-closed 抛 state_conflict。五个终态（AGREEMENT_REACHED / DECLINED /
+ * WITHDRAWN / CANCELLED / EXPIRED）不得以同一 negotiation_id 重开（§17.4 /
+ * 基线 §14.4 Reopen）；新谈判必须新建 negotiation_id。
+ *
+ * 本机只维护 phase 维度的状态（含 AWAITING_CLARIFICATION 的恢复相位与
+ * active offer 记账）；TargetRef 一致性（§9.7）、offer 存在性等由 Ledger 负责。
+ */
+import { NegotiationValidationError } from "../domain/common.js";
+/** KNP/1.0 八态（§21.1 / 基线 §18.1）。 */
+export const NEGOTIATION_PHASES = [
+    "OPEN",
+    "AWAITING_CLARIFICATION",
+    "OFFER_OPEN",
+    "AGREEMENT_REACHED",
+    "DECLINED",
+    "WITHDRAWN",
+    "CANCELLED",
+    "EXPIRED",
+];
+/** 终态：不得重开（§17.4 / 基线 §14.4）。 */
+export const TERMINAL_PHASES = [
+    "AGREEMENT_REACHED",
+    "DECLINED",
+    "WITHDRAWN",
+    "CANCELLED",
+    "EXPIRED",
+];
+export function isTerminalPhase(phase) {
+    return TERMINAL_PHASES.includes(phase);
+}
+/** 新 negotiation 的初始状态：对应转换表首行 none → Inquiry/RFQ start → OPEN。 */
+export function createNegotiationPhase(negotiation_id) {
+    return { negotiation_id, phase: "OPEN" };
+}
+function describeEvent(event) {
+    switch (event.type) {
+        case "withdraw":
+            return `withdraw(scope=${event.scope})`;
+        case "decline":
+            return `decline(scope=${event.scope})`;
+        case "offer":
+        case "counter_offer":
+        case "conditional_offer":
+        case "accept_nonbinding":
+            return `${event.type}(${event.offer_id})`;
+        default:
+            return event.type;
+    }
+}
+function stateConflict(state, event) {
+    return new NegotiationValidationError("state_conflict", `illegal transition: ${state.phase} + ${describeEvent(event)}`, "/phase");
+}
+function applyClarification(state, event) {
+    if (state.phase === "OPEN") {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: "AWAITING_CLARIFICATION",
+            resume_phase: "OPEN",
+        };
+    }
+    if (state.phase === "OFFER_OPEN") {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: "AWAITING_CLARIFICATION",
+            resume_phase: "OFFER_OPEN",
+            active_offer_id: state.active_offer_id,
+        };
+    }
+    throw stateConflict(state, event);
+}
+function applyClarificationResponse(state, event) {
+    if (state.phase === "AWAITING_CLARIFICATION" && state.resume_phase !== undefined) {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: state.resume_phase,
+            active_offer_id: state.active_offer_id,
+        };
+    }
+    throw stateConflict(state, event);
+}
+function applyOffer(state, event) {
+    if (state.phase === "OPEN") {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: "OFFER_OPEN",
+            active_offer_id: event.offer_id,
+        };
+    }
+    throw stateConflict(state, event);
+}
+function applyOfferReplacement(state, event) {
+    if (state.phase === "OFFER_OPEN") {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: "OFFER_OPEN",
+            active_offer_id: event.offer_id,
+        };
+    }
+    throw stateConflict(state, event);
+}
+function applyOfferExpiry(state, event) {
+    if (state.phase === "OFFER_OPEN") {
+        return { negotiation_id: state.negotiation_id, phase: "OPEN" };
+    }
+    throw stateConflict(state, event);
+}
+function applyAccept(state, event) {
+    if (state.phase === "OFFER_OPEN") {
+        return {
+            negotiation_id: state.negotiation_id,
+            phase: "AGREEMENT_REACHED",
+            active_offer_id: state.active_offer_id,
+        };
+    }
+    throw stateConflict(state, event);
+}
+function applyWithdraw(state, event) {
+    if (event.scope === "offer") {
+        if (state.phase === "OFFER_OPEN") {
+            return { negotiation_id: state.negotiation_id, phase: "OPEN" };
+        }
+        throw stateConflict(state, event);
+    }
+    // scope=negotiation：OPEN/OFFER_OPEN → WITHDRAWN（terminal）。
+    if (state.phase === "OPEN" || state.phase === "OFFER_OPEN") {
+        return { negotiation_id: state.negotiation_id, phase: "WITHDRAWN" };
+    }
+    throw stateConflict(state, event);
+}
+function applyDecline(state, event) {
+    if (event.scope === "offer") {
+        if (state.phase === "OFFER_OPEN") {
+            return { negotiation_id: state.negotiation_id, phase: "OPEN" };
+        }
+        throw stateConflict(state, event);
+    }
+    // scope=negotiation：OPEN/OFFER_OPEN → DECLINED（terminal）。
+    if (state.phase === "OPEN" || state.phase === "OFFER_OPEN") {
+        return { negotiation_id: state.negotiation_id, phase: "DECLINED" };
+    }
+    throw stateConflict(state, event);
+}
+/**
+ * 按 §21.2 转换表推进 phase。终态拒绝一切事件（不可重开）；表中不存在的
+ * 组合抛 state_conflict。返回新状态，不改动输入。
+ */
+export function transitionPhase(state, event) {
+    // 终态不可重开：任何事件一律 state_conflict（§17.4 / 基线 §14.4）。
+    if (isTerminalPhase(state.phase)) {
+        throw stateConflict(state, event);
+    }
+    switch (event.type) {
+        case "clarification":
+            return applyClarification(state, event);
+        case "clarification_response":
+            return applyClarificationResponse(state, event);
+        case "offer":
+            return applyOffer(state, event);
+        case "counter_offer":
+        case "conditional_offer":
+            return applyOfferReplacement(state, event);
+        case "offer_expired":
+            return applyOfferExpiry(state, event);
+        case "accept_nonbinding":
+            return applyAccept(state, event);
+        case "withdraw":
+            return applyWithdraw(state, event);
+        case "decline":
+            return applyDecline(state, event);
+        case "cancel":
+            // 非终态（顶层守卫已保证）→ CANCELLED（terminal）。
+            return { negotiation_id: state.negotiation_id, phase: "CANCELLED" };
+        case "negotiation_expired":
+            // 非终态 → EXPIRED（terminal）。
+            return { negotiation_id: state.negotiation_id, phase: "EXPIRED" };
+    }
+}
+//# sourceMappingURL=phase.js.map

package/dist/negotiation/state/phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase.js","sourceRoot":"","sources":["../../../src/negotiation/state/phase.ts"],"names":[],"mappings":"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"}

package/dist/negotiation/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * shopping.negotiation/0.1 protocol types.
+ *
+ * These types mirror the frozen JSON schemas in
+ * contracts/shopping.negotiation/0.1/. The schemas are the source of truth;
+ * keep this file in sync with them.
+ */
+export declare const PROTOCOL_VERSION: "shopping.negotiation/0.1";
+export type Role = "buyer" | "merchant";
+export type NextActor = "buyer" | "merchant" | "none";
+export type ConversationStatus = "open" | "waiting_merchant" | "waiting_buyer" | "human_required" | "closed";
+export type DecisionAction = "ask" | "propose" | "counter" | "accept_nonbinding" | "decline" | "escalate";
+export type StockStatus = "available" | "low" | "out_of_stock" | "unknown";
+export interface StockState {
+    status: StockStatus;
+    quantity: number;
+    observed_at: string;
+    /** Negotiation never reserves inventory; always false. */
+    reserved: false;
+}
+export interface DeliveryQuote {
+    eta_start: string;
+    eta_end: string;
+    fee: number;
+}
+export interface Proposal {
+    sku: string;
+    quantity: number;
+    unit_price: number;
+    currency: string;
+    stock: StockState;
+    delivery: DeliveryQuote;
+    after_sales_policy_refs: string[];
+    /** ISO date-time after which the quote is no longer a current commitment. */
+    valid_until: string;
+}
+export interface NegotiationDecision {
+    protocol_version: typeof PROTOCOL_VERSION;
+    conversation_id: string;
+    in_reply_to_message_id: number;
+    action: DecisionAction;
+    proposal?: Proposal;
+    open_issues: string[];
+    public_message: string;
+    confidence?: number;
+    reason_codes: string[];
+    request_human_review: boolean;
+}
+export type PolicyResultKind = "accepted" | "rejected_retryable" | "human_required";
+export interface PolicyResult {
+    protocol_version: typeof PROTOCOL_VERSION;
+    result: PolicyResultKind;
+    conversation_id: string;
+    message_id?: number;
+    next_actor: NextActor;
+    reason_codes: string[];
+    public_reason: string;
+    retries_remaining: number;
+}
+export interface SnapshotSource {
+    backend: "local_marketplace" | "external_platform";
+    external_id?: string;
+    observed_at: string;
+}
+export interface SnapshotProduct {
+    sku: string;
+    title: string;
+    currency: string;
+    list_price: number;
+    description?: string;
+}
+export interface SnapshotMessage {
+    id: number;
+    sender_role: Role;
+    created_at: string;
+    action?: DecisionAction;
+    public_message: string;
+    proposal?: Proposal | null;
+}
+export interface VisiblePolicyResult {
+    result: PolicyResultKind;
+    reason_codes: string[];
+    public_reason: string;
+}
+export interface NegotiationSnapshot {
+    protocol_version: typeof PROTOCOL_VERSION;
+    conversation: {
+        id: string;
+        status: ConversationStatus;
+        next_actor: NextActor;
+    };
+    role: Role;
+    in_reply_to_message_id: number;
+    product: SnapshotProduct;
+    stock: StockState & {
+        source: SnapshotSource;
+    };
+    delivery: DeliveryQuote & {
+        notes?: string;
+    };
+    after_sales_policies: {
+        ref: string;
+        summary: string;
+    }[];
+    messages: SnapshotMessage[];
+    current_proposal: Proposal | null;
+    open_issues: string[];
+    policy_results: VisiblePolicyResult[];
+}
+export interface CapabilityFlags {
+    catalog_read: boolean;
+    inventory_read: boolean;
+    consultation_read: boolean;
+    consultation_write: boolean;
+    price_negotiate: boolean;
+    webhook: boolean;
+    /** shopping.negotiation/0.1 never creates orders; always false. */
+    orders: false;
+}
+export interface CommerceCapabilities {
+    protocol_versions: string[];
+    backend: "local_marketplace" | "external_platform";
+    capabilities: CapabilityFlags;
+}

package/dist/negotiation/types.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * shopping.negotiation/0.1 protocol types.
+ *
+ * These types mirror the frozen JSON schemas in
+ * contracts/shopping.negotiation/0.1/. The schemas are the source of truth;
+ * keep this file in sync with them.
+ */
+export const PROTOCOL_VERSION = "shopping.negotiation/0.1";
+//# sourceMappingURL=types.js.map

package/dist/negotiation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/negotiation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAAmC,CAAC"}

package/dist/net/safe-http.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 出站 HTTP 客户端共享安全原语（出站侧加固评审项统一实施）。
+ *
+ * 仓库所有出站 fetch 客户端（A2A client / Agent Card / UCP profile / catalog /
+ * shopping-cli / commerce API）统一三条纪律：
+ *
+ * 1. **redirect: "manual"**：绝不跟随 3xx——重定向目标不经过 SSRF/DNS 复查，
+ *    且重定向可能把 Authorization 头转发给第三方（resolve/ucp 此前已实施，
+ *    本模块提供统一判定 `isRedirectResponse` 供其余客户端对齐）。
+ * 2. **超时覆盖响应体读取**：AbortController 的 timer 必须活到 body 读完——
+ *    对端在响应头后停滞 body 是经典的永久挂起手法（此前 timer 在 headers
+ *    到达即 clear，body 读不在任何超时保护内）。
+ * 3. **响应体大小上限**：Content-Length 预检 + 流式读取计数，超过即中断
+ *    （防恶意对端回传 GB 级 body 打爆进程内存）。
+ *
+ * 错误全部类型化（SafeHttpError + code），调用方 catch 后映射为自己的域错误
+ * （fail-closed，不静默容错）。零新增依赖：Node 22 原生 fetch + streams。
+ */
+/** 响应体上限缺省值（8 MiB；Agent Card/UCP profile 等正常响应远小于此）。 */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+export type SafeHttpErrorCode = "redirect" | "response_too_large" | "invalid_json";
+export declare class SafeHttpError extends Error {
+    readonly code: SafeHttpErrorCode;
+    constructor(code: SafeHttpErrorCode, message: string);
+}
+/** redirect: "manual" 下 3xx / opaqueredirect 的统一拒绝判定。 */
+export declare function isRedirectResponse(response: Response): boolean;
+export interface ReadJsonBodyOptions {
+    /** 响应体上限（缺省 DEFAULT_MAX_RESPONSE_BYTES）。 */
+    maxBytes?: number;
+    /** 请求的 AbortController signal：abort 时中断挂起的 body 读（超时兜底）。 */
+    signal?: AbortSignal;
+}
+/**
+ * 流式读取响应体并解析 JSON。Content-Length 预检 + 读取计数超上限即
+ * `response_too_large`；signal abort 会 cancel 底层流（挂起的 read 被中断，
+ * 由调用方按自己的超时错误路径处理）；JSON 解析失败抛 `invalid_json`。
+ */
+export declare function readJsonBody(response: Response, options?: ReadJsonBodyOptions): Promise<unknown>;

package/dist/net/safe-http.js

@@ -0,0 +1,116 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 出站 HTTP 客户端共享安全原语（出站侧加固评审项统一实施）。
+ *
+ * 仓库所有出站 fetch 客户端（A2A client / Agent Card / UCP profile / catalog /
+ * shopping-cli / commerce API）统一三条纪律：
+ *
+ * 1. **redirect: "manual"**：绝不跟随 3xx——重定向目标不经过 SSRF/DNS 复查，
+ *    且重定向可能把 Authorization 头转发给第三方（resolve/ucp 此前已实施，
+ *    本模块提供统一判定 `isRedirectResponse` 供其余客户端对齐）。
+ * 2. **超时覆盖响应体读取**：AbortController 的 timer 必须活到 body 读完——
+ *    对端在响应头后停滞 body 是经典的永久挂起手法（此前 timer 在 headers
+ *    到达即 clear，body 读不在任何超时保护内）。
+ * 3. **响应体大小上限**：Content-Length 预检 + 流式读取计数，超过即中断
+ *    （防恶意对端回传 GB 级 body 打爆进程内存）。
+ *
+ * 错误全部类型化（SafeHttpError + code），调用方 catch 后映射为自己的域错误
+ * （fail-closed，不静默容错）。零新增依赖：Node 22 原生 fetch + streams。
+ */
+/** 响应体上限缺省值（8 MiB；Agent Card/UCP profile 等正常响应远小于此）。 */
+export const DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export class SafeHttpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SafeHttpError";
+        this.code = code;
+    }
+}
+/** redirect: "manual" 下 3xx / opaqueredirect 的统一拒绝判定。 */
+export function isRedirectResponse(response) {
+    return (response.redirected ||
+        response.type === "opaqueredirect" ||
+        (response.status >= 300 && response.status < 400));
+}
+/**
+ * 流式读取响应体并解析 JSON。Content-Length 预检 + 读取计数超上限即
+ * `response_too_large`；signal abort 会 cancel 底层流（挂起的 read 被中断，
+ * 由调用方按自己的超时错误路径处理）；JSON 解析失败抛 `invalid_json`。
+ */
+export async function readJsonBody(response, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const signal = options.signal;
+    // Content-Length 预检：声明长度超限直接拒绝，不开始读（快失败）。
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null) {
+        const declared = Number(contentLength);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            throw new SafeHttpError("response_too_large", `response content-length ${declared} exceeds limit ${maxBytes}`);
+        }
+    }
+    if (response.body === null) {
+        throw new SafeHttpError("invalid_json", "response has no body");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    // signal abort → cancel 底层流：挂起的 reader.read() 被中断（否则慢 body
+    // 会永远挂住——timer 只 abort fetch 头阶段，读阶段必须手动取消）。
+    const onAbort = () => {
+        void reader.cancel().catch(() => { });
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                void reader.cancel().catch(() => { });
+                throw new SafeHttpError("response_too_large", `response body exceeds limit ${maxBytes} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+    }
+    const text = new TextDecoder().decode(concatChunks(chunks));
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SafeHttpError("invalid_json", "response body is not valid JSON");
+    }
+}
+function concatChunks(chunks) {
+    if (chunks.length === 0)
+        return new Uint8Array(0);
+    if (chunks.length === 1)
+        return chunks[0] ?? new Uint8Array(0);
+    const total = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+//# sourceMappingURL=safe-http.js.map

package/dist/net/safe-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-http.js","sourceRoot":"","sources":["../../src/net/safe-http.ts"],"names":[],"mappings":"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"}