feat!: persist T-Bank data and synchronize reads

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

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

src/modules/investments/investment-resource.dto.ts

@@ -0,0 +1,75 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional } from 'class-validator';
+
+export const availabilityValues = ['missing', 'partial', 'complete'] as const;
+export const freshnessValues = ['unknown', 'fresh', 'stale'] as const;
+export const syncStateValues = ['idle', 'queued', 'running', 'failed'] as const;
+
+export class InvestmentReadQueryDto {
+  @ApiPropertyOptional({ enum: ['observe'] })
+  @IsOptional()
+  @IsIn(['observe'])
+  declare sync?: 'observe';
+}
+
+export class InvestmentSyncDto {
+  @ApiProperty({ type: String, nullable: true })
+  declare id: string | null;
+  @ApiProperty({ enum: syncStateValues })
+  declare state: (typeof syncStateValues)[number];
+  @ApiProperty({ type: String, nullable: true })
+  declare errorCode: string | null;
+}
+
+export class InvestmentRangeDto {
+  @ApiPropertyOptional()
+  accountId?: string;
+  @ApiProperty({ format: 'date-time' })
+  declare from: string;
+  @ApiProperty({ format: 'date-time' })
+  declare to: string;
+}
+
+export class InvestmentCoverageDto {
+  @ApiProperty({ type: InvestmentRangeDto, isArray: true })
+  declare requested: InvestmentRangeDto[];
+  @ApiProperty({ type: InvestmentRangeDto, isArray: true })
+  declare completeRanges: InvestmentRangeDto[];
+  @ApiProperty({ type: InvestmentRangeDto, isArray: true })
+  declare missingRanges: InvestmentRangeDto[];
+  @ApiProperty({ type: String, nullable: true, format: 'date-time' })
+  declare asOf: string | null;
+  @ApiProperty({ enum: ['known', 'unknown'] })
+  declare historyBoundary: 'known' | 'unknown';
+  @ApiProperty({
+    enum: ['missing', 'loading', 'partial', 'complete', 'failed'],
+  })
+  declare historyState:
+    'missing' | 'loading' | 'partial' | 'complete' | 'failed';
+}
+
+export class InvestmentDependencyDto {
+  @ApiProperty()
+  declare dataRevision: string;
+  @ApiProperty()
+  declare stateVersion: string;
+  @ApiPropertyOptional({ type: String })
+  unavailableReason?: string;
+  @ApiPropertyOptional({ type: () => InvestmentCoverageDto })
+  coverage?: InvestmentCoverageDto;
+  @ApiProperty()
+  declare resourceKey: string;
+  @ApiProperty({ enum: availabilityValues })
+  declare availability: (typeof availabilityValues)[number];
+  @ApiProperty({ enum: freshnessValues })
+  declare freshness: (typeof freshnessValues)[number];
+  @ApiProperty({ type: String, format: 'date-time', nullable: true })
+  declare lastSuccessfulAt: string | null;
+  @ApiProperty({ type: InvestmentSyncDto })
+  declare sync: InvestmentSyncDto;
+}
+
+export class InvestmentResourceMetaDto extends InvestmentDependencyDto {
+  @ApiPropertyOptional({ type: InvestmentDependencyDto, isArray: true })
+  declare dependencies?: InvestmentDependencyDto[];
+}