Find Contract

Find is the search service for Elonn. It owns query records, findings, heads, provider selection, normalization, and ranking. Find is distinct from Social discovery and Maps field data.

World exposes Find to runtimes through /world/panels/find and /world/find/query. Runtimes do not call provider services directly.

Ownership

Find owns:

query records
findings
finding heads
find sessions
provider normalization and ranking

Boundaries:

Social owns the social graph traversal used for circles.
Maps owns geographic truth.
Surface owns finding surface persistence and placement.
World relays runtime-visible Find behavior.

Runtime routes through World

Runtimes use only World URLs:

GET  /world/panels/find
POST /world/find/query

Panel payload

GET /world/panels/find returns a runtime panel payload with:

Field	Type	Meaning
`kind`	string	`find`
`view`	string	`find`
`title`	string	Panel title
`summary`	string	Panel summary
`nav`	array	Find navigation items
`sections`	array	Query history, provider status, or findings summary
`actions`	object	Top-level action map
`composer`	object	Optional query composer state
`findings`	array	Optional findings summary for the current query

Find panel payloads are transient service content unless World also supplies durable finding_surface records through surface_runtime.

Query flow

Search begins with:

POST /world/find/query

Request body:

Field	Type	Meaning
`query`	string	Search text
`scope`	string	Required runtime choice: `nearby` or `everywhere`
`origin`	object	Required for `nearby`; `{latitude, longitude}` from existing runtime location
`radius_meters`	integer	Find-owned Nearby radius; currently `5000`

World forwards the request to Find, receives normalized findings, asks Surface to create or update detached finding surfaces, and returns an updated surface_runtime.

Find does not classify query words. burger, coffee, Seattle, and unknown future terms use the same free-form Nominatim path:

nearby: Nominatim receives a bounded 5 km viewbox and results are distance-filtered to the exact radius.
everywhere: Nominatim receives an unrestricted query.
term near place: Find resolves the named place globally and applies Nearby around it, regardless of the selected scope.
Nearby without an origin returns location_required and never falls back to Everywhere.

Response status is ok, location_required, or provider_error. location_required and provider_error preserve the existing finding overlay. An ok response replaces the overlay, including when zero findings are returned.

Each successful query replaces membership in the member's finding_overlay. Zero results empty that overlay without changing carry surfaces. If Surface cannot persist the complete overlay, World fails the query rather than silently returning a partial runtime state.

Web resource findings

Any public-web provider result is normalized as:

{
  "finding_id": "web-provider:...",
  "source_service": "web-provider",
  "object_type": "html_resource",
  "title": "...",
  "summary": "...",
  "source_url": "https://example.com",
  "actions": [
    {"id": "preview", "label": "View", "type": "translate_surface"},
    {"id": "save", "label": "Save", "type": "save_object"},
    {"id": "share", "label": "Share", "type": "share_object"}
  ],
  "service_payload": {
    "content_type": "text/html",
    "canonical_url": null
  }
}

content_type is a provider hint. Surface verifies the response and discovers the canonical URL during translation. Find does not fetch or parse result HTML. No public-web provider is required for the current translation milestone. DuckDuckGo is the next planned provider; Brave remains disabled.

Find supplies action labels and semantic types. A place finding uses open_finding; a web resource uses translate_surface. Runtimes do not derive that choice from object_type.

Finding surfaces

A finding surface is a detached surface with surface_type = finding_surface.

Required finding surface behavior:

carry the normalized finding title and summary
preserve source metadata as provenance
remain independently movable
stay persisted in Surface, not in Find

If a query returns zero findings, runtimes must show an empty or zero-results state and leave the existing non-finding carry surfaces alone.

An OSM result is normalized with object_type = place, stable provider/source identity, and coordinates in service_payload. Its open action is not source navigation. The runtime posts the finding surface id to surface_runtime.commands.open_finding; Surface creates or focuses the durable map_surface for that place in carry_primary.

Provider boundary

Find owns provider integrations and normalizes provider output before anything downstream receives it. Runtimes, World, and other services must not talk directly to Brave, OSM, Nominatim, or Overpass.

The provider flow is:

provider result
  -> finding factory
  -> normalized finding
  -> finding surface
  -> Surface translation or place opening on member action
  -> Surface Object
  -> runtime

If a provider fails, Find returns empty findings for that provider plus provider error information. It must not inject demo or mocked findings.

Nominatim is used for named-place geocoding and scoped free-form place findings. Overpass is not part of the normal Find free-text path. Maps may use Overpass for field-oriented geographic datasets.

Runtime rules

Runtimes load Find panels from content_source.url or /world/panels/find.
Runtimes submit queries through /world/find/query.
Runtimes visibly show the active Find scope before submission and the applied scope after a response.
Find scope is independent of Field radius and filters.
Runtimes render returned finding surfaces from surface_runtime.
Runtimes open place findings through commands.open_finding and render the returned map surface.
Runtimes do not call provider services directly.
Runtimes do not confuse discovery with search.

Canonical terms

find - the search service
finding - a discovered or computed result
discovery - the social graph traversal, distinct from find
session - always qualify: find session