mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/lifecycleRefusal.ts

@@ -0,0 +1,92 @@
+// CR067 with CR020 — refusals that say where a story's delivery cursor stands.
+//
+// The story lifecycle's guards in `plan.ts` and `closure.ts` each test the cursor's
+// last event by hand. This module states which event completes each step, so a refusal
+// can tell "not reached yet" from "already done". The order those events come in is
+// the table of positions in `cursorPosition.ts` (CR114), which also places the cursor
+// on the ribbon and names what it accepts next. The guards stay as written; a
+// table-driven test runs every step against every event, so the two expressions cannot
+// drift apart.
+//
+// Delivery Story events are outside the order: a cursor holding one gets no
+// already-complete refusal, never a guessed one.
+
+import { STORY_LIFECYCLE_EVENTS } from "./cursorPosition.ts";
+import type { BuilderDeliveryCursor } from "./deliveryCursor.ts";
+
+/** The story steps a lifecycle command can be refused at. */
+export type LifecycleStep =
+  | "prepare"
+  | "plan"
+  | "plan_approval"
+  | "validate"
+  | "debt_review"
+  | "coherence"
+  | "done";
+
+/** Why a step was refused. Only `already_complete` is decided by this module. */
+export type RefusalKind =
+  | "already_complete"
+  | "pending_confirmation"
+  | "not_reached"
+  | "missing_evidence";
+
+const COMPLETING_EVENT: Readonly<Record<LifecycleStep, string>> = {
+  // CR114 (D3): Prepare is complete once the cursor reaches Plan; Prepare at Prepare
+  // runs again, which rewrites only what Prepare wrote.
+  prepare: "plan",
+  plan: "plan",
+  plan_approval: "plan_approved",
+  validate: "validation_passed",
+  debt_review: "review_complete",
+  coherence: "coherence_complete",
+  done: "done_complete",
+};
+
+const STEP_NAME: Readonly<Record<LifecycleStep, string>> = {
+  prepare: "Prepare",
+  plan: "Plan",
+  plan_approval: "Plan approval",
+  validate: "Validation",
+  debt_review: "Debt Review",
+  coherence: "Coherence",
+  done: "Done",
+};
+
+/** True once the cursor has reached or passed the event that completes `step`. */
+export function isAlreadyComplete(step: LifecycleStep, event: string | null): boolean {
+  const order = STORY_LIFECYCLE_EVENTS;
+  const at = event === null ? -1 : order.indexOf(event);
+  return at !== -1 && at >= order.indexOf(COMPLETING_EVENT[step]);
+}
+
+/** A lifecycle step refused before any change, with its reason's identity. */
+export class LifecycleRefusal extends Error {
+  readonly step: LifecycleStep;
+  readonly kind: RefusalKind;
+
+  constructor(step: LifecycleStep, kind: RefusalKind, message: string) {
+    super(message);
+    this.name = "LifecycleRefusal";
+    this.step = step;
+    this.kind = kind;
+  }
+}
+
+/**
+ * Throw when `step` is already complete for the cursor's item. Every guard calls this
+ * first, so a finished step is never refused with a precondition that holds.
+ */
+export function refuseIfAlreadyComplete(
+  step: LifecycleStep,
+  cursor: Pick<BuilderDeliveryCursor, "activeItem" | "lastDeliveryEvent" | "pendingConfirmation">,
+): void {
+  if (!isAlreadyComplete(step, cursor.lastDeliveryEvent)) return;
+  const pending = cursor.pendingConfirmation ? `, pending ${cursor.pendingConfirmation}` : "";
+  throw new LifecycleRefusal(
+    step,
+    "already_complete",
+    `${STEP_NAME[step]} is already complete for ${cursor.activeItem}: ` +
+      `the cursor is at ${cursor.lastDeliveryEvent}${pending}.`,
+  );
+}

package/ts/src/builder/lifecycleRibbon.ts

@@ -0,0 +1,159 @@
+// CV22.DS7.US8 plateau 2 — the lifecycle progress ribbons.
+//
+// Port of `src/memory/builder/lifecycle_ribbon.py`. Every checkpoint surface
+// prints one of these under its `Delivery` header, so a wrong glyph or a wrong
+// separator is a byte divergence on most of the story's 33 surfaces.
+//
+// Three vocabularies, not one: the Delivery lifecycle, the Refinement Story flow,
+// and the Change Request cycle. Only the first is in this story's scope for
+// rendering, but all three are ported because they share `_render_progress_ribbon`
+// and porting one of three copies of a shared renderer is how the `_wrap_plain_text`
+// divergence happened in Python.
+//
+// An unknown stage RAISES rather than rendering a partial ribbon, and the message
+// names the vocabulary — `unknown Ariad lifecycle stage: x` versus `unknown Ariad
+// Refinement Story stage: x`. That is a Class B refusal with byte-exact text.
+//
+// CR113: a stage the item's level never reaches is drawn `–`, not applicable. A User
+// or Technical Story never expands, and the Delivery ribbon drew its Expand as done
+// once the cursor passed Prepare, and as still to come before. The level is a
+// required argument, so every caller decides; which levels never expand is the
+// runtime's one predicate, `isImplementableByDefault`. A Delivery Story, and a
+// ribbon drawn with no level, look as they always did.
+
+import { isImplementableByDefault } from "./cursorTransitions.ts";
+
+/** Python `DELIVERY_LIFECYCLE_STAGES`. */
+export const DELIVERY_LIFECYCLE_STAGES = [
+  "pull",
+  "prepare",
+  "expand",
+  "plan",
+  "implement",
+  "validate",
+  "debt_review",
+  "done",
+] as const;
+
+const DELIVERY_STAGE_LABELS: Record<string, string> = {
+  pull: "Pull",
+  prepare: "Prepare",
+  expand: "Expand",
+  plan: "Plan",
+  implement: "Implement",
+  validate: "Validate",
+  debt_review: "Debt Review",
+  done: "Done",
+};
+
+/** Python `REFINEMENT_STORY_STAGES`. */
+export const REFINEMENT_STORY_STAGES = [
+  "pull",
+  "select_cr",
+  "cr_cycle",
+  "review",
+  "coherence",
+  "close",
+] as const;
+
+const REFINEMENT_STORY_STAGE_LABELS: Record<string, string> = {
+  pull: "Pull",
+  select_cr: "Select CR",
+  cr_cycle: "CR Cycle",
+  review: "Review",
+  coherence: "Coherence",
+  close: "Close",
+};
+
+/** Python `CHANGE_REQUEST_STAGES`. */
+export const CHANGE_REQUEST_STAGES = [
+  "confirm",
+  "plan",
+  "implement",
+  "validate",
+  "done_note",
+] as const;
+
+const CHANGE_REQUEST_STAGE_LABELS: Record<string, string> = {
+  confirm: "Confirm",
+  plan: "Plan",
+  implement: "Implement",
+  validate: "Validate",
+  done_note: "Done Note",
+};
+
+/** The mark for a stage the item's level never reaches (CR113). */
+const NOT_APPLICABLE = "–";
+
+/** Python `_render_progress_ribbon`, with the stages an item's level never reaches. */
+function renderProgressRibbon(options: {
+  current: string;
+  stages: readonly string[];
+  labels: Record<string, string>;
+  label: string;
+  separator: string;
+  unknownKind: string;
+  notApplicable?: ReadonlySet<string>;
+}): string {
+  const { current, stages, labels, label, separator, unknownKind } = options;
+  const notApplicable = options.notApplicable ?? new Set<string>();
+  const currentIndex = stages.indexOf(current);
+  if (currentIndex === -1) {
+    throw new Error(`unknown ${unknownKind}: ${current}`);
+  }
+  const parts = stages.map((stage, index) => {
+    const marker = notApplicable.has(stage)
+      ? NOT_APPLICABLE
+      : index < currentIndex
+        ? "✓"
+        : index === currentIndex
+          ? "◉"
+          : "○";
+    return `${marker} ${labels[stage]}`;
+  });
+  return `${label}: ${parts.join(` ${separator} `)}`;
+}
+
+/** The Delivery stages an item's level never reaches: Expand, for a story. */
+const STORY_NEVER_REACHES: ReadonlySet<string> = new Set(["expand"]);
+
+/**
+ * Python `render_lifecycle_ribbon`, told the item's level (CR113). `null` is a
+ * ribbon with no item to speak of, drawn as it always was.
+ */
+export function renderLifecycleRibbon(current: string, level: string | null): string {
+  return renderProgressRibbon({
+    current,
+    stages: DELIVERY_LIFECYCLE_STAGES,
+    labels: DELIVERY_STAGE_LABELS,
+    label: "Delivery Flow",
+    separator: "→",
+    unknownKind: "Ariad lifecycle stage",
+    notApplicable:
+      level !== null && isImplementableByDefault(level) ? STORY_NEVER_REACHES : undefined,
+  });
+}
+
+/** Python `render_refinement_lifecycle_ribbon`. */
+export function renderRefinementLifecycleRibbon(current = "pull"): string {
+  return renderProgressRibbon({
+    current,
+    stages: REFINEMENT_STORY_STAGES,
+    labels: REFINEMENT_STORY_STAGE_LABELS,
+    label: "RS Flow",
+    separator: "→",
+    unknownKind: "Ariad Refinement Story stage",
+  });
+}
+
+/** Python `render_change_request_lifecycle_ribbon`. */
+export function renderChangeRequestLifecycleRibbon(current = "confirm"): string {
+  return renderProgressRibbon({
+    current,
+    stages: CHANGE_REQUEST_STAGES,
+    labels: CHANGE_REQUEST_STAGE_LABELS,
+    label: "CR Cycle",
+    separator: "→",
+    unknownKind: "Ariad Change Request stage",
+  });
+}

package/ts/src/builder/load.ts

@@ -0,0 +1,313 @@
+// CV22.DS7.US8 plateau 7 — `build load`, the last leaf.
+//
+// Port of `cmd_load` in `src/memory/cli/build.py`.
+//
+// This is the command `/mm-build <journey>` runs, in all three runtimes, and the
+// only one in the `build` family that crosses the provider seam: two embeddings
+// for its own searches, plus the previous conversation's close tail through
+// `switchConversation`.
+//
+// ## The ORDER of effects is behavior
+//
+// identity read → clone-role guard → banner (stderr) → transition card → entry
+// surface → identity context → two searches → memories block → sticky defaults →
+// operating-mode row → conversation switch → trailer.
+//
+// A port that writes the mode row before the searches passes every surface golden
+// and changes what a CRASHED `load` leaves behind — which is the state a Navigator
+// meets when a provider is down. Four surfaces print before the first provider
+// call, so the transport decision has to be taken before any of them (the route
+// does that; see `frontDoor/buildRoute.ts` at plateau 8).
+//
+// ## What it does NOT do
+//
+// It never falls back mid-command. If the embedding provider fails, the search
+// degrades to FTS-only and the lifecycle continues: the mode row is still written
+// and the conversation still switches, because in Python those statements simply
+// follow the searches. The degraded card is indistinguishable from a healthy one —
+// reproduced, and carried to Debt Review as a CR rather than marked here.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { memoriesById } from "#frontDoor/searchRoute.ts";
+import { getIdentityContent } from "#identity/identityRead.ts";
+import { getProjectPath } from "#journey/journeyStatus.ts";
+import { loadMirrorContext } from "#mirror/context.ts";
+import { persistStickyDefaults } from "#mirror/orchestration.ts";
+import { resolveRuntimeSessionId } from "#mirror/runtimeSession.ts";
+import { activateOperatingMode } from "#mode/operatingMode.ts";
+import { ProviderConfigError } from "#providers/config.ts";
+import type { EmbeddingProvider } from "#providers/embedding.ts";
+import { searchMemoriesWithStatus } from "#search/memorySearch.ts";
+import { PROGRAM } from "#util/program.ts";
+import { shellWord } from "#util/shellWord.ts";
+import { renderBuilderOrientationSurface } from "./homeSurface.ts";
+import { getAdoptedMethod } from "./methodAdoption.ts";
+import { inspectPullCandidates, inspectRoadmapSnapshot } from "./pullCandidates.ts";
+import { renderProjectPositionReport } from "./pullCandidatesRender.ts";
+import { findCanonicalRefinementIndex, inspectRefinementField } from "./refinementField.ts";
+import { readBuilderResumeState } from "./resumeState.ts";
+import { renderBuilderResumeSurface } from "./resumeSurface.ts";
+import { resolveRoadmapScope, scopePullCandidates } from "./roadmapScope.ts";
+import { extractQuery, renderBuilderModeTransition } from "./transition.ts";
+
+export interface BuildLoadResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+  /** Metadata only, for the front-door log: never the query, never a message. */
+  readonly degradedKind?: string;
+  /** How many provider calls the command made, for the log's `calls=` field. */
+  readonly providerCalls: number;
+}
+
+/**
+ * What an unconfigured install has instead of a provider.
+ *
+ * Python has no "absent provider" state: `generate_embedding` raises
+ * `RuntimeError` when the key is missing, the search catches it, and the block
+ * still renders FTS-only. Returning no results here instead -- which this did
+ * until the degraded scenario measured it -- renders an EMPTY memories block on
+ * a machine with a working corpus and no key, and does it silently, in the
+ * surface a Navigator reads to choose the day's work.
+ *
+ * `ProviderConfigError` is the right class, not a convenience: it is the one
+ * failure that fires no ledger hook, which is how Python prices a missing key
+ * too (no call was made, so no row).
+ */
+const MISSING_EMBEDDING_PROVIDER: EmbeddingProvider = {
+  embed: async () => {
+    throw new ProviderConfigError(
+      "No embedding provider was supplied to `build load`; the memories block " +
+        "degrades to the local FTS index.",
+    );
+  },
+};
+
+export interface BuildLoadDeps {
+  readonly nowIso: () => string;
+  readonly newId: () => string;
+  /** Absent means no provider: the searches degrade to FTS-only, as Python's do. */
+  readonly embeddingProvider?: EmbeddingProvider;
+  /** Python's `switch_conversation`, injected because it carries the close tail. */
+  readonly switchConversation?: (journey: string, sessionId: string | null) => Promise<void>;
+  /**
+   * `_check_clone_role_guard`'s outcome, injected because its inputs are the
+   * MACHINE's -- a git root and a marker file -- and this module is graded as a
+   * pure port over a database. `frontDoor/cloneRoleGuard.ts` supplies the real
+   * one; the corpus stages a neutral checkout so the guard stays silent.
+   *
+   * `exitCode: null` is the `--ignore-production-role` case: the warning prints
+   * and the session start CONTINUES.
+   */
+  readonly cloneRoleGuard?: (
+    projectPath: string | null,
+  ) => { readonly stderr: string; readonly exitCode: number | null } | null;
+}
+
+/**
+ * Python `_print_builder_entry_surface`.
+ *
+ * Which surface appears is decided by the CURSOR, not by adoption: an adopted
+ * journey whose cursor has neither an active item nor a pending confirmation gets
+ * the position report plus `■ BUILDER ORIENTATION`; anything else gets
+ * `■ BUILDER RESUME`. Both read the Refinement field from project files only,
+ * since CV22.DS10.TS4 retired the Workbench.
+ *
+ * Exported for the CR114 walk, which compares the list this prints with `build show`'s
+ * at every position of a lifecycle.
+ */
+export function renderBuilderEntrySurface(
+  db: Database,
+  slug: string,
+  projectPath: string | null,
+): string {
+  const canonicalRefinementIndex = findCanonicalRefinementIndex(projectPath);
+  const resumeState = readBuilderResumeState(db, slug);
+  const cursor = resumeState.cursor;
+  // Every "where are we" and "what next" below is the journey's own (CR002):
+  // derived from the cursor these surfaces already render, never from a scan of
+  // the whole roadmap.
+  const scope = resolveRoadmapScope(projectPath || null, cursor);
+  if (cursor && !cursor.activeItem && !cursor.pendingConfirmation) {
+    const candidates = inspectPullCandidates(projectPath, { journey: slug, method: "ariad" });
+    const view = scopePullCandidates(candidates, scope);
+    const roadmap = inspectRoadmapSnapshot(projectPath, { journey: slug, method: "ariad" });
+    return `${printed(renderProjectPositionReport(roadmap, { view }))}${renderBuilderOrientationSurface(
+      {
+        candidates,
+        refinement: inspectRefinementField(projectPath),
+        cadence: cursor,
+      },
+    )}`;
+  }
+  return renderBuilderResumeSurface(resumeState, { scope, canonicalRefinementIndex });
+}
+
+/**
+ * Python's merge of the two searches: dedupe by id, sort by score, take six.
+ *
+ * Exported and pure because the FIRST-occurrence rule is not observable through
+ * the command in any case the corpus could hold. The same memory is ranked in both
+ * searches, but its two scores differ only when MMR's diversity penalty differs
+ * between the candidate sets, AND the difference has to invert the relative order
+ * of two duplicated ids before the rendered block changes. Mutation testing
+ * reported the rule ungraded, two corpus shapes failed to expose it, and inventing
+ * a third would have been engineering a case to satisfy a mutant rather than to
+ * describe behavior.
+ *
+ * So it is graded here instead, with hand-built inputs, and the limitation is
+ * declared rather than implied — the same treatment plateau 5 gave the CAS
+ * conflict branch.
+ *
+ * Keeping the FIRST occurrence means a duplicated memory carries its SCOPED score,
+ * which is the one computed among the journey's own memories.
+ */
+export function mergeRankedResults(
+  scoped: readonly { id: string; score: number }[],
+  global: readonly { id: string; score: number }[],
+  limit = 6,
+): { id: string; score: number }[] {
+  const seen = new Set<string>();
+  const merged: { id: string; score: number }[] = [];
+  for (const result of [...scoped, ...global]) {
+    if (seen.has(result.id)) continue;
+    seen.add(result.id);
+    merged.push({ id: result.id, score: result.score });
+  }
+  // Python sorts by score DESCENDING with a stable sort, so equal scores keep the
+  // scoped-before-global order the merge produced. JavaScript's sort is stable by
+  // specification since ES2019, so the comparator alone reproduces it.
+  merged.sort((left, right) => right.score - left.score);
+  return merged.slice(0, limit);
+}
+
+/** Python's `print(...)`: the value plus the newline `print` adds. */
+function printed(text: string): string {
+  return `${text}\n`;
+}
+
+const BANNER_COLOR = "\u001b[38;5;117m";
+const BANNER_RESET = "\u001b[0m";
+
+/** Python `_print_builder_banner`: stderr, ANSI bytes included. */
+function banner(slug: string, projectPath: string | null): string {
+  const lines = [`${BANNER_COLOR}⚙ Builder Mode active — journey: ${slug}${BANNER_RESET}`];
+  if (projectPath) lines.push(`${BANNER_COLOR}  📁 ${projectPath}${BANNER_RESET}`);
+  return lines.map(printed).join("");
+}
+
+export interface BuildLoadOptions {
+  readonly slug: string;
+  readonly sessionId?: string | null;
+  readonly environmentSessionId?: string | null;
+}
+
+/** Python `cmd_load`. */
+export async function runBuildLoad(
+  db: WritableDatabase,
+  options: BuildLoadOptions,
+  deps: BuildLoadDeps,
+): Promise<BuildLoadResult> {
+  const slug = options.slug;
+  const journeyContent = getIdentityContent(db, "journey", slug);
+  if (!journeyContent) {
+    return {
+      stdout: "",
+      stderr: printed(`Error: journey '${slug}' not found.`),
+      exitCode: 1,
+      providerCalls: 0,
+    };
+  }
+  const projectPath = getProjectPath(db, slug);
+
+  // The clone-role guard runs BEFORE the banner: refusing after it would print a
+  // session start the command then abandons.
+  //
+  // It exits **2**, not 1 -- a usage-level refusal, the class argparse uses --
+  // while the unknown-journey refusal above exits 1. The two are one `if` apart
+  // and were the same code until the guard was ported and graded.
+  const guard = deps.cloneRoleGuard?.(projectPath) ?? null;
+  if (guard !== null && guard.exitCode !== null) {
+    return { stdout: "", stderr: guard.stderr, exitCode: guard.exitCode, providerCalls: 0 };
+  }
+
+  let stdout = printed(renderBuilderModeTransition({ journey: slug, journeyContent, projectPath }));
+  // The override warning precedes the banner, as Python's two `print`s do.
+  const stderr = `${guard?.stderr ?? ""}${banner(slug, projectPath)}`;
+
+  if (getAdoptedMethod(db, slug) === "ariad") {
+    stdout += printed(renderBuilderEntrySurface(db, slug, projectPath));
+  }
+
+  stdout += printed(await loadMirrorContext(db, { persona: "engineer", journey: slug }));
+
+  // The two searches. Python runs them unconditionally and passes `log_access`
+  // by default, so this read MUTATES `access_count` on what it returns — which is
+  // why a second `load` against the same database legitimately reorders the block.
+  const query = extractQuery(journeyContent, slug);
+  let providerCalls = 0;
+  // `calls=` counts round-trips that REACHED a provider. A missing provider is a
+  // configuration failure rather than a call -- Python raises before its attempt
+  // loop and writes no ledger row -- so counting it would put a call in the
+  // front-door log that no ledger row backs.
+  const configured = deps.embeddingProvider !== undefined;
+  const provider = deps.embeddingProvider ?? MISSING_EMBEDDING_PROVIDER;
+  const runSearch = async (journey?: string) => {
+    if (configured) providerCalls += 1;
+    return searchMemoriesWithStatus(db, {
+      query,
+      limit: 5,
+      provider,
+      ...(journey === undefined ? {} : { journey }),
+    });
+  };
+  const scoped = await runSearch(slug);
+  const global = await runSearch();
+  const degradedKind = scoped.degradedKind ?? global.degradedKind;
+
+  // Merge, dedupe by id keeping the FIRST occurrence, then sort by score
+  // descending and take six. Python's `sort` is STABLE, so equal scores keep the
+  // scoped-before-global order the merge produced.
+  const relevant = mergeRankedResults(scoped.results, global.results);
+  if (relevant.length > 0) {
+    // The ranker returns ids and scores; the rendered block needs the rows, read
+    // through the same helper `memories --search` uses.
+    const rows = memoriesById(
+      db,
+      relevant.map((entry) => entry.id),
+    );
+    stdout += "\n=== recent memories ===\n";
+    for (const entry of relevant) {
+      const memory = rows.get(entry.id);
+      if (memory === undefined) continue;
+      stdout += `\n[${memory.layer}] ${memory.title}\n`;
+      stdout += printed(memory.content);
+    }
+  }
+
+  persistStickyDefaults(db, "engineer", slug, deps.nowIso());
+  const resolvedSessionId = resolveRuntimeSessionId(
+    db,
+    options.sessionId ?? null,
+    options.environmentSessionId ?? null,
+  );
+  activateOperatingMode(
+    db,
+    { mode: "Builder Mode", journey: slug, sessionId: resolvedSessionId },
+    deps.nowIso(),
+  );
+  await deps.switchConversation?.(slug, resolvedSessionId);
+
+  stdout += projectPath
+    ? `\nproject_path=${projectPath}\n`
+    : `\n[Journey '${slug}' has no project_path configured. ` +
+      `Run: ${PROGRAM} journey set-path ${shellWord(slug)} /path/to/project]\n`;
+
+  return {
+    stdout,
+    stderr,
+    exitCode: 0,
+    ...(degradedKind === undefined ? {} : { degradedKind }),
+    providerCalls,
+  };
+}

package/ts/src/builder/methodAdoption.ts

@@ -0,0 +1,113 @@
+// CV22.DS7.US8 plateau 1 — which Builder method a journey has adopted.
+//
+// Port of `src/memory/builder/method_adoption.py`. All of Builder's state lives
+// in `runtime_sessions` rows keyed by a prefix, and this is the simplest one: a
+// single-field JSON payload under `__builder_method_adoption__:<journey>`.
+//
+// Reader, writer, and clear land TOGETHER even though plateau 1 only needs the
+// read. The rule that keeps D2's revert honest is that a TS write must produce
+// the bytes Python would write for the same state, and splitting a serializer
+// from its parser across plateaus is how that stops being checkable. The
+// delivery cursor stays in plateau 2 because it carries compare-and-swap,
+// generations, and the preauthorization receipt; this row carries one key.
+//
+// Python writes `json.dumps({"method": ...}, ensure_ascii=False)`, which for a
+// single ASCII key is `{"method": "ariad"}` — note the space after the colon,
+// Python's default separator and NOT `JSON.stringify`'s output.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { getRuntimeSession, upsertRuntimeSession } from "#mirror/runtimeSession.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+
+const ADOPTION_SESSION_PREFIX = "__builder_method_adoption__:";
+
+/** Python `_session_id`. */
+export function adoptionSessionId(journey: string): string {
+  return `${ADOPTION_SESSION_PREFIX}${journey}`;
+}
+
+/** Python `_normalize_journey`: strip, and refuse empty. */
+function normalizeJourney(journey: string): string {
+  const normalized = typeof journey === "string" ? journey.trim() : "";
+  if (!normalized) throw new Error("journey must not be empty");
+  return normalized;
+}
+
+/** Python `_normalize_method`: strip, and refuse empty. */
+function normalizeMethod(method: string): string {
+  const normalized = typeof method === "string" ? method.trim() : "";
+  if (!normalized) throw new Error("method must not be empty");
+  return normalized;
+}
+
+export interface BuilderMethodAdoption {
+  readonly journey: string;
+  readonly method: string;
+}
+
+/**
+ * Python `get_adopted_method`: `None` unless the row exists, is active, has
+ * metadata, parses as a JSON object, and carries a non-empty string `method`.
+ *
+ * Every one of those is a silent `None` rather than an error, so a corrupted row
+ * reads as "not adopted" instead of failing Builder activation.
+ */
+export function getAdoptedMethod(db: Database, journey: string): string | null {
+  const normalizedJourney = normalizeJourney(journey);
+  const session = getRuntimeSession(db, adoptionSessionId(normalizedJourney));
+  if (!session?.active || !session.metadata) return null;
+  let data: unknown;
+  try {
+    data = JSON.parse(session.metadata);
+  } catch {
+    return null;
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
+  const method = (data as Record<string, unknown>).method;
+  if (typeof method !== "string") return null;
+  const normalized = method.trim();
+  return normalized || null;
+}
+
+/** Python `set_adopted_method`. */
+export function setAdoptedMethod(
+  db: WritableDatabase,
+  journey: string,
+  method: string,
+  nowIso: () => string,
+): BuilderMethodAdoption {
+  const normalizedJourney = normalizeJourney(journey);
+  const normalizedMethod = normalizeMethod(method);
+  upsertRuntimeSession(
+    db,
+    adoptionSessionId(normalizedJourney),
+    {
+      interface: "builder_method_adoption",
+      journey: normalizedJourney,
+      active: true,
+      metadata: pythonJsonDumps({ method: normalizedMethod }),
+    },
+    nowIso(),
+  );
+  return { journey: normalizedJourney, method: normalizedMethod };
+}
+
+/** Python `clear_adopted_method`: deactivate the row and null its metadata. */
+export function clearAdoptedMethod(
+  db: WritableDatabase,
+  journey: string,
+  nowIso: () => string,
+): void {
+  const normalizedJourney = normalizeJourney(journey);
+  upsertRuntimeSession(
+    db,
+    adoptionSessionId(normalizedJourney),
+    {
+      interface: "builder_method_adoption",
+      journey: normalizedJourney,
+      active: false,
+      metadata: null,
+    },
+    nowIso(),
+  );
+}