Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
14.3 KB
Raw Blame
/**
 * Semantic candidate lane: the on/off policy the caller's options resolve
 * to, the candidate-pool over-fetch sizing, and the guarded semantic
 * phase that embeds the query and runs the vector top-K (self-degrading
 * to keyword-only with warnings when the lane cannot run).
 */

import {
  BLOCKED_TIER_ERROR_CODE,
  isBlockedCapability,
  resolveSemanticCapability,
  semanticCapabilityLabel,
  SEMANTIC_CAPABILITY_TIER,
} from "./capability-tier.ts";
import { classifyEmbeddingError } from "./embeddings/openai-compat.ts";
import { makeProvider } from "./embeddings/provider.ts";
import {
  prepareQueryEmbed,
  queryEmbedCutMessage,
  queryEmbedEmptyFitMessage,
  queryEmbedRefusalMessage,
} from "./embeddings/query-embed.ts";
import { providerConsentIsDeclined, resolveProviderConsent } from "./provider-consent.ts";
import { RETRIEVAL_DEGRADATION, noteDegradation } from "./retrieval-trail.ts";
import { Store } from "./store.ts";
import { EMBEDDING_QUOTA_MESSAGE, SearchError } from "./types.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
import type { PropertyPushdown } from "./property-pushdown.ts";
import type { RetrievalDegradationSink } from "./retrieval-trail.ts";
import type { ResolvedSearchConfig, SearchOptions } from "./types.ts";

export interface SemanticPolicy {
  /** caller asked for semantic on or off (true), or accepted the default (false). */
  readonly explicit: boolean;
  /** does the caller want semantic at all? */
  readonly wantSemantic: boolean;
}

export function resolveSemanticPolicy(
  config: ResolvedSearchConfig,
  opts: SearchOptions,
): SemanticPolicy {
  if (opts.keywordOnly === true) {
    return { explicit: true, wantSemantic: false };
  }
  if (opts.semantic === true) return { explicit: true, wantSemantic: true };
  if (opts.semantic === false) return { explicit: true, wantSemantic: false };
  return { explicit: false, wantSemantic: config.semantic.enabled };
}

/**
 * Semantic candidate-pool over-fetch policy: rank more than `limit` rows
 * so downstream filtering (property/visibility scope, MMR diversify) has
 * enough headroom to still fill the final window. `floor` is the minimum
 * pool size regardless of `limit`; `overfetch` is the multiplier applied
 * to `limit` itself.
 */
const POOL_OVERFETCH = 5;
const POOL_FLOOR = 50;

export function semanticPoolSize(limit: number): number {
  return Math.max(limit * POOL_OVERFETCH, POOL_FLOOR);
}

/**
 * The embed interval the phase stamps for the overlapped-lane timing
 * (recall-lane-latency). A plain mutable record the JOIN caller owns: the
 * lane forwards it, the phase writes it around the one caller wait it
 * has, and the caller reads it at the join. Absent stamps mean the embed
 * never ran - a pre-flight guard refused before any provider existed.
 */
export interface SemanticEmbedTiming {
  /**
   * The request's clock port: every stamp below reads through it, so the
   * wall clock is read nowhere but the request module (the rank-clock
   * census pins the site) and no stamp precedes the instant the request
   * was resolved at.
   */
  readonly clock: () => number;
  /**
   * The dispatch stamp: written by the provider's dispatch report, the
   * moment the request actually leaves. A provider that never reports a
   * dispatch leaves it unset, and the fold falls back to the pre-call
   * stamp.
   */
  embedStartMs?: number;
  /**
   * The resolution stamp: written when the phase's continuation around
   * the provider promise ran - the answer or the failure came back. It
   * is never a claim about any wire event past the call's own return.
   */
  embedEndMs?: number;
  /**
   * The pre-call fallback start: stamped just before the provider call
   * for providers that never report a dispatch, so their interval stays
   * the whole awaited call, as before the dispatch report existed.
   */
  preCallStartMs?: number;
}

interface SemanticPhaseOutcome {
  readonly attempted: boolean;
  readonly hits: ReturnType<Store["semanticTopK"]>;
  readonly warnings: string[];
  /**
   * The typed half of {@link warnings} (evidence-at-the-boundary, C2).
   * Every arm below that returns `attempted: false` names why it did, so
   * a caller served keyword-only can tell an unconfigured provider from a
   * quota-exhausted one without matching on a sentence.
   */
  readonly degraded: RetrievalDegradationSink;
}

export async function runSemanticPhase(
  store: Store,
  config: ResolvedSearchConfig,
  query: string,
  opts: {
    limit: number;
    pathPrefix: string | undefined;
    /** Chunk-kind pushdown (recall-quality, C4); absent leaves it unfiltered. */
    readonly kind?: "page" | "section";
    /** Promoted property pushdown (recall-quality, C4); absent leaves it unfiltered. */
    readonly pushdown?: PropertyPushdown;
    explicit: boolean;
    /**
     * The caller's cancellation (the composite hybrid deadline). Once it
     * aborts, the query embed stops and the phase rejects with the
     * signal's reason, so an abandoned lane never reaches the store.
     */
    signal?: AbortSignal;
    /**
     * How far the caller reached (`SearchOptions.transportReach`). The
     * query-embed gateway reads it: absent resolves to remote, as
     * everywhere else in the tree.
     */
    transportReach?: TransportReach;
    /**
     * The embed-interval record to stamp (recall-lane-latency), written
     * around the embed await. Absent records nothing.
     */
    timing?: SemanticEmbedTiming;
  },
): Promise<SemanticPhaseOutcome> {
  const warnings: string[] = [];
  const degraded: RetrievalDegradationSink = [];

  // The operator's WRITTEN decision comes before every other arm, and
  // before the capability ladder below. A decline is a more specific fact
  // than a tier: the tier says what the configuration can do, and it
  // cannot say that the operator said no. Reporting the tier for a
  // declined vault would answer "not configured" for a configuration that
  // was configured on purpose - and the sentence it would use is the one
  // that tells an operator to set a provider they deliberately declined.
  //
  // The record is read from the SAME configuration the search
  // configuration was resolved from (`config.configPath`), so the two can
  // never disagree about which file is in force.
  const consent = resolveProviderConsent({
    configPath: config.configPath ?? null,
    env: process.env,
    semantic: config.semantic,
  });
  if (providerConsentIsDeclined(consent)) {
    if (opts.explicit) throw new SearchError("EMBEDDING_DISABLED", consent.detail);
    warnings.push(consent.detail);
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCapabilityBlocked, {
      tier: SEMANTIC_CAPABILITY_TIER.disabled,
    });
    return { attempted: false, hits: [], warnings, degraded };
  }

  const counts = store.counts();
  if (counts.embeddings === 0) {
    warnings.push("no compatible embeddings; run: o2b search index --embeddings");
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticEmbeddingsAbsent);
    return { attempted: false, hits: [], warnings, degraded };
  }

  if (!store.vecLoaded()) {
    if (opts.explicit) {
      throw new SearchError(
        "VEC_EXTENSION_UNAVAILABLE",
        "semantic search unavailable: sqlite-vec extension not loaded",
      );
    }
    warnings.push("sqlite-vec unavailable, semantic disabled this session");
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticVecExtensionUnavailable);
    return { attempted: false, hits: [], warnings, degraded };
  }
  // What the OPERATOR CONFIGURED, from the one shared resolver
  // (provenance-at-the-boundary, F1). The two runtime guards above stay
  // where they are: an empty vector table and a missing extension are
  // facts about this index and this machine, not about the configuration.
  //
  // The explicit arm is the one that ATTEMPTED something and could not,
  // so it keeps reporting the typed `SearchError`; the implicit arm
  // refused before attempting and reports the capability. Neither
  // condition is reported both ways.
  //
  // EVERY blocked rung throws on the explicit arm, not just the missing
  // credential: a caller who asked for semantic recall in so many words and
  // was served lexical results with exit 0 was told the search succeeded.
  // Both arms name the condition with the SAME registry sentence, so the
  // warning and the error message cannot drift apart.
  const capability = consent.capability ?? resolveSemanticCapability(config.semantic);
  if (isBlockedCapability(capability)) {
    const label = await semanticCapabilityLabel(capability.code);
    if (opts.explicit) throw new SearchError(BLOCKED_TIER_ERROR_CODE[capability.tier], label);
    warnings.push(label);
    // The rung is already a closed vocabulary; the label is a registry
    // sentence, which is exactly what the trail must not carry.
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCapabilityBlocked, {
      tier: capability.tier,
    });
    return { attempted: false, hits: [], warnings, degraded };
  }

  // The query-embed gateway (honest-query-embed-and-safe-upgrades): the
  // one place that decides whether a query embed is sent at all and with
  // what text. It runs before any provider exists, so a refusal sends
  // nothing. The explicit arm throws, like every other condition above
  // that stops a lane the caller asked for by name; the implicit arm
  // degrades by code and the lane is not attempted.
  const prepared = prepareQueryEmbed(config, query, opts.transportReach);
  if (prepared.kind === "refused") {
    const message = queryEmbedRefusalMessage(prepared);
    if (opts.explicit) throw new SearchError(prepared.code, message);
    warnings.push(message);
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticCostUnpriced);
    return { attempted: false, hits: [], warnings, degraded };
  }
  if (prepared.truncated) {
    const detail = { windowTokens: prepared.windowTokens };
    if (prepared.emptyFit) {
      // The instruction prefix alone fills the window: there is no query
      // left to embed, and embedding the prefix would search for nothing.
      const message = queryEmbedEmptyFitMessage(prepared);
      if (opts.explicit) throw new SearchError("INVALID_INPUT", message);
      warnings.push(message);
      noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticQueryEmptyFit, detail);
      return { attempted: false, hits: [], warnings, degraded };
    }
    // A cut the server would otherwise make silently (or refuse), made
    // here and disclosed. The lane still runs on the cut query.
    warnings.push(queryEmbedCutMessage(prepared, query));
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticQueryTruncated, detail);
  }

  let queryVec: number[];
  // The embed start is stamped by the provider's dispatch report - the
  // moment the request actually leaves, which is the instant overlap is
  // measured from. The pre-call stamp below is only the fallback for
  // providers that never report a dispatch (the offline local embedder,
  // or one built before the callback existed): their interval stays the
  // whole awaited call, as before. With no sink there is no stamp and no
  // callback, and the call options are exactly what they were.
  const timing = opts.timing;
  if (timing !== undefined) timing.preCallStartMs = timing.clock();
  try {
    const provider = makeProvider(config.semantic, consent);
    const vectors = await provider.embed(
      [prepared.text],
      "query",
      timing === undefined && opts.signal === undefined
        ? undefined
        : {
            ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
            ...(timing !== undefined
              ? {
                  onDispatch: () => {
                    timing.embedStartMs = timing.clock();
                  },
                }
              : {}),
          },
    );
    if (timing !== undefined) timing.embedEndMs = timing.clock();
    queryVec = vectors[0] ?? [];
  } catch (e) {
    // The interval closes even on the failure arm: the overlap figure
    // stays coherent for a lane that ran and lost its embed.
    if (
      timing !== undefined &&
      (timing.embedStartMs !== undefined || timing.preCallStartMs !== undefined)
    ) {
      timing.embedEndMs = timing.clock();
    }
    if (opts.signal?.aborted === true) throw opts.signal.reason;
    if (opts.explicit) {
      // Defensive: provider methods are expected to throw SearchError,
      // but wrap anything else (e.g. an unexpected runtime failure)
      // so callers always see a typed code rather than a bare Error.
      if (e instanceof SearchError) throw e;
      const msg = e instanceof Error ? e.message : String(e);
      throw new SearchError("EMBEDDING_PROVIDER_HTTP", `embedding provider failure: ${msg}`);
    }
    // Implicit path: degrade to keyword-only, but the warning must say WHY
    // by naming the classification category, and for a quota exhaustion it
    // carries the actionable billing message so the CLI/MCP caller learns
    // the remediation, not just that semantic was skipped.
    const cls = classifyEmbeddingError(e);
    const detail =
      cls.category === "quota"
        ? EMBEDDING_QUOTA_MESSAGE
        : e instanceof Error
          ? e.message
          : String(e);
    warnings.push(`embedding provider unavailable [${cls.category}]: ${detail}`);
    // The category is the classification the warning already computed and
    // then buried in prose; the provider's own message stays out of the
    // trail, which travels into logs and MCP payloads.
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticProviderUnavailable, {
      category: cls.category,
    });
    return { attempted: false, hits: [], warnings, degraded };
  }

  // The caller may have abandoned the lane while the embed was in flight;
  // past that point the store it would read can already be closed.
  if (opts.signal?.aborted === true) throw opts.signal.reason;

  if (queryVec.length === 0) {
    warnings.push("embedding provider returned an empty vector; semantic skipped");
    noteDegradation(degraded, RETRIEVAL_DEGRADATION.semanticEmptyQueryVector);
    return { attempted: false, hits: [], warnings, degraded };
  }

  const hits = store.semanticTopK(queryVec, {
    limit: opts.limit,
    pathPrefix: opts.pathPrefix,
    ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
    ...(opts.pushdown !== undefined ? { pushdown: opts.pushdown } : {}),
  });
  return { attempted: true, hits, warnings, degraded };
}