@remnic/core 9.65.6 → 9.65.8

package/src/location/surfaces.ts

@@ -0,0 +1,329 @@
+/**
+ * Location surface runners (issue #2047) — ONE implementation shared by the
+ * CLI (`remnic location ...`), the MCP tools, the HTTP routes, and the
+ * scheduler, so no surface can fork validation or disabled/empty/failure
+ * semantics (same rule as the wearables runner). Parsing here is strict:
+ * unknown flags reject with the valid list, invalid values reject loudly.
+ */
+
+import { EngramAccessInputError } from "../access-errors.js";
+import {
+  checkLocationSources,
+  locationStatus,
+  syncLocation,
+  type LocationSourceCheckResult,
+  type LocationStatusReport,
+} from "./cli.js";
+import { isValidLocationDate } from "./intervals.js";
+import type { LocationSourceSyncResult } from "./pipeline.js";
+import { ensureConfiguredLocationProviders } from "./provider-setup.js";
+import { parseLocationDaySummary, readLocationDay } from "./store.js";
+import type { LocationConfig } from "./types.js";
+
+export interface LocationSurfaceDeps {
+  config: LocationConfig;
+  memoryDir: string;
+}
+
+export interface LocationSyncRun {
+  date: string;
+  results: LocationSourceSyncResult[];
+}
+
+export type LocationSyncRuns = LocationSyncRun[];
+
+export async function runLocationStatus(
+  deps: LocationSurfaceDeps,
+): Promise<LocationStatusReport> {
+  await ensureConfiguredLocationProviders(deps.config);
+  return locationStatus(deps.config, deps.memoryDir);
+}
+
+export async function runLocationCheck(
+  deps: LocationSurfaceDeps,
+  signal?: AbortSignal,
+): Promise<LocationSourceCheckResult[]> {
+  await ensureConfiguredLocationProviders(deps.config);
+  return checkLocationSources(deps.config, signal !== undefined ? { signal } : {});
+}
+
+export async function runLocationSync(
+  deps: LocationSurfaceDeps,
+  request: { endDate?: string; days?: number } = {},
+): Promise<LocationSyncRuns> {
+  await ensureConfiguredLocationProviders(deps.config);
+  const runs = await syncLocation({ ...deps, ...validatedSyncWindow(request) });
+  return runs as LocationSyncRuns;
+}
+
+export interface LocationDayView {
+  date: string;
+  found: boolean;
+  sources: string[];
+  observationCount: number;
+  body: string | null;
+}
+
+export async function runLocationDay(memoryDir: string, rawDate: unknown): Promise<LocationDayView> {
+  const date = requireLocationDate(rawDate, "date");
+  const body = await readLocationDay(memoryDir, date);
+  const summary = body === null ? null : parseLocationDaySummary(body);
+  return {
+    date,
+    found: body !== null,
+    sources: summary?.sources ?? [],
+    observationCount: summary?.observationCount ?? 0,
+    body,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared validation (CLI, MCP, HTTP all reject identically)
+// ---------------------------------------------------------------------------
+
+function requireLocationDate(raw: unknown, label: string): string {
+  if (typeof raw !== "string" || !isValidLocationDate(raw)) {
+    throw new EngramAccessInputError(`location: ${label} is required (YYYY-MM-DD)`);
+  }
+  return raw;
+}
+
+function optionalLocationDays(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null || raw === "") return undefined;
+  const parsed = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 90) {
+    throw new EngramAccessInputError("location: days expects an integer from 1 to 90");
+  }
+  return parsed;
+}
+
+function validatedSyncWindow(request: { endDate?: string; days?: number }): {
+  endDate?: string;
+  days?: number;
+} {
+  const days = optionalLocationDays(request.days);
+  const endDate =
+    request.endDate === undefined || request.endDate === null || request.endDate === ""
+      ? undefined
+      : requireLocationDate(request.endDate, "date");
+  return { ...(endDate !== undefined ? { endDate } : {}), ...(days !== undefined ? { days } : {}) };
+}
+
+/** Day span between two inclusive local dates (from ≤ to, ≤ 90 days). */
+export function parseLocationBackfillRange(
+  rawFrom: unknown,
+  rawTo: unknown,
+): { endDate: string; days: number } {
+  const from = requireLocationDate(rawFrom, "from");
+  const to = requireLocationDate(rawTo, "to");
+  const fromMs = Date.parse(`${from}T00:00:00Z`);
+  const toMs = Date.parse(`${to}T00:00:00Z`);
+  if (toMs < fromMs) {
+    throw new EngramAccessInputError("location: backfill --from must not be after --to");
+  }
+  const days = Math.round((toMs - fromMs) / 86_400_000) + 1;
+  if (days > 90) {
+    throw new EngramAccessInputError("location: backfill range is capped at 90 days");
+  }
+  return { endDate: to, days };
+}
+
+// ---------------------------------------------------------------------------
+// CLI command (shared by every CLI host)
+// ---------------------------------------------------------------------------
+
+export interface LocationCliIo {
+  stdout: { write(chunk: string): unknown };
+  stderr: { write(chunk: string): unknown };
+}
+
+const USAGE = `Usage: location <command> [options]
+
+Commands:
+  status                         Configured sources, registration, last sync
+  check                          Probe every enabled provider (auth/connectivity)
+  sync [options]                 Sync recent local days (default: config.syncDays
+                                   ending yesterday)
+    --date <YYYY-MM-DD>          End the window on this day (inclusive)
+    --days <n>                   Window size, 1..90 (default: location.syncDays)
+  backfill --from <date> --to <date>
+                                 Sync an explicit historical range (≤ 90 days)
+  day <YYYY-MM-DD>               Print one stored location day
+
+Add --json to status/sync/backfill/day for machine-readable output.
+Credentials for built-in providers come from the environment:
+  reitti: REITTI_BASE_URL, REITTI_TOKEN[, REITTI_AUTH_MODE=x-api-token|bearer]
+`;
+
+const VALUE_FLAGS = new Set(["--date", "--days", "--from", "--to"]);
+const BOOLEAN_FLAGS = new Set(["--json"]);
+
+interface ParsedCliFlags {
+  flags: Map<string, string | true>;
+  positional: string[];
+}
+
+function parseCliFlags(args: string[]): ParsedCliFlags {
+  const flags = new Map<string, string | true>();
+  const positional: string[] = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    if (BOOLEAN_FLAGS.has(arg)) {
+      flags.set(arg, true);
+      continue;
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new EngramAccessInputError(`location: ${arg} requires a value`);
+      }
+      flags.set(arg, value);
+      index++;
+      continue;
+    }
+    throw new EngramAccessInputError(
+      `location: unknown flag '${arg}' — valid flags: ${[...VALUE_FLAGS, ...BOOLEAN_FLAGS].join(", ")}`,
+    );
+  }
+  return { flags, positional };
+}
+
+function flagString(parsed: ParsedCliFlags, name: string): string | undefined {
+  const value = parsed.flags.get(name);
+  return typeof value === "string" ? value : undefined;
+}
+
+function renderStatus(report: LocationStatusReport): string {
+  const lines = [
+    `Location: ${report.enabled ? "enabled" : "disabled"} (timezone ${report.timezone})`,
+  ];
+  if (report.sources.length === 0) {
+    lines.push("No sources configured. Add location.sources to the plugin config.");
+    return `${lines.join("\n")}\n`;
+  }
+  for (const source of report.sources) {
+    lines.push(
+      `  ${source.id}: ${source.enabled ? "enabled" : "disabled"}, ` +
+        `provider ${source.providerRegistered ? "registered" : "not registered"}, ` +
+        `${source.trackedDays} tracked day${source.trackedDays === 1 ? "" : "s"}, ` +
+        `last sync ${source.lastSyncedAtUtc ?? "never"}`,
+    );
+  }
+  if (report.recentDays.length > 0) {
+    lines.push("  recent days:");
+    for (const day of report.recentDays) {
+      lines.push(
+        `    ${day.date}  ${day.observationCount} observation${day.observationCount === 1 ? "" : "s"}  [${day.sources.join(", ")}]`,
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function anySourceFailed(runs: LocationSyncRuns): boolean {
+  return runs.some((run) => run.results.some((result) => result.status === "failed"));
+}
+
+function renderRuns(io: LocationCliIo, runs: LocationSyncRuns): void {
+  for (const run of runs) {
+    for (const result of run.results) {
+      io.stdout.write(
+        `${run.date} ${result.sourceId}: ${result.status}${result.error ? ` — ${result.error}` : ""} (${result.fetched} fetched)\n`,
+      );
+    }
+  }
+}
+
+/** Run a `remnic location ...` command; returns a process exit code. */
+export async function runLocationCliCommand(
+  deps: LocationSurfaceDeps,
+  args: string[],
+  io: LocationCliIo,
+): Promise<number> {
+  const [command, ...rest] = args;
+  try {
+    switch (command) {
+      case undefined:
+      case "help":
+      case "--help": {
+        io.stdout.write(USAGE);
+        return command === undefined ? 1 : 0;
+      }
+      case "status": {
+        const parsed = parseCliFlags(rest);
+        const report = await runLocationStatus(deps);
+        if (parsed.flags.has("--json")) {
+          io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+          return 0;
+        }
+        io.stdout.write(renderStatus(report));
+        return 0;
+      }
+      case "check": {
+        const results = await runLocationCheck(deps);
+        for (const result of results) {
+          const skipped = result.skipped === undefined ? "" : ` (skipped: ${result.skipped})`;
+          io.stdout.write(
+            `${result.id}: ${result.ok ? "OK" : "FAILED"}${skipped}${result.detail ? ` — ${result.detail}` : ""}\n`,
+          );
+        }
+        return results.every((result) => result.ok) ? 0 : 1;
+      }
+      case "sync": {
+        const parsed = parseCliFlags(rest);
+        if (parsed.positional.length > 0) {
+          throw new EngramAccessInputError(
+            `location: unexpected argument '${parsed.positional[0]}' — sync takes flags only`,
+          );
+        }
+        const daysValue = flagString(parsed, "--days");
+        const runs = await runLocationSync(deps, {
+          endDate: flagString(parsed, "--date"),
+          ...(daysValue !== undefined ? { days: Number(daysValue) } : {}),
+        });
+        if (parsed.flags.has("--json")) {
+          io.stdout.write(`${JSON.stringify({ days: runs }, null, 2)}\n`);
+        } else {
+          renderRuns(io, runs);
+        }
+        return anySourceFailed(runs) ? 1 : 0;
+      }
+      case "backfill": {
+        const parsed = parseCliFlags(rest);
+        const range = parseLocationBackfillRange(flagString(parsed, "--from"), flagString(parsed, "--to"));
+        const runs = await runLocationSync(deps, range);
+        if (parsed.flags.has("--json")) {
+          io.stdout.write(`${JSON.stringify({ days: runs }, null, 2)}\n`);
+        } else {
+          renderRuns(io, runs);
+        }
+        return anySourceFailed(runs) ? 1 : 0;
+      }
+      case "day": {
+        const parsed = parseCliFlags(rest);
+        const date = parsed.positional[0] ?? flagString(parsed, "--date");
+        const view = await runLocationDay(deps.memoryDir, date);
+        if (!view.found) {
+          io.stderr.write(`No stored location day for ${view.date}.\n`);
+          return 1;
+        }
+        if (parsed.flags.has("--json")) {
+          io.stdout.write(`${JSON.stringify(view, null, 2)}\n`);
+          return 0;
+        }
+        io.stdout.write(`${view.body}\n`);
+        return 0;
+      }
+      default:
+        io.stderr.write(`location: unknown command '${command}'\n${USAGE}`);
+        return 1;
+    }
+  } catch (err) {
+    io.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}

package/src/maintenance/day-summary-cron.ts

@@ -0,0 +1,45 @@
+/**
+ * Day-summary cron model resolution (extracted from
+ * orchestration/maintenance.ts in #2047 so that capped file keeps only
+ * scheduling wiring). Pure function of config — no I/O.
+ */
+
+import type { PluginConfig } from "../types.js";
+
+/**
+ * Resolve the cron-routing model + fallback chain. Only in gateway mode is
+ * summaryModel routable as an OpenClaw agentTurn model; in plugin mode it is
+ * a direct-client model id for Remnic's own LLM calls. Task-chain fallbacks
+ * attach only when the model matches the task-chain primary (a distinct
+ * override's fallbacks would be unrelated); gateway default models are
+ * appended as tail fallbacks (de-duped) so a task-chain outage doesn't stop
+ * the cron before reaching the gateway default chain.
+ */
+export function resolveDaySummaryCronModel(config: PluginConfig): {
+  model?: string;
+  fallbacks: string[];
+} {
+  const rawSummaryModel = config.summaryModel;
+  const taskPrimary = config.taskModelChain?.primary;
+  const isGateway = config.modelSource === "gateway";
+  const model = isGateway ? rawSummaryModel || taskPrimary || undefined : undefined;
+  const fallbacks: string[] = [];
+  if (model && taskPrimary && model === taskPrimary) {
+    const seen = new Set<string>(model ? [model] : []);
+    const addUnique = (value: string | undefined) => {
+      if (typeof value !== "string") return;
+      const trimmed = value.trim();
+      if (trimmed.length > 0 && !seen.has(trimmed)) {
+        seen.add(trimmed);
+        fallbacks.push(trimmed);
+      }
+    };
+    for (const fb of config.taskModelChain?.fallbacks ?? []) addUnique(fb);
+    const gwDefaults = config.gatewayConfig?.agents?.defaults?.model;
+    addUnique(gwDefaults?.primary);
+    if (Array.isArray(gwDefaults?.fallbacks)) {
+      for (const fb of gwDefaults.fallbacks) addUnique(fb);
+    }
+  }
+  return { ...(model ? { model } : {}), fallbacks };
+}

package/src/mcp-read-only-tools.ts

@@ -23,6 +23,8 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   transcript_day: true,
   transcript_search: true,
   transcript_memories: true,
+  location_status: true,
+  location_day: true,
   meetings_list: true,
   meetings_get: true,
   action_confidence: true,

package/src/memory-action-policy.ts

@@ -78,3 +78,31 @@ export function evaluateMemoryActionPolicy(input: {
     eligibility,
   };
 }
+
+/**
+ * Gate for active-context SUMMARY/FILTER plans (issue #2347). The single
+ * deny rule is the shared `contextCompressionActionsEnabled` gate — a closed
+ * gate returns `feature_disabled` before any selection or model work. LLM
+ * summaries carry their own cap gate (`activeContextTransformLlmEnabled`)
+ * resolved at plan time, not here.
+ */
+export interface ActiveContextTransformPolicyResult {
+  decision: "allow" | "deny";
+  rationale: string;
+}
+
+export function evaluateActiveContextTransformPolicy(options: {
+  actionsEnabled: boolean;
+  operation: "SUMMARY" | "FILTER";
+}): ActiveContextTransformPolicyResult {
+  if (!options.actionsEnabled) {
+    return {
+      decision: "deny",
+      rationale: "contextCompressionActionsEnabled=false",
+    };
+  }
+  return {
+    decision: "allow",
+    rationale: `${options.operation.toLowerCase()}_eligible`,
+  };
+}

package/src/memory-worth-outcomes.test.ts

@@ -1,14 +1,15 @@
-import test from "node:test";
 import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import test from "node:test";
 
-import { StorageManager } from "./storage.js";
 import {
-  recordMemoryOutcome,
   memoryWorthOutcomeEligibleCategories,
+  recordMemoryOutcome,
+  toMemoryOutcomeObservation,
 } from "./memory-worth-outcomes.js";
+import { StorageManager } from "./storage.js";
 
 /**
  * Issue #560 PR 3 — tests for the outcome signal pipeline.
@@ -27,7 +28,7 @@ import {
 async function writeFactFile(
   storage: StorageManager,
   body: string,
-  extraFrontmatterLines: string[] = [],
+  extraFrontmatterLines: string[] = []
 ): Promise<{ id: string; filePath: string }> {
   const today = new Date().toISOString().slice(0, 10);
   const id = `fact-${Date.now()}-${Math.random().toString(36).slice(2)}`;
@@ -51,10 +52,7 @@ async function writeFactFile(
   return { id, filePath };
 }
 
-async function writeCorrectionFile(
-  storage: StorageManager,
-  body: string,
-): Promise<{ id: string; filePath: string }> {
+async function writeCorrectionFile(storage: StorageManager, body: string): Promise<{ id: string; filePath: string }> {
   const id = `correction-${Date.now()}-${Math.random().toString(36).slice(2)}`;
   const lines = [
     "---",
@@ -68,10 +66,7 @@ async function writeCorrectionFile(
     "tags: []",
     "---",
   ];
-  const correctionsDir = path.join(
-    (storage as unknown as { baseDir: string }).baseDir,
-    "corrections",
-  );
+  const correctionsDir = path.join((storage as unknown as { baseDir: string }).baseDir, "corrections");
   await mkdir(correctionsDir, { recursive: true });
   const filePath = path.join(correctionsDir, `${id}.md`);
   await writeFile(filePath, `${lines.join("\n")}\n\n${body}\n`, "utf-8");
@@ -140,10 +135,7 @@ test("consecutive outcomes accumulate independently", async () => {
   try {
     const storage = new StorageManager(dir);
     await storage.ensureDirectories();
-    const { id, filePath } = await writeFactFile(storage, "Accumulating outcomes.", [
-      "mw_success: 2",
-      "mw_fail: 0",
-    ]);
+    const { id, filePath } = await writeFactFile(storage, "Accumulating outcomes.", ["mw_success: 2", "mw_fail: 0"]);
 
     await recordMemoryOutcome(storage, { memoryPath: filePath, outcome: "success" });
     await recordMemoryOutcome(storage, { memoryPath: filePath, outcome: "failure" });
@@ -289,7 +281,7 @@ test("concurrent outcomes for the same memory do NOT lose updates", async () =>
 
     const N = 10;
     const calls = Array.from({ length: N }, () =>
-      recordMemoryOutcome(storage, { memoryPath: filePath, outcome: "success" }),
+      recordMemoryOutcome(storage, { memoryPath: filePath, outcome: "success" })
     );
     const results = await Promise.all(calls);
 
@@ -318,3 +310,46 @@ test("eligible-category set is exactly {fact, procedure}", () => {
   assert.ok(eligible.has("fact"));
   assert.ok(eligible.has("procedure"));
 });
+
+// ---------------------------------------------------------------------------
+// Issue #2345 — pure MemoryOutcomeObservation view (no writes, no counters)
+// ---------------------------------------------------------------------------
+
+test("outcome facts with time and join data become observations", () => {
+  const view = toMemoryOutcomeObservation({
+    memoryId: "fact-1",
+    namespace: "test-ns",
+    outcome: "success",
+    observedAt: "2026-08-12T00:00:00.000Z",
+    joinId: "act-1",
+  });
+  assert.equal(view.status, "observed");
+  if (view.status === "observed") {
+    assert.equal(view.observation.schemaVersion, 1);
+    assert.equal(view.observation.observedAt, "2026-08-12T00:00:00.000Z");
+    assert.equal(view.observation.joinId, "act-1");
+    // Round-trips through public types (undefined optionals drop in JSON).
+    const roundTripped = JSON.parse(JSON.stringify(view.observation)) as Record<string, unknown>;
+    assert.equal(roundTripped.schemaVersion, 1);
+    assert.equal(roundTripped.memoryId, "fact-1");
+    assert.equal(roundTripped.joinId, "act-1");
+  }
+});
+
+test("counter-only rows stay missing_observation and never guess an action", () => {
+  const noTime = toMemoryOutcomeObservation({
+    memoryId: "fact-1",
+    namespace: "test-ns",
+    outcome: "success",
+    joinId: "act-1",
+  });
+  assert.deepEqual(noTime, { status: "missing_observation", memoryId: "fact-1", reason: "missing_observed_at" });
+
+  const noJoin = toMemoryOutcomeObservation({
+    memoryId: "fact-2",
+    namespace: "test-ns",
+    outcome: "failure",
+    observedAt: new Date("2026-08-12T00:00:00.000Z"),
+  });
+  assert.deepEqual(noJoin, { status: "missing_observation", memoryId: "fact-2", reason: "missing_join_data" });
+});

package/src/memory-worth-outcomes.ts

@@ -86,7 +86,7 @@ function runSerialized<T>(key: string, task: () => Promise<T>): Promise<T> {
       },
       () => {
         if (outcomeLocks.get(key) === next) outcomeLocks.delete(key);
-      },
+      }
     )
     .catch(() => {
       // Defensive no-op in case a hook inside the cleanup branches throws.
@@ -104,8 +104,10 @@ function runSerialized<T>(key: string, task: () => Promise<T>): Promise<T> {
  * imports from this file's peers. The two constants are validated by a
  * test to stay in lockstep.
  */
-const MEMORY_WORTH_OUTCOME_ELIGIBLE_CATEGORIES: ReadonlySet<MemoryFrontmatter["category"]> =
-  new Set(["fact", "procedure"]);
+const MEMORY_WORTH_OUTCOME_ELIGIBLE_CATEGORIES: ReadonlySet<MemoryFrontmatter["category"]> = new Set([
+  "fact",
+  "procedure",
+]);
 
 /**
  * Exported so downstream tests / operators can query the allowlist without
@@ -170,11 +172,7 @@ export type RecordMemoryOutcomeResult =
     }
   | {
       ok: false;
-      reason:
-        | "not_found"
-        | "ineligible_category"
-        | "invalid_outcome"
-        | "invalid_path";
+      reason: "not_found" | "ineligible_category" | "invalid_outcome" | "invalid_path";
       message: string;
     };
 
@@ -208,7 +206,7 @@ function memoryIdFromPath(memoryPath: string): string | null {
  */
 export async function recordMemoryOutcome(
   storage: StorageManager,
-  input: RecordMemoryOutcomeInput,
+  input: RecordMemoryOutcomeInput
 ): Promise<RecordMemoryOutcomeResult> {
   if (input.outcome !== "success" && input.outcome !== "failure") {
     return {
@@ -288,3 +286,87 @@ export async function recordMemoryOutcome(
     };
   });
 }
+
+// ---------------------------------------------------------------------------
+// Issue #2345 — pure outcome-observation view (no writes, no counter changes)
+// ---------------------------------------------------------------------------
+
+/**
+ * A Memory Worth outcome that carries WHEN it was observed and WHAT it can
+ * join to — the facts the trajectory evaluator needs and plain counter rows
+ * lack. `mw_success` / `mw_fail` totals have no timestamp or join ID, so they
+ * cannot participate in delayed action-to-outcome joins.
+ */
+export interface MemoryOutcomeObservation {
+  schemaVersion: 1;
+  memoryId: string;
+  namespace: string;
+  outcome: MemoryOutcomeKind;
+  observedAt: string;
+  /** Stable join key shared with the action side (never free text). */
+  joinId?: string;
+  sessionKey?: string;
+}
+
+/**
+ * Discriminated view over outcome facts a caller can supply.
+ *
+ * - `missing_observation` — counter-only or incomplete rows. The evaluator
+ *   must never guess the action behind an aggregate counter, so these stay
+ *   visible as missing rather than being inferred.
+ */
+export type MemoryOutcomeObservationView =
+  | { status: "observed"; observation: MemoryOutcomeObservation }
+  | { status: "missing_observation"; memoryId: string; reason: "missing_observed_at" | "missing_join_data" };
+
+const OBSERVATION_ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/**
+ * Build the pure observation view. Accepts exactly what a caller already
+ * knows; performs no storage reads and no writes, and does not alter the
+ * counter path — `recordMemoryOutcome` keeps its current behavior.
+ */
+export function toMemoryOutcomeObservation(raw: {
+  memoryId: string;
+  namespace: string;
+  outcome: MemoryOutcomeKind;
+  observedAt?: unknown;
+  joinId?: unknown;
+  sessionKey?: unknown;
+}): MemoryOutcomeObservationView {
+  if (
+    typeof raw.memoryId !== "string" ||
+    raw.memoryId.length === 0 ||
+    typeof raw.namespace !== "string" ||
+    raw.namespace.length === 0 ||
+    (raw.outcome !== "success" && raw.outcome !== "failure")
+  ) {
+    throw new Error("toMemoryOutcomeObservation requires memoryId, namespace, and outcome");
+  }
+  const observedAt =
+    typeof raw.observedAt === "string" && OBSERVATION_ISO_RE.test(raw.observedAt)
+      ? raw.observedAt
+      : raw.observedAt instanceof Date
+        ? raw.observedAt.toISOString()
+        : null;
+  if (observedAt === null) {
+    return { status: "missing_observation", memoryId: raw.memoryId, reason: "missing_observed_at" };
+  }
+  const joinId = typeof raw.joinId === "string" && raw.joinId.length > 0 ? raw.joinId : undefined;
+  const sessionKey = typeof raw.sessionKey === "string" && raw.sessionKey.length > 0 ? raw.sessionKey : undefined;
+  if (joinId === undefined && sessionKey === undefined) {
+    return { status: "missing_observation", memoryId: raw.memoryId, reason: "missing_join_data" };
+  }
+  return {
+    status: "observed",
+    observation: {
+      schemaVersion: 1,
+      memoryId: raw.memoryId,
+      namespace: raw.namespace,
+      outcome: raw.outcome,
+      observedAt,
+      joinId,
+      sessionKey,
+    },
+  };
+}