Capability specs

Define PDPP's optional lexical retrieval extension: a discoverable, grant-safe, text-query search surface at GET /v1/search with stream-declared searchable fields and portable result-shape guarantees. ## Requirements ### Requirement: Lexical retrieval is an optional, advertised, named extension

Define the durable architecture and boundary rules for the PDPP reference implementation in this repository without competing with the normative PDPP protocol specs. ## Requirements ### Requirement: The reference implementation remains a forkable substrate The forkable implementation substrate SHALL live in reference-implementation/ and SHALL remain usable without the website runtime.

Define how this repository uses OpenSpec relative to the normative PDPP protocol specs, executable reference code, and temporary planning artifacts. ## Requirements ### Requirement: Authority order stays explicit This repository SHALL treat the root PDPP spec files as normative for protocol behavior, code and tests as authoritative for current reference implementation behavior, and OpenSpec as the project layer for reference architecture and change planning.

Define the repository identity of the forkable PDPP reference implementation so active code, package metadata, and implementation-facing documentation no longer present it as an end-to-end test harness. ## Requirements ### Requirement: The forkable implementation substrate has a reference-implementation identity The repo MUST present the forkable implementation substrate as the reference implementation in active code, package metadata, OpenSpec artifacts, and active implementation-facing docs.

Define how the reference implementation keeps native-provider public contracts provider-first while preserving connector-shaped details only where they are implementation internals or polyfill-specific operational surfaces. ## Requirements ### Requirement: Native provider requests stay provider-first The reference implementation SHALL treat native-provider requests as provider/source-bound requests, not as connector requests with hidden branding.

TBD - created by archiving change define-reference-surface-topology. Update Purpose after archive. ## Requirements ### Requirement: Public website surfaces SHALL distinguish artifact categories

Define how website bridge routes consume the current reference AS/RS contract without teaching legacy helper routes, demo-only assumptions, or connector-only client access as durable PDPP behavior. ## Requirements ### Requirement: Web bridge routes reflect the current reference contract Website bridge routes that call the reference implementation SHALL consume the current primary AS/RS surfaces and SHALL not require removed helper routes or connector-only request assumptions when the reference supports a source-aware contract.

Define PDPP's experimental optional semantic retrieval extension: a discoverable, grant-safe, text-query meaning-match surface at GET /v1/search/semantic with explicit instability, server-declared model metadata, and no portable vector or reranking controls. ## Requirements ### Requirement: Semantic retrieval is an experimental, optional, advertised, named extension