mirror-mind 0.0.1 → 0.32.1

package/ts/src/seed/seed.ts

@@ -0,0 +1,256 @@
+// `seed` orchestration — the port of memory.cli.seed.seed(). Scans the
+// identity-template YAML tree and upserts core identity, personas, and
+// journeys, in that order, reusing the already-ported `setIdentity` write
+// primitive. Operates on an already-open `WritableDatabase` and an
+// already-resolved `identityRoot`; CLI-level resolution (mirror home, env,
+// the header print lines) lives in ../frontDoor/cli.ts, matching how every
+// other write in this port keeps CLI argument/env handling out of the pure
+// orchestration.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { identityRowExists } from "#identity/identityRead.ts";
+import { setIdentity } from "#identity/setIdentity.ts";
+import { PROGRAM } from "#util/program.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { shellWord } from "#util/shellWord.ts";
+import {
+  loadJourneyContent,
+  loadPersonaContent,
+  loadYamlContent,
+  YamlFileNotFoundError,
+} from "./seedYaml.ts";
+
+interface CoreIdentityMapping {
+  layer: string;
+  key: string;
+  yamlPath: string;
+  field: string;
+}
+
+/** Port of `IDENTITY_MAP`. Order matters: it is the scan/print order. */
+const IDENTITY_MAP: readonly CoreIdentityMapping[] = [
+  { layer: "self", key: "soul", yamlPath: "self/soul.yaml", field: "soul" },
+  { layer: "ego", key: "identity", yamlPath: "ego/identity.yaml", field: "identity" },
+  { layer: "ego", key: "behavior", yamlPath: "ego/behavior.yaml", field: "behavior" },
+  { layer: "ego", key: "constraints", yamlPath: "ego/constraints.yaml", field: "constraints" },
+  { layer: "ego", key: "expression", yamlPath: "ego/expression.yaml", field: "expression" },
+  { layer: "user", key: "identity", yamlPath: "user/identity.yaml", field: "user" },
+  {
+    layer: "organization",
+    key: "identity",
+    yamlPath: "organization/identity.yaml",
+    field: "identity",
+  },
+  {
+    layer: "organization",
+    key: "principles",
+    yamlPath: "organization/principles.yaml",
+    field: "principles",
+  },
+  { layer: "shadow", key: "profile", yamlPath: "shadow/profile.yaml", field: "profile" },
+];
+
+/** Port of `_REQUIRED_IDENTITY_KEYS`: a missing file here is a recorded error;
+ * a missing file for any other mapping is a fully silent skip. */
+const REQUIRED_IDENTITY_KEYS = new Set([
+  "self/soul",
+  "ego/identity",
+  "ego/behavior",
+  "user/identity",
+]);
+
+export interface SeedResult {
+  created: number;
+  updated: number;
+  skipped: number;
+  errors: string[];
+  /** One entry per scan-time print line, in Python's exact emission order. */
+  lines: string[];
+}
+
+/**
+ * The command that edits an entry seed skipped. It is printed to be run as is, and
+ * a key from before CR104's grammar can hold shell syntax, so every value in it
+ * is one shell word. It named `memory`, the Python program, until CR104 (D1).
+ */
+function editCommand(layer: string, key: string): string {
+  return `${PROGRAM} identity edit ${shellWord(layer)} ${shellWord(key)}`;
+}
+
+function record(
+  result: SeedResult,
+  existing: boolean,
+  force: boolean,
+  label: string,
+  editHint: string,
+): boolean {
+  if (existing && !force) {
+    result.skipped += 1;
+    result.lines.push(`  \u2192 ${label} (skipped \u2014 to update, run: ${editHint})`);
+    return false;
+  }
+  return true;
+}
+
+function seedCoreIdentity(
+  db: WritableDatabase,
+  identityRoot: string,
+  force: boolean,
+  result: SeedResult,
+  readFile: (path: string) => string,
+): void {
+  for (const mapping of IDENTITY_MAP) {
+    const label = `${mapping.layer}/${mapping.key}`;
+    try {
+      const { content, version } = loadYamlContent(
+        join(identityRoot, mapping.yamlPath),
+        mapping.field,
+        readFile,
+      );
+      if (!content) {
+        result.errors.push(`${label}: empty content`);
+        continue;
+      }
+      const existing = identityRowExists(db, mapping.layer, mapping.key);
+      if (!record(result, existing, force, label, editCommand(mapping.layer, mapping.key))) {
+        continue;
+      }
+      setIdentity(
+        db,
+        { id: newId(), layer: mapping.layer, key: mapping.key, content, version },
+        nowIso(),
+      );
+      if (existing) {
+        result.updated += 1;
+        result.lines.push(`  \u21bb ${label} (updated)`);
+      } else {
+        result.created += 1;
+        result.lines.push(`  \u2713 ${label}`);
+      }
+    } catch (error) {
+      if (error instanceof YamlFileNotFoundError) {
+        if (REQUIRED_IDENTITY_KEYS.has(label)) {
+          result.errors.push(`${label}: ${error.message}`);
+          result.lines.push(`  \u2717 ${label}: ${error.message}`);
+        }
+        // Else: fully silent skip for a missing, non-required file -- matches
+        // Python exactly (no error recorded, no line printed at all).
+        continue;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      result.errors.push(`${label}: ${message}`);
+      result.lines.push(`  \u2717 ${label}: ${message}`);
+    }
+  }
+}
+
+/** `.yaml` filenames directly under `dir`, sorted (mirrors `sorted(dir.glob("*.yaml"))`). */
+function yamlFileNames(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".yaml"))
+    .sort();
+}
+
+function seedPersonas(
+  db: WritableDatabase,
+  identityRoot: string,
+  force: boolean,
+  result: SeedResult,
+  readFile: (path: string) => string,
+): void {
+  const personasDir = join(identityRoot, "personas");
+  for (const fileName of yamlFileNames(personasDir)) {
+    const stem = fileName.slice(0, -".yaml".length);
+    try {
+      const { personaId, content, version, metadataJson } = loadPersonaContent(
+        join(personasDir, fileName),
+        readFile,
+      );
+      if (!content) continue;
+      const label = `persona/${personaId}`;
+      const existing = identityRowExists(db, "persona", personaId);
+      if (!record(result, existing, force, label, editCommand("persona", personaId))) {
+        continue;
+      }
+      setIdentity(
+        db,
+        { id: newId(), layer: "persona", key: personaId, content, version, metadata: metadataJson },
+        nowIso(),
+      );
+      if (existing) {
+        result.updated += 1;
+        result.lines.push(`  \u21bb ${label} (updated)`);
+      } else {
+        result.created += 1;
+        result.lines.push(`  \u2713 ${label}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      result.errors.push(`persona/${stem}: ${message}`);
+      result.lines.push(`  \u2717 persona/${stem}: ${message}`);
+    }
+  }
+}
+
+function seedJourneys(
+  db: WritableDatabase,
+  identityRoot: string,
+  force: boolean,
+  result: SeedResult,
+  readFile: (path: string) => string,
+): void {
+  const journeysDir = join(identityRoot, "journeys");
+  for (const fileName of yamlFileNames(journeysDir)) {
+    const stem = fileName.slice(0, -".yaml".length);
+    try {
+      const { journeyId, content, version } = loadJourneyContent(
+        join(journeysDir, fileName),
+        readFile,
+      );
+      if (!content) continue;
+      const label = `journey/${journeyId}`;
+      const existing = identityRowExists(db, "journey", journeyId);
+      if (!record(result, existing, force, label, editCommand("journey", journeyId))) {
+        continue;
+      }
+      setIdentity(
+        db,
+        { id: newId(), layer: "journey", key: journeyId, content, version },
+        nowIso(),
+      );
+      if (existing) {
+        result.updated += 1;
+        result.lines.push(`  \u21bb ${label} (updated)`);
+      } else {
+        result.created += 1;
+        result.lines.push(`  \u2713 ${label}`);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      result.errors.push(`journey/${stem}: ${message}`);
+      result.lines.push(`  \u2717 journey/${stem}: ${message}`);
+    }
+  }
+}
+
+/**
+ * Port of `seed()`'s three scan phases (core identity, personas, journeys),
+ * in order. Does NOT print the "Mirror home:"/"Identity root:" header lines —
+ * those depend on CLI-level resolution and are composed by the caller.
+ */
+export function runSeed(
+  db: WritableDatabase,
+  identityRoot: string,
+  options: { force?: boolean; readFile?: (path: string) => string } = {},
+): SeedResult {
+  const force = options.force ?? false;
+  const readFile = options.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+  const result: SeedResult = { created: 0, updated: 0, skipped: 0, errors: [], lines: [] };
+  seedCoreIdentity(db, identityRoot, force, result, readFile);
+  seedPersonas(db, identityRoot, force, result, readFile);
+  seedJourneys(db, identityRoot, force, result, readFile);
+  return result;
+}

package/ts/src/seed/seedYaml.ts

@@ -0,0 +1,133 @@
+// YAML template parsing for `seed` — the port of the load_* helpers in
+// memory.cli.seed. Uses the `yaml` package (safe `parse`, no arbitrary object
+// instantiation — the same trust boundary as Python's `yaml.safe_load`).
+
+import { basename } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/** Port of Python's uncaught `FileNotFoundError(f"File not found: {full_path}")`. */
+export class YamlFileNotFoundError extends Error {
+  readonly path: string;
+  constructor(path: string) {
+    super(`File not found: ${path}`);
+    this.path = path;
+  }
+}
+
+function asRecord(data: unknown): Record<string, unknown> {
+  return data !== null && typeof data === "object" && !Array.isArray(data)
+    ? (data as Record<string, unknown>)
+    : {};
+}
+
+function stringField(data: Record<string, unknown>, field: string): string | null {
+  const value = data[field];
+  return typeof value === "string" ? value : null;
+}
+
+export interface CoreYamlContent {
+  content: string;
+  version: string;
+}
+
+/**
+ * Port of `load_yaml_content`: read one field (and `version`) from a YAML
+ * file. Throws YamlFileNotFoundError when the file is absent, matching
+ * Python's explicit check (not a generic ENOENT from the read itself).
+ */
+export function loadYamlContent(
+  fullPath: string,
+  field: string,
+  readFile: (path: string) => string,
+): CoreYamlContent {
+  let raw: string;
+  try {
+    raw = readFile(fullPath);
+  } catch {
+    throw new YamlFileNotFoundError(fullPath);
+  }
+  const data = asRecord(parseYaml(raw));
+  return {
+    content: stringField(data, field) ?? "",
+    version: stringField(data, "version") ?? "1.0.0",
+  };
+}
+
+export interface PersonaYamlContent {
+  personaId: string;
+  content: string;
+  version: string;
+  /** Canonical (plain JSON.stringify) form, per the DS6 identity.metadata
+   * decision: byte-mimicking Python's json.dumps spacing was the transition
+   * contract only; every reader JSON.parses, so key order (preserved by
+   * object-literal insertion order here) is what matters, not whitespace. */
+  metadataJson: string;
+}
+
+/** Port of `load_persona_content`. */
+export function loadPersonaContent(
+  fullPath: string,
+  readFile: (path: string) => string,
+): PersonaYamlContent {
+  const data = asRecord(parseYaml(readFile(fullPath)));
+  const stem = basename(fullPath, ".yaml");
+  const personaId = stringField(data, "persona_id") ?? stem;
+  const version = stringField(data, "version") ?? "1.0.0";
+
+  const parts: string[] = [];
+  const systemPrompt = stringField(data, "system_prompt");
+  if (systemPrompt) parts.push(systemPrompt);
+  const briefing = stringField(data, "briefing");
+  if (briefing) parts.push(`\n\n# Briefing\n\n${briefing}`);
+
+  const rawKeywords = data.routing_keywords;
+  const routingKeywords = Array.isArray(rawKeywords)
+    ? rawKeywords.filter((item): item is string => typeof item === "string")
+    : [];
+  const metadata = {
+    persona_id: personaId,
+    name: stringField(data, "name"),
+    inherits_from: stringField(data, "inherits_from"),
+    description: stringField(data, "description"),
+    routing_keywords: routingKeywords,
+    default_model: stringField(data, "default_model"),
+  };
+
+  return {
+    personaId,
+    content: parts.join(""),
+    version,
+    metadataJson: JSON.stringify(metadata),
+  };
+}
+
+export interface JourneyYamlContent {
+  journeyId: string;
+  content: string;
+  version: string;
+}
+
+/** Port of `load_journey_content` (`_resolve_journey_id` inlined). */
+export function loadJourneyContent(
+  fullPath: string,
+  readFile: (path: string) => string,
+): JourneyYamlContent {
+  const data = asRecord(parseYaml(readFile(fullPath)));
+  const stem = basename(fullPath, ".yaml");
+  const journeyId = stringField(data, "journey_id") || stem;
+  const version = stringField(data, "version") ?? "1.0.0";
+
+  const parts: string[] = [];
+  const name = stringField(data, "name");
+  if (name) parts.push(`# ${name}`);
+  const status = stringField(data, "status");
+  if (status) parts.push(`**Status:** ${status}`);
+  const description = stringField(data, "description");
+  if (description) parts.push(`\n## Description\n\n${description}`);
+  const briefing = stringField(data, "briefing");
+  if (briefing) parts.push(`\n## Briefing\n\n${briefing}`);
+  const context = stringField(data, "context");
+  if (context) parts.push(`\n## Context\n\n${context}`);
+
+  return { journeyId, content: parts.join("\n"), version };
+}

package/ts/src/soul/apply.ts

@@ -0,0 +1,218 @@
+// CV22.DS7.US6 plateau 4 — the Soul Mode identity integration, ported from
+// `apply_identity_integration` and `append_identity_integration_to_content`
+// (`src/memory/services/soul.py`).
+//
+// This is the only write in Soul Mode that touches identity, and it does two
+// things: an audit row in `identity_integrations`, and a dated bullet appended
+// into the identity DOCUMENT under a layer-specific section title.
+//
+// On the allowlist question: this write deliberately does NOT go through
+// `applyConsolidationIdentityUpdate`. Python is explicit that the consolidation
+// allowlist is narrow to the `propose_consolidation` -> accept flow, where the
+// target layer is MODEL-CHOSEN and untrusted, and it names Soul Mode
+// integration as a caller of the general-purpose write instead. The two also
+// append differently -- consolidation joins raw content after a blank line,
+// Soul inserts a dated bullet inside a titled section -- so routing Soul
+// through that gate would change behavior, not just tighten it. Soul's own
+// guards are reproduced exactly: the layer must be one of the four section
+// titles, the content must be non-empty, and the CLI additionally requires
+// `--confirm APPLY`. Whether that is the right guard for ritual-authored text
+// is a product question recorded for Debt Review, not one a port may answer.
+//
+// The document surgery is index arithmetic over Markdown with three different
+// strip rules in five lines. Two are graded by the golden. The third,
+// `lstrip("\n")`, is reproduced faithfully but is provably UNREACHABLE as a
+// divergence: the slice it operates on begins at a `"\n## "` match, so after the
+// newlines the next character is always `#` and `trimStart()` would produce the
+// same string. Substituting `trimStart()` fails no scenario, and that is a fact
+// about the call site rather than a gap in the corpus -- recorded so nobody
+// later "strengthens" the test with a case that cannot exist.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { type IdentityRow, upsertIdentity } from "#identity/identityStore.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+import { pyRStrip, pyStrip, sliceCodePoints } from "#util/pythonText.ts";
+
+/** Port of `IDENTITY_INTEGRATION_SECTION_TITLES`. */
+export const IDENTITY_INTEGRATION_SECTION_TITLES: Readonly<Record<string, string>> = {
+  self: "New Incorporated Principles",
+  shadow: "New Hidden Needs Recognized",
+  ego: "New Operational Patterns Identified",
+  persona: "New Participation Patterns Revealed",
+};
+
+/** Python raises `ValueError`; the CLI renders it as `Error: <message>`. */
+export class SoulApplyError extends Error {}
+
+export interface IdentityIntegrationRow {
+  id: string;
+  layer: string;
+  key: string;
+  content: string;
+  source: string;
+  origin: string | null;
+  conversationId: string | null;
+  journalId: string | null;
+  createdAt: string;
+  status: string;
+  metadata: string;
+}
+
+export interface ApplyIdentityIntegrationInput {
+  layer: string;
+  key: string;
+  content: string;
+  origin?: string | null;
+  conversationId?: string | null;
+  journalId?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+export interface ApplyIdentityIntegrationResult {
+  integration: IdentityIntegrationRow;
+  updatedContent: string;
+}
+
+/** Python's `x.strip() if isinstance(x, str) and x.strip() else None`. */
+function strippedOrNull(value: string | null | undefined): string | null {
+  return typeof value === "string" && pyStrip(value) ? pyStrip(value) : null;
+}
+
+export function applyIdentityIntegration(
+  db: WritableDatabase,
+  input: ApplyIdentityIntegrationInput,
+  deps: { newId: () => string; nowIso: string },
+): ApplyIdentityIntegrationResult {
+  const normalized = pyStrip(input.content);
+  if (!normalized) throw new SoulApplyError("identity content must not be empty");
+  if (!(input.layer in IDENTITY_INTEGRATION_SECTION_TITLES)) {
+    throw new SoulApplyError(`unsupported psyche layer: ${input.layer}`);
+  }
+
+  const integration: IdentityIntegrationRow = {
+    id: deps.newId(),
+    layer: input.layer,
+    key: input.key,
+    content: normalized,
+    source: "soul_mode",
+    origin: strippedOrNull(input.origin),
+    conversationId: strippedOrNull(input.conversationId),
+    journalId: strippedOrNull(input.journalId),
+    createdAt: deps.nowIso,
+    status: "active",
+    // Python: json.dumps(metadata or {}, ensure_ascii=False, sort_keys=True).
+    // Note the sort: the harvest journal's metadata is NOT sorted, so the two
+    // Soul writes use different rules and each is pinned by its own golden.
+    metadata: pythonJsonDumpsSorted(input.metadata ?? {}),
+  };
+  addIdentityIntegration(db, integration);
+
+  const existingContent = getIdentityContent(db, input.layer, input.key);
+  const updatedContent = appendIdentityIntegrationToContent(existingContent ?? "", {
+    layer: input.layer,
+    content: integration.content,
+    createdAt: integration.createdAt,
+  });
+  upsertIdentity(
+    db,
+    identityRowFor(db, input.layer, input.key, updatedContent, deps.newId),
+    deps.nowIso,
+  );
+  return { integration, updatedContent };
+}
+
+/** Port of `Store.add_identity_integration`. */
+export function addIdentityIntegration(
+  db: WritableDatabase,
+  integration: IdentityIntegrationRow,
+): void {
+  db.prepare(
+    `INSERT INTO identity_integrations (
+       id, layer, key, content, source, origin, conversation_id,
+       journal_id, created_at, status, metadata
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    integration.id,
+    integration.layer,
+    integration.key,
+    integration.content,
+    integration.source,
+    integration.origin,
+    integration.conversationId,
+    integration.journalId,
+    integration.createdAt,
+    integration.status,
+    integration.metadata,
+  );
+}
+
+/**
+ * Port of `append_identity_integration_to_content`.
+ *
+ * Four branches: empty document, heading absent, heading last, heading followed
+ * by another `## ` section. Python matches the heading as a SUBSTRING, so a
+ * longer heading that contains the title is treated as the section -- preserved
+ * here rather than corrected.
+ */
+export function appendIdentityIntegrationToContent(
+  currentContent: string,
+  integration: { layer: string; content: string; createdAt: string },
+): string {
+  const title = IDENTITY_INTEGRATION_SECTION_TITLES[integration.layer];
+  if (title === undefined) {
+    throw new SoulApplyError(`unsupported psyche layer: ${integration.layer}`);
+  }
+  const date = sliceCodePoints(integration.createdAt, 10);
+  const bullet = `- [${date}] ${pyStrip(integration.content)}`;
+  const base = pyStrip(currentContent);
+  const heading = `## ${title}`;
+  if (!base) return `${heading}\n\n${bullet}`;
+  if (!base.includes(heading)) return `${base}\n\n${heading}\n\n${bullet}`;
+
+  const headingIndex = base.indexOf(heading);
+  const afterHeadingIndex = headingIndex + heading.length;
+  const nextSectionIndex = base.indexOf("\n## ", afterHeadingIndex);
+  const insertAt = nextSectionIndex === -1 ? base.length : nextSectionIndex;
+  const before = pyRStrip(base.slice(0, insertAt));
+  // Python `lstrip("\n")`: newline characters only, NOT whitespace.
+  // Python `lstrip("\n")`: newline characters only, NOT whitespace. Equivalent
+  // to `trimStart()` here because `insertAt` always points at a `"\n## "` match;
+  // kept in Python's form because that is what the oracle does.
+  const after = base.slice(insertAt).replace(/^\n+/, "");
+  const updated = `${before}\n${bullet}`;
+  return after ? `${updated}\n\n${after}` : updated;
+}
+
+/**
+ * Python passes `existing.model_copy(update={"content": ...})`, so an existing
+ * row keeps its id, version, and metadata and only its content moves.
+ */
+function identityRowFor(
+  db: WritableDatabase,
+  layer: string,
+  key: string,
+  content: string,
+  newId: () => string,
+): IdentityRow {
+  const existing = db
+    .prepare("SELECT id, version, metadata FROM identity WHERE layer = ? AND key = ?")
+    .get(layer, key) as { id: string; version: string; metadata: string | null } | undefined;
+  // Absent row: Python builds a fresh `Identity`, whose defaults are a new uuid,
+  // version "1.0.0", and NULL metadata.
+  return {
+    id: existing?.id ?? newId(),
+    layer,
+    key,
+    content,
+    version: existing?.version ?? "1.0.0",
+    metadata: existing?.metadata ?? null,
+  };
+}
+
+/** Python `json.dumps(value, ensure_ascii=False, sort_keys=True)`. */
+function pythonJsonDumpsSorted(value: Record<string, unknown>): string {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).sort()) sorted[key] = value[key];
+  return pythonJsonDumps(sorted);
+}