@harrylabsj/kiwi 0.6.0

package/dist/discovery/resolve.d.ts

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+/**
+ * AgentDiscovery.resolve —— §33 AgentDiscovery 职责落地。
+ *
+ * 输入 domain 或 Agent Card URL：
+ *
+ *   domain        → 双发现入口（基线 §25 / §33，WP3）：
+ *                     1. 先试 UCP 标准入口 `/.well-known/ucp`；
+ *                        解析成功且校验后 profile 含 a2a transport → 用其
+ *                        endpoint（Agent Card URL）继续；
+ *                     2. UCP 失败（解析/校验/无 a2a transport）→ 回退直接试
+ *                        `https://<domain>/.well-known/agent-card.json`。
+ *                     两个都是标准发现入口，权限等价，因此 UCP → Agent Card
+ *                     的回退不违反不变量 21 —— 不变量 21 约束的是通道候选的
+ *                     一次性选择，不是发现入口本身。
+ *   agentCardUrl  → 直接拉取 Agent Card（不走 UCP）。
+ *
+ * 处理链：
+ *   fetch → parseAgentCard（结构校验 + secret 扫描，不变量 24）→
+ *   capability intersection（§3.1 / §33）→ identity bootstrap → channel candidates。
+ *   UCP 优先路径成功时，UCP capability intersection（§3.2，与 A2A binding
+ *   intersection 两个维度并存）与解析出的 profile 一并放入 CounterpartyProfile。
+ *
+ * 通道候选按优先序（§33）：A2A 可用 → a2a-direct；否则若配置了 hosted →
+ * shopping-cli-hosted；否则若配置了 platform → platform-api；都没有 → fail-closed
+ * （抛 DiscoveryError）。候选选择本身是一次性确定性决策（selectChannelCandidate），
+ * 后续失败绝不自动降级到权限更宽的通道（不变量 21）。
+ *
+ * 全部失败路径抛 DiscoveryError（fail-closed，§4.6）。
+ *
+ * v2.3（设计 §21 / MVP Slice A/B）：DiscoveryDeps.catalog 可选配置后启用
+ * resolveViaCatalog —— 通过 shopping-cli Commerce Agent Catalog 发现候选并升级为
+ * CounterpartyProfile。catalog 候选不是已证明的在线身份（契约 §1），升级路径
+ * 必须走 resolve() 做 fresh verification，不直接信任候选元数据。
+ */
+import { type AgentInterface } from "./agent-card/index.js";
+import type { UcpResolverOptions } from "./ucp/resolver.js";
+import type { UcpProfile } from "./ucp/types.js";
+import type { CandidateAgent, CatalogSearchQuery, CatalogSource } from "./catalog-source/index.js";
+import type { CounterpartyProfile } from "../counterparty/channel.js";
+export interface DiscoveryInput {
+    /** 对端域名（不含 scheme）；从 well-known Agent Card 解析。 */
+    domain?: string;
+    /** 直接给 Agent Card URL。 */
+    agentCardUrl?: string;
+}
+/** UCP 优先发现配置（WP3，可选）。 */
+export interface UcpDiscoveryDeps {
+    /** 禁用 UCP 优先发现（domain 输入），保持 v0.5 直接 well-known Agent Card。 */
+    disabled?: boolean;
+    /** Kiwi 平台侧 UCP profile（capability intersection 的 platform 侧）。 */
+    localProfile?: UcpProfile;
+    /** UcpResolver 构造选项（fetchImpl 缺省复用 discovery.fetchImpl）。 */
+    resolver?: UcpResolverOptions;
+}
+/**
+ * Commerce Agent Catalog 集成（v2.3 / 设计 §21、MVP Slice A/B）。
+ * 提供 catalog source 后，AgentDiscovery 可通过 resolveViaCatalog 把候选升级为
+ * CounterpartyProfile。Catalog 返回的是 candidate，不是已证明的在线身份（契约 §1）；
+ * 升级路径必须走 resolve() 做 fresh verification。
+ */
+export interface CatalogDiscoveryDeps {
+    /** CatalogSource 接口：ShoppingCliCatalogSource（legacy）或 KiwiCatalogSource（/v1/agents）。 */
+    source: CatalogSource;
+    /** 缺省搜索查询；resolveViaCatalog 未显式传 query 时使用。 */
+    query?: CatalogSearchQuery;
+    /**
+     * 显式放宽 verification.status 过滤（设计 §8.2：Kiwi SHOULD 按 TrustPolicy
+     * 做 fresh verification）。默认过滤 blocked 状态集 {rejected, suspended,
+     * unreachable}；true 时这些候选也进入 fresh resolve（风险自负，文档注明）。
+     */
+    includeBlocked?: boolean;
+}
+export interface DiscoveryDeps {
+    /** 拉取 card 的 fetch；缺省 globalThis.fetch。 */
+    fetchImpl?: typeof fetch;
+    /** Kiwi 本地 A2A binding 声明（capability intersection 的 local 侧）。 */
+    localInterfaces?: AgentInterface[];
+    /** hosted 通道是否已配置（§33：非 direct 时的次选）。 */
+    hosted?: {
+        configured: boolean;
+        config_id?: string;
+    };
+    /** platform 通道是否已配置（fail-closed：未配置不产生候选）。 */
+    platform?: {
+        configured: boolean;
+        credential_ref?: string;
+    };
+    /** 拉取超时 ms（默认 15000）。 */
+    timeoutMs?: number;
+    /** SSRF DNS 复查的解析函数（缺省 node:dns lookup；受控/测试环境注入用）。 */
+    resolveIp?: (hostname: string) => Promise<string[]>;
+    /** 跳过 SSRF DNS 复查（仅测试/受控环境；生产缺省 false）。 */
+    skipDnsCheck?: boolean;
+    /**
+     * UCP 集成（WP3）：domain 输入先试 `/.well-known/ucp`，失败回退
+     * `/.well-known/agent-card.json`。缺省启用（不传即用默认 resolver）；
+     * `disabled: true` 保持 v0.5 行为。
+     */
+    ucp?: UcpDiscoveryDeps;
+    /**
+     * Commerce Agent Catalog 集成（v2.3，可选）：配置后启用 resolveViaCatalog。
+     * 不影响现有 resolve() 语义。
+     */
+    catalog?: CatalogDiscoveryDeps;
+}
+export type DiscoveryErrorCode = "invalid_input" | "card_fetch_failed" | "card_invalid" | "card_has_secret" | "no_channel_candidate";
+export declare class DiscoveryError extends Error {
+    readonly code: DiscoveryErrorCode;
+    constructor(code: DiscoveryErrorCode, message: string);
+}
+/**
+ * resolveViaCatalog 的产出：catalog 候选 + 经 fresh verification 升级的档案。
+ * `candidate` 保留 catalog 元数据（catalog_agent_id / hosting / verification 等），
+ * 供调用方追溯来源；`profile` 是可信的 CounterpartyProfile。
+ */
+export interface ResolvedCatalogCandidate {
+    candidate: CandidateAgent;
+    profile: CounterpartyProfile;
+}
+export declare class AgentDiscovery {
+    private readonly deps;
+    private readonly ucpResolver;
+    private readonly ucpLocalProfile;
+    constructor(deps?: DiscoveryDeps);
+    private cardUrlFor;
+    private fetchCard;
+    private identityFor;
+    private channelCandidates;
+    /**
+     * 解析对端：domain 或 Agent Card URL → CounterpartyProfile。
+     * 无可用通道候选时抛 DiscoveryError（fail-closed，不返回空档案）。
+     */
+    resolve(input: DiscoveryInput): Promise<CounterpartyProfile>;
+    /**
+     * 通过 Commerce Agent Catalog 发现并升级对端（v2.3，设计 §21 / MVP Slice A/B）。
+     *
+     * 流程：searchCandidates → 按 TrustPolicy 过滤 blocked 状态 → 对每个候选按其
+     * `discovery.agent_card_url` 或 `merchant.domain` 走现有 resolve() 做 fresh
+     * verification → 按候选 hosting.mode 收窄通道候选（不自动降级）→ 返回
+     * `{ candidate, profile }`。
+     *
+     * 关键语义（契约 §1 / 设计 §8.2）：catalog 候选**不是**已证明的在线身份。
+     * 本方法绝不直接信任候选元数据构造档案，profile 必须来自 resolve() 实时拉取
+     * 校验的 Agent Card。没有 agent_card_url / merchant.domain 的候选无法 fresh
+     * verify → 跳过（不产出档案）。filtered 后无可用通道候选 → 跳过（不降级）。
+     *
+     * fail-closed（§4.6）：任一候选的 fresh resolve 失败（fetch / 校验 / 无通道）
+     * 直接抛错，不静默丢弃；blocked 状态候选默认过滤，includeBlocked: true 显式放宽。
+     *
+     * @param query 覆盖 DiscoveryDeps.catalog.query 的搜索查询。
+     */
+    resolveViaCatalog(query?: CatalogSearchQuery): Promise<ResolvedCatalogCandidate[]>;
+    /** blocked verification.status 过滤；includeBlocked 显式放宽（文档注明）。 */
+    private isCatalogCandidateAllowed;
+    /**
+     * 候选 → resolve() 输入。优先 agent_card_url，其次 merchant.domain；
+     * 两者都缺 → undefined（无法 fresh verify，跳过）。
+     */
+    private resolveInputForCandidate;
+}

package/dist/discovery/resolve.js

@@ -0,0 +1,367 @@
+/**
+ * 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.
+ */
+/**
+ * AgentDiscovery.resolve —— §33 AgentDiscovery 职责落地。
+ *
+ * 输入 domain 或 Agent Card URL：
+ *
+ *   domain        → 双发现入口（基线 §25 / §33，WP3）：
+ *                     1. 先试 UCP 标准入口 `/.well-known/ucp`；
+ *                        解析成功且校验后 profile 含 a2a transport → 用其
+ *                        endpoint（Agent Card URL）继续；
+ *                     2. UCP 失败（解析/校验/无 a2a transport）→ 回退直接试
+ *                        `https://<domain>/.well-known/agent-card.json`。
+ *                     两个都是标准发现入口，权限等价，因此 UCP → Agent Card
+ *                     的回退不违反不变量 21 —— 不变量 21 约束的是通道候选的
+ *                     一次性选择，不是发现入口本身。
+ *   agentCardUrl  → 直接拉取 Agent Card（不走 UCP）。
+ *
+ * 处理链：
+ *   fetch → parseAgentCard（结构校验 + secret 扫描，不变量 24）→
+ *   capability intersection（§3.1 / §33）→ identity bootstrap → channel candidates。
+ *   UCP 优先路径成功时，UCP capability intersection（§3.2，与 A2A binding
+ *   intersection 两个维度并存）与解析出的 profile 一并放入 CounterpartyProfile。
+ *
+ * 通道候选按优先序（§33）：A2A 可用 → a2a-direct；否则若配置了 hosted →
+ * shopping-cli-hosted；否则若配置了 platform → platform-api；都没有 → fail-closed
+ * （抛 DiscoveryError）。候选选择本身是一次性确定性决策（selectChannelCandidate），
+ * 后续失败绝不自动降级到权限更宽的通道（不变量 21）。
+ *
+ * 全部失败路径抛 DiscoveryError（fail-closed，§4.6）。
+ *
+ * v2.3（设计 §21 / MVP Slice A/B）：DiscoveryDeps.catalog 可选配置后启用
+ * resolveViaCatalog —— 通过 shopping-cli Commerce Agent Catalog 发现候选并升级为
+ * CounterpartyProfile。catalog 候选不是已证明的在线身份（契约 §1），升级路径
+ * 必须走 resolve() 做 fresh verification，不直接信任候选元数据。
+ */
+import { AgentCardError, parseAgentCard, } from "./agent-card/index.js";
+import { intersectCapabilities } from "./capability/index.js";
+import { UcpResolver } from "./ucp/resolver.js";
+import { isUcpError } from "./ucp/error.js";
+import { computeCapabilityIntersection, intersectionView } from "./ucp/intersect.js";
+import { normalizeHostingMode } from "./catalog-source/index.js";
+import { assertResolvableTargetUrl, assertSafeTargetUrl, } from "../a2a/client/url-policy.js";
+import { readJsonBody, SafeHttpError } from "../net/safe-http.js";
+export class DiscoveryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "DiscoveryError";
+        this.code = code;
+    }
+}
+/** Kiwi 本地默认 A2A binding：JSONRPC 1.0（基线 §3.1 core binding）。 */
+const DEFAULT_LOCAL_INTERFACES = [
+    { url: "https://kiwi.local/a2a", protocolBinding: "JSONRPC", protocolVersion: "1.0" },
+];
+/**
+ * 默认过滤的 verification.status（设计 §8.2 fresh verification / TrustPolicy）。
+ * rejected / suspended / unreachable 说明对端身份已被 catalog 判定不可信；
+ * includeBlocked: true 可显式放宽。
+ */
+const BLOCKED_CATALOG_VERIFICATION_STATUSES = new Set([
+    "rejected",
+    "suspended",
+    "unreachable",
+]);
+const WELL_KNOWN_AGENT_CARD_PATH = "/.well-known/agent-card.json";
+/**
+ * 从校验后的 UCP profile 挑出 a2a transport 服务的 endpoint（Agent Card URL）。
+ * validate 已保证 a2a service 必有 https endpoint；这里只需按序遍历取第一个。
+ */
+function findA2aTransportEndpoint(profile) {
+    const services = profile.ucp.services;
+    if (services === undefined)
+        return undefined;
+    for (const declarations of Object.values(services)) {
+        for (const decl of declarations) {
+            if (decl.transport === "a2a" && decl.endpoint !== undefined)
+                return decl.endpoint;
+        }
+    }
+    return undefined;
+}
+/**
+ * 按 catalog hosting.mode（设计 §22）收窄 resolve() 产出的通道候选。
+ * 不引入自动降级（不变量 21 / §22 fallback 不能自动扩大权限）：
+ *   - direct_only → 只保留 a2a-direct（无 direct 端点则该候选不可用）；
+ *   - hosted_only → 只保留 shopping-cli-hosted（未配置 hosted 则不可用）；
+ *   - hybrid     → 保留 direct + hosted 两个候选，优先序仍由 selectChannelCandidate
+ *                  （direct 优先）决定；
+ *   - unknown    → 只当 resolve() 实际发现 a2a binding 时给 direct 候选。
+ * platform-api 不进入 catalog 驱动的档案（catalog 只表达 direct/hosted 两种偏好；
+ * 附加 platform 候选属于超出 merchant 声明范围的降级/扩权）。
+ */
+function applyHostingMode(candidates, mode) {
+    switch (mode) {
+        case "direct_only":
+            return candidates.filter((c) => c.kind === "a2a-direct");
+        case "hosted_only":
+            return candidates.filter((c) => c.kind === "shopping-cli-hosted");
+        case "hybrid":
+            return candidates.filter((c) => c.kind === "a2a-direct" || c.kind === "shopping-cli-hosted");
+        case "unknown":
+            return candidates.filter((c) => c.kind === "a2a-direct");
+    }
+}
+export class AgentDiscovery {
+    deps;
+    ucpResolver;
+    ucpLocalProfile;
+    constructor(deps = {}) {
+        this.deps = deps;
+        const ucpDeps = deps.ucp;
+        if (ucpDeps === undefined || ucpDeps.disabled === true) {
+            this.ucpResolver = undefined;
+            this.ucpLocalProfile = undefined;
+            return;
+        }
+        this.ucpLocalProfile = ucpDeps.localProfile;
+        this.ucpResolver = new UcpResolver({
+            ...ucpDeps.resolver,
+            fetchImpl: ucpDeps.resolver?.fetchImpl ?? deps.fetchImpl,
+            timeoutMs: ucpDeps.resolver?.timeoutMs ?? deps.timeoutMs ?? 15_000,
+        });
+    }
+    cardUrlFor(input) {
+        if (input.agentCardUrl !== undefined && input.domain !== undefined) {
+            throw new DiscoveryError("invalid_input", "DiscoveryInput must provide exactly one of domain or agentCardUrl");
+        }
+        if (input.agentCardUrl !== undefined)
+            return input.agentCardUrl;
+        if (input.domain !== undefined) {
+            let url;
+            try {
+                url = new URL(`https://${input.domain}${WELL_KNOWN_AGENT_CARD_PATH}`);
+            }
+            catch {
+                throw new DiscoveryError("invalid_input", `domain is not a valid host: "${input.domain}"`);
+            }
+            if (url.hostname.length === 0 || url.username !== "" || url.password !== "") {
+                throw new DiscoveryError("invalid_input", `domain is not a valid host: "${input.domain}"`);
+            }
+            return url.href;
+        }
+        throw new DiscoveryError("invalid_input", "DiscoveryInput must provide domain or agentCardUrl");
+    }
+    async fetchCard(url) {
+        // SSRF 防护（与 UCP resolver 同级，catalog 驱动的 agent_card_url 同样受保护）：
+        //   1. 静态校验（scheme/userinfo/保留网段/loopback http 例外）；
+        //   2. 请求前 DNS 复查（主机名解析的每个 IP 过保留网段判定，防 rebinding）；
+        //   3. 不跟随重定向（redirect:"manual"，3xx → 拒绝）。
+        let safeUrl;
+        try {
+            safeUrl = assertSafeTargetUrl(url);
+            await assertResolvableTargetUrl(safeUrl, {
+                skipDnsCheck: this.deps.skipDnsCheck,
+                resolveIp: this.deps.resolveIp,
+            });
+        }
+        catch (err) {
+            throw new DiscoveryError("card_fetch_failed", `Agent Card URL rejected by safety policy: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? 15_000;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetchImpl(safeUrl.href, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: { accept: "application/json" },
+            });
+        }
+        catch (err) {
+            throw new DiscoveryError("card_fetch_failed", `failed to fetch Agent Card from ${url}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (response.redirected ||
+            response.type === "opaqueredirect" ||
+            (response.status >= 300 && response.status < 400)) {
+            throw new DiscoveryError("card_fetch_failed", `Agent Card fetch must not follow redirects (HTTP ${response.status} from ${url})`);
+        }
+        if (!response.ok) {
+            throw new DiscoveryError("card_fetch_failed", `Agent Card fetch returned HTTP ${response.status} from ${url}`);
+        }
+        let raw;
+        try {
+            // 响应体读取在超时覆盖内 + 大小上限（出站加固：对端停滞 body 或回传
+            // 巨量 body 都不能挂起/打爆本进程）。
+            raw = await readJsonBody(response, { signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new DiscoveryError("card_fetch_failed", `Agent Card fetch timed out after ${timeoutMs}ms: ${url}`);
+            }
+            throw new DiscoveryError("card_fetch_failed", err instanceof SafeHttpError && err.code === "response_too_large"
+                ? `Agent Card response from ${url}: ${err.message}`
+                : `Agent Card response from ${url} is not valid JSON`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return raw;
+    }
+    identityFor(card) {
+        const org = card.provider.organization;
+        return org.length > 0 ? org : card.name;
+    }
+    channelCandidates(card) {
+        const local = this.deps.localInterfaces ?? DEFAULT_LOCAL_INTERFACES;
+        const intersection = intersectCapabilities(local, card);
+        const candidates = [];
+        if (intersection.selected !== undefined) {
+            candidates.push({ kind: "a2a-direct", url: intersection.selected.url });
+        }
+        if (this.deps.hosted?.configured === true) {
+            candidates.push({ kind: "shopping-cli-hosted", config_id: this.deps.hosted.config_id });
+        }
+        if (this.deps.platform?.configured === true) {
+            candidates.push({ kind: "platform-api", credential_ref: this.deps.platform.credential_ref });
+        }
+        return { intersection, candidates };
+    }
+    /**
+     * 解析对端：domain 或 Agent Card URL → CounterpartyProfile。
+     * 无可用通道候选时抛 DiscoveryError（fail-closed，不返回空档案）。
+     */
+    async resolve(input) {
+        const url = this.cardUrlFor(input);
+        // WP3 双发现入口（domain 输入）：
+        //   1. 先试 /.well-known/ucp（UcpResolver 内含 HTTPS-only / SSRF / 重定向 /
+        //      Cache-Control / 结构校验，全部 fail-closed）；
+        //   2. 成功且校验后 profile 含 a2a transport → 用其 endpoint（Agent Card URL）
+        //      继续拉 Agent Card；任何失败 → 回退 /.well-known/agent-card.json。
+        // 回退不违反不变量 21：UCP 与 Agent Card 是权限等价的两个标准发现入口，
+        // 不变量 21 约束的是通道候选的一次性选择，不是发现入口。
+        let ucpProfile;
+        let ucpIntersection;
+        let ucpFallbackReason;
+        let cardUrl = url;
+        if (input.domain !== undefined && this.ucpResolver !== undefined) {
+            try {
+                const ucpResult = await this.ucpResolver.resolve({ domain: input.domain });
+                const endpoint = findA2aTransportEndpoint(ucpResult.profile);
+                if (endpoint === undefined) {
+                    ucpFallbackReason =
+                        "UCP profile is valid but declares no a2a transport endpoint (fallback to well-known Agent Card)";
+                }
+                else {
+                    cardUrl = endpoint;
+                    ucpProfile = ucpResult.profile;
+                    if (this.ucpLocalProfile !== undefined) {
+                        ucpIntersection = intersectionView(computeCapabilityIntersection(ucpResult.profile, this.ucpLocalProfile));
+                    }
+                }
+            }
+            catch (err) {
+                const detail = isUcpError(err)
+                    ? `ucp:${err.code}`
+                    : `ucp:unexpected:${err instanceof Error ? err.message : String(err)}`;
+                ucpFallbackReason = `${detail} (fallback to well-known Agent Card)`;
+            }
+        }
+        const raw = await this.fetchCard(cardUrl);
+        let card;
+        try {
+            card = parseAgentCard(raw);
+        }
+        catch (err) {
+            if (err instanceof AgentCardError) {
+                throw new DiscoveryError(err.code === "secret_found" ? "card_has_secret" : "card_invalid", `Agent Card failed validation: ${err.message}`);
+            }
+            throw new DiscoveryError("card_invalid", `Agent Card failed validation: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const { intersection, candidates } = this.channelCandidates(card);
+        if (candidates.length === 0) {
+            throw new DiscoveryError("no_channel_candidate", `no usable channel candidate for Agent Card "${card.name}": no compatible A2A binding and no hosted/platform configured (fail-closed)`);
+        }
+        return {
+            identity: this.identityFor(card),
+            source: input.agentCardUrl !== undefined
+                ? `card:${input.agentCardUrl}`
+                : `domain:${input.domain ?? url}`,
+            agent_card: card,
+            intersection,
+            channel_candidates: candidates,
+            ...(ucpProfile !== undefined ? { ucp_profile: ucpProfile } : {}),
+            ...(ucpIntersection !== undefined ? { ucp_intersection: ucpIntersection } : {}),
+            ...(ucpFallbackReason !== undefined ? { ucp_fallback_reason: ucpFallbackReason } : {}),
+        };
+    }
+    /**
+     * 通过 Commerce Agent Catalog 发现并升级对端（v2.3，设计 §21 / MVP Slice A/B）。
+     *
+     * 流程：searchCandidates → 按 TrustPolicy 过滤 blocked 状态 → 对每个候选按其
+     * `discovery.agent_card_url` 或 `merchant.domain` 走现有 resolve() 做 fresh
+     * verification → 按候选 hosting.mode 收窄通道候选（不自动降级）→ 返回
+     * `{ candidate, profile }`。
+     *
+     * 关键语义（契约 §1 / 设计 §8.2）：catalog 候选**不是**已证明的在线身份。
+     * 本方法绝不直接信任候选元数据构造档案，profile 必须来自 resolve() 实时拉取
+     * 校验的 Agent Card。没有 agent_card_url / merchant.domain 的候选无法 fresh
+     * verify → 跳过（不产出档案）。filtered 后无可用通道候选 → 跳过（不降级）。
+     *
+     * fail-closed（§4.6）：任一候选的 fresh resolve 失败（fetch / 校验 / 无通道）
+     * 直接抛错，不静默丢弃；blocked 状态候选默认过滤，includeBlocked: true 显式放宽。
+     *
+     * @param query 覆盖 DiscoveryDeps.catalog.query 的搜索查询。
+     */
+    async resolveViaCatalog(query) {
+        const catalogDeps = this.deps.catalog;
+        if (catalogDeps === undefined) {
+            throw new DiscoveryError("invalid_input", "resolveViaCatalog requires a catalog source in DiscoveryDeps.catalog");
+        }
+        const candidates = await catalogDeps.source.searchCandidates(query ?? catalogDeps.query ?? {});
+        const results = [];
+        for (const candidate of candidates) {
+            if (!this.isCatalogCandidateAllowed(candidate))
+                continue;
+            const input = this.resolveInputForCandidate(candidate);
+            if (input === undefined)
+                continue;
+            // 现有 resolve() 实时拉取校验（fresh verification）。失败 propagate。
+            const profile = await this.resolve(input);
+            const channelCandidates = applyHostingMode(profile.channel_candidates, normalizeHostingMode(candidate.hosting.mode));
+            if (channelCandidates.length === 0)
+                continue;
+            results.push({ candidate, profile: { ...profile, channel_candidates: channelCandidates } });
+        }
+        return results;
+    }
+    /** blocked verification.status 过滤；includeBlocked 显式放宽（文档注明）。 */
+    isCatalogCandidateAllowed(candidate) {
+        if (this.deps.catalog?.includeBlocked === true)
+            return true;
+        return !BLOCKED_CATALOG_VERIFICATION_STATUSES.has(candidate.verification.status);
+    }
+    /**
+     * 候选 → resolve() 输入。优先 agent_card_url，其次 merchant.domain；
+     * 两者都缺 → undefined（无法 fresh verify，跳过）。
+     */
+    resolveInputForCandidate(candidate) {
+        const agentCardUrl = candidate.discovery?.agent_card_url;
+        if (agentCardUrl !== undefined && agentCardUrl.length > 0) {
+            return { agentCardUrl };
+        }
+        const domain = candidate.merchant?.domain;
+        if (domain !== undefined && domain.length > 0) {
+            return { domain };
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/discovery/resolve.js.map

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

package/dist/discovery/ucp/error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * UCP resolver / validator 错误。错误码对齐 UCP 错误表（profile_* 系列）。
+ * fail-closed（§4.6）：任何无法证明合法的 profile 都拒绝。
+ */
+export type UcpErrorCode = "invalid_input" | "profile_not_https" | "profile_redirect" | "profile_unreachable" | "profile_bad_status" | "profile_cache_control" | "profile_malformed" | "unsafe_target";
+export declare class UcpError extends Error {
+    readonly code: UcpErrorCode;
+    constructor(code: UcpErrorCode, message: string);
+}
+export declare function isUcpError(err: unknown): err is UcpError;

package/dist/discovery/ucp/error.js

@@ -0,0 +1,27 @@
+/**
+ * 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 class UcpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "UcpError";
+        this.code = code;
+    }
+}
+export function isUcpError(err) {
+    return err instanceof UcpError;
+}
+//# sourceMappingURL=error.js.map

package/dist/discovery/ucp/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/discovery/ucp/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAe;IAC5B,YAAY,IAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,GAAG,YAAY,QAAQ,CAAC;AACjC,CAAC"}

package/dist/discovery/ucp/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+/**
+ * discovery/ucp — UCP Profile（UCP 2026-04-08 spec family，基线 §3.2 / §25 / §43）。
+ *
+ * WP1：UCP Profile 模型 + resolver。后续 WP3 通过 discovery/resolve.ts 集成
+ * （本 WP 不改动 resolve.ts）。
+ */
+export { UcpError, isUcpError } from "./error.js";
+export type { UcpErrorCode } from "./error.js";
+export { computeCapabilityIntersection, intersectionView, requireCapabilitiesCompatible, selectRelevantCapabilities, validateRequiresConstraint, } from "./intersect.js";
+export type { ActiveCapability, CapabilityExclusionReason, CapabilityIntersectionResult, ExcludedCapability, RequiresValidationResult, UcpIntersectionView, UcpRequiresConstraint, UcpRequiresVersionBounds, UcpCapabilityWithRequires, } from "./intersect.js";
+export { validateUcpProfile } from "./validate.js";
+export type { UcpRejectedEntry, UcpRejectionCode, UcpValidationResult } from "./validate.js";
+export { UcpResolver, parseCacheControl, WELL_KNOWN_UCP_PATH } from "./resolver.js";
+export type { CacheControlParse, UcpResolveInput, UcpResolveResult, UcpResolverOptions, } from "./resolver.js";
+export { buildKiwiNegotiationCapability, buildKiwiVendorProfile, KIWI_NEGOTIATION_SCHEMA_PATH, KIWI_NEGOTIATION_SPEC_PATH, KIWI_VENDOR_AUTHORITY, KIWI_VENDOR_CAPABILITY_NAME, KIWI_VENDOR_SERVICE_NAME, } from "./vendor.js";
+export type { KiwiVendorBuildOptions, KiwiVendorCapability, KiwiVendorProfileOptions, } from "./vendor.js";
+export { UCP_TRANSPORTS, isDnsLabel, isHttpsUrl, originHostFor, parseCapabilityNamespace, parseServiceNamespace, reverseDomainToAuthority, } from "./types.js";
+export type { UcpCapabilityDeclaration, UcpNamespaceParts, UcpProfile, UcpServiceDeclaration, UcpSigningKey, UcpTransport, } from "./types.js";