@omnicross/core 0.2.0 → 0.2.1

package/dist/runtime-t8AZacFF.d.ts

@@ -0,0 +1,233 @@
+import { SearchProviderContribution, SearchContributionContext, SearchProviderId, SearchPolicy, SearchRuntimeEvent, SearchRequest, OrchestratedSearchResponse, SearchProviderDescriptor } from '@omnicross/contracts/search-types';
+
+/**
+ * The search provider registry — one place that knows which providers exist.
+ *
+ * Registration is by CONTRIBUTION, not by class: a provider arrives with its
+ * `source` and `kind` declared, so nothing downstream has to guess a trust
+ * boundary from an id's spelling. That is what makes this registry usable by a
+ * Phase-2 host unchanged — Elftia's `local-*` providers register through the
+ * same call an Omnicross builtin does, with `source: 'host'` stated.
+ *
+ * Two rules worth stating out loud:
+ *
+ * 1. **Registration failures are NOT search failures.** They throw
+ *    {@link SearchRegistryError}, a plain `Error`, never a
+ *    `SearchProviderError`. The eight-code taxonomy exists so a fallback policy
+ *    can decide what to do next; a duplicate id is a wiring bug with no "next"
+ *    to decide on, and letting it wear a taxonomy code would teach the
+ *    orchestrator to fall back from a programming error.
+ * 2. **Ordering lives here, once.** `list()` is the single answer to "in what
+ *    order do providers come?", which is the scattered decision plan 阶段3
+ *    exists to consolidate.
+ *
+ * @module search/registry
+ */
+
+/**
+ * A registration was rejected.
+ *
+ * Deliberately not a `SearchProviderError`: see rule 1 in the module doc.
+ */
+declare class SearchRegistryError extends Error {
+    constructor(message: string);
+}
+/** Construction-time registry policy. */
+interface SearchProviderRegistryOptions {
+    /**
+     * Allow a `source: 'host'` contribution to replace a registered
+     * `source: 'builtin'` one.
+     *
+     * Default `false` — plan §7.2's default-deny. This is the admin-policy
+     * escape hatch, not a convenience: shadowing a builtin silently changes where
+     * a user's queries are sent.
+     */
+    allowBuiltinOverride?: boolean;
+}
+/**
+ * The registered providers, ordered.
+ *
+ * Not a singleton: a runtime owns one. Tests, hosts, and future multi-tenant
+ * assemblies each get their own without global state to reset.
+ */
+declare class SearchProviderRegistry {
+    private readonly entries;
+    private readonly allowBuiltinOverride;
+    private nextSequence;
+    constructor(options?: SearchProviderRegistryOptions);
+    /**
+     * Register one provider.
+     *
+     * @param contribution - the provider with its origin, transport, and
+     *   capabilities declared.
+     * @param context - who is registering, for a Phase-2 host. Retained as-is;
+     *   no rule reads it today, and the parameter exists so adding one later is
+     *   not a signature change for every caller.
+     * @throws {SearchRegistryError} on a blank id, a duplicate id, or a host
+     *   contribution colliding with a builtin without `allowBuiltinOverride`.
+     */
+    register(contribution: SearchProviderContribution, context?: SearchContributionContext): void;
+    /** Whether an id is currently registered. */
+    has(id: SearchProviderId): boolean;
+    /** The contribution registered under `id`, if any. */
+    get(id: SearchProviderId): SearchProviderContribution | undefined;
+    /**
+     * Remove a provider.
+     *
+     * The Phase-2 host-disconnect hook: when a host goes away its contributions
+     * go with it, and the id becomes free to register again.
+     *
+     * @returns whether something was removed.
+     */
+    unregister(id: SearchProviderId): boolean;
+    /**
+     * Every registered contribution, in candidate order.
+     *
+     * `priorityHint` ascending; contributions without a hint come AFTER every
+     * hinted one (an absent hint is "no opinion", not "highest priority"); ties
+     * keep registration order. The builtin HTTP contributions carry no hints, so
+     * today this is exactly registration order.
+     */
+    list(): SearchProviderContribution[];
+}
+
+/**
+ * The search orchestrator — the ONE fallback implementation in Omnicross.
+ *
+ * Before this module the repo had three provider orders (the host orchestrator,
+ * the HTTP-only service, and `BuiltinToolExecutor`'s own list), which is how a
+ * query could be sent to a provider twice, or to one a policy meant to exclude.
+ * Plan 阶段3's exit condition is that exactly one implementation decides which
+ * provider runs next, and that no request ever falls back twice. Both are
+ * structural here: consumers submit ONE request and get one answer, with no
+ * loop of their own.
+ *
+ * The semantics that are easy to get wrong, stated plainly:
+ *
+ * - **An empty result set is a SUCCESS.** A provider that returns `[]` has
+ *   already walked its own candidates and is reporting "nothing found". Treating
+ *   that as a failure would re-conflate the empty-vs-broken distinction 阶段2
+ *   built, so it ends the walk. (A deliberate divergence from Elftia, which
+ *   continues to the next provider on zero results — recorded for 阶段5's
+ *   allowed-differences list.)
+ * - **A pinned provider never falls back.** `request.provider` is a caller's
+ *   explicit choice; silently trying someone else would send the query
+ *   somewhere it was not authorized to go, and would be the second fallback in
+ *   a caller that has its own.
+ * - **Cancellation ends everything immediately.** It is the caller's decision,
+ *   not a provider failure, and must never spend another candidate.
+ *
+ * Observability is emitted here because this is where attempts happen, and it
+ * carries a query HASH only — plan §11.3. No event field can hold query text, a
+ * URL, or result content.
+ *
+ * @module search/orchestrator
+ */
+
+/** Receives runtime events. Exceptions from it are swallowed, never propagated. */
+type SearchRuntimeEventListener = (event: SearchRuntimeEvent) => void;
+/** Construction-time orchestrator configuration. */
+interface SearchOrchestratorOptions {
+    /** Default policy for every search; a per-call policy overrides it field by field. */
+    policy?: SearchPolicy;
+    /** Observability sink (plan §11.3). */
+    onEvent?: SearchRuntimeEventListener;
+}
+/**
+ * A short, one-way key for correlating the events of one query.
+ *
+ * Truncated deliberately: enough to group events, far too little to attack the
+ * preimage of a full query with, and the events channel is the one place a
+ * query must never appear in the clear.
+ */
+declare function hashSearchQuery(query: string): string;
+declare class SearchOrchestrator {
+    private readonly registry;
+    private readonly defaultPolicy;
+    private readonly onEvent?;
+    constructor(registry: SearchProviderRegistry, options?: SearchOrchestratorOptions);
+    /**
+     * Run one search.
+     *
+     * @param request - the query, an optional pinned provider, and per-request
+     *   options. `options` is passed to the provider untouched: providers own
+     *   their own timeouts and the orchestrator adds no second timeout layer.
+     * @param policyOverride - per-request policy, merged field-by-field over the
+     *   orchestrator's default.
+     * @throws {SearchProviderError} when no provider produced a response.
+     */
+    search(request: SearchRequest, policyOverride?: SearchPolicy): Promise<OrchestratedSearchResponse>;
+    /** Resolve the candidate list for one request. */
+    private planCandidates;
+    /** Deliver one event. A listener that throws must never fail a search. */
+    private emit;
+}
+
+/**
+ * `SearchRuntime` — the one high-level entry for search in Omnicross.
+ *
+ * Everything above this line (阶段5's protocol frontends, the daemon, and in
+ * Phase 2 the embedding host) calls `search`, `registerContribution`, and
+ * `listProviders`; nothing above it builds a provider chain, because the moment
+ * two callers can, the fallback order is scattered again. That is the whole
+ * point of plan 阶段3.
+ *
+ * The facade is thin on purpose — a registry, an orchestrator, and the wiring
+ * between them. Policy arrives as an argument (runtime default here,
+ * per-request pinning on the request); nothing in this module reads a config
+ * file or a user setting, which keeps "where does policy come from?" a 阶段5
+ * assembly question rather than a contract baked in now.
+ *
+ * @module search/runtime
+ */
+
+/** How a runtime is assembled. Every field has a documented default. */
+interface SearchRuntimeOptions {
+    /**
+     * Providers to register at construction.
+     *
+     * Defaults to {@link builtinHttpSearchContributions} — the two keyless HTTP
+     * engines. Pass an explicit list (including an empty one) to build a runtime
+     * that has only what the caller supplies.
+     */
+    contributions?: SearchProviderContribution[];
+    /** Default policy for every search. Defaults to fallback on, all allowed, unbounded. */
+    policy?: SearchPolicy;
+    /** Observability listener; receives events carrying a query hash, never a query. */
+    onEvent?: SearchRuntimeEventListener;
+    /** Let a host contribution replace a builtin one. Default-deny, per plan §7.2. */
+    allowBuiltinOverride?: boolean;
+}
+/**
+ * The search entry point.
+ *
+ * Search, registration, and capability discovery in one object, so a consumer
+ * never needs a reference to the registry or the orchestrator underneath.
+ */
+interface SearchRuntime {
+    /**
+     * Run one search.
+     *
+     * @throws {SearchProviderError} when no provider produced a response. An
+     *   empty `results` array is a SUCCESS — a provider reporting that it found
+     *   nothing, which is a different answer from failing to look.
+     */
+    search(request: SearchRequest): Promise<OrchestratedSearchResponse>;
+    /** Add a provider (the Phase-2 host registration path). */
+    registerContribution(contribution: SearchProviderContribution, context?: SearchContributionContext): void;
+    /** Remove a provider; returns whether one was removed. */
+    unregisterContribution(id: SearchProviderId): boolean;
+    /** Serializable descriptors of every registered provider, in candidate order. */
+    listProviders(): SearchProviderDescriptor[];
+}
+/**
+ * Build a runtime.
+ *
+ * Defaults to the builtin HTTP providers with an unrestricted policy: the
+ * deliberate 阶段3 stance, since a sensitive default (one provider, egress
+ * restricted) only becomes meaningful once user-facing configuration exists to
+ * express the choice. Both are reachable today through {@link SearchPolicy}.
+ */
+declare function createSearchRuntime(options?: SearchRuntimeOptions): SearchRuntime;
+
+export { type SearchRuntime as S, SearchOrchestrator as a, type SearchOrchestratorOptions as b, SearchProviderRegistry as c, type SearchProviderRegistryOptions as d, SearchRegistryError as e, type SearchRuntimeEventListener as f, type SearchRuntimeOptions as g, createSearchRuntime as h, hashSearchQuery as i };