mirror-mind 0.0.1 → 0.32.1

package/ts/src/frontDoor/cloneRoleGuard.ts

@@ -0,0 +1,98 @@
+// CV22.DS7.US8 plateau 7 — the production-clone guard `build load` runs first.
+//
+// Port of `_is_mirror_mind_checkout` and `_check_clone_role_guard` in
+// `src/memory/cli/build.py`. It lives in the route layer, not in `builder/`,
+// because its inputs are the MACHINE's — a git root, a marker file, a
+// `pyproject.toml` — and `builder/` is graded as a pure port over a database.
+// `runBuildLoad` therefore takes the outcome as an injected seam, which is also
+// what lets the corpus grade the ordering (a refusal prints no banner) without
+// depending on the developer's own checkout.
+//
+// Two behaviors, and the second is easy to miss: `--ignore-production-role` does
+// not skip the guard, it DOWNGRADES it — an orange warning on stderr, and the
+// session start continues. A port that treated the flag as "do not look" would
+// lose the warning, which is the only trace that a Navigator worked in a
+// production clone on purpose.
+
+import { inspectCloneRole } from "#runtime/git.ts";
+import { findPackageIdentity } from "#runtime/packageIdentity.ts";
+
+/** What the guard decided, or null when it has nothing to say. */
+export interface CloneRoleGuardOutcome {
+  /** Bytes for stderr, `print`'s trailing newline included. */
+  readonly stderr: string;
+  /**
+   * The exit code, or null to CONTINUE after printing.
+   *
+   * Python exits **2** here, not 1: the guard is a usage-level refusal, in the
+   * same class as argparse's. Recorded as a value rather than assumed by the
+   * caller, because `runBuildLoad`'s other refusal (an unknown journey) exits 1
+   * and the two are one `if` apart.
+   */
+  readonly exitCode: number | null;
+}
+
+export interface CloneRoleGuardOptions {
+  readonly ignoreProductionRole?: boolean;
+  /** Where the walk starts when the journey has no project path: Python uses `cwd`. */
+  readonly currentDirectory?: string;
+}
+
+/**
+ * Was `_is_mirror_mind_checkout`: walk upward to the first directory holding
+ * both `pyproject.toml` and `src/memory/`, and ask whether that pyproject
+ * declares Mirror Mind.
+ *
+ * **CV22.DS10.TS5 re-points the markers** (decision D1) to the TypeScript
+ * package, because `src/memory/` is deleted at plateau 3 — and a guard keyed
+ * to a deleted directory does not fail, it silently answers "not a checkout"
+ * and stops guarding. The production clone-role refusal would have
+ * disappeared with no test going red. See `#runtime/packageIdentity.ts`.
+ *
+ * The two properties Python had are preserved exactly, and are the reason this
+ * is a walk rather than a lookup:
+ *
+ *   * the walk STOPS at the first directory carrying the structural markers,
+ *     whatever it then answers — a nested project decides for itself instead
+ *     of inheriting its parent's identity;
+ *   * an unreadable or malformed manifest answers `false` rather than
+ *     continuing upward — Python's `return False` inside the `except`.
+ */
+export function isMirrorMindCheckout(start: string): boolean {
+  return findPackageIdentity(start)?.isMirrorMind === true;
+}
+
+/**
+ * Python `_check_clone_role_guard`, as a value.
+ *
+ * `null` means the guard has nothing to say: the path is not a Mirror Mind
+ * checkout, or its clone is not marked `production`.
+ */
+export function inspectBuilderCloneRole(
+  projectPath: string | null,
+  options: CloneRoleGuardOptions = {},
+): CloneRoleGuardOutcome | null {
+  const start = projectPath ?? options.currentDirectory ?? process.cwd();
+  if (!isMirrorMindCheckout(start)) return null;
+  const role = inspectCloneRole(start);
+  if (role.value !== "production") return null;
+  if (options.ignoreProductionRole) {
+    return {
+      stderr:
+        "\u001b[38;5;208m⚠️  Production clone override: --ignore-production-role passed.\u001b[0m\n",
+      exitCode: null,
+    };
+  }
+  // Python renders the absent marker as this literal, so the message names the
+  // reason the default applied instead of printing `None`.
+  const source = role.source ?? "<default: missing marker>";
+  return {
+    stderr:
+      "Builder Mode refused: the journey project clone is marked 'production'.\n" +
+      `  Project path: ${projectPath || "<current directory>"}\n` +
+      `  Clone role source: ${source}\n` +
+      "  Development should happen in a clone marked 'dev'.\n" +
+      "  To proceed here anyway, pass --ignore-production-role.\n",
+    exitCode: 2,
+  };
+}

package/ts/src/frontDoor/consultRoute.ts

@@ -0,0 +1,50 @@
+import { parseConsultArgs } from "#consult/args.ts";
+import { runConsult } from "#consult/core.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { CONSULT_ASK_TRANSPORT, CONSULT_CREDITS_TRANSPORT } from "#providers/transport.ts";
+
+/**
+ * `db` is optional (AI-09): when provided, `consult ask` logs to the
+ * llm_calls ledger with its real fetched cost. `consult credits` never logs
+ * (Python doesn't either), so `db` is passed through but unused on that path.
+ */
+export async function runConsultRoute(
+  db: WritableDatabase | null,
+  args: readonly string[],
+): Promise<string> {
+  const command = parseConsultArgs(args);
+  // Per leaf, from the same specs `routing.ts` decided with: `credits` needs
+  // only a credit provider, `ask` needs a chat provider too (CV22.DS8.US3).
+  const spec = command.command === "credits" ? CONSULT_CREDITS_TRANSPORT : CONSULT_ASK_TRANSPORT;
+  const family = await resolveFamilyProviders(process.env, spec);
+  if (!family?.credits) {
+    // `routing.ts` sends a reverted or half-configured family to Python before
+    // the route is reached, so this is defense in depth.
+    throw new Error("consult requires a credit provider");
+  }
+  if (command.command === "credits") {
+    return `${await runConsult(command, {
+      credits: family.credits,
+      llm: missingLlm(),
+      loadContext: () => "",
+      db: db ?? undefined,
+    })}\n`;
+  }
+  if (!family.llm) throw new Error("consult ask requires an LLM provider");
+  const context = process.env.MIRROR_TS_CONSULT_CONTEXT ?? "";
+  return `${await runConsult(command, {
+    credits: family.credits,
+    llm: family.llm,
+    loadContext: () => context,
+    db: db ?? undefined,
+  })}\n`;
+}
+
+function missingLlm() {
+  return {
+    async complete(): Promise<never> {
+      throw new Error("LLM provider is not available for consult credits");
+    },
+  };
+}

package/ts/src/frontDoor/contentTailRoute.ts

@@ -0,0 +1,239 @@
+/**
+ * Front-door serving paths for the CV22.DS7.US11 content & planning tail.
+ *
+ * `routing.ts` decides; these functions answer. Each mirrors the shape the
+ * cultivation and soul routes established: the replay provider is loaded from
+ * the environment variable `routing.ts` already gated on, so reaching one of
+ * these without it is direct misuse rather than a user-visible path.
+ *
+ * The ported logic lives in `#memory/journal.ts`, `#planning/weekPlan.ts`, and
+ * `#identity/descriptorGenerate.ts` and is graded there against the Python
+ * goldens. This module only assembles prompts, awaits providers, and hands the
+ * results to that synchronous logic — deliberately, so the graded units stay
+ * pure and the async seam stays thin.
+ */
+
+import {
+  LifecycleFaceError,
+  runLifecycleDryRun,
+  runLifecyclePreviewAtMessage,
+} from "#conversation/lifecycleFaces.ts";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { parseJsonResponse } from "#extraction/json.ts";
+import { resolveDescriptorTargets, runDescriptorGenerate } from "#identity/descriptorGenerate.ts";
+import {
+  addJournal,
+  interpretJournalClassification,
+  renderJournalReceipt,
+} from "#memory/journal.ts";
+import { classifyProviderError, type OnProviderCallOutcome } from "#observability/callOutcome.ts";
+import { chatLedgerHook, embeddingLedgerHook } from "#observability/ledgerHooks.ts";
+import {
+  buildDescriptorPrompt,
+  buildJournalClassificationPrompt,
+  buildWeekPlanPrompt,
+  DESCRIPTOR_TEMPERATURE,
+  JOURNAL_TEMPERATURE,
+  WEEK_PLAN_TEMPERATURE,
+  weekPlanClock,
+} from "#planning/promptAssembly.ts";
+import { defaultPendingPath } from "#planning/weekPending.ts";
+import { buildJourneyContext, runWeekPlan } from "#planning/weekPlan.ts";
+import { type EmbeddingProvider, generateEmbeddingSafely } from "#providers/embedding.ts";
+import type { LlmProvider } from "#providers/llm.ts";
+import { memoryEmbedText } from "#soul/harvest.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { pyStrip } from "#util/pythonText.ts";
+
+/** Python `journal`: positional words joined by a single space, plus `--journey`. */
+export function parseJournalArgs(args: readonly string[]): {
+  content: string;
+  journey: string | null;
+} {
+  const words: string[] = [];
+  let journey: string | null = null;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--journey") {
+      journey = args[index + 1] ?? null;
+      index += 1;
+    } else if (token === "--mirror-home" || token === "--db-path") {
+      index += 1;
+    } else {
+      words.push(token);
+    }
+  }
+  return { content: words.join(" "), journey };
+}
+
+export async function runJournalRoute(
+  db: WritableDatabase,
+  args: readonly string[],
+  providers: { llm: LlmProvider; embedding: EmbeddingProvider },
+): Promise<number> {
+  const { content, journey } = parseJournalArgs(args);
+  if (!content.trim()) {
+    console.error("Error: journal entry text cannot be empty");
+    return 1;
+  }
+
+  const prompt = buildJournalClassificationPrompt(content);
+  const response = await providers.llm.complete({
+    role: "journal_classification",
+    prompt,
+    temperature: JOURNAL_TEMPERATURE,
+  });
+  // Python's `add_journal` passes build_llm_logger(role="journal_classification").
+  chatLedgerHook(db, "journal_classification")(response, prompt);
+  const classification = interpretJournalClassification(
+    response.content,
+    content,
+    parseJsonResponse,
+  );
+
+  // Embed the SAME text `addJournal` would compute, so the vector and the
+  // graded write path cannot drift apart.
+  //
+  // Through `generateEmbeddingSafely`, not `provider.embed` directly (CR075).
+  // The wrapper owns three behaviors Python's `generate_embedding` has and a
+  // bare call does not: bounded retry of a transient empty payload, the AI-07
+  // permanent dimension-mismatch guard, and the ledger hook. All three were
+  // harmless while a fixture always answered with a well-formed vector for
+  // free, and all three become reachable the moment this is billable.
+  const vector = await generateEmbeddingSafely(
+    providers.embedding,
+    memoryEmbedText(classification.title, content, null),
+    { onAttempt: embeddingLedgerHook(db) },
+  );
+  const embedding = new Uint8Array(new Float32Array(vector).buffer);
+
+  const result = addJournal(
+    db,
+    { content, journey, classification },
+    { newId, nowIso: nowIso(), embed: () => embedding },
+  );
+
+  const stored = db
+    .prepare("SELECT tags FROM memories WHERE id = ?")
+    .get(result.memoryId) as unknown as { tags: string | null } | undefined;
+  process.stdout.write(renderJournalReceipt(result, journey, stored?.tags ?? null));
+  return 0;
+}
+
+export async function runWeekPlanRoute(
+  db: WritableDatabase,
+  args: readonly string[],
+  llm: LlmProvider,
+  // Test seam only: the pending file lives at one well-known path, shared with
+  // Python, and a test must not write to the operator's real one. The default
+  // is unchanged -- hardening the file itself is CR074, which has to move both
+  // engines together.
+  options: { pendingPath?: string } = {},
+): Promise<number> {
+  const text = args.find((token) => !token.startsWith("--")) ?? "";
+  const clock = weekPlanClock(new Date());
+
+  // Assembled here so the bytes sent are the bytes the digest pins, then the
+  // response is handed to the synchronous, golden-graded walk.
+  const prompt = buildWeekPlanPrompt(text, buildJourneyContext(db), clock);
+  const response = await llm.complete({
+    role: "week_plan",
+    prompt,
+    temperature: WEEK_PLAN_TEMPERATURE,
+  });
+  // Python's `services/tasks.py` passes build_llm_logger(role="week_plan").
+  chatLedgerHook(db, "week_plan")(response, prompt);
+
+  runWeekPlan(db, text, {
+    complete: () => response.content,
+    parseJson: parseJsonResponse,
+    clock,
+    pendingPath: options.pendingPath ?? defaultPendingPath(),
+    print: (value) => process.stdout.write(value),
+  });
+  return 0;
+}
+
+export async function runDescriptorGenerateRoute(
+  db: WritableDatabase,
+  args: readonly string[],
+  llm: LlmProvider,
+  // Without `--layer/--key` this makes ONE CALL PER persona AND per journey.
+  // Nothing bounds it but the argument, so the fan-out is reported rather than
+  // inferred from the ledger afterwards (CV22.DS8.US3 plan review, security).
+  onOutcome?: OnProviderCallOutcome,
+): Promise<number> {
+  const flag = (name: string): string | null => {
+    const index = args.indexOf(name);
+    return index === -1 ? null : (args[index + 1] ?? null);
+  };
+  const selection = { layer: flag("--layer"), key: flag("--key") };
+
+  const resolved = resolveDescriptorTargets(db, selection);
+  const descriptors = new Map<string, string>();
+  if (resolved.kind === "targets") {
+    for (const target of resolved.targets) {
+      // `generate_descriptor` returns "" for empty content BEFORE the model
+      // call, and "" on any provider exception. Both reach the same
+      // "skipped (empty response)" line.
+      if (!pyStrip(target.content)) {
+        // Python returns "" BEFORE the model call, so this entity costs
+        // nothing and is not a call at all.
+        descriptors.set(`${target.layer}/${target.key}`, "");
+        continue;
+      }
+      try {
+        const prompt = buildDescriptorPrompt(target.content, target.layer, target.key);
+        const response = await llm.complete({
+          role: "descriptor",
+          prompt,
+          temperature: DESCRIPTOR_TEMPERATURE,
+        });
+        // A DELIBERATE DIVERGENCE, decided at plan time (CV22.DS8.US3).
+        // Python's `generate_descriptor` is the one LLM caller that takes no
+        // `on_llm_call`, so neither engine recorded this spend. US11 preserved
+        // the gap as parity and flagged it as a DS8 input; DS8 closes it in
+        // TypeScript, which is the product authority for a ported command
+        // (2026-08-13). `descriptor generate` fans out one call per persona
+        // and per journey, so a ledger blind to it is blind to the largest
+        // single-command spend in this story. Recorded in decisions.md; the
+        // descriptor golden now reads "Python zero rows, TS one per entity".
+        chatLedgerHook(db, "descriptor")(response, prompt);
+        const descriptor = pyStrip(response.content);
+        onOutcome?.({ outcome: descriptor ? "answered" : "empty" });
+        descriptors.set(`${target.layer}/${target.key}`, descriptor);
+      } catch (error) {
+        onOutcome?.({ outcome: "transport_failed", kind: classifyProviderError(error) });
+        descriptors.set(`${target.layer}/${target.key}`, "");
+      }
+    }
+  }
+
+  return runDescriptorGenerate(db, selection, {
+    generate: (target) => descriptors.get(`${target.layer}/${target.key}`) ?? "",
+    nowIso: nowIso(),
+  }).exitCode;
+}
+
+/** The two ES-001 read faces; `routing.ts` has already refused the write faces. */
+export function runLifecycleFaceRead(db: Database, args: readonly string[]): number {
+  const value = (name: string): string | null => {
+    const index = args.indexOf(name);
+    return index === -1 ? null : (args[index + 1] ?? null);
+  };
+  try {
+    const dryRunId = value("--metadata-lifecycle-dry-run");
+    const report =
+      dryRunId !== null
+        ? runLifecycleDryRun(db, dryRunId)
+        : runLifecyclePreviewAtMessage(db, value("--metadata-lifecycle-preview-at-message") ?? "");
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof LifecycleFaceError) {
+      console.error(`Error: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}

package/ts/src/frontDoor/conversationLoggerRoute.ts

@@ -0,0 +1,73 @@
+// Front-door route for `conversation-logger` (CV22.DS7.US5 slice A; completed
+// in CV22.DS7.US10 slice F).
+//
+// Routing (`routing.ts`) decides the route; this module builds the logger
+// runtime from the process environment, performs the work, and writes the CLI
+// contract. (Until CV22.DS10.TS5 it could also return `null` to hand an LLM-tail
+// subcommand back to Python; that path left with the fallback.)
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { createZipBackup } from "#backup/zipBackup.ts";
+import { runConversationLoggerCommand, STDIN_SUBCOMMANDS } from "#conversation/loggerCli.ts";
+import { createLoggerRuntime } from "#conversation/loggerRuntime.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+
+export function isConversationLoggerCommand(argv: readonly string[]): boolean {
+  return argv[0] === "conversation-logger";
+}
+
+/** Python's `main()`: strip `--mirror-home X` and `--session-id X`, then `args[0]`. */
+function subcommandOf(args: readonly string[]): string {
+  const remaining = [...args];
+  for (const option of ["--mirror-home", "--session-id"]) {
+    const index = remaining.indexOf(option);
+    if (index !== -1) remaining.splice(index, 2);
+  }
+  return remaining[0] ?? "";
+}
+
+/** The hook subcommands read their JSON payload from stdin. */
+function readStdin(): string {
+  try {
+    return readFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export async function runConversationLoggerRoute(
+  db: WritableDatabase,
+  dbPath: string,
+  argv: readonly string[],
+): Promise<number> {
+  const args = argv.slice(1);
+  const subcommand = subcommandOf(args);
+  const runtime = createLoggerRuntime({
+    db,
+    // The mute flag and the backups live beside the database in the resolved
+    // mirror home.
+    mirrorHome: dirname(dbPath),
+    homeDir: homedir(),
+    env: process.env,
+    deps: { newId, nowIso },
+    // The dated zip Python's `repair-journeys --apply` gates on (DS7.TS1):
+    // non-silent, beside the database, `Mirror home:` line included.
+    backup: (stdout) =>
+      createZipBackup({
+        dbPath,
+        mirrorHome: dirname(dbPath),
+        backupDir: null,
+        silent: false,
+        stdout,
+      }),
+  });
+  const result = await runConversationLoggerCommand(db, args, runtime, {
+    stdin: STDIN_SUBCOMMANDS.has(subcommand) ? readStdin() : undefined,
+  });
+  for (const line of result.stdout) process.stdout.write(`${line}\n`);
+  for (const line of result.stderr) process.stderr.write(`${line}\n`);
+  return result.exitCode;
+}

package/ts/src/frontDoor/cultivationRoute.ts

@@ -0,0 +1,210 @@
+// `consolidate`/`shadow` front-door route (CV22.DS7.US3): the testable core
+// deciding WHAT happened for `list`/`reject`/`apply`/`scan` across both
+// command families. Rendering (HOW it is printed) lives in
+// `render/consolidate.ts` / `render/shadow.ts`.
+
+import {
+  applyIdentityUpdate,
+  applyMerge,
+  applyShadowApply,
+  applyShadowCandidate,
+  rejectConsolidation,
+} from "#cultivation/applyActions.ts";
+import {
+  type ConsolidationRow,
+  resolveProposalByIdOrPrefix,
+  updateConsolidationStatus,
+} from "#cultivation/consolidationStore.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { embeddingLedgerHook } from "#observability/ledgerHooks.ts";
+import type { EmbeddingProvider } from "#providers/embedding.ts";
+
+// --- Shared resolution (both families) ---------------------------------------
+
+export type ResolveProposalOutcome =
+  | { kind: "not_found"; proposalId: string }
+  | { kind: "already_reviewed"; consolidation: ConsolidationRow }
+  | { kind: "pending"; consolidation: ConsolidationRow };
+
+/** Port of the `_resolve_proposal` + "already reviewed" check shared by every
+ * `reject`/`apply` command in both `consolidate_cmd.py` and `shadow_cmd.py`. */
+export function resolveProposalForReview(
+  db: WritableDatabase,
+  proposalId: string,
+): ResolveProposalOutcome {
+  const consolidation = resolveProposalByIdOrPrefix(db, proposalId);
+  if (consolidation === null) return { kind: "not_found", proposalId };
+  if (consolidation.status !== "pending") return { kind: "already_reviewed", consolidation };
+  return { kind: "pending", consolidation };
+}
+
+// --- consolidate reject / shadow reject ---------------------------------------
+
+/** `ResolveProposalOutcome` minus its (internal-only) `"pending"` member --
+ * no route ever RETURNS `"pending"` to a caller; it is always converted into
+ * a more specific outcome first. Narrowing to this excludes `"pending"` from
+ * every exposed union below so a renderer's `if (outcome.kind === "applied")`
+ * (or equivalent) narrows completely, with no unreachable-but-typed member. */
+export type UnresolvedOutcome = Exclude<ResolveProposalOutcome, { kind: "pending" }>;
+
+export type RejectOutcome =
+  | UnresolvedOutcome
+  | { kind: "rejected"; consolidation: ConsolidationRow };
+
+/** Shared by `consolidate reject` and `shadow reject` -- identical Python logic in both CLIs. */
+export function runReject(db: WritableDatabase, proposalId: string, nowIso: string): RejectOutcome {
+  const resolved = resolveProposalForReview(db, proposalId);
+  if (resolved.kind !== "pending") return resolved;
+  rejectConsolidation(db, resolved.consolidation.id, nowIso);
+  return { kind: "rejected", consolidation: resolved.consolidation };
+}
+
+// --- consolidate apply ---------------------------------------------------------
+
+export type ConsolidateApplyOutcome =
+  | UnresolvedOutcome
+  | { kind: "identity_missing_target" }
+  | { kind: "identity_refused"; message: string }
+  | { kind: "merge_source_not_found" }
+  | {
+      kind: "applied";
+      action: string;
+      consolidation: ConsolidationRow;
+      resultContent: string;
+      identityUpdate?: { targetLayer: string; targetKey: string; sourceMemoryIds: string[] };
+      merge?: { mergedMemoryId: string; mergedTitle: string; sourceMemoryIds: string[] };
+      shadowCandidate?: { sourceMemoryIds: string[] };
+    };
+
+export interface ConsolidateApplyIds {
+  /** Injected id for a new identity row (only consumed on INSERT; ignored on UPDATE). */
+  identityId: string;
+  /** Injected id for a freshly merged memory (only consumed by the `merge` action). */
+  mergeMemoryId: string;
+  nowIso: string;
+}
+
+/**
+ * Port of `consolidate_cmd.cmd_apply`'s full dispatch, INCLUDING Python's
+ * silent fallthrough: an action outside `{identity_update, merge,
+ * shadow_candidate}` (never produced by `proposeConsolidation`'s allowlist,
+ * but reachable via a hand-crafted/legacy row) still reaches the SHARED
+ * "mark accepted" statement Python runs unconditionally after the
+ * if/elif chain -- no actual effect, but the consolidation is marked
+ * `accepted` regardless. `embeddingProvider` is required only by the `merge`
+ * branch; the caller (front door) only reaches this function when the
+ * DS7.US3 replay/live embedding gate is already satisfied.
+ */
+export async function runConsolidateApply(
+  db: WritableDatabase,
+  proposalId: string,
+  overrideContent: string | null,
+  ids: ConsolidateApplyIds,
+  embeddingProvider: EmbeddingProvider,
+): Promise<ConsolidateApplyOutcome> {
+  const resolved = resolveProposalForReview(db, proposalId);
+  if (resolved.kind !== "pending") return resolved;
+  const consolidation = resolved.consolidation;
+  const resultContent = overrideContent ?? consolidation.proposal;
+
+  if (consolidation.action === "identity_update") {
+    const outcome = applyIdentityUpdate(db, consolidation, resultContent, {
+      id: ids.identityId,
+      nowIso: ids.nowIso,
+    });
+    if (outcome.kind === "missing_target") return { kind: "identity_missing_target" };
+    if (outcome.kind === "refused") return { kind: "identity_refused", message: outcome.message };
+    return {
+      kind: "applied",
+      action: "identity_update",
+      consolidation,
+      resultContent,
+      identityUpdate: {
+        targetLayer: outcome.targetLayer,
+        targetKey: outcome.targetKey,
+        sourceMemoryIds: outcome.sourceMemoryIds,
+      },
+    };
+  }
+
+  if (consolidation.action === "merge") {
+    const outcome = await applyMerge(db, consolidation, resultContent, {
+      embeddingProvider,
+      id: ids.mergeMemoryId,
+      nowIso: ids.nowIso,
+      // Python's `consolidate_cmd` passes build_llm_logger(role="embedding")
+      // into `generate_embedding` here. The wrapper's hook already existed on
+      // this path; nobody had ever passed it one (CV22.DS8.US3, CR075's
+      // adjacent case).
+      onEmbeddingAttempt: embeddingLedgerHook(db, { now: () => ids.nowIso }),
+    });
+    if (outcome.kind === "source_not_found") return { kind: "merge_source_not_found" };
+    return {
+      kind: "applied",
+      action: "merge",
+      consolidation,
+      resultContent,
+      merge: {
+        mergedMemoryId: outcome.mergedMemoryId,
+        mergedTitle: outcome.mergedTitle,
+        sourceMemoryIds: outcome.sourceMemoryIds,
+      },
+    };
+  }
+
+  if (consolidation.action === "shadow_candidate") {
+    const outcome = applyShadowCandidate(db, consolidation, resultContent, ids.nowIso);
+    return {
+      kind: "applied",
+      action: "shadow_candidate",
+      consolidation,
+      resultContent,
+      shadowCandidate: outcome,
+    };
+  }
+
+  // Unknown action: Python's fallthrough -- the if/elif chain has no `else`,
+  // so an unrecognized action performs NO actual write, yet the shared
+  // post-chain statement still runs and marks the proposal accepted.
+  updateConsolidationStatus(db, consolidation.id, "accepted", resultContent, ids.nowIso);
+  return { kind: "applied", action: consolidation.action, consolidation, resultContent };
+}
+
+// --- shadow apply ---------------------------------------------------------------
+
+export type ShadowApplyRouteOutcome =
+  | UnresolvedOutcome
+  | { kind: "wrong_action"; consolidation: ConsolidationRow }
+  | {
+      kind: "applied";
+      consolidation: ConsolidationRow;
+      targetKey: string;
+      sourceMemoryIds: string[];
+    };
+
+/**
+ * Port of `shadow_cmd.cmd_apply`'s full dispatch: resolve, then refuse any
+ * `action !== 'shadow_observation'` loudly (Python's own guard, separate from
+ * -- and checked BEFORE -- the allowlist gate), then apply.
+ */
+export function runShadowApply(
+  db: WritableDatabase,
+  proposalId: string,
+  overrideContent: string | null,
+  ids: { id: string; nowIso: string },
+): ShadowApplyRouteOutcome {
+  const resolved = resolveProposalForReview(db, proposalId);
+  if (resolved.kind !== "pending") return resolved;
+  const consolidation = resolved.consolidation;
+  if (consolidation.action !== "shadow_observation") {
+    return { kind: "wrong_action", consolidation };
+  }
+  const resultContent = overrideContent ?? consolidation.proposal;
+  const outcome = applyShadowApply(db, consolidation, resultContent, ids);
+  return {
+    kind: "applied",
+    consolidation,
+    targetKey: outcome.targetKey,
+    sourceMemoryIds: outcome.sourceMemoryIds,
+  };
+}