refactor: tidy tbank-sync claim comments (WealthLedger/backend#166 )

refactor: share tbank-sync claim and generation lock (WealthLedger/backend#166 )
refactor(api): describe bank operation create body as oneOf by kind (WealthLedger/backend#172) (#173 )
2026-11-04 17:59:42 +03:00 · 2026-11-04 17:59:35 +03:00 · 2026-11-04 17:47:36 +03:00 · 2026-11-03 22:53:54 +03:00 · 2026-11-03 14:07:40 +03:00 · 2026-11-03 12:04:10 +03:00
83 changed files with 3282 additions and 2278 deletions
@@ -67,7 +67,7 @@ jobs:
      - name: Audit runtime and development dependencies
        run: |
          npm audit --omit=dev --audit-level=low
-          npm audit --include=dev --audit-level=high --ignore-advisory=GHSA-hp3w-g68c-fv3c
+          npm audit --include=dev --audit-level=high

  verify:
    needs: [commits, security]
@@ -1 +1 @@
-24.21.0
+24.22.1
@@ -1,5 +1,50 @@
 # Changelog

+## [2.4.0](https://git.personal.ksv741.ru/WealthLedger/backend/compare/v2.3.1...v2.4.0) (2026-11-01)
+
+### Features
+
+* extend account list portfolio summary ([#138](https://git.personal.ksv741.ru/WealthLedger/backend/issues/138)) ([97fc41f](https://git.personal.ksv741.ru/WealthLedger/backend/commit/97fc41fa295a7a943a27171fa41cdaf286632956))
+* **portfolio:** store and publish instrument sector and issuer (WealthLedger/main[#48](https://git.personal.ksv741.ru/WealthLedger/backend/issues/48)) ([#148](https://git.personal.ksv741.ru/WealthLedger/backend/issues/148)) ([17432df](https://git.personal.ksv741.ru/WealthLedger/backend/commit/17432dfee3d7d06841caea4419a062e2a4bfc82c))
+
+### Bug Fixes
+
+* count brokerage cash once and skip short-position return percent (WealthLedger/backend[#140](https://git.personal.ksv741.ru/WealthLedger/backend/issues/140)) ([f2843e3](https://git.personal.ksv741.ru/WealthLedger/backend/commit/f2843e30bda5442158ec145cc63a5491506bb60f))
+* reset portfolio value points inflated by double-counted cash (WealthLedger/backend[#140](https://git.personal.ksv741.ru/WealthLedger/backend/issues/140)) ([2325b63](https://git.personal.ksv741.ru/WealthLedger/backend/commit/2325b638839240bf5d6d4f7e6e1f8eaa82d4d7fd))
+* scope income and ledger sync to requested intervals (WealthLedger/backend[#57](https://git.personal.ksv741.ru/WealthLedger/backend/issues/57)) ([#147](https://git.personal.ksv741.ru/WealthLedger/backend/issues/147)) ([5e84e1e](https://git.personal.ksv741.ru/WealthLedger/backend/commit/5e84e1e5f1943b5af1992a3a946194b27fc1a1d5))
+* 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))
+
+### Refactoring
+
+* expose tbank-sync public api and guard its boundary (WealthLedger/backend[#118](https://git.personal.ksv741.ru/WealthLedger/backend/issues/118)) ([#143](https://git.personal.ksv741.ru/WealthLedger/backend/issues/143)) ([5295945](https://git.personal.ksv741.ru/WealthLedger/backend/commit/5295945ab237a6e94aa64d7bb54bfd04554ca9f9))
+* publish typed problem detail codes (WealthLedger/backend[#117](https://git.personal.ksv741.ru/WealthLedger/backend/issues/117)) ([#144](https://git.personal.ksv741.ru/WealthLedger/backend/issues/144)) ([d37fa2c](https://git.personal.ksv741.ru/WealthLedger/backend/commit/d37fa2c9034e90e9d22d4022c45fc36c22dd2ab3))
+* remove tbank-sync operations import cycle (WealthLedger/backend[#116](https://git.personal.ksv741.ru/WealthLedger/backend/issues/116)) ([#142](https://git.personal.ksv741.ru/WealthLedger/backend/issues/142)) ([22668da](https://git.personal.ksv741.ru/WealthLedger/backend/commit/22668da3fa0666bdd22737913379c99d4cf01993))
+
+### Tests
+
+* cover portfolio publish rollback and claim fence (WealthLedger/backend[#105](https://git.personal.ksv741.ru/WealthLedger/backend/issues/105)) ([#146](https://git.personal.ksv741.ru/WealthLedger/backend/issues/146)) ([e350146](https://git.personal.ksv741.ru/WealthLedger/backend/commit/e350146749293f2eaf8060f7626ff3c1cd8edf2c))
+* replace operations sync delays with explicit barriers (WealthLedger/backend[#104](https://git.personal.ksv741.ru/WealthLedger/backend/issues/104)) ([#145](https://git.personal.ksv741.ru/WealthLedger/backend/issues/145)) ([99b137e](https://git.personal.ksv741.ru/WealthLedger/backend/commit/99b137ed0b39ab73b6a28d1a494d2d98bf8fa380))
+
+## [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
@@ -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
@@ -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": {
@@ -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.',
+        }],
+      }],
+    },
+  },
 );
@@ -1,12 +1,12 @@
 {
  "name": "wealth-ledger-backend",
-  "version": "2.2.0",
+  "version": "2.4.0",
  "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": {
@@ -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";
@@ -0,0 +1,11 @@
+CREATE TABLE "TbankInstrumentClassification" (
+    "provider" TEXT NOT NULL,
+    "instrumentKey" TEXT NOT NULL,
+    "sector" TEXT,
+    "sectorFetchedAt" DATETIME,
+    "assetUid" TEXT,
+    "brandUid" TEXT,
+    "brandName" TEXT,
+    "brandFetchedAt" DATETIME,
+    PRIMARY KEY ("provider","instrumentKey")
+);
@@ -186,6 +186,20 @@ model TbankInstrumentLookup {
  @@id([provider, identifierType, identifier])
 }

+// Public per-instrument classification; no holdings or credentials.
+model TbankInstrumentClassification {
+  provider        String
+  instrumentKey   String
+  sector          String?
+  sectorFetchedAt DateTime?
+  assetUid        String?
+  brandUid        String?
+  brandName       String?
+  brandFetchedAt  DateTime?
+
+  @@id([provider, instrumentKey])
+}
+
 // Source records contain no holdings, personal estimates or credentials errors.
 model TbankInstrumentSource {
  provider String
@@ -2,7 +2,8 @@
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
-    ":semanticCommitTypeAll(chore)"
+    ":semanticCommitTypeAll(chore)",
+    "security:minimumReleaseAgeNpm"
  ],
  "timezone": "Europe/Moscow",
  "labels": [
@@ -10,6 +11,13 @@
  ],
  "dependencyDashboard": true,
  "rangeStrategy": "pin",
+  "prConcurrentLimit": 5,
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": [
+      "before 4am on the first day of the month"
+    ]
+  },
  "packageRules": [
    {
      "matchUpdateTypes": [
@@ -18,6 +26,27 @@
      ],
      "groupName": "non-major dependencies"
    },
+    {
+      "matchManagers": [
+        "github-actions"
+      ],
+      "matchUpdateTypes": [
+        "minor",
+        "patch"
+      ],
+      "groupName": "non-major github actions"
+    },
+    {
+      "matchManagers": [
+        "docker-compose",
+        "dockerfile"
+      ],
+      "matchUpdateTypes": [
+        "minor",
+        "patch"
+      ],
+      "groupName": "non-major container images"
+    },
    {
      "matchUpdateTypes": [
        "major"
@@ -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');
  });
 });
@@ -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;
@@ -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);
@@ -14,9 +14,12 @@ const allowedFields = new Set([
  'count',
  'durationMs',
  'environment',
+  'errorName',
+  'errorStack',
  'found',
  'grpcCode',
  'headersReceived',
+  'invalidFields',
  'method',
  'networkMs',
  'operation',
@@ -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;
@@ -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;
@@ -7,11 +7,12 @@ import type {
  TbankInstrument as MetadataRow,
  Prisma,
 } from '../../../generated/prisma/client';
-import type { TbankSyncAttempt } from './tbank-access.service';
 import type { TbankInstrument } from './tbank.client';

 import { PrismaService } from '../../prisma/prisma.service';
+import { isJoinableRunningAttempt, type TbankSyncAttempt } from './tbank-access.service';
 import { TbankErrorCode } from './tbank-error-code';
+import { claimSyncWork, lockConnectionGeneration } from './tbank-sync-claim';

 const FIRST_BATCH_OFFSET = 0;
 const UNCHANGED_REVISION_INCREMENT = 0;
@@ -119,11 +120,8 @@ export class InstrumentMetadataRepository {
    active: ReadonlySet<string>,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const valid = await tx.tbankConnection.updateMany({
-        where: { ...attemptOwner, invalidToken: false },
-        data: { membershipRevision: { increment: 0 } },
-      });
-      if (!valid.count) return null;
+      const valid = await lockConnectionGeneration(tx, attemptOwner);
+      if (!valid) return null;
      const scope = {
        ...attemptOwner,
        scopeKey: `metadata:${metadataKey(identity)}`,
@@ -131,11 +129,7 @@ export class InstrumentMetadataRepository {
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
-      if (
-        previous?.state === 'running' &&
-        previous.processRunId === runId &&
-        active.has(previous.attemptId)
-      ) {
+      if (isJoinableRunningAttempt(previous, runId, active)) {
        return { work: previous, launch: false };
      }
      const data = {
@@ -171,15 +165,11 @@ export class InstrumentMetadataRepository {

  publish(attempt: TbankSyncAttempt, results: MetadataLookup[], now: Date) {
    return this.prisma.$transaction(async (tx) => {
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { state: 'complete', progress: {} },
+      const claimed = await claimSyncWork(tx, attempt, {
+        state: 'complete',
+        progress: {},
      });
-      if (!claimed.count) return false;
+      if (!claimed) return false;
      const aliases = new Map(
        results.map((result) => [`${result.type}:${result.id}`, result]),
      );
@@ -268,18 +258,17 @@ export class InstrumentMetadataRepository {
  }

  async finishObserver(attempt: TbankSyncAttempt, success: boolean) {
-    await this.prisma.tbankSyncWork.updateMany({
-      where: {
-        ...attempt,
-        state: 'running',
-        ...(success ? { connection: { invalidToken: false } } : {}),
-      },
-      data: {
+    await claimSyncWork(
+      this.prisma,
+      attempt,
+      {
        state: success ? 'complete' : 'failed',
        errorCode: success ? null : TbankErrorCode.Unavailable,
      },
-    });
+      { withoutConnectionFence: !success },
+    );
    if (success) {
+      // Fails sibling attempts whose connection was invalidated mid-flight.
      await this.prisma.tbankSyncWork.updateMany({
        where: {
          ...attempt,
@@ -12,6 +12,7 @@ import { PrismaService } from '../../prisma/prisma.service';
 import { supportedTbankAccounts } from './tbank-account.policy';
 import { TbankErrorCode } from './tbank-error-code';
 import { tbankSourceNeedsRefresh } from './tbank-source.policy';
+import { claimSyncWork, lockConnectionGeneration } from './tbank-sync-claim';
 import { TbankTokenService } from './tbank-token.service';

 const EXPECTED_UPDATED_CONNECTIONS = 1;
@@ -25,6 +26,22 @@ export type TbankSyncAttempt = {
  userId: string;
 };

+// Join rule shared by sync reservations: the same process joins its own running attempt
+// only while that attempt is still active in memory. Set and Map both satisfy `has`.
+export function isJoinableRunningAttempt<
+  T extends { attemptId: string; processRunId: string; state: string },
+>(
+  previous: null | T,
+  processRunId: string,
+  active: { has(attemptId: string): boolean },
+): previous is T {
+  return (
+    previous?.state === 'running' &&
+    previous.processRunId === processRunId &&
+    active.has(previous.attemptId)
+  );
+}
+
@Injectable()
 export class TbankAccessService {
  constructor(
@@ -40,11 +57,8 @@ export class TbankAccessService {
    force: boolean,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const current = await tx.tbankConnection.updateMany({
-        where: { userId, revision, invalidToken: false },
-        data: { membershipRevision: { increment: 0 } },
-      });
-      if (!current.count) return null;
+      const current = await lockConnectionGeneration(tx, { userId, revision });
+      if (!current) return null;
      const connection = await tx.tbankConnection.findUniqueOrThrow({
        where: { userId },
      });
@@ -62,11 +76,7 @@ export class TbankAccessService {
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
-      if (
-        previous?.state === 'running' &&
-        previous.processRunId === processRunId &&
-        active.has(previous.attemptId)
-      ) {
+      if (isJoinableRunningAttempt(previous, processRunId, active)) {
        return { work: previous, launch: false };
      }
      const data = {
@@ -98,15 +108,11 @@ export class TbankAccessService {

  async failMembership(attempt: TbankSyncAttempt, invalidToken: boolean) {
    if (invalidToken) return this.rejectMembershipToken(attempt);
-    const result = await this.prisma.tbankSyncWork.updateMany({
-      where: {
-        ...attempt,
-        state: 'running',
-        connection: { invalidToken: false },
-      },
-      data: { state: 'failed', errorCode: TbankErrorCode.Unavailable },
+    const result = await claimSyncWork(this.prisma, attempt, {
+      state: 'failed',
+      errorCode: TbankErrorCode.Unavailable,
    });
-    return result.count === EXPECTED_UPDATED_CONNECTIONS;
+    return result === EXPECTED_UPDATED_CONNECTIONS;
  }

  async tokenForAttempt(attempt: TbankSyncAttempt): Promise<null | string> {
@@ -151,15 +157,8 @@ export class TbankAccessService {
    return this.prisma.$transaction(async (tx) => {
      // Acquire the write fence before reading membership. Replacement and
      // attempt supersession cannot interleave with the publication below.
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { updatedAt: new Date() },
-      });
-      if (!claimed.count) return false;
+      const claimed = await claimSyncWork(tx, attempt, { updatedAt: new Date() });
+      if (!claimed) return false;
      const { userId, revision } = attempt;
      const previous = await tx.tbankAccount.findMany({
        where: { userId, revision },
@@ -232,11 +231,11 @@ export class TbankAccessService {

  async rejectMembershipToken(attempt: TbankSyncAttempt): Promise<boolean> {
    return this.prisma.$transaction(async (tx) => {
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: { ...attempt, state: 'running' },
-        data: { state: 'failed', errorCode: TbankErrorCode.InvalidToken },
-      });
-      if (!claimed.count) return false;
+      const claimed = await claimSyncWork(tx, attempt, {
+        state: 'failed',
+        errorCode: TbankErrorCode.InvalidToken,
+      }, { withoutConnectionFence: true });
+      if (!claimed) return false;
      await tx.tbankConnection.update({
        where: {
          userId_revision: {
@@ -0,0 +1,53 @@
+import type { Prisma } from '../../../generated/prisma/client';
+import type { TbankSyncAttempt } from './tbank-access.service';
+
+const NO_UPDATED_ROWS = 0;
+
+// Shared owners for the tbank-sync DB claim/lock protocol.
+// Both helpers are CAS fences: they run inside the caller's transaction and
+// keep the exact where/data shapes they replaced. Callers keep deciding
+// success from the claim count exactly as before.
+
+// Claims the active TbankSyncWork row: only the still-running attempt of a
+// valid connection may transition. `data` is the state transition to apply.
+export type ClaimOptions = {
+  // Overrides the default 'running' fence (e.g. an initiator row also
+  // accepts 'complete').
+  state: Prisma.TbankSyncWorkWhereInput['state'] | undefined;
+  // true drops the `connection: { invalidToken: false }` guard for fences
+  // that must also fire on an invalidated connection.
+  withoutConnectionFence: boolean | undefined;
+};
+export async function claimSyncWork(
+  tx: Prisma.TransactionClient,
+  attempt: TbankSyncAttempt,
+  data: Prisma.TbankSyncWorkUpdateManyMutationInput,
+  options: Partial<ClaimOptions> = {},
+): Promise<number> {
+  const result = await tx.tbankSyncWork.updateMany({
+    where: {
+      ...attempt,
+      state: options.state ?? 'running',
+      ...(options.withoutConnectionFence
+        ? {}
+        : { connection: { invalidToken: false } }),
+    },
+    data,
+  });
+  return result.count;
+}
+
+// Locks the connection generation before reserving or publishing work: the
+// row must still be the current revision with a valid token. `extra`
+// (e.g. account membership) is merged into the where clause.
+export async function lockConnectionGeneration(
+  tx: Prisma.TransactionClient,
+  owner: { revision: string; userId: string },
+  extra: Prisma.TbankConnectionWhereInput = {},
+): Promise<boolean> {
+  const result = await tx.tbankConnection.updateMany({
+    where: { ...owner, ...extra, invalidToken: false },
+    data: { membershipRevision: { increment: 0 } },
+  });
+  return result.count > NO_UPDATED_ROWS;
+}
@@ -3,6 +3,7 @@ export { InstrumentMetadataService } from './instrument-metadata.service';
 export { metadataKey } from './instrument-metadata.service';
 export type { MetadataIdentity } from './instrument-metadata.service';
 export {
+  isJoinableRunningAttempt,
  TbankAccessService,
  type TbankSyncAttempt,
 } from './tbank-access.service';
@@ -236,6 +236,16 @@ describe('TbankClient metadata retries', () => {
    jest.useRealTimers();
  });

+  it.each([
+    ['bondBy', (client: TbankClient, optIn: boolean) => client.getBond('token', 'uid', undefined, optIn)],
+    ['etfBy', (client: TbankClient, optIn: boolean) => client.getEtf('token', 'uid', undefined, optIn)],
+    ['getAssetBy', (client: TbankClient, optIn: boolean) => optIn ? client.getAssetBrand('token', 'uid') : client.getAssetDescription('token', 'uid')],
+  ])('%s reports NOT_FOUND only for classification lookups', async (_method, invoke) => {
+    requestRpc.mockRejectedValue({ code: status.NOT_FOUND });
+    await expect(invoke(client, false)).rejects.toBeInstanceOf(ServiceUnavailableException);
+    await expect(invoke(client, true)).rejects.toBeInstanceOf(NotFoundException);
+  });
+
  it.each([
    status.UNAVAILABLE,
    status.DEADLINE_EXCEEDED,
@@ -375,18 +375,29 @@ export class TbankClient {
    ).then((response) => response.instruments ?? []);
  }

-  getBond(token: string, uid: string): Promise<null | TbankBond> {
+  getBond(token: string, uid: string, idType = InstrumentIdType.Uid, notFound = false): Promise<null | TbankBond> {
    return this.call<{ instrument?: TbankBond }>(
      token,
      this.sparseInstruments,
      'bondBy',
      {
-        idType: InstrumentIdType.Uid,
+        idType,
        id: uid,
      },
+      notFound,
    ).then((response) => response.instrument ?? null);
  }

+  getEtf(
+    token: string,
+    id: string,
+    idType = InstrumentIdType.Uid,
+    notFound = false,
+  ): Promise<null | Pick<TbankShare, 'assetUid' | 'figi' | 'sector' | 'uid'>> {
+    return this.call<{ instrument?: TbankShare }>(token, this.sparseInstruments, 'etfBy', { idType, id }, notFound)
+      .then((response) => response.instrument ?? null);
+  }
+
  getBondCoupons(
    token: string,
    uid: string,
@@ -405,18 +416,25 @@ export class TbankClient {
    ).then((response) => response.events ?? []);
  }

-  getShare(token: string, uid: string): Promise<null | TbankShare> {
+  getShare(token: string, uid: string, idType = InstrumentIdType.Uid, notFound = false): Promise<null | TbankShare> {
    return this.call<{ instrument?: TbankShare }>(
      token,
      this.instruments,
      'shareBy',
      {
-        idType: InstrumentIdType.Uid,
+        idType,
        id: uid,
      },
+      notFound,
    ).then((response) => response.instrument ?? null);
  }

+  getAssetBrand(token: string, assetUid: string): Promise<null | { assetUid?: string; brand?: { name?: string; uid?: string } }> {
+    return this.call<{ asset?: { brand?: { name?: string; uid?: string }; uid?: string } }>(
+      token, this.instruments, 'getAssetBy', { id: assetUid }, true,
+    ).then((response) => response.asset ? { assetUid: response.asset.uid, brand: response.asset.brand } : null);
+  }
+
  getAssetDescription(token: string, assetUid: string): Promise<null | string> {
    return this.call<{ asset?: { description?: string } }>(
      token,
@@ -514,6 +532,7 @@ export class TbankClient {
    client: TbankClientService,
    method: string,
    request: object,
+    notFound = false,
  ): Promise<Response> {
    const metadataCall = method === 'getInstrumentBy';
    for (let attempts = FIRST_ATTEMPT; attempts <= RPC_MAX_ATTEMPTS; attempts += ATTEMPT_INCREMENT) {
@@ -576,7 +595,7 @@ export class TbankClient {
        }
        if (
          grpcCode === status.NOT_FOUND &&
-          (method === 'shareBy' || metadataCall)
+          (notFound || method === 'shareBy' || metadataCall)
        ) {
          throw new NotFoundException();
        }
@@ -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();
 }

@@ -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';
@@ -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,
    };
  }
 }
@@ -1,6 +1,7 @@
 import {
  ApiProperty,
  ApiPropertyOptional,
+  getSchemaPath,
  IntersectionType,
  OmitType,
  PartialType,
@@ -153,6 +154,49 @@ export class CreateBankOperationDto {
  @MaxLength(MAX_OPERATION_DESCRIPTION_LENGTH)
  description?: string;
 }
+
+// OpenAPI-only variants. Runtime validation stays on CreateBankOperationDto so
+// invalid combinations keep the existing BANK_INVALID_INPUT response.
+class BankOperationCreateBaseDto extends OmitType(CreateBankOperationDto, [
+  'kind', 'targetCardId', 'categoryId', 'originalExpenseId',
+] as const) {}
+
+export class CreateExpenseOperationDto extends BankOperationCreateBaseDto {
+  @ApiProperty({ enum: [BankOperationKind.Expense] }) declare kind: 'expense';
+  @ApiPropertyOptional({ format: 'uuid' }) declare categoryId?: string;
+}
+
+export class CreateTopupOperationDto extends BankOperationCreateBaseDto {
+  @ApiProperty({ enum: [BankOperationKind.Topup] }) declare kind: 'topup';
+}
+
+export class CreateTransferOperationDto extends BankOperationCreateBaseDto {
+  @ApiProperty({ enum: [BankOperationKind.Transfer] }) declare kind: 'transfer';
+  @ApiProperty({ format: 'uuid' }) declare targetCardId: string;
+}
+
+export class CreateRefundOperationDto extends BankOperationCreateBaseDto {
+  @ApiProperty({ enum: [BankOperationKind.Refund] }) declare kind: 'refund';
+  @ApiProperty({ format: 'uuid' }) declare originalExpenseId: string;
+}
+
+export const createBankOperationSchema = {
+  oneOf: [
+    CreateExpenseOperationDto,
+    CreateTopupOperationDto,
+    CreateTransferOperationDto,
+    CreateRefundOperationDto,
+  ].map((model) => ({ $ref: getSchemaPath(model) })),
+  discriminator: {
+    propertyName: 'kind',
+    mapping: {
+      expense: getSchemaPath(CreateExpenseOperationDto),
+      topup: getSchemaPath(CreateTopupOperationDto),
+      transfer: getSchemaPath(CreateTransferOperationDto),
+      refund: getSchemaPath(CreateRefundOperationDto),
+    },
+  },
+};
 export class UpdateBankOperationDto extends PartialType(
  OmitType(CreateBankOperationDto, ['id'] as const),
  { skipNullProperties: false },
@@ -16,7 +16,9 @@ import {
 } from '@nestjs/common';
 import {
  ApiBearerAuth,
+  ApiBody,
  ApiCreatedResponse,
+  ApiExtraModels,
  ApiNoContentResponse,
  ApiOkResponse,
  ApiResponse,
@@ -46,6 +48,11 @@ import {
  CategoryNameDto,
  CreateBankCardDto,
  CreateBankOperationDto,
+  createBankOperationSchema,
+  CreateExpenseOperationDto,
+  CreateRefundOperationDto,
+  CreateTopupOperationDto,
+  CreateTransferOperationDto,
  ExpenseCategoryDto,
  UpdateBankCardDto,
  UpdateBankOperationDto,
@@ -73,6 +80,12 @@ type AuthRequest = Request & { user: AccessPayload };
  },
 })
@ApiTags('bank-cards')
+@ApiExtraModels(
+  CreateExpenseOperationDto,
+  CreateTopupOperationDto,
+  CreateTransferOperationDto,
+  CreateRefundOperationDto,
+)
@ApiBearerAuth()
@ApiProblemResponses()
@UseGuards(JwtAuthGuard)
@@ -131,6 +144,7 @@ export class BankCardsController {
  }

  @Post('operations')
+  @ApiBody({ schema: createBankOperationSchema })
  @ApiCreatedResponse({ type: BankOperationDto })
  createOperation(
    @Req() req: AuthRequest,
@@ -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 {
@@ -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({
@@ -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,
          }));
@@ -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;
@@ -110,6 +110,7 @@ export class CatalogEnrichmentService {
      tickers?: Record<string, string>;
      to: string;
    },
+    refreshBefore?: Date,
  ) {
    const { revision } = await this.access.local(userId);
    const inputs = sourceInputs(instrumentType, uids, kinds, range);
@@ -123,6 +124,7 @@ export class CatalogEnrichmentService {
        false,
        kinds,
        range,
+        refreshBefore,
      );
    }
    const work = inputs.length
@@ -175,6 +177,7 @@ export class CatalogEnrichmentService {
      tickers?: Record<string, string>;
      to: string;
    },
+    refreshBefore?: Date,
  ) {
    const inputs = sourceInputs(instrumentType, uids, kinds, range);
    const reservation = this.reservations.then(async () => {
@@ -189,7 +192,9 @@ export class CatalogEnrichmentService {
        );
        const policy = sourcePolicy(input.kind);
        const needsRefresh = force || !row?.fetchedAt ||
-          (policy === 'quote' && tbankSourceNeedsRefresh('quote', row.fetchedAt, new Date()));
+          (policy === 'quote' && tbankSourceNeedsRefresh('quote', row.fetchedAt, new Date())) ||
+          // A walk reads a saved calendar once: later accounts see the new fetchedAt.
+          (policy === 'calendar' && refreshBefore !== undefined && row.fetchedAt < refreshBefore);
        if (!needsRefresh) {
          continue;
        }
@@ -665,6 +670,7 @@ function sourcePolicy(kind: CatalogSource['kind']) {
  ) {
    return 'quote';
  }
+  if (['bond-events', 'dividends'].includes(kind)) return 'calendar';
  return 'stable';
 }
 function producerKey(input: CatalogSource) {
@@ -22,6 +22,8 @@ const row = (
  isin: null,
  ticker: null,
  logoName: null,
+  sector: null,
+  issuer: null,
 });
 const portfolio = (positions: PortfolioPositionDto[]): PortfolioDto => ({
  positions,
@@ -2,8 +2,15 @@ import { Injectable } from '@nestjs/common';
 import { createHash, randomUUID } from 'node:crypto';

 import type { Prisma } from '../../../../../generated/prisma/client';
-import type { TbankSyncAttempt } from '../../../../integrations/tbank/tbank.api';

+import {
+  claimSyncWork,
+  lockConnectionGeneration,
+} from '../../../../integrations/tbank/tbank-sync-claim';
+import {
+  isJoinableRunningAttempt,
+  type TbankSyncAttempt,
+} from '../../../../integrations/tbank/tbank.api';
 import { PrismaService } from '../../../../prisma/prisma.service';
 import {
  type CandleRange,
@@ -62,34 +69,30 @@ export class CandleRepository {
    priority = 1,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const current = await tx.tbankConnection.updateMany({
-        where: { ...owner, invalidToken: false },
-        data: { membershipRevision: { increment: 0 } },
-      });
-      if (!current.count) return null;
+      const current = await lockConnectionGeneration(tx, owner);
+      if (!current) return null;
      const scope = { ...owner, scopeKey };
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
-      if (
-        previous?.state === 'running' &&
-        previous.processRunId === runId &&
-        active.has(previous.attemptId)
-      ) {
-        const previousIntent = previous.intent as Prisma.JsonObject;
+      const joinable = isJoinableRunningAttempt(previous, runId, active)
+        ? previous
+        : null;
+      if (joinable) {
+        const previousIntent = joinable.intent as Prisma.JsonObject;
        const previousNow =
          typeof previousIntent.now === 'string' ? previousIntent.now : '';
-        const nextPriority = Math.min(previous.priority, priority);
+        const nextPriority = Math.min(joinable.priority, priority);
        if (
-          nextPriority === previous.priority &&
+          nextPriority === joinable.priority &&
          (!intent.force ||
            (previousIntent.force === true &&
              (!intent.now || intent.now <= previousNow)))
        ) {
-          return { work: previous, launch: false };
+          return { work: joinable, launch: false };
        }
        const work = await tx.tbankSyncWork.update({
-          where: { id: previous.id },
+          where: { id: joinable.id },
          data: {
            priority: nextPriority,
            intent: {
@@ -163,15 +166,10 @@ export class CandleRepository {
      ).values(),
    ];
    return this.prisma.$transaction(async (tx) => {
-      const valid = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { progress: { lastWindow: key } },
+      const valid = await claimSyncWork(tx, attempt, {
+        progress: { lastWindow: key },
      });
-      if (!valid.count) return false;
+      if (!valid) return false;
      const identity = {
        workId: attempt.id,
        attemptId: attempt.attemptId,
@@ -196,18 +194,11 @@ export class CandleRepository {
    completeWork = true,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: {
-          ...(completeWork ? { state: 'complete' } : {}),
-          errorCode: null,
-        },
+      const claimed = await claimSyncWork(tx, attempt, {
+        ...(completeWork ? { state: 'complete' } : {}),
+        errorCode: null,
      });
-      if (!claimed.count) return false;
+      if (!claimed) return false;
      const staged = await tx.tbankSyncStage.findMany({
        where: {
          workId: attempt.id,
@@ -311,28 +302,17 @@ export class CandleRepository {
        },
      });
      if (!origin) return false;
-      const result = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { state: 'complete', errorCode: null },
+      const result = await claimSyncWork(tx, attempt, {
+        state: 'complete',
+        errorCode: null,
      });
-      return result.count > NO_UPDATED_ROWS;
+      return result > NO_UPDATED_ROWS;
    });
  }

  fail(attempt: TbankSyncAttempt, errorCode: string) {
    return this.prisma.$transaction(async (tx) => {
-      await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { state: 'failed', errorCode },
-      });
+      await claimSyncWork(tx, attempt, { state: 'failed', errorCode });
      await tx.tbankSyncStage.deleteMany({
        where: { workId: attempt.id, attemptId: attempt.attemptId },
      });
@@ -3,9 +3,10 @@ import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';

 import type { Prisma } from '../../../../../generated/prisma/client';
-import type { TbankBond, TbankShare, TbankSyncAttempt } from '../../../../integrations/tbank/tbank.api';

 import { TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
+import { claimSyncWork, lockConnectionGeneration } from '../../../../integrations/tbank/tbank-sync-claim';
+import { isJoinableRunningAttempt, type TbankBond, type TbankShare, type TbankSyncAttempt } from '../../../../integrations/tbank/tbank.api';
 import { PrismaService } from '../../../../prisma/prisma.service';

 const UNCHANGED_REVISION_INCREMENT = 0;
@@ -159,24 +160,18 @@ export class CatalogDiscoveryRepository {
    initiator: TbankSyncAttempt = attempt,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const origin = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...initiator,
-          state: { in: ['running', 'complete'] },
-          connection: { invalidToken: false },
-        },
-        data: { progress: {} },
+      const origin = await claimSyncWork(
+        tx,
+        initiator,
+        { progress: {} },
+        { state: { in: ['running', 'complete'] } },
+      );
+      if (!origin) return false;
+      const claimed = await claimSyncWork(tx, attempt, {
+        state: 'complete',
+        progress: {},
      });
-      if (!origin.count) return false;
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { state: 'complete', progress: {} },
-      });
-      if (!claimed.count) return false;
+      if (!claimed) return false;
      const payload = JSON.parse(
        JSON.stringify(value),
      ) as Prisma.InputJsonObject;
@@ -284,20 +279,13 @@ export class CatalogDiscoveryRepository {
    active: ReadonlySet<string>,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const current = await tx.tbankConnection.updateMany({
-        where: { ...owner, invalidToken: false },
-        data: { membershipRevision: { increment: 0 } },
-      });
-      if (!current.count) return null;
+      const current = await lockConnectionGeneration(tx, owner);
+      if (!current) return null;
      const scope = { ...owner, scopeKey: catalogScope(input) };
      const previous = await tx.tbankSyncWork.findUnique({
        where: { userId_revision_scopeKey: scope },
      });
-      if (
-        previous?.state === 'running' &&
-        previous.processRunId === runId &&
-        active.has(previous.attemptId)
-      ) {
+      if (isJoinableRunningAttempt(previous, runId, active)) {
        return { work: previous, launch: false };
      }
      const data = {
@@ -345,15 +333,11 @@ export class CatalogDiscoveryRepository {
    now: Date,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const claimed = await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: { state: 'complete', progress: {} },
+      const claimed = await claimSyncWork(tx, attempt, {
+        state: 'complete',
+        progress: {},
      });
-      if (!claimed.count) return false;
+      if (!claimed) return false;
      for (const instrument of instruments) {
        // Discovery can create a minimal identity, but cannot overwrite verified metadata.
        const identity = { provider, uid: instrument.uid };
@@ -465,6 +449,7 @@ export class CatalogDiscoveryRepository {

  finish(attempt: TbankSyncAttempt, success: boolean) {
    return this.prisma.$transaction(async (tx) => {
+      // Fails sibling attempts whose connection was invalidated mid-flight.
      await tx.tbankSyncWork.updateMany({
        where: {
          ...attempt,
@@ -473,16 +458,9 @@ export class CatalogDiscoveryRepository {
        },
        data: { state: 'failed', errorCode: TbankErrorCode.InvalidToken },
      });
-      await tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: {
-          state: success ? 'complete' : 'failed',
-          errorCode: success ? null : TbankErrorCode.Unavailable,
-        },
+      await claimSyncWork(tx, attempt, {
+        state: success ? 'complete' : 'failed',
+        errorCode: success ? null : TbankErrorCode.Unavailable,
      });
    });
  }
@@ -1,6 +1,5 @@
 import { Module } from '@nestjs/common';

-import { TbankAccessService } from '../../../integrations/tbank/tbank-access.service';
 import { TbankModule } from '../../../integrations/tbank/tbank.module';
 import { AuthModule } from '../../auth/auth.module';
 import { PortfolioModule } from '../portfolio/portfolio.module';
@@ -21,7 +20,6 @@ import { StockController } from './stocks/presentation/stock.controller';
  controllers: [StockController, BondController],
  exports: [StockIncomeService, BondIncomeService],
  providers: [
-    { provide: 'TBANK_ACCESS', useExisting: TbankAccessService },
    BondIncomeService,
    BondMarketService,
    GetStockCompanyUseCase,
@@ -1,3 +1,7 @@
+jest.mock('../../../../../integrations/tbank/tbank.api', () => ({
+  TbankAccessService: class {},
+}));
+
 import { NotFoundException, ServiceUnavailableException } from '@nestjs/common';

 import type { TbankShare } from '../../../../../integrations/tbank/tbank.api';
@@ -36,7 +40,7 @@ describe('StockScreenerService', () => {
    client.getAllShares.mockResolvedValue(
      Array.from({ length: pageSize + 1 }, (_, index) => share(index)),
    );
-    service = new StockScreenerService(access, client as never, logger as never);
+    service = new StockScreenerService(access as never, client as never, logger as never);
  });

  it('stores the full selected catalog and returns stable non-overlapping pages', async () => {
@@ -1,6 +1,5 @@
 import {
  BadRequestException,
-  Inject,
  Injectable,
  NotFoundException,
  ServiceUnavailableException,
@@ -10,6 +9,7 @@ import { randomUUID } from 'node:crypto';
 import type { TbankShare } from '../../../../../integrations/tbank/tbank-market.types';

 import { StructuredLogger } from '../../../../../common/logging/structured-logger.service';
+import { TbankAccessService } from '../../../../../integrations/tbank/tbank.api';
 import { TbankClient } from '../../../../../integrations/tbank/tbank.client';
 import {
  selectStockScreenerInstruments,
@@ -47,17 +47,13 @@ type StockScreenerPage = {
  searchId: string;
 };
 type Snapshot = { asOf: string; expiresAt: number; items: StockScreenerItem[]; revision: string; userId: string };
-type TbankAccess = {
-  local(userId: string): Promise<{ revision: string }>;
-  online<T>(userId: string, run: (connection: { revision: string; token: string }) => Promise<T>): Promise<T>;
-};

@Injectable()
 export class StockScreenerService {
  private readonly snapshots = new Map<string, Snapshot>();

  constructor(
-    @Inject('TBANK_ACCESS') private readonly access: TbankAccess,
+    private readonly access: TbankAccessService,
    private readonly client: TbankClient,
    private readonly logger: StructuredLogger,
  ) {}
@@ -91,6 +91,7 @@ export class StockController {
    @Body(new ValidationPipe({ forbidNonWhitelisted: true, forbidUnknownValues: true, whitelist: true }))
    criteria: StockScreenerCriteriaDto,
  ) {
+    // The global whitelist pipe strips unknown keys before this param pipe runs, so only the raw body can reject them.
    const allowed = new Set(['countryOfRisk', 'currency', 'maxLot', 'query', 'realExchange', 'sector', 'shareType']);
    if (Object.keys(request.body as object).some((key) => !allowed.has(key))) {
      throw new BadRequestException();
@@ -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,
-    );
  });
 });
@@ -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[],
@@ -0,0 +1,10 @@
+export const operationCategories = [
+  'trade',
+  'income',
+  'tax',
+  'fee',
+  'transfer',
+  'other',
+] as const;
+
+export type OperationCategory = (typeof operationCategories)[number];
@@ -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 };
  }

@@ -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();
@@ -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;

@@ -7,13 +7,14 @@ import { createHash, randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';

 import type { Prisma } from '../../../../../generated/prisma/client';
-import type {
-  TbankOperationItem,
-  TbankOperationsByCursorResponse,
-} from '../../../../integrations/tbank/tbank.api';

 import { TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
 import { isTbankProtocolValue, TbankOperationState } from '../../../../integrations/tbank/tbank-protocol';
+import { claimSyncWork, lockConnectionGeneration } from '../../../../integrations/tbank/tbank-sync-claim';
+import {
+  isJoinableRunningAttempt,
+  type TbankOperationItem, type TbankOperationsByCursorResponse,
+} from '../../../../integrations/tbank/tbank.api';
 import { PrismaService } from '../../../../prisma/prisma.service';
 import {
  dateOnlyBounds,
@@ -268,16 +269,10 @@ export class BrokerageOperationsRepository {
        .update(JSON.stringify([...new Set(intervals.map(intervalKey))].sort()))
        .digest('hex');
    return this.prisma.$transaction(async (tx) => {
-      const locked = await tx.tbankConnection.updateMany({
-        where: {
-          userId,
-          revision,
-          invalidToken: false,
-          membershipAt: { not: null },
-        },
-        data: { membershipRevision: { increment: 0 } },
+      const locked = await lockConnectionGeneration(tx, { userId, revision }, {
+        membershipAt: { not: null },
      });
-      if (!locked.count) return null;
+      if (!locked) return null;
      const accounts = await tx.tbankAccount.findMany({
        where: { userId, revision },
        select: { accountId: true, openedOn: true },
@@ -379,9 +374,7 @@ export class BrokerageOperationsRepository {
        publicationAtomic && previousIntent && !previousIntent.atomic;
      if (
        touching.length <= SINGLE_WORK_GROUP &&
-        previous?.state === 'running' &&
-        previous.processRunId === processRunId &&
-        runningAttempts.has(previous.attemptId) &&
+        isJoinableRunningAttempt(previous, processRunId, runningAttempts) &&
        !upgradeGroup
      ) {
        const pending = previousIntent?.intervals.map(decodeInterval) ?? [];
@@ -933,15 +926,8 @@ async function claim(
  tx: Prisma.TransactionClient,
  attempt: OperationAttempt,
 ): Promise<boolean> {
-  const result = await tx.tbankSyncWork.updateMany({
-    where: {
-      ...attempt,
-      state: 'running',
-      connection: { invalidToken: false },
-    },
-    data: { updatedAt: new Date() },
-  });
-  return result.count === EXPECTED_UPDATED_WORK_ITEMS;
+  const count = await claimSyncWork(tx, attempt, { updatedAt: new Date() });
+  return count === EXPECTED_UPDATED_WORK_ITEMS;
 }

 function decodeInterval(key: string): OperationInterval {
@@ -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';
@@ -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',
@@ -20,6 +20,7 @@ export class ForecastService {
    lastAttempt?: InvestmentResourceMetaDto['lastAttempt'];
    membershipRevision: number;
    portfolio: InvestmentResourceMetaDto;
+    replacesLatest?: boolean;
    revision: string;
    scopeKey: string;
    sources: {
@@ -74,7 +75,7 @@ export class ForecastService {
          .map((dependency) => dependency.sync)
          .find((sync) => sync.state === 'failed');
    return {
-      data: stored ? filterEvents(stored.payload as T, input.scopeKey) : null,
+      data: stored ? filterEvents(stored.payload as T, input.scopeKey, stored.scopeKey) : null,
      meta: investmentResourceMeta({
        resourceKey: input.scopeKey,
        dataRevision: String(stored?.dataRevision ?? MISSING_DATA_REVISION),
@@ -95,7 +96,7 @@ export class ForecastService {
  }
 }

-function filterEvents<T extends object>(payload: T, scopeKey: string): T {
+function filterEvents<T extends object>(payload: T, scopeKey: string, savedScopeKey: string): T {
  if (!scopeKey.startsWith('events/')) return payload;
  try {
    const [, from, to] = JSON.parse(scopeKey.slice('events/'.length)) as [string, string, string];
@@ -111,8 +112,10 @@ function filterEvents<T extends object>(payload: T, scopeKey: string): T {
      const current = totals.get(event.projectedAmount.currency) ?? { value: 0n, scale: 0 };
      totals.set(event.projectedAmount.currency, add(current, decimalFromString(event.projectedAmount.value)));
    }
+    const [, savedFrom, savedTo] = JSON.parse(savedScopeKey.slice('events/'.length)) as [string, string, string];
    return {
      ...value,
+      window: { from: savedFrom, to: savedTo },
      events,
      incomeTotalsByCurrency: [...totals]
        .sort(([left], [right]) => left.localeCompare(right))
@@ -6,9 +6,10 @@ import { PortfolioDto } from '../presentation/portfolio.dto';
 import { PortfolioService } from './portfolio.service';

 describe('persistent portfolio projection', () => {
-  const access = { local: jest.fn(), tokenForAttempt: jest.fn() };
+  const access = { local: jest.fn(), tokenForAttempt: jest.fn(), rejectMembershipToken: jest.fn() };
  const tbank = { getPortfolio: jest.fn(), getPositions: jest.fn() };
  const metadata = { savedMany: jest.fn(), request: jest.fn() };
+  const classification = { refresh: jest.fn() };
  const repository = {
    read: jest.fn(),
    reserve: jest.fn(),
@@ -23,6 +24,7 @@ describe('persistent portfolio projection', () => {
      access as never,
      tbank as never,
      metadata as never,
+      classification as never,
      repository as never,
      { request: jest.fn().mockResolvedValue(null) } as never,
      { event: jest.fn() } as never,
@@ -34,6 +36,7 @@ describe('persistent portfolio projection', () => {
      accounts: [{ accountId: 'a' }, { accountId: 'b' }],
    });
    access.tokenForAttempt.mockResolvedValue('synthetic');
+    access.rejectMembershipToken.mockResolvedValue(undefined);
    repository.reserve.mockResolvedValue(null);
    repository.read.mockResolvedValue({
      membershipAt,
@@ -44,6 +47,37 @@ describe('persistent portfolio projection', () => {
    repository.publish.mockResolvedValue(true);
    metadata.savedMany.mockResolvedValue(new Map());
    metadata.request.mockResolvedValue(null);
+    classification.refresh.mockResolvedValue(new Map());
+  });
+  it('refreshes classification before publishing and passes the hourly walk time', async () => {
+    const walkStartedAt = new Date('2026-10-31T12:00:00Z');
+    const position = { instrumentType: 'share', instrumentUid: 'uid', figi: 'figi', quantity: { units: '1' } };
+    repository.reserve.mockResolvedValue({ launch: true, work: { id: 'work', attemptId: 'attempt' } });
+    tbank.getPortfolio.mockResolvedValue({ positions: [position] });
+    tbank.getPositions.mockResolvedValue({ money: [] });
+    classification.refresh.mockResolvedValue(new Map([[JSON.stringify(['uid', 'figi']), {
+      sector: 'Energy', issuer: { id: 'issuer', name: 'Issuer' },
+    }]]));
+    const handle = await service.request('user', 'private', 'a', true, walkStartedAt);
+    assert(handle);
+    await handle.done;
+    expect(classification.refresh).toHaveBeenCalledWith('synthetic', [position], walkStartedAt);
+    expect(classification.refresh.mock.invocationCallOrder[0]).toBeLessThan(repository.publish.mock.invocationCallOrder[0]);
+    const snapshot = (repository.publish.mock.calls as [unknown, string, PortfolioDto][])[0][2];
+    expect(snapshot.positions[0]).toEqual(expect.objectContaining({
+      sector: 'Energy', issuer: { id: 'issuer', name: 'Issuer' },
+    }));
+  });
+  it('rejects an invalid classification token without publishing the snapshot', async () => {
+    repository.reserve.mockResolvedValue({ launch: true, work: { id: 'work', attemptId: 'attempt' } });
+    tbank.getPortfolio.mockResolvedValue({ positions: [] });
+    tbank.getPositions.mockResolvedValue({ money: [] });
+    classification.refresh.mockRejectedValue(new Error('INVALID_TBANK_TOKEN'));
+    const handle = await service.request('user', 'private', 'a');
+    assert(handle);
+    await handle.done;
+    expect(repository.publish).not.toHaveBeenCalled();
+    expect(access.rejectMembershipToken).toHaveBeenCalled();
  });
  it('normalizes exact signed money, order, UID metadata and unknown types without metadata RPC', async () => {
    repository.reserve.mockResolvedValueOnce({
@@ -159,6 +193,43 @@ 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');
+  });
+
+  // Test intent: a corrupted Json payload must fail loudly instead of being spread into the API response.
+  it('rejects a stored snapshot payload without the persisted shape', async () => {
+    repository.read.mockResolvedValue({
+      membershipAt,
+      membershipRevision: 1,
+      accounts: [{ accountId: 'a', name: 'A', type: 'BROKERAGE', openedOn: null,
+        portfolio: { payload: { positions: 'broken' }, fetchedAt: membershipAt, dataRevision: 1 } }],
+      work: [],
+    });
+    await expect(service.read('user', 'all')).rejects.toThrow('Corrupted portfolio snapshot payload');
+  });
+
  it('does not turn a missing account snapshot into aggregate zero; summaries stay independent', async () => {
    const snapshot: PortfolioDto = {
      lastSuccessfulAt: membershipAt.toISOString(),
@@ -4,6 +4,8 @@ import {
 } from '@nestjs/common';
 import { randomUUID } from 'node:crypto';

+import type { Prisma } from '../../../../../generated/prisma/client';
+
 import { StructuredLogger } from '../../../../common/logging/structured-logger.service';
 import { isTbankErrorCode, TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
 import {
@@ -20,16 +22,18 @@ 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 {
  portfolioFreshForMs,
  PortfolioRepository,
+  portfolioSnapshot,
  portfolioWorkKey,
 } from '../infrastructure/portfolio.repository';
 import { mapPortfolio } from '../infrastructure/tbank-portfolio.mapper';
 import { PortfolioDto } from '../presentation/portfolio.dto';
+import { type Classification, PositionClassificationService } from './position-classification.service';

 const MISSING_DATA_REVISION = 0;
 const NO_ACCOUNTS = 0;
@@ -46,6 +50,7 @@ export class PortfolioService {
    private readonly access: TbankAccessService,
    private readonly tbank: TbankClient,
    private readonly metadata: InstrumentMetadataService,
+    private readonly classification: PositionClassificationService,
    private readonly repository: PortfolioRepository,
    private readonly membership: TbankMembershipService,
    private readonly logger: StructuredLogger,
@@ -86,13 +91,7 @@ export class PortfolioService {
          type: account.type,
          openedOn: account.openedOn,
          snapshot: account.portfolio
-            ? {
-                ...(account.portfolio.payload as unknown as PortfolioDto),
-                lastSuccessfulAt: account.portfolio.fetchedAt.toISOString(),
-                isStale:
-                  Date.now() - account.portfolio.fetchedAt.valueOf() >=
-                  portfolioFreshForMs,
-              }
+            ? savedSnapshot(account.portfolio)
            : null,
          meta: investmentResourceMeta({
            resourceKey: `portfolio/${encodeURIComponent(account.accountId)}`,
@@ -231,8 +230,8 @@ export class PortfolioService {
    };
  }

-  request(userId: string, revision: string, accountId: string, force = false) {
-    return this.queueSnapshot(userId, revision, accountId, force);
+  request(userId: string, revision: string, accountId: string, force = false, walkStartedAt?: Date) {
+    return this.queueSnapshot(userId, revision, accountId, force, walkStartedAt);
  }

  private queueSnapshot(
@@ -240,6 +239,7 @@ export class PortfolioService {
    revision: string,
    accountId: string,
    force = false,
+    walkStartedAt = new Date(),
  ) {
    const reserved = this.reservations.then(async () => {
      const requested = await this.repository.reserve(
@@ -268,9 +268,11 @@ export class PortfolioService {
              this.tbank.getPortfolio(token, accountId),
              this.tbank.getPositions(token, accountId),
            ]);
+            const classifications = await this.classification.refresh(token, portfolio.positions ?? [], walkStartedAt);
            const snapshot = await this.normalize(
              portfolio.positions ?? [],
              positions.money ?? [],
+              classifications,
            );
            const published = await this.repository.publish(
              attempt,
@@ -309,9 +311,24 @@ export class PortfolioService {
  private async normalize(
    upstream: NonNullable<TbankPortfolio['positions']>,
    money: TbankMoney[],
+    classifications: ReadonlyMap<string, Classification>,
  ): Promise<PortfolioDto> {
    const lastSuccessfulAt = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
    const savedMetadata = await this.metadata.savedMany(upstream);
-    return mapPortfolio(upstream, money, savedMetadata, lastSuccessfulAt);
+    return mapPortfolio(upstream, money, savedMetadata, lastSuccessfulAt, classifications);
  }
 }
+
+function savedSnapshot(saved: { fetchedAt: Date; payload: Prisma.JsonValue }): PortfolioDto {
+  const snapshot = portfolioSnapshot(saved.payload);
+  return {
+    ...snapshot,
+    positions: snapshot.positions.map((position) => ({
+      ...position,
+      sector: position.sector ?? null,
+      issuer: position.issuer ?? null,
+    })),
+    lastSuccessfulAt: saved.fetchedAt.toISOString(),
+    isStale: Date.now() - saved.fetchedAt.valueOf() >= portfolioFreshForMs,
+  };
+}
@@ -0,0 +1,172 @@
+import { NotFoundException } from '@nestjs/common';
+
+jest.mock('../../../../prisma/prisma.service', () => ({ PrismaService: class {} }));
+import { TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
+import { InstrumentIdType } from '../../../../integrations/tbank/tbank-protocol';
+import { PositionClassificationService } from './position-classification.service';
+
+describe('PositionClassificationService', () => {
+  const position = { instrumentType: 'share', instrumentUid: 'uid', figi: 'figi', quantity: { units: 1 } };
+  const saved = { sector: 'Old', sectorFetchedAt: new Date('2026-10-30T12:00:00Z'), assetUid: 'asset', brandUid: 'brand', brandName: 'Old brand', brandFetchedAt: new Date('2026-10-30T12:00:00Z') };
+  const tbank = { getShare: jest.fn(), getAssetBrand: jest.fn(), getBond: jest.fn(), getEtf: jest.fn() };
+  const repository = { read: jest.fn(), save: jest.fn() };
+  const logger = { event: jest.fn() };
+  const service = new PositionClassificationService(tbank as never, repository as never, logger as never);
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    repository.read.mockResolvedValue(saved);
+    repository.save.mockImplementation((_key: string, update: Record<string, unknown>) => Promise.resolve({ ...saved, ...update }));
+    tbank.getAssetBrand.mockResolvedValue({ assetUid: 'asset', brand: { uid: 'new-brand', name: 'New brand' } });
+  });
+
+  it('does not fetch a value at 23:59, and refreshes it at 24:00', async () => {
+    await service.refresh('token', [position], new Date('2026-10-31T11:59:00Z'));
+    expect(tbank.getShare).not.toHaveBeenCalled();
+    tbank.getShare.mockResolvedValue({ uid: 'uid', figi: 'figi', sector: ' Tech ', assetUid: 'asset' });
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(result.values().next().value).toEqual({ sector: 'Tech', issuer: { id: 'new-brand', name: 'New brand' } });
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), {
+      sector: 'Tech', sectorFetchedAt: new Date('2026-10-31T12:00:00Z'),
+      brandUid: 'new-brand', brandName: 'New brand', brandFetchedAt: new Date('2026-10-31T12:00:00Z'),
+    });
+  });
+
+  it('accepts a matching FIGI after UID NOT_FOUND', async () => {
+    tbank.getShare.mockRejectedValueOnce(new NotFoundException()).mockResolvedValueOnce({ uid: 'different', figi: 'figi', sector: 'Energy', assetUid: 'asset' });
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(tbank.getShare).toHaveBeenNthCalledWith(2, 'token', 'figi', InstrumentIdType.Figi, true);
+    expect(result.values().next().value?.sector).toBe('Energy');
+  });
+
+  it('preserves saved values on mismatched instrument and returns refreshed values on database failure', async () => {
+    tbank.getShare.mockResolvedValue({ uid: 'wrong', sector: 'Energy' });
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(result.values().next().value?.sector).toBe('Old');
+    repository.save.mockRejectedValue(new Error('db unavailable'));
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'asset' });
+    const fallback = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(fallback.values().next().value?.sector).toBe('Energy');
+    expect(logger.event).toHaveBeenCalled();
+  });
+
+  it('does not retain an issuer from a previous asset when the asset changes', async () => {
+    repository.read.mockResolvedValue({ ...saved, brandFetchedAt: new Date('2026-10-31T12:00:00Z') });
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'other' });
+    tbank.getAssetBrand.mockResolvedValue({ assetUid: 'other', brand: { uid: 'other-brand', name: 'Other brand' } });
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(tbank.getAssetBrand).toHaveBeenCalledWith('token', 'other');
+    expect(result.values().next().value?.issuer).toEqual({ id: 'other-brand', name: 'Other brand' });
+  });
+
+  it('does not restart the brand clock when the brand fetch fails after an asset change', async () => {
+    repository.read.mockResolvedValue({ ...saved, brandFetchedAt: new Date('2026-10-31T12:00:00Z') });
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'other' });
+    tbank.getAssetBrand.mockRejectedValue(new Error('upstream unavailable'));
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(result.values().next().value?.issuer).toBeNull();
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+      assetUid: 'other', brandUid: null, brandName: null, brandFetchedAt: null,
+    }));
+  });
+
+  it('does not return the previous asset brand when saving a changed asset fails', async () => {
+    repository.save.mockRejectedValue(new Error('db unavailable'));
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'other' });
+    tbank.getAssetBrand.mockRejectedValue(new Error('upstream unavailable'));
+    const result = await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(result.values().next().value).toEqual({ sector: 'Energy', issuer: null });
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+      assetUid: 'other', brandUid: null, brandName: null, brandFetchedAt: null,
+    }));
+    expect(logger.event).toHaveBeenCalled();
+  });
+
+  it('records a fetched brand as null when a fresh instrument has no asset_uid', async () => {
+    repository.read.mockResolvedValue(null);
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy' });
+    await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+      brandUid: null, brandName: null, brandFetchedAt: new Date('2026-10-31T12:00:00Z'),
+    }));
+  });
+
+  it('treats a NOT_FOUND answer as fetched and does not refetch it an hour later', async () => {
+    tbank.getShare.mockRejectedValue(new NotFoundException());
+    await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+      sector: null, sectorFetchedAt: new Date('2026-10-31T12:00:00Z'),
+    }));
+    repository.read.mockResolvedValue({ ...saved, sector: null, sectorFetchedAt: new Date('2026-10-31T12:00:00Z'), assetUid: null, brandUid: null, brandName: null, brandFetchedAt: new Date('2026-10-31T12:00:00Z') });
+    tbank.getShare.mockClear();
+    await service.refresh('token', [position], new Date('2026-10-31T13:00:00Z'));
+    expect(tbank.getShare).not.toHaveBeenCalled();
+  });
+
+  it('records a missing brand and restarts its clock when NOT_FOUND has no saved asset UID', async () => {
+    repository.read.mockResolvedValue(null);
+    tbank.getShare.mockRejectedValue(new NotFoundException());
+    const startedAt = new Date('2026-10-31T12:00:00Z');
+    const result = await service.refresh('token', [position], startedAt);
+    expect(result.values().next().value).toEqual({ sector: null, issuer: null });
+    expect(repository.save).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+      brandUid: null, brandName: null, brandFetchedAt: startedAt,
+    }));
+    expect(tbank.getAssetBrand).not.toHaveBeenCalled();
+  });
+
+  it('does not leak one refresh call\'s invalid token into another call', async () => {
+    tbank.getShare.mockRejectedValueOnce(new Error(TbankErrorCode.InvalidToken))
+      .mockResolvedValueOnce({ uid: 'uid', figi: 'figi', sector: 'Energy', assetUid: 'asset' });
+    await expect(service.refresh('first', [position], new Date('2026-10-31T12:00:00Z'))).rejects.toThrow();
+    const result = await service.refresh('second', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(result.values().next().value?.sector).toBe('Energy');
+  });
+
+  it('propagates an invalid token before publishing a classification', async () => {
+    tbank.getShare.mockRejectedValue(new Error(TbankErrorCode.InvalidToken));
+    const result = service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    await expect(result).rejects.toThrow(TbankErrorCode.InvalidToken);
+    expect(repository.save).not.toHaveBeenCalled();
+  });
+
+  it('leaves a fresh brand untouched when the sector refresh finds the same asset', async () => {
+    repository.read.mockResolvedValue({ ...saved, brandFetchedAt: new Date('2026-10-31T12:00:00Z') });
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'asset' });
+    await service.refresh('token', [position], new Date('2026-10-31T12:00:00Z'));
+    expect(tbank.getAssetBrand).not.toHaveBeenCalled();
+  });
+
+  it('skips unsupported types, zero-quantity positions, and shares a brand lookup across instruments', async () => {
+    repository.read.mockResolvedValue(null);
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'asset' });
+    tbank.getBond.mockResolvedValue({ uid: 'bond', sector: 'Energy', assetUid: 'asset' });
+    const result = await service.refresh('token', [
+      { instrumentType: 'currency', instrumentUid: 'cash', figi: 'cash', quantity: { units: 1 } },
+      { instrumentType: 'share', instrumentUid: 'empty', figi: 'empty', quantity: {} },
+      { instrumentType: 'Share', instrumentUid: 'upper', figi: 'upper', quantity: { units: 1 } },
+      position,
+      { instrumentType: 'bond', instrumentUid: 'bond', figi: 'bond-figi', quantity: { units: 1 } },
+    ], new Date('2026-10-31T12:00:00Z'));
+    expect(result.size).toBe(3);
+    expect(tbank.getAssetBrand).toHaveBeenCalledTimes(1);
+    expect(tbank.getEtf).not.toHaveBeenCalled();
+  });
+
+  it('skips duplicate instrument keys and retries a failed asset lookup for another instrument in the same walk', async () => {
+    repository.read.mockResolvedValue(null);
+    tbank.getShare.mockResolvedValue({ uid: 'uid', sector: 'Energy', assetUid: 'asset' });
+    tbank.getBond.mockResolvedValue({ uid: 'bond', sector: 'Energy', assetUid: 'asset' });
+    tbank.getAssetBrand.mockRejectedValueOnce(new Error('upstream unavailable'))
+      .mockResolvedValueOnce({ assetUid: 'asset', brand: { uid: 'new-brand', name: 'New brand' } });
+    const result = await service.refresh('token', [position, position,
+      { instrumentType: 'bond', instrumentUid: 'bond', figi: 'bond-figi', quantity: { units: 1 } },
+    ], new Date('2026-10-31T12:00:00Z'));
+    expect(result.size).toBe(2);
+    expect(tbank.getShare).toHaveBeenCalledTimes(1);
+    expect(tbank.getAssetBrand).toHaveBeenCalledTimes(2);
+    expect([...result.values()].map(({ issuer }) => issuer)).toEqual([
+      null, { id: 'new-brand', name: 'New brand' },
+    ]);
+  });
+});
@@ -0,0 +1,184 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+
+import { isZero } from '../../../../common/decimal';
+import { StructuredLogger } from '../../../../common/logging/structured-logger.service';
+import { MILLISECONDS_PER_DAY } from '../../../../common/time';
+import { decimal } from '../../../../integrations/tbank/decimal';
+import { isTbankErrorCode, TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
+import { InstrumentIdType } from '../../../../integrations/tbank/tbank-protocol';
+import { metadataKey, TbankClient, type TbankPortfolio } from '../../../../integrations/tbank/tbank.api';
+import { PositionClassificationRepository } from '../infrastructure/position-classification.repository';
+
+export type Classification = { issuer: null | { id: string; name: string }; sector: null | string };
+type Position = NonNullable<TbankPortfolio['positions']>[number];
+type Instrument = { assetUid?: string; figi?: string; sector?: string; uid?: string };
+type Row = NonNullable<Awaited<ReturnType<PositionClassificationRepository['read']>>>;
+type Update = Parameters<PositionClassificationRepository['save']>[1];
+
+@Injectable()
+export class PositionClassificationService {
+  constructor(
+    private readonly tbank: TbankClient,
+    private readonly repository: PositionClassificationRepository,
+    private readonly logger: StructuredLogger,
+  ) {}
+
+  async refresh(token: string, positions: Position[], walkStartedAt: Date): Promise<Map<string, Classification>> {
+    const result = new Map<string, Classification>();
+    const inFlight = new Map<string, Promise<unknown>>();
+    for (const position of positions) {
+      if (!['bond', 'etf', 'share'].includes((position.instrumentType ?? '').toLowerCase())) continue;
+      if (isZero(decimal(position.quantity ?? {}))) continue;
+      const key = metadataKey(position);
+      if (result.has(key)) continue;
+      result.set(key, await this.refreshOne(token, position, key, walkStartedAt, inFlight));
+    }
+    return result;
+  }
+
+  private async refreshOne(token: string, position: Position, key: string, startedAt: Date,
+    inFlight: Map<string, Promise<unknown>>): Promise<Classification> {
+    let saved: null | Row = null;
+    const update: Update = {};
+    try {
+      saved = await this.repository.read(key);
+      const due = (at: Date | null | undefined) => !at || startedAt.valueOf() - at.valueOf() >= MILLISECONDS_PER_DAY;
+      const sectorDue = due(saved?.sectorFetchedAt);
+      const brandDue = due(saved?.brandFetchedAt);
+      let assetUid = saved?.assetUid ?? null;
+      let instrumentFresh = false;
+      if (sectorDue || (brandDue && !saved?.assetUid)) {
+        const instrument = await this.refreshInstrument(token, position, sectorDue, assetUid, update, startedAt);
+        assetUid = instrument.assetUid;
+        instrumentFresh = instrument.fresh;
+      }
+      const assetChanged = 'assetUid' in update && update.assetUid !== saved?.assetUid;
+      if (assetChanged) {
+        update.brandUid = null;
+        update.brandName = null;
+        update.brandFetchedAt = null;
+      }
+      if (brandDue || assetChanged) {
+        await this.refreshBrand(token, assetUid, update, startedAt, inFlight, instrumentFresh);
+      }
+      if (Object.keys(update).length) saved = await this.repository.save(key, update);
+    } catch (error) {
+      if (this.invalidToken(error)) throw error;
+      this.failed(error);
+    }
+    const current = { ...saved, ...update };
+    return {
+      issuer: current.brandUid && current.brandName ? { id: current.brandUid, name: current.brandName } : null,
+      sector: current.sector ?? null,
+    };
+  }
+
+  private async refreshInstrument(token: string, position: Position, sectorDue: boolean, savedUid: null | string,
+    update: Update, startedAt: Date): Promise<{ assetUid: null | string; fresh: boolean }> {
+    try {
+      const lookup = await this.instrument(token, position);
+      if (lookup && !this.matches(lookup)) return { assetUid: savedUid, fresh: false };
+      if (lookup) return { assetUid: this.acceptInstrument(lookup.found, savedUid, sectorDue, update, startedAt), fresh: true };
+      if (sectorDue) this.clearSector(update, startedAt);
+    } catch (error) {
+      if (this.invalidToken(error)) throw error;
+      if (error instanceof NotFoundException) {
+        if (sectorDue) this.clearSector(update, startedAt);
+      } else this.failed(error);
+    }
+    return { assetUid: savedUid, fresh: false };
+  }
+
+  private clearSector(update: Update, startedAt: Date) {
+    update.sector = null;
+    update.sectorFetchedAt = startedAt;
+  }
+
+  private acceptInstrument(found: Instrument, savedUid: null | string, sectorDue: boolean, update: Update, startedAt: Date) {
+    const assetUid = found.assetUid?.trim() || null;
+    if (assetUid !== savedUid) update.assetUid = assetUid;
+    if (sectorDue) this.setSector(update, found.sector, startedAt);
+    return assetUid;
+  }
+
+  private setSector(update: Update, sector: string | undefined, startedAt: Date) {
+    update.sector = sector?.trim() || null;
+    update.sectorFetchedAt = startedAt;
+  }
+
+  private async refreshBrand(token: string, assetUid: null | string, update: Update, startedAt: Date,
+    inFlight: Map<string, Promise<unknown>>, instrumentFresh: boolean) {
+    if (!assetUid) {
+      if (instrumentFresh || 'assetUid' in update || 'sectorFetchedAt' in update) this.clearBrand(update, startedAt);
+      return;
+    }
+    try {
+      const asset = await this.dedupe(inFlight, assetUid, () => this.tbank.getAssetBrand(token, assetUid));
+      if (asset && asset.assetUid !== assetUid) return;
+      const uid = asset?.brand?.uid?.trim() || null;
+      const name = asset?.brand?.name?.trim() || null;
+      update.brandUid = uid && name ? uid : null;
+      update.brandName = uid && name ? name : null;
+      update.brandFetchedAt = startedAt;
+    } catch (error) {
+      if (this.invalidToken(error)) throw error;
+      if (error instanceof NotFoundException) this.clearBrand(update, startedAt);
+      else this.failed(error);
+    }
+  }
+
+  private clearBrand(update: Update, startedAt: Date) {
+    update.brandUid = null;
+    update.brandName = null;
+    update.brandFetchedAt = startedAt;
+  }
+
+  private matches(lookup: { found: Instrument; id: string; idType: InstrumentIdType }) {
+    return (lookup.idType === InstrumentIdType.Uid ? lookup.found.uid : lookup.found.figi) === lookup.id;
+  }
+
+  private invalidToken(error: unknown) {
+    return error instanceof Error && isTbankErrorCode(error.message, TbankErrorCode.InvalidToken);
+  }
+
+  private async instrument(token: string, position: Position) {
+    const type = (position.instrumentType ?? '').toLowerCase();
+    const lookup = (id: string, idType: InstrumentIdType) => {
+      switch (type) {
+        case 'bond': return this.tbank.getBond(token, id, idType, true);
+        case 'share': return this.tbank.getShare(token, id, idType, true);
+        default: return this.tbank.getEtf(token, id, idType, true);
+      }
+    };
+    const uid = position.instrumentUid?.trim();
+    const figi = position.figi?.trim();
+    if (uid) {
+      try {
+        const found = await lookup(uid, InstrumentIdType.Uid);
+        if (found) return { found, id: uid, idType: InstrumentIdType.Uid };
+      } catch (error) {
+        if (!(error instanceof NotFoundException)) throw error;
+      }
+    }
+    if (figi) {
+      const found = await lookup(figi, InstrumentIdType.Figi);
+      return found ? { found, id: figi, idType: InstrumentIdType.Figi } : null;
+    }
+    return null;
+  }
+
+  private dedupe<T>(map: Map<string, Promise<unknown>>, key: string, run: () => Promise<T>): Promise<T> {
+    const pending = map.get(key);
+    if (pending) return pending as Promise<T>;
+    const promise = run().catch((error: unknown) => {
+      map.delete(key);
+      throw error;
+    });
+    map.set(key, promise);
+    return promise;
+  }
+
+  private failed(error: unknown) {
+    this.logger.event('warn', 'portfolio.classification.failed', { code: error instanceof Error ? error.name : 'Unknown' });
+  }
+}
@@ -14,12 +14,14 @@ const position = (
  isin: null,
  ticker: null,
  logoName: null,
+  sector: null,
+  issuer: null,
  absoluteReturn: null,
  averagePurchasePrice: null,
 });

 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 +32,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' },
      ],
    });
  });
@@ -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';
@@ -26,6 +26,7 @@ export class ForecastRepository {
    membershipRevision: number;
    portfolioProjection: string;
    portfolios: { accountId: string; dataRevision: number }[];
+    replacesLatest?: boolean;
    revision: string;
    scopeKey: string;
    sources: ForecastSourceVersion[];
@@ -51,32 +52,30 @@ export class ForecastRepository {
      const previous = await tx.tbankForecast.findUnique({
        where: { userId_revision_scopeKey: key },
      });
+      // An events read serves the account's latest complete forecast whatever
+      // the requested window; other scopes keep their exact-key row.
      const requestedWindow = eventsWindow(input.scopeKey);
-      const saved = previous ?? (requestedWindow
-        ? (
-            await tx.tbankForecast.findMany({
-              where: {
-                ...owner,
-                scopeKey: { startsWith: 'events/' },
-                membershipRevision: input.membershipRevision,
+      const latest = requestedWindow
+        ? await tx.tbankForecast.findFirst({
+            where: {
+              ...owner,
+              // scopeKey is `events/[accountId,from,to]` JSON: pin the account.
+              scopeKey: {
+                startsWith: `events/[${JSON.stringify(requestedWindow.accountId)},`,
              },
-            })
-          ).find((forecast) => {
-            const window = eventsWindow(forecast.scopeKey);
-            return (
-              window &&
-              window.accountId === requestedWindow.accountId &&
-              window.from <= requestedWindow.to &&
-              requestedWindow.from <= window.to
-            );
+              membershipRevision: input.membershipRevision,
+            },
+            orderBy: [{ calculatedAt: 'desc' }, { scopeKey: 'asc' }],
          })
-        : null);
+        : previous;
      const fallback =
-        saved?.membershipRevision === input.membershipRevision
-          ? saved
-          : null;
+        latest?.membershipRevision === input.membershipRevision ? latest : null;
      if (!input.candidate) return fallback;
-      if (!previous && fallback) return fallback;
+      // Only the default window may replace the latest forecast; an explicit
+      // range is served from it and publishes only when nothing is saved.
+      if (!input.replacesLatest && fallback && fallback.scopeKey !== input.scopeKey) {
+        return fallback;
+      }
      const portfolios = await tx.tbankPortfolio.findMany({
        where: {
          ...owner,
@@ -152,7 +151,7 @@ export class ForecastRepository {
      ) as Prisma.InputJsonObject;
      const timestamps = input.timestamps as Prisma.InputJsonArray;
      if (
-        fallback &&
+        fallback?.scopeKey === input.scopeKey &&
        isDeepStrictEqual(fallback.dependencyRevisions, revisions) &&
        isDeepStrictEqual(fallback.sourceTimestamps, timestamps)
      ) {
@@ -5,7 +5,8 @@ import type { Prisma } from '../../../../../generated/prisma/client';
 import type { PortfolioDto } from '../presentation/portfolio.dto';

 import { TbankErrorCode } from '../../../../integrations/tbank/tbank-error-code';
-import { tbankSourceNeedsRefresh, tbankSourceTtlMs } from '../../../../integrations/tbank/tbank.api';
+import { lockConnectionGeneration } from '../../../../integrations/tbank/tbank-sync-claim';
+import { isJoinableRunningAttempt, tbankSourceNeedsRefresh, tbankSourceTtlMs } from '../../../../integrations/tbank/tbank.api';
 import { PrismaService } from '../../../../prisma/prisma.service';

 const EXPECTED_UPDATED_ACCOUNTS = 1;
@@ -56,16 +57,10 @@ export class PortfolioRepository {
    force: boolean,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const current = await tx.tbankConnection.updateMany({
-        where: {
-          userId,
-          revision,
-          invalidToken: false,
-          accounts: { some: { accountId } },
-        },
-        data: { membershipRevision: { increment: 0 } },
+      const current = await lockConnectionGeneration(tx, { userId, revision }, {
+        accounts: { some: { accountId } },
      });
-      if (!current.count) return null;
+      if (!current) return null;
      const snapshot = await tx.tbankPortfolio.findUnique({
        where: { userId_revision_accountId: { userId, revision, accountId } },
      });
@@ -86,11 +81,7 @@ export class PortfolioRepository {
        return null;
      }
      const scope = portfolioWorkScope;
-      if (
-        previous?.state === 'running' &&
-        previous.processRunId === processRunId &&
-        pending.has(previous.attemptId)
-      ) {
+      if (isJoinableRunningAttempt(previous, processRunId, pending)) {
        return { work: previous, launch: false };
      }
      const data = {
@@ -200,3 +191,16 @@ export class PortfolioRepository {
 export function portfolioWorkKey(accountId: string): string {
  return `portfolio:${JSON.stringify(accountId)}`;
 }
+
+// Json payload is written only by publish(); a shape check turns corruption into an explicit 500.
+export function portfolioSnapshot(value: Prisma.JsonValue): PortfolioDto {
+  const snapshot = value as null | Partial<PortfolioDto>;
+  if (
+    !Array.isArray(snapshot?.positions) ||
+    !Array.isArray(snapshot.totalsByCurrency) ||
+    !Array.isArray(snapshot.cashBalances)
+  ) {
+    throw new Error('Corrupted portfolio snapshot payload');
+  }
+  return snapshot as PortfolioDto;
+}
@@ -0,0 +1,29 @@
+import { Injectable } from '@nestjs/common';
+
+import { PrismaService } from '../../../../prisma/prisma.service';
+
+@Injectable()
+export class PositionClassificationRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  read(key: string) {
+    return this.prisma.tbankInstrumentClassification.findUnique({
+      where: { provider_instrumentKey: { provider: 'tbank', instrumentKey: key } },
+    });
+  }
+
+  save(key: string, data: {
+    assetUid?: null | string;
+    brandFetchedAt?: Date | null;
+    brandName?: null | string;
+    brandUid?: null | string;
+    sector?: null | string;
+    sectorFetchedAt?: Date;
+  }) {
+    return this.prisma.tbankInstrumentClassification.upsert({
+      where: { provider_instrumentKey: { provider: 'tbank', instrumentKey: key } },
+      create: { provider: 'tbank', instrumentKey: key, ...data },
+      update: data,
+    });
+  }
+}
@@ -1,4 +1,5 @@
 import type { Money } from '../../../../common/money.types';
+import type { Classification } from '../application/position-classification.service';
 import type { PortfolioDto, PortfolioPositionDto } from '../presentation/portfolio.dto';

 import {
@@ -35,9 +36,10 @@ function mapPortfolio(
  cash: TbankMoney[],
  metadata: ReadonlyMap<string, { data?: null | TbankInstrument }>,
  lastSuccessfulAt: string,
+  classification: ReadonlyMap<string, Classification> = new Map(),
 ): PortfolioDto {
  const positions = upstream
-    .map((position) => mapPosition(position, metadata.get(metadataKey(position))?.data ?? null))
+    .map((position) => mapPosition(position, metadata.get(metadataKey(position))?.data ?? null, classification.get(metadataKey(position))))
    .filter((position): position is PortfolioPositionDto => position !== null);
  const balances = new Map<string, ReturnType<typeof decimal>>();
  for (const value of cash) {
@@ -63,6 +65,7 @@ function mapPortfolio(
 function mapPosition(
  position: NonNullable<TbankPortfolio['positions']>[number],
  metadata: null | TbankInstrument,
+  classification?: Classification,
 ): null | PortfolioPositionDto {
  const quantity = decimal(position.quantity ?? {});
  if (isZero(quantity)) return null;
@@ -96,6 +99,8 @@ function mapPosition(
    isin: metadata?.isin?.trim() || null,
    ticker: metadata?.ticker?.trim() || null,
    logoName: metadata?.brand?.logoName?.trim() || null,
+    sector: classification?.sector ?? null,
+    issuer: classification?.issuer ?? null,
  };
 }

@@ -126,7 +131,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)),
@@ -5,4 +5,5 @@ export { PortfolioService } from './application/portfolio.service';
 export {
  PortfolioDto,
  PortfolioPositionDto,
+  PortfolioStructureDto,
 } from './presentation/portfolio.dto';
@@ -5,8 +5,10 @@ import { AuthModule } from '../../auth/auth.module';
 import { TbankSyncRepositoryModule } from '../tbank-sync/tbank-sync-repository.module';
 import { ForecastService } from './application/forecast.service';
 import { PortfolioService } from './application/portfolio.service';
+import { PositionClassificationService } from './application/position-classification.service';
 import { ForecastRepository } from './infrastructure/forecast.repository';
 import { PortfolioRepository } from './infrastructure/portfolio.repository';
+import { PositionClassificationRepository } from './infrastructure/position-classification.repository';
 import { PortfolioController } from './presentation/portfolio.controller';

@Module({
@@ -15,6 +17,8 @@ import { PortfolioController } from './presentation/portfolio.controller';
  providers: [
    PortfolioService,
    PortfolioRepository,
+    PositionClassificationService,
+    PositionClassificationRepository,
    ForecastService,
    ForecastRepository,
  ],
@@ -4,6 +4,14 @@ import { MoneyDto } from '../../../../common/money.dto';
 import { AccountReferenceDto } from '../../account-reference.dto';
 import { InvestmentResourceMetaDto } from '../../investment-resource.dto';

+export class PortfolioIssuerDto {
+  @ApiProperty()
+  declare id: string;
+
+  @ApiProperty()
+  declare name: string;
+}
+
 export class PortfolioPositionDto {
  @ApiPropertyOptional({ type: String, nullable: true })
  instrumentUid?: null | string;
@@ -52,6 +60,12 @@ export class PortfolioPositionDto {

  @ApiProperty({ type: String, nullable: true })
  declare logoName: null | string;
+
+  @ApiProperty({ type: String, nullable: true })
+  declare sector: null | string;
+
+  @ApiProperty({ type: PortfolioIssuerDto, nullable: true })
+  declare issuer: null | PortfolioIssuerDto;
 }

 export class PortfolioStructureCategoryDto {
@@ -132,6 +132,7 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
  // upstream call inside one. The attempt outcome is derived from durable
  // step rows by the repository, never from walk-local state.
  private async walk(attempt: TbankSyncAttempt) {
+    const walkStartedAt = new Date();
    this.active.add(attempt.attemptId);
    try {
      const { userId, revision } = attempt;
@@ -155,6 +156,7 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
        accounts,
        dispatch,
        dispatchProblems,
+        walkStartedAt,
      );
      await this.waitWorks(userId, children.map((child) => child.id));
      for (const account of accounts) {
@@ -239,6 +241,7 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
    accounts: Accounts,
    dispatch: DispatchStep,
    dispatchProblems: HourlySection[],
+    walkStartedAt: Date,
  ) {
    for (const account of accounts) {
      await this.dispatchPortfolio(
@@ -247,6 +250,7 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
        account.accountId,
        dispatch,
        dispatchProblems,
+        walkStartedAt,
      );
    }
    for (const account of accounts) {
@@ -264,6 +268,7 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
        account.accountId,
        dispatch,
        dispatchProblems,
+        walkStartedAt,
      );
    }
  }
@@ -274,10 +279,11 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
    accountId: string,
    dispatch: DispatchStep,
    dispatchProblems: HourlySection[],
+    walkStartedAt: Date,
  ) {
    try {
      const work = await this.withBound(
-        this.portfolio.request(userId, revision, accountId, true),
+        this.portfolio.request(userId, revision, accountId, true, walkStartedAt),
      );
      if (work && work !== BOUND_EXPIRED) {
        await dispatch({ accountId, id: work.id, section: 'portfolio' });
@@ -335,9 +341,12 @@ export class TbankHourlyScheduler implements OnModuleDestroy, OnModuleInit {
    accountId: string,
    dispatch: DispatchStep,
    dispatchProblems: HourlySection[],
+    walkStartedAt: Date,
  ) {
    try {
-      const ids = await this.withBound(this.events.refresh(userId, accountId));
+      const ids = await this.withBound(
+        this.events.refresh(userId, accountId, {}, walkStartedAt),
+      );
      if (ids !== BOUND_EXPIRED) {
        for (const id of ids) {
          await dispatch({ accountId, id, section: 'events' });
@@ -0,0 +1 @@
+export { hourlyAttempt, TbankSyncRepository } from './tbank-sync.repository';
@@ -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;
@@ -0,0 +1,14 @@
+jest.mock('../../../prisma/prisma.service', () => ({
+  PrismaService: class {},
+}));
+
+import { screenIntent } from './tbank-sync.repository';
+
+describe('screen sync intent', () => {
+  it('restores a persisted intent and rejects a corrupted one', () => {
+    const intent = { now: '2026-11-02T00:00:00.000Z', scope: { screen: 'accounts' } };
+    expect(screenIntent(intent)).toEqual(intent);
+    expect(() => screenIntent({ source: 'hourly' })).toThrow('Corrupted screen sync intent');
+    expect(() => screenIntent(null)).toThrow('Corrupted screen sync intent');
+  });
+});
@@ -6,8 +6,18 @@ import type { TbankSyncAttempt } from '../../../integrations/tbank/tbank.api';
 import type { InvestmentAttemptDto } from '../investment-resource.dto';
 import type { InvestmentScreenDto } from './tbank-sync.dto';

+import { claimSyncWork, lockConnectionGeneration } from '../../../integrations/tbank/tbank-sync-claim';
 import { PrismaService } from '../../../prisma/prisma.service';
 export type ScreenIntent = { now: string; scope: InvestmentScreenDto };
+
+// Json columns are written only by this repository; a shape check turns corruption into an explicit 500.
+export function screenIntent(value: Prisma.JsonValue): ScreenIntent {
+  const intent = value as null | Partial<ScreenIntent>;
+  if (typeof intent?.now !== 'string' || typeof intent.scope?.screen !== 'string') {
+    throw new Error('Corrupted screen sync intent');
+  }
+  return intent as ScreenIntent;
+}
 export type ScreenProgress = {
  attempts?: Record<string, string>;
  children: string[];
@@ -79,11 +89,8 @@ export class TbankSyncRepository {
    runId: string,
  ) {
    return this.prisma.$transaction(async (tx) => {
-      const valid = await tx.tbankConnection.updateMany({
-        where: { userId, revision, invalidToken: false },
-        data: { membershipRevision: { increment: 0 } },
-      });
-      if (!valid.count) return null;
+      const valid = await lockConnectionGeneration(tx, { userId, revision });
+      if (!valid) return null;
      const scopeKey = `screen:${JSON.stringify(scope)}`;
      const key = { userId, revision, scopeKey };
      const previous = await tx.tbankSyncWork.findUnique({
@@ -167,17 +174,11 @@ export class TbankSyncRepository {
        ...Object.fromEntries(rows.map((row) => [row.id, row.attemptId])),
        ...old.attempts,
      };
-      return tx.tbankSyncWork.updateMany({
-        where: {
-          ...attempt,
-          state: 'running',
-          connection: { invalidToken: false },
-        },
-        data: {
-          progress: { children: [...new Set(children)], attempts, dispatched },
-          ...(errorCode ? { state: 'failed', errorCode } : {}),
-        },
+      const claimed = await claimSyncWork(tx, attempt, {
+        progress: { children: [...new Set(children)], attempts, dispatched },
+        ...(errorCode ? { state: 'failed', errorCode } : {}),
      });
+      return { count: claimed };
    });
  }

@@ -226,10 +227,8 @@ export class TbankSyncRepository {
        processRunId: runId,
        state: 'running',
        priority: 0,
-        intent: JSON.parse(
-          JSON.stringify({ source: 'hourly' }),
-        ) as Prisma.InputJsonObject,
-        progress: { sections: [] } as unknown as Prisma.InputJsonValue,
+        intent: { source: 'hourly' },
+        progress: { sections: [] },
        errorCode: null,
      };
      const work = await tx.tbankSyncWork.upsert({
@@ -357,20 +356,17 @@ export class TbankSyncRepository {
        where: { userId: attempt.userId, id: child.id },
        select: { attemptId: true },
      });
-      const updated = await tx.tbankSyncWork.updateMany({
-        where: { ...attempt, state: 'running' },
-        data: {
-          progress: {
-            attempts: {
-              ...progress.attempts,
-              ...(row ? { [child.id]: row.attemptId } : {}),
-            },
-            children: [...(progress.children ?? []), child],
-            sections: progress.sections ?? [],
+      const updated = await claimSyncWork(tx, attempt, {
+        progress: {
+          attempts: {
+            ...progress.attempts,
+            ...(row ? { [child.id]: row.attemptId } : {}),
          },
+          children: [...(progress.children ?? []), child],
+          sections: progress.sections ?? [],
        },
-      });
-      return Boolean(updated.count);
+      }, { withoutConnectionFence: true });
+      return Boolean(updated);
    });
  }

@@ -8,10 +8,7 @@ import { randomUUID } from 'node:crypto';
 import { TbankAccessService } from '../../../integrations/tbank/tbank.api';
 import { BrokerageOperationsSyncService } from '../operations/operations.api';
 import { TbankSyncStatusDto } from './tbank-sync.dto';
-import {
-  type ScreenIntent,
-  TbankSyncRepository,
-} from './tbank-sync.repository';
+import { screenIntent, TbankSyncRepository } from './tbank-sync.repository';

@Injectable()
 export class TbankSyncService {
@@ -35,7 +32,7 @@ export class TbankSyncService {
    if (!saved.work.scopeKey.startsWith('screen:')) {
      return this.sourceStatus(userId, saved.work);
    }
-    const intent = saved.work.intent as unknown as ScreenIntent;
+    const intent = screenIntent(saved.work.intent);
    await this.access.local(userId, intent.scope.accountId);
    const children = await Promise.all(
      saved.children.map((child) =>
@@ -65,6 +65,14 @@ export class UpcomingEventDto {
  declare projectedAmount: MoneyDto | null;
 }

+export class UpcomingEventsWindowDto {
+  @ApiProperty({ format: 'date' })
+  declare from: string;
+
+  @ApiProperty({ format: 'date' })
+  declare to: string;
+}
+
 export class UpcomingEventsDto {
  @ApiProperty()
  declare accountId: string;
@@ -72,6 +80,13 @@ export class UpcomingEventsDto {
  @ApiProperty({ format: 'date-time' })
  declare calculatedAt: string;

+  @ApiProperty({
+    type: UpcomingEventsWindowDto,
+    description:
+      'Inclusive UTC window the saved forecast was calculated for. Unchanged by the requested from/to filter.',
+  })
+  declare window: UpcomingEventsWindowDto;
+
  @ApiProperty({ type: UpcomingEventDto, isArray: true })
  declare events: UpcomingEventDto[];

@@ -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;

@@ -150,7 +150,7 @@ export class UpcomingEventsService {
        a.type.localeCompare(b.type) ||
        a.ticker.localeCompare(b.ticker),
    );
-    const candidate: undefined | UpcomingEventsDto = ready
+    const candidate: Omit<UpcomingEventsDto, 'window'> | undefined = ready
      ? {
          accountId,
          calculatedAt: new Date().toISOString(),
@@ -163,6 +163,7 @@ export class UpcomingEventsService {
      revision: connection.revision,
      membershipRevision: connection.membershipRevision,
      scopeKey: `events/${JSON.stringify([accountId, window.from, window.to])}`,
+      replacesLatest: query.from === undefined && query.to === undefined,
      portfolio: portfolio.meta,
      lastAttempt: hourlyAttempt(
        hourly,
@@ -184,6 +185,7 @@ export class UpcomingEventsService {
    userId: string,
    accountId: string,
    query: UpcomingEventsQueryDto = {},
+    walkStartedAt?: Date,
  ): Promise<string[]> {
    const window = dateWindow(query);
    await this.access.local(userId, accountId);
@@ -194,6 +196,7 @@ export class UpcomingEventsService {
      positions,
      window,
      false,
+      walkStartedAt,
    );
    return launched;
  }
@@ -203,6 +206,7 @@ export class UpcomingEventsService {
    positions: Position[],
    window: { from: string; to: string },
    observe: boolean,
+    refreshBefore?: Date,
  ) {
    const metadata = await this.metadata.savedMany(positions);
    const sources: Awaited<ReturnType<CatalogEnrichmentService['readMany']>> =
@@ -228,6 +232,7 @@ export class UpcomingEventsService {
              identities.map((entry) => [entry.uid, entry.ticker]),
            ),
          },
+          refreshBefore,
        );
        sources.push(...batch);
        for (const source of batch) {
@@ -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;
 }
@@ -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',
    );
@@ -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({
@@ -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);
@@ -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 () => {
@@ -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');
@@ -0,0 +1,107 @@
+import { ConfigService } from '@nestjs/config';
+
+import { TbankAccessService } from '../src/integrations/tbank/tbank-access.service';
+import { TbankTokenService } from '../src/integrations/tbank/tbank-token.service';
+import { PrismaService } from '../src/prisma/prisma.service';
+
+// Characterizes the membership reserve protocol on real SQLite transactions.
+// Join by the same process while the attempt is active; launch after it is not.
+describe('membership reservation protocol (SQLite)', () => {
+  const prisma = new PrismaService(
+    new ConfigService({ DATABASE_URL: process.env.DATABASE_URL }),
+  );
+  const tokens = new TbankTokenService(
+    new ConfigService({
+      TOKEN_ENCRYPTION_KEY: process.env.TOKEN_ENCRYPTION_KEY,
+    }) as never,
+  );
+  const access = new TbankAccessService(prisma, tokens);
+  const userId = 'synthetic-membership-reservation';
+  const revision = `${userId}-revision`;
+
+  beforeAll(async () => {
+    await prisma.$connect();
+    await prisma.tbankSyncWork.deleteMany({ where: { userId } });
+    await prisma.tbankConnection.deleteMany({ where: { userId } });
+    await prisma.user.deleteMany({ where: { id: userId } });
+    await prisma.user.create({
+      data: {
+        id: userId,
+        email: `${userId}@example.invalid`,
+        passwordHash: 'synthetic',
+      },
+    });
+    await prisma.tbankConnection.create({
+      data: {
+        userId,
+        revision,
+        encryptedToken: tokens.encrypt('synthetic-membership'),
+        connectedAt: new Date(),
+      },
+    });
+  });
+
+  afterAll(async () => {
+    await prisma.tbankSyncWork.deleteMany({ where: { userId } });
+    await prisma.tbankConnection.deleteMany({ where: { userId } });
+    await prisma.user.deleteMany({ where: { id: userId } });
+    await prisma.$disconnect();
+  });
+
+  it('launches once, joins the active attempt by the same process, and relaunches after it finishes', async () => {
+    const processRunId = 'run-membership-a';
+    const first = await access.reserveMembership(
+      userId,
+      revision,
+      processRunId,
+      new Set(),
+      true,
+    );
+    expect(first?.launch).toBe(true);
+    const attemptId = first?.work.attemptId ?? '';
+
+    const joined = await access.reserveMembership(
+      userId,
+      revision,
+      processRunId,
+      new Set([attemptId]),
+      true,
+    );
+    expect(joined?.launch).toBe(false);
+    expect(joined?.work.id).toBe(first?.work.id);
+    expect(joined?.work.attemptId).toBe(attemptId);
+
+    // The attempt is no longer in the active set: this must not join it.
+    const relaunched = await access.reserveMembership(
+      userId,
+      revision,
+      processRunId,
+      new Set(),
+      true,
+    );
+    expect(relaunched?.launch).toBe(true);
+    expect(relaunched?.work.attemptId).not.toBe(attemptId);
+  });
+
+  it('does not join an attempt started by another process', async () => {
+    const other = await access.reserveMembership(
+      userId,
+      revision,
+      'run-membership-b',
+      new Set(),
+      true,
+    );
+    expect(other?.launch).toBe(true);
+    const attemptId = other?.work.attemptId ?? '';
+
+    const foreign = await access.reserveMembership(
+      userId,
+      revision,
+      'run-membership-c',
+      new Set([attemptId]),
+      true,
+    );
+    expect(foreign?.launch).toBe(true);
+    expect(foreign?.work.attemptId).not.toBe(attemptId);
+  });
+});
@@ -76,7 +76,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
        where: { id },
      });
      if (work.state === expected) return work;
-      await delay(2);
+      await delay(2); // Backoff between exact DB-state polls; not a timing barrier.
    }
    throw new Error(`Sync did not reach ${expected}`);
  }
@@ -113,6 +113,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
    });
    service = createService();
  });
+  afterEach(() => jest.restoreAllMocks());
  afterAll(async () => prisma.$disconnect());

  it.each([[false, 1], [true, 1], [false, 2], [true, 2]] as const)(
@@ -186,13 +187,17 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('publishes the forced visible period before unrelated pending history and retains it if history fails', async () => {
    const gate = deferred<TbankOperationsByCursorResponse>();
+    const started = deferred<void>();
    const march = {
      ...january,
      from: new Date('2026-03-01Z'),
      to: new Date('2026-04-01Z'),
    };
    upstream.getOperationsByCursor
-      .mockReturnValueOnce(gate.promise)
+      .mockImplementationOnce(() => {
+        started.resolve();
+        return gate.promise;
+      })
      .mockImplementation((_token, request) => {
        if (Number(request.from?.seconds) + 1 === march.from.valueOf() / 1000) {
          return Promise.resolve({
@@ -205,7 +210,9 @@ describe('Request-driven operations synchronization (SQLite)', () => {
    const history = requiredHandle(
      await service.request('owner', [february, march], false, 'history'),
    );
-    await delay(5);
+    // RPC starts after reserve/claim commits and pending reads the history plan.
+    // Waiting for state=running alone would not ensure that pending was read.
+    await started.promise;
    const screen = requiredHandle(
      await service.request('owner', [march], true),
    );
@@ -225,8 +232,12 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('moves a newly visible interval ahead of pending backfill and records an unknown requested floor', async () => {
    const gate = deferred<TbankOperationsByCursorResponse>();
+    const started = deferred<void>();
    upstream.getOperationsByCursor
-      .mockReturnValueOnce(gate.promise)
+      .mockImplementationOnce(() => {
+        started.resolve();
+        return gate.promise;
+      })
      .mockResolvedValue({ hasNext: false, items: [] });
    const march = {
      ...january,
@@ -241,7 +252,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
        'history',
      ),
    );
-    await delay(5);
+    await started.promise;
    await service.request('owner', [march], false);
    gate.resolve({ hasNext: false, items: [] });
    await state(history, 'complete');
@@ -471,7 +482,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
        expect(saved.state).toBe(
          checkpoint === 'after-publish' ? 'complete' : 'running',
        );
-        await delay(10);
+        await delay(10); // Bounded pause; absence of a recovery RPC cannot be awaited.
        expect(upstream.getOperationsByCursor).not.toHaveBeenCalled();
        if (checkpoint === 'after-publish') {
          // eslint-disable-next-line jest/no-conditional-expect -- The parameterized fixture chooses the scenario; each branch asserts its outcome and the test also asserts common invariants.
@@ -504,13 +515,17 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('joins a request bridging active groups and keeps both original handles observable', async () => {
    const blocked = deferred<typeof complete>();
+    const started = deferred<void>();
    upstream.getOperationsByCursor
-      .mockReturnValueOnce(blocked.promise)
+      .mockImplementationOnce(() => {
+        started.resolve();
+        return blocked.promise;
+      })
      .mockResolvedValue({ hasNext: false, items: [] });
    const early = { ...january, to: new Date('2026-01-10Z') };
    const late = { ...january, from: new Date('2026-01-20Z') };
    const first = requiredHandle(await service.request('owner', [early], true));
-    await delay(5);
+    await started.promise;
    const second = requiredHandle(await service.request('owner', [late], true));
    const merged = requiredHandle(
      await service.request('owner', [january], true),
@@ -526,25 +541,28 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('extends an overlapping atomic group without rereading its intersection or publishing a partial result', async () => {
    const first = deferred<typeof complete>();
+    const started = deferred<void>();
    const remainder = deferred<typeof complete>();
+    const remainderStarted = deferred<void>();
    const early = { ...january, to: new Date('2026-01-20Z') };
    const late = { ...january, from: new Date('2026-01-10Z') };
    upstream.getOperationsByCursor
-      .mockReturnValueOnce(first.promise)
-      .mockReturnValueOnce(remainder.promise);
+      .mockImplementationOnce(() => {
+        started.resolve();
+        return first.promise;
+      })
+      .mockImplementationOnce(() => {
+        remainderStarted.resolve();
+        return remainder.promise;
+      });
    const handle = requiredHandle(
      await service.request('owner', [early], true),
    );
-    await delay(5);
+    await started.promise;
+    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(1);
    expect(await service.request('owner', [late], true)).toBe(handle);
    first.resolve({ hasNext: false, items: [] });
-    for (
-      let index = 0;
-      index < 500 && upstream.getOperationsByCursor.mock.calls.length < 2;
-      index += 1
-    ) {
-      await delay(2);
-    }
+    await remainderStarted.promise;
    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(2);
    expect(upstream.getOperationsByCursor.mock.calls[1][1].from).toEqual({
      seconds: String(early.to.valueOf() / 1000 - 1),
@@ -561,13 +579,17 @@ describe('Request-driven operations synchronization (SQLite)', () => {
      items: never[];
      nextCursor: string;
    }>();
+    const started = deferred<void>();
    upstream.getOperationsByCursor
-      .mockReturnValueOnce(first.promise)
+      .mockImplementationOnce(() => {
+        started.resolve();
+        return first.promise;
+      })
      .mockResolvedValue({ hasNext: false, items: [] });
    const history = requiredHandle(
      await service.request('owner', [january], false, 'history'),
    );
-    await delay(5);
+    await started.promise;
    const screen = requiredHandle(
      await service.request('owner', [february], true),
    );
@@ -583,19 +605,17 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('keeps published initial windows on recovery and restarts only the unfinished month', async () => {
    const blocked = deferred<typeof complete>();
+    const blockedStarted = deferred<void>();
    upstream.getOperationsByCursor
      .mockResolvedValueOnce(complete)
-      .mockReturnValueOnce(blocked.promise);
+      .mockImplementationOnce(() => {
+        blockedStarted.resolve();
+        return blocked.promise;
+      });
    const handle = requiredHandle(
      await service.request('owner', [january, february], false),
    );
-    for (
-      let index = 0;
-      index < 500 && upstream.getOperationsByCursor.mock.calls.length < 2;
-      index += 1
-    ) {
-      await delay(2);
-    }
+    await blockedStarted.promise;
    expect(await prisma.tbankOperation.count()).toBe(1);
    const before = await prisma.tbankOperationCoverage.findMany();
    expect(before).toHaveLength(1);
@@ -616,8 +636,15 @@ describe('Request-driven operations synchronization (SQLite)', () => {
        })
      ).fetchedAt,
    ).toEqual(before[0].fetchedAt);
+    const stalePage = deferred<Promise<boolean>>();
+    const stagePage = repository.stagePage.bind(repository);
+    jest.spyOn(repository, 'stagePage').mockImplementation((...args) => {
+      const result = stagePage(...args);
+      stalePage.resolve(result);
+      return result;
+    });
    blocked.resolve(complete);
-    await delay(10);
+    expect(await stalePage.promise).toBe(false);
    expect(await prisma.tbankOperation.count()).toBe(1);
    expect(await prisma.tbankOperationCoverage.count()).toBe(2);
  });
@@ -651,7 +678,11 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('coalesces twenty requests, observes without RPC and completes only after the last page', async () => {
    const blocked = deferred<typeof complete>();
-    upstream.getOperationsByCursor.mockReturnValueOnce(blocked.promise);
+    const started = deferred<void>();
+    upstream.getOperationsByCursor.mockImplementationOnce(() => {
+      started.resolve();
+      return blocked.promise;
+    });
    const handles = await Promise.all(
      Array.from({ length: 20 }, () =>
        service.request('owner', [january], true),
@@ -659,7 +690,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
    );
    expect(new Set(handles).size).toBe(1);
    const handle = requiredHandle(handles[0]);
-    await delay(5);
+    await started.promise;
    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(1);
    expect((await service.observe('owner', handle)).state).toBe('running');
    expect(await prisma.tbankOperation.count()).toBe(0);
@@ -699,6 +730,7 @@ describe('Request-driven operations synchronization (SQLite)', () => {
    expect(await prisma.tbankOperationCoverage.findMany()).toEqual(oldCoverage);
    const calls = upstream.getOperationsByCursor.mock.calls.length;
    await service.observe('owner', handle);
+    // Bounded pause; absence of a background retry cannot be awaited.
    await delay(10);
    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(calls);
    upstream.getOperationsByCursor
@@ -713,29 +745,29 @@ describe('Request-driven operations synchronization (SQLite)', () => {

  it('starts an unfinished interval from page one after a new run request and ignores late old pages', async () => {
    const blocked = deferred<typeof complete>();
+    const blockedStarted = deferred<void>();
    upstream.getOperationsByCursor
      .mockResolvedValueOnce({
        hasNext: true,
        nextCursor: 'provider-cursor',
        items: [operation()],
      })
-      .mockReturnValueOnce(blocked.promise);
+      .mockImplementationOnce(() => {
+        blockedStarted.resolve();
+        return blocked.promise;
+      });
    const handle = requiredHandle(
      await service.request('owner', [january], true),
    );
-    for (
-      let index = 0;
-      index < 500 && upstream.getOperationsByCursor.mock.calls.length < 2;
-      index += 1
-    ) {
-      await delay(2);
-    }
-    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(2);
+    await blockedStarted.promise;
    const before = await prisma.tbankSyncWork.findUniqueOrThrow({
      where: { id: handle },
    });
+    expect(await prisma.tbankSyncStage.count()).toBeGreaterThan(0);
+
    service = createService();
    await service.observe('owner', handle);
+    // Bounded pause; absence of work adoption by observe cannot be awaited.
    await delay(5);
    expect(upstream.getOperationsByCursor).toHaveBeenCalledTimes(2);
    upstream.getOperationsByCursor.mockResolvedValueOnce({
@@ -752,8 +784,15 @@ describe('Request-driven operations synchronization (SQLite)', () => {
    expect(
      upstream.getOperationsByCursor.mock.calls[2][1].cursor,
    ).toBeUndefined();
+    const stalePage = deferred<Promise<boolean>>();
+    const stagePage = repository.stagePage.bind(repository);
+    jest.spyOn(repository, 'stagePage').mockImplementation((...args) => {
+      const result = stagePage(...args);
+      stalePage.resolve(result);
+      return result;
+    });
    blocked.resolve(complete);
-    await delay(10);
+    expect(await stalePage.promise).toBe(false);
    expect((await prisma.tbankOperation.findFirstOrThrow()).payload).toEqual(
      operation('30'),
    );
@@ -1,6 +1,9 @@
 import { ConfigService } from '@nestjs/config';
 import assert from 'node:assert/strict';

+import type { Prisma } from '../generated/prisma/client';
+import type { PortfolioDto } from '../src/modules/investments/portfolio/presentation/portfolio.dto';
+
 import { PortfolioRepository } from '../src/modules/investments/portfolio/infrastructure/portfolio.repository';
 import { PrismaService } from '../src/prisma/prisma.service';

@@ -16,9 +19,41 @@ describe('portfolio publication (SQLite)', () => {
    totalsByCurrency: [],
    positions: [],
    cashBalances: [],
-    structure: {},
-  } as never;
+    structure: { currencies: [], unvaluedCategories: [] },
+  } satisfies PortfolioDto;
  const accountId = 'account';
+  const valuedSnapshot = {
+    ...snapshot,
+    totalsByCurrency: [
+      { currency: 'RUB', value: '200' },
+      { currency: 'USD', value: '10' },
+    ],
+  } satisfies PortfolioDto;
+  const createRunningAttempt = () =>
+    prisma.tbankSyncWork.create({
+      data: {
+        id: 'live',
+        userId: 'owner',
+        revision: 'current',
+        scopeKey: `portfolio:${accountId}`,
+        intent: {},
+        state: 'running',
+        attemptId: 'live-attempt',
+        processRunId: 'run',
+        priority: 1,
+        progress: {},
+      },
+    });
+  const interceptTransaction = (intercept: (tx: Prisma.TransactionClient) => void) => {
+    const transaction = prisma.$transaction.bind(prisma);
+    jest.spyOn(prisma, '$transaction').mockImplementation(
+      (callback: (tx: Prisma.TransactionClient) => Promise<unknown>) =>
+        transaction((tx) => {
+          intercept(tx);
+          return callback(tx);
+        }),
+    );
+  };

  beforeAll(async () => {
    await prisma.$connect();
@@ -27,7 +62,9 @@ describe('portfolio publication (SQLite)', () => {
    });
  });
  afterAll(async () => prisma.$disconnect());
+  afterEach(() => jest.restoreAllMocks());
  beforeEach(async () => {
+    await prisma.tbankPortfolioValueHistory.deleteMany();
    await prisma.tbankConnection.deleteMany();
    await prisma.tbankConnection.create({
      data: {
@@ -48,20 +85,7 @@ describe('portfolio publication (SQLite)', () => {
  });

  it('publishes the same snapshot for the running attempt of the current revision', async () => {
-    await prisma.tbankSyncWork.create({
-      data: {
-        id: 'live',
-        userId: 'owner',
-        revision: 'current',
-        scopeKey: `portfolio:${accountId}`,
-        intent: {},
-        state: 'running',
-        attemptId: 'live-attempt',
-        processRunId: 'run',
-        priority: 1,
-        progress: {},
-      },
-    });
+    await createRunningAttempt();
    const published = await repository.publish(
      { id: 'live', attemptId: 'live-attempt', userId: 'owner', revision: 'current' },
      accountId,
@@ -70,4 +94,99 @@ describe('portfolio publication (SQLite)', () => {
    assert.equal(published, true);
    expect(await prisma.tbankPortfolio.count()).toBe(1);
  });
+
+  it('rolls back the snapshot, first value point and claim when the second point fails', async () => {
+    const previousFetchedAt = new Date('2025-12-31T00:00:00.000Z');
+    const previousCapturedAt = new Date('2025-12-31T01:00:00.000Z');
+    await prisma.tbankPortfolio.create({
+      data: {
+        userId: 'owner',
+        revision: 'current',
+        accountId,
+        payload: snapshot,
+        fetchedAt: previousFetchedAt,
+      },
+    });
+    await prisma.tbankPortfolioValueHistory.create({
+      data: {
+        userId: 'owner',
+        accountId,
+        points: {
+          create: {
+            attemptId: 'previous-attempt',
+            currency: 'RUB',
+            value: '100',
+            capturedAt: previousCapturedAt,
+          },
+        },
+      },
+    });
+    await createRunningAttempt();
+    interceptTransaction((tx) => {
+      const upsert = tx.tbankPortfolioValuePoint.upsert.bind(tx.tbankPortfolioValuePoint);
+      jest
+        .spyOn(tx.tbankPortfolioValuePoint, 'upsert')
+        .mockImplementationOnce((args) => upsert(args))
+        .mockRejectedValueOnce(new Error('injected second point failure'));
+    });
+
+    await expect(
+      repository.publish(
+        { id: 'live', attemptId: 'live-attempt', userId: 'owner', revision: 'current' },
+        accountId,
+        valuedSnapshot,
+      ),
+    ).rejects.toThrow('injected second point failure');
+
+    expect(
+      await prisma.tbankPortfolio.findUnique({
+        where: { userId_revision_accountId: { userId: 'owner', revision: 'current', accountId } },
+      }),
+    ).toMatchObject({ payload: snapshot, fetchedAt: previousFetchedAt, dataRevision: 1 });
+    expect(
+      await prisma.tbankPortfolioValuePoint.findMany({
+        select: { attemptId: true, value: true, capturedAt: true },
+      }),
+    ).toEqual([
+      { attemptId: 'previous-attempt', value: '100', capturedAt: previousCapturedAt },
+    ]);
+    expect(await prisma.tbankSyncWork.findUniqueOrThrow({ where: { id: 'live' } }))
+      .toMatchObject({ state: 'running', attemptId: 'live-attempt' });
+  });
+
+  it.each(['stale attempt', 'complete work', 'invalid token'] as const)(
+    'does not publish for %s',
+    async (scenario) => {
+      await createRunningAttempt();
+      if (scenario === 'complete work') {
+        await prisma.tbankSyncWork.update({
+          where: { id: 'live' },
+          data: { state: 'complete' },
+        });
+      }
+      if (scenario === 'invalid token') {
+        await prisma.tbankConnection.update({
+          where: { userId: 'owner' },
+          data: { invalidToken: true },
+        });
+      }
+
+      await expect(
+        repository.publish(
+          {
+            id: 'live',
+            attemptId: scenario === 'stale attempt' ? 'stale-attempt' : 'live-attempt',
+            userId: 'owner',
+            revision: 'current',
+          },
+          accountId,
+          valuedSnapshot,
+        ),
+      ).resolves.toBe(false);
+
+      expect(await prisma.tbankPortfolio.count()).toBe(0);
+      expect(await prisma.tbankPortfolioValueHistory.count()).toBe(0);
+      expect(await prisma.tbankPortfolioValuePoint.count()).toBe(0);
+    },
+  );
 });
@@ -298,6 +298,8 @@ describe('T-Bank value history persistence and visibility (SQLite)', () => {
            isin: null,
            ticker: null,
            logoName: null,
+            sector: null,
+            issuer: null,
          },
        ],
        cashBalances: [{ currency: 'USD', value: '50' }],
@@ -82,7 +82,10 @@ describe('saved payout calendars and complete forecasts (SQLite HTTP)', () => {
      `brokerage-accounts/${scope}/events?from=${range.from}&to=${range.to}${observe ? '&sync=observe' : ''}`,
      userId,
    );
-  const refresh = async (range = window, accountId = 'account') => {
+  const refresh = async (
+    range: { from?: string; to?: string } = window,
+    accountId = 'account',
+  ) => {
    await app.get(UpcomingEventsService).refresh('owner', accountId, range);
    await settled();
  };
@@ -318,17 +321,23 @@ describe('saved payout calendars and complete forecasts (SQLite HTTP)', () => {
    expect(upstream.getDividends).toHaveBeenCalledTimes(count);
  });

-  it('never relabels another range or membership snapshot and rejects inaccessible accounts locally', async () => {
+  it('serves a disjoint range as an empty saved result and never relabels a membership snapshot', async () => {
    await refresh();
    await settled();
-    await events().expect(200);
+    const saved = (await events().expect(200))
+      .body as UpcomingEventsResourceDto;
    const newRange = (
      await events(true, 'account', 'owner', {
        from: '2099-03-01',
        to: '2099-03-31',
      }).expect(200)
    ).body as UpcomingEventsResourceDto;
-    expect(newRange.data).toBeNull();
+    expect(newRange.data).toEqual({
+      ...saved.data,
+      events: [],
+      incomeTotalsByCurrency: [],
+    });
+    expect(newRange.data?.window).toEqual(window);
    await prisma.tbankConnection.update({
      where: { userId: 'owner' },
      data: { membershipRevision: { increment: 1 } },
@@ -640,6 +649,247 @@ describe('saved payout calendars and complete forecasts (SQLite HTTP)', () => {
    expect(moex.bondEvents).not.toHaveBeenCalled();
  });

+  it('keeps the latest wide forecast when an explicit narrower range has a complete candidate', async () => {
+    await refresh();
+    const full = (await events().expect(200))
+      .body as UpcomingEventsResourceDto;
+    const narrowRange = { from: '2099-02-01', to: '2099-02-10' };
+    await refresh(narrowRange);
+
+    const narrow = (await events(true, 'account', 'owner', narrowRange).expect(
+      200,
+    )).body as UpcomingEventsResourceDto;
+
+    expect(narrow.data?.calculatedAt).toBe(full.data?.calculatedAt);
+    expect(narrow.data?.window).toEqual(window);
+    expect(narrow.data?.events.map((event) => event.date)).toEqual([
+      '2099-02-01',
+    ]);
+    expect(await prisma.tbankForecast.count()).toBe(1);
+  });
+
+  describe('daily default window shift', () => {
+    const day0 = '2099-02-01';
+    const day1 = '2099-02-02';
+    const windowOf = (from: string, to: string) => ({ from, to });
+    const w0 = windowOf(day0, '2099-03-03');
+    const w1 = windowOf(day1, '2099-03-04');
+    const dividend = (date: string) => ({
+      recordDate: time(date),
+      dividendNet: { units: '10', nano: 1, currency: 'usd' },
+    });
+    const defaultEvents = async () =>
+      (await get('brokerage-accounts/account/events?sync=observe').expect(200))
+        .body as UpcomingEventsResourceDto;
+    // Only Date is faked: the app and SQLite helpers need real timers.
+    const clock = (date: string) => {
+      jest.useFakeTimers({
+        doNotFake: [
+          'hrtime', 'nextTick', 'performance', 'queueMicrotask',
+          'requestAnimationFrame', 'cancelAnimationFrame',
+          'requestIdleCallback', 'cancelIdleCallback', 'setImmediate',
+          'clearImmediate', 'setInterval', 'clearInterval', 'setTimeout',
+          'clearTimeout',
+        ],
+        now: new Date(`${date}T12:00:00Z`),
+      });
+    };
+    afterEach(() => jest.useRealTimers());
+
+    it('publishes the new window as latest and serves it for stale or disjoint explicit ranges', async () => {
+      clock(day0);
+      upstream.getDividends.mockResolvedValue([
+        dividend('2099-02-05'),
+        dividend('2099-03-04'),
+      ]);
+      await portfolio([position(shareUid, '2')]);
+      await refresh({});
+      const first = await defaultEvents();
+      expect(first.data?.window).toEqual(w0);
+      expect(first.data?.incomeTotalsByCurrency).toEqual([
+        { currency: 'USD', value: '20.000000002' },
+      ]);
+
+      jest.setSystemTime(new Date(`${day1}T12:00:00Z`));
+      await portfolio([position(shareUid, '5')]);
+      await refresh({});
+      const second = await defaultEvents();
+
+      expect(second.data?.window).toEqual(w1);
+      expect(second.data?.calculatedAt).not.toBe(first.data?.calculatedAt);
+      expect(second.data?.events.map((event) => event.date)).toEqual([
+        '2099-02-05',
+        '2099-03-04',
+      ]);
+      expect(second.data?.incomeTotalsByCurrency).toEqual([
+        { currency: 'USD', value: '100.00000001' },
+      ]);
+      const stale = (await events(true, 'account', 'owner', w0).expect(200))
+        .body as UpcomingEventsResourceDto;
+      expect(stale.data?.calculatedAt).toBe(second.data?.calculatedAt);
+      expect(stale.data?.window).toEqual(w1);
+      const disjoint = (
+        await events(true, 'account', 'owner', {
+          from: '2100-01-01',
+          to: '2100-01-31',
+        }).expect(200)
+      ).body as UpcomingEventsResourceDto;
+      expect(disjoint.data).toEqual({
+        ...second.data,
+        events: [],
+        incomeTotalsByCurrency: [],
+      });
+      expect(await prisma.tbankForecast.count()).toBe(2);
+    });
+
+    it('keeps the previous complete forecast when a holding calendar fails after the shift', async () => {
+      clock(day0);
+      upstream.getDividends.mockResolvedValue([dividend('2099-02-05')]);
+      await refresh({});
+      const before = await defaultEvents();
+      expect(before.data?.window).toEqual(w0);
+
+      jest.setSystemTime(new Date(`${day1}T12:00:00Z`));
+      await portfolio([position(shareUid, '7'), position(newUid, '5')]);
+      upstream.getDividends.mockImplementation((_token: string, uid: string) =>
+        uid === newUid
+          ? Promise.reject(new Error('new calendar unavailable'))
+          : Promise.resolve([dividend('2099-02-05')]),
+      );
+      await refresh({});
+
+      expect((await defaultEvents()).data).toEqual(before.data);
+      expect(await prisma.tbankForecast.count()).toBe(1);
+    });
+
+    it('publishes the shifted window even when no source depends on it', async () => {
+      clock(day0);
+      await portfolio([]);
+      await refresh({});
+      expect((await defaultEvents()).data?.window).toEqual(w0);
+
+      jest.setSystemTime(new Date(`${day1}T12:00:00Z`));
+      await refresh({});
+
+      expect((await defaultEvents()).data?.window).toEqual(w1);
+    });
+  });
+
+  describe('hourly pass refreshes saved payout calendars', () => {
+    const date = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
+    const dividend = (units: string, dividendType = 'Regular') => ({
+      recordDate: time(date),
+      dividendType,
+      dividendNet: { units, currency: 'usd' },
+    });
+    // One hourly walk: the scheduler stamps it once and passes it to every account.
+    const startWalk = async () => {
+      await delay(10);
+      return new Date();
+    };
+    const pass = async (walkStartedAt: Date, accountId = 'account') => {
+      await app
+        .get(UpcomingEventsService)
+        .refresh('owner', accountId, {}, walkStartedAt);
+      await settled();
+    };
+    const latest = async () =>
+      (await get('brokerage-accounts/account/events?sync=observe').expect(200))
+        .body as UpcomingEventsResourceDto;
+    const dividendRow = () =>
+      prisma.tbankInstrumentSource.findFirstOrThrow({
+        where: { instrumentUid: shareUid, kind: 'dividends' },
+      });
+
+    it('picks up a changed and then a cancelled payout on the next pass of the same window', async () => {
+      upstream.getDividends.mockResolvedValue([dividend('10')]);
+      await pass(await startWalk());
+      expect((await latest()).data?.incomeTotalsByCurrency).toEqual([
+        { currency: 'USD', value: '20' },
+      ]);
+      const first = await dividendRow();
+
+      upstream.getDividends.mockResolvedValue([dividend('30')]);
+      await pass(await startWalk());
+      expect((await latest()).data?.incomeTotalsByCurrency).toEqual([
+        { currency: 'USD', value: '60' },
+      ]);
+      expect((await dividendRow()).dataRevision).toBe(first.dataRevision + 1);
+
+      upstream.getDividends.mockResolvedValue([dividend('30', 'Cancelled')]);
+      await pass(await startWalk());
+      expect((await latest()).data?.events).toEqual([]);
+    });
+
+    it('keeps the first complete calendar, time and forecast when the next refresh fails', async () => {
+      upstream.getDividends.mockResolvedValue([dividend('10')]);
+      await pass(await startWalk());
+      const before = await latest();
+      const row = await dividendRow();
+
+      upstream.getDividends.mockRejectedValue(new Error('outage'));
+      await pass(await startWalk());
+      const after = await latest();
+
+      expect(after.data).toEqual(before.data);
+      expect(after.meta.lastSuccessfulAt).toBe(before.meta.lastSuccessfulAt);
+      expect(
+        after.meta.dependencies?.some(
+          (dependency) => dependency.lastAttempt.state === 'failed',
+        ),
+      ).toBe(true);
+      const kept = await dividendRow();
+      expect(kept.dataRevision).toBe(row.dataRevision);
+      expect(kept.fetchedAt).toEqual(row.fetchedAt);
+    });
+
+    it('loads one shared calendar once per walk across accounts and leaves detail, GET and a plain refresh alone', async () => {
+      await prisma.tbankAccount.create({
+        data: {
+          userId: 'owner',
+          revision: 'owner-revision',
+          accountId: 'second',
+          type: 'ACCOUNT_TYPE_TINKOFF',
+          name: 'Second',
+          upstreamOrder: 1,
+        },
+      });
+      await portfolio([position()], 'owner', 'second');
+      upstream.getDividends.mockResolvedValue([dividend('10')]);
+      await pass(await startWalk());
+      const detailCalls = () =>
+        upstream.getShare.mock.calls.length +
+        upstream.getInstrumentByUid.mock.calls.length;
+      const detailBefore = detailCalls();
+      expect(upstream.getDividends).toHaveBeenCalledTimes(1);
+
+      const walk = await startWalk();
+      await pass(walk, 'account');
+      await pass(walk, 'second');
+      expect(upstream.getDividends).toHaveBeenCalledTimes(2);
+
+      await app.get(UpcomingEventsService).refresh('owner', 'account', {});
+      await settled();
+      await latest();
+      await get('brokerage-accounts/all/events').expect(200);
+      expect(upstream.getDividends).toHaveBeenCalledTimes(2);
+      expect(detailCalls()).toBe(detailBefore);
+    });
+
+    it('re-reads the bond calendar whose key never changes, only on a walk pass', async () => {
+      await portfolio([position(bondUid, '3', 'BOND')]);
+      await pass(await startWalk());
+      expect(moex.bondEvents).toHaveBeenCalledTimes(1);
+
+      await app.get(UpcomingEventsService).refresh('owner', 'account', {});
+      await settled();
+      expect(moex.bondEvents).toHaveBeenCalledTimes(1);
+
+      await pass(await startWalk());
+      expect(moex.bondEvents).toHaveBeenCalledTimes(2);
+    });
+  });
+
  it('discards a late calendar from a replaced connection and prevents access to old private forecasts', async () => {
    let release: (value: unknown[]) => void = () => {};
    upstream.getDividends.mockReturnValueOnce(
Author	SHA1	Message	Date
ksv741	a2b5306a4c	refactor: tidy tbank-sync claim comments (WealthLedger/backend#166 ) Backend verify / commits (pull_request) Successful in 1m31s Details Backend verify / security (pull_request) Successful in 1m18s Details Backend verify / verify (pull_request) Successful in 6m15s Details	2026-11-04 17:59:42 +03:00
ksv741	812b989130	refactor: share tbank-sync claim and generation lock (WealthLedger/backend#166 )	2026-11-04 17:59:35 +03:00
codex-bot	02e0d560c8	refactor(api): describe bank operation create body as oneOf by kind (WealthLedger/backend#172) (#173 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m12s Details Backend verify / verify (push) Failing after 7m27s Details	2026-11-04 17:47:36 +03:00
codex-bot	fa0a6e5603	refactor: share sync reservation join rule (WealthLedger/backend#119) (#162 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m10s Details Backend verify / verify (push) Failing after 7m39s Details	2026-11-03 22:53:54 +03:00
codex-bot	bade5fae1c	chore(deps): set Renovate release age, PR limit and update groups (WealthLedger/main#6) (#160 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m2s Details Backend verify / verify (push) Failing after 6m42s Details	2026-11-03 14:07:40 +03:00
codex-bot	1a5de9bebd	ci: drop stale npm audit advisory ignore (WealthLedger/backend#158) (#159 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m7s Details Backend verify / verify (push) Failing after 6m59s Details	2026-11-03 12:04:10 +03:00
codex-bot	aeb4647fda	fix(events): refresh saved payout calendars once per hourly pass (WealthLedger/backend#53) (#157 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m6s Details Backend verify / verify (push) Failing after 6m50s Details	2026-11-02 23:06:14 +03:00
codex-bot	169bee1da5	fix(portfolio): publish new complete forecast regardless of request window (WealthLedger/backend#55) (#156 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m11s Details Backend verify / verify (push) Failing after 7m6s Details	2026-11-02 22:42:46 +03:00
codex-bot	554410a271	refactor: inject TbankAccessService directly into stock screener (#151 ) (#155 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m0s Details Backend verify / verify (push) Failing after 6m12s Details	2026-11-02 07:53:11 +03:00
codex-bot	a80bbbf1e2	refactor: check persisted json payload shape instead of double casts (#152 ) (#154 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 59s Details Backend verify / verify (push) Failing after 6m3s Details	2026-11-02 07:31:24 +03:00
ksv741	a18d9dbdc8	chore(release): 2.4.0 Backend verify / commits (pull_request) Successful in 1m28s Details Backend verify / security (pull_request) Successful in 1m3s Details Backend verify / verify (pull_request) Successful in 5m52s Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m7s Details Backend verify / verify (push) Successful in 5m30s Details Backend image / publish (push) Successful in 8m40s Details	2026-11-01 19:33:18 +03:00
codex-bot	17432dfee3	feat(portfolio): store and publish instrument sector and issuer (WealthLedger/main#48) (#148 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 1m4s Details Backend verify / verify (push) Failing after 7m15s Details	2026-11-01 19:13:32 +03:00
codex-bot	5e84e1e5f1	fix: scope income and ledger sync to requested intervals (WealthLedger/backend#57) (#147 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 17s Details Backend verify / verify (push) Failing after 5m52s Details	2026-10-28 21:29:53 +03:00
codex-bot	e350146749	test: cover portfolio publish rollback and claim fence (WealthLedger/backend#105) (#146 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 6m11s Details	2026-10-28 21:10:50 +03:00
codex-bot	99b137ed0b	test: replace operations sync delays with explicit barriers (WealthLedger/backend#104) (#145 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 6m12s Details	2026-10-28 20:41:24 +03:00
codex-bot	d37fa2c903	refactor: publish typed problem detail codes (WealthLedger/backend#117) (#144 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 10s Details Backend verify / verify (push) Failing after 6m8s Details	2026-10-28 17:11:41 +03:00
codex-bot	5295945ab2	refactor: expose tbank-sync public api and guard its boundary (WealthLedger/backend#118) (#143 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 10s Details Backend verify / verify (push) Failing after 6m28s Details	2026-10-28 16:40:01 +03:00
codex-bot	22668da3fa	refactor: remove tbank-sync operations import cycle (WealthLedger/backend#116) (#142 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 10s Details Backend verify / verify (push) Failing after 6m14s Details	2026-10-28 16:26:49 +03:00
ksv741	2325b63883	fix: reset portfolio value points inflated by double-counted cash (WealthLedger/backend#140 ) Backend verify / commits (pull_request) Successful in 27s Details Backend verify / security (pull_request) Skipped Details Backend verify / verify (pull_request) Skipped Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 4m33s Details	2026-10-28 08:00:20 +03:00
ksv741	f2843e30bd	fix: count brokerage cash once and skip short-position return percent (WealthLedger/backend#140 )	2026-10-28 08:00:20 +03:00
codex-bot	97fc41fa29	feat: extend account list portfolio summary (#138 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 8s Details Backend verify / verify (push) Failing after 4m43s Details	2026-10-27 05:44:07 +03:00
ksv741	3dcd1a69a6	chore: restore main ancestry in develop (WealthLedger/backend#135 ) Backend verify / commits (pull_request) Successful in 31s Details Backend verify / security (pull_request) Skipped Details Backend verify / verify (pull_request) Skipped Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 5m47s Details	2026-10-25 10:06:30 +03:00
codex-botandksv741	8503429b46	chore(release): 2.3.1 (#132 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 23s Details Backend verify / verify (push) Successful in 6m19s Details Backend image / publish (push) Successful in 13m17s Details 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>	2026-10-24 21:32:57 +03:00
ksv741	0dff4b4377	chore(release): 2.3.1 Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 11s Details Backend verify / commits (pull_request) Successful in 33s Details Backend verify / verify (push) Failing after 6m28s Details Backend verify / security (pull_request) Successful in 10s Details Backend verify / verify (pull_request) Successful in 6m13s Details	2026-10-24 21:00:38 +03:00
ksv741	a250142a86	fix: use available Debian packages in image build (#129 ) Backend verify / commits (pull_request) Successful in 38s Details Backend verify / security (pull_request) Successful in 11s Details Backend verify / verify (pull_request) Successful in 6m18s Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 13s Details Backend verify / verify (push) Failing after 6m38s Details	2026-10-24 20:48:55 +03:00
ksv741	0a0e70b273	chore(release): 2.3.0 Backend verify / commits (pull_request) Successful in 35s Details Backend verify / security (pull_request) Successful in 9s Details Backend verify / verify (pull_request) Successful in 6m23s Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 11s Details Backend image / publish (push) Failing after 6m34s Details Backend verify / verify (push) Successful in 6m36s Details	2026-10-24 19:15:04 +03:00
ksv741	449cfcd6c5	chore(deps): update non-major dependencies #11 Backend verify / commits (pull_request) Successful in 30s Details Backend verify / security (pull_request) Successful in 9s Details Backend verify / verify (pull_request) Successful in 5m31s Details Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 5m51s Details	2026-10-24 18:20:20 +03:00
codex-bot	966a1f793a	feat: log unhandled errors and pretty dev output (WealthLedger/backend#120) (#126 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 5m39s Details feat: log unhandled errors and pretty dev output (#120)	2026-10-24 15:06:34 +03:00
codex-bot	d1f6969dc7	fix: persist refresh cookie across browser restarts (WealthLedger/backend#123 ) Backend verify / commits (push) Skipped Details Backend verify / security (push) Successful in 9s Details Backend verify / verify (push) Failing after 4m58s Details	2026-10-23 08:34:39 +03:00
@@ -1 +1 @@
 .21.0
 .22.1
				`@@ -0,0 +1 @@`
				`export { hourlyAttempt, TbankSyncRepository } from './tbank-sync.repository';`