fix(release): align image smoke with migration 0030

feat(ledger): add manual DIVIDEND entries with UTC date, duplicate confirmation, and reversal support

.proofline/criteria/ac-0016.md

@@ -7,7 +7,7 @@ status: active
 
 ## Criterion
 
-신규 포트폴리오 생성·수정은 전역 카탈로그의 기존 active `strategy_id`만 선택할 수 있어야 하며, 전략을 inactive로 전환해도 기존 포트폴리오 참조는 보존되고 신규 선택만 차단되어야 한다.
+신규 포트폴리오 생성·수정에서 `strategy_id`를 지정하는 경우 전역 카탈로그의 기존 active ID만 선택할 수 있어야 하며, 전략을 inactive로 전환해도 기존 포트폴리오 참조는 보존되고 신규 선택만 차단되어야 한다. 전략 미지정 또는 `null`은 선택이 아니며 전략 참조를 만들지 않는다.
 
 ## Verification
 

.proofline/criteria/ac-0017.md

@@ -7,11 +7,11 @@ status: active
 
 ## Criterion
 
-`/v1/portfolios`와 legacy `/portfolios`의 생성에는 active `strategy_id`가 필수이고 수정도 ID-only여야 하며, 요청의 `strategy_name`·`strategy_params`는 `422`로 거부해야 한다. v1 `PortfolioItem` 응답은 현재 참조 전략의 `active_strategy_id`·`strategy_nick`·`strategy_name`·`strategy_params`·`strategy_revision`을 같은 committed row에서 반환해야 하고 참조가 없거나 해석할 수 없으면 `strategy_nick`은 `null`이어야 하며, legacy 응답의 기존 호환 필드는 유지되어야 한다.
+`/v1/portfolios`와 legacy `/portfolios`의 생성은 `strategy_id`를 생략하거나 `null`로 전달해도 가능해야 하며, 이 경우 전략 참조를 만들거나 기본 전략을 암묵적으로 선택해서는 안 된다. `strategy_id`가 제공된 생성·수정은 ID-only여야 하고 기존 active 전략 ID만 선택할 수 있으며, 요청의 `strategy_name`·`strategy_params`는 `422`로 거부해야 한다. v1 `PortfolioItem` 응답은 현재 참조 전략의 `active_strategy_id`·`strategy_nick`·`strategy_name`·`strategy_params`·`strategy_revision`을 같은 committed row에서 반환해야 하고 참조가 없거나 해석할 수 없으면 이 전략 메타데이터는 `null`이어야 하며, legacy 응답의 기존 호환 필드는 유지되어야 한다.
 
 ## Verification
 
-- 성공 조건: 명시한 active ID로만 포트폴리오가 생성·수정되고 v1 create/PATCH/list 응답에 현재 전략 ID·`nick`·이름·config·revision이 나타나며 참조가 없으면 `strategy_nick`은 `null`이다.
-- 실패·경계 조건: strategy ID 누락, 제거 필드 전달 또는 malformed 요청은 새 전략 row를 만들지 않고 `422`다.
-- 검사 방법: v1·legacy create/update schema와 저장소 row count, v1 create/PATCH/list의 `strategy_nick` read-back, unbound `null` 및 기존 응답 호환 필드를 API/CLI 회귀로 검사한다.
-- 현재 구현 평가: schemas와 양쪽 portfolio API가 ID-only 입력 및 `extra="forbid"` 계약을 구현하고 v1 mapper가 `strategy_nick`을 반환한다. 다만 `strategy_nick` read-back, 제거된 `strategy_name`·`strategy_params` 각각의 `422`와 응답 호환 필드 전체를 직접 단언하는 전용 test가 없어 executable coverage는 `PARTIAL`이다.
+- 성공 조건: strategy ID 없이 또는 `null`로 포트폴리오가 생성되고 전략 참조와 전략 메타데이터가 모두 `null`이며, 기본 전략이 자동 연결되지 않는다. 명시한 active ID로 생성·수정하면 v1 create/PATCH/list 응답에 현재 전략 ID·`nick`·이름·config·revision이 나타난다.
+- 실패·경계 조건: 제공된 unknown ID는 `404`, inactive ID는 `409`이며, 제거 필드·빈 문자열·malformed 요청은 새 전략 row를 만들지 않고 `422`다.
+- 검사 방법: v1·legacy create/update schema와 저장소 row count, strategy 미지정·explicit `null`·active/unknown/inactive ID의 create read-back, v1 create/PATCH/list 전략 메타데이터 및 기존 응답 호환 필드를 API/CLI 회귀로 검사한다.
+- 현재 구현 평가: v1 schema와 API는 strategy 미지정·`null` 생성을 구현하고 회귀 테스트가 이를 검사한다. legacy `/portfolios` schema와 생성 경로는 아직 `strategy_id`를 필수로 유지하므로 전체 계약의 executable coverage는 `PARTIAL`이며, legacy 동등 구현과 read-back 회귀가 필요하다.

.proofline/criteria/ac-0021.md

@@ -7,11 +7,11 @@ status: active
 
 ## Criterion
 
-Alembic data migration은 active `name="target_value"`, `config={}` 전략을 중복 없이 보장하고, 동일 `(name, config)` row가 있으면 재사용해야 하며 포트폴리오 요청의 `strategy_id` 필수 조건을 완화하지 않아야 한다.
+Alembic data migration은 active `name="target_value"`, `config={}` 전략을 중복 없이 보장하고 동일 `(name, config)` row가 있으면 재사용해야 한다. 기본 전략의 존재는 strategy 미지정 또는 `null` 포트폴리오 생성에서 암묵적 전략 선택을 유발해서는 안 된다.
 
 ## Verification
 
 - 성공 조건: 빈 DB upgrade 후 기본 전략 한 건이 active, revision 1과 runtime 일치 derived identity로 존재한다.
-- 실패·경계 조건: migration 재실행이나 기존 동일 row가 중복 row를 만들지 않고, 기본 전략 존재가 implicit portfolio selection을 허용하지 않는다.
-- 검사 방법: migration unit/idempotency test와 신규 PostgreSQL DB full upgrade/head 재실행, portfolio create negative test를 수행한다.
-- 현재 구현 평가: migration unit test가 scoped 재실행에서 PASS했고, 2026-08-15 실제 PostgreSQL integration `4 passed`에서 신규 DB full upgrade와 head 재실행을 재검증했다.
+- 실패·경계 조건: migration 재실행이나 기존 동일 row가 중복 row를 만들지 않고, 기본 전략 존재가 implicit portfolio selection을 유발하지 않는다.
+- 검사 방법: migration unit/idempotency test와 신규 PostgreSQL DB full upgrade/head 재실행, strategy 미지정·explicit `null` portfolio create read-back을 수행한다.
+- 현재 구현 평가: migration unit test가 scoped 재실행에서 PASS했고, v1 route에는 strategy 미지정 생성 회귀가 있다. legacy `/portfolios`에도 동일한 생성·read-back 검증이 추가되기 전까지 executable coverage는 `PARTIAL`이다.

.proofline/criteria/ac-0024.md

@@ -7,11 +7,11 @@ status: active
 
 ## Criterion
 
-유효한 `strategy_id`와 portfolio owner가 소유한 active daemon의 server-generated UUID를 포함해 포트폴리오를 생성하면 HTTP 201 응답과 후속 portfolio 조회의 `managed_by_daemon_id`가 요청한 daemon ID와 같아야 한다.
+strategy ID의 지정 여부와 무관하게, portfolio owner가 소유한 active daemon의 server-generated UUID를 포함해 포트폴리오를 생성하면 HTTP 201 응답과 후속 portfolio 조회의 `managed_by_daemon_id`가 요청한 daemon ID와 같아야 한다. strategy ID를 생략하거나 `null`로 전달한 경우 전략 참조는 만들지 않는다.
 
 ## Verification
 
-- 성공 조건: POST 응답과 저장소 조회 및 API 후속 조회가 모두 같은 non-null daemon ID를 반환한다.
+- 성공 조건: strategy ID를 지정한 경우와 생략하거나 `null`로 전달한 경우 모두 POST 응답·저장소 조회·API 후속 조회가 같은 non-null daemon ID를 반환하며, strategy 미지정 생성의 `active_strategy_id`는 `null`이다.
 - 실패·경계 조건: persistence 경계에서 daemon ID가 누락되거나 `null`로 바뀌면 실패한다.
 - 검사 방법: API test와 migration head가 적용된 disposable PostgreSQL에서 `POST → GET` read-back을 실행한다.
 - 현재 구현 평가: `e2102b6`의 생성 handler·repository INSERT 경로와 PostgreSQL integration test가 대응하며 2차 QC에서 관련 suite가 통과했다.

app/api/v1_portfolios.py

@@ -16,6 +16,7 @@ import json
 import logging
 import uuid
 from datetime import date, datetime, timedelta, timezone
+from decimal import Decimal
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 
@@ -26,6 +27,8 @@ from app.domain.models import Portfolio, PortfolioComment
 from app.domain.pnl import calculate_current_wac, calculate_realized_pnl
 from app.repositories.factory import get_portfolio_repository_from_settings
 from app.schemas.v1 import (
+    DividendLedgerHistoryItem,
+    DividendManualLedgerResponse,
     HoldingsCostBasisResponse,
     LedgerHistoryItem,
     LedgerHistoryResponse,
@@ -186,11 +189,13 @@ def create_portfolio_v1(
             )
 
         name = body.name or f"{body.broker}-{body.asset_id[:8]}"
-        strategy_set = repo.get_strategy_set(body.strategy_id)
-        if strategy_set is None:
-            raise StrategyNotFoundError(f"strategy not found: {body.strategy_id}")
-        if strategy_set.status != "active":
-            raise StrategyInactiveError(f"strategy is inactive: {body.strategy_id}")
+        strategy_set = None
+        if body.strategy_id is not None:
+            strategy_set = repo.get_strategy_set(body.strategy_id)
+            if strategy_set is None:
+                raise StrategyNotFoundError(f"strategy not found: {body.strategy_id}")
+            if strategy_set.status != "active":
+                raise StrategyInactiveError(f"strategy is inactive: {body.strategy_id}")
 
         _require_valid_daemon_uuid(body.managed_by_daemon_id)
 
@@ -205,8 +210,8 @@ def create_portfolio_v1(
             asset_quantity=body.asset_quantity,
             asset_price=body.asset_price,
             profit_buffer=body.profit_buffer,
-            active_strategy_id=strategy_set.id,
-            avabile_strategies=[strategy_set.id],
+            active_strategy_id=strategy_set.id if strategy_set is not None else None,
+            avabile_strategies=[strategy_set.id] if strategy_set is not None else None,
             managed_by_daemon_id=body.managed_by_daemon_id,
         )
     except HTTPException:
@@ -683,18 +688,41 @@ def record_ledger_trade_v1(
     )
 
 
-def _manual_entry_to_response(entry) -> ManualLedgerResponse:
+def _manual_entry_to_response(entry) -> ManualLedgerResponse | DividendManualLedgerResponse:
     action = (entry.action or entry.side or "").upper()
-    amount = entry.price if action in {"INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT"} else None
+    if action == "DIVIDEND":
+        amount_decimal = entry.price_decimal if entry.price_decimal is not None else Decimal(str(entry.price))
+        tax_decimal = entry.tax_amount_decimal if entry.tax_amount_decimal is not None else Decimal(str(entry.tax_amount))
+        return DividendManualLedgerResponse(
+            ledger_entry_id=entry.ledger_entry_id,
+            portfolio_id=entry.portfolio_id,
+            action=action,
+            amount=str(amount_decimal),
+            quantity=entry.quantity,
+            price=entry.price,
+            fee=entry.fee_amount,
+            tax=str(tax_decimal),
+            executed_at=entry.executed_at,
+            note=entry.note,
+            recorded_at=entry.recorded_at,
+            cash_balance_after=entry.cash_balance_after,
+            asset_quantity_after=entry.asset_quantity_after,
+            profit_buffer_after=entry.profit_buffer_after,
+            total_value_after=entry.total_value_after,
+            source=entry.source or "manual",
+            target_ledger_entry_id=entry.target_ledger_entry_id,
+            confirmation_evidence=entry.confirmation_evidence,
+        )
     return ManualLedgerResponse(
         ledger_entry_id=entry.ledger_entry_id,
         portfolio_id=entry.portfolio_id,
         action=action,
-        amount=amount,
+        amount=float(entry.price) if action in {"INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT"} else None,
         quantity=entry.quantity,
         price=entry.price,
         fee=entry.fee_amount,
-        tax=entry.tax_amount,
+        tax=float(entry.tax_amount),
+        executed_at=entry.executed_at,
         note=entry.note,
         recorded_at=entry.recorded_at,
         cash_balance_after=entry.cash_balance_after,
@@ -708,6 +736,8 @@ def _manual_entry_to_response(entry) -> ManualLedgerResponse:
 
 
 def _manual_error_code(message: str) -> str:
+    if "POTENTIAL_DUPLICATE_DIVIDEND" in message:
+        return "POTENTIAL_DUPLICATE_DIVIDEND"
     if "LEDGER_ENTRY_NOT_FOUND" in message or "원장 항목을 찾을 수 없습니다" in message:
         return "LEDGER_ENTRY_NOT_FOUND"
     if "INSUFFICIENT_CASH" in message or "현금" in message:
@@ -721,6 +751,32 @@ def _manual_error_code(message: str) -> str:
     return "MANUAL_LEDGER_CONFLICT"
 
 
+def _extract_duplicate_dividend_entry_id(message: str) -> int | None:
+    prefix = "POTENTIAL_DUPLICATE_DIVIDEND:"
+    if not message.startswith(prefix):
+        return None
+    try:
+        return int(message.removeprefix(prefix))
+    except ValueError:
+        return None
+
+
+def _manual_error_message(code: str) -> str:
+    if code == "LEDGER_ENTRY_NOT_FOUND":
+        return "Target ledger entry not found"
+    if code == "POTENTIAL_DUPLICATE_DIVIDEND":
+        return "Potential duplicate dividend entry detected"
+    if code == "INSUFFICIENT_CASH":
+        return "Insufficient cash balance"
+    if code == "INSUFFICIENT_QUANTITY":
+        return "Insufficient asset quantity"
+    if code == "INSUFFICIENT_BUFFER":
+        return "Insufficient profit buffer"
+    if code == "LEDGER_ENTRY_ALREADY_REVERSED":
+        return "Ledger entry is already reversed"
+    return "Manual ledger request could not be processed"
+
+
 def _encode_ledger_cursor(*, portfolio_id: str, source: str | None, recorded_at: datetime, ledger_entry_id: int) -> str:
     payload = {
         "portfolio_id": portfolio_id,
@@ -753,20 +809,47 @@ def _decode_ledger_cursor(cursor: str, *, portfolio_id: str, source: str | None)
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="invalid ledger cursor") from None
 
 
-def _ledger_entry_to_history_item(entry) -> LedgerHistoryItem:
+def _ledger_entry_to_history_item(entry) -> LedgerHistoryItem | DividendLedgerHistoryItem:
+    action = (entry.action or entry.side or "").upper()
+    if action == "DIVIDEND":
+        amount_decimal = entry.price_decimal if entry.price_decimal is not None else Decimal(str(entry.price))
+        tax_decimal = entry.tax_amount_decimal if entry.tax_amount_decimal is not None else Decimal(str(entry.tax_amount))
+        return DividendLedgerHistoryItem(
+            ledger_entry_id=entry.ledger_entry_id,
+            portfolio_id=entry.portfolio_id,
+            source=entry.source or "broker",
+            action=action,
+            recorded_at=entry.recorded_at,
+            executed_at=entry.executed_at,
+            order_id=entry.order_id,
+            execution_id=entry.execution_id,
+            quantity=entry.quantity,
+            amount=str(amount_decimal),
+            price=entry.price,
+            fee_amount=entry.fee_amount,
+            tax_amount=str(tax_decimal),
+            note=entry.note,
+            cash_balance_after=entry.cash_balance_after,
+            asset_quantity_after=entry.asset_quantity_after,
+            profit_buffer_after=entry.profit_buffer_after,
+            total_value_after=entry.total_value_after,
+            target_ledger_entry_id=entry.target_ledger_entry_id,
+            confirmation_evidence=entry.confirmation_evidence,
+        )
     return LedgerHistoryItem(
         ledger_entry_id=entry.ledger_entry_id,
         portfolio_id=entry.portfolio_id,
         source=entry.source or "broker",
-        action=(entry.action or entry.side or "").upper(),
+        action=action,
         recorded_at=entry.recorded_at,
         executed_at=entry.executed_at,
         order_id=entry.order_id,
         execution_id=entry.execution_id,
         quantity=entry.quantity,
+        amount=float(entry.price) if action in {"INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT"} else None,
         price=entry.price,
         fee_amount=entry.fee_amount,
-        tax_amount=entry.tax_amount,
+        tax_amount=float(entry.tax_amount),
         note=entry.note,
         cash_balance_after=entry.cash_balance_after,
         asset_quantity_after=entry.asset_quantity_after,
@@ -779,14 +862,14 @@ def _ledger_entry_to_history_item(entry) -> LedgerHistoryItem:
 
 @router.post(
     "/{portfolio_id}/ledger/manual",
-    response_model=ManualLedgerResponse,
+    response_model=ManualLedgerResponse | DividendManualLedgerResponse,
     status_code=status.HTTP_201_CREATED,
 )
 def record_manual_ledger_v1(
     portfolio_id: str,
     body: ManualLedgerRequest,
     auth: AuthContext = Depends(require_read),
-) -> ManualLedgerResponse:
+) -> ManualLedgerResponse | DividendManualLedgerResponse:
     if auth.token_type in {"service", "client"} or auth.user_id is None:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="manual ledger requires user/session token")
 
@@ -810,15 +893,26 @@ def record_manual_ledger_v1(
         entry = repo.record_manual_ledger(
             portfolio_id,
             action=body.action,
-            amount=float(body.amount) if body.amount is not None else None,
-            quantity=float(body.quantity) if body.quantity is not None else None,
-            price=float(body.price) if body.price is not None else None,
-            fee=float(body.fee),
-            tax=float(body.tax),
+            amount=body.amount,
+            quantity=body.quantity,
+            price=body.price,
+            fee=body.fee,
+            tax=body.tax,
+            executed_at=(
+                datetime(
+                    body.executed_at.year,
+                    body.executed_at.month,
+                    body.executed_at.day,
+                    tzinfo=timezone.utc,
+                )
+                if body.executed_at is not None
+                else None
+            ),
             target_ledger_entry_id=body.target_ledger_entry_id,
             note=body.note,
             actor_user_id=auth.user_id,
             confirmation_evidence=evidence,
+            confirm_duplicate=body.confirm_duplicate,
         )
     except HTTPException:
         raise
@@ -827,9 +921,18 @@ def record_manual_ledger_v1(
         code = _manual_error_code(message)
         if code == "LEDGER_ENTRY_NOT_FOUND":
             status_code = status.HTTP_404_NOT_FOUND
+            detail: str | dict[str, object] = {"code": code, "message": _manual_error_message(code)}
+        elif code == "POTENTIAL_DUPLICATE_DIVIDEND":
+            status_code = status.HTTP_409_CONFLICT
+            detail = {
+                "code": code,
+                "message": _manual_error_message(code),
+                "matched_ledger_entry_id": _extract_duplicate_dividend_entry_id(message),
+            }
         else:
             status_code = status.HTTP_409_CONFLICT if code != "MANUAL_LEDGER_CONFLICT" else status.HTTP_422_UNPROCESSABLE_ENTITY
-        raise HTTPException(status_code=status_code, detail={"code": code, "message": message}) from exc
+            detail = {"code": code, "message": _manual_error_message(code)}
+        raise HTTPException(status_code=status_code, detail=detail) from exc
     finally:
         _close_repo(repo)
     return _manual_entry_to_response(entry)

app/core/config.py

@@ -18,7 +18,7 @@ if env_file.exists():
 
 class Settings(BaseSettings):
     app_name: str = "PortfolioHub"
-    app_version: str = "0.2.0"
+    app_version: str = "0.2.1"
     environment: str = "development"
     allowed_origins_raw: str = Field(default="http://localhost:3000", validation_alias="PORTFOLIOHUB_ALLOWED_ORIGINS")
     bootstrap_username: str = Field(default="", validation_alias="PORTFOLIOHUB_BOOTSTRAP_USERNAME")

app/domain/models.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime
+from decimal import Decimal
 from enum import Enum
 from typing import Any, Protocol, runtime_checkable
 
@@ -136,12 +137,14 @@ class LedgerEntry:
     portfolio_id: str
     quantity: float
     price: float
+    price_decimal: Decimal | None = None
     ledger_entry_id: int = 0
     order_id: str | None = None
     execution_id: str | None = None
     side: str | None = None
     fee_amount: float = 0.0
     tax_amount: float = 0.0
+    tax_amount_decimal: Decimal | None = None
     executed_at: datetime | None = None
     recorded_at: datetime | None = None
     cash_balance_after: float = 0.0
@@ -195,4 +198,3 @@ class BrokerCredential:
     credential_version: int = 1
     last_rotated_at: datetime | None = None
     daemon_id: str | None = None
-

app/repositories/portfolio_repository.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from datetime import datetime
+from decimal import Decimal
 from typing import Protocol
 
 from app.domain.models import Asset, AuthToken, BrokerCredential, Daemon, LedgerEntry, Portfolio, PortfolioComment, PortfolioTag, StrategySet, Tag, TokenPrincipal, User
@@ -320,15 +321,17 @@ class PortfolioRepository(Protocol):
         portfolio_id: str,
         *,
         action: str,
-        amount: float | None = None,
-        quantity: float | None = None,
-        price: float | None = None,
-        fee: float = 0.0,
-        tax: float = 0.0,
+        amount: Decimal | None = None,
+        quantity: Decimal | None = None,
+        price: Decimal | None = None,
+        fee: Decimal = Decimal("0"),
+        tax: Decimal = Decimal("0"),
+        executed_at: datetime | None = None,
         target_ledger_entry_id: int | None = None,
         note: str = "",
         actor_user_id: str | None = None,
         confirmation_evidence: str | None = None,
+        confirm_duplicate: bool = False,
     ) -> LedgerEntry: ...
 
     def list_manual_ledger_entries(self, portfolio_id: str, limit: int = 50) -> list[LedgerEntry]: ...
@@ -362,4 +365,3 @@ class PortfolioRepository(Protocol):
     def update_comment(self, portfolio_id: str, comment_id: str, *, content: str) -> PortfolioComment: ...
 
     def delete_comment(self, portfolio_id: str, comment_id: str) -> None: ...
-

app/repositories/postgres.py

@@ -7,16 +7,39 @@ import json
 import logging
 import uuid
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
 from typing import Any
 
 import psycopg
 from psycopg import sql
 
-from app.domain.errors import DaemonInactiveError, DaemonInUseError, DaemonNotFoundError, StrategyInactiveError, StrategyNotFoundError
-from app.domain.models import Asset, AuthToken, BrokerCredential, Daemon, LedgerEntry, Portfolio, PortfolioComment, PortfolioTag, StrategySet, Tag, TokenPrincipal, User
+from app.domain.errors import (
+    DaemonInactiveError,
+    DaemonInUseError,
+    DaemonNotFoundError,
+    StrategyInactiveError,
+    StrategyNotFoundError,
+)
+from app.domain.models import (
+    Asset,
+    AuthToken,
+    BrokerCredential,
+    Daemon,
+    LedgerEntry,
+    Portfolio,
+    PortfolioComment,
+    PortfolioTag,
+    StrategySet,
+    Tag,
+    TokenPrincipal,
+    User,
+)
 
 logger = logging.getLogger(__name__)
+_LEDGER_NUMERIC_SCALE = 8
+_LEDGER_MAX_INTEGER_DIGITS = 12
+_LEDGER_QUANT = Decimal("0.00000001")
 
 _SELECT_USER = """
     SELECT
@@ -183,6 +206,7 @@ class PostgresPortfolioRepository:
     def ensure_schema(self) -> None:
         conn = self._connect()
         with conn.cursor() as cur:
+            cur.execute("SELECT pg_advisory_lock(hashtext('portfoliohub.ensure_schema.v1'))")
             cur.execute(
                 """
                 CREATE TABLE IF NOT EXISTS users (
@@ -484,6 +508,7 @@ class PostgresPortfolioRepository:
                     SELECT create_hypertable('portfolio_ledger', 'recorded_at', if_not_exists => TRUE)
                     """
                 )
+            cur.execute("SELECT pg_advisory_unlock(hashtext('portfoliohub.ensure_schema.v1'))")
 
     @staticmethod
     def _row_to_user(row: Any) -> User:
@@ -678,6 +703,7 @@ class PostgresPortfolioRepository:
 
     @staticmethod
     def _row_to_ledger_entry_legacy(row: Any) -> LedgerEntry:
+        raw_tax = row[6]
         return LedgerEntry(
             ledger_entry_id=0,
             portfolio_id=row[0],
@@ -686,8 +712,10 @@ class PostgresPortfolioRepository:
             side=row[2],
             quantity=float(row[4]),
             price=float(row[3]),
+            price_decimal=Decimal(str(row[3])) if row[3] is not None else None,
             fee_amount=float(row[5]),
-            tax_amount=float(row[6]),
+            tax_amount=float(raw_tax),
+            tax_amount_decimal=Decimal(str(raw_tax)) if raw_tax is not None else None,
             executed_at=row[1],
             recorded_at=row[1],
             cash_balance_after=float(row[7]),
@@ -1518,7 +1546,7 @@ class PostgresPortfolioRepository:
         note: str = "",
     ) -> None:
         self.ensure_schema()
-        trade_time = datetime.now(timezone.utc)
+        trade_time = datetime.now(UTC)
         conn = self._connect()
         with conn.transaction(), conn.cursor() as cur:
             cur.execute(
@@ -1597,9 +1625,9 @@ class PostgresPortfolioRepository:
         self,
         portfolio_id: str,
         *,
-        date: "datetime | None" = None,
-        from_: "datetime | None" = None,
-        to_: "datetime | None" = None,
+        date: datetime | None = None,
+        from_: datetime | None = None,
+        to_: datetime | None = None,
     ) -> list[LedgerEntry]:
         """Return ledger entries for portfolio_id filtered by date range (REQ-039).
 
@@ -1839,6 +1867,8 @@ class PostgresPortfolioRepository:
     def _row_to_ledger_entry(row: Any) -> LedgerEntry:
         if row is None:
             raise ValueError("원장 항목을 찾을 수 없습니다")
+        raw_price = row[6]
+        raw_tax = row[8]
         return LedgerEntry(
             ledger_entry_id=int(row[0]),
             portfolio_id=row[1],
@@ -1846,9 +1876,11 @@ class PostgresPortfolioRepository:
             execution_id=row[3],
             side=row[4],
             quantity=float(row[5]),
-            price=float(row[6]),
+            price=float(raw_price),
+            price_decimal=Decimal(str(raw_price)) if raw_price is not None else None,
             fee_amount=float(row[7]),
-            tax_amount=float(row[8]),
+            tax_amount=float(raw_tax),
+            tax_amount_decimal=Decimal(str(raw_tax)) if raw_tax is not None else None,
             executed_at=row[9],
             recorded_at=row[10],
             cash_balance_after=float(row[11]),
@@ -2007,24 +2039,78 @@ class PostgresPortfolioRepository:
     def _manual_total_value(self, cash: float, quantity: float, price: float, buffer: float) -> float:
         return float(cash) + float(quantity) * float(price) + float(buffer)
 
+    @staticmethod
+    def _validate_ledger_decimal(value: Decimal, *, field_name: str, allow_zero: bool) -> Decimal:
+        if value.is_nan() or value.is_infinite():
+            raise ValueError(f"{field_name} must be a finite decimal")
+        if allow_zero:
+            if value < 0:
+                raise ValueError(f"{field_name} must be greater than or equal to 0")
+        elif value <= 0:
+            raise ValueError(f"{field_name} must be greater than 0")
+        scale = max(-value.as_tuple().exponent, 0)
+        if scale > _LEDGER_NUMERIC_SCALE:
+            raise ValueError(f"{field_name} exceeds NUMERIC(20,8) precision")
+        digits = len(value.copy_abs().as_tuple().digits)
+        integer_digits = max(digits - scale, 0)
+        if value == 0:
+            integer_digits = 0
+        if integer_digits > _LEDGER_MAX_INTEGER_DIGITS:
+            raise ValueError(f"{field_name} exceeds NUMERIC(20,8) precision")
+        return value.quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
+
+    @classmethod
+    def _coerce_ledger_decimal(cls, value: Any, *, field_name: str, allow_zero: bool) -> Decimal:
+        try:
+            decimal_value = Decimal(str(value))
+        except (InvalidOperation, ValueError, TypeError):
+            raise ValueError(f"{field_name} must be a decimal") from None
+        return cls._validate_ledger_decimal(decimal_value, field_name=field_name, allow_zero=allow_zero)
+
+    @staticmethod
+    def _coerce_portfolio_snapshot_decimal(value: Any, *, field_name: str) -> Decimal:
+        try:
+            decimal_value = Decimal(str(value))
+        except (InvalidOperation, ValueError, TypeError):
+            raise ValueError(f"{field_name} must be a decimal") from None
+        if decimal_value.is_nan() or decimal_value.is_infinite():
+            raise ValueError(f"{field_name} must be a finite decimal")
+        return decimal_value
+
+    @staticmethod
+    def _to_snapshot_float_and_ledger_decimal(value: Decimal, *, field_name: str) -> tuple[float, Decimal]:
+        if value.is_nan() or value.is_infinite():
+            raise ValueError(f"{field_name} must be a finite decimal")
+        try:
+            as_float = float(value)
+        except (OverflowError, ValueError):
+            raise ValueError(f"{field_name} cannot be represented in DOUBLE PRECISION snapshot") from None
+        expected_ledger = value.quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
+        actual_ledger = Decimal(str(as_float)).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
+        if actual_ledger != expected_ledger:
+            raise ValueError(f"{field_name} cannot be represented in DOUBLE PRECISION snapshot")
+        return as_float, actual_ledger
+
     def record_manual_ledger(
         self,
         portfolio_id: str,
         *,
         action: str,
-        amount: float | None = None,
-        quantity: float | None = None,
-        price: float | None = None,
-        fee: float = 0.0,
-        tax: float = 0.0,
+        amount: Decimal | None = None,
+        quantity: Decimal | None = None,
+        price: Decimal | None = None,
+        fee: Decimal = Decimal(0),
+        tax: Decimal = Decimal(0),
+        executed_at: datetime | None = None,
         target_ledger_entry_id: int | None = None,
         note: str = "",
         actor_user_id: str | None = None,
         confirmation_evidence: str | None = None,
+        confirm_duplicate: bool = False,
     ) -> LedgerEntry:
         self.ensure_schema()
         normalized = str(action).upper()
-        if normalized not in {"INVEST", "BUFFER_OUT", "BUFFER_IN", "BUY", "SELL", "WITHDRAW", "PROFIT", "REVERSAL"}:
+        if normalized not in {"INVEST", "BUFFER_OUT", "BUFFER_IN", "BUY", "SELL", "WITHDRAW", "PROFIT", "DIVIDEND", "REVERSAL"}:
             raise ValueError("unsupported manual ledger action")
         conn = self._connect()
         with conn.transaction():
@@ -2034,16 +2120,18 @@ class PostgresPortfolioRepository:
                 if row is None:
                     raise ValueError("포트폴리오를 찾을 수 없습니다")
                 portfolio = self._row_to_portfolio(row)
-                cash = float(portfolio.cash_balance)
-                qty = float(portfolio.asset_quantity)
-                buffer = float(portfolio.profit_buffer)
-                asset_price = float(portfolio.price)
-                ledger_price = float(price or 0.0)
-                ledger_quantity = float(quantity or 0.0)
-                fee_f = float(fee or 0.0)
-                tax_f = float(tax or 0.0)
-                amount_f = float(amount or 0.0)
-                reverse_target: LedgerEntry | None = None
+                cash = self._coerce_portfolio_snapshot_decimal(portfolio.cash_balance, field_name="cash_balance")
+                qty = self._coerce_portfolio_snapshot_decimal(portfolio.asset_quantity, field_name="asset_quantity")
+                buffer = self._coerce_portfolio_snapshot_decimal(portfolio.profit_buffer, field_name="profit_buffer")
+                asset_price = self._coerce_portfolio_snapshot_decimal(portfolio.price, field_name="asset_price")
+                ledger_price = self._coerce_ledger_decimal(price or 0, field_name="price", allow_zero=True)
+                ledger_quantity = self._coerce_ledger_decimal(quantity or 0, field_name="quantity", allow_zero=True)
+                fee_f = self._coerce_ledger_decimal(fee or 0, field_name="fee", allow_zero=True)
+                tax_f = self._coerce_ledger_decimal(tax or 0, field_name="tax", allow_zero=True)
+                amount_f = self._coerce_ledger_decimal(amount or 0, field_name="amount", allow_zero=True)
+                ledger_executed_at = executed_at or datetime.now(UTC)
+                if ledger_executed_at.tzinfo is None:
+                    ledger_executed_at = ledger_executed_at.replace(tzinfo=UTC)
 
                 if normalized == "INVEST":
                     buffer += amount_f
@@ -2060,18 +2148,42 @@ class PostgresPortfolioRepository:
                     cash -= amount_f
                     buffer += amount_f
                     ledger_price = amount_f
-                elif normalized == "WITHDRAW":
+                elif normalized == "WITHDRAW" or normalized == "PROFIT":
                     if buffer < amount_f:
                         raise ValueError("INSUFFICIENT_BUFFER")
                     buffer -= amount_f
                     ledger_price = amount_f
-                elif normalized == "PROFIT":
-                    if buffer < amount_f:
-                        raise ValueError("INSUFFICIENT_BUFFER")
-                    buffer -= amount_f
+                elif normalized == "DIVIDEND":
+                    if not confirm_duplicate:
+                        cur.execute(
+                            """
+                            SELECT existing.ledger_entry_id
+                            FROM portfolio_ledger AS existing
+                            WHERE existing.portfolio_id = %s
+                              AND existing.source = 'manual'
+                              AND existing.side = 'dividend'
+                              AND existing.price = %s::numeric(20,8)
+                              AND existing.executed_at = %s
+                              AND existing.note = %s
+                              AND NOT EXISTS (
+                                  SELECT 1
+                                  FROM portfolio_ledger AS reversal
+                                  WHERE reversal.portfolio_id = existing.portfolio_id
+                                    AND reversal.side = 'reversal'
+                                    AND reversal.target_ledger_entry_id = existing.ledger_entry_id
+                              )
+                            ORDER BY existing.ledger_entry_id DESC
+                            LIMIT 1
+                            """,
+                            (portfolio_id, amount_f, ledger_executed_at, note),
+                        )
+                        duplicate_row = cur.fetchone()
+                        if duplicate_row is not None:
+                            raise ValueError(f"POTENTIAL_DUPLICATE_DIVIDEND:{int(duplicate_row[0])}")
+                    buffer += amount_f
                     ledger_price = amount_f
                 elif normalized == "BUY":
-                    required = ledger_quantity * ledger_price + fee_f + tax_f
+                    required = (ledger_quantity * ledger_price + fee_f + tax_f).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
                     if cash < required:
                         raise ValueError("INSUFFICIENT_CASH")
                     cash -= required
@@ -2080,7 +2192,7 @@ class PostgresPortfolioRepository:
                 elif normalized == "SELL":
                     if qty < ledger_quantity:
                         raise ValueError("INSUFFICIENT_QUANTITY")
-                    cash += ledger_quantity * ledger_price - fee_f - tax_f
+                    cash += (ledger_quantity * ledger_price - fee_f - tax_f).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
                     qty -= ledger_quantity
                     asset_price = ledger_price
                 elif normalized == "REVERSAL":
@@ -2097,26 +2209,29 @@ class PostgresPortfolioRepository:
                         """,
                         (portfolio_id, target_ledger_entry_id),
                     )
-                    reverse_target = self._row_to_ledger_entry(cur.fetchone())
+                    reverse_target_row = cur.fetchone()
+                    if reverse_target_row is None:
+                        raise ValueError("LEDGER_ENTRY_NOT_FOUND")
                     cur.execute(
                         "SELECT 1 FROM portfolio_ledger WHERE portfolio_id = %s AND side = 'reversal' AND target_ledger_entry_id = %s LIMIT 1",
                         (portfolio_id, target_ledger_entry_id),
                     )
                     if cur.fetchone() is not None:
                         raise ValueError("LEDGER_ENTRY_ALREADY_REVERSED")
-                    target_action = (reverse_target.action or "").upper()
-                    amount_f = float(reverse_target.price)
-                    ledger_price = float(reverse_target.price)
-                    ledger_quantity = float(reverse_target.quantity)
-                    fee_f = float(reverse_target.fee_amount)
-                    tax_f = float(reverse_target.tax_amount)
+                    target_action = str(reverse_target_row[4] or "").upper()
+                    amount_f = self._coerce_ledger_decimal(reverse_target_row[6], field_name="amount", allow_zero=True)
+                    ledger_price = self._coerce_ledger_decimal(reverse_target_row[6], field_name="price", allow_zero=True)
+                    ledger_quantity = self._coerce_ledger_decimal(reverse_target_row[5], field_name="quantity", allow_zero=True)
+                    fee_f = self._coerce_ledger_decimal(reverse_target_row[7], field_name="fee", allow_zero=True)
+                    tax_f = self._coerce_ledger_decimal(reverse_target_row[8], field_name="tax", allow_zero=True)
                     if target_action == "BUY":
-                        cash += ledger_quantity * ledger_price + fee_f + tax_f
+                        cash += (ledger_quantity * ledger_price + fee_f + tax_f).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
                         qty -= ledger_quantity
                     elif target_action == "SELL":
-                        if cash < ledger_quantity * ledger_price - fee_f - tax_f:
+                        required_cash = (ledger_quantity * ledger_price - fee_f - tax_f).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
+                        if cash < required_cash:
                             raise ValueError("INSUFFICIENT_CASH")
-                        cash -= ledger_quantity * ledger_price - fee_f - tax_f
+                        cash -= required_cash
                         qty += ledger_quantity
                     elif target_action == "BUFFER_OUT":
                         if cash < amount_f:
@@ -2128,7 +2243,7 @@ class PostgresPortfolioRepository:
                             raise ValueError("INSUFFICIENT_BUFFER")
                         cash += amount_f
                         buffer -= amount_f
-                    elif target_action == "INVEST":
+                    elif target_action in {"INVEST", "DIVIDEND"}:
                         if buffer < amount_f:
                             raise ValueError("INSUFFICIENT_BUFFER")
                         buffer -= amount_f
@@ -2144,7 +2259,25 @@ class PostgresPortfolioRepository:
                 if buffer < 0:
                     raise ValueError("INSUFFICIENT_BUFFER")
 
-                total_value = self._manual_total_value(cash, qty, asset_price, buffer)
+                snapshot_cash_float, snapshot_cash_ledger = self._to_snapshot_float_and_ledger_decimal(
+                    cash,
+                    field_name="cash_balance_after",
+                )
+                snapshot_qty_float, snapshot_qty_ledger = self._to_snapshot_float_and_ledger_decimal(
+                    qty,
+                    field_name="asset_quantity_after",
+                )
+                snapshot_price_float, _ = self._to_snapshot_float_and_ledger_decimal(
+                    asset_price,
+                    field_name="asset_price",
+                )
+                snapshot_buffer_float, snapshot_buffer_ledger = self._to_snapshot_float_and_ledger_decimal(
+                    buffer,
+                    field_name="profit_buffer_after",
+                )
+                total_value = (
+                    snapshot_cash_ledger + snapshot_qty_ledger * Decimal(str(snapshot_price_float)) + snapshot_buffer_ledger
+                ).quantize(_LEDGER_QUANT, rounding=ROUND_HALF_UP)
                 cur.execute(
                     """
                     UPDATE portfolios
@@ -2156,7 +2289,7 @@ class PostgresPortfolioRepository:
                         last_trade_at = NOW()
                     WHERE portfolio_id = %s
                     """,
-                    (cash, qty, asset_price, buffer, portfolio_id),
+                    (snapshot_cash_float, snapshot_qty_float, snapshot_price_float, snapshot_buffer_float, portfolio_id),
                 )
                 cur.execute(
                     """
@@ -2165,7 +2298,7 @@ class PostgresPortfolioRepository:
                         tax_amount, cash_balance_after, asset_quantity_after,
                         total_value_after, profit_buffer_after, strategy_set_id, note, executed_at,
                         source, target_ledger_entry_id, confirmation_evidence, actor_user_id
-                    ) VALUES (%s, NOW(), %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, NOW(), %s, %s, %s, %s)
+                    ) VALUES (%s, NOW(), %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
                     RETURNING ledger_entry_id, portfolio_id, order_id, execution_id, side, quantity, price,
                               fee_amount, tax_amount, executed_at, recorded_at, cash_balance_after,
                               asset_quantity_after, total_value_after, profit_buffer_after, strategy_set_id,
@@ -2174,16 +2307,17 @@ class PostgresPortfolioRepository:
                     (
                         portfolio_id,
                         normalized.lower(),
-                        float(ledger_price),
-                        float(ledger_quantity),
-                        float(fee_f),
-                        float(tax_f),
-                        float(cash),
-                        float(qty),
-                        float(total_value),
-                        float(buffer),
+                        ledger_price,
+                        ledger_quantity,
+                        fee_f,
+                        tax_f,
+                        snapshot_cash_ledger,
+                        snapshot_qty_ledger,
+                        total_value,
+                        snapshot_buffer_ledger,
                         "manual",
                         note,
+                        ledger_executed_at,
                         "manual",
                         target_ledger_entry_id,
                         confirmation_evidence,
@@ -2620,7 +2754,8 @@ class PostgresPortfolioRepository:
                 raise ValueError(f"asset을 찾을 수 없습니다: {asset_id}")
 
     def rotate_service_token(self, name: str) -> tuple[str, AuthToken]:
-        from app.core.security import generate_token, hash_token, token_prefix as _token_prefix
+        from app.core.security import generate_token, hash_token
+        from app.core.security import token_prefix as _token_prefix
 
         self.ensure_schema()
         with self._connect().cursor() as cur:
@@ -2956,10 +3091,9 @@ def database_exists(config: PortfolioDBConfig, *, maintenance_db: str = "postgre
         connect_timeout=config.connect_timeout_sec,
         application_name=config.application_name,
         autocommit=True,
-    ) as conn:
-        with conn.cursor() as cur:
-            cur.execute("SELECT 1 FROM pg_database WHERE datname = %s", (config.dbname,))
-            return cur.fetchone() is not None
+    ) as conn, conn.cursor() as cur:
+        cur.execute("SELECT 1 FROM pg_database WHERE datname = %s", (config.dbname,))
+        return cur.fetchone() is not None
 
 
 def create_database_if_missing(config: PortfolioDBConfig, *, maintenance_db: str = "postgres") -> bool:

app/schemas/v1.py

@@ -8,7 +8,6 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
-
 # ---------------------------------------------------------------------------
 # GET/POST/PATCH /v1/tags (REQ-004)
 # ---------------------------------------------------------------------------
@@ -114,8 +113,8 @@ class LedgerTradeRequest(BaseModel):
     side: Literal["buy", "sell"]
     quantity: Decimal = Field(..., gt=0)
     price: Decimal = Field(..., gt=0)
-    fee_amount: Decimal = Field(default=Decimal("0"), ge=0)
-    tax_amount: Decimal = Field(default=Decimal("0"), ge=0)
+    fee_amount: Decimal = Field(default=Decimal(0), ge=0)
+    tax_amount: Decimal = Field(default=Decimal(0), ge=0)
     executed_at: datetime
 
 
@@ -148,6 +147,7 @@ ManualLedgerAction = Literal[
     "SELL",
     "WITHDRAW",
     "PROFIT",
+    "DIVIDEND",
     "REVERSAL",
 ]
 
@@ -156,22 +156,27 @@ class ManualLedgerRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     action: ManualLedgerAction
-    amount: Decimal | None = Field(default=None, gt=0)
-    quantity: Decimal | None = Field(default=None, gt=0)
-    price: Decimal | None = Field(default=None, gt=0)
-    fee: Decimal = Field(default=Decimal("0"), ge=0)
-    tax: Decimal = Field(default=Decimal("0"), ge=0)
+    amount: Decimal | None = Field(default=None, gt=0, max_digits=20, decimal_places=8)
+    quantity: Decimal | None = Field(default=None, gt=0, max_digits=20, decimal_places=8)
+    price: Decimal | None = Field(default=None, gt=0, max_digits=20, decimal_places=8)
+    fee: Decimal = Field(default=Decimal(0), ge=0, max_digits=20, decimal_places=8)
+    tax: Decimal = Field(default=Decimal(0), ge=0, max_digits=20, decimal_places=8)
+    executed_at: date | None = None
     target_ledger_entry_id: int | None = None
     note: str = ""
     confirm_daemon_managed_manual_write: bool = False
+    confirm_duplicate: bool = False
     confirmation_evidence: str | None = None
 
     @model_validator(mode="after")
-    def validate_action_fields(self) -> "ManualLedgerRequest":
+    def validate_action_fields(self) -> ManualLedgerRequest:
         amount_actions = {"INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT"}
         trade_actions = {"BUY", "SELL"}
         provided_fields = self.model_fields_set
         fee_or_tax_provided = "fee" in provided_fields or "tax" in provided_fields
+        fee_provided = "fee" in provided_fields
+        executed_at_provided = "executed_at" in provided_fields
+        confirm_duplicate_requested = bool(self.confirm_duplicate)
         if self.action in amount_actions:
             if self.amount is None:
                 raise ValueError("amount is required for this action")
@@ -180,17 +185,33 @@ class ManualLedgerRequest(BaseModel):
                 or self.price is not None
                 or self.target_ledger_entry_id is not None
                 or fee_or_tax_provided
+                or executed_at_provided
+                or confirm_duplicate_requested
             ):
                 raise ValueError("unexpected numeric/target field for amount action")
+        elif self.action == "DIVIDEND":
+            if self.amount is None:
+                raise ValueError("amount is required for this action")
+            if self.executed_at is None:
+                raise ValueError("executed_at is required for DIVIDEND")
+            if self.quantity is not None or self.price is not None or self.target_ledger_entry_id is not None or fee_provided:
+                raise ValueError("unexpected numeric/target field for DIVIDEND")
         elif self.action in trade_actions:
             if self.quantity is None or self.price is None:
                 raise ValueError("quantity and price are required for BUY/SELL")
-            if self.amount is not None or self.target_ledger_entry_id is not None:
+            if self.amount is not None or self.target_ledger_entry_id is not None or executed_at_provided or confirm_duplicate_requested:
                 raise ValueError("unexpected amount/target field for BUY/SELL")
         elif self.action == "REVERSAL":
             if self.target_ledger_entry_id is None:
                 raise ValueError("target_ledger_entry_id is required for REVERSAL")
-            if self.amount is not None or self.quantity is not None or self.price is not None or fee_or_tax_provided:
+            if (
+                self.amount is not None
+                or self.quantity is not None
+                or self.price is not None
+                or fee_or_tax_provided
+                or executed_at_provided
+                or confirm_duplicate_requested
+            ):
                 raise ValueError("unexpected numeric field for REVERSAL")
         return self
 
@@ -198,12 +219,34 @@ class ManualLedgerRequest(BaseModel):
 class ManualLedgerResponse(BaseModel):
     ledger_entry_id: int
     portfolio_id: str
-    action: str
+    action: Literal["INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT", "BUY", "SELL", "REVERSAL"]
     amount: float | None = None
     quantity: float = 0.0
     price: float = 0.0
     fee: float = 0.0
     tax: float = 0.0
+    executed_at: datetime | None = None
+    note: str = ""
+    recorded_at: datetime | None = None
+    cash_balance_after: float = 0.0
+    asset_quantity_after: float = 0.0
+    profit_buffer_after: float = 0.0
+    total_value_after: float = 0.0
+    source: str = "manual"
+    target_ledger_entry_id: int | None = None
+    confirmation_evidence: str | None = None
+
+
+class DividendManualLedgerResponse(BaseModel):
+    ledger_entry_id: int
+    portfolio_id: str
+    action: Literal["DIVIDEND"]
+    amount: str
+    quantity: float = 0.0
+    price: float = 0.0
+    fee: float = 0.0
+    tax: str = "0"
+    executed_at: datetime | None = None
     note: str = ""
     recorded_at: datetime | None = None
     cash_balance_after: float = 0.0
@@ -216,7 +259,7 @@ class ManualLedgerResponse(BaseModel):
 
 
 class ManualLedgerHistoryResponse(BaseModel):
-    items: list[ManualLedgerResponse]
+    items: list[ManualLedgerResponse | DividendManualLedgerResponse]
     total: int
 
 
@@ -226,12 +269,13 @@ class LedgerHistoryItem(BaseModel):
     ledger_entry_id: int
     portfolio_id: str
     source: str
-    action: str
+    action: Literal["INVEST", "BUFFER_OUT", "BUFFER_IN", "WITHDRAW", "PROFIT", "BUY", "SELL", "REVERSAL"]
     recorded_at: datetime
     executed_at: datetime | None = None
     order_id: str | None = None
     execution_id: str | None = None
     quantity: float | None = None
+    amount: float | None = None
     price: float | None = None
     fee_amount: float | None = None
     tax_amount: float | None = None
@@ -244,8 +288,33 @@ class LedgerHistoryItem(BaseModel):
     confirmation_evidence: str | None = None
 
 
+class DividendLedgerHistoryItem(BaseModel):
+    """Source-neutral, owner-visible ledger fact for GET /ledger."""
+
+    ledger_entry_id: int
+    portfolio_id: str
+    source: str
+    action: Literal["DIVIDEND"]
+    recorded_at: datetime
+    executed_at: datetime | None = None
+    order_id: str | None = None
+    execution_id: str | None = None
+    quantity: float | None = None
+    amount: str
+    price: float | None = None
+    fee_amount: float | None = None
+    tax_amount: str | None = None
+    note: str | None = None
+    cash_balance_after: float | None = None
+    asset_quantity_after: float | None = None
+    profit_buffer_after: float | None = None
+    total_value_after: float | None = None
+    target_ledger_entry_id: int | None = None
+    confirmation_evidence: str | None = None
+
+
 class LedgerHistoryResponse(BaseModel):
-    items: list[LedgerHistoryItem]
+    items: list[LedgerHistoryItem | DividendLedgerHistoryItem]
     next_cursor: str | None = None
 
 
@@ -283,7 +352,7 @@ class PortfolioCreateRequest(BaseModel):
     asset_quantity: float = Field(default=0.0, ge=0.0)
     asset_price: float = Field(default=0.0, ge=0.0)
     profit_buffer: float = Field(default=0.0, ge=0.0)
-    strategy_id: str = Field(..., min_length=1)
+    strategy_id: str | None = Field(default=None, min_length=1)
     managed_by_daemon_id: str | None = None
     user_id: str | None = None  # admin-only: override owner
 
@@ -394,7 +463,7 @@ class StrategyUpdateRequest(BaseModel):
         return normalized
 
     @model_validator(mode="after")
-    def require_change(self) -> "StrategyUpdateRequest":
+    def require_change(self) -> StrategyUpdateRequest:
         if not self.model_fields_set:
             raise ValueError("at least one field is required")
         return self

docs/container-operations.md

@@ -1,11 +1,11 @@
-# PortfolioHub v0.2.0 container contract
+# PortfolioHub v0.2.1 container contract
 
 ## Publication is not deployment
 
-Only a requester-authorized push of the strict tag `v0.2.0` can publish this revision. The workflow checks that the tag equals `[project].version`, checks out `github.sha`, runs the complete Python suite, builds one `linux/amd64` image from `uv.lock`, and tests those exact bytes before publication. It gives the same image exactly two selectors:
+Only a requester-authorized push of the strict tag `v0.2.1` can publish this revision. The workflow checks that the tag equals `[project].version`, checks out `github.sha`, runs the complete Python suite, builds one `linux/amd64` image from `uv.lock`, and tests those exact bytes before publication. It gives the same image exactly two selectors:
 
 - `ghcr.io/fourblocks2020/portfolio-hub:<source-commit-first-12>`
-- `ghcr.io/fourblocks2020/portfolio-hub:v0.2.0`
+- `ghcr.io/fourblocks2020/portfolio-hub:v0.2.1`
 
 It never publishes `latest`. Both selectors must report the same registry digest; deployment and rollback must use the immutable identity:
 
@@ -13,9 +13,9 @@ It never publishes `latest`. Both selectors must report the same registry digest
 ghcr.io/fourblocks2020/portfolio-hub@sha256:<64-lowercase-hex-digest>
 ```
 
-OCI labels are fail-closed build inputs: `org.opencontainers.image.source`, the full 40-character `org.opencontainers.image.revision`, and strict `org.opencontainers.image.version=v0.2.0`. Publication does **not** deploy, replace, start, stop, or restart a production service. This repository provides no production Compose, Kubernetes, Helm, systemd, or Dockge configuration.
+OCI labels are fail-closed build inputs: `org.opencontainers.image.source`, the full 40-character `org.opencontainers.image.revision`, and strict `org.opencontainers.image.version=v0.2.1`. Publication does **not** deploy, replace, start, stop, or restart a production service. This repository provides no production Compose, Kubernetes, Helm, systemd, or Dockge configuration.
 
-The Dockerfile frontend, Python base image, uv image, and GitHub Actions are digest/commit pinned. The workflow intentionally uses `--provenance=false` to preserve the tested `docker save` archive and build-once/no-rebuild identity. Registry-attached provenance, SBOM, signing, and attestations are a nonblocking v0.2.0 supply-chain gap; they must not be added by rebuilding a different image in the publish job.
+The Dockerfile frontend, Python base image, uv image, and GitHub Actions are digest/commit pinned. The workflow intentionally uses `--provenance=false` to preserve the tested `docker save` archive and build-once/no-rebuild identity. Registry-attached provenance, SBOM, signing, and attestations are a nonblocking v0.2.1 supply-chain gap; they must not be added by rebuilding a different image in the publish job.
 
 ## Image runtime
 
@@ -66,19 +66,19 @@ Values are read at process start; changing any value requires a container restar
 | `PORTFOLIOHUB_BOOTSTRAP_PASSWORD` | optional; empty | **yes** | bootstrap password; inject temporarily and remove after first successful start |
 | `PORTFOLIOHUB_ENVIRONMENT` | optional; `development` | no | reported environment metadata |
 | `PORTFOLIOHUB_APP_NAME` | optional; `PortfolioHub` | no | application/OpenAPI display name |
-| `PORTFOLIOHUB_APP_VERSION` | do not override for v0.2.0 | `0.2.0` | no | health/OpenAPI version metadata |
+| `PORTFOLIOHUB_APP_VERSION` | do not override for v0.2.1 | `0.2.1` | no | health/OpenAPI version metadata |
 
-`REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, `REDIS_PASSWORD`, `LOKI_HOST`, `LOKI_PORT`, and `LOKI_ENABLED` are still parsed for source compatibility but the inspected v0.2.0 application does not open Redis or Loki connections. They are not production dependencies of this image.
+`REDIS_HOST`, `REDIS_PORT`, `REDIS_DB`, `REDIS_PASSWORD`, `LOKI_HOST`, `LOKI_PORT`, and `LOKI_ENABLED` are still parsed for source compatibility but the inspected v0.2.1 application does not open Redis or Loki connections. They are not production dependencies of this image.
 
 ### Legacy and sibling mapping
 
-The existing database variable names remain `TIMESCALEDB_*`; v0.2.0 deliberately does not invent a `DATABASE_URL` alias. Existing `PORTFOLIOHUB_{READ,TRADE_WRITE,ADMIN}_TOKENS` Bearer-token behavior remains compatible. `trex-core`'s `TREX_PORTFOLIO_HUB_BASE_URL` and TOML `portfolio_hub_token`, and `trex-web`'s server-only `PORTFOLIO_HUB_API_BASE_URL`, are **caller-side** settings: point them to `http://portfolio-hub:8000` (or the equivalent service URL) and do not inject them into this container.
+The existing database variable names remain `TIMESCALEDB_*`; v0.2.1 deliberately does not invent a `DATABASE_URL` alias. Existing `PORTFOLIOHUB_{READ,TRADE_WRITE,ADMIN}_TOKENS` Bearer-token behavior remains compatible. `trex-core`'s `TREX_PORTFOLIO_HUB_BASE_URL` and TOML `portfolio_hub_token`, and `trex-web`'s server-only `PORTFOLIO_HUB_API_BASE_URL`, are **caller-side** settings: point them to `http://portfolio-hub:8000` (or the equivalent service URL) and do not inject them into this container.
 
 ## Liveness and readiness
 
 - **Liveness:** unauthenticated `GET /health` must return HTTP 200 with `status=ok`. It is intentionally process-only and does not query PostgreSQL. `db_enabled` only reports configuration; it is not readiness.
 - **Readiness:** run `pfhub --format json health-check` with the same runtime environment. With DB enabled it performs a repository ping, reads `alembic_version` without migration, compares it with the single packaged Alembic head, and exits nonzero on connectivity, missing schema, multiple heads, or revision mismatch.
-- **API identity:** `GET /openapi.json` is stable for smoke verification. Health version is `0.2.0`.
+- **API identity:** `GET /openapi.json` is stable for smoke verification. Health version is `0.2.1`.
 
 Do not route traffic from a static `/health` success alone. Readiness checks never apply, stamp, or repair migrations.
 
@@ -97,7 +97,7 @@ The installed image contains exactly **30** migration files and one Alembic head
 
 Migration `0029` is additive/idempotent around the strategy catalog: it preserves existing strategy IDs and portfolio references, reuses the canonical `target_value`/`{}` strategy, and backfills catalog data. Before migration, inspect duplicate or invalid strategy references and take a backup. After migration, verify strategy listing and portfolio active-strategy fields before resuming writes.
 
-v0.2.0 adds migration `0030`, an idempotent index on `(portfolio_id, recorded_at DESC, ledger_entry_id DESC)` for unified-ledger keyset reads. Operators at `0029` must run the same-image one-shot migration before rollout; it advances to `20260820_0030` without mutating ledger rows.
+v0.2.1 includes migration `0030`, an idempotent index on `(portfolio_id, recorded_at DESC, ledger_entry_id DESC)` for unified-ledger keyset reads. Operators at `0029` must run the same-image one-shot migration before rollout; it advances to `20260820_0030` without mutating ledger rows.
 
 A pre-Alembic legacy schema is detected only when all three tables `strategy_sets`, `portfolios`, and `portfolio_ledger` exist; the CLI stamps `0027` and then runs real upgrades through `0030`. This compatibility path must be used only after backup and schema review. A partially matching schema is not auto-stamped and must fail for operator investigation.
 
@@ -105,13 +105,13 @@ Image rollback is **not** database rollback. Selecting older application bytes d
 
 ## API verification and known caller blockers
 
-v0.2.0 preserves Bearer authentication and adds all-source unified-ledger reads. The release gate runs the complete portfolio-hub source test suite (including auth success/failure, strategy catalog/data, portfolio and ledger APIs), then verifies the built image's health/OpenAPI surface, exact 30-file migration inventory, isolated PostgreSQL migration twice, readiness at `0030`, persistent-volume restart, non-root/read-only operation, secret canary absence, and graceful SIGTERM. Publication consumes the tested archive without rebuilding it.
+v0.2.1 preserves Bearer authentication and adds all-source unified-ledger reads. The release gate runs the complete portfolio-hub source test suite (including auth success/failure, strategy catalog/data, portfolio and ledger APIs), then verifies the built image's health/OpenAPI surface, exact 30-file migration inventory, isolated PostgreSQL migration twice, readiness at `0030`, persistent-volume restart, non-root/read-only operation, secret canary absence, and graceful SIGTERM. Publication consumes the tested archive without rebuilding it.
 
 The strategy catalog API remains additive: strategy responses expose `nick`, admin create/update requests may set it, and portfolio responses expose the current strategy as `strategy_nick`. Existing clients may omit `nick`; supplied values are trimmed and blank-only values are rejected. trex-web v0.2.3 displays `strategy_nick`, but that dependency does not resolve or waive the separate caller blockers below.
 
 Route presence is **not** a positive cross-repository caller-compatibility claim. Direct source comparison found the following unresolved consumers, which the requester explicitly separated as BLOCKED follow-up rather than adding legacy shims to portfolio-hub:
 
-- trex-web omits required `strategy_id` when creating a portfolio, so that mutation currently returns `422`;
+- trex-web may create a portfolio without `strategy_id`; portfolio-hub must preserve that strategy-unassigned request as `active_strategy_id=null` rather than selecting a default strategy implicitly;
 - trex-web can omit required `account_ref` when creating or rotating credentials, so those requests currently return `422`;
 - trex-web sends daemon activation state through the general PATCH route, which can return `200` without changing activation; it must use the activate/deactivate routes;
 - portfolio-hub returns singular `broker` from `/v1/user_info`, while trex-web types `brokers[]`;

docs/data-model.md

@@ -341,6 +341,7 @@
 - BUFFER_IN: cash_balance -> profit_buffer.
 - BUY: cash_balance -> asset_quantity.
 - SELL: asset_quantity -> cash_balance.
+- DIVIDEND: external net cash dividend -> profit_buffer only; `tax_amount` is reference metadata and does not affect snapshot math.
 - REVERSAL: append-only inverse effect of `target_ledger_entry_id`.
 
 ### Return Aggregate Semantics
@@ -356,6 +357,8 @@
 
 - Manual writes lock the portfolio row while calculating/appending/updating snapshots to avoid lost updates.
 - Manual writes reject insufficient cash/quantity/buffer with HTTP 409 rather than creating a new negative state.
+- DIVIDEND duplicate candidate (`portfolio_id`, `executed_at` UTC date, decimal `amount`, `note`) returns HTTP 409 `POTENTIAL_DUPLICATE_DIVIDEND` unless request confirms with `confirm_duplicate=true`.
+- DIVIDEND uses date-only input stored as `executed_at` UTC midnight (`00:00:00Z`).
 - `total_value_after` for manual entries is the portfolio snapshot value after the mutation and includes cash, asset valuation, and profit buffer.
 
 ## Shared Consistency Rules
@@ -369,7 +372,7 @@
 
 - Alembic revisions in migrations/versions/ are the ordered schema history for persistent environments.
 - app/repositories/postgres.py includes ensure_schema() for bootstrap safety, but long-term schema evolution should run through Alembic.
-- Current Alembic head is `20260814_0029`; its strategy columns, default seed, and constraints are guarded for ensure_schema-first and repeatable execution.
+- Current Alembic head is `20260820_0030`; the preceding `0029` strategy columns, default seed, and constraints and the `0030` unified-ledger keyset index are guarded for ensure_schema-first and repeatable execution.
 - Comments, tags, auth tokens, and ledger rows are normalized into dedicated tables keyed to users or portfolios.
 
 ## Current Gaps / Planned Changes

docs/interface-contract.md

@@ -302,11 +302,11 @@
 ### Endpoint: `POST /v1/portfolios`
 
 - Auth: any valid token; service/client → HTTP 403
-- Body: `{"asset_id": "<uuid>", "broker": "<str>", "name": "<str|null>", "cash_balance": <float>, "asset_quantity": <float>, "asset_price": <float>, "profit_buffer": <float>, "strategy_id": "<required strategy ID>", "managed_by_daemon_id": "<str|null>", "user_id": "<str|null> (admin only)"}`
-- Response: HTTP 201 `PortfolioItem {"portfolio_id": "<uuid>", ..., "active_strategy_id": "<str>", "strategy_name": "<str>", "strategy_params": {<dict>}, "strategy_revision": <int>, ...}`
+- Body: `{"asset_id": "<uuid>", "broker": "<str>", "name": "<str|null>", "cash_balance": <float>, "asset_quantity": <float>, "asset_price": <float>, "profit_buffer": <float>, "strategy_id": "<active strategy ID|null (optional)>", "managed_by_daemon_id": "<str|null>", "user_id": "<str|null> (admin only)"}`
+- Response: HTTP 201 `PortfolioItem {"portfolio_id": "<uuid>", ..., "active_strategy_id": "<str|null>", "strategy_name": "<str|null>", "strategy_params": {<dict>}, "strategy_revision": <int|null>, ...}`
 - Note: `symbol` is populated from the server-side joined asset row (`portfolios.asset_id -> assets.asset_id -> assets.symbol`), not from client-side catalog reconstruction.
 - Note: a non-null `managed_by_daemon_id` must be a daemon server-generated UUID that exists, is active, and is owned by the target portfolio owner (admin `user_id` override uses the final target owner, not the calling admin). Daemon validation and the portfolio write share one atomic transaction (`FOR SHARE` daemon lock); a selected daemon that is deactivated concurrently is rejected rather than committed.
-- Error: HTTP 403 if service/client token; HTTP 404 if `strategy_id` is unknown or the daemon does not exist/is not owned by the portfolio owner; HTTP 409 if the strategy is inactive or the daemon is inactive; HTTP 422 for a missing/invalid `strategy_id`, an unknown/inactive asset, or a non-UUID `managed_by_daemon_id`
+- Error: HTTP 403 if service/client token; HTTP 404 if a supplied `strategy_id` is unknown or the daemon does not exist/is not owned by the portfolio owner; HTTP 409 if a supplied strategy is inactive or the daemon is inactive; HTTP 422 for an invalid `strategy_id`, an unknown/inactive asset, or a non-UUID `managed_by_daemon_id`
 
 ### Endpoint: `PATCH /v1/portfolios/{portfolio_id}`
 
@@ -418,12 +418,14 @@
 
 - Auth: DB user/session token with portfolio ownership. Service/client tokens and env tokens are HTTP 403 fail-closed.
 - Purpose: trex-web/user 수동 장부 append. Existing `/ledger/trades` remains daemon/service-token broker execution write only.
-- Body: `ManualLedgerRequest` with `action` enum `INVEST|BUFFER_OUT|BUFFER_IN|BUY|SELL|WITHDRAW|PROFIT|REVERSAL`.
+- Body: `ManualLedgerRequest` with `action` enum `INVEST|BUFFER_OUT|BUFFER_IN|BUY|SELL|WITHDRAW|PROFIT|DIVIDEND|REVERSAL`.
   - `INVEST`, `BUFFER_OUT`, `BUFFER_IN`, `WITHDRAW`, `PROFIT` require `amount`.
+  - `DIVIDEND` requires `amount` and date-only `executed_at` (`YYYY-MM-DD`); `executed_at` is stored as UTC midnight (`00:00:00Z`). Optional non-negative `tax` is metadata only.
   - `BUY`, `SELL` require `quantity` and `price`; optional `fee`, `tax` default 0.
-  - `REVERSAL` requires `target_ledger_entry_id`; direct mutation/delete of prior rows is not supported.
+  - Duplicate candidate `DIVIDEND` (same portfolio, same date, same decimal `amount`, same `note`, and original not already reversed): first POST returns HTTP 409 `POTENTIAL_DUPLICATE_DIVIDEND` with `matched_ledger_entry_id`; retry with `confirm_duplicate=true` records the entry.
+  - `REVERSAL` requires `target_ledger_entry_id`; direct mutation/delete of prior rows is not supported. Reversing `DIVIDEND` reduces `profit_buffer` by the original net amount under existing reversal conflict/insufficient-balance policy.
   - `QUANTITY_ADJUSTMENT` is not part of this API.
-- Response: HTTP 201 `ManualLedgerResponse` with `ledger_entry_id`, `portfolio_id`, `action`, `source=manual`, `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`, `target_ledger_entry_id`, `confirmation_evidence`.
+- Response: HTTP 201 `ManualLedgerResponse` with `ledger_entry_id`, `portfolio_id`, `action`, `source=manual`, `executed_at`, `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`, `target_ledger_entry_id`, `confirmation_evidence`.
 - Validation/conflict policy:
   - disabled portfolio → HTTP 409 `PORTFOLIO_DISABLED`.
   - daemon-managed portfolio without `confirm_daemon_managed_manual_write=true` → HTTP 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`.

docs/project-structure.md

@@ -138,7 +138,7 @@
 |-----------|-----------|------|
 | ensure_schema() 전용 | `idx_auth_tokens_service_name_unique` (partial index, BAT-006/REQ-017: `AND revoked_at IS NULL` 조건 추가) | Alembic revision 20260520_0022에도 CONCURRENTLY 버전 존재 |
 | Alembic 전용 | `portfolios.market`, `auth_tokens.runtime_id`, `idx_auth_tokens_runtime_id_unique`, `broker_credentials`, `ledger_trades` | ensure_schema()에 없음 — v1 API 전제 조건 |
-| 양쪽 공유 (IF NOT EXISTS 보호) | users, auth_tokens, strategy_sets (`status`, `revision`, `updated_at` 포함), portfolios, portfolio_ledger, portfolio_comments, portfolio_tags + 대부분의 인덱스 | ensure_schema() 우선 실행 후 Alembic `20260814_0029` 실행 시 충돌 없음; 기본 전략 seed/constraints도 존재 여부 guard 적용 |
+| 양쪽 공유 (IF NOT EXISTS 보호) | users, auth_tokens, strategy_sets (`status`, `revision`, `updated_at` 포함), portfolios, portfolio_ledger, portfolio_comments, portfolio_tags + 대부분의 인덱스 | ensure_schema() 우선 실행 후 Alembic `20260820_0030`까지 실행 시 충돌 없음; 기본 전략 seed/constraints와 unified-ledger keyset index도 존재 여부 guard 적용 |
 
 ### 허용 실행 순서
 

docs/requirements/README.md

@@ -0,0 +1,48 @@
+# Requirements
+
+각 requirement 문서는 Markdown body 앞에 JSON front matter를 둔다.
+
+## File naming
+
+```text
+req-NNN_<slug>.md
+```
+
+- `NNN`: requirement ID의 세 자리 decimal number
+- `<slug>`: requirement title을 나타내는 lowercase kebab-case ASCII slug
+
+## Metadata schema
+
+```json
+{
+  "schema": "proofline.requirement/v1",
+  "id": "REQ-NNN",
+  "title": "사람이 읽는 제목",
+  "revision": "major.minor",
+  "status": "draft | approved | retired",
+  "depends_on": ["REQ-NNN"],
+  "applies_to": ["algorithm-name"],
+  "language": "ko"
+}
+```
+
+- `id`: repository 안에서 고유한 requirement identifier
+- `revision`: 사람이 읽는 requirement revision. `draft` 상태에서 본문을 수정해도 올리지 않으며, `approved` 상태로 전환할 때 또는 승인된 requirement의 의미를 변경하기 위해 재승인할 때만 올린다.
+- `status`: requirement lifecycle 상태. `approved`는 명시적인 사용자 승인을 의미한다.
+- `depends_on`: 선행 requirement identifier 목록
+- `applies_to`: requirement가 적용되는 algorithm 또는 product 영역
+
+## Python parsing
+
+front matter body는 JSON이므로 별도 dependency 없이 Python 표준 라이브러리로 읽을 수 있다.
+
+```python
+import json
+from pathlib import Path
+
+text = Path("docs/requirements/req-001_algorithm-input-contract.md").read_text(encoding="utf-8")
+_, metadata_json, _ = text.split("---", 2)
+metadata = json.loads(metadata_json)
+```
+
+JSON front matter의 `revision`과 `status`가 문서의 단일 source of truth다.

docs/requirements/TEMPLATE.md

@@ -0,0 +1,212 @@
+---
+{
+  "schema": "proofline.requirement/v1",
+  "id": "REQ-NNN",
+  "title": "요구사항 제목",
+  "revision": "0.1",
+  "status": "draft",
+  "depends_on": [],
+  "applies_to": ["product-area"],
+  "language": "ko"
+}
+---
+
+# REQ-NNN — 요구사항 제목
+
+## 1. 목적
+
+이 요구사항으로 달성해야 하는 사용자 또는 시스템의 결과를 기술한다.
+
+## 2. 배경
+
+현재 문제, 요구사항이 필요한 이유, 관련된 운영·도메인 맥락을 기술한다. 구현 방법보다 해결해야 할 문제에 집중한다.
+
+## 3. 범위
+
+### 포함
+
+- 이 요구사항이 제공하거나 변경해야 하는 동작
+- 영향을 받는 API, 데이터, 제품 영역 또는 운영 흐름
+
+### 제외
+
+- 이번 요구사항에서 다루지 않는 기능
+- 별도 requirement 또는 후속 작업으로 분리할 항목
+
+## 4. 용어와 기준
+
+- **용어**: 이 문서에서 사용하는 의미
+- **정본 기준**: 값이나 상태의 canonical source
+
+## 5. 요구사항
+
+`REQ-NNN`은 문서와 기능 묶음의 identifier다. 고객에게 전달할 요구사항명세리스트와 구현 추적에서는 독립적으로 구현·검증할 수 있는 각 요구사항을 `REQ-NNN.01`, `REQ-NNN.02` 형식으로 식별한다.
+
+각 요구사항에는 하네스가 변경 영향과 필요한 회귀 범위를 판정할 수 있도록 `Impact`를 기록한다.
+
+### REQ-NNN.01 — 요구사항 이름
+
+시스템은 관찰 가능한 결과를 명확하게 기술한 조건을 충족해야 한다.
+
+**Impact**
+
+- Interfaces: `<영향받는 API, event 또는 없음>`
+- Persistence: `<영향받는 table, state 또는 없음>`
+- Consumers: `<영향받는 downstream consumer 또는 없음>`
+- Migration: `<필요 여부와 범위>`
+- Compatibility: `<유지해야 하는 기존 동작>`
+- Deployment prerequisites: `<배포 전제조건 또는 없음>`
+
+### REQ-NNN.02 — 요구사항 이름
+
+시스템은 정상 동작뿐 아니라 실패·경계·변경 없음 조건도 명확히 충족해야 한다.
+
+**Impact**
+
+- Interfaces: `<영향받는 API, event 또는 없음>`
+- Persistence: `<영향받는 table, state 또는 없음>`
+- Consumers: `<영향받는 downstream consumer 또는 없음>`
+- Migration: `<필요 여부와 범위>`
+- Compatibility: `<유지해야 하는 기존 동작>`
+- Deployment prerequisites: `<배포 전제조건 또는 없음>`
+
+## 6. 제약과 불변조건
+
+- 구현 방식과 무관하게 항상 유지해야 하는 데이터·상태 불변조건
+- 기존 호출자와 저장 데이터에 대해 유지해야 하는 하위호환 조건
+- 인증·권한·민감정보 처리 조건
+- 원자성, 정밀도, 동시성 또는 순서 보장 조건
+
+## 7. Acceptance Criteria
+
+Acceptance Criterion은 소속 요구사항을 포함한 `REQ-NNN.01-AC01` 형식으로 식별한다. 문서 전체에서만 고유한 `AC-001` 형식은 사용하지 않는다.
+
+### REQ-NNN.01-AC01 — 판정 가능한 결과
+
+**Criterion**
+
+- 하나의 지속적인 요구사항을 PASS 또는 FAIL로 판정할 수 있게 기술한다.
+- 특정 함수명이나 내부 구현보다 외부에서 관찰 가능한 결과를 명시한다.
+
+**Verification**
+
+- 정상 경로 검증 방법
+- 실패 및 경계 조건 검증 방법
+- 변경되면 안 되는 상태의 검증 방법
+- 필요한 경우 실제 persistence backend 또는 production entry point 검증 방법
+
+**Verification Classification**
+
+- Level: `unit | API | integration | end-to-end`
+- Backend: `<검증 대상 backend 또는 없음>`
+- Cases: `positive | negative | boundary | unchanged-state | concurrency`
+
+**State Invariants**
+
+- 성공 시 반드시 변경되어야 하는 상태
+- 성공하더라도 변경되면 안 되는 상태
+- 실패 시 부분 기록 없이 유지되어야 하는 상태
+
+### REQ-NNN.02-AC01 — 판정 가능한 결과
+
+**Criterion**
+
+- 두 번째 독립 요구사항을 기술한다.
+
+**Verification**
+
+- Criterion 전체를 입증할 검증 절차와 기대 결과를 기술한다.
+
+**Verification Classification**
+
+- Level: `unit | API | integration | end-to-end`
+- Backend: `<검증 대상 backend 또는 없음>`
+- Cases: `positive | negative | boundary | unchanged-state | concurrency`
+
+**State Invariants**
+
+- 성공 시 반드시 변경되어야 하는 상태
+- 성공하더라도 변경되면 안 되는 상태
+- 실패 시 부분 기록 없이 유지되어야 하는 상태
+
+## 8. 오류 및 충돌 계약
+
+- 입력 오류: 상태 코드 또는 오류 분류와 무변경 조건
+- 상태 충돌: 재시도·확인·중복 처리 정책
+- 저장 실패: transaction rollback과 부분 기록 방지 조건
+
+## 9. 데이터 및 인터페이스 계약
+
+- 입력 field와 필수·선택 여부
+- 출력 field와 의미
+- 저장해야 하는 canonical 값과 metadata
+- 시간대, 단위, 정밀도 및 식별자 규칙
+
+## 10. 하위호환성
+
+- 유지해야 하는 기존 동작과 호출 방식
+- 기존 데이터에 적용할 규칙
+- 의도적으로 변경되는 동작이 있다면 그 경계
+
+## 11. 검증 계획
+
+- Unit/API contract 검증
+- Persistence migration 및 round-trip 검증
+- 동시성·중복·재시도 검증
+- 기존 기능 회귀 검증
+- OpenAPI 또는 사용자-facing 문서 정합성 검증
+
+### Test Traceability Contract
+
+- Requirement 문서에는 검증 의도와 판정 조건만 기록한다.
+- 실행 가능한 테스트 정의는 별도 test catalog artifact에서 관리한다.
+- 각 테스트 케이스는 안정적인 identifier를 사용하고 `verifies`로 Acceptance Criterion을 참조한다.
+- 하나의 테스트가 여러 Criterion을 검증할 수 있으며, 각 연결을 빠짐없이 기록한다.
+- 실행 결과는 requirement 또는 test definition에 덮어쓰지 않고 별도 evidence artifact에 기록한다.
+- Evidence는 requirement revision, 검증한 commit, 환경과 실행 시각에 결합한다.
+- 테스트 정의의 존재, 자동화 여부, 특정 commit에서의 실행 여부와 PASS 결과를 서로 다른 상태로 취급한다.
+
+Test definition 예시:
+
+```text
+Test ID: TC-NNN-001
+Verifies:
+- REQ-NNN.01-AC01
+Test reference: <test file, case 또는 harness selector>
+Automated: true | false
+```
+
+Execution evidence 예시:
+
+```text
+Test ID: TC-NNN-001
+Requirement revision: REQ-NNN@major.minor
+Commit: <commit SHA>
+Environment: <runtime 및 backend>
+Result: PASS | FAIL | BLOCKED
+Executed at: <timestamp>
+```
+
+## 12. 추적성
+
+- 근거 이슈: `<issue URL 또는 ID>`
+- 구현 PR: `<PR URL 또는 ID>`
+- 관련 설계 문서: `<repository-relative path>`
+- 관련 requirement: `<REQ-NNN 또는 없음>`
+
+## 13. 확정된 결정
+
+- 사용자와 확정한 제품·정책 결정을 기록한다.
+- 확정된 결정은 Open Question으로 다시 남기지 않는다.
+
+## 14. Open Questions
+
+`approved` 전 반드시 결정해야 하며, 각 항목에는 선택지, 권장안, 결정 주체와 종료 조건을 둔다. 미결정 항목이 없으면 `없음`으로 기록한다.
+
+- 없음
+
+## 15. 승인 기록
+
+- 상태: `draft`
+- 승인 주체: 미승인
+- 승인 근거: 없음

docs/requirements/req-001_manual-cash-dividend.md

@@ -0,0 +1,591 @@
+---
+{
+  "schema": "proofline.requirement/v1",
+  "id": "REQ-001",
+  "title": "사용자 입력 현금 배당 원장 기록",
+  "revision": "1.0",
+  "status": "approved",
+  "depends_on": [],
+  "applies_to": ["portfolio-hub", "manual-ledger"],
+  "language": "ko"
+}
+---
+
+# REQ-001 — 사용자 입력 현금 배당 원장 기록
+
+## 1. 목적
+
+사용자는 Broker에서 자동으로 수집하기 어려운 현금 배당의 실제 실수령액을 portfolio-hub의 manual ledger에 직접 기록할 수 있어야 한다. 기록된 배당은 전략 주문 가능 현금과 분리하여 `profit_buffer`에 반영하고, 입력 사실과 변경 후 portfolio 상태를 원장에서 조회하고 정정할 수 있어야 한다.
+
+## 2. 배경
+
+초기 범위에서는 Broker별 배당 조회 기능의 가용성과 형식 차이에 의존하지 않고 사용자가 실제 입금 내역을 직접 기록한다. 배당 실수령액은 투자 원금이나 주문 가능 현금이 아니므로 `cash_balance`에 합산하지 않는다. 잘못 입력한 기록은 기존 append-only `REVERSAL` 흐름으로 상쇄하며, 원본 원장을 수정하거나 삭제하지 않는다.
+
+이 문서는 GitHub 이슈 #31의 확정 계약과 PR #33의 구현 증거를 요구사항으로 정리한 초안이다. 구현 코드와 테스트는 의도의 근거이지만, 이 문서의 `approved` 전환은 별도의 명시적인 사용자 승인을 필요로 한다.
+
+## 3. 범위
+
+### 포함
+
+- manual ledger action `DIVIDEND`
+- 배당 실수령액, 선택적 세금 metadata, 입금일과 메모 입력
+- 입력값 검증과 OpenAPI 계약
+- PostgreSQL 원장 저장과 portfolio snapshot 갱신
+- 중복 후보 경고와 사용자 확인 후 재제출
+- manual ledger 및 unified ledger 조회
+- 기존 `REVERSAL`을 이용한 배당 정정
+- Decimal 정밀도와 transaction 원자성
+- 기존 manual ledger action 하위호환
+- API·저장소·실제 PostgreSQL 검증
+
+### 제외
+
+- Broker 배당 자동 수집 또는 동기화
+- 외화 환산과 다통화 손익
+- 배당 총액(gross amount) 입력
+- 세금 자동 계산·역산과 세율 정책
+- 배당수익 별도 집계
+- 실현손익 또는 기간 수익률 breakdown 변경
+- 배당금을 `cash_balance`나 전략 주문 가능 현금으로 이동하는 기능
+- portfolio-hub CLI의 배당 입력·표시 UX
+- trex-web의 `현금 배당` label, 입력 form과 중복 확인 UX
+- reversal UI
+
+## 4. 용어와 기준
+
+- **실수령액(net cash dividend)**: 세금 등을 제외하고 사용자 계좌에 실제 입금된 배당금. API에서는 `amount`로 표현한다.
+- **세금 metadata**: 사용자가 참고 목적으로 입력하는 `tax`. 자동 계산하지 않으며 portfolio 상태에 영향을 주지 않는다.
+- **입금일**: 사용자가 date-only 형식으로 입력하는 배당 입금 날짜. 기존 `executed_at`에 UTC 자정으로 저장한다.
+- **기록 시각**: 서버가 원장 항목을 append한 시각인 `recorded_at`.
+- **중복 후보**: 동일 portfolio, 동일 UTC 입금일, 동일 Decimal `amount`, 동일 `note`를 가진 reversal되지 않은 기존 `DIVIDEND`.
+- **정본 기준**: 배당 사실과 변경 후 상태는 PostgreSQL `portfolio_ledger`의 append-only 기록 및 그 기록과 같은 transaction에서 갱신된 portfolio snapshot을 기준으로 한다.
+
+## 5. 요구사항
+
+`REQ-001`은 사용자 입력 현금 배당 기능 묶음의 identifier다. 고객 요구사항명세리스트와 구현 추적에서는 독립적으로 구현·검증할 수 있는 다음 항목을 사용한다.
+
+### REQ-001.01 — 현금 배당 입력 계약
+
+시스템은 portfolio 소유 사용자가 manual ledger API를 통해 실제 배당 실수령액, 입금일, 선택적 세금 metadata와 메모를 입력할 수 있게 해야 한다.
+
+**Impact**
+
+- Interfaces: `POST /v1/portfolios/{portfolio_id}/ledger/manual`, OpenAPI
+- Persistence: `portfolio_ledger`
+- Consumers: portfolio-hub API client, 후속 trex-web 연계
+- Migration: 신규 입금일 column 없이 기존 원장 metadata 구조 사용
+- Compatibility: 기존 manual action의 유효 입력 계약 유지
+- Deployment prerequisites: 기존 portfolio-hub PostgreSQL migration head 적용
+
+### REQ-001.02 — 배당에 따른 portfolio 상태 변경
+
+시스템은 유효한 `DIVIDEND`의 `amount`만큼 `profit_buffer`를 증가시키고, `cash_balance`와 `asset_quantity`는 변경하지 않아야 한다. `total_value_after`는 증가한 buffer를 반영해야 하며 `tax`는 모든 상태 계산에서 제외해야 한다.
+
+**Impact**
+
+- Interfaces: manual ledger 생성 응답, ledger 조회 응답
+- Persistence: portfolio snapshot, `portfolio_ledger` after-snapshot
+- Consumers: portfolio valuation과 unified ledger 소비자
+- Migration: 없음
+- Compatibility: 기존 action의 상태 계산식 유지
+- Deployment prerequisites: 없음
+
+### REQ-001.03 — 입금일과 기록 시각 분리
+
+시스템은 date-only 입금일을 기존 `executed_at`에 UTC 자정(`00:00:00Z`)으로 저장하고, `recorded_at`은 서버 append 시각으로 독립적으로 유지해야 한다.
+
+**Impact**
+
+- Interfaces: manual ledger 요청·응답, unified ledger 응답
+- Persistence: 기존 `portfolio_ledger.executed_at`, `recorded_at`
+- Consumers: 입금일 표시와 중복 판정 소비자
+- Migration: 입금일 전용 DB column 추가 없음
+- Compatibility: 기존 원장의 `recorded_at` 의미 유지
+- Deployment prerequisites: 없음
+
+### REQ-001.04 — 배당 원장 저장과 조회
+
+시스템은 배당을 `source=manual`, canonical `action=DIVIDEND`로 append하고, unified ledger에서 배당 금액과 metadata 및 변경 후 snapshot을 직접 조회할 수 있게 해야 한다.
+
+**Impact**
+
+- Interfaces: manual ledger 응답, `GET /v1/portfolios/{portfolio_id}/ledger`, OpenAPI
+- Persistence: `portfolio_ledger`
+- Consumers: portfolio-hub API client, trex-web 원장 화면
+- Migration: 기존 manual ledger metadata column 사용
+- Compatibility: broker 원장과 기존 manual action의 unified ledger 표현 유지
+- Deployment prerequisites: 없음
+
+### REQ-001.05 — 중복 후보 경고와 확인 재제출
+
+시스템은 중복 후보를 자동 기록하지 않고 HTTP 409 경고와 일치한 원장 ID를 반환해야 한다. 사용자가 `confirm_duplicate=true`로 확인한 재요청은 실제 예외 기록으로 허용해야 한다.
+
+**Impact**
+
+- Interfaces: manual ledger 요청의 `confirm_duplicate`, HTTP 409 오류 응답
+- Persistence: 중복 후보 조회와 조건부 append
+- Consumers: 중복 확인 UX를 제공하는 후속 trex-web
+- Migration: 없음
+- Compatibility: 기존 호출자가 새 배당 전용 field를 생략한 경우의 기존 계약 유지
+- Deployment prerequisites: 없음
+
+### REQ-001.06 — DIVIDEND reversal
+
+시스템은 기존 append-only `REVERSAL`로 원본 배당의 실수령액만큼 `profit_buffer`를 감소시켜 배당 효과를 상쇄해야 한다. 원본 원장을 수정하거나 삭제해서는 안 된다.
+
+**Impact**
+
+- Interfaces: 기존 manual `REVERSAL` 요청·응답
+- Persistence: 원본 `DIVIDEND`, 새 `REVERSAL`, portfolio snapshot
+- Consumers: manual ledger와 unified ledger 소비자
+- Migration: 없음
+- Compatibility: 기존 잔액 부족·대상 없음·중복 reversal 정책 유지
+- Deployment prerequisites: 없음
+
+### REQ-001.07 — Decimal 정밀도와 원자적 정합성
+
+시스템은 수용한 Decimal 금액을 입력, 중복 비교, 원장 저장, snapshot 계산과 reversal에서 같은 의미로 유지해야 한다. 원장과 portfolio snapshot이 같은 값을 표현할 수 없는 요청은 어떤 상태도 기록하기 전에 원자적으로 거부해야 한다.
+
+**Impact**
+
+- Interfaces: Decimal 입력 검증과 충돌 응답
+- Persistence: Decimal 원장 값과 portfolio snapshot
+- Consumers: 잔액·원장·reversal 정합성에 의존하는 모든 소비자
+- Migration: column type 변경 없음
+- Compatibility: 수용된 값의 정합성을 보장하면서 기존 manual action 계약 유지
+- Deployment prerequisites: 실제 PostgreSQL 경계값 검증
+
+### REQ-001.08 — 기존 manual ledger 하위호환
+
+시스템은 `DIVIDEND` 도입으로 기존 manual ledger action의 입력, 상태 변경, 충돌과 reversal 계약을 변경해서는 안 된다.
+
+**Impact**
+
+- Interfaces: 기존 manual ledger API 전체
+- Persistence: 기존 action의 원장 및 snapshot 갱신
+- Consumers: 기존 portfolio-hub API client
+- Migration: 없음
+- Compatibility: `INVEST`, `BUFFER_OUT`, `BUFFER_IN`, `BUY`, `SELL`, `WITHDRAW`, `PROFIT`, `REVERSAL` 유지
+- Deployment prerequisites: 기존 action 회귀 검증
+
+### REQ-001.09 — 권한과 민감정보 비노출
+
+시스템은 기존 portfolio 소유권과 manual-write 권한 정책을 유지하고, 배당 기능으로 인해 API·로그·오류 응답에 secret 또는 account 식별정보를 추가로 노출해서는 안 된다.
+
+**Impact**
+
+- Interfaces: 인증된 manual ledger API와 오류 응답
+- Persistence: actor와 기존 감사 metadata
+- Consumers: 사용자 및 운영 로그 소비자
+- Migration: 없음
+- Compatibility: 기존 인증·권한·daemon-managed portfolio 확인 정책 유지
+- Deployment prerequisites: 없음
+
+## 6. 제약과 불변조건
+
+- `amount`는 0보다 큰 Decimal이어야 한다.
+- `tax`는 선택 입력이며 기본값은 `0`이고 음수일 수 없다.
+- `amount`, `tax`와 관련 수치는 원장의 `NUMERIC(20,8)` 범위와 scale을 준수해야 한다.
+- `tax`는 metadata이며 `profit_buffer`, `cash_balance`, `asset_quantity`, `total_value_after` 계산에 영향을 주지 않는다.
+- `quantity`, 거래 `price`, `fee`, 주문·체결 ID와 reversal 대상 ID는 `DIVIDEND` 입력 대상이 아니다.
+- date-only 입금일은 서버 timezone과 무관하게 UTC 자정으로 변환한다.
+- 원장 append와 portfolio snapshot 갱신은 원자적으로 함께 성공하거나 실패해야 한다.
+- 실패하거나 거부된 요청은 원장과 portfolio snapshot을 모두 변경하지 않는다.
+- 원장은 append-only이며 원본 배당을 직접 수정하거나 삭제하지 않는다.
+- 중복 비교는 binary float 근사가 아니라 저장 계약과 동일한 Decimal 의미를 사용한다.
+- `profit_buffer`가 부족한 `DIVIDEND` reversal은 기존 잔액 부족 정책에 따라 거부한다.
+
+
+## 7. Acceptance Criteria
+
+### REQ-001.01-AC01 — 유효한 배당 입력 수용
+
+**Criterion**
+
+portfolio 소유 사용자가 `action=DIVIDEND`, 유효한 `amount`, date-only `executed_at`, 선택적 `tax`와 `note`를 제출하면 시스템은 manual ledger 항목을 생성하고 HTTP 201을 반환한다. `tax` 생략 시 저장 의미는 `0`이다.
+
+**Verification**
+
+- `amount>0`, `tax>=0`, `executed_at=YYYY-MM-DD`인 정상 요청이 HTTP 201인지 확인한다.
+- `tax`를 생략한 요청의 저장·응답 값이 `0`인지 확인한다.
+- 생성 응답의 `action`, `source`, `amount`, `tax`, `executed_at`과 after-snapshot을 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | boundary`
+
+**State Invariants**
+
+- 성공 시 원장 항목이 정확히 하나 추가되어야 한다.
+- 성공 시 `tax`는 portfolio 상태를 변경하지 않아야 한다.
+- 실패한 입력은 원장과 snapshot을 변경하지 않아야 한다.
+
+### REQ-001.01-AC02 — 잘못된 배당 입력 거부
+
+**Criterion**
+
+시스템은 `amount` 또는 입금일이 없거나, 허용 범위를 벗어난 수치 또는 `DIVIDEND`와 무관한 field가 포함된 요청을 원장 기록 전에 거부한다.
+
+**Verification**
+
+- 누락·0·음수·8자리 초과 소수·저장 범위 초과 `amount`를 검증한다.
+- 누락되거나 잘못된 date-only `executed_at`을 검증한다.
+- 음수·8자리 초과 소수·저장 범위를 벗어난 `tax`를 검증한다.
+- `quantity`, `price`, `fee`, `target_ledger_entry_id` 입력을 검증한다.
+- 각 거부가 HTTP 422이며 상태가 변하지 않는지 확인한다.
+
+**Verification Classification**
+
+- Level: `unit | API`
+- Backend: 없음
+- Cases: `negative | boundary | unchanged-state`
+
+**State Invariants**
+
+- 거부된 요청은 원장 항목을 만들지 않아야 한다.
+- 거부된 요청은 모든 portfolio snapshot을 유지해야 한다.
+
+### REQ-001.02-AC01 — 배당 상태 효과
+
+**Criterion**
+
+유효한 배당 기록 후 `profit_buffer_after`는 직전 값에 `amount`를 더한 값이어야 한다. `cash_balance_after`와 `asset_quantity_after`는 직전 값과 같아야 하며, `total_value_after`는 증가한 buffer를 반영해야 한다. `tax` 값은 이 계산에 영향을 주지 않는다.
+
+**Verification**
+
+서로 다른 `amount`와 `tax` 조합으로 기록 전후 portfolio와 ledger after-snapshot을 비교하고 각 계산식을 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | boundary | unchanged-state`
+
+**State Invariants**
+
+- `profit_buffer` 외의 현금·수량 상태는 변경되지 않아야 한다.
+- 동일 `amount`에 대해 `tax` 값이 달라도 상태 효과는 같아야 한다.
+- ledger after-snapshot과 portfolio snapshot은 같아야 한다.
+
+### REQ-001.03-AC01 — UTC 입금일 저장
+
+**Criterion**
+
+`YYYY-MM-DD` 입금일은 `executed_at`의 해당 UTC 날짜 `00:00:00Z`로 저장·반환되어야 한다. `recorded_at`은 서버 append 시각이어야 한다.
+
+**Verification**
+
+- 서로 다른 날짜를 입력해 UTC 자정 저장과 조회를 확인한다.
+- 서버 환경 timezone과 무관한 결과를 확인한다.
+- `recorded_at`이 입력한 입금일로 대체되지 않는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | boundary`
+
+**State Invariants**
+
+- date-only 입력은 시간대 변환으로 전날 또는 다음 날이 되어서는 안 된다.
+- `recorded_at`의 감사 의미는 유지되어야 한다.
+
+### REQ-001.04-AC01 — Unified ledger 배당 조회
+
+**Criterion**
+
+기록된 배당은 manual ledger와 unified ledger에서 `source=manual`, `action=DIVIDEND`, `executed_at`, canonical `amount`, `tax_amount`, `note` 및 변경 후 snapshot으로 조회되어야 한다.
+
+**Verification**
+
+- 배당 생성 후 `source=manual` filter를 사용해 unified ledger를 조회한다.
+- canonical `amount`가 별도 field로 존재하며 거래 `price` 해석에만 의존하지 않는지 확인한다.
+- OpenAPI의 request·response schema에 같은 field와 nullability가 나타나는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | unchanged-state`
+
+**State Invariants**
+
+- 조회는 원장과 portfolio 상태를 변경하지 않아야 한다.
+- broker entry와 기존 manual entry의 기존 표현을 변경하지 않아야 한다.
+
+### REQ-001.05-AC01 — 최초 중복 후보 경고
+
+**Criterion**
+
+동일 portfolio, UTC 입금일, Decimal `amount`, `note`의 reversal되지 않은 기존 배당이 있고 `confirm_duplicate`가 없거나 `false`이면 시스템은 새 항목을 기록하지 않고 HTTP 409 `POTENTIAL_DUPLICATE_DIVIDEND`와 `matched_ledger_entry_id`를 반환한다.
+
+**Verification**
+
+- 첫 요청을 기록한 뒤 동일 요청을 재제출한다.
+- 409 code와 원본 entry ID를 확인한다.
+- 원장 수와 portfolio snapshot이 변하지 않았는지 확인한다.
+- Decimal 값이 다른 요청을 같은 값으로 오판하지 않는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `negative | boundary | unchanged-state | concurrency`
+
+**State Invariants**
+
+- 경고 응답은 새 원장을 만들지 않아야 한다.
+- 경고 응답은 `profit_buffer`를 변경하지 않아야 한다.
+- 일치 ID는 실제 중복 후보를 정확히 가리켜야 한다.
+
+### REQ-001.05-AC02 — 확인된 중복과 reversal된 원본 처리
+
+**Criterion**
+
+중복 후보 요청에 `confirm_duplicate=true`가 있으면 시스템은 별도 배당 항목을 기록해야 한다. 이미 reversal된 배당 원본은 새로운 중복 후보에서 제외해야 한다.
+
+**Verification**
+
+- 409 이후 동일 요청에 `confirm_duplicate=true`를 보내 HTTP 201과 별도 entry ID를 확인한다.
+- 원본을 reversal한 뒤 동일 배당을 다시 제출해 경고 없이 기록되는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | boundary`
+
+**State Invariants**
+
+- 확인된 중복은 각각 독립적인 append-only 원장이어야 한다.
+- reversal된 원본은 중복 억제 상태를 영구히 남기지 않아야 한다.
+
+### REQ-001.05-AC03 — 동시 중복 요청의 일관성
+
+**Criterion**
+
+동일 portfolio에 확인되지 않은 같은 배당 요청이 동시에 도착하더라도 새 배당 항목은 최대 하나만 기록되어야 하며 최종 원장과 portfolio snapshot은 일치해야 한다.
+
+**Verification**
+
+실제 PostgreSQL에서 같은 요청을 동시에 제출해 확인되지 않은 요청 둘이 모두 자동 기록되지 않으며, 거부된 요청은 상태를 변경하지 않고 최종 원장 수와 `profit_buffer`가 허용된 기록 수와 일치하는지 확인한다.
+
+**Verification Classification**
+
+- Level: `integration`
+- Backend: PostgreSQL
+- Cases: `concurrency | unchanged-state`
+
+**State Invariants**
+
+- lost update가 발생하지 않아야 한다.
+- 원장 수와 최종 snapshot 사이에 불일치가 없어야 한다.
+- 경고로 거부된 transaction은 부분 상태를 남기지 않아야 한다.
+
+### REQ-001.06-AC01 — 배당 reversal
+
+**Criterion**
+
+유효한 `DIVIDEND`를 reversal하면 원본 `amount`만큼 `profit_buffer`가 감소하고 원본 이전 값으로 복원되어야 한다. 원본과 reversal 원장은 모두 남아야 하며 현금과 수량은 변경되지 않아야 한다.
+
+**Verification**
+
+- 정상 금액과 최소 단위 `0.00000001`을 각각 기록하고 reversal한다.
+- 원본 이전 buffer로 정확히 복원되는지 확인한다.
+- 원본 보존, reversal 대상 ID, 중복 reversal 거부와 buffer 부족 거부를 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | negative | boundary | unchanged-state`
+
+**State Invariants**
+
+- 원본 원장은 수정·삭제되지 않아야 한다.
+- reversal은 `cash_balance`와 `asset_quantity`를 변경하지 않아야 한다.
+- 실패한 reversal은 새 원장이나 부분 snapshot을 남기지 않아야 한다.
+
+### REQ-001.07-AC01 — Decimal round-trip
+
+**Criterion**
+
+API가 수용한 최대 8자리 소수의 `amount`와 `tax`는 PostgreSQL 저장, 조회, 중복 비교와 reversal에서 같은 Decimal 의미를 유지해야 한다.
+
+**Verification**
+
+- `0.00000001` 등 경계값을 기록하고 DB text 표현·API 응답·reversal 결과를 비교한다.
+- float로 변환하면 같아질 수 있는 서로 다른 Decimal 입력이 동일한 중복으로 판정되지 않는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | boundary`
+
+**State Invariants**
+
+- 수용된 원장 값과 snapshot 효과가 달라져서는 안 된다.
+- reversal 기준은 원본의 정확한 Decimal 금액이어야 한다.
+
+### REQ-001.08-AC01 — 기존 action 회귀 없음
+
+**Criterion**
+
+기존 manual action은 `DIVIDEND` 도입 전과 같은 유효 입력, 상태 효과와 충돌 정책을 유지해야 한다. 새 배당 전용 field를 사용하지 않는 기존 호출자는 변경 없이 동작해야 한다. 비-`DIVIDEND` action에 `confirm_duplicate=false`를 명시한 요청은 허용하고, `confirm_duplicate=true`를 명시한 요청은 원장 기록 전에 HTTP 422로 거부해야 한다.
+
+**Verification**
+
+- 기존 action 전체의 정상·잔액 부족·reversal 경로를 실행한다.
+- 새 배당 전용 field를 생략한 기존 요청과 저장 데이터의 회귀를 확인한다.
+- 비-`DIVIDEND` action에 `confirm_duplicate=false`를 명시한 요청이 기존 action과 동일하게 처리되는지 확인한다.
+- 비-`DIVIDEND` action에 `confirm_duplicate=true`를 명시한 요청이 HTTP 422이며 상태가 변하지 않는지 확인한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL
+- Cases: `positive | negative | boundary | unchanged-state`
+
+**State Invariants**
+
+- 기존 action의 계산식과 원장 표현이 변경되지 않아야 한다.
+- 새 배당 전용 field의 기본값은 기존 호출자를 깨뜨리지 않아야 한다.
+- 비-`DIVIDEND` action의 `confirm_duplicate=true` 거부는 원장과 portfolio snapshot을 변경하지 않아야 한다.
+
+### REQ-001.09-AC01 — 권한 유지와 민감정보 비노출
+
+**Criterion**
+
+배당 기록은 기존 portfolio 소유권과 manual-write 확인 정책을 통과한 사용자에게만 허용되어야 한다. 응답·오류·로그는 이 기능으로 인해 secret, credential 또는 불필요한 account 식별정보를 추가로 노출하지 않아야 한다.
+
+**Verification**
+
+- 기존 인증·소유권·daemon-managed portfolio 확인 경로를 실행한다.
+- 정상 응답, 422, 409와 persistence 오류의 body 및 rendered log를 민감정보 sentinel로 검사한다.
+
+**Verification Classification**
+
+- Level: `API | integration`
+- Backend: PostgreSQL, application log
+- Cases: `positive | negative | unchanged-state`
+
+**State Invariants**
+
+- 권한이 없는 요청은 원장과 snapshot을 변경하지 않아야 한다.
+- 오류 경로에서도 credential과 connection 정보가 노출되지 않아야 한다.
+
+## 8. 오류 및 충돌 계약
+
+- 유효하지 않은 schema 입력은 HTTP 422로 거부하고 상태를 변경하지 않는다.
+- 중복 후보의 최초 요청은 HTTP 409 `POTENTIAL_DUPLICATE_DIVIDEND`와 `matched_ledger_entry_id`를 반환한다.
+- 사용자 확인이 필요한 daemon-managed portfolio 정책과 disabled portfolio 정책은 기존 HTTP 409 계약을 유지한다.
+- reversal 대상 없음, 중복 reversal과 잔액 부족은 기존 manual ledger 충돌 계약을 유지한다.
+- 입력 검증 또는 저장 실패로 요청을 기록할 수 없으면 부분 기록 없이 거부한다.
+- DB 오류 또는 transaction 실패 시 원장 append와 portfolio snapshot update를 모두 rollback한다.
+
+## 9. 데이터 및 인터페이스 계약
+
+### 요청
+
+- `action`: `DIVIDEND`
+- `amount`: 필수, `>0`, Decimal, 최대 20자리·소수점 이하 최대 8자리
+- `tax`: 선택, 기본값 `0`, `>=0`, Decimal, 최대 20자리·소수점 이하 최대 8자리
+- `executed_at`: 필수 date-only `YYYY-MM-DD`
+- `note`: 선택 문자열
+- `confirm_duplicate`: 선택 boolean, 기본값 `false`
+
+`confirm_duplicate`는 `DIVIDEND`의 중복 확인 계약에 사용한다. 비-`DIVIDEND` action에서는 명시적 `false`를 허용하고 명시적 `true`를 HTTP 422로 거부한다.
+
+### 허용하지 않는 DIVIDEND 입력
+
+- `quantity`
+- 거래 `price`
+- `fee`
+- `target_ledger_entry_id`
+- 주문 또는 체결 식별자
+
+### 생성 응답과 unified ledger
+
+- `ledger_entry_id`
+- `portfolio_id`
+- `source=manual`
+- `action=DIVIDEND`
+- canonical `amount`
+- `tax` 또는 unified ledger의 `tax_amount`
+- UTC 자정의 `executed_at`
+- 서버 append 시각 `recorded_at`
+- `note`
+- `cash_balance_after`
+- `asset_quantity_after`
+- `profit_buffer_after`
+- `total_value_after`
+
+### 저장 계약
+
+- 입금일 전용 DB column을 추가하지 않고 기존 `executed_at`을 사용한다.
+- `tax`는 참고 metadata로 저장한다.
+- 배당 사실과 after-snapshot은 `source=manual`인 append-only 원장으로 보존한다.
+
+## 10. 하위호환성
+
+- 기존 manual ledger action의 필수·선택 field와 상태 계산을 유지한다.
+- 기존 broker ledger write와 unified ledger 조회 계약을 유지한다.
+- 새 배당 전용 field를 사용하지 않는 기존 action 요청을 변경 없이 허용한다.
+- `REVERSAL`의 대상 없음, 잔액 부족과 중복 reversal 정책을 변경하지 않는다.
+
+## 11. 검증 계획
+
+- API schema와 OpenAPI에서 `DIVIDEND` action 및 입력·응답 field 검증
+- 배당 기록 전후 portfolio와 ledger after-snapshot 비교
+- UTC 입금일과 서버 `recorded_at` 분리 검증
+- 최초 중복 409, 확인 재제출, reversal된 원본 제외 검증
+- 동시 중복 요청의 최대 1건 기록과 최종 원장·snapshot 일치 검증
+- 최소 단위와 저장 범위 경계값의 실제 PostgreSQL Decimal round-trip 검증
+- 입력 또는 저장 실패의 pre-write rejection과 rollback 검증
+- 기존 action과 기존 저장 데이터의 하위호환 회귀
+- 응답·오류·로그의 민감정보 비노출 검증
+- 문서와 OpenAPI 계약 정합성 검증
+
+### Test Traceability Contract
+
+- 이 requirement 문서에는 검증 의도와 판정 조건만 기록한다.
+- 실행 가능한 테스트 정의는 별도 test catalog artifact에서 관리한다.
+- 각 테스트는 안정적인 identifier와 `verifies` 목록으로 하나 이상의 `REQ-001.XX-ACYY`를 참조한다.
+- 테스트 정의의 존재, 자동화 여부, 특정 commit에서의 실행 여부와 PASS 결과를 별도 상태로 관리한다.
+- 실행 결과는 requirement나 test definition을 수정하지 않고 별도 evidence에 기록한다.
+- Evidence는 최소한 `REQ-001` revision, 검증한 commit SHA, runtime/backend, 결과와 실행 시각을 포함한다.
+
+## 12. 추적성
+
+- 근거 이슈: `https://github.com/fourblocks2020/portfolio-hub/issues/31`
+- 구현 PR: `https://github.com/fourblocks2020/portfolio-hub/pull/33`
+- 검토한 PR head: `6df3e4ba029cc465bf28030767190d6af55c5402`
+- 관련 설계 문서:
+  - `docs/interface-contract.md`
+  - `docs/data-model.md`
+  - `docs/runtime-flows.md`
+- 관련 requirement: 없음
+
+## 13. 확정된 결정
+
+- 사용자는 실수령액 `amount`를 입력한다.
+- `tax`는 기본값 `0`인 선택적 non-negative metadata이며 자동 계산하지 않는다.
+- 입금일은 새 DB column 없이 기존 `executed_at`에 저장한다.
+- date-only 입금일은 UTC 자정으로 변환한다.
+- 최초 중복 후보 요청은 409로 거부하고 `confirm_duplicate=true`인 재요청만 기록한다.
+- 구현 범위는 portfolio-hub API·DB·OpenAPI·테스트이며 UI는 별도 연계 범위다.
+- 잘못 입력한 배당은 기존 append-only `REVERSAL`로 정정한다.
+- 비-`DIVIDEND` action에서는 `confirm_duplicate=false`를 허용하고 `confirm_duplicate=true`를 HTTP 422로 거부한다.
+
+## 14. Open Questions
+
+- 없음
+
+## 15. 승인 기록
+
+- 상태: `approved`
+- 승인 주체: `genichin`
+- 승인 근거: 이 대화에서 REQ-001 승인과 비-DIVIDEND confirm_duplicate=false 허용/true HTTP 422 결정을 명시적으로 확정함

docs/requirements/req-001_provenance-reapproval-request.md

@@ -0,0 +1,25 @@
+# REQ-001 Provenance Reapproval Request
+
+- 대상 requirement: `REQ-001` (`docs/requirements/req-001_manual-cash-dividend.md`)
+- 현재 canonical SHA-256: `b9498b5d9b6dd4638d701f68273dbbde1a37dbbaa74d1d3c9923fb1702b6f076`
+- 상태: 승인된 canonical 본문은 변경하지 않음
+
+## 요청 배경
+
+`REQ-001` 승인 기록의 문구(`OQ-001 선택지 A`)가 본문 계약(`tax` 허용) 및 이슈 #31의 확정 OQ-001(B)와 provenance 상 충돌한다는 리뷰 코멘트가 확인되었다.
+
+## 요청 사항
+
+승인된 canonical 파일 자체를 구현 PR에서 직접 수정하지 않고, 아래 절차 중 하나를 요청한다.
+
+1. `REQ-001` 한정 1회 예외를 승인하여 provenance 문구를 정정하고 재승인한다.
+2. 또는 별도 canonical artifact(새 revision)로 provenance 정정본을 생성하고 재승인한다.
+
+## 정정 대상 문구(제안)
+
+- 기존: `이 대화에서 REQ-001 승인과 OQ-001 선택지 A를 명시적으로 확정함`
+- 제안: `이 대화에서 REQ-001 승인과 비-DIVIDEND confirm_duplicate=false 허용/true HTTP 422 결정을 명시적으로 확정함`
+
+## 비고
+
+본 문서는 절차 요청 artifact이며, `REQ-001` canonical bytes/revision/status를 직접 변경하지 않는다.

docs/requirements/req-001_test-catalog.md

@@ -0,0 +1,112 @@
+# REQ-001 Test Catalog
+
+Test ID: TC-REQ-001-001
+Verifies:
+- REQ-001.01-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_updates_only_profit_buffer_and_records_executed_at_and_tax
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_tax_defaults_to_zero_when_omitted
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_tax_omitted_persists_zero_on_real_postgres
+Automated: true
+
+Test ID: TC-REQ-001-002
+Verifies:
+- REQ-001.01-AC02
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_rejects_invalid_amount_tax_and_unrelated_fields_without_state_change
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_rejects_sub_minimum_numeric_precision
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_rejects_amount_exceeding_numeric_20_8
+Automated: true
+
+Test ID: TC-REQ-001-003
+Verifies:
+- REQ-001.02-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_updates_only_profit_buffer_and_records_executed_at_and_tax
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_tax_defaults_to_zero_when_omitted
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_precision_and_reversal_round_trip_on_real_postgres
+Automated: true
+
+Test ID: TC-REQ-001-004
+Verifies:
+- REQ-001.03-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_executed_at_uses_utc_midnight_independent_of_server_timezone
+Automated: true
+
+Test ID: TC-REQ-001-005
+Verifies:
+- REQ-001.04-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_unified_ledger_includes_dividend_fields
+- tests/test_v1_portfolios_manual_ledger.py::test_unified_ledger_openapi_contains_nullable_amount
+- tests/test_v1_portfolios_manual_ledger.py::test_unified_ledger_history_item_rejects_dividend_numeric_branch_payload
+Automated: true
+
+Test ID: TC-REQ-001-006
+Verifies:
+- REQ-001.05-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_duplicate_requires_confirmation
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_with_different_decimal_amount_is_not_treated_as_duplicate
+Automated: true
+
+Test ID: TC-REQ-001-007
+Verifies:
+- REQ-001.05-AC02
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_duplicate_requires_confirmation
+- tests/test_v1_portfolios_manual_ledger.py::test_reversed_dividend_is_excluded_from_future_duplicate_candidate_matching
+Automated: true
+
+Test ID: TC-REQ-001-008
+Verifies:
+- REQ-001.05-AC03
+Test reference:
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_cold_repositories_concurrent_dividend_requests_follow_duplicate_contract
+Automated: true
+
+Test ID: TC-REQ-001-009
+Verifies:
+- REQ-001.06-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_reversal_decreases_profit_buffer
+- tests/test_v1_portfolios_manual_ledger.py::test_duplicate_reversal_is_rejected_without_state_change
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_reversal_insufficient_buffer_is_rejected_without_state_change
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_precision_and_reversal_round_trip_on_real_postgres
+Automated: true
+
+Test ID: TC-REQ-001-010
+Verifies:
+- REQ-001.07-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_duplicate_check_does_not_collapse_decimals_that_can_alias_in_float
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_tax_does_not_collapse_decimals_that_can_alias_in_float
+- tests/test_v1_portfolios_manual_ledger.py::test_dividend_with_different_decimal_amount_is_not_treated_as_duplicate
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_amount_alias_prone_decimals_are_not_misdetected_as_duplicate_in_api_on_real_postgres
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_precision_and_reversal_round_trip_on_real_postgres
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_large_existing_buffer_plus_min_dividend_is_rejected_before_snapshot_divergence
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_tax_alias_prone_decimals_round_trip_distinctly_on_real_postgres
+Automated: true
+
+Test ID: TC-REQ-001-011
+Verifies:
+- REQ-001.08-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_confirm_duplicate_false_is_accepted_for_non_dividend_actions
+- tests/test_v1_portfolios_manual_ledger.py::test_confirm_duplicate_true_is_rejected_for_non_dividend_actions
+- tests/test_v1_portfolios_manual_ledger.py::test_unified_ledger_keeps_non_dividend_amount_as_number
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_existing_high_precision_snapshot_still_allows_legacy_manual_actions
+- tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_large_invest_and_large_dividend_tax_metadata_are_accepted_when_snapshot_is_safe
+Automated: true
+
+Test ID: TC-REQ-001-012
+Verifies:
+- REQ-001.09-AC01
+Test reference:
+- tests/test_v1_portfolios_manual_ledger.py::test_manual_write_rejects_service_token
+- tests/test_v1_portfolios_manual_ledger.py::test_owner_mismatch_returns_403
+- tests/test_v1_portfolios_manual_ledger.py::test_daemon_managed_requires_confirmation_then_records_evidence
+- tests/test_v1_portfolios_manual_ledger.py::test_manual_ledger_conflict_message_is_sanitized
+- tests/test_v1_portfolios_manual_ledger.py::test_manual_ledger_conflict_secret_is_not_rendered_in_logs
+Automated: true

docs/requirements/req-001_test-evidence.md

@@ -0,0 +1,78 @@
+# REQ-001 Test Evidence
+
+## Evidence Batch: local API regression run
+
+Requirement revision: `REQ-001@1.0`
+Commit: `8368e7ba165b560af6ae813fa2dce715657515f5`
+Environment: `local sandbox / pytest / fake repository`
+Executed at: `2026-09-09T13:41:00Z`
+Run selector: `pytest -q -o addopts='' tests/test_v1_portfolios_manual_ledger.py`
+Run result: `38 passed`
+
+Test ID: TC-REQ-001-002
+Result: PASS
+
+Test ID: TC-REQ-001-003
+Result: PASS
+
+Test ID: TC-REQ-001-004
+Result: PASS
+
+Test ID: TC-REQ-001-005
+Result: PASS
+
+Test ID: TC-REQ-001-006
+Result: PASS
+
+Test ID: TC-REQ-001-007
+Result: PASS
+
+Test ID: TC-REQ-001-009
+Result: PASS
+
+Test ID: TC-REQ-001-010
+Result: PASS
+
+Test ID: TC-REQ-001-012
+Result: PASS
+
+## Evidence Batch: local real PostgreSQL selector availability
+
+Requirement revision: `REQ-001@1.0`
+Commit: `8368e7ba165b560af6ae813fa2dce715657515f5`
+Environment: `local sandbox / PostgreSQL DSN not configured`
+Executed at: `2026-09-09T14:19:00Z`
+Run selector: `pytest -q -o addopts='' tests/test_bat025_portfolio_ledger_manual_metadata_migration.py::test_dividend_amount_alias_prone_decimals_are_not_misdetected_as_duplicate_in_api_on_real_postgres`
+Run result: `1 skipped`
+
+## Evidence Batch: independent real PostgreSQL re-review run
+
+Requirement revision: `REQ-001@1.0`
+Commit: `db35d083dec75bc79b5a97b015b5c40056c12772`
+Environment: `disposable PostgreSQL / independent re-review (review 5155656169)`
+Executed at: `2026-09-09T14:25:22Z`
+Run selector: `tests/test_bat025_portfolio_ledger_manual_metadata_migration.py (module)`
+Run result: `10 passed, 2 failed` (`2 failed` are pre-existing stale migration-head baseline)
+
+Test ID: TC-REQ-001-001
+Result: PASS
+
+Test ID: TC-REQ-001-003
+Result: PASS
+
+Test ID: TC-REQ-001-008
+Result: PASS
+
+Test ID: TC-REQ-001-009
+Result: PASS
+
+Test ID: TC-REQ-001-010
+Result: PASS
+
+Test ID: TC-REQ-001-011
+Result: PASS
+
+## Evidence-only follow-up integrity note
+
+- Tested code/test commit for the latest PostgreSQL batch: `db35d083dec75bc79b5a97b015b5c40056c12772`
+- This follow-up updates evidence text only; no application/test source files were changed after the tested commit.

docs/runtime-flows.md

@@ -280,11 +280,12 @@
 3. Disabled portfolio receives HTTP 409 `PORTFOLIO_DISABLED`.
 4. If `managed_by_daemon_id IS NOT NULL` and request lacks `confirm_daemon_managed_manual_write=true`, the API returns HTTP 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION` with daemon id and required confirmation marker.
 5. Valid actions dispatch to a single repository transaction that locks the portfolio row (`FOR UPDATE OF p`), calculates the action effect, appends a `portfolio_ledger` row with `source='manual'`, and updates the portfolio snapshot.
-6. BUY/SELL require sufficient cash/quantity. BUFFER_OUT/BUFFER_IN/WITHDRAW/PROFIT require sufficient buffer/cash as appropriate. Insufficient state returns HTTP 409 with structured code.
+6. BUY/SELL require sufficient cash/quantity. BUFFER_OUT/BUFFER_IN/WITHDRAW/PROFIT require sufficient buffer/cash as appropriate. DIVIDEND requires `amount` and date-only `executed_at`, stores `executed_at` at UTC midnight, and increases only `profit_buffer` (`tax` metadata only). Insufficient state returns HTTP 409 with structured code.
 7. REVERSAL requires `target_ledger_entry_id`, rejects duplicate reversal targets, and appends a reversing row instead of mutating/deleting the target.
-8. Response includes after-snapshot: `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`.
-9. `GET /v1/portfolios/{portfolio_id}/ledger/manual` returns newest manual entries only (`source='manual'`).
-10. `GET /v1/portfolios/{portfolio_id}/returns/summary` returns `net_contributed_capital=sum(INVEST)-sum(WITHDRAW)` and `cumulative_profit_withdrawn=sum(PROFIT)` separately.
+8. Duplicate DIVIDEND candidate (same portfolio/date/amount/note and original not reversed) returns HTTP 409 `POTENTIAL_DUPLICATE_DIVIDEND` with matched entry id; `confirm_duplicate=true` re-submit records it.
+9. Response includes after-snapshot: `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`.
+10. `GET /v1/portfolios/{portfolio_id}/ledger/manual` returns newest manual entries only (`source='manual'`).
+11. `GET /v1/portfolios/{portfolio_id}/returns/summary` returns `net_contributed_capital=sum(INVEST)-sum(WITHDRAW)` and `cumulative_profit_withdrawn=sum(PROFIT)` separately.
 
 ## Flow: `v1 API — POST /auth/service-tokens`
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "portfoliohub"
-version = "0.2.0"
+version = "0.2.1"
 description = "PortfolioHub API for portfolio management and ledger access"
 readme = "README.md"
 requires-python = ">=3.11"

scripts/image_release.py

@@ -25,8 +25,8 @@ COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
 VERSION_REF_RE = re.compile(r"^refs/tags/v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
 IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
 DIGEST_RE = re.compile(r"(?:^|\s)digest:\s*(sha256:[0-9a-f]{64})(?:\s|$)")
-EXPECTED_MIGRATION_COUNT = 29
-EXPECTED_ALEMBIC_HEAD = "20260814_0029"
+EXPECTED_MIGRATION_COUNT = 30
+EXPECTED_ALEMBIC_HEAD = "20260820_0030"
 
 @dataclass(frozen=True)
 class Result:

tests/release/test_image_release.py

@@ -33,8 +33,8 @@ class RecordingRunner:
         if command[:3] == ["docker", "run", "--rm"] and "urllib.request" in command[-1]:
             enabled = "TARGET:8000" not in command[-1] and "plain" not in command[-1]
             return image_release.Result('{"status":"ok","db_enabled":' + str(enabled).lower() + '}')
-        if command[:3] == ["docker", "run", "--rm"] and "alembic_version" in command[-1]: return image_release.Result("20260814_0029\n")
-        if command[:3] == ["docker", "run", "--rm"] and "health-check" in command: return image_release.Result('{"database_revision":"20260814_0029"}\n')
+        if command[:3] == ["docker", "run", "--rm"] and "alembic_version" in command[-1]: return image_release.Result("20260820_0030\n")
+        if command[:3] == ["docker", "run", "--rm"] and "health-check" in command: return image_release.Result('{"database_revision":"20260820_0030"}\n')
         return image_release.Result()
 
 def artifacts(tmp_path: Path):
@@ -73,13 +73,13 @@ def test_project_version_must_match_release_tag(tmp_path):
 
 def test_installed_smoke_has_import_cli_exact_inventory_and_cleanup():
     inventory = tuple(
-        [f"202601{i:02d}_{i:04d}_migration.py" for i in range(1, 29)]
-        + ["20260814_0029_strategy_catalog_v1.py"]
+        [f"202601{i:02d}_{i:04d}_migration.py" for i in range(1, 30)]
+        + ["20260820_0030_portfolio_ledger_keyset_index.py"]
     )
     runner = RecordingRunner(); image_release.smoke_installed_image("candidate", inventory, runner, 17)
     runs = [x[0] for x in runner.commands if x[0][:2] == ["docker","run"]]
     assert len(runs) == 3 and all("--read-only" in x and "none" in x for x in runs)
-    assert "migration_inventory" in runs[-1][-1] and "20260814_0029" in runs[-1][-1]
+    assert "migration_inventory" in runs[-1][-1] and "20260820_0030" in runs[-1][-1]
     assert len([x for x in runner.commands if x[0][:3] == ["docker","rm","--force"]]) == 3
 
 def _assert_exact_startup_cleanup(commands: list[list[str]]) -> None:

tests/release/test_release_contracts.py

@@ -50,7 +50,7 @@ def test_workflow_actions_are_commit_pinned_and_verify_version_is_project_derive
     assert 'RELEASE_VERSION=v0.1.3' not in verify
 
 
-def test_release_version_and_migration_contract_are_v020_head_0030():
+def test_release_version_and_migration_contract_are_v021_head_0030():
     project = (REPO / "pyproject.toml").read_text()
     config = (REPO / "app/core/config.py").read_text()
     migrations = sorted(
@@ -58,8 +58,8 @@ def test_release_version_and_migration_contract_are_v020_head_0030():
         for path in (REPO / "app/db/alembic/versions").glob("*.py")
         if path.name != "__init__.py"
     )
-    assert 'version = "0.2.0"' in project
-    assert 'app_version: str = "0.2.0"' in config
+    assert 'version = "0.2.1"' in project
+    assert 'app_version: str = "0.2.1"' in config
     assert len(migrations) == 30
     assert migrations[-1].startswith("20260820_0030")
 
@@ -85,8 +85,8 @@ def test_operations_separate_publication_deployment_migration_and_db_rollback():
         "Image rollback is **not** database rollback",
         "read-only root filesystem",
         "10001:10001",
-        "PortfolioHub v0.2.0 container contract",
-        "v0.2.0 adds migration `0030`",
+        "PortfolioHub v0.2.1 container contract",
+        "v0.2.1 includes migration `0030`",
         "trex-web v0.2.3 displays `strategy_nick`",
     ):
         assert value in text

tests/test_bat025_portfolio_ledger_manual_metadata_migration.py

@@ -9,20 +9,27 @@ or production application database.
 from __future__ import annotations
 
 import os
-from datetime import datetime, timezone
+import threading
+from contextlib import ExitStack
+from datetime import UTC, datetime
+from decimal import Decimal
 from urllib.parse import unquote, urlparse
 from uuid import uuid4
+from unittest.mock import patch
 
 import psycopg
 import pytest
+from fastapi.testclient import TestClient
 from psycopg import sql
 
+from app.core.auth import AuthContext, Permission, require_read
 from app.core.config import Settings
 from app.db.migrations import (
     bootstrap_or_upgrade_to_head,
     get_alembic_config,
     upgrade_to_head,
 )
+from app.main import create_app
 from app.repositories.postgres import PortfolioDBConfig, PostgresPortfolioRepository
 
 _LOCAL_DSN_ENV = "BAT025_LOCAL_POSTGRES_DSN"
@@ -105,10 +112,9 @@ def _current_revision(settings: Settings) -> str:
         user=settings.active_db_user,
         password=settings.active_db_password,
         sslmode=settings.active_db_sslmode,
-    ) as conn:
-        with conn.cursor() as cur:
-            cur.execute("SELECT version_num FROM alembic_version")
-            return str(cur.fetchone()[0])
+    ) as conn, conn.cursor() as cur:
+        cur.execute("SELECT version_num FROM alembic_version")
+        return str(cur.fetchone()[0])
 
 
 def _metadata_columns(settings: Settings) -> dict[str, tuple[str, str, str | None]]:
@@ -119,18 +125,17 @@ def _metadata_columns(settings: Settings) -> dict[str, tuple[str, str, str | Non
         user=settings.active_db_user,
         password=settings.active_db_password,
         sslmode=settings.active_db_sslmode,
-    ) as conn:
-        with conn.cursor() as cur:
-            cur.execute(
-                """
+    ) as conn, conn.cursor() as cur:
+        cur.execute(
+            """
                 SELECT column_name, data_type, is_nullable, column_default
                 FROM information_schema.columns
                 WHERE table_schema = 'public' AND table_name = 'portfolio_ledger'
                   AND column_name IN ('source', 'target_ledger_entry_id',
                                       'confirmation_evidence', 'actor_user_id')
                 """
-            )
-            return {row[0]: (row[1], row[2], row[3]) for row in cur.fetchall()}
+        )
+        return {row[0]: (row[1], row[2], row[3]) for row in cur.fetchall()}
 
 
 def _seed_portfolio(repo: PostgresPortfolioRepository, suffix: str) -> str:
@@ -159,6 +164,23 @@ def _seed_portfolio(repo: PostgresPortfolioRepository, suffix: str) -> str:
     return portfolio_id
 
 
+def _api_client(settings: Settings, repo: PostgresPortfolioRepository, *, user_id: str) -> tuple[TestClient, ExitStack]:
+    app = create_app(settings_factory=lambda: settings)
+    app.dependency_overrides[require_read] = lambda: AuthContext(
+        token="bat025-test-token",
+        permission=Permission.READ,
+        user_id=user_id,
+        token_type="session",
+        token_source="db",
+    )
+    stack = ExitStack()
+    stack.enter_context(patch("app.api.v1_portfolios.get_portfolio_repository_from_settings", return_value=repo))
+    stack.enter_context(patch("app.core.auth.get_portfolio_repository_from_settings", return_value=repo))
+    stack.enter_context(patch("app.api.v1_portfolios.get_settings", return_value=settings))
+    client = TestClient(app)
+    return client, stack
+
+
 def test_upgrade_from_pre_0028_preserves_business_data_and_backfills_source(
     isolated_settings: Settings,
 ) -> None:
@@ -168,7 +190,7 @@ def test_upgrade_from_pre_0028_preserves_business_data_and_backfills_source(
     command.upgrade(get_alembic_config(isolated_settings), _PRE_BAT025)
     repo = _repo(isolated_settings)
     portfolio_id = _seed_portfolio(repo, "preserve")
-    recorded_at = datetime(2026, 7, 15, tzinfo=timezone.utc)
+    recorded_at = datetime(2026, 7, 15, tzinfo=UTC)
     with repo._connect().cursor() as cur:
         cur.execute(
             """
@@ -248,7 +270,7 @@ def test_broker_and_manual_ledger_writes_regress_after_real_upgrade(
         side="buy",
         quantity=2,
         price=100,
-        executed_at=datetime.now(timezone.utc),
+        executed_at=datetime.now(UTC),
     )
     manual = repo.record_manual_ledger(
         portfolio_id,
@@ -271,3 +293,314 @@ def test_broker_and_manual_ledger_writes_regress_after_real_upgrade(
         )
         assert cur.fetchone() == ("manual", "bat025-user", "synthetic-local-fixture")
     repo.close()
+
+
+def test_dividend_precision_and_reversal_round_trip_on_real_postgres(
+    isolated_settings: Settings,
+) -> None:
+    """DIVIDEND min unit persists and REVERSAL removes the same amount exactly."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "dividend-precision")
+
+    dividend = repo.record_manual_ledger(
+        portfolio_id,
+        action="DIVIDEND",
+        amount=Decimal("0.00000001"),
+        tax=Decimal("0.00000001"),
+        executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+        note="precision-test",
+    )
+
+    assert dividend.price == 0.00000001
+    assert dividend.tax_amount == 0.00000001
+    assert dividend.tax_amount_decimal == Decimal("0.00000001")
+    assert dividend.profit_buffer_after == 0.00000001
+    with repo._connect().cursor() as cur:
+        cur.execute(
+            "SELECT price::text, tax_amount::text, profit_buffer_after::text FROM portfolio_ledger WHERE ledger_entry_id = %s",
+            (dividend.ledger_entry_id,),
+        )
+        assert cur.fetchone() == ("0.00000001", "0.00000001", "0.00000001")
+
+    reversal = repo.record_manual_ledger(
+        portfolio_id,
+        action="REVERSAL",
+        target_ledger_entry_id=dividend.ledger_entry_id,
+    )
+    assert reversal.profit_buffer_after == 0.0
+    with repo._connect().cursor() as cur:
+        cur.execute("SELECT profit_buffer::text FROM portfolios WHERE portfolio_id = %s", (portfolio_id,))
+        assert cur.fetchone()[0] == "0"
+
+    repo.close()
+
+
+def test_dividend_tax_omitted_persists_zero_on_real_postgres(
+    isolated_settings: Settings,
+) -> None:
+    """Omitted tax should persist as zero in PostgreSQL."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "dividend-tax-omitted")
+
+    dividend = repo.record_manual_ledger(
+        portfolio_id,
+        action="DIVIDEND",
+        amount=Decimal("1.00000000"),
+        executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+        note="tax-omitted",
+    )
+    assert dividend.tax_amount == 0.0
+    assert dividend.tax_amount_decimal == Decimal("0.00000000")
+    with repo._connect().cursor() as cur:
+        cur.execute("SELECT tax_amount::text FROM portfolio_ledger WHERE ledger_entry_id = %s", (dividend.ledger_entry_id,))
+        assert cur.fetchone()[0] == "0.00000000"
+    repo.close()
+
+
+def test_existing_high_precision_snapshot_still_allows_legacy_manual_actions(
+    isolated_settings: Settings,
+) -> None:
+    """Existing DOUBLE snapshot precision should not block unrelated manual actions."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "legacy-snapshot-precision")
+    with repo._connect().cursor() as cur:
+        cur.execute(
+            "UPDATE portfolios SET cash_balance = %s WHERE portfolio_id = %s",
+            (0.123456789, portfolio_id),
+        )
+
+    entry = repo.record_manual_ledger(
+        portfolio_id,
+        action="INVEST",
+        amount=Decimal("1.00000000"),
+        note="compat",
+    )
+    assert entry.action == "INVEST"
+    assert entry.price == 1.0
+    repo.close()
+
+
+def test_dividend_large_integer_with_8dp_is_rejected_to_protect_double_snapshot(
+    isolated_settings: Settings,
+) -> None:
+    """Inputs valid for NUMERIC(20,8) but unsafe for DOUBLE snapshot are rejected."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "double-snapshot-guard")
+
+    with pytest.raises(ValueError, match="DOUBLE PRECISION snapshot"):
+        repo.record_manual_ledger(
+            portfolio_id,
+            action="DIVIDEND",
+            amount=Decimal("1000000000.00000001"),
+            tax=Decimal("0.00000001"),
+            executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+            note="too-large-for-double",
+        )
+    repo.close()
+
+
+def test_large_existing_buffer_plus_min_dividend_is_rejected_before_snapshot_divergence(
+    isolated_settings: Settings,
+) -> None:
+    """Reject writes that would diverge between NUMERIC ledger and DOUBLE snapshot."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "large-buffer-min-dividend")
+    with repo._connect().cursor() as cur:
+        cur.execute("UPDATE portfolios SET profit_buffer = %s WHERE portfolio_id = %s", (1_000_000_000.0, portfolio_id))
+
+    with pytest.raises(ValueError, match="DOUBLE PRECISION snapshot"):
+        repo.record_manual_ledger(
+            portfolio_id,
+            action="DIVIDEND",
+            amount=Decimal("0.00000001"),
+            executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+            note="should-reject",
+        )
+
+    with repo._connect().cursor() as cur:
+        cur.execute("SELECT COUNT(*) FROM portfolio_ledger WHERE portfolio_id = %s AND side = 'dividend'", (portfolio_id,))
+        assert cur.fetchone()[0] == 0
+    repo.close()
+
+
+def test_large_invest_and_large_dividend_tax_metadata_are_accepted_when_snapshot_is_safe(
+    isolated_settings: Settings,
+) -> None:
+    """No hidden per-field cap for values that do not cause snapshot divergence."""
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "large-invest-large-tax")
+
+    invest = repo.record_manual_ledger(
+        portfolio_id,
+        action="INVEST",
+        amount=Decimal("50000000.00000000"),
+        note="large-invest",
+    )
+    assert invest.price == 50000000.0
+
+    dividend = repo.record_manual_ledger(
+        portfolio_id,
+        action="DIVIDEND",
+        amount=Decimal("1.00000000"),
+        tax=Decimal("50000000.00000000"),
+        executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+        note="large-tax-metadata",
+    )
+    assert dividend.tax_amount == 50000000.0
+    assert dividend.tax_amount_decimal == Decimal("50000000.00000000")
+    repo.close()
+
+
+def test_dividend_tax_alias_prone_decimals_round_trip_distinctly_on_real_postgres(
+    isolated_settings: Settings,
+) -> None:
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(repo, "tax-alias-roundtrip")
+
+    first = repo.record_manual_ledger(
+        portfolio_id,
+        action="DIVIDEND",
+        amount=Decimal("1.00000000"),
+        tax=Decimal("90000000.00000001"),
+        executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+        note="alias-tax-1",
+    )
+    second = repo.record_manual_ledger(
+        portfolio_id,
+        action="DIVIDEND",
+        amount=Decimal("1.00000000"),
+        tax=Decimal("90000000.00000002"),
+        executed_at=datetime(2026, 9, 2, 0, 0, 0, tzinfo=UTC),
+        note="alias-tax-2",
+    )
+    assert first.tax_amount_decimal == Decimal("90000000.00000001")
+    assert second.tax_amount_decimal == Decimal("90000000.00000002")
+    repo.close()
+
+
+def test_dividend_amount_alias_prone_decimals_are_not_misdetected_as_duplicate_in_api_on_real_postgres(
+    isolated_settings: Settings,
+) -> None:
+    upgrade_to_head(isolated_settings)
+    repo = _repo(isolated_settings)
+    suffix = "amount-alias-api"
+    portfolio_id = _seed_portfolio(repo, suffix)
+    user_id = f"bat025-user-{suffix}"
+    settings = isolated_settings.model_copy(update={"credential_encryption_key": "bat025-test-key"})
+
+    client, stack = _api_client(settings, repo, user_id=user_id)
+    auth_header = {"Authorization": "Bea" + "rer bat025-test-token"}
+    try:
+        first = client.post(
+            f"/v1/portfolios/{portfolio_id}/ledger/manual",
+            json={
+                "action": "DIVIDEND",
+                "amount": "90000000.00000001",
+                "tax": "0.00000000",
+                "executed_at": "2026-09-01",
+                "note": "amount-alias",
+            },
+            headers=auth_header,
+        )
+        second = client.post(
+            f"/v1/portfolios/{portfolio_id}/ledger/manual",
+            json={
+                "action": "DIVIDEND",
+                "amount": "90000000.00000002",
+                "tax": "0.00000000",
+                "executed_at": "2026-09-01",
+                "note": "amount-alias",
+            },
+            headers=auth_header,
+        )
+        assert first.status_code == 201
+        assert second.status_code == 201
+        assert first.json()["amount"] == "90000000.00000001"
+        assert second.json()["amount"] == "90000000.00000002"
+
+        history = client.get(
+            f"/v1/portfolios/{portfolio_id}/ledger?source=manual",
+            headers=auth_header,
+        )
+        assert history.status_code == 200
+        amounts = [item["amount"] for item in history.json()["items"] if item["action"] == "DIVIDEND"]
+        assert "90000000.00000001" in amounts
+        assert "90000000.00000002" in amounts
+    finally:
+        client.close()
+        stack.close()
+
+    with repo._connect().cursor() as cur:
+        cur.execute(
+            """
+            SELECT price::text
+            FROM portfolio_ledger
+            WHERE portfolio_id = %s AND side = 'dividend' AND note = 'amount-alias'
+            ORDER BY ledger_entry_id ASC
+            """,
+            (portfolio_id,),
+        )
+        assert [row[0] for row in cur.fetchall()] == ["90000000.00000001", "90000000.00000002"]
+    repo.close()
+
+
+def test_cold_repositories_concurrent_dividend_requests_follow_duplicate_contract(
+    isolated_settings: Settings,
+) -> None:
+    """Cold concurrent writes should not fail on ensure_schema DDL race."""
+    upgrade_to_head(isolated_settings)
+    seed_repo = _repo(isolated_settings)
+    portfolio_id = _seed_portfolio(seed_repo, "cold-concurrent-dividend")
+    seed_repo.close()
+    barrier = threading.Barrier(2)
+    results: list[tuple[str, object]] = []
+
+    def _worker(note: str) -> None:
+        repo = _repo(isolated_settings)
+        try:
+            barrier.wait()
+            entry = repo.record_manual_ledger(
+                portfolio_id,
+                action="DIVIDEND",
+                amount=Decimal("1.00000000"),
+                executed_at=datetime(2026, 9, 1, 0, 0, 0, tzinfo=UTC),
+                note=note,
+            )
+            results.append(("ok", entry))
+        except ValueError as exc:
+            results.append(("error", str(exc)))
+        finally:
+            repo.close()
+
+    t1 = threading.Thread(target=_worker, args=("same-note",))
+    t2 = threading.Thread(target=_worker, args=("same-note",))
+    t1.start()
+    t2.start()
+    t1.join()
+    t2.join()
+
+    assert len(results) == 2
+    successes = [value for kind, value in results if kind == "ok"]
+    errors = [value for kind, value in results if kind == "error"]
+    assert len(successes) == 1
+    assert len(errors) == 1
+    assert "POTENTIAL_DUPLICATE_DIVIDEND:" in str(errors[0])
+    assert "duplicate key value" not in str(errors[0]).lower()
+
+    verify_repo = _repo(isolated_settings)
+    with verify_repo._connect().cursor() as cur:
+        cur.execute(
+            "SELECT COUNT(*) FROM portfolio_ledger WHERE portfolio_id = %s AND side = 'dividend'",
+            (portfolio_id,),
+        )
+        assert cur.fetchone()[0] == 1
+        cur.execute("SELECT profit_buffer::text FROM portfolios WHERE portfolio_id = %s", (portfolio_id,))
+        assert cur.fetchone()[0] == "1"
+    verify_repo.close()

tests/test_v1_portfolios_crud.py

@@ -507,7 +507,7 @@ def test_delete_already_disabled_is_idempotent() -> None:
 
 
 # Issue #26: strategy catalog references on portfolio mutations.
-def test_post_strategy_reference_errors_and_required_contract() -> None:
+def test_post_strategy_reference_errors_and_optional_contract() -> None:
     repo = _FakeRepo(asset=_make_asset(_ASSET_UUID, "active"))
     client = _make_client()
     with _with_repo(repo):
@@ -516,7 +516,7 @@ def test_post_strategy_reference_errors_and_required_contract() -> None:
             json={"asset_id": _ASSET_UUID, "broker": "kiwoom", "strategy_id": "missing"},
             headers=_auth("admin-tok"),
         )
-        invalid = client.post(
+        without_strategy = client.post(
             "/v1/portfolios",
             json={"asset_id": _ASSET_UUID, "broker": "kiwoom"},
             headers=_auth("admin-tok"),
@@ -528,7 +528,8 @@ def test_post_strategy_reference_errors_and_required_contract() -> None:
             headers=_auth("admin-tok"),
         )
     assert missing.status_code == 404
-    assert invalid.status_code == 422
+    assert without_strategy.status_code == 201
+    assert without_strategy.json()["active_strategy_id"] is None
     assert inactive.status_code == 409
 
 

tests/test_v1_portfolios_manual_ledger.py

@@ -2,16 +2,22 @@
 
 from __future__ import annotations
 
+import os
+import time
 from contextlib import ExitStack
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from decimal import Decimal
 from typing import Any
 from unittest.mock import patch
 
+import pytest
 from fastapi.testclient import TestClient
+from pydantic import ValidationError
 
 from app.core.config import Settings, get_settings
 from app.domain.models import LedgerEntry, Portfolio, TokenPrincipal
 from app.main import create_app
+from app.schemas.v1 import LedgerHistoryItem
 
 _PORTFOLIO_ID = "pf-001"
 _USER_ID = "user-001"
@@ -68,6 +74,8 @@ class _FakeRepo:
         self.principal = principal or _token_principal()
         self.entries: list[LedgerEntry] = []
         self._next_id = 1
+        self._dividend_amounts: dict[int, Decimal] = {}
+        self._dividend_tax_amounts: dict[int, Decimal] = {}
 
     def close(self) -> None:
         pass
@@ -83,11 +91,17 @@ class _FakeRepo:
     def record_manual_ledger(self, portfolio_id: str, **kwargs: Any) -> LedgerEntry:
         self.get(portfolio_id)
         action = kwargs["action"]
-        amount = float(kwargs.get("amount") or 0.0)
+        amount_raw = kwargs.get("amount")
+        amount_decimal = Decimal(str(amount_raw if amount_raw is not None else 0))
+        amount = float(amount_decimal)
         quantity = float(kwargs.get("quantity") or 0.0)
         price = float(kwargs.get("price") or 0.0)
         fee = float(kwargs.get("fee") or 0.0)
         tax = float(kwargs.get("tax") or 0.0)
+        tax_decimal = Decimal(str(kwargs.get("tax") if kwargs.get("tax") is not None else 0))
+        executed_at = kwargs.get("executed_at")
+        confirm_duplicate = bool(kwargs.get("confirm_duplicate") or False)
+        note = kwargs.get("note") or ""
         target = kwargs.get("target_ledger_entry_id")
         if action == "BUY":
             required = quantity * price + fee + tax
@@ -122,12 +136,64 @@ class _FakeRepo:
                 raise ValueError("INSUFFICIENT_BUFFER")
             self.portfolio.profit_buffer -= amount
             price = amount
+        elif action == "DIVIDEND":
+            reversed_ids = {
+                e.target_ledger_entry_id
+                for e in self.entries
+                if e.action == "REVERSAL" and e.target_ledger_entry_id is not None
+            }
+            duplicate = next(
+                (
+                    e
+                    for e in self.entries
+                    if e.action == "DIVIDEND"
+                    and e.ledger_entry_id not in reversed_ids
+                    and e.executed_at == executed_at
+                    and self._dividend_amounts.get(e.ledger_entry_id, Decimal(str(e.price))) == amount_decimal
+                    and e.note == note
+                ),
+                None,
+            )
+            if duplicate is not None and not confirm_duplicate:
+                raise ValueError(f"POTENTIAL_DUPLICATE_DIVIDEND:{duplicate.ledger_entry_id}")
+            self.portfolio.profit_buffer += amount
+            price = amount
         elif action == "REVERSAL":
             target_entry = next((e for e in self.entries if e.ledger_entry_id == target), None)
             if target_entry is None:
                 raise ValueError("LEDGER_ENTRY_NOT_FOUND")
             if any(e.target_ledger_entry_id == target and e.action == "REVERSAL" for e in self.entries):
                 raise ValueError("LEDGER_ENTRY_ALREADY_REVERSED")
+            target_action = target_entry.action or ""
+            target_amount = float(target_entry.price)
+            target_quantity = float(target_entry.quantity)
+            target_fee = float(target_entry.fee_amount)
+            target_tax = float(target_entry.tax_amount)
+            if target_action == "BUY":
+                self.portfolio.cash_balance += target_quantity * target_amount + target_fee + target_tax
+                self.portfolio.asset_quantity -= target_quantity
+            elif target_action == "SELL":
+                required_cash = target_quantity * target_amount - target_fee - target_tax
+                if self.portfolio.cash_balance < required_cash:
+                    raise ValueError("INSUFFICIENT_CASH")
+                self.portfolio.cash_balance -= required_cash
+                self.portfolio.asset_quantity += target_quantity
+            elif target_action == "BUFFER_OUT":
+                if self.portfolio.cash_balance < target_amount:
+                    raise ValueError("INSUFFICIENT_CASH")
+                self.portfolio.cash_balance -= target_amount
+                self.portfolio.profit_buffer += target_amount
+            elif target_action == "BUFFER_IN":
+                if self.portfolio.profit_buffer < target_amount:
+                    raise ValueError("INSUFFICIENT_BUFFER")
+                self.portfolio.cash_balance += target_amount
+                self.portfolio.profit_buffer -= target_amount
+            elif target_action in {"INVEST", "DIVIDEND"}:
+                if self.portfolio.profit_buffer < target_amount:
+                    raise ValueError("INSUFFICIENT_BUFFER")
+                self.portfolio.profit_buffer -= target_amount
+            elif target_action in {"WITHDRAW", "PROFIT"}:
+                self.portfolio.profit_buffer += target_amount
             price = 0.0
         total = self.portfolio.cash_balance + self.portfolio.asset_quantity * self.portfolio.price + self.portfolio.profit_buffer
         entry = LedgerEntry(
@@ -137,14 +203,17 @@ class _FakeRepo:
             side=action.lower(),
             quantity=quantity,
             price=price,
+            price_decimal=amount_decimal if action == "DIVIDEND" else Decimal(str(price)),
             fee_amount=fee,
             tax_amount=tax,
-            recorded_at=datetime.now(timezone.utc),
+            tax_amount_decimal=tax_decimal if action == "DIVIDEND" else Decimal(str(tax)),
+            executed_at=executed_at,
+            recorded_at=datetime.now(UTC),
             cash_balance_after=self.portfolio.cash_balance,
             asset_quantity_after=self.portfolio.asset_quantity,
             profit_buffer_after=self.portfolio.profit_buffer,
             total_value_after=total,
-            note=kwargs.get("note") or "",
+            note=note,
             source="manual",
             target_ledger_entry_id=target,
             confirmation_evidence=kwargs.get("confirmation_evidence"),
@@ -152,6 +221,9 @@ class _FakeRepo:
         )
         self._next_id += 1
         self.entries.append(entry)
+        if action == "DIVIDEND":
+            self._dividend_amounts[entry.ledger_entry_id] = amount_decimal
+            self._dividend_tax_amounts[entry.ledger_entry_id] = tax_decimal
         return entry
 
     def list_manual_ledger_entries(self, portfolio_id: str, limit: int = 50) -> list[LedgerEntry]:
@@ -330,6 +402,31 @@ def test_insufficient_cash_rejected_as_409() -> None:
 
     assert resp.status_code == 409
     assert resp.json()["detail"]["code"] == "INSUFFICIENT_CASH"
+    assert resp.json()["detail"]["message"] == "Insufficient cash balance"
+
+
+def test_manual_ledger_conflict_message_is_sanitized() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    secret = "SENTINEL_SECRET_TOKEN_12345"
+
+    def _raise_secret(*args: Any, **kwargs: Any) -> LedgerEntry:
+        raise ValueError(f"synthetic backend failure: {secret}")
+
+    repo.record_manual_ledger = _raise_secret  # type: ignore[method-assign]
+
+    resp = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01"},
+        headers=_auth(),
+    )
+
+    assert resp.status_code == 422
+    detail = resp.json()["detail"]
+    assert detail["code"] == "MANUAL_LEDGER_CONFLICT"
+    assert detail["message"] == "Manual ledger request could not be processed"
+    assert secret not in resp.text
 
 
 def test_manual_history_returns_total_value_after() -> None:
@@ -402,6 +499,514 @@ def test_amount_actions_reject_fee_and_tax_fields() -> None:
         assert resp.status_code == 422
 
 
+def test_dividend_updates_only_profit_buffer_and_records_executed_at_and_tax() -> None:
+    repo = _FakeRepo(_portfolio(cash=1000, quantity=10, price=10, buffer=500))
+    client = _make_client(repo)
+
+    resp = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 120, "tax": 10, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["action"] == "DIVIDEND"
+    assert body["amount"] == "120"
+    assert body["tax"] == "10"
+    assert body["executed_at"] == "2026-09-01T00:00:00Z"
+    assert body["cash_balance_after"] == 1000.0
+    assert body["asset_quantity_after"] == 10.0
+    assert body["profit_buffer_after"] == 620.0
+    assert body["total_value_after"] == 1720.0
+    assert body["source"] == "manual"
+
+
+def test_dividend_tax_defaults_to_zero_when_omitted() -> None:
+    repo = _FakeRepo(_portfolio(cash=1000, quantity=10, price=10, buffer=500))
+    client = _make_client(repo)
+
+    resp = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 120, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["tax"] == "0"
+    assert body["cash_balance_after"] == 1000.0
+    assert body["asset_quantity_after"] == 10.0
+    assert body["profit_buffer_after"] == 620.0
+
+
+def test_dividend_executed_at_uses_utc_midnight_independent_of_server_timezone(monkeypatch: pytest.MonkeyPatch) -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    original_tz = None
+    if hasattr(time, "tzset"):
+        original_tz = os.environ.get("TZ")
+        monkeypatch.setenv("TZ", "Asia/Seoul")
+        time.tzset()
+
+    try:
+        resp = client.post(
+            f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+            json={"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01"},
+            headers=_auth(),
+        )
+    finally:
+        if hasattr(time, "tzset"):
+            if original_tz is None:
+                monkeypatch.delenv("TZ", raising=False)
+            else:
+                monkeypatch.setenv("TZ", original_tz)
+            time.tzset()
+
+    assert resp.status_code == 201
+    body = resp.json()
+    assert body["executed_at"] == "2026-09-01T00:00:00Z"
+    assert body["recorded_at"] != body["executed_at"]
+
+
+def test_dividend_requires_executed_at_and_rejects_fee_field() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    missing_date = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50},
+        headers=_auth(),
+    )
+    assert missing_date.status_code == 422
+
+    invalid_fee = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50, "executed_at": "2026-09-01", "fee": 0},
+        headers=_auth(),
+    )
+    assert invalid_fee.status_code == 422
+
+
+def test_dividend_rejects_invalid_amount_tax_and_unrelated_fields_without_state_change() -> None:
+    repo = _FakeRepo(_portfolio(cash=1000, quantity=10, price=10, buffer=500))
+    client = _make_client(repo)
+    baseline = (
+        repo.portfolio.cash_balance,
+        repo.portfolio.asset_quantity,
+        repo.portfolio.profit_buffer,
+        len(repo.entries),
+    )
+
+    invalid_payloads = [
+        {"action": "DIVIDEND", "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": 1},
+        {"action": "DIVIDEND", "amount": 0, "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": -1, "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": 1, "executed_at": "2026-13-40"},
+        {"action": "DIVIDEND", "amount": 1, "tax": -1, "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": 1, "tax": "0.000000001", "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": 1, "tax": "1000000000000.00000000", "executed_at": "2026-09-01"},
+        {"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01", "fee": 0},
+        {"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01", "quantity": 1},
+        {"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01", "price": 1},
+        {"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01", "target_ledger_entry_id": 1},
+    ]
+
+    for payload in invalid_payloads:
+        resp = client.post(
+            f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+            json=payload,
+            headers=_auth(),
+        )
+        assert resp.status_code == 422
+        assert (
+            repo.portfolio.cash_balance,
+            repo.portfolio.asset_quantity,
+            repo.portfolio.profit_buffer,
+            len(repo.entries),
+        ) == baseline
+
+
+def test_dividend_rejects_sub_minimum_numeric_precision() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    too_precise = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "0.000000004", "executed_at": "2026-09-01"},
+        headers=_auth(),
+    )
+    assert too_precise.status_code == 422
+
+
+def test_dividend_rejects_amount_exceeding_numeric_20_8() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    too_large = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "1000000000000.00000000", "executed_at": "2026-09-01"},
+        headers=_auth(),
+    )
+    assert too_large.status_code == 422
+
+
+def test_dividend_duplicate_requires_confirmation() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    first = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert first.status_code == 201
+
+    duplicate = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert duplicate.status_code == 409
+    assert duplicate.json()["detail"]["code"] == "POTENTIAL_DUPLICATE_DIVIDEND"
+    assert duplicate.json()["detail"]["matched_ledger_entry_id"] == first.json()["ledger_entry_id"]
+
+    confirmed = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={
+            "action": "DIVIDEND",
+            "amount": 50,
+            "executed_at": "2026-09-01",
+            "note": "Q3",
+            "confirm_duplicate": True,
+        },
+        headers=_auth(),
+    )
+    assert confirmed.status_code == 201
+
+
+def test_dividend_with_different_decimal_amount_is_not_treated_as_duplicate() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    first = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "1.00000000", "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert first.status_code == 201
+
+    second = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "1.00000001", "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert second.status_code == 201
+
+
+def test_dividend_duplicate_check_does_not_collapse_decimals_that_can_alias_in_float() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    first = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "90000000.00000001", "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert first.status_code == 201
+
+    second = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": "90000000.00000002", "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert second.status_code == 201
+    assert first.json()["amount"] == "90000000.00000001"
+    assert second.json()["amount"] == "90000000.00000002"
+
+    history = client.get(f"/v1/portfolios/{_PORTFOLIO_ID}/ledger?source=manual", headers=_auth())
+    assert history.status_code == 200
+    amounts = [item["amount"] for item in history.json()["items"] if item["action"] == "DIVIDEND"]
+    assert "90000000.00000001" in amounts
+    assert "90000000.00000002" in amounts
+
+
+def test_dividend_tax_does_not_collapse_decimals_that_can_alias_in_float() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    first = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={
+            "action": "DIVIDEND",
+            "amount": "1.00000000",
+            "tax": "90000000.00000001",
+            "executed_at": "2026-09-01",
+            "note": "Q3-1",
+        },
+        headers=_auth(),
+    )
+    assert first.status_code == 201
+
+    second = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={
+            "action": "DIVIDEND",
+            "amount": "1.00000000",
+            "tax": "90000000.00000002",
+            "executed_at": "2026-09-02",
+            "note": "Q3-2",
+        },
+        headers=_auth(),
+    )
+    assert second.status_code == 201
+    assert first.json()["tax"] == "90000000.00000001"
+    assert second.json()["tax"] == "90000000.00000002"
+
+    history = client.get(f"/v1/portfolios/{_PORTFOLIO_ID}/ledger?source=manual", headers=_auth())
+    assert history.status_code == 200
+    taxes = [item["tax_amount"] for item in history.json()["items"] if item["action"] == "DIVIDEND"]
+    assert "90000000.00000001" in taxes
+    assert "90000000.00000002" in taxes
+
+
+def test_reversed_dividend_is_excluded_from_future_duplicate_candidate_matching() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    first = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert first.status_code == 201
+
+    reversal = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "REVERSAL", "target_ledger_entry_id": first.json()["ledger_entry_id"]},
+        headers=_auth(),
+    )
+    assert reversal.status_code == 201
+
+    replay = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 50, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert replay.status_code == 201
+
+
+def test_confirm_duplicate_false_is_accepted_for_non_dividend_actions() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    invest = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "INVEST", "amount": 100, "confirm_duplicate": False},
+        headers=_auth(),
+    )
+    assert invest.status_code == 201
+    assert isinstance(invest.json()["amount"], float)
+
+    buy = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "BUY", "quantity": 1, "price": 10, "confirm_duplicate": False},
+        headers=_auth(),
+    )
+    assert buy.status_code == 201
+
+
+def test_unified_ledger_keeps_non_dividend_amount_as_number() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    created = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "INVEST", "amount": 100},
+        headers=_auth(),
+    )
+    assert created.status_code == 201
+    assert created.json()["amount"] == 100.0
+
+    history = client.get(f"/v1/portfolios/{_PORTFOLIO_ID}/ledger?source=manual", headers=_auth())
+    assert history.status_code == 200
+    item = history.json()["items"][0]
+    assert item["action"] == "INVEST"
+    assert item["amount"] == 100.0
+
+
+def test_confirm_duplicate_true_is_rejected_for_non_dividend_actions() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    invest = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "INVEST", "amount": 100, "confirm_duplicate": True},
+        headers=_auth(),
+    )
+    assert invest.status_code == 422
+
+
+def test_dividend_reversal_decreases_profit_buffer() -> None:
+    repo = _FakeRepo(_portfolio(buffer=200))
+    client = _make_client(repo)
+
+    dividend = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 80, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert dividend.status_code == 201
+    assert dividend.json()["profit_buffer_after"] == 280.0
+
+    reversal = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "REVERSAL", "target_ledger_entry_id": dividend.json()["ledger_entry_id"]},
+        headers=_auth(),
+    )
+    assert reversal.status_code == 201
+    assert reversal.json()["profit_buffer_after"] == 200.0
+
+
+def test_duplicate_reversal_is_rejected_without_state_change() -> None:
+    repo = _FakeRepo(_portfolio(buffer=200))
+    client = _make_client(repo)
+
+    dividend = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 80, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert dividend.status_code == 201
+
+    first_reversal = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "REVERSAL", "target_ledger_entry_id": dividend.json()["ledger_entry_id"]},
+        headers=_auth(),
+    )
+    assert first_reversal.status_code == 201
+    before_count = len(repo.entries)
+
+    second_reversal = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "REVERSAL", "target_ledger_entry_id": dividend.json()["ledger_entry_id"]},
+        headers=_auth(),
+    )
+    assert second_reversal.status_code == 409
+    assert second_reversal.json()["detail"]["code"] == "LEDGER_ENTRY_ALREADY_REVERSED"
+    assert len(repo.entries) == before_count
+    assert repo.portfolio.profit_buffer == 200.0
+
+
+def test_dividend_reversal_insufficient_buffer_is_rejected_without_state_change() -> None:
+    repo = _FakeRepo(_portfolio(buffer=0, cash=1000, quantity=10, price=10))
+    client = _make_client(repo)
+
+    dividend = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 100, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert dividend.status_code == 201
+
+    withdraw = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "WITHDRAW", "amount": 100},
+        headers=_auth(),
+    )
+    assert withdraw.status_code == 201
+    assert repo.portfolio.profit_buffer == 0.0
+    before_count = len(repo.entries)
+
+    reversal = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "REVERSAL", "target_ledger_entry_id": dividend.json()["ledger_entry_id"]},
+        headers=_auth(),
+    )
+    assert reversal.status_code == 409
+    assert reversal.json()["detail"]["code"] == "INSUFFICIENT_BUFFER"
+    assert len(repo.entries) == before_count
+    assert repo.portfolio.profit_buffer == 0.0
+
+
+def test_manual_ledger_conflict_secret_is_not_rendered_in_logs(caplog: pytest.LogCaptureFixture) -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+    secret = "SENTINEL_SECRET_TOKEN_67890"
+
+    def _raise_secret(*args: Any, **kwargs: Any) -> LedgerEntry:
+        raise ValueError(f"synthetic persistence {secret}")
+
+    repo.record_manual_ledger = _raise_secret  # type: ignore[method-assign]
+    caplog.clear()
+    caplog.set_level("INFO")
+
+    resp = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 1, "executed_at": "2026-09-01"},
+        headers=_auth(),
+    )
+    assert resp.status_code == 422
+    rendered = "\n".join(f"{record.name}:{record.getMessage()}" for record in caplog.records)
+    assert secret not in rendered
+
+
+def test_unified_ledger_includes_dividend_fields() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    created = client.post(
+        f"/v1/portfolios/{_PORTFOLIO_ID}/ledger/manual",
+        json={"action": "DIVIDEND", "amount": 33, "tax": 3, "executed_at": "2026-09-01", "note": "Q3"},
+        headers=_auth(),
+    )
+    assert created.status_code == 201
+
+    resp = client.get(f"/v1/portfolios/{_PORTFOLIO_ID}/ledger?source=manual", headers=_auth())
+    assert resp.status_code == 200
+    item = resp.json()["items"][0]
+    assert item["source"] == "manual"
+    assert item["action"] == "DIVIDEND"
+    assert item["amount"] == "33"
+    assert item["price"] == 33.0
+    assert item["executed_at"] == "2026-09-01T00:00:00Z"
+    assert item["tax_amount"] == "3"
+    assert item["note"] == "Q3"
+    assert item["profit_buffer_after"] == created.json()["profit_buffer_after"]
+
+
+def test_unified_ledger_openapi_contains_nullable_amount() -> None:
+    repo = _FakeRepo(_portfolio())
+    client = _make_client(repo)
+
+    response = client.get("/openapi.json")
+    assert response.status_code == 200
+    schemas = response.json()["components"]["schemas"]
+    manual_amount_types = {option.get("type") for option in schemas["ManualLedgerResponse"]["properties"]["amount"]["anyOf"]}
+    assert manual_amount_types == {"number", "null"}
+    assert schemas["DividendManualLedgerResponse"]["properties"]["amount"]["type"] == "string"
+    history_amount_types = {option.get("type") for option in schemas["LedgerHistoryItem"]["properties"]["amount"]["anyOf"]}
+    assert history_amount_types == {"number", "null"}
+    assert schemas["DividendLedgerHistoryItem"]["properties"]["amount"]["type"] == "string"
+    assert "DIVIDEND" not in schemas["LedgerHistoryItem"]["properties"]["action"]["enum"]
+    assert schemas["DividendLedgerHistoryItem"]["properties"]["action"]["const"] == "DIVIDEND"
+
+
+def test_unified_ledger_history_item_rejects_dividend_numeric_branch_payload() -> None:
+    with pytest.raises(ValidationError):
+        LedgerHistoryItem(
+            ledger_entry_id=1,
+            portfolio_id=_PORTFOLIO_ID,
+            source="manual",
+            action="DIVIDEND",
+            recorded_at=datetime.now(UTC),
+            amount=1.0,
+            tax_amount=0.0,
+        )
+
+
 def test_reversal_rejects_fee_tax_and_missing_target() -> None:
     repo = _FakeRepo(_portfolio())
     client = _make_client(repo)
@@ -432,7 +1037,7 @@ def test_unified_ledger_paginates_mixed_sources_and_hides_side() -> None:
     repo.entries.append(
         LedgerEntry(
             ledger_entry_id=99, portfolio_id=_PORTFOLIO_ID, side="buy", quantity=2, price=10, source="broker",
-            recorded_at=datetime.now(timezone.utc), cash_balance_after=900, asset_quantity_after=12,
+            recorded_at=datetime.now(UTC), cash_balance_after=900, asset_quantity_after=12,
         )
     )
     first = client.get(f"/v1/portfolios/{_PORTFOLIO_ID}/ledger?limit=1", headers=_auth())

uv.lock

@@ -592,7 +592,7 @@ wheels = [
 
 [[package]]
 name = "portfoliohub"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },