@remnic/core 9.69.0 → 9.69.1

package/src/activity/timeline/week-recurring.test.ts

@@ -0,0 +1,177 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_RECURRENCE_MIN_DAYS,
+  MIN_RECURRENCE_MIN_DAYS,
+  findRecurringPatterns,
+  type WeekDayOccurrence,
+} from "./week-recurring.js";
+
+function rangeErrorMatching(pattern: RegExp): (err: unknown) => boolean {
+  return (err: unknown) => err instanceof RangeError && pattern.test((err as Error).message);
+}
+
+test("default minDays is 3; a key on exactly minDays distinct dates qualifies", () => {
+  assert.equal(DEFAULT_RECURRENCE_MIN_DAYS, 3);
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-11", key: "code", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 300 }]);
+});
+
+test("a key on minDays - 1 distinct dates does not qualify", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 999_999 },
+      { date: "2026-08-11", key: "code", durationMs: 999_999 },
+    ],
+  });
+  assert.deepEqual(result, []);
+});
+
+test("same-date occurrences count as one day but all durations sum", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-10", key: "code", durationMs: 40 },
+      { date: "2026-08-11", key: "code", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 340 }]);
+});
+
+test("blank keys are ignored", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "", durationMs: 100 },
+      { date: "2026-08-11", key: "   ", durationMs: 100 },
+      { date: "2026-08-12", key: "\t", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, []);
+});
+
+test("keys are compared trimmed and case-sensitively", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-11", key: " code ", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+      { date: "2026-08-10", key: "Code", durationMs: 100 },
+      { date: "2026-08-11", key: "Code", durationMs: 100 },
+    ],
+  });
+  // " code " folds into "code" (3 distinct days); "Code" stays separate at 2 days.
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 300 }]);
+});
+
+test("minDays must be an integer >= MIN_RECURRENCE_MIN_DAYS", () => {
+  for (const bad of [0, 1, -3, 1.5]) {
+    assert.throws(
+      () => findRecurringPatterns({ occurrences: [], minDays: bad }),
+      rangeErrorMatching(/minDays/),
+    );
+  }
+  assert.doesNotThrow(() =>
+    findRecurringPatterns({
+      occurrences: [{ date: "2026-08-10", key: "code", durationMs: 1 }],
+      minDays: MIN_RECURRENCE_MIN_DAYS,
+    }),
+  );
+});
+
+// minDays 1 would make a single-day key "recurring", which is the invariant
+// this helper exists to enforce — configuration must not be able to disable it.
+test("minDays 1 is refused rather than reporting one-off keys", () => {
+  assert.throws(
+    () =>
+      findRecurringPatterns({
+        occurrences: [{ date: "2026-08-10", key: "code", durationMs: 5 }],
+        minDays: 1,
+      }),
+    rangeErrorMatching(/minDays/),
+  );
+  assert.equal(MIN_RECURRENCE_MIN_DAYS, 2);
+});
+
+test("durationMs must be a finite number >= 0", () => {
+  for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, -1]) {
+    assert.throws(
+      () =>
+        findRecurringPatterns({
+          occurrences: [{ date: "2026-08-10", key: "code", durationMs: bad }],
+        }),
+      rangeErrorMatching(/durationMs/),
+    );
+  }
+});
+
+test("date must be a valid YYYY-MM-DD calendar date", () => {
+  for (const bad of ["", "not-a-date", "2026-8-10", "2026-02-30"]) {
+    assert.throws(
+      () =>
+        findRecurringPatterns({
+          occurrences: [{ date: bad, key: "code", durationMs: 0 }],
+        }),
+      rangeErrorMatching(/date/),
+    );
+  }
+});
+
+test("ordering: dayCount desc, then totalDurationMs desc, then key asc", () => {
+  const result = findRecurringPatterns({
+    minDays: 2,
+    occurrences: [
+      // alpha: 2 days, biggest total — dayCount still ranks it last.
+      { date: "2026-08-10", key: "alpha", durationMs: 999_999 },
+      { date: "2026-08-11", key: "alpha", durationMs: 999_999 },
+      // beta: 3 days, 10 total — wins the dayCount tie on duration.
+      { date: "2026-08-10", key: "beta", durationMs: 4 },
+      { date: "2026-08-11", key: "beta", durationMs: 4 },
+      { date: "2026-08-12", key: "beta", durationMs: 2 },
+      // gamma: 3 days, 8 total — ties delta on both, loses on key ascending.
+      { date: "2026-08-10", key: "gamma", durationMs: 8 },
+      { date: "2026-08-11", key: "gamma", durationMs: 0 },
+      { date: "2026-08-12", key: "gamma", durationMs: 0 },
+      // delta: 3 days, 8 total.
+      { date: "2026-08-10", key: "delta", durationMs: 8 },
+      { date: "2026-08-11", key: "delta", durationMs: 0 },
+      { date: "2026-08-12", key: "delta", durationMs: 0 },
+    ],
+  });
+  assert.deepEqual(result.map((p) => p.key), ["beta", "delta", "gamma", "alpha"]);
+  assert.deepEqual(result[0], { key: "beta", dayCount: 3, totalDurationMs: 10 });
+  assert.deepEqual(result[3], { key: "alpha", dayCount: 2, totalDurationMs: 1_999_998 });
+});
+
+test("empty input and no-qualifier input return []", () => {
+  assert.deepEqual(findRecurringPatterns({ occurrences: [] }), []);
+  assert.deepEqual(
+    findRecurringPatterns({
+      occurrences: [{ date: "2026-08-10", key: "code", durationMs: 5000 }],
+    }),
+    [],
+  );
+});
+
+test("pure: two calls deep-equal and the input is not mutated", () => {
+  const occurrences: WeekDayOccurrence[] = [
+    { date: "2026-08-10", key: "code", durationMs: 100 },
+    { date: "2026-08-10", key: "code", durationMs: 50 },
+    { date: "2026-08-11", key: "mail", durationMs: 10 },
+    { date: "2026-08-11", key: "code", durationMs: 100 },
+    { date: "2026-08-12", key: "code", durationMs: 100 },
+  ];
+  const snapshot = structuredClone(occurrences);
+  const first = findRecurringPatterns({ occurrences });
+  const second = findRecurringPatterns({ occurrences });
+  assert.deepEqual(first, second);
+  assert.deepEqual(first, [{ key: "code", dayCount: 3, totalDurationMs: 350 }]);
+  assert.deepEqual(occurrences, snapshot);
+});

package/src/activity/timeline/week-recurring.ts

@@ -0,0 +1,88 @@
+/**
+ * Recurring weekly pattern gate (issue #2052).
+ *
+ * A category/application key counts as recurring only when it appeared on at
+ * least `minDays` DISTINCT days of the analyzed week, so a one-off blip is
+ * never reported as a pattern. Pure: no I/O, no clock, no input mutation.
+ * Validation happens on the exact occurrence values before any key trimming
+ * (AGENTS.md: validate before normalizing; reject non-finite numbers
+ * explicitly instead of letting NaN fall through a comparison).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+export const DEFAULT_RECURRENCE_MIN_DAYS = 3;
+
+/** Lowest threshold that still means "recurring": two distinct days. */
+export const MIN_RECURRENCE_MIN_DAYS = 2;
+
+export interface WeekDayOccurrence {
+  /** YYYY-MM-DD inside the analyzed week. */
+  date: string;
+  /** Category id or application/domain label. */
+  key: string;
+  durationMs: number;
+}
+
+export interface RecurringPattern {
+  key: string;
+  /** Count of DISTINCT days the key appeared on. */
+  dayCount: number;
+  totalDurationMs: number;
+}
+
+export function findRecurringPatterns(input: {
+  occurrences: readonly WeekDayOccurrence[];
+  minDays?: number;
+}): RecurringPattern[] {
+  const minDays = input.minDays ?? DEFAULT_RECURRENCE_MIN_DAYS;
+  // A floor of 2 is the module's defining invariant, not a preference: at
+  // minDays 1 every key that appeared once is "recurring", which is exactly
+  // the one-off blip this helper exists to exclude. Configuration must not be
+  // able to switch the invariant off.
+  if (!Number.isInteger(minDays) || minDays < MIN_RECURRENCE_MIN_DAYS) {
+    throw new RangeError(
+      `Invalid minDays ${minDays}; expected an integer >= ${MIN_RECURRENCE_MIN_DAYS}.`,
+    );
+  }
+
+  const daysByKey = new Map<string, Set<string>>();
+  const totalsByKey = new Map<string, number>();
+
+  for (const occurrence of input.occurrences) {
+    if (!isValidActivityDate(occurrence.date)) {
+      throw new RangeError(`Invalid date "${occurrence.date}"; expected YYYY-MM-DD.`);
+    }
+    if (
+      typeof occurrence.durationMs !== "number" ||
+      !Number.isFinite(occurrence.durationMs) ||
+      occurrence.durationMs < 0
+    ) {
+      throw new RangeError(`Invalid durationMs ${occurrence.durationMs}; expected a finite number >= 0.`);
+    }
+    const key = occurrence.key.trim();
+    if (key === "") continue;
+    let days = daysByKey.get(key);
+    if (!days) {
+      days = new Set<string>();
+      daysByKey.set(key, days);
+      totalsByKey.set(key, 0);
+    }
+    days.add(occurrence.date);
+    totalsByKey.set(key, totalsByKey.get(key)! + occurrence.durationMs);
+  }
+
+  const patterns: RecurringPattern[] = [];
+  for (const [key, days] of daysByKey) {
+    if (days.size < minDays) continue;
+    patterns.push({ key, dayCount: days.size, totalDurationMs: totalsByKey.get(key)! });
+  }
+
+  patterns.sort((a, b) => {
+    if (a.dayCount !== b.dayCount) return b.dayCount - a.dayCount;
+    if (a.totalDurationMs !== b.totalDurationMs) return b.totalDurationMs - a.totalDurationMs;
+    if (a.key < b.key) return -1;
+    if (a.key > b.key) return 1;
+    return 0;
+  });
+  return patterns;
+}

package/src/dedup/index.ts

@@ -474,3 +474,10 @@ export {
   type MergeJudgeVerdictName,
   type ParseMergeVerdictResult,
 } from "./merge-verdict.js";
+
+export {
+  MERGE_DERIVED_VIA,
+  buildMergeFrontmatterUpdate,
+  type MergeFrontmatterUpdate,
+  type MergeProvenanceSource,
+} from "./merge-provenance.js";

package/src/dedup/merge-provenance.test.ts

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  buildMergeFrontmatterUpdate,
+  MERGE_DERIVED_VIA,
+  type MergeProvenanceSource,
+} from "./merge-provenance.js";
+
+const NOW = "2026-08-19T12:00:00.000Z";
+
+function source(overrides: Partial<MergeProvenanceSource> = {}): MergeProvenanceSource {
+  return {
+    sessionKey: "project/demo/1",
+    observedAt: "2026-08-18T09:00:00.000Z",
+    quote: "the API limit is 100/min",
+    ...overrides,
+  };
+}
+
+test("appends incoming sources after target sources in order", () => {
+  const a = source({ quote: "first" });
+  const b = source({ quote: "second" });
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [a],
+    incomingSources: [b],
+    nowIso: NOW,
+  });
+  assert.deepEqual(
+    update.sources.map((s) => s.quote),
+    ["first", "second"],
+  );
+});
+
+test("uses the serializer's allow-listed operator, not an invented one", () => {
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW });
+  assert.equal(update.derived_via, "merge");
+  assert.equal(MERGE_DERIVED_VIA, "merge");
+});
+
+test("preserves every canonical optional field on an accepted source", () => {
+  const full = source({ turnId: "turn-7", charStart: 4, charEnd: 12 });
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [full], nowIso: NOW });
+  assert.deepEqual(update.sources, [
+    {
+      sessionKey: full.sessionKey,
+      observedAt: full.observedAt,
+      quote: full.quote,
+      turnId: "turn-7",
+      charStart: 4,
+      charEnd: 12,
+    },
+  ]);
+});
+
+test("accepts a source with no turnId, which the canonical shape allows", () => {
+  const update = buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW });
+  assert.equal(update.sources.length, 1);
+  assert.equal("turnId" in update.sources[0]!, false);
+});
+
+test("deduplicates on the full field tuple and keeps the first", () => {
+  const first = source({ turnId: "turn-1" });
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [first],
+    incomingSources: [{ ...first }, source({ turnId: "turn-2" })],
+    nowIso: NOW,
+  });
+  assert.deepEqual(
+    update.sources.map((s) => s.turnId),
+    ["turn-1", "turn-2"],
+  );
+});
+
+test("sources differing only in offsets are both kept", () => {
+  const update = buildMergeFrontmatterUpdate({
+    incomingSources: [source({ charStart: 0, charEnd: 5 }), source({ charStart: 6, charEnd: 9 })],
+    nowIso: NOW,
+  });
+  assert.equal(update.sources.length, 2);
+});
+
+test("a blank sessionKey or quote is rejected", () => {
+  for (const bad of [source({ sessionKey: "  " }), source({ quote: "" })]) {
+    assert.throws(() => buildMergeFrontmatterUpdate({ incomingSources: [bad], nowIso: NOW }), /non-blank/);
+  }
+});
+
+test("a missing or malformed observedAt is rejected", () => {
+  for (const bad of ["", "2026-08-18", "not-a-date", undefined as unknown as string]) {
+    assert.throws(
+      () => buildMergeFrontmatterUpdate({ incomingSources: [source({ observedAt: bad })], nowIso: NOW }),
+      /observedAt/,
+    );
+  }
+});
+
+test("a blank turnId is rejected while an absent one is fine", () => {
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ turnId: " " })], nowIso: NOW }),
+    /turnId/,
+  );
+});
+
+test("negative, non-integer, and inverted offsets are rejected", () => {
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ charStart: -1 })], nowIso: NOW }),
+    /charStart/,
+  );
+  assert.throws(
+    () => buildMergeFrontmatterUpdate({ incomingSources: [source({ charEnd: 1.5 })], nowIso: NOW }),
+    /charEnd/,
+  );
+  assert.throws(
+    () =>
+      buildMergeFrontmatterUpdate({
+        incomingSources: [source({ charStart: 9, charEnd: 2 })],
+        nowIso: NOW,
+      }),
+    /charEnd must be >= charStart/,
+  );
+});
+
+test("reinforcement_count starts at 1 and increments from the target", () => {
+  assert.equal(
+    buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: NOW }).reinforcement_count,
+    1,
+  );
+  assert.equal(
+    buildMergeFrontmatterUpdate({
+      incomingSources: [source()],
+      targetReinforcementCount: 2,
+      nowIso: NOW,
+    }).reinforcement_count,
+    3,
+  );
+});
+
+test("an invalid target reinforcement_count is rejected", () => {
+  for (const bad of [-1, 1.5, Number.NaN, "2" as unknown as number]) {
+    assert.throws(
+      () =>
+        buildMergeFrontmatterUpdate({
+          incomingSources: [source()],
+          targetReinforcementCount: bad,
+          nowIso: NOW,
+        }),
+      /reinforcement_count/,
+    );
+  }
+});
+
+// Date.parse alone accepts "123" and rolls 2026-02-30 into March; the value is
+// echoed verbatim into frontmatter, so the full ISO shape is required.
+test("nowIso must be a full ISO instant with a real calendar date", () => {
+  for (const bad of ["", "   ", "123", "2026-01-01", "2026-02-30T00:00:00Z", "nope"]) {
+    assert.throws(
+      () => buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: bad }),
+      /nowIso/,
+    );
+  }
+  assert.equal(
+    buildMergeFrontmatterUpdate({ incomingSources: [source()], nowIso: "2026-08-19T12:00:00+02:00" }).updated,
+    "2026-08-19T12:00:00+02:00",
+  );
+});
+
+test("empty incomingSources still bumps the counter and preserves target sources", () => {
+  const update = buildMergeFrontmatterUpdate({
+    targetSources: [source()],
+    incomingSources: [],
+    targetReinforcementCount: 1,
+    nowIso: NOW,
+  });
+  assert.equal(update.sources.length, 1);
+  assert.equal(update.reinforcement_count, 2);
+});
+
+test("inputs are not mutated", () => {
+  const target = [source({ turnId: "t" })];
+  const incoming = [source({ quote: "other" })];
+  const snapshot = JSON.stringify({ target, incoming });
+  buildMergeFrontmatterUpdate({ targetSources: target, incomingSources: incoming, nowIso: NOW });
+  assert.equal(JSON.stringify({ target, incoming }), snapshot);
+});

package/src/dedup/merge-provenance.ts

@@ -0,0 +1,151 @@
+/**
+ * Merge frontmatter builder (issue #2330).
+ *
+ * On a create-or-update merge the target keeps its own provenance and gains
+ * the incoming fact's, so a merge can never erase where a claim came from.
+ *
+ * Fields here match the canonical schema in `types.ts` deliberately: the
+ * serializer rejects a `derived_via` outside its allow-list and drops keys
+ * `MemoryFrontmatter` does not define, so an invented operator name or
+ * counter would vanish on write. Pure — no I/O, no clock.
+ */
+
+/** The serializer's allow-listed operator for a create-or-update merge. */
+export const MERGE_DERIVED_VIA = "merge" as const;
+
+/**
+ * Structural mirror of `ProvenanceSource` (types.ts). `sessionKey`,
+ * `observedAt`, and `quote` are required; `turnId` and the character
+ * offsets are optional and MUST survive a merge untouched.
+ */
+export interface MergeProvenanceSource {
+  sessionKey: string;
+  observedAt: string;
+  quote: string;
+  turnId?: string;
+  charStart?: number;
+  charEnd?: number;
+}
+
+export interface MergeFrontmatterUpdate {
+  updated: string;
+  derived_via: typeof MERGE_DERIVED_VIA;
+  /** Follows the `reinforcement_count` convention; the serializer requires > 0. */
+  reinforcement_count: number;
+  sources: MergeProvenanceSource[];
+}
+
+const ISO_TIMESTAMP =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Require a full ISO 8601 instant whose calendar components round-trip.
+ * `Date.parse` alone accepts `123` and rolls `2026-02-30` over into March,
+ * and this value is echoed verbatim into frontmatter.
+ */
+function assertIsoInstant(value: unknown, field: string): string {
+  if (typeof value !== "string" || !ISO_TIMESTAMP.test(value)) {
+    throw new RangeError(`${field} must be a full ISO 8601 instant, got ${JSON.stringify(value)}`);
+  }
+  const ms = Date.parse(value);
+  if (Number.isNaN(ms)) {
+    throw new RangeError(`${field} must be a full ISO 8601 instant, got ${JSON.stringify(value)}`);
+  }
+  // Reject a rolled-over calendar date (2026-02-30 -> 2026-03-02).
+  if (!new Date(ms).toISOString().startsWith(value.slice(0, 10))) {
+    throw new RangeError(`${field} is not a real calendar date: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+function assertOffset(value: unknown, field: string): void {
+  if (value === undefined) return;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new RangeError(`${field} must be a non-negative integer when present, got ${String(value)}`);
+  }
+}
+
+function normalizeSource(source: MergeProvenanceSource, index: number): MergeProvenanceSource {
+  const label = `sources[${index}]`;
+  for (const field of ["sessionKey", "quote"] as const) {
+    const value = source[field];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new RangeError(`${label}.${field} must be a non-blank string`);
+    }
+  }
+  assertIsoInstant(source.observedAt, `${label}.observedAt`);
+  if (source.turnId !== undefined && (typeof source.turnId !== "string" || source.turnId.trim() === "")) {
+    throw new RangeError(`${label}.turnId must be a non-blank string when present`);
+  }
+  assertOffset(source.charStart, `${label}.charStart`);
+  assertOffset(source.charEnd, `${label}.charEnd`);
+  if (source.charStart !== undefined && source.charEnd !== undefined && source.charEnd < source.charStart) {
+    throw new RangeError(`${label}.charEnd must be >= charStart`);
+  }
+  // Copy every canonical field, including the optional ones: dropping
+  // observedAt or the offsets here would make the serializer discard the
+  // clone, turning "append provenance" into "erase provenance".
+  const copy: MergeProvenanceSource = {
+    sessionKey: source.sessionKey,
+    observedAt: source.observedAt,
+    quote: source.quote,
+  };
+  if (source.turnId !== undefined) copy.turnId = source.turnId;
+  if (source.charStart !== undefined) copy.charStart = source.charStart;
+  if (source.charEnd !== undefined) copy.charEnd = source.charEnd;
+  return copy;
+}
+
+function sourceKey(source: MergeProvenanceSource): string {
+  return JSON.stringify([
+    source.sessionKey,
+    source.turnId ?? null,
+    source.observedAt,
+    source.quote,
+    source.charStart ?? null,
+    source.charEnd ?? null,
+  ]);
+}
+
+export function buildMergeFrontmatterUpdate(input: {
+  /** Existing sources already on the merge target. */
+  targetSources?: readonly MergeProvenanceSource[];
+  /** Sources from the incoming fact being merged in. */
+  incomingSources: readonly MergeProvenanceSource[];
+  /** Existing reinforcement_count on the target, if any. */
+  targetReinforcementCount?: number;
+  nowIso: string;
+}): MergeFrontmatterUpdate {
+  const updated = assertIsoInstant(input.nowIso, "nowIso");
+
+  const previous = input.targetReinforcementCount;
+  if (
+    previous !== undefined &&
+    (typeof previous !== "number" || !Number.isInteger(previous) || previous < 0)
+  ) {
+    throw new RangeError(
+      `reinforcement_count must be a non-negative integer when supplied, got ${String(previous)}`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const sources: MergeProvenanceSource[] = [];
+  const append = (source: MergeProvenanceSource, index: number): void => {
+    const copy = normalizeSource(source, index);
+    const key = sourceKey(copy);
+    if (seen.has(key)) return;
+    seen.add(key);
+    sources.push(copy);
+  };
+
+  const target = input.targetSources ?? [];
+  target.forEach(append);
+  input.incomingSources.forEach((source, i) => append(source, target.length + i));
+
+  return {
+    updated,
+    derived_via: MERGE_DERIVED_VIA,
+    reinforcement_count: (previous ?? 0) + 1,
+    sources,
+  };
+}