mirror-mind 0.0.1 → 0.32.1

package/ts/src/journey/journeyWrite.ts

@@ -0,0 +1,203 @@
+// TS journey writes — the write path of create_journey and set_project_path.
+//
+// A journey is an identity row (layer "journey"). Its metadata is serialized in
+// the canonical JSON form (plain JSON.stringify) chosen in CV22.DS6.US1, which
+// retired the transition-only Python json.dumps byte-mimicry (pyJson.ts) once TS
+// owned schema custody. Existing rows written in the old Python dialects still
+// read back fine — every reader JSON.parses — and converge to the canonical form
+// on their next write. The project_path is normalized by the caller against the
+// real filesystem (Path.resolve equivalent), so we take it pre-normalized
+// (injected) — the same way id and now are injected.
+
+import { type WritableDatabase, withTransaction } from "#db/database.ts";
+import {
+  type IdentityRow,
+  updateIdentityMetadata,
+  upsertIdentity,
+} from "#identity/identityStore.ts";
+import { resolveParentJourney } from "#journey/parentJourney.ts";
+import { type JourneyParentRow, validateParentJourney } from "#journey/validateParentJourney.ts";
+
+export const JOURNEY_LAYER = "journey";
+
+/** Raised when a journey slug has no identity row to update. */
+export class JourneyNotFoundError extends Error {
+  readonly slug: string;
+  constructor(slug: string) {
+    super(`journey not found: ${slug}`);
+    this.slug = slug;
+  }
+}
+
+export interface JourneyFields {
+  /** Already normalized (Path.resolve equivalent) when present. */
+  projectPath?: string | null;
+  syncFile?: string | null;
+  icon?: string | null;
+  color?: string | null;
+  parentJourney?: string | null;
+}
+
+export interface CreateJourneyInput extends JourneyFields {
+  id: string;
+  slug: string;
+  content: string;
+}
+
+/** Read the complete parent graph through CR050's metadata-only resolver. */
+function journeyParentRows(db: WritableDatabase): JourneyParentRow[] {
+  return db
+    .prepare("SELECT key, metadata FROM identity WHERE layer = ? ORDER BY key")
+    .all(JOURNEY_LAYER)
+    .map((row) => ({
+      key: typeof row.key === "string" ? row.key : "",
+      parentJourney: resolveParentJourney({
+        metadata: typeof row.metadata === "string" ? row.metadata : null,
+      }),
+    }));
+}
+
+/** Python's tolerant metadata-object boundary for parent updates. */
+function metadataObject(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "string" || raw.length === 0) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { ...(parsed as Record<string, unknown>) }
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function normalizeParentJourney(value: string | null | undefined): string {
+  const clean = (value ?? "").trim();
+  if (clean.length > 500) throw new Error("parent_journey must be at most 500 characters");
+  return clean;
+}
+
+/**
+ * Select the non-empty metadata fields in a fixed order (trim; keep only
+ * non-empty), mirroring Python's _metadata_from_fields. The fixed order makes
+ * the canonical JSON.stringify output deterministic and gives set_project_path a
+ * stable key order to update in place.
+ */
+export function journeyMetadata(fields: JourneyFields): Record<string, string> {
+  const ordered: [string, string | null | undefined][] = [
+    ["project_path", fields.projectPath],
+    ["sync_file", fields.syncFile],
+    ["icon", fields.icon],
+    ["color", fields.color],
+    ["parent_journey", fields.parentJourney],
+  ];
+  const metadata: Record<string, string> = {};
+  for (const [key, value] of ordered) {
+    const clean = key === "parent_journey" ? normalizeParentJourney(value) : (value ?? "").trim();
+    if (clean) {
+      metadata[key] = clean;
+    }
+  }
+  return metadata;
+}
+
+/**
+ * Port of create_journey's write: compose metadata, serialize, upsert identity,
+ * and atomically mirror `parent_journey` into the first-class column in the
+ * SAME transaction (CV22.DS6.US3 rider, activated here). Both statements
+ * commit or roll back together — a failure between them must never leave the
+ * JSON and the column disagreeing (see reinforcement.ts's `logAccess` for the
+ * same `withTransaction` idiom applied to a different two-statement write).
+ *
+ * `setParentJourney` below is the dedicated move seam. Python's
+ * `JourneyService.update_metadata_fields` can still change or remove a parent
+ * and does not know the column exists — that path remains live through the
+ * Python Workspace/web backend. CR050 therefore keeps metadata as mixed-engine
+ * semantic authority and treats column writes as projection maintenance.
+ */
+export function createJourney(
+  db: WritableDatabase,
+  input: CreateJourneyInput,
+  nowIso: string,
+): void {
+  const metadata = journeyMetadata(input);
+  const metadataJson = Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : null;
+  const parentJourney = metadata.parent_journey ?? null;
+  const row: IdentityRow = {
+    id: input.id,
+    layer: JOURNEY_LAYER,
+    key: input.slug,
+    content: input.content,
+    version: "1.0.0",
+    metadata: metadataJson,
+  };
+  withTransaction(db, () => {
+    if (parentJourney) {
+      validateParentJourney(input.slug, parentJourney, journeyParentRows(db));
+    }
+    upsertIdentity(db, row, nowIso);
+    db.prepare("UPDATE identity SET parent_journey = ? WHERE layer = ? AND key = ?").run(
+      parentJourney,
+      JOURNEY_LAYER,
+      input.slug,
+    );
+  });
+}
+
+/**
+ * Move an existing journey, or make it a root, without changing any other
+ * identity field. Graph read, full-ancestry validation, metadata update, and
+ * migration 017 projection maintenance share one immediate transaction so a
+ * concurrent writer cannot invalidate the checked ancestry before commit.
+ */
+export function setParentJourney(
+  db: WritableDatabase,
+  slug: string,
+  parentJourney: string | null,
+  nowIso: string,
+): void {
+  const cleanParent = normalizeParentJourney(parentJourney);
+  withTransaction(db, () => {
+    const row = db
+      .prepare("SELECT metadata FROM identity WHERE layer = ? AND key = ?")
+      .get(JOURNEY_LAYER, slug);
+    if (row === undefined) throw new JourneyNotFoundError(slug);
+
+    const parentRows = journeyParentRows(db);
+    validateParentJourney(slug, cleanParent || null, parentRows);
+
+    const metadata = metadataObject(row.metadata);
+    if (cleanParent) metadata.parent_journey = cleanParent;
+    else delete metadata.parent_journey;
+    updateIdentityMetadata(db, JOURNEY_LAYER, slug, JSON.stringify(metadata), nowIso);
+    db.prepare("UPDATE identity SET parent_journey = ? WHERE layer = ? AND key = ?").run(
+      cleanParent || null,
+      JOURNEY_LAYER,
+      slug,
+    );
+  });
+}
+
+/**
+ * Port of set_project_path's write: read the journey metadata, set project_path
+ * (already normalized), re-serialize in the canonical JSON form, update.
+ * Preserves the existing key order and updates project_path in place when present.
+ */
+export function setProjectPath(
+  db: WritableDatabase,
+  slug: string,
+  normalizedProjectPath: string,
+  nowIso: string,
+): void {
+  const row = db
+    .prepare("SELECT metadata FROM identity WHERE layer = ? AND key = ?")
+    .get(JOURNEY_LAYER, slug);
+  if (row === undefined) {
+    throw new JourneyNotFoundError(slug);
+  }
+  const existing =
+    typeof row.metadata === "string" && row.metadata.length > 0
+      ? (JSON.parse(row.metadata) as Record<string, unknown>)
+      : {};
+  const meta: Record<string, unknown> = { ...existing, project_path: normalizedProjectPath };
+  updateIdentityMetadata(db, JOURNEY_LAYER, slug, JSON.stringify(meta), nowIso);
+}

package/ts/src/journey/parentJourney.ts

@@ -0,0 +1,41 @@
+// Mixed-engine parent-journey resolution (RS008/CR050).
+//
+// Python v0.31.9 stores the semantic parent in identity.metadata and remains
+// runtime authority for the unported Workspace/web parent writer. TS migration
+// 017's `identity.parent_journey` column is therefore only a derived projection
+// while both engines can write: Python can move or unparent a journey without
+// updating that column. Reading the column as authority or fallback would then
+// resurrect stale structure.
+//
+// Every supported TS parent writer still updates metadata and the projection
+// atomically. A future column-authority flip requires every parent writer to be
+// on TS plus a separate decision; until then all TS readers use this one
+// metadata-only resolver and column/metadata disagreement is drift to diagnose,
+// never something a read silently repairs.
+
+export interface ParentJourneySource {
+  /** Migration 017's derived projection. Not semantic authority during mixed-engine operation. */
+  parent_journey?: string | null;
+  /** The semantic journey metadata written by both Python and TS. */
+  metadata?: string | null;
+}
+
+/** Parse the parent journey out of JSON metadata; "" on malformed/non-object
+ * metadata or a non-string value, matching the Python reader's tolerance. */
+function resolveParentJourneyFromMetadata(metadata: string | null | undefined): string {
+  if (!metadata) return "";
+  let payload: unknown;
+  try {
+    payload = JSON.parse(metadata);
+  } catch {
+    return "";
+  }
+  if (payload === null || typeof payload !== "object") return "";
+  const parent = (payload as Record<string, unknown>).parent_journey;
+  return typeof parent === "string" ? parent : "";
+}
+
+/** Resolve a journey's parent from the mixed-engine semantic authority. */
+export function resolveParentJourney(source: ParentJourneySource): string {
+  return resolveParentJourneyFromMetadata(source.metadata);
+}

package/ts/src/journey/validateParentJourney.ts

@@ -0,0 +1,55 @@
+// Port of `JourneyService._validate_parent_journey` (src/memory/services/journey.py).
+//
+// Pure over resolved journey rows — the DB seam supplies them, keeping this the
+// decision core. Walks complete ancestry in Python's exact order and with
+// Python's exact messages, so the front door and every parent write route
+// reject an invalid parent identically to the Python oracle. Parent information
+// is read from mixed-engine-authoritative metadata (CR050) via
+// `resolveParentJourney`, the same resolver the listing sort uses, so validation
+// and listing can never disagree.
+
+/** Raised when a proposed parent_journey violates a hierarchy rule. */
+export class ParentJourneyValidationError extends Error {}
+
+/** One journey with its CR050 metadata-authoritative parent; "" when it has none. */
+export interface JourneyParentRow {
+  key: string;
+  parentJourney: string;
+}
+
+/**
+ * Validate a proposed `parentJourney` for `journey` against all known journey
+ * rows. No-op when the parent is empty. Otherwise enforce the released
+ * arbitrary-depth boundary: the proposed parent must exist, its full ancestry
+ * must not reach the journey being moved, and that ancestry must not already
+ * contain a cycle. A missing legacy ancestor safely ends the walk, matching
+ * Python's tolerant read behavior.
+ */
+export function validateParentJourney(
+  journey: string | null,
+  parentJourney: string | null,
+  rows: readonly JourneyParentRow[],
+): void {
+  if (!parentJourney) return;
+  if (journey && parentJourney === journey) {
+    throw new ParentJourneyValidationError("parent_journey cannot be the journey itself");
+  }
+  const byKey = new Map(rows.map((row) => [row.key, row]));
+  let current = byKey.get(parentJourney);
+  if (!current) {
+    throw new ParentJourneyValidationError(`Parent journey '${parentJourney}' not found`);
+  }
+
+  const visited = new Set<string>();
+  while (current) {
+    if (journey && current.key === journey) {
+      throw new ParentJourneyValidationError("parent_journey would create a cycle");
+    }
+    if (visited.has(current.key)) {
+      throw new ParentJourneyValidationError("Parent lineage contains an existing cycle");
+    }
+    visited.add(current.key);
+    if (!current.parentJourney) return;
+    current = byKey.get(current.parentJourney);
+  }
+}

package/ts/src/mcp/boundary.ts

@@ -0,0 +1,151 @@
+// The guard boundary around the wired MCP registry (CV22.DS9.TS1).
+//
+// Placement is the whole design. Validation lives in a WRAPPER rather than inside the
+// tools, because the parity golden calls the tool functions directly: the tools stay
+// Python-faithful -- `recall_conversation` with `limit=0` still returns the whole
+// transcript, as the oracle does and `mcp-tools.golden.json` records -- while the registry
+// a client reaches refuses the same arguments. DS9's D4 asked for the divergence to be
+// visible on both sides rather than one silently overwriting the other, and this is what
+// makes that possible.
+//
+// Both controls the threat model assigns to TS1 sit here:
+//
+//   * argument bounds (items 1-2, exfiltration shapes) -- `limit=0` returning an entire
+//     transcript is the cheapest one the surface offers;
+//   * the spend decision (item 3, denial of wallet) -- applied only to the tools that can
+//     reach a provider, because a wallet guard has no business refusing a free read.
+
+import type { Database } from "#db/database.ts";
+import { decideSpend, PAID_TOOLS, readSpendState, type SpendPolicy } from "./guards.ts";
+import type { Tool, ToolRegistry } from "./registry.ts";
+import { buildRegistry } from "./registry.ts";
+
+/** Per-tool argument bounds. A table, not a JSON-Schema validator: seven declarations
+ * do not earn one, and the rules a schema cannot express (the caps) are the point. */
+interface ArgumentRules {
+  /** Inclusive upper bound for `limit`, when the tool takes one. */
+  limitMax?: number;
+  /** Inclusive upper bound for the length of `query`, when the tool takes one. */
+  queryMaxLength?: number;
+}
+
+const QUERY_MAX_LENGTH = 4_000;
+
+const RULES: Record<string, ArgumentRules> = {
+  // Caps chosen an order of magnitude above any plausible agent request, so they bound
+  // abuse without ever shaping legitimate use.
+  search_memories: { limitMax: 50, queryMaxLength: QUERY_MAX_LENGTH },
+  list_conversations: { limitMax: 100 },
+  recall_conversation: { limitMax: 200 },
+  mirror_context: { queryMaxLength: QUERY_MAX_LENGTH },
+  detect_persona: { queryMaxLength: QUERY_MAX_LENGTH },
+};
+
+export interface GuardOptions {
+  db: Database;
+  policy: SpendPolicy;
+  /** Where the refusal line goes. Defaults to stderr, the client's log for this server. */
+  warn?: (line: string) => void;
+  /** Injectable clock for the window, used by tests. */
+  now?: () => Date;
+}
+
+/**
+ * Python's `int(...)` tolerance, bounded.
+ *
+ * `int("5")` and `int(5)` both succeed in Python and clients do send the string form, so
+ * that stays. `int(5.9)` also succeeds -- it truncates -- but a fractional limit from an
+ * agent is a mistake worth naming rather than silently rounding, and no oracle behaviour
+ * depends on it reaching the tool: the boundary refuses before the tool is entered.
+ */
+function boundedLimit(value: unknown, max: number): number | null {
+  const numeric =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim() !== ""
+        ? Number(value)
+        : Number.NaN;
+  if (!Number.isInteger(numeric) || numeric < 1 || numeric > max) return null;
+  return numeric;
+}
+
+function received(value: unknown): string {
+  // Numbers and short scalars are safe to quote back; agent-authored TEXT is not -- the
+  // refusal travels into the model's context and into the client's log (RS005).
+  if (typeof value === "number" || typeof value === "boolean" || value === null)
+    return String(value);
+  if (typeof value === "string") return Number.isNaN(Number(value)) ? "a non-numeric value" : value;
+  return "a value of the wrong type";
+}
+
+/**
+ * Validate one call's arguments. Throws the refusal, which `protocol.ts` turns into an
+ * `isError` result -- a readable failure the session survives, never a protocol error.
+ *
+ * Argument refusals are deliberately NOT terminal: unlike a spend refusal, the right
+ * response is to correct the value and call again, so the text states the valid range and
+ * says nothing about retrying.
+ */
+function validateArguments(tool: string, args: unknown): void {
+  const rules = RULES[tool];
+  if (!rules) return;
+  const record =
+    args !== null && typeof args === "object" && !Array.isArray(args)
+      ? (args as Record<string, unknown>)
+      : {};
+
+  if (rules.limitMax !== undefined && record.limit !== undefined && record.limit !== null) {
+    if (boundedLimit(record.limit, rules.limitMax) === null) {
+      throw new Error(
+        `${tool}: limit must be an integer from 1 to ${rules.limitMax} (received ${received(record.limit)})`,
+      );
+    }
+  }
+
+  if (rules.queryMaxLength !== undefined && typeof record.query === "string") {
+    // Embedding cost is proportional to tokens, so an unbounded query is unbounded spend
+    // in a single call -- the rate guard alone would not catch it.
+    const length = [...record.query].length;
+    if (length > rules.queryMaxLength) {
+      throw new Error(
+        `${tool}: query must be at most ${rules.queryMaxLength} characters (received ${length})`,
+      );
+    }
+  }
+}
+
+/**
+ * Wrap a wired registry with argument validation and, for the provider-crossing tools, the
+ * spend decision.
+ *
+ * `tools/list` is untouched: the declarations a client caches are the contract US1 froze,
+ * and a guard is server behaviour, not a change to what the surface offers.
+ */
+export function guardedRegistry(inner: ToolRegistry, options: GuardOptions): ToolRegistry {
+  const warn = options.warn ?? ((line: string) => process.stderr.write(`${line}\n`));
+  const now = options.now ?? (() => new Date());
+
+  const guard = (tool: Tool): Tool => ({
+    ...tool,
+    handler: async (args: unknown) => {
+      validateArguments(tool.name, args);
+      if (PAID_TOOLS.includes(tool.name)) {
+        const decision = decideSpend(
+          tool.name,
+          readSpendState(options.db, options.policy, now()),
+          options.policy,
+        );
+        if (!decision.allow) {
+          // Metadata only: the tool and the reason, never the arguments.
+          warn(`guard refused tool=${tool.name} reason=${decision.reason}`);
+          throw new Error(decision.text);
+        }
+      }
+      return await tool.handler(args);
+    },
+  });
+
+  const list = inner.list.map(guard);
+  const extras = [...inner.byName.values()].filter((tool) => !inner.list.includes(tool)).map(guard);
+  return buildRegistry(list, extras);
+}