mirror-mind 0.0.1 → 0.33.0

package/ts/src/tasks/taskStore.ts

@@ -0,0 +1,312 @@
+// Task read/write model parity port (CV22.DS7.US2).
+//
+// A faithful TypeScript port of `TaskStore` (`src/memory/storage/tasks.py`) and
+// `TaskService.list_tasks` (`src/memory/services/tasks.py`). Following the
+// database-seam philosophy established in DS2/DS4, ordering and filtering are
+// pushed down to SQLite exactly as Python's SQL does (including `NULLS LAST`,
+// supported by the bundled `node:sqlite` engine) — these functions are query
+// builders + row mappers, not a re-implementation of SQLite's sort.
+//
+// `resolveTaskByIdOrPrefix` is the ONE shared prefix resolver behind
+// `done`/`doing`/`block`/`delete` (the `kebab_slug` writer/locator lesson: two
+// commands must not grow two copies of the same scan). Python itself has no
+// such shared function — each CLI command inlines its own scan and prints its
+// own message, and the two commands disagree on the ambiguous case
+// (`status_change` reports "Ambiguous ID"; `delete` folds it into "not found").
+// This resolver reproduces that fact honestly: it returns what happened
+// (found/ambiguous/not_found), and each front-door command decides how to
+// render the ambiguous case — so the asymmetry lives in presentation, where
+// Python's own asymmetry actually lives, not baked into the resolver's logic.
+
+import type { Database, SqlValue, WritableDatabase } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+/** A task row, mirroring the Python `Task` model exactly. */
+export interface Task {
+  id: string;
+  journey: string | null;
+  title: string;
+  status: string; // 'todo' | 'doing' | 'done' | 'blocked'
+  due_date: string | null;
+  scheduled_at: string | null;
+  time_hint: string | null;
+  stage: string | null;
+  context: string | null;
+  source: string; // 'manual' | 'journey_path' | 'conversation' | 'week_plan' | 'sync'
+  created_at: string;
+  updated_at: string;
+  completed_at: string | null;
+  metadata: string | null;
+}
+
+const TASK_COLUMNS =
+  "id, journey, title, status, due_date, scheduled_at, time_hint, stage, context, " +
+  "source, created_at, updated_at, completed_at, metadata";
+
+function toTask(row: Record<string, unknown>): Task {
+  return {
+    id: requireString(row, "id"),
+    journey: optionalString(row, "journey"),
+    title: requireString(row, "title"),
+    status: requireString(row, "status"),
+    due_date: optionalString(row, "due_date"),
+    scheduled_at: optionalString(row, "scheduled_at"),
+    time_hint: optionalString(row, "time_hint"),
+    stage: optionalString(row, "stage"),
+    context: optionalString(row, "context"),
+    source: requireString(row, "source"),
+    created_at: requireString(row, "created_at"),
+    updated_at: requireString(row, "updated_at"),
+    completed_at: optionalString(row, "completed_at"),
+    metadata: optionalString(row, "metadata"),
+  };
+}
+
+// --- Reads -----------------------------------------------------------------
+
+/** Port of `Store.get_task`. */
+export function getTaskById(db: Database, id: string): Task | null {
+  const row = db.prepare(`SELECT ${TASK_COLUMNS} FROM tasks WHERE id = ?`).get(id);
+  return row === undefined ? null : toTask(row);
+}
+
+/** Port of `Store.get_all_tasks`: `ORDER BY status, due_date ASC NULLS LAST, created_at ASC`. */
+export function getAllTasks(db: Database): Task[] {
+  return db
+    .prepare(
+      `SELECT ${TASK_COLUMNS} FROM tasks ORDER BY status, due_date ASC NULLS LAST, created_at ASC`,
+    )
+    .all()
+    .map(toTask);
+}
+
+/** Port of `Store.get_open_tasks`: status IN ('todo','doing','blocked'), optional journey filter. */
+export function getOpenTasks(db: Database, journey: string | null = null): Task[] {
+  const base = `SELECT ${TASK_COLUMNS} FROM tasks WHERE status IN ('todo', 'doing', 'blocked')`;
+  const order = "ORDER BY due_date ASC NULLS LAST, created_at ASC";
+  if (journey) {
+    return db.prepare(`${base} AND journey = ? ${order}`).all(journey).map(toTask);
+  }
+  return db.prepare(`${base} ${order}`).all().map(toTask);
+}
+
+/** Port of `Store.get_tasks_by_status`. */
+export function getTasksByStatus(db: Database, status: string): Task[] {
+  return db
+    .prepare(
+      `SELECT ${TASK_COLUMNS} FROM tasks WHERE status = ? ORDER BY due_date ASC NULLS LAST, created_at ASC`,
+    )
+    .all(status)
+    .map(toTask);
+}
+
+/** Port of `Store.get_tasks_by_journey`. */
+export function getTasksByJourney(db: Database, journey: string): Task[] {
+  return db
+    .prepare(
+      `SELECT ${TASK_COLUMNS} FROM tasks WHERE journey = ? ORDER BY due_date ASC NULLS LAST, created_at ASC`,
+    )
+    .all(journey)
+    .map(toTask);
+}
+
+/** Port of `Store.find_tasks_by_title`: `LIKE %fragment%`, optional journey filter. */
+export function findTasksByTitle(
+  db: Database,
+  titleFragment: string,
+  journey: string | null = null,
+): Task[] {
+  const pattern = `%${titleFragment}%`;
+  if (journey) {
+    return db
+      .prepare(
+        `SELECT ${TASK_COLUMNS} FROM tasks WHERE title LIKE ? AND journey = ? ORDER BY created_at DESC`,
+      )
+      .all(pattern, journey)
+      .map(toTask);
+  }
+  return db
+    .prepare(`SELECT ${TASK_COLUMNS} FROM tasks WHERE title LIKE ? ORDER BY created_at DESC`)
+    .all(pattern)
+    .map(toTask);
+}
+
+/**
+ * Build the parameterized week-range query, mirroring Python's builder exactly:
+ * `due_date` in range OR `scheduled_at` in range (both bounds inclusive), the
+ * `scheduled_at` upper bound extended to `T23:59` so a same-day scheduled item
+ * is not excluded by a bare date string, ordered `due_date ASC NULLS LAST,
+ * scheduled_at ASC NULLS LAST`. `NULLS LAST` is honored by the bundled SQLite
+ * engine (>= 3.30), same as Python's.
+ */
+export function buildTasksForWeekQuery(
+  startDate: string,
+  endDate: string,
+): { sql: string; params: SqlValue[] } {
+  return {
+    sql:
+      `SELECT ${TASK_COLUMNS} FROM tasks ` +
+      "WHERE (due_date >= ? AND due_date <= ?) OR (scheduled_at >= ? AND scheduled_at <= ?) " +
+      "ORDER BY due_date ASC NULLS LAST, scheduled_at ASC NULLS LAST",
+    params: [startDate, endDate, startDate, `${endDate}T23:59`],
+  };
+}
+
+/** Port of `Store.get_tasks_for_week`. */
+export function getTasksForWeek(db: Database, startDate: string, endDate: string): Task[] {
+  const { sql, params } = buildTasksForWeekQuery(startDate, endDate);
+  return db
+    .prepare(sql)
+    .all(...params)
+    .map(toTask);
+}
+
+/** Filters for `listTasks`, mirroring `TaskService.list_tasks`'s parameters. */
+export interface ListTasksFilters {
+  journey?: string | null;
+  status?: string | null;
+  openOnly?: boolean;
+}
+
+/**
+ * Port of `TaskService.list_tasks`: branch order is open_only -> status ->
+ * journey -> all, matching Python exactly (an `openOnly` request ignores
+ * `status`, and a `status` request applies `journey` as a post-filter over the
+ * status read rather than its own query, exactly as Python does).
+ */
+export function listTasks(db: Database, filters: ListTasksFilters = {}): Task[] {
+  const { journey = null, status = null, openOnly = false } = filters;
+  if (openOnly) return getOpenTasks(db, journey);
+  if (status) {
+    const tasks = getTasksByStatus(db, status);
+    return journey ? tasks.filter((t) => t.journey === journey) : tasks;
+  }
+  if (journey) return getTasksByJourney(db, journey);
+  return getAllTasks(db);
+}
+
+// --- Prefix resolution -------------------------------------------------------
+
+/** The outcome of resolving a task id or id-prefix, naming every real branch. */
+export type ResolveTaskResult =
+  | { kind: "found"; task: Task }
+  | { kind: "ambiguous"; matches: Task[] }
+  | { kind: "not_found" };
+
+/**
+ * Resolve a task by exact id, falling back to a unique-prefix scan over ALL
+ * tasks (`Task.id.startswith(idOrPrefix)`), matching the inline logic
+ * duplicated in Python's `cmd_status_change`/`cmd_delete`. Callers render the
+ * `ambiguous` case differently on purpose (see module doc); this function only
+ * reports the fact.
+ */
+export function resolveTaskByIdOrPrefix(db: Database, idOrPrefix: string): ResolveTaskResult {
+  const exact = getTaskById(db, idOrPrefix);
+  if (exact) return { kind: "found", task: exact };
+
+  const matches = getAllTasks(db).filter((t) => t.id.startsWith(idOrPrefix));
+  if (matches.length === 1) return { kind: "found", task: matches[0] };
+  if (matches.length > 1) return { kind: "ambiguous", matches };
+  return { kind: "not_found" };
+}
+
+// --- Writes ------------------------------------------------------------------
+
+/** Fields accepted when creating a task, mirroring `TaskService.add_task`'s parameters. */
+export interface CreateTaskInput {
+  title: string;
+  journey?: string | null;
+  dueDate?: string | null;
+  scheduledAt?: string | null;
+  timeHint?: string | null;
+  stage?: string | null;
+  context?: string | null;
+  source?: string;
+}
+
+/**
+ * Port of `TaskService.add_task` + `Store.create_task`. `id` and `nowIso` are
+ * injected by the caller (front door), the same determinism-injection idiom
+ * DS4 established: `created_at`/`updated_at` both take the single injected
+ * `nowIso`, matching a frozen-clock Python run where every `_now()` call
+ * returns the same value. New tasks always start `status: "todo"`,
+ * `completed_at: null` — Python's `Task` defaults, never overridden here.
+ */
+export function createTask(
+  db: WritableDatabase,
+  input: CreateTaskInput,
+  id: string,
+  nowIso: string,
+): Task {
+  const task: Task = {
+    id,
+    journey: input.journey ?? null,
+    title: input.title,
+    status: "todo",
+    due_date: input.dueDate ?? null,
+    scheduled_at: input.scheduledAt ?? null,
+    time_hint: input.timeHint ?? null,
+    stage: input.stage ?? null,
+    context: input.context ?? null,
+    source: input.source ?? "manual",
+    created_at: nowIso,
+    updated_at: nowIso,
+    completed_at: null,
+    metadata: null,
+  };
+  db.prepare(
+    `INSERT INTO tasks (${TASK_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    task.id,
+    task.journey,
+    task.title,
+    task.status,
+    task.due_date,
+    task.scheduled_at,
+    task.time_hint,
+    task.stage,
+    task.context,
+    task.source,
+    task.created_at,
+    task.updated_at,
+    task.completed_at,
+    task.metadata,
+  );
+  return task;
+}
+
+/**
+ * Port of `Store.update_task(task_id, status=...)`, the primitive behind
+ * `doing`/`block`. Always bumps `updated_at` to the injected `nowIso`,
+ * matching Python's `Store.update_task`, which sets `updated_at = _now()` on
+ * every call regardless of which other fields are passed.
+ */
+export function updateTaskStatus(
+  db: WritableDatabase,
+  id: string,
+  status: string,
+  nowIso: string,
+): void {
+  db.prepare("UPDATE tasks SET status = ?, updated_at = ? WHERE id = ?").run(status, nowIso, id);
+}
+
+/**
+ * Port of `TaskService.complete_task` + the `Store.update_task` it calls:
+ * sets `status = 'done'`, `completed_at`, and `updated_at` to the single
+ * injected `nowIso` (a frozen-clock run returns the same value for both of
+ * Python's two independent `_now()` calls here).
+ */
+export function completeTask(db: WritableDatabase, id: string, nowIso: string): void {
+  db.prepare("UPDATE tasks SET status = 'done', completed_at = ?, updated_at = ? WHERE id = ?").run(
+    nowIso,
+    nowIso,
+    id,
+  );
+}
+
+/** Port of `Store.delete_task`: returns whether a row was actually removed. */
+export function deleteTaskById(db: WritableDatabase, id: string): boolean {
+  const before = getTaskById(db, id);
+  db.prepare("DELETE FROM tasks WHERE id = ?").run(id);
+  return before !== null;
+}

package/ts/src/tasks/weekView.ts

@@ -0,0 +1,120 @@
+// `week view` business logic parity port (CV22.DS7.US2 slice 3b).
+//
+// A faithful port of the non-printing logic inside `cmd_view`
+// (`src/memory/cli/week.py`): computing the Monday-Sunday week window around
+// "now", filtering out tasks scheduled in the past that aren't done, and
+// grouping/sorting the rest by calendar day. Rendering (icons, columns,
+// headers) is a separate concern in `frontDoor/render/week.ts`.
+//
+// `now` is always injected as a `Date` constructed via the LOCAL constructor
+// form (`new Date(y, m, d, h, mi)`), never `Date.UTC`/an ISO `Z` string --
+// Python's `datetime.now()` is naive local time, and JS's local constructor
+// stores the same literal calendar/clock fields with no timezone conversion,
+// so the two agree on any machine regardless of its system timezone. The same
+// applies to parsing `scheduled_at` ("YYYY-MM-DDTHH:MM", no offset): per the
+// JS Date spec, a date-TIME string without a designator parses as local time
+// (unlike a bare date string, which parses as UTC midnight -- a real
+// asymmetry, avoided here because `scheduled_at` always carries the `T`).
+
+import type { Task } from "./taskStore.ts";
+
+export interface WeekRange {
+  /** ISO date (YYYY-MM-DD), Monday of the week containing `now`. */
+  start: string;
+  /** ISO date (YYYY-MM-DD), the Sunday six days after `start`. */
+  end: string;
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** Format y/m(1-based)/d as an ISO date string. */
+export function formatIsoDate(year: number, month: number, day: number): string {
+  return `${String(year).padStart(4, "0")}-${pad2(month)}-${pad2(day)}`;
+}
+
+/** Add `days` (may be negative) to an ISO date string, DST-safe (calendar-only, no time component). */
+export function addIsoDays(isoDate: string, days: number): string {
+  const [y, m, d] = isoDate.split("-").map(Number);
+  const shifted = new Date(y, m - 1, d + days);
+  return formatIsoDate(shifted.getFullYear(), shifted.getMonth() + 1, shifted.getDate());
+}
+
+/** The local calendar date (YYYY-MM-DD) of a `Date`, ignoring its time-of-day. */
+export function toIsoDate(date: Date): string {
+  return formatIsoDate(date.getFullYear(), date.getMonth() + 1, date.getDate());
+}
+
+/**
+ * The Monday-Sunday week containing `now`, mirroring Python's
+ * `start = today - timedelta(days=today.weekday())`. JS `getDay()` is
+ * Sunday=0..Saturday=6; Python's `weekday()` is Monday=0..Sunday=6, so the
+ * conversion is `(getDay() + 6) % 7`.
+ */
+export function computeWeekRange(now: Date): WeekRange {
+  const pythonWeekday = (now.getDay() + 6) % 7;
+  const todayIso = toIsoDate(now);
+  const start = addIsoDays(todayIso, -pythonWeekday);
+  const end = addIsoDays(start, 6);
+  return { start, end };
+}
+
+/**
+ * Drop tasks that are scheduled in the past and not done, matching Python's
+ * `if t.scheduled_at and t.status != "done": ... if sched < now: continue`.
+ * An unparseable `scheduled_at` is NOT excluded (Python's `except ValueError:
+ * pass` falls through to keep the task) -- reproduced here by only excluding
+ * on a successfully-parsed, strictly-earlier instant.
+ */
+export function filterVisibleTasks(tasks: readonly Task[], now: Date): Task[] {
+  const visible: Task[] = [];
+  for (const t of tasks) {
+    if (t.scheduled_at && t.status !== "done") {
+      const schedMs = new Date(t.scheduled_at).getTime();
+      if (!Number.isNaN(schedMs) && schedMs < now.getTime()) {
+        continue;
+      }
+    }
+    visible.push(t);
+  }
+  return visible;
+}
+
+/**
+ * Sort key mirroring Python's `(scheduled_at or "99", time_hint or "zz",
+ * title)` tuple: a scheduled task sorts before any unscheduled one (any real
+ * ISO datetime string is lexically less than the "99" sentinel), then by
+ * time-hint, then alphabetically by title.
+ */
+function compareByDaySortKey(a: Task, b: Task): number {
+  const aKey = [a.scheduled_at ?? "99", a.time_hint ?? "zz", a.title];
+  const bKey = [b.scheduled_at ?? "99", b.time_hint ?? "zz", b.title];
+  for (let i = 0; i < aKey.length; i += 1) {
+    if (aKey[i] !== bKey[i]) return aKey[i] < bKey[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Group tasks by calendar day (`due_date`, falling back to `scheduled_at`'s
+ * date portion), sorting each day's bucket by the (scheduled_at, time_hint,
+ * title) key. A task with neither `due_date` nor `scheduled_at` has no day
+ * and is dropped -- matching Python's `if day:` guard (in practice this never
+ * happens for a task `getTasksForWeek` actually returned, since its WHERE
+ * clause already requires one of the two to be in range).
+ */
+export function groupTasksByDay(tasks: readonly Task[]): Map<string, Task[]> {
+  const byDay = new Map<string, Task[]>();
+  for (const t of tasks) {
+    const day = t.due_date || (t.scheduled_at ? t.scheduled_at.slice(0, 10) : null);
+    if (!day) continue;
+    const bucket = byDay.get(day);
+    if (bucket) bucket.push(t);
+    else byDay.set(day, [t]);
+  }
+  for (const bucket of byDay.values()) {
+    bucket.sort(compareByDaySortKey);
+  }
+  return byDay;
+}

package/ts/src/util/clipCodePoints.ts

@@ -0,0 +1,26 @@
+// CR018 — a cut that says so.
+//
+// The card primitives cut silently, as Python's did, and a Navigator reading a title
+// cut mid-word had no way to know it went on. This rule marks the cut with `…`, and
+// backs a cut that would split a word up to the word's start, because a code cut short
+// reads as another code: `(per D12)` must not become `(per D1…`. It began as `card.ts`'s
+// own; CR103 moved it here so a status clause can be bounded by the same rule before it
+// reaches any card.
+
+/**
+ * `text` cut to fit `width` code points, with `…` in the last place when anything was
+ * cut. A cut that would split a word backs up to the word's start, but only while at
+ * least half the width stays; past that, the word is cut. A space the cut leaves at the
+ * end goes, so the mark sits on the word.
+ */
+export function clipCodePoints(text: string, width: number): string {
+  const points = Array.from(text);
+  if (points.length <= width) return text;
+  let kept = points.slice(0, width - 1);
+  const next = points[width - 1] ?? "";
+  if (!/\s/u.test(next)) {
+    const wordStart = kept.lastIndexOf(" ");
+    if (wordStart >= Math.ceil(width / 2)) kept = kept.slice(0, wordStart);
+  }
+  return `${kept.join("").trimEnd()}…`;
+}

package/ts/src/util/paths.ts

@@ -0,0 +1,63 @@
+// Filesystem path helpers for the front door.
+//
+// normalizeProjectPath is the parity crux of routing `journey set-path`: it must
+// canonicalize a path the way Python's _normalize_project_path does
+// (`Path(value).expanduser().resolve()`).
+
+import { accessSync, constants, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+
+/**
+ * Expand a leading `~` or `~/` to the home directory. A `~user` path passes
+ * through unchanged (Python's expanduser resolves known users; for the front
+ * door's purposes pass-through matches the unknown-user behavior and never
+ * fabricates a wrong path — pre-CR007 this mangled `~user/x` into home+`ser/x`).
+ */
+export function expandHome(path: string): string {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+  return path;
+}
+
+/** Can this process execute the file at `path`? */
+export function isExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where `command` resolves on `env.PATH`, or null: what a shell's `command -v`
+ * answers, for the PATH this process was given. The one rule for "is `mirror`
+ * reachable", "which runtimes are installed", and the hook wrappers' Node.
+ */
+export function commandOnPath(
+  command: string,
+  env: NodeJS.ProcessEnv,
+  canExecute: (path: string) => boolean = isExecutable,
+): string | null {
+  for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const candidate = join(dir, command);
+    if (canExecute(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Canonicalize a project path like Python's `Path(value).expanduser().resolve()`:
+ * expand `~`, make it absolute, and resolve symlinks. Node's `realpathSync` throws
+ * on a missing path, so fall back to the absolute (non-symlink) path — Python
+ * resolves non-strict, but `set-path` targets a real directory in the normal case.
+ */
+export function normalizeProjectPath(value: string): string {
+  const absolute = resolve(expandHome(value));
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}

package/ts/src/util/program.ts

@@ -0,0 +1,9 @@
+// The name the product gives itself in every command it tells a user to run
+// (CV22.DS10.TS5, decisions D2 and D12).
+//
+// `mirror` is not yet a command on anyone's PATH: the npm `bin` is
+// CV22.DS10.US3's to name. Until TS5 the usage lines and hints named the Python
+// program instead, in both its bare and its `uv`-wrapped form, and that program
+// no longer exists. Every one of them reads this constant now, so when US3
+// names the `bin`, this is the one place that changes.
+export const PROGRAM = "mirror";

package/ts/src/util/pyGenerators.ts

@@ -0,0 +1,144 @@
+// Deterministic identifier + timestamp generation matching the Python core.
+//
+// During DS4 parity, `id` and `now` were INJECTED so the TS write matched the
+// oracle. For live front-door writes (US4) the TS core must GENERATE them the way
+// Python does: `_uuid()` = uuid4().hex[:8] (8 lowercase hex chars) and `_now()` =
+// datetime.now(timezone.utc).isoformat().replace("+00:00","Z") (microsecond ISO-Z).
+
+import { randomUUID } from "node:crypto";
+import { compareByCodePoint } from "./pythonText.ts";
+
+/** Match Python `_uuid()` = uuid4().hex[:8]: 8 lowercase hex chars. */
+/**
+ * Serialize like Python `json.dumps(value, ensure_ascii=False)`: item
+ * separator `", "` and key separator `": "`. Scoped to JSON-decodable values
+ * (the shapes Mirror stores in TEXT metadata columns); byte-parity of stored
+ * metadata is part of the DS7 golden contract.
+ */
+export function pythonJsonDumps(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => pythonJsonDumps(item)).join(", ")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>).map(
+      ([key, item]) => `${JSON.stringify(key)}: ${pythonJsonDumps(item)}`,
+    );
+    return `{${entries.join(", ")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Serialize like Python's DEFAULT `json.dumps(value)` -- same `", "`/`": "`
+ * separators as above, but with `ensure_ascii=True`, so non-ASCII characters
+ * are escaped as `\uXXXX`.
+ *
+ * Mirror uses both variants, and which one applies is a per-call-site fact, not
+ * a preference: conversation `metadata`/`tags` are written with
+ * `ensure_ascii=False` (raw UTF-8), while memory `tags` go through
+ * `services/memory.py`'s plain `json.dumps(tags)` and are escaped. Storing
+ * `["café"]` where Python stored `["caf\u00e9"]` is a silent byte divergence in
+ * a column both cores read.
+ *
+ * JavaScript strings are UTF-16, so astral characters are already surrogate
+ * pairs and escaping each unit reproduces Python's surrogate-pair output.
+ */
+export function pythonJsonDumpsEnsureAscii(value: unknown): string {
+  return escapeNonAscii(pythonJsonDumps(value));
+}
+
+/**
+ * Serialize like Python `json.dumps(value, indent=2, sort_keys=True)` -- the
+ * shape of a file written to be read back by BOTH cores.
+ *
+ * `ensure_ascii` is left at Python's default (True), because the call site this
+ * mirrors leaves it there too: the welcome's update cache is written with a
+ * plain `json.dumps(payload, indent=2, sort_keys=True)`. A release title
+ * carrying an em dash must land as `\u2014`, not as raw UTF-8, or the two
+ * cores write different bytes for the same state and thrash each other's TTL.
+ */
+export function pythonJsonDumpsIndented(value: unknown, indent = 2): string {
+  return escapeNonAscii(JSON.stringify(sortKeysDeep(value), null, indent));
+}
+
+/**
+ * Serialize like Python `json.dumps(value, indent=2)` -- indented and
+ * ASCII-escaped, but in INSERTION order.
+ *
+ * Separate from `pythonJsonDumpsIndented` because that one carries
+ * `sort_keys=True`, and this call site does not: the extension runtime catalog
+ * is written key by key as `schema_version, runtime, target_root,
+ * generated_at, extensions`. Sorting would hoist `extensions` to the top and
+ * change every byte of a file both cores read and rewrite.
+ */
+export function pythonJsonDumpsIndentedOrdered(value: unknown, indent = 2): string {
+  return escapeNonAscii(JSON.stringify(value, null, indent));
+}
+
+/**
+ * Serialize like Python `json.dumps(value, ensure_ascii=True,
+ * separators=(",", ":"), sort_keys=True)` -- the canonical form a HASH is taken
+ * over.
+ *
+ * Separate from `pythonJsonDumpsIndented` because the bytes differ in three ways
+ * at once (no indent, no spaces after separators, escaped non-ASCII), and this one
+ * feeds `scope_fingerprint`. A fingerprint is an equality test on authority: if the
+ * two engines canonicalize differently, a receipt Python recorded cannot be
+ * consumed by TypeScript and the Navigator is asked to approve a Plan they already
+ * authorized.
+ *
+ * Keys are ordered by CODE POINT, not by JavaScript's default UTF-16 comparison.
+ * The fingerprint payload has fixed ASCII keys so the two orders coincide today;
+ * using the correct comparator means a future key cannot silently diverge.
+ */
+export function pythonJsonDumpsCanonical(value: unknown): string {
+  return escapeNonAscii(JSON.stringify(sortKeysByCodePoint(value)));
+}
+
+function sortKeysByCodePoint(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysByCodePoint);
+  if (typeof value !== "object" || value === null) return value;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort(compareByCodePoint)) {
+    sorted[key] = sortKeysByCodePoint((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+/** Python's `sort_keys=True`, applied at every level. */
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (typeof value !== "object" || value === null) return value;
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+function escapeNonAscii(text: string): string {
+  return text.replace(/[\u0080-\uffff]/g, (character) => {
+    const code = character.charCodeAt(0).toString(16).padStart(4, "0");
+    return `\\u${code}`;
+  });
+}
+
+export function newId(): string {
+  return randomUUID().replace(/-/g, "").slice(0, 8);
+}
+
+/**
+ * Format a Date the way Python's `_now()` does: an ISO-8601 UTC string with a `Z`
+ * suffix and 6-digit microseconds. JS Date resolves only to milliseconds, so the
+ * final three digits are zero-padded. This keeps the stored string the same length
+ * and lexicographic ordering as Python's timestamps — a millisecond `.123Z` would
+ * otherwise sort *after* a microsecond `.123456Z`, corrupting recency ordering.
+ */
+export function toMicrosecondIso(date: Date): string {
+  return date.toISOString().replace(/\.(\d{3})Z$/, ".$1000Z");
+}
+
+/** Match Python `_now()`: the current UTC time as a microsecond ISO-`Z` string. */
+export function nowIso(): string {
+  return toMicrosecondIso(new Date());
+}