fix: scope income and ledger sync to requested intervals (WealthLedger/backend#57)

Backend patch #129 for WealthLedger/deploy#12. Verified release SHA `0dff4b43773041a73a725fa0b9d0c665eac0cab2`; fast-forward-only main then tag on exact SHA.

---------

Co-authored-by: Sergey Krylov <ksv741@mail.ru>
Reviewed-on: #132
Co-authored-by: codex-bot <codex-bot@ksv741.ru>

.nvmrc

@@ -1 +1 @@
-24.21.0
+24.22.1

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2.3.1](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v2.3.0...v2.3.1) (2026-10-24)
+
+### Bug Fixes
+
+* use available Debian packages in image build ([#129](https://git.personal.ksv741.ru/WealthLedger/backend/issues/129)) ([a250142](https://git.personal.ksv741.ru/WealthLedger/backend/commit/a250142a86e07ec7047e642afa16492fa4987f9a))
+
+## [2.3.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v2.2.0...v2.3.0) (2026-10-24)
+
+### Features
+
+* log unhandled errors and pretty dev output (WealthLedger/backend[#120](https://git.personal.ksv741.ru/WealthLedger/backend/issues/120)) ([#126](https://git.personal.ksv741.ru/WealthLedger/backend/issues/126)) ([966a1f7](https://git.personal.ksv741.ru/WealthLedger/backend/commit/966a1f793aa2087cce3e47750e0017f78315bd64))
+
+### Bug Fixes
+
+* persist refresh cookie across browser restarts (WealthLedger/backend[#123](https://git.personal.ksv741.ru/WealthLedger/backend/issues/123)) ([d1f6969](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d1f6969dc7c22ae3cf7396bccdbf0cea2f61db2e))
+
+### Maintenance
+
+* **deps:** update non-major dependencies [#11](https://git.personal.ksv741.ru/WealthLedger/backend/issues/11) ([449cfcd](https://git.personal.ksv741.ru/WealthLedger/backend/commit/449cfcd6c5a91307012bb3a640c8255ba243cbf5))
+
 ## [2.2.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v2.1.0...v2.2.0) (2026-10-18)
 
 ### Features

Dockerfile

@@ -1,9 +1,9 @@
-FROM node:24.21.0-bookworm-slim AS base
+FROM node:24.22.1-bookworm-slim AS base
 WORKDIR /app
 
 FROM base AS dependencies
 # Native SQLite/bcrypt builds happen only here; compilers stay out of runtime.
-RUN apt-get update && apt-get install -y --no-install-recommends python3=3.11.2-1+b1 make=4.3-4.1 g++=4:12.2.0-3 ca-certificates=20250419~deb12u1 openssl=3.0.20-1~deb12u2 && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ ca-certificates openssl && rm -rf /var/lib/apt/lists/*
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY . .
@@ -11,7 +11,7 @@ RUN npx --no-install prisma generate
 
 FROM dependencies AS development
 # Nest watch uses ps to stop the previous process tree before restarting.
-RUN apt-get update && apt-get install -y --no-install-recommends procps=2:4.0.2-3 && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends procps && rm -rf /var/lib/apt/lists/*
 RUN mkdir /data && chown node:node /data && chown -R node:node /app
 USER node
 ENV NODE_ENV=development DATABASE_URL=file:/data/wealthledger.db
@@ -23,7 +23,7 @@ FROM dependencies AS build
 RUN npx --no-install nest build && npm prune --omit=dev --omit=optional
 
 FROM base AS production
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates=20250419~deb12u1 openssl=3.0.20-1~deb12u2 && rm -rf /var/lib/apt/lists/* \
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates openssl && rm -rf /var/lib/apt/lists/* \
     && mkdir /data && chown node:node /data
 ARG VERSION
 ARG REVISION

eslint-suppressions.json

@@ -92,11 +92,8 @@
     }
   },
   "src/modules/investments/investment-sync-plan.ts": {
-    "sonarjs/cognitive-complexity": {
-      "count": 1
-    },
     "sonarjs/no-nested-conditional": {
-      "count": 4
+      "count": 3
     }
   },
   "src/modules/investments/operations/application/brokerage-operations.service.ts": {

eslint.config.mjs

@@ -37,7 +37,7 @@ export default defineConfig(
     linterOptions: { reportUnusedDisableDirectives: 'error' },
     settings: {
       'import-x/resolver-next': [createTypeScriptImportResolver()],
-      'node': { tryExtensions: ['.ts', '.js', '.json', '.node'], version: '24.21.0' },
+      'node': { tryExtensions: ['.ts', '.js', '.json', '.node'], version: '24.22.1' },
     },
     rules: {
       'curly': ['error', 'multi-line'],
@@ -56,6 +56,7 @@ export default defineConfig(
         'after',
         { overrides: { '?': 'before', ':': 'before' } },
       ],
+      'import-x/no-cycle': 'error',
       'import-x/no-duplicates': ['error', { 'prefer-inline': true }],
     },
   },
@@ -211,4 +212,24 @@ export default defineConfig(
       '@typescript-eslint/no-unsafe-enum-comparison': 'error',
     },
   },
+  {
+    files: ['src/**/*.ts'],
+    ignores: [...tests, 'src/modules/investments/tbank-sync/**'],
+    rules: {
+      // Separate rule so it does not replace layer-specific no-restricted-imports configs.
+      'import-x/no-restricted-paths': ['error', {
+        zones: [{
+          target: './src',
+          from: './src/modules/investments/tbank-sync',
+          except: [
+            './tbank-sync.api.ts',
+            './tbank-sync.dto.ts',
+            './tbank-sync.module.ts',
+            './tbank-sync-repository.module.ts',
+          ],
+          message: 'Use tbank-sync.api for cross-module access.',
+        }],
+      }],
+    },
+  },
 );

package.json

@@ -1,12 +1,12 @@
 {
   "name": "wealth-ledger-backend",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "",
   "author": "",
   "private": true,
   "license": "UNLICENSED",
   "engines": {
-    "node": "v24.21.0"
+    "node": "v24.22.1"
   },
   "scripts": {
     "build": "prisma generate && nest build",
@@ -39,17 +39,17 @@
     "test:lint": "node --test test/eslint-config.cjs"
   },
   "dependencies": {
-    "@grpc/grpc-js": "1.14.5",
+    "@grpc/grpc-js": "1.14.6",
     "@grpc/proto-loader": "0.8.1",
-    "@nestjs/common": "12.0.1",
-    "@nestjs/config": "12.0.0",
-    "@nestjs/core": "12.0.1",
-    "@nestjs/jwt": "12.0.1",
+    "@nestjs/common": "12.2.0",
+    "@nestjs/config": "12.0.1",
+    "@nestjs/core": "12.2.0",
+    "@nestjs/jwt": "12.0.3",
     "@nestjs/passport": "12.0.0",
-    "@nestjs/platform-express": "12.0.1",
-    "@nestjs/swagger": "12.0.1",
-    "@prisma/adapter-better-sqlite3": "7.10.0",
-    "@prisma/client": "7.10.0",
+    "@nestjs/platform-express": "12.2.0",
+    "@nestjs/swagger": "12.0.4",
+    "@prisma/adapter-better-sqlite3": "7.10.1",
+    "@prisma/client": "7.10.1",
     "bcrypt": "6.0.0",
     "better-sqlite3": "12.11.1",
     "cheerio": "1.2.0",
@@ -57,67 +57,77 @@
     "class-validator": "0.15.1",
     "cookie-parser": "1.4.7",
     "dotenv": "17.4.2",
-    "lru-cache": "11.5.2",
-    "nestjs-pino": "5.1.0",
+    "lru-cache": "11.5.3",
+    "nestjs-pino": "5.3.1",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "pino-http": "11.0.0",
-    "prisma": "7.10.0",
+    "prisma": "7.10.1",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2"
   },
   "devDependencies": {
-    "@commitlint/cli": "21.2.2",
-    "@commitlint/config-conventional": "21.2.2",
-    "@darraghor/eslint-plugin-nestjs-typed": "7.5.6",
+    "@commitlint/cli": "21.2.4",
+    "@commitlint/config-conventional": "21.2.4",
+    "@darraghor/eslint-plugin-nestjs-typed": "7.5.8",
     "@eslint/js": "10.0.1",
-    "@nestjs/cli": "12.0.0",
-    "@nestjs/schematics": "12.0.1",
-    "@nestjs/testing": "12.0.1",
-    "@release-it/conventional-changelog": "12.0.0",
+    "@nestjs/cli": "12.0.10",
+    "@nestjs/schematics": "12.0.10",
+    "@nestjs/testing": "12.2.0",
+    "@release-it/conventional-changelog": "12.0.2",
     "@stylistic/eslint-plugin": "5.10.0",
     "@types/bcrypt": "6.0.0",
     "@types/cookie-parser": "1.4.10",
     "@types/express": "5.0.6",
     "@types/jest": "30.0.0",
-    "@types/node": "24.13.4",
+    "@types/node": "24.19.2",
     "@types/passport-jwt": "4.0.1",
     "@types/supertest": "7.2.1",
-    "conventional-changelog-conventionalcommits": "10.4.0",
-    "eslint": "10.11.0",
+    "conventional-changelog-conventionalcommits": "10.4.1",
+    "eslint": "10.13.0",
     "eslint-import-resolver-typescript": "4.4.5",
     "eslint-plugin-import-x": "4.17.1",
-    "eslint-plugin-jest": "29.16.6",
-    "eslint-plugin-n": "18.4.0",
-    "eslint-plugin-perfectionist": "5.12.1",
+    "eslint-plugin-jest": "29.17.0",
+    "eslint-plugin-n": "18.5.0",
+    "eslint-plugin-perfectionist": "5.13.0",
     "eslint-plugin-regexp": "3.3.1",
-    "eslint-plugin-security": "4.1.0",
-    "eslint-plugin-sonarjs": "4.2.1",
-    "globals": "17.12.0",
-    "jest": "30.5.1",
-    "release-it": "21.0.2",
-    "supertest": "7.2.2",
-    "ts-jest": "29.4.12",
+    "eslint-plugin-security": "4.2.0",
+    "eslint-plugin-sonarjs": "4.2.2",
+    "globals": "17.13.0",
+    "jest": "30.5.2",
+    "pino-pretty": "13.2.0",
+    "release-it": "21.1.1",
+    "supertest": "7.3.1",
+    "ts-jest": "29.4.15",
     "ts-loader": "9.6.2",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.70.1"
+    "typescript-eslint": "8.72.0"
   },
   "overrides": {
     "proxy-addr": "2.0.8",
+    "express": {
+      "body-parser": "2.4.0"
+    },
     "@nestjs/platform-express": {
-      "multer": "2.4.0"
+      "multer": "2.5.0"
+    },
+    "ajv": {
+      "fast-uri": "3.1.9"
     },
     "@prisma/config@7.10.0": {
       "deepmerge-ts": "8.0.2"
     },
     "release-it": {
-      "basic-ftp": "6.2.1",
-      "undici": "7.29.1"
+      "basic-ftp": "6.2.3",
+      "undici": "7.30.1"
+    },
+    "socks": {
+      "ip-address": "10.7.4"
     },
     "prisma": {
-      "mysql2": "3.24.4"
+      "mysql2": "3.24.6"
     }
   },
   "jest": {

prisma/migrations/20261028080000_reset_inflated_portfolio_value_points/migration.sql

@@ -0,0 +1,4 @@
+-- Points written before WealthLedger/backend#140 counted cash twice (cash balance
+-- plus the mirroring CURRENCY position). Historical compositions and FX rates are
+-- not stored, so the points cannot be recomputed exactly; history restarts here.
+DELETE FROM "TbankPortfolioValuePoint";

src/common/filters/http-exception.filter.spec.ts

@@ -1,24 +1,29 @@
-import { ArgumentsHost } from '@nestjs/common';
+import { ArgumentsHost, BadRequestException } from '@nestjs/common';
 
+import { StructuredLogger } from '../logging/structured-logger.service';
 import { HttpExceptionFilter } from './http-exception.filter';
 
 describe('HttpExceptionFilter', () => {
-  it('does not expose internal error details', () => {
+  const setup = () => {
     const status = jest.fn().mockReturnThis();
     const type = jest.fn().mockReturnThis();
     const json = jest.fn();
     const locals: Record<string, unknown> = {};
-    const filter = new HttpExceptionFilter();
+    const logger = { event: jest.fn() };
+    const filter = new HttpExceptionFilter(logger as unknown as StructuredLogger);
     const host = {
       switchToHttp: () => ({
         getResponse: () => ({ status, type, json, locals }),
       }),
     } as unknown as ArgumentsHost;
+    return { filter, host, status, type, json, locals, logger };
+  };
 
-    filter.catch(
-      new Error('operation failed\npassword: SYNTHETIC_AUDIT_SECRET'),
-      host,
-    );
+  it('logs unhandled errors with name and stack frames but never the message', () => {
+    const { filter, host, status, type, json, locals, logger } = setup();
+    const error = new Error('operation failed\npassword: SYNTHETIC_AUDIT_SECRET');
+
+    filter.catch(error, host);
 
     expect(status).toHaveBeenCalledWith(500);
     expect(type).toHaveBeenCalledWith('application/problem+json');
@@ -27,6 +32,29 @@ describe('HttpExceptionFilter', () => {
       code: 'INTERNAL_SERVER_ERROR',
     });
     expect(locals.publicErrorCode).toBe('INTERNAL_SERVER_ERROR');
-    expect(locals.errorStack).toBeUndefined();
+    expect(logger.event).toHaveBeenCalledTimes(1);
+    const [level, event, fields] = logger.event.mock.calls[0] as [string, string, Record<string, unknown>];
+    expect(level).toBe('error');
+    expect(event).toBe('http.request.unhandled');
+    expect(fields).toMatchObject({ code: 'INTERNAL_SERVER_ERROR', errorName: 'Error' });
+    expect(JSON.stringify(fields)).not.toContain('SYNTHETIC_AUDIT_SECRET');
+    expect(String(fields['errorStack']).split('\n').every((line) => line.startsWith('    at '))).toBe(true);
+  });
+
+  it('logs field pointers without values for validation errors', () => {
+    const { filter, host, status, logger, locals } = setup();
+    const exception = new BadRequestException({
+      message: [
+        { property: 'amount', constraints: { isPositive: 'amount must be positive' }, value: -42 },
+        { property: 'amount', constraints: { min: 'amount too small' }, value: -42 },
+      ],
+    });
+
+    filter.catch(exception, host);
+
+    expect(status).toHaveBeenCalledWith(400);
+    expect(locals.invalidFields).toBe('#/amount');
+    expect(logger.event).not.toHaveBeenCalled();
+    expect(JSON.stringify(locals)).not.toContain('-42');
   });
 });

src/common/filters/http-exception.filter.ts

@@ -10,9 +10,12 @@ import {
 } from '@nestjs/common';
 
 import { HttpErrorCode } from '../error-code';
+import { StructuredLogger } from '../logging/structured-logger.service';
 
 @Catch()
 export class HttpExceptionFilter implements ExceptionFilter {
+  constructor(private readonly logger: StructuredLogger) {}
+
   catch(exception: unknown, host: ArgumentsHost): void {
     const context = host.switchToHttp();
     const response = context.getResponse<Response>();
@@ -31,6 +34,18 @@ export class HttpExceptionFilter implements ExceptionFilter {
       : this.codeFor(status, payload);
     response.locals ??= {};
     response.locals.publicErrorCode = code;
+    if (isValidation) {
+      response.locals.invalidFields = [
+        ...new Set(
+          this.validationErrors(
+            (payload as { message: ValidationError[] }).message,
+          ).map((error) => error.pointer),
+        ),
+      ].join(',');
+    }
+    if (!(exception instanceof HttpException)) {
+      this.logUnhandled(exception, code);
+    }
     response
       .status(status)
       .type('application/problem+json')
@@ -47,6 +62,20 @@ export class HttpExceptionFilter implements ExceptionFilter {
       });
   }
 
+  // ponytail: stack содержит текст message в первой строке; оставляем только кадры, message не пишем.
+  private logUnhandled(exception: unknown, code: string): void {
+    const error = exception instanceof Error ? exception : undefined;
+    const frames = (error?.stack ?? '')
+      .split('\n')
+      .filter((line) => line.startsWith('    at '))
+      .join('\n');
+    this.logger.event('error', 'http.request.unhandled', {
+      code,
+      errorName: error?.name ?? typeof exception,
+      errorStack: frames,
+    });
+  }
+
   private codeFor(status: number, payload: unknown): string {
     if (typeof payload === 'object' && payload !== null && 'code' in payload) {
       const code = (payload as { code?: unknown }).code;

src/common/logging/logging.module.ts

@@ -24,6 +24,7 @@ function completion(request: Request, response: Response, value: { responseTime:
     status: response.statusCode,
     durationMs: Math.round(value.responseTime),
     ...(typeof response.locals.publicErrorCode === 'string' ? { code: response.locals.publicErrorCode } : {}),
+    ...(typeof response.locals.invalidFields === 'string' ? { invalidFields: response.locals.invalidFields } : {}),
   };
 }
 
@@ -31,6 +32,10 @@ export function loggingOptions(config: ConfigService<Environment, true>): Option
   return {
     level: config.getOrThrow('LOG_LEVEL'),
     messageKey: 'message',
+    // ponytail: development-only pretty output; production never loads pino-pretty.
+    ...(process.env['NODE_ENV'] === 'development'
+      ? { transport: { target: 'pino-pretty', options: { colorize: true, singleLine: true, messageKey: 'message' } } }
+      : {}),
     genReqId: (_request, response) => {
       const id = randomUUID();
       response.setHeader('X-Request-ID', id);

src/common/logging/structured-logger.service.ts

@@ -14,9 +14,12 @@ const allowedFields = new Set([
   'count',
   'durationMs',
   'environment',
+  'errorName',
+  'errorStack',
   'found',
   'grpcCode',
   'headersReceived',
+  'invalidFields',
   'method',
   'networkMs',
   'operation',

src/integrations/moex/moex.client.ts

@@ -1,7 +1,7 @@
 import { Injectable, ServiceUnavailableException } from '@nestjs/common';
 import { constants as httpStatus } from 'node:http2';
 
-enum MoexErrorCode { Unavailable = 'MOEX_UNAVAILABLE' }
+export enum MoexErrorCode { Unavailable = 'MOEX_UNAVAILABLE' }
 
 const MIN_PRICE_PERCENT_EXCLUSIVE = 0;
 const FIRST_PAGE_OFFSET = 0;

src/integrations/ncr/ncr-ratings.client.ts

@@ -4,7 +4,7 @@ import { LRUCache } from 'lru-cache';
 
 import { ISO_DATE_LENGTH, ISO_DATE_START } from '../../common/time';
 
-enum NcrErrorCode { Unavailable = 'NCR_UNAVAILABLE' }
+export enum NcrErrorCode { Unavailable = 'NCR_UNAVAILABLE' }
 
 const EXPECTED_REGISTRY_TABLES = 1;
 const RATING_COLUMN = 2;

src/main.ts

@@ -37,7 +37,7 @@ export function configureApp(app: INestApplication): void {
       exceptionFactory: (message) => new BadRequestException({ message }),
     }),
   );
-  app.useGlobalFilters(new HttpExceptionFilter());
+  app.useGlobalFilters(new HttpExceptionFilter(app.get(StructuredLogger)));
   app.enableShutdownHooks();
 }
 

src/modules/auth/application/auth.service.ts

@@ -17,7 +17,7 @@ import { AuthenticationResult, AuthUser, RefreshPayload } from './auth.types';
 const EXPECTED_ROTATED_SESSIONS = 1;
 
 const PASSWORD_HASH_ROUNDS = 12;
-const REFRESH_TTL_MS = 604_800_000;
+export const REFRESH_TTL_MS = 604_800_000;
 
 const ACCESS_TTL = '15m';
 const REFRESH_TTL = '7d';

src/modules/auth/presentation/auth.controller.ts

@@ -22,7 +22,7 @@ import {
 
 import { ApiProblemResponses } from '../../../common/decorators/api-safe-error-response.decorator';
 import { HttpErrorCode } from '../../../common/error-code';
-import { AuthService } from '../application/auth.service';
+import { AuthService, REFRESH_TTL_MS } from '../application/auth.service';
 import { AccessPayload, AuthenticationResult } from '../application/auth.types';
 import { LoginDto, RegisterDto } from './auth.dto';
 import { JwtAuthGuard } from './jwt-auth.guard';
@@ -134,6 +134,7 @@ export class AuthController {
       sameSite: 'lax' as const,
       secure: process.env['NODE_ENV'] !== 'development',
       path: COOKIE_PATH,
+      maxAge: REFRESH_TTL_MS,
     };
   }
 }

src/modules/investments/brokerage-accounts/brokerage-account.dto.ts

@@ -2,12 +2,39 @@ import { ApiProperty } from '@nestjs/swagger';
 
 import { MoneyDto } from '../../../common/money.dto';
 import { InvestmentResourceMetaDto } from '../investment-resource.dto';
+import { PortfolioStructureDto } from '../portfolio/portfolio.api';
 import { HourlySyncStatusDto } from '../tbank-sync/tbank-sync.dto';
 
+export class UnrealizedReturnDto {
+  @ApiProperty()
+  declare currency: string;
+
+  @ApiProperty({ example: '12.345678901' })
+  declare absolute: string;
+
+  @ApiProperty({ example: '100.00' })
+  declare costBasis: string;
+
+  @ApiProperty({ type: String, nullable: true, example: '12.34' })
+  declare percent: null | string;
+
+  @ApiProperty()
+  declare partial: boolean;
+}
+
 export class PortfolioSummaryDto {
   @ApiProperty({ type: MoneyDto, isArray: true })
   declare totalsByCurrency: MoneyDto[];
 
+  @ApiProperty({ type: MoneyDto, isArray: true })
+  declare cashBalances: MoneyDto[];
+
+  @ApiProperty({ type: PortfolioStructureDto })
+  declare structure: PortfolioStructureDto;
+
+  @ApiProperty({ type: UnrealizedReturnDto, isArray: true })
+  declare unrealizedReturnByCurrency: UnrealizedReturnDto[];
+
   @ApiProperty({
     type: 'integer',
     minimum: 0,
@@ -21,6 +48,20 @@ export class PortfolioSummaryDto {
     description: 'Number of non-zero bond positions, not the number of units.',
   })
   declare bondPositionCount: number;
+
+  @ApiProperty({
+    type: 'integer',
+    minimum: 0,
+    description: 'Number of non-zero fund positions, not the number of units.',
+  })
+  declare fundPositionCount: number;
+
+  @ApiProperty({
+    type: 'integer',
+    minimum: 0,
+    description: 'Number of all non-zero positions, not the number of units.',
+  })
+  declare totalPositionCount: number;
 }
 
 export class BrokerageAccountDto {

src/modules/investments/brokerage-accounts/brokerage-accounts.service.spec.ts

@@ -33,6 +33,7 @@ describe('saved brokerage account projection', () => {
   });
 
   it('keeps exact saved totals and independent missing summaries', async () => {
+    const structure = { currencies: [], unvaluedCategories: [] };
     portfolio.saved.mockResolvedValue({
       membership: meta,
       accounts: [
@@ -43,10 +44,12 @@ describe('saved brokerage account projection', () => {
           openedOn: null,
           meta,
           snapshot: {
+            cashBalances: [{ currency: 'RUB', value: '10.000000001' }],
+            structure,
             totalsByCurrency: [
               { currency: 'RUB', value: '100000000.000000001' },
             ],
-            positions: [{ type: 'STOCK' }, { type: 'BOND' }],
+            positions: [{ type: 'STOCK', quantity: '1' }, { type: 'BOND', quantity: '2' }],
           },
         },
         {
@@ -61,15 +64,91 @@ describe('saved brokerage account projection', () => {
     });
     const response = await service.list('owner');
     expect(response.data?.[0].portfolioSummary).toEqual({
+      cashBalances: [{ currency: 'RUB', value: '10.000000001' }],
+      structure,
       totalsByCurrency: [{ currency: 'RUB', value: '100000000.000000001' }],
       stockPositionCount: 1,
       bondPositionCount: 1,
+      fundPositionCount: 0,
+      totalPositionCount: 2,
+      unrealizedReturnByCurrency: [],
     });
     expect(response.data?.[1].portfolioSummary).toBeNull();
     expect(response.meta.availability).toBe('available');
     expect(response.meta.completeness).toBe('complete');
   });
 
+  it('returns an empty summary from an empty saved portfolio', async () => {
+    const structure = { currencies: [], unvaluedPositions: [], unknownValues: [] };
+    portfolio.saved.mockResolvedValueOnce({
+      membership: meta,
+      accounts: [{
+        id: 'empty', name: 'Empty', type: 'BROKERAGE', openedOn: null, meta,
+        snapshot: { cashBalances: [], structure, totalsByCurrency: [], positions: [] },
+      }],
+    });
+
+    expect((await service.list('owner')).data?.[0].portfolioSummary).toEqual({
+      cashBalances: [], structure, totalsByCurrency: [],
+      stockPositionCount: 0, bondPositionCount: 0,
+      fundPositionCount: 0, totalPositionCount: 0,
+      unrealizedReturnByCurrency: [],
+    });
+  });
+
+  it('calculates exact returns by currency, partial data, and zero cost basis', async () => {
+    portfolio.saved.mockResolvedValueOnce({
+      membership: meta,
+      accounts: [{
+        id: 'a', name: 'A', type: 'BROKERAGE', openedOn: null, meta,
+        snapshot: {
+          cashBalances: [], structure: {}, totalsByCurrency: [
+            { currency: 'RUB', value: '100' }, { currency: 'USD', value: '20' },
+          ],
+          positions: [
+            { type: 'STOCK', quantity: '2', averagePurchasePrice: { currency: 'RUB', value: '10.000000001' }, absoluteReturn: { currency: 'RUB', value: '0.000000003' } },
+            { type: 'BOND', quantity: '0.5', averagePurchasePrice: { currency: 'RUB', value: '20' }, absoluteReturn: { currency: 'RUB', value: '1.25' } },
+            { type: 'FUND', quantity: '3', averagePurchasePrice: { currency: 'USD', value: '2.5' }, absoluteReturn: null },
+            { type: 'STOCK', quantity: '4', averagePurchasePrice: { currency: 'USD', value: '0' }, absoluteReturn: { currency: 'USD', value: '2.5' } },
+            { type: 'CURRENCY', quantity: '100', averagePurchasePrice: { currency: 'EUR', value: '1' }, absoluteReturn: { currency: 'EUR', value: '5' } },
+            { type: 'BOND', quantity: '1', currentValue: { currency: 'CNY', value: '7' }, averagePurchasePrice: null, absoluteReturn: null },
+          ],
+        },
+      }],
+    });
+
+    expect((await service.list('owner')).data?.[0].portfolioSummary).toMatchObject({
+      stockPositionCount: 2, bondPositionCount: 2,
+      fundPositionCount: 1, totalPositionCount: 6,
+      unrealizedReturnByCurrency: [
+        { currency: 'CNY', absolute: '0', costBasis: '0', percent: null, partial: true },
+        { currency: 'RUB', absolute: '1.250000003', costBasis: '30.000000002', percent: '4.17', partial: false },
+        { currency: 'USD', absolute: '2.5', costBasis: '0', percent: null, partial: true },
+      ],
+    });
+  });
+
+  it('omits return percent for a currency with short positions', async () => {
+    portfolio.saved.mockResolvedValueOnce({
+      membership: meta,
+      accounts: [{
+        id: 'a', name: 'A', type: 'BROKERAGE', openedOn: null, meta,
+        snapshot: {
+          cashBalances: [], structure: {}, totalsByCurrency: [],
+          positions: [
+            { type: 'STOCK', quantity: '-2', averagePurchasePrice: { currency: 'RUB', value: '100' }, absoluteReturn: { currency: 'RUB', value: '-20' } },
+            { type: 'STOCK', quantity: '1', averagePurchasePrice: { currency: 'USD', value: '10' }, absoluteReturn: { currency: 'USD', value: '1' } },
+          ],
+        },
+      }],
+    });
+
+    expect((await service.list('owner')).data?.[0]?.portfolioSummary?.unrealizedReturnByCurrency).toEqual([
+      { currency: 'RUB', absolute: '-20', costBasis: '-200', percent: null, partial: false },
+      { currency: 'USD', absolute: '1', costBasis: '10', percent: '10', partial: false },
+    ]);
+  });
+
   it('observes the latest hourly walk without starting another one', async () => {
     portfolio.saved.mockResolvedValue({ membership: meta, accounts: [] });
     sync.hourly.mockResolvedValue({

src/modules/investments/brokerage-accounts/brokerage-accounts.service.ts

@@ -1,10 +1,82 @@
 import { Injectable } from '@nestjs/common';
 import { createHash } from 'node:crypto';
 
+import {
+  decimalFromString,
+  divide,
+  formatDecimal,
+  isZero,
+  multiply,
+} from '../../../common/decimal';
 import { investmentResourceMeta } from '../investment-resource.mapper';
-import { PortfolioService } from '../portfolio/portfolio.api';
-import { hourlyAttempt, TbankSyncRepository } from '../tbank-sync/tbank-sync.repository';
-import { BrokerageAccountDto, BrokerageAccountsResourceDto } from './brokerage-account.dto';
+import { sumMoneyByCurrency } from '../portfolio/domain/portfolio-totals';
+import { PortfolioPositionDto, PortfolioService } from '../portfolio/portfolio.api';
+import { hourlyAttempt, TbankSyncRepository } from '../tbank-sync/tbank-sync.api';
+import {
+  BrokerageAccountDto,
+  BrokerageAccountsResourceDto,
+  UnrealizedReturnDto,
+} from './brokerage-account.dto';
+
+const PERCENT_DECIMAL_PLACES = 2;
+const ZERO_QUANTITY = 0n;
+
+function unrealizedReturns(positions: PortfolioPositionDto[]): UnrealizedReturnDto[] {
+  // Cash-like CURRENCY positions must not duplicate the separately returned cash balances.
+  const investments = positions.filter((position) => position.type !== 'CURRENCY');
+  const absolute = sumMoneyByCurrency(
+    investments.flatMap((position) => position.absoluteReturn ? [position.absoluteReturn] : []),
+  );
+  const costs = sumMoneyByCurrency(
+    investments.flatMap((position) =>
+      position.absoluteReturn && position.averagePurchasePrice
+        ? [{
+            currency: position.absoluteReturn.currency,
+            value: formatDecimal(multiply(
+              decimalFromString(position.averagePurchasePrice.value),
+              decimalFromString(position.quantity),
+            )),
+          }]
+        : [],
+    ),
+  );
+  const partial = new Set(
+    investments.flatMap((position) => {
+      const money = position.absoluteReturn
+        ? null
+        : position.averagePurchasePrice ?? position.currentValue;
+      return money ? [money.currency] : [];
+    }),
+  );
+  // A short position has negative cost basis, so a percent would flip sign or net out.
+  const withShorts = new Set(
+    investments.flatMap((position) => {
+      const money = position.absoluteReturn ?? position.averagePurchasePrice ?? position.currentValue;
+      return money && decimalFromString(position.quantity).value < ZERO_QUANTITY ? [money.currency] : [];
+    }),
+  );
+  const currencies = new Set([...absolute, ...costs].map((money) => money.currency));
+  return [...new Set([...currencies, ...partial])]
+    .sort((left, right) => left.localeCompare(right))
+    .map((currency) => {
+      const absoluteReturn = absolute.find((money) => money.currency === currency)?.value ?? '0';
+      const costBasis = costs.find((money) => money.currency === currency)?.value ?? '0';
+      const cost = decimalFromString(costBasis);
+      return {
+        currency,
+        absolute: absoluteReturn,
+        costBasis,
+        percent: isZero(cost) || withShorts.has(currency)
+          ? null
+          : formatDecimal(divide(
+              multiply(decimalFromString(absoluteReturn), decimalFromString('100')),
+              cost,
+              PERCENT_DECIMAL_PLACES,
+            )),
+        partial: partial.has(currency),
+      };
+    });
+}
 
 @Injectable()
 export class BrokerageAccountsService {
@@ -26,12 +98,20 @@ export class BrokerageAccountsService {
             portfolioSummary: account.snapshot
               ? {
                   totalsByCurrency: account.snapshot.totalsByCurrency,
+                  cashBalances: account.snapshot.cashBalances,
+                  structure: account.snapshot.structure,
+                  unrealizedReturnByCurrency: unrealizedReturns(account.snapshot.positions),
                   stockPositionCount: account.snapshot.positions.filter(
                     (position) => position.type === 'STOCK',
                   ).length,
                   bondPositionCount: account.snapshot.positions.filter(
                     (position) => position.type === 'BOND',
                   ).length,
+                  fundPositionCount: account.snapshot.positions.filter(
+                    (position) => position.type === 'FUND',
+                  ).length,
+                  // The snapshot mapper already drops zero-quantity positions.
+                  totalPositionCount: account.snapshot.positions.length,
                 }
               : null,
           }));

src/modules/investments/income/income-period.ts

@@ -8,7 +8,7 @@ import {
   utcDate,
 } from '../investment-calendar';
 
-enum IncomeErrorCode { InvalidPeriod = 'INVALID_INCOME_PERIOD' }
+export enum IncomeErrorCode { InvalidPeriod = 'INVALID_INCOME_PERIOD' }
 
 const MONDAY_WEEKDAY_INDEX = 1;
 const INCLUSIVE_DAY_OFFSET = 1;

src/modules/investments/investment-sync-plan.spec.ts

@@ -1,196 +1,16 @@
-import {
-  accountHistory,
-  ledgerRange,
-  planInvestmentScreen,
-} from './investment-sync-plan';
+import { accountHistory, ledgerRange } from './investment-sync-plan';
 
-describe('screen dependency and history planning', () => {
+// Missing opening dates must not silently narrow the reported history boundary.
+describe('account history boundaries', () => {
   const now = new Date('2026-09-25T12:00:00Z');
-  const context = {
-    membershipKnown: true,
-    accounts: [{ accountId: 'a', openedOn: '2020-01-01' }],
-    instruments: [
-      {
-        uid: 'uid',
-        type: 'STOCK' as const,
-        historyFrom: new Date('2020-01-01Z'),
-      },
-    ],
-  };
-  it('prioritizes discovery, the selected period, then history; Moscow dates are converted once', () => {
-    const plan = planInvestmentScreen(
-      {
-        screen: 'income',
-        accountId: 'a',
-        from: '2024-02-01',
-        to: '2024-02-29',
-      },
-      context,
-      now,
-    );
-    expect(plan.sources[0].kind).toBe('membership');
-    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',
-      ),
-    ).toBe(true);
-    expect(
-      selected.some(
-        (source) => source.to?.toISOString() === '2024-02-29T21:00:00.000Z',
-      ),
-    ).toBe(true);
-    expect(plan.unavailable).toEqual([]);
-    const firstHistory = plan.sources.findIndex(
-      (source) => source.priority === 'history',
-    );
-    expect(
-      plan.sources
-        .slice(firstHistory)
-        .every((source) => source.priority === 'history'),
-    ).toBe(true);
-  });
-  it('force contains only shown dependencies and retains instrument reconciliation predicates', () => {
-    const plan = planInvestmentScreen(
-      {
-        screen: 'stock',
-        instrumentUid: 'uid',
-        from: '2026-01-01',
-        to: '2026-02-01',
-        candlePeriod: 'year',
-      },
-      context,
-      now,
-      true,
-    );
-    expect(plan.sources.map((source) => source.kind)).toEqual(
-      expect.arrayContaining([
-        'membership',
-        'portfolio',
-        'operations',
-        'metadata',
-        'quote',
-        'company',
-        'calendar',
-        'candles',
-      ]),
-    );
-    expect(plan.sources.every((source) => source.priority !== 'history')).toBe(
-      true,
-    );
-    expect(
-      plan.sources
-        .filter((source) => source.kind === 'operations')
-        .every((source) => source.instrumentUid === 'uid'),
-    ).toBe(true);
-    const accounts = planInvestmentScreen(
-      { screen: 'accounts' },
-      context,
-      now,
-      true,
-    );
-    expect(
-      accounts.sources.some((source) => source.kind === 'operations'),
-    ).toBe(false);
-  });
-  it('never invents an account or candle history boundary; discovery gates unknown membership', () => {
-    const unknown = {
-      ...context,
-      accounts: [{ accountId: 'a', openedOn: null }],
-      instruments: [],
-    };
-    expect(accountHistory(unknown.accounts, now)[0].from.toISOString()).toBe(
+  const accounts = [{ accountId: 'a', openedOn: null }];
+
+  it('retains the unknown opening boundary for history and instrument ledger', () => {
+    expect(accountHistory(accounts, now)[0].from.toISOString()).toBe(
       '1970-01-01T00:00:00.000Z',
     );
     expect(
-      ledgerRange(
-        undefined,
-        undefined,
-        'uid',
-        unknown.accounts,
-        now,
-      ).from.toISOString(),
+      ledgerRange(undefined, undefined, 'uid', accounts, now).from.toISOString(),
     ).toBe('1970-01-01T00:00:00.000Z');
-    const plan = planInvestmentScreen(
-      { screen: 'bond', instrumentUid: 'uid', candlePeriod: 'all' },
-      unknown,
-      now,
-    );
-    expect(plan.sources.some((source) => source.kind === 'candles')).toBe(
-      false,
-    );
-    expect(plan.unavailable[0].reason).toBe('history_start_unavailable');
-    expect(
-      planInvestmentScreen(
-        { screen: 'account' },
-        { ...context, membershipKnown: false },
-        now,
-      ).sources,
-    ).toEqual([{ kind: 'membership', priority: 'discovery' }]);
-  });
-  it('keeps UTC event days separate from Moscow instrument calendar days at year rollover', () => {
-    const rollover = new Date('2026-12-31T22:00:00Z');
-    const events = planInvestmentScreen(
-      { screen: 'events' },
-      context,
-      rollover,
-      true,
-    );
-    expect(
-      events.sources.find((source) => source.kind === 'calendar')?.from,
-    ).toEqual(new Date('2026-12-31Z'));
-    const stock = planInvestmentScreen(
-      { screen: 'stock', instrumentUid: 'uid' },
-      context,
-      rollover,
-      true,
-    );
-    expect(
-      stock.sources.find((source) => source.kind === 'calendar'),
-    ).toMatchObject({
-      from: new Date('2022-01-01Z'),
-      to: new Date('2028-01-01Z'),
-    });
-    expect(rollover.toISOString()).toBe('2026-12-31T22:00:00.000Z');
-  });
-
-  it('keeps search queries separate and events scoped to their inclusive period', () => {
-    const search = planInvestmentScreen(
-      { screen: 'stocks', query: ' sber ' },
-      context,
-      now,
-      true,
-    );
-    expect(
-      search.sources.find((source) => source.kind === 'catalog')?.query,
-    ).toBe('SBER');
-    const events = planInvestmentScreen(
-      { screen: 'events', from: '2026-10-01', to: '2026-10-31' },
-      context,
-      now,
-      true,
-    );
-    expect(
-      events.sources.find((source) => source.kind === 'calendar'),
-    ).toMatchObject({
-      from: new Date('2026-10-01Z'),
-      to: new Date('2026-10-31Z'),
-    });
-    expect(events.sources.some((source) => source.kind === 'operations')).toBe(
-      false,
-    );
   });
 });

src/modules/investments/investment-sync-plan.ts

@@ -1,267 +1,11 @@
-import { ISO_DATE_LENGTH, ISO_DATE_START } from '../../common/time';
-import { planIncomePeriod } from './income/income.api';
-import { dateOnlyBounds, moscowDate } from './investment-calendar';
-import {
-  type OperationInterval,
-  operationIntervals,
-} from './operations/domain/operations-sync-plan';
+import type { OperationInterval } from './operations/domain/operations-sync-plan';
 
-const FORECAST_YEARS = 1;
 const JANUARY_INDEX = 0;
 const FIRST_DAY_OF_MONTH = 1;
 const EXCLUSIVE_END_OFFSET_MS = 1;
 const NO_END_OFFSET_MS = 0;
 
-export type InvestmentScreen = {
-  accountId?: string;
-  candlePeriod?: 'all' | 'halfYear' | 'month' | 'year';
-  candleRange?: { from: Date; to: Date };
-  from?: string;
-  instrumentUid?: string;
-  query?: string;
-  screen:
-    | 'account' |
-    'accounts' |
-    'bond' |
-    'bonds' |
-    'events' |
-    'income' |
-    'operations' |
-    'stock' |
-    'stocks';
-  to?: string;
-};
-const defaultEventDays = 30;
-const incomeHistoryYears = 5;
-const candleMonths = { month: 1, halfYear: 6, year: 12 };
-
 type Account = { accountId: string; openedOn: null | string };
-type Instrument = {
-  historyFrom: Date | null;
-  type: 'BOND' | 'STOCK';
-  uid: string;
-};
-type Source = {
-  accountId?: string;
-  from?: Date;
-  instrumentType?: 'BOND' | 'STOCK';
-  instrumentUid?: string;
-  kind:
-    | 'calendar' |
-    'candles' |
-    'catalog' |
-    'company' |
-    'membership' |
-    'metadata' |
-    'metrics' |
-    'operations' |
-    'portfolio' |
-    'quote';
-  priority: 'discovery' | 'history' | 'screen';
-  query?: string;
-  to?: Date;
-};
-
-// Expands screen scope, never credentials or arbitrary caller-supplied jobs.
-// Owners execute their own sources and expand instruments after discovery.
-export function planInvestmentScreen(
-  screen: InvestmentScreen,
-  context: {
-    accounts: Account[];
-    instruments: Instrument[];
-    membershipKnown: boolean;
-  },
-  now: Date,
-  force = false,
-) {
-  const sources: Source[] = [{ kind: 'membership', priority: 'discovery' }];
-  const accounts = context.accounts.filter(
-    (account) =>
-      !screen.accountId ||
-      screen.accountId === 'all' ||
-      account.accountId === screen.accountId,
-  );
-  const unavailable: { reason: string; resourceKey: string }[] = [];
-  const operations = (from: Date, to: Date, instrumentUid?: string) => {
-    const targets = accounts.flatMap((account) =>
-      from < to
-        ? [
-            {
-              accountId: account.accountId,
-              from,
-              to,
-              ...(instrumentUid ? { instrumentUid } : {}),
-            },
-          ]
-        : [],
-    );
-    sources.push(
-      ...operationIntervals(targets).map((range) => ({
-        ...range,
-        kind: 'operations' as const,
-        priority: 'screen' as const,
-      })),
-    );
-  };
-  const portfolio = () =>
-    sources.push(
-      ...accounts.map(({ accountId }) => ({
-        kind: 'portfolio' as const,
-        accountId,
-        priority: 'screen' as const,
-      })),
-    );
-  if (!context.membershipKnown) return { sources, unavailable, now };
-  if (
-    ['account', 'accounts', 'bond', 'events', 'stock'].includes(screen.screen)
-  ) {
-    portfolio();
-  }
-  if (
-    screen.screen === 'operations' ||
-    screen.screen === 'stock' ||
-    screen.screen === 'bond'
-  ) {
-    const range = ledgerRange(
-      screen.from,
-      screen.to,
-      screen.instrumentUid,
-      accounts,
-      now,
-    );
-    operations(range.from, range.to, force ? screen.instrumentUid : undefined);
-  }
-  if (screen.screen === 'account' || screen.screen === 'income') {
-    const period = planIncomePeriod(
-      screen.screen === 'income' ? screen.from : undefined,
-      screen.screen === 'income' ? screen.to : undefined,
-    );
-    const bounds = dateOnlyBounds(period.selected, now);
-    operations(bounds.from, bounds.to);
-    if (screen.screen === 'account') {
-      const range = ledgerRange(
-        screen.from,
-        screen.to,
-        undefined,
-        accounts,
-        now,
-      );
-      operations(range.from, range.to);
-    }
-  }
-  if (screen.screen === 'stocks' || screen.screen === 'bonds') {
-    sources.push({
-      kind: 'catalog',
-      instrumentType: screen.screen === 'stocks' ? 'STOCK' : 'BOND',
-      query: screen.query?.trim().toUpperCase() ?? '',
-      priority: 'screen',
-    });
-  }
-  const instruments = context.instruments.filter(
-    (instrument) =>
-      !screen.instrumentUid || instrument.uid === screen.instrumentUid,
-  );
-  if (
-    screen.instrumentUid &&
-    !instruments.length &&
-    (screen.screen === 'stock' || screen.screen === 'bond')
-  ) {
-    instruments.push({
-      uid: screen.instrumentUid,
-      type: screen.screen === 'stock' ? 'STOCK' : 'BOND',
-      historyFrom: null,
-    });
-  }
-  for (const instrument of instruments) {
-    const identity = {
-      instrumentUid: instrument.uid,
-      instrumentType: instrument.type,
-    };
-    sources.push({ ...identity, kind: 'metadata', priority: 'screen' });
-    if (['bond', 'bonds', 'stock', 'stocks'].includes(screen.screen)) {
-      sources.push({ ...identity, kind: 'quote', priority: 'screen' });
-    }
-    if (screen.screen === 'stock' || screen.screen === 'bond') {
-      sources.push({
-        ...identity,
-        kind: screen.screen === 'stock' ? 'company' : 'metrics',
-        priority: 'screen',
-      });
-      const from = new Date(now);
-      const period = screen.candlePeriod ?? 'month';
-      if (period !== 'all') {
-        // eslint-disable-next-line security/detect-object-injection -- The period belongs to the validated candle-period union.
-        from.setUTCMonth(from.getUTCMonth() - candleMonths[period]);
-      }
-      const range =
-        screen.candleRange ??
-        (period === 'all'
-          ? instrument.historyFrom
-            ? { from: instrument.historyFrom, to: now }
-            : null
-          : { from, to: now });
-      if (range) {
-        sources.push({
-          ...identity,
-          kind: 'candles',
-          ...range,
-          priority: 'screen',
-        });
-      } else {
-        unavailable.push({
-          resourceKey: `candles/${instrument.uid}/all`,
-          reason: 'history_start_unavailable',
-        });
-      }
-    }
-    if (['account', 'bond', 'events', 'stock'].includes(screen.screen)) {
-      const day =
-        screen.screen === 'stock' || screen.screen === 'bond'
-          ? moscowDate(now)
-          : now.toISOString().slice(ISO_DATE_START, ISO_DATE_LENGTH);
-      const from =
-        screen.screen === 'events' && screen.from
-          ? new Date(`${screen.from}T00:00:00Z`)
-          : new Date(`${day}T00:00:00Z`);
-      const to =
-        screen.screen === 'events' && screen.to
-          ? new Date(`${screen.to}T00:00:00Z`)
-          : new Date(from);
-      if (
-        !(screen.screen === 'events' && screen.to) &&
-        screen.screen !== 'stock' &&
-        screen.screen !== 'bond'
-      ) {
-        to.setUTCDate(to.getUTCDate() + defaultEventDays);
-      }
-      if (screen.screen === 'stock' || screen.screen === 'bond') {
-        from.setUTCFullYear(from.getUTCFullYear() - incomeHistoryYears);
-        to.setUTCFullYear(to.getUTCFullYear() + FORECAST_YEARS);
-      }
-      sources.push({
-        ...identity,
-        kind: 'calendar',
-        from,
-        to,
-        priority: 'screen',
-      });
-    }
-  }
-  if (!force && !['bonds', 'stocks'].includes(screen.screen)) {
-    sources.push(
-      ...accountHistory(accounts, now).map((range) => ({
-        ...range,
-        kind: 'operations' as const,
-        priority: 'history' as const,
-      })),
-    );
-  }
-  const priorities = { discovery: 0, screen: 1, history: 2 };
-  sources.sort(
-    (left, right) => priorities[left.priority] - priorities[right.priority],
-  );
-  return { sources, unavailable, now };
-}
 
 export function accountHistory(
   accounts: Account[],

src/modules/investments/operation-category.ts

@@ -0,0 +1,10 @@
+export const operationCategories = [
+  'trade',
+  'income',
+  'tax',
+  'fee',
+  'transfer',
+  'other',
+] as const;
+
+export type OperationCategory = (typeof operationCategories)[number];

src/modules/investments/operations/application/brokerage-operations-sync.service.ts

@@ -6,13 +6,11 @@ import { MILLISECONDS_PER_SECOND } from '../../../../common/time';
 import { isTbankErrorCode, TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
 import { TbankOperationState } from '../../../../integrations/tbank/tbank-protocol';
 import { TbankAccessService, TbankClient } from '../../../../integrations/tbank/tbank.api';
-import { accountHistory } from '../../investment-sync-plan';
 import {
   type OperationInterval,
   operationIntervals,
   operationsSyncPriority,
   planOperationRead,
-  uncoveredOperationIntervals,
 } from '../domain/operations-sync-plan';
 import {
   BrokerageOperationsRepository,
@@ -48,7 +46,6 @@ export class BrokerageOperationsSyncService {
     intervals: OperationInterval[],
     options: {
       force?: boolean;
-      history?: boolean;
       movingEnd?: boolean;
       observe?: boolean;
       revision?: string;
@@ -99,30 +96,6 @@ export class BrokerageOperationsSyncService {
             connection.revision,
           )
         : null;
-    if (!options.observe && !options.force && options.history) {
-      const accountIds = new Set(
-        intervals.map((interval) => interval.accountId),
-      );
-      const history = accountHistory(
-        connection.accounts.filter((account) =>
-          accountIds.has(account.accountId),
-        ),
-        now,
-      );
-      const missing = planOperationRead(history, coverage, now, {
-        movingEnd: true,
-      }).load;
-      const remaining = uncoveredOperationIntervals(missing, targets);
-      if (remaining.length) {
-        await this.request(
-          userId,
-          remaining,
-          false,
-          'history',
-          connection.revision,
-        );
-      }
-    }
     return { plan, handle };
   }
 

src/modules/investments/operations/application/brokerage-operations.service.ts

@@ -6,21 +6,16 @@ import {
   InstrumentMetadataService,
   metadataKey,
   TbankAccessService,
-  TbankMembershipService,
   type TbankOperationItem,
   tbankSourceTtlMs,
 } from '../../../../integrations/tbank/tbank.api';
 import { dateOnlyBounds, DateOnlyRange } from '../../investment-calendar';
 import { investmentResourceMeta } from '../../investment-resource.mapper';
-import {
-  accountHistory,
-  ledgerRange,
-  planInvestmentScreen,
-} from '../../investment-sync-plan';
+import { accountHistory, ledgerRange } from '../../investment-sync-plan';
 import {
   hourlyAttempt,
   TbankSyncRepository,
-} from '../../tbank-sync/tbank-sync.repository';
+} from '../../tbank-sync/tbank-sync.api';
 import { OperationErrorCode } from '../domain/operation-error-code';
 import {
   confirmedOperationRanges,
@@ -37,7 +32,6 @@ import {
 } from '../presentation/brokerage-operation.dto';
 import { BrokerageOperationsSyncService } from './brokerage-operations-sync.service';
 
-const EXCLUSIVE_END_OFFSET_MS = 1;
 const FIRST_RESULT_OFFSET = 0;
 const MISSING_MEMBERSHIP_REVISION = 0;
 const STALE_FRESHNESS_MS = 0;
@@ -61,7 +55,6 @@ export class BrokerageOperationsService {
     private readonly metadata: InstrumentMetadataService,
     private readonly repository: BrokerageOperationsRepository,
     private readonly sync: BrokerageOperationsSyncService,
-    private readonly membership: TbankMembershipService,
     private readonly config: ConfigService,
     private readonly hourlySync: TbankSyncRepository,
   ) {}
@@ -117,35 +110,14 @@ export class BrokerageOperationsService {
       cursor,
     };
     if (cursor) await this.repository.readPage(readInput);
-    const screen = planInvestmentScreen(
-      {
-        screen: 'operations',
-        accountId,
-        from: from.toISOString(),
-        to: new Date(to.valueOf() - EXCLUSIVE_END_OFFSET_MS).toISOString(),
-      },
-      {
-        accounts: selected,
-        instruments: [],
-        membershipKnown: Boolean(connection.membershipAt),
-      },
-      now,
-    );
-    const intervals = screen.sources.flatMap((source) =>
-      source.kind === 'operations' &&
-      source.priority === 'screen' &&
-      source.accountId &&
-      source.from &&
-      source.to
-        ? [{ accountId: source.accountId, from: source.from, to: source.to }]
-        : [],
+    const intervals = selected.flatMap((account) =>
+      from < to ? [{ accountId: account.accountId, from, to }] : [],
     );
     // The ledger only starts the first-time load of missing intervals; the
     // mutable tail belongs to the hourly walk and membership is not rechecked.
     if (intervals.length) {
       await this.sync.readPlan(userId, intervals, {
         movingEnd,
-        history: true,
         revision: connection.revision,
       });
     }
@@ -406,32 +378,19 @@ export class BrokerageOperationsService {
       periods: ranges,
     };
     let saved = await this.repository.readPage(input);
-    const schedule = async () => {
-      const current = await this.access.local(userId, accountId);
-      if (current.revision !== connection.revision) return;
-      const snapshot = await this.repository.readPage(input);
-      if (!snapshot?.connection.membershipAt) return;
-      const targets = snapshot.connection.accounts.flatMap((account) =>
-        (snapshot.periods ?? []).map((period) => ({
+    if (!observe) {
+      const targets = (saved?.connection.accounts ?? []).flatMap((account) =>
+        (saved?.periods ?? []).map((period) => ({
           accountId: account.accountId,
           ...period,
         })),
       );
       if (targets.length) {
         await this.sync.readPlan(userId, targets, {
-          movingEnd: snapshot.periods?.some((period) => period.movingEnd),
-          history: true,
+          movingEnd: saved?.periods?.some((period) => period.movingEnd),
           revision: connection.revision,
         });
       }
-    };
-    if (!observe) {
-      const discovery = await this.membership.request(
-        userId,
-        connection.revision,
-      );
-      if (discovery) void discovery.done.then(schedule).catch(() => undefined);
-      else await schedule();
       saved = await this.repository.readPage(input);
     }
     const now = new Date();

src/modules/investments/operations/infrastructure/brokerage-operation.mapper.ts

@@ -3,10 +3,8 @@ import { MILLISECONDS_PER_SECOND } from '../../../../common/time';
 import { decimal } from '../../../../integrations/tbank/decimal';
 import { TbankOperationType } from '../../../../integrations/tbank/tbank-protocol';
 import { TbankMoney, TbankOperationItem } from '../../../../integrations/tbank/tbank.api';
-import {
-  BrokerageOperationDto,
-  OperationCategory,
-} from '../presentation/brokerage-operation.dto';
+import { type OperationCategory } from '../../operation-category';
+import { BrokerageOperationDto } from '../presentation/brokerage-operation.dto';
 
 const MISSING_TIMESTAMP_COMPONENT = 0;
 

src/modules/investments/operations/operations.api.ts

@@ -5,4 +5,3 @@ export type { OperationInterval } from './domain/operations-sync-plan';
 
 // Public cross-module surface. Nest providers are exported by the matching module.
 export { BrokerageOperationDto } from './presentation/brokerage-operation.dto';
-export { operationCategories } from './presentation/brokerage-operation.dto';

src/modules/investments/operations/presentation/brokerage-operation.dto.ts

@@ -16,6 +16,7 @@ import {
 import { MoneyDto } from '../../../../common/money.dto';
 import { AccountReferenceDto } from '../../account-reference.dto';
 import { InvestmentResourceMetaDto } from '../../investment-resource.dto';
+import { operationCategories, type OperationCategory } from '../../operation-category';
 
 const MIN_OPERATIONS_PAGE_SIZE = 1;
 
@@ -23,16 +24,6 @@ const MAX_CURSOR_LENGTH = 4096;
 const MAX_OPERATIONS_PAGE_SIZE = 1000;
 export const DEFAULT_OPERATIONS_PAGE_SIZE = 100;
 
-export const operationCategories = [
-  'trade',
-  'income',
-  'tax',
-  'fee',
-  'transfer',
-  'other',
-] as const;
-export type OperationCategory = (typeof operationCategories)[number];
-
 export class BrokerageOperationsQueryDto {
   @ApiPropertyOptional({
     format: 'uuid',

src/modules/investments/portfolio/application/portfolio.service.spec.ts

@@ -159,6 +159,31 @@ describe('persistent portfolio projection', () => {
     expect(snapshot.positions[1].averagePurchasePrice).toEqual({ currency: 'RUB', value: '2' });
   });
 
+  it('counts cash once when T-Bank also returns it as a CURRENCY position', async () => {
+    repository.reserve.mockResolvedValueOnce({
+      launch: true,
+      work: { id: 'work', attemptId: 'attempt' },
+    });
+    tbank.getPortfolio.mockResolvedValue({ positions: [
+      { figi: 'FUND', instrumentType: 'etf', quantity: { units: '1' }, currentPrice: { currency: 'RUB', units: '120', nano: 240000000 } },
+      { figi: 'RUB000UTSTOM', instrumentType: 'currency', quantity: { units: '1', nano: 250000000 }, currentPrice: { currency: 'RUB', units: '1' } },
+    ] });
+    tbank.getPositions.mockResolvedValue({ money: [{ currency: 'RUB', units: '1', nano: 250000000 }] });
+    repository.read.mockResolvedValue({
+      membershipAt,
+      membershipRevision: 1,
+      accounts: [{ accountId: 'a', name: 'A', type: 'BROKERAGE', openedOn: null, portfolio: null }],
+      work: [],
+    });
+    const handle = await service.request('user', 'private', 'a');
+    assert(handle);
+    await handle.done;
+    const snapshot = (repository.publish.mock.calls as [unknown, string, PortfolioDto][])[0][2];
+    expect(snapshot.totalsByCurrency).toEqual([{ currency: 'RUB', value: '121.49' }]);
+    expect(snapshot.positions.map((position) => position.type)).toEqual(['FUND', 'CURRENCY']);
+    expect(snapshot.structure.currencies[0].totalValue).toBe('121.49');
+  });
+
   it('does not turn a missing account snapshot into aggregate zero; summaries stay independent', async () => {
     const snapshot: PortfolioDto = {
       lastSuccessfulAt: membershipAt.toISOString(),

src/modules/investments/portfolio/application/portfolio.service.ts

@@ -20,7 +20,7 @@ import { investmentResourceMeta } from '../../investment-resource.mapper';
 import {
   hourlyAttempt,
   TbankSyncRepository,
-} from '../../tbank-sync/tbank-sync.repository';
+} from '../../tbank-sync/tbank-sync.api';
 import { portfolioStructure } from '../domain/portfolio-structure';
 import { sumMoneyByCurrency } from '../domain/portfolio-totals';
 import {

src/modules/investments/portfolio/domain/portfolio-structure.spec.ts

@@ -19,7 +19,7 @@ const position = (
 });
 
 describe('portfolio structure', () => {
-  it('includes cash once and keeps currency instruments among other assets', () => {
+  it('counts cash once and skips CURRENCY positions that mirror it', () => {
     const result = portfolioStructure(
       [
         position('STOCK', '60'),
@@ -30,13 +30,13 @@ describe('portfolio structure', () => {
     );
     expect(result.currencies[0]).toEqual({
       currency: 'RUB',
-      totalValue: '100',
+      totalValue: '90',
       hasNegativeValues: false,
       categories: [
-        { type: 'STOCK', value: '60', sharePercent: '60' },
-        { type: 'BOND', value: '20', sharePercent: '20' },
-        { type: 'OTHER', value: '10', sharePercent: '10' },
-        { type: 'CASH', value: '10', sharePercent: '10' },
+        { type: 'STOCK', value: '60', sharePercent: '66.666667' },
+        { type: 'BOND', value: '20', sharePercent: '22.222222' },
+        { type: 'OTHER', value: '0', sharePercent: '0' },
+        { type: 'CASH', value: '10', sharePercent: '11.111111' },
       ],
     });
   });

src/modules/investments/portfolio/domain/portfolio-structure.ts

@@ -43,6 +43,8 @@ export function portfolioStructure(
     currencies.set(money.currency, group);
   };
   for (const position of positions) {
+    // CURRENCY positions mirror cash, which is counted once as CASH below.
+    if (position.type === 'CURRENCY') continue;
     const type = ['BOND', 'STOCK'].includes(position.type)
       ? position.type
       : 'OTHER';

src/modules/investments/portfolio/infrastructure/tbank-portfolio.mapper.ts

@@ -126,7 +126,8 @@ function totalsByCurrency(
   for (const value of money) addTotal(value.currency, decimal(value));
   for (const position of positions) {
     const price = position.currentPrice;
-    if (!price) continue;
+    // CURRENCY positions mirror the cash balances already added above.
+    if (!price || types[position.instrumentType?.toLowerCase() ?? ''] === 'CURRENCY') continue;
     addTotal(
       price.currency,
       multiply(decimal(position.quantity ?? {}), decimal(price)),

src/modules/investments/portfolio/portfolio.api.ts

@@ -5,4 +5,5 @@ export { PortfolioService } from './application/portfolio.service';
 export {
   PortfolioDto,
   PortfolioPositionDto,
+  PortfolioStructureDto,
 } from './presentation/portfolio.dto';

src/modules/investments/tbank-sync/tbank-sync.api.ts

@@ -0,0 +1 @@
+export { hourlyAttempt, TbankSyncRepository } from './tbank-sync.repository';

src/modules/investments/tbank-sync/tbank-sync.dto.ts

@@ -23,7 +23,7 @@ import {
 
 import { MAX_INSTRUMENT_QUERY_LENGTH, MIN_INSTRUMENT_QUERY_LENGTH } from '../instrument-query';
 import { InvestmentAttemptProblemDto } from '../investment-resource.dto';
-import { operationCategories } from '../operations/operations.api';
+import { operationCategories } from '../operation-category';
 
 const MIN_ACCOUNT_ID_LENGTH = 1;
 const MIN_SYNC_PAGE_SIZE = 1;

src/modules/investments/upcoming-events/upcoming-events.service.ts

@@ -24,7 +24,7 @@ import {
 import {
   hourlyAttempt,
   TbankSyncRepository,
-} from '../tbank-sync/tbank-sync.repository';
+} from '../tbank-sync/tbank-sync.api';
 import { bondEvent, dividendEvent } from './upcoming-event.mapper';
 import {
   UpcomingEventDto,
@@ -32,7 +32,7 @@ import {
   UpcomingEventsQueryDto,
 } from './upcoming-events.dto';
 
-enum EventsErrorCode { InvalidPeriod = 'INVALID_EVENTS_PERIOD' }
+export enum EventsErrorCode { InvalidPeriod = 'INVALID_EVENTS_PERIOD' }
 
 const FIRST_BATCH_OFFSET = 0;
 

src/openapi.ts

@@ -1,12 +1,38 @@
 import { INestApplication } from '@nestjs/common';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 
+import { HttpErrorCode } from './common/error-code';
+import { MoexErrorCode } from './integrations/moex/moex.client';
+import { NcrErrorCode } from './integrations/ncr/ncr-ratings.client';
+import { TbankErrorCode } from './integrations/tbank/tbank-error-code';
+import { AuthErrorCode } from './modules/auth/application/auth-error-code';
+import { BankErrorCode } from './modules/banking/bank-cards/application/bank-card-input';
+import { IncomeErrorCode } from './modules/investments/income/income-period';
+import { InstrumentErrorCode } from './modules/investments/instruments/domain/instrument-error-code';
+import { OperationErrorCode } from './modules/investments/operations/domain/operation-error-code';
+import { EventsErrorCode } from './modules/investments/upcoming-events/upcoming-events.service';
+
 export const API_PREFIX = 'api/v1';
 
 // Nest Swagger cannot express additionalProperties on a class, so closed request
 // bodies are restored here after generation; the runtime allowlist stays in the controller.
 const CLOSED_SCHEMAS = ['StockScreenerCriteriaDto'];
 
+// Every code HttpExceptionFilter can emit. Assembled at the composition root so
+// common/ProblemDetailsDto does not depend on modules.
+export const PROBLEM_CODES = [
+  ...Object.values(HttpErrorCode),
+  ...Object.values(AuthErrorCode),
+  ...Object.values(OperationErrorCode),
+  ...Object.values(InstrumentErrorCode),
+  ...Object.values(TbankErrorCode),
+  ...Object.values(BankErrorCode),
+  ...Object.values(MoexErrorCode),
+  ...Object.values(NcrErrorCode),
+  ...Object.values(EventsErrorCode),
+  ...Object.values(IncomeErrorCode),
+];
+
 export function createOpenApiDocument(app: INestApplication) {
   const document = SwaggerModule.createDocument(
     app,
@@ -18,5 +44,8 @@ export function createOpenApiDocument(app: INestApplication) {
       schema.additionalProperties = false;
     }
   }
+  const problem = schemas.ProblemDetailsDto;
+  const problemCode = problem && 'properties' in problem ? problem.properties?.code : undefined;
+  if (problemCode && !('$ref' in problemCode)) problemCode.enum = PROBLEM_CODES;
   return document;
 }

test/app.e2e-spec.ts

@@ -32,6 +32,7 @@ describe('Authentication (e2e)', () => {
         pinoHttp: {
           ...loggingOptions(config),
           level: 'info',
+          transport: undefined,
           stream: { write: (line: string) => logs.push(JSON.parse(line) as Record<string, unknown>) },
         },
         assignResponse: true,
@@ -131,6 +132,9 @@ describe('Authentication (e2e)', () => {
         .filter((attribute) => !attribute.startsWith('Expires='))
         .sort((a, b) => a.localeCompare(b));
     const host = ['HttpOnly', 'Path=/api/v1/auth', 'SameSite=Lax'];
+    // Persistent for the Session lifetime (7 days), otherwise the browser drops it on restart.
+    const persistent = [...host, 'Max-Age=604800'];
+    const sorted = (items: string[]) => [...items].sort((a, b) => a.localeCompare(b));
     const login = async () => {
       const registration = await request(app.getHttpServer())
         .post('/api/v1/auth/register')
@@ -150,7 +154,7 @@ describe('Authentication (e2e)', () => {
       }
     };
 
-    it('issues, rotates and clears it HttpOnly, Lax, path-scoped, host-only and Secure in production', async () => {
+    it('issues and rotates it persistent (Max-Age) HttpOnly, Lax, path-scoped, host-only and Secure in production, and clears it', async () => {
       await inEnvironment('production', async () => {
         const issued = await login();
         const rotated = await request(app.getHttpServer())
@@ -162,16 +166,20 @@ describe('Authentication (e2e)', () => {
           .set('Cookie', rotated.headers['set-cookie'][0])
           .expect(204);
 
-        // Exact set: any added Domain/Max-Age or a dropped flag fails.
-        for (const cookie of [issued, rotated.headers['set-cookie'][0], cleared.headers['set-cookie'][0]]) {
-          expect(attributes(cookie)).toEqual([...host, 'Secure'].sort((a, b) => a.localeCompare(b)));
+        // Exact set: any added Domain, changed Max-Age or dropped flag fails.
+        for (const cookie of [issued, rotated.headers['set-cookie'][0]]) {
+          expect(attributes(cookie)).toEqual(sorted([...persistent, 'Secure']));
         }
+        // Clearing must not carry Max-Age; Express expires it with a past Expires.
+        const clearedCookie = cleared.headers['set-cookie'][0];
+        expect(attributes(clearedCookie)).toEqual(sorted([...host, 'Secure']));
+        expect(clearedCookie).toContain('Expires=Thu, 01 Jan 1970');
       });
     });
 
     it('drops only Secure in development and keeps every other attribute', async () => {
       await inEnvironment('development', async () => {
-        expect(attributes(await login())).toEqual(host);
+        expect(attributes(await login())).toEqual(sorted(persistent));
       });
     });
   });
@@ -532,7 +540,14 @@ describe('Authentication (e2e)', () => {
       'X-Request-ID',
     );
     expect(logs.filter((entry) => entry.requestId === response.headers['x-request-id'])).toEqual([
-      expect.objectContaining({ level: 40, message: 'http.request.completed', status: 401, code: 'UNAUTHORIZED' }),
+      expect.objectContaining({
+        level: 40,
+        message: 'http.request.completed',
+        method: 'GET',
+        route: '/api/v1/auth/me',
+        status: 401,
+        code: 'UNAUTHORIZED',
+      }),
     ]);
   });
 
@@ -544,7 +559,7 @@ describe('Authentication (e2e)', () => {
         new Error('operation failed\npassword: SYNTHETIC_AUDIT_SECRET'),
       );
 
-    const response = await request(app.getHttpServer())
+    await request(app.getHttpServer())
       .post('/api/v1/auth/login')
       .set('X-Request-ID', clientRequestId)
       .send({ email: 'user@example.com', password: 'a secure password' })
@@ -554,17 +569,30 @@ describe('Authentication (e2e)', () => {
         expect(body).toEqual({ status: 500, code: 'INTERNAL_SERVER_ERROR' }),
       );
 
-    const completed = logs.filter((entry) => entry.requestId === response.headers['x-request-id']);
-    expect(completed).toEqual([
-      expect.objectContaining({
-        requestId: response.headers['x-request-id'],
-        clientRequestId,
-        status: 500,
-        code: 'INTERNAL_SERVER_ERROR',
-        level: 50,
-        message: 'http.request.completed',
-      }),
-    ]);
+    expect(logs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          method: 'POST',
+          route: '/api/v1/auth/login',
+          status: 500,
+          code: 'INTERNAL_SERVER_ERROR',
+          level: 50,
+          message: 'http.request.completed',
+        }),
+      ]),
+    );
+    expect(logs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          clientRequestId,
+          code: 'INTERNAL_SERVER_ERROR',
+          level: 50,
+          message: 'http.request.unhandled',
+          errorName: 'Error',
+          errorStack: expect.stringContaining('    at ') as unknown,
+        }),
+      ]),
+    );
     expect(JSON.stringify(logs)).not.toContain(
       'SYNTHETIC_AUDIT_SECRET',
     );

test/openapi-contract.e2e-spec.ts

@@ -121,6 +121,55 @@ describe('OpenAPI contract (integration)', () => {
     expect(analytics.properties).not.toHaveProperty('yearComparison');
   });
 
+  it('publishes every emitted problem detail code as a named enum', () => {
+    const schemas = createOpenApiDocument(app).components?.schemas;
+    const expectedCodes = [
+      'BAD_REQUEST',
+      'INTERNAL_SERVER_ERROR',
+      'NOT_FOUND',
+      'UNAUTHORIZED',
+      'UNSUPPORTED_MEDIA_TYPE',
+      'VALIDATION_ERROR',
+      'EMAIL_ALREADY_REGISTERED',
+      'INVALID_CREDENTIALS',
+      'INVALID_OPERATIONS_CURSOR',
+      'BOND_HISTORY_START_UNAVAILABLE',
+      'BOND_TICKER_AMBIGUOUS',
+      'STOCK_HISTORY_START_UNAVAILABLE',
+      'STOCK_TICKER_AMBIGUOUS',
+      'INVALID_TBANK_TOKEN',
+      'TBANK_NOT_CONNECTED',
+      'TBANK_UNAVAILABLE',
+      'BANK_CARD_ARCHIVED',
+      'BANK_DEPENDENT_REFUNDS',
+      'BANK_DUPLICATE_CATEGORY',
+      'BANK_IMMUTABLE_OPERATION',
+      'BANK_INTENT_CONFLICT',
+      'BANK_INVALID_DATE',
+      'BANK_INVALID_INPUT',
+      'BANK_INVALID_MONEY',
+      'BANK_INVALID_REFUND',
+      'BANK_NOT_FOUND',
+      'BANK_OPENING_DATE_CONFLICT',
+      'BANK_OPERATION_DELETED',
+      'BANK_REFUND_LIMIT',
+      'BANK_VERSION_CONFLICT',
+      'BANK_WRITE_CONFLICT',
+      'MOEX_UNAVAILABLE',
+      'NCR_UNAVAILABLE',
+      'INVALID_EVENTS_PERIOD',
+      'INVALID_INCOME_PERIOD',
+    ];
+
+    const problem = schemas?.ProblemDetailsDto;
+    assert(problem && !('$ref' in problem));
+    const codeSchema = problem.properties?.code;
+    assert(codeSchema && !('$ref' in codeSchema));
+    expect(codeSchema.type).toBe('string');
+    expect(codeSchema.enum).toEqual(expect.arrayContaining(expectedCodes));
+    expect(codeSchema.enum).toHaveLength(expectedCodes.length);
+  });
+
   it('generates the runtime contract without server startup or deployment configuration', async () => {
     const schemas = createOpenApiDocument(app).components?.schemas;
     expect(schemas?.StockScreenerCriteriaDto).toMatchObject({

test/tbank-income-local.e2e-spec.ts

@@ -297,6 +297,58 @@ describe('local income completeness and exact money (SQLite)', () => {
     expect(result.data?.calculatedAt).toBe('2025-02-01T00:00:00.000Z');
     expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
   });
+  it('ordinary covered income reads local data without membership or operations RPC', async () => {
+    await prisma.tbankConnection.update({
+      where: { userId: 'income-owner' },
+      data: { membershipAt: new Date('2020-01-01Z') },
+    });
+    const response = await get('a', undefined, false).expect(200);
+    const result = response.body as IncomeAnalyticsResourceDto;
+    expect(result.data).not.toBeNull();
+    expect(result.meta.completeness).toBe('complete');
+    expect(upstream.getOpenAccounts).not.toHaveBeenCalled();
+    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
+  });
+  it('cold income imports only the missing requested interval', async () => {
+    await prisma.tbankConnection.update({
+      where: { userId: 'income-owner' },
+      data: { membershipAt: new Date('2020-01-01Z') },
+    });
+    let release: () => void = () => {
+      throw new Error('Upstream not initialized');
+    };
+    const blocked = new Promise<{ hasNext: boolean; items: never[] }>((resolve) => {
+      release = () => resolve({ hasNext: false, items: [] });
+    });
+    upstream.getOperationsByCursor.mockReturnValue(blocked);
+    const first = await get('a', 'from=2025-02-01&to=2025-02-28', false).expect(200);
+    const cold = first.body as IncomeAnalyticsResourceDto;
+    release();
+    expect(cold.data).toBeNull();
+    expect(cold.meta.completeness).toBe('incomplete');
+    let result: IncomeAnalyticsResourceDto = cold;
+    for (let attempt = 0; attempt < 100; attempt++) {
+      const response = await get('a', 'from=2025-02-01&to=2025-02-28').expect(200);
+      result = response.body as IncomeAnalyticsResourceDto;
+      if (result.meta.completeness === 'complete') break;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    expect(result.data).not.toBeNull();
+    expect(result.meta.completeness).toBe('complete');
+    expect(upstream.getOpenAccounts).not.toHaveBeenCalled();
+    expect(upstream.getOperationsByCursor.mock.calls).toEqual([
+      ['synthetic', expect.objectContaining({
+        accountId: 'a',
+        from: { seconds: '1738357199' },
+        to: { seconds: '1738368001' },
+      })],
+      ['synthetic', expect.objectContaining({
+        accountId: 'a',
+        from: { seconds: '1738367999' },
+        to: { seconds: '1740776401' },
+      })],
+    ]);
+  });
   it('returns while a cold upstream is blocked and validates access/period before scheduling', async () => {
     await get('absent', undefined, false).expect(404);
     await get('a', 'from=2025-02-31&to=2025-03-01', false).expect(400);

test/tbank-ledger-local.e2e-spec.ts

@@ -113,6 +113,50 @@ describe('persistent ledger HTTP and cursor (SQLite)', () => {
       }
     }
   });
+  it.each([
+    'from=2099-01-01',
+    'from=2025-03-01&to=2025-02-01',
+  ])('empty ledger range %s returns 200 without upstream RPC', async (query) => {
+    const response = await request(app.getHttpServer())
+      .get(`/api/v1/brokerage-accounts/a/operations?${query}`)
+      .set('Authorization', auth())
+      .expect(200);
+    const result = response.body as BrokerageOperationsResourceDto;
+    expect(result.data?.items).toEqual([]);
+    expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
+  });
+  it('cold ledger imports only the missing requested interval', async () => {
+    upstream.getOperationsByCursor.mockResolvedValue({
+      hasNext: false,
+      items: [],
+    });
+    await put().expect(200);
+    await request(app.getHttpServer())
+      .get('/api/v1/brokerage-accounts/a/operations?from=2025-02-01&to=2025-02-28')
+      .set('Authorization', auth())
+      .expect(200);
+    let complete = false;
+    for (let attempt = 0; attempt < 100; attempt++) {
+      const response = await request(app.getHttpServer())
+        .get('/api/v1/brokerage-accounts/a/operations?from=2025-02-01&to=2025-02-28&sync=observe')
+        .set('Authorization', auth())
+        .expect(200);
+      const result = response.body as BrokerageOperationsResourceDto;
+      complete = result.meta.completeness === 'complete';
+      if (complete) break;
+      await delay(10);
+    }
+    expect(complete).toBe(true);
+    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(1);
+    expect(upstream.getOperationsByCursor).toHaveBeenCalledWith(
+      'synthetic',
+      expect.objectContaining({
+        accountId: 'a',
+        from: { seconds: '1738367999' },
+        to: { seconds: '1740787201' },
+      }),
+    );
+  });
   it('reads ordered pages with identical IDs/timestamps across accounts and no upstream RPC, including after reopen', async () => {
     let cursor: null | string = null;
     const ids: string[] = [];
@@ -409,7 +453,7 @@ describe('persistent ledger HTTP and cursor (SQLite)', () => {
     const result = (await get('sync=observe', 'a').expect(200))
       .body as BrokerageOperationsResourceDto;
     expect(result.meta.coverage?.historyBoundary).toBe('unknown');
-    expect(result.meta.coverage?.historyState).toBe('loading');
+    expect(result.meta.coverage?.historyState).toBe('missing');
   }, 30_000);
 
   it('returns cold missing while upstream is blocked, then confirms an empty interval; observe never retries failure', async () => {

test/tbank-local-reads.e2e-spec.ts

@@ -216,7 +216,27 @@ describe('local accounts and portfolio HTTP (SQLite)', () => {
     ).toEqual({
       stockPositionCount: 1,
       bondPositionCount: 0,
+      fundPositionCount: 0,
+      totalPositionCount: 1,
       totalsByCurrency: [{ currency: 'RUB', value: '21.100000002' }],
+      cashBalances: [{ currency: 'RUB', value: '1.1' }],
+      structure: {
+        currencies: [{
+          currency: 'RUB',
+          totalValue: '21.100000002',
+          hasNegativeValues: false,
+          categories: [
+            { type: 'STOCK', value: '20.000000002', sharePercent: '94.78673' },
+            { type: 'BOND', value: '0', sharePercent: '0' },
+            { type: 'OTHER', value: '0', sharePercent: '0' },
+            { type: 'CASH', value: '1.1', sharePercent: '5.21327' },
+          ],
+        }],
+        unvaluedCategories: [],
+      },
+      unrealizedReturnByCurrency: [
+        { currency: 'RUB', absolute: '0', costBasis: '0', percent: null, partial: true },
+      ],
     });
     const portfolio = await get('brokerage-accounts/account/portfolio').expect(
       200,
@@ -492,9 +512,18 @@ describe('local accounts and portfolio HTTP (SQLite)', () => {
     }
     const summaries = (await get('brokerage-accounts?sync=observe').expect(200))
       .body as BrokerageAccountsResourceDto;
-    expect(summaries.data?.[0].portfolioSummary?.totalsByCurrency).toEqual([
-      { currency: 'RUB', value: '21.1' },
-    ]);
+    expect(summaries.data?.[0].portfolioSummary).toMatchObject({
+      totalsByCurrency: [{ currency: 'RUB', value: '21.1' }],
+      cashBalances: [{ currency: 'RUB', value: '1.1' }],
+      structure: { currencies: [{ currency: 'RUB' }] },
+      unrealizedReturnByCurrency: [
+        { currency: 'RUB', absolute: '0', costBasis: '0', percent: null, partial: true },
+      ],
+      stockPositionCount: 1,
+      bondPositionCount: 0,
+      fundPositionCount: 0,
+      totalPositionCount: 1,
+    });
     expect(summaries.data?.[1].portfolioSummary).toBeNull();
     expect(summaries.meta.availability).toBe('available');
     expect(summaries.meta.completeness).toBe('complete');