mirror-mind 0.0.1 → 0.32.1

package/ts/src/hooks/runtime.ts

@@ -0,0 +1,159 @@
+// Shared machinery for every Mirror hook entry.
+//
+// Two jobs, both learned from what the Python hooks did and what they hid.
+//
+// **Reuse the front door rather than reimplement it.** `cli.ts` exports
+// `main(argv)`, so a hook runs the exact route a skill or the Pi extension
+// runs -- same routing, same front-door log, same guards -- in ONE process.
+// The Claude inject hook used to start the interpreter up to five times per
+// prompt; it now starts Node once.
+//
+// **Never fail silently.** Every Python hook ended in `2>/dev/null || true`,
+// which was survivable because `python3` is on every macOS at /usr/bin. `node`
+// usually is not: it lives under nvm or Homebrew, and a GUI-launched runtime
+// does not inherit that PATH. The same silence would therefore hide a NEW
+// failure mode -- no logging, no inject, no close tail -- discovered weeks
+// later as "Mirror stopped remembering". So a hook that cannot do its job
+// writes one line to `<mirror-home>/hooks.log`, and `runtime diagnose` reports
+// whether Node is resolvable from hook context.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveMirrorHome } from "#frontDoor/dbPath.ts";
+import { runningTreeRoot } from "#runtime/treeRoot.ts";
+
+/** Where a hook records that it could not do its job. */
+export function hookLogPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  try {
+    const home = resolveMirrorHome(env as Parameters<typeof resolveMirrorHome>[0]);
+    return join(home, "hooks.log");
+  } catch {
+    // An unconfigured home has nowhere to complain to. Better than throwing
+    // from inside a hook, which would surface as a broken turn.
+    return null;
+  }
+}
+
+/**
+ * Append one line about a hook that could not complete.
+ *
+ * Redaction is the contract, not a nicety: this file records that something
+ * failed and which hook it was, NEVER the prompt or the response. The
+ * front-door log has the same rule (`hookPayloadRedaction.test.ts`), and hook
+ * entries bypass the CLI where that rule is enforced, so it is restated here
+ * and tested directly.
+ */
+export function noteHookFailure(hook: string, reason: string, env = process.env): void {
+  const path = hookLogPath(env);
+  if (!path) return;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const line = `${new Date().toISOString()} ${hook}: ${reason.split("\n")[0]}\n`;
+    appendFileSync(path, line, { encoding: "utf8", mode: 0o600 });
+  } catch {
+    // A hook cannot report that it could not report. Stop here.
+  }
+}
+
+/**
+ * The Operating Instructions a SessionStart hook should hand its runtime, or
+ * null when the project already carries this same file.
+ *
+ * CV22.DS10.US3, decision D13. An installed package reaches Claude Code and
+ * Gemini CLI through hooks, skills, and an MCP server; none of those reads a
+ * CLAUDE.md or GEMINI.md, so a session wired to the package would answer
+ * `/mm-mirror` and still route no mode, sign no persona, and hold no Builder
+ * boundary. Both runtimes read SessionStart's
+ * `hookSpecificOutput.additionalContext`, so the session-start hook returns
+ * `AGENTS.md` from the tree THIS code runs from -- the instructions always
+ * match the core they ship with -- unless the project the session opened in
+ * is that same tree (the checkout, whose CLAUDE.md imports the same file), in
+ * which case a second copy is noise. A file that cannot be read is recorded:
+ * a Mirror session without its instructions is not a Mirror session.
+ */
+export function operatingInstructionsFor(
+  hook: string,
+  projectDir: string | undefined,
+): string | null {
+  try {
+    const ours = join(runningTreeRoot(), "AGENTS.md");
+    const theirs = projectDir ? join(projectDir, "AGENTS.md") : "";
+    if (theirs && existsSync(theirs) && realpathSync(theirs) === realpathSync(ours)) return null;
+    return readFileSync(ours, "utf8");
+  } catch (error) {
+    noteHookFailure(
+      hook,
+      `operating instructions not delivered: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * The SessionStart answer both runtimes read: context as JSON, or `nothing`
+ * -- what each runtime's hook printed before D13 (Gemini `{}`, Claude none).
+ */
+export function sessionStartOutput(instructions: string | null, nothing = ""): string {
+  if (instructions === null) return nothing;
+  return `${JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: instructions },
+  })}\n`;
+}
+
+export interface FrontDoorRun {
+  readonly code: number;
+  readonly stdout: string;
+}
+
+/**
+ * Run a front-door command in this process, capturing what it printed.
+ *
+ * The capture is what lets the inject hook decide whether context was actually
+ * produced -- the shell version tested `[ -n "$CONTEXT" ]` on command
+ * substitution, and this is the same test without a second process.
+ */
+export async function runFrontDoor(argv: readonly string[]): Promise<FrontDoorRun> {
+  const { main } = await import("#frontDoor/cli.ts");
+  const chunks: string[] = [];
+  const original = process.stdout.write.bind(process.stdout);
+  // biome-ignore lint/suspicious/noExplicitAny: matching Node's overloaded write signature
+  (process.stdout as any).write = (chunk: any, ...rest: any[]): boolean => {
+    chunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    const callback = rest.find((argument) => typeof argument === "function");
+    if (callback) callback();
+    return true;
+  };
+  try {
+    const code = await main([...argv]);
+    return { code, stdout: chunks.join("") };
+  } finally {
+    process.stdout.write = original;
+  }
+}
+
+/**
+ * The command a failure line may name: the family and its subcommand, never
+ * the arguments. Arguments are where hooks put what the user said and what the
+ * model answered -- the Gemini logger passes the prompt and the response as
+ * argv -- and the first version of the failure line printed all of them (TS5
+ * handoff review, finding P1).
+ */
+function commandName(argv: readonly string[]): string {
+  return argv.slice(0, 2).join(" ");
+}
+
+/**
+ * Run a front-door command for its effect, swallowing failure the way the
+ * shell hooks did with `|| true` -- but recording it.
+ */
+export async function runFrontDoorQuietly(hook: string, argv: readonly string[]): Promise<void> {
+  try {
+    const result = await runFrontDoor(argv);
+    if (result.code !== 0) {
+      noteHookFailure(hook, `\`${commandName(argv)}\` exited ${result.code}`);
+    }
+  } catch (error) {
+    noteHookFailure(hook, error instanceof Error ? error.message : String(error));
+  }
+}

package/ts/src/identity/applyConsolidationIdentityUpdate.ts

@@ -0,0 +1,67 @@
+// TS port of `IdentityService.apply_consolidation_identity_update` (AI-23,
+// CV9.E2.S23) -- the identity-write allowlist gate behind `consolidate apply`'s
+// `identity_update` action (CV22.DS7.US3).
+//
+// Unlike `setIdentity` (general-purpose, unconditional write used for seeding,
+// Soul Mode integration, `identity set`, etc.), this is narrowly for the
+// propose_consolidation() -> mm-consolidate accept flow: `target_layer` is
+// model-chosen and untrusted, so it is checked against
+// `VALID_IDENTITY_UPDATE_LAYERS` before anything is written. A rejected layer
+// throws -- it never silently no-ops, never redirects, and never writes a
+// partial row. This is the ONE path `consolidate apply`'s `identity_update`
+// action may reach an identity write through; it must never call the ungated
+// `upsertIdentity`/`setIdentity` directly for that action.
+//
+// Preserves the accept flow's existing append semantics for an allowed write:
+// new content is appended after a blank line, never replaces existing content
+// outright -- the same shape as Python's `f"{existing.content.rstrip()}\n\n{content}"`.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { getIdentityContent } from "./identityRead.ts";
+import { type IdentityRow, upsertIdentity } from "./identityStore.ts";
+
+/** Mirrors `models.VALID_IDENTITY_UPDATE_LAYERS = frozenset({"self", "ego"})`. */
+export const VALID_IDENTITY_UPDATE_LAYERS: ReadonlySet<string> = new Set(["self", "ego"]);
+
+export interface ApplyConsolidationIdentityUpdateParams {
+  targetLayer: string;
+  targetKey: string;
+  content: string;
+  /** Injected id/now, the DS4 determinism idiom -- used only on INSERT. */
+  id: string;
+  nowIso: string;
+}
+
+/**
+ * Refuse a non-allowlisted `targetLayer` with the exact Python message and no
+ * write at all (no row, no partial row); otherwise append-or-create at parity.
+ *
+ * The thrown message is byte-identical to Python's:
+ * `Refusing identity_update to layer {target_layer!r}: not in the
+ * consolidation allowlist {sorted(VALID_IDENTITY_UPDATE_LAYERS)}.` --
+ * `sorted({"self", "ego"})` is `['ego', 'self']`, and Python's `!r` repr of a
+ * str is single-quoted.
+ */
+export function applyConsolidationIdentityUpdate(
+  db: WritableDatabase,
+  params: ApplyConsolidationIdentityUpdateParams,
+): void {
+  if (!VALID_IDENTITY_UPDATE_LAYERS.has(params.targetLayer)) {
+    throw new Error(
+      `Refusing identity_update to layer '${params.targetLayer}': not in ` +
+        "the consolidation allowlist ['ego', 'self'].",
+    );
+  }
+  const existingContent = getIdentityContent(db, params.targetLayer, params.targetKey);
+  const updatedContent =
+    existingContent !== null ? `${existingContent.trimEnd()}\n\n${params.content}` : params.content;
+  const row: IdentityRow = {
+    id: params.id,
+    layer: params.targetLayer,
+    key: params.targetKey,
+    content: updatedContent,
+    version: "1.0.0",
+    metadata: null,
+  };
+  upsertIdentity(db, row, params.nowIso);
+}

package/ts/src/identity/descriptorGenerate.ts

@@ -0,0 +1,162 @@
+/**
+ * `descriptor generate` — CV22.DS7.US11 plateau 5.
+ *
+ * Generates a routing descriptor per identity and upserts it. CR068 found this
+ * leaf unowned: DS7.US1 kept it on Python "as the DS7↔DS8 live seam", but DS8
+ * flips live mode and ports nothing, so its orchestration belongs here.
+ *
+ * Graded by `ts/test/goldens/descriptor.golden.json`. Two behaviours the
+ * corpus pins:
+ *
+ *   - **No ledger row.** `_cmd_generate` calls `generate_descriptor` WITHOUT an
+ *     `on_llm_call`, making this the only LLM role in the product that writes
+ *     nothing to `llm_calls`. The corpus records zero rows so a port cannot
+ *     "helpfully" start logging and diverge. Closing the gap is a DS8 input.
+ *   - **The 80-character preview is CODE POINTS**, and the ellipsis appears
+ *     only when the descriptor is strictly longer than 80.
+ *
+ * `generate_descriptor` itself returns `""` for empty content BEFORE calling
+ * the model, and `""` on any provider exception — both land on the same
+ * "skipped (empty response)" line, and the target still counts in the
+ * denominator.
+ */
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { codePointLength, sliceCodePoints } from "#util/pythonText.ts";
+
+export interface DescriptorTarget {
+  layer: string;
+  key: string;
+  content: string;
+}
+
+export interface IdentityRow {
+  key: string;
+  content: string | null;
+}
+
+/** Python `store.get_identity_by_layer(layer)` ordering. */
+export function identitiesInLayer(db: Database, layer: string): IdentityRow[] {
+  return db
+    .prepare("SELECT key, content FROM identity WHERE layer = ? ORDER BY key")
+    .all(layer) as unknown as IdentityRow[];
+}
+
+export interface ResolveTargetsInput {
+  layer?: string | null;
+  key?: string | null;
+}
+
+export type ResolveTargetsResult =
+  | { kind: "targets"; targets: DescriptorTarget[] }
+  | { kind: "missing-identity"; layer: string; key: string };
+
+/**
+ * Python's target selection: a specific pair, a whole layer, or — with no
+ * flags — every persona THEN every journey, in that order.
+ */
+export function resolveDescriptorTargets(
+  db: Database,
+  input: ResolveTargetsInput,
+): ResolveTargetsResult {
+  if (input.layer && input.key) {
+    const row = db
+      .prepare("SELECT key, content FROM identity WHERE layer = ? AND key = ?")
+      .get(input.layer, input.key) as unknown as IdentityRow | undefined;
+    if (!row) return { kind: "missing-identity", layer: input.layer, key: input.key };
+    return {
+      kind: "targets",
+      targets: [{ layer: input.layer, key: input.key, content: row.content ?? "" }],
+    };
+  }
+  if (input.layer) {
+    return {
+      kind: "targets",
+      targets: identitiesInLayer(db, input.layer).map((row) => ({
+        layer: input.layer as string,
+        key: row.key,
+        content: row.content ?? "",
+      })),
+    };
+  }
+  const targets: DescriptorTarget[] = [];
+  for (const layer of ["persona", "journey"]) {
+    for (const row of identitiesInLayer(db, layer)) {
+      targets.push({ layer, key: row.key, content: row.content ?? "" });
+    }
+  }
+  return { kind: "targets", targets };
+}
+
+/** Python `upsert_descriptor`. */
+export function upsertDescriptor(
+  db: WritableDatabase,
+  layer: string,
+  key: string,
+  descriptor: string,
+  generatedAt: string,
+): void {
+  db.prepare(
+    "INSERT INTO identity_descriptors (layer, key, descriptor, generated_at) VALUES (?, ?, ?, ?) " +
+      "ON CONFLICT(layer, key) DO UPDATE SET descriptor = excluded.descriptor, generated_at = excluded.generated_at",
+  ).run(layer, key, descriptor, generatedAt);
+}
+
+/** Python: `f"done — {descriptor[:80]}{'...' if len(descriptor) > 80 else ''}"`. */
+export function descriptorPreview(descriptor: string): string {
+  const head = sliceCodePoints(descriptor, 80);
+  return codePointLength(descriptor) > 80 ? `${head}...` : head;
+}
+
+export interface DescriptorGenerateDeps {
+  /** Returns the descriptor text, already stripped; `""` means skip. */
+  generate: (target: DescriptorTarget) => string;
+  nowIso: string;
+  print?: (line: string) => void;
+  printError?: (line: string) => void;
+}
+
+export interface DescriptorGenerateResult {
+  exitCode: number;
+  generated: number;
+  total: number;
+}
+
+export function runDescriptorGenerate(
+  db: WritableDatabase,
+  input: ResolveTargetsInput,
+  deps: DescriptorGenerateDeps,
+): DescriptorGenerateResult {
+  const print = deps.print ?? ((line: string) => process.stdout.write(line));
+  const printError = deps.printError ?? ((line: string) => process.stderr.write(line));
+
+  const resolved = resolveDescriptorTargets(db, input);
+  if (resolved.kind === "missing-identity") {
+    // Python's `!r` renders Python string repr: single quotes.
+    printError(`No identity found for layer='${resolved.layer}' key='${resolved.key}'\n`);
+    return { exitCode: 1, generated: 0, total: 0 };
+  }
+
+  const { targets } = resolved;
+  if (targets.length === 0) {
+    print("No entities found to describe.\n");
+    return { exitCode: 0, generated: 0, total: 0 };
+  }
+
+  let generated = 0;
+  for (const target of targets) {
+    // Python prints with `end=" "`, so the line stays open until the outcome.
+    print(`  generating ${target.layer}/${target.key}... `);
+    const descriptor = deps.generate(target);
+    if (descriptor) {
+      upsertDescriptor(db, target.layer, target.key, descriptor, deps.nowIso);
+      print(`done — ${descriptorPreview(descriptor)}\n`);
+      generated += 1;
+    } else {
+      print("skipped (empty response)\n");
+    }
+  }
+
+  print(`\n${generated}/${targets.length} descriptors generated.\n`);
+  return { exitCode: 0, generated, total: targets.length };
+}

package/ts/src/identity/identityEdit.ts

@@ -0,0 +1,143 @@
+// `identity edit <layer> <key>` (CV22.DS7.TS4 plateau 6, Scope F).
+//
+// Port of `cmd_edit` in `src/memory/cli/identity_cmd.py`. The command is small
+// and its risk is not: it hands a human's identity content to an arbitrary
+// program and saves whatever comes back, so the three refusals matter more than
+// the happy path.
+//
+//   * **A failed editor saves nothing.** A non-zero exit is an abort, not an
+//     empty buffer -- someone who quits `vim` with `:cq` means "discard".
+//   * **Blank content is refused, never stored.** An identity layer emptied by
+//     accident is a silent loss the next Mirror Mode load would inherit.
+//   * **An unchanged buffer writes nothing at all**, so `updated_at` does not
+//     move and the content's history stays honest.
+//
+// The temp file carries the content of a person's identity, so it is created
+// 0600 (Python gets this from `NamedTemporaryFile`) and removed on EVERY path,
+// including the ones that refuse. Both are asserted by tests rather than
+// assumed: they are the security-engineer's plan-stage requirement.
+
+import { spawnSync } from "node:child_process";
+import { closeSync, openSync, readFileSync, rmSync, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { applyIdentitySet } from "#frontDoor/identityWrite.ts";
+
+export interface IdentityEditResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface IdentityEditDeps {
+  /** The editor argv[0], resolved the way Python resolves it. */
+  editor?: string | undefined;
+  visual?: string | undefined;
+  nowIso: () => string;
+  /** Injected so a test can watch the buffer without driving a real editor. */
+  spawn?: typeof spawnSync;
+  /** Injected so a test can assert the temp file is gone afterwards. */
+  onTempFile?: (path: string) => void;
+  newId: () => string;
+}
+
+/** Python's `os.environ.get("EDITOR") or os.environ.get("VISUAL") or "nano"`. */
+export function resolveEditor(deps: IdentityEditDeps): string {
+  return deps.editor || deps.visual || "nano";
+}
+
+/**
+ * Python's `NamedTemporaryFile(prefix=..., suffix=".md", delete=False)`: a
+ * fresh name in the system temp directory, created 0600 by the open itself.
+ *
+ * `wx` is what makes it safe: creating with exclusive intent means the command
+ * can never write identity content into a path that already exists, which is
+ * the whole difference between a temp file and a target of someone else's
+ * choosing.
+ */
+function writePrivateTempFile(prefix: string, content: string): string {
+  for (let attempt = 0; attempt < 10; attempt += 1) {
+    const suffix = Math.random().toString(36).slice(2, 10);
+    const path = join(tmpdir(), `${prefix}${suffix}.md`);
+    try {
+      const handle = openSync(path, "wx", 0o600);
+      try {
+        writeSync(handle, content);
+      } finally {
+        closeSync(handle);
+      }
+      return path;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  throw new Error("could not create a private temporary file for identity edit");
+}
+
+/** Port of `cmd_edit`. */
+export function runIdentityEdit(
+  db: WritableDatabase,
+  layer: string,
+  key: string,
+  deps: IdentityEditDeps,
+): IdentityEditResult {
+  const existing = db
+    .prepare("SELECT content FROM identity WHERE layer = ? AND key = ?")
+    .get(layer, key) as { content: string } | undefined;
+  const currentContent = existing?.content ?? "";
+  const editor = resolveEditor(deps);
+
+  const tempPath = writePrivateTempFile(`mirror-identity-${layer}-${key}-`, currentContent);
+  deps.onTempFile?.(tempPath);
+
+  let newContent: string;
+  try {
+    const spawn = deps.spawn ?? spawnSync;
+    const result = spawn(editor, [tempPath], { stdio: "inherit", shell: false });
+    if (result.error) {
+      // Python raises FileNotFoundError here and the traceback escapes. Same
+      // exit code, one line, on the same stream: the recorded divergence class.
+      return {
+        stdout: "",
+        stderr: `Editor '${editor}' could not be started.\n`,
+        exitCode: 1,
+      };
+    }
+    if (result.status !== 0) {
+      return {
+        stdout: "",
+        stderr: `Editor exited with code ${result.status}. Aborted.\n`,
+        exitCode: 1,
+      };
+    }
+    newContent = readFileSync(tempPath, "utf8");
+  } finally {
+    // Every path, including the refusals above: the buffer holds identity
+    // content and must not outlive the command.
+    rmSync(tempPath, { force: true });
+  }
+
+  if (!newContent.trim()) {
+    return {
+      stdout: "",
+      stderr: "Content is empty after editing. No changes saved.\n",
+      exitCode: 1,
+    };
+  }
+  if (newContent === currentContent) {
+    return { stdout: "No changes detected.\n", stderr: "", exitCode: 0 };
+  }
+
+  // The same write `identity set` routes through, including its created/updated
+  // verb: two commands that disagree about whether a key existed would be two
+  // truths about one row.
+  const outcome = applyIdentitySet(db, {
+    layer,
+    key,
+    content: newContent,
+    id: deps.newId(),
+    nowIso: deps.nowIso(),
+  });
+  return { stdout: `✓ ${layer}/${key} ${outcome.action}\n`, stderr: "", exitCode: 0 };
+}

package/ts/src/identity/identityKey.ts

@@ -0,0 +1,77 @@
+// CR104 — the identity keys agents put into commands.
+//
+// A journey slug and a persona id are identity keys, and they do not stay in the
+// database: `--journey <slug>` goes into every Builder command, and the id that
+// `detect-persona` prints goes into `mirror load --persona <id>`. Agents write
+// those commands. A key that holds shell syntax is therefore two steps from a
+// command on the user's machine: a crafted key, then a command that carries it.
+// Persona ids can arrive from a stranger, in a persona bundle made to be shared
+// and seeded.
+//
+// So a NEW key in these layers must be a kebab-case slug (`isKebabSlug`), checked
+// where every creation passes: `upsertIdentity`'s INSERT branch. `identity set`
+// and `identity edit` ask the same question earlier, before the write seam takes
+// its snapshot and before an editor opens. A key that already exists predates
+// the rule and stays writable; `runtime diagnose` reports it instead
+// (`identityKeyBreaksGrammar`).
+//
+// Nothing here normalizes a key. A key stored differently from how it was typed
+// would miss the next command that uses the typed one, so the answer is a refusal
+// that names a key that would work.
+
+import { pyRepr } from "#util/pythonText.ts";
+import { isKebabSlug, kebabSlug } from "#util/slug.ts";
+
+/** What each guarded layer calls its key, in the refusal. */
+const KEY_NAMES: ReadonlyMap<string, string> = new Map([
+  ["journey", "journey slug"],
+  ["persona", "persona id"],
+]);
+
+/** The layers whose keys agents put into commands, and so must be kebab-case slugs. */
+export const SLUG_KEYED_LAYERS: readonly string[] = [...KEY_NAMES.keys()];
+
+/** Whether `key` breaks the grammar its layer requires. Always false for other layers. */
+export function identityKeyBreaksGrammar(layer: string, key: string): boolean {
+  return KEY_NAMES.has(layer) && !isKebabSlug(key);
+}
+
+/**
+ * Why a NEW row in `layer` cannot take `key`, or null when it can. The sentence
+ * leads with the consequence, because the reader is often an agent deciding its
+ * next move, then gives the rule and a key that would work. The key is printed
+ * escaped, so a newline or a terminal escape inside it cannot forge output.
+ */
+export function newIdentityKeyProblem(layer: string, key: string): string | null {
+  const keyName = KEY_NAMES.get(layer);
+  if (keyName === undefined || isKebabSlug(key)) return null;
+  const suggestion = kebabSlug(key);
+  const example = suggestion ? `, for example ${pyRepr(suggestion)}` : "";
+  return (
+    `no ${layer} was created: ${pyRepr(key)} is not a ${keyName}. ` +
+    `Use lowercase letters, digits, and single hyphens, up to 80 characters${example}.`
+  );
+}
+
+/**
+ * Thrown when a new identity row's key breaks its layer's grammar. Nothing was written.
+ * A route that did not ask first lets it through, and the front door answers it as
+ * one `Error:` line (`#frontDoor/namedRefusal.ts`).
+ */
+export class InvalidIdentityKeyError extends Error {
+  readonly layer: string;
+  readonly key: string;
+
+  constructor(layer: string, key: string, problem: string) {
+    super(problem);
+    this.name = "InvalidIdentityKeyError";
+    this.layer = layer;
+    this.key = key;
+  }
+}
+
+/** Throw `InvalidIdentityKeyError` when a new row in `layer` cannot take `key`. */
+export function assertNewIdentityKey(layer: string, key: string): void {
+  const problem = newIdentityKeyProblem(layer, key);
+  if (problem !== null) throw new InvalidIdentityKeyError(layer, key, problem);
+}

package/ts/src/identity/identityRead.ts

@@ -0,0 +1,69 @@
+// Identity read primitives — the port of Store.get_all_identity,
+// get_identity_by_layer, and get_identity (read side only; the write side
+// lives in identityStore.ts / setIdentity.ts).
+
+import type { Database } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+/** The projection `identity list` needs: layer, key, and content for the preview. */
+export interface IdentityListRow {
+  layer: string;
+  key: string;
+  content: string;
+}
+
+function toListRow(row: Record<string, unknown>): IdentityListRow {
+  return {
+    layer: requireString(row, "layer"),
+    key: requireString(row, "key"),
+    content: requireString(row, "content"),
+  };
+}
+
+/** Port of `get_all_identity`: every identity row, ordered by (layer, key). */
+export function listAllIdentity(db: Database): IdentityListRow[] {
+  return db
+    .prepare("SELECT layer, key, content FROM identity ORDER BY layer, key")
+    .all()
+    .map(toListRow);
+}
+
+/** Port of `get_identity_by_layer`: rows for one layer, ordered by key. */
+export function listIdentityByLayer(db: Database, layer: string): IdentityListRow[] {
+  return db
+    .prepare("SELECT layer, key, content FROM identity WHERE layer = ? ORDER BY key")
+    .all(layer)
+    .map(toListRow);
+}
+
+/** Port of `get_identity` (content only): null when the (layer, key) row is absent. */
+export function getIdentityContent(db: Database, layer: string, key: string): string | null {
+  const row = db
+    .prepare("SELECT content FROM identity WHERE layer = ? AND key = ?")
+    .get(layer, key);
+  if (row === undefined) return null;
+  return requireString(row, "content");
+}
+
+/** Raw metadata column for one (layer, key): null when the row or its metadata is absent. */
+export function getIdentityMetadata(db: Database, layer: string, key: string): string | null {
+  const row = db
+    .prepare("SELECT metadata FROM identity WHERE layer = ? AND key = ?")
+    .get(layer, key);
+  if (row === undefined) return null;
+  return optionalString(row, "metadata");
+}
+
+/**
+ * Whether an identity row exists for (layer, key) — an existence check
+ * independent of content truthiness. Needed because Python's `existing and not
+ * force` checks object truthiness (an `Identity` row is always truthy, even
+ * with empty content); reusing `getIdentityContent(...)` for this would
+ * misread an existing-but-empty-content row as absent.
+ */
+export function identityRowExists(db: Database, layer: string, key: string): boolean {
+  return (
+    db.prepare("SELECT 1 FROM identity WHERE layer = ? AND key = ? LIMIT 1").get(layer, key) !==
+    undefined
+  );
+}