mirror-mind 0.0.1 → 0.33.0

package/ts/src/frontDoor/mirrorModeRoute.ts

@@ -0,0 +1,163 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import {
+  deactivateMirrorState,
+  listActiveMirrorJourneys,
+  logMirrorResponse,
+  runMirrorLoad,
+} from "#mirror/orchestration.ts";
+import {
+  activateOperatingMode,
+  deactivateOperatingMode,
+  getActiveOperatingMode,
+  renderModeActivation,
+  renderModeStatus,
+} from "#mode/operatingMode.ts";
+import type { OnProviderCallOutcome } from "#observability/callOutcome.ts";
+import { resolveFamilyProviders } from "#providers/familyProviders.ts";
+import { MIRROR_QUERY_TRANSPORT } from "#providers/transport.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { hasOption, optionValue, stripOptionWithValue } from "./args.ts";
+
+/**
+ * A type alias rather than an interface, for the same reason `RouteEnvironment`
+ * is one: aliases get an implicit index signature, which is what lets the named
+ * variables still be handed to `resolveFamilyProviders`, whose families name
+ * their variables as data.
+ */
+export type MirrorRouteEnvironment = {
+  MIRROR_SESSION_ID?: string;
+  MEMORY_RECEPTION?: string;
+  MIRROR_TS_MIRROR_LLM_REPLAY?: string;
+  MIRROR_TS_MIRROR_EMBEDDING_REPLAY?: string;
+};
+
+export function isMirrorWrite(argv: readonly string[]): boolean {
+  return argv[0] === "mirror" && ["load", "deactivate", "log"].includes(argv[1] ?? "");
+}
+
+export function isModeWrite(argv: readonly string[]): boolean {
+  if (argv[0] !== "mode") return false;
+  const args = modePositionals(argv.slice(1));
+  return args[0] === "activate" || args[0] === "deactivate";
+}
+
+export function mirrorDeactivateMissingSession(argv: readonly string[]): boolean {
+  return argv[0] === "mirror" && argv[1] === "deactivate" && !optionValue(argv, "--session-id");
+}
+
+export function runMirrorRead(db: Database, args: readonly string[]): number {
+  if (args[0] !== "journeys") throw new Error(`Unsupported TS mirror read: ${args[0]}`);
+  process.stdout.write(listActiveMirrorJourneys(db));
+  return 0;
+}
+
+export function runModeRead(db: Database, args: readonly string[]): number {
+  const sessionId = optionValue(args, "--session-id");
+  process.stdout.write(renderModeStatus(getActiveOperatingMode(db, sessionId)));
+  return 0;
+}
+
+export async function runMirrorWriteRoute(
+  db: WritableDatabase,
+  dbPath: string,
+  argv: readonly string[],
+  env: MirrorRouteEnvironment = process.env,
+  options: { onReceptionOutcome?: OnProviderCallOutcome } = {},
+): Promise<number> {
+  const sub = argv[1];
+  const args = argv.slice(2);
+  const sessionId = optionValue(args, "--session-id");
+  if (sub === "deactivate") {
+    deactivateMirrorState(db, sessionId as string, nowIso());
+    console.error("Mirror Mode deactivated.");
+    return 0;
+  }
+  if (sub === "log") {
+    const summary = stripOptionWithValue(
+      stripOptionWithValue(stripOptionWithValue(args, "--session-id"), "--mirror-home"),
+      "--db-path",
+    )[0];
+    if (!summary) {
+      console.error("mirror log requires a summary");
+      return 2;
+    }
+    logMirrorResponse(db, {
+      summary,
+      sessionId,
+      environmentSessionId: env.MIRROR_SESSION_ID ?? null,
+      muted: existsSync(join(dirname(dbPath), "mute")),
+      newId,
+      nowIso,
+    });
+    console.error("Response recorded.");
+    return 0;
+  }
+  const query = optionValue(args, "--query");
+  const receptionEnabled = env.MEMORY_RECEPTION !== "0";
+  // Built from the same spec `routing.ts` decided with, and only for a query
+  // run: a deterministic `mirror load` must not construct a provider, let
+  // alone resolve a key (CV22.DS8.US3).
+  const family = query ? await resolveFamilyProviders(env, MIRROR_QUERY_TRANSPORT) : null;
+  const mirrorHome = dirname(dbPath);
+  const rendered = await runMirrorLoad(db, {
+    identity: basename(mirrorHome),
+    databasePath: dbPath,
+    mirrorHome,
+    user: basename(mirrorHome),
+    persona: optionValue(args, "--persona"),
+    journey: optionValue(args, "--journey"),
+    query,
+    org: hasOption(args, "--org"),
+    contextOnly: hasOption(args, "--context-only"),
+    sessionId,
+    environmentSessionId: env.MIRROR_SESSION_ID ?? null,
+    receptionEnabled,
+    onReceptionOutcome: options.onReceptionOutcome,
+    llmProvider: receptionEnabled ? family?.llm : undefined,
+    embeddingProvider: family?.embedding,
+    newId,
+    nowIso,
+  });
+  process.stdout.write(rendered.stdout);
+  process.stderr.write(rendered.stderr);
+  for (const diagnostic of rendered.extensionDiagnostics) {
+    process.stderr.write(`warning: extension context ${diagnostic.kind}; continuing.\n`);
+  }
+  return 0;
+}
+
+export function runModeWriteRoute(db: WritableDatabase, argv: readonly string[]): number {
+  const rawArgs = argv.slice(1);
+  const args = modePositionals(rawArgs);
+  const sub = args[0];
+  const sessionId = optionValue(rawArgs, "--session-id");
+  if (sub === "activate") {
+    const mode = args[1];
+    if (!mode) {
+      console.error("mode activate requires a mode");
+      return 2;
+    }
+    const state = activateOperatingMode(
+      db,
+      { mode, journey: optionValue(rawArgs, "--journey"), sessionId },
+      nowIso(),
+    );
+    process.stdout.write(renderModeActivation(state));
+    return 0;
+  }
+  deactivateOperatingMode(db, sessionId, nowIso());
+  process.stdout.write("Deactivated active mode\n");
+  return 0;
+}
+
+function modePositionals(args: readonly string[]): string[] {
+  return stripOptionWithValue(
+    stripOptionWithValue(
+      stripOptionWithValue(stripOptionWithValue(args, "--mirror-home"), "--db-path"),
+      "--session-id",
+    ),
+    "--journey",
+  );
+}

package/ts/src/frontDoor/namedRefusal.ts

@@ -0,0 +1,35 @@
+// The refusals the front door answers by name when no route answered them.
+//
+// A route answers its own refusals. Two can reach the top of the front door
+// unanswered, and each is still a refusal the user can act on, so each gets one
+// line and an exit code, never a stack trace:
+//
+//   * a half-configured replay fixture, raised wherever a provider is built. Until
+//     CV22.DS10.TS5 a plain family sent this case to the Python fallback instead,
+//     which had no replay transport and would have called the live provider;
+//   * a new journey slug or persona id outside the grammar, which the identity
+//     store refuses for any route that did not ask first (CR104). Today every route
+//     asks first, so this answers the next route that creates a key.
+//
+// Like every `Error:` line, the answer claims nothing about what changed before
+// the refusal was raised.
+
+import { InvalidIdentityKeyError } from "#identity/identityKey.ts";
+import { ReplayFixtureIncompleteError } from "#providers/transport.ts";
+
+export interface NamedRefusal {
+  /** The one line printed to stderr. */
+  readonly line: string;
+  readonly exitCode: number;
+}
+
+/** The line and exit code for a refusal the front door can name, or null for a crash. */
+export function namedRefusal(error: unknown): NamedRefusal | null {
+  if (error instanceof ReplayFixtureIncompleteError) {
+    return { line: `Mirror TS front door: ${error.message}`, exitCode: 2 };
+  }
+  if (error instanceof InvalidIdentityKeyError) {
+    return { line: `Error: ${error.message}`, exitCode: 1 };
+  }
+  return null;
+}

package/ts/src/frontDoor/nodeSupport.ts

@@ -0,0 +1,24 @@
+// Node runtime support check for the front door (CR025).
+//
+// Kept in its own module so it is importable without executing the CLI entry
+// (`cli.ts` runs `main()` at module load). The front door calls this first.
+
+/** Minimum Node major the TS core supports (node:sqlite + TS type-stripping). */
+export const MINIMUM_NODE_MAJOR = 24;
+
+/**
+ * Return an actionable message when `version` is below the supported Node
+ * major, or null when it is fine. Pure and side-effect-free. (On Node too old
+ * to strip TypeScript the front door never loads at all — that band is covered
+ * by the documented prerequisite, not this guard.)
+ */
+export function nodeVersionError(version: string): string | null {
+  const major = Number(version.split(".")[0]);
+  if (Number.isFinite(major) && major < MINIMUM_NODE_MAJOR) {
+    return (
+      `Mirror TS front door requires Node >= ${MINIMUM_NODE_MAJOR} (running ${version}). ` +
+      "Upgrade Node (https://nodejs.org/) — node:sqlite and TypeScript execution need it."
+    );
+  }
+  return null;
+}

package/ts/src/frontDoor/render/consolidate.ts

@@ -0,0 +1,199 @@
+// `consolidate` command rendering (CV22.DS7.US3) -- the port of
+// `cli/consolidate_cmd.py`'s print statements. Every function here is a pure
+// string builder over already-decided data (`cultivationRoute.ts` decides
+// WHAT happened; this module decides HOW it is printed), matching Python's
+// exact output including its blank-line quirks (`print(f"...\n")` followed by
+// `print()`'s own newline -- see `tasks.ts`'s module doc for the same idiom).
+
+import type { ConsolidationRow, CultivationMemory } from "#cultivation/consolidationStore.ts";
+import type { ConsolidateScanResult } from "#cultivation/scan.ts";
+import type { ConsolidateApplyOutcome, RejectOutcome } from "#frontDoor/cultivationRoute.ts";
+import { PROGRAM } from "#util/program.ts";
+import { renderAlreadyReviewed, renderProposalNotFound } from "./cultivationShared.ts";
+
+const ACTION_ICON: Record<string, string> = {
+  merge: "🔀",
+  identity_update: "🧬",
+  shadow_candidate: "🌑",
+};
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "⏳",
+  accepted: "✓",
+  rejected: "✗",
+};
+
+function sourceIdCount(sourceMemoryIds: string): number {
+  const parsed: unknown = sourceMemoryIds ? JSON.parse(sourceMemoryIds) : [];
+  return Array.isArray(parsed) ? parsed.length : 0;
+}
+
+/** Port of `consolidate list`'s `cmd_list`. */
+export function renderConsolidateList(
+  items: readonly ConsolidationRow[],
+  status: string | null,
+): string {
+  if (items.length === 0) {
+    const label = status ? ` (${status})` : "";
+    return `No consolidations found${label}.\n`;
+  }
+  const lines: string[] = [];
+  for (const c of items) {
+    const icon = ACTION_ICON[c.action] ?? "•";
+    const st = STATUS_ICON[c.status] ?? "?";
+    const date = c.created_at.slice(0, 10);
+    const target = c.target_layer && c.target_key ? ` → ${c.target_layer}/${c.target_key}` : "";
+    lines.push(
+      `${st} [${c.id.slice(0, 8)}] ${date}  ${icon} ${c.action}${target}  (${sourceIdCount(c.source_memory_ids)} memories)`,
+    );
+    if (c.rationale) lines.push(`   ${c.rationale}`);
+  }
+  return lines.map((line) => `${line}\n`).join("");
+}
+
+/** Port of `consolidate reject`'s success message; not-found/already-reviewed are shared. */
+export function renderConsolidateRejected(consolidation: ConsolidationRow): string {
+  return `Proposal [${consolidation.id.slice(0, 8)}] rejected. Source memories unchanged.\n`;
+}
+
+/** Port of `consolidate reject`'s full output (not_found/already_reviewed shared, success family-specific). */
+export function renderConsolidateReject(outcome: RejectOutcome): RenderedCommand {
+  if (outcome.kind === "not_found") {
+    return { text: renderProposalNotFound(outcome.proposalId), stderr: true, exitCode: 1 };
+  }
+  if (outcome.kind === "already_reviewed") {
+    return { text: renderAlreadyReviewed(outcome.consolidation), stderr: false, exitCode: 0 };
+  }
+  return { text: renderConsolidateRejected(outcome.consolidation), stderr: false, exitCode: 0 };
+}
+
+/**
+ * Port of `consolidate apply`'s full output, one branch per
+ * `ConsolidateApplyOutcome` kind. Returns the text plus which stream/exit
+ * code it belongs to -- `cultivationRoute.ts` decided the outcome, this
+ * decides the Python-exact bytes AND (unlike every prior front-door
+ * renderer) the stream/exit code, because `consolidate apply` fans out into
+ * more distinct terminal states than any single-outcome command ported so
+ * far.
+ */
+export interface RenderedCommand {
+  text: string;
+  stderr: boolean;
+  exitCode: number;
+}
+
+export function renderConsolidateApply(outcome: ConsolidateApplyOutcome): RenderedCommand {
+  if (outcome.kind === "not_found") {
+    return { text: renderProposalNotFound(outcome.proposalId), stderr: true, exitCode: 1 };
+  }
+  if (outcome.kind === "already_reviewed") {
+    return { text: renderAlreadyReviewed(outcome.consolidation), stderr: false, exitCode: 0 };
+  }
+  if (outcome.kind === "identity_missing_target") {
+    return {
+      text: "Error: identity_update proposal has no target_layer/target_key.\n",
+      stderr: true,
+      exitCode: 1,
+    };
+  }
+  if (outcome.kind === "identity_refused") {
+    return { text: `Error: ${outcome.message}\n`, stderr: true, exitCode: 1 };
+  }
+  if (outcome.kind === "merge_source_not_found") {
+    return { text: "Error: source memory not found.\n", stderr: true, exitCode: 1 };
+  }
+
+  // outcome.kind === "applied"
+  const id8 = outcome.consolidation.id.slice(0, 8);
+  let text = "";
+  if (outcome.identityUpdate) {
+    const { targetLayer, targetKey, sourceMemoryIds } = outcome.identityUpdate;
+    text += `✓ Updated identity: ${targetLayer}/${targetKey}\n`;
+    text += `  Source memories (${sourceMemoryIds.length}) advanced to 'acknowledged'.\n`;
+  } else if (outcome.merge) {
+    const { mergedMemoryId, mergedTitle, sourceMemoryIds } = outcome.merge;
+    text += `✓ Created merged memory: [${mergedMemoryId.slice(0, 8)}] ${mergedTitle}\n`;
+    text += `  Source memories (${sourceMemoryIds.length}) marked as 'integrated'.\n`;
+  } else if (outcome.shadowCandidate) {
+    text += `✓ Shadow candidate accepted. ${outcome.shadowCandidate.sourceMemoryIds.length} memories advanced to 'candidate'.\n`;
+    text += "  Run mm-shadow to surface these in the next shadow review pass.\n";
+  }
+  // Unrecognized action (Python's silent fallthrough): no branch text above,
+  // only the shared trailing line below.
+  text += `\nProposal [${id8}] marked as accepted.\n`;
+  return { text, stderr: false, exitCode: 0 };
+}
+
+const BAR = "─".repeat(60);
+
+/** Port of `_print_proposal` in `consolidate_cmd.py` (the scan-time proposal card). */
+function formatProposalBlock(
+  proposal: ConsolidationRow,
+  cluster: readonly CultivationMemory[],
+  index: number,
+  total: number,
+): string {
+  const icon = ACTION_ICON[proposal.action] ?? "•";
+  let out = `\n${BAR}\n`;
+  out += `Proposal ${index}/${total}  [${proposal.id.slice(0, 8)}]  ${icon} ${proposal.action.toUpperCase()}\n`;
+  out += `${BAR}\n`;
+  out += "\n**Source memories:**\n";
+  for (const memory of cluster) {
+    const date = memory.created_at.slice(0, 10);
+    out += `  • [${memory.id.slice(0, 8)}] ${memory.title}  (${memory.memory_type}/${memory.layer}, ${date})\n`;
+  }
+  if (proposal.target_layer && proposal.target_key) {
+    out += `\n**Target:** \`${proposal.target_layer}/${proposal.target_key}\`\n`;
+  }
+  if (proposal.rationale) {
+    out += `\n**Rationale:** ${proposal.rationale}\n`;
+  }
+  out += `\n**Proposed content:**\n${proposal.proposal}\n`;
+  out += "\n";
+  return out;
+}
+
+/**
+ * Port of `consolidate scan`'s full output. `threshold` is rendered two
+ * different ways in Python -- plain `str(float)` in the opening "Scanning..."
+ * line, `:.2f` in the "Try lowering" hint -- both reproduced here. Plain
+ * `String(threshold)` matches Python's float-to-str for ordinary decimal
+ * thresholds (e.g. the 0.75 default); exotic float inputs are not
+ * byte-audited against CPython's `repr` here.
+ */
+export function renderConsolidateScan(result: ConsolidateScanResult, threshold: number): string {
+  if (result.memoriesScanned === 0) {
+    return "No memories with embeddings found for the given filters.\n";
+  }
+  let out = `Scanning ${result.memoriesScanned} memories (threshold=${threshold})...\n`;
+  if (result.results.length === 0) {
+    out += "No clusters found above the similarity threshold.\n";
+    out += `Try lowering --threshold (current: ${threshold.toFixed(2)}).\n`;
+    return out;
+  }
+  out += `Found ${result.results.length} cluster(s). Generating proposals...\n\n`;
+
+  let createdCount = 0;
+  for (const { cluster, proposal } of result.results) {
+    if (proposal === null) {
+      out += `  ⚠ LLM returned no valid proposal for cluster of ${cluster.length} memories.\n`;
+      continue;
+    }
+    createdCount += 1;
+    out += formatProposalBlock(proposal, cluster, createdCount, result.results.length);
+  }
+
+  if (createdCount === 0) {
+    out += "No proposals were generated.\n";
+    return out;
+  }
+
+  out +=
+    `\n${createdCount} proposal(s) created with status='pending'.\n` +
+    "Review each proposal above, then:\n" +
+    `  Accept:  ${PROGRAM} consolidate apply <proposal_id>\n` +
+    `  Edit:    ${PROGRAM} consolidate apply <proposal_id> --content "revised text"\n` +
+    `  Reject:  ${PROGRAM} consolidate reject <proposal_id>\n` +
+    `  List all: ${PROGRAM} consolidate list\n`;
+  return out;
+}

package/ts/src/frontDoor/render/conversations.ts

@@ -0,0 +1,33 @@
+// `conversations` (plain listing) rendering — the port of the summary print
+// loop in memory.cli.conversations.main. The metadata-lifecycle/backfill flags
+// on the same Python command are out of scope (see routing.ts) and never reach
+// this renderer.
+
+import {
+  type ListRecentConversationsFilters,
+  listRecentConversationSummaries,
+} from "#conversation/listing.ts";
+import type { Database } from "#db/database.ts";
+
+/** Render the `conversations` plain listing. */
+export function renderConversationsListing(
+  db: Database,
+  filters: ListRecentConversationsFilters,
+): string {
+  const summaries = listRecentConversationSummaries(db, filters);
+  if (summaries.length === 0) return "No conversations found.\n";
+  const prints: string[] = [];
+  for (const summary of summaries) {
+    const title = summary.title || "(untitled)";
+    const date = summary.started_at ? summary.started_at.slice(0, 10) : "?";
+    const journeyStr = summary.journey ? ` [${summary.journey}]` : "";
+    const personaStr = summary.persona ? ` \u25c7 ${summary.persona}` : "";
+    prints.push(
+      `**${date}** | \`${summary.id.slice(0, 8)}\`${journeyStr}${personaStr} ` +
+        `(${summary.message_count} msgs)`,
+    );
+    prints.push(`  ${title}`);
+    prints.push("");
+  }
+  return prints.map((line) => `${line}\n`).join("");
+}

package/ts/src/frontDoor/render/cultivationShared.ts

@@ -0,0 +1,21 @@
+// Shared rendering for the `consolidate`/`shadow` proposal-review commands
+// (CV22.DS7.US3): the "not found" / "already reviewed" messages are
+// byte-identical across both families' `reject`/`apply` commands in Python
+// (each CLI module inlines the same two checks independently), so they are
+// ported once here instead of copy-pasted into `consolidate.ts`/`shadow.ts`.
+
+import type { ConsolidationRow } from "#cultivation/consolidationStore.ts";
+
+/** Port of `f"Error: proposal '{proposal_id}' not found."` (stderr, exit 1). */
+export function renderProposalNotFound(proposalId: string): string {
+  return `Error: proposal '${proposalId}' not found.\n`;
+}
+
+/**
+ * Port of `f"Proposal {consolidation.id[:8]} is already '{consolidation.status}'."`
+ * (stdout, exit 0). Deliberately NO brackets around the id excerpt here --
+ * unlike every success message in both families, which wraps it `[id8]`.
+ */
+export function renderAlreadyReviewed(consolidation: ConsolidationRow): string {
+  return `Proposal ${consolidation.id.slice(0, 8)} is already '${consolidation.status}'.\n`;
+}

package/ts/src/frontDoor/render/descriptor.ts

@@ -0,0 +1,20 @@
+// `descriptor list` rendering — the port of memory.cli.descriptor._cmd_list's
+// print loop. `descriptor generate` is LLM-backed and stays on Python.
+
+import type { DescriptorRow } from "#descriptor/descriptorRead.ts";
+
+/**
+ * Render `descriptor list`. Each row is three Python `print()` calls
+ * (`[layer/key]`, the indented descriptor, and a bare blank-line `print()`) —
+ * modeled as three array elements, each getting exactly one trailing newline.
+ */
+export function renderDescriptorList(rows: DescriptorRow[]): string {
+  if (rows.length === 0) return "No descriptors stored.\n";
+  const prints: string[] = [];
+  for (const row of rows) {
+    prints.push(`[${row.layer}/${row.key}]`);
+    prints.push(`  ${row.descriptor}`);
+    prints.push("");
+  }
+  return prints.map((line) => `${line}\n`).join("");
+}

package/ts/src/frontDoor/render/detectPersona.ts

@@ -0,0 +1,50 @@
+// `detect-persona` rendering: read persona routing rows, score the query,
+// format the matches. Extracted from cli.ts (CR002).
+
+import type { Database } from "#db/database.ts";
+import { requireString } from "#db/rowDecode.ts";
+import { stripOptionWithValue } from "#frontDoor/args.ts";
+import { detectPersona, type PersonaRoutingRow } from "#persona/detectPersona.ts";
+import { identityRows } from "./identityRows.ts";
+
+/** Parse each persona row's `routing_keywords` out of its identity metadata. */
+export function routingRows(db: Database): PersonaRoutingRow[] {
+  return identityRows(db, "persona").map((row) => {
+    let keywords: string[] = [];
+    const metadata = row.metadata;
+    if (typeof metadata === "string" && metadata) {
+      try {
+        const parsed = JSON.parse(metadata) as Record<string, unknown>;
+        if (Array.isArray(parsed.routing_keywords)) {
+          keywords = parsed.routing_keywords.filter(
+            (item): item is string => typeof item === "string",
+          );
+        }
+      } catch {
+        keywords = [];
+      }
+    }
+    return { key: requireString(row, "key"), routing_keywords: keywords };
+  });
+}
+
+/**
+ * Render `detect-persona`. Strips known option flags (and their values) so only
+ * the query tokens remain — both `--mirror-home` and `--db-path`, the latter of
+ * which previously leaked into the query text.
+ */
+export function renderDetectPersona(db: Database, args: readonly string[]): string {
+  const query = stripOptionWithValue(stripOptionWithValue(args, "--mirror-home"), "--db-path")
+    .join(" ")
+    .trim();
+  const matches = detectPersona(query, routingRows(db));
+  const lines = [`query: ${query}`];
+  if (matches.length === 0) {
+    lines.push("  (no persona match)");
+  } else {
+    for (const match of matches) {
+      lines.push(`  ${match.key} score=${match.score} match=${match.matchType}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/ts/src/frontDoor/render/icons.ts

@@ -0,0 +1,13 @@
+// Memory-type icons shared by the memory renderer.
+
+export const ICONS: Record<string, string> = {
+  decision: "⚖️",
+  insight: "💡",
+  idea: "🌱",
+  journal: "📓",
+  tension: "⚡",
+  learning: "📚",
+  pattern: "🔄",
+  commitment: "🤝",
+  reflection: "🪞",
+};

package/ts/src/frontDoor/render/identity.ts

@@ -0,0 +1,59 @@
+// `identity list` / `identity get` rendering — the port of
+// memory.cli.identity_cmd.cmd_list / cmd_get (read-only subcommands; `set` is
+// US4/identityWrite.ts and `edit` stays on Python — it spawns `$EDITOR`).
+
+import type { Database } from "#db/database.ts";
+import {
+  getIdentityContent,
+  type IdentityListRow,
+  listAllIdentity,
+  listIdentityByLayer,
+} from "#identity/identityRead.ts";
+
+/** Raised when `identity get` finds no row for (layer, key) — mirrors Python's exit 1. */
+export class IdentityEntryNotFoundError extends Error {
+  readonly layer: string;
+  readonly key: string;
+  constructor(layer: string, key: string) {
+    super(`No identity entry found for ${layer}/${key}`);
+    this.layer = layer;
+    this.key = key;
+  }
+}
+
+/** `entry.content[:70]`, newlines collapsed to spaces, "..." appended when truncated. */
+function preview(content: string): string {
+  const clipped = content.slice(0, 70).replaceAll("\n", " ");
+  return content.length > 70 ? `${clipped}...` : clipped;
+}
+
+/**
+ * Render `identity list`: one "print call" per array element (each gets exactly
+ * one trailing newline appended, matching Python's `print()`), so a header's own
+ * embedded leading `\n` reproduces the blank line before every layer group.
+ */
+export function renderIdentityList(rows: IdentityListRow[]): string {
+  if (rows.length === 0) return "No identity entries found.\n";
+  const prints: string[] = [];
+  let currentLayer: string | null = null;
+  for (const row of rows) {
+    if (row.layer !== currentLayer) {
+      currentLayer = row.layer;
+      prints.push(`\n[${row.layer}]`);
+    }
+    prints.push(`  ${row.key.padEnd(22)}  ${preview(row.content)}`);
+  }
+  return prints.map((line) => `${line}\n`).join("");
+}
+
+/** Read identity rows for `identity list`, optionally filtered by `--layer`. */
+export function identityListRows(db: Database, layer: string | null): IdentityListRow[] {
+  return layer ? listIdentityByLayer(db, layer) : listAllIdentity(db);
+}
+
+/** Render `identity get <layer> <key>`: raw content + newline, or throw not-found. */
+export function renderIdentityGet(db: Database, layer: string, key: string): string {
+  const content = getIdentityContent(db, layer, key);
+  if (content === null) throw new IdentityEntryNotFoundError(layer, key);
+  return `${content}\n`;
+}

package/ts/src/frontDoor/render/identityRows.ts

@@ -0,0 +1,17 @@
+// Shared read of `identity`-layer rows for the read renderers.
+
+import type { Database, Row } from "#db/database.ts";
+
+/**
+ * All identity rows for a layer, ordered by key (as the Python oracle reads
+ * them). Includes migration 017's `parent_journey` projection so parity and
+ * drift diagnostics can observe it; mixed-engine semantic reads still resolve
+ * journey parentage from metadata (CR050).
+ */
+export function identityRows(db: Database, layer: string): Row[] {
+  return db
+    .prepare(
+      "SELECT key, content, metadata, parent_journey FROM identity WHERE layer = ? ORDER BY key",
+    )
+    .all(layer);
+}