Why samesake?

samesake is for teams whose search quality depends on the quality and structure of their catalog data. It gives you a typed enrichment loop, record resolution, and grounded retrieval without taking ownership of your models, runtime, or storage.

The useful boundary

Most product-search failures begin before ranking: titles are inconsistent, attributes are absent, vendors describe the same item differently, and a nearest-neighbour list cannot tell the difference between weak evidence and a real match. samesake makes those steps explicit:

• enrich extracts typed attributes, derives search surfaces, and quarantines weak rows;
• resolve turns a candidate provider plus pure scoring into entity matches or product groups with offers;
• search combines grounded intent, lexical evidence, vector evidence, hard constraints, ranking policy, honest cutoffs, and optional facets.

Search and facets are one capability. A retrieval port may provide exact facet counts, approximate counts, or no facets, and the result contract remains explicit about what the backend supports.

Why the ports matter

Concern	samesake owns	Your application owns
Catalog and query logic	Pure transforms, plans, scoring, gates	Configuration and policy
Models	Request and response contracts	Embed, generate, rerank, and grounding closures
Enrichment state	EnrichStore contract	Durable state, retries, scheduling, and dead-lettering
Retrieval	Retriever and VocabProvider contracts	Index, query engine, and backend-specific facet behavior
Candidate blocking	CandidateProvider contract and scorer	The shortlist query and its recall/latency tradeoff

This lets a consumer use a reference SQL backend, a D1 plus native vector index, Turbopuffer, an in-memory test store, or a backend it already operates. The core does not change when the port implementation changes.

Model and domain neutrality

The engine treats model identifiers and vector dimensions as opaque configuration. Presets carry overridable field, pipeline, and indexing choices; they never mandate a provider or dimension. A concrete model such as Gemini, a 768-dimensional collection, or the fashion preset is an example of composition, never a product default.

Choose the right tier

• Use the pure functions when your workflow platform owns persistence and retries.
• Use createEnricher or createSearch when you want one capability over your own ports.
• Use @samesake/postgres when its reference backend is the right fit; it is an adapter, not a prerequisite for @samesake/core, @samesake/enrich, or @samesake/query.

The canonical API reference describes the package contracts and their boundaries. The enrichment guide shows the durable workflow shape without making one backend the center of the product.

Note

samesake is alpha. Treat package contracts as the source of truth and validate the configuration and port implementations against your own catalog and workload.