@plurnk/plurnk-execs-search

Web search runtime executor for plurnk-service's exec scheme. Dispatches ## EXEC0 [search] with a query body to a SearXNG instance and returns a compact digest of results (title / url / snippet).

The first non-subprocess @plurnk/plurnk-execs-* sibling, built on the plurnk-execs framework.

Runtime tags

The text-retrieval harness exposes the two SearXNG categories it can represent faithfully:

| Tag | Glyph | Category | | -------------- | ----- | ------------ | | search | 🔎 | general | | news | 📰 | news |

Engine, language, and time-range selection ride the query string via SearXNG's native !bang and :lang syntax (for example, body !gh node streams). External bangs (!!) are refused — they redirect rather than return results. An operator-configured engine list replaces the runtime category; SearXNG otherwise unions the two selections. Media and vertical categories are not registered because this executor projects ranked text metadata and materialized readable pages, not their category-specific payloads.

Configuration (environment)

Every tunable is an optional env override — no code default hides a magic number (suggested values ship in this package's .env.defaults).

| Variable | Required | Behavior when unset | | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | PLURNK_EXECS_SEARCH_SEARXNG_URL | yes | Search is unavailable. URL userinfo, when present, supplies redacted HTTP Basic credentials. | | PLURNK_EXECS_SEARCH_LANGUAGE | no | SearXNG default. | | PLURNK_EXECS_SEARCH_ENGINES | no | Exclusive SearXNG engine selection; replaces the runtime category. | | PLURNK_EXECS_SEARCH_LIMIT | no | .env.defaults supplies 12 candidates. | | PLURNK_EXECS_SEARCH_TIMEOUT | no | Consumer cancellation is the primary deadline; this is an extra local ceiling in milliseconds. | | PLURNK_EXECS_SEARCH_SAFESEARCH | no | Instance default; accepted values are 0, 1, or 2. | | PLURNK_EXECS_SEARCH_SNIPPET | no | Snippets are unbounded. | | PLURNK_EXECS_SEARCH_QUERY_PREVIEW | no | .env.defaults supplies 120 characters for error facts. | | PLURNK_EXECS_SEARCH_RAW | no | Truthy emits capped upstream result rows and skips projection and prefetch for debugging. |

Page-fetch knobs belong to the consumer and schemes-http because the executor does not fetch result pages ({§executor-entry-sink}).

Page prefetch

The executor emits the digest but never fetches. It hands each unique candidate URL to entry(url, null, { tags: [slug] }); the consumer acquires, MIME-projects, and materializes the https:// entry behind its own URL check. Generic public HTML becomes Tavily Markdown when the HTTP scheme is configured for Tavily; otherwise the installed HTML reader supplies the local projection floor.

• Materialized: entry() resolves — the row carries materialized: true; its body lives in the ordinary HTTP entry.
• Unavailable body: entry() rejects for any reason — the row is omitted from the model-facing digest.
• No sink: every candidate rides the digest and the materialized field is omitted because no verdict exists.

Discovery membership and rank belong to SearXNG. Plurnk does not rerank or judge result quality; it only removes rows whose pages did not materialize, preserving the upstream order of the survivors.

Output

Writes a compact ranked digest—{ title, url, snippet, materialized? } per result, plus publishedDate when present—as JSON to #results under the emitted search://-family address ({§executor-output-address}). The digest is bounded by PLURNK_EXECS_SEARCH_LIMIT; successful page bodies live in materialized HTTP entries rather than this stream. Every emitted row names an ordinary readable entry.

Search is a read effect, so it bypasses proposal review and still returns through the ordinary background stream path ({§executor-effect}).

Failures return RFC 9457 Problems in the terminal operation result. Bounded aggregate acquisition progress remains a transient Notice.

Tests

test:lint, test:unit.