import { z } from "zod"; import { VendoError, type VendoErrorCode } from "./errors.js"; import { type KnowledgeDoc, type KnowledgePosture, type KnowledgeQuery, type KnowledgeRef, type KnowledgeStatus } from "./knowledge.js"; /** Knowledge design v2 (2026-07-22) R2 — the wire protocol version tag. The HTTP profile of the KnowledgeAdapter contract, shared verbatim by the cloud client and the BYO `httpKnowledge` template (decision 2026-07-24: two cloud backend adapters sit BEHIND this protocol — nothing backend-specific may appear on the wire). */ export declare const VENDO_KNOWLEDGE_WIRE_FORMAT: "vendo/knowledge-wire@1"; /** Mount-relative endpoint paths. The mounting surface owns the prefix (cloud: `/api/v1/knowledge`; BYO: the `httpKnowledge` url) and owns auth — the protocol itself is auth-agnostic and carries NO tenant selector of any kind (R5 invariant 1: tenancy derives server-side). Verbs: the four adapter operations are POST-JSON RPC; `status` is GET and doubles as the discovery handshake (format + posture). Requests to an endpoint the declared posture does not cover (POST /upsert or /remove on `write: false`, POST /fetch on `fetch: false`) are answered with the `not-implemented` envelope, 501 — never a bare 404, never `blocked`. Servers validate request bodies against the schemas in this module and answer schema-invalid bodies with the `validation` envelope, 400. The principal deliberately never crosses the wire — visibility is the only context-derived behavior, and it rides `includeInternal`. */ export declare const KNOWLEDGE_WIRE_PATHS: { readonly search: "/search"; readonly fetch: "/fetch"; readonly upsert: "/upsert"; readonly remove: "/remove"; readonly status: "/status"; }; /** POST /search — the wire form of `search(query, ctx)`. Response body on 200: a `KnowledgeSearchResult` (see knowledge.js) — hits ordered most-relevant-first, refs carrying doc-id + opaque chunk-id. `includeInternal` is legitimate on the wire ONLY because every mounting surface is a key-authed, host-trusted hop (R5, KB-COV-7): the OSS composition enforces the trusted-caller rule BEFORE the request leaves the process, and the server trusts the flag because the bearer key already proves the caller is host code, never an end user. */ export interface KnowledgeWireSearchRequest { query: KnowledgeQuery; includeInternal?: boolean; } export declare const knowledgeWireSearchRequestSchema: z.ZodObject<{ query: z.ZodObject<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ query: z.ZodObject<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ query: z.ZodObject<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ text: z.ZodString; intent: z.ZodOptional>; kinds: z.ZodOptional, "many">>; limit: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; /** POST /fetch — the wire form of `fetch(ref, ctx)`. A missing or internal-invisible ref is answered with the 404 error envelope, which clients translate back to the contract's `null` (a ref is not a capability — internal docs behave as unknown without `includeInternal`). Clients MUST require the envelope for that translation: only an enveloped `not-found` means `null`; a bare 404 with no parseable envelope is a mount/deployment failure and must surface as an error, never as `null` (the hosted-store bare-404 lesson). Response body on 200: a `KnowledgeFetchResult` (see knowledge.js). */ export interface KnowledgeWireFetchRequest { ref: KnowledgeRef; includeInternal?: boolean; } export declare const knowledgeWireFetchRequestSchema: z.ZodObject<{ ref: z.ZodObject<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ ref: z.ZodObject<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ ref: z.ZodObject<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docId: z.ZodString; chunkId: z.ZodOptional; title: z.ZodOptional; source: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; includeInternal: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; /** POST /upsert — document-level, engines own chunking. The 200 response is an empty JSON object and MUST NOT be sent before the documents are searchable (the contract's upsert-resolves-when-searchable semantic — backends with asynchronous indexing await it server-side). */ export interface KnowledgeWireUpsertRequest { docs: KnowledgeDoc[]; } export declare const knowledgeWireUpsertRequestSchema: z.ZodObject<{ docs: z.ZodArray; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>, "many">; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docs: z.ZodArray; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>, "many">; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docs: z.ZodArray; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ id: z.ZodString; kind: z.ZodEnum<["docs", "glossary", "api"]>; visibility: z.ZodEnum<["public", "internal"]>; title: z.ZodString; text: z.ZodString; source: z.ZodString; metadata: z.ZodOptional>; updatedAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>, "many">; }, z.ZodTypeAny, "passthrough">>; /** POST /remove — unknown ids resolve as no-ops; 200 is an empty object. */ export interface KnowledgeWireRemoveRequest { docIds: string[]; } export declare const knowledgeWireRemoveRequestSchema: z.ZodObject<{ docIds: z.ZodArray; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docIds: z.ZodArray; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docIds: z.ZodArray; }, z.ZodTypeAny, "passthrough">>; /** GET /status — the discovery handshake. Clients learn the protocol version (`format`), the declared capability posture, and the corpus counts in one round-trip; the posture here is the same declaration the conformance suite verifies (knowledge design v2 R2). */ export interface KnowledgeWireStatus { format: typeof VENDO_KNOWLEDGE_WIRE_FORMAT; posture: KnowledgePosture; status: KnowledgeStatus; } export declare const knowledgeWireStatusSchema: z.ZodObject<{ format: z.ZodLiteral<"vendo/knowledge-wire@1">; posture: z.ZodObject<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">>; status: z.ZodObject<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ format: z.ZodLiteral<"vendo/knowledge-wire@1">; posture: z.ZodObject<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">>; status: z.ZodObject<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ format: z.ZodLiteral<"vendo/knowledge-wire@1">; posture: z.ZodObject<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ fetch: z.ZodBoolean; write: z.ZodBoolean; visibility: z.ZodEnum<["enforced", "public-only"]>; }, z.ZodTypeAny, "passthrough">>; status: z.ZodObject<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ docs: z.ZodNumber; byKind: z.ZodOptional, z.ZodNumber>>; lastSyncAt: z.ZodOptional; }, z.ZodTypeAny, "passthrough">>; }, z.ZodTypeAny, "passthrough">>; /** The standard wire error envelope — byte-identical to the umbrella wire's (`packages/vendo/src/wire/shared.ts`): `{ error: { code, message } }`. */ export interface KnowledgeWireError { error: { code: VendoErrorCode; message: string; }; } export declare const knowledgeWireErrorSchema: z.ZodObject<{ error: z.ZodObject<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">>; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ error: z.ZodObject<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">>; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ error: z.ZodObject<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ code: z.ZodEnum<["validation", "blocked", "not-implemented", "sandbox-unavailable", "cloud-required", "not-found", "conflict", "forbidden", "unavailable", "schema-proposal"]>; message: z.ZodString; }, z.ZodTypeAny, "passthrough">>; }, z.ZodTypeAny, "passthrough">>; /** Mirrors the umbrella wire's STATUS_BY_CODE so the two surfaces never diverge; core cannot import it (layering — core depends on nothing). */ export declare const KNOWLEDGE_WIRE_STATUS_BY_CODE: Record; /** Server half: one VendoError → the enveloped body + HTTP status. */ export declare function knowledgeWireErrorBody(error: VendoError): { status: number; body: KnowledgeWireError; }; /** Client half: a non-2xx response → VendoError. An enveloped wire-legal code wins over the bare status; recognized statuses map through STATUS_TO_CODE; anything else degrades to "not-implemented" (never blame the caller with "validation" for a server-shaped failure). Client-specific tails — e.g. the cloud client folding bare 401 into "cloud-required" — belong to the client (ENG-364), not the protocol. */ export declare function parseKnowledgeWireError(status: number, body: unknown): VendoError;