@remnic/core 9.63.12 → 9.64.1

package/src/location/registry.ts

@@ -0,0 +1,54 @@
+/**
+ * Location provider registry (issue #2044).
+ *
+ * In-memory only: host adapters register provider implementations at startup.
+ * Core never statically imports an optional provider package — the registry
+ * holds whatever the host wired in, and a configured source whose provider is
+ * not registered is skipped (not an error), so partial installs keep working.
+ */
+
+import type { LocationProvider } from "./types.js";
+
+const PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+const providers = new Map<string, LocationProvider>();
+
+function assertValidProvider(provider: LocationProvider): void {
+  if (typeof provider !== "object" || provider === null) {
+    throw new TypeError("location provider must be an object");
+  }
+  if (typeof provider.id !== "string" || !PROVIDER_ID_PATTERN.test(provider.id)) {
+    throw new RangeError(
+      "location provider id must be a non-empty lowercase kebab string (a-z, 0-9, hyphens)",
+    );
+  }
+  if (typeof provider.displayName !== "string" || provider.displayName.trim().length === 0) {
+    throw new TypeError(`location provider '${provider.id}' must declare a non-empty displayName`);
+  }
+  if (typeof provider.verify !== "function" || typeof provider.fetchObservations !== "function") {
+    throw new TypeError(
+      `location provider '${provider.id}' must implement verify() and fetchObservations()`,
+    );
+  }
+}
+
+export function registerLocationProvider(provider: LocationProvider): void {
+  assertValidProvider(provider);
+  if (providers.has(provider.id)) {
+    throw new Error(`location provider '${provider.id}' is already registered`);
+  }
+  providers.set(provider.id, provider);
+}
+
+export function getLocationProvider(id: string): LocationProvider | undefined {
+  return typeof id === "string" ? providers.get(id) : undefined;
+}
+
+export function listLocationProviders(): string[] {
+  return [...providers.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** Test-only: reset the registry between cases. */
+export function clearLocationProviders(): void {
+  providers.clear();
+}

package/src/location/store.test.ts

@@ -0,0 +1,170 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, symlink, writeFile, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  composeLocationDayBody,
+  composeLocationDayMeta,
+  emptyLocationSyncState,
+  listLocationDayDates,
+  loadLocationSyncState,
+  locationDayFilePath,
+  locationSyncStateFilePath,
+  parseLocationDaySummary,
+  serializeLocationDay,
+  updateLocationSourceDay,
+  writeLocationDay,
+} from "./store.js";
+import type { LocationDaySourceEntry } from "./store.js";
+
+function entry(overrides: Partial<LocationDaySourceEntry> = {}): LocationDaySourceEntry {
+  return {
+    observationCount: 1,
+    segments: [
+      {
+        startUtc: "2026-08-17T09:00:00.000Z",
+        endUtc: "2026-08-17T09:30:00.000Z",
+        place: { id: "home", label: "Home" },
+      },
+    ],
+    ...overrides,
+  };
+}
+
+test("day rendering is deterministic across source-map insertion order", () => {
+  const a: Record<string, LocationDaySourceEntry> = {
+    reitti: entry({ providerDisplayName: "Reitti" }),
+    other: entry({
+      providerDisplayName: "Other",
+      observationCount: 0,
+      segments: [],
+    }),
+  };
+  const b: Record<string, LocationDaySourceEntry> = {
+    other: entry({ providerDisplayName: "Other", observationCount: 0, segments: [] }),
+    reitti: entry({ providerDisplayName: "Reitti" }),
+  };
+  const render = (sources: Record<string, LocationDaySourceEntry>) => {
+    const body = composeLocationDayBody("2026-08-17", "UTC", sources);
+    return serializeLocationDay(composeLocationDayMeta("2026-08-17", "UTC", sources, body), body);
+  };
+  const first = render(a);
+  const second = render(b);
+  assert.equal(first, second, "identical content renders byte-identical regardless of key order");
+  const reparsed = parseLocationDaySummary(first);
+  assert.deepEqual(reparsed, {
+    date: "2026-08-17",
+    timezone: "UTC",
+    sources: ["other", "reitti"],
+    observationCount: 1,
+    contentHash: parseLocationDaySummary(second)!.contentHash,
+  });
+  assert.equal(parseLocationDaySummary("# not a location day\n"), null);
+});
+
+test("writeLocationDay is idempotent and read-back verifies content", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-store-"));
+  try {
+    const body = composeLocationDayBody("2026-08-17", "UTC", { reitti: entry() });
+    const serialized = serializeLocationDay(
+      composeLocationDayMeta("2026-08-17", "UTC", { reitti: entry() }, body),
+      body,
+    );
+    assert.equal(await writeLocationDay(memoryDir, "2026-08-17", serialized), true);
+    assert.equal(await writeLocationDay(memoryDir, "2026-08-17", serialized), false, "unchanged content rewrites nothing");
+    assert.equal(await readFile(locationDayFilePath(memoryDir, "2026-08-17"), "utf-8"), serialized);
+    assert.deepEqual(await listLocationDayDates(memoryDir), ["2026-08-17"]);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("locationDayFilePath rejects traversal-shaped dates", () => {
+  assert.throws(() => locationDayFilePath("/tmp/x", "../../etc/passwd"), RangeError);
+  assert.throws(() => locationDayFilePath("/tmp/x", "2026-13-01"), RangeError);
+});
+
+test("store rejects a symlinked locations directory even when it resolves inside memoryDir", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-location-symlink-"));
+  try {
+    const memoryDir = path.join(root, "memory");
+    const target = path.join(root, "elsewhere");
+    await mkdir(memoryDir, { recursive: true });
+    await mkdir(target, { recursive: true });
+    await symlink(target, path.join(memoryDir, "locations"));
+    await assert.rejects(
+      () => writeLocationDay(memoryDir, "2026-08-17", "---\nkind: location-day\n"),
+      /symlink/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("store rejects a symlinked day file that escapes the memory dir", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-location-symlinkfile-"));
+  try {
+    const memoryDir = path.join(root, "memory");
+    await mkdir(path.join(memoryDir, "locations"), { recursive: true });
+    await writeFile(path.join(root, "secret.md"), "outside", "utf-8");
+    await symlink(path.join(root, "secret.md"), path.join(memoryDir, "locations", "2026-08-17.md"));
+    await assert.rejects(
+      () => writeLocationDay(memoryDir, "2026-08-17", "---\nkind: location-day\n"),
+      /outside the memory dir|symbolic link/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("sync state cold-starts on absence and corrupt JSON, then persists atomically", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-state-"));
+  try {
+    assert.deepEqual(await loadLocationSyncState(memoryDir), emptyLocationSyncState());
+    await mkdir(path.dirname(locationSyncStateFilePath(memoryDir)), { recursive: true });
+    await writeFile(locationSyncStateFilePath(memoryDir), "{not json", "utf-8");
+    assert.deepEqual(await loadLocationSyncState(memoryDir), emptyLocationSyncState());
+    await updateLocationSourceDay(memoryDir, "reitti", "2026-08-17", entry(), "2026-08-18T00:00:05.000Z");
+    const state = await loadLocationSyncState(memoryDir);
+    assert.equal(state.sources.reitti?.lastSyncedAtUtc, "2026-08-18T00:00:05.000Z");
+    assert.equal(state.sources.reitti?.days?.["2026-08-17"]?.observationCount, 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("concurrent source state updates do not lose each other", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-concurrent-"));
+  try {
+    await Promise.all([
+      updateLocationSourceDay(memoryDir, "reitti", "2026-08-17", entry(), "2026-08-18T00:00:01.000Z"),
+      updateLocationSourceDay(memoryDir, "other", "2026-08-17", entry({ observationCount: 2 }), "2026-08-18T00:00:02.000Z"),
+      updateLocationSourceDay(memoryDir, "third", "2026-08-16", entry(), "2026-08-18T00:00:03.000Z"),
+    ]);
+    const state = await loadLocationSyncState(memoryDir);
+    assert.deepEqual(Object.keys(state.sources).sort(), ["other", "reitti", "third"]);
+    assert.equal(state.sources.reitti?.days?.["2026-08-17"]?.observationCount, 1);
+    assert.equal(state.sources.other?.days?.["2026-08-17"]?.observationCount, 2);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("day payloads prune beyond the retention cap, newest kept", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-location-prune-"));
+  try {
+    for (let day = 0; day < 95; day += 1) {
+      const date = new Date(Date.UTC(2026, 5, 1) + day * 86_400_000).toISOString().slice(0, 10);
+      await updateLocationSourceDay(memoryDir, "reitti", date, entry(), "2026-09-01T00:00:00.000Z");
+    }
+    const state = await loadLocationSyncState(memoryDir);
+    const days = Object.keys(state.sources.reitti?.days ?? {});
+    assert.equal(days.length, 90);
+    assert.equal(days.includes("2026-06-01"), false, "oldest days pruned");
+    assert.equal(days.includes("2026-06-06"), true, "newest 90 days kept");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/location/store.ts

@@ -0,0 +1,478 @@
+/**
+ * Location day-file + sync-state store (issue #2044).
+ *
+ * Day documents live at `<memoryDir>/locations/<YYYY-MM-DD>.md` — OUTSIDE the
+ * memory scan roots (facts/, entities/, …) so raw location history never
+ * surfaces as a memory in recall or governance passes, and INSIDE the QMD
+ * collection root so the markdown stays full-text searchable once an index
+ * update runs. Per-source sync state lives at
+ * `<memoryDir>/state/locations/sync.json` and is written only after the day
+ * document is durable (see pipeline.ts).
+ *
+ * Both writes are atomic (temp file + rename) and containment-checked: a
+ * symlinked `locations/` root or day file is rejected even when it resolves
+ * inside the memory dir (AGENTS.md pattern #3), and a path that escapes the
+ * memory dir is refused outright.
+ */
+
+import { createHash } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { pathIsInside } from "../utils/path-containment.js";
+import { isValidLocationDate, placeDurations } from "./intervals.js";
+import type { LocationSegment } from "./types.js";
+
+export const LOCATIONS_DIR_NAME = "locations";
+export const LOCATION_DAY_KIND = "location-day";
+export const LOCATION_DAY_FORMAT_VERSION = 1;
+
+/** Cap on remembered day payloads per source (~3 months of days). */
+const MAX_TRACKED_LOCATION_DAYS = 90;
+
+const DAY_FILE_NAME_PATTERN = /^\d{4}-\d{2}-\d{2}\.md$/;
+
+// Serializes state load→mutate→save sections per state file so two sources
+// syncing concurrently cannot lose-update each other's entries.
+const stateLocks = new Map<string, Promise<unknown>>();
+
+function withStateLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const prior = stateLocks.get(key) ?? Promise.resolve();
+  const next = prior.then(fn, fn);
+  const tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  stateLocks.set(key, tail);
+  void tail.then(() => {
+    if (stateLocks.get(key) === tail) stateLocks.delete(key);
+  });
+  return next;
+}
+
+export function locationDayFilePath(memoryDir: string, date: string): string {
+  if (!isValidLocationDate(date)) {
+    // Never interpolate an unvalidated date into a filesystem path (a `../`
+    // would escape <memoryDir>/locations/). Reject loudly.
+    throw new RangeError(`Invalid location date "${date}"; expected a real YYYY-MM-DD day.`);
+  }
+  return path.join(memoryDir, LOCATIONS_DIR_NAME, `${date}.md`);
+}
+
+export function locationSyncStateFilePath(memoryDir: string): string {
+  return path.join(memoryDir, "state", "locations", "sync.json");
+}
+
+/** A source's derived day payload, kept in sync state for multi-source merges. */
+export interface LocationSourceDayPayload {
+  observationCount: number;
+  segments: LocationSegment[];
+  providerDisplayName?: string;
+}
+
+export interface LocationSourceSyncState {
+  lastSyncedAtUtc?: string;
+  days?: Record<string, LocationSourceDayPayload>;
+}
+
+export interface LocationSyncStateFile {
+  version: 1;
+  sources: Record<string, LocationSourceSyncState>;
+}
+
+export function emptyLocationSyncState(): LocationSyncStateFile {
+  return { version: 1, sources: {} };
+}
+
+export async function loadLocationSyncState(memoryDir: string): Promise<LocationSyncStateFile> {
+  let raw: string;
+  try {
+    raw = await readFile(locationSyncStateFilePath(memoryDir), "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return emptyLocationSyncState();
+    throw err;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // A corrupt state file must not brick syncing forever; treat it as a cold
+    // start. The worst case is re-syncing days already on disk, and the day
+    // file's contentHash makes that rewrite idempotent.
+    return emptyLocationSyncState();
+  }
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    Array.isArray(parsed) ||
+    typeof (parsed as LocationSyncStateFile).sources !== "object" ||
+    (parsed as LocationSyncStateFile).sources === null
+  ) {
+    return emptyLocationSyncState();
+  }
+  return { version: 1, sources: (parsed as LocationSyncStateFile).sources };
+}
+
+export async function saveLocationSyncState(
+  memoryDir: string,
+  state: LocationSyncStateFile,
+): Promise<void> {
+  await mkdir(path.dirname(locationSyncStateFilePath(memoryDir)), { recursive: true, mode: 0o700 });
+  await writeFileAtomically(
+    locationSyncStateFilePath(memoryDir),
+    `${JSON.stringify(state, null, 2)}\n`,
+  );
+}
+
+function pruneSourceDays(source: LocationSourceSyncState): void {
+  const days = source.days;
+  if (days === undefined) return;
+  const keys = Object.keys(days).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  for (const key of keys.slice(0, Math.max(0, keys.length - MAX_TRACKED_LOCATION_DAYS))) {
+    delete days[key];
+  }
+}
+
+/**
+ * Record one source's completed day sync. Runs the whole read-modify-write
+ * under the per-directory state lock so concurrent sources cannot clobber
+ * each other, and prunes day payloads beyond the retention cap.
+ */
+export async function updateLocationSourceDay(
+  memoryDir: string,
+  sourceId: string,
+  date: string,
+  payload: LocationSourceDayPayload,
+  completedAtUtc: string,
+): Promise<LocationSyncStateFile> {
+  if (!isValidLocationDate(date)) {
+    throw new RangeError(`Invalid location date "${date}"; expected a real YYYY-MM-DD day.`);
+  }
+  return withStateLock(locationSyncStateFilePath(memoryDir), async () => {
+    const state = await loadLocationSyncState(memoryDir);
+    const source = state.sources[sourceId] ?? {};
+    const days = source.days ?? {};
+    days[date] = payload;
+    source.days = days;
+    source.lastSyncedAtUtc = completedAtUtc;
+    state.sources[sourceId] = source;
+    for (const candidate of Object.values(state.sources)) pruneSourceDays(candidate);
+    await saveLocationSyncState(memoryDir, state);
+    return state;
+  });
+}
+/** Frontmatter persisted on a rendered day document. */
+export interface LocationDayMeta {
+  kind: typeof LOCATION_DAY_KIND;
+  date: string;
+  timezone: string;
+  formatVersion: number;
+  sources: string[];
+  observationCount: number;
+  /** SHA-256 of the rendered body (rebuild idempotency). */
+  contentHash: string;
+}
+
+/** A parsed day document (frontmatter + rendered body). */
+export interface LocationDayDocument {
+  meta: LocationDayMeta;
+  body: string;
+}
+
+/** The per-source view a day document is composed from. */
+export interface LocationDaySourceEntry extends LocationSourceDayPayload {
+  /** Provider display name for the timeline heading; falls back to the id. */
+  providerDisplayName?: string;
+}
+
+export function hashLocationBody(body: string): string {
+  return createHash("sha256").update(body, "utf8").digest("hex");
+}
+
+function clockHhMm(iso: string, timezone: string): string {
+  return new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(new Date(iso));
+}
+
+function formatDuration(ms: number): string {
+  const totalMinutes = Math.round(ms / 60_000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours <= 0) return `${minutes}m`;
+  return `${hours}h ${String(minutes).padStart(2, "0")}m`;
+}
+
+/** Collapse whitespace and strip markdown emphasis/backticks from a label. */
+function safeLabel(label: string): string {
+  return label.replace(/\s+/g, " ").replace(/[`*_]/g, "").trim();
+}
+
+function formatPlaceLabel(segment: LocationSegment): string {
+  const label = safeLabel(segment.place.label);
+  return segment.place.kind === undefined ? label : `${label} (${segment.place.kind})`;
+}
+
+function formatCoordinates(segment: LocationSegment): string {
+  if (segment.place.latitude === undefined || segment.place.longitude === undefined) return "";
+  return ` @ ${segment.place.latitude.toFixed(4)},${segment.place.longitude.toFixed(4)}`;
+}
+
+export function composeLocationDayBody(
+  date: string,
+  timezone: string,
+  sources: Record<string, LocationDaySourceEntry>,
+): string {
+  const lines: string[] = [`# Location day — ${date} (${timezone})`, ""];
+  const allSegments: LocationSegment[] = [];
+  let observationCount = 0;
+  for (const entry of Object.values(sources)) {
+    allSegments.push(...entry.segments);
+    observationCount += entry.observationCount;
+  }
+
+  lines.push("## Summary", "");
+  if (observationCount === 0) {
+    lines.push("No location observations recorded.", "");
+  } else {
+    const durations = placeDurations(allSegments).sort((a, b) => b.totalMs - a.totalMs);
+    lines.push(
+      `- Places visited: ${durations.length}`,
+      ...durations.map(
+        (duration) => `- ${safeLabel(duration.place.label)}: ${formatDuration(duration.totalMs)}`,
+      ),
+      "",
+    );
+  }
+
+  const sourceIds = Object.keys(sources).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  for (const sourceId of sourceIds) {
+    const entry = sources[sourceId]!;
+    lines.push(`## Timeline — ${safeLabel(entry.providerDisplayName ?? sourceId)}`, "");
+    if (entry.segments.length === 0) {
+      lines.push("No observations.", "");
+      continue;
+    }
+    for (const segment of entry.segments) {
+      lines.push(
+        `- ${clockHhMm(segment.startUtc, timezone)}–${clockHhMm(segment.endUtc, timezone)} — ${formatPlaceLabel(segment)}${formatCoordinates(segment)}`,
+      );
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+export function composeLocationDayMeta(
+  date: string,
+  timezone: string,
+  sources: Record<string, LocationDaySourceEntry>,
+  body: string,
+): LocationDayMeta {
+  let observationCount = 0;
+  for (const entry of Object.values(sources)) observationCount += entry.observationCount;
+  return {
+    kind: LOCATION_DAY_KIND,
+    date,
+    timezone,
+    formatVersion: LOCATION_DAY_FORMAT_VERSION,
+    sources: Object.keys(sources).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
+    observationCount,
+    contentHash: hashLocationBody(body),
+  };
+}
+
+function frontmatterScalar(key: string, value: string | number): string {
+  return `${key}: ${typeof value === "number" ? value : JSON.stringify(value)}`;
+}
+
+function frontmatterList(key: string, values: readonly string[]): string[] {
+  if (values.length === 0) return [`${key}: []`];
+  const lines = [`${key}:`];
+  for (const value of values) lines.push(`  - ${JSON.stringify(value)}`);
+  return lines;
+}
+
+export function serializeLocationDay(meta: LocationDayMeta, body: string): string {
+  const lines: string[] = ["---"];
+  lines.push(frontmatterScalar("kind", meta.kind));
+  lines.push(frontmatterScalar("date", meta.date));
+  lines.push(frontmatterScalar("timezone", meta.timezone));
+  lines.push(frontmatterScalar("formatVersion", meta.formatVersion));
+  lines.push(...frontmatterList("sources", meta.sources));
+  lines.push(frontmatterScalar("observationCount", meta.observationCount));
+  lines.push(frontmatterScalar("contentHash", meta.contentHash));
+  lines.push("---", "", body);
+  return lines.join("\n");
+}
+
+function parseScalar(raw: string): string {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "string" ? parsed : raw;
+  } catch {
+    return raw;
+  }
+}
+
+/** A day document's frontmatter, parsed for idempotency checks and status. */
+export interface LocationDaySummary {
+  date: string;
+  timezone: string;
+  sources: string[];
+  observationCount: number;
+  contentHash: string;
+}
+
+/**
+ * Parse a day document's frontmatter. Returns null when the content is not a
+ * location day document (wrong kind, missing frontmatter) so callers can
+ * distinguish a foreign file from a corrupt one.
+ */
+export function parseLocationDaySummary(raw: string): LocationDaySummary | null {
+  if (!raw.startsWith("---\n")) return null;
+  const closeIndex = raw.indexOf("\n---\n", 4);
+  if (closeIndex === -1) return null;
+  const scalars: Record<string, string> = {};
+  const lists: Record<string, string[]> = {};
+  let currentList: string | null = null;
+  for (const line of raw.slice(4, closeIndex).split("\n")) {
+    const listItem = /^ {2}- (.*)$/.exec(line);
+    if (listItem !== null && currentList !== null) {
+      lists[currentList]!.push(parseScalar(listItem[1]!));
+      continue;
+    }
+    currentList = null;
+    const separator = line.indexOf(":");
+    if (separator === -1) continue;
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1).trim();
+    if (value === "" || value === "[]") {
+      lists[key] = [];
+      currentList = key;
+      continue;
+    }
+    if (value.startsWith("[")) {
+      lists[key] = [parseScalar(value)];
+      currentList = key;
+      continue;
+    }
+    scalars[key] = value;
+  }
+  if (scalars.kind === undefined || parseScalar(scalars.kind) !== LOCATION_DAY_KIND) return null;
+  if (scalars.date === undefined || scalars.contentHash === undefined) return null;
+  return {
+    date: parseScalar(scalars.date),
+    timezone: scalars.timezone === undefined ? "UTC" : parseScalar(scalars.timezone),
+    sources: lists.sources ?? [],
+    observationCount: scalars.observationCount === undefined ? 0 : Number(scalars.observationCount) || 0,
+    contentHash: parseScalar(scalars.contentHash),
+  };
+}
+
+// ── Containment-checked day-file IO ─────────────────────────────────────────
+
+function isErrnoCode(err: unknown, code: string): boolean {
+  return err instanceof Error && (err as NodeJS.ErrnoException).code === code;
+}
+
+async function assertNotSymlink(target: string, kind: "directory" | "day file"): Promise<void> {
+  let stat: { isSymbolicLink(): boolean };
+  try {
+    stat = await lstat(target);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return;
+    throw err;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(
+      `locations ${kind} '${path.basename(target)}' is a symbolic link — refusing to follow it even when it resolves inside the memory dir (AGENTS.md pattern #3)`,
+    );
+  }
+}
+
+async function assertNoEscape(rootReal: string, candidate: string): Promise<void> {
+  let candidateReal: string;
+  try {
+    candidateReal = await realpath(candidate);
+  } catch {
+    return;
+  }
+  if (!pathIsInside(rootReal, candidateReal)) {
+    throw new Error(
+      "location day path resolves outside the memory dir — refusing to follow a symlink/traversal (AGENTS.md pattern #3)",
+    );
+  }
+}
+
+async function assertDayPathContained(memoryDir: string, targetPath: string): Promise<void> {
+  let rootReal: string;
+  try {
+    rootReal = await realpath(memoryDir);
+  } catch {
+    rootReal = path.resolve(memoryDir);
+  }
+  const locationsDir = path.join(memoryDir, LOCATIONS_DIR_NAME);
+  await assertNoEscape(rootReal, locationsDir);
+  await assertNoEscape(rootReal, targetPath);
+  // Reject a symlinked locations root or day file outright — even when the
+  // link resolves inside the memory dir (aliasing / tampering) — before IO.
+  await assertNotSymlink(locationsDir, "directory");
+  await assertNotSymlink(targetPath, "day file");
+}
+
+/**
+ * Idempotently persist a day document: skip the write when the on-disk
+ * contentHash already matches. The write is atomic and containment-checked;
+ * the caller (pipeline) advances sync state only after this resolves.
+ */
+export async function writeLocationDay(
+  memoryDir: string,
+  date: string,
+  serialized: string,
+): Promise<boolean> {
+  const target = locationDayFilePath(memoryDir, date);
+  await assertDayPathContained(memoryDir, target);
+  try {
+    if ((await readFile(target, "utf-8")) === serialized) return false;
+  } catch (err) {
+    if (!isErrnoCode(err, "ENOENT")) throw err;
+  }
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await writeFileAtomically(target, serialized);
+  return true;
+}
+
+/** Read a stored day document's raw markdown; null when absent. */
+export async function readLocationDay(memoryDir: string, date: string): Promise<string | null> {
+  const target = locationDayFilePath(memoryDir, date);
+  await assertDayPathContained(memoryDir, target);
+  try {
+    return await readFile(target, "utf-8");
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return null;
+    throw err;
+  }
+}
+
+/** List dates that have a stored day document, newest first. */
+export async function listLocationDayDates(memoryDir: string): Promise<string[]> {
+  const locationsDir = path.join(memoryDir, LOCATIONS_DIR_NAME);
+  await assertDayPathContained(memoryDir, locationsDir);
+  let entries: string[];
+  try {
+    entries = await readdir(locationsDir);
+  } catch (err) {
+    if (isErrnoCode(err, "ENOENT")) return [];
+    throw err;
+  }
+  const dates = entries
+    .filter((entry) => DAY_FILE_NAME_PATTERN.test(entry))
+    .map((entry) => entry.slice(0, -3));
+  dates.sort((a, b) => (a > b ? -1 : a < b ? 1 : 0));
+  return dates;
+}