@remnic/core 9.67.0 → 9.68.0

package/src/activity/privacy-delete-plan.test.ts

@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MS_PER_DAY } from "./privacy.js";
+import {
+  ACTIVITY_DELETE_SCOPES,
+  planActivityDeletion,
+  type ActivityDeleteCandidate,
+} from "./privacy-delete-plan.js";
+
+const NOW = 100 * MS_PER_DAY;
+
+function cand(
+  scope: string,
+  relPath: string,
+  capturedAtMs: number,
+): ActivityDeleteCandidate {
+  return { scope, relPath, capturedAtMs };
+}
+
+function plan(
+  candidates: readonly ActivityDeleteCandidate[],
+  overrides: Partial<Parameters<typeof planActivityDeletion>[0]> = {},
+) {
+  return planActivityDeletion({
+    candidates,
+    scopes: ACTIVITY_DELETE_SCOPES,
+    retentionDays: 30,
+    nowMs: NOW,
+    ...overrides,
+  });
+}
+
+test("expired in-scope activity paths are planned across every owned root", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([
+    cand("observations", "activity/2026-01-01.md", expired),
+    cand("cards", "wearables/limitless/2026-01-01.md", expired),
+    cand("journal", "meetings/2026-01-01/mtg-x.md", expired),
+  ]);
+  assert.deepEqual(result.deletePaths, [
+    "activity/2026-01-01.md",
+    "meetings/2026-01-01/mtg-x.md",
+    "wearables/limitless/2026-01-01.md",
+  ]);
+  assert.equal(result.keptCount, 0);
+  assert.deepEqual(result.refused, []);
+});
+
+test("fresh in-scope candidates are kept, not deleted", () => {
+  const result = plan([cand("observations", "activity/2026-08-19.md", NOW - MS_PER_DAY)]);
+  assert.deepEqual(result.deletePaths, []);
+  assert.equal(result.keptCount, 1);
+  assert.deepEqual(result.refused, []);
+});
+
+test("retentionDays 0 deletes nothing but counts kept", () => {
+  const ancient = NOW - 4000 * MS_PER_DAY;
+  const result = plan([cand("weekly", "activity/2015-01-01.md", ancient)], {
+    retentionDays: 0,
+  });
+  assert.deepEqual(result.deletePaths, []);
+  assert.equal(result.keptCount, 1);
+});
+
+test("facts paths are refused even when expired and in scope", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([cand("observations", "facts/2026-01-01/fact-1.md", expired)]);
+  assert.deepEqual(result.deletePaths, []);
+  assert.deepEqual(result.refused, ["facts/2026-01-01/fact-1.md"]);
+  assert.equal(result.keptCount, 0);
+});
+
+test("profile.md, entities, and state files are refused", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([
+    cand("journal", "profile.md", expired),
+    cand("journal", "entities/person-a.md", expired),
+    cand("providerCache", "state/buffer.json", expired),
+  ]);
+  assert.deepEqual(result.deletePaths, []);
+  assert.deepEqual(result.refused, ["entities/person-a.md", "profile.md", "state/buffer.json"]);
+});
+
+test("absolute, traversal, and blank paths are refused", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([
+    cand("observations", "/etc/passwd", expired),
+    cand("observations", "activity/../../facts/fact-1.md", expired),
+    cand("observations", "   ", expired),
+  ]);
+  assert.deepEqual(result.deletePaths, []);
+  assert.deepEqual(result.refused, [
+    "   ",
+    "/etc/passwd",
+    "activity/../../facts/fact-1.md",
+  ]);
+});
+
+test("unknown candidate scope is refused", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([cand("bogus", "activity/2026-01-01.md", expired)]);
+  assert.deepEqual(result.deletePaths, []);
+  assert.deepEqual(result.refused, ["activity/2026-01-01.md"]);
+  assert.equal(result.keptCount, 0);
+});
+
+test("scope absent from scopes is skipped entirely", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([cand("cards", "activity/2026-01-01.md", expired)], {
+    scopes: ["observations"],
+  });
+  assert.deepEqual(result.deletePaths, []);
+  assert.deepEqual(result.refused, []);
+  assert.equal(result.keptCount, 0);
+});
+
+test("unknown value in scopes throws RangeError", () => {
+  assert.throws(
+    () => plan([], { scopes: ["observations", "everything"] }),
+    (error: unknown) => error instanceof RangeError && /scope/.test(error.message),
+  );
+});
+
+test("negative or float retentionDays throws RangeError", () => {
+  assert.throws(
+    () => plan([], { retentionDays: -1 }),
+    (error: unknown) => error instanceof RangeError && /retentionDays/.test(error.message),
+  );
+  assert.throws(
+    () => plan([], { retentionDays: 2.5 }),
+    (error: unknown) => error instanceof RangeError && /retentionDays/.test(error.message),
+  );
+});
+
+test("non-finite nowMs throws RangeError", () => {
+  assert.throws(
+    () => plan([], { nowMs: Number.POSITIVE_INFINITY }),
+    (error: unknown) => error instanceof RangeError && /nowMs/.test(error.message),
+  );
+  assert.throws(
+    () => plan([], { nowMs: Number.NaN }),
+    (error: unknown) => error instanceof RangeError && /nowMs/.test(error.message),
+  );
+});
+
+test("deletePaths and refused are sorted and deduplicated", () => {
+  const expired = NOW - 40 * MS_PER_DAY;
+  const result = plan([
+    cand("observations", "activity/b.md", expired),
+    cand("cards", "activity/a.md", expired),
+    cand("journal", "activity/b.md", expired),
+    cand("observations", "facts/z.md", expired),
+    cand("cards", "facts/z.md", expired),
+  ]);
+  assert.deepEqual(result.deletePaths, ["activity/a.md", "activity/b.md"]);
+  assert.deepEqual(result.refused, ["facts/z.md"]);
+});
+
+test("half-open boundary: age exactly retentionDays * MS_PER_DAY is deleted", () => {
+  const boundary = NOW - 30 * MS_PER_DAY;
+  const result = plan([
+    cand("observations", "activity/boundary.md", boundary),
+    cand("observations", "activity/inside.md", boundary + 1),
+  ]);
+  assert.deepEqual(result.deletePaths, ["activity/boundary.md"]);
+  assert.equal(result.keptCount, 1);
+});
+
+test("input candidates are not mutated", () => {
+  const candidates = [
+    cand("observations", "activity/2026-01-01.md", NOW - 40 * MS_PER_DAY),
+    cand("observations", "facts/2026-01-01/fact-1.md", NOW - 40 * MS_PER_DAY),
+  ];
+  const snapshot = structuredClone(candidates);
+  plan(candidates);
+  assert.deepEqual(candidates, snapshot);
+});
+
+// Review round 1: the planner trimmed relPath before validating it, so
+// " activity/x.md" validated as owned and the plan then targeted
+// "activity/x.md" — a path the caller never supplied.
+test("a path with surrounding whitespace is refused, not normalized into a delete", () => {
+  const expired = 0;
+  for (const relPath of [" activity/day.md", "activity/day.md ", "\tactivity/day.md"]) {
+    const plan = planActivityDeletion({
+      candidates: [{ scope: "cards", relPath, capturedAtMs: expired }],
+      scopes: ["cards"],
+      retentionDays: 1,
+      nowMs: 10 * 86_400_000,
+    });
+    assert.deepEqual(plan.deletePaths, [], `${JSON.stringify(relPath)} must not be planned`);
+    assert.deepEqual(plan.refused, [relPath], "the exact candidate path is reported as refused");
+  }
+});
+
+// Review round 1: every comparison against NaN is false, so shouldRetain
+// reported "not retained" and a corrupt timestamp resolved toward deletion.
+test("a non-finite capturedAtMs is refused instead of deleted", () => {
+  for (const capturedAtMs of [Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
+    const plan = planActivityDeletion({
+      candidates: [{ scope: "cards", relPath: "activity/corrupt.md", capturedAtMs }],
+      scopes: ["cards"],
+      retentionDays: 1,
+      nowMs: 10 * 86_400_000,
+    });
+    assert.deepEqual(
+      plan.deletePaths,
+      [],
+      `capturedAtMs ${String(capturedAtMs)} must never resolve toward deletion`,
+    );
+    assert.deepEqual(plan.refused, ["activity/corrupt.md"]);
+    assert.equal(plan.keptCount, 0);
+  }
+});

package/src/activity/privacy-delete-plan.ts

@@ -0,0 +1,116 @@
+/**
+ * Activity retention deletion planner (issue #2053).
+ *
+ * Pure: decides what a retention pass may delete. Never performs I/O.
+ * Safety rule: a path outside the activity-owned roots is refused, never
+ * planned for deletion, so unrelated Remnic memories survive.
+ */
+import { shouldRetain } from "./privacy.js";
+
+export const ACTIVITY_DELETE_SCOPES = [
+  "observations",
+  "cards",
+  "journal",
+  "weekly",
+  "providerCache",
+] as const;
+export type ActivityDeleteScope = (typeof ACTIVITY_DELETE_SCOPES)[number];
+
+const KNOWN_SCOPES: readonly string[] = ACTIVITY_DELETE_SCOPES;
+
+/** Deletion only ever touches these memory-dir-relative roots. */
+const OWNED_ROOTS: readonly string[] = ["activity", "wearables", "meetings"];
+
+export interface ActivityDeleteCandidate {
+  /** Which activity artifact family this item belongs to. */
+  scope: string;
+  /** Memory-dir-relative path, POSIX separators. */
+  relPath: string;
+  capturedAtMs: number;
+}
+
+export interface ActivityDeletePlan {
+  deletePaths: string[];
+  keptCount: number;
+  /** Candidates refused because they are not activity-owned paths. */
+  refused: string[];
+}
+
+function isRefusablePath(relPath: unknown): boolean {
+  if (typeof relPath !== "string") return true;
+  if (relPath.trim() === "") return true;
+  // Validate the EXACT candidate path. Trimming first would let
+  // " activity/x.md" validate as owned and then plan a delete for
+  // "activity/x.md" — a path the caller never supplied. Surrounding
+  // whitespace means this is not a clean owned path: refuse it.
+  if (relPath !== relPath.trim()) return true;
+  if (relPath.startsWith("/")) return true;
+  const segments = relPath.split("/");
+  if (segments.includes("..")) return true;
+  const [root = "", ...rest] = segments;
+  return (
+    rest.length === 0 ||
+    !OWNED_ROOTS.includes(root) ||
+    rest.some((segment) => segment.length === 0)
+  );
+}
+
+function sortedUnique(paths: Iterable<string>): string[] {
+  return [...new Set(paths)].sort();
+}
+
+export function planActivityDeletion(input: {
+  candidates: readonly ActivityDeleteCandidate[];
+  scopes: readonly string[];
+  retentionDays: number;
+  nowMs: number;
+}): ActivityDeletePlan {
+  const { candidates, scopes, retentionDays, nowMs } = input;
+
+  for (const scope of scopes) {
+    if (!KNOWN_SCOPES.includes(scope)) {
+      throw new RangeError(`unknown activity delete scope: ${scope}`);
+    }
+  }
+  if (!Number.isInteger(retentionDays) || retentionDays < 0) {
+    throw new RangeError("retentionDays must be a non-negative integer");
+  }
+  if (!Number.isFinite(nowMs)) {
+    throw new RangeError("nowMs must be a finite number");
+  }
+
+  const selectedScopes = new Set(scopes);
+  const deletePaths: string[] = [];
+  const refused: string[] = [];
+  let keptCount = 0;
+
+  for (const candidate of candidates) {
+    if (!KNOWN_SCOPES.includes(candidate.scope)) {
+      refused.push(String(candidate.relPath));
+      continue;
+    }
+    if (!selectedScopes.has(candidate.scope)) continue;
+    if (isRefusablePath(candidate.relPath)) {
+      refused.push(String(candidate.relPath));
+      continue;
+    }
+    // A corrupt timestamp must never resolve toward deletion: every
+    // comparison against NaN is false, which shouldRetain reads as
+    // "not retained". Refuse the candidate instead.
+    if (typeof candidate.capturedAtMs !== "number" || !Number.isFinite(candidate.capturedAtMs)) {
+      refused.push(candidate.relPath);
+      continue;
+    }
+    if (shouldRetain(candidate.capturedAtMs, nowMs, retentionDays, true)) {
+      keptCount += 1;
+      continue;
+    }
+    deletePaths.push(candidate.relPath);
+  }
+
+  return {
+    deletePaths: sortedUnique(deletePaths),
+    keptCount,
+    refused: sortedUnique(refused),
+  };
+}

package/src/activity/timeline/index.ts

@@ -22,3 +22,4 @@ export * from "./analysis-claim.js";
 export * from "./analysis-order.js";
 export * from "./recap-window.js";
 export * from "./analysis-failure.js";
+export * from "./recap-merge-edits.js";

package/src/activity/timeline/recap-merge-edits.test.ts

@@ -0,0 +1,181 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mergeRecapUserEdits,
+  type RecapSection,
+} from "./recap-merge-edits.js";
+
+test("edited section survives regeneration", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "hand edit" }],
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "hand edit" }]);
+  assert.deepEqual(result.preserved, ["highlights"]);
+  assert.deepEqual(result.regenerated, []);
+});
+
+test("reset discards every edit", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "hand edit" }],
+    reset: true,
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "new body" }]);
+  assert.deepEqual(result.preserved, []);
+  assert.deepEqual(result.regenerated, ["highlights"]);
+});
+
+test("edited-only section is kept and counted preserved", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [
+      { key: "highlights", body: "hand edit" },
+      { key: "zeta", body: "user section" },
+      { key: "alpha", body: "another user section" },
+    ],
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights", "alpha", "zeta"],
+  );
+  assert.deepEqual(result.preserved, ["highlights", "alpha", "zeta"]);
+  assert.deepEqual(result.regenerated, []);
+  const alpha = result.sections.find((s) => s.key === "alpha");
+  assert.equal(alpha?.body, "another user section");
+});
+
+test("edited-only section is dropped on reset", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "zeta", body: "user section" }],
+    reset: true,
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights"],
+  );
+  assert.deepEqual(result.preserved, []);
+});
+
+test("generated-only section is included and counted regenerated", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "new body" },
+      { key: "notes", body: "generated notes" },
+    ],
+    edited: [{ key: "highlights", body: "hand edit" }],
+  });
+  const notes = result.sections.find((s) => s.key === "notes");
+  assert.equal(notes?.body, "generated notes");
+  assert.deepEqual(result.regenerated, ["notes"]);
+});
+
+test("whitespace-only edit falls back to generated body", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "highlights", body: "  \n\t " }],
+  });
+  assert.deepEqual(result.sections, [{ key: "highlights", body: "new body" }]);
+  assert.deepEqual(result.preserved, []);
+  assert.deepEqual(result.regenerated, ["highlights"]);
+});
+
+test("whitespace-only edited-only key is dropped entirely", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "new body" }],
+    edited: [{ key: "zeta", body: "   " }],
+  });
+  assert.deepEqual(
+    result.sections.map((s) => s.key),
+    ["highlights"],
+  );
+  assert.deepEqual(result.preserved, []);
+});
+
+test("duplicate keys keep the first occurrence", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "first generated" },
+      { key: "highlights", body: "second generated" },
+    ],
+    edited: [
+      { key: "highlights", body: "first edit" },
+      { key: "highlights", body: "second edit" },
+    ],
+  });
+  assert.deepEqual(result.sections, [
+    { key: "highlights", body: "first edit" },
+  ]);
+});
+
+test("duplicate edited-only keys keep the first occurrence", () => {
+  const result = mergeRecapUserEdits({
+    generated: [{ key: "highlights", body: "gen" }],
+    edited: [
+      { key: "zeta", body: "first user section" },
+      { key: "zeta", body: "second user section" },
+    ],
+  });
+  const zeta = result.sections.find((s) => s.key === "zeta");
+  assert.equal(zeta?.body, "first user section");
+  assert.equal(result.sections.filter((s) => s.key === "zeta").length, 1);
+});
+
+test("output is deterministic across two calls on the same input", () => {
+  const input = {
+    generated: [
+      { key: "notes", body: "generated notes" },
+      { key: "highlights", body: "new body" },
+    ],
+    edited: [
+      { key: "zeta", body: "user section" },
+      { key: "highlights", body: "hand edit" },
+      { key: "alpha", body: "another user section" },
+    ],
+  };
+  const first = mergeRecapUserEdits(input);
+  const second = mergeRecapUserEdits(input);
+  assert.deepEqual(first, second);
+  assert.deepEqual(
+    first.sections.map((s) => s.key),
+    ["notes", "highlights", "alpha", "zeta"],
+  );
+});
+
+test("preserved and regenerated are disjoint and cover every output key", () => {
+  const result = mergeRecapUserEdits({
+    generated: [
+      { key: "highlights", body: "new body" },
+      { key: "notes", body: "generated notes" },
+    ],
+    edited: [
+      { key: "highlights", body: "hand edit" },
+      { key: "zeta", body: "user section" },
+    ],
+  });
+  const outputKeys = result.sections.map((s) => s.key).sort();
+  const accounted = [...result.preserved, ...result.regenerated].sort();
+  assert.deepEqual(accounted, outputKeys);
+  for (const key of result.preserved) {
+    assert.equal(result.regenerated.includes(key), false);
+  }
+});
+
+test("inputs are not mutated", () => {
+  const generated: RecapSection[] = [
+    { key: "highlights", body: "new body" },
+    { key: "notes", body: "generated notes" },
+  ];
+  const edited: RecapSection[] = [
+    { key: "highlights", body: "hand edit" },
+    { key: "zeta", body: "user section" },
+  ];
+  const generatedSnapshot = structuredClone(generated);
+  const editedSnapshot = structuredClone(edited);
+  mergeRecapUserEdits({ generated, edited, reset: false });
+  mergeRecapUserEdits({ generated, edited, reset: true });
+  assert.deepEqual(generated, generatedSnapshot);
+  assert.deepEqual(edited, editedSnapshot);
+});

package/src/activity/timeline/recap-merge-edits.ts

@@ -0,0 +1,70 @@
+/**
+ * Merge user hand-edits into a regenerated journal recap (issue #2051).
+ *
+ * Rule: user edits survive regeneration; an explicit reset is the only
+ * way to discard them. Pure — no I/O, no clock, no randomness.
+ */
+
+export interface RecapSection {
+  /** Stable section key, e.g. "highlights". */
+  key: string;
+  body: string;
+}
+
+export type MergeRecapEditsResult = {
+  sections: RecapSection[];
+  /** Section keys whose user edit was kept over the regenerated body. */
+  preserved: string[];
+  /** Section keys taken from the regenerated recap. */
+  regenerated: string[];
+};
+
+function dedupeByFirst(list: readonly RecapSection[]): RecapSection[] {
+  const seen = new Set<string>();
+  const out: RecapSection[] = [];
+  for (const section of list) {
+    if (seen.has(section.key)) continue;
+    seen.add(section.key);
+    out.push(section);
+  }
+  return out;
+}
+
+export function mergeRecapUserEdits(input: {
+  generated: readonly RecapSection[];
+  edited?: readonly RecapSection[];
+  reset?: boolean;
+}): MergeRecapEditsResult {
+  const generated = dedupeByFirst(input.generated);
+  const edited = dedupeByFirst(input.edited ?? []);
+  const editedByKey = new Map(edited.map((s) => [s.key, s]));
+
+  const sections: RecapSection[] = [];
+  const preserved: string[] = [];
+  const regenerated: string[] = [];
+
+  for (const gen of generated) {
+    const edit = editedByKey.get(gen.key);
+    if (!input.reset && edit !== undefined && edit.body.trim() !== "") {
+      sections.push({ key: gen.key, body: edit.body });
+      preserved.push(gen.key);
+    } else {
+      sections.push({ key: gen.key, body: gen.body });
+      regenerated.push(gen.key);
+    }
+  }
+
+  if (!input.reset) {
+    const generatedKeys = new Set(generated.map((s) => s.key));
+    const editedOnly = edited
+      .filter((s) => !generatedKeys.has(s.key))
+      .filter((s) => s.body.trim() !== "")
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    for (const edit of editedOnly) {
+      sections.push({ key: edit.key, body: edit.body });
+      preserved.push(edit.key);
+    }
+  }
+
+  return { sections, preserved, regenerated };
+}