ci: validate release PR commits independently (WealthLedger/main#30 )

chore(release): 2.1.0
2026-10-12 23:39:30 +03:00 · 2026-10-12 23:19:12 +03:00
25 changed files with 418 additions and 448 deletions
@@ -34,7 +34,11 @@ jobs:
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          printf '%s\n' "$PR_TITLE" | npm run commitlint -- --strict
-          npm run commitlint -- --strict --from "$BASE_SHA" --to "$HEAD_SHA"
+          if [[ "$PR_TITLE" =~ ^chore\(release\):\ [0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            npm run commitlint -- --strict --from "$HEAD_SHA^" --to "$HEAD_SHA"
+          else
+            npm run commitlint -- --strict --from "$BASE_SHA" --to "$HEAD_SHA"
+          fi

  security:
    needs: commits
@@ -1,5 +1,43 @@
 # Changelog

+## [2.1.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v2.0.0...v2.1.0) (2026-10-12)
+
+### Features
+
+* add hourly portfolio sync history ([0057925](https://git.personal.ksv741.ru/WealthLedger/backend/commit/0057925888dde874830149865fc5e13920ac5783))
+* add stock screener ([7d10ef8](https://git.personal.ksv741.ru/WealthLedger/backend/commit/7d10ef8adfce76ad2ed6368e1022fbd3f6847a23))
+* reconcile hourly investment resource states ([323b83b](https://git.personal.ksv741.ru/WealthLedger/backend/commit/323b83b5827d1191fbc14cfdf1d0e62f249fc78d))
+
+### Bug Fixes
+
+* align backend workflow rules (WealthLedger/main[#27](https://git.personal.ksv741.ru/WealthLedger/backend/issues/27)) ([c7d0600](https://git.personal.ksv741.ru/WealthLedger/backend/commit/c7d060023b612af9e1dd4c2a2fb2d5d1bf173784))
+* bound hourly step awaits by the per-step wait limit ([#56](https://git.personal.ksv741.ru/WealthLedger/backend/issues/56)) ([52fa3a3](https://git.personal.ksv741.ru/WealthLedger/backend/commit/52fa3a36baa5ab236a7ebd64ef1b4f447c91e129))
+* keep candle retries read-only ([947ffef](https://git.personal.ksv741.ru/WealthLedger/backend/commit/947ffefa9b8cad7f19355c187f2bd50c9739a822))
+* restore terminal hourly lifecycle after persistence failure ([#56](https://git.personal.ksv741.ru/WealthLedger/backend/issues/56)) ([fa57a20](https://git.personal.ksv741.ru/WealthLedger/backend/commit/fa57a201fdd8127774aee9af553da75a75add07c))
+* unblock backend dependency audit ([85858a1](https://git.personal.ksv741.ru/WealthLedger/backend/commit/85858a160f00dd428c80b8fa1824c1779245fdfe))
+
+### Documentation
+
+* clarify backend verification policy ([d7895f2](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d7895f287ee802e7b13df7a2a4c6dba0b711e5a9))
+* pin backend workflow reference (WealthLedger/main[#27](https://git.personal.ksv741.ru/WealthLedger/backend/issues/27)) ([c5248db](https://git.personal.ksv741.ru/WealthLedger/backend/commit/c5248dbefc4b11a9f417bc835041a4294bd61047))
+
+### CI
+
+* skip checks on PR metadata edits ([0ad84ff](https://git.personal.ksv741.ru/WealthLedger/backend/commit/0ad84ff4f0b4712abc7e69dc299856f14af6eadd))
+
+### Tests
+
+* align all accounts metadata ([db375cb](https://git.personal.ksv741.ru/WealthLedger/backend/commit/db375cbee7d8f1eff48822b8e3c74898f40e8886))
+* align resource availability metadata ([bc631e7](https://git.personal.ksv741.ru/WealthLedger/backend/commit/bc631e72de0d9b0ff7b261b1ea644a73c2943d2a))
+* align upcoming events with local reads ([966b2a5](https://git.personal.ksv741.ru/WealthLedger/backend/commit/966b2a5836cdaf5b761e3c76568ff30a90ba1f4c))
+* extend ledger sqlite timeout ([4870d49](https://git.personal.ksv741.ru/WealthLedger/backend/commit/4870d4950303ad1de743e19b665b2fbdc05b781a))
+* increase ledger request timeout ([2facd86](https://git.personal.ksv741.ru/WealthLedger/backend/commit/2facd8675c74a97d92e0e8f44ed4a93aabb47674))
+
+### Maintenance
+
+* align backend engineering workflow (WealthLedger/main[#27](https://git.personal.ksv741.ru/WealthLedger/backend/issues/27)) ([a31e8d2](https://git.personal.ksv741.ru/WealthLedger/backend/commit/a31e8d2c4d85a21cdd5efdcc9f5fe503f210804b))
+* prune obsolete eslint suppressions ([a46a411](https://git.personal.ksv741.ru/WealthLedger/backend/commit/a46a4112cbcc72b1c3ff17cac4ac8bebcf579bca))
+
 ## [2.0.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v1.0.0...v2.0.0) (2026-10-07)

 ### ⚠ BREAKING CHANGES
@@ -248,9 +248,8 @@ breaking changes относительно предыдущего выпуска.
 настраивается отдельно. История migrations применяется штатным `migrate deploy`.

 Регрессия самого запуска: `node test/sqlite-regression.cjs`. Она выполняет
-три последовательных и два параллельных запуска двух обычных e2e suites,
-проверяет уникальность DB, сохранность вымышленного внешнего файла, отказ migration
-и SIGINT/SIGTERM cleanup. Полный e2e набор остаётся в `npm run test:e2e`.
+три последовательных и два параллельных полных e2e, проверяет уникальность DB,
+сохранность вымышленного внешнего файла, отказ migration и SIGINT/SIGTERM cleanup.
 Логи остаются в каталоге из вывода. Для одной suite:
 `node test/sqlite.cjs app.e2e-spec.ts`.

@@ -1,12 +1,12 @@
 {
  "name": "wealth-ledger-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "wealth-ledger-backend",
-      "version": "2.0.0",
+      "version": "2.1.0",
      "license": "UNLICENSED",
      "dependencies": {
        "@grpc/grpc-js": "1.14.5",
@@ -21,7 +21,7 @@
        "@prisma/adapter-better-sqlite3": "7.10.0",
        "@prisma/client": "7.10.0",
        "bcrypt": "6.0.0",
-        "better-sqlite3": "12.11.1",
+        "better-sqlite3": "13.0.3",
        "cheerio": "1.2.0",
        "class-transformer": "0.5.1",
        "class-validator": "0.15.1",
@@ -3769,6 +3769,20 @@
        "better-sqlite3": "^12.6.0"
      }
    },
+    "node_modules/@prisma/adapter-better-sqlite3/node_modules/better-sqlite3": {
+      "version": "12.11.1",
+      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.11.1.tgz",
+      "integrity": "sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "bindings": "^1.5.0",
+        "prebuild-install": "^7.1.1"
+      },
+      "engines": {
+        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
+      }
+    },
    "node_modules/@prisma/client": {
      "version": "7.10.0",
      "resolved": "https://registry.npmjs.org/@prisma/client/-/client-7.10.0.tgz",
@@ -6268,17 +6282,15 @@
      "license": "MIT"
    },
    "node_modules/better-sqlite3": {
-      "version": "12.11.1",
-      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.11.1.tgz",
-      "integrity": "sha512-dq9AtApgg5PGFtBzPFSBl3HZQjHok5gaQCM6zh2Yk0aSmDCs1CbnVI8/HgASQkNKsWFpseIO9beg5xxpYhbIfA==",
-      "hasInstallScript": true,
+      "version": "13.0.3",
+      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.3.tgz",
+      "integrity": "sha512-RbOBxmLBG8uvFUc15X9+9SFemKcQ0WBuISBVkpuiaUB2qblC8UWlHEjdWVoZ8AdhSwmoEgsiXKfopX0CQxaACQ==",
      "license": "MIT",
      "dependencies": {
-        "bindings": "^1.5.0",
-        "prebuild-install": "^7.1.1"
+        "node-addon-api": "^8.0.0"
      },
      "engines": {
-        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
+        "node": ">=22"
      }
    },
    "node_modules/bindings": {
@@ -1,6 +1,6 @@
 {
  "name": "wealth-ledger-backend",
-  "version": "2.0.0",
+  "version": "2.1.0",
  "description": "",
  "author": "",
  "private": true,
@@ -50,7 +50,7 @@
    "@prisma/adapter-better-sqlite3": "7.10.0",
    "@prisma/client": "7.10.0",
    "bcrypt": "6.0.0",
-    "better-sqlite3": "12.11.1",
+    "better-sqlite3": "13.0.3",
    "cheerio": "1.2.0",
    "class-transformer": "0.5.1",
    "class-validator": "0.15.1",
@@ -144,6 +144,7 @@
    "better-sqlite3@12.11.1": true,
    "fsevents@2.3.3": true,
    "protobufjs@7.6.5": true,
-    "unrs-resolver@1.12.2": true
+    "unrs-resolver@1.12.2": true,
+    "better-sqlite3@13.0.3": true
  }
 }
@@ -8,7 +8,6 @@ const allowedFields = new Set([
  'asOf',
  'attempts',
  'brokerageAccountId',
-  'channelState',
  'clientRequestId',
  'code',
  'count',
@@ -16,15 +15,12 @@ const allowedFields = new Set([
  'environment',
  'found',
  'grpcCode',
-  'headersReceived',
  'method',
  'operation',
-  'queueWaitMs',
  'requestId',
  'route',
  'service',
  'status',
-  'trackingId',
  'userId',
 ]);

@@ -1,6 +1,5 @@
-import { Metadata, status } from '@grpc/grpc-js';
+import { status } from '@grpc/grpc-js';
 import { NotFoundException, ServiceUnavailableException } from '@nestjs/common';
-import { EventEmitter } from 'node:events';

 import { TbankOperationState } from './tbank-protocol';
 import { TbankClient } from './tbank.client';
@@ -137,68 +136,6 @@ describe('TbankClient operations', () => {
    );
    jest.useRealTimers();
  });
-
-  it('distinguishes a gRPC deadline from queue delay without logging upstream secrets', async () => {
-    const logger = { event: jest.fn() };
-    const client = Object.assign(Object.create(TbankClient.prototype) as TbankClient, {
-      logger,
-      queue: { size: 0, run: (operation: () => Promise<unknown>) => operation() },
-    });
-    const channel = { getConnectivityState: () => 1 };
-    const service = {
-      getChannel: () => channel,
-      getAccounts: (_input: unknown, _metadata: unknown, _options: unknown, callback: (error: unknown) => void) => {
-        const call = new EventEmitter();
-        void Promise.resolve().then(() => callback({ code: status.DEADLINE_EXCEEDED, details: 'Bearer secret' }));
-        return call;
-      },
-    };
-    const invoke = (client as unknown as { call: (token: string, service: unknown, method: string, input: object) => Promise<unknown> }).call.bind(client);
-    jest.useFakeTimers();
-    try {
-      const failed = invoke('secret', service, 'getAccounts', {});
-      await Promise.all([
-        expect(failed).rejects.toBeInstanceOf(ServiceUnavailableException),
-        jest.advanceTimersByTimeAsync(1000),
-      ]);
-      expect(logger.event).toHaveBeenLastCalledWith('error', 'tbank.rpc.failed', expect.objectContaining({
-        operation: 'getAccounts', grpcCode: status.DEADLINE_EXCEEDED,
-        queueWaitMs: 0, channelState: 'CONNECTING', headersReceived: false,
-      }));
-      expect(JSON.stringify(logger.event.mock.calls)).not.toContain('secret');
-    } finally {
-      jest.useRealTimers();
-    }
-  });
-
-  it('records response headers and a validated upstream tracking ID', async () => {
-    const logger = { event: jest.fn() };
-    const client = Object.assign(Object.create(TbankClient.prototype) as TbankClient, {
-      logger,
-      queue: { size: 0, run: (operation: () => Promise<unknown>) => operation() },
-    });
-    const headers = new Metadata();
-    headers.set('x-tracking-id', '123e4567-e89b-12d3-a456-426614174000');
-    headers.set('authorization', 'Bearer secret');
-    const service = {
-      getChannel: () => ({ getConnectivityState: () => 2 }),
-      getAccounts: (_input: unknown, _metadata: unknown, _options: unknown, callback: (error: null, response: object) => void) => {
-        const call = new EventEmitter();
-        void Promise.resolve().then(() => {
-          call.emit('metadata', headers);
-          callback(null, { accounts: [] });
-        });
-        return call;
-      },
-    };
-    const invoke = (client as unknown as { call: (token: string, service: unknown, method: string, input: object) => Promise<unknown> }).call.bind(client);
-    await expect(invoke('secret', service, 'getAccounts', {})).resolves.toEqual({ accounts: [] });
-    expect(logger.event).toHaveBeenLastCalledWith('debug', 'tbank.rpc.completed', expect.objectContaining({
-      channelState: 'READY', headersReceived: true,
-      trackingId: '123e4567-e89b-12d3-a456-426614174000',
-    }));
-    expect(JSON.stringify(logger.event.mock.calls)).not.toContain('secret');
-  });
 });

 describe('TbankClient metadata retries', () => {
@@ -2,7 +2,6 @@ import {
  ChannelCredentials,
  Client,
  ClientUnaryCall,
-  connectivityState,
  loadPackageDefinition,
  Metadata,
  ServiceError,
@@ -61,12 +60,6 @@ type Unary<Request, Response> = (
  callback: (error: null | ServiceError, response: Response) => void,
 ) => ClientUnaryCall;
 type TbankClientService = Client & Record<string, Unary<never, never>>;
-type RpcDiagnostics = {
-  channelState?: string;
-  headersReceived?: boolean;
-  queueWaitMs?: number;
-  trackingId?: string;
-};
 export type TbankDecimal = { nano?: number | string; units?: number | string };
 export type TbankMoney = TbankDecimal & { currency?: string };
 export type TbankAccount = {
@@ -518,20 +511,15 @@ export class TbankClient {
    for (let attempts = FIRST_ATTEMPT; attempts <= RPC_MAX_ATTEMPTS; attempts += ATTEMPT_INCREMENT) {
      const startedAt = performance.now();
      const queueFull = this.queue.size >= MAX_QUEUE_SIZE;
-      const diagnostics: RpcDiagnostics = {};
      try {
        if (queueFull) {
          throw new ServiceUnavailableException({ code: TbankErrorCode.Unavailable });
        }
-        const response = await this.queue.run(() => {
-          diagnostics.queueWaitMs = Math.round(performance.now() - startedAt);
-          return this.request<Response>(
-            token, client, method, request, diagnostics,
-          );
-        });
+        const response = await this.queue.run(() =>
+          this.request<Response>(token, client, method, request),
+        );
        this.logger.event('debug', 'tbank.rpc.completed', {
          operation: method,
-          ...diagnostics,
          attempts,
          durationMs: Math.round(performance.now() - startedAt),
        });
@@ -549,7 +537,6 @@ export class TbankClient {
        if (retryable && attempts < RPC_MAX_ATTEMPTS) {
          this.logger.event('warn', 'tbank.rpc.retry', {
            operation: method,
-            ...diagnostics,
            ...failureContext,
            attempts,
            durationMs: Math.round(performance.now() - startedAt),
@@ -559,7 +546,6 @@ export class TbankClient {
        }
        this.logger.event('error', 'tbank.rpc.failed', {
          operation: method,
-          ...diagnostics,
          ...failureContext,
          attempts: queueFull ? NO_RPC_ATTEMPTS : attempts,
          durationMs: Math.round(performance.now() - startedAt),
@@ -587,42 +573,17 @@ export class TbankClient {
    client: TbankClientService,
    method: string,
    request: object,
-    diagnostics?: RpcDiagnostics,
  ): Promise<Response> {
    return new Promise((resolve, reject) => {
      const metadata = new Metadata();
      metadata.set('Authorization', `Bearer ${token}`);
-      // A channel state is a snapshot, not proof that this particular call reached the server.
-      const channel = diagnostics && client.getChannel();
-      if (diagnostics) diagnostics.headersReceived = false;
      // eslint-disable-next-line security/detect-object-injection -- Service and method names are internal RPC selections, not request input.
-      const call = client[method](
+      client[method](
        request as never,
        metadata,
        { deadline: new Date(Date.now() + requestDeadlineMs) },
-        (error, response) => {
-          if (diagnostics && channel) {
-            diagnostics.channelState = connectivityState[
-              channel.getConnectivityState(false)
-            ];
-          }
-          if (error) reject(error);
-          else resolve(response);
-        },
+        (error, response) => (error ? reject(error) : resolve(response)),
      );
-      if (diagnostics) {
-        call.on('metadata', (headers: Metadata) => {
-          diagnostics.headersReceived = true;
-          const trackingId = headers.get('x-tracking-id')[0];
-          // Only a UUID may enter logs; never forward arbitrary upstream metadata.
-          if (
-            typeof trackingId === 'string' &&
-            /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trackingId)
-          ) {
-            diagnostics.trackingId = trackingId;
-          }
-        });
-      }
    });
  }
 }
@@ -91,101 +91,6 @@ export class BankOperationsService {
    };
  }

-  private async pageViews(tx: Tx, rows: BankCardOperation[]) {
-    const userId = rows[0]?.userId;
-    if (!userId) return [];
-    const cardIds = new Set(
-      rows.flatMap((row) =>
-        [row.cardId, row.targetCardId].filter(
-          (id): id is string => id !== null,
-        ),
-      ),
-    );
-    const sourceIds = new Set(
-      rows.flatMap((row) => (row.originalExpenseId ? [row.originalExpenseId] : [])),
-    );
-    const [cards, sources] = await Promise.all([
-      tx.bankCard.findMany({ where: { userId, id: { in: [...cardIds] } } }),
-      tx.bankCardOperation.findMany({
-        where: { userId, id: { in: [...sourceIds] } },
-      }),
-    ]);
-    const categoryIds = new Set(
-      rows
-        .map(
-          (row) =>
-            sources.find((source) => source.id === row.originalExpenseId)
-              ?.categoryId ?? row.categoryId,
-        )
-        .filter((id): id is string => id !== null),
-    );
-    const expenseIds = new Set(
-      rows.flatMap((row) => {
-        const source = sources.find((item) => item.id === row.originalExpenseId);
-        return row.kind === BankOperationKind.Expense || source
-          ? [source?.id ?? row.id]
-          : [];
-      }),
-    );
-    const [categories, refunds] = await Promise.all([
-      tx.expenseCategory.findMany({
-        where: { userId, id: { in: [...categoryIds] } },
-      }),
-      tx.bankCardOperation.findMany({
-        where: {
-          userId,
-          originalExpenseId: { in: [...expenseIds] },
-          deletedAt: null,
-        },
-      }),
-    ]);
-    const cardsById = new Map(cards.map((card) => [card.id, card]));
-    const sourcesById = new Map(sources.map((source) => [source.id, source]));
-    const categoriesById = new Map(categories.map((category) => [category.id, category]));
-    return rows.map((row) => {
-      const card = cardsById.get(row.cardId) as { name: string };
-      const target = row.targetCardId ? cardsById.get(row.targetCardId) : null;
-      const source = row.originalExpenseId
-        ? sourcesById.get(row.originalExpenseId)
-        : null;
-      const categoryId = source?.categoryId ?? row.categoryId;
-      const relatedRefunds =
-        row.kind === BankOperationKind.Expense || source
-          ? refunds.filter(
-              (refund) =>
-                refund.originalExpenseId === (source?.id ?? row.id) &&
-                (!source || refund.id !== row.id),
-            )
-          : [];
-      return {
-        id: row.id,
-        kind: row.kind as BankOperationDto['kind'],
-        cardId: row.cardId,
-        cardName: card.name,
-        targetCardId: row.targetCardId,
-        targetCardName: target?.name ?? null,
-        categoryId,
-        categoryName: categoriesById.get(categoryId ?? '')?.name ?? null,
-        originalExpenseId: row.originalExpenseId,
-        amount: rubMoney(row.amountKopecks),
-        availableRefund:
-          row.kind === BankOperationKind.Expense || source
-            ? rubMoney(
-                (source?.amountKopecks ?? row.amountKopecks) -
-                relatedRefunds.reduce(
-                  (sum, refund) => sum + refund.amountKopecks,
-                  ZERO_KOPECKS,
-                ),
-              )
-            : null,
-        date: row.date,
-        description: row.description,
-        version: row.version,
-        createdAt: row.createdAt.toISOString(),
-      };
-    });
-  }
-
  private async validateOperation(
    tx: Tx,
    userId: string,
@@ -454,7 +359,9 @@ export class BankOperationsService {
        take: limit,
      });
      return {
-        items: await this.pageViews(tx, rows),
+        items: await Promise.all(
+          rows.map((row) => this.operationView(tx, row)),
+        ),
        total,
        page,
        hasNext: page * limit < total,
@@ -67,6 +67,28 @@ export class IncomeSummaryDto {
  declare calculatedAt: string;
 }

+export class IncomeComparisonCurrencyDto {
+  @ApiProperty()
+  declare currency: string;
+
+  @ApiProperty({ type: IncomeCurrencySummaryDto })
+  declare selected: IncomeCurrencySummaryDto;
+
+  @ApiProperty({ type: IncomeCurrencySummaryDto })
+  declare compared: IncomeCurrencySummaryDto;
+
+  @ApiProperty({ type: IncomeCurrencySummaryDto })
+  declare difference: IncomeCurrencySummaryDto;
+}
+
+export class IncomeComparisonDto {
+  @ApiProperty({ type: IncomePeriodDto })
+  declare period: IncomePeriodDto;
+
+  @ApiProperty({ type: IncomeComparisonCurrencyDto, isArray: true })
+  declare totalsByCurrency: IncomeComparisonCurrencyDto[];
+}
+
 export class IncomeBucketDto {
  @ApiProperty({ type: IncomePeriodDto })
  declare period: IncomePeriodDto;
@@ -113,6 +135,12 @@ export class IncomeAnalyticsEntryDto extends BrokerageOperationDto {
 }

 export class IncomeAnalyticsDto extends IncomeSummaryDto {
+  @ApiProperty({ type: IncomeComparisonDto, nullable: true })
+  declare previous: IncomeComparisonDto | null;
+
+  @ApiProperty({ type: IncomeComparisonDto, nullable: true })
+  declare yearComparison: IncomeComparisonDto | null;
+
  @ApiProperty({ enum: ['day', 'week', 'month'] })
  declare bucketGranularity: 'day' | 'month' | 'week';

@@ -134,7 +162,7 @@ export class IncomeSummaryResourceDto {
  declare meta: InvestmentResourceMetaDto;
 }

-const incomeDependencyRoles = ['selected'] as const;
+const incomeDependencyRoles = ['selected', 'previous', 'year'] as const;

 export class IncomeDependencyDto extends InvestmentDependencyDto {
  @ApiProperty({ enum: incomeDependencyRoles })
@@ -17,7 +17,7 @@ describe('IncomeAnalyticsService', () => {

  beforeEach(() => jest.clearAllMocks());

-  it('labels the selected dependency independently of its resource key', async () => {
+  it('labels each comparison dependency independently of its resource key', async () => {
    seed([]);
    const response = await service.analytics(
      'user',
@@ -27,10 +27,32 @@ describe('IncomeAnalyticsService', () => {
    );
    expect(response.meta.dependencies).toEqual([
      expect.objectContaining({ role: 'selected', resourceKey: 'period/0' }),
+      expect.objectContaining({ role: 'previous', resourceKey: 'period/1' }),
+      expect.objectContaining({ role: 'year', resourceKey: 'period/2' }),
    ]);
-    expect(
-      response.meta.dependencies.some((dependency) => dependency.role !== 'selected'),
-    ).toBe(false);
+  });
+
+  it('labels an unavailable leap-day comparison as year', async () => {
+    operations.collectRanges.mockImplementation(
+      (_user: string, _account: string, build: () => unknown[]) =>
+        build().map((_, index) => ({ items: [], meta: completeMeta(index) })),
+    );
+    const response = await service.analytics(
+      'user',
+      'account',
+      '2024-02-29',
+      '2024-02-29',
+    );
+    expect(response.meta.dependencies).toEqual([
+      expect.objectContaining({ role: 'selected' }),
+      expect.objectContaining({ role: 'previous' }),
+      expect.objectContaining({
+        role: 'year',
+        availability: 'temporarily-unavailable',
+        unavailableReason: 'CALENDAR_OR_ACCOUNT_HISTORY',
+      }),
+    ]);
+    expect(response.data?.yearComparison).toBeNull();
  });

  function seed(items: BrokerageOperationDto[]) {
@@ -41,7 +63,7 @@ describe('IncomeAnalyticsService', () => {
        build: (opened?: Date) => unknown[],
      ) => {
        build(undefined);
-        return [items].map((items, index) => ({
+        return [items, [], []].map((items, index) => ({
          items,
          meta: completeMeta(index),
        }));
@@ -225,6 +247,8 @@ describe('IncomeAnalyticsService', () => {
            entry('transfer', 'OPERATION_TYPE_DIVIDEND_TRANSFER', '99', 'RUB'),
            entry('usd', 'OPERATION_TYPE_COUPON', '1', 'USD'),
          ],
+          [],
+          [],
        ].map((items, index) => ({ items, meta: completeMeta(index) }));
      },
    );
@@ -6,6 +6,7 @@ import {
  compare,
  decimalFromString,
  formatDecimal,
+  subtract,
 } from '../../../common/decimal';
 import { isTbankProtocolValue, TbankOperationType } from '../../../integrations/tbank/tbank-protocol';
 import { DateOnlyRange, moscowDate } from '../investment-calendar';
@@ -17,6 +18,7 @@ import {
 import {
  IncomeAnalyticsEntryDto,
  IncomeAnalyticsResourceDto,
+  IncomeComparisonDto,
  IncomeCurrencySummaryDto,
  IncomeDependencyDto,
  IncomeInstrumentDto,
@@ -45,11 +47,14 @@ export class IncomeAnalyticsService {
    accountId: string,
    observe = false,
  ): Promise<IncomeSummaryResourceDto> {
-    const plan = planIncomePeriod(undefined, undefined);
+    let plan = planIncomePeriod(undefined, undefined);
    const [selected] = await this.operations.collectRanges(
      userId,
      accountId,
-      () => [plan.selected],
+      (openedAt) => {
+        plan = planIncomePeriod(undefined, undefined, openedAt);
+        return [plan.selected];
+      },
      observe,
    );
    if (selected.items === null) return { data: null, meta: selected.meta };
@@ -72,17 +77,44 @@ export class IncomeAnalyticsService {
    to: string | undefined,
    observe = false,
  ): Promise<IncomeAnalyticsResourceDto> {
-    const plan = planIncomePeriod(from, to);
-    const [current] = await this.operations.collectRanges(
+    let plan = planIncomePeriod(from, to);
+    const periods = await this.operations.collectRanges(
      userId,
      accountId,
-      () => [plan.selected],
+      (openedAt) => {
+        plan = planIncomePeriod(from, to, openedAt);
+        return [
+          plan.selected,
+          plan.previous,
+          ...(plan.yearAgo ? [plan.yearAgo] : []),
+        ];
+      },
      observe,
    );
+    const [current, prior, year] = periods;
+    // Preserve the legacy order while consumers migrate to explicit roles.
    const dependencies: IncomeDependencyDto[] = [
      { ...current.meta, role: 'selected' },
+      { ...prior.meta, role: 'previous' },
+      {
+        ...(plan.yearAgo && year
+          ? year.meta
+          : investmentResourceMeta({
+              resourceKey: 'income/yearAgo', // gitleaks:allow public resource identifier
+              dataRevision: 'unavailable',
+              availability: 'missing',
+              fetchedAt: null,
+              freshForMs: 0,
+              work: null,
+              unavailableReason: 'CALENDAR_OR_ACCOUNT_HISTORY',
+            })),
+        role: 'year',
+      },
    ];
-    const work = current.meta.sync;
+    const states = periods.map((period) => period.meta.sync);
+    const work =
+      states.find((state) => state.state === 'running') ??
+      states.find((state) => state.state === 'failed');
    const meta = {
      ...investmentResourceMeta({
        resourceKey: `income/${accountId}/${plan.selected.from}/${plan.selected.to}`,
@@ -95,9 +127,7 @@ export class IncomeAnalyticsService {
          ? new Date(current.meta.lastSuccessfulAt)
          : null,
        freshForMs: current.meta.freshness === 'fresh' ? Infinity : STALE_FRESHNESS_MS,
-        work: work.id
-          ? { id: work.id, state: work.state, errorCode: work.errorCode }
-          : null,
+        work: work?.id ? { ...work, id: work.id } : null,
        coverage: current.meta.coverage,
        dependencies,
      }),
@@ -117,6 +147,14 @@ export class IncomeAnalyticsService {
          selected,
          current.meta.lastSuccessfulAt,
        ),
+        previous:
+          prior.items === null
+            ? null
+            : comparison(selected, plan.previous, qualifying(prior.items)),
+        yearComparison:
+          plan.yearAgo && year?.items !== null && year
+            ? comparison(selected, plan.yearAgo, qualifying(year.items))
+            : null,
        bucketGranularity: plan.granularity,
        buckets: buckets(plan.selected, plan.granularity, selected),
        instruments: instruments(selected),
@@ -160,6 +198,38 @@ function totals(entries: BrokerageOperationDto[]): IncomeCurrencySummaryDto[] {
    .map(([currency, total]) => presentTotal(currency, total));
 }

+function comparison(
+  selectedEntries: BrokerageOperationDto[],
+  comparedPeriod: DateOnlyRange,
+  comparedEntries: BrokerageOperationDto[],
+): IncomeComparisonDto {
+  const selected = new Map(
+    totals(selectedEntries).map((total) => [total.currency, total]),
+  );
+  const compared = new Map(
+    totals(comparedEntries).map((total) => [total.currency, total]),
+  );
+  const currencies = [
+    ...new Set([...selected.keys(), ...compared.keys()]),
+  // eslint-disable-next-line sonarjs/no-alphabetical-sort -- Code-unit ordering is intentional for canonical keys and ISO dates; locale collation would change persisted bindings.
+  ].sort();
+  return {
+    period: comparedPeriod,
+    totalsByCurrency: currencies.map((currency) => {
+      const current =
+        selected.get(currency) ?? presentTotal(currency, zeroTotal());
+      const prior =
+        compared.get(currency) ?? presentTotal(currency, zeroTotal());
+      return {
+        currency,
+        selected: current,
+        compared: prior,
+        difference: difference(current, prior),
+      };
+    }),
+  };
+}
+
 function buckets(
  range: DateOnlyRange,
  granularity: IncomeBucketGranularity,
@@ -223,6 +293,22 @@ function instrumentKey(entry: BrokerageOperationDto): string {
  return `operation:${entry.account ? `${entry.account.id}:` : ''}${entry.id}`;
 }

+function difference(
+  left: IncomeCurrencySummaryDto,
+  right: IncomeCurrencySummaryDto,
+): IncomeCurrencySummaryDto {
+  return presentTotal(left.currency, {
+    coupon: subtract(
+      decimalFromString(left.coupon.value),
+      decimalFromString(right.coupon.value),
+    ),
+    dividend: subtract(
+      decimalFromString(left.dividend.value),
+      decimalFromString(right.dividend.value),
+    ),
+  });
+}
+
 function zeroTotal(): Total {
  return { coupon: { value: 0n, scale: 0 }, dividend: { value: 0n, scale: 0 } };
 }
@@ -23,14 +23,16 @@ describe('income period planning', () => {
    }
  });

-  it('keeps empty buckets and skips removed comparison ranges', () => {
+  it('uses a full previous month, skips impossible year-ago dates, and keeps empty buckets', () => {
+    const fullMonth = planIncomePeriod('2026-03-01', '2026-03-31');
+    expect(fullMonth.previous).toEqual({
+      from: '2026-02-01',
+      to: '2026-02-28',
+    });
+    expect(planIncomePeriod('2024-02-29', '2024-02-29').yearAgo).toBeNull();
    expect(
      rangeBuckets({ from: '2026-01-01', to: '2026-02-15' }, 'week'),
    ).toHaveLength(7);
-    expect(planIncomePeriod('2026-03-01', '2026-03-31')).toEqual({
-      selected: { from: '2026-03-01', to: '2026-03-31' },
-      granularity: 'day',
-    });
  });

  it('accepts multi-year periods and creates monthly buckets for the entire range', () => {
@@ -41,6 +43,7 @@ describe('income period planning', () => {
    expect(plan.selected).toEqual({ from: '2020-01-01', to: '2025-12-31' });
    expect(plan.granularity).toBe('month');
    expect(rangeBuckets(plan.selected, plan.granularity)).toHaveLength(72);
+    expect(plan.yearAgo).toEqual({ from: '2019-01-01', to: '2024-12-31' });
  });

  it('does not send the unfinished Moscow day as a future instant', () => {
@@ -14,28 +14,45 @@ const MONDAY_WEEKDAY_INDEX = 1;
 const INCLUSIVE_DAY_OFFSET = 1;
 const NEXT_DAY_OFFSET = 1;
 const PREVIOUS_MONTH_LAST_DAY = 0;
+const PREVIOUS_DAY_OFFSET = -1;
+const PREVIOUS_YEAR_OFFSET = 1;
+const DATE_COMPONENT_DIGITS = 2;

 const DAILY_BUCKET_MAX_DAYS = 45;
 const WEEKLY_BUCKET_MAX_DAYS = 180;
 const DAYS_PER_WEEK = 7;
 const ISO_MONTH_LENGTH = 7;
+const ISO_YEAR_LENGTH = 4;

 export type IncomeBucketGranularity = 'day' | 'month' | 'week';

 export function planIncomePeriod(
  from: string | undefined,
  to: string | undefined,
+  openedDate?: Date,
 ): {
  granularity: IncomeBucketGranularity;
+  previous: DateOnlyRange;
  selected: DateOnlyRange;
+  yearAgo: DateOnlyRange | null;
 } {
  if (Boolean(from) !== Boolean(to)) throw invalidPeriod();
  const today = moscowDate(new Date());
  const selected =
    from && to ? { from, to } : { from: firstOfMonth(today), to: today };
  assertRange(selected, today);
+  const previous = isFullMonth(selected)
+    ? previousMonth(selected.from)
+    : shiftDays(selected, -rangeDays(selected));
+  const candidate = yearAgo(selected);
+  const yearAgoRange =
+    candidate && (!openedDate || candidate.from >= moscowDate(openedDate))
+      ? candidate
+      : null;
  return {
    selected,
+    previous,
+    yearAgo: yearAgoRange,
    granularity:
      rangeDays(selected) <= DAILY_BUCKET_MAX_DAYS
        ? 'day'
@@ -119,6 +136,34 @@ function endOfMonth(value: string): string {
  return new Date(Date.UTC(year, month, PREVIOUS_MONTH_LAST_DAY)).toISOString().slice(ISO_DATE_START, ISO_DATE_LENGTH);
 }

+function isFullMonth(range: DateOnlyRange): boolean {
+  return (
+    range.from === firstOfMonth(range.from) && range.to === endOfMonth(range.to)
+  );
+}
+
+function previousMonth(from: string): DateOnlyRange {
+  const last = addDays(firstOfMonth(from), PREVIOUS_DAY_OFFSET);
+  return { from: firstOfMonth(last), to: last };
+}
+
+function shiftDays(range: DateOnlyRange, days: number): DateOnlyRange {
+  return { from: addDays(range.from, days), to: addDays(range.to, days) };
+}
+
+function yearAgo(range: DateOnlyRange): DateOnlyRange | null {
+  const shift = (value: string) => {
+    const [year, month, day] = dateParts(value);
+    const result = `${String(year - PREVIOUS_YEAR_OFFSET).padStart(ISO_YEAR_LENGTH, '0')}-${String(month).padStart(DATE_COMPONENT_DIGITS, '0')}-${String(day).padStart(DATE_COMPONENT_DIGITS, '0')}`;
+    return utcDate(result).toISOString().slice(ISO_DATE_START, ISO_DATE_LENGTH) === result
+      ? result
+      : null;
+  };
+  const from = shift(range.from);
+  const to = shift(range.to);
+  return from && to ? { from, to } : null;
+}
+
 function invalidPeriod(): BadRequestException {
  return new BadRequestException({ code: IncomeErrorCode.InvalidPeriod });
 }
@@ -9,7 +9,9 @@ import { StructuredLogger } from '../../../../common/logging/structured-logger.s
 import { isTbankErrorCode, TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
 import {
  TbankAccessService,
+  type TbankBond,
  TbankClient,
+  type TbankShare,
  tbankSourceTtlMs,
  type TbankSyncAttempt,
 } from '../../../../integrations/tbank/tbank.api';
@@ -26,7 +28,6 @@ import {
  catalogSearchLimit,
  selectCatalogInstruments,
 } from './catalog-selection';
-import { publicInstrument } from './public-instrument';

 const UNAMBIGUOUS_MATCH_COUNT = 1;
 const NO_MATCHES = 0;
@@ -494,3 +495,37 @@ export class CatalogDiscoveryService {
    }
  }
 }
+
+function publicInstrument(value: TbankBond | TbankShare) {
+  const bond = value as TbankBond;
+  const share = value as TbankShare;
+  return {
+    uid: value.uid,
+    figi: value.figi,
+    assetUid: value.assetUid,
+    name: value.name,
+    ticker: value.ticker,
+    isin: value.isin,
+    classCode: value.classCode,
+    realExchange: value.realExchange,
+    apiTradeAvailableFlag: value.apiTradeAvailableFlag,
+    currency: value.currency,
+    shareType: share.shareType,
+    sector: value.sector,
+    lot: value.lot,
+    brand: value.brand ? { logoName: value.brand.logoName } : undefined,
+    first_1dayCandleDate: value.first_1dayCandleDate,
+    nominal: bond.nominal,
+    initialNominal: bond.initialNominal,
+    aciValue: bond.aciValue,
+    maturityDate: bond.maturityDate,
+    callDate: bond.callDate,
+    couponQuantityPerYear: bond.couponQuantityPerYear,
+    floatingCouponFlag: bond.floatingCouponFlag,
+    perpetualFlag: bond.perpetualFlag,
+    amortizationFlag: bond.amortizationFlag,
+    subordinatedFlag: bond.subordinatedFlag,
+    bondType: bond.bondType,
+    riskLevel: bond.riskLevel,
+  };
+}
@@ -38,7 +38,6 @@ import {
 import { toSavedCandle } from '../infrastructure/tbank-candle.mapper';
 import { catalogSearchLimit } from './catalog-selection';
 import { previousClose, timestamp } from './instrument-market';
-import { publicInstrument } from './public-instrument';

 const MISSING_DATA_REVISION = 0;
 const FIRST_QUEUE_INDEX = 0;
@@ -652,6 +651,39 @@ export type CatalogPayload = {
  tradingStatus?: null | string;
 };

+function publicInstrument(value: TbankBond | TbankShare) {
+  const bond = value as TbankBond;
+  const share = value as TbankShare;
+  return {
+    uid: value.uid,
+    figi: value.figi,
+    assetUid: value.assetUid,
+    name: value.name,
+    ticker: value.ticker,
+    isin: value.isin,
+    classCode: value.classCode,
+    realExchange: value.realExchange,
+    apiTradeAvailableFlag: value.apiTradeAvailableFlag,
+    currency: value.currency,
+    shareType: share.shareType,
+    sector: value.sector,
+    lot: value.lot,
+    brand: value.brand ? { logoName: value.brand.logoName } : undefined,
+    first_1dayCandleDate: value.first_1dayCandleDate,
+    nominal: bond.nominal,
+    initialNominal: bond.initialNominal,
+    aciValue: bond.aciValue,
+    maturityDate: bond.maturityDate,
+    callDate: bond.callDate,
+    couponQuantityPerYear: bond.couponQuantityPerYear,
+    floatingCouponFlag: bond.floatingCouponFlag,
+    perpetualFlag: bond.perpetualFlag,
+    amortizationFlag: bond.amortizationFlag,
+    subordinatedFlag: bond.subordinatedFlag,
+    bondType: bond.bondType,
+    riskLevel: bond.riskLevel,
+  };
+}
 function sourcePolicy(kind: CatalogSource['kind']) {
  if (
    [
@@ -1,64 +0,0 @@
-import type {
-  TbankBond,
-  TbankShare,
-} from '../../../../integrations/tbank/tbank.api';
-
-import { publicInstrument } from './public-instrument';
-
-const share = {
-  uid: 'share-uid',
-  figi: 'FIGI1',
-  assetUid: 'asset-1',
-  name: 'Share',
-  ticker: 'SHAR',
-  isin: 'US000',
-  classCode: 'TQBR',
-  realExchange: 'REAL_EXCHANGE_MOEX',
-  apiTradeAvailableFlag: true,
-  currency: 'rub',
-  shareType: 'SHARE_TYPE_COMMON',
-  sector: 'Finance',
-  lot: 1,
-  brand: { logoName: 'logo.png', title: 'Brand', id: 'brand-1' },
-  first_1dayCandleDate: '2020-01-01T00:00:00Z',
-  privateField: 'must-not-leak',
-} as unknown as TbankShare;
-
-const bond = {
-  uid: 'bond-uid',
-  figi: 'FIGI2',
-  assetUid: 'asset-2',
-  name: 'Bond',
-  ticker: 'BOND',
-  classCode: 'TQOB',
-  currency: 'rub',
-  lot: 1,
-  nominal: { value: '1000', currency: 'rub' },
-  initialNominal: { value: '1000', currency: 'rub' },
-  aciValue: { value: '10', currency: 'rub' },
-  maturityDate: '2030-01-01T00:00:00Z',
-  couponQuantityPerYear: 2,
-  bondType: 'BOND_TYPE_EXPIRING',
-  brand: null,
-  privateField: 'must-not-leak',
-} as unknown as TbankBond;
-
-describe('publicInstrument projection', () => {
-  it('keeps approved share fields, trims brand, drops private extras', () => {
-    const result = publicInstrument(share);
-    expect(result.uid).toBe('share-uid');
-    expect(result.shareType).toBe('SHARE_TYPE_COMMON');
-    expect(result.brand).toEqual({ logoName: 'logo.png' });
-    expect(result).not.toHaveProperty('privateField');
-    expect(result).not.toHaveProperty('brand.title');
-  });
-
-  it('projects bonds with missing optional fields and null brand', () => {
-    const result = publicInstrument(bond);
-    expect(result.nominal).toEqual({ value: '1000', currency: 'rub' });
-    expect(result.shareType).toBeUndefined();
-    expect(result.brand).toBeUndefined();
-    expect(result.isin).toBeUndefined();
-    expect(result).not.toHaveProperty('privateField');
-  });
-});
@@ -1,38 +0,0 @@
-import type {
-  TbankBond,
-  TbankShare,
-} from '../../../../integrations/tbank/tbank.api';
-
-export function publicInstrument(value: TbankBond | TbankShare) {
-  const bond = value as TbankBond;
-  const share = value as TbankShare;
-  return {
-    uid: value.uid,
-    figi: value.figi,
-    assetUid: value.assetUid,
-    name: value.name,
-    ticker: value.ticker,
-    isin: value.isin,
-    classCode: value.classCode,
-    realExchange: value.realExchange,
-    apiTradeAvailableFlag: value.apiTradeAvailableFlag,
-    currency: value.currency,
-    shareType: share.shareType,
-    sector: value.sector,
-    lot: value.lot,
-    brand: value.brand ? { logoName: value.brand.logoName } : undefined,
-    first_1dayCandleDate: value.first_1dayCandleDate,
-    nominal: bond.nominal,
-    initialNominal: bond.initialNominal,
-    aciValue: bond.aciValue,
-    maturityDate: bond.maturityDate,
-    callDate: bond.callDate,
-    couponQuantityPerYear: bond.couponQuantityPerYear,
-    floatingCouponFlag: bond.floatingCouponFlag,
-    perpetualFlag: bond.perpetualFlag,
-    amortizationFlag: bond.amortizationFlag,
-    subordinatedFlag: bond.subordinatedFlag,
-    bondType: bond.bondType,
-    riskLevel: bond.riskLevel,
-  };
-}
@@ -17,7 +17,7 @@ describe('screen dependency and history planning', () => {
      },
    ],
  };
-  it('prioritizes discovery, the selected period, then history; Moscow dates are converted once', () => {
+  it('prioritizes discovery, selected/comparisons, then history; Moscow dates are converted once', () => {
    const plan = planInvestmentScreen(
      {
        screen: 'income',
@@ -32,17 +32,6 @@ describe('screen dependency and history planning', () => {
    const selected = plan.sources.filter(
      (source) => source.kind === 'operations' && source.priority === 'screen',
    );
-    // The single selected range is chunked into month-aligned intervals.
-    expect(selected).toHaveLength(2);
-    expect(
-      selected.every(
-        (source) =>
-          source.from != null &&
-          source.from.toISOString() >= '2024-01-31T21:00:00.000Z' &&
-          source.to != null &&
-          source.to.toISOString() <= '2024-02-29T21:00:00.000Z',
-      ),
-    ).toBe(true);
    expect(
      selected.some(
        (source) => source.from?.toISOString() === '2024-01-31T21:00:00.000Z',
@@ -53,7 +42,9 @@ describe('screen dependency and history planning', () => {
        (source) => source.to?.toISOString() === '2024-02-29T21:00:00.000Z',
      ),
    ).toBe(true);
-    expect(plan.unavailable).toEqual([]);
+    expect(plan.unavailable).toEqual([
+      { resourceKey: 'income/yearAgo', reason: 'calendar_or_account_boundary' }, // gitleaks:allow public resource identifier
+    ]);
    const firstHistory = plan.sources.findIndex(
      (source) => source.priority === 'history',
    );
@@ -111,6 +111,13 @@ export function planInvestmentScreen(
        priority: 'screen' as const,
      })),
    );
+  const knownOpening =
+    accounts.length && accounts.every((account) => account.openedOn)
+      ? new Date(
+          // eslint-disable-next-line sonarjs/no-alphabetical-sort -- Code-unit ordering is intentional for canonical keys and ISO dates; locale collation would change persisted bindings.
+          `${accounts.map((account) => account.openedOn ?? '').sort()[0]}T00:00:00+03:00`,
+        )
+      : undefined;
  if (!context.membershipKnown) return { sources, unavailable, now };
  if (
    ['account', 'accounts', 'bond', 'events', 'stock'].includes(screen.screen)
@@ -135,9 +142,23 @@ export function planInvestmentScreen(
    const period = planIncomePeriod(
      screen.screen === 'income' ? screen.from : undefined,
      screen.screen === 'income' ? screen.to : undefined,
+      knownOpening,
    );
-    const bounds = dateOnlyBounds(period.selected, now);
-    operations(bounds.from, bounds.to);
+    for (const range of [
+      period.selected,
+      ...(screen.screen === 'income'
+        ? [period.previous, ...(period.yearAgo ? [period.yearAgo] : [])]
+        : []),
+    ]) {
+      const bounds = dateOnlyBounds(range, now);
+      operations(bounds.from, bounds.to);
+    }
+    if (screen.screen === 'income' && !period.yearAgo) {
+      unavailable.push({
+        resourceKey: 'income/yearAgo', // gitleaks:allow public resource identifier
+        reason: 'calendar_or_account_boundary',
+      });
+    }
    if (screen.screen === 'account') {
      const range = ledgerRange(
        screen.from,
@@ -451,11 +451,7 @@ export class BrokerageOperationsService {
        key: `${period.from}/${period.to}`,
        movingEnd: false,
      }));
-    const rows = saved?.rows ?? [];
-    const instruments = await this.metadata.savedMany(
-      rows.map((row) => row.payload as TbankOperationItem),
-    );
-    return periods.map((period) => {
+    return periods.map((period, index) => {
      const targets = (saved?.connection.accounts ?? []).map((account) => ({
        accountId: account.accountId,
        ...period,
@@ -491,7 +487,8 @@ export class BrokerageOperationsService {
          null;
      const confirmed = confirmedOperationRanges(plan.intervals, sources);
      const meta = investmentResourceMeta({
-        resourceKey: `income/${accountId}/selected/${period.key}`,
+        // eslint-disable-next-line security/detect-object-injection -- The numeric index enumerates the three comparison periods.
+        resourceKey: `income/${accountId}/${['selected', 'previous', 'yearAgo'][index]}/${period.key}`,
        dataRevision: saved?.binding ?? 'missing',
        availability: !known
          ? 'missing'
@@ -545,7 +542,7 @@ export class BrokerageOperationsService {
      return {
        meta,
        items: complete
-          ? rows
+          ? (saved?.rows ?? [])
              .filter((row) =>
                plan.intervals.some(
                  (interval) =>
@@ -559,10 +556,6 @@ export class BrokerageOperationsService {
                  row.payload as TbankOperationItem,
                  row.occurredAt,
                ),
-                logoName:
-                  instruments
-                    .get(metadataKey(row.payload as TbankOperationItem))
-                    ?.data?.brand?.logoName?.trim() || null,
                ...(accountId === 'all'
                  ? {
                      account: {
@@ -2,7 +2,6 @@ import { BadRequestException, Injectable } from '@nestjs/common';

 import {
  add,
-  type Decimal,
  decimalFromString,
  formatDecimal,
  isZero,
@@ -281,7 +280,7 @@ function dateWindow(query: UpcomingEventsQueryDto) {
 }

 function incomeTotals(events: UpcomingEventDto[]): MoneyDto[] {
-  const totals = new Map<string, Decimal>();
+  const totals = new Map<string, ReturnType<typeof decimalFromString>>();
  for (const event of events) {
    if (!['coupon', 'dividend'].includes(event.type) || !event.projectedAmount) {
      continue;
@@ -77,7 +77,7 @@ describe('OpenAPI contract (integration)', () => {
    }
  });

-  it('exposes only the selected income dependency role and no comparison data', () => {
+  it('exposes required semantic income dependency roles', () => {
    const schemas = createOpenApiDocument(app).components?.schemas;
    expect(schemas?.IncomeAnalyticsResourceDto).toMatchObject({
      properties: {
@@ -100,25 +100,9 @@ describe('OpenAPI contract (integration)', () => {
    expect(dependency.required).toContain('role');
    expect(dependency).toMatchObject({
      properties: {
-        role: { type: 'string', enum: ['selected'] },
+        role: { type: 'string', enum: ['selected', 'previous', 'year'] },
      },
    });
-    const analytics = schemas?.IncomeAnalyticsDto;
-    assert(analytics && !('$ref' in analytics));
-    expect(analytics.required).toEqual(
-      expect.arrayContaining([
-        'accountId',
-        'period',
-        'totalsByCurrency',
-        'calculatedAt',
-        'bucketGranularity',
-        'buckets',
-        'instruments',
-        'entries',
-      ]),
-    );
-    expect(analytics.properties).not.toHaveProperty('previous');
-    expect(analytics.properties).not.toHaveProperty('yearComparison');
  });

  it('generates the runtime contract without server startup or deployment configuration', async () => {
@@ -18,7 +18,7 @@ writeFileSync(sentinel, 'fictional user database: must never be opened');
 const before = readFileSync(sentinel);
 const databases = new Set();
 async function check(name, overrides = {}, signal) {
-  const child = spawn(process.execPath, ['test/sqlite.cjs'], {
+  const child = spawn(process.execPath, ['test/sqlite.cjs', '--all'], {
    cwd,
    env: {
      ...process.env,
@@ -124,7 +124,7 @@ describe('local income completeness and exact money (SQLite)', () => {
      }
    }
  });
-  it('returns exact selected sums; reopen and observe need no RPC', async () => {
+  it('returns exact selected sums without a false zero comparison; reopen and observe need no RPC', async () => {
    for (let index = 0; index < 2; index++) {
      const result = await read();
      assert(result.data);
@@ -140,55 +140,22 @@ describe('local income completeness and exact money (SQLite)', () => {
          .filter((row) => row.id === 'same')
          .map((row) => row.account?.id),
      ).toEqual(['a', 'b']);
+      expect(result.data.previous).toBeNull();
+      expect(result.data.yearComparison).toBeNull();
      expect(result.meta.dependencies.map(({ role }) => role)).toEqual([
        'selected',
+        'previous',
+        'year',
      ]);
+      const previous = result.meta.dependencies.find(({ role }) => role === 'previous');
+      expect(previous?.availability).toBe('temporarily-unavailable');
+      expect(previous?.completeness).toBe('incomplete');
      expect(result.data.calculatedAt).toBe('2025-02-01T00:00:00.000Z');
      await prisma.$disconnect();
    }
    expect(upstream.getOpenAccounts).not.toHaveBeenCalled();
    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
  });
-  it('uses saved instrument logos for income entries without changing their financial data', async () => {
-    const before = await read();
-    const base = before.data;
-    assert(base);
-    const fetchedAt = new Date();
-    await prisma.tbankOperation.update({
-      where: {
-        userId_revision_accountId_brokerOperationId: {
-          userId: 'income-owner', revision, accountId: 'a', brokerOperationId: 'same',
-        },
-      },
-      data: {
-        payload: {
-          id: 'same', figi: 'income-figi', type: 'OPERATION_TYPE_COUPON',
-          date: { seconds: String(Date.parse('2025-01-15Z') / 1000) },
-          payment: { units: '10', nano: 1, currency: 'rub' },
-        },
-      },
-    });
-    await prisma.tbankInstrument.create({
-      data: {
-        provider: 'tbank', uid: 'income-uid', figi: 'income-figi',
-        instrumentType: 'bond', fetchedAt,
-        metadata: { uid: 'income-uid', figi: 'income-figi', name: 'Bond', brand: { logoName: 'bond.png' } },
-      },
-    });
-    await prisma.tbankInstrumentLookup.create({
-      data: {
-        provider: 'tbank', identifierType: 'figi', identifier: 'income-figi',
-        matchedUids: ['income-uid'], fetchedAt,
-      },
-    });
-    const after = await read();
-    assert(after.data);
-    expect(after.data.entries.find((entry) => entry.account?.id === 'a' && entry.id === 'same')?.logoName).toBe('bond.png');
-    expect(after.data.entries.find((entry) => entry.account?.id === 'b' && entry.id === 'same')?.logoName).toBeNull();
-    expect(after.data.totalsByCurrency).toEqual(base.totalsByCurrency);
-    expect(after.data.calculatedAt).toBe(base.calculatedAt);
-    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
-  });
  it('requires every account and separates missing, partial and confirmed empty periods', async () => {
    await prisma.tbankOperationCoverage.deleteMany({
      where: { accountId: 'b' },
@@ -209,7 +176,15 @@ describe('local income completeness and exact money (SQLite)', () => {
    ).toEqual([]);
    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
  });
-  it('counts corrected identities once for the selected period', async () => {
+  it('completes previous/yearAgo independently and counts corrected identities once', async () => {
+    for (const account of ['a', 'b']) {
+      await coverage(account, new Date('2024-11-30T21:00:00Z'), from);
+      await coverage(
+        account,
+        new Date('2023-12-31T21:00:00Z'),
+        new Date('2024-01-31T21:00:00Z'),
+      );
+    }
    await prisma.tbankOperation.updateMany({
      where: { accountId: 'a', brokerOperationId: 'same' },
      data: {
@@ -222,12 +197,14 @@ describe('local income completeness and exact money (SQLite)', () => {
      },
    });
    const result = await read();
-    assert(result.data);
+    assert(result.data?.previous && result.data.yearComparison);
    expect(result.data.entries).toHaveLength(6);
    expect(
-      result.data.totalsByCurrency.find(({ currency }) => currency === 'RUB')
-        ?.total,
-    ).toEqual({ currency: 'RUB', value: '25.000000002' });
+      result.data.previous.totalsByCurrency[0].difference.total.value,
+    ).toBe('25.000000002');
+    expect(
+      result.data.yearComparison.totalsByCurrency[0].compared.total.value,
+    ).toBe('0');
  });
  it('preserves the complete financial result and timestamp through failed atomic reconciliation', async () => {
    const before = await read();
@@ -299,13 +276,12 @@ describe('local income completeness and exact money (SQLite)', () => {
    const response = await get('all', undefined, false).expect(200);
    expect((response.body as IncomeAnalyticsResourceDto).data).not.toBeNull();
  });
-  it('plans only the selected period for a leap day without scheduling it', async () => {
+  it('distinguishes unavailable calendar comparison without scheduling it', async () => {
    const result = await read('a', 'from=2024-02-29&to=2024-02-29');
-    expect(result.meta.dependencies.map(({ role }) => role)).toEqual([
-      'selected',
-    ]);
-    expect(result.meta.dependencies[0].availability).toBe('temporarily-unavailable');
-    expect(result.data).toBeNull();
+    expect(
+      result.meta.dependencies.find(({ role }) => role === 'year')
+        ?.unavailableReason,
+    ).toBe('CALENDAR_OR_ACCOUNT_HISTORY');
    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
  });
 });
Author	SHA1	Message	Date
ksv741	3d50db7903	ci: validate release PR commits independently (WealthLedger/main#30 ) Backend verify / commits (push) Skipped Details Backend image / publish (push) Successful in 7m28s Details Backend verify / security (push) Successful in 10s Details Backend verify / verify (push) Successful in 5m3s Details Backend verify / commits (pull_request) Successful in 27s Details Backend verify / security (pull_request) Successful in 10s Details Backend verify / verify (pull_request) Successful in 5m11s Details	2026-10-12 23:39:30 +03:00
ksv741	8d5569a3c7	chore(release): 2.1.0 Backend verify / commits (pull_request) Failing after 31s Details Backend verify / security (pull_request) Skipped Details Backend verify / verify (pull_request) Skipped Details	2026-10-12 23:19:12 +03:00