mirror-mind 0.0.1 → 0.33.0

package/ts/src/cultivation/applyActions.ts

@@ -0,0 +1,241 @@
+// Deterministic + Slice B `consolidate`/`shadow` apply/reject actions
+// (CV22.DS7.US3).
+//
+// Ports `cli/consolidate_cmd.py:cmd_apply`/`cmd_reject` and
+// `cli/shadow_cmd.py:cmd_apply`/`cmd_reject`, including the `merge` action
+// (which needs a fresh embedding -- Slice B, gated on the caller supplying a
+// replay/live `EmbeddingProvider`; see `propose.ts` for the sibling `scan`
+// orchestration). Each action is its own small, individually-tested function
+// behind the front door's dispatch, not one branching mega-handler.
+//
+// Security posture: `identity_update` reaches an identity write ONLY through
+// `applyConsolidationIdentityUpdate` (the self/ego allowlist gate, AI-23) --
+// never the ungated `upsertIdentity`/`setIdentity`. `shadow apply`'s safety is
+// the HARDCODED constant `layer: "shadow"`; only the *key* is model-influenced,
+// and the port must never let the proposal drive the layer.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { embeddingToBytes } from "#db/decode.ts";
+import { applyConsolidationIdentityUpdate } from "#identity/applyConsolidationIdentityUpdate.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { upsertIdentity } from "#identity/identityStore.ts";
+import { createMemoryRow, getMemorySourceForMerge } from "#memory/memoryWrite.ts";
+import {
+  addEmbeddingProvenance,
+  type EmbeddingAttemptInfo,
+  type EmbeddingProvider,
+  generateEmbeddingSafely,
+} from "#providers/embedding.ts";
+import {
+  type ConsolidationRow,
+  updateConsolidationStatus,
+  updateMemoryReadinessState,
+} from "./consolidationStore.ts";
+
+function sourceMemoryIds(consolidation: ConsolidationRow): string[] {
+  return JSON.parse(consolidation.source_memory_ids) as string[];
+}
+
+// --- Reject (shared by both families) ----------------------------------------
+
+/**
+ * Port of `consolidate reject` / `shadow reject`: `status -> 'rejected'`, no
+ * source-memory or identity mutation at all. Both CLIs are byte-identical
+ * here, so one function serves both front-door commands.
+ */
+export function rejectConsolidation(db: WritableDatabase, id: string, nowIso: string): void {
+  updateConsolidationStatus(db, id, "rejected", null, nowIso);
+}
+
+// --- consolidate apply: identity_update --------------------------------------
+
+export type IdentityUpdateOutcome =
+  | { kind: "applied"; targetLayer: string; targetKey: string; sourceMemoryIds: string[] }
+  | { kind: "missing_target" }
+  | { kind: "refused"; message: string };
+
+/**
+ * `consolidate apply` for `action = 'identity_update'`. Routes the write
+ * exclusively through `applyConsolidationIdentityUpdate` (the allowlist gate)
+ * -- there is no other reachable path to an identity write from this
+ * function. A refused layer writes NOTHING: no identity row, no readiness
+ * advance, no consolidation status change (mirrors Python's `sys.exit(1)`
+ * before any of those side effects run).
+ */
+export function applyIdentityUpdate(
+  db: WritableDatabase,
+  consolidation: ConsolidationRow,
+  resultContent: string,
+  ids: { id: string; nowIso: string },
+): IdentityUpdateOutcome {
+  if (!consolidation.target_layer || !consolidation.target_key) {
+    return { kind: "missing_target" };
+  }
+  try {
+    applyConsolidationIdentityUpdate(db, {
+      targetLayer: consolidation.target_layer,
+      targetKey: consolidation.target_key,
+      content: resultContent,
+      id: ids.id,
+      nowIso: ids.nowIso,
+    });
+  } catch (error) {
+    return { kind: "refused", message: error instanceof Error ? error.message : String(error) };
+  }
+
+  const sourceIds = sourceMemoryIds(consolidation);
+  for (const memoryId of sourceIds) {
+    updateMemoryReadinessState(db, memoryId, "acknowledged");
+  }
+  updateConsolidationStatus(db, consolidation.id, "accepted", resultContent, ids.nowIso);
+  return {
+    kind: "applied",
+    targetLayer: consolidation.target_layer,
+    targetKey: consolidation.target_key,
+    sourceMemoryIds: sourceIds,
+  };
+}
+
+// --- consolidate apply: shadow_candidate --------------------------------------
+
+export interface ShadowCandidateOutcome {
+  sourceMemoryIds: string[];
+}
+
+/**
+ * `consolidate apply` for `action = 'shadow_candidate'`: advances every
+ * source memory's readiness to `'candidate'` for the next `mm-shadow` pass,
+ * then records the consolidation as accepted.
+ */
+export function applyShadowCandidate(
+  db: WritableDatabase,
+  consolidation: ConsolidationRow,
+  resultContent: string,
+  nowIso: string,
+): ShadowCandidateOutcome {
+  const sourceIds = sourceMemoryIds(consolidation);
+  for (const memoryId of sourceIds) {
+    updateMemoryReadinessState(db, memoryId, "candidate");
+  }
+  updateConsolidationStatus(db, consolidation.id, "accepted", resultContent, nowIso);
+  return { sourceMemoryIds: sourceIds };
+}
+
+// --- shadow apply --------------------------------------------------------------
+
+export interface ShadowApplyOutcome {
+  targetKey: string;
+  sourceMemoryIds: string[];
+}
+
+/**
+ * `shadow apply`: append (or create) the structural `shadow` identity layer at
+ * `target_key` (default `'profile'`), advance source memories to
+ * `'acknowledged'`, and record acceptance. SAFETY: `layer` is the HARDCODED
+ * constant `"shadow"` -- never read from `consolidation.target_layer` or any
+ * other proposal field. Only `target_key` (or the `'profile'` default) is
+ * model-influenced; that is the entire allowed surface, matching Python's
+ * `mem.store.upsert_identity(Identity(layer="shadow", key=target_key, ...))`.
+ */
+export function applyShadowApply(
+  db: WritableDatabase,
+  consolidation: ConsolidationRow,
+  resultContent: string,
+  ids: { id: string; nowIso: string },
+): ShadowApplyOutcome {
+  const targetKey = consolidation.target_key ?? "profile";
+  const existingContent = getIdentityContent(db, "shadow", targetKey);
+  const updatedContent =
+    existingContent !== null
+      ? `${existingContent.trimEnd()}\n\n---\n\n${resultContent}`
+      : resultContent;
+
+  upsertIdentity(
+    db,
+    {
+      id: ids.id,
+      layer: "shadow",
+      key: targetKey,
+      content: updatedContent,
+      version: "1.0.0",
+      metadata: null,
+    },
+    ids.nowIso,
+  );
+
+  const sourceIds = sourceMemoryIds(consolidation);
+  for (const memoryId of sourceIds) {
+    updateMemoryReadinessState(db, memoryId, "acknowledged");
+  }
+  updateConsolidationStatus(db, consolidation.id, "accepted", resultContent, ids.nowIso);
+  return { targetKey, sourceMemoryIds: sourceIds };
+}
+
+// --- consolidate apply: merge (Slice B -- needs a fresh embedding) -----------
+
+export type MergeOutcome =
+  | { kind: "merged"; mergedMemoryId: string; mergedTitle: string; sourceMemoryIds: string[] }
+  | { kind: "source_not_found" };
+
+export interface ApplyMergeOptions {
+  embeddingProvider: EmbeddingProvider;
+  /** The NEW merged memory's id, injected (DS4 determinism idiom) -- unrelated to `consolidation.id`. */
+  id: string;
+  nowIso: string;
+  onEmbeddingAttempt?: (info: EmbeddingAttemptInfo) => void;
+}
+
+/**
+ * `consolidate apply` for `action = 'merge'`: distill the cluster into one
+ * sharper memory. Reads the FIRST source memory only for `memory_type`/
+ * `layer`/`journey` (Python's `first = mem.store.get_memory(source_ids[0])`),
+ * titles the merge `"[merged] {first.title}"`, sets `context` to the exact
+ * `"Merged from: {id, id, ...}"` provenance string (source id order, not
+ * sorted), embeds `resultContent` via the injected `EmbeddingProvider`
+ * (replay under DS7, live under DS8), stamps embedding provenance, marks
+ * every source memory `'integrated'`, and records acceptance. A missing
+ * first source memory returns `source_not_found` -- no memory row, no
+ * readiness advance, no consolidation status change, mirroring Python's
+ * `sys.exit(1)` before any side effect runs.
+ */
+export async function applyMerge(
+  db: WritableDatabase,
+  consolidation: ConsolidationRow,
+  resultContent: string,
+  options: ApplyMergeOptions,
+): Promise<MergeOutcome> {
+  const sourceIds = sourceMemoryIds(consolidation);
+  const first = getMemorySourceForMerge(db, sourceIds[0] as string);
+  if (first === null) {
+    return { kind: "source_not_found" };
+  }
+
+  const embedding = await generateEmbeddingSafely(options.embeddingProvider, resultContent, {
+    onAttempt: options.onEmbeddingAttempt,
+  });
+
+  createMemoryRow(db, {
+    id: options.id,
+    memoryType: first.memory_type,
+    layer: first.layer,
+    title: `[merged] ${first.title}`,
+    content: resultContent,
+    journey: first.journey,
+    context: `Merged from: ${sourceIds.join(", ")}`,
+    createdAt: options.nowIso,
+    relevanceScore: 1.0,
+    embedding: embeddingToBytes(embedding),
+    metadata: addEmbeddingProvenance(null),
+  });
+
+  for (const memoryId of sourceIds) {
+    updateMemoryReadinessState(db, memoryId, "integrated");
+  }
+  updateConsolidationStatus(db, consolidation.id, "accepted", resultContent, options.nowIso);
+  return {
+    kind: "merged",
+    mergedMemoryId: options.id,
+    mergedTitle: `[merged] ${first.title}`,
+    sourceMemoryIds: sourceIds,
+  };
+}

package/ts/src/cultivation/cluster.ts

@@ -0,0 +1,86 @@
+// Port of `cluster_memories` (`src/memory/intelligence/consolidate.py`,
+// CV22.DS7.US3). Pure function, no DB/clock/provider dependency -- graded
+// against the Python oracle by a committed synthetic-embedding golden
+// (`ts/parity/generate_cluster_golden.py`).
+//
+// Greedy single-linkage: a memory joins an existing cluster when its cosine
+// similarity to the cluster SEED (the first member, never re-derived as a
+// centroid) meets the threshold. A memory can only belong to one cluster
+// (first match wins). Memories with no embedding or in a terminal readiness
+// state are skipped up front; singleton groups (clusters of one) are dropped.
+
+import { blobToFloat32 } from "#db/decode.ts";
+import { cosineSimilarity } from "#search/ranker.ts";
+import type { CultivationMemory } from "./consolidationStore.ts";
+
+/** Mirrors Python's `DEFAULT_CLUSTER_THRESHOLD`. */
+export const DEFAULT_CLUSTER_THRESHOLD = 0.75;
+
+/** Mirrors Python's `MAX_CLUSTER_SIZE` -- caps memories per cluster (prevents unwieldy LLM prompts). */
+export const MAX_CLUSTER_SIZE = 5;
+
+/** Mirrors Python's `_TERMINAL_STATES` -- readiness states already "done", skipped for clustering. */
+const TERMINAL_READINESS_STATES: ReadonlySet<string> = new Set(["integrated"]);
+
+/**
+ * The input shape `clusterMemories` needs: a cultivation memory whose
+ * embedding MAY be absent (`null`), mirroring Python's `Memory.embedding:
+ * bytes | None`. `CultivationMemoryWithEmbedding` (embedding always present,
+ * guaranteed by the `embedding IS NOT NULL` SQL filter) is structurally
+ * assignable here -- the real `consolidate scan` read path never actually
+ * exercises the null branch, but the defensive skip is still a faithful part
+ * of the ported function and is proven directly by the golden/unit tests.
+ */
+export interface ClusterableMemory extends CultivationMemory {
+  embedding_b64: string | null;
+}
+
+/**
+ * Group semantically similar memories into clusters, byte-for-byte matching
+ * Python's `cluster_memories` algorithm and iteration order (both the outer
+ * seed scan and the inner candidate scan iterate the SAME `eligible` array in
+ * its original order -- not a shrinking remainder -- with `assigned` doing
+ * the exclusion).
+ */
+export function clusterMemories<T extends ClusterableMemory>(
+  memories: readonly T[],
+  threshold: number = DEFAULT_CLUSTER_THRESHOLD,
+): T[][] {
+  const eligible = memories.filter(
+    (memory) =>
+      memory.embedding_b64 !== null && !TERMINAL_READINESS_STATES.has(memory.readiness_state),
+  );
+  if (eligible.length < 2) return [];
+
+  const embeddings = new Map<string, Float32Array>();
+  for (const memory of eligible) {
+    embeddings.set(memory.id, blobToFloat32(Buffer.from(memory.embedding_b64 as string, "base64")));
+  }
+
+  const assigned = new Set<string>();
+  const clusters: T[][] = [];
+
+  for (const seed of eligible) {
+    if (assigned.has(seed.id)) continue;
+    const cluster: T[] = [seed];
+    assigned.add(seed.id);
+    const seedEmbedding = embeddings.get(seed.id) as Float32Array;
+
+    for (const candidate of eligible) {
+      if (assigned.has(candidate.id)) continue;
+      if (cluster.length >= MAX_CLUSTER_SIZE) break;
+      const similarity = cosineSimilarity(
+        seedEmbedding,
+        embeddings.get(candidate.id) as Float32Array,
+      );
+      if (similarity >= threshold) {
+        cluster.push(candidate);
+        assigned.add(candidate.id);
+      }
+    }
+
+    if (cluster.length >= 2) clusters.push(cluster);
+  }
+
+  return clusters;
+}

package/ts/src/cultivation/consolidationStore.ts

@@ -0,0 +1,281 @@
+// Consolidation persistence + cultivation memory reads (CV22.DS7.US3).
+//
+// A faithful TypeScript port of `ConsolidationStore`
+// (`src/memory/storage/consolidations.py`) plus the two `Store` memory reads
+// `consolidate`/`shadow` depend on: `get_all_memories_with_embeddings` (used by
+// `consolidate scan`, filtered client-side in Python -- pushed down to SQL here,
+// same database-seam philosophy as DS2/US2) and `get_shadow_candidate_memories`
+// (used by `shadow scan`). The `consolidations` table and `memories.readiness_state`
+// column already exist in the TS-authored schema (DS6) -- no new migration here.
+
+import type { Database, SqlValue, WritableDatabase } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+/** A consolidation row, mirroring the Python `Consolidation` model exactly. */
+export interface ConsolidationRow {
+  id: string;
+  action: string; // 'merge' | 'identity_update' | 'shadow_candidate' | 'shadow_observation'
+  proposal: string;
+  result: string | null;
+  source_memory_ids: string; // JSON-encoded array of Memory.id values
+  target_layer: string | null;
+  target_key: string | null;
+  rationale: string | null;
+  status: string; // 'pending' | 'accepted' | 'rejected'
+  created_at: string;
+  reviewed_at: string | null;
+}
+
+const CONSOLIDATION_COLUMNS =
+  "id, action, proposal, result, source_memory_ids, target_layer, target_key, " +
+  "rationale, status, created_at, reviewed_at";
+
+function toConsolidation(row: Record<string, unknown>): ConsolidationRow {
+  return {
+    id: requireString(row, "id"),
+    action: requireString(row, "action"),
+    proposal: requireString(row, "proposal"),
+    result: optionalString(row, "result"),
+    source_memory_ids: requireString(row, "source_memory_ids"),
+    target_layer: optionalString(row, "target_layer"),
+    target_key: optionalString(row, "target_key"),
+    rationale: optionalString(row, "rationale"),
+    status: requireString(row, "status"),
+    created_at: requireString(row, "created_at"),
+    reviewed_at: optionalString(row, "reviewed_at"),
+  };
+}
+
+// --- Consolidations ----------------------------------------------------------
+
+/** Port of `ConsolidationStore.create_consolidation`. Returns the row as-is. */
+export function createConsolidation(
+  db: WritableDatabase,
+  consolidation: ConsolidationRow,
+): ConsolidationRow {
+  db.prepare(
+    `INSERT INTO consolidations (${CONSOLIDATION_COLUMNS}) ` +
+      "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  ).run(
+    consolidation.id,
+    consolidation.action,
+    consolidation.proposal,
+    consolidation.result,
+    consolidation.source_memory_ids,
+    consolidation.target_layer,
+    consolidation.target_key,
+    consolidation.rationale,
+    consolidation.status,
+    consolidation.created_at,
+    consolidation.reviewed_at,
+  );
+  return consolidation;
+}
+
+/** Port of `ConsolidationStore.get_consolidation`. */
+export function getConsolidation(db: Database, id: string): ConsolidationRow | null {
+  const row = db
+    .prepare(`SELECT ${CONSOLIDATION_COLUMNS} FROM consolidations WHERE id = ?`)
+    .get(id);
+  return row === undefined ? null : toConsolidation(row);
+}
+
+/**
+ * Port of `ConsolidationStore.update_consolidation_status`: `result` is
+ * `COALESCE(?, result)` -- passing `null` preserves the existing `result`
+ * (Python's default `result: str | None = None` parameter), matching a
+ * `reject` call (no result) leaving `result` untouched.
+ */
+export function updateConsolidationStatus(
+  db: WritableDatabase,
+  id: string,
+  status: string,
+  result: string | null,
+  nowIso: string,
+): void {
+  db.prepare(
+    "UPDATE consolidations SET status = ?, result = COALESCE(?, result), reviewed_at = ? WHERE id = ?",
+  ).run(status, result, nowIso, id);
+}
+
+/** Filters for `listConsolidations`, mirroring the Python signature. */
+export interface ListConsolidationsFilters {
+  status?: string | null;
+  limit?: number;
+}
+
+/**
+ * Port of `ConsolidationStore.list_consolidations`: a `1=1` seed, an optional
+ * `status = ?` clause, `ORDER BY created_at DESC`, trailing `LIMIT ?`.
+ */
+export function listConsolidations(
+  db: Database,
+  filters: ListConsolidationsFilters = {},
+): ConsolidationRow[] {
+  const { status = null, limit = 20 } = filters;
+  const conditions = ["1=1"];
+  const params: SqlValue[] = [];
+  if (status) {
+    conditions.push("status = ?");
+    params.push(status);
+  }
+  params.push(limit);
+  return db
+    .prepare(
+      `SELECT ${CONSOLIDATION_COLUMNS} FROM consolidations WHERE ${conditions.join(" AND ")} ` +
+        "ORDER BY created_at DESC LIMIT ?",
+    )
+    .all(...params)
+    .map(toConsolidation);
+}
+
+/**
+ * Port of the `_resolve_proposal` helper duplicated in both
+ * `cli/consolidate_cmd.py` and `cli/shadow_cmd.py`: exact id first, else a
+ * first-match-wins scan (by `created_at DESC` order) over the most recent 200
+ * consolidations. Deliberately kept SEPARATE from `resolveTaskByIdOrPrefix`
+ * (US2): Python itself has no ambiguous-match branch here (unlike tasks) --
+ * the first prefix hit in listing order simply wins, so unifying the two
+ * resolvers would invent a branch Python does not have.
+ */
+export function resolveProposalByIdOrPrefix(
+  db: Database,
+  idOrPrefix: string,
+): ConsolidationRow | null {
+  const exact = getConsolidation(db, idOrPrefix);
+  if (exact) return exact;
+  const recent = listConsolidations(db, { limit: 200 });
+  return recent.find((item) => item.id.startsWith(idOrPrefix)) ?? null;
+}
+
+// --- Memory readiness ---------------------------------------------------------
+
+/**
+ * Port of `ConsolidationStore.update_memory_readiness_state`. Valid states:
+ * observed | candidate | surfaced | acknowledged | integrated. One statement,
+ * one implicit commit -- callers must NOT wrap a sequence of these (plus a
+ * sibling write) in an explicit transaction; Python commits each call
+ * separately and the port preserves that commit boundary exactly.
+ */
+export function updateMemoryReadinessState(
+  db: WritableDatabase,
+  memoryId: string,
+  state: string,
+): void {
+  db.prepare("UPDATE memories SET readiness_state = ? WHERE id = ?").run(state, memoryId);
+}
+
+// --- Cultivation memory reads --------------------------------------------------
+
+/** The memory projection cultivation formatting needs, shared by both scans. */
+export interface CultivationMemory {
+  id: string;
+  memory_type: string;
+  layer: string;
+  title: string;
+  content: string;
+  context: string | null;
+  journey: string | null;
+  created_at: string;
+  readiness_state: string;
+}
+
+/** A cultivation memory with its embedding, for clustering (`consolidate scan`). */
+export interface CultivationMemoryWithEmbedding extends CultivationMemory {
+  embedding_b64: string;
+}
+
+const CULTIVATION_COLUMNS_BASE =
+  "id, memory_type, layer, title, content, context, journey, created_at, readiness_state";
+
+function toCultivationMemory(row: Record<string, unknown>): CultivationMemory {
+  return {
+    id: requireString(row, "id"),
+    memory_type: requireString(row, "memory_type"),
+    layer: requireString(row, "layer"),
+    title: requireString(row, "title"),
+    content: requireString(row, "content"),
+    context: optionalString(row, "context"),
+    journey: optionalString(row, "journey"),
+    created_at: requireString(row, "created_at"),
+    readiness_state: requireString(row, "readiness_state"),
+  };
+}
+
+/** Optional equality filters for the cultivation memory reads. */
+export interface CultivationMemoryFilters {
+  journey?: string | null;
+  layer?: string | null;
+}
+
+/**
+ * Port of `Store.get_all_memories_with_embeddings`, plus the `--journey`/
+ * `--layer` filters `consolidate_cmd.cmd_scan` applies client-side in Python
+ * -- pushed down into the SQL `WHERE` here (same result set, DS2/US2's
+ * query-builder philosophy). `ORDER BY created_at DESC`, matching Python.
+ */
+export function getMemoriesWithEmbeddingsForCultivation(
+  db: Database,
+  filters: CultivationMemoryFilters = {},
+): CultivationMemoryWithEmbedding[] {
+  const conditions = ["embedding IS NOT NULL"];
+  const params: SqlValue[] = [];
+  if (filters.journey) {
+    conditions.push("journey = ?");
+    params.push(filters.journey);
+  }
+  if (filters.layer) {
+    conditions.push("layer = ?");
+    params.push(filters.layer);
+  }
+  return db
+    .prepare(
+      `SELECT ${CULTIVATION_COLUMNS_BASE}, embedding FROM memories ` +
+        `WHERE ${conditions.join(" AND ")} ORDER BY created_at DESC`,
+    )
+    .all(...params)
+    .map((row) => {
+      const embedding = row.embedding;
+      if (!(embedding instanceof Uint8Array)) {
+        throw new Error("memory embedding must be a BLOB/Uint8Array");
+      }
+      return {
+        ...toCultivationMemory(row),
+        embedding_b64: Buffer.from(embedding).toString("base64"),
+      };
+    });
+}
+
+/** Filters for `getShadowCandidateMemories`, mirroring the Python signature. */
+export interface ShadowCandidateFilters {
+  readinessStates?: readonly string[];
+  limit?: number;
+}
+
+const DEFAULT_SHADOW_READINESS_STATES: readonly string[] = ["observed", "candidate"];
+
+/**
+ * Port of `Store.get_shadow_candidate_memories`: memories with `layer =
+ * 'shadow'` OR `memory_type IN ('tension', 'pattern')`, restricted to the
+ * given readiness states (default `observed`/`candidate`), `ORDER BY
+ * created_at DESC LIMIT ?`. No embedding requirement -- shadow candidates need
+ * not have been embedded.
+ */
+export function getShadowCandidateMemories(
+  db: Database,
+  filters: ShadowCandidateFilters = {},
+): CultivationMemory[] {
+  const readinessStates = filters.readinessStates ?? DEFAULT_SHADOW_READINESS_STATES;
+  const limit = filters.limit ?? 100;
+  const placeholders = readinessStates.map(() => "?").join(", ");
+  const params: SqlValue[] = [...readinessStates, limit];
+  return db
+    .prepare(
+      `SELECT ${CULTIVATION_COLUMNS_BASE} FROM memories ` +
+        "WHERE (layer = 'shadow' OR memory_type IN ('tension', 'pattern')) " +
+        `AND readiness_state IN (${placeholders}) ` +
+        "ORDER BY created_at DESC LIMIT ?",
+    )
+    .all(...params)
+    .map(toCultivationMemory);
+}

package/ts/src/cultivation/promptContext.ts

@@ -0,0 +1,62 @@
+// The two inputs `cmd_scan` resolves from the database before calling the
+// LLM (CV22.DS8.TS2): the owner's first name and the identity context the
+// consolidation prompt shows the model. Ports `cli/shadow_cmd.py:_user_name`
+// and `cli/consolidate_cmd.py:_identity_context`.
+//
+// On the name: Python has TWO resolvers for these leaves. `shadow_cmd` uses
+// the regex below; `consolidate_cmd` first short-circuits on the literal
+// owner's name being anywhere in the content (a distribution defect, CR014).
+// TS ships one resolver, the regex form. The only input where the two Python
+// forms disagree is content that names the owner without the seed template's
+// "speaking with" line, which no shipped template produces; the golden's
+// `resolvers` section records both columns so the deviation stays visible
+// (plan decision D1, docs/project/decisions.md).
+//
+// This is NOT the close tail's `resolveUserName` (`conversation/extraction.ts`),
+// which ports a third oracle (`You are talking to`). Unifying the three is
+// CR014's job, not this story's.
+
+import type { Database } from "#db/database.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { sliceCodePoints } from "#util/pythonText.ts";
+
+/** Python's `\w+` on a `str` pattern: Unicode letters, digits, underscore. A
+ * combining mark (Mn) is not a word character in either engine. */
+const SPEAKING_WITH = /speaking with ([\p{L}\p{N}_]+)/u;
+
+/** Python's fallback when the row or the marker phrase is absent. */
+export const FALLBACK_USER_NAME = "the user";
+
+/** Port of `shadow_cmd._user_name`: the owner's first name from `user/identity`. */
+export function cultivationUserName(db: Database): string {
+  const content = getIdentityContent(db, "user", "identity");
+  const match = content?.match(SPEAKING_WITH);
+  return match?.[1] ?? FALLBACK_USER_NAME;
+}
+
+/** `entry.content[:600]` -- code points, not UTF-16 units. */
+export const IDENTITY_CONTEXT_CODE_POINTS = 600;
+
+/** The layers `_identity_context` reads, in Python's order. */
+const IDENTITY_CONTEXT_LAYERS: readonly (readonly [string, string])[] = [
+  ["ego", "behavior"],
+  ["ego", "identity"],
+  ["self", "soul"],
+];
+
+/** Python's fallback when none of the three rows exists. */
+export const FALLBACK_IDENTITY_CONTEXT = "(no identity context loaded)";
+
+/**
+ * Port of `consolidate_cmd._identity_context`: a brief, system-side identity
+ * digest for the consolidation prompt's IDENTITY_UPDATE reference.
+ */
+export function consolidationIdentityContext(db: Database): string {
+  const parts: string[] = [];
+  for (const [layer, key] of IDENTITY_CONTEXT_LAYERS) {
+    const content = getIdentityContent(db, layer, key);
+    if (content === null) continue;
+    parts.push(`## ${layer}/${key}\n${sliceCodePoints(content, IDENTITY_CONTEXT_CODE_POINTS)}`);
+  }
+  return parts.length > 0 ? parts.join("\n\n") : FALLBACK_IDENTITY_CONTEXT;
+}