@harrylabsj/kiwi 0.6.0

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

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+/**
+ * Capability intersection 错误。无共同可协商 binding 时抛
+ * `capability_incompatible`（基线 §4.6 / §32）。
+ */
+export declare class CapabilityError extends Error {
+    readonly code: "capability_incompatible";
+    constructor(message: string);
+}

package/dist/discovery/capability/error.js

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * Capability intersection 错误。无共同可协商 binding 时抛
+ * `capability_incompatible`（基线 §4.6 / §32）。
+ */
+export class CapabilityError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = "CapabilityError";
+        this.code = "capability_incompatible";
+    }
+}
+//# sourceMappingURL=error.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../../src/discovery/capability/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AAEH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAA4B;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF"}

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

@@ -0,0 +1,21 @@
+/**
+ * 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/capability — 双方 capability intersection（基线 §3.1 / §33）。
+ */
+export { DEFAULT_BINDING_PREFERENCE, intersectCapabilities, requireCompatibleCapabilities, } from "./intersect.js";
+export type { CapabilityIntersection, IncompatibleBinding, IntersectOptions } from "./intersect.js";
+export { CapabilityError } from "./error.js";

package/dist/discovery/capability/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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/capability — 双方 capability intersection（基线 §3.1 / §33）。
+ */
+export { DEFAULT_BINDING_PREFERENCE, intersectCapabilities, requireCompatibleCapabilities, } from "./intersect.js";
+export { CapabilityError } from "./error.js";
+//# sourceMappingURL=index.js.map

package/dist/discovery/capability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/discovery/capability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AAEH,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/discovery/capability/intersect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { AgentCard, AgentInterface } from "../agent-card/types.js";
+/** core binding 的确定性选择顺序：JSONRPC 优先，其次 GRPC，最后 HTTP+JSON。 */
+export declare const DEFAULT_BINDING_PREFERENCE: readonly string[];
+export interface IncompatibleBinding {
+    binding: string;
+    localVersion?: string;
+    remoteVersion?: string;
+    reason: string;
+}
+export interface CapabilityIntersection {
+    /** 是否存在共同 core binding 且协议版本兼容。 */
+    compatible: boolean;
+    /**
+     * 共同且版本兼容的 core binding 的远端接口；调用方可按顺序逐个尝试。
+     * 数组顺序即 preference 顺序。
+     */
+    candidates: AgentInterface[];
+    /** 确定性选出的单一 binding 的远端接口；无兼容候选时为 undefined。 */
+    selected?: AgentInterface;
+    /** 双方都有但协议版本不兼容的 binding（fail-closed，§4.6）。 */
+    incompatible: IncompatibleBinding[];
+    /** 双方共同支持但不是 core binding 的 binding——不选择（§26）。 */
+    unknownShared: string[];
+    /** 只在一方出现、无法协商的 binding（仅诊断）。 */
+    oneSided: string[];
+}
+export interface IntersectOptions {
+    /** core binding 选择顺序。默认 JSONRPC > GRPC > HTTP+JSON。 */
+    preference?: readonly string[];
+    /** 版本兼容判定；默认精确字符串匹配，缺省版本视为不兼容。 */
+    versionMatch?: (localVersion: string | undefined, remoteVersion: string | undefined) => boolean;
+}
+/**
+ * 双方 supportedInterfaces 的交集。
+ *
+ * 版本兼容定义（默认）：双方都声明了该 binding 的 protocolVersion 且字符串相等。
+ * 任一方的版本缺省、或双方版本不同，该 binding 即视为不兼容（fail-closed）。
+ */
+export declare function intersectCapabilities(local: AgentCard | AgentInterface[], remote: AgentCard | AgentInterface[], options?: IntersectOptions): CapabilityIntersection;
+/** 无共同可协商 binding 时抛 CapabilityError（fail-closed 断言）。 */
+export declare function requireCompatibleCapabilities(local: AgentCard | AgentInterface[], remote: AgentCard | AgentInterface[], options?: IntersectOptions): CapabilityIntersection;

package/dist/discovery/capability/intersect.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+/**
+ * Capability intersection（基线 §3.1 / §33 AgentDiscovery：capability intersection）。
+ *
+ * 双方各持一组 `supportedInterfaces`；Kiwi MUST 从中选择双方共同支持的 binding，
+ * 不得把某一种 binding 硬编码为协议本身（§3.1）。本模块：
+ *
+ * - 计算共同 binding 及其协议版本兼容性（未知版本 fail-closed，§4.6）；
+ * - core binding（JSONRPC/GRPC/HTTP+JSON）中确定性地选一个作为 `selected`；
+ * - 未知（非 core）binding 出现在 `unknownShared` 但**不选择**（§26 不拒绝但不选择）；
+ * - 任一 binding 仅一方支持时记入 `oneSided`（诊断用）。
+ *
+ * 版本兼容默认精确匹配；可通过 `versionMatch` 注入未来 semver 匹配策略。
+ */
+import { isCoreProtocolBinding } from "../agent-card/types.js";
+import { CapabilityError } from "./error.js";
+/** core binding 的确定性选择顺序：JSONRPC 优先，其次 GRPC，最后 HTTP+JSON。 */
+export const DEFAULT_BINDING_PREFERENCE = ["JSONRPC", "GRPC", "HTTP+JSON"];
+function toInterfaces(card) {
+    if (Array.isArray(card))
+        return card;
+    return card.supportedInterfaces;
+}
+/** 同 binding 名合并多接口声明（同一 binding 出现多次时取全部，供版本匹配）。 */
+function indexByBinding(interfaces) {
+    const map = new Map();
+    for (const iface of interfaces) {
+        const entry = { version: iface.protocolVersion, iface };
+        const list = map.get(iface.protocolBinding);
+        if (list === undefined) {
+            map.set(iface.protocolBinding, [entry]);
+        }
+        else {
+            list.push(entry);
+        }
+    }
+    return map;
+}
+/**
+ * 双方 supportedInterfaces 的交集。
+ *
+ * 版本兼容定义（默认）：双方都声明了该 binding 的 protocolVersion 且字符串相等。
+ * 任一方的版本缺省、或双方版本不同，该 binding 即视为不兼容（fail-closed）。
+ */
+export function intersectCapabilities(local, remote, options = {}) {
+    const preference = options.preference ?? DEFAULT_BINDING_PREFERENCE;
+    const versionMatch = options.versionMatch ?? ((l, r) => l !== undefined && l === r);
+    const localInterfaces = toInterfaces(local);
+    const remoteInterfaces = toInterfaces(remote);
+    const localByBinding = indexByBinding(localInterfaces);
+    const remoteByBinding = indexByBinding(remoteInterfaces);
+    const allBindings = new Set([...localByBinding.keys(), ...remoteByBinding.keys()]);
+    const candidates = [];
+    const incompatible = [];
+    const unknownShared = [];
+    const oneSided = [];
+    for (const binding of allBindings) {
+        const localEntries = localByBinding.get(binding);
+        const remoteEntries = remoteByBinding.get(binding);
+        const localPresent = localEntries !== undefined;
+        const remotePresent = remoteEntries !== undefined;
+        if (!localPresent || !remotePresent) {
+            if (isCoreProtocolBinding(binding)) {
+                oneSided.push(binding);
+            }
+            continue;
+        }
+        // 双方都有。对同一 binding 的多份声明，取任一可兼容组合。
+        const matched = remoteEntries?.find((remoteEntry) => (localEntries ?? []).some((localEntry) => versionMatch(localEntry.version, remoteEntry.version)));
+        if (matched === undefined) {
+            const localVersion = localEntries?.[0]?.version;
+            const remoteVersion = remoteEntries?.[0]?.version;
+            incompatible.push({
+                binding,
+                localVersion,
+                remoteVersion,
+                reason: localVersion === undefined || remoteVersion === undefined
+                    ? "protocolVersion missing on one side (fail-closed)"
+                    : `protocolVersion mismatch: local ${localVersion} vs remote ${remoteVersion}`,
+            });
+            continue;
+        }
+        if (!isCoreProtocolBinding(binding)) {
+            unknownShared.push(binding);
+            continue;
+        }
+        candidates.push(matched.iface);
+    }
+    // 按 preference 顺序稳定排序：preference 中靠前的 binding 优先。
+    const preferenceRank = new Map(preference.map((b, i) => [b, i]));
+    candidates.sort((a, b) => {
+        const ra = preferenceRank.get(a.protocolBinding) ?? Number.POSITIVE_INFINITY;
+        const rb = preferenceRank.get(b.protocolBinding) ?? Number.POSITIVE_INFINITY;
+        return ra - rb;
+    });
+    const selected = candidates.length > 0 ? candidates[0] : undefined;
+    return {
+        compatible: candidates.length > 0,
+        candidates,
+        selected,
+        incompatible,
+        unknownShared,
+        oneSided,
+    };
+}
+/** 无共同可协商 binding 时抛 CapabilityError（fail-closed 断言）。 */
+export function requireCompatibleCapabilities(local, remote, options = {}) {
+    const intersection = intersectCapabilities(local, remote, options);
+    if (!intersection.compatible) {
+        const detail = [
+            ...intersection.incompatible,
+            ...intersection.oneSided.map((b) => ({
+                binding: b,
+                reason: "binding supported by only one side",
+            })),
+        ]
+            .map((i) => `${i.binding} (${i.reason})`)
+            .join("; ");
+        throw new CapabilityError(`no common compatible A2A binding: ${detail || "no shared protocolBinding"}`);
+    }
+    return intersection;
+}
+//# sourceMappingURL=intersect.js.map

package/dist/discovery/capability/intersect.js.map

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

package/dist/discovery/catalog-source/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * ShoppingCliCatalogSource 错误（fail-closed，基线 §4.6 / 设计 §17.1）。
+ *
+ * 任何校验 / 网络失败都必须抛 CatalogSourceError，绝不静默容错、不自动降级：
+ *   - invalid_input      调用方给了非法查询（类型 / 取值错误）；
+ *   - request_failed     HTTP 非 2xx、网络异常或超时；
+ *   - response_invalid   响应体不是契约要求的信封结构（缺 results / catalog_agent）；
+ *   - contract_violation 候选元素未通过 CandidateAgent DTO schema 校验，或 contract
+ *                        注解非 candidate-agent / 非 1.x（视为协议级违规）。
+ */
+export declare const CATALOG_SOURCE_ERROR_CODES: readonly ["invalid_input", "request_failed", "response_invalid", "contract_violation"];
+export type CatalogSourceErrorCode = (typeof CATALOG_SOURCE_ERROR_CODES)[number];
+/** Catalog 读取失败。带错误码；fail-closed，调用方不得吞掉。 */
+export declare class CatalogSourceError extends Error {
+    readonly code: CatalogSourceErrorCode;
+    constructor(code: CatalogSourceErrorCode, message: string);
+}

package/dist/discovery/catalog-source/errors.js

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+/**
+ * ShoppingCliCatalogSource 错误（fail-closed，基线 §4.6 / 设计 §17.1）。
+ *
+ * 任何校验 / 网络失败都必须抛 CatalogSourceError，绝不静默容错、不自动降级：
+ *   - invalid_input      调用方给了非法查询（类型 / 取值错误）；
+ *   - request_failed     HTTP 非 2xx、网络异常或超时；
+ *   - response_invalid   响应体不是契约要求的信封结构（缺 results / catalog_agent）；
+ *   - contract_violation 候选元素未通过 CandidateAgent DTO schema 校验，或 contract
+ *                        注解非 candidate-agent / 非 1.x（视为协议级违规）。
+ */
+export const CATALOG_SOURCE_ERROR_CODES = [
+    "invalid_input",
+    "request_failed",
+    "response_invalid",
+    "contract_violation",
+];
+/** Catalog 读取失败。带错误码；fail-closed，调用方不得吞掉。 */
+export class CatalogSourceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CatalogSourceError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/discovery/catalog-source/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/discovery/catalog-source/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,eAAe;IACf,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;CACZ,CAAC;AAIX,6CAA6C;AAC7C,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAyB;IAEtC,YAAY,IAA4B,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/discovery/catalog-source/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+/**
+ * catalog-source —— ShoppingCliCatalogSource（设计 §21 仓库归属：Kiwi 侧消费端）。
+ *
+ * 从 shopping-cli Commerce Agent Catalog 读取 CandidateAgent；候选不是已证明的
+ * 在线身份（契约 §1），升级为 CounterpartyProfile 由 AgentDiscovery.resolveViaCatalog
+ * 完成。本桶只含 source 自身，集成在 ../resolve.ts。
+ */
+export { ShoppingCliCatalogSource } from "./source.js";
+export type { CatalogSourceDeps } from "./source.js";
+export { KiwiCatalogSource } from "./kiwi-source.js";
+export { CatalogSourceError } from "./errors.js";
+export type { CatalogSourceErrorCode } from "./errors.js";
+export { validateCatalogAgentRecord, validateListingRecord, validateListingSearchResult } from "./kiwi-schema.js";
+export { normalizeCatalogAgent, type AdministrativeState, type CatalogAgentRecord, type CatalogSkill, type FreshnessState, type KiwiCatalogSearchQuery, type KiwiListingSearchQuery, type ListingAgentProjection, type ListingFreshnessState, type ListingMatch, type ListingMerchantSummary, type ListingRecord, type ListingSearchResult, type ListingType, type PublicationState, type VerificationLevel, } from "./kiwi-record.js";
+export { normalizeHostingMode, type CandidateAgent, type CandidateContract, type CandidateDiscovery, type CandidateHosting, type CandidateMerchant, type CandidateSkill, type CandidateVerification, type CatalogSearchQuery, type CatalogSource, type HostingMode, type RawHostingMode, type VerificationStatus, } from "./types.js";

package/dist/discovery/catalog-source/index.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/**
+ * catalog-source —— ShoppingCliCatalogSource（设计 §21 仓库归属：Kiwi 侧消费端）。
+ *
+ * 从 shopping-cli Commerce Agent Catalog 读取 CandidateAgent；候选不是已证明的
+ * 在线身份（契约 §1），升级为 CounterpartyProfile 由 AgentDiscovery.resolveViaCatalog
+ * 完成。本桶只含 source 自身，集成在 ../resolve.ts。
+ */
+export { ShoppingCliCatalogSource } from "./source.js";
+export { KiwiCatalogSource } from "./kiwi-source.js";
+export { CatalogSourceError } from "./errors.js";
+export { validateCatalogAgentRecord, validateListingRecord, validateListingSearchResult } from "./kiwi-schema.js";
+export { normalizeCatalogAgent, } from "./kiwi-record.js";
+export { normalizeHostingMode, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/discovery/catalog-source/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/discovery/catalog-source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAClH,OAAO,EACL,qBAAqB,GAgBtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,GAarB,MAAM,YAAY,CAAC"}

package/dist/discovery/catalog-source/kiwi-record.d.ts

@@ -0,0 +1,183 @@
+/**
+ * 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.
+ */
+/**
+ * kiwi-catalog CatalogAgentRecord —— /v1/agents wire 形状的 TS 投影。
+ *
+ * 契约来源：contracts/kiwi-catalog/1.0/agent-record.schema.json（产品文档
+ * kiwi-catalog v0.3 §6/§7）。运行时校验以 ajv 编译后的 schema 为准（kiwi-schema.ts）。
+ *
+ * 三正交状态域（v0.3 §7，MUST NOT 坍缩为一个状态机）：
+ *   - VerificationLevel：证据链级别（可降级，历史证据可审计）；
+ *   - FreshnessState：profile 新鲜度 / 可达性（FRESH/STALE/UNREACHABLE）；
+ *   - AdministrativeState：治理处置（ACTIVE/SUSPENDED/REJECTED 终态）。
+ *
+ * `normalizeCatalogAgent` 把 record 折叠成 CandidateAgent 共享候选形状（DTO 1.0），
+ * 供 AgentDiscovery.resolveViaCatalog 复用同一升级路径；折叠优先级：
+ *   rejected > suspended > unreachable > stale > verification_level
+ * （行政处置最重，其次可达性，再其次新鲜度——与 legacy BLOCKED 状态集语义一致）。
+ */
+import type { DestinationType } from "../../handoff/destination.js";
+import type { CandidateAgent, CatalogSearchQuery, HostingMode } from "./types.js";
+/** 验证级别（v0.3 §7.1）。 */
+export type VerificationLevel = "discovered" | "profile_valid" | "domain_verified" | "agent_verified" | "commerce_verified";
+/** 新鲜度 / 可达性（v0.3 §7.2）。 */
+export type FreshnessState = "fresh" | "stale" | "unreachable";
+/** 行政处置（v0.3 §7.3）。 */
+export type AdministrativeState = "active" | "suspended" | "rejected";
+/** kiwi-catalog agent 公开记录（public-only，完成定义 #8）。 */
+export interface CatalogAgentRecord {
+    readonly catalog_agent_id: string;
+    readonly principal_type: "buyer" | "merchant";
+    readonly merchant_id?: string;
+    readonly display_name: string;
+    readonly canonical_domain: string;
+    readonly agent_card_url?: string;
+    readonly ucp_profile_url?: string;
+    readonly protocols?: Readonly<Record<string, readonly string[]>>;
+    readonly capabilities?: readonly string[];
+    readonly skills?: readonly CatalogSkill[];
+    readonly hosting_mode: HostingMode;
+    readonly handoff_destination_types?: readonly DestinationType[];
+    readonly verification_level: VerificationLevel;
+    readonly freshness_state: FreshnessState;
+    readonly administrative_state: AdministrativeState;
+    readonly last_verified_at?: string;
+    readonly fresh_until?: string;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+/** 公开 skill（v0.3 §6，与 DTO 1.0 CandidateSkill 同形）。 */
+export interface CatalogSkill {
+    readonly skill_id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+}
+/**
+ * kiwi-catalog 富搜索查询（新 API /v1/agents/search；词表单一来源）。
+ * 继承共享 CatalogSearchQuery（hosting_mode 接受 canonical + legacy 别名——
+ * record schema 的 hosting_mode 枚举两者都收），新增三态域过滤与
+ * `handoff_destination_types`（精确 KTH destination_type 词表，禁止平行词表）。
+ */
+export interface KiwiCatalogSearchQuery extends Omit<CatalogSearchQuery, "category" | "region" | "skill"> {
+    verification_level?: VerificationLevel;
+    freshness_state?: FreshnessState;
+    administrative_state?: AdministrativeState;
+    /** 精确匹配 KTH destination_type（禁止 supports_* 平行词表）。 */
+    handoff_destination_types?: readonly DestinationType[];
+    /** 分页游标（searchRecords 内部翻页用；调用方无需直接设置）。 */
+    cursor?: string;
+}
+/** listing 类型（v0.4 §4/§5；词表单一来源见 listing-record.schema.json）。 */
+export type ListingType = "product" | "capability";
+/** Listing 发布状态（v0.4 §7.1；大写，与 Agent 域小写 administrative_state 拼写区分）。 */
+export type PublicationState = "ACTIVE" | "WITHDRAWN" | "SUSPENDED";
+/** Listing 新鲜度（v0.4 §7.2；FRESH/STALE 两态，独立于 Agent freshness 三态）。 */
+export type ListingFreshnessState = "FRESH" | "STALE";
+/**
+ * kiwi-catalog ListingRecord —— /v1/listings wire 形状的 TS 投影（v0.4 §4/§5）。
+ *
+ * public-only discovery projection：不得携带 cost / floor price / 私有库存 /
+ * 凭据（v0.4 §4.2）。`listing_freshness_state` 与 `owner_agent_id` 的 Agent
+ * `freshness_state` 是两套独立状态（v0.4 §7.2）；CapabilityListing 不携带
+ * `handoff_destination_types`。
+ */
+export interface ListingRecord {
+    readonly listing_id: string;
+    readonly listing_type: ListingType;
+    readonly owner_agent_id: string;
+    readonly merchant_id: string;
+    readonly source_product_ref?: string;
+    readonly source_revision?: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly category: string;
+    readonly brand?: string;
+    readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+    readonly regions?: readonly string[];
+    readonly tags?: readonly string[];
+    readonly commercial_hints?: Readonly<{
+        moq?: number;
+        price_range_hint?: string;
+        availability_hint?: string;
+        lead_time_hint?: string;
+        supports_bulk_quote?: boolean;
+        supports_customization?: boolean;
+        fulfillment_regions?: readonly string[];
+    }>;
+    readonly handoff_destination_types?: readonly DestinationType[];
+    readonly listing_digest: string;
+    readonly publication_state: PublicationState;
+    readonly listing_freshness_state: ListingFreshnessState;
+    readonly published_at: string;
+    readonly updated_at: string;
+    readonly fresh_until: string;
+}
+/** 搜索结果中的 merchant 投影（v0.4 §9）。 */
+export interface ListingMerchantSummary {
+    readonly merchant_id: string;
+    readonly display_name: string;
+}
+/** 搜索结果中的 owner Agent 投影（join 自 catalog_agents；不复制 endpoint）。 */
+export interface ListingAgentProjection {
+    readonly catalog_agent_id: string;
+    readonly verification_level: VerificationLevel;
+    readonly freshness_state: FreshnessState;
+    readonly administrative_state: AdministrativeState;
+}
+/** match/reason 字段（v0.4 §9，optional）。 */
+export interface ListingMatch {
+    readonly matched_category?: boolean;
+    readonly matched_region?: boolean;
+    readonly matched_brand?: boolean;
+    readonly score?: number;
+}
+/** /v1/listings/search 单个结果（v0.4 §9；authority/requires_direct_confirmation 恒值）。 */
+export interface ListingSearchResult {
+    readonly listing: ListingRecord;
+    readonly merchant: ListingMerchantSummary;
+    readonly agent: ListingAgentProjection;
+    readonly listing_freshness_state: ListingFreshnessState;
+    readonly authority: "discovery_projection";
+    readonly requires_direct_confirmation: true;
+    readonly match?: ListingMatch;
+}
+/**
+ * kiwi-catalog listing 搜索查询（v0.4 §8 query 面；词表单一来源）。
+ * 与 KiwiCatalogSearchQuery 分离：listing 面有自己的键集与 JSON1 结构化过滤。
+ */
+export interface KiwiListingSearchQuery {
+    q?: string;
+    listing_type?: ListingType;
+    category?: string;
+    brand?: string;
+    region?: string;
+    tag?: string;
+    min_moq?: number;
+    max_moq?: number;
+    supports_bulk_quote?: boolean;
+    supports_customization?: boolean;
+    freshness_state?: ListingFreshnessState;
+    handoff_destination_type?: DestinationType;
+    limit?: number;
+    cursor?: string;
+}
+/**
+ * 三态域 record → CandidateAgent DTO 1.0 共享候选形状。
+ * 注意：handoff_destination_types **不进入** CandidateAgent（DTO 1.0
+ * additionalProperties: false）；需要 handoff 词表的消费方走 searchRecords。
+ */
+export declare function normalizeCatalogAgent(record: CatalogAgentRecord): CandidateAgent;