mirror-mind 0.0.1 → 0.33.0

package/ts/src/frontDoor/searchRoute.ts

@@ -0,0 +1,166 @@
+import type { WritableDatabase } from "#db/database.ts";
+import { requireString } from "#db/rowDecode.ts";
+import type { EmbeddingProvider } from "#providers/embedding.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { SEARCH_TRANSPORT } from "#providers/transport.ts";
+import type { FreshSearchResult } from "#search/memorySearch.ts";
+import { searchMemoriesWithStatus } from "#search/memorySearch.ts";
+import { optionValue } from "./args.ts";
+import { ICONS } from "./render/icons.ts";
+import { tagsText } from "./render/memories.ts";
+
+// Mirrors Python's cli/memories.py degraded_note wording exactly (AI-04),
+// including under a degraded search with zero results.
+const DEGRADED_NOTE =
+  "⚠ Degraded: lexical-only search (embedding unavailable — offline or no API key).";
+
+export interface SearchMemoryRow {
+  id: string;
+  memory_type: string;
+  layer: string;
+  title: string;
+  content: string;
+  created_at: string;
+  journey: string | null;
+  tags: string | null;
+}
+
+/**
+ * Resolve the embedding provider by the same precedence the router used
+ * (CV22.DS8.US1), so the route can never disagree with the routing decision
+ * about which transport is in play.
+ */
+export async function resolveSearchEmbeddingProvider(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<EmbeddingProvider> {
+  // The live provider resolves its config lazily, so a missing key surfaces
+  // inside searchMemoriesWithStatus and degrades to lexical-only rather than
+  // failing the command -- Python's behavior for an unconfigured install.
+  const family = await resolveFamilyProviders(env, SEARCH_TRANSPORT);
+  if (!family.embedding) {
+    // The search family declares an embedding fixture, so replay and live both
+    // build one; this is defense in depth, not a reachable state.
+    throw new Error("memories --search requires an embedding provider");
+  }
+  return family.embedding;
+}
+
+export interface MemorySearchRouteOptions {
+  /** Receives a content-free degraded category for the front-door log. */
+  onDegraded?: (detail: string) => void;
+}
+
+export async function runMemorySearchRoute(
+  db: WritableDatabase,
+  args: readonly string[],
+  options: MemorySearchRouteOptions = {},
+): Promise<string> {
+  const query = optionValue(args, "--search");
+  if (!query) throw new Error("memories --search requires a query");
+  const provider = await resolveSearchEmbeddingProvider();
+  const limit = Number(optionValue(args, "--limit") ?? 20);
+  const { results, degraded, degradedKind } = await searchMemoriesWithStatus(db, {
+    query,
+    limit,
+    memoryType: optionValue(args, "--type"),
+    layer: optionValue(args, "--layer"),
+    journey: optionValue(args, "--journey"),
+    provider,
+    // An exploratory CLI search is not a genuine context load, so it must not
+    // reinforce: `access_count` feeds `reinforcement_score` and the hybrid
+    // ranker, and a ranker fed by its own exhaust drifts toward whatever was
+    // searched for rather than whatever was used (AI-12). Python's
+    // `cli/memories.py` has passed `log_access=False` since 2026-07-16; this
+    // port did not, and reinforced on every `memories --search` from the flip
+    // until CV22.DS9.US2 measured it. Builder context load deliberately keeps
+    // the default and still reinforces -- that one IS a genuine load.
+    logAccess: false,
+  });
+  // A degraded live search is the one failure an operator has to diagnose
+  // without a re-run, so the taxonomy class reaches the front-door log rather
+  // than dying inside the degrade path. Category only -- never a message,
+  // never the query (RS005/CR026).
+  if (degraded && degradedKind) {
+    options.onDegraded?.(`embedding_degraded kind=${degradedKind}`);
+  }
+  const rows = memoriesById(
+    db,
+    results.map((result) => result.id),
+  );
+  return formatSearchResults(query, results, rows, degraded);
+}
+
+/**
+ * Pure rendering of a fresh-search outcome (AI-04). Split out from
+ * `runMemorySearchRoute` so the degraded/normal render branches are directly
+ * unit-testable without a database or a live-failing embedding provider (none
+ * exists yet -- see CR037 plan).
+ */
+export function formatSearchResults(
+  query: string,
+  results: readonly FreshSearchResult[],
+  rows: ReadonlyMap<string, SearchMemoryRow>,
+  degraded: boolean,
+): string {
+  if (results.length === 0) {
+    return degraded ? `${DEGRADED_NOTE}\n` : "No memories found.\n";
+  }
+  const lines: string[] = [];
+  if (degraded) {
+    lines.push(`${DEGRADED_NOTE} Ranked by keyword match.`, "");
+  }
+  lines.push(`🔍 Search: "${query}" (${results.length} results)`, "");
+  for (const result of results) {
+    const memory = rows.get(result.id);
+    if (!memory) continue;
+    const icon = ICONS[memory.memory_type] ?? "•";
+    const date = memory.created_at ? memory.created_at.slice(0, 10) : "?";
+    const journey = memory.journey ? ` 🧭 ${memory.journey}` : "";
+    const tags = tagsText(memory.tags);
+    lines.push(`${icon} **${memory.title}** (score: ${result.score.toFixed(3)})`);
+    lines.push(
+      `  ${date} | \`${memory.id.slice(0, 8)}\` | ${memory.memory_type} [${memory.layer}]${journey}`,
+    );
+    lines.push(`  ${memory.content.slice(0, 200)}`);
+    if (tags) lines.push(`  🏷 ${tags}`);
+    lines.push("");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The row reader both search faces share.
+ *
+ * Exported for `build load` (CV22.DS7.US8 plateau 7), which renders the same
+ * memories from the same ranked ids: the ranker returns `{id, score}` only, so a
+ * second copy of this query is a second chance for the two blocks to disagree
+ * about what a memory says.
+ */
+export function memoriesById(
+  db: WritableDatabase,
+  ids: readonly string[],
+): Map<string, SearchMemoryRow> {
+  if (ids.length === 0) return new Map();
+  const placeholders = ids.map(() => "?").join(", ");
+  const rows = db
+    .prepare(
+      `SELECT id, memory_type, layer, title, content, created_at, journey, tags FROM memories ` +
+        `WHERE id IN (${placeholders})`,
+    )
+    .all(...ids);
+  return new Map(
+    rows.map((row) => [
+      requireString(row, "id"),
+      {
+        id: requireString(row, "id"),
+        memory_type: requireString(row, "memory_type"),
+        layer: requireString(row, "layer"),
+        title: requireString(row, "title"),
+        content: requireString(row, "content"),
+        created_at: requireString(row, "created_at"),
+        journey: typeof row.journey === "string" ? row.journey : null,
+        tags: typeof row.tags === "string" ? row.tags : null,
+      },
+    ]),
+  );
+}

package/ts/src/frontDoor/seedPaths.ts

@@ -0,0 +1,98 @@
+// `seed` path resolution — the port of the bespoke resolution inside
+// memory.cli.seed.seed(), which is NOT the same precedence chain
+// `resolveDbPath` (dbPath.ts) uses for every other command. Verified against
+// the live oracle (never assumed) because it diverges in a genuinely
+// surprising way:
+//
+// - `identity_root`/`mirror_home` resolve via `--mirror-home` or the plain
+//   MIRROR_HOME/MIRROR_USER chain (`resolveMirrorHome`) -- completely
+//   independent of `--env`, `MEMORY_DIR`, or `DB_PATH`.
+// - When `--mirror-home` IS given, the database path is ALWAYS
+//   `<mirror_home>/memory.db` -- `--env` is silently ignored for the
+//   filename (`default_db_path_for_home` hardcodes "memory.db"). Confirmed
+//   live: `seed --mirror-home X --env test` writes `X/memory.db`, not
+//   `X/memory_test.db`.
+// - When `--mirror-home` is absent and `--env` differs from the ambient
+//   `MEMORY_ENV` (or ambient is unset, defaulting "production" like Python's
+//   module-level MEMORY_ENV constant), the database path follows
+//   `db_path_for_env`: MEMORY_PROD_DIR (production only) > MEMORY_DIR > the
+//   resolved mirror home, with the env-appropriate filename -- but WITHOUT
+//   checking `DB_PATH` (that env var is only wired to the *ambient*
+//   environment in Python, cached once at import time).
+// - When `--mirror-home` is absent and `--env` matches the ambient
+//   `MEMORY_ENV` (or is omitted), the database path follows the SAME full
+//   generic chain every other command uses (`require_db_path()` ==
+//   `resolveDbPath`).
+//
+// `--db-path` is a TS-front-door-only convenience (Python's `seed` CLI has no
+// such flag), kept here for consistency with every other ported command --
+// it wins over everything, as documented in dbPath.ts.
+
+import { join } from "node:path";
+import { expandHome } from "#util/paths.ts";
+import { optionValue } from "./args.ts";
+import {
+  type DbPathEnv,
+  type DbPathIo,
+  dbNameForEnv,
+  MirrorHomeNotConfiguredError,
+  resolveDbPath,
+  resolveMirrorHome,
+} from "./dbPath.ts";
+
+export interface SeedPaths {
+  dbPath: string;
+  identityRoot: string;
+  mirrorHome: string;
+  env: string;
+}
+
+/**
+ * Resolve `seed`'s database path, identity root, mirror home, and effective
+ * env, mirroring the Python branches documented above exactly. Throws
+ * MirrorHomeNotConfiguredError when nothing resolves (mapped to exit 2 by the
+ * caller, matching every other command's unconfigured-home contract).
+ */
+export function resolveSeedPaths(
+  args: readonly string[],
+  env: DbPathEnv = process.env,
+  io: DbPathIo = {},
+): SeedPaths {
+  const explicitDbPath = optionValue(args, "--db-path");
+  const explicitMirrorHome = optionValue(args, "--mirror-home");
+  const envFlag = optionValue(args, "--env");
+  const ambientEnv = env.MEMORY_ENV || "production";
+  const effectiveEnv = envFlag || ambientEnv;
+
+  const mirrorHome = explicitMirrorHome
+    ? expandHome(explicitMirrorHome)
+    : resolveMirrorHome(env, io);
+  const identityRoot = join(mirrorHome, "identity");
+
+  if (explicitDbPath) {
+    return { dbPath: expandHome(explicitDbPath), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  if (explicitMirrorHome) {
+    // default_db_path_for_home: ALWAYS "memory.db", --env is not consulted.
+    return { dbPath: join(mirrorHome, "memory.db"), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  if (envFlag && envFlag !== ambientEnv) {
+    const dbName = dbNameForEnv(envFlag);
+    let dir: string;
+    if (envFlag === "production" && env.MEMORY_PROD_DIR) {
+      dir = expandHome(env.MEMORY_PROD_DIR);
+    } else if (env.MEMORY_DIR) {
+      dir = expandHome(env.MEMORY_DIR);
+    } else {
+      dir = mirrorHome;
+    }
+    return { dbPath: join(dir, dbName), identityRoot, mirrorHome, env: effectiveEnv };
+  }
+  // require_db_path(): by construction neither --db-path nor --mirror-home is
+  // present here, so this is exactly resolveDbPath's own DB_PATH ->
+  // MEMORY_PROD_DIR -> MEMORY_DIR -> resolved-mirror-home chain -- the same
+  // one every other command uses. Reused directly rather than re-implemented.
+  return { dbPath: resolveDbPath(args, env, io), identityRoot, mirrorHome, env: effectiveEnv };
+}
+
+export { MirrorHomeNotConfiguredError };

package/ts/src/frontDoor/sessionStartWelcomeRoute.ts

@@ -0,0 +1,166 @@
+// `conversation-logger session-start --fast --welcome --format json` (CV9.E2.S32).
+//
+// The Pi extension used to open a session with three awaited front-door
+// processes in a row -- `session-start --fast`, `welcome`, and
+// `welcome --status-line` -- paying the loader's fixed cost three times
+// before the user could type. They cannot run in parallel: the first WRITES
+// the orientation the other two READ. They can run in one process, as long as
+// the write commits before the reads. This route is that sequencing and
+// nothing else.
+//
+// What it deliberately does not do:
+//
+//   * It does not teach `loggerCli.ts` to render a welcome card. That module
+//     is the conversation domain; composition across domains is this layer's
+//     job.
+//   * It does not touch `runWelcomeRoute`'s read-only contract. Both renders
+//     run through that route with captured io, AFTER the write handle has
+//     closed, so the card and the status line are byte-identical to the
+//     standalone commands and never share the live write lock with the
+//     card's bounded update check.
+//   * It has no text form. The card is free text; the only safe delimiter is
+//     a JSON envelope.
+//
+// The envelope is for the extension, not for a skill. A skill that called this
+// would put card text in front of the model through a channel the Ariad
+// surface rules do not cover; `checkSkillCommandParity.ts` refuses the flag in
+// every SKILL.md.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { runConversationLoggerRoute } from "./conversationLoggerRoute.ts";
+import { runWelcomeRoute } from "./runtimeRoute.ts";
+
+export const SESSION_START_WELCOME_SCHEMA_VERSION = "1.0.0";
+
+export interface SessionStartWelcomeEnvelope {
+  schemaVersion: typeof SESSION_START_WELCOME_SCHEMA_VERSION;
+  /** The logger's stdout lines, joined with `\n`: what `session-start --fast` prints. */
+  sessionStart: string;
+  /** `mirror welcome`'s stdout minus the trailing newline; `""` when disabled. */
+  welcome: string;
+  /** `mirror welcome --status-line`'s stdout minus the trailing newline; `""` when empty. */
+  statusLine: string;
+}
+
+export interface SessionStartWelcomeOutcome {
+  exitCode: number;
+  /** Content-free category for the front-door log when a render failed after the write. */
+  detail?: string;
+}
+
+export interface SessionStartWelcomeDeps {
+  /** The real write path: opens the live write database, runs `write`, closes it. */
+  withMirrorWriteDb: (
+    argv: readonly string[],
+    write: (db: WritableDatabase, dbPath: string) => Promise<number> | number,
+  ) => Promise<number>;
+  /**
+   * The welcome renderer. Defaults to the real route; the render-failure test
+   * injects one that throws. The write path is never injected: it is the real
+   * one in every test.
+   */
+  renderWelcome?: typeof runWelcomeRoute;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+/** Only the `--fast --welcome` composite answers here; everything else is the plain logger route. */
+export function isSessionStartWelcome(argv: readonly string[]): boolean {
+  return (
+    argv[0] === "conversation-logger" &&
+    argv.includes("session-start") &&
+    argv.includes("--welcome")
+  );
+}
+
+function optionValue(args: readonly string[], name: string): string | null {
+  const index = args.indexOf(name);
+  if (index === -1) return null;
+  return args[index + 1] ?? null;
+}
+
+/** The logger's `--mirror-home` reaches the welcome renders too, so both read the same home. */
+function welcomeArgv(argv: readonly string[], statusLine: boolean): string[] {
+  const out = ["welcome"];
+  if (statusLine) out.push("--status-line");
+  const home = optionValue(argv, "--mirror-home");
+  if (home !== null) out.push("--mirror-home", home);
+  const sessionId = optionValue(argv, "--session-id");
+  if (statusLine && sessionId !== null) out.push("--session-id", sessionId);
+  return out;
+}
+
+/** The logger's own argv: the composite flags removed, `--format`'s value with it. */
+function withoutCompositeFlags(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i] as string;
+    if (arg === "--welcome") continue;
+    if (arg === "--format") {
+      i += 1;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
+export async function runSessionStartWelcomeRoute(
+  argv: readonly string[],
+  deps: SessionStartWelcomeDeps,
+): Promise<SessionStartWelcomeOutcome> {
+  const stdout = deps.stdout ?? ((text: string) => process.stdout.write(text));
+  const stderr = deps.stderr ?? ((text: string) => process.stderr.write(text));
+  const renderWelcome = deps.renderWelcome ?? runWelcomeRoute;
+
+  if (!argv.includes("--fast")) {
+    stderr("session-start: --welcome requires --fast (the full session-start runs maintenance)\n");
+    return { exitCode: 2 };
+  }
+  const format = optionValue(argv, "--format");
+  if (format !== "json") {
+    stderr(
+      "session-start: --welcome requires --format json (the card has no safe text delimiter)\n",
+    );
+    return { exitCode: 2 };
+  }
+
+  // 1. The write, through the real path. Its handle is closed when this returns.
+  const loggerArgv = withoutCompositeFlags(argv);
+  const sessionStartLines: string[] = [];
+  const exitCode = await deps.withMirrorWriteDb(loggerArgv, (db, dbPath) =>
+    runConversationLoggerRoute(db, dbPath, loggerArgv, {
+      stdout: (line) => sessionStartLines.push(line),
+      // The logger's refusals keep going to stderr, as they do standalone.
+      stderr: (line) => stderr(`${line}\n`),
+    }),
+  );
+  if (exitCode !== 0) return { exitCode };
+
+  // 2. The reads, after the write committed and its handle closed. A render
+  //    failure must not lose the unmute: the envelope still goes out, with the
+  //    failed field empty, and the category reaches the front-door log.
+  let detail: string | undefined;
+  const render = (statusLine: boolean): string => {
+    let captured = "";
+    try {
+      renderWelcome(welcomeArgv(argv, statusLine), { stdout: (text) => (captured += text) });
+    } catch (error) {
+      detail = `render-failed=${error instanceof Error ? error.name : "unknown"}`;
+      return "";
+    }
+    return stripTrailingNewline(captured);
+  };
+  const envelope: SessionStartWelcomeEnvelope = {
+    schemaVersion: SESSION_START_WELCOME_SCHEMA_VERSION,
+    sessionStart: sessionStartLines.join("\n"),
+    welcome: render(false),
+    statusLine: render(true),
+  };
+  stdout(`${JSON.stringify(envelope)}\n`);
+  return detail ? { exitCode: 0, detail } : { exitCode: 0 };
+}