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
8.1 KB
Raw Blame
/**
 * Snake_case wire serializers shared by the CLI (`o2b search`) and MCP
 * (`brain_search`) surfaces, so the two output contracts cannot drift
 * field-by-field the way independently hand-written copies do.
 */

import type { StampMismatch } from "../integrity/stamp.ts";
import type {
  ChunkWindowCensus,
  EmbedderRecordCensus,
  IndexStatusSnapshot,
  PendingVectorCensus,
  SearchCard,
  VisibilityHonestyFinding,
} from "./types.ts";

/**
 * Wire shape for a stamp comparison. `recorded` is what the index
 * wrote, `runtime` what this build would write; a `recorded` of `null`
 * is a field the index never stamped. Shared by `o2b search check`,
 * `o2b search status --json` and the MCP `search.*` status block, so
 * one drift cannot be described three ways.
 */
export function serializeStampMismatches(
  mismatches: ReadonlyArray<StampMismatch>,
): Array<Record<string, unknown>> {
  return mismatches.map((m) => ({
    field: m.field,
    recorded: m.expected,
    runtime: m.actual,
  }));
}

/** Layer-1 card projection - identical shape on both the CLI and MCP surfaces. */
export function serializeSearchCard(c: SearchCard): Record<string, unknown> {
  return {
    path: c.path,
    title: c.title,
    score: c.score,
    snippet: c.snippet,
    pointer: c.pointer,
    reasons: c.reasons,
    document_id: c.documentId,
    chunk_id: c.chunkId,
    ...(c.origin !== undefined ? { origin: c.origin } : {}),
    // Exact-duplicate merge (task D): the `path:Lstart-Lend` pointers the
    // surviving card was folded from. Absent, never null, when nothing
    // was merged - the card carries the key only in that case.
    ...(c.duplicatePointers !== undefined ? { duplicate_pointers: c.duplicatePointers } : {}),
  };
}

/**
 * Wire shape of the pending-vector census (nothing-writes-silently,
 * unit A). Emitted in EVERY state, which is what separates it from the
 * drift fields on the same report: those say nothing when there is
 * nothing to say, while a census whose count could not be taken has
 * something to say precisely then. The unrecorded arm carries no
 * `pending` key at all, so a consumer cannot read a default zero out of
 * a state that measured nothing.
 */
export function serializePendingVectorCensus(census: PendingVectorCensus): Record<string, unknown> {
  if (census.verdict === "unrecorded") {
    return { verdict: census.verdict, reason: census.reason };
  }
  return { verdict: census.verdict, pending: census.pending, chunks: census.chunks };
}

/**
 * Wire shape of the record-vs-data embedder audit
 * (nothing-writes-silently, unit G). Emitted in every state on the same
 * terms as the pending-vector census beside it, and the `unrecorded`
 * arm carries no numbers at all - there is no dimension to report when
 * nothing was compared.
 *
 * `reconciliation` keeps the shared vocabulary's own field names, so a
 * consumer reading this audit and one reading the import census read
 * the same three words for the same three quantities.
 */
export function serializeEmbedderRecordCensus(
  census: EmbedderRecordCensus,
): Record<string, unknown> {
  if (census.verdict === "unrecorded") {
    return { verdict: census.verdict, reason: census.reason };
  }
  return {
    verdict: census.verdict,
    outcome: census.outcome,
    recorded_dimension: census.recordedDimension,
    stored_dimensions: census.storedDimensions,
    vec_declared_width: census.vecDeclaredWidth,
    reconciliation: {
      attempted: census.reconciliation.attempted,
      found: census.reconciliation.found,
      missing: census.reconciliation.missing,
    },
  };
}

/**
 * Wire shape of the visibility honesty finding (nothing-writes-silently,
 * unit H, form B). Present only when the caller already established
 * there is something to report - `search check` omits the key entirely
 * rather than serializing a zero-count finding, the same convention
 * `embeddingAbi` uses for a matching store.
 */
export function serializeVisibilityHonestyFinding(
  finding: VisibilityHonestyFinding,
): Record<string, unknown> {
  return {
    excluded_surface_count: finding.excludedSurfaceCount,
    total_surface_count: finding.totalSurfaceCount,
    reserved_document_count: finding.reservedDocumentCount,
    unmeasured_document_count: finding.unmeasuredDocumentCount,
  };
}

/**
 * Wire shape of an oversize-chunk census verdict, shared by the index
 * run's report and the status snapshot so the two cannot describe one
 * verdict with different field names.
 *
 * No `next_command` here: whether a surface names an exit beside a
 * verdict is that surface's decision, and the index run spreads its own
 * on top. Baking one in would put a command on the status field the
 * ruling deliberately keeps out of the warning channel.
 */
export function serializeChunkWindowCensus(census: ChunkWindowCensus): Record<string, unknown> {
  if (census.verdict === "window-undeclared") {
    return {
      verdict: census.verdict,
      model: census.model,
      chunks_measured: census.chunksMeasured,
    };
  }
  if (census.verdict === "estimate-undecided") {
    // No `chunks_over_window` here on the same terms the undeclared
    // verdict carries no window: nothing was proved over it.
    return {
      verdict: census.verdict,
      model: census.model,
      window_tokens: census.windowTokens,
      chunks_undecided: census.chunksUndecided,
      chunks_measured: census.chunksMeasured,
    };
  }
  return {
    verdict: census.verdict,
    model: census.model,
    window_tokens: census.windowTokens,
    chunks_over_window: census.chunksOverWindow,
    // Absent, never zero - an index the estimate decided in full emits
    // the record it emitted before the undecided band existed.
    ...(census.chunksUndecided === undefined ? {} : { chunks_undecided: census.chunksUndecided }),
    chunks_measured: census.chunksMeasured,
  };
}

/**
 * Full snake_case index-status mapping. The CLI surfaces every field; the
 * MCP block (token-budget conscious) picks a subset of the returned object
 * rather than re-declaring the mapping.
 */
export function serializeIndexStatus(s: IndexStatusSnapshot): Record<string, unknown> {
  return {
    index_path: s.indexPath,
    exists: s.exists,
    schema_version: s.schemaVersion,
    documents: s.documents,
    chunks: s.chunks,
    embeddings: s.embeddings,
    stale_embeddings: s.staleEmbeddings,
    embedding_model: s.embeddingModel,
    embedding_dimension: s.embeddingDimension,
    embedding_signature: s.embeddingSignature,
    estimated_refresh_cost_usd: s.estimatedRefreshCostUsd,
    refresh_price_source: s.refreshPriceSource,
    vec_extension: s.vecExtension,
    semantic_enabled: s.semanticEnabled,
    embedding_key_present: s.embeddingKeyPresent,
    last_indexed_at: s.lastIndexedAt,
    last_full_index_at: s.lastFullIndexAt,
    // Emitted only on drift, so a matching store's JSON is byte-identical
    // to the pre-gate output (context-integrity-gates, Unit E).
    ...(s.embeddingAbi.length > 0
      ? { embedding_abi: serializeStampMismatches(s.embeddingAbi) }
      : {}),
    // Emitted only when the oversize-chunk census could NOT run, on the
    // same terms and for the same reason: a status over a model with a
    // declared window is byte-identical to the pre-census output. The
    // two verdicts the census reaches by measuring - overflow, and the
    // band its estimate cannot decide - are not here; both are warnings,
    // because both name a command.
    ...(s.chunkWindowUndeclared === undefined
      ? {}
      : { chunk_window_undeclared: serializeChunkWindowCensus(s.chunkWindowUndeclared) }),
    // The same terms as the census field above: present only when the
    // index actually holds chunks under the active key, so a status with
    // nothing held serializes the bytes it emitted before this existed.
    ...(s.heldChunks === undefined
      ? {}
      : {
          held_chunks: {
            total: s.heldChunks.total,
            items: s.heldChunks.items.map((item) => ({
              path: item.path,
              chunk_index: item.chunkIndex,
              estimated_tokens: item.estimatedTokens,
              window_tokens: item.windowTokens,
              reason: item.reason,
            })),
          },
        }),
    warnings: s.warnings,
  };
}