feat!: persist T-Bank data and synchronize reads

Store account membership, portfolio, operations, forecasts and market sources in SQLite.
Coalesce scoped refreshes, fence connection revisions, preserve complete financial
snapshots and stabilize operation period state.

BREAKING CHANGE: investment reads return data/meta resource envelopes and locally
persisted snapshots; consumers must use the matching OpenAPI contract and explicit
synchronization endpoints.

src/modules/investments/operations/domain/operations-sync-plan.spec.ts

@@ -0,0 +1,141 @@
+import { operationIntervals, planOperationRead } from './operations-sync-plan';
+
+describe('operations calendar windows', () => {
+  it('merges overlaps before splitting leap February and keeps precise Moscow-derived boundaries', () => {
+    const result = operationIntervals([
+      {
+        accountId: 'a',
+        from: new Date('2024-02-01T00:00:00+03:00'),
+        to: new Date('2024-03-01T00:00:00+03:00'),
+      },
+      {
+        accountId: 'a',
+        from: new Date('2024-02-10Z'),
+        to: new Date('2024-04-01Z'),
+      },
+    ]);
+    expect(
+      result.map(({ from, to }) => [from.toISOString(), to.toISOString()]),
+    ).toEqual([
+      ['2024-01-31T21:00:00.000Z', '2024-02-01T00:00:00.000Z'],
+      ['2024-02-01T00:00:00.000Z', '2024-03-01T00:00:00.000Z'],
+      ['2024-03-01T00:00:00.000Z', '2024-04-01T00:00:00.000Z'],
+    ]);
+  });
+
+  it('does not combine account or instrument predicates and rejects invalid ranges', () => {
+    const range = {
+      from: new Date('2026-12-15Z'),
+      to: new Date('2027-01-15Z'),
+    };
+    const result = operationIntervals([
+      { accountId: 'a', ...range },
+      { accountId: 'b', ...range },
+      { accountId: 'a', instrumentUid: 'uid', ...range },
+    ]);
+    expect(result).toHaveLength(6);
+    expect(() =>
+      operationIntervals([{ accountId: 'a', from: range.to, to: range.from }]),
+    ).toThrow();
+  });
+});
+
+describe('operation completeness and freshness', () => {
+  const from = new Date('2026-09-01Z');
+  const asOf = new Date('2026-09-25T12:00:00Z');
+  const covered = { accountId: 'a', from, to: asOf, asOf, fetchedAt: asOf };
+
+  it.each([1, 299, 300])(
+    'preserves the observed complete end after %s seconds, separately from TTL',
+    (seconds) => {
+      const now = new Date(asOf.valueOf() + seconds * 1000);
+      const plan = planOperationRead(
+        [{ accountId: 'a', from, to: now }],
+        [covered],
+        now,
+        { movingEnd: true },
+      );
+      expect(plan.intervals[0]).toMatchObject({
+        availability: 'complete',
+        asOf,
+        to: asOf,
+        stale: seconds >= 300,
+      });
+      expect(plan.load).toEqual(
+        seconds >= 300 ? [{ accountId: 'a', from, to: now }] : [],
+      );
+    },
+  );
+
+  it('preserves a cursor observed end after the clock and calendar advance', () => {
+    const cursorEnd = new Date(asOf.valueOf() + 1000);
+    const plan = planOperationRead(
+      [{ accountId: 'a', from, to: cursorEnd }],
+      [covered],
+      new Date('2026-10-01Z'),
+      { movingEnd: true },
+    );
+    expect(plan.intervals[0]).toMatchObject({
+      availability: 'complete',
+      to: asOf,
+      asOf,
+    });
+    expect(plan.load).toEqual([]);
+  });
+  it('does not hide earlier holes or reuse an instrument subset as whole-account completeness', () => {
+    const now = new Date(asOf.valueOf() + 1000);
+    const partial = { ...covered, from: new Date('2026-09-10Z') };
+    const plan = planOperationRead(
+      [{ accountId: 'a', from, to: now }],
+      [partial],
+      now,
+      { movingEnd: true },
+    );
+    expect(plan.intervals[0]).toMatchObject({
+      availability: 'partial',
+      stale: false,
+    });
+    expect(plan.load).toEqual([{ accountId: 'a', from, to: partial.from }]);
+    expect(
+      planOperationRead(
+        [{ accountId: 'a', from, to: now }],
+        [{ ...covered, instrumentUid: 'uid' }],
+        now,
+      ).intervals[0].availability,
+    ).toBe('missing');
+  });
+
+  it('loads a newly explicit tail and closes the previous month after rollover', () => {
+    const now = new Date(asOf.valueOf() + 1000);
+    expect(
+      planOperationRead([{ accountId: 'a', from, to: now }], [covered], now)
+        .load,
+    ).toEqual([{ accountId: 'a', from: asOf, to: now }]);
+    const monthEnd = new Date('2026-10-01Z');
+    const rollover = new Date('2026-10-01T00:00:01Z');
+    const plan = planOperationRead(
+      [{ accountId: 'a', from, to: rollover }],
+      [covered],
+      rollover,
+      { movingEnd: true },
+    );
+    expect(plan.load).toEqual([
+      { accountId: 'a', from: asOf, to: monthEnd },
+      { accountId: 'a', from: monthEnd, to: rollover },
+    ]);
+    expect(
+      planOperationRead(
+        [{ accountId: 'a', from, to: monthEnd }],
+        [{ ...covered, to: monthEnd, asOf: monthEnd }],
+        rollover,
+      ).load,
+    ).toEqual([]);
+  });
+
+  it('force refresh reloads only the shown target even when coverage is fresh', () => {
+    const target = { accountId: 'a', from: new Date('2026-09-20Z'), to: asOf };
+    expect(
+      planOperationRead([target], [covered], asOf, { force: true }).load,
+    ).toEqual([target]);
+  });
+});

src/modules/investments/operations/domain/operations-sync-plan.ts

@@ -0,0 +1,183 @@
+export type OperationInterval = {
+  accountId: string;
+  from: Date;
+  to: Date;
+  instrumentUid?: string;
+};
+
+// Normalize duplicate/overlapping targets before creating a durable identity.
+// Calendar windows keep each provider walk bounded without changing [from,to).
+export function operationIntervals(
+  requested: OperationInterval[],
+): OperationInterval[] {
+  const groups = new Map<string, OperationInterval[]>();
+  for (const interval of requested) {
+    if (!(interval.from < interval.to))
+      throw new Error('Invalid operations interval');
+    const key = JSON.stringify([
+      interval.accountId,
+      interval.instrumentUid ?? '',
+    ]);
+    const group = groups.get(key) ?? [];
+    group.push(interval);
+    groups.set(key, group);
+  }
+  const result: OperationInterval[] = [];
+  for (const key of [...groups.keys()].sort()) {
+    const merged: OperationInterval[] = [];
+    for (const interval of (groups.get(key) ?? []).sort(
+      (left, right) => left.from.valueOf() - right.from.valueOf(),
+    )) {
+      const previous = merged.at(-1);
+      if (previous && interval.from <= previous.to)
+        previous.to = new Date(
+          Math.max(previous.to.valueOf(), interval.to.valueOf()),
+        );
+      else merged.push({ ...interval });
+    }
+    for (const interval of merged) {
+      let from = interval.from;
+      while (from < interval.to) {
+        const nextMonth = new Date(
+          Date.UTC(from.getUTCFullYear(), from.getUTCMonth() + 1, 1),
+        );
+        const to = new Date(
+          Math.min(nextMonth.valueOf(), interval.to.valueOf()),
+        );
+        result.push({ ...interval, from, to });
+        from = to;
+      }
+    }
+  }
+  return result;
+}
+
+export function operationIntervalsOverlap(
+  left: OperationInterval,
+  right: OperationInterval,
+): boolean {
+  return (
+    left.accountId === right.accountId &&
+    (!left.instrumentUid ||
+      !right.instrumentUid ||
+      left.instrumentUid === right.instrumentUid) &&
+    left.from < right.to &&
+    right.from < left.to
+  );
+}
+
+export function uncoveredOperationIntervals(
+  requested: OperationInterval[],
+  existing: OperationInterval[],
+): OperationInterval[] {
+  return requested.flatMap((interval) => {
+    let fragments = [interval];
+    for (const covered of existing) {
+      fragments = fragments.flatMap((fragment) => {
+        if (
+          !operationIntervalsOverlap(fragment, covered) ||
+          (covered.instrumentUid &&
+            covered.instrumentUid !== fragment.instrumentUid)
+        )
+          return [fragment];
+        return [
+          ...(fragment.from < covered.from
+            ? [{ ...fragment, to: covered.from }]
+            : []),
+          ...(covered.to < fragment.to
+            ? [{ ...fragment, from: covered.to }]
+            : []),
+        ];
+      });
+    }
+    return fragments;
+  });
+}
+
+export type OperationCoverage = OperationInterval & {
+  fetchedAt: Date;
+  asOf: Date;
+};
+const operationsFreshForMs = 300_000;
+
+export function planOperationRead(
+  requested: OperationInterval[],
+  coverage: OperationCoverage[],
+  now: Date,
+  options: { movingEnd?: boolean; force?: boolean } = {},
+) {
+  const monthStart = new Date(
+    Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1),
+  );
+  const observedEnd = Math.max(
+    ...requested.map((interval) => interval.to.valueOf()),
+  );
+  const load: OperationInterval[] = [];
+  const intervals = operationIntervals(requested).map((target) => {
+    const sources = coverage.filter(
+      (row) =>
+        row.accountId === target.accountId &&
+        (!row.instrumentUid || row.instrumentUid === target.instrumentUid) &&
+        row.from < target.to &&
+        target.from < row.to,
+    );
+    const ranges = sources.map((row) => ({
+      ...row,
+      instrumentUid: target.instrumentUid,
+    }));
+    const current = target.from >= monthStart && target.to <= now;
+    const fresh = sources.filter(
+      (row) => now.valueOf() - row.fetchedAt.valueOf() < operationsFreshForMs,
+    );
+    let effective = target;
+    if (options.movingEnd && target.to.valueOf() === observedEnd) {
+      const latest = sources
+        .filter(
+          (row) =>
+            row.asOf.valueOf() === row.to.valueOf() && row.to > target.from,
+        )
+        .sort((left, right) => right.to.valueOf() - left.to.valueOf())[0];
+      if (latest && latest.to < target.to)
+        effective = { ...target, to: latest.to };
+    }
+    const missing = uncoveredOperationIntervals([effective], ranges);
+    const complete = missing.length === 0;
+    const stale =
+      current &&
+      sources.length > 0 &&
+      uncoveredOperationIntervals(
+        ranges
+          .map((row) => ({
+            ...target,
+            from: new Date(
+              Math.max(effective.from.valueOf(), row.from.valueOf()),
+            ),
+            to: new Date(Math.min(effective.to.valueOf(), row.to.valueOf())),
+          }))
+          .filter((row) => row.from < row.to),
+        fresh.map((row) => ({ ...row, instrumentUid: target.instrumentUid })),
+      ).length > 0;
+    if (options.force) load.push(target);
+    else if (stale) load.push({ ...target, from: monthStart, to: now });
+    else load.push(...missing);
+    // Completeness is bounded by the observed end, never by the new wall clock.
+    return {
+      ...effective,
+      availability: complete
+        ? ('complete' as const)
+        : sources.length
+          ? ('partial' as const)
+          : ('missing' as const),
+      stale,
+      asOf: sources.length
+        ? new Date(
+            Math.min(
+              effective.to.valueOf(),
+              Math.max(...sources.map((row) => row.asOf.valueOf())),
+            ),
+          )
+        : null,
+    };
+  });
+  return { intervals, load: operationIntervals(load) };
+}